mirror of
https://github.com/zeek/zeek.git
synced 2025-10-02 14:48:21 +00:00
5c9a7a92a4
Added new sections on operators, statements, and directives. Also improved the documentation on types and attributes by providing more examples and added a chart on the top of each page with links to each type and attribute for easier access to the information.
232 lines
9.7 KiB
ReStructuredText
232 lines
9.7 KiB
ReStructuredText
Attributes
|
|
==========
|
|
|
|
The Bro scripting language supports the following attributes.
|
|
|
|
+-----------------------------+-----------------------------------------------+
|
|
| Name | Description |
|
|
+=============================+===============================================+
|
|
| :bro:attr:`&redef` |Redefine a global constant or extend a type. |
|
|
+-----------------------------+-----------------------------------------------+
|
|
| :bro:attr:`&priority` |Specify priority for event handler or hook. |
|
|
+-----------------------------+-----------------------------------------------+
|
|
| :bro:attr:`&log` |Mark a record field to be written to a log. |
|
|
+-----------------------------+-----------------------------------------------+
|
|
| :bro:attr:`&optional` |Allow a record field value to be missing. |
|
|
+-----------------------------+-----------------------------------------------+
|
|
| :bro:attr:`&default` |Specifies a default value. |
|
|
+-----------------------------+-----------------------------------------------+
|
|
| :bro:attr:`&add_func` |Specify a function to call for each "redef +=".|
|
|
+-----------------------------+-----------------------------------------------+
|
|
| :bro:attr:`&delete_func` |Same as "&add_func", except for "redef -=". |
|
|
+-----------------------------+-----------------------------------------------+
|
|
| :bro:attr:`&expire_func` |Specify a function to call when container |
|
|
| |element expires. |
|
|
+-----------------------------+-----------------------------------------------+
|
|
| :bro:attr:`&read_expire` |Specify a read timeout interval. |
|
|
+-----------------------------+-----------------------------------------------+
|
|
| :bro:attr:`&write_expire` |Specify a write timeout interval. |
|
|
+-----------------------------+-----------------------------------------------+
|
|
| :bro:attr:`&create_expire` |Specify a creation timeout interval. |
|
|
+-----------------------------+-----------------------------------------------+
|
|
| :bro:attr:`&synchronized` |Synchronize a variable across nodes. |
|
|
+-----------------------------+-----------------------------------------------+
|
|
| :bro:attr:`&persistent` |Make a variable persistent (written to disk). |
|
|
+-----------------------------+-----------------------------------------------+
|
|
| :bro:attr:`&rotate_interval`|Rotate a file after specified interval. |
|
|
+-----------------------------+-----------------------------------------------+
|
|
| :bro:attr:`&rotate_size` |Rotate a file after specified file size. |
|
|
+-----------------------------+-----------------------------------------------+
|
|
| :bro:attr:`&encrypt` |Encrypt a file when writing to disk. |
|
|
+-----------------------------+-----------------------------------------------+
|
|
| :bro:attr:`&raw_output` |Open file in raw mode (chars. are not escaped).|
|
|
+-----------------------------+-----------------------------------------------+
|
|
| :bro:attr:`&mergeable` |Prefer set union for synchronized state. |
|
|
+-----------------------------+-----------------------------------------------+
|
|
| :bro:attr:`&group` |Group event handlers to activate/deactivate. |
|
|
+-----------------------------+-----------------------------------------------+
|
|
| :bro:attr:`&error_handler` |Used internally for reporter framework events. |
|
|
+-----------------------------+-----------------------------------------------+
|
|
| :bro:attr:`&type_column` |Used by input framework for "port" type. |
|
|
+-----------------------------+-----------------------------------------------+
|
|
|
|
Here is a more detailed explanation of each attribute:
|
|
|
|
.. bro:attr:: &redef
|
|
|
|
Allows for redefinition of initial values of global objects declared as
|
|
constant.
|
|
|
|
In this example, the constant (assuming it is global) can be redefined
|
|
with a :bro:keyword:`redef` at some later point::
|
|
|
|
const clever = T &redef;
|
|
|
|
.. bro:attr:: &priority
|
|
|
|
Specifies the execution priority (as a signed integer) of a hook or
|
|
event handler. Higher values are executed before lower ones. The
|
|
default value is 0. Example::
|
|
|
|
event bro_init() &priority=10
|
|
{
|
|
print "high priority";
|
|
}
|
|
|
|
.. bro:attr:: &log
|
|
|
|
Writes a :bro:type:`record` field to the associated log stream.
|
|
|
|
.. bro:attr:: &optional
|
|
|
|
Allows a record field value to be missing (i.e., neither initialized nor
|
|
ever assigned a value).
|
|
|
|
In this example, the record could be instantiated with either
|
|
"myrec($a=127.0.0.1)" or "myrec($a=127.0.0.1, $b=80/tcp)"::
|
|
|
|
type myrec: record { a: addr; b: port &optional; };
|
|
|
|
The ``?$`` operator can be used to check if a record field has a value or
|
|
not (it returns a ``bool`` value of ``T`` if the field has a value,
|
|
and ``F`` if not).
|
|
|
|
.. bro:attr:: &default
|
|
|
|
Specifies a default value for a record field, container element, or a
|
|
function/hook/event parameter.
|
|
|
|
In this example, the record could be instantiated with either
|
|
"myrec($a=5, $c=3.14)" or "myrec($a=5, $b=53/udp, $c=3.14)"::
|
|
|
|
type myrec: record { a: count; b: port &default=80/tcp; c: double; };
|
|
|
|
In this example, the table will return the string ``"foo"`` for any
|
|
attempted access to a non-existing index::
|
|
|
|
global mytable: table[count] of string &default="foo";
|
|
|
|
When used with function/hook/event parameters, all of the parameters
|
|
with the "&default" attribute must come after all other parameters.
|
|
For example, the following function could be called either as "myfunc(5)"
|
|
or as "myfunc(5, 53/udp)"::
|
|
|
|
function myfunc(a: count, b: port &default=80/tcp)
|
|
{
|
|
print a, b;
|
|
}
|
|
|
|
.. bro:attr:: &add_func
|
|
|
|
Can be applied to an identifier with &redef to specify a function to
|
|
be called any time a "redef <id> += ..." declaration is parsed. The
|
|
function takes two arguments of the same type as the identifier, the first
|
|
being the old value of the variable and the second being the new
|
|
value given after the "+=" operator in the "redef" declaration. The
|
|
return value of the function will be the actual new value of the
|
|
variable after the "redef" declaration is parsed.
|
|
|
|
.. bro:attr:: &delete_func
|
|
|
|
Same as :bro:attr:`&add_func`, except for :bro:keyword:`redef` declarations
|
|
that use the "-=" operator.
|
|
|
|
.. bro:attr:: &expire_func
|
|
|
|
Called right before a container element expires. The function's
|
|
first parameter is of the same type of the container and the second
|
|
parameter the same type of the container's index. The return
|
|
value is an :bro:type:`interval` indicating the amount of additional
|
|
time to wait before expiring the container element at the given
|
|
index (which will trigger another execution of this function).
|
|
|
|
.. bro:attr:: &read_expire
|
|
|
|
Specifies a read expiration timeout for container elements. That is,
|
|
the element expires after the given amount of time since the last
|
|
time it has been read. Note that a write also counts as a read.
|
|
|
|
.. bro:attr:: &write_expire
|
|
|
|
Specifies a write expiration timeout for container elements. That
|
|
is, the element expires after the given amount of time since the
|
|
last time it has been written.
|
|
|
|
.. bro:attr:: &create_expire
|
|
|
|
Specifies a creation expiration timeout for container elements. That
|
|
is, the element expires after the given amount of time since it has
|
|
been inserted into the container, regardless of any reads or writes.
|
|
|
|
.. bro:attr:: &synchronized
|
|
|
|
Synchronizes variable accesses across nodes. The value of a
|
|
``&synchronized`` variable is automatically propagated to all peers
|
|
when it changes.
|
|
|
|
.. bro:attr:: &persistent
|
|
|
|
Makes a variable persistent, i.e., its value is written to disk (per
|
|
default at shutdown time).
|
|
|
|
.. bro:attr:: &rotate_interval
|
|
|
|
Rotates a file after a specified interval.
|
|
|
|
.. bro:attr:: &rotate_size
|
|
|
|
Rotates a file after it has reached a given size in bytes.
|
|
|
|
.. bro:attr:: &encrypt
|
|
|
|
Encrypts files right before writing them to disk.
|
|
|
|
.. bro:attr:: &raw_output
|
|
|
|
Opens a file in raw mode, i.e., non-ASCII characters are not
|
|
escaped.
|
|
|
|
.. bro:attr:: &mergeable
|
|
|
|
Prefers set union to assignment for synchronized state. This
|
|
attribute is used in conjunction with :bro:attr:`&synchronized`
|
|
container types: when the same container is updated at two peers
|
|
with different value, the propagation of the state causes a race
|
|
condition, where the last update succeeds. This can cause
|
|
inconsistencies and can be avoided by unifying the two sets, rather
|
|
than merely overwriting the old value.
|
|
|
|
.. bro:attr:: &group
|
|
|
|
Groups event handlers such that those in the same group can be
|
|
jointly activated or deactivated.
|
|
|
|
.. bro:attr:: &error_handler
|
|
|
|
Internally set on the events that are associated with the reporter
|
|
framework: :bro:id:`reporter_info`, :bro:id:`reporter_warning`, and
|
|
:bro:id:`reporter_error`. It prevents any handlers of those events
|
|
from being able to generate reporter messages that go through any of
|
|
those events (i.e., it prevents an infinite event recursion). Instead,
|
|
such nested reporter messages are output to stderr.
|
|
|
|
.. bro:attr:: &type_column
|
|
|
|
Used by the input framework. It can be used on columns of type
|
|
:bro:type:`port` (such a column only contains the port number) and
|
|
specifies the name of an additional column in
|
|
the input file which specifies the protocol of the port (tcp/udp/icmp).
|
|
|
|
In the following example, the input file would contain four columns
|
|
named "ip", "srcp", "proto", and "msg"::
|
|
|
|
type Idx: record {
|
|
ip: addr;
|
|
};
|
|
|
|
|
|
type Val: record {
|
|
srcp: port &type_column = "proto";
|
|
msg: string;
|
|
};
|
|
|