From 78e9bb837c258ac0ec7712b3d612cc2f407e731e Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 12 Jun 2024 05:50:42 +0200 Subject: Merging upstream version 256. Signed-off-by: Daniel Baumann --- man/machinectl.xml | 360 +++++++++-------------------------------------------- 1 file changed, 56 insertions(+), 304 deletions(-) (limited to 'man/machinectl.xml') diff --git a/man/machinectl.xml b/man/machinectl.xml index 1afd431..3964dc0 100644 --- a/man/machinectl.xml +++ b/man/machinectl.xml @@ -1,6 +1,6 @@ %entities; ]> @@ -80,6 +80,9 @@ The file system tree of the host OS itself. + Images may be downloaded, imported and exported via the + importctl1 + tool. @@ -87,8 +90,9 @@ The following commands are understood: - Machine Commands + Machine Commands + list @@ -279,7 +283,8 @@ 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. + containers running any system manager. Use restart as alias + for reboot. @@ -360,8 +365,9 @@ - Image Commands + Image Commands + list-images @@ -514,7 +520,7 @@ When combined with the switch removes all images, not just hidden ones. This command effectively empties /var/lib/machines/. - Note that commands such as machinectl pull-tar or machinectl + Note that commands such as importctl pull-tar or importctl pull-raw 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 machinectl clean to remove old, hidden images created this @@ -524,197 +530,6 @@ - - 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, 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 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 , only the SHA256 checksum - for the file is verified, based on the .sha256 - suffixed file or the SHA256SUMS file. - With , 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. - - 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. - - Note that the read-only subvolume is prefixed with - .tar-, and is thus not 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, 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 downloaded image is in - .qcow2 format it is 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. - - Similarly to the behavior of pull-tar, the read-only image is prefixed with - .raw-, and thus not 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. - - - - - - import-tar FILE [NAME] - import-raw FILE [NAME] - Imports a TAR or RAW container or VM image, - and places it under the specified name in - /var/lib/machines/. When - import-tar 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 - import-raw 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. - - Optionally, the switch may be used to create a read-only container or VM - image. No cryptographic validation is done when importing the images. - - Much like image downloads, ongoing imports may be listed - with list-transfers and aborted with - cancel-transfer. - - - - - - import-fs DIRECTORY [NAME] - - Imports a container image stored in a local directory into - /var/lib/machines/, operates similarly to import-tar or - import-raw, but the first argument is the source directory. If supported, this - command will create a btrfs snapshot or subvolume for the new image. - - - - - - export-tar NAME [FILE] - export-raw NAME [FILE] - 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 - switch. This is in particular - useful if the second parameter is left unspecified. - - Much like image downloads and imports, ongoing exports - may be listed with list-transfers and - aborted with - cancel-transfer. - - Note that, currently, only directory and subvolume images - may be exported as TAR images, and only raw disk images as RAW - images. - - - - - - list-transfers - - Shows a list of container or VM image - downloads, imports and exports that are currently in - progress. - - - - - - cancel-transfer ID… - - Aborts a download, import or export of the - container or VM image with the specified ID. To list ongoing - transfers and their IDs, use - list-transfers. - - - - - - @@ -738,6 +553,17 @@ + + + + When printing properties with show, only print the value, + and skip the property name and =. + + + + + + @@ -755,15 +581,6 @@ - - - - When printing properties with show, only print the value, - and skip the property name and =. - - - - @@ -833,8 +650,7 @@ When used with bind, creates a read-only bind mount. - When used with clone, import-raw or import-tar a - read-only container or VM image is created. + When used with clone a read-only container or VM image is created. @@ -866,24 +682,26 @@ - - - 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'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 operating on machines choose whether to use + systemd-nspawn1 + or + systemd-vmspawn1. + By default + systemd-nspawn1 + is used. + + + + + + + + + is a shorthand for . + + @@ -902,28 +720,11 @@ - 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. - - - - When used with the - or 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. - - - - @@ -1045,58 +846,8 @@ Examples - - Download a 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 a service - - # machinectl pull-raw --verify=no \ - https://download.fedoraproject.org/pub/fedora/linux/releases/&fedora_latest_version;/Cloud/x86_64/images/Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86_64.raw.xz \ - Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86-64 -# systemd-nspawn -M Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86-64 -# passwd -# exit -# machinectl start Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86-64 -# machinectl login Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86-64 - - 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. - - - - Exports a container image as tar file - - # machinectl export-tar fedora myfedora.tar.xz - - Exports the container fedora as an - xz-compressed tar file myfedora.tar.xz into the - current directory. - - - - Create a new shell session - - # machinectl shell --uid=lennart - - This creates a new shell session on the local host for - the user ID lennart, in a su1-like - fashion. - + + @@ -1111,16 +862,17 @@ See Also - - systemd1, - systemd-machined.service8, - systemd-nspawn1, - systemd.special7, - tar1, - xz1, - gzip1, - bzip21 - + + systemd1 + systemd-machined.service8 + systemd-nspawn1 + systemd.special7 + importctl1 + tar1 + xz1 + gzip1 + bzip21 + -- cgit v1.2.3