AGENTS.md

What this repo is

Shell scripts to backport and build OpenSSH RPMs for CentOS/RHEL-like distros (EL5 through EL9, also Rocky, AlmaLinux, Anolis, UOS, openEuler, Amazon Linux).

Essential commands

# Download source tarballs into downloads/
./pullsrc.sh

# Build RPMs (auto-detects the EL version from the running system)
./compile.sh

# Force a specific EL target (useful on non-RPM build hosts like Docker/Ubuntu)
./compile.sh el7

# Docker-based build (see docker/README.md for per-version commands)
docker build -t elssh:el8 -f ./docker/Dockerfile.centos-stream --build-arg VERSION_NUM=8 .
docker run --rm -v .:/data elssh:el8

Configuration

version.env — source versions (OpenSSH, OpenSSL, Perl). Committed.
version-local.env — user overrides like PKGREL, WITH_OPENSSL. Gitignored (*-local*).
compile.sh sources version.env then version-local.env (if present), so version-local.env wins.

Key variables

WITH_OPENSSL: 0 = no OpenSSL (no ssh-rsa keys), 1 = system OpenSSL, 2 = static OpenSSL. Only the el7 spec dir (covering EL7/8/9) auto-detects in compile.sh TOPDIR_SELECT: system OpenSSL >= 3 -> 1, else 2. EL5/EL6 leave it unset and rpmbuild falls back to 2 via ${WITH_OPENSSL:-2}. Note docker/docker_compile.sh has its own overlapping auto-detect (checks openssl-devel presence + version), so behavior inside Docker may differ from a direct ./compile.sh run.
PKGREL: package release number (defaults to 1)
M32=1: build 32-bit RPMs (EL5 only)
DOCKERBUILD=1: when set, pullsrc.sh skips the openssh/openssl/askpass downloads but still fetches PERLSRC
UOS20=1: build the UOS 20 variant — enables the kernel-panic patch (openssh-uos20-kernel-panic-fix.patch) and prefixes PKGREL with uos20. so resulting RPMs are distinguishable.

Architecture notes

EL8 and EL9 both use el7/ as the spec directory, since they share systemd. compile.sh GUESS_DIST returns el7 for all versions >= EL7.
EL6 uses el6/ (SysVinit).
EL5 uses el5/ (SysVinit, requires Perl bootstrap for building OpenSSL).
Supported architectures: x86_64 for all EL versions; aarch64 for EL7/8/9 and UOS20 via per-arch tags (aarch64_el7, aarch64_el8, aarch64_el9). Docker tags are per-arch (e.g. ghcr.io/boypt/openssh-rpms:aarch64_el7), not multi-arch manifests.
WITH_OPENSSL auto-detection: for el7 (which covers EL7/8/9), if system OpenSSL >= 3, defaults to 1 (system), otherwise 2 (static).
compile.sh has subcommands: GETEL (print detected distro), GETRPM (list RPM paths), RPMDIR (print RPM output dir).
el7/SPECS/ has two spec files: openssh.spec (default, systemd) and openssh.initv.spec (SysVinit). The default spec is selected via SPECFILE env var. The UOS 20 build uses the default spec with UOS20=1.
docker/docker_compile.sh is the entrypoint inside Docker images — it copies the appropriate el* dir to /BUILD and runs compile.sh against it.
docker/modify_vault_source.sh handles vault mirrors; for aarch64 it appends /altarch (CentOS AltArch vault, e.g. .../centos-vault/altarch/7.9.2009/). For EL5 EPEL always uses http://mirrors.aliyun.com/epel-archive (avoids Python 2.4 TLS 1.0 → 302 → https failure on archives.fedoraproject.org).

CI

.github/workflows/build-images.yml — manually triggered (workflow_dispatch), builds Docker images and pushes to ghcr.io. Matrix: build-amd64 (5 images: el5, el6, el7, el8, el9 on ubuntu-latest) + build-arm64 (3 images: aarch64_el7, aarch64_el8, aarch64_el9 on ubuntu-latest with setup-qemu-action + platforms: linux/arm64). Cache: type=gha.
.github/workflows/build-rpm.yml — runs on v* tags, builds RPMs inside Docker containers and creates a GitHub release. Jobs: build-arm64 (ubuntu-24.04-arm, natively runs aarch64_* images), build-amd64 (ubuntu-latest), build-el5 (ubuntu-latest, handles m32 for i686). Final release needs all three and zips artifacts as openssh_<tag>_<artifact>.zip.

Linting & formatting

All shell scripts (*.sh) must pass shellcheck and shfmt before committing:

# Lint (warnings are errors)
shellcheck -S warning compile.sh pullsrc.sh

# Format check (must produce no diff)
shfmt -d -i 0 -bn -ci compile.sh pullsrc.sh

# Auto-fix formatting in-place
shfmt -w -i 0 -bn -ci compile.sh pullsrc.sh

shellcheck -S warning: treat warnings as failures; informational/style notes may be suppressed inline with # shellcheck disable=SCxxxx.
shfmt -i 0 -bn -ci: tabs for indentation (no extra indent), binary operators (&&, ||, |) at start of next line, case body indented.
Both tools must exit 0 before any commit touching *.sh files.

Gitignore

*-local* is gitignored — version-local.env, editor swap files, etc. *.tar.gz is gitignored everywhere, including downloads/. Generated RPMs go to output/ (also gitignored).

Version bump workflow

When the user says "update to <version>" (e.g. "update to 10.5", "update to 10.6p1"), perform the following steps autonomously. Only update README.md and version.env — do not touch other files unless explicitly asked.

Normalize the version: append p1 if not already present (all portable releases use p1). E.g. 10.5 → 10.5p1.
Update version.env: change the OPENSSHSRC line to openssh-<version>.tar.gz. OPENSSHVER is derived automatically from OPENSSHSRC. Do NOT change OPENSSLSRC/OPENSSLVER or any other line unless the user explicitly asks.
Update README.md: in the "Current Version" section, update only the OpenSSH version line. Leave the OpenSSL line unchanged.

Determine the next build number:

TAG_PREFIX="v${NEW_VERSION}_b"
BUILD_NUM=$(git tag | grep "^${TAG_PREFIX}" | sed "s/^${TAG_PREFIX}//" | sort -n | tail -1)
BUILD_NUM=$(( ${BUILD_NUM:-0} + 1 ))

Commit and tag (do not push yet):

git add version.env README.md
git commit -m "bump: OpenSSH ${NEW_VERSION}_b${BUILD_NUM}"
git tag "v${NEW_VERSION}_b${BUILD_NUM}"

Ask the user for confirmation to push to remote. This is the only confirmation needed — do not ask about file changes, commit message, tag name, or anything else.
After pushing, the tag triggers .github/workflows/build-rpm.yml which builds RPMs for all EL versions and creates a GitHub release. Monitor CI using gh commands and report the status:
```
gh run list --limit 5
gh run watch    # watch the latest run to completion
```

6.5 KiB Raw Blame History