# importctl

## NAME



           importctl - Download, import or export disk images
    


## SYNOPSIS



    
           **importctl**[OPTIONS...] {COMMAND} [NAME...]
    


## DESCRIPTION



           **importctl** may be used to download, import, and export disk images
           via systemd-importd.service(8).
    
           **importctl** operates both on block-level disk images (such as DDIs)
           as well as file-system-level images (tarballs). It supports disk
           images in one of the four following classes:
    
           •   VM images or full OS container images, that may be run via
               systemd-vmspawn(1) or systemd-nspawn(1), and managed via
               machinectl(1).
    
           •   Portable service images, that may be attached and managed via
               portablectl(1).
    
           •   System extension (sysext) images, that may be activated via
               systemd-sysext(8).
    
           •   Configuration extension (confext) images, that may be
               activated via systemd-confext(8).
    
           When images are downloaded or imported they are placed in the
           following directories, depending on the **--class=** parameter:
    
           **Table 1. 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 **--class=**. 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
               **--verify=no** is specified. Verification is done either via a
               file with the name of the image and the suffix .sha256 and a
               detached .sha256.asc or .sha256.gpg signature or via separate
               SHA256SUMS and SHA256SUMS.asc or 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
               **--verify=checksum** , only the SHA256 checksum for the file is
               verified, based on the .sha256 suffixed file or the SHA256SUMS
               file. With **--verify=signature** , the sha checksum file is first
               verified with the detached GPG signature of .sha256 or
               SHA256SUMS. The public key for this verification step needs to
               be available in /usr/lib/systemd/import-pubring.pgp or
               /etc/systemd/import-pubring.pgp.
    
               If **-keep-download=yes** 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 (see **HTTP ETag******[1] for more information). 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 Control-c during execution of this command
               will not abort the download. Use**cancel-transfer** , described
               below.
    
               Added in version 256.
    
           **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 **--class=**. 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 **-keep-download=yes** 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 Control-c during execution of this command
               will not abort the download. Use **cancel-transfer** , described
               below.
    
               Added in version 256.
    
           **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
               **--class=**. When **import-tar** is used, the file specified as the
               first argument should be a tar(1) archive, possibly compressed
               with **xz**(1), **gzip**(1), **zstd**(1), or **bzip2**(1). 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, zstd 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**.
    
               Added in version 256.
    
           **import-fs** _DIRECTORY_ [_NAME_]
               Imports an image stored in a local directory into the image
               directory for the image class selected via **--class=** 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(8) snapshot or subvolume for the new
               image.
    
               Added in version 256.
    
           **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**(1), if it ends in ".xz", with **xz**(1), if it ends in
               ".zst", with **zstd**(1), and if it ends in ".bz2", with **bzip2**(1).
               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 **--format=** 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.
    
               Added in version 256.
    
           **list-transfer**
               Shows a list of image downloads, imports and exports that are
               currently in progress.
    
               Added in version 256.
    
           **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**.
    
               Added in version 256.
    
           **list-images**
               Shows a list of already downloaded/imported images.
    
               Added in version 256.
    


## OPTIONS



           The following options are understood:
    
           **--read-only**
               When used with **pull-raw** , **pull-tar** , **import-raw** , **import-tar** or
               **import-fs** a read-only image is created.
    
               Added in version 256.
    
           **--verify=**
               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".
    
               Added in version 256.
    
           **--force**
               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.
    
               Added in version 256.
    
           **--format=**
               When used with the **export-tar** or **export-raw** commands,
               specifies the compression format to use for the resulting
               file. Takes one of "uncompressed", "xz", "gzip", "zst",
               "bzip2". By default, the format is determined automatically
               from the output image file name passed.
    
               Added in version 256.
    
           **-q** , **--quiet**
               Suppresses additional informational output while running.
    
               Added in version 256.
    
           **-H** , **--host=**
               Execute the operation remotely. Specify a hostname, or a
               username and hostname separated by "@", to connect to. The
               hostname may optionally be suffixed by a port ssh is listening
               on, separated by ":", and then a container name, separated by
               "/", which connects directly to a specific container on the
               specified host. This will use SSH to talk to the remote
               machine manager instance. Container names may be enumerated
               with **machinectl -H** _HOST_. Put IPv6 addresses in brackets.
    
           **-M** , **--machine=**
               Connect to **systemd-import.service**(8) running in a local
               container, to perform the specified operation within the
               container.
    
               Added in version 256.
    
           **--class=** , **-m** , **-P** , **-S** , **-C**
               Selects the image class for the downloaded images. This
               primarily selects the directory to download into. The **--class=**
               switch takes "machine", "portable", "sysext" or "confext" as
               argument. The short options **-m** , **-P** , **-S** , **-C** are shortcuts for
               **--class=machine** , **--class=portable** , **--class=sysext** ,
               **--class=confext**.
    
               Note that **--keep-download=** defaults to true for
               **--class=machine** and false otherwise, see below.
    
               Added in version 256.
    
           **--keep-download=** , **-N**
               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
               **--class=machine** , false otherwise.
    
               The **-N** switch is a shortcut for **--keep-download=no**.
    
               Added in version 256.
    
           **--json=**_MODE_
               Shows output formatted as JSON. Expects one of "short" (for
               the shortest possible output without any redundant whitespace
               or line breaks), "pretty" (for a pretty version of the same,
               with indentation and line breaks) or "off" (to turn off JSON
               output, the default).
    
           **-j**
               Equivalent to **--json=pretty** if running on a terminal, and
               **--json=short** otherwise.
    
           **--no-pager**
               Do not pipe output into a pager.
    
           **--no-legend**
               Do not print the legend, i.e. column headers and the footer
               with hints.
    
           **--no-ask-password**
               Do not query the user for authentication for privileged
               operations.
    
           **-h** , **--help**
               Print a short help text and exit.
    
           **--version**
               Print a short version string and exit.
    


## EXAMPLES



           **Example 1. 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-nspawn(1) to open a shell in it.
    
           **Example 2. 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-firstboot(1). Afterwards the machine is started as system
           service. With the last command a login prompt into the container
           is requested.
    
           **Example 3. 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.
    


## ENVIRONMENT



           _$SYSTEMD_LOG_LEVEL_
               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)
               **emerg** , **alert** , **crit** , **err** , **warning** , **notice** , **info** , **debug** , or an
               integer in the range 0...7. See syslog(3) for more
               information. Each value may optionally be prefixed with one of
               **console** , **syslog** , **kmsg** or **journal** followed by a colon to set
               the maximum log level for that specific log target (e.g.
               **SYSTEMD_LOG_LEVEL=debug,console:info** 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.
    
           _$SYSTEMD_LOG_COLOR_
               A boolean. If true, messages written to the tty will be
               colored according to priority.
    
               This setting is only useful when messages are written directly
               to the terminal, because journalctl(1) and other tools that
               display logs will color messages based on the log level on
               their own.
    
           _$SYSTEMD_LOG_TIME_
               A boolean. If true, console log messages will be prefixed with
               a timestamp.
    
               This setting is only useful when messages are written directly
               to the terminal or a file, because journalctl(1) and other
               tools that display logs will attach timestamps based on the
               entry metadata on their own.
    
           _$SYSTEMD_LOG_LOCATION_
               A boolean. If true, messages will be prefixed with a filename
               and line number in the source code where the message
               originates.
    
               Note that the log location is often attached as metadata to
               journal entries anyway. Including it directly in the message
               text can nevertheless be convenient when debugging programs.
    
           _$SYSTEMD_LOG_TID_
               A boolean. If true, messages will be prefixed with the current
               numerical thread ID (TID).
    
               Note that the this information is attached as metadata to
               journal entries anyway. Including it directly in the message
               text can nevertheless be convenient when debugging programs.
    
           _$SYSTEMD_LOG_TARGET_
               The destination for log messages. One of **console**(log to the
               attached tty), **console-prefixed**(log to the attached tty but
               with prefixes encoding the log level and "facility", see
               syslog(3), **kmsg**(log to the kernel circular log buffer),
               **journal**(log to the journal), **journal-or-kmsg**(log to the
               journal if available, and to kmsg otherwise), **auto**(determine
               the appropriate log target automatically, the default), **null**
               (disable log output).
    
           _$SYSTEMD_LOG_RATELIMIT_KMSG_
               Whether to ratelimit kmsg or not. Takes a boolean. Defaults to
               "true". If disabled, systemd will not ratelimit messages
               written to kmsg.
    
           _$SYSTEMD_PAGER_ , _$PAGER_
               Pager to use when **--no-pager** is not given.  _$SYSTEMD_PAGER_ is
               used if set; otherwise _$PAGER_ is used. If neither
               _$SYSTEMD_PAGER_ nor _$PAGER_ are set, a set of well-known pager
               implementations is tried in turn, including less(1) and
               more(1), until one is found. If no pager implementation is
               discovered, no pager is invoked. Setting those environment
               variables to an empty string or the value "cat" is equivalent
               to passing **--no-pager**.
    
               Note: if _$SYSTEMD_PAGERSECURE_ is not set, _$SYSTEMD_PAGER_ and
               _$PAGER_ can only be used to disable the pager (with "cat" or
               ""), and are otherwise ignored.
    
           _$SYSTEMD_LESS_
               Override the options passed to **less**(by default "FRSXMK").
    
               Users might want to change two options in particular:
    
               **K**
                   This option instructs the pager to exit immediately when
                   Ctrl+C is pressed. To allow **less** to handle Ctrl+C itself
                   to switch back to the pager command prompt, unset this
                   option.
    
                   If the value of _$SYSTEMD_LESS_ does not include "K", and
                   the pager that is invoked is **less** , Ctrl+C will be ignored
                   by the executable, and needs to be handled by the pager.
    
               **X**
                   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.
    
               Note that setting the regular _$LESS_ environment variable has
               no effect for **less** invocations by systemd tools.
    
               See less(1) for more discussion.
    
           _$SYSTEMD_LESSCHARSET_
               Override the charset passed to **less**(by default "utf-8", if
               the invoking terminal is determined to be UTF-8 compatible).
    
               Note that setting the regular _$LESSCHARSET_ environment
               variable has no effect for **less** invocations by systemd tools.
    
           _$SYSTEMD_PAGERSECURE_
               Common pager commands like less(1), in addition to "paging",
               i.e. scrolling through the output, support opening of or
               writing to other files and running arbitrary shell commands.
               When commands are invoked with elevated privileges, for
               example under sudo(8) or **pkexec**(1), the pager becomes a
               security boundary. Care must be taken that only programs with
               strictly limited functionality are used as pagers, and
               unintended interactive features like opening or creation of
               new files or starting of subprocesses are not allowed. "Secure
               mode" for the pager may be enabled as described below, _if the_
               _pager supports that_ (most pagers are not written in a way that
               takes this into consideration). It is recommended to either
               explicitly enable "secure mode" or to completely disable the
               pager using **--no-pager** or _PAGER=cat_ when allowing untrusted
               users to execute commands with elevated privileges.
    
               This option takes a boolean argument. When set to true, the
               "secure mode" of the pager is enabled. In "secure mode",
               **LESSSECURE=1** will be set when invoking the pager, which
               instructs the pager to disable commands that open or create
               new files or start new subprocesses. Currently only less(1) is
               known to understand this variable and implement "secure mode".
    
               When set to false, no limitation is placed on the pager.
               Setting _SYSTEMD_PAGERSECURE=0_ or not removing it from the
               inherited environment may allow the user to invoke arbitrary
               commands.
    
               When _$SYSTEMD_PAGERSECURE_ is not set, systemd tools attempt to
               automatically figure out if "secure mode" should be enabled
               and whether the pager supports it. "Secure mode" is enabled if
               the effective UID is not the same as the owner of the login
               session, see geteuid(2) and sd_pid_get_owner_uid(3), or when
               running under sudo(8) or similar tools (_$SUDO_UID_ is set [2]).
               In those cases, _SYSTEMD_PAGERSECURE=1_ will be set and pagers
               which are not known to implement "secure mode" will not be
               used at all. Note that this autodetection only covers the most
               common mechanisms to elevate privileges and is intended as
               convenience. It is recommended to explicitly set
               _$SYSTEMD_PAGERSECURE_ or disable the pager.
    
               Note that if the _$SYSTEMD_PAGER_ or _$PAGER_ variables are to be
               honoured, other than to disable the pager,
               _$SYSTEMD_PAGERSECURE_ must be set too.
    
           _$SYSTEMD_COLORS_
               Takes a boolean argument. When true, **systemd** and related
               utilities will use colors in their output, otherwise the
               output will be monochrome. Additionally, the variable can take
               one of the following special values: "16", "256" to restrict
               the use of colors to the base 16 or 256 ANSI colors,
               respectively. This can be specified to override the automatic
               decision based on _$TERM_ and what the console is connected to.
    
           _$SYSTEMD_URLIFY_
               The value must be a boolean. Controls whether clickable links
               should be generated in the output for terminal emulators
               supporting this. This can be specified to override the
               decision that **systemd** makes based on _$TERM_ and other
               conditions.
    


## NOTES



            1. HTTP ETag
               https://en.wikipedia.org/wiki/HTTP_ETag
    
            2. It is recommended for other tools to set and check _$SUDO_UID_
               as appropriate, treating it is a common interface.
    


* * *