Skip to content
zoryn/ maintainer-assistant

zoryn builder

Manage build machines (local and remote hasher setups).

Synopsis

zoryn builder <subcommand>

Subcommands

  • list [--simple] — list available builders (--simple for names only, one per line).
  • status — check builder availability (free/busy).
  • config [NAME] — show full builder configuration including defaults.
  • shell [--builder=NAME] — open shell in hasher.
  • install [--builder=NAME] PKG... — install packages in hasher.
  • run [BUILDER] [--rooter] [--execute=PATH] -- CMD [ARGS] — run a command in hasher chroot.
  • add [options] — add a new builder configuration (interactive or non-interactive).
  • remove NAME [-y] — remove a builder configuration (the built-in local cannot be removed).
  • copy SRC... DST — copy files into or out of hasher chroot (use builder:path for chroot paths).
  • clean [--all|--all-local|--all-remote] [NAME...] — clean hasher chroot and auxiliary directories.

zoryn builder add

Options:

  • --name=NAME — builder name (required for non-interactive mode).
  • --type=TYPE — builder type: local or remote (default: remote).
  • --host=HOST — remote host (SSH alias). Required for remote builders.
  • --arch=ARCH — target architecture. Auto-detected from host if not specified.
  • --hasher-dir=DIR — hasher directory. Without --multi-add: path as-is (default: ~/hasher). With --multi-add: template with {hasher_number} placeholder (default: ~/hasher_{hasher_number}, e.g. /tmp/h_{hasher_number}).
  • --remote-dir=DIR — remote build directory (default: ~/build).
  • --description=TEXT — human-readable description.
  • -n, --number=N — hasher number for parallel builds (1–128).
  • --based=NAME — copy settings from an existing builder as defaults.
  • --repo=PATH — repository path or URL for local apt config management. Can be repeated for --multi-add (branch is auto-detected from each repo's release file). Generates apt.conf, sources.list, and preferences locally and syncs to the builder before each build. Local paths are auto-prefixed with file:///.
  • --multi-add=N — create N builders per branch with sequential hasher numbering. Requires at least one --repo (branches are auto-detected).
  • --start-number=M — start hasher numbering from M (default: 1). Used with --multi-add.
  • --dry-run — preview planned builders without creating them. Used with --multi-add.
  • --force — overwrite existing builder configs. Used with --multi-add.
  • --apt-conf=PATH — alternative apt.conf (instead of /etc/apt/apt.conf). Supports host:path syntax for reading from remote hosts via SSH.
  • --sources-list=PATH — alternative sources.list (overrides the path from apt.conf). Supports host:path.
  • --no-create-hasher-users — do not create hasher satellite users (by default they are created via sudo hasher-useradd).
  • -y, --yes — auto-confirm, don't ask for confirmation.

Local apt config with --repo

Instead of configuring apt on the builder host, specify a repository with --repo:

zoryn builder add arm-server --host arm.local --repo /home/repo/p11

This generates apt configuration (apt.conf, sources.list, preferences) locally in ~/.config/zoryn/builders.d/{name}/apt/ and syncs it to the builder before each build. The branch is auto-detected from the repository's release file.

In interactive mode, the repository is prompted with TAB completion for both local and remote filesystem paths. The default value is auto-detected from the builder host's /etc/apt/sources.list. The branch is then auto-detected from the repository.

The --repo flag accepts:

  • Local paths: /path/to/repo (auto-prefixed with file:///).
  • HTTP/HTTPS URLs: http://example.com/repo or https://example.com/repo.

Manual overrides (--apt-conf, --sources-list) have higher priority than --repo.

Mass builder creation

# Create 5 builders for two branches (10 total, branches auto-detected from repos)
zoryn builder add --name node1 --host user@server --multi-add 5 \
  --repo /srv/repo/p11 --repo /srv/repo/sisyphus -y

# Preview without creating
zoryn builder add --name node1 --host user@server --multi-add 3 \
  --repo /srv/repo/p11 --dry-run

# Start numbering from 10
zoryn builder add --name node1 --host user@server --multi-add 5 \
  --repo /srv/repo/p11 --start-number 10 -y

Hasher user creation

By default, builder add automatically creates hasher satellite users via sudo hasher-useradd if they don't exist. This requires passwordless sudo on the builder host. Use --no-create-hasher-users to skip creation.

Examples

zoryn builder list                  # list all builders
zoryn builder list --simple         # list builder names only (for scripts)
zoryn builder list -a x86_64        # filter by architecture
zoryn builder list --host local     # show only local builders
zoryn builder list -a i586 -B p10   # combine filters
zoryn builder status                # show status of all builders
zoryn builder status -b shell64     # show status of specific builder
zoryn builder config                # show default local builder config
zoryn builder config arm-server     # show config for specific builder
zoryn builder shell                 # open shell in default builder's hasher
zoryn builder shell -b arm-server   # open shell on remote builder
zoryn builder run -- rpm -qa             # run command in default builder's hasher
zoryn builder run my-builder -- ls -la   # run command on specific builder
zoryn builder run --rooter -- cat /etc/shadow  # run as pseudoroot
zoryn builder run --execute=./setup.sh   # execute script in hasher
zoryn builder install vim nano      # install packages in hasher
zoryn builder copy ./file.c mybuilder:src/  # copy file into builder chroot
zoryn builder copy mybuilder:build.log ./   # copy file from builder chroot
zoryn builder add                   # interactively create new builder
zoryn builder add --based shell64   # create builder based on existing one
zoryn builder add --name arm --host myserver -y  # non-interactive with auto-detection
zoryn builder add --name local-i586 --type local --arch i586 -y    # local builder
zoryn builder add --name arm --host user@myserver --number 3 -y     # auto-creates hasher users
zoryn builder add --name arm --host user@myserver --number 3 --no-create-hasher-users -y
zoryn builder add --name p11 --host myserver --repo /home/repo/p11 -y  # local apt config from repo
zoryn builder add --name nfs --type local --apt-conf /etc/apt-nfs/apt.conf -y  # custom apt config
zoryn builder add --name p11 --host mybuilder --apt-conf mybuilder:apt/p11/apt.conf -y
zoryn builder remove mybuilder      # remove builder (with confirmation)
zoryn builder remove mybuilder -y   # remove builder without confirmation
zoryn builder clean local           # clean specific builder
zoryn builder clean --all-local     # clean all local builders
zoryn builder clean --all           # clean all builders
zoryn builder clean --all --dry-run # preview what would be cleaned