vib – Page 4

How To Compile Google Authenticator for ESXi

03.19.2013 by William Lam // 2 Comments

In my previous article I demonstrated how to use Google Authenticator to provide two-factor authentication for ESXi using the custom VIB that I had built. In this article, I will show you how to compile Google Authenticator to run on ESXi as well as an additional customizations that can be made to the source code to support multiple users.

Disclaimer: This is not officially supported by VMware, use at your own risk

Prerequisite:

Download and install 32-bit Linux distribution. In my lab, I used latest CentOS 6.2
Install pam-devel package (CentOS) or libpam0g-dev package (Ubuntu). You can reference this blog here for more details on installation
Ensure you have both gcc and make installed

Step 1 - Download Google Authenticator source code by running the following command:

wget http://google-authenticator.googlecode.com/files/libpam-google-authenticator-1.0-source.tar.bz2

Step 2 - Extract the source code by running the following command and change into the libpam-google-authenticator-1.0 directory:

tar -jxf libpam-google-authenticator-1.0-source.tar.bz2
cd libpam-google-authenticator-1.0

Step 3 - Edit pam_google_authenticator.c and towards the top of the file comment out the following three lines which should look like this:

//#include <sys/fsuid.h>
//#define HAS_SETFSUID
//#endif

Step 4 - By default the SECRET file is stored in /.google-authenticator and we can change the path by modifying both google-authenticator.c and pam_google_authenticator.c by editing the SECRET macro file which should look like the following:

#define SECRET      "/etc/vmware/.google_authenticator"

Google Authenticator supports multiple users by default and you can also provide this support in ESXi by leveraging the $USER OS environmental variable within the SECRET file location. This would allow each user to generate and store their own SECRET file. To do so, set the path to /etc/vmware/$USER/.google-authenticator and the username will automatically be populated when configuring Google Authenticator for each user.

Note: If you are going to create a custom VIB and would like to support multiple users, you will need to know the usernames in advance so you can create the dummy .google-authenticator file for each user. This is required so the files will automatically persist after setting up Google Authenticator.

Step 5 - Save the changes and then type "make" which will then compile the source code and produce google-authenticator binary and PAM module pam_google_authenticator.so in the same directory.

Step 6 - If you decided to create your own custom VIB, ensure you include an empty secret file so when you go and configure it, the changes will be saved. If you do not wish to lower the acceptance level of your ESXi host for the custom VIB, an alternative trick is to store the google-authenticator binary and PAM module in a local datastore as well as the secret file and copy them over using either /etc/rc.local.d/local.sh for ESXi 5.1 or /etc/rc.local for ESXi 5.0. Here is a sample of what that should look like:

Using Google Authenticator To Provide Two-Factor Authentication For ESXi

03.11.2013 by William Lam // 12 Comments

Last year, I came across an interesting open source project called Google Authenticator, which provides two-factor authentication by using both a PAM (Pluggable Authentication Module) module and a mobile application for generating one-time passcodes. This project sparked my curiosity and I wanted to see if I could get Google Authenticator to run on ESXi to provide additional security by requiring two-factor authentication when attempting to login to the ESXi Shell. After several attempts, I failed to get Google Authenticator working on ESXi and eventually gave up. I reported the behavior I saw in my environment in the Issues section of the project which did not yield any responses and I thought that was the end of that experiment.

Almost eight months later, I received a surprising email from two VMware engineers who were also interested in the Google Authenticator project and were able to figure out how to get Google Authenticator to work on ESXi. In sharing their findings, it turns out that the solution was actually quite simple and it just required commenting out three lines of C Macros in the Google Authenticator source code (tweak is documented in this blog post here). I was able to confirm the engineers findings in my home lab and was also able to build a custom Google Authenticator VIB for ESXi to help with the setup.

Disclaimer: This is not officially supported by VMware, use at your own risk

Installing Google Authenticator Custom VIB / Offline Bundle

Prerequisite:

Ensure that your ESXi host's clock is in sync with a proper time source (skew should be < 4minutes)
Keep a separate SSH connection open to your ESXi host, in case something goes wrong you can easily revert the changes else you can potentially lock yourself out

Step 1 - Download either the Google Authenticator VIB vghetto-google-auth.vib or offline bundle vghetto-google-auth.zip and upload it to the datastore of your ESXi host

Step 2 - You will need to change the acceptance level of your ESXi host to Community Supported as this is a requirement for any custom VIBs created. Run the following ESXCLI command:

esxcli software acceptance set --level CommunitySupported

Step 3 - To install Google Authenticator VIB, you will need to run the following ESXCLI command and specify the full datastore path of the VIB:

esxcli software vib install -v /vmfs/volumes/mini-local-datastore-1/vghetto-google-auth.vib -f

To install the Google Authenticator offline bundle, you will run the same command but instead of using the -v argument, you will specify the -d

Step 4 - You can verify the Google Authenticator was installed successfully by running the following ESXCLI command:

esxcli software vib get -n vGhetto-goog-auth

Configuring Google Authenticator & ESXi Configurations

Step 1 - Download the Google Authenticator app for your mobile phone. In this example, I am using the iPhone's Google Authenticator mobile app.

Step 2 - Next you will need to configure Google Authenticator for the ESXi host, run the google-authenticator command in the ESXi Shell which will start the setup.

You should see a URL as well as the secret key which you will need to enter into your Google Authenticator mobile app. You can either manually add your ESXi host into the mobile app by entering the secret key OR copy and paste the URL into a web browser which provides a QRC code that the mobile app can just read.

For all the prompted questions, you can use yes for the defaults.

Step 3 - You will need to add the following configuration to your SSHD configuration under /etc/ssh/sshd_config

ChallengeResponseAuthentication yes

Step 4 - You will also need to add the following entry to the following PAM configuration files /etc/pam.d/login and /etc/pam.d/sshd

auth required pam_google_authenticator.so

To add the entry into both files on the ESXi Shell, run the following two commands:

sed -i -e '3iauth required pam_google_authenticator.so\' /etc/pam.d/login
sed -i -e '3iauth required pam_google_authenticator.so\' /etc/pam.d/sshd

Note: To ensure the above configuration persists after a reboot, you will need to add the two sed commands to /etc/rc.local.d/local.sh for ESXi 5.1 or /etc/rc.local for ESXi 5.0 hosts which will automatically add the entries upon bootup.

Finally, you will need to restart the SSH daemon for the changes to go into effect by running the following command:

/etc/init.d/SSH restart

Step 5 - To validate that everything was configured correctly, open a new SSH session to your ESXi host. Instead of seeing the usual password prompt, you should now see a verification code prompt. Open up your Google Authenticator mobile app and enter the code that is displayed for your ESXi host and then enter the root password.

If everything was correct, you should now be authorized and logged into your ESXi host

Though the configuration could be a bit more automated including adding each ESXi host to your mobile application, this is a pretty nifty and free solution to provide two-factor authentication for your ESXi hosts. I am curious to see if others are interested in such functionality within ESXi or if this would be useful? Feel free to leave a comment.

Big thanks to VMware engineers who helped me get this solution to work!

Creating Custom VIBs For ESXi 5.0 & 5.1 with VIB Author Fling

09.28.2012 by William Lam // 41 Comments

VMware Labs just released a really cool new Fling called VIB Author which is a tool that allows you to easily create custom VIBs for your ESXi 5.x hosts. If you have tried to create custom ESXi firewall rules or add custom scripts to your ESXi host, you may have noticed they are not persisted after a system reboot and you had to play all sorts of games to get the files to persist. The VIB Author tool now solves that problem and you can even take your custom VIB and integrate them into an Auto Deploy Image Profile using Image Builder. Before you jump right in, be sure to read over the important note in the documentation before getting started.

So how does the VIB Author tool work?

You will need to provide two pieces of input: payload which is set of files you wish to include in your VIB and the descriptor.xml which contains the metadata for your files. From that, VIB Author can produce either a VIB and/or an offline bundle (can be used with Image Builder).

VIB Author is distributed only as an RPM and you will need to install the VIB Author tool on a 32-bit Linux system (sorry, no 64-bit support). In my home setup, I went with CentOS 6.2 i386 as it was free to download & easy to setup or you may choose go with SUSE Linux Enterprise 11 SP2 which is the recommended platform per the documentation.

UPDATE (07/25/23) - To create custom VIBs for ESXi 8.x or later, please see the update process HERE.

To install the RPM, run the following command:

rpm -ivh vmware-esx-vib-author-5.0.0-0.0.844296.i386.rpm

In the example below, I will show you how to create a custom VIB that contains several different configurations:

Custom Firewall Rule
Custom Startup script (adds a static route)
Custom Files (ghettoVCB)

Disclaimer: The example below is not officially supported by VMware, please thoroughly test this in a development environment before using in production.

Here is the directory structure for the example that we will be going through:

Step 1 - Create your stage directory structure which we will then populate with your payload files as well as the descriptor.xml file.

mkdir -p stage/payloads/payload1

Step 2 - Create your descriptor.xml file which should be placed in the stage directory. For more details on the parameters within the descriptor.xml, please take a look at the documentation.

Here is an example of my descriptor.xml file:

<vib version="5.0">
  <type>bootbank</type>
  <name>virtuallyghetto</name>
  <version>5.0.0-0.0.1</version>
  <vendor>virtuallyGhetto</vendor>
  <summary>Custom VIB from virtuallyGhetto</summary>
  <description>Adds custom firewall rule, ghettoVCB script and static routes to ESXi host</description>
  <relationships>
    <depends>
    </depends>
    <conflicts/>
    <replaces/>
    <provides/>
    <compatibleWith/>
  </relationships>
  <software-tags>
  </software-tags>
  <system-requires>
    <maintenance-mode>false</maintenance-mode>
  </system-requires>
  <file-list>
  </file-list>
  <acceptance-level>community</acceptance-level>
  <live-install-allowed>true</live-install-allowed>
  <live-remove-allowed>true</live-remove-allowed>
  <cimom-restart>false</cimom-restart>
  <stateless-ready>true</stateless-ready>
  <overlay>false</overlay>
  <payloads>
    <payload name="payload1" type="vgz"></payload>
  </payloads>
</vib>

Step 3 - Create the directory structure and store the files you wish to include under payload1. Ensure the the directory structure matches the absolute path of how you want the files to appear on the ESXi host. For example, if you wish to create a file call foo in /etc/vmware/foo then your directory structure should look like stage/payloads/payload1/etc/vmware/foo

Note: In the documentation, there is a list of default supported paths, if you venture off of this supported list, then you will need to issue the -f flag when creating your VIB as well as installing your VIB on your ESXi host

So for our examples we have the following files:

stage/payloads/payload1/etc/vmware/firewall/virtuallyghetto.xml
This one should be pretty straight forward, we are just creating a custom ESXi firewall rule and you will need to place your configuration file under /etc/vmware/firewall, please take a look at this article for more details on creating your own firewall rules.

stage/payloads/payload1/etc/rc.local.d/999.addStaticRoute.sh
This is a custom shell script that adds a static route to an ESXi host upon bootup under /etc/rc.local.d. There maybe other startup scripts that could be executed and you do not want to conflict with any system defaults. I recommend you label yours with a high number such as 999 to ensure it is one of the last scripts to execute.

stage/payloads/payload1/opt/ghettoVCB/{ghettoVCB.conf,ghettoCB-restore.sh,ghettoVCB.sh}
This is a custom set of files that I would like to store in ESXi under /opt directory and the files are my free ghettoVCB backup script.

Here is a copy of my directory structure (stage.zip) which can be used as a reference.

Step 4 - Now we ready to create our VIB and/or offline bundle by specifying our stage directory as input. In this example, we will generate both a VIB as well as an offline bundle containing the same contents. Run the following command:

vibauthor -C -t stage -v virtuallyghetto.vib -O virtuallyghetto-offline-bundle.zip -f

Note: Since we added some files outside of the default supported paths, we also need to specify the -f flag to force the creation.

We can also extract information about our VIB by using the -i option in VIB Author, to do so, run the following command:

vibauthor -i -v virtuallyghetto.vib

Finally, we are now ready to copy the VIB over to our ESXi host and install our custom VIB.

To install VIB run the following command:

esxcli software vib install -v /vmfs/volumes/[datastore-name]/virtuallyghetto.vib -f

To install the offline bundle run the following command:

esxcli software vib install -d /vmfs/volumes/[datastore-name]/virtuallyghetto-offline-bundle.zip -f

Note: You need to specify the -f flag to force the installation since we created files in an unsupported path. I have been able to test the VIB and offline bundle installation on both ESXi 5.0 as well as ESXi 5.1

To confirm we have succesfully installed our custom VIB, we can query it by running the following command:

esxcli software vib list | grep virtuallyghetto

So there you have it, in just a few steps, you can create your own custom VIBs!