service.v2 – gopkg.in/hlandau/service.v2 Index | Examples | Files | Directories

package service

import "gopkg.in/hlandau/service.v2"

Package service wraps all the complexity of writing daemons while enabling seamless integration with OS service management facilities.

Example

The following example illustrates the minimal skeleton structure to implement a daemon. This example can run as a service on Windows or a daemon on Linux. The systemd notify protocol is supported.

Code: 

{
	service.Main(&service.Info{
		Title:       "Foobar Web Server",
		Name:        "foobar",
		Description: "Foobar Web Server is the greatest webserver ever.",

		RunFunc: func(smgr service.Manager) error {
			// Start up your service.
			// ...

			// Once initialization requiring root is done, call this.
			err := smgr.DropPrivileges()
			if err != nil {
				return err
			}

			// When it is ready to serve requests, call this.
			// You must call DropPrivileges first.
			smgr.SetStarted()

			// Optionally set a status
			smgr.SetStatus("foobar: running ok")

		loop:
			for {
				select {
				// Handle requests, or do so in another goroutine controlled from here.
				case <-smgr.StopChan():
					break loop
				}
			}

			// Do any necessary teardown.
			// ...

			return nil
		},
	})
}

Index

Examples

Variables 

var EmptyChrootPath = daemon.EmptyChrootPath

This will always point to a path which the platform guarantees is an empty directory. You can use it as your default chroot path if your service doesn't access the filesystem after it's started.

On Linux, the FHS provides that "/var/empty" is an empty directory, so it points to that.

Functions

func Main 

func Main(info *Info)

This function should typically be called directly from func main(). It takes care of all housekeeping for running services and handles service lifecycle.

Types

type Info 

type Info struct {
	// Recommended. Codename for the service, e.g. "foobar"
	//
	// If this is not set, exepath.ProgramName is used, which by default is the
	// program's binary basename (e.g. "FooBar.exe" would become "foobar").
	Name string

	// Required unless NewFunc is specified instead. Starts the service. Must not
	// return until the service has stopped. Must call smgr.SetStarted() to
	// indicate when it has finished starting and use smgr.StopChan() to
	// determine when to stop.
	//
	// Should call SetStatus() periodically with a status string.
	RunFunc func(smgr Manager) error

	// Optional. An alternative to RunFunc. If this is provided, RunFunc must not
	// be specified, and this package will provide its own implementation of
	// RunFunc.
	//
	// The NewFunc will be called to instantiate the runnable service.
	// Privileges will then be dropped and Start will be called. Start must
	// return. When the service is to be stopped, Stop will be called. Stop must
	// return.
	//
	// To implement status notification, implement also the StatusSource interface.
	NewFunc func() (Runnable, error)

	Title       string // Optional. Friendly name for the service, e.g. "Foobar Web Server"
	Description string // Optional. Single line description for the service

	AllowRoot     bool   // May the service run as root? If false, the service will refuse to run as root unless privilege dropping is set.
	DefaultChroot string // Default path to chroot to. Use this if the service can be chrooted without consequence.
	NoBanSuid     bool   // Set to true if the ability to execute suid binaries must be retained.
	// contains filtered or unexported fields
}

An instantiable service.

type Manager 

type Manager interface {
	// Must be called when the service is ready to drop privileges.
	// This must be called before SetStarted().
	DropPrivileges() error

	// Must be called by a service payload when it has finished starting.
	SetStarted()

	// A service payload must stop when this channel is closed.
	StopChan() <-chan struct{}

	// Called by a service payload to provide a single line of information on the
	// current status of that service.
	SetStatus(status string)
}

The interface between the service library and the application-specific code. The application calls the methods in the provided instance of this interface at various stages in its lifecycle.

type Runnable 

type Runnable interface {
	// Start the runnable. Any initialization requiring root privileges must
	// already have been obtained as this will be called after dropping
	// privileges. Must return.
	Start() error

	// Stop the runnable. Must return.
	Stop() error
}

Used only by the NewFunc interface.

type StatusSource 

type StatusSource interface {
	// Return a channel on which status messages will be sent. If a Runnable
	// implements this, it is guaranteed that the channel will be consumed until
	// Stop is called.
	StatusChan() <-chan string
}

An upgrade interface for Runnable, implementation of which is optional.

Source Files

service.go service_unix.go

Directories

PathSynopsis
daemonPackage daemon provides functions to assist with the writing of UNIX-style daemons in go.
daemon/bansuidPackage bansuid provides a function to prevent processes from reacquiring privileges.
gsptcallPackage gsptcall provides a call wrapper for SetProcTitle which does nothing when it is not supported.
Version
v2.0.17 (latest)
Published
Mar 2, 2021
Platform
linux/amd64
Imports
21 packages
Last checked
9 hours ago –

Tools for package owners.