Host service

A lightweight daemon and client for managing host functions from inside edge containers.

Overview

The Host Service exposes a simple API over a Unix domain socket, allowing edge containers to issue system-level commands on the host. It consists of two main components:

host-service - The daemon that listens for API requests on the Unix socket.
hostctl - A statically linked client program used to issue commands.

Container usage

By default, the host system provides:

A Unix domain socket, typically at /host/host-service
The client binary, hostctl, typically at /host/hostctl

Inside the container, you can run commands by referencing these paths directly. For example:

/host/hostctl --socket-path=/host/host-service ping
/host/hostctl -s /host/host-service suspend

Note

By default, hostctl expects the socket at /run/host-service. Use the --socket-path (or -s) option to specify a custom path.

Creating symbolic links

For convenience, you can create symbolic links to the Unix socket and the client binary so that you do not need to specify the full path or --socket-path each time. On a systemd-based system, you can do this with a tmpfiles.d configuration:

cat > /etc/tmpfiles.d/host-service.conf <<EOF
L /run/host-service - - - - /host/host-service
L /usr/bin/hostctl - - - - /host/hostctl
EOF

When the systemd-tmpfiles-setup service runs (typically at boot), it will create these symbolic links. Once in place, you can simply run:

hostctl reboot

instead of specifying the full paths.

Lifecycle management

In addition to basic host management, the Host Service supports lifecycle operations for both the host firmware and containerized systems running on the host. Both follow a similar upgrade/install, commit, rollback, and status pattern, and both require a reboot to activate the new version and an explicit commit to make it permanent.

Host lifecycle management

Commands for managing host system firmware upgrades.

Upgrade

To upgrade the host system, provide the upgrade file path to the host upgrade command:

/host/hostctl --socket-path=/host/host-service host upgrade /path/to/firmware.multi-mender

If successful, a reboot is required to start the newly upgraded firmware:

/host/hostctl --socket-path=/host/host-service reboot

If you have created symbolic links as described above, these commands can be shortened to:

hostctl host upgrade /path/to/firmware.multi-mender && hostctl reboot

Note

The file must be a regular file. Other types (e.g., devices, sockets) will be rejected.

Commit

Marks a host upgrade as successful. Once committed, the changes become permanent.

/host/hostctl --socket-path=/host/host-service host commit

Rollback

Rolls back the host system to the previously committed firmware version. This is useful if an upgrade failed or produced unexpected behavior.

/host/hostctl --socket-path=/host/host-service host rollback

Note

Any reboot of the host system without a commit will cause it to roll back to the previous firmware version.

Upgrade status

Returns the current status of the host upgrade lifecycle.

/host/hostctl --socket-path=/host/host-service host upgrade-status

Possible returned states:

normal : No new firmware version, or rollbacks, are pending.

pending : A new firmware version has been received but not yet committed.

trying : The host is running with uncommitted firmware changes.

rollback : The host is rolling back to a previous firmware version.

failed : A firmware upgrade failed.

System lifecycle management

Commands for managing container installs and rollbacks.

System Install

Install a new system using a configuration file (container-config.yaml) and a root filesystem image (rootfs.tar.xz). Optionally a metadata file (meta.tar.xz) and host configuration (host-config.yaml) can be included. The Host Service copies and installs these files on the host system synchronously.

Example:

/host/hostctl --socket-path=/host/host-service system install <container-config.yaml> <rootfs.tar.xz> [-M meta.tar.xz] [-S host-config.yaml]

A reboot is required after a successful installation to apply changes and start the new system.

If you don't require a metadata file or host configuration, simply omit the flags:

/host/hostctl --socket-path=/host/host-service system install container-config.yaml rootfs.tar.xz

Commit

Marks a system installation as successful. Once committed, the changes become permanent.

/host/hostctl --socket-path=/host/host-service system commit

Rollback

Rolls back the system to the previously committed version. This is useful if an install failed or produced unexpected behavior.

/host/hostctl --socket-path=/host/host-service system rollback

Note

Any reboot of the host system without a commit will cause it to roll back to the previous system version.

Install status

Returns the current status of the system lifecycle.

/host/hostctl --socket-path=/host/host-service system install-status

Possible returned states:

normal : No new system version, or rollbacks, are pending.

pending : A new system version has been received but not yet committed.

trying : The system is running with uncommitted changes.

rollback : The system is rolling back to a previous state.

System lifecycle illustration

system lifecycle

Security

By default, only the root user in the container can communicate over the Unix domain socket. If you need non-root users (or groups) in the container to have access, you can adjust the ownership and permissions on the socket using chown and chmod. However, these changes will revert after a host reboot unless made persistent.

To make the user permissions persistent on a systemd-based system, add a line like this to your tmpfiles.d config (e.g., /etc/tmpfiles.d/host-service.conf):

z /host/host-service 0660 root admin - -

This assigns ownership and permissions to the /host/host-service socket so that it is writable by the root user and members of the admin group (if that group exists).

Warning

Important: Granting access to host-service is powerful and should be done with caution. It allows issuing host-level commands such as upgrade, reboot, and suspend.

Commands

The following commands can be issued with hostctl:

`hostctl ping`

Verify the connection to the host service.

`hostctl reboot`

Reboot the host system.

`hostctl suspend`

Suspend the host system.

`hostctl host upgrade <file>`

Upgrade the host system using the provided firmware file.

`hostctl host commit`

Mark the current host upgrade as successful, making the changes permanent.

`hostctl host rollback`

Roll back to the previously committed firmware version if the current one fails or behaves unexpectedly.

`hostctl host upgrade-status`

Show the current status of the host upgrade lifecycle.

`hostctl system install <container-config.yaml> <rootfs.tar.xz> [-M meta.tar.xz] [-S host-config.yaml]`

Install a new system using the provided configuration and image files. An optional metadata file and/or host configuration file can be included.

`hostctl system commit`

Mark the current system installation as successful, making the changes permanent.

`hostctl system rollback`

Roll back to the previously installed system if the current one fails or behaves unexpectedly.

`hostctl system install-status`

Show the current status of the system installation lifecycle.

Exit codes and output

On success, hostctl prints OK\n to standard output and exits with status 0.
On upgrade success, hostctl prints:

Upgrade installed successfully. Please reboot to complete the process.

and exits with status 0.

On failure, it returns a non-zero exit code and prints a descriptive error message to standard output.
To suppress normal output, use the --quiet flag.