# XML-RPC API Documentation

To use the XML-RPC interface, first make sure you have configured the interface factory properly by setting the default factory. See Configuring XML-RPC Interface Factories.

Then you can connect to supervisor’s HTTP port with any XML-RPC client library and run commands against it.

An example of doing this using Python 2’s `xmlrpclib` client library is as follows.

    import xmlrpclib
    server = xmlrpclib.Server('http://localhost:9001/RPC2')

An example of doing this using Python 3’s `xmlrpc.client` library is as follows.

    from xmlrpc.client import ServerProxy
    server = ServerProxy('http://localhost:9001/RPC2')

You may call methods against supervisord and its subprocesses by using the `supervisor` namespace. An example is provided below.

    server.supervisor.getState()

You can get a list of methods supported by the supervisord XML-RPC interface by using the XML-RPC `system.listMethods` API:

    server.system.listMethods()

You can see help on a method by using the `system.methodHelp` API against the method:

    server.system.methodHelp('supervisor.shutdown')

The supervisord XML-RPC interface also supports the XML-RPC multicall API.

You can extend supervisord functionality with new XML-RPC API methods by adding new top-level RPC interfaces as necessary. See Configuring XML-RPC Interface Factories.

Note

Any XML-RPC method call may result in a fault response. This includes errors caused by the client such as bad arguments, and any errors that make supervisord unable to fulfill the request. Many XML-RPC client programs will raise an exception when a fault response is encountered.

## Status and Control

> class supervisor.rpcinterface.SupervisorNamespaceRPCInterface(supervisord)
>   getAPIVersion()

>     Return the version of the RPC API used by supervisord

>     @return string version id

>     This API is versioned separately from Supervisor itself. The API version returned by `getAPIVersion` only changes when the API changes. Its purpose is to help the client identify with which version of the Supervisor API it is communicating.

>     When writing software that communicates with this API, it is highly recommended that you first test the API version for compatibility before making method calls.

>     Note

>     The `getAPIVersion` method replaces `getVersion` found in Supervisor versions prior to 3.0a1. It is aliased for compatibility but getVersion() is deprecated and support will be dropped from Supervisor in a future version.

>   getSupervisorVersion()

>     Return the version of the supervisor package in use by supervisord

>     @return string version id

>   getIdentification()

>     Return identifying string of supervisord

>     @return string identifier identifying string

>     This method allows the client to identify with which Supervisor instance it is communicating in the case of environments where multiple Supervisors may be running.

>     The identification is a string that must be set in Supervisor’s configuration file. This method simply returns that value back to the client.

>   getState()

>     Return current state of supervisord as a struct

>     @return struct A struct with keys int statecode, string statename

>     This is an internal value maintained by Supervisor that determines what Supervisor believes to be its current operational state.

>     Some method calls can alter the current state of the Supervisor. For example, calling the method supervisor.shutdown() while the station is in the RUNNING state places the Supervisor in the SHUTDOWN state while it is shutting down.

>     The supervisor.getState() method provides a means for the client to check Supervisor’s state, both for informational purposes and to ensure that the methods it intends to call will be permitted.

>     The return value is a struct:

>         {'statecode': 1,
>          'statename': 'RUNNING'}

>     The possible return values are:

>     statecode | statename | Description
>     --- | --- | ---
>     2 | FATAL | Supervisor has experienced a serious error.
>     1 | RUNNING | Supervisor is working normally.
>     0 | RESTARTING | Supervisor is in the process of restarting.
>     -1 | SHUTDOWN | Supervisor is in the process of shutting down.

>     The `FATAL` state reports unrecoverable errors, such as internal errors inside Supervisor or system runaway conditions. Once set to `FATAL`, the Supervisor can never return to any other state without being restarted.

>     In the `FATAL` state, all future methods except supervisor.shutdown() and supervisor.restart() will automatically fail without being called and the fault `FATAL_STATE` will be raised.

>     In the `SHUTDOWN` or `RESTARTING` states, all method calls are ignored and their possible return values are undefined.

>   getPID()

>     Return the PID of supervisord

>     @return int PID

>   readLog(offset, length)

>     Read length bytes from the main log starting at offset

>     @param int offset offset to start reading from. @param int length number of bytes to read from the log. @return string result Bytes of log

>     It can either return the entire log, a number of characters from the tail of the log, or a slice of the log specified by the offset and length parameters:

>     Offset | Length | Behavior of `readProcessLog`
>     --- | --- | ---
>     Negative | Not Zero | Bad arguments. This will raise the fault `BAD_ARGUMENTS`.
>     Negative | Zero | This will return the tail of the log, or offset number of characters from the end of the log. For example, if `offset` = -4 and `length` = 0, then the last four characters will be returned from the end of the log.
>     Zero or Positive | Negative | Bad arguments. This will raise the fault `BAD_ARGUMENTS`.
>     Zero or Positive | Zero | All characters will be returned from the `offset` specified.
>     Zero or Positive | Positive | A number of characters length will be returned from the `offset`.

>     If the log is empty and the entire log is requested, an empty string is returned.

>     If either offset or length is out of range, the fault `BAD_ARGUMENTS` will be returned.

>     If the log cannot be read, this method will raise either the `NO_FILE` error if the file does not exist or the `FAILED` error if any other problem was encountered.

>     Note

>     The readLog() method replaces readMainLog() found in Supervisor versions prior to 2.1. It is aliased for compatibility but readMainLog() is deprecated and support will be dropped from Supervisor in a future version.

>   clearLog()

>     Clear the main log.

>     @return boolean result always returns True unless error

>     If the log cannot be cleared because the log file does not exist, the fault `NO_FILE` will be raised. If the log cannot be cleared for any other reason, the fault `FAILED` will be raised.

>   shutdown()

>     Shut down the supervisor process

>     @return boolean result always returns True unless error

>     This method shuts down the Supervisor daemon. If any processes are running, they are automatically killed without warning.

>     Unlike most other methods, if Supervisor is in the `FATAL` state, this method will still function.

>   restart()

>     Restart the supervisor process

>     @return boolean result always return True unless error

>     This method soft restarts the Supervisor daemon. If any processes are running, they are automatically killed without warning. Note that the actual UNIX process for Supervisor cannot restart; only Supervisor’s main program loop. This has the effect of resetting the internal states of Supervisor.

>     Unlike most other methods, if Supervisor is in the `FATAL` state, this method will still function.

## Process Control

> class supervisor.rpcinterface.SupervisorNamespaceRPCInterface(supervisord)
>   getProcessInfo(name)

>     Get info about a process named name

>     @param string name The name of the process (or ‘group:name’) @return struct result A structure containing data about the process

>     The return value is a struct:

>         {'name':           'process name',
>          'group':          'group name',
>          'description':    'pid 18806, uptime 0:03:12'
>          'start':          1200361776,
>          'stop':           0,
>          'now':            1200361812,
>          'state':          20,
>          'statename':      'RUNNING',
>          'spawnerr':       '',
>          'exitstatus':     0,
>          'logfile':        '/path/to/stdout-log', # deprecated, b/c only
>          'stdout_logfile': '/path/to/stdout-log',
>          'stderr_logfile': '/path/to/stderr-log',
>          'pid':            1}

>     name

>       Name of the process

>     group

>       Name of the process’ group

>     description

>       If process state is running description’s value is process_id and uptime. Example “pid 18806, uptime 0:03:12 “. If process state is stopped description’s value is stop time. Example:”Jun 5 03:16 PM “.

>     start

>       UNIX timestamp of when the process was started

>     stop

>       UNIX timestamp of when the process last ended, or 0 if the process has never been stopped.

>     now

>       UNIX timestamp of the current time, which can be used to calculate process up-time.

>     state

>       State code, see Process States.

>     statename

>       String description of state, see Process States.

>     logfile

>       Deprecated alias for `stdout_logfile`. This is provided only for compatibility with clients written for Supervisor 2.x and may be removed in the future. Use `stdout_logfile` instead.

>     stdout_logfile

>       Absolute path and filename to the STDOUT logfile

>     stderr_logfile

>       Absolute path and filename to the STDERR logfile

>     spawnerr

>       Description of error that occurred during spawn, or empty string if none.

>     exitstatus

>       Exit status (errorlevel) of process, or 0 if the process is still running.

>     pid

>       UNIX process ID (PID) of the process, or 0 if the process is not running.

>   getAllProcessInfo()

>     Get info about all processes

>     @return array result An array of process status results

>     Each element contains a struct, and this struct contains the exact same elements as the struct returned by `getProcessInfo`. If the process table is empty, an empty array is returned.

>   getAllConfigInfo()

>     Get info about all available process configurations. Each struct represents a single process (i.e. groups get flattened).

>     @return array result An array of process config info structs

>   startProcess(name, wait=True)

>     Start a process

>     @param string name Process name (or `group:name`, or `group:*`) @param boolean wait Wait for process to be fully started @return boolean result Always true unless error

>   startAllProcesses(wait=True)

>     Start all processes listed in the configuration file

>     @param boolean wait Wait for each process to be fully started @return array result An array of process status info structs

>   startProcessGroup(name, wait=True)

>     Start all processes in the group named ‘name’

>     @param string name The group name @param boolean wait Wait for each process to be fully started @return array result An array of process status info structs

>   stopProcess(name, wait=True)

>     Stop a process named by name

>     @param string name The name of the process to stop (or ‘group:name’) @param boolean wait Wait for the process to be fully stopped @return boolean result Always return True unless error

>   stopProcessGroup(name, wait=True)

>     Stop all processes in the process group named ‘name’

>     @param string name The group name @param boolean wait Wait for each process to be fully stopped @return array result An array of process status info structs

>   stopAllProcesses(wait=True)

>     Stop all processes in the process list

>     @param boolean wait Wait for each process to be fully stopped @return array result An array of process status info structs

>   signalProcess(name, signal)

>     Send an arbitrary UNIX signal to the process named by name

>     @param string name Name of the process to signal (or ‘group:name’) @param string signal Signal to send, as name (‘HUP’) or number (‘1’) @return boolean

>   signalProcessGroup(name, signal)

>     Send a signal to all processes in the group named ‘name’

>     @param string name The group name @param string signal Signal to send, as name (‘HUP’) or number (‘1’) @return array

>   signalAllProcesses(signal)

>     Send a signal to all processes in the process list

>     @param string signal Signal to send, as name (‘HUP’) or number (‘1’) @return array An array of process status info structs

>   sendProcessStdin(name, chars)

>     Send a string of chars to the stdin of the process name. If non-7-bit data is sent (unicode), it is encoded to utf-8 before being sent to the process’ stdin. If chars is not a string or is not unicode, raise INCORRECT_PARAMETERS. If the process is not running, raise NOT_RUNNING. If the process’ stdin cannot accept input (e.g. it was closed by the child process), raise NO_FILE.

>     @param string name The process name to send to (or ‘group:name’) @param string chars The character data to send to the process @return boolean result Always return True unless error

>   sendRemoteCommEvent(type, data)

>     Send an event that will be received by event listener subprocesses subscribing to the RemoteCommunicationEvent.

>     @param string type String for the “type” key in the event header @param string data Data for the event body @return boolean Always return True unless error

>   reloadConfig()

>     Reload the configuration.

>     The result contains three arrays containing names of process groups:

>     - added gives the process groups that have been added

>     - changed gives the process groups whose contents have changed

>     - removed gives the process groups that are no longer in the configuration

>     @return array result [[added, changed, removed]]

>   addProcessGroup(name)

>     Update the config for a running process from config file.

>     @param string name name of process group to add @return boolean result true if successful

>   removeProcessGroup(name)

>     Remove a stopped process from the active configuration.

>     @param string name name of process group to remove @return boolean result Indicates whether the removal was successful

## Process Logging

> class supervisor.rpcinterface.SupervisorNamespaceRPCInterface(supervisord)
>   readProcessStdoutLog(name, offset, length)

>     Read length bytes from name’s stdout log starting at offset

>     @param string name the name of the process (or ‘group:name’) @param int offset offset to start reading from. @param int length number of bytes to read from the log. @return string result Bytes of log

>   readProcessStderrLog(name, offset, length)

>     Read length bytes from name’s stderr log starting at offset

>     @param string name the name of the process (or ‘group:name’) @param int offset offset to start reading from. @param int length number of bytes to read from the log. @return string result Bytes of log

>   tailProcessStdoutLog(name, offset, length)

>     Provides a more efficient way to tail the (stdout) log than readProcessStdoutLog(). Use readProcessStdoutLog() to read chunks and tailProcessStdoutLog() to tail.

>     Requests (length) bytes from the (name)’s log, starting at (offset). If the total log size is greater than (offset + length), the overflow flag is set and the (offset) is automatically increased to position the buffer at the end of the log. If less than (length) bytes are available, the maximum number of available bytes will be returned. (offset) returned is always the last offset in the log +1.

>     @param string name the name of the process (or ‘group:name’) @param int offset offset to start reading from @param int length maximum number of bytes to return @return array result [string bytes, int offset, bool overflow]

>   tailProcessStderrLog(name, offset, length)

>     Provides a more efficient way to tail the (stderr) log than readProcessStderrLog(). Use readProcessStderrLog() to read chunks and tailProcessStderrLog() to tail.

>     Requests (length) bytes from the (name)’s log, starting at (offset). If the total log size is greater than (offset + length), the overflow flag is set and the (offset) is automatically increased to position the buffer at the end of the log. If less than (length) bytes are available, the maximum number of available bytes will be returned. (offset) returned is always the last offset in the log +1.

>     @param string name the name of the process (or ‘group:name’) @param int offset offset to start reading from @param int length maximum number of bytes to return @return array result [string bytes, int offset, bool overflow]

>   clearProcessLogs(name)

>     Clear the stdout and stderr logs for the named process and reopen them.

>     @param string name The name of the process (or ‘group:name’) @return boolean result Always True unless error

>   clearAllProcessLogs()

>     Clear all process log files

>     @return array result An array of process status info structs

## System Methods

> class supervisor.xmlrpc.SystemNamespaceRPCInterface(namespaces)
>   listMethods()

>     Return an array listing the available method names

>     @return array result An array of method names available (strings).

>   methodHelp(name)

>     Return a string showing the method’s documentation

>     @param string name The name of the method. @return string result The documentation for the method name.

>   methodSignature(name)

>     Return an array describing the method signature in the form [rtype, ptype, ptype…] where rtype is the return data type of the method, and ptypes are the parameter data types that the method accepts in method argument order.

>     @param string name The name of the method. @return array result The result.

>   multicall(calls)

>     Process an array of calls, and return an array of results. Calls should be structs of the form {‘methodName’: string, ‘params’: array}. Each result will either be a single-item array containing the result value, or a struct of the form {‘faultCode’: int, ‘faultString’: string}. This is useful when you need to make lots of small calls without lots of round trips.

>     @param array calls An array of call requests @return array result An array of results