Operating system control

Control the OS facilities like time, network, etc.

Minimum user role is admin for every endpoint, except GET /system/time which is available to viewer.

Note: firmware update endpoints are not part of /system/* proxying and are described on the Firmware Update page.

API

Time

• Get available timezones of the system

  • Path: /system/time/timezones

  • Method: GET

  • Response:

    [
      {
        "id": "Africa/Harare",
        "code": "ZW",
        "coordinates": "-1750+03103",
        "description": ""
      },
      {
        "id": "Africa/Johannesburg",
        "code": "ZA",
        "coordinates": "-2615+02800",
        "description": ""
      }
    ]

• Get the current time settings of the system

  • Path: /system/time

  • Method: GET

  • Minimum user role: viewer

  • Response:

    {
      "time": 1675090550,
      "timezone_id": "Europe/Amsterdam",
      "ntp_enabled": true,
      "ntp_servers": [
          "0.ubuntu.pool.ntp.org"
      ]
    }

• Change time settings of the system
  • Path: /system/time
  • Method: PUT
  • Request body: same shape as the GET response
    • timezone_id must be one of id-s of response of /system/time/timezones request; if empty value is passed, it will default to UTC

Network

In order to use this API, one must firstly get the list of available networks using the /system/network endpoint. The network_id values returned there are used to address a particular network in the other requests.

• Get all networks of the device

  • Path: /system/network

  • Method: GET

  • Response:

    [{
      "network_id": 1,
      "connection_start_time": 1675771183,
      "state": "connected",
      "dhcp_enabled": true,
      "ip": "192.168.1.9",
      "netmask": "255.255.255.0",
      "gateway": "192.168.1.1",
      "nameserver": "192.168.1.1",
      "mac": "70:85:cc:3e:dd:f6",
      "hostname": "profitap-desktop",
      "network_authentication_enabled": true,
      "network_authentication_md5":
      {
        "identity": "foobar",
        "password": "barfoo"
      },
      "network_authentication_tls":
      {
        "identity": "foobar",
        "ca_cert": "foobar",
        "client_cert": "foobar",
        "private_key": "foobar",
        "private_key_pw": "foobar"
      }
    }]

    • network_id contains ID of this network which is to be used to change the settings of this network in other requests
    • if network_authentication_enabled is true, one and only one of {network_authentication_md5, network_authentication_tls} must be set
    • if dhcp_enabled is false, both ip and netmask must be set
• Get the network settings
  • Path: /system/network/{ID}
  • Method: GET
  • Response: a single network object (same shape as the entries of the /system/network response, without the network_id field)
• Change network settings of the system

  • Path: /system/network/{ID}

  • Method: PUT

  • Request body: a subset of the network object. Writable fields include dhcp_enabled, ip, netmask, gateway, nameserver, hostname, network_authentication_enabled, network_authentication_md5, network_authentication_tls.

    {
      "dhcp_enabled": true,
      "hostname": "profitap-desktop"
    }

    • hostname field can only be changed if request is done to /system/network/0 endpoint; all other networks will reject the request with this field set
    • if dhcp_enabled is false, both ip and netmask must be set
    • if network_authentication_enabled is true, exactly one of network_authentication_md5 or network_authentication_tls must be set

  • Response: on success, 200 OK with the updated network object; on failure, 400 Bad Request with validation errors or 500 Internal Server Error

State

• Get state of the system

  • Path: /system/state

  • Method: GET

  • Response:

    {
        "time": 1695036185,
        "uptime": 19397,
        "commit_id": "fb2d6b9",
        "hardware": {
            "hardware_ok": true,
            "hardware_version": null,
            "hardware_failure_reason": null,
            "hardware_failure_time": null
        },
        "software": {
            "software_version": "5.0.0",
            "software_release_timestamp": "2023.11"
        },
        "nvme": [
            {
                "name": "data1",
                "temperature": 37,
                "critical_warnings": 0,
                "available_spare": 100,
                "available_spare_threshold": 10,
                "percentage_used": 0
            }
        ],
        "cpu": {
            "main_cpu_temperature": 68,
            "ipmi_cpu_temperature": 75
        },
        "fan": [
            {
                "name": "FAN1",
                "speed_rpm": 7300
            }
        ]
    }

    • time - current server timestamp (unix epoch, seconds)
    • uptime - system uptime in seconds
    • commit_id - git commit hash of the running system daemon build
    • hardware - generic hardware health
      • hardware_ok - true if no failure has been detected
      • hardware_version - platform-specific hardware version (nullable)
      • hardware_failure_reason / hardware_failure_time - populated when hardware_ok is false
    • software - installed IOTA software info
    • nvme - per-disk SMART data for every present NVMe drive (fields follow NVMe SMART/Health attributes)
    • cpu - CPU temperature readings (fields present depend on the platform)
    • fan - fan speed readings, one entry per fan present on the platform
• Get the status of the watched applications

  • Path: /system/state/components

  • Method: GET

  • Response:

    [
        {
            "component": "centralised-server-ng",
            "critical_app": true,
            "state": "off",
            "start_timestamp": "",
            "failed_idx": 1
        },
        {
            "component": "clickhouse-server",
            "critical_app": false,
            "state": "off",
            "start_timestamp": "Tue 2023-08-08 10:43:43 EEST",
            "failed_idx": 1
        }
    ]

    • component - name of the watched application
    • critical_app - true if a failure of this application is considered critical
    • state - current state of the application (e.g. on, off)
    • start_timestamp - when the application was last started, empty if never started
    • failed_idx - counter of consecutive failed start attempts

Power

• Reboot the device

  • Path: /system/reboot

  • Method: POST

  • Response:

    {
        "message": "rebooting the device"
    }

• Shutdown the device

  • Path: /system/shutdown

  • Method: POST

  • Response:

    {
        "message": "shutting down the device"
    }

• Factory reset
  • Path: /system/factory_reset
  • Method: POST
  • Responses:
    • 200 OK - factory reset has been initiated
    • 500 Internal Server Error - failure occurred before the reset could be initiated
• Notes on reboot, shutdown and factory_reset:
  • while the operation is in progress, the general state of the system is set to restarting; other operations are rejected with 409 Conflict until it completes

License

• Get the current state of the license on the device

  • Path: /system/license

  • Method: GET

  • Response:

    {
        "key": "AAAA-BBBB-CCCC-DDDD-EEEE",
        "state": "active",
        "description": "license is activated successfully",
        "expiry": 4832342389,
        "maintenance_max_version": "2023.07",
        "ssd_key_seed": "hidden",
        "zerotier_expiry": "2023.07",
        "zerotier_available": true,
        "graid_key": "set"
    }

    • key - license key
    • state - one of: inactive, active, expired, suspended, grace_period_over, machine_fingerprint_changed, error
    • description - string containing additional info about the license state, for instance, a human-readable error
    • expiry - epoch in seconds of when the license is going to expire
    • maintenance_max_version - maximum maintenance date in YYYY.MM format
    • ssd_key_seed - obfuscated indicator for the SSD key seed; "hidden" when present, null when not set (the actual value is never exposed)
    • zerotier_expiry - maximum ZeroTier availability date in YYYY.MM format
    • zerotier_available - shows if ZeroTier functionality is allowed by the license
    • graid_key - "set" when a graid key is stored on the device, "not set" otherwise (the actual value is never exposed)
• Change the license key

  • Path: /system/license

  • Method: PUT

  • Request body:

    {
        "key": "AAAA-BBBB-CCCC-DDDD-EEEE"
    }

  • Response: on success, 200 OK with the updated license object (same shape as GET response, with state = "active"); on failure, 400 Bad Request with the error description

ZeroTier

• Get the current ZeroTier settings of the system

  • Path: /system/zerotier

  • Method: GET

  • Response:

    {
        "network_id": "19ac4a1e719d3ad9",
        "node_id": "d817f95681",
        "state": "disabled",
        "status": null,
        "zt_ip": null,
        "last_error": "could not disable ZeroTier: no connection to daemon",
        "last_error_ts_sec": 483534
    }

    • network_id - ID of the network this device is connected to (nullable)
    • node_id - node ID of this device (nullable)
    • state - one of: unknown, disabled, restarting_failed, disabling, disabling_failed, configuring_failed, enabling, connected
    • status - human-readable state of ZeroTier (nullable)
    • zt_ip - IP address assigned to the device on the ZeroTier network (nullable, only populated when connected)
    • last_error - last error which happened when configuring ZeroTier (nullable)
    • last_error_ts_sec - timestamp (in sec) when the last error happened (nullable)
• Change the ZeroTier settings

  • Path: /system/zerotier

  • Method: PUT

  • Request body:

    {
        "network_id": null
    }

    • network_id - network to connect the device to
      • send the string network ID to make the device to connect to that network
      • send null to disconnect the device from the network

Logs

• Reset the logs
  • Path: /system/log/sys or /system/log/app
  • Method: DELETE
• Remote logging server object

  • fields:

    • id: unsigned integer (read-only)
    • hostname: string, hostname of the server, mandatory to set (read/write); must be a valid DNS hostname or IP address
    • port: unsigned integer, port of the server, default: 514 (read/write); must be a valid TCP/UDP port (1-65535)
    • protocol: udp|tcp, protocol of the server, default: udp (read/write)
    • priority: emerg|alert|crit|error|warning|notice|info|debug minimum logging priority to send, default: info (read/write)
    • active: bool, tells whether server is enabled, default: true (read/write)
    • facility: system|application|both, what kind of logs should be forwarded, e.g. only the application logs (default value if not specified is system)

  • example:

    {
        "id": 5,
        "hostname": "1.2.3.4",
        "port": 514,
        "protocol": "udp",
        "priority": "info",
        "active": true,
        "facility": "system"
    }

• List remote logging servers
  • Path: /system/log/servers
  • Method: GET
• List specific remote logging server
  • Path: /system/log/servers/{ID}
  • Method: GET
• Add remote logging server
  • Path: /system/log/servers
  • Method: POST
• Edit remote logging server
  • Path: /system/log/servers/{ID}
  • Method: PUT
• Delete remote logging server
  • Path: /system/log/servers/{ID}
  • Method: DELETE

Changelog

• Get the device changelog
  • Path: /system/changelog
  • Method: GET
  • Responses:
    • 200 OK - body contains the changelog text
    • 404 Not Found - the changelog file is not available on the device

Back to Index