vagabond
A simple utility for managing the virtual machine lifecycle
Introduction
Vagabond is a tool to manage the lifecycle of virtual machines. It is useful in environments where a build environment may not completely match the deployment environment. Vagabond makes it easy to install a virtual machine for testing from the command line or an automated script. Vagabond takes it's configuration information from a properties file suitable for inclusion into a source code control system.
In short, Vagabond makes dealing with virtual machines a little easier on developers.
Install
Vagabond is dependent on Oracle's VirtualBox system, so it should be installed before you install Vagabond. You should also ensure that the VBoxManage utility is in your path before executing Vagabond commands.
To install Vagabond, use NPM:
sudo npm install -g vagabond
Simple Example
Before starting a Vagabond-managed virtual machine, you should create a configuration file with the "init" command:
vagabond init
This will create the file vagabond.json
with a few default configuration options.
Here's an example:
{ "name": "66e3efa7e9143ddb_helium", "hostname": "helium", "addr": "192.168.56.2", "ova": "http://sm5.us/larb/Larb%20v2.02%20Debian%207.3.0%20i386.ova", "user": { "name": "<username>", "ssh": "ssh-rsa AAAAB3N ..." } }
If Vagabond can determine your username and find your SSH public key, it will fill in those values
automagically. If it can't, you should add them yourself. If you plan to use Samba file
sharing or you don't want to use public-key authentication with SSH, you must add a
passwd
entry to the user object, so it looks something like this:
"user": { "name": "<username>", "passwd": "IAmABadPassword", "ssh": "ssh-rsa AAAAB3N ..." }
After editing the vagabond.json file, you're ready to create a virtual machine instance, launch it and log in with these commands:
vagabond create vagabond launch vagabond user ssh `vagabond ip`
The commands listed above create a virtual machine, start the virtual machine, create the user account defined in the vagabond.json file and ssh to the virtual machine. Once you're finished with the virtual machine, you can destroy it with these commands:
vagabond shutdown vagabond destroy
You can specify multiple commands with a single instance, like this:
vagabond create launch user; \ `vagabond ssh` "npm install foo; cd node_modules/foo/test; ./test"; \ vagabond shutdown destroy
Command Line Options
init - Create a skeletal init file
This command creates a skeletal vagabond.json
file. You should do this once before using
other Vagabond commands.
create - Create a virtual machine instance
This command uses the VirtualBox appliance file specified in the configuration file to create a new
virtual machine instance. If the appliance file is not found in the local cache (in the ~/.vagabond
directory) it will download a local copy.
launch - Starts a virtual machine instance
This command starts a virtual machine and waits for the OpenSSH service in the virtual machine to start.
user - Creates a user in the virtual machine
This command creates a user account in the virtual machine using parameters found in the configuration file.
ip - return the ip address of the virtual machine's internal network adapter
This command echos the IP address of the virtual machine's internal network adapter. Example:
ssh `vagabond ip`
ssh - return a ssh command to connect to the virtual machine
When connecting to a machine via ssh, it will cache that machine's server public key in the
~/.ssh/known_host
file. New server keys are generated for each machine created,
which will lead to stale key fingerprints in the known_host file. This command echos a
ssh command that ignores the known_host file when connecting to the virtual machine. Unix
users can use it like this:
`vagabond ssh`
shutdown - shutdown a virtual machine
This command shuts down a virtual machine and waits for it to completely stop.
destroy - destroy the virtual machine instance
This command destroys the virtual machine instance specified in the config file.