NBI Port Access Control🔗
NBI Port Access Control is a configurable GUI feature that administrators apply to selected ports. It grants a client of the API access to the specified ports, enabling it to retrieve MAC addresses connected to those ports and control the set of services allowed on said port(s). The API utilizes a Representational State Transfer (REST) style interface over HTTPS.
NBI Port Access Control is a configurable GUI feature that administrators apply to selected ports. It grants a client of the API access to the specified ports, enabling it to retrieve MAC addresses connected to those ports and control the set of services allowed on said port(s). The API utilizes a Representational State Transfer (REST) style interface over HTTPS.
How to Configure Port Access Control🔗
Create NBI Eth Ports🔗
Double-click to open the Eth-Ports tile.
Double-Click to open NBI Eth Ports.
Click the Add New NBI Eth Port button and name your profile.
Set your selected Eth-Port-Profile(s), enable them, and save by clicking the check button.
Each Eth-Port-Profile has an index assigned from 0 called “nbi_index”. Remember this number because it is going to be used later in the API description.
Assign to Port🔗
In Topology -> Network View, choose a port and set the Provisioning value to your chosen NBI Eth-Port.
REST API Documentation🔗
GET API🔗
access_control_ports_get()
access_control_ports_get -> json -- Collect details about NBI-controllable ports, along with known MACs
Return NBI-controllable ports with associated MACs
to allow an external agent to make decisions about
network access from those ports
dev_id: int_list
Either a single Device ID or a list of Device IDs
product_class: text_list
Like this product class or list (eg 'FTTP')
mac_address: MAC address to search for
logging: truthy
If true, log query execution
In general, the function is called with no arguments. A curl command to do this looks like the following example.
curl -s 'https://readonly:password@vnetc.domain.com/api/request?query=access_control_ports_get'
If the user wants to use the MAC search functionality, the request looks as follows:
curl -s 'https://readonly:password@vnetc.domain.com/api/request?query=access_control_ports_get&mac_address=2c%3A54%3A2d%3Abd%3A1b%3Ac7'
Notice how “:” in the MAC address changes to “%3A”, due to URL encoding rules.
The response has the following structure.
[
{
"dev_id": 580,
"hw_hostname": "IPHO0051169E",
"hw_ident": "IPHO0051169E",
"hw_mfg": "IPHOTONIX",
"hw_model": "7281",
"hw_sn": "IPHO0051169E",
"management_ip": "10.200.20.69",
"ports": {
"cpe-Eth1": {
"link_change": "2023-09-18T20:15:53Z",
"link_up": true,
"macs": [
"40:6c:8f:42:6e:70"
],
"nbi_index": 1,
"nbi_eth_port": "NBI B",
"nbi_max_index": 3
}
}
},
{
"dev_id": 1044,
"hw_hostname": "pipe-tor",
"hw_ident": "cc:37:ab:c5:b6:20",
"hw_mfg": "Edge-Core",
"hw_model": "ECS2100-10PE",
"hw_sn": "EC1614000881",
"management_ip": "10.200.20.71",
"ports": {
"swp10": {
"link_change": "2023-09-18T20:15:24Z",
"link_up": true,
"macs": [
"00:1c:15:04:a9:e9",
"06:1c:15:04:a9:e9",
"06:1c:15:04:a9:ea",
"26:1c:15:04:a9:e9",
"40:6c:8f:42:6e:70"
],
"nbi_eth_port": "NBI A",
"nbi_max_index": 2
},
"swp9": {
"link_change": "2023-09-18T11:33:41Z",
"link_up": false,
"nbi_eth_port": "NBI B",
"nbi_max_index": 3
}
}
}
]
In addition to returning the above information to the caller, the "ports" section is updated in the device object using the data_class "ipho.nbi_macs". This provides internal observers (e.g., the GUI) visibility into what was returned to the most recent caller.
Notice that we return both "nbi_index" and "nbi_index_max". The latter represents the maximum index for the specific NBI port profile. For example, if 5 services are listed in the profile, "nbi_index_max" will be set to 4.
When "mac_address" is specified, the result has the following structure:
[
{
"dev_id": 400,
"vlan_ids": [
4094
],
"nbi_max_index": 2,
"port_name": "swp10",
"mac_address": "2c:54:2d:bd:1b:c7",
"nbi_index": 1
}
]
SET API🔗
access_control_ports_set()
access_control_ports_set -> json -- Update profile for NBI-controllable ports
Set to profile index on one or more
NBI-controllable ports. The (dev_id, port_name,
index) args provide a simplified API call to make a
single change. The NBI can also PUT or POST a list
of these settings to control multiple ports at the
same time
dev_id: int
Device ID to control
port_name: Port name to control (eg 'cpe-Eth1')
index: int
Profile index to set port to (base 0)
port_list: json_text
List of ports to control from POST or PUT, eg:
[{"dev_id": 123, "port_name": "swp1", "index": 1},
...]
logging: truthy
If true, log query execution
The command may be run to perform a single update, eg:
curl -s 'https://readonly:password@vnetc.domain.com/api/request?\
query=access_control_ports_set&dev_id=123&port_name=cpe-Eth1&nbi_index=1'
This returns an output like the following example.
[
{
"change": [0, 1],
"dev_id": 123,
"nbi_index": 1,
"info": "dev_id 123, port 'cpe-Eth1' index change 0 -> 1",
"port_name": "cpe-Eth1"
}
]
curl -s --data @test.json -H 'Content-Type: application/json'\
'https://readonly:password@vnetc.domain.com/api/request/'
In the command, "test.json" would contain:
{
"request": {
"query": "access_control_ports_set",
"port_list": [
{
"dev_id": 123,
"nbi_index": 1,
"port_name": "cpe-Eth1"
},
{
"dev_id": 123,
"nbi_index": 2,
"port_name": "cpe-Eth2"
},
{
"dev_id": 321,
"nbi_index": 1,
"port_name": "swp10"
}
]
}
}
The response is like the single-command response, with an entry for each control item.