Output Switches¶

--fields FIELD[, FIELDS]¶

Produces output containing the listed fields. Record types that do not include at least one of the chosen fields will not be output. Records that contain some but not all of the included fields will be output with blanks for the missing fields.

Fields may be included in any order, and may appear multiple times. The columns of the output will be in the same order as specified by this switch.

The following field names are understood by orquery:

• time, sensor, direction, type, address

  These fields are present in all records. They represent the time the record was observed (in YYYY/MM/DDTHH:MM:SS.SSS format), the name of the sensor that observed it, the direction (either int for traffic involving internal hosts or ext for traffic involving external hosts), the type (QUERY, NXDOMAIN, or a DNS resource record type name like A), and the IPv4 or IPv6 address of the internal or external host involved.

• q-name, q-type, q-class

  These fields are present in “QUERY” and “NXDOMAIN” records. They represent the name, type, and class of the query being made or being replied to.

• rr-name, rr-section, rr-ttl

  These fields are present in all DNS resource record types. They represent the name the resource record describes, the section of the DNS response they appeared in (AN for the answer section, NS for the authority section, and AR for the additional section), and the TTL of the resource record.

• rr-a

  For “A” records, this contains the IPv4 address.

• rr-aaaa

  For “AAAA” records, this contains the IPv6 address.

• rr-cname

  For “CNAME” records, this contains the canonical hostname.

• rr-mx-preference, rr-mx-exchange

  For “MX” records, these contain the numeric preference value of the record, and the domain name for the mail exchanger.

• rr-ns-name

  For “NS” records, this contains the name server hostname.

• rr-ptr-name

  For “PTR” records, this contains the target host name.

• rr-soa-mname, rr-soa-rname, rr-soa-serial, rr-soa-refresh, rr-soa-retry, rr-soa-expire, rr-soa-minimum

  For “SOA” records, these contain the zone master domain name, the responsible party contact email (encoded as a domain name), the zone file serial number, the refresh interval, the retry interval, the maximum caching time before expiry, and the zone’s minimum TTL.

• rr-srv-priority, rr-srv-weight, rr-srv-port, rr-srv-target

  For “SRV” records, these contain the service record’s numeric priority and weight, the service port number, and the target server’s domain name.

• rr-txt

  For “TXT” records, this contains the text of the record.

Selection switches¶

A number of selection arguments allow lists of values or patterns for values to be specified. Specifically:

INTEGER_LIST

Many DNS fields contain integers, and INTEGER_LIST arguments allow you to specify one or more ranges of allowed values using a comma-separated list of numbers and ranges.

Example:

-27,29,35-100,200-

This would match anything up to 27, 29, 35 through 100 inclusive, and anything greater or equal to 200. If you wish to look for everything but a specific value, you can use a list like -6,8- to skip that item but include everything else.

IP_SPEC

An IP address specification (also IPv4_SPEC or IPv6_SPEC for values limited to v4 or v6 IP addresses) consists of a comma-separated list of IP addresses and IP address prefixes. In IPv4 addresses, trailing zero octets can be left out. In IPv6 addresses, the standard abbreviations are available.

Example:

127.0.0.1,192.168.0.0/16,204/8

This would match 127.0.0.1, 192.168.237.115, 204.1.2.3, and so on.

Note that IPv6 addresses and the “equivalent” IPv4 addresses are treated separately. 1.2.3.4 is not equivalent to either ::ffff:1.2.3.4 nor ::1.2.3.4.

NAME_PATTERN, TEXT_PATTERN

Domain names and text fields allow filtering based on exact matches, shell-style globs, or regular expressions. Don’t forget that Orcus works with all domain names in “reversed” order. Top-level domains come first, then second-level, and so on.

The type of pattern is specified at the start of the pattern with “TYPE:”, and the recognized types are “glob” for UNIX-style globs, “re” for regular expressions, and “exact” for exact matches. If no type is specified, “glob” is assumed.

Examples:

org.sample.*
glob:org.sample.*
re:org\.sample(\..*)?
exact:org.sample.*

The first two examples have the same meaning: any name starting with “org.sample.” followed by anything else. The third is a regular expression that matches “org.sample”, as well as “org.sample.” followed by anything else. The final example is an exact match, looking for a name that contains a literal asterisk character as the hostname.

--type [{DIRECTION|TYPE|DIRECTION/TYPE}[, DIRTYPES]]¶

Chooses the types and/or the directions) of records to be queried.

The following DNS record types are recognized: “QUERY”, “NXDOMAIN”, “A”, “AAAA”, “CNAME”, “MX”, “NS”, “PTR”, “SOA”, “SRV”, “TXT”. “QUERY” and “NXDOMAIN” are “pseudo-resource-records” representing DNS queries and no-such-domain responses. Each of the others is a DNS resource record type.

The following traffic directions are recognized: “int” which represents queries from and responses to internal hosts, and “ext” which represents queries to and response from external hosts.

If only a direction or only a record type is specific, all matching records will be included. For example, “int/a” will query “A” records sent to internal hosts, and “ext/soa” will query “SOA” records sent from external hosts. “int” will query all queries from and responses to internal hosts, and “soa” will query all “SOA” records sent by external hosts or sent to internal hosts.

--start-date YYYY/MM/DD[:HH]¶

Determines the beginning of the time-period to process. Time is given in UTC. Defaults to the start of the current day.

--end-date YYYY/MM/DD[:HH]¶

Determines the end of the time-period to process, based on the precision of the value. For example, if a date is specified all records up to the end of that day are included. If an hour is specified, all records up to the end of that hour. Time is given in UTC. Defaults to the value given for --start-date.

--sensor SENSOR[, SENSORS]¶

Chooses which sensors to process, by sensor name.

--address IP_SPEC¶

Filters the results based on the “address” field of records. For external (direction “ext”) records this is the external IP address that received a query or sent a response. For internal queries (direction “int”), this is the internal IP address that sent a query or received a response.

Record-specific switches¶

Note that it is possible to provide a set of filtering switches such that no records can possibly be returned. If this occurs, orquery will exit and report an error. (For example, if you ask for records using both --rr-a and --rr-aaaa, no records could be returned, since no record is both an “A” record and a “AAAA” record.