Appliance definition files are written in YAML. If you don't know YAML, read more here, it's really easy to understand!
Let's start with a small example:
name: httpd summary: Appliance with Apache HTTPD web server appliances: - jeos packages: - httpd
Note: Only the name and os/name os/version is required. Every other section can be omitted, and defaults will be used.
Every appliance definition file consists of one or more sections. Let's discuss them.
This is a name for your appliance. It must be unique in all of your appliances.
A small (one sentence or such) summary of the appliance; purpose, goals, etc.
An integer representing the appliance version.
An integer representing the appliance release. Version and release are used when generating unique names for deliverables.
The appliances section is designed to reuse appliances in new definitions. For example, you can create a template for your appliances, and then create a new specialized definition with your appliance template as a dependency; it'll automatically be merged into one behind the scenes.
Example appliances section:
appliances: - jeos - other
This section contains all of the packages you wish to add to your appliance.
Example packages section:
packages: - httpd - mc
In this section you can specify additional repositories in order to add packages to your appliance that are sourced from these repositories.
Note: Name of repository is required. This must be one word.
There are two types of link:
Notice that you can use
#BASE_ARCH# tag to substitute architecture for the current building architecture, eg. if the appliance will be built on a 64 bit platform, x86_64 will be injected. In the other case i386 will be injected.
Read more about parameters here.
A boolean to indicate whether the OSes default repositories should be loaded. If you disable this, you must provide alternatives else it will be impossible to successfully complete a build. This is useful for those that wish to use a local mirror rather than the remote defaults.
By default all repositories listed in an appliance definition file are installed into the appliance. If you want to specify a repository to be used only during the install phase, and don't want to install it into the YUM config of the appliance, make it ephemeral:
repos: - name: "local-repo" baseurl: "file:///var/repo" ephemeral: true
Example repos section:
repos: - name: "fedora-15" baseurl: "http://ftp.man.poznan.pl/pub/linux/fedora/releases/16/Everything/#BASE_ARCH#/os/" - name: "fedora-16-updates" mirrorlist: "http://mirrors.fedoraproject.org/mirrorlist?repo=updates-released-f16&arch=#BASE_ARCH#"
This section gives the ability to specify virtual hardware requirements.
cpus- virtual CPU count, default: 1.
memory- memory quantity in MB, default: 256.
partitions- partitioning scheme with root mounts and size in GB.
Example hardware section:
hardware: cpus: 2 memory: 256 partitions: "/": size: 5 "/home": size: 10
Note: Not all platforms will respect the CPU/memory values; some environments will override it.
hardware / partitions
partitions subsection you define the partition scheme. Partition sizes are specified in gigabytes (GB).
Example partition scheme:
hardware: partitions: "/": size: 5 # 5 GB "/home": size: 0.5 # 0.5 GB
There must be only one root partition with '/' mount point.
If there is no partition scheme specified, one root partition with size 1GB will be added, which is equivalent to this:
hardware: partitions: "/": size: 1 # 1 GB
To specify filesystem type, add a
Default operating system filesystem type is used when no type is specified.
hardware: partitions: "/": size: 5 type: ext3 # currently supported: ext3 and ext4
Note: Every partition specified in this section will be located on one disk.
This section specifies operating system information for the appliance.
name- OS name
version- OS version; this could be a number or string: 1, rawhide.
password- this is the root password, default: boxgrinder.
Example os section:
os: name: fedora version: rawhide password: fedorarulez
Added in 0.9.6
This section allows to specify which local or remote files should be installed in appliance.
files: "/opt": - "install.sh" - "http://somehost.com/repos/a_file.zip"
Files section is executed before post section. This allows you to execute some scripts copied to the appliance.
You can specify both relative (to the application definition file) and absolute paths. We strongly advise you to use relative paths which makes your appliance definition more portable. If you use absolute path - the whole path will be included in appliance.
For instance, if you specified a
files section as follows:
files: "/opt": - "/tmp/dir/file.txt"
BoxGrinder will place
file.txt in the
/opt/tmp/dir/ directory located in the appliance. Keep that in mind.
In this section you can execute commands after the build is finished for the selected appliance format.
The post section has subsections for each platform. If you want execute operations for the base image (this means the change you make will also be included in all other appliances based on it) use the
post: base: - "/sbin/chkconfig postgresql on"
If you want to execute different commands for different platforms, use the platform name as subsection name, like this:
post: vmware: - "echo 'vmware' > /etc/platform" ec2: - "echo 'ec2' > /etc/platform"
Note: If you specify commands to execute for a selected format, but you do not convert the appliance to this format - the command will be not executed.
Example post section with one command executed for the base image and one command executed for VMware appliances:
post: base: - "/sbin/chkconfig postgresql on" vmware: - "/bin/echo 'hello vmware' > /etc/sysconfig/vmware"
name: your-appliance summary: This describes your appliance version: 1 release: 0 os: name: fedora version: 15 password: weakpassword hardware: cpus: 2 memory: 512 partitions: "/": size: 2 packages: - httpd - mc default_repos: true # default is true repos: - name: "other-repo" baseurl: "http://repo.yoursite.com/fedora/15/#BASE_ARCH#"