freight-builder man page

freight-builder — utility to convert manifest files into systemd-nspawn images


frieght-builder [options]


freight-builder is a utility to convert manifest files of rpms into disk images suitable for use with systemd-nspawn. These disk images also create meta data useful for image validation and adminstrative operation, such as determination of the need for rebuilding due to updated packages. Freight-builder accepts as input a manifest file (described below), and produces a source and binary rpm as output. The former is suitable for rebuilding on alternate arches, while the latter (and any rebuilds of the source rpm) can be placed in a repository for installations on systems running freight-agent, and are usable as systemd containers.


freight-builder [OPTIONS]
-h | --help
Display options and usage for the utility
-k | --keep
Keep working files and src rpms around for insepction/debug after exit
-s | --source
Only build the soruce rpm, not the binary container rpm
-m | --manifest <manifest file>
Specify the manifest file to convert into a container image
-o | --output path/to/output/dir
Write the resultant source and binary rpms to this directory
-p | --pcache /path/to/rpm/dir
Set the parent cache directory. Any rpms in this directory will be installed in the working directory prior to building a container. Used to ensure parent containers are available to snapshot from
-c | --container <path/to/container/rpm>
Instead of building an rpm, introspect an rpm to see if any packages need updates within the container
-v | --verbose
Make freight-builder output lots of diagnostic information
-w | --workdir <path/to/workdir>
Specify the base directory in which freight-builder uses as working space to build rpms
-r | --relver
The release version to specify when inspecting or deriving child containers

Manifest File Format

The Manifest file codifies the contents of a container image and generally has this format:

# These are comments

inherit = "/path/to/inherited/file";

repositories = (
		name = "Yum_respository_1";
		url = "http://yum.repo.com/path/to/repo";
	}, ...

manifest = (

packaging = {
	name = "web-server";
	version = "1.0";
	release = "1";
	summary = "Summarize This container here";
	license = "GPLv2|BSD|Proprietary";	
	author = "Name <email>";
	post_script ="/path/to/script";
	parent_container = "parent-container-nvr";

yum_opts = {
	releasever = "f21";

container_opts = {
	user = "username";



Manifest files can be stacked on one another. The inherit directive indicates the parent of the manifest file being processed. Inheritance may be nested (i.e. manifest A may inherit from manifest B, and B may inherit from manifest C). However multiple inheritance is not allowed. Inherited files have their repository and manifest groups merged. The options group is overridden by child option groups

repositories = ( ... )

The repositories group represents the set of yum repositories that this utility will search for the manifest designated rpms.

manifest = ( ... )

A list of Strings representing package nvr's to include in the systemd-nspawn image file.


A list of details to include when the container is packaged up as an rpm


Path to a file to be executed in the container root after the install is complete. Note the Environment Variables section below for information about the script environment


This optional setting allows for the creation of derivative containers. That is to say, the resultant container will be a delta from specified parent container rpm. This allows for very small container images, but requires that the parent container be installed when building. Used in conjunction with --pcache option


A list of config specifications to pass to yum:

releasever This allows yum to specify the rpmdb release version when creating a container for updates. yum repositories with $releasever in their urls will be resolved properly with this option


A list of options to direct behavior of an instance of the container when executed

user The container will run as the specified user

Environment Variables

Environment variables are used to convey information about the container being built to the post_script that may be optionally specified in the manifest file. The following Environment variables are set and accessible to the post_script

This variable points to the root of the container file system. It can be used as a chroot destination for modifying the container, or as a destination directory base for copying additional files into the container


Apr 2015