fips/packaging/aur

AUR Publication Guide for FIPS

This directory contains Arch Linux packaging files for two AUR packages:

• fips -- release package, builds from a tagged GitHub tarball
• fips-git -- development package, builds from latest git master

Overview

Files in This Directory

File	Purpose
PKGBUILD	Release package build script (builds from tagged tarball)
PKGBUILD-git	Git development package build script (builds from latest master)
fips.install	Pacman post-install/post-upgrade messaging
fips.sysusers	sysusers.d fragment (creates fips system group)
fips.tmpfiles	tmpfiles.d fragment (creates /run/fips/)
fips.service	Symlink to ../debian/fips.service
fips-dns.service	Symlink to ../debian/fips-dns.service
build-aur.sh	Local fips-git build plus namcap validation (run by make aur)
patch-pkgbuild.sh	Rewrites pkgver, pkgrel, conflicts, options, and b2sums in the PKGBUILD at publish time
await-package-runs.sh	Holds the AUR publish until every package-*.yml run for the release tag has succeeded
test-await-package-runs.sh	Fixture tests for await-package-runs.sh, run by the aur-build job
namcap-gate.sh	Fails the aur-build job on namcap error-level findings; warnings are advisory
test-namcap-gate.sh	Fixture tests for namcap-gate.sh with canned namcap output, plus --live against real namcap; both run by the aur-build job

Both PKGBUILDs reference files from packaging/debian/ (service files) and packaging/common/ (config files) at build time. These are pulled from the source tree during package(), not from this directory.

What Gets Installed

Both PKGBUILDs install the same payload, kept at parity with the Debian package:

• Binaries: fips, fipsctl, fipstop, fips-gateway
• Systemd units: fips.service, fips-dns.service, fips-gateway.service, fips-firewall.service
• DNS helpers: /usr/lib/fips/fips-dns-setup, /usr/lib/fips/fips-dns-teardown
• Config: /etc/fips/fips.yaml, /etc/fips/hosts, /etc/fips/fips.nft
• sysusers/tmpfiles fragments for the fips group and /run/fips/

The fips.nft baseline is shipped as a conffile (listed in backup=()) so operator edits to the nftables ruleset survive package upgrades. fips-firewall.service is shipped disabled by default, matching the Debian package: operators opt in by enabling it explicitly.

Both PKGBUILDs opt out of makepkg's automatic *-debug split packages. The package metadata still conflicts with stale peer debug package names (fips-debug / fips-git-debug) so switching between release and development variants removes old debug-file owners cleanly.

Local Build and Validation

Build and validate the -git package locally using the Makefile target:

make -C packaging aur

This runs makepkg -sf followed by namcap on the resulting package.

For manual testing of individual steps:

# Build the -git package (uses local git clone, no network download needed)
cd packaging/aur
makepkg -sf -p PKGBUILD-git

# Lint the built package
namcap fips-git-*.pkg.tar.zst

# Lint the PKGBUILD itself
namcap PKGBUILD-git

The -git variant builds from the local git clone, so no network download is needed for the source. The release PKGBUILD requires a tagged release tarball on GitHub to build and cannot be tested without one.

Prerequisites for AUR Publication

1. AUR Account

Register at https://aur.archlinux.org/register/ using the maintainer email (jcorgan@corganlabs.com).

2. SSH Key

Generate a dedicated ed25519 key for AUR access:

ssh-keygen -t ed25519 -f ~/.ssh/aur -C "jcorgan@corganlabs.com" -N ""

3. SSH Config

Add the following to ~/.ssh/config:

Host aur.archlinux.org
    IdentityFile ~/.ssh/aur
    User aur

4. Register the Key with AUR

1. Copy the public key contents:

   cat ~/.ssh/aur.pub
   

2. Go to https://aur.archlinux.org -> My Account -> SSH Public Key
3. Paste the public key and save

5. Test the Connection

ssh -T aur@aur.archlinux.org

This should print a welcome message or your username. If it hangs or returns "Permission denied", verify that the key was added correctly.

Initial Push -- fips-git Package

Follow these steps exactly. Each command is concrete and copy-pasteable.

Step 1: Clone the AUR Repo

Cloning an AUR repo that does not yet exist creates the package entry:

git clone ssh://aur@aur.archlinux.org/fips-git.git /tmp/aur-fips-git

If the package does not exist yet, this creates an empty repository.

Step 2: Copy Required Files

From the root of the fips source repository:

cp packaging/aur/PKGBUILD-git /tmp/aur-fips-git/PKGBUILD
cp packaging/aur/fips.install /tmp/aur-fips-git/
cp packaging/aur/fips.sysusers /tmp/aur-fips-git/
cp packaging/aur/fips.tmpfiles /tmp/aur-fips-git/

Only PKGBUILD, .SRCINFO, and files referenced in source=() or install= go into the AUR repo. Service files and config files are NOT copied -- they come from the source tree at build time via the source=() git clone.

Step 3: Generate .SRCINFO

This step is critical -- AUR requires .SRCINFO alongside every PKGBUILD:

cd /tmp/aur-fips-git
makepkg --printsrcinfo > .SRCINFO

Step 4: Commit and Push

cd /tmp/aur-fips-git
git add PKGBUILD .SRCINFO fips.install fips.sysusers fips.tmpfiles
git commit -m "Initial import of fips-git"
git push

Step 5: Verify

Visit https://aur.archlinux.org/packages/fips-git -- the package should appear within a few seconds of the push.

Initial Push -- fips Release Package

Same pattern as the -git package, but using the release PKGBUILD.

Step 1: Clone the AUR Repo

git clone ssh://aur@aur.archlinux.org/fips.git /tmp/aur-fips

Step 2: Copy Files

From the root of the fips source repository:

cp packaging/aur/PKGBUILD /tmp/aur-fips/PKGBUILD
cp packaging/aur/fips.install /tmp/aur-fips/
cp packaging/aur/fips.sysusers /tmp/aur-fips/
cp packaging/aur/fips.tmpfiles /tmp/aur-fips/

Step 3: Verify the Release PKGBUILD

Before pushing, ensure the PKGBUILD is correct for the current release:

1. Verify pkgver matches the latest tagged release. The checked-in value is a placeholder; patch-pkgbuild.sh rewrites it at publish time
2. If the tarball b2sum is a placeholder, download the tarball and compute:

   curl -sL https://github.com/jmcorgan/fips/archive/v<VERSION>.tar.gz | b2sum | cut -d' ' -f1
   

3. Update the first entry in b2sums=() in the PKGBUILD with the real hash

Step 4: Generate .SRCINFO

cd /tmp/aur-fips
makepkg --printsrcinfo > .SRCINFO

Step 5: Commit and Push

cd /tmp/aur-fips
git add PKGBUILD .SRCINFO fips.install fips.sysusers fips.tmpfiles
git commit -m "Initial import of fips <VERSION>"
git push

Step 6: Verify

Visit https://aur.archlinux.org/packages/fips -- the package should appear.

Verification

After both packages are pushed, verify everything works end-to-end.

Search AUR

yay -Ss fips

Or visit https://aur.archlinux.org/?K=fips in a browser.

Install the Git Variant

yay -S fips-git

Verify the Installation

fips --version
fipsctl --version
fipstop --version
systemctl cat fips.service
cat /usr/lib/sysusers.d/fips.conf
cat /usr/lib/tmpfiles.d/fips.conf

Test the Release Variant

On a separate machine or after removing fips-git:

yay -R fips-git
yay -S fips

Then run the same verification commands above.

GitHub Secrets for CI

AUR publication is automated: .github/workflows/aur-publish.yml pushes the release package, and aur-publish-git.yml pushes fips-git. The manual steps above are the fallback for when the workflow cannot be used. The automation needs a separate SSH key.

Step 1: Generate a CI-Specific Key

Generate a separate passphrase-less ed25519 key for CI. Do NOT reuse the personal key from the prerequisites section:

ssh-keygen -t ed25519 -f /tmp/github-aur -C "github-actions-aur" -N ""

Step 2: Add the Public Key to AUR

AUR supports multiple SSH keys per account. Add the contents of /tmp/github-aur.pub to the AUR account alongside the personal key:

1. Go to https://aur.archlinux.org -> My Account -> SSH Public Key
2. Paste the new public key (you can have multiple keys, one per line)

Step 3: Add the Private Key to GitHub

1. Go to https://github.com/jmcorgan/fips/settings/secrets/actions
2. Create a new repository secret named AUR_SSH_PRIVATE_KEY
3. Paste the contents of /tmp/github-aur (the private key file)

Step 4: Clean Up Local Key Files

rm /tmp/github-aur /tmp/github-aur.pub

Updating Packages

fips-git (Development)

AUR convention is to only push when the PKGBUILD itself changes (new dependencies, build flags, source URL changes, etc.). Users get new builds automatically via:

yay -Syu --devel

Do NOT push pkgver-only bumps to the AUR -- the pkgver() function handles versioning at build time.

fips (Release)

Push an update when a new version is tagged. The steps are:

1. Update pkgver in the PKGBUILD to the new version
2. Reset pkgrel to 1
3. Recompute the tarball b2sum:

   curl -sL https://github.com/jmcorgan/fips/archive/v<NEW_VERSION>.tar.gz | b2sum | cut -d' ' -f1
   

4. Update b2sums=() with the new hash
5. Regenerate .SRCINFO:

   makepkg --printsrcinfo > .SRCINFO
   

6. Commit and push both PKGBUILD and .SRCINFO

The AUR Publish workflow performs these steps automatically on a new GitHub release; run them by hand only as a fallback.

For a packaging-only republish of an existing release tag, run the AUR Publish workflow manually with the existing tag and incremented pkgrel (for example, tag=v0.3.0, pkgrel=2). This keeps the upstream source tarball unchanged while forcing AUR helpers to rebuild with the corrected package metadata.