X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fmachinectl.xml;h=61ea1c45d8f58e5ac599373a007ffb0e9b0fe3c9;hb=78eb158a20e2bee772f6e49d8b432b98f68cbb55;hp=91bdb5e111505b068d0dd34acf3c92e773fae908;hpb=e45fc5e738b0b7700e8b4f3c4b25c58a49b44b27;p=elogind.git diff --git a/man/machinectl.xml b/man/machinectl.xml index 91bdb5e11..61ea1c45d 100644 --- a/man/machinectl.xml +++ b/man/machinectl.xml @@ -150,14 +150,6 @@ SIGTERM. - - - - Do not print the legend, - i.e. the column headers and the - footer. - - @@ -205,12 +197,63 @@ 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. + + + + - @@ -291,10 +334,10 @@ name. systemd-nspawn looks for a container image by the specified name in - /var/lib/container - and runs it. Use - list-images (see - below), for listing available + /var/lib/machines/ + (and other search paths, see below) and runs + it. Use list-images + (see below), for listing available container images to start. Note that @@ -488,7 +531,7 @@ images. This enumerates all raw disk images and container directories and subvolumes in - /var/lib/container/. Use + /var/lib/machines/ (and other search paths, see below). Use start (see above) to run a container off one of the listed images. Note that by default @@ -590,11 +633,316 @@ 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. + + + + Files and Directories + + Machine images are preferably stored in + /var/lib/machines/, but are also + searched for in + /usr/local/lib/machines/ and + /usr/lib/machines/. For + compatibility reasons the directory + /var/lib/container/ is searched, + too. Note that images stored below + /usr are always considered + read-only. It is possible to symlink machines images + from other directories into + /var/lib/machines/ to make them + available for control with + machinectl. + + Disk images are understood by + systemd-nspawn1 + and machinectl in three + formats: + + + A simple directory tree, + containing the files and directories of the + container to boot. + + A subvolume (on btrfs file + systems), which are similar to the simple + directories, described above. However, they + have additional benefits, such as efficient + cloning and quota reporting. + + "Raw" disk images, i.e. binary + images of disks with a GPT or MBR partition + table. Images of this type are regular + files with the suffix + .raw. + + + See + systemd-nspawn1 + for more information on image formats, in particular + it's and + 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