There’s plenty of documentation out there on how to implement a VIRL server in the cloud, specifically Packet’s bare metal cloud service. But I wanted to document the process during a play-by-play installation process with the hopes of capturing any one-off nuances or issues that come up.

I’ll be installing VIRL on Packet for use on macOS Sierra (10.12.2) without any prerequisites installed. This is as scratch as it gets.

Prerequisites

  1. You’ll need VirtualBox installed to host the VM that will perform the remote calls to Packet’s API in order to get your VIRL server spinning up in the cloud. You can create bare metal servers straight from Packet’s Web UI / Portal, but I much preferred this method in terms of consistent, concise, quick, and trackable delivery.
  2. You’ll need to install Vagrant as well. It’s an awesome tool that was developed to make building & maintaining VM’s much easier.
  3. SSH. You’re all set if you’re running macOS.
  4. Git. I installed Git with Homebrew. If you don’t have Homebrew, you can install it by running /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)", then just run brew install git to install Git from the terminal. There are dozens of GUI-based Git clients if you prefer a graphical experience.
  5. Tunnelblick. This is a free open-source OpenVPN client. Download it here. You’re welcome to use any OpenVPN client you’re comfortable with.
  6. VIRL license file. That will be 2 Benjamins, please.
  7. VM Maestro Installer. This is the client side app, and is bundled with the VIRL server during provisioning. You must be licensed to use VIRL by Cisco in order to access the VIRL client software.
  8. Packet.net account. Free to setup. Check here for pricing plans.

Procedure

    1. Open Terminal and run the following command to ensure that the Vagrant plugin is up-to-date.
      vagrant plugin install virtualbox
    2. Login to your Packet.net account and create an API key. I already had a key created at the time of this writing, but I can attest to the process being very intuitive via the web UI.
    3. Now we need to setup Boxcutter on your local filesystem. In the Terminal, run git clone https://github.com/Snergster/virl_boxcutter.git to clone the Boxcutter repository to ~/ of your local filesystem.

      virl_boxcutter directory cloned from Git repo located in my local home directory
    4. Make sure you have your VIRL license file/key handy. If you don’t, download it by logging in here.
    5. Copy your license file to virl_boxcutter/salt. I did it from my Downloads folder via the following command (but you can use Finder if you prefer):
      cp ~/Downloads/xxxxxxxx.virl.info.pem ~/virl_boxcutter/salt/
    6. Rename xxxxxxxx.virl.info.pem to minion.pem.
      mv xxxxxxxx.virl.info.pem minion.pem
    7. Make a backup copy of id.conf.orig from the root of virl_boxcutter and rename it id.conf.
      cp id.conf.orig id.conf
    8. Open the newly created id.conf with a text editor of your choice. I used nano [because I’m beta and hate vim].
      sudo nano id.conf
    9. You should see the following lines of text:
      id: badid
      append_domain: virl.info

       

      1. Change badid to %VIRL-license-key% — your key is the 8-digit string listed in the filename of xxxxxxxx.virl.info.pem.
      2. Change virl-info to %VIRL-license-File-End% — this is the entirety of the license key filename following xxxxxxxx. (e.g. virl30.info or virl.info)
    10. Save the file and verify it’s contents. If you’re using nano, press control+O and Enter to save the file, then control+X to exit nano. Enter cat if.conf and verify that the output reads the correct values.
    11. From the root of virl_boxcutter, make a copy of settings.tf.orig and rename it settings.tf
      cp settings.tf.orig settings.tf
    12. Open settings.tf
      nano settings.tf
    13. Replace bad_api_key with the Token that we generated in Step 2.
    14. [Optional] Change the value for variable packet_machine_type if you need to deviate from Packet’s default server settings. packet_machine_type defines how many resources your bare metal server will be procured with. You can read the specs on each machine type on Packet’s website. At the time of this writing, it was as follows:
      Server Type Variable Description
      Type 0 baremetal_0 4 Cores @ 2.4Ghz 8Gb RAM 80Gb SSD 1Gbps
      Type 1 baremetal_1 4 Cores @ 3.4Ghz 32 Gb RAM 120Gb SSD 2Gbps
      Type 2 baremetal_2 24 Cores @ 2.2Ghz 256Gb RAM 2.8Tb SSD HBA/RAID Controller 20Gbps
      Type 2A baremetal_2a 96 Cores @ 2.0Ghz 128 Gb RAM 340 Gb SSD 20 Gbps
      Type 3 baremetal_3 16 Cores @ 2.6Ghz 128 Gb RAM 120 Gb RAID1 SSD 1600 Gb NVMe Flash 20 Gbps
      I had at least 1 or 2 poor experiences using Type 0 with the Boxcutter method. While Type 1 typically took 30-45 minutes to provision the Packet server, Type 0 took well over an hour, and in one instance triggered terraform to enter a hung state.Type 0 fits the minimum spec requirements for VIRL. But when I queried the Packet Support team, they advised to stick with Type 1 specifically because of slow provisioning times. Packet’s Guide on VIRL Deployments specifically states that “to meet VIRL’s minimum system requirements Type 0 would be fine.” But their Support Team explained to me that “going to Type, 0 it will affect a lot the time for the whole thing to come up…” I couldn’t find any formal documentation on min/avg/max provisioning times for each of the server types, so you’ll have to consider that potential when choosing your server.
    15. [Optional] Change the value for variable dead_mans_timer if you want to deviate from the Packet default kill switch timer of 4 hours. The purpose of this is to avoid racking up undesired Packet charges because you unknowingly left your server running for an indefinite period. Read more about it here.
    16. Open Terminal and navigate to the root of virl_boxcutter if you’ve not done so already.
      cd ~/virl_boxcutter
    17. Enter the following to begin configuring your local Boxcutter VM:
      vagrant up
      Note that this may take several minutes (~5) if you’re spinning up a fresh VM.
      In the future, you can run vagrant halt to forcefully shutdown the VM or vagrant suspend to suspend the VM. In either case, you can run vagrant up to bring it back online, which will circumvent the 5+ minutes of provisioning that we’re running through now. Alternatively, you have the option of killing and re-provisioning the VM after each use with vagrant destroy.
    18. When your VM has finished spinning up, SSH into it.
      vagrant ssh
      Verify that your CLI identification changes:

      vagrant@vagrant:~$
    19. Navigate to the virl_packet directory
      cd virl_packet
    20. Enter the following to prepare your VIRL server:
      terraform plan . [Don’t forget the ‘dot’!]
    21. Run the following the execute the procurement of your VIRL server:
      terraform apply . [Don’t forget the ‘dot’!]
      Note that this typically takes 30-45 minutes, and sometimes upwards of an hour. Read my notes in Step 14 for additional clarity. In either case, get some coffee and check back occasionally because it’s going to take a while.

    22. When the installation finishes, take particular note of the tail output. It includes the VIRL server info you’ll need to connect & login to the server.
    23. Copy the OpenVPN Profile (that Vagrant automatically generated) to your local filesystem.
      cp ./client.ovpn /vagrant/
    24. Start Tunnelblick if it’s not already running.
    25. Open Finder and navigate to ~/virl_boxcutter/ (the root of virl_boxcutter may vary depending on your Git configuration). From there, drag client.ovpn on top of the Tunnelblick icon in your System Tray.
    26. Click the Tunnelblick icon and select Connect client.
      Taking note here for the worrisome – the connection process is usually quick & painless, but I’ve had multiple experiences where it took upwards of 3 minutes to connect. If you didn’t run into any issues until now, it could be Packet having network issues. Try opening a ticket with Packet Support to make sure it’s not you.
    27. Once you’re connected, navigate to the “uwm over OpenVPN” address (e.g. http://172.16.11.254:19400) via a web browser. The “uwm over OpenVPN” value is included in the trailing terraform output as seen in the screenshot above.
    28. Login using the “uwm login” credentials as seen in the trailing terraform output.
    29. Expand VIRL Server from the left pane, then select VIRL Software.
    30. Check the radio box next for “VM Maestro Mac OSX” then click Start installation.
    31. Navigate back to your VIRL Server Homepage by removing all trailing port and subdomain information from the address (e.g. http://172.16.11.254:19400/admin/ >> http://172.16.11.254).
    32. Click VM Maestro Clients & Python Libraries
    33. Click VMMaestro-dev-1.2.8-474.dmg to begin downloading the most up-to-date VIRL client installer. (Your filename may vary slightly).
    34. Run the installer.
      Note that you may need to authorize the installation by navigating to System Preferences > Security & Privacy > Open Anyway.
    35. Once the installer creates a mount point on your filesystem, navigate to it.
    36. Select the VMMaestro application and move it to your Applications folder.
    37. Open VM Maestro.
    38. Click Agree when the License Agreement pop-up appears.
    39. A window will appear requesting input for a Server, Username, and Password.

      Replace the info with the variables generated from the terraform output.

    40. Click OK.
    41. A “Secure Storage – Password Hint Needed” pop-up will appear. You can click No. There’s no need for a password hint because Packet will randomly generate a unique password upon each VIRL server spin-up.
    42. To verify that VM Maestro has successfully connected to the VIRL server, click VM Maestro in the System Tray Menu, then click Preferences. Click Web Services in the left pane, and verify that all services have green checkmarks.
    43. That’s it! You’re all set to start deploying nodes on your remote VIRL server.