Replicator API¶
Authentication¶
Users must authenticate before using any of the API calls. This is done through the resource URL /api/1/login. To log out manually, use the resource URL /api/1/logout. Log out is not required to end sessions. Sessions are automatically expired after 30 minutes.
Log in¶
Used to start a new API session.
GET request
Note
Legacy API – Deprecated- recommend using POST
Resource URL
https://[replicator]/api/1/login/[sha2]
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
[sha2] | The interactive (CLI) mode’s password converted to sha2 512-bit hex |
Example request
POST request
Used to start a new API session.
Resource URL
POST https://[replicator]/api/1/login/
{
“user” : “admin”
“passwd”: “[passwd]”
}
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
[passwd] | The sha512 hash of the password for admin |
Example response
{
"path": "login successful.",
"result": "success"
}
Log out¶
Used to manually stop an API session.
Resource URL
https://[replicator]/api/1/logout
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
Example request
https://10.30.17.131/api/1/logout
Example response
{
"path": "logout successful.",
"result": "success"
}
Acknowledge¶
Used to acknowledge collectors and exporters in an alarm state.
Resource URL
https://[replicator]/api/1/acknowledge/[entity]/[ip:port]
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
[entity] | valid options are collector or exporter |
[ip:port] | The IP address and port of the [entity] to acknowledge |
Example request
https://10.30.17.131/api/1/acknowledge/collector/10.1.10.4:2055
Example response
{
"description": "Success: collector '10.1.10.4:2055' acknowledged.",
"result": "success"
}
Collector¶
Perform actions to manage collectors in profiles.
RESOURCE URL
Use this resource to manage a collector for an individual profile.
https://[replicator]/api/1/collector/[action]/[ip]/[profile]
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the replicator appliance |
[action] | valid actions are add or remove |
[ip] | The IP address of the collector |
[profile] | The profile to perform the [action] for the [ip] |
Example request
https://10.30.17.131/api/1/collector/add/10.1.10.60/myprofile
Example response
{
"description": "Success: Collector [10.1.10.60] -> Profile [myprofile]",
"result": "success"
}
RESOURCE URL
Use this resource to remove a collector from all profiles.
https://[replicator]/api/1/collector/allremove/[ip]
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
[ip] | The IP of the collector to remove from all profiles |
Example request
https://10.30.17.131/api/1/collector/allremove/10.1.10.4
Example response
{
"description": "Success: Collector [10.1.10.4] <- All Profiles",
"result": "success"
}
DNSCheck¶
Performs a DNS check on an IP Address
RESOURCE URL
Use this resource to manually perform a DNS Name resolve on an IP address.
https://[replicator]/api/1/dnscheck/[ip]
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
[ip] | The IP address to resolve |
Example request
https://10.30.17.131/api/1/dnscheck/10.1.1.3
Example response
{
"dnscheck": {
"addr": "10.1.1.3",
"expiry": {
"epoch": 1462801036,
"time": "Mon May 9 09:37:16 2016"
},
"name": "newexp.plxr.local",
"resolveTime": 0.04485,
"status": "success"
}
}
Exporter¶
Perform actions to manage exporters in profiles.
RESOURCE URL
Use this resource to manage an exporter for an individual profile.
https://[replicator]/api/1/exporter/[action]/[ip]/[profile]
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
[action] | valid actions are add or remove |
[ip] | The IP address of the exporter |
[profile] | The profile to perform the [action] for the [ip] |
Example request
https://10.30.17.131/api/1/exporter/add/10.1.1.1/myprofile
Example response
{
"description": "Success: Exporter [10.1.1.1] -> Profile [myprofile]",
"result": "success"
}
RESOURCE URL
Use this resource to remove an exporter from all profiles.
https://[replicator]/api/1/exporter/allremove/[ip]
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
[ip] | The IP of the exporter to remove from all profiles |
Example request
https://10.30.17.131/api/1/exporter/allremove/10.1.1.4
Example response
{
"description": "Success: Exporter [10.1.1.4] <- All Profiles",
"result": "success"
}
RESOURCE URL
This resource identifies exporters sending data to the replicator that are not members of any profiles.
https://[replicator]/api/1/exporter/noprofile/[filter]
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
[filter] | The filter to apply against the list of exporters in no profiles. To get the entire list, pass a 0. |
Example request
https://10.30.17.131/api/1/exporter/noprofile/0
Example response
{
"noprofile": {
"10.30.17.131": {
"in_o_delta": 0,
"in_o_rate": "0.0",
"in_p_delta": 0,
"in_p_rate": "0.0",
"lastseen": "Tue Apr 19 09:55:18 2016",
"out_o_delta": 1493,
"out_o_rate": "49.8",
"out_p_delta": 6,
"out_p_rate": "0.2",
"unixtime": 1461074118
},
"total": 1
}
}
License¶
Check the status of the current license
RESOURCE URL
This resource returns current license details.
https://[replicator]/api/1/license/check
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
Example request
https://10.30.17.131/api/1/license/check
Example response
{
"daysLeft" : "365 day(s)",
"expiration" : "Thu May 18 2017",
"licensedType" : "eval",
"licensedVersion" : "16.6",
"machineID" : "6YZ6XEPTA66JA6VHFPXG749B",
"role" : "failover"
}
Notate¶
Users can add descriptions for profiles, collectors, and exporters.
RESOURCE URL
https://[replicator]/api/1/notate/[entity]/[identity]/[description]
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
[entity] | valid options are profile or ip. |
[identity] | Use a profile name when [entity] profile is specified, or the IP address of a collector or exporter when [entity] ip is specified. |
[description] | the description of the entity. Use standard ASCII characters the are URI compatible. |
Example request
https://10.30.17.131/api/1/notate/profile/myprofile/My_Fantastic_Description
Example response
{
"description": "Success: Profile 'myprofile' has a new description",
"result": "success"
}
Policies¶
Manage policies that are associated to profiles.
RESOURCE URL
https://[replicator]/api/1/policies/[action]/[network]/[cidr]/[profile]/[incexc]
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
[action] | valid options are add or remove |
[network] | the address to the network (e.g. 172.17.0.0) |
[cidr] | the CIDR to the network specified (e.g. 16) |
[profile] | the name of the profile to perform the [action] |
[incexc] | valid options are include or exclude |
Example request
https://10.30.17.131/api/1/policies/add/10.1.20.0/16/myprofile/include
Example response
{
"description": "Success: Policy [10.1.20.0/16] -> Profile [myprofile]",
"result": "success"
}
Profile¶
Manage characteristics and behaviors of profiles.
RESOURCE URL
Use this resource to rename an existing profile.
https://[replicator]/api/1/profile/rename/[current]/[new]
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
[current] | The name of the profile to rename |
[new] | The new name of the profile |
Example request
https://10.30.17.131/api/1/profile/rename/oldprofile/myprofile
Example response
{
"description": "Success: Profile 'oldprofile' is now 'myprofile'",
"result": "success"
}
RESOURCE URL
Use this resource to toggle the singularity flag.
https://[replicator]/api/1/profile/singularity/[name]/[action]
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
[name] | the name of the profile to toggle singularity |
[action] | valid options are enable and disable |
Example request
https://10.30.17.131/api/1/profile/singularity/myprofile/enable
Example response
{
"description": "Success: Profile 'myprofile' singularity enabled",
"result": "success"
}
RESOURCE URL
Use this resource to enable, disable, or remove a profile
https://[replicator]/api/1/profile/[action]/[name]
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
[action] | valid options are enable, disable, and remove |
[name] | the name of the profile to perform the [action] |
Example request
https://10.30.17.131/api/1/profile/disable/myprofile
Example response
{
"description": "Success: Profile myprofile has been set to 'disable'",
"result": "success"
}
RESOURCE URL
Use this resource to create or update an existing profile.
https://[replicator]/api/1/profile/[action]/[name]/[listeningport]/[sendingport]
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
[action] | valid options are add and update |
[name] | The name of the profile |
[listeningport] | The UDP port for this profile to listen for incoming packets |
[sendingport] | The UDP port for this profile to send packets out |
Example request
https://10.30.17.131/api/1/profile/add/myprofile/2055/4739
Example response
{
"description": "Success: Profile 'myprofile' has been added and enabled.",
"result": "success"
}
Rebuild¶
Force the replicator to rebuild its configuration immediately instead of waiting for the replicator to automatically do it.
RESOURCE URL
https://[replicator]/api/1/rebuild
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
Example request
https://10.30.17.131/api/1/rebuild
Example response
{
"description": "rebuild request submitted",
"result": "success"
}
Role¶
When a replicator is configured as a secondary/backup, send a test to verify its configured properly.
RESOURCE URL
https://[replicator]/api/1/role/test/secondary
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
Example request
https://10.30.17.131/api/1/role/test/secondary
Example response
{
"description": "!!! This replicator is the primary !!!",
"result": "error"
}
Setting¶
Manage global settings of the replicator.
RESOURCE URL
Use this resource to set values for specified settings
https://[replicator]/api/1/setting/set/[name]/[value]
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
[name] | the exact name of the setting to modify |
[value] | the value to set the setting specified in [name] |
Example request
https://10.30.17.131/api/1/setting/set/metricssent/10.1.2.3:2055
Example response
{
"description": "Success: setting 'metricssent' has been set to '10.1.2.3:2055'",
"result": "success"
}
RESOURCE URL
Use this resource to enable or disable the specified setting.
https://[replicator]/api/1/setting/[action]/[name]
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
[action] | valid options are enable or disable |
[name] | the exact name of the setting to modify |
Example request
https://10.30.17.131/api/1/setting/disable/metricssent
Example response
{
"description": "Success: setting 'metricssent' has been set to 'disable'",
"result": "success"
}
Show¶
Shows configuration and realtime information from the replicator.
RESOURCE URL
Use this resource to view the current configuration of the replicator.
https://[replicator]/api/1/show/config
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
Example request
https://10.30.17.131/api/1/show/config
Example response
{
"api": {
"collector": [
"/api/1/collector/add/10.30.1.20/benchmark-20",
...
],
"notate": [
"/api/1/notate/ip/10.1.4.101/ej-win2012 install test machine (fresh)",
...
],
"policy": [
"/api/1/policies/add/10.1.1.252/32/buildqa/include",
...
],
"profile": [
"/api/1/profile/add/frandev/2002/2055",
...
]
},
"cli": {
"collector": [
"collector add 10.30.1.20 benchmark-20",
...
],
"notate": [
"notate ip 10.1.4.101 ej-win2012 install test machine (fresh)",
...
],
"policy": [
"policy add 10.1.1.252/32 buildqa include",
...
],
"profile": [
"profile add frandev 2002 2055",
...
]
}
}
RESOURCE URL
Use this resource to view the current status of the replicator.
https://[replicator]/api/1/show/status
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
Example request
https://10.30.17.131/api/1/show/status
Example response
{
"converting syslog" : "active",
"ipfixify system metrics" : "active",
"replicating port 2002" : "active",
"replicating port 2003" : "active",
"replicating port 2055" : "active",
"replicator api" : "active",
"replicator license" : "259 day(s)",
"replicator monitor" : "active",
"replicator vitalizer" : "active",
"result" : "success",
"version" : "v17.12.19.2255"
}
RESOURCE URL
Use this resource to see realtime data from the replicator.
https://[replicator]/api/1/show/realtime/[filter]
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
[filter] | Currently filter is not supported. Pass in 0 to get the entire state of statistics. |
Example request
https://10.30.17.131/api/1/show/realtime/0
Example response
{
"collector": {
"10.1.4.19": {
"in": {
"octets": {
"delta": 0,
"rate": 0
},
"packets": {
"delta": 0,
"rate": 0
}
}
},
"10.1.4.20": {
...
},
},
"exporter": {
"10.30.17.131": {
"awareness": {
"last_epoch": 1461175921,
"last_timestamp": "2016-04-20 14:12:01"
},
"in": {
"octets": {
"delta": 0,
"rate": "0.0"
},
"packets": {
"delta": 0,
"rate": "0.0"
}
},
"out": {
"octets": {
"delta": 0,
"rate": "0.0"
},
"packets": {
"delta": 0,
"rate": "0.0"
}
},
"profiles": [
"benp"
]
}
},
"pair": {
"10.30.17.131 -> 10.1.4.19": {
"octets": {
"delta": 0,
"rate": 0
},
"packets": {
"delta": 0,
"rate": 0
}
},
"10.30.17.131 -> 10.1.4.20": {
...
},
"profile": {
"benp": {
"in": {
"octets": {
"delta": 0,
"rate": 0
},
"packets": {
"delta": 0,
"rate": 0
}
},
"out": {
"octets": {
"delta": 0,
"rate": 0
},
"packets": {
"delta": 0,
"rate": 0
}
}
}
},
"stats": {
"totals": {
"collectors": 2,
"exporters": 1,
"pairs": 2,
"profiles": {
"disabled": 3,
"enabled": 67,
"total": 70
}
}
},
"system": {
"cpu": "0"
}
RESOURCE URL
Use this resource to show various configured information from the replicator.
https://[replicator]/api/1/show/[entity]/[filter]
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
[entity] | Valid options are alarms, assets, collectors, config, exporters, profile, realtime, settings, and status |
[filter] | A custom keyword match filter can be specified. If no filter is necessary, pass 0. |
Example request
https://10.30.17.131/api/1/show/collector/10.1.10.1
Example response
{
"collector": {
"10.1.10.1": {
"acknowledged": [
9996
],
"description": "erpdev",
"in_profiles": [
"steady-replays"
],
"ip": "10.1.10.1",
"name": null,
"status": {
"unreachable_port": [
"9996"
],
}
"threshold": 10000
}
}
}
Threshold¶
Set thresholds on collectors to warn when replicated packets are exceeding the current packet per second replicated.
RESOURCE URL
https://[replicator]/api/1/collector/threshold/[collector]/[threshold]
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
[collector] | The IP address of the collector |
[threshold] | The threshold to set. It represents packets per second. Set this to a number higher then 0. If 0 is set, the threshold is removed. |
Example request
https://10.30.17.131/api/1/collector/threshold/10.1.5.2/10000
Example response
{
"description": "Success: Collector [10.1.5.2] threshold set to 10000",
"result": "success"
}
Version¶
Returns version information about the replicator.
RESOURCE URL
https://[replicator]/api/1/version
Parameter | Description |
---|---|
[replicator] | The hostname or IP address of the Replicator appliance |
Example request
https://10.30.17.131/api/1/version
Example response
- {
- “apiversion” : “1”, “bestipfixcollector” : “Need an IPFIX Collector? Download Scrutinizer at https://www.plixer.com”, “build” : “2019-12-03 13:07:44 -0500 (Tue, 03 Dec 2019)”, “copyright” : “Copyright (C) 2012 - 2019 Plixer, All rights reserved.”, “name” : “Plixer Replicator (TM) v18.14.1.2410 “, “result” : “success”, “yeswecan” : “Replicate Anything!”
}