sdnotify

README

sdnotify

Package sdnotify implements systemd readiness notifications as described in https://www.freedesktop.org/software/systemd/man/sd_notify.html. MIT Licensed.

Documentation

Overview

Package sdnotify implements systemd readiness notifications as described in https://www.freedesktop.org/software/systemd/man/sd_notify.html.

Index

• Constants
• func Statusf(format string, v ...interface{}) string
• type Notifier
  • func New() (*Notifier, error)
  • func Open(sock string) (*Notifier, error)
  • func (n *Notifier) Close() error
  • func (n *Notifier) Notify(s ...string) error

Examples

• Notifier

Constants

const (
	Ready     = "READY=1"
	Reloading = "RELOADING=1"
	Stopping  = "STOPPING=1"
)

Common notification values. For a description of each, see: https://www.freedesktop.org/software/systemd/man/sd_notify.html#Description.

const Socket = "NOTIFY_SOCKET"

Socket is the predefined systemd notification socket environment variable.

Functions

func Statusf

func Statusf(format string, v ...interface{}) string

Statusf creates a formatted STATUS notification with the input format string and values.

Types

type Notifier

type Notifier struct {
	// contains filtered or unexported fields
}

A Notifier can notify systemd of service status and readiness. Any methods called on a nil Notifier will result in a no-op, allowing graceful functionality degradation when a Go program is not running under systemd supervision.

Example

This example demonstrates typical use of a Notifier when starting a service, indicating readiness, and shutting down the service.

package main

import (
	"errors"
	"log"
	"os"
	"time"

	"github.com/mdlayher/sdnotify"
)

func main() {
	// Create a Notifier which will send notifications when running under
	// systemd unit Type=notify, or will no-op otherwise if the NOTIFY_SOCKET
	// environment variable is not set.
	n, err := sdnotify.New()
	if err != nil && !errors.Is(err, os.ErrNotExist) {
		log.Fatalf("failed to open systemd notifier: %v", err)
	}
	// Clean up the notification socket when all done.
	defer n.Close()

	// Now that the Notifier is created, any further method calls will update
	// systemd with the service's readiness state.
	start := time.Now()
	if err := n.Notify(sdnotify.Statusf("starting, waiting %s for readiness", 5*time.Second)); err != nil {
		log.Fatalf("failed to send startup notification: %v", err)
	}

	// Do service initialization work, ex: go srv.Start() ...

	// Indicate the service is now ready so 'systemctl start' and similar
	// commands can unblock.
	err = n.Notify(
		sdnotify.Statusf("service started successfully in %s", time.Since(start)),
		sdnotify.Ready,
	)
	if err != nil {
		log.Fatalf("failed to send ready notification: %v", err)
	}

	// Wait for a signal or cancelation, ex: <-ctx.Done() ...

	// Finally, indicate the service is shutting down.
	err = n.Notify(
		sdnotify.Statusf("received %s, shutting down", os.Interrupt),
		sdnotify.Stopping,
	)
	if err != nil {
		log.Fatalf("failed to send stopping notification: %v", err)
	}
}

func New

func New() (*Notifier, error)

New creates a Notifier which sends notifications to the UNIX socket specified by the NOTIFY_SOCKET environment variable. See Open for more details.

func Open

func Open(sock string) (*Notifier, error)

Open creates a Notifier which sends notifications to the UNIX socket specified by sock.

If sock does not exist or is unset (meaning the service is not running under systemd supervision, or is not using systemd unit Type=notify), Open will return an error which can be checked with 'errors.Is(err, os.ErrNotExist)'. Calling any of the resulting nil Notifier's methods will result in a no-op.

func (*Notifier) Close

func (n *Notifier) Close() error

Close closes the Notifier's socket. If n is nil, Close is a no-op.

func (*Notifier) Notify

func (n *Notifier) Notify(s ...string) error

Notify sends zero or more notifications to systemd. See the package constants for a list of common notifications or use the Statusf function to create a STATUS notification.

For advanced use cases, see: https://www.freedesktop.org/software/systemd/man/sd_notify.html#Description.

If n is nil or no strings are specified, Notify is a no-op.