Skip to content

Latest commit

 

History

History
364 lines (278 loc) · 11.2 KB

DOCUMENTATION.md

File metadata and controls

364 lines (278 loc) · 11.2 KB
Raw

#Vagrant-Builder

##Vagrant-Builder by James ####Available from: ####https://github.com/purpleidea/vagrant-builder/

####This documentation is available in: Markdown or PDF format.

####Table of Contents

  1. Overview
  2. Project description - What the project does
  3. Setup - Getting started with Vagrant Builder
  4. Usage/FAQ - Notes on usage and frequently asked questions
  5. Reference - Detailed reference
  6. Examples - Example configurations
  7. Limitations - Vagrant versions, OS compatibility, etc...
  8. Development - Background on module development and reporting bugs
  9. Author - Author and contact information

##Overview

The Vagrant Builder project provides an elegant Makefile approach to building Vagrant base image "boxes" for vagrant-libvirt.

##Project Description

The Vagrant Builder project tracks the multiple steps in the image generation process, and only rebuilds missing parts that are out of date. It utilizes the power of GNU make to do so, and as a result comes in at a few hundred lines of code.

The base images are provided by the virt-builder project, although your own base images can be used provided you provide an ISO starting point.

For more information, start by reading and working through the introductory blog post.

For information on how to use vagrant-builder to build RHEL base images, read: https://ttboj.wordpress.com/2015/02/23/building-rhel-vagrant-boxes-with-vagrant-builder/.

##Setup

###Dependencies

  • In order to build a vagrant box, a virtual machine needs to be installed, started up, modified, then shutdown. To this end, the machine you use vagrant-builder on must be a libvirt hypervisor:
$ sudo dnf install virt-install libvirt kvm libguestfs-tools
  • During the virtual machine build using an ISO, the qemu user needs access to the ISO. One way to accomplish this is to give this user access to your home directory:
$ getfacl /home/james # james is my home directory
# file: james
# owner: james
# group: james
user::rwx
group::---
other::---

$ sudo setfacl -m u:qemu:r-x /home/james # this is the important line
$ getfacl /home/james
# file: james
# owner: james
# group: james
user::rwx
user:qemu:r-x
group::---
mask::r-x
other::---
  • Specify subscription-manager credentials if using RHEL: NOTE: Unfortunately the password will be displayed on the virt-builder command-line. Patches to fix this welcome!
$ cat ~/.vagrant-builder/auth.sh
# these values are used by vagrant-builder
USERNAME='purpleidea@redhat.com' # replace with your access.redhat.com username
PASSWORD='hunter2'               # replace with your access.redhat.com password
  • Increase your /tmp directory to 6 GiB or larger:
$ sudo mount -o remount,size=8G /tmp
$ df -h /tmp
Filesystem Size Used Avail Use% Mounted on
tmpfs 1.9G 1.3M 1.9G 1% /tmp

$ sudo mount -o remount,size=8G /tmp
$ df -h /tmp
Filesystem Size Used Avail Use% Mounted on
tmpfs 8.0G 1.3M 8.0G 1% /tmp
  • Install the necessary documentation packages to build the docs:
$ sudo dnf install pandoc texlive

###Installation

  • Start by cloning the project, and entering the v directory of your choice:
$ git clone --recursive https://github.com/purpleidea/vagrant-builder
  • Change into the directory of the version you would like to build
$ cd vagrant-builder/v7/

That's it!

###Simple usage

The v directory represents the different similarities of OS images that we're going to build. For example, the v7/ directory represents CentOS 7.x, RHEL 7.x, Fedora 20, and Fedora 21. These are similar enough to be able to be represented by almost the same code.

To decide what type of image to build, you must edit a file in the versions/ directory. Once you have set the parameters you so desire, you run it from the parent directory:

./versions/fedora-21.sh

To run a specific target, you can pass that in. For example, to run the upload target, you can run:

./versions/fedora-21.sh upload

The Makefile will now get to work building your images! They usually appear in: ~/tmp/builder/.

###Complex usage

A slightly more complex variant is possible if you'd like to build a base image using an ISO as the initial starting point. In this scenario, start by downloading the ISO of your choice, and putting in the iso/ directory, which should be next to the versions/ directory. Example:

$ pwd
/home/james/code/vagrant-builder/v7

$ tree -L 1
.
|-- files
|-- iso
|-- keys
|-- Makefile
|-- repos
|-- scripts
|-- Vagrantfile
`-- versions

After the ISO is in place, set the ISO path and any other necessary variables in the correct versions file. The remaining steps are the same as in the simple usage.

##Usage and frequently asked questions (Send your questions as a patch to this FAQ! I'll review it, merge it, and respond by commit with the answer.)

###Why did you start this project?

I needed Vagrant images for vagrant-libvirt, and very few were available, and there were even no working tools that would generate them! As a result, this project was born. I'm still maintaining it because it's still useful to me, and because others are using it too!

###Awesome work, but it's missing support for a feature and/or platform!

Since this is an Open Source / Free Software project that I also give away for free (as in beer, free as in gratis, free as in libre), I'm unable to provide unlimited support. Please consider donating funds, hardware, virtual machines, and other resources. For specific needs, you could perhaps sponsor a feature!

###You didn't answer my question, or I have a question!

Contact me through my technical blog and I'll do my best to help. If you have a good question, please remind me to add my answer to this documentation!

##Reference Please note that there are a number of undocumented options. For more information on these options, please view the source at: https://github.com/purpleidea/vagrant-builder/. If you feel that a well used option needs documenting here, please contact me.

###Overview of reference

  • Variables: Variables used in the versions/ files
  • Targets: Special named Makefile targets

###Variables These are the variables that can be used in versions/ files.

####VERSION This is the name for the image. In general it should match the names used in the output of virt-builder -l.

###Targets These are the special Makefile targets used in the project. The following targets are available:

####all

Alias: all
Target: $(OUTPUT)/vagrant-box-add.sh $(OUTPUT)/vagrant-box-remove.sh
Purpose: Runs all targets except clean
Dependencies: none

####xz

Alias: xz
Target: $(OUTPUT)/$(VERSION).xz
Purpose: Installs KVM VM via virt-install then converts to .xz compressed file
Dependencies: ISO file the iso/ directory

####index

Alias: index
Target: $(OUTPUT)/index
Purpose: Created index file used for virt-builder
Dependencies: $(OUTPUT)/$(VERSION).xz

####asc

Alias: asc
Target: $(OUTPUT)/index.asc
Purpose: Encrypted index file used for virt-builder
Dependencies: $(OUTPUT)/index

####builder

Alias: builder
Target: $(OUTPUT)/builder.img
Purpose: Takes the .xz image and makes specific changes to the image
Dependencies: Index file

####convert

Alias: convert
Target: $(OUTPUT)/box.img
Purpose: Convert image to qcow2
Dependencies: $(OUTPUT)/builder.img

####local

Alias: local
Target: $(OUTPUT)/SHA256SUMS.asc
Purpose: Encrypted SHA256SUM
Dependencies: $(OUTPUT)/SHA256SUMS

####upload

Alias: upload
Target: upload
Purpose: Secure copy resultant vagrant box to remote server with SSH keys already established
Dependencies: $(OUTPUT)/$(BOX) $(OUTPUT)/SHA256SUMS $(OUTPUT)/SHA256SUMS.asc

####clean

Alias: clean
Target: clean
Purpose: Remove files from previous run
Dependencies: None

##Examples For example configurations, please consult the examples/ directory in the git source repository. It is available from:

https://github.com/purpleidea/vagrant-builder/tree/master/examples

##Limitations This project will work with virt-builder version 1.28.6 and greater. It may work with certain older versions, but they are no longer tested. Hopefully new versions of virt-builder don't introduce any regressions that break this project.

This project is routinely tested on:

  • Fedora 21+

It will probably work without incident or without major modification on:

  • Fedora 20
  • CentOS 5.x/6.x/7.x
  • RHEL 5.x/6.x/7.x

It has not been tested by the author (but should work) on:

  • Ubuntu 12.04+
  • Debian 7+

It will most likely work on other GNU/Linux platforms, but testing on those platforms has been minimal due to lack of time and resources.

Testing is community supported! Please report any issues as there are a lot of features, and in particular, support for additional distros isn't well tested.

##Development

This is my personal project that I work on in my free time. Donations of funding, hardware, virtual machines, and other resources are appreciated. Please contact me if you'd like to sponsor a feature, invite me to talk/teach or for consulting.

You can follow along on my technical blog.

To report any bugs, please file a ticket at: https://github.com/purpleidea/vagrant-builder/issues.

##Author

Copyright (C) 2012-2013+ James Shubin