1OSBUILD(1) User Commands OSBUILD(1)
2
6 osbuild - Build-Pipelines for Operating System Artifacts
7
9 osbuild [ OPTIONS ] MANIFEST
10 osbuild [ OPTIONS ] -
11 osbuild --help
12 osbuild --version
13
16 osbuild is a build-system for operating system artifacts. It takes an
17 input manifest describing the build pipelines and produces file-system
18 trees, images, or other artifacts as output. Its pipeline description
19 gives comprehensive control over the individual steps to execute as
20 part of a pipeline. osbuild provides isolation from the host system as
21 well as caching capabilities, and thus ensures that pipeline builds
22 will be deterministic and efficient.
23
25 osbuild reads the pipeline description from the file passed on the com‐
26 mand-line. To make osbuild read the pipeline description from standard
27 input, pass -.
28 The following command-line options are supported. If an option is
30 passed, which is not listed here, osbuild will deny startup and exit
31 with an error.
32 -h, --help
34 print usage information and exit immediately
35 --version
37 print version information and exit immediately
38 --store=DIR
40 directory where intermediary file system trees are stored
41 -l DIR, --libdir=DIR
43 directory containing stages, assemblers, and the osbuild library
44 --cache-max-size=SIZE
46 maximum size of the cache (bytes) or 'unlimited' for no restric‐
47 tion (size may include an optional unit suffix, like kB, kiB,
48 MB, MiB and so on)
49 --checkpoint=CHECKPOINT
51 stage to commit to the object store during build (can be passed
52 multiple times)
53 --export=OBJECT
55 object to export (can be passed multiple times)
56 --json output results in JSON format
58 --output-directory=DIR
60 directory where result objects are stored
61 --inspect
63 return the manifest in JSON format including all the ids
64 --monitor=TYPE
66 name of the monitor to be used
67 --monitor-fd=NUM
69 file-descriptor to be used for the monitor
70 --stage-timeout
72 set the maximal time (in seconds) each stage is allowed to run
73 NB: If neither --output-directory nor --checkpoint is specified, no at‐
75 tempt to build the manifest will be made.
76
78 The input to osbuild is a description of the pipelines to execute, as
79 well as required parameters to each pipeline stage. This data must be
80 JSON encoded. It is read from the file specified on the command-line,
81 or, if - is passed, from standard input.
82 The format of the manifest is described in osbuild-manifest(5). The
84 formal schema of the manifest is available online as the OSBuild JSON
85 Schema [1].
86
88 Live activity of the pipeline execution can be monitored via a built-in
89 set of different monitors. The --monitor=TYPE option selects the type
90 of monitor that is used. Valid types are:
91 NullMonitor
93 No live coverage is reported and all monitoring features are
94 disabled. This is the default monitor if --json was specified
95 on the command-line.
96 LogMonitor
98 A human-readable live monitor of the pipeline execution. This
99 monitor prints pipeline names, stage names, and relevant options
100 of each stage as it is executed. Additionally, timing informa‐
101 tion is provided for each stage. The output is not machine-read‐
102 able and is interspersed with the individual log messages of the
103 stages. This is the default monitor if --json was not speci‐
104 fied.
105 Monitor output is written to the file-descriptor provided via --moni‐
107 tor-fd=NUM. If none was specified, standard output is used.
108
110 OSBuild only ever builds the requested artifacts, rather than all arti‐
111 facts defined in a manifest. Each stage and pipeline has an associated
112 ID (which can be acquired by passing --inspect). To export an artifact
113 after a stage or pipeline finished, pass its ID via --export=ID. A
114 sub-directory will be created in the output-directory with the ID as
115 the name. The contents of the artifact are then stored in that sub-di‐
116 rectory.
117 Additionally, any completed pipeline or stage can be cached to avoid
119 rebuilding them in subsequent invocations. Use --checkpoint=ID to re‐
120 quest caching of a specific stage or pipeline.
121
123 The following sub-sections contain examples on running osbuild. Gener‐
124 ally, osbuild must be run with superuser privileges, since this is re‐
125 quired to create file-system images.
126 Example 1: Run an empty pipeline
128 To verify your osbuild setup, you can run it on an empty pipeline which
129 produces no output:
130 # echo {} | osbuild -
132 Example 2: See pipeline IDs of a Fedora qcow2 image
136 To inspect a basic qcow2 image of Fedora, use:
137 # osbuild ./samples/fedora-boot.json
139 The pipeline definition ./samples/fedora-boot.json is provided in the
143 upstream source repository of osbuild.
144 This will print out the pipeline IDs of the provided manifest but will
146 not actually build anything because no artifact was requested. The
147 pipeline IDs can then be passed to --export= to actually get the re‐
148 quested artifacts.
149 Example 3: Build a Fedora qcow2 image
151 To build a basic qcow2 image of Fedora, use:
152 # osbuild --output-dir ./out --export image ./samples/fedora-boot.json
154 Note that the command requires to be run as root. It will create an
158 out/image directory and put the generated "disk.img" there.
159 Example 4: Run from a local checkout
161 To run osbuild from a local checkout, use:
162 # python3 -m osbuild --libdir . --output-dir ./out --export image samples/fedora-boot.json
164 This will make sure to execute the osbuild module from the current di‐
168 rectory, as well as use it to search for stages, assemblers, and more.
169
171 osbuild-manifest(5), osbuild-composer(1)
172
174 [1] OSBuild JSON Schema v2: https://osbuild.org/schemas/osbuild2.json
175 OSBUILD(1)