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

https://10.30.17.131/api/1/login/098f6bcd4621d373ca098f6bcd4621d563cade4e832629b4f6d098f4bcd4621d373cade4e831627b4f6e4e832627b4f

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!”

}