242 lines
7.9 KiB
ReStructuredText
242 lines
7.9 KiB
ReStructuredText
.. _sec-api-system:
|
|
|
|
******
|
|
System
|
|
******
|
|
|
|
.. note::
|
|
|
|
All system operations require admin rights.
|
|
|
|
.. _sec-api-system-command-list:
|
|
|
|
List all registered system commands
|
|
===================================
|
|
|
|
.. http:get:: /api/system/commands
|
|
|
|
Retrieves all configured system commands.
|
|
|
|
A :http:statuscode:`200` with a :ref:`List all response <sec-api-system-commands-listall>`
|
|
will be returned.
|
|
|
|
**Example**
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /api/system/commands/core HTTP/1.1
|
|
Host: example.com
|
|
X-Api-Key: abcdef...
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 Ok
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"core": [
|
|
{
|
|
"action": "shutdown",
|
|
"name": "Shutdown",
|
|
"command": "sudo shutdown -h now",
|
|
"confirm": "<b>You are about to shutdown the system.</b></p><p> This action may disrupt any ongoing print jobs (depending on your printer's controller and general setup that might also apply to prints run directly from your printer's internal storage).",
|
|
"async": true,
|
|
"ignore": true,
|
|
"source": "core",
|
|
"resource": "http://example.com/api/system/commands/core/shutdown"
|
|
},
|
|
{
|
|
"action": "reboot",
|
|
"name": "Reboot",
|
|
"command": "sudo reboot",
|
|
"confirm": "<b>You are about to reboot the system.</b></p><p> This action may disrupt any ongoing print jobs (depending on your printer's controller and general setup that might also apply to prints run directly from your printer's internal storage).",
|
|
"async": true,
|
|
"ignore": true,
|
|
"source": "core",
|
|
"resource": "http://example.com/api/system/commands/core/reboot"
|
|
},
|
|
{
|
|
"action": "restart",
|
|
"name": "Restart OctoPrint",
|
|
"command": "sudo service octoprint restart",
|
|
"confirm": "<b>You are about to restart the OctoPrint server.</b></p><p> This action may disrupt any ongoing print jobs (depending on your printer's controller and general setup that might also apply to prints run directly from your printer's internal storage).",
|
|
"async": true,
|
|
"ignore": true,
|
|
"source": "core",
|
|
"resource": "http://example.com/api/system/commands/core/restart"
|
|
}
|
|
],
|
|
"custom": []
|
|
}
|
|
|
|
:statuscode 200: No error
|
|
|
|
.. _sec-api-system-command-listsource:
|
|
|
|
List all registered system commands for a source
|
|
================================================
|
|
|
|
.. http:get:: /api/system/commands/(string:source)
|
|
|
|
Retrieves the configured system commands for the specified source.
|
|
|
|
The response will contain a list of :ref:`command definitions <sec-api-system-commands-definiton>`.
|
|
|
|
**Example**
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /api/system/commands/core HTTP/1.1
|
|
Host: example.com
|
|
X-Api-Key: abcdef...
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 Ok
|
|
Content-Type: application/json
|
|
|
|
[
|
|
{
|
|
"action": "shutdown",
|
|
"name": "Shutdown",
|
|
"command": "sudo shutdown -h now",
|
|
"confirm": "<b>You are about to shutdown the system.</b></p><p> This action may disrupt any ongoing print jobs (depending on your printer's controller and general setup that might also apply to prints run directly from your printer's internal storage).",
|
|
"async": true,
|
|
"ignore": true,
|
|
"source": "core",
|
|
"resource": "http://example.com/api/system/commands/core/shutdown"
|
|
},
|
|
{
|
|
"action": "reboot",
|
|
"name": "Reboot",
|
|
"command": "sudo reboot",
|
|
"confirm": "<b>You are about to reboot the system.</b></p><p> This action may disrupt any ongoing print jobs (depending on your printer's controller and general setup that might also apply to prints run directly from your printer's internal storage).",
|
|
"async": true,
|
|
"ignore": true,
|
|
"source": "core",
|
|
"resource": "http://example.com/api/system/commands/core/reboot"
|
|
},
|
|
{
|
|
"action": "restart",
|
|
"name": "Restart OctoPrint",
|
|
"command": "sudo service octoprint restart",
|
|
"confirm": "<b>You are about to restart the OctoPrint server.</b></p><p> This action may disrupt any ongoing print jobs (depending on your printer's controller and general setup that might also apply to prints run directly from your printer's internal storage).",
|
|
"async": true,
|
|
"ignore": true,
|
|
"source": "core",
|
|
"resource": "http://example.com/api/system/commands/core/restart"
|
|
}
|
|
]
|
|
|
|
:param source: The source for which to list commands, currently either ``core`` or ``custom``
|
|
:statuscode 200: No error
|
|
:statuscode 404: If a ``source`` other than ``core`` or ``custom`` is specified.
|
|
|
|
.. _sec-api-system-command-execute:
|
|
|
|
Execute a registered system command
|
|
===================================
|
|
|
|
.. http:post:: /api/system/commands/(string:source)/(string:action)
|
|
|
|
Execute the system command ``action`` on defined in ``source``.
|
|
|
|
**Example**
|
|
|
|
Restart OctoPrint via the core system command ``restart`` (which is available if the server
|
|
restart command is configured).
|
|
|
|
.. sourcecode:: http
|
|
|
|
POST /api/system/commands/core/restart HTTP/1.1
|
|
Host: example.com
|
|
X-Api-Key: abcdef...
|
|
|
|
.. sourcecode:: http
|
|
|
|
204 No Content
|
|
|
|
:param source: The source for which to list commands, currently either ``core`` or ``custom``
|
|
:param action: The identifier of the command, ``action`` from its definition
|
|
:statuscode 204: No error
|
|
:statuscode 400: If a ``divider`` is supposed to be executed or if the request is malformed otherwise
|
|
:statuscode 404: If the command could not be found for ``source`` and ``action``
|
|
:statuscode 500: If the command didn't define a ``command`` to execute, the command returned a non-zero
|
|
return code and ``ignore`` was not ``true`` or some other internal server error occurred
|
|
|
|
.. _sec-api-system-datamodel:
|
|
|
|
Data model
|
|
==========
|
|
|
|
.. _sec-api-system-commands-listall:
|
|
|
|
List all response
|
|
-----------------
|
|
|
|
.. list-table::
|
|
:widths: 15 5 10 30
|
|
:header-rows: 1
|
|
|
|
* - Name
|
|
- Multiplicity
|
|
- Type
|
|
- Description
|
|
* - ``core``
|
|
- 0..n
|
|
- List of :ref:`command definitions <sec-api-system-commands-definiton>`
|
|
- List of all core commands defined.
|
|
* - ``custom``
|
|
- 0..n
|
|
- List of :ref:`command definitions <sec-api-system-commands-definiton>`
|
|
- List of all custom commands defined in ``config.yaml``.
|
|
|
|
.. _sec-api-system-commands-definiton:
|
|
|
|
Command definition
|
|
------------------
|
|
|
|
.. list-table::
|
|
:widths: 15 5 10 30
|
|
:header-rows: 1
|
|
|
|
* - Name
|
|
- Multiplicity
|
|
- Type
|
|
- Description
|
|
* - ``name``
|
|
- 1
|
|
- string
|
|
- The name of the command to display in the System menu.
|
|
* - ``command``
|
|
- 1
|
|
- string
|
|
- The full command line to execute for the command.
|
|
* - ``action``
|
|
- 1
|
|
- string
|
|
- An identifier to refer to the command programmatically. The special ``action`` string
|
|
``divider`` signifies a divider in the menu.
|
|
* - ``confirm``
|
|
- 0..1
|
|
- string
|
|
- If present and set, this text will be displayed to the user in a confirmation dialog
|
|
they have to acknowledge in order to really execute the command.
|
|
* - ``async``
|
|
- 0..1
|
|
- bool
|
|
- Whether to execute the command asynchronously or wait for its result before responding
|
|
to the HTTP execution request.
|
|
* - ``ignore``
|
|
- 0..1
|
|
- bool
|
|
- Whether to ignore the return code of the command's execution.
|
|
* - ``source``
|
|
- 1
|
|
- string
|
|
- Source of the command definition, currently either ``core`` (for system actions defined by
|
|
OctoPrint itself) or ``custom`` (for custom system commands defined by the user through ``config.yaml``).
|
|
* - ``resource``
|
|
- 1
|
|
- string
|
|
- The URL of the command to use for executing it.
|