The FlowTraq Web API provides a RESTful interface for retrieving flow data, aggregations, and alerts; and for configuring FlowTraq. All responses are provided in JSON format.
A successful response (which may include a response with an empty value) will return an HTTP code of 200 or 204. If the response is 200, the service will respond with a JSON object with the first key mirroring the last section of the requested path. For example, a successful call to api/v3/info will be a JSON object {'info': {...}} while a call to api/v3/info/licensekeyinfo will be a JSON object {'licensekeyinfo': {...}}. If the response is 204, there will be no payload.
An unsuccessful response will return an HTTP error code (typically 404 Not Found, 403 Forbidden, or 500 Server Error) and a JSON object containing a 'message' key. For example,
{'message': 'Provided credentials were rejected or session key has expired'}
In general, a valid, well-formatted request that cannot be found (e.g. retrieving a valid key that happens to not be set) will return a 404 error. Errors in authentication (including attempting actions not permitted to this user), request format, etc. will return a 403 error. Server errors such as FlowTraq not responding will return 500 errors.
![[Note]](../common/images/admon/note.png) | Note |
|---|---|
By default, FlowTraq does not permit API access via HTTP. To enable API access over HTTP (as opposed to HTTPS) add the line,
To the config.php file in the FlowTraq Web main directory (typically |
Every API call must contain authentication information. There are two options for authenticating. First, basic HTTP authentication can be used with a FlowTraq username and password. For example, using cURL:
curl -u USERNAME:PASSWORD "https://example.com/flowtraq/api/v3/sessions/
The second method is to generate a FlowTraq session key and provide that as part of the HTTP header:
curl -k -H "ftsessionkey: aeb70b050dd8d4230e6debaa4bc11d36"
A session key can be generated by a POST call to the endpoint sessionkey or login
POST https://example.com/flowtraq/api/v3/sessionkey
| Parameter Name | Value | Default Value | Notes |
|---|---|---|---|
| username | string | required | Username of a user on the Flowtraq server. |
| password | string | required | Password of the Flowtraq server user. |
Using cURL as an example, this can be performed with the following command. Note the use of the application/json content type.
curl "https://example.com/flowtraq/api/v3/sessionkey" -d '{"username":"USERNAME","password":"PASSWORD"}' -H "Content-Type: application/json"
{"sessionkey":"479d2d621afbed1dd0daa2ea7bd98df5"}
This session key can be used for repeated requests. Each request will keep the key alive.
| Note |
|---|---|
Many FlowTraq installs do not have SSL keys; add the "-k" flag to cURL to override that limitation. |
If the request is successful, the return code will be 200, and the result (in JSON format) will be as follows:
| Parameter Name | Value | Notes |
|---|---|---|
| sessionkey | string | Only returned if authentication successful. |
If the request is NOT successful, the return code will be other than 200 (typically 403 for login failures), and the result (in JSON format) will be as follows:
| Parameter Name | Value | Notes |
|---|---|---|
| message | string | Describes the error condition. |
| Note |
|---|---|
On some systems, when the request header contains Accept: application/json, Apache will return a 406 Not Acceptable error. This can be overridden by adding
becomes,
|
GET https://example.com/flowtraq/api/v3/sessions
| Parameter Name | Value | Default Value | Notes |
|---|---|---|---|
| relative_time | time descriptor | none | A relative time in the form of number and unit; e.g. "15m" for "15 minutes" or "2h" for "2 hours". Accepts "m" for "minute", "h" for "hour", "d" for "day", "w" for "week" and "y" for "year" |
| start_time | timestamp | none | A timestamp in the format "MM/DD/YY hh:mm:ss.microsec" or an integer in seconds since the UNIX epoch |
| end_time | timestamp | none | A timestamp in the format "MM/DD/YY hh:mm:ss.microsec" or an integer in seconds since the UNIX epoch |
| filter | string | none | A filter string as described in Section 3.4.4, “Filter String Syntax”. |
| sample_count | number | 0 | Return only the first N session records (typically, but not always the first sessions); set to 0 to retrieve all sessions, or omit entirely. |
A successful response will contain the resulting data table:
| Parameter Name | Value | Notes |
|---|---|---|
| data | [{FlowObject}] | An array of flow records. |
The response will contain either the resulting data table or an error message:
| Parameter Name | Value | Notes |
|---|---|---|
| CLIENT ADDRESS | String | IP address of the endpoint identified as the client (initiator of session) |
| CLIENT MASK | String | The netblock the client address belongs to, as identified by router or ASN lookup |
| CLIENT COUNTRY | String | Country code associated with the client address according to reverse lookup |
| CLIENT AS | String | Autonomous system to which the client address belongs, according to router or reverse lookup |
| CLIENT TG | String | Traffic group to which the client address belongs |
| SPORT | String | Source port, associated with client side of communication |
| SERVER ADDRESS | String | IP address of the endpoint identified as the server (receiver of session) |
| SERVER MASK | String | The netblock the server address belongs to, as identified by router or ASN lookup |
| SERVER COUNTRY | String | Country code associated with the server address according to reverse lookup |
| SERVER AS | String | Autonomous system to which the server address belongs according to router or reverse lookup |
| SERVER TG | String | Traffic group to which the server address belongs |
| DPORT | String | Destination port, associated with server side of communication |
| PROTO | String | Protocol as identified in packet headers; string from IANA protocol list, or number if not found/known |
| CLN PKTS | String | Number of packets sent from client to server over session history. Not statistically reconstructed when sampling is used, this is the raw total reported by the router |
| CLN BYTES | String | Number of octets sent from client to server over session history. Not statistically reconstructed when sampling is used, this is the raw total reported by the router |
| SRV PKTS | String | Number of packets sent from server to client over session history; may be 0. Not statistically reconstructed when sampling is used, this is the raw total reported by the router |
| SRV BYTES | String | Number of octets sent from server to client over session history; may be 0. Not statistically reconstructed when sampling is used, this is the raw total reported by the router |
| START TIME | String | Time of first-observed packet in this session |
| LAST UPDATE | String | Time of most recent packet in this session |
| TTIME | String | Total time elapsed in session |
| FLAGS | String | Compiled list of all TCP flags seen in session |
| TOS | String | Raw TOS/QOS/DiffServ number (interpreted differently depending on how number is used) |
| EXPORTER ADDRESS | String | Observed IP address of the device reporting this session (affected by NATting) |
| EXPV | String | Flow version in which exporter encoded this session data |
| CID | String | Partition ID number |
| SAMPL | String | Reported sampling rate |
| UPDTS | String | Number of flow updates comprising this session |
| IFIN | String | Ingress interface number, with ring number denoted by @ (e.g. 1 @0 is interface 1 in ring 0) |
| IFOUT | String | Egress interface number |
| VLANIN | String | Ingress VLAN |
| VLANOUT | String | Egress VLAN |
| CLNMAC | String | MAC address associated with client side of communication |
| SRVMAC | String | MAC address associated with server side of communication |
| APPLICATION | String | Application as (sometimes) reported by exporter, such as using NBAR or AppID |
Because the full structure of the ordinary JSON output adds considerably to the file size, large retrievals may benefit from using compact mode, which sends the result in two arrays: a 'header' array containing the names of the variables, and a 'data' array, containing arrays of strings in the same order as the header array. (e.g. the first entry in the 'header' array is CLIENT IP, and the first element in each data array is the client IP)
GET https://example.com/flowtraq/api/v3/sessions/compact
| Parameter Name | Value | Default Value | Notes |
|---|---|---|---|
| relative_time | time descriptor | none | A relative time in the form of number and unit; e.g. "15m" for "15 minutes" or "2h" for "2 hours". Accepts "m" for "minute", "h" for "hour", "d" for "day", "w" for "week" and "y" for "year" |
| start_time | timestamp | none | A timestamp in the format "MM/DD/YY hh:mm:ss.microsec" or an integer in seconds since the UNIX epoch |
| end_time | timestamp | none | A timestamp in the format "MM/DD/YY hh:mm:ss.microsec" or an integer in seconds since the UNIX epoch |
| filter | string | none | A filter string as described in Section 3.4.4, “Filter String Syntax”. |
| sample_count | number | 0 | Return only the first N session records (typically, but not always the first sessions); set to 0 to retrieve all sessions, or omit entirely. |
The 'count' endpoint performs a query using the provided parameters, but returns only the number of sessions that match the time frame and filter provided. This does perform a full query and so may take some time, but it can greatly reduce bandwidth and client memory use in cases where a simple answer is needed, or can help determine whether it is feasible to download the entire list of sessions.
GET https://example.com/flowtraq/api/v3/sessions/count
| Parameter Name | Value | Default Value | Notes |
|---|---|---|---|
| relative_time | time descriptor | none | A relative time in the form of number and unit; e.g. "15m" for "15 minutes" or "2h" for "2 hours". Accepts "m" for "minute", "h" for "hour", "d" for "day", "w" for "week" and "y" for "year" |
| start_time | timestamp | none | A timestamp in the format "MM/DD/YY hh:mm:ss.microsec" or an integer in seconds since the UNIX epoch |
| end_time | timestamp | none | A timestamp in the format "MM/DD/YY hh:mm:ss.microsec" or an integer in seconds since the UNIX epoch |
| filter | string | none | A filter string as described in Filter String Syntax. |
The table endpoint provides the ability to retrieve the results of an ftstat command, equivalent to a FlowTraq workspace. The returned results include a time series of the "count by" value suitable for graphing.
GET https://example.com/flowtraq/api/v3/table
| Parameter Name | Value | Default Value | Notes |
|---|---|---|---|
| relative_time | time descriptor | 15m (if not superceded by start_time and end_time) | A relative time in the form of number and unit; e.g. "15m" for "15 minutes" or "2h" for "2 hours". Accepts "m" for "minute", "h" for "hour", "d" for "day", "w" for "week" and "y" for "year" |
| start_time | timestamp | none | A timestamp in the format "MM/DD/YY hh:mm:ss.microsec" or an integer in seconds since the UNIX epoch; must also include end_time, or relative_time will be used |
| end_time | timestamp | none | A timestamp in the format "MM/DD/YY hh:mm:ss.microsec" or an integer in seconds since the UNIX epoch; must also include end_time |
| filter | string | none | A filter string as described in Section 3.4.4, “Filter String Syntax”. |
| group_by | one of: IP, IPPAIR, PORTPROTO, QOS, TCPFLAGS, IF, IFPAIR, COUNTRY, VLAN, VLANPAIR, ASN, ASNPAIR, MAC, MACPAIR, SRVIPPORT, CLNSRVIPPORT, EXPIPVERS, CID, SAMPRATE, CIDR, CIDRPAIR, TG, EXPIF, EXPIFPAIR, CLNPORTPROTO, IPROTOCOL, APPLICATION, SRVCIDRPORT, CLNSRVCIDRPORT, SRVIPCLNPORT, SRVCIDRCLNPORT | ||
| count_by | One of: BYTES, BITS, SESSIONS, PACKETS, NEWCONN, UNIQUE, or UPDATES | "UNIQUE" requires the unique field, below | |
| unique | One of: IP, PORTPROTO, QOS, TCPFLAGS, IF, COUNTRY, VLAN, ASN, MAC, MACPAIR, SRVIPPORT, CLNSRVIPPORT, EXPIPVERS, CID, SAMPRATE, CIDR, CIDRPAIR, TG, EXPIF, EXPIFPAIR, CLNPORTPROTO, IPROTOCOL, APPLICATION, SRVCIDRPORT, CLNSRVCIDRPORT, SRVIPCLNPORT, SRVCIDRCLNPORT | ||
| direction | One of snd or rcv (if omitted, will use both) | ||
| rows | 10 | May include an extra row for "OTHER" | |
| time_series | 175 |
A successful response will contain the resulting data table. The exact parameters of this table will vary according to the request made, but will always contain the following:
| Parameter Name | Value | Notes |
|---|---|---|
| table | Array (see following table) | An array of table entries in order of rank. |
| Parameter Name | Value | Notes |
|---|---|---|
| (Group Entry) | (Varies) | Matches the selected group_by from the request (Default: ADDRESS) |
| (Rank Entry) | (Varies) | Matches the selected count_by from the request (Default: BYTES TOTAL) |
| TOT. BYTES | Integer | Total bytes sent or received |
| TOT. PACKETS | Integer | Total packets sent or received |
| CID | Integer | Partition ID |
| CID NAME | String | Partition name |
| COLORS | String | Unique encoded color value based on user preference |
| TIME SERIES | Space-separated list of integers | Rank entry broken up evently across the time frame |
The alerts endpoint provides the ability to retrieve alerts, equivalent to a FlowTraq alert page retrieval. Pre-filtering is limited; it is recommended that most filtering be performed client-side.
GET https://example.com/flowtraq/api/v3/alerts
| Parameter Name | Value | Default Value | Notes |
|---|---|---|---|
| relative_time | time descriptor | 15m (if not superceded by start_time and end_time) | A relative time in the form of number and unit; e.g. "15m" for "15 minutes" or "2h" for "2 hours". Accepts "m" for "minute", "h" for "hour", "d" for "day", "w" for "week" and "y" for "year" |
| start_time | timestamp | none | A timestamp in the format "MM/DD/YY hh:mm:ss.microsec" or an integer in seconds since the UNIX epoch; must also include end_time, or relative_time will be used |
| end_time | timestamp | none | A timestamp in the format "MM/DD/YY hh:mm:ss.microsec" or an integer in seconds since the UNIX epoch; must also include end_time |
| cid | partition number | none | Select a partition to retrieve alerts from, either instead of or in addition to filter parameter. |
| tg | traffic group number | none | Select a traffic group to retrieve alerts from, either instead of or in addition to filter parameter. |
| exp | exporter IP address | none | Select an exporter to retrieve alerts from, either instead of or in addition to filter parameter. |
| iface | interface number | none | Select an interface to retrieve alerts from, either instead of or in addition to filter parameter. exp must be present, or this parameter will be ignored. |
| filter | string | none | A filter string as described in Section 3.4.4, “Filter String Syntax”. Alerts do not have the same fields as session records; filter-matching is best-effort according to alert contents. |
A successful response will contain the resulting data table. The exact parameters of this table will vary according to the request made, but will always contain the following:
| Parameter Name | Value | Notes |
|---|---|---|
| alerts | Array (see following table) | An array of alerts, not ordered. |
| Parameter Name | Value | Notes |
|---|---|---|
| alert_type | ||
| id | ||
| CID | ||
| earliest_utc | ||
| latest_utc | ||
| plugin_actions | (See plugin actions table) | |
| tg (if applicable) | ||
| exporter_address (if applicable) | ||
| iface (if applicable) | ||
| severity |
If plugin actions were taken, the plugin_actions will contain an array of the following objects:
| Parameter Name | Value | Notes |
|---|---|---|
| aid | Action ID | |
| plugin_name | ||
| current_state | ||
| var_count | (internal field) | |
| hold_remaining | (internal field; reserved for future use) |
Traffic groups and blacklists are organized in a short hierarchy. First, the base URL value (either "trafficgroups" or "blacklists") selects the type of IP list being addressed. The next level of organization is the Partition (called "cid"), which is nearly always "cid0" for blacklists. Finally each traffic group or blacklist is addressed by number; e.g. "tg5" or "bl3". There is no overlap in numbering between the two; the prefix is used to make sure that the type is preserved.
The overall structure, therefore, is:
{
"trafficgroups": {
"cid0": {
"tg1": {TG ENTRY},
"tg2": {TG ENTRY}
},
"cid1": {
"tg3": {TG ENTRY}
}
}
}
The "TG ENTRY" (also used for blacklists) has three elements:
| Element Name | Notes |
|---|---|
| name | Name of the traffic group or blacklist; required; need not be unique |
| filter | Optional filter restricting application of TG/BL designation, in the form of an ordinary ftstat filter |
| blocks | Array containing a list of at least one IP address or CIDR block; required |
Individual portions of a traffic group can be addressed, e.g.: https://example.com/flowtraq/api/v3/trafficgroups/cid0/tg5/name refers directly to the name of Traffic Group 5 in Partition 0. A GET request to that endpoint will return {"name": "Traffic Group 5's Name"} if that traffic group exists. Similarly, a POST or PUT request to that endpoint with the JSON-formatted payload {"name": "Traffic Group 5's New Name"} will rename Traffic Group 5.
Entire traffic groups can be updated with POST or PUT, by uploading the new JSON-formatted traffic group. If it's performed as a PUT, then the traffic group definition will match exactly what's uploaded -- if no filter is included, then any existing filter will be removed. Any block not in the new definition will be removed. If the definition is uploaded as a POST, then omitted items (name, filter, individual blocks) will not be affected; the resulting definition will include any new blocks, but none will be deleted. To create a new traffic group, the special endpoints api/v3/trafficgroups/cidX/tg or api/v3/blacklists/cidX/bg (in both cases replacing "X" with a number such as 0) can be used with a PUT or POST, and the new assigned number will be included in the output (in the following example, the resulting assignment was to blacklist 11).
# curl -k -H "ftsessionkey: f5a31950af869e1761bafed1cd6823a9" \
-H "Content-Type: application/json" "https://example.com/flowtraq/api/v3/blacklists/cid0/bl" \
-X POST -d '{"bl": {"name": "My New TG", "blocks": ["8.8.8.1/32"]}}'
{"bl11":{"name":"My New TG","blocks":["8.8.8.1\/32"]}}
A DELETE call can be used to remove whole traffic groups, or filters. It cannot be used to delete multiple traffic groups (e.g. via a call to an endpoint /api/v3/cid#) nor to delete required items like "name".
Administrative users can retrieve a list of users through the users endpoint. Output is in the form of an array indexed by username.
GET https://example.com/flowtraq/api/v3/users
Each user block contains four elements:
| Element Name | Notes |
|---|---|
| role | One of: USER or ADMIN |
| last_login | The date and time, in server time, at which this user last authenticated. |
| userfilter | Optional filter restricting user access to data, in addition to partition; null for ADMIN users |
| cid | Partition (also called customer ID) to which this user is bound, or 0 if global |
{
"users": {
"@abarsam": {
"role": "USER",
"last_login": "10/31/2016 19:46:01",
"userfilter": "None",
"cid": "1"
},
"@admin": {
"role": "ADMIN",
"last_login": "08/1/2017 03:54:41",
"userfilter": null,
"cid": "0"
}
}
| Note |
|---|---|
In order to avoid potential namespace collision issues, usernames must be prepended with an '@' sign. That sign is included in the output for consistency. If a username begins with an '@' sign, the output will include two, and addressing attempts must include two. |
Individual users may be addressed, as well as the four available keys (role, last_login, userfilter, cid).
GET https://example.com/flowtraq/api/v3/users/@USERNAME
These endpoints do not currently support POST, PUT, or DELETE.
| Note |
|---|---|
The @USERNAME endpoint does not retrieve the preferences list, as this is an expensive operation. |
The FlowTraq API can be used to get and set user preferences, individually and in batches. An administrative user can make changes to other users' preferences (in order to, for example, copy dashboards from one user to another). The basic endpoint, retrieving all of a user's keys (which may take some time) is:
https://example.com/flowtraq/api/v3/users/@USERNAME/prefs
Listing of individual preferences is beyond the scope of this document, but there are several useful structures that are commonly copies between users, such as individual dashboards (listed hierarchically under prefs/USERNAME/dashboard, with individual dashboards listed as d0, d1, etc.) To copy one user's dashboards over another users, save the results (in JSON format) of a GET request to api/v3/prefs/DONORUSER/dashboard, and PUT the same structure to api/v3/prefs/RECIPIENTUSER/dashboard. For example:
{
"prefs": {
"userfilter": "(TGRP==1||TGRP==27))",
"dashboard": {
"d0": {
"w0": "{\"widgetVersion\":1,\"widgetType\":6,\"widgetTitle\":\"Welcome Widget\"}",
"w1": "{\"widgetVersion\":1,\"widgetType\":5,\"widgetTitle\":\"\",\"viewSpec\":
{\"filter\":\"\",\"timeRange\":\"3h\",\"viewSelection\":\"tg,bytes,,snd,\"},\"showChart\":true,
\"showLegend\":false,\"showTable\":true,\"refreshRate\":\"180\"}",
"arrangement": "[[\"0\"],[\"1\"]]"
}
},
"colorscheme": "1b9e77d95f027570b3e7298a66a61ee6ab02a6761d666666"
}
}
Individual nested values may be addressed directly, and will take less time to retrieve. For example, to retrieve a specific dashboard:
GET https://example.com/flowtraq/api/v3/users/@USERNAME/prefs/dashboard/d0
This returns the d0 stanza:
{
"d0": {
"w0": "{\"widgetVersion\":1,\"widgetType\":6,\"widgetTitle\":\"Welcome Widget\"}",
"w1": "{\"widgetVersion\":1,\"widgetType\":5,\"widgetTitle\":\"\",\"viewSpec\":
{\"filter\":\"\",\"timeRange\":\"3h\",\"viewSelection\":\"tg,bytes,,snd,\"},\"showChart\":true,
\"showLegend\":false,\"showTable\":true,\"refreshRate\":\"180\"}",
"arrangement": "[[\"0\"],[\"1\"]]"
}
}
PUT, POST, and DELETE also work with user preferences, both individual preferences addressed directly, and preference trees. When addressing individual preferences, PUT and POST work identically. E.g. POST https://example.com/flowtraq/api/v3/users/@USERNAME/prefs/dashboard/d0/w0 sets the widget 0 on dashboard 0 (with a JSON-formatted payload, not shown), as does PUT. However, whole stanzas operate differently; a PUT of a stanza will delete entries not listed in the stanza, while a POST ignores those entries. If the user's dashboard d0 is as set above, then,
POST https://example.com/flowtraq/api/v3/users/@USERNAME/prefs/dashboard/d0 with the payload,
{
"d0": {
"w0": "{\"widgetVersion\":1,\"widgetType\":5,\"widgetTitle\":\"\",\"viewSpec\":
{\"filter\":\"\",\"timeRange\":\"3h\",\"viewSelection\":
\"tg,bytes,,snd,\"},\"showChart\":true,\"showLegend\":false,\"showTable\":
true,\"refreshRate\":\"180\"}",
"arrangement": "[[\"0\"],[\"1\"]]"
}
}
Results in,
{
"d0": {
"w0": "{\"widgetVersion\":1,\"widgetType\":5,\"widgetTitle\":\"\",\"viewSpec\":
{\"filter\":\"\",\"timeRange\":\"3h\",
\"viewSelection\":\"tg,bytes,,snd,\"},\"showChart\":true,\"showLegend\":false,
\"showTable\":true,\"refreshRate\":\"180\"}",
"w1": "{\"widgetVersion\":1,\"widgetType\":5,\"widgetTitle\":\"\",\"viewSpec\":
{\"filter\":\"\",\"timeRange\":\"3h\",\"viewSelection\":
\"tg,bytes,,snd,\"},\"showChart\":true,\"showLegend\":false,\"showTable\":true,
\"refreshRate\":\"180\"}",
"arrangement": "[[\"0\"],[\"1\"]]"
}
}
While PUTting the same payload deletes the unspecified w1key, so that the PUT payload is the entirety of the key structure:
{
"d0": {
"w0": "{\"widgetVersion\":1,\"widgetType\":5,\"widgetTitle\":\"\",\"viewSpec\":
{\"filter\":\"\",\"timeRange\":\"3h\",\"viewSelection\":
\"tg,bytes,,snd,\"},\"showChart\":true,\"showLegend\":false,
\"showTable\":true,\"refreshRate\":\"180\"}",
"arrangement": "[[\"0\"],[\"1\"]]"
}
}
A DELETE request will, similarly, remove the entire block. (Note: DELETE will not work on the base @USERNAME/prefs endpoint)
FlowTraq configuration parameters, as set in the flowtraq.conf file can be set through the API, for one or more FlowTraq nodes. The basic endpoint for configuration is:
GET https://example.com/flowtraq/api/v3/config
Output varies according to settings, but will resemble the following:
{
"config": {
"userdata": {
"userdatapath": "USERDATA",
"maxsessionkeyage": "3600"
},
"querythreads": "3",
"listenport": "9640",
"sflow": {
"bufsize": "8388608",
"sflowport": "6343"
},
"recursion": {
"forwardmode": "balance",
"localmode": "keep"
},
"storage": {
"storageinterval": "7.5",
"autoconfigure": "64GB",
"databasepath": "/opt/flowtraq/SESSIONDB"
},
"totalram": "85 %",
"quickview": {
"1hr": {
"autoconfigure": "8GB",
"databasepath": "NBI2/QVIEW1HR"
},
"1min": {
"autoconfigure": "8GB",
"databasepath": "NBI2/QVIEW1MIN"
},
"5min": {
"autoconfigure": "8GB",
"databasepath": "NBI2/QVIEW5MIN"
}
},
"detection": {
"dt": "65",
"pctl": "1/1"
},
"syslog": {
"facility": "LOCAL0"
},
"user": "USERNAME",
"debuglevel": "MEDIUM",
"netflow": {
"ipfixtcpport": "4739",
"netflowport": "2055 9666 9996",
"ignoreoldnetflows": "no",
"bufsize": "16777216"
},
"maxclientlatency": "30",
"archive": {
"databasepath": "/opt/flowtraq/ARCHIVE",
"autoconfigure": "128G"
},
"sessiontables": {
"toolong": "7200",
"timeout": "1800"
}
}
}
As with the user preferences, individual values or stanzas can be addressed, e.g.:
GET https://example.com/flowtraq/api/v3/config/netflow
{
"netflow": {
"ipfixtcpport": "4739",
"netflowport": "2055 9666 9996",
"ignoreoldnetflows": "no",
"bufsize": "16777216"
}
}
GET https://example.com/flowtraq/api/v3/config/netflow/netflowport
{
"netflowport": "2055 9666 9996"
}
As with user preferences, individual keys and stanzas can be set using PUT and POST. If the value being set is stored as a single string (e.g. netflowport is set to "2055 9666 9996" in the above case) then a POST of a value will overwrite the whole string. POSTing,
{
"netflowport": "2056"
}
to the endpoint config/netflow/netflowport will result in the netflowport being set to "2056", not "2056 2055 9666 9996". The PUT/POST difference operates only at the stanza level -- e.g. omitting ipfixtcpport from a PUT to config/netflow is equivalent to DELETEing config/netflow/ipfixtcpport, but POSTing the same stanza omitting that key leaves it in place.
| Note |
|---|---|
Some parameters which cannot be retrieved can still be set through this interface via a PUT or POST. Currently this includes |
Without further arguments, this endpoint returns the configuration parameters for the FlowTraq portal (single-node installs will always use this and will not require other endpoints.) To address individual nodes, use the path GET parameter path. The path parameter accepts a dotted notation as follows:
| Path | Addressed Nodes | Example output with config/netflow/netflowport |
|---|---|---|
| (omitted) | Portal only |
{
"netflowport": {
"local": "2055 9666 9996"
}
}
|
| 1 | Worker #1, if there is a worker #1 belonging to the portal |
{
"netflowport": "2055 9666 9996"
}
|
| * | All of the portal's workers, and the portal itself, labeled "local". Note: If the portal has no workers, this (like any all-wildcard entry) will be treated as though the path were omitted. |
{
"netflowport": {
"local": "2055 9666 9996",
"0": "2055 9666 9996",
"1": "2055 9666 9996"
}
}
|
| 0.1 | Worker #0's Worker #1 |
{
"netflowport": "2055"
}
|
| *.1 | For each of the portal's workers, that worker's worker #1. |
{
"netflowport": {
"1": "2055 9666 9996",
"0.1": "2055",
"1.1": "2055"
}
}
|
![[Important]](../common/images/admon/important.png) | Important |
|---|---|
GET parameters need to be URL encoded, so the
|
Current information about the FlowTraq install is available via the info endpoint. There is typically no need to reference these values on a day-to-day basis, but they are typically useful for troubleshooting FlowTraq's operations in the event of a problem, or for the purposes of integrating with third-party monitoring tools. The full list contains a number of items that are for internal or specialized use (such as for debugging trouble conditions). It is divided into five basic sections:
storageperfinfoInformation related to storage performance
databaseinfoInformation related to the main session database
sessiontableinfoInformation related to the RAM-based cache of sessions
licenseinfoInformation about the current license installed on the selected host
basicinfoA collection of additional parameters used for a variety of purposes.
The info endpoint operates similarly to the config endpoint, in its usage of the path parameter, and in the ability to select specific sections or individual entries. For example, the following URL will select the license status of every node in a three-level cluster:
GET https://example.com/flowtraq/api/v3/info/licenseinfo/STATUS?path=%2A.%2A.%2A
{
"STATUS": {
"local": "license OK",
"1": "license OK",
"0": "license OK",
"1.0": "license OK",
"1.1": "license OK",
"0.0": "license OK",
"0.1": "license OK"
}
}
Because of the informational nature of this endpoint, it does not accept PUT, POST, or DELETE requests.
Exporters and their interfaces are managed through the partitions endpoint. To get a full list of all (visible) partitions, including the list of exporters that have sent data to those partitions and the reporting interfaces on those exporters, use the basic endpoint:
GET https://example.com/flowtraq/api/v3/partitions
{
"partitions": {
"cid0": {
"exporters": {
"exp10.100.2.1": {
"iface1": {
"clockSkewMs": "0",
"bitRateOut": 8000,
"bitRateInLearned": false,
"flowVersion": "IPFIX",
"bitRateIn": 4,
"bitRateOutLearned": false,
"clockSkewCorrection": false,
"friendlyName": "onesixone one",
"ring": 0,
"sampleRateLearned": true,
"sampleRate": 1
},
[...]
},
[...]
}
}
"cid10": {
"exporters": {
"exp127.0.0.1": {
"iface63": {
"clockSkewMs": "0",
"bitRateOut": 19127,
"bitRateInLearned": true,
"flowVersion": "NFv1",
"bitRateIn": 25253,
"bitRateOutLearned": true,
"clockSkewCorrection": false,
"friendlyName": "",
"ring": 0,
"sampleRateLearned": true,
"sampleRate": 0
},
[...]
}
}
},
"cid7": {
"exporters": {
"exp127.0.0.1": {
"iface32": {
"clockSkewMs": "0",
"bitRateOut": 0,
"bitRateInLearned": true,
"flowVersion": "NFv9",
"bitRateIn": 33586,
"bitRateOutLearned": true,
"clockSkewCorrection": false,
"friendlyName": "",
"ring": 0,
"sampleRateLearned": true,
"sampleRate": 1
},
[...]
}
}
}
}
}
Individual partitions are selected using the "cidnumber" notation:
GET https://example.com/flowtraq/api/v3/partitions/cid7
"cid7": {
"exporters": {
"exp192.168.18.21": {
"iface0": {
"clockSkewMs": "261",
"bitRateOut": 21830742,
"bitRateInLearned": true,
"flowVersion": "NFv1",
"bitRateIn": 0,
"bitRateOutLearned": true,
"clockSkewCorrection": false,
"friendlyName": "",
"ring": 0,
"sampleRateLearned": true,
"sampleRate": 0
},
"iface1": {
"clockSkewMs": "0",
"bitRateOut": 25814004,
"bitRateInLearned": true,
"flowVersion": "NFv1",
"bitRateIn": 26055518,
"bitRateOutLearned": true,
"clockSkewCorrection": false,
"friendlyName": "WIFI 1",
"ring": 0,
"sampleRateLearned": true,
"sampleRate": 0
}
},
[...]
}
}
Individual exporters are addressed with the "exp" prefix, by their IP address (in either IPv4 or IPv6 notation, using URL encoding as needed) and their interfaces by "ifacenumber" with the special interface "0" reserved to make certain exporter-wide changes (primarily, turning on clock skew correction). Any of the parameters can be retrieved with a GET request by direct addressing. Certain of them are also addressable to change by PUT or POST:
| Endpoint | Descriptions | Allowed values |
|---|---|---|
| friendlyName | Name applied to interface in the FlowTraq UI | String 126 characters or less |
| bitRateOut | When PUT/POST, override the estimated maximum bit rate out of this interface | non-zero positive integer |
| bitRateIn | When PUT/POST, override the estimated maximum bit rate into this interface | non-zero positive integer |
| clockSkewCorrection (iface0 only) | Instruct FlowTraq to automatically adjust time stamps for all interfaces on this exporter | true, false |
| sampleRate (iface 0 only) | Override the reported sampling rate reported by this exporter | positive integer |
| ring | The ring ID# to assign this interface (0 - no assignment (default), 1 - uplink/border, 2-3 - edge, 8-9 - core, 15 - ignore, ) | 0-15 |
Version 2 of the FlowTraq API was designed to include a limited subset of functionality for use in individual integrations with third-party tools. It is not intended for general use. If a third-party integration requires the Version 2 API and cannot locate it, please contact FlowTraq Support for assistance. All new applications should use the Version 3 API.
The FlowTraq Web API provides a RESTful interface for for retrieving NetFlow data from a FlowTraq Server in JSON format for use by third-party applications. This API defines two methods of retrieving data:
NetFlow data processed into specific FlowTraq views
Raw NetFlow session records as stored by FlowTraq
An API authentication token is required for all requests. Authentication tokens must be generated for each client through the FlowTraq command line tools. To request the token, send an HTTP request such as:
POST https://example.com/flowtraq/api/v1/auth
| Parameter Name | Value | Default Value | Notes |
|---|---|---|---|
| server | string | "localhost" | The FlowTraq server address. |
| port | number | 9640 | The FlowTraq server port. |
| username | string | required | Username of a user on the Flowtraq server. |
| password | string | required | Password of the Flowtraq server user. |
The response will contain either the resulting auth token or an error message:
| Parameter Name | Value | Notes |
|---|---|---|
| auth_token | string | Only returned if authentication successful. |
| error | string | Only returned if authentication failed. |
Various FlowTraq view combinations may be retrieved via the API by sending requests to:
GET https://example.com/flowtraq/api/v1/stat
| Parameter Name | Value | Default Value | Notes |
|---|---|---|---|
| server | string | "localhost" | The FlowTraq server address. |
| port | number | 9640 | The FlowTraq server port. |
| auth_token | string | required | A recently acquired authentication token from an authentication request. |
| group_by | string | "IP" | A rank entity as described in Retrieving Statistical Queries from the Command Line. |
| count_by | string | "BYTES" | A rank field as described in Retrieving Statistical Queries from the Command Line. Use a space to separate the token "unique". |
| direction | string | none | Possible values: "snd", "rcv". |
| before_time | timestamp | none | A timestamp in the format "MM/DD/YY hh:mm:ss.microsec". |
| after_time | timestamp | none | A timestamp in the format "MM/DD/YY hh:mm:ss.microsec". |
| time_range | string | -15m | A time specifier as described in Time Navigation. |
| query | string | none | A filter string as described in Filter String Syntax. |
| rows | number | 10 | The maximum number or rows to return. |
The response will contain either the resulting data table or an error message:
| Parameter Name | Value | Notes |
|---|---|---|
| columns | [string] | An array of column names. |
| data | [[string]] | An array of rows, one rank entity per row. Values in each row correspond to the column names in the columns field. |
| error | string | Only returned if the request failed. |
For example, using curl in a shell command:
$ curl "https://example.com/flowtraq/api/v1/stat?auth_token=18265a85ca45db35d0a8c263e6dd2c37&group_by=COUNTRY&count_by=BYTES&time_range=-1h"
{"columns":["COUNTRY","SENT BYTES","COLORS","SENT BYTES","RECV BYTES","SENT PCKTS","RECV PCKTS","SESS. INIT","SESS. ACPT","TIME SERIES"],"data":[["192.0.0.7","291953601","9f5afbff","291953601","288067046","597183","592799","1999","2092",["2473710","2478259", ... ]] ... ]}
Raw NetFlow session records may be retrieved from FlowTraq storage API via:
GET https://example.com/flowtraq/api/v1/sessions
Request parameters are the same as when retrieving processed FlowTraq views. See Retrieving Processed FlowTraq Views: Request Parameters.
The response will contain either the resulting data table or an error message:
| Parameter Name | Value | Notes |
|---|---|---|
| columns | [string] | An array of column names. |
| data | [[string]] | An array of rows, one session per row. Values in each row correspond to the column names in the columns field. |
| summary | [string] | A total byte and session count of the query. |
| error | string | Only returned if the request failed. |
For example, using curl in a shell command:
$ curl "https://example.com/flowtraq/api/v1/sessions?auth_token=18265a85ca45db35d0a8c263e6dd2c37&group_by=COUNTRY&count_by=BYTES&time_range=-1h"
{"columns":["CLIENT ADDRESS","CLIENT COUNTRY","CLIENT AS", ... ],"data":[["192.168.68.13","??","0", ... ], ...], "summary":["Total sessions: 802","Total Packets: 1832127","Total Bytes: 1160933394"]}
