godaemon

README

godaemon

Daemonize Go applications with exec() instead of fork(). Read our blog post on the subject.

You can't daemonize the usual way in Go. Daemonizing is a Unix concept that requires some specific things you can't do easily in Go. But you can still accomplish the same goals if you don't mind that your program will start copies of itself several times, as opposed to using fork() the way many programmers are accustomed to doing.

It is somewhat controversial whether it's even a good idea to make programs daemonize themselves, or how to do it correctly (and whether it's even possible to do correctly in Go). Read here, here, and here for more on this topic. However, at VividCortex we do need to run one of our processes as a daemon with the usual attributes of a daemon, and we chose the approach implemented in this package.

Because of the factors mentioned in the first link just given, you should take great care when using this package's approach. It works for us, because we don't do anything like starting up goroutines in our init() functions, or other things that are perfectly legal in Go in general.

Getting Started

View the package documentation for details about how it works. Briefly, to make your program into a daemon, do the following as soon as possible in your main() function:

import (
	"github.com/VividCortex/godaemon"
)

func main() {
	godaemon.MakeDaemon(&godaemon.DaemonAttr{})
}

Use the CaptureOutput attribute if you need to capture your program's standard output and standard error streams. In that case, the function returns two valid readers (io.Reader) that you can read from the program itself. That's particularly useful for functions that write error or diagnosis messages right to the error output, which are normally lost in a daemon.

Contribute

Contributions are welcome. Please open pull requests or issue reports!

License

This repository is Copyright (c) 2013 VividCortex, Inc. All rights reserved. It is licensed under the MIT license. Please see the LICENSE file for applicable license terms.

Authors

The primary author is Gustavo Kristic, with some documentation and other minor contributions by others at VividCortex.

History

An earlier version of this concept with a slightly different interface was developed internally at VividCortex.

Cats

A Go Daemon is a good thing, and so we present an angelic cat picture:

Documentation

Overview

Package godaemon runs a program as a Unix daemon.

Index

• func Daemonize(child ...bool)
• func GetExecutablePath() (string, error)
• func MakeDaemon(attrs *DaemonAttr) (io.Reader, io.Reader, error)
• type DaemonAttr

Functions

func Daemonize

func Daemonize(child ...bool)

Daemonize is equivalent to MakeDaemon(&DaemonAttr{}). It is kept only for backwards API compatibility, but it's usage is otherwise discouraged. Use MakeDaemon() instead. The child parameter, previously used to tell whether to reset the environment or not (see MakeDaemon()), is currently ignored. The environment is reset in all cases.

func GetExecutablePath

func GetExecutablePath() (string, error)

GetExecutablePath returns the absolute path to the currently running executable. It is used internally by the godaemon package, and exported publicly because it's useful outside of the package too.

func MakeDaemon

func MakeDaemon(attrs *DaemonAttr) (io.Reader, io.Reader, error)

MakeDaemon turns the process into a daemon. But given the lack of Go's support for fork(), MakeDaemon() is forced to run the process all over again, from the start. Hence, this should probably be your first call after main begins, unless you understand the effects of calling from somewhere else. Keep in mind that the PID changes after this function is called, given that it only returns in the child; the parent will exit without returning.

Options are provided as a DaemonAttr structure. In particular, setting the CaptureOutput member to true will make the function return two io.Reader streams to read the process' standard output and standard error, respectively. That's useful if you want to capture things you'd normally lose given the lack of console output for a daemon. Some libraries can write error conditions to standard error or make use of Go's log package, that defaults to standard error too. Having these streams allows you to capture them as required. (Note that this function takes no action whatsoever on any of the streams.)

NOTE: If you use them, make sure NOT to take one of these readers and write the data back again to standard output/error, or you'll end up with a loop.

Daemonizing is a 3-stage process. In stage 0, the program increments the magical environment variable and starts a copy of itself that's a session leader, with its STDIN, STDOUT, and STDERR disconnected from any tty. It then exits.

In stage 1, the (new copy of) the program starts another copy that's not a session leader, and then exits.

In stage 2, the (new copy of) the program chdir's to /, then sets the umask and reestablishes the original value for the environment variable.

Types

type DaemonAttr

type DaemonAttr struct {
	CaptureOutput bool // whether to capture stdout/stderr
}

DaemonAttr describes the options that apply to daemonization