1KIWI::SYSTEM::BOXBUILD(8) KIWI - Boxed Build Plugin KIWI::SYSTEM::BOXBUILD(8)
2
6 kiwi::system::boxbuild - Self Contained Image Build
7
9 kiwi-ng [global options] service <command> [<args>]
10 kiwi-ng system boxbuild -h | --help
12 kiwi-ng system boxbuild --box=<name>
13 [--box-memory=<vmgb>]
14 [--box-smp-cpus=<number>]
15 [--box-debug]
16 [--kiwi-version=<version>]
17 [--shared-path=<path>]
18 [--no-update-check]
19 [--no-snapshot]
20 [--no-accel]
21 [--9p-sharing | --virtiofs-sharing | --sshfs-sharing]
22 [--ssh-key=<name>]
23 [--x86_64 | --aarch64]
24 [--machine=<qemu_machine>]
25 [--cpu=<qemu_cpu>]
26 -- <kiwi_build_command_args>...
27 kiwi-ng system boxbuild --list-boxes
28 kiwi-ng system boxbuild help
29
31 build an image in a self contained environment. The boxbuild command
32 uses KVM to start a virtual machine and run the kiwi build command in‐
33 side of that virtual machine. The provided --description and --tar‐
34 get-dir options are setup as shared folders between the host and the
35 guest. No other data will be shared with the host which also allows for
36 cross distribution builds. The boxbuild command provides the following
37 additional features over the standard build command:
38 • Build images independent of the host.
40 • Build images as normal user not as root.
42 • Build cross distribution images on one host.
44 • Build in predefined build VMs called boxes which includes all compo‐
46 nents needed to build appliances.
47 For running the build process in a virtual machine it's required to
49 provide VM images that are suitable to perform this job. We call the VM
50 images boxes and they contain kiwi itself as well as all other compo‐
51 nents needed to build appliances. Those boxes are hosted in the Open
52 Build Service and are publicly available on the Subprojects tab at:
53 https://build.opensuse.org/project/show/Virtualization:Appliances:SelfContained
54 As a user you don't need to work with the boxes because this is all
56 done by the plugin. The boxbuild command knows where to fetch the box
57 and also cares for an update of the box when it has changed.
58
60 --box=<name>
61 Name of the virtual machine that should be used for the build
62 process.
63 --list-boxes
65 show available build boxes.
66 --box-memory=<vmgb>
68 Number of GBs to reserve as main memory for the virtual machine.
69 By default 8GB will be used.
70 --box-smp-cpus=<number>
72 Number of CPUs to use in the SMP setup. By default 4 CPUs will
73 be used
74 --no-update-check
76 Skip check for available box update. The option has no effect if
77 the selected box does not yet exist on the host.
78 --no-snapshot
80 Run box with snapshot mode switched off. This causes the box
81 disk file to be modified by the build process and allows to keep
82 a persistent package cache as part of the box. The option can
83 be used to increase the build performance due to data stored in
84 the box which doesn't have to be reloaded from the network. On
85 the contrary this option invalidates the immutable box attribute
86 and should be used with care. On update of the box all data
87 stored will be wiped. To prevent this combine the option with
88 the --no-update-check option.
89 --no-accel
91 Run box without hardware acceleration. By default KVM accelera‐
92 tion is activated
93 --9p-sharing|--virtiofs-sharing|--sshfs-sharing
95 Select sharing backend to use for sharing data between the host and
96 the box. This can be either 9p, virtiofs or sshfs. By default 9p is
97 used
98 --ssh-key=<name>
100 Name of ssh key to authorize for connection. By default
101 'id_rsa' is used.
102 --x86_64|--aarch64
104 Select box for the x86_64 architecture. If no architecture is se‐
105 lected the host architecture is used for selecting the box. The se‐
106 lected box architecture also specifies the target architecture for
107 the image build with that box.
108 --box-debug
110 In debug mode the started virtual machine will be kept open
111 --kiwi-version=<version>
113 Specify a KIWI version to use for the build. The referenced KIWI
114 will be fetched from pip and replaces the box installed KIWI
115 version. Note: If --no-snapshot is used in combination with this
116 option, the change of the KIWI version will be permanently
117 stored in the used box.
118 --shared-path=<path>
120 Optional host path to share with the box. The same path as it is
121 present on the host will also be available inside of the box
122 during build time.
123 --machine=<qemu_machine>
125 Optional machine name used by QEMU. By default no specific value
126 is used here and qemu selects its default machine type. For
127 cross arch builds or for system architectures for which QEMU de‐
128 fines no default like for Arm, it's required to specify a ma‐
129 chine name.
130 If you don’t care about reproducing the idiosyncrasies of a par‐
132 ticular bit of hardware, the best option is to use the 'virt'
133 machine type.
134 --cpu=<qemu_cpu>
136 Optional CPU type used by QEMU. By default the host CPU type is
137 used which is only a good selection if the host and the selected
138 box are from the same architecture. On cross arch builds it's
139 required to specify the CPU emulation the box should use
140 -- <kiwi_build_command_args>...
142 List of command parameters as supported by the kiwi-ng build com‐
143 mand. The information given here is passed along to the kiwi-ng sys‐
144 tem build command running in the virtual machine. See the Example
145 below how to provide options to the build command correctly.
146
148 $ git clone https://github.com/OSInside/kiwi-descriptions
149 $ kiwi --type vmx system boxbuild --box suse -- \
151 --description kiwi-descriptions/suse/x86_64/suse-tumbleweed-JeOS \
152 --target-dir /tmp/myimage
153
155 Marcus Schäfer
156
158 2020, Marcus Schäfer
1590.2.23 May 30, 2022 KIWI::SYSTEM::BOXBUILD(8)