1OSBUILD(1)                       User Commands                      OSBUILD(1)
2
3
4

NAME

6       osbuild - Build-Pipelines for Operating System Artifacts
7

SYNOPSIS

9       osbuild [ OPTIONS ] MANIFEST
10       osbuild [ OPTIONS ] -
11       osbuild --help
12       osbuild --version
13
14

DESCRIPTION

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

OPTIONS

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
29       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
33       -h, --help
34              print usage information and exit immediately
35
36       --version
37              print version information and exit immediately
38
39       --store=DIR
40              directory where intermediary file system trees are stored
41
42       -l DIR, --libdir=DIR
43              directory containing stages, assemblers, and the osbuild library
44
45       --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
50       --checkpoint=CHECKPOINT
51              stage  to commit to the object store during build (can be passed
52              multiple times)
53
54       --export=OBJECT
55              object to export (can be passed multiple times)
56
57       --json output results in JSON format
58
59       --output-directory=DIR
60              directory where result objects are stored
61
62       --inspect
63              return the manifest in JSON format including all the ids
64
65       --monitor=TYPE
66              name of the monitor to be used
67
68       --monitor-fd=NUM
69              file-descriptor to be used for the monitor
70
71       --stage-timeout
72              set the maximal time (in seconds) each stage is allowed to run
73
74       NB: If neither --output-directory nor --checkpoint is specified, no at‐
75       tempt to build the manifest will be made.
76

MANIFEST

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
83       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

MONITOR

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
92       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
97       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
106       Monitor output is written to the file-descriptor provided  via  --moni‐
107       tor-fd=NUM. If none was specified, standard output is used.
108

OUTPUT

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
118       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

EXAMPLES

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
127   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
131          # echo {} | osbuild -
132
133
134
135   Example 2: See pipeline IDs of a Fedora qcow2 image
136       To inspect a basic qcow2 image of Fedora, use:
137
138          # osbuild ./samples/fedora-boot.json
139
140
141
142       The pipeline definition ./samples/fedora-boot.json is provided  in  the
143       upstream source repository of osbuild.
144
145       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
150   Example 3: Build a Fedora qcow2 image
151       To build a basic qcow2 image of Fedora, use:
152
153          # osbuild --output-dir ./out --export image ./samples/fedora-boot.json
154
155
156
157       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
160   Example 4: Run from a local checkout
161       To run osbuild from a local checkout, use:
162
163          # python3 -m osbuild --libdir . --output-dir ./out --export image samples/fedora-boot.json
164
165
166
167       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

SEE ALSO

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

NOTES

174       [1]  OSBuild JSON Schema v2: https://osbuild.org/schemas/osbuild2.json
175
176
177
178
179                                                                    OSBUILD(1)
Impressum