dbus

Documentation

Overview

Integration with the systemd D-Bus API. See http://www.freedesktop.org/wiki/Software/systemd/dbus/

Index

• type Conn
  • func New() (*Conn, error)
  • func (c *Conn) EnableUnitFiles(files []string, runtime bool, force bool) (bool, []EnableUnitFileChange, error)
  • func (c *Conn) GetUnitInfo(path dbus.ObjectPath) (map[string]dbus.Variant, error)
  • func (c *Conn) KillUnit(name string, signal int32)
  • func (c *Conn) ListUnits() ([]UnitStatus, error)
  • func (c *Conn) ReloadOrRestartUnit(name string, mode string) (string, error)
  • func (c *Conn) ReloadOrTryRestartUnit(name string, mode string) (string, error)
  • func (c *Conn) ReloadUnit(name string, mode string) (string, error)
  • func (c *Conn) RestartUnit(name string, mode string) (string, error)
  • func (c *Conn) SetSubStateSubscriber(updateCh chan<- *SubStateUpdate, errCh chan<- error)
  • func (c *Conn) StartTransientUnit(name string, mode string, properties ...Property) (string, error)
  • func (c *Conn) StartUnit(name string, mode string) (string, error)
  • func (c *Conn) StopUnit(name string, mode string) (string, error)
  • func (c *Conn) SubscribeUnits(interval time.Duration) (<-chan map[string]*UnitStatus, <-chan error)
  • func (c *Conn) SubscribeUnitsCustom(interval time.Duration, buffer int, ...) (<-chan map[string]*UnitStatus, <-chan error)
  • func (c *Conn) TryRestartUnit(name string, mode string) (string, error)
• type EnableUnitFileChange
• type Property
  • func PropAfter(units ...string) Property
  • func PropBefore(units ...string) Property
  • func PropBindsTo(units ...string) Property
  • func PropBoundBy(units ...string) Property
  • func PropConflictedBy(units ...string) Property
  • func PropConflicts(units ...string) Property
  • func PropDescription(desc string) Property
  • func PropExecStart(command []string, uncleanIsFailure bool) Property
  • func PropOnFailure(units ...string) Property
  • func PropPropagatesReloadTo(units ...string) Property
  • func PropRemainAfterExit(b bool) Property
  • func PropRequiredBy(units ...string) Property
  • func PropRequiredByOverridable(units ...string) Property
  • func PropRequires(units ...string) Property
  • func PropRequiresMountsFor(units ...string) Property
  • func PropRequiresOverridable(units ...string) Property
  • func PropRequisite(units ...string) Property
  • func PropRequisiteOverridable(units ...string) Property
  • func PropTriggeredBy(units ...string) Property
  • func PropTriggers(units ...string) Property
  • func PropWantedBy(units ...string) Property
  • func PropWants(units ...string) Property
• type SubStateUpdate
• type UnitStatus

Types

type Conn

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

func New

func New() (*Conn, error)

func (*Conn) EnableUnitFiles

func (c *Conn) EnableUnitFiles(files []string, runtime bool, force bool) (bool, []EnableUnitFileChange, error)

EnableUnitFiles() may be used to enable one or more units in the system (by creating symlinks to them in /etc or /run).

It takes a list of unit files to enable (either just file names or full absolute paths if the unit files are residing outside the usual unit search paths), and two booleans: the first controls whether the unit shall be enabled for runtime only (true, /run), or persistently (false, /etc). The second one controls whether symlinks pointing to other units shall be replaced if necessary.

This call returns one boolean and an array with the changes made. The boolean signals whether the unit files contained any enablement information (i.e. an [Install]) section. The changes list consists of structures with three strings: the type of the change (one of symlink or unlink), the file name of the symlink and the destination of the symlink.

func (*Conn) GetUnitInfo

func (c *Conn) GetUnitInfo(path dbus.ObjectPath) (map[string]dbus.Variant, error)

func (*Conn) KillUnit

func (c *Conn) KillUnit(name string, signal int32)

KillUnit takes the unit name and a UNIX signal number to send. All of the unit's processes are killed.

func (*Conn) ListUnits

func (c *Conn) ListUnits() ([]UnitStatus, error)

ListUnits returns an array with all currently loaded units. Note that units may be known by multiple names at the same time, and hence there might be more unit names loaded than actual units behind them.

func (*Conn) ReloadOrRestartUnit

func (c *Conn) ReloadOrRestartUnit(name string, mode string) (string, error)

ReloadOrRestart attempts a reload if the unit supports it and use a restart otherwise.

func (*Conn) ReloadOrTryRestartUnit

func (c *Conn) ReloadOrTryRestartUnit(name string, mode string) (string, error)

ReloadOrTryRestart attempts a reload if the unit supports it and use a "Try" flavored restart otherwise.

func (*Conn) ReloadUnit

func (c *Conn) ReloadUnit(name string, mode string) (string, error)

ReloadUnit reloads a unit. Reloading is done only if the unit is already running and fails otherwise.

func (*Conn) RestartUnit

func (c *Conn) RestartUnit(name string, mode string) (string, error)

RestartUnit restarts a service. If a service is restarted that isn't running it will be started.

func (*Conn) SetSubStateSubscriber

func (c *Conn) SetSubStateSubscriber(updateCh chan<- *SubStateUpdate, errCh chan<- error)

SetSubStateSubscriber writes to updateCh when any unit's substate changes. Althrough this writes to updateCh on every state change, the reported state may be more recent than the change that generated it (due to an unavoidable race in the systemd dbus interface). That is, this method provides a good way to keep a current view of all units' states, but is not guaranteed to show every state transition they go through. Furthermore, state changes will only be written to the channel with non-blocking writes. If updateCh is full, it attempts to write an error to errCh; if errCh is full, the error passes silently.

func (*Conn) StartTransientUnit

func (c *Conn) StartTransientUnit(name string, mode string, properties ...Property) (string, error)

StartTransientUnit() may be used to create and start a transient unit, which will be released as soon as it is not running or referenced anymore or the system is rebooted. name is the unit name including suffix, and must be unique. mode is the same as in StartUnit(), properties contains properties of the unit.

func (*Conn) StartUnit

func (c *Conn) StartUnit(name string, mode string) (string, error)

StartUnit enqeues a start job and depending jobs, if any (unless otherwise specified by the mode string).

Takes the unit to activate, plus a mode string. The mode needs to be one of replace, fail, isolate, ignore-dependencies, ignore-requirements. If "replace" the call will start the unit and its dependencies, possibly replacing already queued jobs that conflict with this. If "fail" the call will start the unit and its dependencies, but will fail if this would change an already queued job. If "isolate" the call will start the unit in question and terminate all units that aren't dependencies of it. If "ignore-dependencies" it will start a unit but ignore all its dependencies. If "ignore-requirements" it will start a unit but only ignore the requirement dependencies. It is not recommended to make use of the latter two options.

Result string: one of done, canceled, timeout, failed, dependency, skipped. done indicates successful execution of a job. canceled indicates that a job has been canceled before it finished execution. timeout indicates that the job timeout was reached. failed indicates that the job failed. dependency indicates that a job this job has been depending on failed and the job hence has been removed too. skipped indicates that a job was skipped because it didn't apply to the units current state.

func (*Conn) StopUnit

func (c *Conn) StopUnit(name string, mode string) (string, error)

StopUnit is similar to StartUnit but stops the specified unit rather than starting it.

func (*Conn) SubscribeUnits

func (c *Conn) SubscribeUnits(interval time.Duration) (<-chan map[string]*UnitStatus, <-chan error)

Returns two unbuffered channels which will receive all changed units every @interval@ seconds. Deleted units are sent as nil.

func (*Conn) SubscribeUnitsCustom

func (c *Conn) SubscribeUnitsCustom(interval time.Duration, buffer int, isChanged func(*UnitStatus, *UnitStatus) bool) (<-chan map[string]*UnitStatus, <-chan error)

SubscribeUnitsCustom is like SubscribeUnits but lets you specify the buffer size of the channels and the comparison function for detecting changes.

func (*Conn) TryRestartUnit

func (c *Conn) TryRestartUnit(name string, mode string) (string, error)

TryRestartUnit is like RestartUnit, except that a service that isn't running is not affected by the restart.

type EnableUnitFileChange

type EnableUnitFileChange struct {
	Type        string // Type of the change (one of symlink or unlink)
	Filename    string // File name of the symlink
	Destination string // Destination of the symlink
}

type Property

type Property struct {
	Name  string
	Value dbus.Variant
}

func PropAfter

func PropAfter(units ...string) Property

PropAfter sets the After unit property. See http://www.freedesktop.org/software/systemd/man/systemd.unit.html#After=

func PropBefore

func PropBefore(units ...string) Property

PropBefore sets the Before unit property. See http://www.freedesktop.org/software/systemd/man/systemd.unit.html#Before=

func PropBindsTo

func PropBindsTo(units ...string) Property

PropBindsTo sets the BindsTo unit property. See http://www.freedesktop.org/software/systemd/man/systemd.unit.html#BindsTo=

func PropBoundBy

func PropBoundBy(units ...string) Property

PropBoundBy sets the BoundBy unit property. See http://www.freedesktop.org/software/systemd/main/systemd.unit.html#BoundBy=

func PropConflictedBy

func PropConflictedBy(units ...string) Property

PropConflictedBy sets the ConflictedBy unit property. See http://www.freedesktop.org/software/systemd/man/systemd.unit.html#ConflictedBy=

func PropConflicts

func PropConflicts(units ...string) Property

PropConflicts sets the Conflicts unit property. See http://www.freedesktop.org/software/systemd/man/systemd.unit.html#Conflicts=

func PropDescription

func PropDescription(desc string) Property

PropDescription sets the Description unit property. See http://www.freedesktop.org/software/systemd/man/systemd.unit#Description=

func PropExecStart

func PropExecStart(command []string, uncleanIsFailure bool) Property

PropExecStart sets the ExecStart service property. The first argument is a slice with the binary path to execute followed by the arguments to pass to the executed command. See http://www.freedesktop.org/software/systemd/man/systemd.service.html#ExecStart=

func PropOnFailure

func PropOnFailure(units ...string) Property

PropOnFailure sets the OnFailure unit property. See http://www.freedesktop.org/software/systemd/man/systemd.unit.html#OnFailure=

func PropPropagatesReloadTo

func PropPropagatesReloadTo(units ...string) Property

PropPropagatesReloadTo sets the PropagatesReloadTo unit property. See http://www.freedesktop.org/software/systemd/man/systemd.unit.html#PropagatesReloadTo=

func PropRemainAfterExit

func PropRemainAfterExit(b bool) Property

PropRemainAfterExit sets the RemainAfterExit service property. See http://www.freedesktop.org/software/systemd/man/systemd.service.html#RemainAfterExit=

func PropRequiredBy

func PropRequiredBy(units ...string) Property

PropRequiredBy sets the RequiredBy unit property. See http://www.freedesktop.org/software/systemd/man/systemd.unit.html#RequiredBy=

func PropRequiredByOverridable

func PropRequiredByOverridable(units ...string) Property

PropRequiredByOverridable sets the RequiredByOverridable unit property. See http://www.freedesktop.org/software/systemd/man/systemd.unit.html#RequiredByOverridable=

func PropRequires

func PropRequires(units ...string) Property

PropRequires sets the Requires unit property. See http://www.freedesktop.org/software/systemd/man/systemd.unit.html#Requires=

func PropRequiresMountsFor

func PropRequiresMountsFor(units ...string) Property

PropRequiresMountsFor sets the RequiresMountsFor unit property. See http://www.freedesktop.org/software/systemd/man/systemd.unit.html#RequiresMountsFor=

func PropRequiresOverridable

func PropRequiresOverridable(units ...string) Property

PropRequiresOverridable sets the RequiresOverridable unit property. See http://www.freedesktop.org/software/systemd/man/systemd.unit.html#RequiresOverridable=

func PropRequisite

func PropRequisite(units ...string) Property

PropRequisite sets the Requisite unit property. See http://www.freedesktop.org/software/systemd/man/systemd.unit.html#Requisite=

func PropRequisiteOverridable

func PropRequisiteOverridable(units ...string) Property

PropRequisiteOverridable sets the RequisiteOverridable unit property. See http://www.freedesktop.org/software/systemd/man/systemd.unit.html#RequisiteOverridable=

func PropTriggeredBy

func PropTriggeredBy(units ...string) Property

PropTriggeredBy sets the TriggeredBy unit property. See http://www.freedesktop.org/software/systemd/man/systemd.unit.html#TriggeredBy=

func PropTriggers

func PropTriggers(units ...string) Property

PropTriggers sets the Triggers unit property. See http://www.freedesktop.org/software/systemd/man/systemd.unit.html#Triggers=

func PropWantedBy

func PropWantedBy(units ...string) Property

PropWantedBy sets the WantedBy unit property. See http://www.freedesktop.org/software/systemd/man/systemd.unit.html#WantedBy=

func PropWants

func PropWants(units ...string) Property

PropWants sets the Wants unit property. See http://www.freedesktop.org/software/systemd/man/systemd.unit.html#Wants=

type SubStateUpdate

type SubStateUpdate struct {
	UnitName string
	SubState string
}

type UnitStatus

type UnitStatus struct {
	Name        string          // The primary unit name as string
	Description string          // The human readable description string
	LoadState   string          // The load state (i.e. whether the unit file has been loaded successfully)
	ActiveState string          // The active state (i.e. whether the unit is currently started or not)
	SubState    string          // The sub state (a more fine-grained version of the active state that is specific to the unit type, which the active state is not)
	Followed    string          // A unit that is being followed in its state by this unit, if there is any, otherwise the empty string.
	Path        dbus.ObjectPath // The unit object path
	JobId       uint32          // If there is a job queued for the job unit the numeric job id, 0 otherwise
	JobType     string          // The job type as string
	JobPath     dbus.ObjectPath // The job object path
}