LANTIME: Monitoring Your Time Server Using the REST API

Modern network infrastructures have increasingly stringent monitoring requirements. The Meinberg LANTIME timeserver, operating on the LTOS system, adheres to the highest standards of monitoring. The following sections will guide you through the instructions for setting up monitoring on your timeserver effectively, using the device's REST API.

• Firmware LTOS V7.04.xxx or newer
• Network Connectivity through HTTP/HTTPS
• REST API Enabled by configuration

Device information will be obtained through the LANTIME's REST API. This means that potentially sensitive information will traverse the network infrastructure. Therefore, it is highly recommended by Meinberg to use secure HTTPS communication exclusively between the LANTIME and your local monitoring system, even though HTTP may be possible in general. To retrieve the requested resource information from the device, user authentication is required during the retrieval process.

LTOS supports two ways of user 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.

A Bearer Token can be requested from the LANTIME. Therefore you must send a PUT Request - using your username and password - to this path: https://mylantime/api/get-token The LANTIME 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” can be copied from the JSON response. Simply add an “Authorization” header to your next request that contains the “Bearer [token]” information. So for example:

Bearer 8B922A7293A28A42FFFEF0513DB1AEAF78F7B74FEE1E301C7F7A314B49D4B7DE3CAC87A514306E361BF489DE1CB108EFBA1845B67735F5FD6BE5477D20BDD0C1

The REST API is enabled by default and accessable through HTTP/HTTPS whenever a user is able to reach the device's web interface as well. However, please make sure, the REST API is enabled. This can be done easily using the web interface. Therefore open the “System” Tab and open the “General Settings” submenu. There you'll find the corresponding configuration option.

Device resources can be requested using specific URL paths. When a request is processed successfully, the LANTIME will respond with a JSON object in the response body and an HTTP 200 (OK) status code. The base API path on the system is /api/ and can be used to retrieve the entire configuration and state of your LANTIME. The complete request URL would be:
https://mylantime/api/

Upon a successful request, the LANTIME will provide a JSON dataset that follows a specific structure. The response body will contain a JSON object with three nested properties:
system-information: This property provides basic information about the requested system, such as the running LTOS version.
data: This object contains the requested resource information. Please note that there may be further nested JSON objects inside.
links: This property offers a set of potentially helpful API links, as well as the currently requested URL.

Example:

{
  “system-information”: {
    “API Version”: “LANTIME REST API V15.00.000”,
    “version”: “fw_7.08.000”,
    “serial-number”: “030111000000”,
    “hostname”: “mylantime.meinberg.de”,
    “time-stamp”: “2023-05-26T06:02:39”,
    “model”: “M300”
  },
  “data”: [
    {
      “object-id”: “lan0”,
      “duplex”: “full”,
      “operstate”: true,
      “speed”: “100”,
      “mac-address”: “00:13:95:00:00:00”,
      “link”: true,
      “slot-id”: 7,
      “slot-name”: “cpu”,
      “port-id”: 0,
      “card-name”: “c05f1-v33”
    },
    {
      “object-id”: “lan1”,
      “duplex”: “full”,
      “operstate”: true,
      “speed”: “100”,
      “mac-address”: “ec:46:70:00:00:00”,
      “link”: true,
      “slot-id”: 7,
      “slot-name”: “cpu”,
      “port-id”: 1,
      “card-name”: “c05f1-v33”
    }
  ],
  “changes”: {
    “pending-changes”: 0
  },
  “links”: {
    “self”: “http://myLantime/api/status/network/ports”
  }
}

If for whatever reason the request to the LANTIME ends up in an error condition, the device will respond with a corresponding HTTP Status code and a message in the body.

Example:

{
  “messages”: [
    “ERROR: access denied! - Unsufficient Permissions”
  ]
}

In this case a resource was requested, the provided user account did not have the rights to ask for. The device correspondingly responded with a HTTP 403 (Forbidden) status code and the above message in the body.

Below you can find a table containing possibly important API Paths you could use for monitoring. Please be aware, that not all of those path may apply to your LANTIME system.

{"object-id": "clock-status","clock": "synchronized","oscillator": "warmed-up","antenna": "connected"}

{"object-id":"","status":{"network":{"ports":[{"object-id":"lan0","link":true},{"object-id":"lan1","link":false},{"object-id":"lan2","link":false},{"object-id":"lan3","link":false},{"object-id":"lan4","link":false},{"object-id":"lan5","link":false}]}}}

{"object-id": "ntp-sync","type": "info","triggered": 1,"last-triggered": "2023-05-31T13:05:26"}

{"object-id": "ntp","running": true}

That'd be too much...

LTOS REST API Reference: https://wolke.meinberg.de/index.php/s/ATdYpnzp66DoHo7
Installtation of HTTPS Certificate: https://www.meinbergglobal.com/download/docs/manuals/english/ltos_7-06.pdf#page=115
mbgNMS Management System: https://www.meinberg.de/german/products/meinberg-network-management-system.htm
Enabling HTTP/HTTPS: https://www.meinbergglobal.com/download/docs/manuals/english/ltos_7-06.pdf#page=88

If further assistance is required, contact Meinberg Technical Support: https://www.meinbergglobal.com/english/support/tech-support.htm