1VIRT-BOOTSTRAP(1) Container bootstrapping tool VIRT-BOOTSTRAP(1)
2
6 virt-bootstrap - Setup root file system for libvirt-based containers
7
9 virt-bootstrap URI DEST [OPTIONS]
10
12 virt-bootstrap is a tool providing an easy way to setup the root file
13 system for libvirt-based containers. It allows to use either a tarball
14 containing the file system, an image on a docker registry or virt-
15 builder template and unpacks it either as a folder or in a
16 Supported sources are:
18 file:///path/to/rootfs.tar
19 Tar archive which contains root file system
20 docker://registry:port/image:tag
22 Docker registry
23 virt-builder://template
25 virt-builder templates
26 Docker container images are downloaded and the layers are getting
28 cached. If virt-bootstrap is running with effective UID=0 (root) the
29 layersq are cached in "/var/cache/virt-bootstrap/docker_images". For
30 unprivileged users the "~/.cache/virt-bootstrap/docker_images"
31 directory is used. If the environment variable "XDG_CACHE_HOME" is
32 specified then this directory is used instead of "~/.cache".
33 The environment variable "VIRTBOOTSTRAP_TMPDIR" can be used to specify
35 temporary directory used by virt-bootstrap or default "/tmp" will be
36 used.
37
39 -f, --format
40 Output format of the root file system. Possible values are dir
41 (default) and qcow2.
42 --root-password SELECTOR
44 This argument will generate hash from ROOT_PASSWORD, gotten from
45 the SELECTOR field, and insert the hashed value into "/etc/shadow"
46 in the created root file system.
47 Note that SELECTOR can be one of the following: "file:".
49 If the output format is "qcow2" these modifications are applied in
51 additional qcow2 disk image.
52 Note that the "/etc/shadow" file must already exist in the
54 extracted root file system of the container image and it must have
55 entry for root user.
56 --no-cache
58 When this flag is used Docker images will be downloaded in
59 temporary directory and discarded after the root file system is
60 extracted.
61 --status-only
63 If this flag is used the log messages will be suppresses and only
64 information about the current progress will be displayed.
65 -q, --quiet
67 Show only warning and error messages.
68 -d, --debug
70 Show debugging output messages.
71 -h, --help
73 Display command line help summary.
74 --version
76 Show virt-bootstrap's version number and exit.
77 Authentication options for accessing private Docker registry
79 Note: If --username argument is specified and --password omitted
80 password prompt will be issued. If --username is omitted the --password
81 argument will be ignored.
82 -u, --username USERNAME
84 This argument takes USERNAME to be used to access Docker source registry.
85 -p, --password PASSWORD
87 This argument takes PASSWORD to be used to access Docker source
88 registry.
89 --not-secure
91 Don't require HTTPS and verification of certificates when talking
92 to Docker registry.
93 See "skopeo copy" in skopeo(1)
95 UID/GID mapping
97 --uidmap start:target:count
98 Shift UIDs of all root file system entries with some offset. This
99 parameter can be specified multiple times.
100 Example: "--uidmap 0:1000:10 --uidmap 500:1500:10" This will map
102 the UIDs: 0-9 to 1000-1009 and 500-509 to 1500-1509
103 See "INSTALLATION OPTIONS" in virt-install(1)
105 --gidmap start:target:count
107 Shift GIDs of all root file system entries with some offset. This
108 parameter can be specified multiple times.
109 Example: "--gidmap 0:1000:10 --gidmap 500:1500:10" This will map
111 the GIDs: 0-9 to 1000-1009 and 500-509 to 1500-1509
112 See "INSTALLATION OPTIONS" in virt-install(1)
114 --idmap start:target:count
116 Remapping owner and group of all files and directories inside of
117 the root file system. This parameter can be specified multiple
118 times.
119 Example: "--idmap 0:1000:10 --idmap 500:1500:10" This will map UIDs
121 and GIDs: 0-9 to 1000-1009 and 500-509 to 1500-1509
122 See "INSTALLATION OPTIONS" in virt-install(1)
124
126 Create root file system using Ubuntu image docker.io registry:
127 $ virt-bootstrap docker://ubuntu /tmp/foo
128 Create root file system from image stored on private Docker registry:
130 $ virt-bootstrap docker://localhost:5000/ubuntu /tmp/foo \
131 --username testuser \
132 --password testpassoword \
133 --not-secure
134 Apply UIDs/GIDs mapping for root file system entries
136 $ virt-bootstrap docker://fedora /tmp/foo \
137 --idmap 0:1000:10
138 This above command will map UIDs/GIDs: 0-9 to 1000-1009
140 The same result can be achieved with:
142 $ virt-bootstrap docker://fedora /tmp/foo \
144 --uidmap 0:1000:10 \
145 --gidmap 0:1000:10
146 Multiple mapping values can be specified as follows:
148 $ virt_bootstrap.py docker://ubuntu /tmp/foo \
149 --idmap 0:1000:10 \
150 --idmap 500:1500:10
151 This will map the UID/GIDs: 0-9 to 1000-1009 and 500-509 to
153 1500-1509
154 Set root password
156 $ virt_bootstrap.py docker://opensuse /tmp/foo \
157 --root-password file:/tmp/secret
158 The above command will download the "opensuse" container image and
160 extract the root file system to "/tmp/foo". Then it will generate
161 hash of the password present in "/tmp/secret" file and insert it
162 into "/tmp/foo/etc/shadow" file.
163 $ virt_bootstrap.py docker://opensuse /tmp/foo \
165 --root-password file:/tmp/secret \
166 -f qcow2
167 Similarly for qcow2 format the container image will be downloaded
169 and the root file system will be extracted into qcow2 disk images
170 with backing chains. Then additional qcow2 image will be created
171 with backing file set to the last layer and the modification of
172 "shadow" file will be applied there.
173
175 Written by Cedric Bosdonnat and Radostin Stoyanov
1761.1.1 2023-07-22 VIRT-BOOTSTRAP(1)