Back to home


Build-Pipelines for Operating System Artifacts



osbuild - Build-Pipelines for Operating System Artifacts


osbuild --help


osbuild is a build-system for operating system artifacts. It takes a pipeline description as input and produces file-system trees, images, or other artifacts as output. Its pipeline description gives comprehensive control over the individual steps to execute as part of a pipeline. osbuild provides isolation from the host system as well as caching capabilities, and thus ensures that pipeline builds will be deterministic and efficient.


osbuild reads the pipeline description from the file passed on the command-line. To make osbuild read the pipeline description from standard input, pass -.

The following command-line options are supported. If an option is passed, which is not listed here, osbuild will deny startup and exit with an error.
, --help

print usage information and exit immediately


directory where intermediary file system trees are stored


json file containing a dictionary of secrets that are passed to sources

-l DIR--libdir=DIR

directory containing stages, assemblers, and the osbuild library


stage to commit to the object store during build (can be passed multiple times)


object to export (can be passed multiple times)


output results in JSON format


directory where result objects are stored


return the manifest in JSON format including all the ids

NB: If neither --output-directory nor --checkpoint is specified, no attempt to build the manifest will be made.


The input to osbuild is a description of the pipeline to execute, as well as required parameters to each pipeline stage. This data must be JSON encoded. It is read from the file specified on the command-line, or, if - is passed, from standard input.

The format of the manifest is described in osbuild-manifest(5). The formal schema of the manifest is available online as the OSBuild JSON Schema [1].


The following sub-sections contain examples on running osbuild. Generally, osbuild must be run with superuser privileges, since this is required to create file-system images.

Example 1: Run an empty pipeline
To verify your osbuild setup, you can run it on an empty pipeline which produces no output:

# echo {} | osbuild -

Example 1: Build a Fedora 30 qcow2 image
To build a basic qcow2 image of Fedora 30, use:

# osbuild ./samples/base-qcow2.json

The pipeline definition ./samples/base-rpm-qcow2.json is provided in the upstream source repository of osbuild.

Example 2: Run from a local checkout
To run osbuild from a local checkout, use:

# python3 -m osbuild --libdir . samples/base-rpm-qcow2.json

This will make sure to execute the osbuild module from the current directory, as well as use it to search for stages, assemblers, and more.


osbuild-manifest(5), osbuild-composer(1)



OSBuild JSON Schema: