4. How-To: Create a Package Source

zkg, by default, is configured to obtain packages from a single "package source", the Zeek Packages Git Repository, which is hosted by and loosely curated by the Zeek Team. However, users may configure zkg to use other package sources: either ones they've set up themselves for organization purposes or those hosted by other third parties.

4.1. Package Source Setup

In order to set up such a package source, one simply has to create a git repository and then add Package Index Files to it. These files may be created at any path in the package source's git repository. E.g. the Zeek Packages Git Repository organizes package index files hierarchically based on package author names such as alice/zkg.index or bob/zkg.index where alice and bob are usually GitHub usernames or some unique way of identifying the organization/person that maintains Zeek packages. However, a source is free to use a flat organization with a single, top-level zkg.index.

Note

The magic index file name of zkg.index is available since zkg v2.0. For compatibility purposes, the old index file name of bro-pkg.index is also still supported.

After creating a git repo for the package source and adding package index files to it, it's ready to be used by zkg.

4.2. Package Index Files

Files named zkg.index (or the legacy bro-pkg.index) are used to describe the Zeek Packages found within the package source. They are simply a list of git URLs pointing to the git repositories of packages. For example:

https://github.com/zeek/foo
https://github.com/zeek/bar
https://github.com/zeek/baz

Local filesystem paths are also valid if the package source is only meant for your own private usage or testing.

4.3. Adding Packages

Adding packages is as simple as adding new Package Index Files or extending existing ones with new URLs and then commiting/pushing those changes to the package source git repository.

zkg will see new packages listed the next time it uses the refresh command.

4.4. Removing Packages

Just remove the package's URL from the Package Index File that it's contained within.

After the next time zkg uses the refresh command, it will no longer see the now-removed package when viewing package listings via by the list command.

Users that had previously installed the now-removed package may continue to use it and receive updates for it.

4.5. Aggregating Metadata

The maintainer/operator of a package source may choose to periodically aggregate the metadata contained in its packages' zkg.meta (and legacy bro-pkg.meta) files. The zkg refresh is used to perform the task. For example:

$ zkg refresh --aggregate --push --sources my_source

The optional --push flag is helpful for setting up cron jobs to automatically perform this task periodically, assuming you've set up your git configuration to push changesets without interactive prompts. E.g. to set up pushing to remote servers you could set up SSH public key authentication.

Aggregated metadata gets written to a file named aggregate.meta at the top-level of a package source and the list, search, and info all may access this file. Having access to the aggregated metadata in this way is beneficial to all zkg users because they then will not have to crawl the set of packages listed in a source in order to obtain this metadata as it will have already been pre-aggregated by the operator of the package source.