diff options
Diffstat (limited to 'upstream/debian-unstable/man1/machinectl.1')
| -rw-r--r-- | upstream/debian-unstable/man1/machinectl.1 | 368 |
1 files changed, 83 insertions, 285 deletions
diff --git a/upstream/debian-unstable/man1/machinectl.1 b/upstream/debian-unstable/man1/machinectl.1 index 0fdde67e..d7de1edb 100644 --- a/upstream/debian-unstable/man1/machinectl.1 +++ b/upstream/debian-unstable/man1/machinectl.1 @@ -1,5 +1,5 @@ '\" t -.TH "MACHINECTL" "1" "" "systemd 255" "machinectl" +.TH "MACHINECTL" "1" "" "systemd 256~rc3" "machinectl" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -128,6 +128,10 @@ Similarly, block devices containing MBR or GPT partition tables and file systems .\} The file system tree of the host OS itself\&. .RE +.PP +Images may be downloaded, imported and exported via the +\fBimportctl\fR(1) +tool\&. .SH "COMMANDS" .PP The following commands are understood: @@ -299,7 +303,10 @@ Added in version 212\&. .PP \fBreboot\fR \fINAME\fR\&... .RS 4 -Reboot one or more containers\&. This will trigger a reboot by sending SIGINT to the container\*(Aqs 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\&. +Reboot one or more containers\&. This will trigger a reboot by sending SIGINT to the container\*(Aqs 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\&. Use +\fBrestart\fR +as alias for +\fBreboot\fR\&. .sp Added in version 209\&. .RE @@ -470,191 +477,47 @@ switch removes all images, not just hidden ones\&. This command effectively empt /var/lib/machines/\&. .sp Note that commands such as -\fBmachinectl pull\-tar\fR +\fBimportctl pull\-tar\fR or -\fBmachinectl pull\-raw\fR +\fBimportctl pull\-raw\fR usually create hidden, read\-only, unmodified machine images from the downloaded image first, before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are reused multiple times\&. Use \fBmachinectl clean\fR to remove old, hidden images created this way\&. .sp Added in version 230\&. .RE -.SS "Image Transfer Commands" -.PP -\fBpull\-tar\fR \fIURL\fR [\fINAME\fR] -.RS 4 -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, it is automatically derived from the last component of the URL, with its suffix removed\&. -.sp -The image is verified before it is made available, unless -\fB\-\-verify=no\fR -is specified\&. Verification is done either via an inline signed file with the name of the image and the suffix -\&.sha256 -or via separate -SHA256SUMS -and -SHA256SUMS\&.gpg -files\&. The signature files need to be made available on the same web server, under the same URL as the -\&.tar -file\&. With -\fB\-\-verify=checksum\fR, only the SHA256 checksum for the file is verified, based on the -\&.sha256 -suffixed file or the -SHA256SUMS -file\&. With -\fB\-\-verify=signature\fR, the sha checksum file is first verified with the inline signature in the -\&.sha256 -file or the 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\&. -.sp -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 behavior 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\&. -.sp -Note that the read\-only subvolume is prefixed with -\&.tar\-, and is thus not shown by -\fBlist\-images\fR, unless -\fB\-\-all\fR -is passed\&. -.sp -Note that pressing C\-c during execution of this command will not abort the download\&. Use -\fBcancel\-transfer\fR, described below\&. -.sp -Added in version 219\&. -.RE -.PP -\fBpull\-raw\fR \fIURL\fR [\fINAME\fR] -.RS 4 -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, it is automatically derived from the last component of the URL, with its suffix removed\&. -.sp -Image verification is identical for raw and tar images (see above)\&. -.sp -If the downloaded image is in -\&.qcow2 -format it is converted into a raw image file before it is made available\&. -.sp -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\&. -.sp -Similarly to the behavior of -\fBpull\-tar\fR, the read\-only image is prefixed with -\&.raw\-, and thus not shown by -\fBlist\-images\fR, unless -\fB\-\-all\fR -is passed\&. -.sp -Note that pressing C\-c during execution of this command will not abort the download\&. Use -\fBcancel\-transfer\fR, described below\&. -.sp -Added in version 219\&. -.RE -.PP -\fBimport\-tar\fR \fIFILE\fR [\fINAME\fR], \fBimport\-raw\fR \fIFILE\fR [\fINAME\fR] -.RS 4 -Imports a TAR or RAW container or VM image, and places it under the specified name in -/var/lib/machines/\&. When -\fBimport\-tar\fR -is used, the file specified as the first argument should be a tar archive, possibly compressed with xz, gzip or bzip2\&. It will then be unpacked into its own subvolume in -/var/lib/machines/\&. When -\fBimport\-raw\fR -is used, the file should be a qcow2 or raw disk image, possibly compressed with xz, gzip or bzip2\&. If the second argument (the resulting image name) is not specified, it is automatically derived from the file name\&. If the filename is passed as -"\-", the image is read from standard input, in which case the second argument is mandatory\&. -.sp -Optionally, the -\fB\-\-read\-only\fR -switch may be used to create a read\-only container or VM image\&. No cryptographic validation is done when importing the images\&. -.sp -Much like image downloads, ongoing imports may be listed with -\fBlist\-transfers\fR -and aborted with -\fBcancel\-transfer\fR\&. -.sp -Added in version 220\&. -.RE -.PP -\fBimport\-fs\fR \fIDIRECTORY\fR [\fINAME\fR] -.RS 4 -Imports a container image stored in a local directory into -/var/lib/machines/, operates similarly to -\fBimport\-tar\fR -or -\fBimport\-raw\fR, but the first argument is the source directory\&. If supported, this command will create a btrfs snapshot or subvolume for the new image\&. -.sp -Added in version 240\&. -.RE +.SH "OPTIONS" .PP -\fBexport\-tar\fR \fINAME\fR [\fIFILE\fR], \fBexport\-raw\fR \fINAME\fR [\fIFILE\fR] -.RS 4 -Exports a TAR or RAW container or VM image and stores it in the specified file\&. The first parameter should be a VM or container image name\&. The second parameter should be a file path the TAR or RAW image is written to\&. If the path ends in -"\&.gz", the file is compressed with gzip, if it ends in -"\&.xz", with xz, and if it ends in -"\&.bz2", with bzip2\&. If the path ends in neither, the file is left uncompressed\&. If the second argument is missing, the image is written to standard output\&. The compression may also be explicitly selected with the -\fB\-\-format=\fR -switch\&. This is in particular useful if the second parameter is left unspecified\&. -.sp -Much like image downloads and imports, ongoing exports may be listed with -\fBlist\-transfers\fR -and aborted with -\fBcancel\-transfer\fR\&. -.sp -Note that, currently, only directory and subvolume images may be exported as TAR images, and only raw disk images as RAW images\&. -.sp -Added in version 220\&. -.RE +The following options are understood: .PP -\fBlist\-transfers\fR +\fB\-p\fR, \fB\-\-property=\fR .RS 4 -Shows a list of container or VM image downloads, imports and exports that are currently in progress\&. +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\&. .sp -Added in version 219\&. +Added in version 206\&. .RE .PP -\fBcancel\-transfer\fR \fIID\fR\&... +\fB\-\-value\fR .RS 4 -Aborts a download, import or export of the container or VM image with the specified ID\&. To list ongoing transfers and their IDs, use -\fBlist\-transfers\fR\&. +When printing properties with +\fBshow\fR, only print the value, and skip the property name and +"="\&. .sp -Added in version 219\&. +Added in version 230\&. .RE -.SH "OPTIONS" -.PP -The following options are understood: .PP -\fB\-p\fR, \fB\-\-property=\fR +\fB\-P\fR .RS 4 -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\&. +Equivalent to +\fB\-\-value\fR +\fB\-\-property=\fR, i\&.e\&. shows the value of the property without the property name or +"="\&. Note that using +\fB\-P\fR +once will also affect all properties listed with +\fB\-p\fR/\fB\-\-property=\fR\&. .sp -Added in version 206\&. +Added in version 256\&. .RE .PP \fB\-a\fR, \fB\-\-all\fR @@ -668,15 +531,6 @@ When cleaning VM or container images, remove all images, not just hidden ones\&. Added in version 206\&. .RE .PP -\fB\-\-value\fR -.RS 4 -When printing properties with -\fBshow\fR, only print the value, and skip the property name and -"="\&. -.sp -Added in version 230\&. -.RE -.PP \fB\-l\fR, \fB\-\-full\fR .RS 4 Do not ellipsize process tree entries or table\&. This implies @@ -760,10 +614,7 @@ When used with \fBbind\fR, creates a read\-only bind mount\&. .sp When used with -\fBclone\fR, -\fBimport\-raw\fR -or -\fBimport\-tar\fR +\fBclone\fR a read\-only container or VM image is created\&. .sp Added in version 219\&. @@ -787,23 +638,25 @@ When used with Added in version 219\&. .RE .PP -\fB\-\-verify=\fR +\fB\-\-runner=\fR\fBnspawn\fR|\fBvmspawn\fR .RS 4 -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 the transfer is complete, but no signatures are verified\&. If -"signature" -is specified, the checksum is verified and the image\*(Aqs 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 operating on machines choose whether to use +\fBsystemd-nspawn\fR(1) +or +\fBsystemd-vmspawn\fR(1)\&. By default +\fBsystemd-nspawn\fR(1) +is used\&. .sp -Added in version 219\&. +Added in version 256\&. +.RE +.PP +\fB\-V\fR +.RS 4 +\fB\-V\fR +is a shorthand for +\fB\-\-runner=vmspawn\fR\&. +.sp +Added in version 256\&. .RE .PP \fB\-\-now\fR @@ -818,26 +671,11 @@ Added in version 253\&. .PP \fB\-\-force\fR .RS 4 -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\&. +Replace target file when copying files\&. .sp Added in version 219\&. .RE .PP -\fB\-\-format=\fR -.RS 4 -When used with the -\fBexport\-tar\fR -or -\fBexport\-raw\fR -commands, specifies the compression format to use for the resulting file\&. Takes one of -"uncompressed", -"xz", -"gzip", -"bzip2"\&. By default, the format is determined automatically from the image file name passed\&. -.sp -Added in version 220\&. -.RE -.PP \fB\-\-max\-addresses=\fR .RS 4 When used with the @@ -990,39 +828,18 @@ and options\&. .SH "EXAMPLES" .PP -\fBExample\ \&1.\ \&Download a Ubuntu image and open a shell in it\fR +\fBExample\ \&1.\ \&Download an Ubuntu RAW image, set a root password in it, start it as a service\fR .sp .if n \{\ .RS 4 .\} .nf -# 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 -.fi -.if n \{\ -.RE -.\} -.PP -This downloads and verifies the specified -\&.tar -image, and then uses -\fBsystemd-nspawn\fR(1) -to open a shell in it\&. -.PP -\fBExample\ \&2.\ \&Download a Fedora image, set a root password in it, start it as a service\fR -.sp -.if n \{\ -.RS 4 -.\} -.nf -# machinectl pull\-raw \-\-verify=no \e - https://download\&.fedoraproject\&.org/pub/fedora/linux/releases/38/Cloud/x86_64/images/Fedora\-Cloud\-Base\-38\-1\&.6\&.x86_64\&.raw\&.xz \e - Fedora\-Cloud\-Base\-38\-1\&.6\&.x86\-64 -# systemd\-nspawn \-M Fedora\-Cloud\-Base\-38\-1\&.6\&.x86\-64 -# passwd -# exit -# machinectl start Fedora\-Cloud\-Base\-38\-1\&.6\&.x86\-64 -# machinectl login Fedora\-Cloud\-Base\-38\-1\&.6\&.x86\-64 +# importctl pull\-raw \-mN \e + https://cloud\-images\&.ubuntu\&.com/jammy/current/jammy\-server\-cloudimg\-amd64\-disk\-kvm\&.img \e + jammy +# systemd\-firstboot \-\-image=/var/lib/machines/jammy\&.raw \-\-prompt\-root\-password \-\-force +# machinectl start jammy +# machinectl login jammy .fi .if n \{\ .RE @@ -1030,41 +847,9 @@ to open a shell in it\&. .PP 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\&. -.PP -\fBExample\ \&3.\ \&Exports a container image as tar file\fR -.sp -.if n \{\ -.RS 4 -.\} -.nf -# machinectl export\-tar fedora myfedora\&.tar\&.xz -.fi -.if n \{\ -.RE -.\} -.PP -Exports the container -"fedora" -as an xz\-compressed tar file -myfedora\&.tar\&.xz -into the current directory\&. -.PP -\fBExample\ \&4.\ \&Create a new shell session\fR -.sp -.if n \{\ -.RS 4 -.\} -.nf -# machinectl shell \-\-uid=lennart -.fi -.if n \{\ -.RE -.\} -.PP -This creates a new shell session on the local host for the user ID -"lennart", in a -\fBsu\fR(1)\-like fashion\&. +image and makes it available under the local name +"jammy"\&. Then, a root password is set with +\fBsystemd-firstboot\fR(1)\&. Afterwards the machine is started as system service\&. With the last command a login prompt into the container is requested\&. .SH "EXIT STATUS" .PP On success, 0 is returned, a non\-zero failure code otherwise\&. @@ -1072,7 +857,7 @@ On success, 0 is returned, a non\-zero failure code otherwise\&. .PP \fI$SYSTEMD_LOG_LEVEL\fR .RS 4 -The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Either one of (in order of decreasing importance) +The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Takes a comma\-separated list of values\&. A value may be either one of (in order of decreasing importance) \fBemerg\fR, \fBalert\fR, \fBcrit\fR, @@ -1082,7 +867,15 @@ The maximum log level of emitted messages (messages with a higher log level, i\& \fBinfo\fR, \fBdebug\fR, or an integer in the range 0\&...7\&. See \fBsyslog\fR(3) -for more information\&. +for more information\&. Each value may optionally be prefixed with one of +\fBconsole\fR, +\fBsyslog\fR, +\fBkmsg\fR +or +\fBjournal\fR +followed by a colon to set the maximum log level for that specific log target (e\&.g\&. +\fBSYSTEMD_LOG_LEVEL=debug,console:info\fR +specifies to log at debug level except when logging to the console which should be at info level)\&. Note that the global maximum log level takes priority over any per target maximum log levels\&. .RE .PP \fI$SYSTEMD_LOG_COLOR\fR @@ -1201,6 +994,12 @@ will be ignored by the executable, and needs to be handled by the pager\&. This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal\&. It is set by default to allow command output to remain visible in the terminal even after the pager exits\&. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse\&. .RE .sp +Note that setting the regular +\fI$LESS\fR +environment variable has no effect for +\fBless\fR +invocations by systemd tools\&. +.sp See \fBless\fR(1) for more discussion\&. @@ -1212,6 +1011,12 @@ Override the charset passed to \fBless\fR (by default "utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&. +.sp +Note that setting the regular +\fI$LESSCHARSET\fR +environment variable has no effect for +\fBless\fR +invocations by systemd tools\&. .RE .PP \fI$SYSTEMD_PAGERSECURE\fR @@ -1267,11 +1072,4 @@ and other conditions\&. .RE .SH "SEE ALSO" .PP -\fBsystemd\fR(1), -\fBsystemd-machined.service\fR(8), -\fBsystemd-nspawn\fR(1), -\fBsystemd.special\fR(7), -\fBtar\fR(1), -\fBxz\fR(1), -\fBgzip\fR(1), -\fBbzip2\fR(1) +\fBsystemd\fR(1), \fBsystemd-machined.service\fR(8), \fBsystemd-nspawn\fR(1), \fBsystemd.special\fR(7), \fBimportctl\fR(1), \fBtar\fR(1), \fBxz\fR(1), \fBgzip\fR(1), \fBbzip2\fR(1) |