diff --git a/website/docs/source/layouts/layout.erb b/website/docs/source/layouts/layout.erb index cb93de1fd..9f957dff3 100644 --- a/website/docs/source/layouts/layout.erb +++ b/website/docs/source/layouts/layout.erb @@ -137,6 +137,7 @@ >Boxes <% if sidebar_section == "boxes" %> <% end %> @@ -190,7 +191,7 @@ <% if sidebar_section == "virtualbox" %> <% end %> diff --git a/website/docs/source/stylesheets/_pages.less b/website/docs/source/stylesheets/_pages.less index c336f0ea2..5daab0892 100644 --- a/website/docs/source/stylesheets/_pages.less +++ b/website/docs/source/stylesheets/_pages.less @@ -12,7 +12,8 @@ .page-contents { h1, - h2 { + h2, + h3 { text-transform: uppercase; text-align: left; .museo-sans-light; @@ -37,6 +38,14 @@ margin-top: @baseline * .5; } //h2 first child } //h2 + + h3 { + margin: (@baseline * 2) 0 @baseline; + + &:first-child { + margin-top: @baseline * .5; + } //h3 first child + } } //page-contents /* home */ diff --git a/website/docs/source/v2/boxes/base.html.md b/website/docs/source/v2/boxes/base.html.md new file mode 100644 index 000000000..57f213890 --- /dev/null +++ b/website/docs/source/v2/boxes/base.html.md @@ -0,0 +1,198 @@ +--- +page_title: "Creating a Base Box" +sidebar_current: "boxes-base" +--- + +# Creating a Base Box + +There are a special category of boxes known as "base boxes." These boxes +contain the bare minimum required for Vagrant to function, are generally +not made by repackaging an existing Vagrant environment (hence the "base" +in the "base box"). + +For example, the Ubuntu boxes provided by the Vagrant project (such as +"precise64") are base boxes. They were created from a minimal Ubuntu install +from an ISO, rather than repackaging an existing environment. + +Base boxes are extremely useful for having a clean slate starting point from +which to build future development environments. The Vagrant project hopes +in the future to be able to provide base boxes for many more operating systems. +Until then, this page documents how you can create your own base box. + +
+

+Advanced topic! Creating a base box can be a time consuming +and tedious process, and is not recommended for new Vagrant users. If you're +just getting started with Vagrant, we recommend trying to find existing +base boxes to use first. +

+
+ +## What's in a Base Box? + +A base box typically consists of only a bare minimum set of software +for Vagrant to function. As an example, a Linux box may contain only the +following: + +* Package manager +* SSH +* SSH user so Vagrant can connect +* Perhaps Chef, Puppet, etc. but not strictly required. + +In addition to this, each [provider](/v2/providers/index.html) may require +additional software. For example, if you're making a base box for VirtualBox, +you'll want to include the VirtualBox guest additions so that shared folders +work properly. But if you're making an AWS base box, this is not required. + +## Creating a Base Box + +Creating a base box is actually provider-specific. This means that depending +on if you're using VirtualBox, VMware, AWS, etc. the process for creating +a base box is different. Because of this, this one document can't be a +full guide to creating a base box. + +This page will document some general guidelines for creating base boxes, +however, and will link to provider-specific guides for creating base +boxes. + +Provider-specific guides are linked below: + +* [VirtualBox Base Boxes](/v2/virtualbox/boxes.html) + +### Disk Space + +When creating a base box, make sure the user will have enough disk space +to do interesting things, without being annoying. For example, in VirtualBox, +you should create a dynamically resizing drive with a large maximum size. +This causes the actual footprint of the drive to be small initially, but +to dynamically grow towards the max size as disk space is needed, providing +the most flexibility for the end user. + +If you're creating an AWS base box, don't force the AMI to allocate +terabytes of EBS storage, for example, since the user can do that on their +own. But you should default to mounting ephemeral drives, because they're +free and provide a lot of disk space. + +### Memory + +Like disk space, finding the right balance of the default amount of memory +is important. For most providers, the user can modify the memory with +the Vagrantfile, so don't use too much by default. It would be a poor +user experience (and mildly shocking) if a `vagrant up` from a base box +instantly required many gigabytes of RAM. Instead, choose a value such +as 512MB, which is usually enough to play around and do interesting things +with a Vagrant machine, but can easily be increased when needed. + +### Peripherals (Audio, USB, etc.) + +Disable any non-necessary hardware in a base box such as audio and USB +controllers. These are generally unnecessary for Vagrant usage and, again, +can be easily added via the Vagrantfile in most cases. + +## Default User Settings + +Just about every aspect of Vagrant can be modified. However, Vagrant does +expect some defaults which will cause your base box to "just work" out +of the box. You should create these as defaults if you intent to publicly +distribute your box. + +If you're creating a base box for private use, you should try _not_ to +follow these, as they open up your base box to security risks (known +users, passwords, private keys, etc.). + +### "vagrant" User + +By default, Vagrant expects a "vagrant" user to SSH into the machine as. +This user should be setup with the +[insecure keypair](https://github.com/mitchellh/vagrant/tree/master/keys) +that Vagrant uses as a default to attempt to SSH. Also, even though +Vagrant uses key-based authentication by default, it is a general convention +to set the password for the "vagrant" user to "vagrant". This lets people +login as that user manually if they need to. + +To configure SSH access with the insecure keypair, place the public +key into the `~/.ssh/authorized_keys` file for the "vagrant" user. Note +that OpenSSH is very picky about file permissions. Therefore, make sure +that `~/.ssh` has `0700` permissions and the authorized keys file has +`0600` permissions. + +### Root Password: "vagrant" + +Vagrant doesn't actually use or expect any root password. However, having +a generally well known root password makes it easier for the general public +to modify the machine if needed. + +Publicly available base boxes usually use a root password of "vagrant" to +keep things easy. + +### Password-less Sudo + +This is **important!**. Many aspects of Vagrant expect the default SSH user +to have passwordless sudo configured. This lets Vagrant configure networks, +mount synced folders, install software, and more. + +To begin, some minimal installations of operating systems don't even include +`sudo` by default. Verify that you install `sudo` in some way. + +After installing sudo, configure it (usually using `visudo`) to allow +passwordless sudo for the "vagrant" user. This can be done with the +following line at the end of the configuration file: + +``` +vagrant ALL=(ALL) NOPASSWD: ALL +``` + +Additionally, Vagrant doesn't use a pty or tty by default when connected +via SSH. You'll need to ake sure there is no line that has `requiretty` in +it. Remove that if it exists. This allows sudo to work properly without a +tty. Note that you _can_ configure Vagrant to request a pty, which lets +you keep this configuration. But Vagrant by default doesn't do this. + +### SSH Tweaks + +In order to keep SSH speedy even when your machine or the Vagrant machine +is not connected to the internet, set the `UseDNS` configuration to `no` +in the SSH server configuration. + +This avoids a reverse DNS lookup on the connecting SSH client which +can take many seconds. + +## Other Software + +At this point, you have all the common software you absolutely _need_ for +your base box to work with Vagrant. However, there is some additional software +you can install if you wish. + +While we plan on it in the future, Vagrant still doesn't install Chef +or Puppet automatically when using those provisioners. Uesrs can use a shell +provisioner to do this, but if you want Chef/Puppet to just work out of the +box, you'll have to install them in the base box. + +Installing this is outside the scope of this page, but should be fairly +straightforward. + +In addition to this, feel free to install and configure any other software +you want available by default for this base box. + +## Packaging the Box + +Packaging the box into a `box` file is provider-specific. Please refer to +the provider-specific documentation for creating a base box. Some +provider-specific guides are linked to towards the top of this page. + +## Testing the Box + +To test the box, pretend you're a new user of Vagrant and give it a shot: + +``` +$ vagrant box add my-box /path/to/the/new.box +... +$ vagrant init my-box +... +$ vagrant up +... +``` + +If you made a box for some other provider, be sure to specify the +`--provider` option to `vagrant up`. If the up succeeded, then your +box worked! diff --git a/website/docs/source/v2/virtualbox/boxes.html.md b/website/docs/source/v2/virtualbox/boxes.html.md index cd144cbff..91c6c8773 100644 --- a/website/docs/source/v2/virtualbox/boxes.html.md +++ b/website/docs/source/v2/virtualbox/boxes.html.md @@ -1,21 +1,26 @@ --- -page_title: "Box Format - VirtualBox Provider" +page_title: "Creating a Base Box - VirtualBox Provider" sidebar_current: "virtualbox-boxes" --- -# Boxes +# Creating a Base Box As with [every provider](/v2/providers/basic_usage.html), the VirtualBox -provider has a custom box format. +provider has a custom box format that affects how base boxes are made. -This page documents the format so that you can create your own base -boxes. Note that currently you must make these boxes by hand. A future -release of Vagrant will provide additional mechanisms for automatically -creating such images. +Prior to reading this, you should read the +[general guide to creating base boxes](/v2/boxes/base.html). Actually, +it would probably be most useful to keep this open in a separate tab +as you may be referencing it frequently while creating a base box. That +page contains important information about common software to install +on the box. -
+Additionally, it is helpful to understand the +[basics of the box file format](/v2/boxes/format.html). + +

- Note: This is a reasonably advanced topic that + Advanced topic! This is a reasonably advanced topic that a beginning user of Vagrant doesn't need to understand. If you're just getting started with Vagrant, skip this and use an available box. If you're an experienced user of Vagrant and want to create @@ -23,10 +28,71 @@ creating such images.

-Prior to reading this page, please understand the -[basics of the box file format](/v2/boxes/format.html). +## Additional Software -## Contents +In addition to the software that should be installed based on the +[general guide to creating base boxes](/v2/boxes/base.html), +VirtualBox base boxes require some additional software. + +### VirtualBox Guest Additions + +[VirtualBox Guest Additions](http://www.virtualbox.org/manual/ch04.html) +must be installed so that things such as shared folders can function. +Installing guest additions also usually improves performance since the guest +OS can make some optimizations by knowing it is running within VirtualBox. + +Before installing the guest additions, you'll need the linux kernel headers +and the basic developer tools. On Ubuntu, you can easily install these like +so: + +``` +$ sudo apt-get install linux-headers-$(uname -r) build-essential +``` + +Next, make sure that the guest additions image is available by using the +GUI and clicking on "Devices" followed by "Install Guest Additions". +Then mount the CD-ROM to some location. On Ubuntu, this usually looks like +this: + +``` +$ sudo mount /dev/cdrom /mnt/cdrom +``` + +Finally, run the shell script that matches your system to install the +guest additions. For example, for Linux on x86, it is the following: + +``` +$ sudo sh /media/cdrom/VBoxLinuxAdditions.run +``` + +If you didn’t install a Desktop environment when you installed the operating +system, as recommended to reduce size, the install of the VirtualBox additions +should warn you about the lack of OpenGL or Window System Drivers, but you can +safely ignore this. + +If the command succeeds, then the guest additions are now installed! + +## Packaging the Box + +Vagrant includes a simple way to package VirtualBox base boxes. Once you've +installed all the software you want to install, you can run this command: + +``` +$ vagrant package --base my-virtual-machine +``` + +Where "my-virtual-machine" is replaced by the name of the virtual machine +in VirtualBox to package as a base box. + +It will take a few minutes, but after it is complete, a file "package.box" +should be in your working directory which is the new base box. At this +point, you've successfully created a base box! + +## Raw Contents + +This section documents the actual raw contents of the box file. This isn't +as useful when creating a base box but can be useful in debugging issues +if necessary. A VirtualBox base box is an archive of the resulting files of [exporting](http://www.virtualbox.org/manual/ch08.html#vboxmanage-export) @@ -45,7 +111,7 @@ $ tree ``` In addition to the files from exporting a VirtualBox VM, there is -a "metadata.json" file used by Vagrant itself. +the "metadata.json" file used by Vagrant itself. Also, there is a "Vagrantfile." This contains some configuration to properly set the MAC address of the NAT network device, since VirtualBox @@ -54,18 +120,3 @@ requires this to be correct in order to function properly. When bringing up a VirtualBox backed machine, Vagrant [imports](http://www.virtualbox.org/manual/ch08.html#vboxmanage-import) the first "ovf" file found in the box contents. - -## Installed Software - -Base boxes for VirtualBox should have the following software installed, as -a bare minimum: - -* SSH server with key-based authentication setup. If you want the box to - work with default Vagrant settings, the SSH user must be set to accept - the [insecure keypair](https://github.com/mitchellh/vagrant/blob/master/keys/vagrant.pub) - that ships with Vagrant. - -* [VirtualBox Guest Additions](http://www.virtualbox.org/manual/ch04.html) so that things such as shared - folders can function. There are many other benefits to installing the tools, - such as improved networking performance. -