From: Lennart Poettering Date: Tue, 27 Feb 2024 08:39:57 +0000 (+0100) Subject: man: document new importctl/importd functionality X-Git-Tag: v256-rc1~671^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fd571c9df0ba86636401582c4ea0a8cb608e1216;p=thirdparty%2Fsystemd.git man: document new importctl/importd functionality This also replaces the Fedora download example with another one from Ubuntu, since Fedora's images these days no longer qualify as DDIs, they have no distinctive partition type UUIDs set for multiple of their partitions, hence the images cannot be booted. A bit sad. Let's provide a command that just works in its place. --- diff --git a/man/importctl.xml b/man/importctl.xml new file mode 100644 index 00000000000..25c49fc5dc9 --- /dev/null +++ b/man/importctl.xml @@ -0,0 +1,442 @@ + + +%entities; +]> + + + + + + importctl + systemd + + + + importctl + 1 + + + + importctl + Download, import or export disk images + + + + + importctl + OPTIONS + COMMAND + NAME + + + + + Description + + importctl may be used to download, import export disk images via + systemd-importd.service8. + + importctl operates both on block-level disk images (such as DDIs) as well as + file-system-level images (tarballs). It supports disk images are one of the four following + classes: + + + VM images or full OS container images, that may be run via + systemd-vmspawn1 or + systemd-nspawn1, and + managed via + machinectl1. + + Portable service images, that may be attached an managed via + portablectl1. + + System extension (sysext) images, that may be activated via + systemd-sysext8. + + Configuration extension (confext) images, that may be activated via + systemd-confext8. + + + When images are downloaded or imported they are placed in the following directories, depending on + the parameter: + + + Classes and Directories + + + + + + Class + Directory + + + + + machine + /var/lib/machines/ + + + portable + /var/lib/portables/ + + + sysext + /var/lib/extensions/ + + + confext + /var/lib/confexts/ + + + +
+ + + + Commands + + The following commands are understood: + + + + pull-tar URL [NAME] + + Downloads a .tar image from the specified URL, and makes it + available under the specified local name in the image directory for the selected + . 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 image 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. + + If is specified the image will be downloaded and stored in + a read-only subvolume/directory in the image directory 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 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 name. + + 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 disk image from the specified URL, and makes it + available under the specified local name in the image directory for the selected + . The URL must be of type http:// or + https://. The image must either be a .qcow2 or raw disk + image, optionally compressed as .gz, .xz, or + .bz2. If the local 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. + + If is specified the image will be downloaded and stored in + a read-only file in the image directory that is named after the specified URL and its HTTP etag. A + writable copy is then made from this file, and named after the specified local name. This behavior + ensures that creating multiple 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 copy, + specify - as local name. + + 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 image, and places it under the specified name in the image + directory for the image class selected via . 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/directory. 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. + + No cryptographic validation is done when importing the images. + + Much like image downloads, ongoing imports may be listed with list + and aborted with cancel-transfer. + + + + + + import-fs DIRECTORY [NAME] + + Imports an image stored in a local directory into the image directory for the image + class selected via and 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 image and stores it in the specified file. The first parameter + should be an 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 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-transfer + + Shows a list of image downloads, imports and exports that are currently in + progress. + + + + + + cancel-transfer ID… + + Aborts a download, import or export of the image with the specified ID. To list + ongoing transfers and their IDs, use list. + + + + + + list-images + + Shows a list of already downloaded/imported images. + + + + + + + + + Options + + The following options are understood: + + + + + + + When used with pull-raw, pull-tar, + import-raw, import-tar or import-fs a + read-only image is created. + + + + + + + + + When downloading an 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 downloading an image, and a local copy by the specified local name already + exists, delete it first and replace it by the newly downloaded image. + + + + + + + + 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 output image + file name passed. + + + + + + + + + Suppresses additional informational output while running. + + + + + + + + + + + Connect to + systemd-import.service8 + running in a local container, to perform the specified operation within the container. + + + + + + + + + + + + Selects the image class for the downloaded images. This primarily selects the + directory to download into. The switch takes machine, + portable, sysext or confext as argument. The + short options , , , are + shortcuts for , , + , . + + Note that defaults to true for + and false otherwise, see below. + + + + + + + + + Takes a boolean argument. When specified with pull-raw or + pull-tar, selects whether to download directly into the specified local image + name, or whether to download into a read-only copy first of which to make a writable copy after the + download is completed. Defaults to true for , false otherwise. + + The switch is a shortcut for . + + + + + + + + + + + + + + + Examples + + Download an Ubuntu TAR image and open a shell in it + + # importctl pull-tar -mN https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64-root.tar.xz +# systemd-nspawn -M jammy-server-cloudimg-amd64-root + + This downloads and verifies the specified .tar image, and then uses + systemd-nspawn1 to + open a shell in it. + + + + Download an Ubuntu RAW image, set a root password in it, start + it as a service + + # importctl pull-raw -mN \ + https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64-disk-kvm.img \ + jammy +# systemd-firstboot --image=/var/lib/machines/jammy.raw --prompt-root-password --force +# machinectl start jammy +# machinectl login jammy + + This downloads the specified .raw image and makes it available under the + local name jammy. Then, a root password is set with + systemd-firstboot1. Afterwards + the machine is started as system service. With the last command a login prompt into the container is + requested. + + + + Exports a container image as tar file + + # importctl export-tar -m fedora myfedora.tar.xz + + Exports the container fedora as an xz-compressed tar file + myfedora.tar.xz into the current directory. + + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + + + See Also + + systemd1 + systemd-importd.service8 + systemd-nspawn1 + systemd-vmspawn1 + machinectl1 + portablectl1 + systemd-sysext8 + systemd-confext8 + tar1 + xz1 + gzip1 + bzip21 + + + + diff --git a/man/machinectl.xml b/man/machinectl.xml index a4d53175433..319942207bf 100644 --- a/man/machinectl.xml +++ b/man/machinectl.xml @@ -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 @@ -361,8 +365,9 @@ - Image Commands + Image Commands + list-images @@ -515,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 @@ -525,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. - - - - - - @@ -834,8 +648,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,27 +679,6 @@ - - - - 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. - - - - | @@ -926,28 +718,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. - - - - @@ -1069,58 +844,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. - + + @@ -1140,6 +865,7 @@ systemd-machined.service8 systemd-nspawn1 systemd.special7 + importctl1 tar1 xz1 gzip1 diff --git a/man/org.freedesktop.import1.xml b/man/org.freedesktop.import1.xml index e230a69f4cc..2486eea4b38 100644 --- a/man/org.freedesktop.import1.xml +++ b/man/org.freedesktop.import1.xml @@ -25,11 +25,11 @@ systemd-importd.service8 - is a system service which may be used to import, export and download additional system images. These - images can be used by tools such as - systemd-nspawn1 - to run local containers. The service is used as the backend for machinectl pull-raw, - machinectl pull-tar and related commands. This page describes the D-Bus interface. + is a system service which may be used to import, export and download disk images. These images can be + used by tools such as + systemd-nspawn1 to run + local containers. The service is used as the backend for importctl pull-raw, + importctl pull-tar and related commands. This page describes the D-Bus interface. Note that @@ -56,42 +56,94 @@ node /org/freedesktop/import1 { in b read_only, out u transfer_id, out o transfer_path); + ImportTarEx(in h fd, + in s local_name, + in s class, + in t flags, + out u transfer_id, + out o transfer_path); ImportRaw(in h fd, in s local_name, in b force, in b read_only, out u transfer_id, out o transfer_path); + ImportRawEx(in h fd, + in s local_name, + in s class, + in t flags, + out u transfer_id, + out o transfer_path); ImportFileSystem(in h fd, in s local_name, in b force, in b read_only, out u transfer_id, out o transfer_path); + ImportFileSystemEx(in h fd, + in s local_name, + in s class, + in t flags, + out u transfer_id, + out o transfer_path); ExportTar(in s local_name, in h fd, in s format, out u transfer_id, out o transfer_path); + ExportTarEx(in s local_name, + in s class, + in h fd, + in s format, + in t flags, + out u transfer_id, + out o transfer_path); ExportRaw(in s local_name, in h fd, in s format, out u transfer_id, out o transfer_path); + ExportRawEx(in s local_name, + in s class, + in h fd, + in s format, + in t flags, + out u transfer_id, + out o transfer_path); PullTar(in s url, in s local_name, in s verify_mode, in b force, out u transfer_id, out o transfer_path); + PullTarEx(in s url, + in s local_name, + in s class, + in s verify_mode, + in t flags, + out u transfer_id, + out o transfer_path); PullRaw(in s url, in s local_name, in s verify_mode, in b force, out u transfer_id, out o transfer_path); + PullRawEx(in s url, + in s local_name, + in s class, + in s verify_mode, + in t flags, + out u transfer_id, + out o transfer_path); ListTransfers(out a(usssdo) transfers); + ListTransfersEx(in s class, + in t flags, + out a(ussssdo) transfers); CancelTransfer(in u transfer_id); + ListImages(in s class, + in t flags, + out a(ssssbtttttt) images); signals: TransferNew(u transfer_id, o transfer_path); @@ -105,8 +157,6 @@ node /org/freedesktop/import1 { }; - - @@ -115,22 +165,40 @@ node /org/freedesktop/import1 { + + + + + + + + + + + + + + + + + + @@ -140,81 +208,114 @@ node /org/freedesktop/import1 { Methods - ImportTar() and ImportRaw() import a system image and - place it into /var/lib/machines/. The first argument should be a file descriptor - (opened for reading) referring to the tar or raw file to import. It should reference a file on disk, - a pipe or a socket. When ImportTar() is used the file descriptor should - refer to a tar file, optionally compressed with - gzip1, - bzip21, - or + ImportTar()/ImportTarEx() and + ImportRaw()/ImportRawEx() import a disk image and place it + into the image directory. The first argument should be a file descriptor (opened for reading) referring + to the tar or raw file to import. It should reference a file on disk, a pipe or a socket. When + ImportTar()/ImportTarEx() is used the file descriptor should + refer to a tar file, optionally compressed with gzip1, + bzip21, or xz1. systemd-importd will detect the used compression scheme (if any) automatically. When - ImportRaw() is used the file descriptor should refer to a raw or qcow2 disk image - containing an MBR or GPT disk label, also optionally compressed with gzip, bzip2 or xz. In either case, - if the file is specified as a file descriptor on disk, progress information is generated for the import - operation (as in that case we know the total size on disk). If a socket or pipe is specified, progress information is not - available. The file descriptor argument is followed by a local name for the image. This should be a - name suitable as a hostname and will be used to name the imported image below - /var/lib/machines/. A tar import is placed as a directory tree or a - btrfs8 - subvolume below /var/lib/machines/ under the specified name with no suffix - appended. A raw import is placed as a file in /var/lib/machines/ with the - .raw suffix appended. If the argument is true, any - pre-existing image with the same name is removed before starting the operation. Otherwise, the - operation fails if an image with the same name already exists. Finally, the - argument controls - whether to create a writable or read-only image. Both methods return immediately after starting the import, - with the import transfer ongoing. They return a pair of transfer identifier and object path, which may - be used to retrieve progress information about the transfer or to cancel it. The transfer identifier is a - simple numeric identifier, the object path references an + ImportRaw()/ImportRawEx() is used the file descriptor should + refer to a raw or qcow2 disk image containing an MBR or GPT disk label, also optionally compressed with + gzip, bzip2 or xz. In either case, if the file is specified as a file descriptor on disk, progress + information is generated for the import operation (as in that case we know the total size on disk). If + a socket or pipe is specified, progress information is not available. The file descriptor argument is + followed by a local name for the image. This should be a name suitable as a hostname and will be used + to name the imported image below /var/lib/machines/. A tar import is placed as a + directory tree or a btrfs8 + subvolume below the image directory under the specified name with no suffix appended. A raw import is + placed as a file in the image directory with the .raw suffix appended. In case of + ImportTar()/ImportRaw(), if the + argument is true, any pre-existing image with the same name is removed before starting the + operation. Otherwise, the operation fails if an image with the same name already exists. The + argument controls whether to create a writable or read-only image. In case + of ImportTarEx()/ImportRawEx() these boolean flags are + provided via a 64bit flags parameter instead, with bit 0 mapping to the + parameter, and bit 1 mapping to . The parameter + specifies the image class, and takes one of machine, portable, + sysext, confext. All four methods return immediately after + starting the import, with the import transfer ongoing. They return a pair of transfer identifier and + object path, which may be used to retrieve progress information about the transfer or to cancel it. The + transfer identifier is a simple numeric identifier, the object path references an org.freedesktop.import1.Transfer object, see below. Listen for a TransferRemoved() signal for the transfer ID in order to detect when a transfer is complete. The returned transfer object is useful to determine the current progress or log output of the ongoing import operation. - ExportTar() and ExportRaw() implement the reverse - operation, and may be used to export a system image in order to place it in a tar or raw image. They - take the machine name to export as their first parameter, followed by a file descriptor (opened for writing) - where the tar or raw file will be written. It may either reference a file on disk or a pipe/socket. The - third argument specifies in which compression format to write the image. It takes one of + ExportTar()/ExportTarEx() and + ExportRaw()/ExportRaw() implement the reverse operation, and + may be used to export a system image in order to place it in a tar or raw image. They take the machine + name to export as their first parameter, followed by a file descriptor (opened for writing) where the + tar or raw file will be written. It may either reference a file on disk or a pipe/socket. The third + argument specifies in which compression format to write the image. It takes one of uncompressed, xz, bzip2 or gzip, depending on which compression scheme is required. The image written to the - specified file descriptor will be a tar file in case of ExportTar() or a raw disk - image in case of ExportRaw(). Note that currently raw disk images may not be - exported as tar files, and vice versa. This restriction might be lifted eventually. The method - returns a transfer identifier and object path for cancelling or tracking the export operation, similarly - to ImportTar() or ImportRaw() as described above. - - PullTar() and PullRaw() may be used to download, verify - and import a system image from a URL. They take a URL argument which should point to a tar or - raw file on the http:// or https:// protocols, possibly - compressed with xz, bzip2 or gzip. The second argument is a local name for the image. It should be - suitable as a hostname, similarly to the matching argument of the ImportTar() and - ImportRaw() methods above. The third argument indicates the verification mode for - the image. It may be one of no, checksum, - signature. no turns off any kind of verification of the image; - checksum looks for a SHA256SUM file next to the downloaded - image and verifies any SHA256 hash value in that file against the image; signature - does the same but also tries to authenticate the SHA256SUM file via - gpg8 - first. The last argument indicates whether to replace a possibly pre-existing image with the same local - name (if true), or whether to fail (if false). Like the import - and export calls above, these calls return a pair of transfer identifier and object path for the ongoing + specified file descriptor will be a tar file in case of + ExportTar()/ExportTarEx() or a raw disk image in case of + ExportRaw()/ExportRawEx(). Note that currently raw disk + images may not be exported as tar files, and vice versa. This restriction might be lifted + eventually. The method returns a transfer identifier and object path for cancelling or tracking the + export operation, similarly to ImportTar()/ImportTarEx() or + ImportRaw()/ImportRawEx() as described + above. ExportTarEx()/ExportRawEx() expect the image class as + additional parameter, as well as a 64bit flags parameter that currently must be specified as + zero. + + PullTar()/PullTarEx() and + PullRaw()/PullRawEx() may be used to download, verify and + import a system image from a URL. They take a URL argument which should point to a tar or raw file on + the http:// or https:// protocols, possibly compressed with xz, + bzip2 or gzip. The second argument is a local name for the image. It should be suitable as a hostname, + similarly to the matching argument of the + ImportTar()/ImportTarEx() and + ImportRaw()/ImportRawEx() methods above. The third argument + indicates the verification mode for the image. It may be one of no, + checksum, signature. no turns off any kind of + verification of the image; checksum looks for a SHA256SUM file + next to the downloaded image and verifies any SHA256 hash value in that file against the image; + signature does the same but also tries to authenticate the + SHA256SUM file via gpg8 first. In + case of PullTar()/PullRaw() the last argument indicates + whether to replace a possibly pre-existing image with the same local name (if true), + or whether to fail (if false). In case of + PullTarEx()/PullRawEx() the last argument is a 64bit flags + parameter, where bit 0 controls the force flag, bit 1 is a + read_only flag that controls whether the created image shall be marked read-only, + and bit 2 is a keep_download flag that indicates whether a pristine, read-only copy + of the downloaded image shell be kept, in addition for the local copy of the image. The + …_Ex() variants also expect an image class string (as above). Like the import and + export calls above, these calls return a pair of transfer identifier and object path for the ongoing download. - ListTransfers() returns a list of ongoing import, export or download - operations as created with the six calls described above. It returns an array of structures which - consist of the numeric transfer identifier, a string indicating the operation (one of - import-tar, import-raw, export-tar, - export-raw, pull-tar or pull-raw), a string - describing the remote file (in case of download operations this is the source URL, in case of - import/export operations this is a short string describing the file descriptor passed in), a string - with the local machine image name, a progress value between 0.0 (for 0%) and 1.0 (for 100%), as well as - the transfer object path. + ImportFileSystem()/ImportFileSystemEx() are similar to + ImportTar()/ImportTarEx() but import a directory tree. The + first argument must refer to a directory file descriptor for the source hierarchy to import. + + ListTransfers()/ListTransfersEx() return a list of + ongoing import, export or download operations as created with the six calls described above. They + return an array of structures which consist of the numeric transfer identifier, a string indicating the + operation (one of import-tar, import-raw, + export-tar, export-raw, pull-tar or + pull-raw), a string describing the remote file (in case of download operations this + is the source URL, in case of import/export operations this is a short string describing the file + descriptor passed in), a string with the local machine image name, the image class (only in case of + ListTransfersEx(); one of machine, portable, + sysext, confext), a progress value between 0.0 (for 0%) and 1.0 + (for 100%), as well as the transfer object path. CancelTransfer() may be used to cancel an ongoing import, export or download operation. Simply specify the transfer identifier to cancel the ongoing operation. + + ListImages() returns a list of currently installed images. It takes a image + class string and a flags parameter. The image class is either the empty string or specifies one of the + four image classes, by which it will then filter. The flags parameter must be zero at this time. It + returns an array of items, each describing one image. The item fields are in order: the image class, + the local image name, the image type, the image path, the read-only flag, the creation and modification + times (in microseconds since the UNIX epoch), as well as the current disk usage in bytes (both overall, + and exclusive), as well as any size limit in bytes set on the image (both overall and + exclusive). @@ -242,6 +343,7 @@ node /org/freedesktop/import1/transfer/_1 { signals: LogMessage(u priority, s line); + ProgressUpdate(d progress); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u Id = ...; @@ -262,8 +364,6 @@ node /org/freedesktop/import1/transfer/_1 { }; - - @@ -274,6 +374,8 @@ node /org/freedesktop/import1/transfer/_1 { + + @@ -315,6 +417,17 @@ node /org/freedesktop/import1/transfer/_1 { between 0.0 and 1.0. To show a progress bar on screen we recommend to query this value in regular intervals, for example every 500 ms or so. + + + Signals + + The LogMessage() signal is emitted for log messages generated by a transfer. It + carries a pair of syslog log level integer and log string. + + The ProgressUpdate() signal is emitted in regular intervals when new + download progress information is available for a transfer. It carries a double precision floating + pointer number between 0.0 and 1.0 indicating the transfer progress. + @@ -340,4 +453,20 @@ node /org/freedesktop/import1/transfer/_1 { + + History + + The Manager Object + ImportTarEx(), ImportRawEx(), + ImportFileSystemEx(), ExportTarEx(), + ExportRawEx(), PullTarEx(), PullRawEx(), + ListTransfersEx(), ListImages() were added in version + 256. + + + Transfer Objects + ProgressUpdate() was added in version 256. + + + diff --git a/man/portablectl.xml b/man/portablectl.xml index 12953bc1397..5223131368f 100644 --- a/man/portablectl.xml +++ b/man/portablectl.xml @@ -511,6 +511,7 @@ systemd-sysext8 org.freedesktop.portable15 systemd-portabled.service8 + importctl1 diff --git a/man/rules/meson.build b/man/rules/meson.build index 15de3fa576f..e6d714ba7d5 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -23,6 +23,7 @@ manpages = [ ['hostname', '5', [], ''], ['hostnamectl', '1', [], 'ENABLE_HOSTNAMED'], ['hwdb', '7', [], 'ENABLE_HWDB'], + ['importctl', '1', [], 'ENABLE_MACHINED'], ['integritytab', '5', [], 'HAVE_LIBCRYPTSETUP'], ['iocost.conf', '5', [], ''], ['journal-remote.conf', '5', ['journal-remote.conf.d'], 'HAVE_MICROHTTPD'], diff --git a/man/systemd-importd.service.xml b/man/systemd-importd.service.xml index 7e617cfc67a..dfeaff4fd77 100644 --- a/man/systemd-importd.service.xml +++ b/man/systemd-importd.service.xml @@ -29,12 +29,12 @@ Description - systemd-importd is a system service that allows importing, exporting and downloading of - system images suitable for running as VM or containers. It is a companion service for - systemd-machined.service8, and provides the implementation for - machinectl1's + systemd-importd is a system service that allows importing, exporting and + downloading of disk images. It provides the implementation for + importctl1's pull-raw, pull-tar, import-raw, - import-tar, import-fs, export-raw, and export-tar commands. + import-tar, import-fs, export-raw, and + export-tar commands. See org.freedesktop.import15 @@ -47,7 +47,7 @@ See Also systemd1 - machinectl1 + importctl1 systemd-machined.service8 systemd-nspawn1 diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index 29edbba4cc8..8f7e6d103d2 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -1800,19 +1800,7 @@ After=sys-subsystem-net-devices-ens1.device Examples - - Download a - <ulink url="https://getfedora.org">Fedora</ulink> image and start a shell in it - - # 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 - - This downloads an image using - machinectl1 - and opens a shell in it. - + Build and boot a minimal Fedora distribution in a container @@ -1921,6 +1909,7 @@ After=sys-subsystem-net-devices-ens1.device zypper8 systemd.slice5 machinectl1 + importctl1 btrfs8 diff --git a/man/systemd-sysext.xml b/man/systemd-sysext.xml index ea1af001a79..8e5a6a6aa1b 100644 --- a/man/systemd-sysext.xml +++ b/man/systemd-sysext.xml @@ -449,6 +449,7 @@ systemd1 systemd-nspawn1 systemd-stub7 + importctl1 diff --git a/man/systemd-vmspawn.xml b/man/systemd-vmspawn.xml index c9ad82b2f02..ef4d3ca2b62 100644 --- a/man/systemd-vmspawn.xml +++ b/man/systemd-vmspawn.xml @@ -485,6 +485,8 @@ $ systemd-vmspawn --image=image.raw systemd1 mkosi1 + machinectl1 + importctl1