Provides idiomatic systemctl bindings for go developers, in order to make it easier to write system tooling using golang.
Go to file
2024-08-08 15:37:04 -07:00
.github add sponsorship 2021-07-05 21:08:33 -07:00
properties add property definitions and show test 2021-05-15 14:24:31 -07:00
errors_test.go update to fix some tests, remove panics, and wrap errors 2023-06-17 23:18:28 -04:00
errors.go update to fix some tests, remove panics, and wrap errors 2023-06-17 23:18:28 -04:00
go.mod update to fix some tests, remove panics, and wrap errors 2023-06-17 23:18:28 -04:00
go.sum update go compiler target version 2021-08-17 10:08:09 -07:00
helpers_test.go add ability to list all units 2024-08-08 15:37:04 -07:00
helpers.go add ability to list all units 2024-08-08 15:37:04 -07:00
LICENSE Adds 0bsd license 2021-05-14 14:39:38 -07:00
README.md update to fix some tests, remove panics, and wrap errors 2023-06-17 23:18:28 -04:00
structs.go add ability to list all units 2024-08-08 15:37:04 -07:00
systemctl_test.go fix broken error filtration 2023-06-28 23:43:20 -07:00
systemctl.go gofumpt against systemctl + add reenable 2022-10-23 23:26:52 -07:00
util.go fix broken error filtration 2023-06-28 23:43:20 -07:00

PkgGoDev

systemctl

This library aims at providing idiomatic systemctl bindings for go developers, in order to make it easier to write system tooling using golang. This tool tries to take guesswork out of arbitrarily shelling out to systemctl by providing a structured, thoroughly-tested wrapper for the systemctl functions most-likely to be used in a system program.

If your system isn't running (or targeting another system running) systemctl, this library will be of little use to you.

What is systemctl

systemctl is a command-line program which grants the user control over the systemd system and service manager.

systemctl may be used to introspect and control the state of the "systemd" system and service manager. Please refer to systemd(1) for an introduction into the basic concepts and functionality this tool manages.

Supported systemctl functions

  • systemctl daemon-reload
  • systemctl disable
  • systemctl enable
  • systemctl reenable
  • systemctl is-active
  • systemctl is-enabled
  • systemctl is-failed
  • systemctl mask
  • systemctl restart
  • systemctl show
  • systemctl start
  • systemctl status
  • systemctl stop
  • systemctl unmask

Helper functionality

  • Get start time of a service (ExecMainStartTimestamp) as a Time type
  • Get current memory in bytes (MemoryCurrent) an an int
  • Get the PID of the main process (MainPID) as an int
  • Get the restart count of a unit (NRestarts) as an int

Useful errors

All functions return a predefined error type, and it is highly recommended these errors are handled properly.

Context support

All calls into this library support go's context functionality. Therefore, blocking calls can time out according to the caller's needs, and the returned error should be checked to see if a timeout occurred (ErrExecTimeout).

Simple example

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/taigrr/systemctl"
)

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()
    // Equivalent to `systemctl enable nginx` with a 10 second timeout
    opts := systemctl.Options{ UserMode: false }
    unit := "nginx"
    err := systemctl.Enable(ctx, unit, opts)
    if err != nil {
        log.Fatalf("unable to enable unit %s: %v", "nginx", err)
    }
}

License

This project is licensed under the 0BSD License, written by Rob Landley. As such, you may use this library without restriction or attribution, but please don't pass it off as your own. Attribution, though not required, is appreciated.

By contributing, you agree all code submitted also falls under the License.

External resources