1VIRT-BOOTSTRAP(1)        Container bootstrapping tool        VIRT-BOOTSTRAP(1)
2
3
4

NAME

6       virt-bootstrap - Setup root file system for libvirt-based containers
7

SYNOPSIS

9       virt-bootstrap URI DEST [OPTIONS]
10

DESCRIPTION

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
17   Supported sources are:
18       file:///path/to/rootfs.tar
19           Tar archive which contains root file system
20
21       docker://registry:port/image:tag
22           Docker registry
23
24       virt-builder://template
25           virt-builder templates
26
27       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
34       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

OPTIONS

39       -f, --format
40           Output format of the root file system. Possible values are dir
41           (default) and qcow2.
42
43       --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
48           Note that SELECTOR can be one of the following: "file:".
49
50           If the output format is "qcow2" these modifications are applied in
51           additional qcow2 disk image.
52
53           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
57       --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
62       --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
66       -q, --quiet
67           Show only warning and error messages.
68
69       -d, --debug
70           Show debugging output messages.
71
72       -h, --help
73           Display command line help summary.
74
75       --version
76           Show virt-bootstrap's version number and exit.
77
78   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
83       -u, --username USERNAME
84              This argument takes USERNAME to be used to access Docker source registry.
85
86       -p, --password PASSWORD
87           This argument takes PASSWORD to be used to access Docker source
88           registry.
89
90       --not-secure
91           Don't require HTTPS and verification of certificates when talking
92           to Docker registry.
93
94           See "skopeo copy" in skopeo(1)
95
96   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
101           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
104           See "INSTALLATION OPTIONS" in virt-install(1)
105
106       --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
110           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
113           See "INSTALLATION OPTIONS" in virt-install(1)
114
115       --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
120           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
123           See "INSTALLATION OPTIONS" in virt-install(1)
124

USAGE EXAMPLES

126       Create root file system using Ubuntu image docker.io registry:
127               $ virt-bootstrap docker://ubuntu /tmp/foo
128
129       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
135       Apply UIDs/GIDs mapping for root file system entries
136               $ virt-bootstrap docker://fedora /tmp/foo \
137                 --idmap 0:1000:10
138
139           This above command will map UIDs/GIDs: 0-9 to 1000-1009
140
141           The same result can be achieved with:
142
143               $ virt-bootstrap docker://fedora /tmp/foo \
144                 --uidmap 0:1000:10 \
145                 --gidmap 0:1000:10
146
147       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
152           This will map the UID/GIDs: 0-9 to 1000-1009 and 500-509 to
153           1500-1509
154
155       Set root password
156               $ virt_bootstrap.py docker://opensuse /tmp/foo \
157                 --root-password file:/tmp/secret
158
159           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
164               $ virt_bootstrap.py docker://opensuse /tmp/foo \
165                 --root-password file:/tmp/secret \
166                 -f qcow2
167
168           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

AUTHOR

175       Written by Cedric Bosdonnat and  Radostin Stoyanov
176
177
178
1791.1.1                             2022-01-22                 VIRT-BOOTSTRAP(1)
Impressum