Last updated on: January 19 2023.

F5OS-A 1.0.0 - API Endpoint Overview¶

Feature Overview¶

F5OS-A exposes an API via RESTCONF, by Tail-F, the makers of Confd, and it is a RESTful API implementation of confd. The F5OS-A GUI uses the RESTCONF API.

The F5OS-A API is for provisioning F5OS, not for interacting with BIG-IP tenants.

API reference¶

The customer-facing API reference can be found athttps://clouddocs.f5.com/api/velos-api/. An API reference that is specific to F5OS-A will be available post-release.

Token auth (X-Auth-Token)¶

After successfully logging in with basic auth to the /api endpoint, an X-Auth-Token header is returned. The contents of this token can be used in subsequent API requests. The following is a cURL example, and is what the GUI does. (The -I parameter tells cURL to print the response headers)

curl -I -sku admin:admin https://vanquish/api/

HTTP/1.1 200 OK
...other headers...
X-Auth-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRoaW5mbyI6ImFkbWluIDEwMDAgOTAw...Z7tkjFWNhZCXD6FayAsLAvsLDayZr9Tg63HY
...other headers...

Now you can pass the token in as a header for subsequent commands.

curl -sk -H "X-Auth-Token: <token_value>" https://vanquish/api/data/openconfig-system:system/f5-system-licensing:licensing

<licensing xmlns="http://f5.com/yang/system/licensing"  xmlns:f5-licensing="http://f5.com/yang/system/licensing"  xmlns:oc-sys="http://openconfig.net/yang/system">
  <config>
...license file is dumped...
</licensing>

The X-Auth-Token has a lifetime of fifteen minutes and can be renewed a maximum of five times before you need to authenticate again using basic auth. The renewal period begins at the ten-minute point, where the API will start sending a new X-Auth-Token in the response for the next five minutes. If your API calls fail to start using the new token by the 15-minute point, API calls will start returning 401 Not Authorized.

API example¶

F5OS-A listens on TCP port 443 for API requests. It uses RESTCONF to implement the API. RESTCONF is defined in RFC8040. RESTCONF uses a data modeling language called YANG (Yet Another Next Generation) v1.1, seeRFC 7950. The API is published publicly athttps://clouddocs.f5.com/api/velos-api/.

Restconf example: get the system license¶

$ curl -sku admin:admin https://<rSeries_mgmt_ip>/api/data/openconfig-system:system/f5-system-licensing:licensing/f5-system-licensing:config
...<outputs the license>...

$ curl -sku admin:admin -H "Accept: application/yang-data+json" https://<rSeries_mgmt_ip>/api/data/openconfig-system:system/f5-system-licensing:licensing/f5-system-licensing:config
...<outputs the license as a json object>...

Download the configuration (RESTCONF) file¶

Sending a GET request to /api/data will fetch all of the modules and all of the current settings for those modules.

curl -sku admin:admin -H "Content-Type: application/yang-data+json" https://vanquish/api/data -o openapi.json

Download a file example¶

These commands were run on version 1.0.0 build 9998 which was the limited access milestone. They are listed as examples.

Here are the valid download paths on F5OS-A.

API path	File system path on Vanquish rSeries
log/host/	/var/log/
log/system/	/var/F5/system/log/
diags/core/	/var/core/
diags/crash/	/var/crash/
configs/	/var/F5/system/configs/
diags/shared/	/var/shared/
log/confd/	/var/confd/log/
images/staging/	/var/import/staging/
images/import/	/var/export/chassis/import/
images/tenant/	/var/F5/system/IMAGES/

List the files in log/host, which corresponds to /var/log/ on the rSeries filesystem

$ curl -X POST -H "Content-Type: application/yang-data+json" -sk -H "X-Auth-Token: <TOKEN>" 'https://vanquish/api/data/f5-utils-file-transfer:file/list' --data-raw '{"path": "log/host"}'
{
  "f5-utils-file-transfer:output": {
    "entries": [
      {
        "name": "\nanaconda/\nansible.log\nappliance.log\naudit\nmessages\nmessages.1\nmessages.2.gz\nmessages.3.gz...\nwtmp"
      }
    ]
  }
}

Enumerate the files located in diags/crash.

$ curl -X POST -H "Content-Type: application/yang-data+json" -sk -H "X-Auth-Token: <TOKEN>" 'https://vanquish/api/data/f5-utils-file-transfer:file/list' --data-raw '{"path": "diags/crash/"}'
{
  "f5-utils-file-transfer:output": {
    "entries": [
      {
        "name": "\n127.0.0.1-2021-10-26-13:47:06/"
      }
    ]
  }
}

There’s one folder named 127.0.1.1-2021-10-26-13:47:06. Drill down into that directory:

$ curl -X POST -H "Content-Type: application/yang-data+json" -sk -H "X-Auth-Token: <TOKEN>" 'https://vanquish/api/data/f5-utils-file-transfer:file/list' --data-raw '{"path": "diags/crash/127.0.0.1-2021-10-26-13:47:06/"}'
{
  "f5-utils-file-transfer:output": {
    "entries": [
      {
        "name": "\nvmcore\nvmcore-dmesg.txt"
      }
    ]
  }
}

Download vmcore-dmesg.txt.You need to change ‘api’ to ‘restconf’ in the URL if you want to download the file, otherwise the response is a path to a file in /tmp/download/.

$ curl -X POST -H "Content-Type: application/yang-data+json" -sk -H "X-Auth-Token: <TOKEN>" 'https://vanquish/restconf/data/f5-utils-file-transfer:file/f5-file-download:download-file/f5-file-download:start-download' --data-raw '{"file-name": "vmcore-dmesg.txt", "file-path": "diags/crash/"}'
...
[  306.937169]  [<ffffffff85722193>] ? copy_module_from_fd.isra.45+0x53/0x160
[  306.944010]  [<ffffffff85726eae>] SyS_finit_module+0xae/0xf0
[  306.949639]  [<ffffffff85dbc892>] system_call_fastpath+0x25/0x2a
...

Enumerate the system logs

$ curl -X POST -H "Content-Type: application/yang-data+json" -sk -H "X-Auth-Token: <TOKEN>" 'https://vanquish/api/data/f5-utils-file-transfer:file/list' --data-raw '{"path": "log/system/"}'
{
  "f5-utils-file-transfer:output": {
    "entries": [
      {
        "name": "\naudit.log\nconfd.log\ndevel.log\nlcd.log\nlcd.log.1\nlcd.log.2.gz\nlogrotate.log\nlogrotate.log.1\nlogrotate.log.2.gz\nplatform.log..."
      }
    ]
  }
}

Download velos.log. Change ‘api’ to ‘restconf’ in the URL to download the file, otherwise the response is a path to a file in /tmp/download/.

curl -X POST -H "Content-Type: application/yang-data+json" -sk -H "X-Auth-Token: <TOKEN>" \
'https://vanquish/restconf/data/f5-utils-file-transfer:file/f5-file-download:download-file/f5-file-download:start-download' \
--data-raw '{"file-name": "velos.log", "file-path": "log/system/"}' -o velos.log

F5OS-A supports up to five simultaneous downloads. This is tracked by the number of files in /tmp/download/. It can be changed with the concurrent-operations-limit setting.

(config)# file config concurrent-operations-limit <num - default 5>

API troubleshooting¶

If RESTCONF isn’t functioning then the GUI won’t function, so you might be troubleshooting the API as part of troubleshooting a non-responsive GUI. The easiest way to tell if the API is working is to confirm the GUI is working.

Can’t log into an API endpoint¶

This can show up a number of ways, this is an example of a return code

curl -sku admin:wrongpassword -H "Content-Type: application/yang-data+json" https://vanquish-01.npi.f5net.com/api/
{
  "ietf-restconf:errors": {
    "error": [
      {
        "error-type": "protocol",
        "error-tag": "access-denied"
      }
    ]
  }
}

A 401 error appears in the logs:

==> /var/log/httpd/ssl_access_log <==
172.18.4.44 - - [06/Dec/2021:23:15:37 +0000] "GET /api/ HTTP/1.1" 401 144

Wrong API endpoint is used¶

Curl bails on certain failed calls, like an incorrect URL path

$ curl -sku admin:admin -H "Content-Type: application/yang-data+json" https://vanquish-01.npi.f5net.com/api/wrongendpoint
$

The 404 is logged to the log file

==> /var/log/httpd/ssl_access_log <==
172.18.4.44 - - [06/Dec/2021:23:17:08 +0000] "GET /api/wrongendpoint HTTP/1.1" 404 -

curl -v would enable verbose output and the 404 error would be printed.

Unable to reach port 443¶

Port 443 and 8888, 161, and many other ports are opened via a container called system_latest_vers. I killed it see what the behavior would look like

[root@appliance-1 ~]# docker inspect system_latest_vers
[
    {
        "Id": "4d7fc17ce59fe677e4b5378710519610fa891b84d1721f5bb42355d30f5c8201",
        "Created": "2021-12-03T21:26:06.601772763Z",
        "Path": "/bin/bash",
        "Args": [
            "-c",
            "sleep infinity & wait"
        ],
        "State": {
            "Status": "exited", <====
            "Running": false,   <====
            "Paused": false,    <====
            "Restarting": false,
            "OOMKilled": false,
            "Dead": false,
            "Pid": 0,
            "ExitCode": 137,
            "Error": "",
            "StartedAt": "2021-12-03T21:26:07.005765234Z",

I don’t know what you’d do…reboot? Gather diagnostics first? This might be a contrived example.

Expected / Possible Problems¶

None known

Known Issues¶