daemon

Documentation

Overview

Package daemon implements utilities useful in writing daemons, including logging, restarting, and privilege dropping.

Index

• Variables
• func LogFileFlag(name string, mode os.FileMode) **os.File
• func Restart(timeout time.Duration)
• func Run()
• func Shutdown(timeout time.Duration)
• type Forker
  • func ForkPIDFlags(forkFlagName, pidFlagName string, defPIDFile string) Forker
• type Listenable
  • func ListenFlag(name, netw, addr, proto string) Listenable
• type Logger
  • func LogLevelFlag(name string) *Logger
  • func V(level int) Logger
  • func (l Logger) Printf(format string, args ...interface{})
• type Privileges
  • func PrivilegesFlag(name, def string) *Privileges
  • func (p *Privileges) Drop() (dropped bool)
• type WaitListener
  • func (w *WaitListener) Accept() (conn net.Conn, err error)
  • func (w *WaitListener) Close() error
  • func (w *WaitListener) File() *os.File
  • func (w *WaitListener) Stop()
  • func (w *WaitListener) Wait()

Variables

var ErrStopped = errors.New("daemon: listener stopped")

ErrStopped is returned when Accept is called on a listener which has been stopped.

var ErrTimeout = errors.New("daemon: timeout")

ErrTimeout is returned when Restart times out.

var LameDuck = 15 * time.Second

LameDuck specifies the duration of the lame duck mode after the listener is closed before the binary exits.

var Lamed = make(chan struct{})

Lamed is a channel which will be closed when the daemon is instructed to shut down via the Shutdown or Restart method.

var LogLevel = Info

LogLevel controls what log messages are written to the log. Only logs destined for an equal or higher level will be written.

var RedirectStdout = true

RedirectStdout will cause anything written to standard output to be also written to the LogFileFlagged file. In particular, when this is true, panic traces and standard uses of the "log" package will find their way into the logfile. Set this to false during init to suppress this behavior.

Functions

func LogFileFlag

func LogFileFlag(name string, mode os.FileMode) **os.File

LogFileFlag registers a flag with the given name which, when set, causes daemon logs to be sent to the given file in addition to standard error. A pointer to the file is also returned, which can be used for a deferred Close in main.

func Restart

func Restart(timeout time.Duration)

Restart re-execs the current process, passing all of the same flags, except that ListenFlags will be replaced with "&fd" to copy the file descriptor from this process. Restart does not return.

func Run

func Run()

Run is the last thing to call from main. It does not return.

Run handles the following signals:

SIGINT    - Calls Shutdown
SIGTERM   - Calls Shutdown
SIGHUP    - Calls Restart
SIGUSR1   - Dumps a stack trace to the logs

If another signal is received during Shutdown or Restart, the process will terminate immediately.

func Shutdown

func Shutdown(timeout time.Duration)

Shutdown closes all ListenFlags and waits for their connections to finish. Shutdown does not return.

Types

type Forker

type Forker interface {
	Fork()
}

A Forker knows how to duplicate the main process by replicating its flags. Fork only returns in the subprocess. The parent process exits, and the child process writes its pid to the pidfile.

func ForkPIDFlags

func ForkPIDFlags(forkFlagName, pidFlagName string, defPIDFile string) Forker

ForkPIDFlags registers two flags, with the given names, and returns a Forker which should be called to manage forking and writing the PID to file.

type Listenable

type Listenable interface {
	Listen() (net.Listener, error)
	String() string
}

A Listenable is something which can listen. It can either be backed by a file descriptor of an existing listener, or if none is available, a new listener. String returns the intended address for the listening socket as a string.

func ListenFlag

func ListenFlag(name, netw, addr, proto string) Listenable

ListenFlag registers a flag, which, when set, causes the returned Listenable to listen on the provided address. If the flag is not provided, the default addr will be used. The given proto is used to create the help text.

type Logger

type Logger int

A Logger is a level-filtered log writer.

const (
	Error Logger = iota
	Warning
	Info
	Verbose

	Exit  Logger = -1
	Fatal Logger = -2
)

Default log levels. Some of these levels have special meanings; see the documentation for Printf.

In the documentation for this package, "higher" log levels correspond to lower numeric values in this list; that is, Error is a higher log level than Verbose.

func LogLevelFlag

func LogLevelFlag(name string) *Logger

LogLevelFlag registers a flag with the given name which, when set, causes only log messages of equal or higher level to be logged. A pointer to the log level chosen is returned.

func V

func V(level int) Logger

V returns a verbose logger at the given level. This should generally be 3 or higher, to avoid collisions with the standard log levels. By default, these will be suppressed unless LogLevel is set or a LogLevelFlag is registered.

func (Logger) Printf

func (l Logger) Printf(format string, args ...interface{})

Printf formats the log message and writes it to the log if the level is sufficient. If the message is directed at Exit or Fatal, the binary will terminate after the log message is written. If the message is directed to Fatal or lower, a stack trace of all goroutines will also be written to the log before exiting. If the logger is Warning or higher, the log will be Sync'd after writing.

type Privileges

type Privileges struct {
	Username string // User to whom to drop privileges
}

A Privileges stores the desired privileges of a process and metadata after they have been dropped.

In the future, this might be extended to also include capabilities.

func PrivilegesFlag

func PrivilegesFlag(name, def string) *Privileges

PrivilegesFlag registers a flag which, when set, will cause the returned Privileges object to drop to the given username. Recommended default value is "nobody".

func (*Privileges) Drop

func (p *Privileges) Drop() (dropped bool)

Drop drops to the configured privileges and returns if any dropping was intended. If dropped privileges (that is, a nonzero Username) were requested but failed, the process aborts for safety reasons.

type WaitListener

type WaitListener struct {
	net.Listener
	// contains filtered or unexported fields
}

A WaitListener is a listener which accepts connections like a normal Listener, but counts them and can Wait for all of them to close.

func (*WaitListener) Accept

func (w *WaitListener) Accept() (conn net.Conn, err error)

Accept is a wrapper around the underlying Listener's accept to facilitate tracking connections.

func (*WaitListener) Close

func (w *WaitListener) Close() error

Close stops and closes the listener; it is an error to close more than once.

func (*WaitListener) File

func (w *WaitListener) File() *os.File

File copies and the listener's underlying file descriptor. This is intended to be used to pass the file descriptor on to a restarted version of this process.

func (*WaitListener) Stop

func (w *WaitListener) Stop()

Stop stops the listener so that it can be used in another process. After Stop, it may be necessary to create a dummy connection to this Listener to fall out of an existing Accept. It is an error to call Stop more than once.

func (*WaitListener) Wait

func (w *WaitListener) Wait()

Wait waits for all associated connections to close.