_       _
| |_ ___| |_ _
|   | . | | | |
|_|_|___|_|_  |
          |___|

file man/holy.conf.5

.TH HOLY.CONF 5 "September 2026" "Holy" "File Formats"
.SH NAME
holy.conf \- Holy source configuration format
.SH 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.
.SH SYNOPSIS
.B holypkg config check FILE
.SH 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.
.PP
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.
.PP
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.
.PP
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.
.PP
[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.
.PP
[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).
.SH EXAMPLE
.nf
[general]
arch x86_64
scripts ask
[source arch]
type pacman
repo core "https://mirror.example/arch/$repo/os/$arch"
.fi
.SH FILES
/etc/holy.conf is the proposed system path. The checker takes an explicit file.
.SH 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.
.PP
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.
.PP
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.
.PP
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.
.PP
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.
.PP
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.
.PP
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.
.PP
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.