service

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 29, 2016 License: Zlib, MIT Imports: 13 Imported by: 0

README

service

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.

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.

BUGS

  • Dependencies field is not implemented for Linux systems and Launchd.
  • OS X when running as a UserService Interactive will not be accurate.

Documentation

Overview

Package service provides a simple way to create a system service. Currently supports Windows, Linux/(systemd | Upstart | SysV), and OSX/Launchd.

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.

Examples in the example/ folder. 

package main

import (
	"log"

	"github.com/kardianos/service"
)

var logger service.Logger

type program struct{}

func (p *program) Start(s service.Service) error {
	// Start should not block. Do the actual work async.
	go p.run()
	return nil
}
func (p *program) run() {
	// Do work here
}
func (p *program) Stop(s service.Service) error {
	// Stop should not block. Return with a few seconds.
	return nil
}

func main() {
	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)
	}
	logger, err = s.Logger(nil)
	if err != nil {
		log.Fatal(err)
	}
	err = s.Run()
	if err != nil {
		logger.Error(err)
	}
}

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNameFieldRequired is returned when Conifg.Name is empty.
	ErrNameFieldRequired = errors.New("Config.Name field is required.")
	// ErrNoServiceSystemDetected is returned when no system was detected.
	ErrNoServiceSystemDetected = errors.New("No service system detected.")
	// ErrServiceIsNotInstalled is returned when the service is not installed
	ErrServiceIsNotInstalled = errors.New("Service is not installed.")
	// ErrServiceIsNotRunning is returned when the service is not running
	ErrServiceIsNotRunning = errors.New("Service is not running.")
)
View Source 
var ConsoleLogger = consoleLogger{}

ConsoleLogger logs to the std err.

View Source 
var ControlAction = [6]string{"start", "stop", "restart", "install", "uninstall", "status"}

ControlAction list valid string texts to use in Control.

Functions

func ChooseSystem 

func ChooseSystem(a ...System)

ChooseSystem chooses a system from the given system services. SystemServices are considered in the order they are suggested. Calling this may change what Interactive and Platform return.

func Control 

func Control(s Service, action string) error

Control issues control functions to the service from a given action string.

func Interactive 

func Interactive() bool

Interactive returns false if running under the OS service manager and true otherwise.

func Platform 

func Platform() string

Platform returns a description of the system service.

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.

	// Optional field to specify the executable for service.
	// If empty the current executable is used.
	Executable string

	// Array of service dependencies.
	// Not yet implemented on Linux or OS X.
	Dependencies []string

	// The following fields are not supported on Windows.
	WorkingDirectory string // Initial working directory.
	ChRoot           string

	// System specific options.
	//  * OS X
	//    - KeepAlive     bool (true)
	//    - RunAtLoad     bool (false)
	//    - UserService   bool (false) - Install as a current user service.
	//    - SessionCreate bool (false) - Create a full user session.
	//  * POSIX
	//    - RunWait      func() (wait for SIGNAL) - Do not install signal but wait for this function to return.
	//    - ReloadSignal string () [USR1, ...] - Signal to send on reaload.
	//    - PIDFile     string () [/run/prog.pid] - Location of the PID file.
	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.

  1. OS service manager executes user program.
  2. User program sees it is executed from a service manager (IsInteractive is false).
  3. User program calls Service.Run() which blocks.
  4. Interface.Start() is called and quickly returns.
  5. User program runs.
  6. OS service manager signals the user program to stop.
  7. Interface.Stop() is called and quickly returns. - For a successful exit, os.Exit should not be called in Interface.Stop().
  8. Service.Run returns.
  9. 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

	// Status returns nil if the given service is running.
	// Will return an error if the service is not running or is not present.
	Status() 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.

func New 

func New(i Interface, c *Config) (Service, error)

New creates a new service based on a service interface and configuration.

type System 

type System interface {
	// String returns a description of the system.
	String() string

	// Detect returns true if the system is available to use.
	Detect() bool

	// Interactive returns false if running under the system service manager
	// and true otherwise.
	Interactive() bool

	// New creates a new service for this system.
	New(i Interface, c *Config) (Service, error)
}

System represents the service manager that is available.

func AvailableSystems 

func AvailableSystems() []System

AvailableSystems returns the list of system services considered when choosing the system service.

func ChosenSystem 

func ChosenSystem() System

ChosenSystem returns the system that service will use.

type WindowsLogger 

type WindowsLogger struct {
	// contains filtered or unexported fields
}

WindowsLogger allows using windows specific logging methods.

func (WindowsLogger) Error 

func (l WindowsLogger) Error(v ...interface{}) error

Error logs an error message.

func (WindowsLogger) Errorf 

func (l WindowsLogger) Errorf(format string, a ...interface{}) error

Errorf logs an error message.

func (WindowsLogger) Info 

func (l WindowsLogger) Info(v ...interface{}) error

Info logs an info message.

func (WindowsLogger) Infof 

func (l WindowsLogger) Infof(format string, a ...interface{}) error

Infof logs an info message.

func (WindowsLogger) NError 

func (l WindowsLogger) NError(eventID uint32, v ...interface{}) error

NError logs an error message and an event ID.

func (WindowsLogger) NErrorf 

func (l WindowsLogger) NErrorf(eventID uint32, format string, a ...interface{}) error

NErrorf logs an error message and an event ID.

func (WindowsLogger) NInfo 

func (l WindowsLogger) NInfo(eventID uint32, v ...interface{}) error

NInfo logs an info message and an event ID.

func (WindowsLogger) NInfof 

func (l WindowsLogger) NInfof(eventID uint32, format string, a ...interface{}) error

NInfof logs an info message and an event ID.

func (WindowsLogger) NWarning 

func (l WindowsLogger) NWarning(eventID uint32, v ...interface{}) error

NWarning logs an warning message and an event ID.

func (WindowsLogger) NWarningf 

func (l WindowsLogger) NWarningf(eventID uint32, format string, a ...interface{}) error

NWarningf logs an warning message and an event ID.

func (WindowsLogger) Warning 

func (l WindowsLogger) Warning(v ...interface{}) error

Warning logs an warning message.

func (WindowsLogger) Warningf 

func (l WindowsLogger) Warningf(format string, a ...interface{}) error

Warningf logs an warning message.

Source Files

View all Source files

Directories

Path Synopsis
example
logging
Simple service that only works by printing a log message every few seconds.
 Simple service that only works by printing a log message every few seconds.
runner
Simple service that only works by printing a log message every few seconds.
 Simple service that only works by printing a log message every few seconds.
simple
simple does nothing except block while running the service.
 simple does nothing except block while running the service.
stopPause
simple does nothing except block while running the service.
 simple does nothing except block while running the service.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.