Summary
This chapter describes how to enable and use HTTP API. Traffic Dictator API is available with either insecure (HTTP) or secure (HTTPS) connection. HTTP doesn’t require certificates and keys, so it’s easier to use for studying, PoC testing etc. However, best practice for production deployments is to disable HTTP and use only HTTPS.
HTTP configuration
Default configuration of HTTP API:
management api http-commands
protocol http
port 80
Verify that HTTP API is running:
TD1#show management api http HTTP server statistics Enabled: True Running: True Port: 80 Hit count: 0 Last hit: June 05, 2024 11:14:58
It is possible to change port or shutdown the HTTP API.
management api http-commands
protocol http
port 8080
shutdown
Verify:
TD1#show management api http HTTP server statistics Enabled: False Running: False Port: 8080 Hit count: 0 Last hit: June 05, 2024 11:14:58
HTTPS configuration
By default, HTTPS API is not running because it requries an TLS certificate and key.
TD1#show management api https HTTP server statistics Enabled: True Running: False Port: 443 Hit count: 0 Last hit: June 05, 2024 11:14:58 Certificate: None Key: None Ciphers: None TLS versions: TLSv1.3
You can use TLS certificate provided by a Certificate Authority (CA) or generate a self-signed certificate.
Generate a self-signed TLS certificate
Example command to generate a self-signed certificate and key:
bash openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout mykey.key -out mycert.crt
Adjust parameters as required.
Configure HTTPS API to use TLS cerficiate
Add the following config:
management api http-commands
protocol https
port 443
certificate mycert.crt key mykey.key
Files must be in /usr/local/td/ directory, or you can specify an absolute path to certificate and key.
Verify that HTTPS API is running:
TD1#show management api https HTTP server statistics Enabled: True Running: True Port: 443 Hit count: 0 Last hit: June 05, 2024 11:14:58 Certificate: mycert.crt Key: mykey.key Ciphers: TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256 TLS versions: TLSv1.3
Similarly to HTTP, you can change HTTPS port or shutdown the HTTPS API.
Using API
Once the API has been configured, you can connect to it and run all kinds of commands to either configure Traffic Dictator or get outputs.
Note: when using Traffic Dictator in Docker container, you might need to expose additional ports if you’re using non-standard ports. Ports 80 and 443 are exposed by default.
First, create a user if required. Or you can use RADIUS/TACACS/LDAP etc authentication. TD API relies on PAM authentication configured in the system.
bash useradd tdadmin bash passwd tdadmin
You can use python and jsonrpclib to connect to Traffic Dictator API.
Note: when using self-signed certificate, create unverified ssl context so that the API client accepts it. Otherwise this is not required.
python3
from jsonrpclib import Server
import ssl
_create_unverified_https_context = ssl._create_unverified_context
ssl._create_default_https_context = _create_unverified_https_context
td_api = Server("https://tdadmin:td123@172.17.0.2:443/command-api")
You can use API to get the output of any show command. For example:
>>> show_ver = td_api.runCmds( 1, ["show version"])
>>> pprint(show_ver)
[{'customer_id': '000555',
'customer_name': 'Vegvisir Systems',
'expire_date': '2025-12-31',
'hostname': 'TD1',
'mfg_name': 'Vegvisir Systems',
'model_name': 'Traffic Dictator',
'start_time': 1717600431,
'uptime': '0:08:32',
'valid_license': True,
'version': '1.0'}]
Also you can use API to configure Traffic Dictator. Just add configuration commands separated by comma, for example:
>>> td_api.runCmds( 1, ["configure", "router bgp 65001", "neighbor 192.168.0.102", "remote-as 65002"])
[{}, {}, {}, {}]
If any of the commands fails, you will get an error message and the subsequent commands will not be executed.
To explore available commands, use TDCLI and try autocomplete with tab or question mark to see all commands and options.
Add a large config using API
Copy-pasting many config lines to TDCLI is not the best option because it can be slow, prone to errors, and difficult to see if any of the commands fails.
Better option would be using API to add a large configuration. Let’s say you have a text config with a lot of traffic engineering policies called “policy_config.txt”. It contents look like this:
policy R1_R4_ISP1_001
headend 1.1.1.1 topology-id 101
endpoint 172.16.0.11 color 100
binding-sid 15001
priority 7 7
install direct srte 192.168.123.101
!
candidate-path preference 100
metric igp
bandwidth 1 gbps
...
Then you can create a simple python script to push this config from a text file to TD API:
#!/usr/bin/env python3
from jsonrpclib import Server
import ssl
_create_unverified_https_context = ssl._create_unverified_context
ssl._create_default_https_context = _create_unverified_https_context
td_api = Server("https://tdadmin:td123@172.17.0.2:443/command-api")
with open("/home/dima/policy_config.txt", "r") as f:
config_lines = f.readlines()
send_command = [
"configure",
"traffic-eng policies"
]
for line in config_lines:
line = line.strip()
if not line: continue
if line == "!": continue
send_command.append(line)
td_api.runCmds( 1, send_command)
Therefore, HTTP API is a powerful tool that can be used to integrate Traffic Dictator with your network automation system.