holy.conf(5)

NAME

holy.conf - Holy source configuration format

STATUS

This page describes the syntax checker and source identity registration. A registered holy-http source can mirror one explicitly pinned or explicitly accepted unsigned current index through holypkg sync. A registered holy-git source uses a pinned commit and index digest. A source with an Ed25519 public key verifies signed generations. General multi-source resolution and full disk installation are not implemented; the restricted local data/static-ELF transaction uses separate commands.

SYNOPSIS

holypkg config check FILE

DESCRIPTION

Input must be UTF-8. Each record contains a key and whitespace-separated arguments. Double quotes retain spaces. A hash sign at the start of a token begins a comment outside quotes. Escapes are backslash-quote, double-backslash, backslash-n, backslash-t, backslash-r and backslash-x followed by two hexadecimal digits. NUL is rejected. The parser does not run shell expansion.

Sections are [general], [resolver], [source NAME], [rule NAME], [install] and [disk]. [install-plan], [disk-plan] and [disk-finalize-plan] are emitted by holyinstall and are not user config sections. Include takes one path relative to the containing file. Repeated scalar keys within a section are errors with both source locations. The source repo and resolver prefer and install artifact keys are lists and can repeat. Recursive includes are rejected. The checker validates lexical and structural syntax; it does not yet validate rule references. It checks that source parents exist and do not form cycles. It rejects userinfo in URL authorities without echoing credentials in diagnostics. It validates key names, argument counts, and the scripts, trust, ask-sources and prefer values. The alias local is reserved and cannot name a source.

Each populated source section requires type and at least one url or repo. Repository names within one source must be distinct. Each populated rule requires consumer, require and provider. Empty values are rejected. These checks do not prove that a repository is reachable or its packages can resolve.

For holy-http and holy-git, "public-key PATH" names an Ed25519 PEM public key. The path is relative to the file containing that entry. source plan reads it and freezes the raw 32-byte public key in the reviewed registry plan; source apply does not reopen the PEM file. "public-key-ed25519 HEX" supplies those bytes as 64 lowercase hex digits. Only one form is allowed. trust require needs a key for either native source type. A configured key requires signed catalogs for sync, binding and later source queries even when trust is warn. Private signing keys are not configuration inputs.

[install] accepts one root directory and ordered artifact SHA-256 entries for holyinstall's pre-mounted-root package transaction. The first artifact is the explicit package. The installer checks required fields, digest syntax and duplicate artifacts before planning. See holyinstall(8). An addressable accept-arch list can approve placement of selected artifacts with a different target architecture. The frozen plan retains each approval. An accept-privileged list confirms the exact artifact hashes whose setuid executables have been reviewed. holyinstall records these decisions in its frozen plan and passes them to holypkg. The list key "source ARTIFACT_SHA256 SOURCE_ID" associates a selected local artifact with an active registered origin. The installed instance retains the source ID and alias snapshot; metadata inside the archive grants no source authority.

[disk] accepts one image path and layout gpt-ext4. The disk plan accepts regular image files, not block devices. Its fixed plan schema forbids include. The installer's text menu can save [disk] alongside [install] and prepare the disk plan independently of package selection. See holyinstall(8).

EXAMPLE

[general]
arch x86_64
scripts ask
[source arch]
type pacman
repo core "https://mirror.example/arch/$repo/os/$arch"

FILES

/etc/holy.conf is the proposed system path. The checker takes an explicit file.

SOURCE IDENTITIES

The source plan command reads this syntax, including includes, and proposes a registry replacement. The source apply command consumes that frozen plan; it does not reread the configuration. See holypkg(8) for the command sequence.

The current source ID is SHA-256 of a canonical, sorted representation of type, url and repo records. Alias, parent, family, priority, trust policy and public key are excluded. Renaming an alias preserves the ID. Changing an endpoint, backend type or repository name creates another ID and retains the previous definition as inactive history. Readding the same definition reactivates its existing ID. Equivalent URL spellings and mirrors are not automatically identified as one source.

Registration requires endpoints with a scheme followed by :// and rejects URL userinfo, queries, fragments and whitespace. Plans therefore cannot carry those credential forms. Two aliases with the same definition require a decision. Registration neither contacts a repository nor verifies its signatures. Set installation can bind local artifacts to registered IDs through explicit --source associations. The registry stores parent as a source-id, separate from the endpoint-derived identity. Renaming a parent alias retains the relationship. Parent preference applies when add discovers a missing native provider; it does not replace the child's URL with the parent's URL.

Optional family NAME groups sources for dependency preference. Optional priority SIGNED_INTEGER ranks candidates within the same preference group; a larger number wins. The default priority is zero. Family and priority are policy, not part of source identity. A changed policy is recorded by source apply. holypkg source show ALIAS displays the policy after apply.

A registered APK source uses type apk and one or more repo NAME HTTPS_BASE/ entries. holypkg apk sync names the repo, obtains its APKINDEX.tar.gz and writes a source-id-bearing catalog and target-root binding. public-key points to an RSA PEM public key for APK sources; source plan freezes its SHA-256 fingerprint. trust require needs that key and a valid APKINDEX signature. The matching key file is supplied to apk sync and apk fetch through --public-key. Fetch verifies the bound APK package signature with the same registered key. See holypkg(8) for the digest confirmation and fetch sequence.

A registered APT source uses type apt and one url HTTPS_BASE/. public-key points to a binary OpenPGP keyring; source plan freezes its SHA-256. trust require needs that key. holypkg apt sync-source requires the same keyring and records the stable source-id in its signed catalog and database binding. Queries and fetches can select it with source, suite, component and index architecture; they recheck the current registry. The keyring is selected by the user; adding a source does not import public keys from the network. The --inrelease option selects a clearsigned InRelease; without it sync-source uses Release and Release.gpg.

A registered RPM-MD source uses type rpm-md and one url HTTPS_BASE/, with no repo entries. The base is the repository root that serves repodata/repomd.xml. holypkg sync RPM_MD_SOURCE takes an explicit repomd --sha256 pin and records the source-id in the catalog it writes. No repository signature is checked, so trust require is not available for this backend. Query, capability lookup and fetch select the source by alias and recheck the registered url and source-id against the stored catalog.

A registered XBPS source uses type xbps and one url HTTPS_BASE/. public-key points to an RSA PEM public key; source plan freezes the SHA-256 fingerprint of its public-key encoding. trust require needs that key. xbps sync-source checks the selected key against the registry and the index metadata. It also requires an explicit repodata SHA-256 pin. Source-aware queries check the catalog's source-id, URL and recorded key fingerprint. Fetch requires the same key file and verifies the package .sig2 signature. sync-source also binds the catalog's conversion digest under the target database; later queries can select that binding by source and index architecture.