RARC(5)

💖 rarc(5) — the ra client resource file 💖

ok so bestie. this is the manual page for rarc(5), aka the lil config file that all your ra* friends read before they do literally anything. it's giving "settings file that runs the whole vibe". let's get into it 🫶

---

✨ NAME ✨

rarc — ra client resource file. that's it. that's the whole name. she's simple, she's powerful, she's the blueprint 💅

---

✨ SYNOPSIS ✨

rarc

yeah. that's the whole synopsis. no arguments, no flags, she just exists in your home directory and the ra* clients come find her. main character energy tbh 👑

---

✨ DESCRIPTION ✨

okay so here's the tea 🍓 — all the ra* clients will open this file if it's sitting in your $HOME directory, or in the $ARGUSHOME directory, and they'll parse it to set up their common configuration options. it's like a group chat they all read before they start talking.

heads up bestie: every single one of these values gets overridden by options you set on the command line, or by a file you specify with the -F conffile option. so command line always wins, no cap. the rarc file is just the default vibe setter.

values can be quoted to make string denotation easier, but — plot twist — the parser does not require string values to be quoted. to make that work, the parser will remove " (double quote) characters from input strings, so do not use that character inside strings themselves. it will simply get eaten. gone. deleted. 💀

and if you specify a value as "" — that's treated as a NULL string, and the parser will just ignore the variable setting entirely. so no, you can't "set it to empty", it just doesn't count.

---

✨ RA_ARGUS_SERVER ✨

all ra* clients can attach to a remote server and collect argus data in real time ⏰ this variable can be a name, or a dot notation IP address. optionally you can specify a port number by adding a : and then the port number you want.

RA_ARGUS_SERVER=localhost:561

that's it, that's the whole thing. remote server, go 🌈

---

✨ PID FILE SUPPORT ✨

any ra* program can generate a pid file, and that pid file can be used to control the number of instances that the system can support. very "only one of me allowed" of her.

creating a system pid file may require privileges that may not be appropriate for all cases. but bestie — by specifying RA_PID_PATH, you can create personal pid files that enforce your own policy for your own use of the ra* programs. your rules, your kingdom, your crown 👑

so here's how it works when a ra* program is configured to generate a pid file: if a file called ra*.pid (where ra* is the name of the program in question) exists in the RA_PID_PATH directory, and a program exists with a pid that matches the one contained in that file — then the program will not start. blocked. denied. not today.

if that pid does not exist, then the ra* program replaces the value in the file with its own pid. and if a pid file doesn't exist at all? then the ra* program will create it in the RA_PID_PATH directory, if it can. the end result is that the system will support only one instance of the program, based on name, running at a time. periodt.

the default value is to not generate a pid. and the default path for the pid file is /var/run.

No Commandline equivalent

RA_SET_PID="no"
RA_PID_PATH="/var/run"

---

✨ RA_OUTPUT_FILE ✨

all ra* clients can support writing output as Argus Records into a file or stdout. stdout is specified as '-' ✨

RA_OUTPUT_FILE="filename"

---

✨ RA_TIMERANGE ✨

all ra* clients can support input filtering on a time range 🕰️ the format is:

timeSpecification[-timeSpecification]

and the format of a timeSpecification can be:

[[[yy/]mm/]dd.]hh[:mm[:ss]]
[yy/]mm/dd

examples, because examples slay:

RA_TIMERANGE="55/12/04.00:00:01-55/12/04.23:59:59"
RA_TIMERANGE="12/04-12/05"

---

✨ RA_RUN_TIME ✨

all ra* clients can support running for a number of seconds while attached to a remote source of argus data. this is a type of polling 🔄 the default is zero (0), which means run indefinately.

RA_RUN_TIME=0

---

✨ RA_PRINT_MAN_RECORDS ✨

specify if ra* clients should print management records by default. this does not affect management record processing, nor down stream management record propagation — so don't panic, it's just about the printing 💅

commandline equivalents: -M [no]man

RA_PRINT_MAN_RECORDS=no RA_PRINT_EVENT_RECORDS=no

---

✨ RA_PRINT_LABELS ✨

most ra* clients are designed to print argus records out in ASCII, with each client supporting its own output formats. for ra() like clients, this variable will generate column headers as labels 🏷️

the number is the number of lines between repeated header labeling. setting this value to zero (0) will cause the labels to be printed once. if you don't want labels, comment this line out, delete it, or set the value to -1.

RA_PRINT_LABELS=0

---

✨ RA_FIELD_DELIMITER ✨

most ra* clients are designed to print argus records out in ASCII, with each client supporting its own output formats. for ra() like clients, this variable can overide the default field delimiter — which are variable spans of space (' ') — to be any character. the most common are expected to be '' for tabs, and ',' for comma separated fields.

RA_FIELD_DELIMITER=','

---

✨ RA_PRINT_NAMES ✨

for ra(1) like clients, this variable controls the translation of various numbers to names — like address hostnames, port service names, and/or protocol names 🌸

warning bestie: there can be a huge performance impact with name lookup, so the default is to not resolve hostnames.

RA_PRINT_NAMES=port

other valid options are:

• none — print no names
• proto — translate the protocol names
• port — translate port names
• all — translate all the fields

and an invalid option will default to port, silently. no error, no drama, just port. 🙈

---

✨ RA_CIDR_ADDRESS_FORMAT ✨

use this variable to specify whether ra() clients, when printing numeric IP addresses, will print them as CIDR addresses or not.

CIDR notation is constructed from the IP address and the prefix size — the latter being the number of leading 1 bits of the routing prefix. the IP address is expressed according to the standards of IPv4 or IPv6. it's followed by a separator character, the forward slash (/) character, and the prefix size expressed as a decimal number. 📐

Argus IPv4 data contains the CIDR mask length when it's less than 32, and ra* programs will by default provide the /masklen suffix when the mask is less than 32.

this may be confusing for some data processors, which would rather not see the /masklen never, or all the time. use this option to specify changes in the default printing stratgy 🎀

acceptable values for this variable are:

• "no" — do not provide the CIDR mask length (legacy mode) [default]
• "yes" — print CIDR mask length when less than 32
• "strict" — always print CIDR mask length

RA_CIDR_ADDRESS_FORMAT="no"

---

✨ RA_ASN_PRINT_FORMAT ✨

all ra() clients can print and process AS Numbers that have been added to the records through metadata labeling, or were a part of the original Netflow to argus conversion process.

RFC 5396 specifies 3 formats for representing AS Numbers, and all 3 are acceptable formats. these formats are:

• "asplain" — 2 and 4-byte ASNs are printed as decimal integers.
• "asdot+" — 2 and 4-byte ASNs are printed using a dot notation.
• "asdot" — 2 byte ASNs are printed as decimal, and 4-byte ASNs are printed using a dotted notation.

the default is 'asplain'.

No Commandline equivalent

RA_ASN_PRINT_FORMAT="asplain"

---

✨ RA_PRINT_RESPONSE_DATA ✨

for ra() like clients, this variable will include the response data that is provided by Argus. this is protocol and state specific 🦋

RA_PRINT_RESPONSE_DATA=no

---

✨ RA_PRINT_UNIX_TIME ✨

for ra() like clients, this variable will force the timestamp to be in Unix time format — which is an integer representing the number of elapsed seconds since the epoch ⏳

RA_PRINT_UNIX_TIME=no

---

✨ RA_TIME_FORMAT ✨

for ra() like clients, the format used to print timestamps is based on the strftime() library call, with an extension to print fractions of a second using %f. the default is "%T.%f".

you can overide this default time format by setting this variable. this string must conform to the format specified in strftime().

real talk: malformed strings can generate interesting output, so be aware with this one — and don't forget the . when doing fractions of a second. 💅

RA_TIME_FORMAT="%T.%f"

---

✨ RA_TZ ✨

the timezone used for timestamps is specified by the tzset() library routines, and is normally specified by factors such as the TZ environment variable found on most machines 🌍

you can override the TZ environment variable by specifying a time zone using this variable. the format of this string must conform to the format specified by tzset(3).

RA_TZ="EST5EDT4,M3.2.0/02,M11.1.0/02"
RA_TZ="PST8PDT"

---

✨ RA_USEC_PRECISION ✨

for ra() like clients, this variable is used to override the time format of the timestamp. it specifies the number of decimal places that will be printed as the fractional part of the time 🔬

Argus collects usec precision, and so a maximum value of 6 is supported. to not print the fractional part, specify the value zero (0).

RA_USEC_PRECISION=6

---

✨ RA_USERDATA_ENCODE ✨

Argus can capture user data, and the argus clients can print, merge, filter, and strip user data from argus records. when printing out the user data contents using tools such as ra.1, the type of encoding used to print the buffers can be specified here 🎨

this is available because many user data buffers are not printable text, and other representations may be more appropriate. thoughtful of her, honestly.

supported values are "Ascii", "Obfuscate", "Hex", "Encode32" or "Encode64". the default is "Ascii".

Obfuscate is an extension to the Ascii print, that attempts to over-write plain text passwords encountered in the user data with 'x's. privacy icon behavior 🫶

commandline equivalent: -M printer=<printer>

RA_USERDATA_ENCODE=Ascii

---

✨ RA_FILTER ✨

you can provide a filter expression here, if you like 💜 it should be limited to 2K in length. the default is to not filter. see ra(1) for the format of the filter expression.

RA_FILTER=""

---

✨ SASL SUPPPORT ✨

(yes bestie, that's genuinely how the section is spelled, we keep it 💀)

when argus is compiled with SASL support, ra* clients may be required to authenticate to the argus server before argus will accept the connection 🔐 this variable will allow one to set the user and authorization id's, if needed.

listen up: although not the best practice, you can provide a password through the RA_AUTH_PASS variable. if you do this, you should protect the contents of this file. seriously. bestie. protect it.

the format for this variable is:

RA_USER_AUTH="user_id/authorization_id"
RA_AUTH_PASS="password"

the clients can also specify a part of the negotiation of the security policy that argus uses. this is controlled through the use of a minimum and maximum allowable protection strength values. set these variables to control this policy:

RA_MIN_SSF=0
RA_MAX_SSF=128

---

✨ RA_DEBUG_LEVEL ✨

if compiled to support this option, ra* clients are capable of generating a lot of [full | less | whatever] debug information 🔊 the default value is zero (0).

RA_DEBUG_LEVEL=0

---

✨ RA_CONNECT_TIME ✨

some ra style clients use a non-blocking method to connect to remote data sources, so you might need to control how long to wait if a remote source doesn't respond 😭

this variable sets the number of seconds to wait. this number should be set to a reasonable value (5 < value < 60). the default value is 10 seconds.

RA_CONNECT_TIME=10

---

✨ RA_SORT_ALGORITHMS ✨

many ra* programs sort records as a part of their function 📊 programs like rasort.1 provide explicit command-line options to specify the sort algorithms and their order, using the -m field [field ...] option.

use this configuration directive to specify the default sorting algorithm table for your ra* programs. the default sort algorithm is record start time "stime".

RA_SORT_ALGORITHMS="stime "

---

ok so that's all of part one bestie, and there's more coming — don't go anywhere 💖

🌸 RA_HASHTABLE_SIZE

So, the ra* clients that match flow attributes — think aggregators and their friends — keep their data in hash tables while they're processing. This variable lets you resize those hash tables, which is how you either keep memory in check or speed things up. ✨ The default is 262144 (0x40000).

RA_HASHTABLE_SIZE=262144

---

💖 RA_TIMEOUT_INTERVAL

Some ra* clients have a timeout-based function, and ratop is the classic example: it times out flows and drops them off the screen at a fixed interval. You set that interval with the RA_TIMEOUT_INTERVAL variable, which is a float in seconds. The default is 60.0 seconds.

RA_TIMEOUT_INTERVAL=60.0

---

🎀 RA_UPDATE_INTERVAL

Some ra* clients have an interval-based function. ratop, for example, can refresh the screen at a fixed interval. Set it with the RA_UPDATE_INTERVAL variable, another float in seconds. The default is 0.5 seconds.

RA_UPDATE_INTERVAL=0.5

---

🦋 RA_SRC_ALIAS

Every single ra* client can alias the srcid to the "node" field, bestie, and the method for finding that alias is specified with this variable, RA_SRCID_ALIAS. The URL format covers both file and database access — file access is the one that's actually implemented. 👑

file:/usr/local/argus/argus.srcid.alias.txt
mysql://[username[:password]@]hostname[:port]/database/tablename

RA_SRCID_ALIAS="file:/usr/local/argus/argus.srcid.alias.txt"

---

🌸 RA_PRINT_ETHERNET_VENDORS

All ra* clients can print vendor names for the vendor part of ethernet addresses sitting in flow records. The ra* programs grab their ethernet vendor strings from Wireshark 'manuf' files. One ships with the distribution and gets installed into /usr/local/argus. 🫶

No Commandline equivalent

RA_PRINT_ETHERNET_VENDORS="no"
RA_ETHERNET_VENDORS="/usr/local/argus/wireshark.manuf.txt"

---

✨ RA_DELEGATED_IP

All ra* clients can print country codes for the IP addresses in a flow record, and those country codes are generated from the ARIN delegated address space files. Point at your DELEGATED_IP file right here. 🌍

No Commandline equivalent

RA_DELEGATED_IP="/usr/local/argus/delegated-ipv4-latest"

---

💅 RA_RELIABLE_CONNECT

All ra* clients can reliably connect to remote data sources. This makes the ra* program try to reconnect to lost remote sources every 5 seconds, indefinitely — so instead of terminating when a connection fails, it just keeps retrying. 😤

Heads up: this feature is implemented using threads, so threads support has to be compiled in.

No Commandline equivalent

RA_RELIABLE_CONNECT=no

---

🔥 MYSQL SUPPORT

Lots of ra* clients can connect to and use a MySQL database, whether reading or writing. That may mean referencing remote database hosts, databases, tables, and mysql account names and passwords. 🔐

You can set the default values for these variables right here — but support has to be compiled in.

Commandline equivalents:

-r mysql://[username[:password]@]hostname[:port]/database/tablename
-w mysql://[username[:password]@]hostname[:port]/database/tablename
-u username:password

RA_DATABASE="argus"
RA_DB_TABLE="table"
RA_DB_USER="carter"
RA_DB_PASS="whatever"

Those ra* clients that can create database tables may need you to specify a table type — or rather, a database engine other than the default, InnoDB.

Commandline equivalents:

-M mysql_engine=tableType

Current tableTypes are

• InnoDB
• MyISAM
• Merge
• Memory
• Archive
• NDB
• Federated
• CSV

MYSQL_DB_ENGINE="InnoDB"

---

🌈 COLOR SUPPORT

For the ra* programs that use curses, these variables define color schemes and color assignments. 🎨

Argus uses a sixteen color palette — 8 monotone and 8 accent colors — plus 16 colors of gray. Currently these color values are hard coded. New versions should let you provide color definitions for all internal values using a 256 Xterm color wheel, to assign foreground and background colors. But we're not there yet. 😭

RA_COLOR_SUPPORT="yes"
RA_COLOR_CONFIG="/usr/carter/.racolor.conf"

---

🧭 DIRECTION SUPPORT

Many ra* clients process flow records based on source and destination properties. TCP and UDP port values can be used to assign direction, and they're best used for well-known ports (< 1024), values that are in the /etc/services defintions, and the reserved ports (> 1023, < 49151).

The syntax is:

RA_PORT_DIRECTION="services"
RA_PORT_DIRECTION="services,wellknown"
RA_PORT_DIRECTION="services,wellknown,registered"

We recommend the wellknown and services options, since they're a bit more discriminating. If there are ports you know are services sitting in the registered port range, we suggest adding them to your /etc/services file rather than including the registered port range — only because the registered range is so large. However, this option is applied only to flow in which the direction is ambiguous, and as such, corrections based on the logic should have minimum effect on analytics.

RA_PORT_DIRECTION="services,wellknown"

Sites use locality for a number of features, such as access control, and this support is intended to support visualization, and analytics. 📍

Currently, you can identify a collection of IP addresses that represent RA_LOCAL, specified using an iana-address-file formatted file. (See ralabel.conf)

RA_LOCAL="/usr/local/argus/local.addrs"

When locality information is available, programs like ra(), and as the assignement of source when there is ambiguity in the flow record as to who is the actual initiator or receiver of the flow. When locality information is available, programs like ra(), and ratop() can use that information to make display decisions, such

RA_LOCAL_DIRECTION provides the logic for using the locality information to assign flow direction. You can force the local address to be either the source (src) or the destination (dst). 💫

The syntax is:

RA_LOCAL_DIRECTION="local:src"
RA_LOCAL_DIRECTION="local:dst"

RA_LOCAL_DIRECTION="suggest:src"
RA_LOCAL_DIRECTION="force:src

---

👑 COPYRIGHT

Copyright (c) 2000-2024 QoSient. All rights reserved.

---

🫶 SEE ALSO

ra(1)

---

okay bestie that's literally the whole page, no cap 💖 this was rarc version 5.0.3, dated 14 September 2016 — go forth and configure your ra* clients, you absolute icon 🌟