Merge remote-tracking branch 'origin/topic/dnthayer/doc-fixes-for-2.6'

* origin/topic/dnthayer/doc-fixes-for-2.6:
  Fix some typos and improve formatting in NEWS
  Update the operators documentation
  Replace references to libgeoip in the documentation
  Update install instructions for python-ipaddress
  Update documentation of "option" and "redef" declarations
  Improvements to the config framework documentation
  Rearrange some lines on the "Log Files" documentation page
  Improve install/setup instructions for libmaxminddb
  Update NEWS for config framework clusterization changes
  Update config framework doc for clusterization changes
  Fix typos and formatting issues in config framework docs

CHANGES

@@ -1,4 +1,8 @@
 
+2.5-870 | 2018-08-17 17:07:57 -0500
+
+  * Documentation improvements (Daniel Thayer)
+
 2.5-855 | 2018-08-17 16:34:51 -0500
 
   * Add script to support the old DHCP events (Vlad Grigorescu)

NEWS

@@ -114,7 +114,11 @@ New Functionality
   - Option variables: The new "option" keyword allows variables to be
     declared as runtime options. Such variables cannot be changed
     using normal assignments. Instead, they can be changed using the
-    new function Option::set.
+    new function Config::set_value.  This function will automatically
+    apply the change to all nodes in a cluster.  Note that options can also
+    be changed using the new function Option::set, but this function will
+    not send the change to any other nodes, so Config::set_value should
+    typically be used instead of Option::set.
 
     It is possible to "subscribe" to an option through
     Option::set_change_handler, which will trigger a handler callback
@@ -162,7 +166,7 @@ New Functionality
         }
 
     The specified file will now be monitored continuously for changes, so
-    that writing "testbool T" into /path/to/config.dat will
+    that writing "TestConfig::testbool T" into /path/to/config.dat will
     automatically update the option's value accordingly.
 
     The configuration framework creates a config.log that shows all
@@ -220,7 +224,6 @@ New Functionality
   ssl_server_curve event, ssl_server_curve is now marked as deprecated.
 
 - Functions for retrieving files by their ID have been added:
-
   Files::file_exists, Files::lookup_File
 
 - New functions in the logging API: Log::get_filter_names, Log::enable_stream
@@ -237,13 +240,13 @@ New Functionality
     mount_proc_umnt, mount_proc_umnt_all, mount_proc_not_implemented,
     mount_reply_status.
 
-- Added new NFS events: nfs_proc_symlink, nfs_proc_link, nfs_proc_sattr
+- Added new NFS events: nfs_proc_symlink, nfs_proc_link, nfs_proc_sattr.
 
 - The SMB scripts in policy/protocols/smb are now moved into base/protocols/smb
   and loaded/enabled by default.
 
 - Added new SMB events: smb1_transaction_secondary_request,
-  smb1_transaction2_secondary_request, smb1_transaction_response
+  smb1_transaction2_secondary_request, smb1_transaction_response.
 
 - Bro can now decrypt Kerberos tickets, and retrieve the authentication from
   them, given a suitable keytab file.
@@ -260,20 +263,18 @@ New Functionality
 
 - You can now specify that a pattern matches in a case-insensitive
   fashion by adding 'i' to the end of its specification.  So for example
-  /fOO/i == "Foo" yields T, as does /fOO/i in "xFoObar".  Characters
+  /fOO/i == "Foo" yields T, as does /fOO/i in "xFoObar".
-  enclosed in quotes however keep their casing, so /"fOO"/i in "xFoObar"
-  yields F, though it yields T for "xfOObar".
 
   You can achieve the same functionality for a subpattern enclosed in
   parentheses by adding "?i:" to the open parenthesis.  So for example
-  "/foo|(?i:bar)/" will match "BaR", but not "FoO".
+  /foo|(?i:bar)/ will match "BaR", but not "FoO".
 
   For both ways of specifying case-insensitivity, characters enclosed in
-  double quotes maintain their case-sensitivity.  So for example /"foo"/i
+  double quotes remain case-sensitive.  So for example /"foo"/i will not
-  will not match "Foo", but it will match "foo".
+  match "Foo", but it will match "foo".
 
 - "make install" now installs Bro's include headers (and more) into
-  --prefix so that compiling plugins does no longer need access to a
+  --prefix so that compiling plugins no longer needs access to a
   source/build tree. For OS distributions, this also facilitates
   creating "bro-devel" packages providing all files necessary to build
   plugins.
@@ -313,7 +314,7 @@ New Functionality
   of non-equality, proper superset, and superset-or-equal.
 
 - An expression of the form "v += e" will append the value of the expression
-  "e" to the end of the vector "v" (of course assuming type-compatbility).
+  "e" to the end of the vector "v" (of course assuming type-compatibility).
   "redef v += { a, b, c }" will similarly extend a vector previously declared
   with &redef by appending the result of expressions "a", "b", and "c" to
   the vector at initialization-time.
@@ -336,9 +337,9 @@ Changed Functionality
     script since it's generally less relevant now with the updated log.
 
   - Removed the base/protocols/dhcp/utils.bro script and thus the
-    'reverse_ip' function.
+    "reverse_ip" function.
 
-  - Replaced all DHCP events with the single 'dhcp_message' event.
+  - Replaced all DHCP events with the single "dhcp_message" event.
     The list of removed events includes:
 
     - dhcp_discover
@@ -381,9 +382,9 @@ Changed Functionality
   redef SOCKS::default_capture_password = T;
 
 - The DNS base scripts no longer generate some noisy and annoying
-  weirds (dns_unmatched_msg, dns_unmatched_msg_quantity, dns_unmatched_reply)
+  weirds (dns_unmatched_msg, dns_unmatched_msg_quantity, dns_unmatched_reply).
 
-- The 'tunnel_parents' field of conn.log is now marked &optional, so, for
+- The "tunnel_parents" field of conn.log is now marked &optional, so, for
   the default configuration of logs, this field will show "-" instead of
   "(empty)" for connections that lack any tunneling.
 
@@ -403,7 +404,7 @@ Changed Functionality
   - event ssl_server_signature now has an additional argument
     "signature_and_hashalgorithm".
 
-- The "dnp3_header_block" event no longer has the "start" parameter
+- The "dnp3_header_block" event no longer has the "start" parameter.
 
 - The string_to_pattern() built-in (and the now-deprecated merge_pattern()
   built-in) is no longer restricted to only be called at initialization time.
@@ -426,11 +427,11 @@ Removed Functionality
   https://github.com/bro/packages for a list of Bro packages currently
   available.
 
-- BroControl: The option 'IPv6Comm' and 'ZoneID' options are no longer
-  available (though Broker should be able to handle IPv6 automatically).
-
 - The "ocsp_request" event no longer has "requestorName" parameter.
 
+- BroControl: The "IPv6Comm" and "ZoneID" options are no longer
+  available (though Broker should be able to handle IPv6 automatically).
+
 Deprecated Functionality
 ------------------------
 
@@ -445,10 +446,6 @@ Deprecated Functionality
   as BiFs like send_id(). Use Broker data stores and the new
   configuration framework instead.
 
-- BroControl: The 'update' command is deprecated and scheduled for
-  removal with the next Bro release. Bro's new configuration framework
-  is taking its place.
-
 - Mixing of scalars and vectors, such as "v + e" yielding a vector
   corresponding to the vector v with the scalar e added to each of
   its elements, has been deprecated.
@@ -459,6 +456,10 @@ Deprecated Functionality
 - The undocumented feature of using "&&" and "||" operators for patterns
   has been deprecated.
 
+- BroControl: The "update" command is deprecated and scheduled for
+  removal with the next Bro release. Bro's new configuration framework
+  is taking its place.
+
 Bro 2.5.1
 =========
 

VERSION

@@ -1 +1 @@
-2.5-855
+2.5-870

doc/frameworks/configuration.rst

@@ -11,7 +11,7 @@ Bro includes a "configuration framework" that allows
 updating script options dynamically at runtime. This functionality
 consists of several components: an "option" declaration, the
 ability to specify input files to enable changing the value of options at
-runtime, a couple of built-in functions, and a log file "config.log"
+runtime, a couple of functions, and a log file "config.log"
 which contains information about every change to option values.
 
 
@@ -50,14 +50,28 @@ The "option" keyword allows variables to be declared as configuration options.
         option my_networks: set[subnet] = {};
         option enable_feature = F;
         option hostname = "testsystem";
+        option timeout = 1min;
+        option my_ports: vector of port = {};
     }
 
 The rules regarding options can be thought of as being in between global
 variables and constants.  Like global variables, options cannot be declared
 inside a function, hook, or event handler.  Like constants, options must be
-initialized when declared.  The value of an option can change at runtime,
+initialized when declared (the type can often be inferred from the initializer
+but may need to be specified).  The value of an option can change at runtime,
 but options cannot be assigned a new value using normal assignments.
 
+The initial value of an option can be redefined with a :bro:keyword:`redef`
+declaration just like for global variables and constants.  The only difference
+being that there is no need to specify the :bro:attr:`&redef` attribute in
+the declaration of an option.  For example, given the above option
+declarations, here are some possible redefs:
+
+.. code:: bro
+
+    redef TestModule::enable_feature = T;
+    redef TestModule::my_networks += { 10.1.0.0/16, 10.2.0.0/16 };
+
 
 Changing options
 ----------------
@@ -70,21 +84,32 @@ The format for these files looks like this:
 
     [option name][tab/spaces][new value]
 
-Configuration files can be specified by adding them to Config::config_files.
+Configuration files can be specified by adding them
+to :bro:id:`Config::config_files`.  Note that in a cluster configuration,
+only the manager node attempts to read the specified configuration files.
+
 For example, simply add something like this to local.bro:
 
 .. code:: bro
 
     redef Config::config_files += { "/path/to/config.dat" };
 
-The specified configuration file will then be monitored continuously for changes,
+The specified configuration file will then be monitored continuously for
-so that writing ``TestModule::enable_feature T`` into that file will
+changes, so that writing ``TestModule::enable_feature T`` into that file will
-automatically update the option's value accordingly.  Here is an example
+automatically update the option's value accordingly (in a cluster
-configuration file::
+configuration, the change will be sent from the manager to all other nodes in
+the cluster).  Here is an example configuration file::
 
     TestModule::my_networks 10.0.12.0/24,192.168.17.0/24
     TestModule::enable_feature  T
     TestModule::hostname  host-1
+    TestModule::timeout 50.5
+    TestModule::my_ports 80/tcp,53/udp
+
+Note that as seen in the above example, for options of
+type :bro:type:`interval`, the numeric value in the config file
+is interpreted as seconds and there cannot be any time units
+(such as sec, min, etc.).
 
 Internally, the configuration framework uses the Bro input framework
 with a type of input reader specifically for reading config files. Users
@@ -94,13 +119,34 @@ for configuration files: the files need no header lines and either
 tabs or spaces are accepted as separators.
 
 If you inspect the configuration framework scripts, you will notice that the
-scripts simply catch events from the input framework and then a built-in
+scripts simply catch events from the input framework and then a
-function :bro:see:`Option::set` is called to set an option to the new value.
+function :bro:see:`Config::set_value` is called to set an option to the new
-If you want to change an option yourself during runtime, you can
+value.  If you want to change an option yourself during runtime, you can
-call Option::set directly from a script.
+call Config::set_value directly from a script (in a cluster configuration,
+this only needs to happen on the manager, as the change will be automatically
+sent to all other nodes in the cluster).
 
-The log file "config.log" contains information about each configuration
+Note that some data types (such as pattern, table, and record) are not
-change that occurs during runtime.
+supported by the config input reader.  In that case you would need to use
+the Config::set_value function to change the value of such an option as
+shown in the following example.
+
+.. code:: bro
+
+    module TestModule;
+
+    export {
+        option host_port: table[addr] of port = {};
+    }
+
+    event bro_init() {
+        local t: table[addr] of port = { [10.0.0.2] = 123/tcp };
+        Config::set_value("TestModule::host_port", t);
+    }
+
+Regardless of whether an option change is triggered by a config file or by
+the Config::set_value function, the change is always logged to the
+log file "config.log".
 
 
 Change handlers
@@ -114,7 +160,11 @@ accordingly):
 
 .. code:: bro
 
+    module TestModule;
+
+    export {
         option testaddr = 127.0.0.1;
+    }
 
     # Note: the data type of 2nd parameter and return type must match
     function change_addr(ID: string, new_value: addr): addr
@@ -125,24 +175,26 @@ accordingly):
 
     event bro_init()
         {
-        Option::set_change_handler("testaddr", change_addr);
+        Option::set_change_handler("TestModule::testaddr", change_addr);
         }
 
-Each time the specified option value is changed, the change handler
+Immediately before the specified option value is changed, the change handler
-function will be called before the change is performed.  The value returned
+function will be called.  The value returned by the change handler is the
-by the change handler is the value finally assigned to the option. This
+value finally assigned to the option. This allows, for example, checking of
-allows, for example, checking of values to reject invalid input (the original
+values to reject invalid input (the original value can be returned to reject
-value can be returned to reject the change).
-
-A change handler can optionally have a third argument, which is the location
-string (this is normally the pathname of the configuration file that triggered
 the change).
 
-It is also possible to chain together multiple change handlers.  In this
+It is possible define multiple change handlers for a single option.  In
-case, the value returned by the first change handler is the "new value" seen
+this case, the change handlers are chained together: the value returned by the
-by the next change handler, and so on.  The built-in function
+first change handler is the "new value" seen by the next change handler, and
-:bro:see:`Option::set_change_handler` takes an optional third argument
+so on.  The built-in function :bro:see:`Option::set_change_handler` takes an
-that can specify a priority for the handlers.
+optional third argument that can specify a priority for the handlers.
+
+A change handler function can optionally have a third argument of type
+string.  When a config file triggers a change, then the third argument is
+the pathname of the config file.  When the Config::set_value function triggers
+a change, then the third argument of the change handler is the value passed
+to the optional third argument of the Config::set_value function.
 
 Note that change handlers are also used internally by the
 configuration framework. If you look at the script level source code of

doc/frameworks/geoip.rst

@@ -10,8 +10,8 @@ GeoLocation
     During the process of creating policy scripts the need may arise
     to find the geographic location for an IP address. Bro had support
     for the `GeoIP library <http://www.maxmind.com/app/c>`__ at the
-    policy script level from release 1.3 to 2.5.X to account for this
+    policy script level from release 1.3 to 2.5.x to account for this
-    need.  Starting with release 2.6 GeoIP support requires `libmaxminddb
+    need.  Starting with release 2.6, GeoIP support requires `libmaxminddb
     <https://github.com/maxmind/libmaxminddb/releases>`__.
     To use this functionality, you need to first install the libmaxminddb
     software, and then install the GeoLite2 city database before building
@@ -19,17 +19,11 @@ GeoLocation
 
 .. contents::
 
-Install libGeoIP
+Install libmaxminddb
-----------------
+--------------------
 
 Before building Bro, you need to install libmaxminddb.
 
-* FreeBSD:
-
-  .. console::
-
-      sudo pkg install libmaxminddb
-
 * RPM/RedHat-based Linux:
 
   .. console::
@@ -42,12 +36,17 @@ Before building Bro, you need to install libmaxminddb.
 
       sudo apt-get install libmaxminddb-dev
 
+* FreeBSD:
+
+  .. console::
+
+      sudo pkg install libmaxminddb
+
 * Mac OS X:
 
   You need to install from your preferred package management system
-  (e.g. MacPorts, Fink, or Homebrew).  The name of the package that you need
+  (e.g. Homebrew, MacPorts, or Fink).  For Homebrew, the name of the package
-  may be libmaxminddb, maxminddb, or libmaxminddb-dev, depending on which
+  that you need is libmaxminddb.
-  package management system you are using.
 
 
 GeoLite2-City Database Installation
@@ -64,8 +63,8 @@ the GeoLite2 city binary database:
     wget http://geolite.maxmind.com/download/geoip/database/GeoLite2-City.tar.gz
     tar zxf GeoLite2-City.tar.gz
 
-Next, the file "GeoLite2-City_YYYYMMDD/GeoLite2-City.mmdb" needs to be renamed
+Next, the file "GeoLite2-City_YYYYMMDD/GeoLite2-City.mmdb" needs to be moved
-and put in the GeoIP database directory.  This directory should already exist
+to the GeoIP database directory.  This directory might already exist
 and will vary depending on which platform and package you are using.  For
 FreeBSD, use ``/usr/local/share/GeoIP``.  For Linux, use ``/usr/share/GeoIP``
 or ``/var/lib/GeoIP`` (choose whichever one already exists).
@@ -88,22 +87,23 @@ functionality works by running a command like this:
 
 If you see an error message similar to "Failed to open GeoIP location
 database", then you may need to either rename or move your GeoIP
-location database file.  Bro looks for location database files in the
+location database file.  If the :bro:see:`mmdb_dir` value is set to a
-following order by default:
+directory pathname (it is not set by default), then Bro looks for location
+database files in that directory.  If none are found or if mmdb_dir is not set,
+then Bro looks for location database files in the following order:
 
-    /usr/share/GeoIP/GeoLite2-City.mmdb
+* /usr/share/GeoIP/GeoLite2-City.mmdb
-    /var/lib/GeoIP/GeoLite2-City.mmdb
+* /var/lib/GeoIP/GeoLite2-City.mmdb
-    /usr/local/share/GeoIP/GeoLite2-City.mmdb
+* /usr/local/share/GeoIP/GeoLite2-City.mmdb
-    /usr/local/var/GeoIP/GeoLite2-City.mmdb
+* /usr/local/var/GeoIP/GeoLite2-City.mmdb
-    /usr/share/GeoIP/GeoLite2-Country.mmdb
+* /usr/share/GeoIP/GeoLite2-Country.mmdb
-    /var/lib/GeoIP/GeoLite2-Country.mmdb
+* /var/lib/GeoIP/GeoLite2-Country.mmdb
-    /usr/local/share/GeoIP/GeoLite2-Country.mmdb
+* /usr/local/share/GeoIP/GeoLite2-Country.mmdb
-    /usr/local/var/GeoIP/GeoLite2-Country.mmdb
+* /usr/local/var/GeoIP/GeoLite2-Country.mmdb
 
 If you see an error message similar to "Bro was not configured for GeoIP
-support", then you either need to rebuild Bro and make sure it is linked
+support", then you need to rebuild Bro and make sure it is linked
-against libmaxminddb or else set the :bro:see:`mmdb_dir` value
+against libmaxminddb.  Normally, if libmaxminddb is installed correctly then it
-correctly.  Normally, if libmaxminddb is installed correctly then it
 should automatically be found when building Bro.  If this doesn't
 happen, then you may need to specify the path to the libmaxminddb
 installation (e.g. ``./configure --with-geoip=<path>``).

doc/install/install.rst

@@ -60,6 +60,9 @@ To install the required dependencies, you can use:
 
      sudo apt-get install cmake make gcc g++ flex bison libpcap-dev libssl-dev python-dev swig zlib1g-dev
 
+  If your system uses Python 2.7, then you will also need to install the
+  "python-ipaddress" package.
+
 * FreeBSD:
 
   Most required dependencies should come with a minimal FreeBSD install
@@ -114,7 +117,7 @@ Optional Dependencies
 Bro can make use of some optional libraries and tools if they are found at
 build time:
 
-    * LibGeoIP (for geolocating IP addresses)
+    * libmaxminddb (for geolocating IP addresses)
     * sendmail (enables Bro and BroControl to send mail)
     * curl (used by a Bro script that implements active HTTP)
     * gperftools (tcmalloc is used to improve memory and CPU usage)
@@ -122,9 +125,9 @@ build time:
     * PF_RING (Linux only, see :doc:`Cluster Configuration <../configuration/index>`)
     * ipsumdump (for trace-summary; http://www.cs.ucla.edu/~kohler/ipsumdump)
 
-LibGeoIP is probably the most interesting and can be installed
+Geolocation is probably the most interesting and can be installed
 on most platforms by following the instructions for :ref:`installing
-libGeoIP and the GeoIP database
+the GeoIP library and database
 <geolocation>`.
 
 

doc/script-reference/log-files.rst

@@ -14,8 +14,6 @@ Network Protocols
 +============================+=======================================+=================================+
 | conn.log                   | TCP/UDP/ICMP connections              | :bro:type:`Conn::Info`          |
 +----------------------------+---------------------------------------+---------------------------------+
-| config.log                 | Configuration option changes          | :bro:type:`Config::Info`        |
-+----------------------------+---------------------------------------+---------------------------------+
 | dce_rpc.log                | Distributed Computing Environment/RPC | :bro:type:`DCE_RPC::Info`       |
 +----------------------------+---------------------------------------+---------------------------------+
 | dhcp.log                   | DHCP leases                           | :bro:type:`DHCP::Info`          |
@@ -161,12 +159,14 @@ Bro Diagnostics
 +----------------------------+---------------------------------------+---------------------------------+
 | Log File                   | Description                           | Field Descriptions              |
 +============================+=======================================+=================================+
+| broker.log                 | Peering status events between Bro or  | :bro:type:`Broker::Info`        |
+|                            | Broker-enabled processes              |                                 |
++----------------------------+---------------------------------------+---------------------------------+
 | capture_loss.log           | Packet loss rate                      | :bro:type:`CaptureLoss::Info`   |
 +----------------------------+---------------------------------------+---------------------------------+
 | cluster.log                | Bro cluster messages                  | :bro:type:`Cluster::Info`       |
 +----------------------------+---------------------------------------+---------------------------------+
-| broker.log                 | Peering status events between Bro or  | :bro:type:`Broker::Info`        |
+| config.log                 | Configuration option changes          | :bro:type:`Config::Info`        |
-|                            | Broker-enabled processes              |                                 |
 +----------------------------+---------------------------------------+---------------------------------+
 | loaded_scripts.log         | Shows all scripts loaded by Bro       | :bro:type:`LoadedScripts::Info` |
 +----------------------------+---------------------------------------+---------------------------------+

doc/script-reference/operators.rst

@@ -10,6 +10,11 @@ Relational operators
 
 The relational operators evaluate to type :bro:type:`bool`.
 
+In addition to numeric operands, the relational operators also work with
+operands of type :bro:type:`interval`, :bro:type:`time`, :bro:type:`string`,
+:bro:type:`port`, :bro:type:`addr`, and :bro:type:`set`.
+
+
 +------------------------------+--------------+
 | Name                         | Syntax       |
 +==============================+==============+
@@ -104,12 +109,27 @@ only.
 | Bitwise complement           | ~ *a*       |
 +------------------------------+-------------+
 
+Set operators
+-------------
+
++------------------------------+-------------+
+| Name                         | Syntax      |
++==============================+=============+
+| Set intersection             | *s1* & *s2* |
++------------------------------+-------------+
+| Set union                    | *s1* | *s2* |
++------------------------------+-------------+
+| Set difference               | *s1* - *s2* |
++------------------------------+-------------+
 
 Assignment operators
 --------------------
 
 The assignment operators evaluate to the result of the assignment.
 
+The "+=" operator can also be used to append an element to the end of a
+vector.  For example, ``v += e`` is equivalent to ``v[|v|] = e``.
+
 +------------------------------+-------------+
 | Name                         | Syntax      |
 +==============================+=============+
@@ -215,7 +235,14 @@ Other operators
 | Name                           | Syntax            | Notes                  |
 +================================+===================+========================+
 | Membership test                | *a* in *b*        |Evaluates to type       |
-|                                |                   |:bro:type:`bool`. Do not|
+|                                |                   |:bro:type:`bool`. Works |
+|                                |                   |with :bro:type:`string`,|
+|                                |                   |:bro:type:`pattern`,    |
+|                                |                   |:bro:type:`subnet`,     |
+|                                |                   |:bro:type:`set`,        |
+|                                |                   |:bro:type:`table`, or   |
+|                                |                   |:bro:type:`vector`      |
+|                                |                   |operands.  Do not       |
 |                                |                   |confuse this use of "in"|
 |                                |                   |with that used in a     |
 |                                |                   |:bro:keyword:`for`      |

doc/script-reference/statements.rst

@@ -190,7 +190,11 @@ all loaded Bro scripts.
         option hostname = "host-1";
         option peers: set[addr] = {};
 
-    The value of an option cannot be changed by an assignment statement.
+    The initial value can be redefined with a :bro:keyword:`redef`.
+
+    The value of an option cannot be changed by an assignment statement, but
+    it can be changed by either the :bro:id:`Config::set_value` function or
+    by changing a config file specified in :bro:id:`Config::config_files`.
 
     The scope of an option is global.
 
@@ -215,26 +219,30 @@ all loaded Bro scripts.
 
 .. bro:keyword:: redef
 
-    There are three ways that "redef" can be used:  to change the value of
+    There are several ways that "redef" can be used:  to redefine the initial
-    a global variable (but only if it has the :bro:attr:`&redef` attribute),
+    value of a global variable or runtime option, to extend a record type or
-    to extend a record type or enum type, or to specify
+    enum type, or to specify a new event handler body that replaces all those
-    a new event handler body that replaces all those that were previously
+    that were previously defined.
-    defined.
 
-    If you're using "redef" to change a global variable (defined using either
+    If you're using "redef" to redefine the initial value of a global variable
-    :bro:keyword:`const` or :bro:keyword:`global`), then the variable that you
+    (defined using either :bro:keyword:`const` or :bro:keyword:`global`), then
-    want to change must have the :bro:attr:`&redef` attribute.  If the variable
+    the variable that you want to change must have the :bro:attr:`&redef`
-    you're changing is a table, set, or pattern, you can use ``+=`` to add
+    attribute.  You can use "redef" to redefine the initial value of a
-    new elements, or you can use ``=`` to specify a new value (all previous
+    runtime option (defined using :bro:keyword:`option`) even if it doesn't
-    contents of the object are removed).  If the variable you're changing is a
+    have the :bro:attr:`&redef` attribute.
-    set or table, then you can use the ``-=`` operator to remove the
+
-    specified elements (nothing happens for specified elements that don't
+    If the variable you're changing is a table, set, vector, or pattern, you can
+    use ``+=`` to add new elements, or you can use ``=`` to specify a new value
+    (all previous contents of the object are removed).  If the variable you're
+    changing is a set or table, then you can use the ``-=`` operator to remove
+    the specified elements (nothing happens for specified elements that don't
     exist).  If the variable you are changing is not a table, set, or pattern,
     then you must use the ``=`` operator.
 
     Examples::
 
         redef pi = 3.14;
+        redef set_of_ports += { 22/tcp, 53/udp };
 
     If you're using "redef" to extend a record or enum, then you must
     use the ``+=`` assignment operator.

doc/script-reference/types.rst

@@ -253,10 +253,10 @@ Here is a more detailed description of each type:
 
     When specifying a pattern, you can add a final ``i`` specifier to
     mark it as case-insensitive.  For example, ``/foo|bar/i`` will match
-    a "foo", "Foo", "BaR", etc.
+    "foo", "Foo", "BaR", etc.
 
     You can also introduce a case-insensitive sub-pattern by enclosing it
-    in ``(?i:``<pattern>``)``.  So, for example, ``/foo|(?i:bar)/`` will
+    in ``(?i:<pattern>)``.  So, for example, ``/foo|(?i:bar)/`` will
     match "foo" and "BaR", but *not* "Foo".
 
     For both ways of specifying case-insensitivity, characters enclosed
@@ -545,13 +545,14 @@ Here is a more detailed description of each type:
         |s|
 
     You can compute the union, intersection, or difference of two sets
-    using the ``|``, ``&``, and ``-`` operators.  You can compare
+    using the ``|``, ``&``, and ``-`` operators.
-    sets for equality (they have exactly the same elements) using ``==``.
+
-    The ``<`` operator returns ``T`` if the lefthand operand is a proper
+    You can compare sets for equality (they have exactly the same elements)
-    subset of the righthand operand.  Similarly, ``<=`` returns ``T``
+    using ``==``.  The ``<`` operator returns ``T`` if the lefthand operand
-    if the lefthand operator is a subset (not necessarily proper, i.e.,
+    is a proper subset of the righthand operand.  Similarly, ``<=``
-    it may be equal to the righthand operand).  The operators ``!=``, ``>``
+    returns ``T`` if the lefthand operator is a subset (not necessarily proper,
-    and ``>=`` provide the expected complementary operations.
+    i.e., it may be equal to the righthand operand).  The operators ``!=``,
+    ``>`` and ``>=`` provide the expected complementary operations.
 
     See the :bro:keyword:`for` statement for info on how to iterate over
     the elements in a set.
@@ -601,8 +602,9 @@ Here is a more detailed description of each type:
 
         v[3] = "four";
 
-    The number of elements in a vector can be obtained by placing the vector
+    The size of a vector (this is one greater than the highest index value, and
-    identifier between vertical pipe characters:
+    is normally equal to the number of elements in the vector) can be obtained
+    by placing the vector identifier between vertical pipe characters:
 
     .. code:: bro
 
@@ -622,6 +624,11 @@ Here is a more detailed description of each type:
 
         v[|v|] = e;
 
+    The "in" operator can be used to check if a value has been assigned at a
+    specified index value in the vector.  For example, if a vector has size 4,
+    then the expression ``3 in v`` would yield true and ``4 in v`` would yield
+    false.
+
     Vectors of integral types (``int`` or ``count``) support the pre-increment
     (``++``) and pre-decrement operators (``--``), which will increment or
     decrement each element in the vector.

scripts/base/frameworks/config/input.bro

@@ -60,8 +60,8 @@ event InputConfig::new_value(name: string, source: string, id: string, value: an
 
 function read_config(filename: string)
 	{
-	# Only read the configuration on the manager. The other nodes are being fed from
+	# Only read the configuration on the manager. The other nodes are being fed
-	# the manager.
+	# from the manager.
 	if ( Cluster::is_enabled() && Cluster::local_node_type() != Cluster::MANAGER )
 		return;
 

scripts/base/frameworks/config/main.bro

@@ -28,15 +28,15 @@ export {
 	## record as it is sent on to the logging framework.
 	global log_config: event(rec: Info);
 
-	## Broker topic for announcing new configuration value. Sending new_value,
+	## Broker topic for announcing new configuration values. Sending new_value,
-	## peers can send configuration changes that will be distributed accross
+	## peers can send configuration changes that will be distributed across
 	## the entire cluster.
 	const change_topic = "bro/config/change";
 
 	## This function is the config framework layer around the lower-level
 	## :bro:see:`Option::set` call. Config::set_value will set the configuration
 	## value for all nodes in the cluster, no matter where it was called. Note
-	## that `bro:see:`Option::set` does not distribute configuration changes
+	## that :bro:see:`Option::set` does not distribute configuration changes
 	## to other nodes.
 	##
 	## ID: The ID of the option to update.
@@ -45,7 +45,7 @@ export {
 	##
 	## location: Optional parameter detailing where this change originated from.
 	##
-	## Returns: true on success, false when an error ocured.
+	## Returns: true on success, false when an error occurs.
 	global set_value: function(ID: string, val: any, location: string &default = "" &optional): bool;
 }
 
@@ -73,7 +73,7 @@ event Config::cluster_set_option(ID: string, val: any, location: string)
 function set_value(ID: string, val: any, location: string &default = "" &optional): bool
 	{
 	local cache_val: any;
-	# first cache value in case setting it succeeds and we have to store it.
+	# First cache value in case setting it succeeds and we have to store it.
 	if ( Cluster::local_node_type() == Cluster::MANAGER )
 		cache_val = copy(val);
 	# First try setting it locally - abort if not possible.
@@ -151,8 +151,8 @@ event bro_init() &priority=10
 
 	# Limit logging to the manager - everyone else just feeds off it.
 @if ( !Cluster::is_enabled() || Cluster::local_node_type() == Cluster::MANAGER )
-	# Iterate over all existing options and add ourselves as change handlers with
+	# Iterate over all existing options and add ourselves as change handlers
-	# a low priority so that we can log the changes.
+	# with a low priority so that we can log the changes.
 	local gids = global_ids();
 	for ( i in gids )
 		{

scripts/base/frameworks/notice/actions/add-geodata.bro

@@ -19,7 +19,7 @@ export {
 	};
 	
 	redef record Info += {
-		## If libGeoIP support is built in, notices can have geographic
+		## If GeoIP support is built in, notices can have geographic
 		## information attached to them.
 		remote_location: geo_location  &log &optional;
 	};

scripts/base/utils/geoip-distance.bro

@@ -1,7 +1,7 @@
 ##! Functions to calculate distance between two locations, based on GeoIP data.
 
 ## Returns the distance between two IP addresses using the haversine formula,
-## based on GeoIP database locations.  Requires Bro to be built with libgeoip.
+## based on GeoIP database locations.  Requires Bro to be built with GeoIP.
 ##
 ## a1: First IP address.
 ##

scripts/policy/protocols/smtp/detect-suspicious-orig.bro

@@ -10,7 +10,7 @@ export {
 
 	## Places where it's suspicious for mail to originate from represented
 	## as all-capital, two character country codes (e.g., US).  It requires
-	## libGeoIP support built in.
+	## Bro to be built with GeoIP support.
 	const suspicious_origination_countries: set[string] = {} &redef;
 	const suspicious_origination_networks: set[subnet] = {} &redef;
 

scripts/site/local.bro

@@ -66,7 +66,7 @@
 # certificate notary service; see http://notary.icsi.berkeley.edu .
 # @load protocols/ssl/notary
 
-# If you have libGeoIP support built in, do some geographic detections and
+# If you have GeoIP support built in, do some geographic detections and
 # logging for SSH traffic.
 @load protocols/ssh/geo-data
 # Detect hosts doing SSH bruteforce attacks.