orcus.conf - Orcus configuration file

Description

The orcus.conf file contains variable settings which control the behavior of the orloader(8), orlookup(1), and orquery(1) tools. It’s typically found in /etc/orcus.conf or ${PREFIX}/etc/orcus.conf, but an alternative location may be specified on the command-line of each tool.

Each line of the file is in the following format:

<variable-name>: <variable-value>

Blank lines and lines beginning with ‘#’ are ignored.

If an unrecognized variable name is encountered during the processing of the file, or if the value is not syntactically correct, an error is reported and processing stops.

If variables are provided more than once, later entries will override any previous entries.

Variables

The following configuration variables are allowed. Note that several (error-directory, incoming-directory, and loading-directory) must be set for the configuration to be valid.

archive-directory

Used by orloader. This variable is optional. If this variable is set, then each input file will be moved to DIR_PATH once loading successfully completes. If this switch is not provided, input files are deleted once they have been successfully loaded.

database-uri

Used by all tools. This variable is optional. Use URI as the database to connect to. If this option is present, it overrides database-uri-file, including the default value.

Note that this URI will frequently contain password information, which may be visible as a program argument by examining the process list. You should prefer the –database-uri-file option to read the connection URI from a file if the URI contains password information.

database-uri-file

Used by all tools. This variable is optional. Read the database connection URI from FILE_PATH.

If neither this variable nor database-uri is set, then orloader looks in the following locations (in the listed order):

${PREFIX}/etc/orcus-db-load.uri
/etc/orcus-db-load.uri
${PREFIX}/etc/orcus-db.uri
/etc/orcus-db.uri

orlookup and orquery skip looking in the orcus-db-load.uri files, and only consult the orcus-db.uri files.

If none of those files exists, and neither database-uri nor database-uri-file is specified, all of the tools will exit with an error.

debug-errors

Used by orloader. Defaults to no. If yes, then when saving input files that produced an error during loading, also keep the intermediate files from the loading directory.

error-directory

Used by orloader. Use this directory to store data from failed loads. The original input file is stored, unless debug-errors is set, in which case the contents of the loading directory at the time of the error are also stored here. The same security constraints apply as for loading-directory regarding database connection information.

incoming-directory

User by orloader. Watch this directory for new input files to load into the database. orloader ignores any files in this directory that are empty or whose names begin with a dot (”.”). In addition, new files will only be considered when their size is constant for one polling-interval after they are first noticed.

keep-unique-only

Used by orloader. This variable is optional, and defaults to no. If this flag is set, loaded RR data is discarded after being processed for unique information, and orquery will not have data to work with.

Normally, the RR data is kept for orquery searches. However, the RR database can be quite large, so if data is tight it may be discarded automatically. In addition, when using the super_mediator to deduplicate DNS records, this option should be turned on (since RRs are already being discarded before the data even reaches Orcus).

loading-directory

Used by orloader. Use this directory for temporary work while processing files and loading them into the database. This directory will include files which contain database connection information, so permissions on it should be limited to those who are allowed to have write access to the database.

log-pathname

Used by orloader. Use FILE_PATH as the complete path to the log file. The log file is not automatically rotated.

net-list

Used by orloader. When set to a comma-separated list of IPv4 and IPv6 CIDR blocks, this variable specifies a set of hosts used to distinguish internal DNS traffic from external DNS traffic, interpreted as described in net-list-mode.

net-list-mode

Used by orloader. Determines the intepretation of the addresses in net-list:

"internal" indicates that the networks listed in net-list contain internal hosts. Queries with an internal source and responses to an internal destination are treated as “internal” traffic. Other queries and responses are treated as “external” traffic. Internal queries store the source address. Internal responses store the destination address. External queries store the destination address. External responses store the source address.

"proxy" indicates that the networks listed in net-list contain “edge” hosts: proxies that make requests for internal hosts. Queries with a source in the edge are treated as external queries, other queries are treated as internal. Responses with a destincation in the edge are treated as external responses, other responses are treated as internal. Internal queries store the source address. Internal responses store the destination address. External queries store the destination address. External responses store the source address.

no-fix-pcap

Used by orloader. Defaults to yes. When reading PCAP files, don’t apply a fix for files which record an incorrect “snaplan” in their headers.

polling-interval

Used by orloader. Configures orloader to check the incoming directory at most every NUM seconds. The default polling interval is 30 seconds. If the previous round of loading takes longer than the polling interval, orloader will immediately resume processing. Otherwise, it will wait until at least NUM seconds have passed since the last load began.