From 91913f584af38b29a816cca959ba648acd60ac9f Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 24 Aug 2015 22:17:52 +0200 Subject: machinectl: make machine name parameters for "shell" and "login" optional If no machine name is specified, imply that we connect to ".host", i.e. the local host. --- man/machinectl.xml | 123 ++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 104 insertions(+), 19 deletions(-) (limited to 'man') diff --git a/man/machinectl.xml b/man/machinectl.xml index 43dcbbdb18..2f68f91b93 100644 --- a/man/machinectl.xml +++ b/man/machinectl.xml @@ -65,6 +65,43 @@ systemd1 virtual machine and container registration manager systemd-machined.service8. + + machinectl may be used to execute + operations on machines and images. Machines in this sense are + considered running instances of: + + + Virtual Machines (VMs) that virtualize hardware + to run full operating system (OS) instances (including their kernels) + in a virtualized environment on top of the host OS. + + Containers that share the hardware and + OS kernel with the host OS, in order to run + OS userspace instances on top the host OS. + + The host system itself + + + Machines are identified by names that follow the same rules + as UNIX and DNS host names, for details see below. Machines are + instantiated from disk or file system images, that frequently but not + necessarily carry the same name as machines running from + them. Images in this sense are considered: + + + Directory trees containing an OS, including its + top-level directories /usr, + /etc, and so on. + + btrfs subvolumes containing OS trees, similar to + normal directory trees. + + Binary "raw" disk images containing MBR or GPT + partition tables and Linux file system partitions. + + The file system tree of the host OS itself. + + @@ -270,9 +307,11 @@ list List currently running (online) virtual - machines and containers. To enumerate container images that - can be started, use list-images (see - below). + machines and containers. To enumerate machine images that can + be started, use list-images (see + below). Note that this command hides the special + .host machine by default. Use the + switch to show it. @@ -290,7 +329,7 @@ - show NAME... + show [NAME...] Show properties of one or more registered virtual machines or containers or the manager itself. If no @@ -339,31 +378,42 @@ - login NAME + login [NAME] Open an interactive terminal login session in - 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 + a container or on the local host. If an argument is supplied + it refers to the container machine to connect to. If none is + specified, or the container name is specified as the empty + string, or the special machine name .host + (see below) is specified, the connection is made to the local + host instead. This will create a TTY connection to a specific + container or the local host 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 - shell (see below) or + container or the local host, which then asks for username and + password. Use shell (see below) or systemd-run1 - with the switch to invoke a single - command, either interactively or in the background within a - local container. + with the switch to directly invoke + a single command, either interactively or in the + background. - shell NAME [PATH [ARGUMENTS...]] + shell [NAME [PATH [ARGUMENTS...]]] Open an interactive shell session in a - container. This works similar to login but - immediately invokes a user process. Invokes the specified - executable with the specified arguments, or + container or on the local host. The first argument refers to + the container machine to connect to. If none is specified, or + the machine name is specified as the empty string, or the + special machine name .host (see below) is + specified, the connection is made to the local host + instead. This works similar to login but + immediately invokes a user process. This command runs the + specified executable with the specified arguments, or /bin/sh if none is specified. By default opens a root shell, but using a different user may be selected. Use @@ -491,7 +541,7 @@ - image-status NAME... + image-status [NAME...] Show terse status information about one or more container or VM images. This function is intended to @@ -501,7 +551,7 @@ - show-image NAME... + show-image [NAME...] Show properties of one or more registered virtual machine or container images, or the manager itself. If @@ -803,6 +853,41 @@ + + Machine and Image Names + + The machinectl tool operates on machines + and images, whose names must be chosen following strict + rules. Machine names must be suitable for use as host names + following a conservative subset of DNS and UNIX/Linux + semantics. Specifically, they must consist of one or more + non-empty label strings, separated by dots. No leading or trailing + dots are allowed. No sequences of multiple dots are allowed. The + label strings may only consists of alphanumeric characters as well + as the dash and underscore. The maximum length of a machine name + is 64 characters. + + A special machine with the name .host + refers to the running host system itself. This is useful for execution + operations or inspecting the host system as well. Not that + machinectl list will not show this special + machine unless the switch is specified. + + Requirements on image names are less strict, however must be + valid UTF-8, must be suitable as file names (hence not be the + single or double dot, and not include a slash), and may not + contain control characters. Since many operations search for an + image by the name of a requested machine it is recommended to name + images in the same strict fashion as machines. + + A special image with the name .host + refers to the image of the running host system. It is hence + conceptually maps to the special .host machine + name described above. Note that machinectl + list-images won't show this special image either, unless + is specified. + + Files and Directories -- cgit v1.2.3-54-g00ecf