boxgrinder-build

BoxGrinder

BoxGrinder is a set of projects that help you grind out appliances for multiple virtualization and Cloud providers.

Visit us at boxgrinder.org, or join #boxgrinder on irc.freenode.net

BoxGrinder Build

BoxGrinder Build is a command line tool to help you build appliances. With an appliance definition and just a single command, BoxGrinder can create your appliance, target it to a platform and deliver it.

Boxgrinder Build Meta Appliance: BoxGrinder the Easy Way

The BoxGrinder Meta appliance is pre-configured with an optimal environment prepared to use BoxGrinder right from launch. Just download the latest appliance from boxgrinder.org in your desired format, launch it, and you're ready to grind out images!

It is a great way to use or test BoxGrinder in a virtual environment without affecting your local system.

Visit the BoxGrinder Meta appliance usage article to learn more.

Supported OSes

At present the project officially supports the following OSes in x86_64 and i386 variants:

• Fedora (13, 14, 15)
• RHEL (5.x, 6.x) and CentOS (5.x)

Requirements

• Acquiring and installing BoxGrinder is very simple, with RPMs ensuring the correct dependencies are pulled and installed. However, depending upon your OS of choice, the prerequisites for installing BoxGrinder vary slightly.
• Administrative level permissions (root or equivalent)

Fedora

BoxGrinder and all of its dependencies reside within the official Fedora repositories, therefore there are no special requirements. Simply install via your package manager.

RHEL/CentOS

EPEL and BoxGrinder repositories locations must be added to your package manager in order to install BoxGrinder and resolve its dependencies successfully.

For detailed instructions, see: Preparing your environment

Installing

Once the prerequisites are satisfied, install BoxGrinder via a package manager, for instance in YUM;

• sudo yum install rubygem-boxgrinder-build to install BoxGrinder Build.

Removing

You should remove BoxGrinder through your system package manager, for instance with YUM:

• sudo yum remove rubygem-boxgrinder*

Usage

BoxGrinder.org's quick-start tutorial is the best place to learn the fundamentals of BoxGrinder Build, enabling you to rapidly leverage the feature-set on offer.

The following sections provide a basic overview of functionality.

Plugins

Most of the features of BoxGrinder Build are provided through plugins, with three primary variants (Operating System, Platform and Delivery), each catering for a phase of the build process. Furthermore, the flexible and extensible structure of BoxGrinder Build enables users to seamlessly add new features and functionality.

As of version 0.9.0 BoxGrinder Build is distributed with standard plugins installed by default.

• Operating System - provide support to run and build for a given OS
• Platform - ability to produce appliances for a specific platform, such as Amazon's EC2 or VirtualBox VM
• Delivery - send the completed appliance, for instance by SFTP or bundled as an AMI and uploaded to S3.

Learn more: BoxGrinder Build, BoxGrinder Plugins

Plugin Configuration

Many plugins allow, or mandate, some degree of configuration before they are executed. These properties are aggregated into a single per-user configuration file, at ~/.boxgrinder/config. The user should consult the documentation of a given plugin to determine what fields it should be configured with, and which fields (if any), are requisite.

plugins:
  sftp:
    host: 192.168.0.1
    username: boxgrinder
    path: /home/boxgrinder/appliances

• In this example, the SFTP plugin's fields are all mandatory.

Learn more: BoxGrinder Plugins

Defining Appliances

Appliances are defined in YAML, the following "JEOS" definition can be used by BoxGrinder to produce a basic, but fully functional appliance;

name: f14-basic
summary: Just Enough Operating System based on Fedora 14
os:
  name: fedora
  version: 14
hardware:
  partitions:
    "/":
      size: 2
packages:
  - @core

• With this simple definition, BoxGrinder will produce a Fedora 14 appliance with the Core group of packages. You can easily add packages, repositories, and harness a plethora of powerful features in a concise, declarative manner.
• For an introduction to Appliance Definitions, see: Quick-start, building your first appliance
• For fuller explanations of all parameters BoxGrinder offers, see: Appliance definition parameters

Building Appliances

The BoxGrinder Build CLI is a simple interface through which you can instruct BoxGrinder to build your appliances. You can view a brief manual by using boxgrinder-build --help, and version information through boxgrinder-build --version

BoxGrinder Build is run with a mandatory appliance definition, along with optional platform and delivery plugin specifiers. BoxGrinder resolves the packages and associated dependencies in the appliance definition, and installs them into the new image it generates based upon the operating system and versions specified.

boxgrinder-build [appliance definition file] [options]

• The two most common options are [-p|--platform=] and [-d|--delivery=]. Neither is mandatory, if platform is omitted then only the raw KVM image is created. You can can later return and target a build to different platforms, and BoxGrinder will always reuse the intermediary data where it is available. If you wish to force a rebuild, you can use the [-f|--force] flag.
• It is possible to manually provide key-value pairs for platform and delivery plugin configuration on the command line. These will override any pre-existing plugin parameters set in the BoxGrinder config file.
• Shell commands can be executed in post sections of the appliance definition files, which is useful for basic configuration. However, it is advisable that more complex configuration and installation of custom software is performed properly through RPM files. This is often best achieved through local repositories, which can be configured as ephemeral in order to avoid the repository being installed into the resultant image's package manager.

See: BoxGrinder Build Usage Instructions, How to use local repositories

Examples

boxgrinder-build fedora-14.appl -p vmware -d sftp

Build an image based upon fedora-14.appl, and produce an image targeted at the vmware platform. Once complete, deliver by sftp. Note that each of these plugins must be configured in ~/.boxgrinder/conf or by providing the key-value pairs as command-line arguments.

---

boxgrinder-build fedora-14.appl -p virtualbox -d local

Assuming that BoxGrinder had succeeded in building the prior image, the RAW file is again used as an intermediary without needing to be rebuild. An image targeted at VirtualBox is then produced, and delivered to a local file, as determined in conf.

---

setarch i386 boxgrinder-build fedora-14.appl

Build an i386 appliance (on an x86_64 machine).