From e0ea94c1e2ab3930c85c6057189a2a829a13a800 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 22 Jan 2015 15:12:11 +0100 Subject: [PATCH] man: document new download magic --- man/machinectl.xml | 312 ++++++++++++++++++++++++++++++++++++++++- man/systemd-nspawn.xml | 83 ++++++----- 2 files changed, 360 insertions(+), 35 deletions(-) diff --git a/man/machinectl.xml b/man/machinectl.xml index ff447b621..61ea1c45d 100644 --- a/man/machinectl.xml +++ b/man/machinectl.xml @@ -197,6 +197,56 @@ short. + + + + When downloading a + container or VM image, specify whether + the image shall be verified before it + is made available. Takes one of + no, + checksum and + signature. If + no no verification + is done. If + checksum is + specified the download is checked for + integrity after transfer is complete, + but no signatures are verified. If + signature is + specified, the checksum is verified + and the images's signature is checked + against a local keyring of trustable + vendors. It is strongly recommended to + set this option to + signature if the + server and protocol support this. + Defaults to + signature. + + + + + + When downloading a + container or VM image, and a local + copy by the specified local machine + name already exists, delete it first + and replace it by the newly downloaded + image. + + + + + + Specifies the index + server to use for downloading + dkr images with the + pull-dkr. Takes a + http://, + https:// URL. + + @@ -583,6 +633,215 @@ removed. + + + Image Transfer Commands + + + pull-tar URL [NAME] + + Downloads a + .tar container + image from the specified URL, and + makes it available under the specified + local machine name. The URL must be of + type http:// or + https://, and must + refer to a .tar, + .tar.gz, + .tar.xz or + .tar.bz2 archive + file. If the local machine name is + omitted the name it is automatically + derived from the last component of the + URL, with its suffix removed. + + The image is verified before it + is made available, unless + is + specified. Verification is done via + SHA256SUMS and SHA256SUMS.gpg files, + that need to be made available on the + same web server, under the same URL as + the .tar file, + but with the last component (the + filename) of the URL replaced. With + + only the SHA256 checksum for the file + is verified, based on the + SHA256SUMS + file. With + + the SHA256SUMS file is first verified + with detached GPG signature file + SHA256SUMS.gpg. The + public key for this verification step + needs to be available in + /usr/lib/systemd/import-pubring.gpg + or + /etc/systemd/import-pubring.gpg. + + The container image will be + downloaded and stored in a read-only + subvolume in + /var/lib/machines/, + that is named after the specified URL + and its HTTP etag. A writable snapshot + is then taken from this subvolume, and + named after the specified local + name. This behaviour ensures that + creating multiple container instances + of the same URL is efficient, as + multiple downloads are not + necessary. In order to create only the + read-only image, and avoid creating + its writable snapshot, specify + - as local machine + name. + + Note that the read-only + subvolume is prefixed with + .tar-, and + is thus now shown by + list-images, unless + is passed. + + Note that pressing C-c during + execution of this command will not + abort the download. Use + cancel-transfer, + described below. + + + + pull-raw URL [NAME] + + Downloads a + .raw container or + VM disk image from the specified URL, + and makes it available under the + specified local machine name. The URL + must be of type + http:// or + https://. The + container image must either be a + .qcow2 or raw + disk image, optionally compressed as + .gz, + .xz, or + .bz2. If the + local machine name is omitted the name + it is automatically derived from the + last component of the URL, with its + suffix removed. + + Image verification is identical + for raw and tar images (see above). + + If the the downloaded image is + in .qcow2 format + it es converted into a raw image file + before it is made available. + + Downloaded images of this type + will be placed as read-only + .raw file in + /var/lib/machines/. A + local, writable (reflinked) copy is + then made under the specified local + machine name. To omit creation of the + local, writable copy pass + - as local machine + name. + + Similar to the behaviour of + pull-tar, the + read-only image is prefixed with + .raw-, and thus + now shown by + list-images, unless + is + passed. + + Note that pressing C-c during + execution of this command will not + abort the download. Use + cancel-transfer, + described below. + + + + pull-dkr REMOTE [NAME] + + Downloads a + dkr container image + and makes it available locally. The + remote name refers to a + dkr container + name. If omitted, the local machine + name is derived from the + dkr container + name. + + Image verification is not + available for dkr + containers, and thus + must + always be specified with this + command. + + This command downloads all + (missing) layers for the specified + container and places them in read-only + subvolumes in + /var/lib/machines/. A + writable snapshot of the newest layer + is then created under the specified + local machine name. To omit creation + of this writable snapshot, pass + - as local machine + name. + + The read-only layer subvolumes + are prefixed with + .dkr-, and thus + now shown by + list-images, unless + is + passed. + + To specify the + dkr index server to + use for looking up the specified + container, use + . + + Note that pressing C-c during + execution of this command will not + abort the download. Use + cancel-transfer, + described below. + + + + list-transfers + + Shows a list of + container or VM image downloads that + are currently in + progress. + + + + cancel-transfers ID... + + Aborts download of the + container or VM image with the + specified ID. To list ongoing + transfers and their IDs, use + list-transfers. + + @@ -606,7 +865,10 @@ available for control with machinectl. - Disk images are understood in three formats: + Disk images are understood by + systemd-nspawn1 + and machinectl in three + formats: A simple directory tree, @@ -633,6 +895,54 @@ options. + + Examples + + Download an Ubuntu image and open a shell in it + + # machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz +# systemd-nspawn -M trusty-server-cloudimg-amd64-root + + This downloads and verifies the + specified .tar image, and + then uses + systemd-nspawn1 + to open a shell in it. + + + + Download a Fedora image, set a root password in it, start it as service + + # machinectl pull-raw --verify=no http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.raw.xz +# systemd-nspawn -M Fedora-Cloud-Base-20141203-21 +# passwd +# exit +# machinectl start Fedora-Cloud-Base-20141203-21 +# machinectl login Fedora-Cloud-Base-20141203-21 + + This downloads the specified + .raw image with + verification disabled. Then a shell is opened + in it and a root password is set. Afterwards + the shell is left, and the machine started as + system service. With the last command a login + prompt into the container is requested. + + + + Download a Fedora <literal>dkr</literal> image + + # machinectl pull-dkr --verify=no mattdm/fedora +# systemd-nspawn -M fedora + + Downloads a dkr image + and opens a shell in it. Note that the + specified download command might require an + index server to be specified with the + --dkr-index-url=. + + + Exit status diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index b7f3be923..b0f7aa37c 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -247,26 +247,43 @@ the root directory for the container from. Takes a path to a regular file or to a block device node. The file or - block device must contain either an - MBR partition table with a single - partition of type 0x83 that is marked - bootable, or a GUID partition table - with a root partition which is mounted - as the root directory of the - container. Optionally, GPT images may - contain a home and/or a server data - partition which are mounted to the - appropriate places in the - container. All these partitions must - be identified by the partition types - defined by the Discoverable - Partitions Specification. Any - other partitions, such as foreign - partitions, swap partitions or EFI - system partitions are not mounted. May - not be specified together with - , + block device must contain either: + + + An MBR + partition table with a single + partition of type 0x83 that is + marked + bootable. + + A GUID + partition table (GPT) with a single + partition of type + 0fc63daf-8483-4772-8e79-3d69d8477de4. + + A GUID + partition table (GPT) with a + marked root partition which is + mounted as the root directory + of the container. Optionally, + GPT images may contain a home + and/or a server data partition + which are mounted to the + appropriate places in the + container. All these + partitions must be identified + by the partition types defined + by the Discoverable + Partitions + Specification. + + + Any other partitions, such as + foreign partitions, swap partitions or + EFI system partitions are not + mounted. May not be specified together + with , or . @@ -412,7 +429,7 @@ - Create a + Create an ipvlan interface of the specified Ethernet network interface and add it to the @@ -831,8 +848,18 @@ Examples + + + Download a Fedora image and start a shell in it + + # machinectl pull-raw --verify=no http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.raw.xz +# systemd-nspawn -M Fedora-Cloud-Base-20141203-21 + +This downloads an image using machinectl1 and opens a shell in it. + + - Boot a minimal Fedora distribution in a container + Build and boot a minimal Fedora distribution in a container # yum -y --releasever=21 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal # systemd-nspawn -bD /srv/mycontainer @@ -866,18 +893,6 @@ boots an OS in a namespace container in it. - - Enable Arch Linux container on boot - - # mv ~/arch-tree /var/lib/machines/arch -# systemctl enable systemd-nspawn@arch.service -# systemctl start systemd-nspawn@arch.service - - This makes the Arch Linux container part of the - multi-user.target on the host. - - - Boot into an ephemeral <literal>btrfs</literal> snapshot of the host system -- 2.30.2