Working Across Many Zeek Versions

As Zeek develops, various incompatibilities and breakages occur, but they are introduced in a controlled manner according to the intended Release Cadence.

It's often desirable for developers of Zeek scripts, plugins, and packages to have their code work across multiple Zeek versions, such as with both the current Long-Term Support (LTS) and Feature versions. Here are some tips to help accomplish that:

Version-Aware Zeek Scripts

To write Zeek script logic that is dependent upon Zeek version, you can make use of the misc/version.zeek script that ships with Zeek along with parse-time conditional directives:

@load base/misc/version

# Version::number is encoded as: (major * 10000 + minor * 100 + patch)
# For example, 3.1.2 becomes 30102.

@if ( Version::number >= 30200 )

# Put code that requires Zeek 3.2+ here. It can be any code, not just zeek_init.
event zeek_init() { print "This example ran on Zeek 3.2+"; }

@else

# Put code that works on older versions here
event zeek_init() { print "This example ran on an older Zeek"; }

@endif

# To avoid an incompatibility or deprecation message due to a change in an
# event handler's prototype, you may find it convenient to surround only the
# the event handler prototype with the pre-processing conditional
# (or even just surrounding the differing parameter) rather than
# re-implement/copy logic that's common between the event handler bodies:

@if ( Version::number >= 30200 )
event icmp_router_advertisement(c: connection, info: icmp_info, cur_hop_limit: count,
                                managed: bool, other: bool, home_agent: bool, pref: count,
                                proxy: bool, rsv: count, router_lifetime: interval,
                                reachable_time: interval, retrans_timer: interval,
                                options: icmp6_nd_options)
@else
event icmp_router_advertisement(c: connection, icmp: icmp_conn, cur_hop_limit: count,
                                managed: bool, other: bool, home_agent: bool, pref: count,
                                proxy: bool, rsv: count, router_lifetime: interval,
                                reachable_time: interval, retrans_timer: interval,
                                options: icmp6_nd_options)
@endif
    {
    # Common event handler code goes in here as long it doesn't refer to either
    # the "info" or "icmp" arguments, which differ depending on Zeek version.
    # This may also be a case where you may find it clearer to break the
    # differing parameters out to an individual lines and have them be the only
    # things surrounded by the pre-processing "@if" conditionals.
    }

Version-Aware Zeek Plugins (C++)

To write Zeek C++ plugin logic that is dependent upon Zeek version:

#include "zeek-config.h"

// ZEEK_VERSION_NUMBER is encoded as: (major * 10000 + minor * 100 + patch)
// For example, 3.1.2 becomes 30102.

// ZEEK_VERSION_NUMBER itself is only available in Zeek 3.2+, so the check
// for its definition may be required depending on your goals.

#if defined(ZEEK_VERSION_NUMBER) && ZEEK_VERSION_NUMBER >= 30200
// Code that requires Zeek 3.2+ goes here
#else
// Code that works on older versions goes here
#endif

Version Dependency Checks for Packages

To have the zkg package-manager check whether the installed Zeek version is adequate to run a package, a depends metadata field can assert the Zeek versions with which it may be used. Such a version dependency is checked upon attempting to install a package.