Skip to content

Latest commit

 

History

History
242 lines (194 loc) · 6.72 KB

system.rst

File metadata and controls

242 lines (194 loc) · 6.72 KB
Raw

System

Note

All system operations require admin rights.

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": "You are about to shutdown the system.",
            "async": true,
            "ignore": true,
            "source": "core",
            "resource": "http://example.com/api/system/commands/core/shutdown"
          },
          {
            "action": "reboot",
            "name": "Reboot",
            "command": "sudo reboot",
            "confirm": "You are about to reboot the system.",
            "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": "You are about to restart the OctoPrint server.",
            "async": true,
            "ignore": true,
            "source": "core",
            "resource": "http://example.com/api/system/commands/core/restart"
          }
        ],
        "custom": []
      }

   :statuscode 200: No error

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": "You are about to shutdown the system.",
          "async": true,
          "ignore": true,
          "source": "core",
          "resource": "http://example.com/api/system/commands/core/shutdown"
        },
        {
          "action": "reboot",
          "name": "Reboot",
          "command": "sudo reboot",
          "confirm": "You are about to reboot the system.",
          "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": "You are about to restart the OctoPrint server.",
          "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.

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

Data model

List all response

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.

Command definition

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.