cerberus

README

Cerberus

Cerberus is a Windows service helper program inspired by NSSM. It can be used to create and manage Windows services for ordinary binaries.

Usage

Help Options:
  -h, --help  Show this help message

Available commands:
  edit      Editing an installed service
  install   Install a binary as service
  list      Show cerberus installed services
  recovery  Editing recovery actions for an installed service
  remove    Removes an installed service
  run       Runs a configured service
  version   Show version

Install

Usage:
  cerberus_64.exe [OPTIONS] install [install-OPTIONS]

Install a binary as service

Help Options:
  -h, --help              Show this help message

[install command options]
      -v, --verbose       Verbose output
      -x, --executable=   Full path to the executable
      -w, --workdir=      Working directory of the executable, if not specified
                          the folder of the executable is used.
      -n, --name=         Name of the service, if not specified name of the
                          executable is used.
      -i, --display-name= Display name of the service, if not specified name of
                          the executable is used.
      -d, --desc=         Description of the service
      -a, --arg=          Arguments to pass to the executable in the same order
                          as specified. (ex. -a "-la" -a "123")
      -e, --env=          Environment variables to set for the executable. (ex.
                          -e "TERM=bash" -e "EDITOR=none")

Edit

Usage:
  cerberus_64.exe [OPTIONS] edit [edit-OPTIONS] SERVICE_NAME

Editing an installed service

Help Options:
  -h, --help                    Show this help message

[edit command options]
      -v, --verbose             Verbose output
      -w, --workdir=            Working directory of the executable..
      -i, --display-name=       Display name of the service.
      -d, --desc=               Description of the service
      -a, --arg=                Arguments to pass to the executable in the same
                                order as specified. (ex. -a "-la" -a "123")
      -e, --env=                Environment variables to set for the
                                executable. (ex. -e "TERM=bash" -e
                                "EDITOR=none")
      -n, --dependencies=       Services on which this service depend on. (ex.
                                -a serviceA -a serviceB)
      -u, --user=               User under which this service will run.
      -p, --password=           Password for the specified service user.
      -s, --start-type=         Service start type. One of
                                [manual|autostart|delayed|disabled]
          --signal-ctrlc        Send Ctrl-C to process if service has to stop.
          --signal-wmquit       Send WM_QUIT to process if service has to stop.
          --signal-wmclose      Send WM_CLOSE to process if service has to stop.
          --no-signal           Restore default behaviour and doesn't send any
                                signals.
          --no-deps             Remove all dependencies for this service.
          --no-args             Remove all arguments for this service.
          --no-env              Remove all environment variables for this
                                service.
          --use-system-account  Use local system account to run this service.

[edit command arguments]
  SERVICE_NAME:                 Name of the service to edit.

Remove

Usage:
  cerberus_64.exe [OPTIONS] remove [remove-OPTIONS] SERVICE_NAME

Removes an installed service

Help Options:
  -h, --help              Show this help message

[remove command options]
      -v, --verbose       Verbose output

[remove command arguments]
  SERVICE_NAME:           Name of the service to remove.

Recovery Actions

Usage:
  cerberus_64.exe [OPTIONS] recovery set [set-OPTIONS] SERVICE_NAME ARGUMENTS...

Set a recovery action for an installed service

Help Options:
  -h, --help              Show this help message

[set command options]
      -v, --verbose       Verbose output
      -e, --exit-code=    Exit code to handle by this action.
      -a, --action=       Action to take if an error occurred. One of
                          [run-restart|none|restart|run]
      -d, --delay=        Delay restart of the program in seconds. (default: 0)
      -r, --max-restart=  Maximum restarts of the service within the specified
                          time span. Zero means unlimited restarts. (default: 0)
      -c, --reset-timer=  Specify the duration in seconds after which the
                          restart counter will be cleared. (default: 0)
      -x, --exec=         Specify the program to run if an error occurred.

[set command arguments]
  SERVICE_NAME:           Name of the service to set a recovery action.
  ARGUMENTS:              Arguments for the program to run if an error
                          occurred. Use '--' after SERVICE_NAME to specify
                          arguments starting with '-'.

Usage:
  cerberus_64.exe [OPTIONS] recovery del [del-OPTIONS] SERVICE_NAME EXIT_CODE

Deletes a recovery action for an installed service

Help Options:
  -h, --help              Show this help message

[del command options]
      -v, --verbose       Verbose output

[del command arguments]
  SERVICE_NAME:           Name of the service to delete a recovery action.
  EXIT_CODE:              Exit code for which the recovery action should be
                          deleted.                    

Example

This is a minimal example:

cerberus_64.exe install -x "C:\Windows\notepad.exe" -n "MySuperService"

Caveat: The cerberus_64.exe must not be moved after installation of a service, otherwise the service won't work anymore.

Build

Requirments:

• Go >= 1.13 https://golang.org/
• GoVersionInfo https://github.com/josephspurrier/goversioninfo

Change into the cmd directory and run the following command:

C:\repo\cerberus\cmd> build.bat

Documentation

Overview

Package cerberus is a Windows service helper program inspired by [NSSM](https://nssm.cc/). It can be used to create and manage Windows services for ordinary binaries.

Index

• Variables
• func InstallService(config SvcConfig) error
• func RemoveService(name string) error
• func RemoveServiceCfg(name string) error
• func RunService(name string) error
• func UpdateService(config SvcConfig) error
• type Error
  • func (e Error) Error() string
  • func (e Error) Is(target error) bool
  • func (e Error) Unwrap(err error) error
• type ErrorCode
• type RecoveryAction
• type StartType
• type StopSignal
  • func (s StopSignal) String() string
• type SvcConfig
  • func LoadServiceCfg(name string) (cfg *SvcConfig, err error)
  • func LoadServicesCfg() (svcs []*SvcConfig, err error)
• type SvcRecoveryAction

Variables

var DebugLogger = log.New(ioutil.Discard, "Cerberus: ", 0)

DebugLogger logs all debug information, per default ioutil.Discard is used and no output is generated.

var Logger = log.New(os.Stdout, "Cerberus: ", 0)

Logger is the default logger for cerberus. Per default os.Stdout is used.

Functions

func InstallService

func InstallService(config SvcConfig) error

InstallService installs a windows service with the given configuration.

func RemoveService

func RemoveService(name string) error

RemoveService removes the service with the given name. Stops the service first, can return a timeout error if it can't stop the service.

func RemoveServiceCfg

func RemoveServiceCfg(name string) error

RemoveServiceCfg removes the service configuration form the cerberus service db. It returns a generic error if call fails.

func RunService

func RunService(name string) error

RunService runs the service with the given name.

func UpdateService

func UpdateService(config SvcConfig) error

UpdateService updates a cerberus service with the given configuration.

Types

type Error

type Error struct {
	Code    ErrorCode
	Message string
	// contains filtered or unexported fields
}

Error is a cerberus specific error.

func (Error) Error

func (e Error) Error() string

Error implements the error interface.

func (Error) Is

func (e Error) Is(target error) bool

Is implements the errors.Is interface.

func (Error) Unwrap

func (e Error) Unwrap(err error) error

Unwrap implements the errors.Unwrap interface.

type ErrorCode

type ErrorCode int

ErrorCode cerberus unique error codes.

const (

	// ErrGeneric indicates a general error.
	ErrGeneric ErrorCode
	// ErrSaveServiceCfg indicates error while saving the service configuration.
	ErrSaveServiceCfg
	// ErrLoadServiceCfg indicates error while loading the service configuration.
	ErrLoadServiceCfg
	// ErrInstallService indicates error while installing a service.
	ErrInstallService
	// ErrUpdateService indicates error while updating a service.
	ErrUpdateService
	// ErrInvalidConfiguration indicates error while validating service configuration.
	ErrInvalidConfiguration
	// ErrRemoveService indicates error while removing a service.
	ErrRemoveService
	// ErrRunService indicates error while running a service.
	ErrRunService
	// ErrTimeout indicates an action run into a timeout.
	ErrTimeout
	// ErrSCMConnect indicates a failure while connecting to the SCM.
	ErrSCMConnect
)

type RecoveryAction

type RecoveryAction int

RecoveryAction defines what happens if a binary exits with error

const (
	// NoAction is the default action and will stop the service on error.
	NoAction RecoveryAction = 1 << iota
	// RestartAction restarts the serivce according the specified settings.
	RestartAction
	// RunProgramAction will run the specified program.
	RunProgramAction

	// RunAndRestartAction restarts the service and runs the specified program.
	RunAndRestartAction = RestartAction | RunProgramAction
)

type StartType

type StartType uint32

StartType configures the startup type.

const (
	// AutoStartType configures the service to startup automatically.
	AutoStartType StartType = 2
	// AutoDelayedStartType configures the service to startup automatically with delay.
	AutoDelayedStartType StartType = 9999
	// ManualStartType configures the service for manual startup.
	ManualStartType StartType = 3
	// DisabledStartType disables the service.
	DisabledStartType StartType = 4
)

type StopSignal

type StopSignal int

StopSignal specifies a signal to send to a process if the service has to stop.

const (
	CtrlCSignal StopSignal = 1 << iota
	WmQuitSignal
	WmCloseSignal

	NoSignal StopSignal = 0
)

Signals to send to a process to gracefully terminate a process. WmQuit and WmClose signal works only for application with a window.

func (StopSignal) String

func (s StopSignal) String() string

type SvcConfig

type SvcConfig struct {
	// Base configuration
	Name        string
	Desc        string
	DisplayName string
	ExePath     string
	WorkDir     string
	Args        []string
	Env         []string

	// Extended Configurations
	RecoveryActions map[int]SvcRecoveryAction
	StopSignal      StopSignal

	// SCM Properties (Admin rights require to load this properties)
	Dependencies []string
	ServiceUser  string
	Password     *string
	StartType    StartType
}

SvcConfig is the data required run the executable as a service.

func LoadServiceCfg

func LoadServiceCfg(name string) (cfg *SvcConfig, err error)

LoadServiceCfg loads a service configuration for a given service from the cerberus service db.

func LoadServicesCfg

func LoadServicesCfg() (svcs []*SvcConfig, err error)

LoadServicesCfg loads all configured services.

type SvcRecoveryAction

type SvcRecoveryAction struct {
	ExitCode    int
	Action      RecoveryAction
	Delay       int
	MaxRestarts int
	ResetAfter  time.Duration
	Program     string
	Arguments   []string
}

SvcRecoveryAction defines what cerberus should do if a binary returns an error.