• DBusInterface

• BR	Until 1.0, the Upstart D-Bus Interface is considered unstable and subject to change. Before making any calls to a running init daemon, you should first retrieve the value of the version property.BRBRCompatible versions:BRinit (upstart 0.6.0)

Connecting to Upstart

The init daemon is available on the system bus with the well-known name com.ubuntu.Upstart, this is the preferred method for applications to communicate with the daemon since the D-Bus security policy allows non-superusers to request read-only information.

Since the D-Bus system bus daemon may not always be available, the initctl, telinit and shutdown utilities included with Upstart use an alternate method. It is not recommended that most software use this, however there may be situations in which it is useful. A private D-Bus connection to the address unix:abstract=/com/ubuntu/upstart may be made, no well-known name is required. The same objects as published on the system bus are available from this connection, however access is for superusers only.

Manager object

The manager object is the primary communication point for the init daemon. One of the primary uses for the manager object is to look up jobs by name, or enumerate all of the jobs. The secondary use is the emission of events.

Methods

com.ubuntu.Upstart.GetJobByName

com.ubuntu.Upstart.GetJobByName (in String name,
                                 out ObjectPath job)

Looks up a job by name, returning the path of the job object. The job object represents the on disk configuration of a job, not a running instance, however the running instances are obtained from the job objects. See Job objects below.

While it's technically possible to extrapolate the path of a job object from its name, you should not do this as the encoding is always subject to change. Always use this method instead.

Errors

com.ubuntu.Upstart.Error.UnknownJob: the job name given was not known.

com.ubuntu.Upstart.GetAllJobs

com.ubuntu.Upstart.GetAllJobs (out <Array of ObjectPath> jobs)

Returns a list of all currently registered job objects. Job objects represent the on disk configuration of a job, not a running instance, however the running instances are obtained from the job objects. See Job objects below.

com.ubuntu.Upstart.EmitEvent

com.ubuntu.Upstart.EmitEvent (in String name,
                              in <Array of String> env,
                              in Boolean wait)

Causes an event to be emitted, which may result in jobs automatically starting and stopping. The event name should be provided, along with an array of strings containing KEY=VALUE pairs denoting the accompanying environment for the event. These environment variables will be exported into any jobs started or stopped by the event.

When wait is TRUE, this method call will not return until all side-effects of the event (services finishing starting, tasks finishing running, jobs stopping) have completed. When wait is FALSE, the method call will return once Upstart has queued the event.

Signals

com.ubuntu.Upstart.JobAdded

com.ubuntu.Upstart.JobAdded (ObjectPath job)

This signal is emitted when a new job object is registered. The job object represents the on disk configuration of a job, not a running instance, however the running instances are obtained from the job objects. See Job objects below.

You tend to see this signal when a configuration file is created or changed.

com.ubuntu.Upstart.JobRemoved

com.ubuntu.Upstart.JobRemoved (ObjectPath job)

This signal is emitted when a job object is unregistered. The job object represents the on disk configuration of a job, not a running instance, however the running instances are obtained from the job objects. See Job objects below.

You tend to see this signal when a configuration file is changed or deleted.

Properties

com.ubuntu.Upstart.version

READ String com.ubuntu.Upstart.version

This property contains the version of the init daemon as a string. Since the D-Bus interface is unstable, you should retrieve the value of this property before communicating.

com.ubuntu.Upstart.log_priority

READWRITE String com.ubuntu.Upstart.log_priority

This property may be used to change the priority of log messages that Upstart will output to the system log, it may also be used to obtain the current setting. Valid values are fatal, error, warn, message, info and debug.

Job objects

Job objects represent the configuration of a job, not the running instances, however the running instances are obtained from the job objects.

Methods

com.ubuntu.Upstart.Job.GetInstance

com.ubuntu.Upstart.Job.GetInstance (in <Array of String> env
                                    out ObjectPath instance)

Looks up an instance by the environment with which it was started, returning the path of the instance object. The instance object represents a running instance of a job. See Instance objects below.

This is possible because Upstart generates the name of an instance from the environment; this is actually the preferred method of looking up instances.

com.ubuntu.Upstart.Job.GetInstanceByName

com.ubuntu.Upstart.Job.GetInstanceByName (in String name,
                                          out ObjectPath instance)

Looks up an instance by name, returning the path of the instance object. The instance object represents a running instance of a job. See Instance objects below.

While it's technically possible to extrapolate the path of a instance object from its name, you should not do this as the encoding is always subject to change. Always use this method instead.

Errors

com.ubuntu.Upstart.Error.UnknownInstance: the instance name given was not known.

com.ubuntu.Upstart.Job.GetAllInstances

com.ubuntu.Upstart.Job.GetAllInstances (out <Array of ObjectPath> instances)

Returns a list of all currently registered job objects. Instance object represent running instances of a job. See Instance objects below.

com.ubuntu.Upstart.Job.Start

com.ubuntu.Upstart.Job.Start (in <Array of String> env,
                              in Boolean wait,
                              out ObjectPath instance)

Starts a new instance of the job, or restarts an existing stopping instance of the job, based on the env argument which should be an array of strings containing KEY=VALUE pairs denoting the accompanying environment for the job.

When wait is TRUE, this method call will not return until the job has finished (services finishing starting, tasks finishing running). When wait is FALSE, the method call will return once Upstart has queued the command.

The object path of the instance object is returned.

com.ubuntu.Upstart.Job.Stop

com.ubuntu.Upstart.Job.Stop (in <Array of String> env,
                             in Boolean wait)

Stops an existing instance of the job based on the env argument which should be an array of strings containing KEY=VALUE pairs denoting the accompanying environment for the job.

When wait is TRUE, this method call will not return until the job has been stopped. When wait is FALSE, the method call will return once Upstart has queued the command.

com.ubuntu.Upstart.Job.Restart

com.ubuntu.Upstart.Job.Restart (in <Array of String> env,
                                in Boolean wait,
                                out ObjectPath instance)

Restarts an existing instance of the job based on the env argument which should be an array of strings containing KEY=VALUE pairs denoting the accompanying environment for the job.

When wait is TRUE, this method call will not return until the job has been restarted. When wait is FALSE, the method call will return once Upstart has queued the command.

This will not cause a new instance to start, it only restarts an existing instance.

Signals

com.ubuntu.Upstart.Job.InstanceAdded

com.ubuntu.Upstart.Job.InstanceAdded (ObjectPath instance)

This signal is emitted when a new job instance is created. The instance object represents a running instance of a job. See Instance objects below.

You tend to see this signal when a job is started for the first time.

com.ubuntu.Upstart.Job.InstanceRemoved

com.ubuntu.Upstart.Job.InstanceRemoved (ObjectPath instance)

This signal is emitted when a job instance is destroyed. The instance object represents a running instance of a job. See Instance objects below.

You tend to see this signal when a job is stopped.

Properties

com.ubuntu.Upstart.Job.name

READ String com.ubuntu.Upstart.Job.name

com.ubuntu.Upstart.Job.description

READ String com.ubuntu.Upstart.Job.description

com.ubuntu.Upstart.Job.author

READ String com.ubuntu.Upstart.Job.author

com.ubuntu.Upstart.Job.version

READ String com.ubuntu.Upstart.Job.version

Instance objects

Instance objects represent the running instances of a job; beware that if there are no running instances, there will be no instance objects.

Methods

com.ubuntu.Upstart.Instance.Start

com.ubuntu.Upstart.Instance.Start (in Boolean wait)

com.ubuntu.Upstart.Instance.Stop

com.ubuntu.Upstart.Instance.Stop (in Boolean wait)

com.ubuntu.Upstart.Instance.Restart

com.ubuntu.Upstart.Instance.Restart (in Boolean wait)

Signals

Properties

com.ubuntu.Upstart.Instance.name

READ String com.ubuntu.Upstart.Instance.name

com.ubuntu.Upstart.Instance.goal

READ String com.ubuntu.Upstart.Instance.goal

com.ubuntu.Upstart.Instance.state

READ String com.ubuntu.Upstart.Instance.state

com.ubuntu.Upstart.Instance.processes

READ <Array of Struct<String Int32>> com.ubuntu.Upstart.Instance.processes

-- CategoryDoc