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 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 system upgrade command with a path to a valid upgrade file (such as a firmware image):

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

After a successful upgrade, a reboot is required for 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 system upgrade /path/to/firmware.img && hostctl reboot

Note

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

Container Lifecycle Management

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

Available Container Commands

Install

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

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

Commit

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

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

Rollback

Rollback to the previously installed container if current changes fail or behave unexpectedly.

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

Status

Show current status of container installation lifecycle.

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

Installation Process

Container installation uses a configuration file (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 container install config.yaml rootfs.tar.xz meta.tar.xz

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

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

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

Committing or Rolling Back

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

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

If an installation behaves unexpectedly, revert to the previous state with:

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

Note

Any form of host system reboot without a commit will make the system roll back to the old container

Checking Container Status

You can verify the container's current lifecycle state using:

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

Possible returned states:

normal : No updates or rollbacks are pending.

pending : A reboot will boot into the newly installed container

trying : Currently running an installed but uncommitted container

rollback : A reboot will boot into the old container.

Container Lifecycle Illustration

Container 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 with chown and chmod. However, these changes will revert after a host reboot unless you make them persistent.

To make changes persistent on a systemd-based system, add a line like this to your tmpfiles.d config (e.g., in /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 (e.g., host upgrade, reboot, suspend).

Commands

The following commands can be issued with hostctl:

`hostctl ping`

Verify connection with the host service.

`hostctl reboot`

Reboot the host system.

`hostctl suspend`

Suspend the host system.

`hostctl system upgrade <file>`

Upgrade the host system using the provided firmware file

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

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

`hostctl container commit`

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

`hostctl container rollback`

Rollback to the previously installed container if current changes fail or behave unexpectedly.

`hostctl container status`

Show current status of container installation lifecycle.

Exit Codes and Output

On success, hostctl prints OK\n to standard output, and exits with status 0.
On upgrade success, upgrade 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.