Configuration¶

zoryn reads configuration from three places, in order of specificity:

Run zoryn gen environment to bootstrap ~/.zoryn plus SSH, hasher and GPG configs in one shot.

~/.zoryn¶

Minimal example — zoryn works with just this:

[gitery]
remote = "gitery"

All other sections have sensible defaults. Override only what genuinely differs for you.

Full example¶

[build]
command = "hsh -v --number={hasher_number} --mountpoint=/proc,/dev/pts,/dev/kvm --lazy-cleanup {hasher_dir}"
log_filename = "build.{batch}.{builder}.log"

[builders]
default = "local"
default_arch = "x86_64"
parallel = "off"
results_download_dir = "{git_root}/hasher_out"
batch_repo = "~/zoryn-batch-repo"

[gitery]
host = "gitery"
remote = "gitery"

[gyle]
host = "gyle"

[sources]
srpms_path = "/mnt/ftp/pub/distributions/ALTLinux/Sisyphus/files/SRPMS/"

[rebuild]
command = "hsh -v --mountpoint=/proc,/dev/pts,/dev/kvm --lazy-cleanup"
log_dir = "/tmp/rebuild-logs"

[add_changelog]
up_template = "- {old_version} -> {new_version} {cves}"

[ssh]
multiplexing = true   # reuse TCP connections via ControlMaster (default: true)
persist = "2m"        # keep master connection alive after last use (default: 2m)

[notify]
enabled = true        # desktop notifications for long-running commands (default: true)

[commands]
# Optional: override paths and arguments for external commands
# git = "/usr/local/bin/git"
# git.fetch = "{git} fetch --prune"
# ssh = "ssh -o ConnectTimeout=10"
# ssh.gitery = "{ssh} -p 2222 -i ~/.ssh/alt_key"

Section reference¶

[build]¶

• command — hsh command for local builds (default: hsh --lazy-cleanup). Use hsh, not gear-hsh — the tarball is created separately with gear --commit. For parallel builds with multiple local hashers, use {hasher_number} and {hasher_dir} placeholders.
• log_filename — log filename template (default: build.{batch}.{builder}.log). Placeholders: {builder}, {batch}, {pkgname}.

[builders]¶

• default — default builder(s) when no --builder is specified and no per-branch override applies. Comma-separated string or TOML array (e.g. "local" or ["local", "arm-server"]).
• default_arch — default architecture(s) for multi-builder mode. Comma-separated string or TOML array. When multiple architectures are listed, multi-builder mode is enabled automatically.
• parallel — default parallel mode for multi-builder builds (on or off, default: off). Override with --parallel / --sequential.
• results_download_dir — directory for downloading remote build results (default: {git_root}/hasher_out). Supports {git_root}.
• batch_repo — directory for accumulating RPMs during batch builds. Used by download_rpms / upload_rpms.

[builders.<branch>] — per-branch defaults¶

[builders]
default = "sis-x86, sis-arm"
default_arch = "x86_64"

[builders.p11]
default = "p11-x86"
default_arch = "x86_64"

[gitery]¶

• host — SSH alias for gitery. Must match an entry in ~/.ssh/config.
• remote — name of the git remote pointing to gitery, used for push operations.

[gyle]¶

• host — SSH alias for the gyle build system.

[sources]¶

• srpms_path — local SRPMS mirror (required for zoryn task rebuild).

[rebuild]¶

• command — hasher command for rebuilding packages (default: hsh -v --mountpoint=/proc,/dev/pts,/dev/kvm --lazy-cleanup).
• log_dir — base directory for build logs (default: /tmp/rebuild-logs).

[tasks]¶

• api_url — Tasks API base URL (default: https://git.altlinux.org/tasks/api).
• user — girar username for API queries (default: extracted from %packager email in ~/.rpmmacros).

[rdb]¶

• api_url — RDB API base URL (default: https://rdb.altlinux.org/api).

[add_changelog]¶

• up_template — changelog entry template for zoryn up (default: - updated from {old_version} to {new_version} {cves}).
• {old_version}, {new_version}, {cves} (the latter expands to (Fixes: CVE-...) or empty).
• The per-package .gear/version-up [add_changelog] takes priority over ~/.zoryn.
• Trailing whitespace is trimmed automatically.

[submit]¶

• run — whether to run a task after creating/modifying (default: false).
• test_only — whether to mark tasks as test-only (default: true).

To restore the pre-zoryn behaviour (run with --commit by default):

[submit]
run = true
test_only = false

[ssh]¶

• multiplexing — enable SSH connection multiplexing via OpenSSH ControlMaster (default: true). Reuses TCP connections to the same host, reducing latency for multi-step builder operations.
• persist — how long the master connection stays alive after the last session ends (default: 2m). Uses the same time format as ssh_config(5) ControlPersist.
• Socket files are stored in $XDG_RUNTIME_DIR/zoryn/ (or $TMPDIR fallback) and cleaned up automatically on exit.

[notify]¶

• enabled — enable desktop notifications for long-running commands (default: true). Sends OSC 99 escape codes (kitty protocol) followed by BEL to stderr. Kitty, WezTerm and foot show a popup; other terminals play the bell. Notifications fire at completion of: build, up, task rebuild, task test-rebuild, task batch.

[commands]¶

• Override paths and global arguments for external commands (git, ssh, gear-*, rpm, etc.).
• Subcommands inherit from their base: git.fetch = "{git} fetch --prune" — if git is overridden, git.fetch uses the override.
• ~/ and $HOME are expanded to absolute paths.
• Shell metacharacters (;, |, `, $()) are rejected at startup.

~/.config/zoryn/builders.d/¶

Each .conf file defines one builder — a local or remote hasher machine.

# ~/.config/zoryn/builders.d/arm-server.conf
[builder]
name = "arm-server"
type = "remote"
arch = "aarch64"
branch = "sisyphus"
host = "builder-arm.internal"
hasher_dir = "~/hasher"
remote_dir = "~/build"
# hasher_number = 1  # for parallel builds (requires hasher-useradd --number=N)

[commands]
upload = "rsync -av {tarball} {host}:{remote_dir}/"
build = "hsh -v --lazy-cleanup --apt-config=$HOME/hasher_{hasher_number}.env/{branch}/apt.conf {hasher_dir} {remote_dir}/{tarball_name}"
# download uses smart download by default (only newly built packages)
cleanup = "ssh {host} \"rm -rf {remote_dir}/*\""
shell = "hsh-shell {hasher_dir}"
install = "hsh-install {hasher_dir} {packages}"

[builder]¶

• name — builder name (used for --builder).
• type — local or remote.
• arch — target architecture (x86_64, aarch64, i586, …).
• branch — target branch (sisyphus, p11, …).
• host — SSH host for remote builders.
• hasher_dir — hasher working directory (default: ~/hasher).
• remote_dir — working directory on remote host.
• hasher_number — hasher subconfig number for parallel builds.

[commands]¶

• upload — upload tarball (runs locally).
• build — build command (wrapped in SSH for remote builders).
• download — download results (runs locally). Smart by default: downloads only newly built packages via rsync --files-from. Old configs with full repo download are auto-migrated.
• list_rpms — list RPMs with mtimes in hasher repo (default: find {hasher_dir}/repo -name '*.rpm' -printf '%P\t%T@\n'). Feeds smart download.
• cleanup — cleanup command after build.
• shell — for zoryn builder shell.
• install — for zoryn builder install.
• check_busy, download_rpms, upload_rpms — auto-generated if not specified.

Variables available in command templates:

{host}, {hasher_dir}, {remote_dir}, {tarball}, {tarball_name}, {results_download_dir}, {git_root}, {packages}, {batch_repo}, {arch}, {name}, {hasher_number}, {branch}.

See zoryn builder add for the interactive and mass-creation workflows.

.gear/version-up¶

Per-package overrides for how zoryn converts upstream tags to RPM versions, where to fetch CVEs from, and merge strategy. TOML format.

[version]
pattern = "{major:+}.{minor:+}.{patch:+}"
template = "{major}.{minor}.{patch}"
strip-prefix = "v"
create-alias = true
filter = "minor=4"

[changelog]
file = "CHANGELOG.md"
# or use remote URL:
# url = "https://curl.se/docs/vuln.json"
# parser = "osv-json"
# cve-format = "extended"
# or use OSV API for projects without changelog files (e.g. Wireshark):
# parser = "osv-api"
# osv-package = "gitlab.com/wireshark/wireshark"
# osv-ecosystem = "GIT"

[merge]
use-theirs = ["meson.build", "configure.ac"]
# scheme = "git-merge"  # override auto-detection: "git-merge" or "tarball"

[tarball]
gear-update-opts = "--all"

Validate your config with zoryn check version-up.

[version] — tag → RPM version mapping¶

Placeholder format: {name:length}

• name — capture group name (e.g. major, minor, patch, year, month, day).
• length — digit count specifier:
  • + or * — one or more digits (regex [0-9]+)
  • N (number) — exactly N digits (regex [0-9]{N})

Literal characters: . matches a literal dot; -, _ match literal hyphen/underscore; any other character matches as-is.

Template field: uses captured group names without length specifier: {major}, {minor}, …

Pattern examples¶

Optional groups use standard regex (?:...)?. When the optional part is absent in the tag, the corresponding segment in the template is omitted.

Filtering tags¶

filter limits which tags are considered. filter = "minor=4" matches only tags where captured minor equals 4. Multiple filters: filter = "major=8, minor=4".

[changelog] — CVE scanning source¶

Both CVE-YYYY-NNNNN and CVE:YYYY-NNNNN (ISC format) are normalized to the standard CVE-YYYY-NNNNN. Version headers like Product X.Y.Z (status) released on Date (ISC Kea/BIND) are recognised.

• file — local changelog path (CHANGELOG.md, NEWS, ChangeLog).
• url — URL with security advisories (e.g. https://curl.se/docs/vuln.json).
• parser — parser type:
  • auto (default) — auto-detect from content.
  • osv-json / json — OSV JSON format (used by curl).
  • markdown / md — standard markdown changelog.
  • html / html-table — HTML table with CVE info.
  • osv-api — query OSV API directly (requires osv-package).
  • oracle-csaf — Oracle CSAF JSON advisory (for Oracle products like MySQL).
  • mozilla — Mozilla Foundation Security Advisories (structured YAML from mozilla/foundation-security-advisories). Use for firefox, firefox-esr, thunderbird. Anonymous GitHub API calls are rate-limited to ~60/hour.
• osv-package — package name(s) in the OSV database. Accepts a single name, comma-separated list, or TOML array. gitlab.com/wireshark/wireshark, "stdlib,toolchain", ["stdlib", "toolchain"].
• osv-ecosystem — OSV ecosystem (default: GIT; also PyPI, npm, crates.io, Go, Maven).
• oracle-advisory-product — Oracle product name for filtering (e.g. MySQL Server). Auto-detected from SRPM name if not set.
• oracle-advisory-max-body-size — max response size for CSAF download in bytes (default: ~4 MB).
• mozilla-product — Mozilla product name used to match advisory fixed_in: entries (e.g. Firefox, Firefox ESR, Thunderbird). Auto-detected from the SRPM name when omitted (firefox → Firefox, firefox-esr → Firefox ESR, thunderbird → Thunderbird).
• cve_format — CVE entry format in the RPM changelog:
  • compact (default) — inline: (Fixes: CVE-..., CVE-...).
  • compact_continuation — continuation lines with 4 CVEs per line: + (fixes: CVE-..., ...).
  • extended — multi-line with OSV descriptions: - Fixes: / * CVE-...: description.
  • With compact and an existing spec, the format is auto-detected from the prior changelog style — both + and * sub-item markers are recognised, and the detected style is preserved.

url takes precedence over file if both are set. For parser = osv-api both url and file are ignored — the OSV API is queried directly. For parser = oracle-csaf, url is optional: the latest quarterly CPU URL is generated automatically if absent. For parser = mozilla, url and file are ignored — advisories are fetched from the mozilla/foundation-security-advisories repository, scanning up to three announce/<year>/ directories back and picking the advisory whose fixed_in: list mentions <mozilla-product> <new-version>.

Finding osv-package¶

1. Open osv.dev and search for the project (e.g. wireshark, curl).
2. Open any vulnerability for that project.
3. Look at the Affected packages section — the package name is shown (e.g. gitlab.com/wireshark/wireshark for the GIT ecosystem).
4. Copy name and ecosystem into the config.

Or query the API directly:

curl -s -X POST https://api.osv.dev/v1/query \
  -d '{"package":{"name":"gitlab.com/wireshark/wireshark","ecosystem":"GIT"},"version":"4.4.3"}' \
  | python3 -m json.tool | head -20

Full list: https://ossf.github.io/osv-schema/#affectedpackage-field

[merge]¶

• scheme — override auto-detection of update scheme: "git-merge" or "tarball". Automatically set by --switch-to-upstream-git.
• use-theirs — files to take from upstream on conflict (comma/space separated). Useful for version-bearing files like meson.build, configure.ac.

[tarball]¶

• gear-update-opts — extra options for gear-update (e.g. --all to extract every directory from the archive).
• subdir — subdirectory name inside the tarball to extract (passed as gear-update --subdir=<value>). Supports {version} and {name} placeholders, e.g. subdir = "thunderbird-{version}". Useful for tarballs with multiple top-level entries like ./ and <name>-<version>/ (Mozilla source tarballs). Validated against shell metacharacters and path separators before use.

[add_changelog] — per-package override¶

• up_template — changelog entry template for zoryn up. Supports {old_version}, {new_version}, {cves}. Example: up_template = "- {old_version} -> {new_version} {cves}".

Date-based versions — example¶

[version]
pattern = "{year:4}{month:2}{day:2}"
template = "{year}.{month}.{day}"

Related¶

• Hooks — .gear/merge-up.d/, .gear/up.d/, syntax highlighting, log themes
• Sandbox — hybrid / bwrap / direct runners for hook isolation