## CLIHelp (https://[IP of device]/clihelp)

This firmware image does not include the CLI/RESTAPI reference documentation in order to save space. Please download the full reference documentation from our website.

### CLI and REST API Reference Introduction

The CLI and API reference describes the CLI/API data structure. For example, the tree-path main-menu/status/network0/ports/lan[ID]/speed points to the link speed status object of a LAN interface (the [ID] placeholder can be replaced with any of the existing LAN interface IDs, e.g. 0 for the very first physical network interface).

In order to access this object from within the CLI, the path would be /status/network/ports/lan0/speed and its current value could be read by using the get CLI command (or, as a shortcut, just entering the path itself which has the same effect):

`root:/ > get /status/network/ports/lan0/speed speed: 1000 root:/ > _`

To access the same object via the REST API, the following link would be used:
https://[IP of the device]/api/status/network/ports/lan0/speed

For objects that have enum values, i.e. there is a fixed list of possible values for the object, the value can be returned in two different ways in a query. As a default, the value is shown as a string-representation, e.g. "ocxo-hq". Each enum value can also be represented by an integer value by sending the raw option together with the query. This is demonstrated for the osc-type object (and all other enum objects) in the following two examples:
Example 1: https://[IP of device]/api/status/system/sync-status (string representation of enum values)
Example 2: https://[IP of device]/api/status/system/sync-status?raw (numeric representation of enum values)

#### Sub-Menus

The description for menus includes all the sub-menus and objects it contains. There is also a See also section which offers direct links to the description of those objects and sub-menus.

To show the contents of an entire sub-menu in the CLI, the view command is used:

`root:/ > view /status/system/sync-status/ sync-status clock-status clock "holdover [2]" oscillator "not-warmed-up [0]" antenna "disconnected [1]" end #clock-status holdover-status time-offset 938820 nanoseconds time-elapsed 175551 seconds end #holdover-status reference "clk1 none" ref-type "none [255]" clock-idx 0 osc-type "ocxo-sq [10]" est-time-quality "less-than-100ns [6]" end #sync-status root:/ >`

Please note that there are multiple output formats available for the view command (see help view for a list).

If applicable, a RESTAPI link is provided as well. Clicking on the link will automatically send a GET request to the corresponding RESTAPI container, resulting in the JSON formatted response to be shown in the right panel. Please note that this API link only works if the API has been enabled on the system on which the clihelp web application is used. If a sub-menu is not supported via the RESTAPI, this is mentioned. In this case there will not be a link provided.

Accessing the contents of a sub menu with the REST API is as easy as just specifying the path to the sub-menu in the URL:
GET https://[IP of device]/api/status/system/sync-status
which will retrieve the entire contents of the sync-status sub-menu in JSON format:

`{ "system-information": { "version": "", "serial-number": "", "hostname": " ", "time-stamp": "2021-02-26T10:06:25", "model": "" }, "data": { "object-id": "sync-status", "clock-status": { "clock": "holdover", "oscillator": "not-warmed-up", "antenna": "disconnected" }, "holdover-status": { "time-offset": 941258, "time-elapsed": 175779 }, "reference": "clk1 none", "ref-type": "none", "clock-idx": 0, "osc-type": "ocxo-sq", "est-time-quality": "less-than-100ns" }, "links": { "self": "http://[IP of the device]/api/status/system/sync-status" } }`

#### Commands

The description of commands will include the parameters and an explanation how to use the command, together with a reference to other, related commands. If a command can also be used with the REST API, this will be mentioned as well, including the HTTP method (verb) that has to be used. Please note that for all RESTAPI links which are not usable with GET, there will be no active link provided in clihelp.

#### Objects

The description of objects will include information about the data-type of the values it can hold. It will also be indicated if this is a read-write object (i.e. for configuration parameters) or a read-only object (for status objects).

If applicable, a description of valid values is also included in an object description, for example an allowed range for integer values or the min/max length of string values.

For enum objects, i.e. objects there is a list of valid entries in the description, with both the text representation (e.g. “free-running”) and the numeric representation (1 in this example for the /status/system/sync-status/clock-status object).

### Capabilities

A JSON model of all available RESTAPI objects can be downloaded from the URL
https://[IP of device]/clihelp/capabilities/restapi-capabilities.json

This model contains all objects and their attributes as well as validation parameters (datatype, min/max values, enums, string regex checks etc.).

### REST API Supported Authentication Methods

The REST API is protected and can only be accessed by LTOS users, either local accounts or via remote authentication (RADIUS, TACACS+, LDAP). It is possible to use the BASIC AUTH method and provide username and password credentials with every request. Alternatively, a BEARER TOKEN can be used instead.

#### Basic Authentication

The HTTP/S Basic Authentication (BA) is widely supported and still the mostly used authentication scheme. BA is used by an HTTP/S agent, in this case your monitoring system, to provide a username and password in a request header. You can use this method, to authenticate at the LANTIME in order to retrieve the requested ressources.

#### Bearer Token Authentication

Note: For Bearer Token Authentication the running LTOS version must be 7.08.xxx or newer.

As a first step, a Bearer Token must be requested from the REST API. For this a PUT Request has to be sent - using valid username and password credentials - to this endpoint: https://mylantime/api/get-token The system itself, if the request succeeded, will respond with a valid Bearer token that can be used to authenticate at the LANTIME. This is, what the token will look like:

    {
        "token": "8B922A7293A28A42FFFEF0513DB1AEAF78F7B74FEE1E301C7F7A314B49D4B7DE3CAC87A514306E361BF489DE1CB108EFBA1845B67735F5FD6BE5477D20BDD0C1",
            "timeout-seconds": 900
    }

The "token" provided in the JSON response is used afterwards for authentication by adding an "Authorization" header to all following requests. The Authorization header field is expected to be in the format "Bearer [token]", where "[token]" is replaced by the token in the get-token response.

Example:

    Bearer 8B922A7293A28A42FFFEF0513DB1AEAF78F7B74FEE1E301C7F7A314B49D4B7DE3CAC87A514306E361BF489DE1CB108EFBA1845B67735F5FD6BE5477D20BDD0C1

Please note that the bearer token provided by the get-token endpoint is only valid for a certain amount of time, which is indicated in the JSON response. To ensure a continous operation, a new bearer token should be requested before the current one expires.