README
¶
service (BETA)
service will install / un-install, start / stop, and run a program as a service (daemon). Currently supports Windows XP+, Linux/(systemd | Upstart | SysV), and OSX/Launchd.
moved to https://github.com/kardianos/service
Windows controls services by setting up callbacks that is non-trivial. This is very different then other systems. This package provides the same API despite the substantial differences. It also can be used to detect how a program is called, from an interactive terminal or from a service manager.
TODO
Need to test the Interactive test for the following platforms:
- SysV
- systemd system and user service
- Launchd system and user service
The following items need to be done:
- Determine if systemd has a launchd equivalent user service.
- Fix Interactive test for user services.
- Document that windows doesn't have a user service.
- Document that upstart's user service definition changes over versions. Do not support.
- For Linux platforms and Launchd add:
- UserName
- Arguments
- WorkingDirectory
- ChRoot
- Determine the best way to document the Config.Option values per platform.
- Should some of the current parameters like "ChRoot" and "WorkingDirectory" move to "Option" map?
Documentation
¶
Overview ¶
Package service provides a simple way to create a system service. Currently supports Windows, Linux/(systemd | Upstart | SysV), and OSX/Launchd.
moved to github.com/kardianos/service
Windows controls services by setting up callbacks that is non-trivial. This is very different then other systems. This package provides the same API despite the substantial differences. It also can be used to detect how a program is called, from an interactive terminal or from a service manager.
// Simple service that only works by printing a log message every few seconds.
package main
import (
"flag"
"log"
"time"
"bitbucket.org/kardianos/service2beta"
)
var logger service.Logger
// Program structures.
// Define Start and Stop methods.
type program struct {
exit chan struct{}
}
func (p *program) Start(s service.Service) error {
if service.Interactive() {
logger.Info("Running in terminal.")
} else {
logger.Info("Running under service manager.")
}
p.exit = make(chan struct{})
// Start should not block. Do the actual work async.
go p.run()
return nil
}
func (p *program) run() error {
logger.Infof("I'm running %v.", service.Platform())
ticker := time.NewTicker(2 * time.Second)
for {
select {
case tm := <-ticker.C:
logger.Infof("Still running at %v...", tm)
case <-p.exit:
ticker.Stop()
return nil
}
}
return nil
}
func (p *program) Stop(s service.Service) error {
// Any work in Stop should be quick, usually a few seconds at most.
logger.Info("I'm Stopping!")
close(p.exit)
return nil
}
// Service setup.
// Define service config.
// Create the service.
// Setup the logger.
// Handle service controls (optional).
// Run the service.
func main() {
svcFlag := flag.String("service", "", "Control the system service.")
flag.Parse()
svcConfig := &service.Config{
Name: "GoServiceTest",
DisplayName: "Go Service Test",
Description: "This is a test Go service.",
}
prg := &program{}
s, err := service.New(prg, svcConfig)
if err != nil {
log.Fatal(err)
}
errs := make(chan error, 5)
logger, err = s.Logger(errs)
if err != nil {
log.Fatal(err)
}
go func() {
for {
err := <-errs
if err != nil {
log.Print(err)
}
}
}()
if len(*svcFlag) != 0 {
err := service.Control(s, *svcFlag)
if err != nil {
log.Printf("Valid actions: %q\n", service.ControlAction)
log.Fatal(err)
}
return
}
err = s.Run()
if err != nil {
logger.Error(err)
}
}
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ConsoleLogger = consoleLogger{}
ConsoleLogger logs to the std err.
var ControlAction = [5]string{"start", "stop", "restart", "install", "uninstall"}
ControlAction list valid string texts to use in Control.
Functions ¶
func Interactive ¶
func Interactive() bool
Interactive returns false if running under the OS service manager and true otherwise.
Types ¶
type Config ¶
type Config struct {
Name string // Required name of the service. No spaces suggested.
DisplayName string // Display name, spaces allowed.
Description string // Long description of service.
UserName string // Run as username.
Arguments []string // Run with arguments.
WorkingDirectory string // Service working directory.
ChRoot string
UserService bool // Install as a current user service.
// System specific options.
Option KeyValue
}
Config provides the setup for a Service. The Name field is required.
type Interface ¶
type Interface interface {
// Start provides a place to initiate the service. The service doesn't not
// signal a completed start until after this function returns, so the
// Start function must not take more then a few seconds at most.
Start(s Service) error
// Stop provides a place to clean up program execution before it is terminated.
// It should not take more then a few seconds to execute.
// Stop should not call os.Exit directly in the function.
Stop(s Service) error
}
Interface represents the service interface for a program. Start runs before the hosting process is granted control and Stop runs when control is returned.
- OS service manager executes user program.
- User program sees it is executed from a service manager (IsInteractive is false).
- User program calls Service.Run() which blocks.
- Interface.Start() is called and quickly returns.
- User program runs.
- OS service manager signals the user program to stop.
- Interface.Stop() is called and quickly returns. - For a successful exit, os.Exit should not be called in Interface.Stop().
- Service.Run returns.
- User program should quickly exit.
type KeyValue ¶
type KeyValue map[string]interface{}
KeyValue provides a list of platform specific options. See platform docs for more details.
type Logger ¶
type Logger interface {
Error(v ...interface{}) error
Warning(v ...interface{}) error
Info(v ...interface{}) error
Errorf(format string, a ...interface{}) error
Warningf(format string, a ...interface{}) error
Infof(format string, a ...interface{}) error
}
Logger writes to the system log.
type Service ¶
type Service interface {
// Run should be called shortly after the program entry point.
// After Interface.Stop has finished running, Run will stop blocking.
// After Run stops blocking, the program must exit shortly after.
Run() error
// Start signals to the OS service manager the given service should start.
Start() error
// Stop signals to the OS service manager the given service should stop.
Stop() error
// Restart signals to the OS service manager the given service should stop then start.
Restart() error
// Install setups up the given service in the OS service manager. This may require
// greater rights. Will return an error if it is already installed.
Install() error
// Uninstall removes the given service from the OS service manager. This may require
// greater rights. Will return an error if the service is not present.
Uninstall() error
// Opens and returns a system logger. If the user program is running
// interactively rather then as a service, the returned logger will write to
// os.Stderr. If errs is non-nil errors will be sent on errs as well as
// returned from Logger's functions.
Logger(errs chan<- error) (Logger, error)
// SystemLogger opens and returns a system logger. If errs is non-nil errors
// will be sent on errs as well as returned from Logger's functions.
SystemLogger(errs chan<- error) (Logger, error)
// String displays the name of the service. The display name if present,
// otherwise the name.
String() string
}
Service represents a service that can be run or controlled.
Source Files
Directories