C.3 /programs

A request sent to this URI selects one or more components and applies operation defined by the request type to all of them.

Components are selected using a query in the form of JSON object (a selector). Valid selectors are:

‘null’

‘false’

Matches nothing.

‘true’

Matches all components.

‘{ "op": "component", "arg": tag }’

Matches component with the given tag (see tag).

‘{ "op": "type", "arg": "component" }’

Matches all components.

‘{ "op": "type", "arg": "command" }’

Matches all commands.

‘{ "op": "mode", "arg": mode }’

Matches all components with the given mode. See component mode.

‘{ "op": "active" }’

Matches all active components.

‘{ "op": "status", "arg": status }’

Matches all components with the given status (one of ‘stopped’, ‘running’, ‘listener’, ‘sleeping’, ‘stopping’, ‘finished’). See component status for a discussion of these values.

‘{ "op: "not", "arg": condition }’

Negates condition, which is any valid selector.

‘{ "op": "and", "arg": array }’

Returns the result of logical conjunction on the array of selectors.

‘{ "op": "or", "arg": array }’

Returns the result of logical disjunction on the array of selectors.

For example, the following selector matches all components that are in ‘running’ state, excepting components of ‘inetd’ mode:

{ "op": "and",
   "arg": [ { "op": "type", "arg": "component" },
            { "op": "not", "arg": { "op": "mode", "arg": "inetd" }
          ]
}

The following requests are supported:

Request: GET /programs?selector

Request: GET /programs/tag

This request returns information about components matched by selector (see below for the ‘/programs/tag variant’. The response is a JSON array of descriptions. If no component matches the selector, empty array is returned. Each description is a JSON object with the following attributes:

Attr: string type

Type of the described entity: ‘component’ for an instance of a configured component, and ‘command’ for a command run as a part of exit action (see Exit Actions), including mailer invocations (see Notification).

Attr: string mode

Mode of the entity. See component mode.

Attr: string status

Entity status. Possible values are:

finished

A ‘once’ or ‘startup’ component has finished.

listener

Component is an inetd listener.

running

Component is running.

sleeping

Component has been put to sleep because of excessive number of failures (see respawn).

stopped

Component is stopped.

stopping

Component is being stopped (a SIGTERM was sent).

Attr: boolean active

Whether this component is active. By default, all components are active, unless marked with a ‘disable’ flag (see flags) or administratively stopped.

Attr: integer PID

PID of the running process.

Attr: string URL

(for ‘inetd’ components) URL of the socket the component is listening on.

Attr: string service

(for ‘tcpmux’ components) TCPMUX service name. See TCPMUX.

Attr: string master

(for ‘tcpmux’ components) Tag of master TCPMUX component. See TCPMUX.

Attr: string runlevels

For inittab components, the string of runlevels this component is configured to run in. See Init Process.

Attr: integer wakeup-time

If component is in the ‘sleeping’ state, this attribute gives the number of seconds after which an attempt will be made to restart it.

Attr: array argv

Component command line split into words.

Attr: string command

Component command.

Request: DELETE /programs?selector

Request: DELETE /programs/tag

Stop components matched by the selector. On success returns:

{ "status":"OK" }

On failure, returns

{ "status":"ER", "message": text }

where text is a textual human-readable description of the failure.

Request: PUT /programs?selector

Request: PUT /programs/tag

Start components matched by selector.

Request: POST /programs

Restart components. The selector is supplied in the request content.

Wherever a selector is passed via query parameters, a simplified form with component tag passed as query path is also allowed. For example:

 GET /programs/tag

is a shortcut for:

{ "op":"and",
   "arg":[ {"op":"type", "arg":"component"},
           {"op":"component", "arg":tag } ] }