1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
# -*- coding: utf-8 -*-
# Authors:
# Radostin Stoyanov <rstoyanov1@gmail.com>
# Copyright (c) 2017 Radostin Stoyanov
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
r"""
The virtBootstrap module provides an easy way to setup the root file system for
Libvirt-LXC containers.
This module exports the method bootstrap() which takes the following arguments:
uri
This parameter takes a string of source URI.
Supported URI formats:
--------------------------------------
- File (tarball)
/path/to/local/rootfs.tar.xz
file://path/to/local/rootfs.tar.xz
- Docker registry (skopeo)
docker://ubuntu:latest
docker://docker.io/fedora
docker://privateregistry:5000/image
- virt-builder
virt-builder://fedora-25
virt-builder://ubuntu-16.04
--------------------------------------
* If Docker registry is not specified "docker.io" is used.
dest
This parameter takes a string which represents absolute or real path of
destination directory where the root file system will be extract or
qcow2 images will be stored.
fmt (optional)
This parameter takes a string which represents the output format for
the root file system. Possible values are:
- dir (default)
- qcow2
username (optional)
This parameter takes a string which represents the username used to
access Docker source registry. See also "password" and "not_secure".
If this parameter is specified and the "password" is ommited password
prompt will be issued.
*See https://docs.docker.com/registry/deploying/#restricting-access
password (optional)
This parameter takes a string which represents the password used to
access Docker source registry.
*See https://docs.docker.com/registry/deploying/#restricting-access
root_password (optional)
This parameter takes a string which represents root password.
This string is hashed and inserted into /etc/shadow file of the
extracted root file system.
If the output format is "qcow2" the modification of /etc/shadow are
applied in additional qcow2 disk image with backing file set to the
last layer.
*The /etc/shadow file must already exist in the rootfs of the container
image and have "root" user entry.
uid_map (optional)
This parameter takes a list of lists which represents the translation
map for UID. See also "gid_map".
Format:
[[<start>, <target>, <count>]]
Example:
[[0, 1000, 10], [500, 1500, 10]]
This will map the UID: 0-9 to 1000-1009 and 500-509 to 1500-1509
*When the output format is "dir" (fmt="dir") this option is available
only for privileged users.
gid_map (optional)
This parameter is used to map group ownership of files in the
extracted rootfs. It works in a similar way as "uid_map".
not_secure (optional)
This parameter takes a boolean which indicates whether HTTPS errors
will be ignored. Default value is False.
*See "--src-tls-verify" from "skopeo copy".
https://www.mankier.com/1/skopeo#skopeo_copy
no_cache (optional)
This parameter takes a boolean which indicates whether the downloaded
Docker images will be discarded after the root file system was
extracted.
By default downloaded images are stored in:
/var/cache/virt-bootstrap/docker_images/
for non-root users:
~/.cache/share/virt-bootstrap/docker_images/
progress_cb (optional)
This parameter takes a function which is called every time when the
progress information is updated. Only one parameter passed to the
called function - a dictionary with keys 'status' and 'value'.
Examples:
{'status': 'Checking cached layers', 'value': 0}
{'status': 'Downloading layer (1/1)', 'value': 12.82051282051282}
Usage Examples
import virtBootstrap
# Bootstrap latest Ubuntu container image from docker.io
virtBootstrap.bootstrap(uri='docker://ubuntu', dest='/tmp/foo')
# Bootstrap Fedora 25 container image from docker.io
virtBootstrap.bootstrap(
uri='docker://registry.fedoraproject.org/fedora:25',
dest='/tmp/bar'
)
# Set password for root
virtBootstrap.bootstrap(
uri='docker://fedora',
dest='/tmp/foo',
root_password='secret'
)
# Convert Ubuntu container image to qcow2 disk image using backing chains
virtBootstrap.bootstrap(
uri='docker://ubuntu',
dest='/tmp/foo',
fmt='qcow2'
)
# Bootstrap root file system from image stored in private registry
virtBootstrap.bootstrap(
uri='docker://localhost:5000/opensuse',
dest='/tmp/foo',
username='testuser',
password='testpassoword',
not_secure=True
)
# Apply UID/GID mapping (root privileges required).
virtBootstrap.bootstrap(
uri='docker://ubuntu',
dest='/tmp/foo',
uid_map=[[0,1000,10]],
gid_map=[[0,1000,10]]
)
# Use progress callback to print the current progress to stdout
def show(prog): print(prog)
virtBootstrap.bootstrap(
uri='docker://ubuntu',
dest='/tmp/foo',
progress_cb=show
)
Note:
You don't necessarily need to be root when using virt-bootstrap with
"qcow2" output format, however, for "dir" format there are some drawbacks:
1. Mapping UID/GID is not supported for unprivileged users.
2. All extracted files will be owned by the current unprivileged user.
"""
from virtBootstrap.virt_bootstrap import bootstrap
from virtBootstrap.virt_bootstrap import __version__
|
