Deploy and Customize a FreeBSD Virtual Machine Image on Microsoft Azure

VM Depot now has a FreeBSD base image! We expect this to be great news for open source fans who prefer BSD to Linux. And we hope that with the availability of this new base image, we will soon begin to see the community deliver FreeBSD based open source stacks to complement the existing range of Linux images available.

This tutorial below will help you to get started with FreeBSD on Azure using the VM Depot image, by:

  1. Creating a FreeBSD Virtual Machine from the base image
  2. Customizing this virtual machine by adding our own software stack
  3. Republishing the customized image to VM Depot

Setup Requirements

Most of your work will be done on your preferred development machine. It can be any operating system, all you really need is a connection to the internet, a shell or command prompt and a browser. However, there are a couple of pre-requisites:

  • Node.js
  • Microsoft Azure Subscription

Please read through the description below for additional details. If you already have these items configured jump forward to the section on “Creating a FreeBSD Virtual Machine on Microsoft Azure”.

Node.js Cross-Platform Command Line Toolsclip_image002[6]

While most of this work could be performed in the Azure management portal, in this instance, we will be working with the cross-platform node.js command line tools. This tutorial only covers a very small part of the CLI tools, for more information see the Cross platform Azure CLI Documentation page.

If you are using Mac or Windows as your development machines operating system you can either use the Node Package Manager (NPM), as discussed below, or you can use the native installers for your platform (Windows or Mac) and skip forward to the next section. If you are using Linux or would prefer to use NPM then continue reading this section.

Visit the node.js site, click the "Install" button and, follow the installation wizard.

Once node.js is installed, you will need to open a command prompt (on Windows you will need to open it with administrator privileges). You can then install the command line tools with "npm install azure-cli --global".

Azure Subscription

You will need an active Azure subscription. If you don't currently have one, you can sign up for a free trial subscription.

Once you have your Azure subscription set up you need to tell the CLI tools to use it. You can login to a subscription using the tools (“azure login”) but in this tutorial we'll import the subscription credentials into your installation of the command line tools so that you don't need to log in every time you want to do something.

In a command prompt/shell on your development machine run the command "azure account download". This will navigate you to a page in your browser and, after authenticating your account, will start a download of your account credentials. Save the file somewhere convenient then use it to import the account details into the CLI tool by running the command "azure account import [path]".

If you have more than one subscription attached to your live id you will need to ensure that the right subscription is being used. To see which subscription that is currently active run the command "azure account show":


If you want to change the selected subscription you can list which subscriptions are available with the command "azure account list" and then change the active subscription with "azure account set [ACCOUNT]":


Creating a FreeBSD Virtual Machine on Microsoft Azure

Once you have completed the initial set up, you are ready to create your FreeBSD virtual machine on Microsoft Azure. We are working with FreeBSD in this tutorial, however, this will be the same for any image in VM Depot.

To find the FreeBSD image in VM Depot, conduct a simple search for "FreeBSD" on the VM Depot site.


Now click on the "Deployment Script" link to the right of the image description, agree to the terms and select your region, and the required command for deploying this image will be displayed.


Copy this command into your command prompt/shell on your dev machine, replacing the DNS-PREFIX with the prefix that will identify your machine to the world, e.g. Don't forget to provide your own USER_NAME and PASSWORD. You will also want to include the "--ssh" option as this ensures SSH is enabled and that port 22 is open.

There are several configuration options available via the CLI. For the purposes of this tutorial we are going to use the defaults, but you should reference the CLI tools documentation for additional information.

In our examples the command used is "azure vm create rgfreebsd3 -o vmdepot-36254-2-1 -l "West US" rgardler Pa$$Word123 --ssh". Go ahead and run your own version of this command now:


Once this command has completed, you will have created a VM image. However, it may take a short while before it actually starts. You can monitor the status using the "azure vm list" command. Once your VM is listed as "ReadyRole", it will be ready for the next step.


Customizing Your FreeBSD Virtual Machine

You now have a plain vanilla FreeBSD virtual machine running on Microsoft Azure. You can SSH into this machine and do whatever you want with it. For the purposes of this tutorial we will simply add Jetty the web server and javax.servlet container.

First, you will need to log in to the server using SSH. Use the credentials you defined when creating the machine earlier. In our example, we will login with "ssh -l rgardler". You'll need to verify the authenticity of the server the first time you do this. Once the command has completed you will be able to run commands on your new virtual machine.


Now, to use the FreeBSD package manager to install Jetty, simply run the command "sudo pkg install jetty" on the virtual machine. You will also want to make sure that Jetty starts when the machine boots, so add 'jetty_enable="YES"' to /etc/rc.conf and copy the default configuration file with "sudo cp /usr/local/jetty/etc/jetty.xml /usr/local/etc/jetty.xml".

Ideally you would reboot the machine to test whether this works, but the impatient might choose to start Jetty manually with "sudo /usr/local/etc/rc.d/jetty start", then “exit” the machine. Once you have exited you will be back on your dev machine again.

You need to ensure that the outside world can access your new server. HTTP traffic normally goes over port 80, which is not open by default on your virtual machine, so you will need to open it now. To do this, run the command "azure vm endpoint create rgfreebsd3 80 8080" (make sure you use the right name for your machine). This will map the public port 80 to the private (VM) port 8080, which is the default port for Jetty.


Now you can check that everything is working with your browser by visiting the URL you defined when creating the virtual machine (e.g. If everything is working you will see the standard Jetty home page:


Sharing your FreeBSD Image with the VM Depot Community

Having customized the FreeBSD image, it is now time to re-share with the community via VM Depot. You want everyone to benefit from your work, right? Take note that there are a few preparation steps before you can publish via the web form on VM Depot.

The first thing you will need to do is de-provision the virtual machine. This will stop the Azure Agent, remove the SSH keys and root password and delete the network configuration. To do this SSH into the virtual machine again (see earlier). Once logged in execute the command "sudo waagent -deprovision" then "exit" the virtual machine.


Now you should use the CLI on your dev machine to shutdown the virtual machine and capture an image of it. To shutdown run the command "azure vm shutdown rgfreebsd3".


To capture an image of this stopped VM, we ran "azure vm capture rgfreebsd3 freebsd_jetty --delete". Take note that "freebsd_jetty" is the name you want to assign to this image, feel free to use your own name here. The --delete option is required. It will delete your existing (stopped) VM. This is because re-provisioning a captured VM is not currently supported. Don't worry. You will be able to re-provision from the image you are capturing.


You will now have an image from which you can create a new VM. It would be a good idea to verify at this point that everything is working. Yet, you can also skip forward to the publication stage below if you are feeling confident.

Let’s go ahead and create a new VM from the captured image using a command similar to the one used to create a VM from a community image earlier on. The only significant difference will be that we will not be using the "-o" switch to identify a community image, rather we will be using an image attached to our subscription. The command to be used here is "azure vm create rgfreebsd4 freebsd_jetty -l "West US" rgardler Pa$$Word345 --ssh". Remember to use the image name you defined when running the “capture” command above, choose your own DNS prefix to replace “rgfreebsd4” here, and provide your own username and password.

As before, you will need to open the appropriate endpoint so that you can access Jetty on your VM. The command is the same as with the earlier VM (but with the new DNS prefix) e.g. "azure vm endpoint create rgfreebsd4 80 8080". Once you have completed that step, you can visit your new VM in a browser (, as before you should see the Jetty default page:


Publishing to VM Depot

In order to publish your image to VM Depot, you must first ensure that it is readable by the VM Depot application. To do this, you must make the blob in which the VM image is stored publicly accessible. To be consistent, we will use the CLI on our dev machine to do this. Yet, it can also be done through the Azure management portal.

To perform this function, you will need to know where the VM image is stored. Look at the meta-data for the image using the command "azure vm image show freebsd_jetty"


In order to make the blob publicly accessible, you will need a key for the storage container. This can be retrieved with the command "azure storage account keys list <storage-account-name>". The storage account name will be derived from the meta-data you just looked at – specifically, it is the first part of the "MediaLink" URL. In the above example, it is "ajamepiblobs". This will display a primary and secondary key, either of which will work.

Once you have your key, you may run the command "azure storage container set <container-name> -p Blob -a <storage-account-name> -k <key>" to set access control to "Public Blob". The container-name is also contained in the MediaLink URL, it is the first component of the path. In this example, it is "vm-images". The storage-account-name is the same name you used in the previous step and the key is the one you just retrieved.

Now that VM Depot is able to read the VM image, you can easily publish it to VM Depot.

Log in to VM Depot and click the "Publish" button. You will be presented with a short form:


This form should be pretty straightforward. One potentially complex item may be the request for the URL of the VHD. This is the MediaLink URL referenced above when running the "azure vm image show freebsd_jetty" command.

It takes a little while for the image to be copied across all of the regions you have selected, you’ll see status updates on the webpage that you are taken to after submitting the above form. Additional details about the submission process are available on in the VM Depot help documents. Once they have been copied they will appear in VM Depot and you can delete you local copy of the VM (no point in paying storage costs when we'll pick up the bill on VM Depot) and start telling everyone you know about your wonderful new VM image.

One thought on “Deploy and Customize a FreeBSD Virtual Machine Image on Microsoft Azure

  1. Pingback: FreeBSD on Azure « ブチザッキ