systemdkit

Pure Elixir tools for systemd unit files and D-Bus manager control.

systemdkit is for Elixir applications and deployment tools that need to generate unit files, inspect systemd state, or control systemd directly over D-Bus without shelling out to systemctl.

Installation

The Hex package and Mix application are named systemdkit; public modules use the Systemd namespace.

def deps do
  [
    {:systemdkit, "~> 0.1.1"}
  ]
end

Unit files

Build systemd units with typed helpers, render them, and validate them before installation:

unit_file =
  Systemd.UnitFile.service(
    unit: [description: "My app", after: "network.target"],
    service: [
      type: :exec,
      user: "deploy",
      working_directory: "/opt/my-app/current",
      exec_start: "/opt/my-app/current/bin/my_app start",
      restart: "on-failure",
      memory_max: "512M",
      tasks_max: 512,
      no_new_privileges: true,
      protect_system: :strict
    ],
    install: [wanted_by: "multi-user.target"]
  )

:ok = Systemd.UnitFile.validate(unit_file, :service)
Systemd.UnitFile.to_string(unit_file)

Parsing is loss-aware: comments, blank lines, duplicate directives, reset directives, and source spans are preserved.

{:ok, unit_file} = Systemd.UnitFile.parse("[Service]\nExecStart=/bin/true\n")
Systemd.UnitFile.get_all(unit_file, "Service", "ExecStart")

Builders are available for service, socket, timer, mount, path, and target units.

D-Bus manager control

Use the top-level API for short-lived D-Bus operations:

{:ok, units} = Systemd.list_units()
{:ok, unit_files} = Systemd.list_unit_files()
{:ok, state} = Systemd.unit_state("dbus.service")

:ok = Systemd.reload()
:ok = Systemd.start_unit("my_app.service")
:ok = Systemd.restart_unit("my_app.service")

Use Systemd.Manager when you want to reuse a connection or inspect jobs:

Systemd.with_connection([], fn conn ->
  with {:ok, job} <- Systemd.Manager.restart_unit(conn, "my_app.service"),
       :ok <- Systemd.Job.await_signal(conn, job, timeout: 10_000) do
    :ok
  end
end)

Errors and permissions

APIs return {:ok, value} or {:error, %Systemd.Error{}}. Permission and polkit failures are classified as :permission:

case Systemd.start_unit("my_app.service") do
  :ok -> :ok
  {:error, error} ->
    if Systemd.Error.permission?(error), do: {:error, :permission_denied}, else: {:error, error}
end

Read-only calls often work unprivileged. Mutating system units typically require root or appropriate polkit rules. systemdkit reports those D-Bus errors directly; it does not retry through sudo.

For user units, pass bus: :session when a systemd user session bus is available:

Systemd.list_units(bus: :session)

Guides

• D-Bus manager operations
• Xamal-style deployment units

Integration testing

The test suite includes optional integration tests against a real Linux systemd manager. They are excluded by default:

mix test

Run them on Linux with systemd and a system bus:

SYSTEMD_INTEGRATION=1 mix test

This repository also includes a Lima helper used by maintainers:

scripts/integration_test.sh