Replicator APIs

Replicator APIs#

Replicator supports the following RESTful APIs to enable programmatic monitoring and management of its functions.

On this page:

Authentication
Authentication
System information
Show
Version details
Version
License status
License
Profile management
Profile
Collector management
Collector
Exporter management
Exporter
Policy management
Policies
Threshold settings
Threshold
System settings
Setting
Acknowledgments
Acknowledge
Notifications
Notate
DNS check
DNSCheck
Configuration rebuild
Rebuild
HA role testing
Role

Authentication#

Used to authenticate the user and start/stop API sessions

Login#

Starts a new API session

GET request (Legacy - Deprecated)

Note

Legacy API – Deprecated- recommend using POST

Resource URL: https://[replicator]/api/1/login/[sha2]

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

[sha2]

Interactive Mode (CLI) password converted to SHA2 512-bit hex

API request example

https://10.30.17.131/api/1/login/098f6bcd4621d373ca098f6bcd4621d563cade4e832629b4f6d098f4bcd4621d373cade4e831627b4f6e4e832627b4f
POST request (Recommended)

Resource URL: POST https://[replicator]/api/1/login/

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

[passwd]

SHA512 hash of the password for the admin username

API request example

{
 "user" : "admin"
 "passwd": "[passwd]"
}

Returned JSON object

{
 "path": "login successful.",
 "result": "success"
}

Log out#

Manually terminates an API session (API sessions are automatically terminated after 30 minutes)

Logout API call

Resource URL: https://[replicator]/api/1/logout

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

API request example

https://10.30.17.131/api/1/logout

Returned JSON object

{
 "path": "logout successful.",
 "result": "success"
}

Show#

Displays configuration details and real-time information from the Replicator appliance

Displaying current configuration#

Configuration API call

Resource URL: Displays the current configuration of the Replicator

https://[replicator]/api/1/show/config

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

API request example

https://10.30.17.131/api/1/show/config

Returned JSON object

{
 "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",
   ...
  ]
 }
}

Displaying appliance status#

Status API call

Resource URL: Displays the current status of the appliance

https://[replicator]/api/1/show/status

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

API request example

https://10.30.17.131/api/1/show/status

Returned JSON object

{
   "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"
}

Displaying real-time data#

Real-time data API call

Resource URL: Displays real-time data from the appliance

https://[replicator]/api/1/show/realtime/[filter]

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

[filter]

Currently not supported; defaults to full report if not provided

API request example

https://10.30.17.131/api/1/show/realtime/0

Returned JSON object

{
 "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"
}

Displaying configuration details#

Configuration details API call

Resource URL: Displays various configuration details for the appliance

https://[replicator]/api/1/show/[entity]/[filter]

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

[entity]

alarms, assets, collectors, config, exporters, profile, realtime, settings, or status

[filter]

Optional filter to apply to the output; defaults to the full report if not provided

API request example

https://10.30.17.131/api/1/show/collectors/10.1.10.1

Returned JSON object

{
 "collectors": {
  "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
  }
 }
}

Version#

Used to display the Replicator appliance’s version information

Version information API call

Resource URL:

https://[replicator]/api/1/version

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

API request example

https://10.30.17.131/api/1/version

Returned JSON object

{  
  "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) v19.0.0.101236",
  "result" : "success",
  "yeswecan" : "Replicate Anything!"
}

License#

Used to check the license status/details for the Replicator appliance

License status API call

Resource URL: Returns the details of the current license

https://[replicator]/api/1/license/check

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

API request example

https://10.30.17.131/api/1/license/check

Returned JSON object

{
    "daysLeft" : "365 day(s)",
    "expiration" : "Thu May 18 2017",
    "licensedType" : "eval",
    "licensedVersion" : "16.6",
    "machineID" : "6YZ6XEPTA66JA6VHFPXG749B",
    "role" : "failover"
}

Profile#

Used to manage profile settings and behavior

Renaming a profile#

Rename profile API call

Resource URL: Renames an existing profile

https://[replicator]/api/1/profile/rename/[current]/[new]

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

[current]

Name of the profile to be renamed

[new]

New name for the profile

API request example

https://10.30.17.131/api/1/profile/rename/oldprofile/myprofile

Returned JSON object

{
    "description": "Success: Profile 'oldprofile' is now 'myprofile'",
    "result": "success"
}

Toggling singularity setting#

Singularity toggle API call

Resource URL: Toggles the singularity setting for a profile

https://[replicator]/api/1/profile/singularity/[name]/[action]

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

[name]

Name of the profile to be updated

[action]

enable or disable

API request example

https://10.30.17.131/api/1/profile/singularity/myprofile/enable

Returned JSON object

{
    "description": "Success: Profile 'myprofile' singularity enabled",
    "result": "success"
}

Removing, disabling, or enabling a profile#

Profile state management API call

Resource URL: Removes, disables, or enables a profile

https://[replicator]/api/1/profile/[action]/[name]

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

[action]

remove, disable, or enable

[name]

Target profile for the operation

API request example

https://10.30.17.131/api/1/profile/disable/myprofile

Returned JSON object

{
    "description": "Success: Profile myprofile has been set to 'disable'",
    "result": "success"
}

Creating or updating a profile#

Create/update profile API call

Resource URL: Creates a new profile or updates an existing profile

https://[replicator]/api/1/profile/[action]/[name]/[listeningport]/[sendingport]

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

[action]

add or update

[name]

Name of the profile to create or update

[listeningport]

UDP port to listen to for incoming packets (In Port)

[sendingport]

The UDP port to send packets from (Out Port)

API request example

https://10.30.17.131/api/1/profile/add/myprofile/2055/4739

Returned JSON object

{
    "description": "Success: Profile 'myprofile' has been added and enabled.",
    "result": "success"
}

Collector#

Used for collector management operations for profiles

Add/remove collector for profile API call

Resource URL: Manages a collector for an individual profile

https://[replicator]/api/1/collector/[action]/[ip]/[profile]

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

[action]

add or remove

[ip]

IP address of the collector

[profile]

Target profile for the operation

API request example

https://10.30.17.131/api/1/collector/add/10.1.10.60/myprofile

Returned JSON object

{
  "description": "Success: Collector [10.1.10.60] -> Profile [myprofile]",
  "result": "success"
}
Remove collector from all profiles API call

Resource URL: Removes a collector from all profiles

https://[replicator]/api/1/collector/allremove/[ip]

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

[ip]

IP address of the collector to be removed

API request example

https://10.30.17.131/api/1/collector/allremove/10.1.10.4

Returned JSON object

{
  "description": "Success: Collector [10.1.10.4] <- All Profiles",
  "result": "success"
}

Exporter#

Used for exporter management operations for profiles

Managing an exporter for an individual profile#

Add/remove exporter for profile API call

Resource URL: Manages an exporter for an individual profile

https://[replicator]/api/1/exporter/[action]/[ip]/[profile]

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

[action]

add or remove

[ip]

IP address of the exporter

[profile]

Target profile for the operation

API request example

https://10.30.17.131/api/1/exporter/add/10.1.1.1/myprofile

Returned JSON object

{
  "description": "Success: Exporter [10.1.1.1] -> Profile [myprofile]",
  "result": "success"
}

Removing an exporter from all profiles#

Remove exporter from all profiles API call

Resource URL: Removes an exporter from all profiles

https://[replicator]/api/1/exporter/allremove/[ip]

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

[ip]

IP address of the exporter to be removed

API request example

https://10.30.17.131/api/1/exporter/allremove/10.1.1.4

Returned JSON object

{
   "description": "Success: Exporter [10.1.1.4] <- All Profiles",
   "result": "success"
}

Identifying exporters not assigned to profiles#

List unassigned exporters API call

Resource URL: Identifies exporters that are sending data to the Replicator but not assigned to any profiles

https://[replicator]/api/1/exporter/noprofile/[filter]

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

[filter]

Optional filter to apply to the displayed list of exporters not assigned to any profiles; returns the full list if not provided

API request example

https://10.30.17.131/api/1/exporter/noprofile/0

Returned JSON object

{
  "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
  }
}

Policies#

Used to manage policies for profiles

Policy management API call

Resource URL: https://[replicator]/api/1/policies/[action]/[network]/[cidr]/[profile]/[incexc]

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

[action]

add or remove

[network]

address of the network (e.g. 172.17.0.0)

[cidr]

CIDR of the network specified (e.g. 16)

[profile]

Target profile for the operation

[incexc]

include or exclude

API request example

https://10.30.17.131/api/1/policies/add/10.1.20.0/16/myprofile/include

Returned JSON object

{
    "description": "Success: Policy [10.1.20.0/16] -> Profile [myprofile]",
    "result": "success"
}

Threshold#

Used to set packet per second thresholds that will trigger warnings for collectors

Threshold configuration API call

Resource URL: https://[replicator]/api/1/collector/threshold/[collector]/[threshold]

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

[collector]

IP address of the collector

[threshold]

Threshold value in packets per second; disabled if set to 0

API request example

https://10.30.17.131/api/1/collector/threshold/10.1.5.2/10000

Returned JSON object

{
  "description": "Success: Collector [10.1.5.2] threshold set to 10000",
  "result": "success"
}

Setting#

Used to manage the Replicator appliance’s global settings

Setting a value#

Set configuration value API call

Resource URL: Sets the value for the specified setting

https://[replicator]/api/1/setting/set/[name]/[value]

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

[name]

Exact name of the setting to modify

[value]

New value for the setting specified

API request example

https://10.30.17.131/api/1/setting/set/metricssent/10.1.2.3:2055

Returned JSON object

{
    "description": "Success: setting 'metricssent' has been set to '10.1.2.3:2055'",
    "result": "success"
}

Enabling or disabling a feature#

Enable/disable feature API call

Resource URL: Enables or disables the specified feature

https://[replicator]/api/1/setting/[action]/[name]

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

[action]

enable or disable

[name]

Exact name of the feature to enable/disable

API request example

https://10.30.17.131/api/1/setting/disable/metricssent

Returned JSON object

{
    "description": "Success: setting 'metricssent' has been set to 'disable'",
    "result": "success"
}

Acknowledge#

Used to acknowledge collectors and exporters that have triggered alarms

Acknowledgment API call

Resource URL: https://[replicator]/api/1/acknowledge/[entity]/[ip:port]

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

[entity]

exporter or collector

[ip:port]

IP address and port of the [entity] to be acknowledged

API request example

https://10.30.17.131/api/1/acknowledge/collector/10.1.10.4:2055

Returned JSON object

{
   "description": "Success: collector '10.1.10.4:2055' acknowledged.",
   "result": "success"
}

Notate#

Used to add a description to an exporter, collector, or profile

Add description API call

Resource URL: https://[replicator]/api/1/notate/[entity]/[identity]/[description]

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

[entity]

profile or ip

[identity]

[profile_name] or [ip_address] of entity specified

[description]

Description or note to add to the entity in standard ASCII URI-compatible characters

API request example

https://10.30.17.131/api/1/notate/profile/myprofile/My_Fantastic_Description

Returned JSON object

{
    "description": "Success: Profile 'myprofile' has a new description",
    "result": "success"
}

DNSCheck#

Used to perform a DNS check on an IP address

DNS resolution API call

Resource URL: Forces a DNS name resolution for an IP address

https://[replicator]/api/1/dnscheck/[ip]

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

[ip]

IP address to resolve

API request example

https://10.30.17.131/api/1/dnscheck/10.1.1.3

Returned JSON object

{
  "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"
  }
}

Rebuild#

Used to force the Replicator appliance to immediately rebuild its internal configuration

Configuration rebuild API call

Resource URL: https://[replicator]/api/1/rebuild

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

API request example

https://10.30.17.131/api/1/rebuild

Returned JSON object

{
    "description": "rebuild request submitted",
    "result": "success"
}

Role#

Used to test whether a secondary appliance in a high availability configuration has been configured correctly

HA role test API call

Resource URL: https://[replicator]/api/1/role/test/secondary

Parameter

Description

[replicator]

Hostname or IP address of the Replicator

API request example

https://10.30.17.131/api/1/role/test/secondary

Returned JSON object

{
    "description": "!!! This replicator is the primary !!!",
    "result": "error"
}
Contents