systemd

README

blitiri.com.ar/go/systemd

systemd is a Go package implementing a way to get network listeners from systemd, similar to C's sd_listen_fds() and sd_listen_fds_with_names() (man).

Supports named file descriptors, which is useful if your daemon needs to be able to tell the different ports apart (e.g. http vs https).

It is used by daemons such as chasquid to listen on privileged ports without needing to run as root.

Example

listeners, err := systemd.Listeners()
for _, l := range listeners["service.socket"] {
	go serve(l)
}

Status

The API should be considered stable, and no backwards-incompatible changes are expected.

Contact

If you have any questions, comments or patches please send them to albertito@blitiri.com.ar.

Documentation

Overview

Package systemd implements a way to get network listeners from systemd, similar to C's sd_listen_fds(3) and sd_listen_fds_with_names(3).

Example

package main

import (
	"fmt"
	"net"

	"blitiri.com.ar/go/systemd"
)

func serve(l net.Listener) {
	// Serve over the listener.
}

func main() {
	listeners, err := systemd.Listeners()
	if err != nil {
		fmt.Printf("error getting listeners: %v", err)
		return
	}

	// Iterate over the listeners of a particular systemd socket.
	// The name comes from the FileDescriptorName option, defaults to the name
	// of the socket unit.
	for _, l := range listeners["service.socket"] {
		go serve(l)
	}
}

Index

• Variables
• func Files() (map[string][]*os.File, error)
• func Listen(netw, laddr string) (net.Listener, error)
• func Listeners() (map[string][]net.Listener, error)
• func OneListener(name string) (net.Listener, error)

Examples

• Package

Variables

var (
	// Error to return when $LISTEN_PID does not refer to us.
	ErrPIDMismatch = errors.New("$LISTEN_PID != our PID")
)

Functions

func Files

func Files() (map[string][]*os.File, error)

Files returns the open files passed by systemd via environment variables.

It returns a map of the form (file descriptor name -> []*os.File).

The file descriptor name comes from the "FileDescriptorName=" option in the systemd socket unit. Multiple socket units can have the same name, hence the slice of listeners for each name.

If the "FileDescriptorName=" option is not used, then all file descriptors are mapped to the "" name.

Ideally you should not need to call this more than once. If you do, the same files will be returned, as repeated calls to this function will return the same results: the parsing is done only once, and the results are saved and reused.

See sd_listen_fds(3) and sd_listen_fds_with_names(3) for more details on how the passing works.

Normally you would use Listeners instead; however, access to the file descriptors can be useful if you need more fine-grained control over listener creation, for example if you need to create packet connections from them.

func Listen

func Listen(netw, laddr string) (net.Listener, error)

Listen returns a net.Listener for the given address, similar to net.Listen.

If the address begins with "&" it is interpreted as a systemd socket being passed. For example, using "&http" would mean we expect a systemd socket passed to us, named with "FileDescriptorName=http" in its unit.

Otherwise, it uses net.Listen to create a new listener with the given net and local address.

This function can be convenient for simple callers where you get the address from a user, and want to let them specify either "use systemd" or a normal address without too much additional complexity.

This is a convenience function built on top of Listeners().

func Listeners

func Listeners() (map[string][]net.Listener, error)

Listeners returns net.Listeners corresponding to the file descriptors passed by systemd via environment variables.

It returns a map of the form (file descriptor name -> []net.Listener).

The file descriptor name comes from the "FileDescriptorName=" option in the systemd socket unit. Multiple socket units can have the same name, hence the slice of listeners for each name.

If the "FileDescriptorName=" option is not used, then all file descriptors are mapped to the "" name.

Ideally you should not need to call this more than once. If you do, the same listeners will be returned, as repeated calls to this function will return the same results: the parsing is done only once, and the results are saved and reused.

See sd_listen_fds(3) and sd_listen_fds_with_names(3) for more details on how the passing works.

func OneListener

func OneListener(name string) (net.Listener, error)

OneListener returns a net.Listener for the first systemd socket with the given name. If there are none, the listener and error will both be nil. An error will be returned only if there were issues parsing the file descriptors.

This function can be convenient for simple callers where you know there's only one file descriptor being passed with the given name.

This is a convenience function built on top of Listeners().