X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fmachinectl.xml;h=61ea1c45d8f58e5ac599373a007ffb0e9b0fe3c9;hb=5fae368bda9419d9d378ea32077c8fd183dd4b81;hp=baa0e17e3679bad93c0a3d2310214f80286488cc;hpb=8b0cc9a36c8f92f010f2e8465942d2cd7c580d78;p=elogind.git diff --git a/man/machinectl.xml b/man/machinectl.xml index baa0e17e3..61ea1c45d 100644 --- a/man/machinectl.xml +++ b/man/machinectl.xml @@ -76,27 +76,31 @@ - When showing - machine properties, limit the - output to certain properties as - specified by the argument. If not - specified, all set properties are - shown. The argument should be a - property name, such as - Name. If - specified more than once, all - properties with the specified names - are shown. + When showing machine + or image properties, limit the output + to certain properties as specified by + the argument. If not specified, all + set properties are shown. The argument + should be a property name, such as + Name. If specified + more than once, all properties with + the specified names are + shown. - When showing - machine properties, show all - properties regardless of whether they are - set or not. + When showing machine + or image properties, show all + properties regardless of whether they + are set or not. + + When listing VM or container + images, do not suppress images + beginning in a dot character + (.). @@ -108,6 +112,14 @@ + + + + Do not query the user + for authentication for privileged + operations. + + @@ -138,14 +150,6 @@ SIGTERM. - - - - Do not print the legend, - i.e. the column headers and the - footer. - - @@ -193,23 +197,82 @@ 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. + + + + - + + + + Commands The following commands are understood: - + Machine Commands + list List currently running - virtual machines and containers. - + (online) virtual machines and + containers. To enumerate container + images that can be started, + use list-images + (see below). @@ -256,30 +319,92 @@ output. + + start NAME... + + Start a container as a + system service, using + systemd-nspawn1. + This starts + systemd-nspawn@.service, + instantiated for the specified machine + name, similar to the effect of + systemctl start on + the service + name. systemd-nspawn + looks for a container image by the + specified name in + /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 + systemd-machined.service8 + also interfaces with a variety of + other container and VM managers, + systemd-nspawn is + just one implementation of it. Most of + the commands available in + machinectl may be + used on containers or VMs controlled + by other managers, not just + systemd-nspawn. Starting + VMs and container images on those + managers requires manager-specific + tools. + + To interactively start a + container on the command line with + full access to the container's + console, please invoke + systemd-nspawn + directly. To stop a running container + use machinectl + poweroff, see + below. + + login NAME - Open a terminal login + Open an interactive terminal login session to a container. This will create a TTY connection to a specific container and asks for the execution of a getty on it. Note that this is only supported for containers running systemd1 - as init system. + as init system. + + This command will open a full + login prompt on the container, which + then asks for username and + password. Use + systemd-run1 + with the + switch to invoke a single command, + either interactively or in the + background within a local + container. - reboot NAME... - - Reboot one or more - containers. This will trigger a reboot - by sending SIGINT to the container's - init process, which is roughly - equivalent to pressing Ctrl+Alt+Del on - a non-containerized system, and is - compatible with containers running any - init system. + enable NAME... + disable NAME... + + Enable or disable a + container as a system service to start + at system boot, using + systemd-nspawn1. + This enables or disables + systemd-nspawn@.service, + instantiated for the specified machine + name, similar to the effect of + systemctl enable or + systemctl disable + on the service name. @@ -294,8 +419,38 @@ not work on containers that do not run a systemd1-compatible - init system, such as - sysvinit. + init system, such as sysvinit. Use + terminate (see + below) to immediately terminate a + container or VM, without cleanly + shutting it down. + + + + reboot NAME... + + Reboot one or more + containers. This will trigger a reboot + by sending SIGINT to the container's + init process, which is roughly + equivalent to pressing Ctrl+Alt+Del on + a non-containerized system, and is + compatible with containers running any + system manager. + + + + terminate NAME... + + Immediately terminates + a virtual machine or container, + without cleanly shutting it down. This + kills all processes of the virtual + machine or container and deallocates + all resources attached to that + instance. Use + poweroff to issue a + clean shutdown request. @@ -313,17 +468,6 @@ the signal to send. - - terminate NAME... - - Terminates a virtual - machine or container. This kills all - processes of the virtual machine or - container and deallocates all - resources attached to that - instance. - - bind NAME PATH [PATH] @@ -375,9 +519,428 @@ omitted the same as the source path is used. + + + Image Commands + + + list-images + + Show a list of locally + installed container and VM + images. This enumerates all raw disk + images and container directories and + subvolumes in + /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 + containers whose name begins with a + dot (.) are not + shown. To show these too, specify + . Note that a + special image .host + always implicitly exists and refers to + the image the host itself is booted + from. + + + + image-status NAME... + + Show terse status + information about one or more + container or VM images. This function + is intended to generate human-readable + output. Use + show-image (see + below) to generate computer-parsable + output instead. + + + + show-image NAME... + + Show properties of one + or more registered virtual machine or + container images, or the manager + itself. If no argument is specified, + properties of the manager will be + shown. If an NAME is specified, + properties of this virtual machine or + container image are shown. By default, + empty properties are suppressed. Use + to show those + too. To select specific properties to + show, use + . This + command is intended to be used + whenever computer-parsable output is + required. Use + image-status if you + are looking for formatted + human-readable + output. + + + + clone NAME NAME + + Clones a container or + disk image. The arguments specify the + name of the image to clone and the + name of the newly cloned image. Note + that plain directory container images + are cloned into subvolume images with + this command. Note that cloning a + container or VM image is optimized for + btrfs file systems, and might not be + efficient on others, due to file + system limitations. + + + + rename NAME NAME + + Renames a container or + disk image. The arguments specify the + name of the image to rename and the + new name of the + image. + + + + read-only NAME [BOOL] + + Marks or (unmarks) a + container or disk image + read-only. Takes a VM or container + image name, followed by a boolean as + arguments. If the boolean is omitted, + positive is implied, i.e. the image is + marked read-only. + - + + remove NAME... + + Removes one or more + container or disk images. The special + image .host, which + refers to the host's own directory + tree may not be + 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=. +