diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 10524f131..19d5c236e 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -7,3 +7,11 @@ repos: - id: ruff-format - id: ruff args: [--fix] + +- repo: https://github.com/pre-commit/pygrep-hooks + rev: v1.10.0 + hooks: + - id: rst-directive-colons + stages: ["pre-commit"] + - id: rst-backticks + stages: ["pre-commit"] diff --git a/cluster-setup.rst b/cluster-setup.rst index 4adcaf7a8..46beab8e1 100644 --- a/cluster-setup.rst +++ b/cluster-setup.rst @@ -177,7 +177,7 @@ Offloading and ethtool tuning While not specific to AF_PACKET, it is recommended to disable any offloading features provided by the network card or Linux networking stack when running Zeek. This allows to see network packets as they arrive on the wire. -See this `blog post _ +See this `blog post `_ for more background Toggling these features can be done with the ``ethtool -K`` command, for example:: @@ -600,4 +600,3 @@ same packets multiple times with different tools. This issue has been fixed in all stable kernels for at least 5 years. You're unlikely to be affected. - diff --git a/customizations.rst b/customizations.rst index 71e26f103..fc6b15e82 100644 --- a/customizations.rst +++ b/customizations.rst @@ -286,14 +286,14 @@ package helps you with that. Long Connections ---------------- -Zeek logs connection entries into the ``conn.log`` only upon termination +Zeek logs connection entries into the :file:`conn.log` only upon termination or due to expiration of inactivity timeouts. Depending on the protocol and chosen timeout values this can significantly delay the appearance of a log entry for a given connection. The delay may be up to an hour for lingering SSH connections or connections where the final FIN or RST packets were missed. -The `zeek-long-connections`_ package alleviates this by creating a ``conn_long.log`` -log with the same format as ``conn.log``, but containing entries for connections +The `zeek-long-connections`_ package alleviates this by creating a :file:`conn_long.log` +log with the same format as :file:`conn.log`, but containing entries for connections that have been existing for configurable intervals. By default, the first entry for a connection is logged after 10mins. Depending on the environment, this can be lowered as even a 10 minute delay may be significant diff --git a/devel/plugins.rst b/devel/plugins.rst index b7395ed62..91b36d26f 100644 --- a/devel/plugins.rst +++ b/devel/plugins.rst @@ -449,7 +449,7 @@ If your plugin isn't loading as expected, Zeek's debugging facilities can help illuminate what's going on. To enable, recompile Zeek with debugging support (``./configure --enable-debug``), and afterwards rebuild your plugin as well. If you then run Zeek with ``-B -plugins``, it will produce a file ``debug.log`` that records details +plugins``, it will produce a file :file:`debug.log` that records details about the process for searching, loading, and activating plugins. To generate your own debugging output from inside your plugin, you can @@ -463,7 +463,7 @@ your plugin's debugging output with ``-B plugin-``, where ``Configure()`` method, yet with the namespace-separator ``::`` replaced with a simple dash. Example: If the plugin is called ``Demo::Rot13``, use ``-B plugin-Demo-Rot13``. As usual, the debugging -output will be recorded to ``debug.log`` if Zeek's compiled in debug +output will be recorded to :file:`debug.log` if Zeek's compiled in debug mode. Building Plugins Statically diff --git a/devel/spicy/autogen/init-bare.zeek b/devel/spicy/autogen/init-bare.zeek index a9f9d2dbd..b844dab08 100644 --- a/devel/spicy/autogen/init-bare.zeek +++ b/devel/spicy/autogen/init-bare.zeek @@ -23,7 +23,7 @@ export { # doc-options-end # doc-types-start - ## Result type for `Spicy::resource_usage()`. The values reflect resource + ## Result type for ``Spicy::resource_usage()``. The values reflect resource ## usage as reported by the Spicy runtime system. type ResourceUsage: record { user_time : interval; ##< user CPU time of the Zeek process diff --git a/devel/spicy/reference.rst b/devel/spicy/reference.rst index bc18629bb..5977b9999 100644 --- a/devel/spicy/reference.rst +++ b/devel/spicy/reference.rst @@ -305,7 +305,7 @@ File analyzers support the following properties: "content sniffing" (i.e., similar to libmagic), and usually not by protocol-level headers (e.g., *not* through HTTP's ``Content-Type`` header). If in doubt, examine - ``files.log`` for what it records as a file's type. + :file:`files.log` for what it records as a file's type. ``replaces ANALYZER_NAME`` Disables an existing file analyzer that Zeek already provides @@ -942,7 +942,7 @@ membership in a ``set`` like this: .. code-block:: zeek - # Zeek module `MyModule` + # Zeek module MyModule option my_set: set[count] = { 1, 2, 3 }; .. code-block:: spicy @@ -958,7 +958,7 @@ functions for conversion. Example accessing a record's field: .. code-block:: zeek - # Zeek module `MyModule` + # Zeek module MyModule option my_record: record { a: count &default = 42; b: string &default = "foo"; @@ -1103,7 +1103,7 @@ see what it's doing at runtime. You'll need a debug version of Zeek for that, as well as a small trace with traffic that you expect your analyzer to process. Run Zeek with ``-B dpd`` (or ``-B file_analysis`` if you're debugging a file analyzer) on your trace to record the -analyzer activity into ``debug.log``. For example, with the same HTTP +analyzer activity into :file:`debug.log`. For example, with the same HTTP example, we get: .. code-block:: text @@ -1189,4 +1189,3 @@ their full Zeek-side values:: [2] uri: string = /index.html [3] version: string = 1.0 [...] - diff --git a/devel/spicy/tutorial.rst b/devel/spicy/tutorial.rst index abb6ffa5f..a1905c452 100644 --- a/devel/spicy/tutorial.rst +++ b/devel/spicy/tutorial.rst @@ -208,7 +208,7 @@ the corresponding value of ``is_read``. Let's try it with a new # zeek -r tftp_rrq.pcap tftp.hlto tftp.zeek TFTP read request, [orig_h=192.168.0.253, orig_p=50618/udp, resp_h=192.168.0.10, resp_p=69/udp], T, rfc1350.txt, octet -If we look at the ``conn.log`` that Zeek produces during this run, we +If we look at the :file:`conn.log` that Zeek produces during this run, we will see that the ``service`` field is not filled in yet. That's because our analyzer does not yet confirm to Zeek that it has been successful in parsing the content. To do that, we can call a library @@ -333,7 +333,7 @@ analyzers' events, and collect and correlate their activity as desired. We have created such :download:`a script for TFTP `, based on the events that our Spicy analyzer generates. Once we add that to the Zeek command line, we will see a -new ``tftp.log``: +new :file:`tftp.log`: .. code:: @@ -346,7 +346,7 @@ new ``tftp.log``: The TFTP script also labels the second session as TFTP data by adding a corresponding entry to the ``service`` field inside the Zeek-side connection record. With that, we are now seeing this in -``conn.log``: +:file:`conn.log`: .. code:: diff --git a/ext/spicy-pygments.py b/ext/spicy-pygments.py index 9822c4737..adb101483 100644 --- a/ext/spicy-pygments.py +++ b/ext/spicy-pygments.py @@ -1,4 +1,4 @@ -# Copyright (c) 2020-2023 by the Zeek Project. See LICENSE for details. +# Copyright (c) 2020-now by the Zeek Project. See LICENSE for details. from pygments.lexer import RegexLexer, bygroups, include, words from pygments.token import ( diff --git a/frameworks/file-analysis.rst b/frameworks/file-analysis.rst index 30331bc96..323dcb958 100644 --- a/frameworks/file-analysis.rst +++ b/frameworks/file-analysis.rst @@ -84,12 +84,12 @@ File Type Identification Zeek ships with its own library of content signatures to determine the type of a file, conveyed as MIME types in the :zeek:see:`file_sniff` event. You can find those signatures in the Zeek distribution's ``scripts/base/frameworks/files/magic/`` -directory. (Despite the name, Zeek does `not` rely on libmagic for content analysis.) +directory. (Despite the name, Zeek does *not* rely on libmagic for content analysis.) Adding Analysis =============== -Zeek supports customized file analysis via `file analyzers` that users can +Zeek supports customized file analysis via *file analyzers* that users can attach to observed files. You can attach analyzers selectively to individual files, or register them for auto-attachment under certain conditions. Once attached, file analyzers start receiving the contents of files as Zeek parses @@ -139,7 +139,7 @@ for additional APIs and data structures. Regardless of which file analyzers end up acting on a file, general information about the file (e.g. size, time of last data transferred, -MIME type, etc.) is logged in ``files.log``. +MIME type, etc.) is logged in :file:`files.log`. Protocol-specific state ----------------------- @@ -207,8 +207,8 @@ customized analysis. Since observed files can be very large, Zeek cannot buffer these files and provide their entire content to the script layer once complete. Instead, the ``FileDataEvent`` analyzer reflects the incremental nature of file content as Zeek observes it, and supports two types of events to -allow you to process it: user-provided `stream events` receive new file content -as supplied by connection-oriented protocols, while `chunk events` receive +allow you to process it: user-provided *stream events* receive new file content +as supplied by connection-oriented protocols, while *chunk events* receive observed data as provided by protocols that do not feature stream semantics. The following example manually computes the SHA256 hash of each observed file by diff --git a/frameworks/input.rst b/frameworks/input.rst index 0ae2b630a..1eeaa6197 100644 --- a/frameworks/input.rst +++ b/frameworks/input.rst @@ -318,7 +318,7 @@ Broken input data ----------------- The input framework notifies you of problems during data ingestion in two ways. -First, reporter messages, ending up in reporter.log, indicate the type of +First, reporter messages, ending up in :file:`reporter.log`, indicate the type of problem and the file in which the problem occurred:: #fields ts level message location diff --git a/frameworks/logging.rst b/frameworks/logging.rst index f25383fdc..d9d0b92c9 100644 --- a/frameworks/logging.rst +++ b/frameworks/logging.rst @@ -261,7 +261,7 @@ Disable a Stream ---------------- One way to “turn off” a log is to completely disable the stream. For example, -the following example will prevent the conn.log from being written: +the following example will prevent the :file:`conn.log` from being written: .. code-block:: zeek diff --git a/frameworks/management.rst b/frameworks/management.rst index 62082302e..b66368adc 100644 --- a/frameworks/management.rst +++ b/frameworks/management.rst @@ -764,7 +764,7 @@ Retrieving configurations ------------------------- The client's ``get-config`` command lets you retrieve staged and deployed -configurations from the controller, in JSON or `.ini` form. This is helpful for +configurations from the controller, in JSON or :file:`.ini` form. This is helpful for examining the differences between the two. Following the successful deployment shown above, we have: diff --git a/frameworks/netcontrol.rst b/frameworks/netcontrol.rst index 549693551..a40cb408e 100644 --- a/frameworks/netcontrol.rst +++ b/frameworks/netcontrol.rst @@ -141,7 +141,7 @@ sees being established: Running this script on a file containing one connection will cause the debug plugin to print one line to the standard output, which contains information -about the rule that was added. It will also cause creation of `netcontrol.log`, +about the rule that was added. It will also cause creation of :file:`netcontrol.log`, which contains information about all actions that are taken by NetControl: .. code-block:: console @@ -166,7 +166,7 @@ which contains information about all actions that are taken by NetControl: 1398529018.678276 2 NetControl::RULE ADD NetControl::SUCCEEDED NetControl::DROP NetControl::FORWARD NetControl::CONNECTION 192.168.18.50/56981<->74.125.239.97/443 - - 0 20.000000 - Debug-All #close 2018-12-14-18-50-53 -In our case, `netcontrol.log` contains several :zeek:see:`NetControl::MESSAGE` +In our case, :file:`netcontrol.log` contains several :zeek:see:`NetControl::MESSAGE` entries, which show that the debug plugin has been initialized and added. Afterwards, there are two :zeek:see:`NetControl::RULE` entries; the first shows that the addition of a rule has been requested (state is @@ -175,8 +175,8 @@ successfully added (the state is :zeek:see:`NetControl::SUCCEEDED`). The remainder of the log line gives more information about the added rule, which in our case applies to a specific 5-tuple. -In addition to the netcontrol.log, the drop commands also create a second, -additional log called `netcontrol_drop.log`. This log file is much more succinct and +In addition to the :file:`netcontrol.log`, the drop commands also create a second, +additional log called :file:`netcontrol_drop.log`. This log file is much more succinct and only contains information that is specific to drops that are enacted by NetControl: @@ -259,7 +259,7 @@ the :zeek:see:`Notice::ACTION_DROP` action of the notice framework: #close 2018-12-14-18-50-55 Using the :zeek:see:`Notice::ACTION_DROP` action of the notice framework also -will cause the `dropped` column in `notice.log` to be set to true each time that +will cause the ``dropped`` column in :file:`notice.log` to be set to true each time that the NetControl framework enacts a block: .. code-block:: console @@ -540,7 +540,7 @@ for 10 minutes and monitored for 1 hour. If the address reappears after the first 10 minutes, it is blocked for 1 hour and then monitored for 24 hours, etc. Catch and release adds its own new logfile in addition to the already existing -ones (netcontrol_catch_release.log): +ones (:file:`netcontrol_catch_release.log`): .. code-block:: console @@ -631,7 +631,7 @@ use the plugin, we first had to instantiate it by calling calling :zeek:see:`NetControl::activate`. As we already hinted before, NetControl supports having several plugins that are -active at the same time. The second argument to the `NetControl::activate` +active at the same time. The second argument to the :zeek:see:`NetControl::activate` function is the priority of the backend that was just added. Each rule is sent to all plugins in order, from highest priority to lowest priority. The backend can then choose if it accepts the rule and pushes it out to the hardware that it @@ -646,7 +646,7 @@ network with two OpenFlow switches. The first switch forwards packets from the network to the external world, the second switch sits in front of your Zeek cluster to provide packet shunting. In this case, you can add two OpenFlow backends to NetControl. When you create the instances using -:zeek:see:`NetControl::create_openflow`, you set the `monitor` and `forward` +:zeek:see:`NetControl::create_openflow`, you set the ``monitor`` and ``forward`` attributes of the configuration in :zeek:see:`NetControl::OfConfig` appropriately. Afterwards, one of the backends will only accept rules for the monitor path; the other backend will only accept rules for the forward path. @@ -660,7 +660,7 @@ rule if the rule matches the subnet that the specific switch is responsible for. To give an example, the following script adds two backends to NetControl. One backend is the NetControl debug backend, which just outputs the rules to the console. The second backend is an OpenFlow backend, which uses the OpenFlow -debug mode that outputs the openflow rules to openflow.log. The OpenFlow +debug mode that outputs the openflow rules to :file:`openflow.log`. The OpenFlow backend uses a predicate function to only accept rules with a source address in the 192.168.17.0/24 network; all other rules will be passed on to the debug plugin. We manually block a few addresses in the @@ -680,7 +680,7 @@ plugin. We manually block a few addresses in the As you can see, only the single block affecting the 192.168.17.0/24 network is output to the command line. The other two lines are handled by the OpenFlow -plugin. We can verify this by looking at netcontrol.log. The plugin column shows +plugin. We can verify this by looking at :file:`netcontrol.log`. The plugin column shows which plugin handled a rule and reveals that two rules were handled by OpenFlow: .. code-block:: console @@ -707,7 +707,7 @@ which plugin handled a rule and reveals that two rules were handled by OpenFlow: 1544813458.913148 4 NetControl::RULE ADD NetControl::SUCCEEDED NetControl::DROP NetControl::FORWARD NetControl::ADDRESS 192.168.18.2/32 - - 0 60.000000 - Openflow-Log-42 #close 2018-12-14-18-50-58 -Furthermore, openflow.log also shows the two added rules, converted to OpenFlow +Furthermore, :file:`openflow.log` also shows the two added rules, converted to OpenFlow flow mods: .. code-block:: console @@ -758,13 +758,13 @@ communicate with the Switch. NetControl and OpenFlow architecture (click to enlarge). The Python scripts that are used to interface with the available NetControl -plugins are contained in the `zeek-netcontrol` repository (`github link `_). +plugins are contained in the ``zeek-netcontrol`` repository (`github link `_). The repository contains scripts for the OpenFlow as well as the acld plugin. Furthermore, it contains a script for the broker plugin which can be used to call configurable command-line programs when used with the broker plugin. The repository also contains documentation on how to install these connectors. -The `netcontrol` directory contains an API that allows you to write your own +The ``netcontrol`` directory contains an API that allows you to write your own connectors to the broker plugin. Writing plugins diff --git a/frameworks/notice.rst b/frameworks/notice.rst index 3f0545c9f..4cef1496a 100644 --- a/frameworks/notice.rst +++ b/frameworks/notice.rst @@ -359,7 +359,7 @@ Configuring Notice Emails If :zeek:see:`Notice::mail_dest` is set, notices with an associated e-mail action will be sent to that address. For additional customization, users can use the :zeek:see:`Notice::policy` hook to -modify the `email_dest` field. The following example would result in 3 +modify the ``email_dest`` field. The following example would result in three separate e-mails: .. code-block:: zeek @@ -375,7 +375,7 @@ separate e-mails: You can also use :zeek:see:`Notice::policy` hooks to add extra information to emails. The :zeek:see:`Notice::Info` record contains a vector of strings named -`$email_body_sections` which Zeek will include verbatim when sending email. +``email_body_sections`` which Zeek will include verbatim when sending email. An example of including some information from an HTTP request is included below. .. code-block:: zeek diff --git a/frameworks/signatures.rst b/frameworks/signatures.rst index c51c0e5b4..c1dc8dbd1 100644 --- a/frameworks/signatures.rst +++ b/frameworks/signatures.rst @@ -331,7 +331,7 @@ two actions defined, ``event`` and ``enable``. .. note:: Matches for signatures that use custom events do not appear - in ``signatures.log``. + in :file:`signatures.log`. ``enable `` @@ -484,4 +484,3 @@ the two systems are just too different. We therefore stopped maintaining the ``snort2bro`` script, and there are now many newer Snort options which it doesn't support. The script is now no longer part of the Zeek distribution. - diff --git a/frameworks/telemetry.rst b/frameworks/telemetry.rst index b9cdc46b3..e3d40de40 100644 --- a/frameworks/telemetry.rst +++ b/frameworks/telemetry.rst @@ -87,7 +87,7 @@ centralize, or aggregate metrics across the cluster. Instead, it adds the name of the node a particular metric originated from at collection time, leaving any aggregation to post-processing where desired. -.. note: +.. note:: This is a departure from the design in earlier versions of Zeek, which could (either by default, or after activation) centralize metrics in the cluster's @@ -107,8 +107,8 @@ them in turn. Zeek Logs --------- -Zeek can export current metrics continuously via `telemetry.log` and -`telemetry_histogram.log`. It does not do so by default. To enable, load the +Zeek can export current metrics continuously via :file:`telemetry.log` and +:file:`telemetry_histogram.log`. It does not do so by default. To enable, load the policy script ``frameworks/telemetry/log`` on the command line, or via ``local.zeek``. @@ -119,7 +119,7 @@ cluster node the metric originated from. By default, Zeek reports current telemetry every 60 seconds, as defined by the :zeek:see:`Telemetry::log_interval`, which you're free to adjust. -Also, by default only metrics with the `prefix` (namespace) ``zeek`` and +Also, by default only metrics with the ``prefix`` (namespace) ``zeek`` and ``process`` are included in above logs. If you add new metrics with your own prefix and expect these to be included, redefine the :zeek:see:`Telemetry::log_prefixes` option:: @@ -404,7 +404,7 @@ representation becomes rather verbose. To work with histogram data, Prometheus provides specialized query functions. For example `histogram_quantile()`_. -Note, when using data from `conn.log` and post-processing, a proper +Note, when using data from :file:`conn.log` and post-processing, a proper histogram of connection durations can be calculated and possibly preferred. The above example is meant for demonstration purposes. Histograms may be primarily be useful for Zeek operational metrics such as processing times diff --git a/frameworks/tls-decryption.rst b/frameworks/tls-decryption.rst index 1f6004504..29e37ffcf 100644 --- a/frameworks/tls-decryption.rst +++ b/frameworks/tls-decryption.rst @@ -70,14 +70,14 @@ will perform the conversion: echo "Script expects one argument (key log filename)" >/dev/stderr exit -1 fi - + FILE=$1 - + if [ ! -f ${FILE} ]; then echo "${FILE} does not exist or is not readable" >/dev/stderr exit -1 fi - + echo "#fields client_random secret" grep CLIENT_RANDOM ${FILE} | sed 's/^CLIENT_RANDOM ........\(.*\) \(.*\)$/\1 \2/' | sed 's/[A-Za-z0-9][A-Za-z0-9]/\\x&/g' @@ -123,7 +123,7 @@ stops processing while the TLS keylog file is loaded. It also loads the required #types time string addr port addr port enum string interval count count string bool bool count string count count count count set[string] 1646150638.631834 CTy5Us4OUaTOcyrPvc 192.168.20.12 60679 193.99.144.85 443 tcp http,ssl 7.246461 10853 151695 SF - - 0 ShADadFf 98 15961 139 158931 - #close 2022-03-01-16-57-26 - + $ cat http.log #separator \x09 #set_separator , @@ -138,7 +138,7 @@ stops processing while the TLS keylog file is loaded. It also loads the required 1646150638.976118 CTy5Us4OUaTOcyrPvc 192.168.20.12 60679 193.99.144.85 443 3 GET www.heise.de /assets/heise/hobell/css/hobell.css?.ltc.3746e7e49abafa23b5fb https://www.heise.de/ 1.1 Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:97.0) Gecko/20100101 Firefox/97.0 - 0 85280 200 OK - - (empty) - - - - - - FyvBkl2nwRXf0hkDO1 - text/plain ... -Now ``conn.log`` shows that the HTTP as well as the SSL analyzers were attached. ``http.log`` shows the +Now :file:`conn.log` shows that the HTTP as well as the SSL analyzers were attached. :file:`http.log` shows the information from the decrypted HTTP session. If you try this yourself note that today a lot of encrypted Internet traffic uses HTTP/2. Zeek currently does not diff --git a/install.rst b/install.rst index 1b6580bfd..93a03137e 100644 --- a/install.rst +++ b/install.rst @@ -453,14 +453,14 @@ following: # The CMAKE_STAGING_PREFIX option may not work. # Given that Zeek is configured: # - # `./configure --prefix=` + # ``./configure --prefix=`` # # The options are: # - # (1) `make install` and then copy over the --prefix dir from host to + # (1) ``make install`` and then copy over the --prefix dir from host to # target system. # - # (2) `DESTDIR= make install` and then copy over the + # (2) ``DESTDIR= make install`` and then copy over the # contents of that staging directory. set(toolchain /home/jon/x-tools/arm-rpi-linux-gnueabihf) diff --git a/logs/conn.rst b/logs/conn.rst index 692e5b3e0..6cb995807 100644 --- a/logs/conn.rst +++ b/logs/conn.rst @@ -145,7 +145,7 @@ They spoke the HyperText Transfer Protocol (HTTP), identified by Zeek as HTTP over TCP using TCP port 80 listening on ``31.3.245.133``. If we wanted to move beyond who talked with whom, when, for how long, and with -what protocol, the second conn.log entry offers a few more items of interest. +what protocol, the second :file:`conn.log` entry offers a few more items of interest. For example, we know that ``192.168.4.76`` sent 77 bytes of data in its application layer payload, and 397 bytes in its IP layer payload. @@ -421,7 +421,7 @@ You can adapt this feature in several ways. Load the to add an ``ip_proto_name`` column with a string version of the ``ip_proto`` value. Also, you may disable the whole feature by loading the :doc:`/scripts/policy/protocols/conn/disable-unknown-ip-proto-support.zeek` -script, returning conn.log to its pre-7.1 state. Zeek's :ref:`logging framework +script, returning :file:`conn.log` to its pre-7.1 state. Zeek's :ref:`logging framework ` supports additional customizations. The ``uid`` and Other Fields diff --git a/logs/dhcp.rst b/logs/dhcp.rst index ab92971d7..83f474865 100644 --- a/logs/dhcp.rst +++ b/logs/dhcp.rst @@ -5,7 +5,7 @@ dhcp.log Dynamic Host Configuration Protocol is a core protocol found in Internet Protocol (IP) networks. Using the protocol, DHCP servers provide clients with IP addresses and other key information needed to make use of the network. This -entry will describe some aspects of Zeek’s dhcp.log that may be of use to +entry will describe some aspects of Zeek’s :file:`dhcp.log` that may be of use to network and security personnel. As with all entries in this document, for full explanation of each field in the diff --git a/logs/files.rst b/logs/files.rst index 5abc56ab5..255755eeb 100644 --- a/logs/files.rst +++ b/logs/files.rst @@ -19,7 +19,8 @@ written to disk. In the following example, an analyst has configured Zeek to extract files of MIME type ``application/x-dosexec`` and write them to disk. To understand the chain of events that result in having a file on disk, we will start with the -conn.log, progress to the :file:`http.log`, and conclude with the :file:`files.log`. +:file:`conn.log`, progress to the :file:`http.log`, and conclude with the +:file:`files.log`. The Zeek scripting manual, derived from the Zeek source code, completely explains the meaning of each field in the :file:`files.log` (and other logs). diff --git a/logs/ftp.rst b/logs/ftp.rst index 5f6801e05..ec4ad6c69 100644 --- a/logs/ftp.rst +++ b/logs/ftp.rst @@ -3,7 +3,7 @@ ftp.log ======= Zeek’s :file:`ftp.log` summarizes activity using the File Transfer Protocol -(FTP). Similar to the http.log, :file:`ftp.log` captures the essential +(FTP). Similar to the :file:`http.log`, :file:`ftp.log` captures the essential information an analyst would likely need to understand how a client and server interact using FTP. @@ -196,8 +196,8 @@ Reading this transcript, some important items include the following: With this understanding in place, let’s see how Zeek represents this activity. -Inspecting the ftp.log -====================== +Inspecting the :file:`ftp.log` +============================== Let’s take a second look at the two :file:`ftp.log` entries. diff --git a/logs/irc.rst b/logs/irc.rst index 20627acb5..56fbe10fa 100644 --- a/logs/irc.rst +++ b/logs/irc.rst @@ -58,8 +58,8 @@ by the IRC client. The server sent the remaining text. :barjavel.freenode.net 265 zeektest 3809 5891 :Current local users 3809, max 5891 :barjavel.freenode.net 266 zeektest 82182 90930 :Current global users 82182, max 90930 :barjavel.freenode.net 250 zeektest :Highest connection count: 5892 (5891 clients) (1543159 connections received) - :barjavel.freenode.net 375 zeektest :- barjavel.freenode.net Message of the Day - - :barjavel.freenode.net 372 zeektest :- Welcome to barjavel.freenode.net in Paris, FR, EU. + :barjavel.freenode.net 375 zeektest :- barjavel.freenode.net Message of the Day - + :barjavel.freenode.net 372 zeektest :- Welcome to barjavel.freenode.net in Paris, FR, EU. ...edited… :barjavel.freenode.net 372 zeektest :- Thank you for using freenode! :barjavel.freenode.net 376 zeektest :End of /MOTD command. @@ -401,7 +401,7 @@ control of the Muhstihk botnet. More details are available in this blog post: https://blog.netlab.360.com/botnet-muhstik-is-actively-exploiting-drupal-cve-2018-7600-in-a-worm-style-en/ -Here is a summary of the conn.log for the malicious IRC traffic. +Here is a summary of the :file:`conn.log` for the malicious IRC traffic. .. code-block:: console diff --git a/logs/known-and-software.rst b/logs/known-and-software.rst index 8d9832f32..f2187f683 100644 --- a/logs/known-and-software.rst +++ b/logs/known-and-software.rst @@ -129,7 +129,7 @@ These examples show an SSH server and two different SSH clients. Conclusion ========== -Details recorded in :file:`known_certs.log`, :file:`known_hosts,log`, +Details recorded in :file:`known_certs.log`, :file:`known_hosts.log`, :file:`known_services.log`, and :file:`software.log` files can help network and security analysts better understand the nature of the activity in their environment. Some of this information relies on capturing clear text, while diff --git a/logs/ldap.rst b/logs/ldap.rst index 889a47fd7..d8e073a76 100644 --- a/logs/ldap.rst +++ b/logs/ldap.rst @@ -41,8 +41,8 @@ For details on every element of the :file:`ldap.log` and :file:`ldap_search.log` refer to :zeek:see:`LDAP::MessageInfo` and :zeek:see:`LDAP::SearchInfo`, respectively. Below is an inspection of the :file:`ldap.log` and :file:`ldap_search.log` in JSON format. -ldap.log -======== +:file:`ldap.log` +================ An example of an :file:`ldap.log`. @@ -69,8 +69,8 @@ An example of an :file:`ldap.log`. } -ldap_search.log -=============== +:file:`ldap_search.log` +======================= An example of an :file:`ldap_search.log`. Note the default for :zeek:see:`LDAP::default_log_search_attributes` is F, excluding attributes diff --git a/logs/postgresql.rst b/logs/postgresql.rst index b91f28dfe..6477c0180 100644 --- a/logs/postgresql.rst +++ b/logs/postgresql.rst @@ -60,7 +60,7 @@ TLS The PostgreSQL protocol provides a mechanism to upgrade client-server connections to TLS. The analyzer detects this mechanism and hands off analysis to Zeek's -TLS analyzer. The ``postgresql.log`` and ``conn.log`` files will look +TLS analyzer. The :file:`postgresql.log` and :file:`conn.log` files will look as follows: .. code-block:: console diff --git a/logs/smb.rst b/logs/smb.rst index 198af0a9a..fe8f379cd 100644 --- a/logs/smb.rst +++ b/logs/smb.rst @@ -1414,7 +1414,7 @@ all 20 entries. The first entry shows a call to the Windows endpoint mapper, ``epmapper``, on port 135 TCP on ``192.168.10.30``. The response from this service directs the client ``192.168.10.31`` to port 49155 TCP on ``192.168.10.30``. The second and -subsequent dce_rpc.log entries involve port 49155 TCP on the target, which is +subsequent :file:`dce_rpc.log` entries involve port 49155 TCP on the target, which is offering ``svcctrl``. We see the target IP address is ``192.168.10.30``, confirming the activity in diff --git a/logs/ssl.rst b/logs/ssl.rst index 540056845..2715087c6 100644 --- a/logs/ssl.rst +++ b/logs/ssl.rst @@ -26,7 +26,7 @@ following command to search hundreds of days of Zeek :file:`ssl.log` entries: .. code-block:: console - $ for i in `find . -name ssl*.log.gz`; do zcat $i; done | jq '[."version"]' | grep -v "\]" | grep -v "\[" | sort -n | uniq -c | sort -rn + $ for i in $(find . -name ssl*.log.gz); do zcat $i; done | jq '[."version"]' | grep -v "\]" | grep -v "\[" | sort -n | uniq -c | sort -rn :: @@ -49,7 +49,7 @@ command to search 10 days of Zeek :file:`ssl.log` entries: .. code-block:: console - $ for i in `find ./2020-08-1* -name ssl*.log.gz`; do zcat $i; done | jq -c '[."version", ."next_protocol"]' | sort -n | uniq -c | sort -rn + $ for i in $(find ./2020-08-1* -name ssl*.log.gz); do zcat $i; done | jq -c '[."version", ."next_protocol"]' | sort -n | uniq -c | sort -rn :: diff --git a/logs/tunnel.rst b/logs/tunnel.rst index 5de6e2070..1c040b242 100644 --- a/logs/tunnel.rst +++ b/logs/tunnel.rst @@ -643,7 +643,7 @@ Zeek creates a single :file:`conn.log` entry for this traffic: ] } -As with the previous example, the only conn.log entry lists the encapsulated +As with the previous example, the only :file:`conn.log` entry lists the encapsulated source and destination IP addresses for the traffic, i.e., ``1.1.1.1`` and ``2.2.2.2``. To see the outer IP addresses, we need to look for the ``tunnel_parents`` connection in the :file:`tunnel.log`. diff --git a/script-reference/attributes.rst b/script-reference/attributes.rst index 742837ca7..afc883ccc 100644 --- a/script-reference/attributes.rst +++ b/script-reference/attributes.rst @@ -582,7 +582,7 @@ table. .. warning:: Storing complex types in Broker backed store comes with severe restrictions. - When you modify a stored complex type after inserting it into a table, that change in a stored complex type + When you modify a stored complex type after inserting it into a table, that change in a stored complex type will *not propagate* to Broker. Hence to send out the new value, so that it will be persisted/synchronized over the cluster, you will have to re-insert the complex type into the local zeek table. @@ -768,10 +768,10 @@ For cases where it's desirable to suppress the warning, the &group ------ -The `&group` attribute can be used on event handlers and hooks to add them +The ``&group`` attribute can be used on event handlers and hooks to add them into event groups. By default, all event groups are enabled. Disabling an event group disables -all event handlers and hooks with a matching `&group` attribute. When an +all event handlers and hooks with a matching ``&group`` attribute. When an event handler or hook is part of multiple groups it is enabled only if all groups are enabled. diff --git a/script-reference/statements.rst b/script-reference/statements.rst index 4c73afdbd..425c64d70 100644 --- a/script-reference/statements.rst +++ b/script-reference/statements.rst @@ -561,7 +561,7 @@ Example: :tab-width: 4 This script prints the following messages to stderr, as well as logging them to -``reporter.log``. +:file:`reporter.log`. .. code-block:: console diff --git a/scripting/basics.rst b/scripting/basics.rst index cc5535101..a21ddae95 100644 --- a/scripting/basics.rst +++ b/scripting/basics.rst @@ -17,7 +17,7 @@ generating events while Zeek's scripting language is the medium through which we mere mortals can achieve communication. Zeek scripts effectively notify Zeek that should there be an event of a type we define, then let us have the information about the connection so we -can perform some function on it. For example, the ``ssl.log`` file is +can perform some function on it. For example, the :file:`ssl.log` file is generated by a Zeek script that walks the entire certificate chain and issues notifications if any of the steps along the certificate chain are invalid. This entire process is setup by telling Zeek that should @@ -488,7 +488,7 @@ called "scriptland" that details are being refined and decisions being made. Were we to continue running in "bare mode" we could slowly keep adding infrastructure through ``@load`` statements. For example, were we to ``@load base/frameworks/logging``, Zeek would generate a -``conn.log`` and ``http.log`` for us in the current working directory. +:file:`conn.log` and :file:`http.log` for us in the current working directory. As mentioned above, including the appropriate ``@load`` statements is not only good practice, but can also help to indicate which functionalities are being used in a script. Take a second to run the @@ -1202,7 +1202,7 @@ composite type. We have, in fact, already encountered a complex example of the ``record`` data type in the earlier sections, the :zeek:type:`connection` record passed to many events. Another one, :zeek:type:`Conn::Info`, which corresponds to the fields logged into -``conn.log``, is shown by the excerpt below. +:file:`conn.log`, is shown by the excerpt below. .. literalinclude:: data_type_record.zeek :caption: @@ -1401,7 +1401,7 @@ formatted ``Factor::Info`` record, a log entry will be generated. Now, if we run this script, instead of generating logging information to stdout, no output is created. Instead the -output is all in ``factor.log``, properly formatted and organized. +output is all in :file:`factor.log`, properly formatted and organized. .. code-block:: console @@ -1451,7 +1451,7 @@ when created, is given a default filter called, not surprisingly, with the ``&log`` attribute is written to a single file. For the example we've been using, let's extend it so as to write any factorial which is a factor of 5 to an alternate file, while writing the -remaining logs to factor.log. +remaining logs to :file:`factor.log`. .. literalinclude:: framework_logging_factorial_03.zeek :caption: @@ -1473,9 +1473,9 @@ record that defines the ``name`` and ``path_func`` fields. We then call ``Log::add_filter`` to add the filter to the ``Factor::LOG`` ``Log::ID`` and call ``Log::remove_filter`` to remove the ``default`` filter for ``Factor::LOG``. Had we not removed the ``default`` filter, -we'd have ended up with three log files: ``factor-mod5.log`` with all the -factorials that are a factors of 5, ``factor-non5.log`` with the -factorials that are not factors of 5, and ``factor.log`` which would have +we'd have ended up with three log files: :file:`factor-mod5.log` with all the +factorials that are a factors of 5, :file:`factor-non5.log` with the +factorials that are not factors of 5, and :file:`factor.log` which would have included all factorials. .. code-block:: console @@ -1510,7 +1510,7 @@ anyone wishing to act upon the data being sent to the stream. By convention these events are usually in the format ``log_x`` where x is the name of the logging stream; as such the event raised for every log sent to the Logging Framework by the HTTP parser would be ``log_http``. -Instead of using an external script to parse the ``http.log`` file and +Instead of using an external script to parse the :file:`http.log` file and do post-processing for each entry, this can be done in real time inside Zeek by defining an event handler for the ``log_http`` event. @@ -1681,7 +1681,7 @@ itself an enumerable that defines the values shown in the table below along with their corresponding meanings. The :zeek:enum:`Notice::ACTION_LOG` action writes the notice to the ``Notice::LOG`` logging stream which, in the default configuration, -will write each notice to the ``notice.log`` file and take no further +will write each notice to the :file:`notice.log` file and take no further action. The :zeek:enum:`Notice::ACTION_EMAIL` action will send an email to the address or addresses defined in the :zeek:id:`Notice::mail_dest` variable with the particulars of the notice as the body of the email. diff --git a/scripting/javascript.rst b/scripting/javascript.rst index 0cfacf4b0..220e8268e 100644 --- a/scripting/javascript.rst +++ b/scripting/javascript.rst @@ -237,8 +237,8 @@ will keep it alive within Zeek even if Zeek itself does not reference it anymore. Updates to fields in Zeek become visible within JavaScript. Updates to properties of such objects in JavaScript become visible in Zeek. -On the other hand, normal JavaScript objects (`{}` or `Object()`) are passed -from JavaScript to Zeek are passed by copy as new Zeek record values. Changes +On the other hand, normal JavaScript objects (``{}`` or ``Object()``) are passed +from JavaScript to Zeek as new Zeek record values. Changes to the original JavaScript object will not be reflected within Zeek. In the example below, the ``intel_item`` JavaScript object will be converted to a new :zeek:see:`Intel::Item` Zeek record which is then @@ -295,7 +295,7 @@ Set and vector values The :zeek:see:`set` and :zeek:see:`vector` types are currently copied from Zeek to JavaScript as `Array`_ objects. These objects don't reference the original set or vector on the Zeek side. This means that mutation of the -JavaScript side objects via accessors on the `Array` do not modify the +JavaScript side objects via accessors on ``Array`` do not modify the Zeek side value. However, objects referencing the Zeek record values within these arrays are mutable. @@ -366,8 +366,7 @@ debug stream may provide some helpful clues. 0.000000/1685018723.551120 [plugin Zeek::JavaScript] Registered zeek_init 1685018723.601898/1685018723.621106 [plugin Zeek::JavaScript] ZeekInvoke: invoke for zeek_version 1685018723.601898/1685018723.621177 [plugin Zeek::JavaScript] Invoke zeek_version with 0 args - 1685018723.601898/1685018723.621212 [plugin Zeek::JavaScript] ZeekInvoke: invoke for zeek_version returned: - Hello, Zeek 6.0.0-dev.636-debug! + 1685018723.601898/1685018723.621212 [plugin Zeek::JavaScript] ZeekInvoke: invoke for zeek_version returned: Hello, Zeek 6.0.0-dev.636-debug! 1685018723.644485/1685018723.644726 [plugin Zeek::JavaScript] Done... 1685018723.644485/1685018723.644754 [plugin Zeek::JavaScript] Done: uv_loop not alive anymore on iteration 0 diff --git a/scripting/optimization.rst b/scripting/optimization.rst index 41e94311a..3d300a687 100644 --- a/scripting/optimization.rst +++ b/scripting/optimization.rst @@ -14,7 +14,7 @@ Script Optimization Introduction ============ -The `Zeek Abstract Machine`, "ZAM", is an optional script optimization engine +The *Zeek Abstract Machine* (ZAM) is an optional script optimization engine built into Zeek. Using ZAM changes the basic execution model for Zeek scripts in an effort to gain higher performance. Normally, Zeek parses scripts into abstract syntax trees that it then executes by recursively interpreting each @@ -44,7 +44,7 @@ depends heavily on several factors: .. note:: At startup, ZAM takes a few seconds to generate the low-level code for the - loaded set of scripts, unless you're using Zeek's `bare mode` (via the + loaded set of scripts, unless you're using Zeek's *bare mode* (via the ``-b`` command-line option), which loads only a minimal set of scripts. Keep this in mind when comparing Zeek runtimes, to ensure you're comparing only actual script execution time. diff --git a/scripts/base/bif/event.bif.zeek.rst b/scripts/base/bif/event.bif.zeek.rst index bddb41fa0..d9f3c1831 100644 --- a/scripts/base/bif/event.bif.zeek.rst +++ b/scripts/base/bif/event.bif.zeek.rst @@ -662,8 +662,8 @@ Events of the file. The analysis can be augmented at this time via :zeek:see:`Files::add_analyzer`. The amount of data fed into the file sniffing can be increased or decreased by changing either - :zeek:see:`default_file_bof_buffer_size` or the `bof_buffer_size` field - in an `fa_file` record. The event will be raised even if content inspection + :zeek:see:`default_file_bof_buffer_size` or the ``bof_buffer_size`` field + in an :zeek:type:`fa_file` record. The event will be raised even if content inspection has been unable to infer any metadata, in which case the fields in *meta* will be left all unset. diff --git a/scripts/base/bif/packet_analysis.bif.zeek.rst b/scripts/base/bif/packet_analysis.bif.zeek.rst index 051191613..d1aca93cb 100644 --- a/scripts/base/bif/packet_analysis.bif.zeek.rst +++ b/scripts/base/bif/packet_analysis.bif.zeek.rst @@ -12,16 +12,16 @@ Summary ~~~~~~~ Functions ######### -====================================================================================== ============================================================================================================== +====================================================================================== ================================================================================================================ :zeek:id:`PacketAnalyzer::__disable_analyzer`: :zeek:type:`function` Internal function to disable a packet analyzer. :zeek:id:`PacketAnalyzer::__enable_analyzer`: :zeek:type:`function` Internal function to enable a packet analyzer. -:zeek:id:`PacketAnalyzer::__set_ignore_checksums_nets`: :zeek:type:`function` Internal function that is used to update the core-mirror of the script-level `ignore_checksums_nets` variable. +:zeek:id:`PacketAnalyzer::__set_ignore_checksums_nets`: :zeek:type:`function` Internal function that is used to update the core-mirror of the script-level ``ignore_checksums_nets`` variable. :zeek:id:`PacketAnalyzer::register_packet_analyzer`: :zeek:type:`function` Add an entry to parent's dispatcher that maps a protocol/index to a next-stage child analyzer. :zeek:id:`PacketAnalyzer::register_protocol_detection`: :zeek:type:`function` Registers a child analyzer with a parent analyzer to perform packet detection when determining whether to forward from parent to child. -:zeek:id:`PacketAnalyzer::try_register_packet_analyzer_by_name`: :zeek:type:`function` Attempts to add an entry to `parent`'s dispatcher that maps a protocol/index to a next-stage `child` +:zeek:id:`PacketAnalyzer::try_register_packet_analyzer_by_name`: :zeek:type:`function` Attempts to add an entry to ``parent``'s dispatcher that maps a protocol/index to a next-stage ``child`` analyzer. -====================================================================================== ============================================================================================================== +====================================================================================== ================================================================================================================ Detailed Interface @@ -47,7 +47,7 @@ Functions :Type: :zeek:type:`function` (v: :zeek:type:`subnet_set`) : :zeek:type:`bool` - Internal function that is used to update the core-mirror of the script-level `ignore_checksums_nets` variable. + Internal function that is used to update the core-mirror of the script-level ``ignore_checksums_nets`` variable. .. zeek:id:: PacketAnalyzer::register_packet_analyzer :source-code: base/bif/packet_analysis.bif.zeek 15 15 @@ -82,7 +82,7 @@ Functions :Type: :zeek:type:`function` (parent: :zeek:type:`string`, identifier: :zeek:type:`count`, child: :zeek:type:`string`) : :zeek:type:`bool` - Attempts to add an entry to `parent`'s dispatcher that maps a protocol/index to a next-stage `child` + Attempts to add an entry to ``parent``'s dispatcher that maps a protocol/index to a next-stage ``child`` analyzer. This may fail if either of the two names does not respond to a known analyzer. diff --git a/scripts/base/frameworks/broker/main.zeek.rst b/scripts/base/frameworks/broker/main.zeek.rst index 6dc8337ee..582655ef8 100644 --- a/scripts/base/frameworks/broker/main.zeek.rst +++ b/scripts/base/frameworks/broker/main.zeek.rst @@ -21,7 +21,7 @@ Runtime Options Redefinable Options ################### -============================================================================================ ======================================================================= +============================================================================================ =========================================================================== :zeek:id:`Broker::aggressive_interval`: :zeek:type:`count` :zeek:attr:`&redef` Frequency of work-stealing polling attempts for Broker/CAF threads in "aggressive" mode. :zeek:id:`Broker::aggressive_polls`: :zeek:type:`count` :zeek:attr:`&redef` Number of work-stealing polling attempts for Broker/CAF threads @@ -67,9 +67,9 @@ Redefinable Options certificate. :zeek:id:`Broker::ssl_passphrase`: :zeek:type:`string` :zeek:attr:`&redef` Passphrase to decrypt the private key specified by :zeek:see:`Broker::ssl_keyfile`. -:zeek:id:`Broker::web_socket_buffer_size`: :zeek:type:`count` :zeek:attr:`&redef` Same as `peer_buffer_size` but for WebSocket clients. -:zeek:id:`Broker::web_socket_overflow_policy`: :zeek:type:`string` :zeek:attr:`&redef` Same as `peer_overflow_policy` but for WebSocket clients. -============================================================================================ ======================================================================= +:zeek:id:`Broker::web_socket_buffer_size`: :zeek:type:`count` :zeek:attr:`&redef` Same as :zeek:see:`Broker::peer_buffer_size` but for WebSocket clients. +:zeek:id:`Broker::web_socket_overflow_policy`: :zeek:type:`string` :zeek:attr:`&redef` Same as :zeek:see:`Broker::peer_overflow_policy` but for WebSocket clients. +============================================================================================ =========================================================================== Types ##### @@ -299,7 +299,7 @@ Redefinable Options :Default: ``1`` Max number of threads to use for Broker/CAF functionality. The - ZEEK_BROKER_MAX_THREADS environment variable overrides this setting. + ``ZEEK_BROKER_MAX_THREADS`` environment variable overrides this setting. .. zeek:id:: Broker::moderate_interval :source-code: base/frameworks/broker/main.zeek 140 140 @@ -340,7 +340,7 @@ Redefinable Options Max number of items we buffer at most per peer. What action to take when the buffer reaches its maximum size is determined by - `peer_overflow_policy`. + :zeek:see:`Broker::peer_overflow_policy`. .. zeek:id:: Broker::peer_overflow_policy :source-code: base/frameworks/broker/main.zeek 99 99 @@ -454,7 +454,7 @@ Redefinable Options :Attributes: :zeek:attr:`&redef` :Default: ``512`` - Same as `peer_buffer_size` but for WebSocket clients. + Same as :zeek:see:`Broker::peer_buffer_size` but for WebSocket clients. .. zeek:id:: Broker::web_socket_overflow_policy :source-code: base/frameworks/broker/main.zeek 105 105 @@ -463,7 +463,7 @@ Redefinable Options :Attributes: :zeek:attr:`&redef` :Default: ``"disconnect"`` - Same as `peer_overflow_policy` but for WebSocket clients. + Same as :zeek:see:`Broker::peer_overflow_policy` but for WebSocket clients. Types ##### diff --git a/scripts/base/frameworks/input/main.zeek.rst b/scripts/base/frameworks/input/main.zeek.rst index 98843a9d0..992233dd1 100644 --- a/scripts/base/frameworks/input/main.zeek.rst +++ b/scripts/base/frameworks/input/main.zeek.rst @@ -72,7 +72,7 @@ Runtime Options :Attributes: :zeek:attr:`&redef` :Default: ``Input::MANUAL`` - The default reader mode used. Defaults to `MANUAL`. + The default reader mode used. Defaults to :zeek:see:`Input::MANUAL`. .. zeek:id:: Input::default_reader :source-code: base/frameworks/input/main.zeek 28 28 @@ -81,7 +81,7 @@ Runtime Options :Attributes: :zeek:attr:`&redef` :Default: ``Input::READER_ASCII`` - The default input reader used. Defaults to `READER_ASCII`. + The default input reader used. Defaults to :zeek:see:`Input::READER_ASCII`. Redefinable Options ################### @@ -149,7 +149,7 @@ Types source: :zeek:type:`string` String that allows the reader to find the source. - For `READER_ASCII`, this is the filename. + For :zeek:see:`Input::READER_ASCII`, this is the filename. reader: :zeek:type:`Input::Reader` :zeek:attr:`&default` = ``Input::READER_BINARY`` :zeek:attr:`&optional` Reader to use for this stream. Compatible readers must be @@ -200,7 +200,7 @@ Types source: :zeek:type:`string` String that allows the reader to find the source. - For `READER_ASCII`, this is the filename. + For :zeek:see:`Input::READER_ASCII`, this is the filename. reader: :zeek:type:`Input::Reader` :zeek:attr:`&default` = :zeek:see:`Input::default_reader` :zeek:attr:`&optional` Reader to use for this stream. @@ -223,8 +223,8 @@ Types ev: :zeek:type:`any` The event that is raised each time a new line is received from the - reader. The event will receive an Input::EventDescription record - as the first argument, an Input::Event enum as the second + reader. The event will receive an :zeek:see:`Input::EventDescription` record + as the first argument, an :zeek:see:`Input::Event` enum as the second argument, and the fields (as specified in *fields*) as the following arguments (this will either be a single record value containing all fields, or each field value as a separate argument). @@ -233,12 +233,12 @@ Types Error event that is raised when an information, warning or error is raised by the input stream. If the level is error, the stream will automatically be closed. - The event receives the Input::EventDescription as the first argument, the - message as the second argument and the Reporter::Level as the third argument. + The event receives the :zeek:see:`Input::EventDescription` as the first argument, the + message as the second argument and the :zeek:see:`Reporter::Level` as the third argument. The event is raised like it had been declared as follows: error_ev: function(desc: EventDescription, message: string, level: Reporter::Level) &optional; - The actual declaration uses the ``any`` type because of deficiencies of the Zeek type system. + The actual declaration uses the :zeek:type:`any` type because of deficiencies of the Zeek type system. config: :zeek:type:`table` [:zeek:type:`string`] of :zeek:type:`string` :zeek:attr:`&default` = ``{ }`` :zeek:attr:`&optional` A key/value table that will be passed to the reader. @@ -273,7 +273,7 @@ Types source: :zeek:type:`string` String that allows the reader to find the source of the data. - For `READER_ASCII`, this is the filename. + For :zeek:see:`Input::READER_ASCII`, this is the filename. reader: :zeek:type:`Input::Reader` :zeek:attr:`&default` = :zeek:see:`Input::default_reader` :zeek:attr:`&optional` Reader to use for this stream. @@ -323,7 +323,7 @@ Types The event is raised like if it had been declared as follows: error_ev: function(desc: TableDescription, message: string, level: Reporter::Level) &optional; - The actual declaration uses the ``any`` type because of deficiencies of the Zeek type system. + The actual declaration uses the :zeek:type:`any` type because of deficiencies of the Zeek type system. config: :zeek:type:`table` [:zeek:type:`string`] of :zeek:type:`string` :zeek:attr:`&default` = ``{ }`` :zeek:attr:`&optional` A key/value table that will be passed to the reader. @@ -390,7 +390,7 @@ Functions Create a new event input stream from a given source. - :param description: `EventDescription` record describing the source. + :param description: :zeek:see:`Input::EventDescription` record describing the source. :returns: true on success. @@ -403,7 +403,7 @@ Functions Create a new table input stream from a given source. - :param description: `TableDescription` record describing the source. + :param description: :zeek:see:`Input::TableDescription` record describing the source. :returns: true on success. diff --git a/scripts/base/frameworks/logging/main.zeek.rst b/scripts/base/frameworks/logging/main.zeek.rst index 3b572e080..20917f9d2 100644 --- a/scripts/base/frameworks/logging/main.zeek.rst +++ b/scripts/base/frameworks/logging/main.zeek.rst @@ -29,7 +29,7 @@ Redefinable Options ################### =========================================================================================== ===================================================================== :zeek:id:`Log::default_ext_prefix`: :zeek:type:`string` :zeek:attr:`&redef` A prefix for extension fields which can be optionally prefixed - on all log lines by setting the `ext_func` field in the + on all log lines by setting the ``ext_func`` field in the log filter. :zeek:id:`Log::default_field_name_map`: :zeek:type:`table` :zeek:attr:`&redef` Default field name mapping for renaming fields in a logging framework filter. @@ -199,7 +199,7 @@ Redefinable Options :Default: ``"_"`` A prefix for extension fields which can be optionally prefixed - on all log lines by setting the `ext_func` field in the + on all log lines by setting the ``ext_func`` field in the log filter. .. zeek:id:: Log::default_field_name_map @@ -326,8 +326,8 @@ Redefinable Options Default separator for log field scopes when logs are unrolled and flattened. This will be the string between field name components. - For example, setting this to "_" will cause the typical field - "id.orig_h" to turn into "id_orig_h". + For example, setting this to ``_`` will cause the typical field + ``id.orig_h`` to turn into ``id_orig_h``. .. zeek:id:: Log::default_writer :source-code: base/frameworks/logging/main.zeek 27 27 diff --git a/scripts/base/frameworks/notice/main.zeek.rst b/scripts/base/frameworks/notice/main.zeek.rst index 264d88656..8cae07e82 100644 --- a/scripts/base/frameworks/notice/main.zeek.rst +++ b/scripts/base/frameworks/notice/main.zeek.rst @@ -213,7 +213,7 @@ Redefinable Options on rotation with :zeek:enum:`Notice::ACTION_ALARM`. Note that this is overridden by the ZeekControl MailTo option or by - the `email_dest` field in the :zeek:see:`Notice::Info` record. + the ``email_dest`` field in the :zeek:see:`Notice::Info` record. .. zeek:id:: Notice::max_email_delay :source-code: base/frameworks/notice/main.zeek 221 221 @@ -607,7 +607,7 @@ Types Limitations in BPF make shunting some connections with BPF - impossible. This notice encompasses those various cases. + impossible. This notice encompasses those various cases. .. zeek:enum:: Software::Software_Version_Change Notice::Type diff --git a/scripts/base/frameworks/spicy/init-bare.zeek.rst b/scripts/base/frameworks/spicy/init-bare.zeek.rst index 6fd7dd4e2..5168d85c1 100644 --- a/scripts/base/frameworks/spicy/init-bare.zeek.rst +++ b/scripts/base/frameworks/spicy/init-bare.zeek.rst @@ -27,9 +27,9 @@ Constants Types ##### -====================================================== ========================================== -:zeek:type:`Spicy::ResourceUsage`: :zeek:type:`record` Result type for `Spicy::resource_usage()`. -====================================================== ========================================== +====================================================== ================================================== +:zeek:type:`Spicy::ResourceUsage`: :zeek:type:`record` Result type for :zeek:see:`Spicy::resource_usage`. +====================================================== ================================================== Detailed Interface @@ -118,7 +118,7 @@ Types cached_fibers: :zeek:type:`count` number of fibers currently cached - Result type for `Spicy::resource_usage()`. The values reflect resource + Result type for :zeek:see:`Spicy::resource_usage`. The values reflect resource usage as reported by the Spicy runtime system. diff --git a/scripts/base/frameworks/supervisor/api.zeek.rst b/scripts/base/frameworks/supervisor/api.zeek.rst index d3641c371..dc83399fc 100644 --- a/scripts/base/frameworks/supervisor/api.zeek.rst +++ b/scripts/base/frameworks/supervisor/api.zeek.rst @@ -206,7 +206,7 @@ Hooks :Type: :zeek:type:`hook` (node: :zeek:type:`string`, msg: :zeek:type:`string`) : :zeek:type:`bool` Hooks into the stderr stream for all supervisor's child processes. - If a hook terminates with `break`, that will suppress output to the + If a hook terminates with ``break``, that will suppress output to the associated stream. @@ -226,7 +226,7 @@ Hooks :Type: :zeek:type:`hook` (node: :zeek:type:`string`, msg: :zeek:type:`string`) : :zeek:type:`bool` Hooks into the stdout stream for all supervisor's child processes. - If a hook terminates with `break`, that will suppress output to the + If a hook terminates with ``break``, that will suppress output to the associated stream. diff --git a/scripts/base/frameworks/telemetry/main.zeek.rst b/scripts/base/frameworks/telemetry/main.zeek.rst index acba8b531..3cfd26a3c 100644 --- a/scripts/base/frameworks/telemetry/main.zeek.rst +++ b/scripts/base/frameworks/telemetry/main.zeek.rst @@ -41,18 +41,18 @@ Functions :zeek:id:`Telemetry::collect_metrics`: :zeek:type:`function` Collect all counter and gauge metrics matching the given *name* and *prefix*. :zeek:id:`Telemetry::counter_family_inc`: :zeek:type:`function` Increment a :zeek:see:`Telemetry::Counter` through the :zeek:see:`Telemetry::CounterFamily`. :zeek:id:`Telemetry::counter_family_set`: :zeek:type:`function` Set a :zeek:see:`Telemetry::Counter` through the :zeek:see:`Telemetry::CounterFamily`. -:zeek:id:`Telemetry::counter_inc`: :zeek:type:`function` Increment a :zeek:see:`Telemetry::Counter` by `amount`. -:zeek:id:`Telemetry::counter_set`: :zeek:type:`function` Helper to set a :zeek:see:`Telemetry::Counter` to the given `value`. +:zeek:id:`Telemetry::counter_inc`: :zeek:type:`function` Increment a :zeek:see:`Telemetry::Counter` by ``amount``. +:zeek:id:`Telemetry::counter_set`: :zeek:type:`function` Helper to set a :zeek:see:`Telemetry::Counter` to the given ``value``. :zeek:id:`Telemetry::counter_with`: :zeek:type:`function` Get a :zeek:see:`Telemetry::Counter` instance given family and label values. -:zeek:id:`Telemetry::gauge_dec`: :zeek:type:`function` Decrement a :zeek:see:`Telemetry::Gauge` by `amount`. -:zeek:id:`Telemetry::gauge_family_dec`: :zeek:type:`function` Decrement a :zeek:see:`Telemetry::Gauge` by the given `amount` through +:zeek:id:`Telemetry::gauge_dec`: :zeek:type:`function` Decrement a :zeek:see:`Telemetry::Gauge` by ``amount``. +:zeek:id:`Telemetry::gauge_family_dec`: :zeek:type:`function` Decrement a :zeek:see:`Telemetry::Gauge` by the given ``amount`` through the :zeek:see:`Telemetry::GaugeFamily`. -:zeek:id:`Telemetry::gauge_family_inc`: :zeek:type:`function` Increment a :zeek:see:`Telemetry::Gauge` by the given `amount` through +:zeek:id:`Telemetry::gauge_family_inc`: :zeek:type:`function` Increment a :zeek:see:`Telemetry::Gauge` by the given ``amount`` through the :zeek:see:`Telemetry::GaugeFamily`. -:zeek:id:`Telemetry::gauge_family_set`: :zeek:type:`function` Set a :zeek:see:`Telemetry::Gauge` to the given `value` through +:zeek:id:`Telemetry::gauge_family_set`: :zeek:type:`function` Set a :zeek:see:`Telemetry::Gauge` to the given ``value`` through the :zeek:see:`Telemetry::GaugeFamily`. -:zeek:id:`Telemetry::gauge_inc`: :zeek:type:`function` Increment a :zeek:see:`Telemetry::Gauge` by `amount`. -:zeek:id:`Telemetry::gauge_set`: :zeek:type:`function` Helper to set a :zeek:see:`Telemetry::Gauge` to the given `value`. +:zeek:id:`Telemetry::gauge_inc`: :zeek:type:`function` Increment a :zeek:see:`Telemetry::Gauge` by ``amount``. +:zeek:id:`Telemetry::gauge_set`: :zeek:type:`function` Helper to set a :zeek:see:`Telemetry::Gauge` to the given ``value``. :zeek:id:`Telemetry::gauge_with`: :zeek:type:`function` Get a :zeek:see:`Telemetry::Gauge` instance given family and label values. :zeek:id:`Telemetry::histogram_family_observe`: :zeek:type:`function` Observe a measurement for a :zeek:see:`Telemetry::Histogram` through the :zeek:see:`Telemetry::HistogramFamily`. @@ -252,8 +252,8 @@ Functions :Type: :zeek:type:`function` (c: :zeek:type:`Telemetry::Counter`, amount: :zeek:type:`double` :zeek:attr:`&default` = ``1.0`` :zeek:attr:`&optional`) : :zeek:type:`bool` - Increment a :zeek:see:`Telemetry::Counter` by `amount`. - Using a negative `amount` is an error. + Increment a :zeek:see:`Telemetry::Counter` by ``amount``. + Using a negative ``amount`` is an error. :param c: The counter instance. @@ -269,7 +269,7 @@ Functions :Type: :zeek:type:`function` (c: :zeek:type:`Telemetry::Counter`, value: :zeek:type:`double`) : :zeek:type:`bool` - Helper to set a :zeek:see:`Telemetry::Counter` to the given `value`. + Helper to set a :zeek:see:`Telemetry::Counter` to the given ``value``. This can be useful for mirroring counter metrics in an :zeek:see:`Telemetry::sync` hook implementation. Setting a value that is less than the current value of the @@ -296,7 +296,7 @@ Functions :Type: :zeek:type:`function` (g: :zeek:type:`Telemetry::Gauge`, amount: :zeek:type:`double` :zeek:attr:`&default` = ``1.0`` :zeek:attr:`&optional`) : :zeek:type:`bool` - Decrement a :zeek:see:`Telemetry::Gauge` by `amount`. + Decrement a :zeek:see:`Telemetry::Gauge` by ``amount``. :param g: The gauge instance. @@ -312,7 +312,7 @@ Functions :Type: :zeek:type:`function` (gf: :zeek:type:`Telemetry::GaugeFamily`, label_values: :zeek:type:`Telemetry::labels_vector` :zeek:attr:`&default` = ``[]`` :zeek:attr:`&optional`, value: :zeek:type:`double` :zeek:attr:`&default` = ``1.0`` :zeek:attr:`&optional`) : :zeek:type:`bool` - Decrement a :zeek:see:`Telemetry::Gauge` by the given `amount` through + Decrement a :zeek:see:`Telemetry::Gauge` by the given ``amount`` through the :zeek:see:`Telemetry::GaugeFamily`. This is a short-cut for :zeek:see:`Telemetry::gauge_dec`. @@ -333,7 +333,7 @@ Functions :Type: :zeek:type:`function` (gf: :zeek:type:`Telemetry::GaugeFamily`, label_values: :zeek:type:`Telemetry::labels_vector` :zeek:attr:`&default` = ``[]`` :zeek:attr:`&optional`, value: :zeek:type:`double` :zeek:attr:`&default` = ``1.0`` :zeek:attr:`&optional`) : :zeek:type:`bool` - Increment a :zeek:see:`Telemetry::Gauge` by the given `amount` through + Increment a :zeek:see:`Telemetry::Gauge` by the given ``amount`` through the :zeek:see:`Telemetry::GaugeFamily`. This is a short-cut for :zeek:see:`Telemetry::gauge_inc`. Using a negative amount is an error. @@ -355,7 +355,7 @@ Functions :Type: :zeek:type:`function` (gf: :zeek:type:`Telemetry::GaugeFamily`, label_values: :zeek:type:`Telemetry::labels_vector`, value: :zeek:type:`double`) : :zeek:type:`bool` - Set a :zeek:see:`Telemetry::Gauge` to the given `value` through + Set a :zeek:see:`Telemetry::Gauge` to the given ``value`` through the :zeek:see:`Telemetry::GaugeFamily`. This is a short-cut for :zeek:see:`Telemetry::gauge_set`. @@ -376,7 +376,7 @@ Functions :Type: :zeek:type:`function` (g: :zeek:type:`Telemetry::Gauge`, amount: :zeek:type:`double` :zeek:attr:`&default` = ``1.0`` :zeek:attr:`&optional`) : :zeek:type:`bool` - Increment a :zeek:see:`Telemetry::Gauge` by `amount`. + Increment a :zeek:see:`Telemetry::Gauge` by ``amount``. :param g: The gauge instance. @@ -392,7 +392,7 @@ Functions :Type: :zeek:type:`function` (g: :zeek:type:`Telemetry::Gauge`, value: :zeek:type:`double`) : :zeek:type:`bool` - Helper to set a :zeek:see:`Telemetry::Gauge` to the given `value`. + Helper to set a :zeek:see:`Telemetry::Gauge` to the given ``value``. :param g: The gauge instance. diff --git a/scripts/base/misc/version.zeek.rst b/scripts/base/misc/version.zeek.rst index 52348499a..bb14c0dea 100644 --- a/scripts/base/misc/version.zeek.rst +++ b/scripts/base/misc/version.zeek.rst @@ -4,9 +4,9 @@ base/misc/version.zeek ====================== .. zeek:namespace:: Version -Provide information about the currently running Zeek version. -The most convenient way to access this are the Version::number -and Version::info constants. +Provide information about the currently running Zeek version. The most +convenient way to access this are the :zeek:see:`Version::number` and +:zeek:see:`Version::info` constants. :Namespace: Version @@ -14,10 +14,12 @@ Summary ~~~~~~~ Constants ######### -================================================================== ==================================================================================== -:zeek:id:`Version::info`: :zeek:type:`Version::VersionDescription` `VersionDescription` record pertaining to the currently running version of Zeek. -:zeek:id:`Version::number`: :zeek:type:`count` version number of the currently running version of Zeek as a numeric representation. -================================================================== ==================================================================================== +================================================================== ========================================================================== +:zeek:id:`Version::info`: :zeek:type:`Version::VersionDescription` :zeek:see:`Version::VersionDescription` record pertaining to the currently + running version of Zeek. +:zeek:id:`Version::number`: :zeek:type:`count` version number of the currently running version of Zeek as a numeric + representation. +================================================================== ========================================================================== Types ##### @@ -27,11 +29,11 @@ Types Functions ######### -=================================================== ==================================================================================== -:zeek:id:`Version::at_least`: :zeek:type:`function` Test if the current running version of Zeek is greater or equal to the given version - string. +=================================================== ================================================================== +:zeek:id:`Version::at_least`: :zeek:type:`function` Test if the current running version of Zeek is greater or equal to + the given version string. :zeek:id:`Version::parse`: :zeek:type:`function` Parse a given version string. -=================================================== ==================================================================================== +=================================================== ================================================================== Detailed Interface @@ -39,21 +41,23 @@ Detailed Interface Constants ######### .. zeek:id:: Version::info - :source-code: base/misc/version.zeek 122 122 + :source-code: base/misc/version.zeek 123 123 :Type: :zeek:type:`Version::VersionDescription` - `VersionDescription` record pertaining to the currently running version of Zeek. + :zeek:see:`Version::VersionDescription` record pertaining to the currently + running version of Zeek. .. zeek:id:: Version::number - :source-code: base/misc/version.zeek 128 128 + :source-code: base/misc/version.zeek 130 130 :Type: :zeek:type:`count` - version number of the currently running version of Zeek as a numeric representation. - The format of the number is ABBCC with A being the major version, - bb being the minor version (2 digits) and CC being the patchlevel (2 digits). - As an example, Zeek 2.4.1 results in the number 20401 + version number of the currently running version of Zeek as a numeric + representation. The format of the number is ABBCC with A being the + major version, bb being the minor version (2 digits) and CC being the + patchlevel (2 digits). As an example, Zeek 2.4.1 results in the + number 20401 Types ##### @@ -104,12 +108,12 @@ Types Functions ######### .. zeek:id:: Version::at_least - :source-code: base/misc/version.zeek 131 134 + :source-code: base/misc/version.zeek 133 136 :Type: :zeek:type:`function` (version_string: :zeek:type:`string`) : :zeek:type:`bool` - Test if the current running version of Zeek is greater or equal to the given version - string. + Test if the current running version of Zeek is greater or equal to + the given version string. :param version_string: Version to check against the current running version. @@ -128,6 +132,6 @@ Functions :param version_string: Zeek version string. - :returns: `VersionDescription` record. + :returns: :zeek:see:`Version::VersionDescription` record. diff --git a/scripts/base/utils/exec.zeek.rst b/scripts/base/utils/exec.zeek.rst index c80748146..0e08e0f60 100644 --- a/scripts/base/utils/exec.zeek.rst +++ b/scripts/base/utils/exec.zeek.rst @@ -36,7 +36,7 @@ Types :Type: :zeek:type:`record` cmd: :zeek:type:`string` - The command line to execute. Use care to avoid injection + The command line to execute. Use care to avoid injection attacks (i.e., if the command uses untrusted/variable data, sanitize it with :zeek:see:`safe_shell_quote`). @@ -81,11 +81,11 @@ Functions :Type: :zeek:type:`function` (cmd: :zeek:type:`Exec::Command`) : :zeek:type:`Exec::Result` Function for running command line programs and getting - output. This is an asynchronous function which is meant - to be run with the `when` statement. + output. This is an asynchronous function which is meant + to be run with the ``when`` statement. - :param cmd: The command to run. Use care to avoid injection attacks! + :param cmd: The command to run. Use care to avoid injection attacks! :returns: A record representing the full results from the diff --git a/scripts/base/utils/numbers.zeek.rst b/scripts/base/utils/numbers.zeek.rst index 029dc253c..ce48de729 100644 --- a/scripts/base/utils/numbers.zeek.rst +++ b/scripts/base/utils/numbers.zeek.rst @@ -29,10 +29,10 @@ Functions :param s: The string to search for a number. - :param get_first: Provide `F` if you would like the last number found. + :param get_first: Provide ``F`` if you would like the last number found. - :returns: The request integer from the given string or 0 if + :returns: The request integer from the given string or ``0`` if no integer was found. diff --git a/scripts/policy/frameworks/packet-filter/shunt.zeek.rst b/scripts/policy/frameworks/packet-filter/shunt.zeek.rst index 954059644..0bb2b65be 100644 --- a/scripts/policy/frameworks/packet-filter/shunt.zeek.rst +++ b/scripts/policy/frameworks/packet-filter/shunt.zeek.rst @@ -41,9 +41,9 @@ Functions :zeek:id:`PacketFilter::shunt_conn`: :zeek:type:`function` Call this function to use BPF to shunt a connection (to prevent the data packets from reaching Zeek). :zeek:id:`PacketFilter::shunt_host_pair`: :zeek:type:`function` This function will use a BPF expression to shunt traffic between - the two hosts given in the `conn_id` so that the traffic is never + the two hosts given in the ``conn_id`` so that the traffic is never exposed to Zeek's traffic processing. -:zeek:id:`PacketFilter::unshunt_host_pair`: :zeek:type:`function` Remove shunting for a host pair given as a `conn_id`. +:zeek:id:`PacketFilter::unshunt_host_pair`: :zeek:type:`function` Remove shunting for a host pair given as a ``conn_id``. ========================================================================== ============================================================================ @@ -90,7 +90,7 @@ Functions :Type: :zeek:type:`function` (id: :zeek:type:`conn_id`) : :zeek:type:`bool` Call this function to use BPF to shunt a connection (to prevent the - data packets from reaching Zeek). For TCP connections, control + data packets from reaching Zeek). For TCP connections, control packets are still allowed through so that Zeek can continue logging the connection and it can stop shunting once the connection ends. @@ -100,7 +100,7 @@ Functions :Type: :zeek:type:`function` (id: :zeek:type:`conn_id`) : :zeek:type:`bool` This function will use a BPF expression to shunt traffic between - the two hosts given in the `conn_id` so that the traffic is never + the two hosts given in the ``conn_id`` so that the traffic is never exposed to Zeek's traffic processing. .. zeek:id:: PacketFilter::unshunt_host_pair @@ -108,8 +108,8 @@ Functions :Type: :zeek:type:`function` (id: :zeek:type:`conn_id`) : :zeek:type:`bool` - Remove shunting for a host pair given as a `conn_id`. The filter + Remove shunting for a host pair given as a ``conn_id``. The filter is not immediately removed. It waits for the occasional filter - update done by the `PacketFilter` framework. + update done by the ``PacketFilter`` framework. diff --git a/scripts/policy/frameworks/telemetry/log.zeek.rst b/scripts/policy/frameworks/telemetry/log.zeek.rst index 5086b639d..39849ee64 100644 --- a/scripts/policy/frameworks/telemetry/log.zeek.rst +++ b/scripts/policy/frameworks/telemetry/log.zeek.rst @@ -4,8 +4,8 @@ policy/frameworks/telemetry/log.zeek ==================================== .. zeek:namespace:: Telemetry -Implementation of a telemetry.log and telemetry_histogram.log file -using metrics accessible via the Telemetry module. +Implementation of a :file:`telemetry.log` and :file:`telemetry_histogram.log` +file using metrics accessible via the Telemetry module. :Namespace: Telemetry :Imports: :doc:`base/frameworks/telemetry ` @@ -17,7 +17,8 @@ Runtime Options ============================================================================= =============================================================== :zeek:id:`Telemetry::log_interval`: :zeek:type:`interval` :zeek:attr:`&redef` How often metrics are reported. :zeek:id:`Telemetry::log_prefixes`: :zeek:type:`set` :zeek:attr:`&redef` Only metrics with prefixes in this set will be included in the - `telemetry.log` and `telemetry_histogram.log` files by default. + :file:`telemetry.log` and :file:`telemetry_histogram.log` files + by default. ============================================================================= =============================================================== Types @@ -66,7 +67,7 @@ Runtime Options How often metrics are reported. .. zeek:id:: Telemetry::log_prefixes - :source-code: policy/frameworks/telemetry/log.zeek 22 22 + :source-code: policy/frameworks/telemetry/log.zeek 23 23 :Type: :zeek:type:`set` [:zeek:type:`string`] :Attributes: :zeek:attr:`&redef` @@ -81,8 +82,9 @@ Runtime Options Only metrics with prefixes in this set will be included in the - `telemetry.log` and `telemetry_histogram.log` files by default. - Setting this option to an empty set includes all prefixes. + :file:`telemetry.log` and :file:`telemetry_histogram.log` files + by default. Setting this option to an empty set includes all + prefixes. For more fine-grained customization, setting this option to an empty set and implementing the :zeek:see:`Telemetry::log_policy` @@ -92,7 +94,7 @@ Runtime Options Types ##### .. zeek:type:: Telemetry::HistogramInfo - :source-code: policy/frameworks/telemetry/log.zeek 50 77 + :source-code: policy/frameworks/telemetry/log.zeek 51 78 :Type: :zeek:type:`record` @@ -126,7 +128,7 @@ Types Record type used for logging histogram metrics. .. zeek:type:: Telemetry::Info - :source-code: policy/frameworks/telemetry/log.zeek 25 47 + :source-code: policy/frameworks/telemetry/log.zeek 26 48 :Type: :zeek:type:`record` @@ -157,14 +159,14 @@ Types Events ###### .. zeek:id:: Telemetry::log_telemetry - :source-code: policy/frameworks/telemetry/log.zeek 86 86 + :source-code: policy/frameworks/telemetry/log.zeek 87 87 :Type: :zeek:type:`event` (rec: :zeek:type:`Telemetry::Info`) Event triggered for every record in the stream. .. zeek:id:: Telemetry::log_telemetry_histogram - :source-code: policy/frameworks/telemetry/log.zeek 89 89 + :source-code: policy/frameworks/telemetry/log.zeek 90 90 :Type: :zeek:type:`event` (rec: :zeek:type:`Telemetry::HistogramInfo`) @@ -173,14 +175,14 @@ Events Hooks ##### .. zeek:id:: Telemetry::log_policy - :source-code: policy/frameworks/telemetry/log.zeek 80 80 + :source-code: policy/frameworks/telemetry/log.zeek 81 81 :Type: :zeek:type:`Log::PolicyHook` A default logging policy hook for the stream. .. zeek:id:: Telemetry::log_policy_histogram - :source-code: policy/frameworks/telemetry/log.zeek 83 83 + :source-code: policy/frameworks/telemetry/log.zeek 84 84 :Type: :zeek:type:`Log::PolicyHook` diff --git a/troubleshooting.rst b/troubleshooting.rst index b33769631..e217f6d54 100644 --- a/troubleshooting.rst +++ b/troubleshooting.rst @@ -272,7 +272,7 @@ which then stores metrics data for later visualization. process_resident_memory_bytes{endpoint=""} 268935168 1684826824560 -If you prefer to consume metrics via logs, the ``telemetry.log`` +If you prefer to consume metrics via logs, the :file:`telemetry.log` (:zeek:see:`Telemetry::Info`) may work. Its format is a bit unusual, however. See the :ref:`framework-telemetry`'s documentation for more details about the log and how to add further metrics @@ -281,11 +281,11 @@ from your own Zeek scripts. .. _Prometheus server: https://prometheus.io/ -stats.log ---------- +:file:`stats.log` +----------------- -The ``stats.log`` is enabled when loading the :doc:`/scripts/policy/misc/stats.zeek` script. -This is the default with the stock ``local.zeek`` included with Zeek. This +The :file:`stats.log` is enabled when loading the :doc:`/scripts/policy/misc/stats.zeek` script. +This is the default with the stock :file:`local.zeek` included with Zeek. This log provides stats about Zeek's operational behavior in a structured log format. See the :zeek:see:`Stats::Info` record documentation for a description of @@ -309,7 +309,7 @@ metrics to continuously grow and compute rates or delta values on the fly. always be derived from two absolute values. The inverse is not true. Popular metrics systems usually assume absolute counter values, too. -Following an example of a ``stats.log`` entry: +Following an example of a :file:`stats.log` entry: .. code-block:: console @@ -345,23 +345,23 @@ Following an example of a ``stats.log`` entry: "reassem_unknown_size": 0 } -prof.log --------- +:file:`prof.log` +---------------- -The ``prof.log`` provides aggregated information about Zeek's runtime status +The :file:`prof.log` provides aggregated information about Zeek's runtime status in a fairly non-structured text format. Likely future metrics will be added through the Telemetry framework mentioned above, but as of now it does contain information about queue sizes within the threading subsystem and other details that are not yet exposed otherwise. -To enable ``prof.log``, load the :doc:`/scripts/policy/misc/profiling.zeek` script -in ``local.zeek`` or start Zeek with ``misc/profiling`` on the command-line: +To enable :file:`prof.log`, load the :doc:`/scripts/policy/misc/profiling.zeek` script +in :file:`local.zeek` or start Zeek with ``misc/profiling`` on the command-line: .. code-block:: console $ zeek -C -i eth0 misc/profiling -The following provides an example of ``prof.log`` content: +The following provides an example of :file:`prof.log` content: .. code-block:: console