We’d like to spotlight TrueOS community member Cliff Gordon (chief1983 on Discourse) for documenting his experience setting up a TrueOS Vagrant box. Great job! I’ve reproduced his work here, but please head over to his post on Discourse to ask questions or discuss using Vagrant with TrueOS.


TrueOS Vagrant Boxes


I have created my first ever Vagrant box hosted on Hashicorp’s Atlas.


It is a mostly clean install of TrueOS STABLE 2017-06-01, currently only supporting VirtualBox as a provider. I might have goofed something up, but I thought I would document my process here for posterity and for anyone to point out any improvements that could be made.


# Install vagrant from https://www.vagrantup.com/
mkdir trueos-vagrant
cd trueos-vagrant
vagrant init chief1983/trueos-server64
# Make any desired edits to the Vagrantfile if you wish
vagrant up

Why Vagrant

For those not too familiar with Vagrant, this allows me to quickly reset my entire machine to a known original state and I don’t have to worry about physical hardware. That might also be possible with solid usage of boot environments, but I can also easily manipulate the network configuration of the machine, and also easily mount shared folders via NFS, something that is a bigger pain to deal with when using just VirtualBox alone. The overall setup time is reduced as well, since the base machine is already installed. You download the base box once and it remains cached until you delete it, making subsequent destroys and rebuilds very fast. It also comes pre-configured for password-less sudo, another step that is a time-save for a locally hosted development machine. All in all, I think this would be a huge help for anyone interesting in experimenting with TrueOS in any kind of server or desktop environment role. I made a desktop box as well, as I’ve found the ease of shared folder creation carries over well to the desktop world, even though desktop vagrant boxes are not terribly common.

Build Details

First, it helps to have the basic understanding of how to create a Vagrant box for local use. Most of this is copied from a Google doc I used to document that process. Reading the official Vagrant documentation on this is very helpful.




When creating the new VirtualBox machine, there are some options that are fairly important to get right.

  • The machine needs to be configured as 64-Bit FreeBSD machine, which should be obvious.
  • Make note of the machine name, you will need it for packaging below. I used “TrueOS Vagrant Dev”.
  • When choosing the initial hard drive, I create a new 50GB VMDK dynamically allocated drive.
  • Under General/Advanced, For a desktop machine, I believe the Shared Clipboard setting has been working (I leave it checked anyway, it has caused me no trouble so far).
  • Under System/Motherboard, the memory can be adjusted via the Vagrantfile, but I start with 2GB (could probably go smaller by default on the server one).
  • I correct the boot order for an installed system, so it starts with the hard drive.I could probably uncheck the CD-ROM completely as a boot device.
  • I’ve been using the PIIX3 chipset, PS/2 Mouse as a pointing device, and have enabled all extended features (I/O APIC, EFI, Hardware Clock in UTC time).
  • Under System/Processor, it is configured to 1 CPU, 100% Execution cap, and PAE/NX is enabled.
  • Under System/Acceleration, paravirtualization interface is left at default, and Nested Paging is enabled.
  • Under Display/Screen, I increase the video memory from the default for a desktop machine to 32MB. It could remain default for a server. Monitor count is left alone, but I do enable 3d Acceleration for the desktop machines and have had no issue yet.
  • Under Storage, I remove the default IDE controller and move the VMDK and CD-ROM drive to a new SATA controller. I have read reports it might help with the VM performance, but haven’t done any tests myself. I’ve been happy with the performance using this method though.
  • I enable the Host I/O cache on the SATA controller, and set the VMDK drive to a Solid-state drive (also something that I thought I read might improve performance).
  • I leave audio enabled, and set to ICH AC97, and the default Host Audio Driver (wondering how well this will work when moving the VM to platforms besides Macintosh though). Could probably disable Audio for the server release.
  • Under Network, you need to start with one NAT adapter I believe. Vagrant will toss out any network configuration in the VM and match the configuration to its own needs anyway, so it probably doesn’t matter what you configure. But I do boot the machine at least once with a Host-only adapter, in the belief that maybe having it see the host-only interface at least once might help it configure it faster the next time. Not sure if there’s any truth to that.
  • Under ports, I enable the USB 2.0 controller.
  • No need to configure Shared Folders.
  • I have not experimented with any machine UI configuration yet, could be some useful changes there perhaps.

Install TrueOS

Now it is time to install TrueOS Server or Desktop into the newly created VM. You’ll need to configure the VM CD-ROM drive to mount the downloaded ISO, and make sure it is configured to boot to CD-ROM for the time being. The installer should start, and some care needs to be given to certain options during the install process:

  • Check Enable SSHD during post-install configuration (works for Desktop last I checked, but server needs to manually add SSHD_ENABLE=”YES” to the rc.conf still)
  • Use full-disk and defaults for the HD configuration
  • Sync clock to UTC
  • root pass should be set to vagrant
  • Daily User: Vagrant User/vagrant/vagrant

Final Configuration

After the install, the box is almost ready to be packaged. There are a few more necessary (or optional but beneficial) tweaks to be made before it will work as expected, mostly documented in the Vagrant docs.

  • For the Desktop only, I disable the screensaver and power saving settings, and pin QTerminal to Favorites.
  • Bash must be installed for Vagrant to function correctly, if the distro didn’t already.
sudo pkg install -y bash
  • On the Desktop, I disable the firewall so it won’t interfere with host to guest networking.
sudo service ipfw stop
sudo rc-update del ipfw boot
  • I also install nano if it’s not already
sudo pkg install -y nano
  • I install the insecure Vagrant public key, which is now replaced with a randomly generated pair on the first boot of your VM, so no real concerns to be had with your VM running a known private key. The key installation proces can be scripted as follows.
mkdir ~/.ssh
chmod 700 ~/.ssh
echo "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA6NF8iallvQVp22WDkTkyrtvp9eWW6A8YVr+kz4TjGYe7gHzIw+niNltGEFHzD8+v1I2YJ6oXevct1YeS0o9HZyN1Q9qgCgzUFtdOKLv6IedplqoPkcmF0aYet2PkEDo3MlTBckFXPITAMzF8dJSIFo9D8HfdOV0IAdx4O7PtixWKn5y2hMNG0zQPyUecp4pzC6kivAIhyfHilFR61RGL+GPXQ2MWZWFYbAGjyiYJnAmCP3NOTd0jMZEnDkbUvxhMmBYSdETk1rRgm+R4LOzFUGaHqHDLKLX+FIPKcF96hrucXzcWyLbIbEgE98OHlnVYCzRdK8jlqm8tehUc9c9WhQ== vagrant insecure public key" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
  • Password-less sudo is important for Vagrant functionality. The commands below should be able to accomplish it without much more interaction than entering the sudo password (or just login as root and run them that way). They should also ensure that you don’t accidentally leave your sudoers file in a broken state.
sudo cp /usr/local/etc/sudoers /usr/local/etc/sudoers.tmp
sudo chmod 666 /usr/local/etc/sudoers.tmp
echo "vagrant ALL=(ALL) NOPASSWD: ALL" >> /usr/local/etc/sudoers.tmp
sudo chmod 440 /usr/local/etc/sudoers.tmp
sudo visudo -c -f /usr/local/etc/sudoers.tmp && sudo mv /usr/local/etc/sudoers.tmp /usr/local/etc/sudoers
  • Disabling DNS lookups from SSH can speed up the SSH behavior with Vagrant significantly. This command can automate that regardless of the value of the setting or if it is commented out in your existing ssh config file.
sudo sed -E -i.bak 's/^#?UseDNS .*/UseDNS no/' /etc/ssh/sshd_config
  • Because of the broken shared folder support, the /vagrant/ shared folder cannot load by default on FreeBSD. But it can load via an NFS share, which will allow the VM to load /vagrant/ and act like a normal *nix Vagrant machine. This can be configured to happen by default, without end user intervention, with a custom Vagrantfile included with the box.
    This one is the one from the Desktop, as it has an extra argument indicating to Vagrant that the GUI should be enabled (the box is not headless).
Vagrant.configure("2") do |config|
  config.vm.synced_folder ".", "/vagrant", disabled: true
  config.vm.post_up_message = <<-EOT
Shared folders do not work with BSD guests and VirtualBox, so /vagrant is unavailable.
To access it, add a host-only network interface to your Vagrantfile, like follows:
config.vm.network "private_network", ip: ""
DHCP also does not seem to work at the moment, so you will need to pick a static IP.
Then just add the following to enable the shared folder via NFS:
config.vm.synced_folder ".", "/vagrant", type: "nfs"
This can also be used to add any other shared folders you would like to access.
You will likely be required to supply your sudo password as Vagrant will edit /etc/exports.
See https://www.vagrantup.com/docs/synced-folders/nfs.html#root-privilege-requirement
for info on how to avoid that.
  config.vm.provider "virtualbox" do |v|
    v.gui = true

I just place this file alongside where I will be creating the Vagrant box, in my workspace folder.


Your box is configured! All that’s left now is packaging and uploading it. I was hung up on getting from the packaging concept to the uploading concept, but it’s actually much easier than I had though it would be. The name, versioning, etc of your local box doesn’t actually matter at all. That is all configured on the Hashicorp Atlas website. So, shut down the VM, and we will package it with the following command (remember the –base argument is the machine name you provided when you created the new VirtualBox machine earlier). Parts I change between whether I am working with the Desktop or Server are indicated with square brackets below. I have two different base Vagrantfiles, because it was easier than remembering to delete or add the v.gui option each time.

vagrant package --base "TrueOS Vagrant Dev" --output TrueOS[Desktop|Server].box --vagrantfile Vagrantfile[-desktop].pkg

Once you have packaged your box, you should probably test it. Add it to your local box cache with the following command.

vagrant box add TrueOS[Desktop|Server] ./TrueOS[Desktop|Server]Vagrant.box

Spawn a new machine using this newly cached box.

mkdir trueos-vagrant-test
cd trueos-vagrant-test
vagrant init TrueOS[Desktop|Server]
vagrant up

If all goes well, you’ll have a clean bit of output and be able to vagrant ssh, see your /vagrant/ shared folder containing your local Vagrantfile, install packages, etc. The last bit now is to share your box with the world.


I will admit I had a hard time finding the Create Account link on the Atlas site. In fact I only found it in the Vagrant docs themselves. Maybe I was just suffering temporary blindness. Anyway, visit the link to create a new Atlas account on Hashicorp if you don’t already have one. Be sure to validate your email address. Once logged in, you can see your existing boxes (probably don’t have any if you just created an account), and create a new box via the aptly-named New Box button. Once I got this far, it was fairly self-explanatory as I’ve got a bit of experience using Vagrant boxes already, but I’ll try to cover the items for anyone less familiar.

The box name consists of your username followed by the actual box name you define. Hence why mine is chief1983/trueos-server64. I defined the trueos-server64 part. The ubuntu org has the ubuntu account, which is why theirs can be ubuntu/zappy64 or whatever. If someone were to create a trueos account to make these official they could have the same result, but I did not want to presume I should do that.

Leave the Private checkbox unchecked, and give a short description of the box (really the descriptive title of the box would suffice).

The next page has one of the more important fields, the version. This is used to control box updates to your end users. They highly recommend semantic versioning, which works well with the new release system. I have used a version of 20170601.0.0. The release date is the major version. As it is now ABI compatible throughout any updates to the release, it works fine to use the full release date as the major version number. Any other non-breaking significant or tweak updates to the box could warrant updating the second or third significant version, respectfully.

The full description field is where you could write a novel if you’d like defining all the significant configuration tweaks to your box, and sell end users on why your version of operating system Y is better than some other release. Maybe you included chef, puppet, a full web stack, etc out of the box. That’s where to explain those things.

Once you have created your box, you can make further edits to the configuration, or version, upload your box, and finally you can release it to the unsuspecting masses.

To upload your box, you need to add a provider. Since we just built our box using VirtualBox, we’ll do that.

  • Click “Create new provider” under your new version display.
  • Fill in “virtualbox” in the provider field (without quotes of course).
  • If you uploaded it to a remote server already, you can specify the URL.
  • Otherwise, upload your box via the web interface
  • If uploading, it’s probably a good time to use the restroom, grab lunch, take a nap, etc. The box is likely around 2.5GB and will take a little while to upload.
  • Once the upload is complete, return to Edit your version, and click the release button. That should do it!

The commands at the beginning of the article should now work for you to create a new local Vagrant machine, changing the box name to the one you just created. You may want to delete any test Vagrant machines, and prune any unused imports of your local Vagrant box to free up some space. They can start to add up when your HD space is a bit limited.

This is the most detailed technical write-up I’ve done for public consumption in quite some time, so I hope I haven’t been too verbose or glossed over anything too quickly. If there are any questions or suggestions for process improvement, please don’t hesitate to offer them. I’m fairly new to TrueOS, FreeBSD, and BSDs in general. I hope for these machines to be very useful to anyone with Vagrant experience and who desires an easy way to dip their toes into the TrueOS world.


(EDIT: Just one more thing…)


Because the guest additions were already installed, I did not have a step for that in my notes. But on the server side of things, they need to be manually installed. You should install the no-X11 version of them as well.

sudo pkg install -y virtualbox-guest-additions-nox11

This will ensure things like the host-only adapter and port forwarding work.

You may also need to follow the package’s instructions to enable the kernel extension to be loaded in rc.conf. I believe what might be necessary is to add the following: