Skip to content

Examples

Fifteen small, runnable programs live in examples/. Each one is a complete main package (or a package with tests) that compiles against the current API in CI. Clone the repository and run any of them with go run:

git clone https://github.com/rossedman/sdvarlink && cd sdvarlink
go run ./examples/hostname

No systemd handy?

The two testing examples run anywhere: go test ./examples/testing-with-fake/ ./examples/record-replay/.

Queries

Single calls with typed inputs and outputs.

  • Resolve a hostname

    Resolve names through systemd-resolved's io.systemd.Resolve interface, like resolvectl query.

    io.systemd.Resolve · Unprivileged

  • Describe the host

    Print what systemd-hostnamed knows about the machine, like hostnamectl.

    io.systemd.Hostname · Unprivileged

  • Concurrent lookups

    Resolve many names in parallel with one pooled generated client.

    io.systemd.Resolve · Unprivileged

  • Journal control

    Ask systemd-journald to sync, rotate, flush or relinquish, like journalctl --sync/--rotate/--flush.

    io.systemd.Journal · Root

Streaming

Methods that answer with many replies, as Go iterators.

  • List users

    Stream every user record from systemd's userdb multiplexer, like userdbctl user.

    io.systemd.UserDatabase · Unprivileged

  • List units

    List units through PID 1's io.systemd.Unit interface (systemd v258+), with feature detection.

    io.systemd.Unit · Unprivileged

  • List machines

    List containers and VMs registered with systemd-machined, like machinectl list.

    io.systemd.Machine · Unprivileged

  • Monitor DNS

    Stream every DNS query systemd-resolved answers, like resolvectl monitor.

    io.systemd.Resolve.Monitor · Root

  • Read metrics

    Read the io.systemd.Metrics interface systemd services publish under /run/systemd/report/ (v260+).

    io.systemd.Metrics · Unprivileged

File descriptors

Open files over the socket, in both directions.

  • Mount a disk image

    Pass a disk image to systemd-mountfsd as a file descriptor and receive mount file descriptors back.

    io.systemd.MountFileSystem · Root or polkit

Core & introspection

The varlink core and IDL parser, no bindings needed.

  • Introspect a service

    List a Varlink service's interfaces and methods with the core package and the IDL parser.

    core · Depends on the socket

  • Raw calls

    Call any Varlink method with JSON parameters and print the replies, like varlinkctl call.

    core · Depends on the socket

  • Feature detection

    Report which Varlink services and methods the host's systemd offers, with ErrUnsupported and Supports.

    core · Unprivileged

Servers

Serve Varlink interfaces from Go.

  • A job queue service

    A complete service with a typed call, a stream, a typed error, peer-credential checks and socket activation.

    io.example.Queue · Unprivileged

  • Publish metrics

    Serve io.systemd.Metrics with the generated types, readable by systemd tooling.

    io.systemd.Metrics · Unprivileged

Testing

Test code built on sdvarlink without systemd.

  • Testing with a fake

    Unit-test application code against a varlinktest fake io.systemd.Resolve, no systemd required.

    io.systemd.Resolve · None (runs anywhere)

  • Record & replay

    Record a session against real systemd-journald into a golden file and replay it in CI.

    io.systemd.Journal · Root to record; none to replay