<div dir="ltr">Hi everyone! I am Radostin, a student involved with Libvirt in the <a href="https://wiki.libvirt.org/page/Google_Summer_of_Code_Ideas#Ease_creation_of_containers" style="text-decoration-line:none">Ease creation of containers</a> Google Summer of Code (GSoC) Project. The idea of this project was to provide a simple way to setup root file system for the Libvirt LXC driver. Here I present the complete work I did during the GSoC term and also explanations for the same. This summer I mostly worked on 2 things: <ul style="margin-top:0pt;margin-bottom:0pt"><li dir="ltr" style="list-style-type:disc;font-size:12pt;font-family:Arial;color:rgb(0,0,10);background-color:transparent;vertical-align:baseline">Adding new features to <a href="https://github.com/virt-manager/virt-bootstrap" style="text-decoration-line:none">virt-bootstrap</a></li><li dir="ltr" style="list-style-type:disc;font-size:12pt;font-family:Arial;color:rgb(0,0,10);background-color:transparent;vertical-align:baseline">Integration of virt-bootstrap with <a href="https://github.com/virt-manager/virt-manager" style="text-decoration-line:none">virt-manager</a> for smooth user experience.</li></ul> What has been done?At the beginning of the project I <a href="https://www.redhat.com/archives/virt-tools-list/2017-April/msg00053.html" style="text-decoration-line:none">shared my idea</a> for extending the user interface of virt-manager on the virt-tools mailing list. The received feedback gave me ideas for adjustments to work towards but mainly this was to show the progress of virt-bootstrap in virt-manager. Before the integration with virt-manager some improvements for virt-bootstrap were required to ensure that the installation process is simple and the progress information is tracked in accessible for virt-manager way.In addition to that, conversion of Docker image layers to qemu copy-on-write images using backing chains was enabled.<a href="https://github.com/virt-manager/virt-bootstrap/commit/0b998e5c230cdf458a390d0d9c28c85f21b9fbd2" style="text-decoration-line:none">[virt-bootstrap] Cache downloaded container images</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/9ebc936407911ee29570e05565255b8b7aaa38b2" style="text-decoration-line:none">[virt-bootstrap] Extract tar archives safely using virt-sandbox</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/8a3e52019315a00f8fee222ecdc803a914608068" style="text-decoration-line:none">[virt-bootstrap] Add support for layer extraction in qcow2 images</a> <a href="https://github.com/virt-manager/virt-bootstrap/commit/31e38232b7857bbf190a1234976e93f521fbffe0" style="text-decoration-line:none">[virt-bootstrap] Move source files in src/virtBootstrap</a> <a href="https://github.com/virt-manager/virt-bootstrap/commit/6f80e1a8182acdbd1d49e21a4451850d6df4f05c" style="text-decoration-line:none">[virt-bootstrap] Use setuptools (setup.py) for installation</a> <a href="https://github.com/virt-manager/virt-bootstrap/commit/4ca83f7b40bc147b9d59cc38de0e5bea44abdbda" style="text-decoration-line:none">[virt-bootstrap] Log executed process calls</a> <a href="https://github.com/virt-manager/virt-bootstrap/commit/dfbfc0f2613bf746948da871e3aa0ec054f6bd4f" style="text-decoration-line:none">[virt-bootstrap] Add "debug" and "quiet" flags</a> <a href="https://github.com/virt-manager/virt-bootstrap/commit/3001ebf7249de17ab733b1e6978b1ff372219a56" style="text-decoration-line:none">[virt-bootstrap] Show error if destination path is not folder</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/1be26027e7b42cd65937ca185a106ce9139ba4c1" style="text-decoration-line:none">[virt-bootstrap] Improve logging of executed processes</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/34a25916646108454fac8dd490ae5d70eb7ce6bd" style="text-decoration-line:none">[virt-bootstrap] Raise exception if file source is invalid</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/6903f23563549f8d81fa911103594f9f472ab3c7" style="text-decoration-line:none">[virt-bootstrap] Improve logging of virt-sandbox</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/8306c37832613c2c0d4d75806c6763e6678c5edd" style="text-decoration-line:none">[virt-bootstrap] Refactor info messages</a> <a href="https://github.com/virt-manager/virt-bootstrap/commit/bb5932eea5e0f9c32bb782ca70e2c9d0af0e0940" style="text-decoration-line:none">[virt-bootstrap] Auto-correct docker source URI</a> <a href="https://github.com/virt-manager/virt-bootstrap/commit/96109db4bd08ffc1e1dcca6f87994761642ce413" style="text-decoration-line:none">[virt-bootstrap] Check for write permissions on destination path</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/1dd194f36079fd822f667419e030fbd07a8480b9" style="text-decoration-line:none">[virt-bootstrap] Set logger name/format/level</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/65ef323df230b770c56217367e9c019cffcb0a7d" style="text-decoration-line:none">[virt-bootstrap] Expose bootstrap method from virtBootstrap module</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/970b4247bd9a39d36ade980967371e4d1bc3f893" style="text-decoration-line:none">[virt-bootstrap] bootstrap: Use explicit arguments</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/7daf37d2a5155e742b3c4daea24923e4a7b7d855" style="text-decoration-line:none">[virt-bootstrap] Improve URI parse of DockerSource</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/7bb698af895af30007f2034e554a3d999090dd2a" style="text-decoration-line:none">[virt-bootstrap] DockerSource: Use getter for image directory</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/78a5313c1076580c4a7308294765c26caa2da127" style="text-decoration-line:none">[virt-bootstrap] DockerSource: Retrieve manifest before download</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/847886deea03e95d35afec925a598a498d68265c" style="text-decoration-line:none">[virt-bootstrap] Log the size of layers when extracting</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/c1cdbeee437c5c82d9928e73211f6bac91259dcc" style="text-decoration-line:none">[virt-bootstrap] Compact layers' details passed to extract methods</a> <a href="https://github.com/virt-manager/virt-bootstrap/commit/04dfccb8acda9d79a3a7dccb16a5670fb3f279e7" style="text-decoration-line:none">[virt-bootstrap] DockerSource: Encapsulate skopeo copy in a method</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/64ef61bd999ab669dcb21424528894f8fad97e0f" style="text-decoration-line:none">[virt-bootstrap] DockerSource: Use downloaded layers</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/a1ba3edb9a76fa89001f0a069e5c8eada876fb40" style="text-decoration-line:none">[virt-bootstrap] Remove redundant checksum verification</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/9d1bc151c7eb72c1281d6a22476a9082fef8374e" style="text-decoration-line:none">[virt-bootstrap] checksum: Log failures</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/b8b69f2f41802bf87e119845a6f532d4970d2481" style="text-decoration-line:none">[virt-bootstrap] Add new module to store the progress</a> <a href="https://github.com/virt-manager/virt-bootstrap/commit/08d036a433b830319c931976b7a4e17574934720" style="text-decoration-line:none">[virt-bootstrap] Add --status-only flag</a> <a href="https://github.com/virt-manager/virt-bootstrap/commit/c7a25202019cad8a6a9302ab81cc80d547da0ec9" style="text-decoration-line:none">[virt-bootstrap] Detect and log download progress of layers</a> <a href="https://github.com/virt-manager/virt-bootstrap/commit/0095aca7457911d8515967fd03cd53f76abd465e" style="text-decoration-line:none">[virt-bootstrap] get_image_details: Use connection options</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/971313ccb67068035622b3f5bbcf8737e9aeee80" style="text-decoration-line:none">[virt-bootstrap] Gather common utility functions in "utils" module</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/f23d759eda69738917985feb9af727f792d1145e" style="text-decoration-line:none">[virt-bootstrap] DockerSource: Ignore short lines from skopeo</a> <a href="https://github.com/virt-manager/virt-bootstrap/commit/5afb6c9b0728c7f5f0edd14a44e62ae91959194d" style="text-decoration-line:none">[virt-bootstrap] utils: size_to_bytes convert from int</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/4a0152f73fcf94c739836e4b8bbe969b56daddba" style="text-decoration-line:none">[virt-bootstrap] utils: bytes_to_size remove trailing space</a><a href="https://github.com/virt-manager/virt-bootstrap/commit/3e7cbbdcc953b5249b9b462a97acff0176dfcbfd" style="text-decoration-line:none">[virt-bootstrap] DockerSource: Encapsulate layers' info retrieval</a> The integration of virt-bootstrap with virt-manager was achieved by extending the UI and importing the virtBootstrap python module. Creation of the root file system tree is done using the bootstrap() method which is called asynchronously in a thread. [<a href="https://www.youtube.com/watch?v=CDeDobeyU0I" style="text-decoration-line:none">Demo video</a>] <a href="https://www.redhat.com/archives/virt-tools-list/2017-July/msg00005.html" style="text-decoration-line:none">[virt-manager] create: Add support for OS tree creation</a> <a href="https://www.redhat.com/archives/virt-tools-list/2017-July/msg00006.html" style="text-decoration-line:none">[virt-manager] create: Validate input on container bootstrap</a> <a href="https://www.redhat.com/archives/virt-tools-list/2017-July/msg00010.html" style="text-decoration-line:none">[virt-manager] gschema: Populate/Store previous container URLs</a> <a href="https://www.redhat.com/archives/virt-tools-list/2017-July/msg00030.html" style="text-decoration-line:none">[virt-manager] create: Show progress of container bootstrap</a> <a href="https://www.redhat.com/archives/virt-tools-list/2017-July/msg00029.html" style="text-decoration-line:none">[virt-manager] create: Call virt-bootstrap asynchronously</a> <a href="https://www.redhat.com/archives/virt-tools-list/2017-July/msg00031.html" style="text-decoration-line:none">[virt-manager] create: Show details of container bootstrap</a> <a href="https://www.redhat.com/archives/virt-tools-list/2017-July/msg00032.html" style="text-decoration-line:none">[virt-manager] asyncjob: Add enable/update details methods</a> Another feature added to virt-bootstrap was the UID/GID mapping which can be used to create Libvirt LXC container with enabled user namespace. In such container the owner/group of files must be mapped to UID/GID of users inside the container. <a href="https://github.com/virt-manager/virt-bootstrap/commit/e92b724289120c262c635e6005703477ebaa3fe0" style="text-decoration-line:none">[virt-bootstrap] Add remapping ownership of files in rootfs</a> What code was merged? <a href="https://github.com/virt-manager/virt-bootstrap/commits?author=rst0git" style="text-decoration-line:none">Merged commits for virt-bootstrap</a><a href="https://github.com/virt-manager/virt-manager/commits?author=rst0git" style="text-decoration-line:none">Merged commits for virt-manager</a> How to use virt-bootstrap? The command line tool virt-bootstrap provides an easy way to setup root file system from various sources such as a tar archive containing the file system, container image from Docker registry or VM disk image created with virt-builder. <ul style="margin-top:0pt;margin-bottom:0pt"><li dir="ltr" style="list-style-type:disc;font-size:14pt;font-family:Arial;color:rgb(0,0,10);background-color:transparent;vertical-align:baseline">Extract root file system from a tar archive.</li></ul> $ virt-bootstrap /home/user/rootfs.tar /var/lib/Libvirt/filesystems/container1 This will extract securely the root file system from rootfs.tar to /var/lib/Libvirt/filesystems/container1 using LXC container if the user is with effective UID 0 or kvm instance (qemu:///session) otherwise. Optionally to apply adjustments can be the flags:--fmt Specify the output format. Possible values are “dir” and “qcow2”--idmap Apply map for owner and group of entries--uidmap Apply map for owner of entries--gidmap Apply map for group of entries--root-password Set password for root <ul style="margin-top:0pt;margin-bottom:0pt"><li dir="ltr" style="list-style-type:disc;font-size:14pt;font-family:Arial;color:rgb(0,0,10);background-color:transparent;vertical-align:baseline">Extract root file system from Docker image</li></ul> Container images might have multiple layers where each layer store only the changes made. To extract root file system from them we have to extract the layers in order starting from base layer. This is what you can do with virt-bootstrap in the following example: $ virt-bootstrap docker://ubuntu /var/lib/Libvirt/filesystems/ct1 The root file system extracted in /var/lib/Libvirt/filesystems/ct1 can be used by Libvirt to start LXC container. Alternatively the layers of container image can be preserved using qcow2 image with backing chains: $ virt-bootstrap docker://ubuntu /var/lib/Libvirt/filesystems/ct1 \ –-format qcow2 This example will create qcow2 image with single partition and ext3 file system which contains the base layer of the latest Ubuntu container image available on <a href="http://docker.io">docker.io</a>. Then it will create qcow2 image with backing file for each layer of the container image and store only the changes applied within this layer. This is implemented using libguestfs and does not require root privileges. Optionally the flags for UID/GID mapping or root password can be used as well. <ul style="margin-top:0pt;margin-bottom:0pt"><li dir="ltr" style="list-style-type:disc;font-size:14pt;font-family:Arial;color:rgb(0,0,10);background-color:transparent;vertical-align:baseline">Extract root file system from VM image build with virt-builder</li></ul> The tool virt-builder can be used to build disk image for virtual machine from template. To create container from such VM image we have to extract the root file system. The example below demonstrates how this can be achieved with virt-bootstrap: $ virt-bootstrap virt-builder://fedora-25 /var/lib/Libvirt/filesystems/ct1 This command will build VM image from fedora-25 in temporary file and extract the root file system to /var/lib/Libvirt/filesystems/ct1 which can be used with Libvirt to create LXC container. Optionally the flags for UID/GID mapping or setting root password can be used as well. <ul style="margin-top:0pt;margin-bottom:0pt"><li dir="ltr" style="list-style-type:disc;font-size:14pt;font-family:Arial;color:rgb(0,0,10);background-color:transparent;vertical-align:baseline">Apply UID/GID mapping</li></ul> The flags --idmap, --uidmap and --gidmap can be used to map the owner and group of members in the created root file system. Each of these flags can be used multiple times and take input with format: <start>:<target>:<count> Where <start> is the UID/GID on the host, <target> is the UID/GID inside the container and <count> is the number of UID/GIDs to be mapped (range). Example: $ virt-bootstrap docker://fedora /var/lib/Libvirt/filesystems/ct1 \ --idmap 0:1000:10 \ -–idmap 500:1500:10 This will apply the UID/GID map: 0, 1, 2 … 9 to 1000, 1001, … 1009500, 501 … 509 to 1500, 1501 … 1509 Limitations and known bugs You do not necessarily need to be root to use virt-bootstrap, however there are some limitations for unprivileged users when used with output format “dir”. In such case all members of the extracted root file system will be owned by the same unprivileged and UID/GID mapping cannot be applied. When the output format is qcow2 all functionalities are available for unprivileged users, however at the time of writing this post Libvirt has a bug which does not allow to start LXC container from qcow2 image with enabled user namespace . This bug has been reported here <a href="https://bugzilla.redhat.com/show_bug.cgi?id=1328946" style="text-decoration-line:none">https://bugzilla.redhat.com/show_bug.cgi?id=1328946</a> and the work around is to mount the qcow2 image and start LXC container from the mounted directory with enabled user namespaces. Acknowledgements I would like to thanks all members of Libvirt and virt-tools communities and particularly Cédric Bosdonnat, Cole Robinson and Pavel Hrdina for all commit reviews and suggestions.I would also like to thanks Daniel P. Berrange for the help in resolving issues.And of course, many thanks to the staff of GSoC for running the programme.<div> </div><div>Kind Regards,</div><div>Radostin</div></div>