X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fmachinectl.xml;h=ff447b62105ba17cff4b4373584982800791d0a8;hb=12f15e596a3040f32bb8c9aa9d0bf9b43fc96567;hp=2606180d123d70890d217502e5099d6f4777b547;hpb=19887cd06a3af2f045e763986eda19e208bd3f85;p=elogind.git diff --git a/man/machinectl.xml b/man/machinectl.xml index 2606180d1..ff447b621 100644 --- a/man/machinectl.xml +++ b/man/machinectl.xml @@ -21,7 +21,8 @@ along with systemd; If not, see . --> - + machinectl @@ -71,64 +72,46 @@ The following options are understood: - - - - - Prints a short help - text and exits. - - - - - - Prints a short version - string and exits. - - - When showing - session/user properties, limit - display to certain properties as - specified as 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 - unit/job/manager properties, show all - properties regardless 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 + (.). - Do not ellipsize cgroup - members. + Do not ellipsize + process tree entries. - - - - Do not pipe output into a - pager. - - @@ -141,13 +124,13 @@ When used with - kill-session, + kill, choose which processes to kill. Must be one of , or to select whether to kill only the leader process of the - session or all processes of the - session. If omitted, defaults to + machine or all processes of the + machine. If omitted, defaults to . @@ -156,11 +139,10 @@ When used with - kill-session or - kill-user, choose + kill, choose which signal to send to selected - processes. Must be one of the well - known signal specifiers, such as + processes. Must be one of the + well-known signal specifiers, such as SIGTERM, SIGINT or SIGSTOP. If @@ -169,60 +151,109 @@ - - - - Execute operation - remotely. Specify a hostname, or - username and hostname separated by @, - to connect to. This will use SSH to - talk to the remote machine manager - instance. + + + When used with + bind creates the + destination directory before applying + the bind mount. + + + + + + + When used with + bind applies a + read-only bind + mount. + + + + + + + + When used with + status, controls + the number of journal lines to show, + counting from the most recent + ones. Takes a positive integer + argument. Defaults to 10. + - - + + - Acquire privileges via - PolicyKit before executing the - operation. + When used with + status, controls + the formatting of the journal entries + that are shown. For the available + choices, see + journalctl1. + Defaults to + short. + + + + + + + + + + + + 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). - status [ID...] + status NAME... Show terse runtime status information about one or more - virtual machines and containers. This - function is intended to generate - human-readable output. If you are - looking for computer-parsable output, - use show instead. - + virtual machines and containers, + followed by the most recent log data + from the journal. This function is + intended to generate human-readable + output. If you are looking for + computer-parsable output, use + show instead. Note + that the log data shown is reported by + the virtual machine or container + manager, and frequently contains + console output of the machine, but not + necessarily journal contents of the + machine itself. - show [ID...] + show NAME... Show properties of one or more registered virtual machines or containers or the manager itself. If no argument is specified, properties - of the manager will be shown. If a an - ID is specified, properties of this + of the manager will be shown. If an + NAME is specified, properties of this virtual machine or container are shown. By default, empty properties are suppressed. Use @@ -239,18 +270,141 @@ - terminate [ID...] - - Terminates a virtual - machine or container. This kills all - processes of the virtual machine or - container and deallocates all - resources attached to that - instance. + 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. - kill [ID...] + login NAME + + 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. + + 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. + + + + 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. + + + + poweroff NAME... + + Power off one or more + containers. This will trigger a reboot + by sending SIGRTMIN+4 to the + container's init process, which causes + systemd-compatible init systems to + shut down cleanly. This operation does + not work on containers that do not run + a + systemd1-compatible + 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. + + + + kill NAME... Send a signal to one or more processes of the virtual @@ -263,8 +417,220 @@ to select the signal to send. - + + bind NAME PATH [PATH] + + Bind mounts a + directory from the host into the + specified container. The first + directory argument is the source + directory on the host, the second + directory argument the source + directory on the host. When the latter + is omitted the destination path in the + container is the same as the source + path on the host. When combined with + the + switch a ready-only bind mount is + created. When combined with the + switch the + destination path is first created + before the mount is applied. Note that + this option is currently only + supported for + systemd-nspawn1 + containers. + + + + copy-to NAME PATH [PATH] + + Copies files or + directories from the host system into + a running container. Takes a container + name, followed by the source path on + the host and the destination path in + the container. If the destination path + is omitted the same as the source path + is used. + + + + + copy-from NAME PATH [PATH] + + Copies files or + directories from a container into the + host system. Takes a container name, + followed by the source path in the + container the destination path on the + host. If the destination path is + 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. + + + + + + + + + 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 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. @@ -274,27 +640,14 @@ code otherwise. - - Environment - - - - $SYSTEMD_PAGER - Pager to use when - is not given; - overrides $PAGER. Setting - this to an empty string or the value - cat is equivalent to passing - . - - - + See Also systemd-machined.service8, - systemd-logind.service8 + systemd-nspawn1, + systemd.special7