mgr

Documentation

Overview

Package mgr can be used to manage Windows service programs. It can be used to install and remove them. It can also start, stop and pause them. The package can query / change current service state and config parameters.

Index

• Constants
• type Config
• type LockStatus
• type Mgr
  • func Connect() (*Mgr, error)
  • func ConnectRemote(host string) (*Mgr, error)
  • func (m *Mgr) CreateService(name, exepath string, c Config, args ...string) (*Service, error)
  • func (m *Mgr) Disconnect() error
  • func (m *Mgr) ListServices() ([]string, error)
  • func (m *Mgr) LockStatus() (*LockStatus, error)
  • func (m *Mgr) OpenService(name string) (*Service, error)
• type RecoveryAction
• type Service
  • func (s *Service) Close() error
  • func (s *Service) Config() (Config, error)
  • func (s *Service) Control(c svc.Cmd) (svc.Status, error)
  • func (s *Service) Delete() error
  • func (s *Service) ListDependentServices(status svc.ActivityStatus) ([]string, error)
  • func (s *Service) Query() (svc.Status, error)
  • func (s *Service) RebootMessage() (string, error)
  • func (s *Service) RecoveryActions() ([]RecoveryAction, error)
  • func (s *Service) RecoveryActionsOnNonCrashFailures() (bool, error)
  • func (s *Service) RecoveryCommand() (string, error)
  • func (s *Service) ResetPeriod() (uint32, error)
  • func (s *Service) ResetRecoveryActions() error
  • func (s *Service) SetRebootMessage(msg string) error
  • func (s *Service) SetRecoveryActions(recoveryActions []RecoveryAction, resetPeriod uint32) error
  • func (s *Service) SetRecoveryActionsOnNonCrashFailures(flag bool) error
  • func (s *Service) SetRecoveryCommand(cmd string) error
  • func (s *Service) Start(args ...string) error
  • func (s *Service) UpdateConfig(c Config) error

Constants

const (
	// Service start types.
	StartManual    = windows.SERVICE_DEMAND_START // the service must be started manually
	StartAutomatic = windows.SERVICE_AUTO_START   // the service will start by itself whenever the computer reboots
	StartDisabled  = windows.SERVICE_DISABLED     // the service cannot be started

	// The severity of the error, and action taken,
	// if this service fails to start.
	ErrorCritical = windows.SERVICE_ERROR_CRITICAL
	ErrorIgnore   = windows.SERVICE_ERROR_IGNORE
	ErrorNormal   = windows.SERVICE_ERROR_NORMAL
	ErrorSevere   = windows.SERVICE_ERROR_SEVERE
)

const (
	// Possible recovery actions that the service control manager can perform.
	NoAction       = windows.SC_ACTION_NONE        // no action
	ComputerReboot = windows.SC_ACTION_REBOOT      // reboot the computer
	ServiceRestart = windows.SC_ACTION_RESTART     // restart the service
	RunCommand     = windows.SC_ACTION_RUN_COMMAND // run a command
)

Types

type Config

type Config struct {
	ServiceType      uint32
	StartType        uint32
	ErrorControl     uint32
	BinaryPathName   string // fully qualified path to the service binary file, can also include arguments for an auto-start service
	LoadOrderGroup   string
	TagId            uint32
	Dependencies     []string
	ServiceStartName string // name of the account under which the service should run
	DisplayName      string
	Password         string
	Description      string
	SidType          uint32 // one of SERVICE_SID_TYPE, the type of sid to use for the service
	DelayedAutoStart bool   // the service is started after other auto-start services are started plus a short delay
}

type LockStatus

type LockStatus struct {
	IsLocked bool          // Whether the SCM has been locked.
	Age      time.Duration // For how long the SCM has been locked.
	Owner    string        // The name of the user who has locked the SCM.
}

type Mgr

type Mgr struct {
	Handle windows.Handle
}

Mgr is used to manage Windows service.

func Connect

func Connect() (*Mgr, error)

Connect establishes a connection to the service control manager.

func ConnectRemote

func ConnectRemote(host string) (*Mgr, error)

ConnectRemote establishes a connection to the service control manager on computer named host.

func (*Mgr) CreateService

func (m *Mgr) CreateService(name, exepath string, c Config, args ...string) (*Service, error)

CreateService installs new service name on the system. The service will be executed by running exepath binary. Use config c to specify service parameters. Any args will be passed as command-line arguments when the service is started; these arguments are distinct from the arguments passed to Service.Start or via the "Start parameters" field in the service's Properties dialog box.

func (*Mgr) Disconnect

func (m *Mgr) Disconnect() error

Disconnect closes connection to the service control manager m.

func (*Mgr) ListServices

func (m *Mgr) ListServices() ([]string, error)

ListServices enumerates services in the specified service control manager database m. If the caller does not have the SERVICE_QUERY_STATUS access right to a service, the service is silently omitted from the list of services returned.

func (*Mgr) LockStatus

func (m *Mgr) LockStatus() (*LockStatus, error)

LockStatus returns whether the service control manager is locked by the system, for how long, and by whom. A locked SCM indicates that most service actions will block until the system unlocks the SCM.

func (*Mgr) OpenService

func (m *Mgr) OpenService(name string) (*Service, error)

OpenService retrieves access to service name, so it can be interrogated and controlled.

type RecoveryAction

type RecoveryAction struct {
	Type  int           // one of NoAction, ComputerReboot, ServiceRestart or RunCommand
	Delay time.Duration // the time to wait before performing the specified action
}

RecoveryAction represents an action that the service control manager can perform when service fails. A service is considered failed when it terminates without reporting a status of SERVICE_STOPPED to the service controller.

type Service

type Service struct {
	Name   string
	Handle windows.Handle
}

Service is used to access Windows service.

func (*Service) Close

func (s *Service) Close() error

Close relinquish access to the service s.

func (*Service) Config

func (s *Service) Config() (Config, error)

Config retrieves service s configuration paramteres.

func (*Service) Control

func (s *Service) Control(c svc.Cmd) (svc.Status, error)

Control sends state change request c to the service s. It returns the most recent status the service reported to the service control manager, and an error if the state change request was not accepted. Note that the returned service status is only set if the status change request succeeded, or if it failed with error ERROR_INVALID_SERVICE_CONTROL, ERROR_SERVICE_CANNOT_ACCEPT_CTRL, or ERROR_SERVICE_NOT_ACTIVE.

func (*Service) Delete

func (s *Service) Delete() error

Delete marks service s for deletion from the service control manager database.

func (*Service) ListDependentServices

func (s *Service) ListDependentServices(status svc.ActivityStatus) ([]string, error)

ListDependentServices returns the names of the services dependent on service s, which match the given status.

func (*Service) Query

func (s *Service) Query() (svc.Status, error)

Query returns current status of service s.

func (*Service) RebootMessage

func (s *Service) RebootMessage() (string, error)

RebootMessage is broadcast to server users before rebooting in response to the ComputerReboot service controller action.

func (*Service) RecoveryActions

func (s *Service) RecoveryActions() ([]RecoveryAction, error)

RecoveryActions returns actions that service controller performs when service fails. The service control manager counts the number of times service s has failed since the system booted. The count is reset to 0 if the service has not failed for ResetPeriod seconds. When the service fails for the Nth time, the service controller performs the action specified in element [N-1] of returned slice. If N is greater than slice length, the service controller repeats the last action in the slice.

func (*Service) RecoveryActionsOnNonCrashFailures

func (s *Service) RecoveryActionsOnNonCrashFailures() (bool, error)

RecoveryActionsOnNonCrashFailures returns the current value of the failure actions flag. If the flag is set to false, recovery actions will only be performed if the service terminates without reporting a status of SERVICE_STOPPED. If the flag is set to true, recovery actions are also perfomed if the service stops with a nonzero exit code.

func (*Service) RecoveryCommand

func (s *Service) RecoveryCommand() (string, error)

RecoveryCommand is the command line of the process to execute in response to the RunCommand service controller action. This process runs under the same account as the service.

func (*Service) ResetPeriod

func (s *Service) ResetPeriod() (uint32, error)

ResetPeriod is the time after which to reset the service failure count to zero if there are no failures, in seconds.

func (*Service) ResetRecoveryActions

func (s *Service) ResetRecoveryActions() error

ResetRecoveryActions deletes both reset period and array of failure actions.

func (*Service) SetRebootMessage

func (s *Service) SetRebootMessage(msg string) error

SetRebootMessage sets service s reboot message. If msg is "", the reboot message is deleted and no message is broadcast.

func (*Service) SetRecoveryActions

func (s *Service) SetRecoveryActions(recoveryActions []RecoveryAction, resetPeriod uint32) error

SetRecoveryActions sets actions that service controller performs when service fails and the time after which to reset the service failure count to zero if there are no failures, in seconds. Specify INFINITE to indicate that service failure count should never be reset.

func (*Service) SetRecoveryActionsOnNonCrashFailures

func (s *Service) SetRecoveryActionsOnNonCrashFailures(flag bool) error

SetRecoveryActionsOnNonCrashFailures sets the failure actions flag. If the flag is set to false, recovery actions will only be performed if the service terminates without reporting a status of SERVICE_STOPPED. If the flag is set to true, recovery actions are also perfomed if the service stops with a nonzero exit code.

func (*Service) SetRecoveryCommand

func (s *Service) SetRecoveryCommand(cmd string) error

SetRecoveryCommand sets the command line of the process to execute in response to the RunCommand service controller action. If cmd is "", the command is deleted and no program is run when the service fails.

func (*Service) Start

func (s *Service) Start(args ...string) error

Start starts service s. args will be passed to svc.Handler.Execute.

func (*Service) UpdateConfig

func (s *Service) UpdateConfig(c Config) error

UpdateConfig updates service s configuration parameters.