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



2.1.6.1 Flags

When invoking Bro, you can control its behavior using the following flags:

-f 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
Generate a help message summarizing Bro's options and environment variables, and exit.


-i interface
Add interface to the list of interfaces from which Bro should read network traffic Live 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
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 XXX for discussion.


-r 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 signaturefile
Add signaturefile to the list of files containing signatures to match against the network traffic. See XXX for more information about signatures.


-w 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
Print the version of Bro and exit.
-F
Instructs Bro that it must resolve all hostnames out of its private DNS cache (See XXX). 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 indeterminant 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).

-O
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
Instructs Bro to prime its private DNS cache (See XXX). 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.
-W
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.