Installing Vagrant

If you are going to follow the recommendation to use Vagrant, let’s get started installing it. You’ll need to download two packages.

Go to VirtualBox Downloads and download the appropriate platform package for your system.

Next, go to Vagrant Downloads and download the appropriate platform package for your system.

Install these packages according to the instructions for your operating system. I’ve included detailed instructions for Windows and Mac users in the following subsections. If you’re running Vagrant on Linux or another platform, I’m going to assume you are expert enough to handle this installation yourself.

Installing Vagrant on Mac

First, you should run the VirtualBox installer. Open the VirtualBox DMG image file you downloaded and click on the Virtualbox.pkg installer, as shown in Figure 2-1.

Accept the license and the installer will complete the installation.

Next, you should run the Vagrant installer. Open the Vagrant DMG image file you downloaded and click on the Vagrant.pkg installer, as shown in Figure 2-2.

Figure 2-1. VirtualBox package installer for Mac

Figure 2-2. Vagrant package installer for Mac

Likewise, accept the license agreement and the installer will complete the installation.

Finally, if you don’t already have it, you will need to install Xcode on your machine. Perform the following steps:

1. Pull down on the Apple logo at the top left of your screen.
2. Select “App Store...”
3. In the App Store, type xcode into the search bar on the right.
4. The top-left application should be Xcode Developer Tools.
5. Click GET and then click INSTALL APP beneath its name.

Installing Git Tools on Windows

On Windows platforms, you must install Git and its tools in order to use Vagrant successfully.

Open your browser to Git Source Code Management and click the Windows Build on the lower right of the page. Run the installer when the download completes.

Accept the default components.

On the “Adjusting your PATH environment” screen, select “Use Git from the Windows Command Prompt,” as shown in Figure 2-3.

Figure 2-3. Select “Use Git from the Windows Prompt”

On the “Configuring the line ending conversions” screen (as shown in Figure 2-4), any option will work successfully for this book. Select the default option if you are unsure. You can change this later.

Figure 2-4. Choose which line endings you prefer

Select the MinTTY terminal emulator on the following screen (Figure 2-5).

Figure 2-5. Choose the MinTTY terminal for the Bash shell

Accept the final prompts to complete the installation.

Installing VirtualBox on Windows

Vagrant will use the VirtualBox virtualization engine to run the test systems. Installing VirtualBox is very straightforward. Run the VirtualBox installer package that you downloaded on the previous page.

Click Next to start the installation, and then click Next again to install all features (Figure 2-6).

Figure 2-6. Install all features (the default choice)

You can disable the options to create shortcuts (Figure 2-7), as these won’t be necessary for the learning environment.

Figure 2-7. Select only the “Register file associations” checkbox

Accept the warning about a short interruption to networking (Figure 2-8). In most situations, you won’t notice any effect.

Figure 2-8. VirtualBox network interruption notice

To install VirtualBox, click Install, as shown in Figure 2-9.

Figure 2-9. Install VirtualBox

At this point, you’ll be prompted to install several virtualization drivers (Figure 2-10). You can either choose to always trust software from Oracle, or click Install for each one.

Figure 2-10. Oracle drivers

Disable the checkbox to start VirtualBox after installation (Figure 2-11). Vagrant will start it automatically.

Figure 2-11. Disable autostart

Installing Vagrant on Windows

Now we should install Vagrant. Run the Vagrant installer package that you downloaded (Figure 2-12).

Figure 2-12. Vagrant installer for Windows

You’ll need to accept the license agreement, as shown in Figure 2-13.

Figure 2-13. License agreement

Select where you want to install Vagrant. As Figure 2-14 shows, I prefer to install Vagrant in the normal system location for 64-bit programs. It doesn’t matter which path you choose here.

Figure 2-14. Select an installation path for Vagrant

Once you get to the confirmation screen acknowledging completion of the installation, you can exit the Setup Wizard by clicking Finish (Figure 2-15).

Figure 2-15. Click Finish to complete the installation

Windows systems will need to reboot, as shown in Figure 2-16.

Figure 2-16. Restart after installation

Starting a Bash Shell

At this point, you’ll need to start a Bash prompt. We’ll be using Bash for the remainder of this book, so now is a good time to become comfortable using it.

On a Macintosh, follow these steps:

1. Open Finder.
2. In the sidebar on the left, click on Applications.
3. Open the Utilities folder.
4. Start the Terminal application.

On Windows 7 and before, follow these steps:

1. From the taskbar, click on the Windows Start button.
2. Select All Programs.
3. Select Git.
4. Click on Git Bash.

On Windows 8, follow these steps:

1. From the Metro desktop, click the down-arrow icon at the bottom left.
2. Scroll to the right and locate the Git section.
3. Click on Git Bash.

On Windows 10 (see Figure 2-17), follow these steps:

1. From the taskbar, click the Windows Start button.
2. Select the first item, All Apps.
3. Scroll to G.
4. Expand the arrow next to Git.
5. Click on Git Bash.

Figure 2-17. Windows 10: Git Bash

On Linux or any other platform, use the terminal prompt of your choice.

No matter which operating system you are using, the instructions assume you will start at a command prompt in your home directory.

Downloading a Box

To save some time later, you can download the virtual box image used as the base system for our learning environment (as mentioned before, we’ll use CentOS 7, as it is well supported by all Puppet Labs programs and modules):

$ vagrant box add --provider virtualbox centos/7
==> box: Loading metadata for box 'centos/7'
    box: URL: https://vagrantcloud.com/centos/7
==> box: Adding box 'centos/7' (v1707.01) for provider: virtualbox
    box: Downloading: https://vagrantcloud.com/centos/boxes/7/versions/1707.01
==> box: Successfully added box 'centos/7' (v1707.01) for 'virtualbox'!

You may note that Vagrant Cloud contains many boxes that already have Puppet installed. For this book you will go through the installation of Puppet on a stock system so that you have that experience.

Cloning the Learning Repository

Now we’ll download a repository that contains virtual machine configurations and learning materials. Starting in your home directory, use git to clone the following repository:

$ git clone https://github.com/jorhett/learning-puppet4
Cloning into 'learning-puppet4'...
remote: Counting objects: 238, done.
remote: Total 238 (delta 0), reused 0 (delta 0), pack-reused 238
Receiving objects: 100% (238/238), 38.50 KiB | 0 bytes/s, done.
Resolving deltas: 100% (110/110), done.

$ cd learning-puppet4/

As shown, change into the learning-puppet4 directory. All further instructions will assume you are in this directory.

Install the Vagrant vbguest Plugin

Now you should install the vagrant-vbguest plugin. This plugin ensures that the VirtualBox extensions on the virtual machine are kept up to date.

$ vagrant plugin install vagrant-vbguest
Installing the 'vagrant-vbguest' plugin. This can take a few minutes...
Fetching: vagrant-share-1.1.9.gem (100%)
Fetching: micromachine-2.0.0.gem (100%)
Fetching: vagrant-vbguest-0.14.2.gem (100%)

In particular, this plugin helps avoid problems that happen when a new kernel is installed, such as the /vagrant shared mount not being available.

Initializing the Vagrant Setup

The learning repository contains a Vagrantfile that lists the systems we’ll use in this book. If you are familiar with Vagrant, you’ll know that we can easily start these systems with vagrant up. We’ll do that now to initialize a client system for learning Puppet:

$ vagrant up client
Bringing machine 'client' up with 'virtualbox' provider...
==> client: Importing base box 'centos/7'...
==> client: Matching MAC address for NAT networking...
==> client: Checking if box 'centos/7' is up to date...
==> client: Setting the name of the VM: learning-puppet4_client_1504376676610_6140
==> client: Clearing any previously set network interfaces...
==> client: Preparing network interfaces based on configuration...
    client: Adapter 1: nat
    client: Adapter 2: hostonly
==> client: Forwarding ports...
    client: 22 (guest) => 2222 (host) (adapter 1)
==> client: Running 'pre-boot' VM customizations...
==> client: Booting VM...
==> client: Waiting for machine to boot. This may take a few minutes...
    client: SSH address: 127.0.0.1:2222
    client: SSH username: vagrant
    client: SSH auth method: private key
    client:
    client: Vagrant insecure key detected. Vagrant will automatically replace
    client: this with a newly generated keypair for better security.
    client:
    client: Inserting generated public key within guest...
    client: Removing insecure key from the guest if it's present...
    client: Key inserted! Disconnecting and reconnecting using new SSH key...
==> client: Machine booted and ready!

On a first boot the vbguest plugin will install the Virtualbox Guest Additions. This requires installing some CentOS packages we’ll skip over, but it should end like this:

Copy iso file VBoxGuestAdditions.iso into the box /tmp/VBoxGuestAdditions.iso
mount: /dev/loop0 is write-protected, mounting read-only
Installing Virtualbox Guest Additions 5.1.26 - guest version is unknown
Verifying archive integrity... All good.
Uncompressing VirtualBox 5.1.26 Guest Additions for Linux...........
VirtualBox Guest Additions installer
Copying additional installer modules ...
Installing additional modules ...
vboxadd.sh: Starting the VirtualBox Guest Additions.

Could not find the X.Org or XFree86 Window System, skipping.
Redirecting to /bin/systemctl start  vboxadd.service
Redirecting to /bin/systemctl start  vboxadd-service.service
==> client: Checking for guest additions in VM...
==> client: Setting hostname...
==> client: Configuring and enabling network interfaces...
    client: SSH address: 127.0.0.1:2222
    client: SSH username: vagrant
    client: SSH auth method: private key
==> client: Rsyncing folder: /Users/jorhett/learning-puppet4/ => /vagrant
==> client: Running provisioner: shell...
    client: Running: inline script

We’ve started only a single machine to learn from, named client. There are several other machines available that we will utilize in future chapters:

$ vagrant status
Current machine states:

client                    running (virtualbox)
puppetmaster              not created (virtualbox)
puppetserver              not created (virtualbox)
dashboard                 not created (virtualbox)
web1                      not created (virtualbox)

This environment represents multiple VMs. The VMs are all listed
above with their current state. For more information about a specific
VM, run `vagrant status NAME`.

You can suspend, resume, and destroy these instances quite easily:

$ vagrant suspend client
==> client: Saving VM state and suspending execution...

$ vagrant resume client
==> client: Resuming suspended VM...
==> client: Booting VM...
==> client: Waiting for machine to boot. This may take a few minutes...
    client: SSH address: 127.0.0.1:2222
    client: SSH username: vagrant
    client: SSH auth method: private key
    client: Warning: Connection refused. Retrying...
==> client: Machine booted and ready!

$ vagrant destroy client
    client: Are you sure you want to destroy the 'client' VM? [y/N] n
==> client: The VM 'client' will not be destroyed, since the confirmation
==> client: was declined.

If you do destroy the instance, just run vagrant up client to create a new instance and start over. We’re not going to spend any more time covering Vagrant here, but remember suspend and resume when you want to stop your test environment but don’t want to have to restart from scratch.

Now that this is running, let’s log in to the client system and get started.

$ vagrant ssh client
[vagrant@client ~]$ 

If you are using Windows and a version of Vagrant below 1.7.5, it has a bug that prevents it from recognizing MinTTY properly. Upgrade to a more recent version.

If you are using Windows and not using Git Bash, you may get an error about SSH not being found. This is due to not having the Git binaries in your path. You can correct that for this command prompt like so:

C:> set PATH=%PATH%;C:Program Files (x86)Gitin

Verifying the /vagrant Filesystem

The folder learning-puppet4 from your personal system should be synced to the client node as /vagrant. Let’s do a quick verification that it shows up here. You should see directory contents similar to this:

$ ls /vagrant
bin  doc  etc-puppet  LICENSE  manifests README.md  systemd-puppet  Vagrantfile

If you don’t see that, read back in your terminal to see if there was an error message about rsync of the /vagrant directory.

Unfortunately this isn’t a book about VirtualBox, so I feel obliged to send you to the VirtualBox support forum for a solution.

Initializing Non-Vagrant Systems

If you are using a virtual machine of your own choice, we’ll need to take a couple of steps so that you can follow the instructions in this book. If possible, mount the learning-puppet4/ directory to the virtual machine as /vagrant/. If you’re not sure how to do this, you can simulate it with the following commands:

$ git clone https://github.com/jorhett/learning-puppet4
…
$ sudo ln -s /home/username/learning-puppet4 /vagrant

Throughout this book, you will see the following prompt shown in the examples:

[vagrant@client ~]$ 

You’ll need to mentally replace this with whatever your virtual node’s shell prompt is. If you wish to ensure it looks the same, you can use the following environment variable to sync them up:

$ export PS1='[vagrant@client W]$ ' 

Installing Some Helpful Utilities

I recommend installing the following helpful utilities on the virtual machine, as we’ll be using them in subsequent chapters:

[vagrant@client ~]$ sudo yum install git

Choosing a Text Editor

Before we install Puppet on your virtual system, stop and take a moment to ensure you have a good text editor available to use. There are two ways to use text editors:

Inside the virtual system

If you are comfortable using Unix text editors such as Vim, Emacs, or Nano, you can run your editor inside the virtual system.

On your desktop

The folder learning-puppet4 is mounted inside the virtual system as /vagrant. This means you can use a text editor of your choice to edit files inside this directory, and they will be visible and available to Puppet on your virtual system.

One issue for both Mac and Windows users is the handling of carriage returns and line feeds within files. Puppet and Git both work best when lines are terminated by line feeds without carriage returns, which is known as “Unix file format.” It is important to select an editor that can read and write files in this format without any surprises.

Many editors on Windows open Unix format files correctly, but will quietly replace the endings with a carriage return when saving. As your target nodes may expect line-feed–terminated files, this can cause file corruption on the target host. Likewise, the opposite problem can exist: if you are editing files to be written out to Windows nodes, then you may need to preserve the carriage returns in the file. If you have a mixed environment of Unix/Linux and Windows nodes, it is essential that your editor can handle both file formats.

The following subsections provide a list of editors we recommend. I have limited this list to only include editors that handle both file formats well. If you don’t have any Windows nodes, then you can use any editor you like.

[vagrant@client ~]$ echo "EDITOR=nano" >> ~/.bashrc

[vagrant@client ~]$ $EDITOR filename

[vagrant@client ~]$ nano filename

Reviewing the Learning Environment

In this chapter, you created a virtualized environment suitable for learning and testing Puppet without affecting any production or personal systems.

The default learning environment we recommended had you install the Git development tools, Vagrant, and VirtualBox to provide a virtualized CentOS system on which you can test and develop.

If you already have a virtualization platform that you prefer to work with, you are welcome to use that instead. We recommended using an operating system compatible with RedHat Enterprise Linux 6 or 7, as it is the best tested and guaranteed version for compatibility with Puppet Supported modules that we will be using throughout the book. After you feel confident in the use of Puppet, there are detailed notes for use on other platforms in Appendix A.

During the course of this chapter, you cloned a Git repository that contains Vagrant system definitions, some example manifests, and other helpful files we’ll use throughout this book.

We also discussed the need for editing text files, and how you can use either an editor on the virtualized system or an editor on your desktop to create and edit Puppet manifests.

This environment is yours to keep. It will be useful as you develop and test Puppet manifests and modules during the learning process.