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.

Upgrading the Host

To upgrade the host system, use the upgrade command with the path to a valid upgrade file (such as a firmware image):

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

After a successful upgrade, a reboot is required for the changes to take effect:

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

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

hostctl upgrade /path/to/firmware.img && hostctl reboot

Note

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

System Lifecycle Management

The Host Service supports system lifecycle management. This feature allows users to handle container installation, rollbacks, and status checks from within edge containers.

Available System Commands

Install

Install a new system using provided configuration and image files. An optional metadata file (meta.tar.xz) can be included.

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

Commit

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

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

Rollback

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

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

Status

Show the current status of the system installation lifecycle.

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

Installation Process

System installation uses a configuration file (container-config.yaml), a root filesystem image (rootfs.tar.xz), and optionally a metadata file (meta.tar.xz). 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

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

If you don't require a metadata file during installation, simply omit the third argument:

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

Committing or Rolling Back

Once installed and booted into, you must explicitly mark the installation as successful using:

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

If the system behaves unexpectedly, revert to the previous state with:

/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 version.

Checking System Status

You can verify the current lifecycle state using:

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

Possible returned states:

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

pending : A reboot will boot into the newly installed system version.

trying : The system is running an installed but uncommitted system version.

rollback : A reboot will revert to the previous commited system version.

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 upgrade <file>`

Upgrade the host system using the provided firmware file.

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

Install a new system using the provided configuration and image files. An optional metadata 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.