Next: , Up: Bro flags and run-time environment



2.1.6.1 Flags

When invoking Bro, you can control its behavior using a large number of flags and arguments. Most options can be specified using either a more readable long version (starting with two dashes), or a more compact but sometimes less intuitive short version (single dash followed by a single letter). Arguments can be provided after whitespace (i.e., “-r file.pcap” or “--readfile file.pcap”) and also using an equation mark when the long version is used (i.e., “--readfile=file.pcap”). Single-letter flags without arguments can be combined into a single option element (i.e., “-dWF” is the same as “-d -W -F”).

-d|--debug-policy
Activates policy file debugging. See Interactive Debugger for details.

-e|--exec <Bro statements>
Adds the given Bro policy statements to the loaded policy. Use for manual refinement, or for verifying the resulting value of a given variable. Note that you can omit trailing semi-colons.

-f|--filter filter
Use filter as the tcpdump filter for capturing packets, rather than the combination of and restrict_filter, or the default of “tcp or udp” .

-h|--help|-?
Generate a help message summarizing Bro's options and environment variables, and exit.

-g|--dump-config
Writes out the current configuration into the persistent state directory configured through the state_dir variable, defined in bro.init and subject to refinement.

-i|--iface <interface>
Add interface to the list of interfaces from which Bro should read network traffic. You can use this flag multiple times to direct Bro to read from multiple interfaces. You can also, or in addition, use refinements of the variable to specify interfaces.

Note that if no interfaces are specified, then Bro will not read any network traffic. It does not have a notion of a “default” interface from which to read.

-p|--prefix <prefix>
Add prefix to the list of prefixes searched by Bro when loading a script. You can also, or in addition, use prefix to specify search prefixes. See prefixes for discussion.

-r|--readfile <readfile>
Add readfile to the list of tcpdump save files that Bro should read. You can use this flag multiple times to direct Bro to read from multiple save files; it will merge the packets read from the different files based on their timestamps. Note that if the save files contain only packet headers and not contents, then of course Bro's analysis of them will be limited.

Note that use of -r is mutually exclusive with use of -i. However, you can use -r when running scripts that refine interfaces, in which case the -r option takes precedence and Bro performs off-line analysis.

-s|--rulefile <signaturefile>
Add signaturefile to the list of files containing signatures to match against the network traffic. See Signatures for more information.

-t|--tracefile <tracefile>
Enables tracing of Bro script execution. See Execution tracing.

-w|--writefile <writefile>
Write a tcpdump save file to the file writefile. Bro will record all of the packets it captures, including their contents, except as controlled by calls to set_record_packets. Note: One exception is that unless you are analyzing HTTP events (for example, by loading the refhttp analyzer), Bro does not record the contents of HTTP SYN/FIN/RST packets to the trace file. The reason for this is that HTTP FIN packets often contain a large amount of data, which is not of any interest if you are not using HTTP analysis, and due to the very high volume of HTTP traffic at many sites, removing this data can significantly reduce the size of the save file. Deficiency: Clearly, this should not be hardwired into Bro but under user control.

Save files written using -w are of course readable using -r. Accordingly, you will generally want to use -w when running Bro on live network traffic so you can rerun it off-line later to understand any problems that arise, and also to experiment with the effects of changes to the policy scripts.

You can also combine -r with -w to both read a save file(s) and write another. This is of interest when using multiple instances of -r, as it provides a way to merge tcpdump save files.

-v|--version
Print the version of Bro and exit.

-x|--print-state <Bro state file>
Reads the contents of the specified Bro state file, prints them to the console, and exits.

-z|--analyze <analysis>
Runs the specified analyzer over the configured policy. See Policy analyzers.

-A|--transfile <writefile>
Write transformed trace to the tcpdump file given. See Trace rewriting.

-C|--no-checksums
Incorrect IP, TCP, or UDP checksums normally trigger different variants of net_weird and conn_weird events (see also Events handled by net_weird, Events handled by conn_weird, and weird variables). This flag causes Bro to ignore incorrect checksums.

-D|--dfa-size <size>
Sets the cache size of deterministic finite automata (used extensively for signatures) to the given number of entries. The default is 10,000.

-F|--force-dns
Instructs Bro that it must resolve all hostnames out of its private DNS cache. If the script refers to a hostname not in the cache, then Bro exits with a fatal error.

The point behind this option is to ensure that Bro starts quickly, rather than possibly stalling for an undetermined amount of time resolving a hostname. Fast startup simplifies checkpointing a running Bro—you can start up a new Bro and then killing off the old one shortly after. You'd like this to occur in a manner such that there's no period during which neither Bro is watching the network (the older because you killed it off too early, the newer because it's stuck resolving hostnames).

-I|--print-id <name>
Looks up the variable identified by “name” in the global scope (see Scope) and prints it to the console.

-K|--md5-hashkey <hashkey>
Allows you to specify a fixed seed for MD5 initialization. MD5 is used by default for hashing elements in the Bro core, and by default some randomness is gathered at Bro startup before PRNG initialization.

Note: This means that by default repeated runs of Bro on identical inputs do not necessarily yield identical output. If you want to ensure determinism, use the --save-seeds and --load-seeds options.

-L|--rule-benchmark
See Rule benchmarking.

-O|--optimize
Turns on Bro's optimizer for improving its internal representation of the policy script. Note: Currently, the amount of improvement is modest, and there's (as always) a risk of an optimizer bug introducing errors into the execution of the script, so the optimizer is not enabled by default.

-P|--prime-dns
Instructs Bro to prime its private DNS cache. It does so by parsing the policy scripts, but not executing them. Bro looks up each hostname's address(es) and records them in the private cache. The idea is that once bro -P finishes, you can then use bro -F to start up Bro quickly because it will read all the information it needs from the cache.

-S|--debug-rules
Prints debugging output for the rules used in signature matching. See also Signatures.

-T|--re-level <level>
Sets the level in the tree of rules at which regular expressions are built. Default is 4.

-W|--watchdog
Instructs Bro to activate its internal watchdog. The watchdog provides self-monitoring to enable Bro to detect if its processing is wedged.

Bro only activates the watchdog if it is reading live network traffic. The watchdog consists of a periodic timer that fires every WATCHDOG_INTERVAL seconds. (Deficiency:clearly this should be a user-definable value.) At that point, the watchdog checks to see whether Bro is still working on the same packet as it was the last time the watchdog expired. If so, then the watchdog logs this fact along with some information regarding when Bro began processing the current packet and how many events it processed after handling the packet. Finally, it prints the packet drop information for the different interfaces Bro was reading from, and aborts execution.

--save-seeds <file>
Writes the seeds used for initializing the PRNGs in Bro to the given file. This can be combined with -K|--md5-hashkey, and is intended to be used with --load-seeds in future Bro runs.

--save-seeds <file>
Seeds the PRNGs in Bro using a file produced by --save-seeds in an earlier Bro invocation.