# updatectl

## NAME



           updatectl - Control the system update service
    


## SYNOPSIS



    
           **updatectl**[OPTIONS...] {COMMAND} [TARGET...]
    


## DESCRIPTION



           **updatectl** may be used to check for and install system updates
           managed by systemd-sysupdated.service(8).
    


## COMMANDS



           The following commands are understood:
    
           **list**[_TARGET_[@_VERSION_]]
               Show information about targets and their versions.
    
               When no _TARGET_ is specified, this command lists all available
               targets. When a _TARGET_ is specified without a _VERSION_ , this
               command lists all known versions of the specified target. If a
               _VERSION_ is specified, this command lists all known information
               about the specific version.
    
               See the example below for details of the output.
    
               Added in version 257.
    
           **check**[_TARGET_...]
               Check if any updates are available for the specified targets.
               If no targets are specified, all available targets will be
               checked for updates.
    
               See the example below for details of the output.
    
               Added in version 257.
    
           **update**[_TARGET_[@_VERSION_]...]
               Update the specified targets to the specified versions. If a
               target is specified without a version, then it will be updated
               to the latest version. If no targets are specified, then all
               available targets will be updated to the latest version.
    
               Added in version 257.
    
           **vacuum**[_TARGET_...]
               Clean up old versions of the specified targets. If no targets
               are specified, all available targets will be vacuumed.
    
               Added in version 257.
    
           **features**[_FEATURE_]
               When no _FEATURE_ is specified, this command lists all optional
               features. When a _FEATURE_ is specified, this command lists all
               known information about that feature.
    
               Added in version 257.
    
           **enable** _FEATURE_..., **disable** _FEATURE_...
               These commands enable or disable optional features. See
               sysupdate.features(5). These commands always operate on the
               host system.
    
               By default, these commands will only change the system's
               configuration by creating or deleting drop-in files; they will
               not immediately download the enabled features, or clean up
               after the disabled ones. Enabled features will be downloaded
               and installed the next time the target is updated, and
               disabled transfers will be cleaned up the next time the target
               is updated or vacuumed. Pass **--now** to immediately apply these
               changes.
    
               Added in version 257.
    
           **-h** , **--help**
               Print a short help text and exit.
    
           **--version**
               Print a short version string and exit.
    


## OPTIONS



           The following commands are understood:
    
           **--reboot**
               When used with the **update** command, reboots the system after
               updates finish applying. If any update fails, the system will
               not reboot.
    
               When used with the **enable** or **disable** commands and the **--now**
               flag, reboots the system after download or clean-up finish
               applying.
    
               Added in version 257.
    
           **--offline**
               When used with the **list** command, disables fetching metadata
               from the network. This makes the **list** command only return
               information that is available locally (i.e. about versions
               already installed on the system).
    
               Added in version 257.
    
           **--now**
               When used with the **enable** command, downloads and installs the
               enabled features. When used with the **disable** command, deletes
               all resources downloaded by the disabled features.
    
               Added in version 257.
    
           **-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.
    
           **--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.
    


## 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 [1]).
               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.
    


## EXAMPLES



           Note that these examples are just here for demonstration purposes,
           and the output of these commands is free to change. These commands
           are intended for display to a user. If you'd like machine-readable
           output, use the org.freedesktop.sysupdate1(5) D-Bus API directly.
    
           **Example 1. Output from list**
    
               $ **updatectl list**
               TARGET         VERSION PATH
               host           48      sysupdate.d
               machine:fedora 38      /var/lib/machines/fedora.raw
               component:shim 15.7    sysupdate.shim.d
               $ **updatectl list host**
                 VERSION STATUS
               ↻ 50      candidate
                 49      available
               ● 48      current
                 47      available
                 46      available
                 45      available
               [...]
               × 25      available+obsolete
               × 24      available+obsolete
               × 23      available+obsolete
               [...]
               $ **updatectl list host@49**
               ↻ Version: 50
                 State: candidate
                 ChangeLog: https://vendor.com/os/v50.html
    
               TYPE     PATH                                                                   PTUUID                               PTFLAGS SHA256
               url-file http://dl.vendor.com/os/uki_50                                         -                                          - 90f6534282dd720f7a222fa781086990dc9c83e5c7499f085970a8e75e3ac349
               url-file http://dl.vendor.com/os/usr_50_981a5b84-a301-c819-f681-3e575fe16f16    981a5b84-a301-c819-f681-3e575fe16f16       - c0596ab1095258ec6f16c7c281a50d71c419a9f587c1ef858cfbbb69fb0a16f3
               url-file http://dl.vendor.com/os/verity_50_2f8d0f3b-f80a-6ddc-a556-3722bfbb5b79 2f8d0f3b-f80a-6ddc-a556-3722bfbb5b79       - e1e90a128e038b3a53455e55d1ca717c743aba31fe6b4b4624109df0243c6338
               url-file http://dl.vendor.com/os/verity_sig_50                                  -                                          - ca3d163bab055381827226140568f3bef7eaac187cebd76878e0b63e9e442356
    
           **Example 2. Checking for and installing updates**
    
               $ **updatectl check**
               TARGET         UPDATE
               host           48 → 50
               machine:fedora 38 → 40
               $ **updatectl update host machine:fedora@39**
               [...]
               ✓ host@50
               ✓ machine:fedora@39
    


## NOTES



            1. It is recommended for other tools to set and check _$SUDO_UID_
               as appropriate, treating it is a common interface.
    


* * *