3.2. Command Line Interface

3.2.1. Overview

ftsq: FlowTraq Session Query Retrieval Tool. The ftsq command allows you to retrieve bi-directional session data assembled from the unidirectional flow data. This command accepts as parameters a report type, a timeframe, and an optional filter string to narrow the scope of the report. It presents its results as CSV or an ASCII table.
ftstat: FlowTraq Statistical Query Retrieval Tool. Use ftstat to retrieve the kinds of statistical reports you can retrieve in a FlowTraq Workspace, such as "Hosts Ranked by Bytes Sent" or "Applications ranked by Sessions Received". Like the ftsq command, ftstat accepts a timeframe and filter string. It presents tabular results as either CSV or an ASCII table.
ftname: FlowTraq Friendly Names. The ftname command allows users to set userfriendly names for objects such as IP addresses, exporters, interfaces, traffic groups, and autonomous systems.
ftum: FlowTraq User Management. The ftum command allows administrative users to create and delete users, reset passwords, and grant administrative privileges. The use of this tool is covered in the Administration Section of this manual.
fttg: FlowTraq Traffic Groups. The fttg command allows administrative users to create traffic groups for tagging flows upon ingress. The use of this tool is covered in the Administration Section of this manual.

3.2.2. Retrieving Raw Session Data from the Command Line with `ftsq`

To retrieve raw session records, use the ftsq command.

For example, the following invocation of ftsq returns all records in the last hour to HTTP servers with a client address that is outside the 123.45.67.89 class-C block, in CSV format with a header line:

Figure 3.2. ftsq Example

The ftsq commands accepts a wide range of parameters. Some are optional and some are required.

You should always specify a FlowTraq Server to log in to (or accept the default, localhost), supply a username and password, and select a timeframe over which to perform your query (or accept the default, which is the last 15 minutes).

Optionally, you may supply a filter string to further narrow your query, and you may specify a preference for how you would like the command's output formatted.

Most of the parameters are self-explanatory, but timeframe specification and the filter string syntax are described in depth in Section 3.2.3, “Time Navigation” and Section 3.2.4, “Filter String Syntax”. First, however, please review the complete list of parameters:

Table 3.1. Connection Parameters

Parameter	Description
`-s SERVER`	Address (or hostname) of FlowTraq server to query. (Default: `localhost`.)
`-p PORT`	Port on which to connect to FlowTraq server. (Default: 9640.)

Table 3.2. Login Parameters

Parameter	Description
`-un USER`	Username for profile login. Required.
`-up PASS`	Password for profile login. (Note: If you do not use `-up` , you will be prompted to enter a password.)
`-us [SESSIONKEY]`	Authenticate with a session key rather than with a username and password, or generate a session key. (For more information, see Section 3.2.7, “Session Key Reauthentication”).

Table 3.3. Timeframe Parameters

Parameter	Description
`-te "MM/DD/YY hh:mm:ss.microsec"`	Specify an absolute timeframe starting time. Must be used in conjunction with `-tl` . Cannot be used in conjunction with `-tn` .
`-tl "MM/DD/YY hh:mm:ss.microsec"`	Specify an absolute timeframe ending time. Must be used in conjunction with `-te` . Cannot be used in conjunction with `-tn` .
`-tn RELTIME`	Specify a timeframe relative to now (e.g. `-tn -1h30m` for the last 1.5 hours). Default: last 15 minutes. Cannot be used in conjunction with `-te` or `-ts`. Please see Section 3.2.3, “Time Navigation” for more information on valid specifiers for `RELTIME`.

Table 3.4. Filtering Parameters

Parameter	Description
`-e IP`	Filter for flows from exporter with a given IP address. Default: all exporters. Must be specified before `-ei` and `-ef` .
`-ei INDEX`	Filter for flows with a given interface index of exporter. Default: all interfaces.
`-ef [nf1\|nf5\|nf9\|sf2\|sf4\|sf5]`	Filter for flows from a given exporter version. Default: any version.
`-snd`	The `-snd` parameter indicates that FlowTraq should only count outbound packets, bytes, or sessions when generating rankings. May not be used in conjunction with the `-rcv` parameter.
`-rcv`	The `-rcv` parameter indicates that FlowTraq should only count inbound packets, bytes, or sessions when generating rankings. May not be used in conjunction with the `-snd` parameter.
`-q "RAWQUERY"`	Specify a query string (enclose in ""-pair). See Section 3.2.4, “Filter String Syntax” for a description of the query string syntax.

	Important
	Note that the `-snd` and `-rcv` parameters are not applicable to the `ftsq` command, since rankings are not generated when returning raw session records. Use these parameters in conjunction with `ftstat`, as described below.

Table 3.5. Output Parameters

Parameter	Description
`-w NUM`	Create a time series with `NUM` slices. Default: don't create a time series.
`-r num`	Number of rows per table. Default: 128.
`-c`	Use CSV output format.
`-c+`	Use CSV output format with headers and summaries.
`-v`	Display a progress indicator. Useful for longer summary queries.
`-g filename.tga`	If specified, in addition to writing the tabular result to the terminal, the command will write a stack chart to `filename.tga` . Default: don't write a stack graph.
`-gx X`	The width, in pixels, of the image produced. May only be used in conjunction with `-g` and `-gy`.
`-gy Y`	The height, in pixels, of the image produced. May only be used in conjunction with `-g` and `-gx`.

	Important
	Note that the `-w` parameter is not applicable to the `ftsq` command, since there is no accompanying time series for raw session records. Use this parameter in conjunction with `ftstat`, as described below.

	Important
	Note that the `-g`, `-gx`, and `-gy` parameters are not applicable to the `ftsq` command, since there is no accompanying stack graph for raw session records. Use these parameters in conjunction with `ftstat`, as described below.

3.2.3. Time Navigation

Both ftstat and ftsq require a timeframe specification.

You can set an absolute timeframe by specifying start and end times with -te and -tl. Specify both a starting and ending time in the following format: "MM/DD/YY hh:mm:ss.microsec".

Alternatively, you can specify a timeframe relative to now by using the -tn option, For example, -tn -1h specifies the last hour, -tn -1d12h specifies the day and a half, and -tn -5m specifies the last five minutes.

Valid time specifiers for the -tn option are as follows:

s: Seconds
m: Minutes
h: Hours
d: Days
w: Weeks
M: Months
y: Years

	Important
	Time specifiers must be given in order of magnitude. This means that `-tn -2d1w` is an invalid way to specify "the last 9 days". Instead, use `-tn -1w2d` , which is valid.

3.2.4. Filter String Syntax

All data retrieval commands accept an optional filter string. The filter string is used to select which sessions to include in the retrieval.

Filter strings consist of statements, such as SRVIP==123.45.67.89 ("server IP address is 123.45.67.89") and CLNPKTS>=100 ("number of client-transmitted packets is at least 100"), which may be combined using logical operators.

You can combine statements using the following logical operators:

&&: logical 'AND'
||: logical 'OR'
^|: logical 'XOR' (exclusive-OR)
!: logical 'NOT'

For example: SRVIP==123.45.67.89 && CLNIP==89.67.45.123 .

Tip

You can build compound statements and specify precedence by using parentheses. For example, you might use:

(SRVPORT==22 && SRVIP==123.45.67.89) || (SRVIP==89.67.45.123)

to specify all sessions which are either connections on port 22 to 123.45.67.89, or connections on ANY port to 89.67.45.123.

Statements are formed by combining field names (such as SRVIP) with comparators (such as ==) and values to compare them to. The following lists the available comparators and field names.

Comparators

==: equals
!=: does not equal
>=: greater than or equal to
<=: less than or equal to
>: greater than
<: less than

Table 3.6. Filter String Fields

Field	Description	Valid Comparators
`SRVIP`	server IP (or CIDR), IPv4: `123.45.67.89/32`, or IPv6: `fed9::c0:ffee/128`	`==, !=`
`CLNIP`	client IP (or CIDR), same as SRVIP	`==, !=`
`ADDR`	IP or CIDR block	`==, !=`
`SRVPORT`	server port, integer number	`==, !=, >=, <=, >, <`
`CLNPORT`	client port, integer number	`==, !=, >=, <=, >, <`
`PORT`	port, integer number	`==, !=, >=, <=, >, <`
`PROTO`	protocol, one of TCP/UDP/ICMP, or integer number	`==, !=, >=, <=, >, <`
`CLNPKTS`	number of client transmitted packets, integer number	`==, !=, >=, <=, >, <`
`SRVPKTS`	number of server transmitted packets, integer number	`==, !=, >=, <=, >, <`
`PACKETS`	match either of the packet fields (server or client), integer number	`==, !=, >=, <=, >, <`
`TOTPKTS`	total packets (server plus client), integer number	`==, !=, >=, <=, >, <`
`CLNBYTS`	number of client transmitted bytes, integer number	`==, !=, >=, <=, >, <`
`SRVBYTS`	number of server transmitted bytes, integer number	`==, !=, >=, <=, >, <`
`BYTES`	match either of the bytes fields (server or client), integer number	`==, !=, >=, <=, >, <`
`TOTBYTS`	total bytes (server plus client), integer number	`==, !=, >=, <=, >, <`
`TTIME`	total time of session, floating point, in seconds: 2.5	`==, !=, >=, <=, >, <`
`TOS`	ToS, QoS, DiffServ, integer number 0-256	`==, !=, >=, <=, >, <`
`CLNCC`	client country code, two characters: 'US', 'NL'	`==, !=`
`SRVCC`	server country code, same as client country code	`==, !=`
`INIF`	inbound interface, integer number 0-65536	`==, !=, >=, <=, >, <`
`OUTIF`	outbound interface, integer number 0-65536	`==, !=, >=, <=, >, <`
`IFACE`	match either of the interface fields (inbound or outbound), integer number 0-65536	`==, !=, >=, <=, >, <`
`INVLAN`	inbound VLAN, integer number 0-4096	`==, !=, >=, <=, >, <`
`OUTVLAN`	outbound VLAN, integer number 0-4096	`==, !=, >=, <=, >, <`
`VLAN`	match either of the VLAN fields (inbound or outbound), integer number 0-4096	`==, !=, >=, <=, >, <`
`CLNAS`	client autonomous system number, integer number	`==, !=, >=, <=, >, <`
`SRVAS`	server autonomous system number, integer number	`==, !=, >=, <=, >, <`
`ASN`	match either of the autonomous system number fields (server or client), integer number	`==, !=, >=, <=, >, <`
`ASAEVT`	ASA event code, integer number	`==, !=, >=, <=, >, <`
`ASAEXTEVT`	ASA extended event code, integer number	`==, !=, >=, <=, >, <`
`FLAGS`	TCP flags in session, one of: 'FSYN' (syn), 'FACK' (ack), 'FRST' (reset), 'FFIN' (fin), 'FPSH' (push), 'FECN' (ECN-echo), 'FCWR' (congestion window reduced), 'FURG' (urgent)	`==, !=`
`EXPIP`	IP of the device that exported the record	`==, !=`
`EXPV`	flow version, use: 1, 5, 7, 9 (NetFlow v1/5/7/9), 18, 20, 21 (sFlow v2/4/5)	`==, !=`

3.2.5. Retrieving Statistical Queries from the Command Line with `ftstat`

The FlowTraq Statistical Query Retrieval command ftstat creates tables and graphs of grouped items that are ranked by some criterion. For example, you can retrieve the list of hosts that sent the most packets during a given timeframe or the list of hosts that received the most packets during the same. You can also find out which port/application accounted for the most bytes on your network, find which host pair exchanged the most bytes, and more.

It is also possible to score by more complex criteria. For instance, it is possible to find the list of hosts that contacted the largest number of unique hosts, or the list of countries that contacted your servers on the largest number of unique server ports.

As with the ftsq command, you must specify a FlowTraq Server to connect to, supply login details, select a timeframe and (optionally) specify a filter. And like ftsq, the results are returned in a formatted table, by default, or in CSV format (use either the -c option for CSV without a header, or the -c+ option for CSV with a header line). Please refer to the complete list of parameters in Section 3.2.2, “Retrieving Raw Session Data from the Command Line with ftsq”, Section 3.2.4, “Filter String Syntax” for more information on the filter language syntax, and Section 3.2.3, “Time Navigation” for information on timeframe specifications.

Where the usage of ftstat differs from that of ftsq is in specifying the desired statistic to calculate. Specify the statistic by using the -grp and -cnt paramaters:

Table 3.7. Statistical Query Parameters

Parameter Description

-grp ENTITY_TYPE Create a ranking of the given entity type, one of: IP, IPPAIR, PORTPROTO, QOS, TCPFLAGS, IF, IFPAIR, COUNTRY, VLAN, VLANPAIR, ASN, ASNPAIR, MAC, or MACPAIR.

Parameter	Description
`-grp ENTITY_TYPE`	Create a ranking of the given entity type, one of: `IP, IPPAIR, PORTPROTO, QOS, TCPFLAGS, IF, IFPAIR, COUNTRY, VLAN, VLANPAIR, ASN, ASNPAIR, MAC, or MACPAIR`.
`-cnt COUNT`	Rank entities on the specified field, one of: `BYTES, BITS, SESSIONS, PACKETS, or UNIQUE`. `UNIQUE` requires an additional argument, one of: `IP, PORTPROTO, QOS, TCPFLAGS, IF, COUNTRY, VLAN, ASN, or MAC`

-cnt COUNT

Rank entities on the specified field, one of: BYTES, BITS, SESSIONS, PACKETS, or UNIQUE.

UNIQUE requires an additional argument, one of: IP, PORTPROTO, QOS, TCPFLAGS, IF, COUNTRY, VLAN, ASN, or MAC

	`ftstat` Example 1
	To retrieve the top 25 hosts by bytes sent in the last week, use the following command:

	`ftstat` Example 2
	To retrieve the five host-pairs that communicated over the largest number of ports during last five hours, use the following command:

	Tip
	You may use the `-g` parameter to request the accompanying stack graph, and the `-gx` and `-gy` parameters to specify the size of the graph you would like.

	Tip
	You may use the `-w` parameter to request a timeseries for each row of the table.

3.2.6. Assigning Friendlynames from the Command Line with `ftname`

FlowTraq allows users to assign userfriendly names to a range of objects. These names can be used to quickly identify objects such as IP addresses, exporters, interfaces, etc. Some objects have built-in name resultion, such as Autonomous Systems (ASN). Names for ASN objects can be overridden by the user.

Names assigned by regular users are only visible to those users when an ftstat query is performed. Administrators have the option of specifying a -global parameter to the ftname command, which names the object for all users. The ftname command may also be used to query and list names that a user can see.

Table 3.8. Friendlyname Parameters

Parameter	Description
`-object GT OBJ`	Set or retrieve the name for an object of type `GT`. The object itself (for instance an IP address) is given as a second argument. Valid object types: `IP, PORTPROTO, VLAN, ASN, TG, EXPIPVERS, EXPIF, QOS, CID`. Do not mix with an `-nlist` parameter.
`-name NAME`	Assign the given name of the specificed object. Requires the `-object` parameter to be present.
`-global`	Administrative users may set names that can be seen by all users by using this parameter.
`-nlist`	List all known names. Optionally, this command takes an 'type' argument to restrict the listing to a particular object type only. Do not mix with an `-object` parameter.

Figure 3.3. ftname Example

3.2.7. Session Key Reauthentication

The session key reauthentication mechanism allows for FlowTraq's command line tools to be easily integrated with third-party applications and applications hosted on other systems. The use of session keys allows automated scripts and script-based interfaces such as web GUIs to call additional command line tools without the need to store the username and password in a client-side cookie. Since the session key automatically expires, and is only valid from the originating IP address, it is unnecessary to perform an explicit "log out."

	Default Timeout 30 Minutes
	The FlowTraq server daemon times session keys out automatically after they have not been used for 30 minutes. Additionally, session keys will only be accepted from the IP address that generated the session key. To change this default behavior, please refer to the Administration Section of this manual.

To create and use a session key, a command line tool must first provide a valid user's credentials to log into a session, and provide the -us parameter to request that a session key be created. Any command will work, but ftum is convenient because it doesn't need to interact with session data, so we use it in our example:

			ftum -un USERNAME -up PASSWORD -us

If the credentials provided are valid, the stderr output of the command will be a session key; for example:

			91389bd1127bce0a2615d390be08f696

The session key may subsequently used with the -us argument instead of a username/password combination to re-login to the same FlowTraq Server from the same IP address. Continuing our example:

			ftstat -us 91389bd1127bce0a2615d390be08f696 [...]

	Tip
	Each time the session key is used, the timer is reset. The session key will eventually expire on the server side after the period of time specified in the `userdata/maxsessionkeyage` configuration parameter.

Prev	Up	Next
	Home

	Tip
	The CLI tools, like the client, connect to FlowTraq Server via 9640/tcp. You don't have to run the CLI tools from the host on which you installed FlowTraq Server.