FreeBSD Manual Pages
sratool(1) General Commands Manual sratool(1) NAME sratool -- SIE Remote Access (SRA) tool SYNOPSIS [-dhINV] [-c cfile] [-n config] [-E ciphers] [-F fields] [commands] DESCRIPTION sratool connects and sends Advanced Exchange Access (AXA) protocol mes- sages to SIE Remote Access (SRA) servers and displays the responses. It can also tunnel SIE data like sratunnel(1). sratool is a programming example for the Advanced Exchange Access (AXA) applications programming interface to SRA servers, the AXA protocol. It also demonstrates the use of the AXA helper library, libaxa.a. Start using sratool with the connect command described below. Use one or more watch commands to specify interesting patterns of SIE messages or IP packets. Limit the number of packets or messages transmitted from the SRA server or displayed with the rate limit and count com- mands. Turn on one or more channels of messages or packets with the channel command. Unless more output is enabled with the verbose command, most messages or packets are displayed in two lines. The first line includes the channel number on which it was received, the SIE message vendor of the message, the name of the field that caused the message to be selected, and the contents of the field. The second line is a summary of the message or packet. When more verbose output is enabled or when sratool does not understand the message, IP packets are printed in ASCII and SIE messages are printed in the standard nmsg presentation format also seen from nmsgtool(1). OPTIONS The following arguments are available: -c cfile reads commands from cfile as if the first command string on the command line were "source cfile". -d turns on tracing and debugging reports. Additional -d turn on more messages. -E ciphers specifies the TLS encryption ciphers to use with apikey connec- tions. -I enables insecure mode for apikey authentication. When enabled, client connections will not be performed via TLS. -n config overrides the default location of the config file that contains AXA client configuration data. Details are below. The default is ~/.axa/config. -F fields overrides the default location of the fields file that defines re- lationships among and semantics among SIE message fields. The de- fault is $AXACONF/fields, ~/.axa/fields, or /usr/local/etc/axa/fields. -h display options summary. -N instructs sratool to not display a command line prompt. -V displays the version of sratool and its preferred version of the AXA protocol. commands are optional commands strings that are executed before sratool starts accepting commands from the use. There can be more than one string of commands. Multiple commands within a string are separated by semicolons. COMMANDS sratool executes commands read from the standard input. Command his- tory is available if the standard input is a terminal. Multiple com- mands can be specified at once by separating them with semicolons. The following commands are available: accounting Tell the server to report counts of packets seen, missed, sent, and lost. alias List the available connection aliases (culled from the axa client config file). buffer Toggle NMSG output buffering. By default, this is enabled, which buffers network writes until the container is full. If disabled, NMSG payloads are emitted as quickly as possible. ciphers [cipher-list] set the list of ciphers for the next TLS connection or show the current contents of the list. connect [alias | apikey:<apikey>@host,port | tcp:[user@]host,port | unix:[user@]/ud/socket] By itself connect shows the current connection. Otherwise connect to the specified SRA server. alias: use a connection alias specified in the AXA config file (see FILES). apikey: identify and authenticate the user via a Farsight Security provided apikey. tcp: identify the user for clear text communication via the TCP/IP host,port pair. unix: identify the user for communication over a local UNIX domain socket. count [N | off] sets terminal output to stop displaying packets after a number of packets (including immediately with a number of 0), show the cur- rently remaining count, or turn off the packet count limit. debug [on | off | quiet | N] increases, decreases or shows the level of debugging and tracing messages that is also controlled by -d. Debug quiet turns off re- ports of successful AXA commands. disconnect disconnects from the SRA server. error mode [disconnect | off] disconnects from the SRA server and exits when the server reports an error or the connection breaks. In the default mode error mode off, errors are only reported. exit Ends the program. go Tell the SRA server to resume sending data. sratool. help [command] lists all commands or describes a single command. mode [SRA | RAD] Show the current command mode or expect to connect to an SRA or RAD server. The default command mode is set by the name of the program. nop sends a command to the server that does nothing but test the con- nection. forward Start, stop or show the state of forwarding packets received from the server. Received NMSG messages and IP packets can be for- warded as NMSG messages to a TCP or UDP port. Received IP packets can be forwarded as a pcap stream to a file, to a FIFO created with separately with mkfifo(1), or in Ethernet frames on a named network interface to a 48-bit address. nmsg:[tcp:|udp:]host,port [count] sends nmsg messages to the UDP or optional TCP host name and port number host,port. UDP is the default. IP packets are converted to NMSG messages. nmsg:file:path [count] sends binary nmsg messages to the file named path. IP pack- ets are converted to nmsg messages. nmsg:file_json:path [count] sends nmsg newline-delimited json blobs to the file named path. Note that newline-delimited json outputs can incur a slight performance penalty versus binary nmsg outputs for "high-velocity" outputs. This is because the underlying nmsg json output object is unbuffered and results a filesystem write for every forwarded nmsg. pcap[-fifo]:path [count] sends IP packets to a file or FIFO named path for examina- tion with tcpdump(1) or another packet tracing tool. An or- dinary file is the default. Only IP packets but not nmsg messages are sent. pcap-if:[dst/]ifname [count] transmits IP packets on the network interface named ifname for examination with tcpdump(1) or another packet tracing tool. dst optionally specifies a destination 48-bit Ether- net address other than all 0:0:0:0:0:0 default. This output usually requires that sratool be run by root. Only IP pack- ets but not nmsg messages are sent. If count is present, forwarding stops after that many packets. pause Tell the SRA server to stop sending data. rate limit [[-|MAX|per-sec] [-|NEVER|report-secs]] Tell the SRA server to report its per-second packet rate limit or set the rate limit and the minimum interval between rate limit re- ports. Hits in excess of the rate limit are discarded by the server. radd Change to RAD mode. sample [X%] Get and optionally set the percentage of hits that the SRA servers sends. sleep x.y Do nothing for x.y seconds. source filename reads and executes commands from a file. srad Change to SRA mode. status Show information about the current connection state including time connected. trace N Set the server trace level to N. user name sends a username to the server. verbose [on | off | N] controls the length of SIE message and IP packet descriptions. The default, verbose off, generally displays one line summaries. version displays the version of sratool and its version of the AXA proto- col. window [bufsize] Get and optionally set the TCP output buffer size or maximum send window used by the server. zlib Toggle NMSG zlib container compression. channel {list | {on|off} {all|chN}} List available SRA channels or enable or disable one or all SIE channels. [tag] delete [watches [all]] With a tag (numeric label), stop or delete the specified watch. Without a tag (or with the keyword "all"), delete all watches. get channels List all SIE channels available to the user on the SRA server. [tag] get watches With a tag (numeric label), get (list) the specified watch. With- out a tag (or with the keyword "all"), list all watches. tag watch {ip=IP[/n] | dns=[*.]dom | ch=chN | errors} Tell the SRA server to send NMSG messages or IP packets that are to, from, or contain the specified IP addresses, that contain the specified domain name, that arrived at the server on the specified SIE channel, or are SIE messages or IP packets that could not be decoded. Tag is a number labeling the watch. ip=IP[/n] The IPv4 or IPv6 address IP specifies a host address unless a prefix length is specified. dns=[*.]dom watches for the domain anywhere in the IP packets or SIE messages on the enabled channels. A wild card watches for occurrences of the domain and all sub-do- mains. ch=all ch=chN selects SIE messages or IP packets on the specified channel number or all channels. errors selects SIE messages or IP packets that could not be decoded. Errors can also include nmsg process- ing/field decoding errors, malformed or excessively long DNS names, errors encountered at the datalink level, and unexpected address family types. [tag] list watches Synonym for the get watches command. [tag] stop [watch [all]] Synonym for the delete command. EXAMPLES The following captures and displays one SIE newdomain message. The "dns=*." watch or pattern was matched by the "nflxso.net" domain in DNS NS rdata. $ sratool sra> connect apikey:<yourapikey>@axa-sie.domaintools.com,49500 * HELLO srad v3.0.1 prod-sie-axa-1 supporting AXA protocols v1 to v2; currently using v1 * Using AXA protocol 2 * OK USER mschiffm authorized sra> count 1 sra> channel 213 on * OK CHANNEL ON/OFF channel ch213 on sra> 1 watch dns=*. 1 OK WATCH started 1 ch213 SIE newdomain ad6uq65jvhekifbbgu36u.r.nflxso.net/CNAME: nflxso.net packet count limit exceeded sra> exit FILES ~/.axa/config contains AXA client configuration data. Currently supported are connection aliases that provide the user with a facility to create shortcut mnemonics to specify the SRA server connection string. For example: $ cat ~/.axa/config # SRA alias:sra-apikey=apikey:<elided>@axa-sie.domaintools.com,49500 If the user wanted to connect to SRA, she would only have to remember "sra-apikey" and could do: $ sratool sra> connect sra-apikey This config file is shared for sratool, radtool, sratunnel, and radtunnel. Because this file can contain sensitive information such as apikeys, it must not be readable or writeable to any- body other than "owner" or sratool will not load. ~/.sratool_history contains the command history from previous sratool and/or radtool invocations ENVIRONMENT VARIABLES If set, AXACONF specifies the AXA configuration directory instead of the default, ~/.axa or /usr/local/etc/axa. SEE ALSO sratool(1), sratunnel(1), radtunnel(1), mkfifo(1), and nmsgtool(1). April 12, 2025 sratool(1)
NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | FILES | ENVIRONMENT VARIABLES | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=sratool&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>