Skip to content

Commit 82d03f1

Browse files
authored
fix(linux): lower host glibc floor to 2.28 to support RHEL/Rocky 8 (ai-openshell#1934)
1 parent ffc102a commit 82d03f1

11 files changed

Lines changed: 249 additions & 57 deletions

File tree

‎.github/workflows/driver-vm-linux.yml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -81,13 +81,13 @@ jobs:
8181
- arch: arm64
8282
runner: linux-arm64-cpu8
8383
target: aarch64-unknown-linux-gnu
84-
zig_target: aarch64-unknown-linux-gnu.2.31
84+
zig_target: aarch64-unknown-linux-gnu.2.28
8585
platform: linux-aarch64
8686
guest_arch: aarch64
8787
- arch: amd64
8888
runner: linux-amd64-cpu8
8989
target: x86_64-unknown-linux-gnu
90-
zig_target: x86_64-unknown-linux-gnu.2.31
90+
zig_target: x86_64-unknown-linux-gnu.2.28
9191
platform: linux-x86_64
9292
guest_arch: x86_64
9393
runs-on: ${{ matrix.runner }}
@@ -165,7 +165,7 @@ jobs:
165165
set -euo pipefail
166166
sed -i -E '/^\[workspace\.package\]/,/^\[/{s/^version[[:space:]]*=[[:space:]]*".*"/version = "'"${{ inputs['cargo-version'] }}"'"/}' Cargo.toml
167167
168-
- name: Build openshell-driver-vm with glibc 2.31 floor
168+
- name: Build openshell-driver-vm with glibc 2.28 floor
169169
run: |
170170
set -euo pipefail
171171
mise x -- rustup target add ${{ matrix.target }}
@@ -182,7 +182,7 @@ jobs:
182182
grep -q '^openshell-driver-vm ' <<<"$OUTPUT"
183183
184184
- name: Verify glibc symbol floor
185-
run: tasks/scripts/verify-glibc-symbols.sh 2.31 artifacts/bin/openshell-driver-vm
185+
run: tasks/scripts/verify-glibc-symbols.sh 2.28 artifacts/bin/openshell-driver-vm
186186

187187
- name: sccache stats
188188
if: always()

‎.github/workflows/release-dev.yml‎

Lines changed: 42 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -376,7 +376,7 @@ jobs:
376376
retention-days: 5
377377

378378
# ---------------------------------------------------------------------------
379-
# Build standalone gateway binaries (Linux GNU — glibc 2.31 floor)
379+
# Build standalone gateway binaries (Linux GNU — glibc 2.28 floor)
380380
# ---------------------------------------------------------------------------
381381
build-gateway-binary-linux:
382382
name: Build Gateway Binary (Linux ${{ matrix.arch }})
@@ -387,11 +387,11 @@ jobs:
387387
- arch: amd64
388388
runner: linux-amd64-cpu8
389389
target: x86_64-unknown-linux-gnu
390-
zig_target: x86_64-unknown-linux-gnu.2.31
390+
zig_target: x86_64-unknown-linux-gnu.2.28
391391
- arch: arm64
392392
runner: linux-arm64-cpu8
393393
target: aarch64-unknown-linux-gnu
394-
zig_target: aarch64-unknown-linux-gnu.2.31
394+
zig_target: aarch64-unknown-linux-gnu.2.28
395395
runs-on: ${{ matrix.runner }}
396396
timeout-minutes: 60
397397
container:
@@ -419,7 +419,7 @@ jobs:
419419
- name: Cache Rust target and registry
420420
uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2
421421
with:
422-
shared-key: gateway-binary-gnu-${{ matrix.arch }}
422+
shared-key: gateway-binary-gnu-${{ matrix.arch }}-zig-wrapper-${{ hashFiles('tasks/scripts/setup-zig-cc-wrapper.sh') }}
423423
cache-directories: .cache/sccache
424424
cache-targets: "true"
425425

@@ -429,6 +429,9 @@ jobs:
429429
set -euo pipefail
430430
sed -i -E '/^\[workspace\.package\]/,/^\[/{s/^version[[:space:]]*=[[:space:]]*".*"/version = "'"${{ needs.compute-versions.outputs.cargo_version }}"'"/}' Cargo.toml
431431
432+
- name: Set up Zig C/C++ wrappers
433+
run: tasks/scripts/setup-zig-cc-wrapper.sh ${{ matrix.zig_target }} ${{ matrix.zig_target }} /tmp/zig-gnu
434+
432435
- name: Build ${{ matrix.zig_target }}
433436
env:
434437
OPENSHELL_IMAGE_TAG: ${{ github.sha }}
@@ -452,7 +455,7 @@ jobs:
452455
fi
453456
454457
- name: Verify glibc symbol floor
455-
run: tasks/scripts/verify-glibc-symbols.sh 2.31 artifacts/bin/openshell-gateway
458+
run: tasks/scripts/verify-glibc-symbols.sh 2.28 artifacts/bin/openshell-gateway
456459

457460
- name: sccache stats
458461
if: always()
@@ -676,7 +679,7 @@ jobs:
676679

677680
smoke-linux-dev-artifacts:
678681
name: Smoke Linux Dev Artifacts (${{ matrix.name }})
679-
needs: [build-gateway-binary-linux, build-driver-vm-linux, build-deb]
682+
needs: [build-gateway-binary-linux, build-driver-vm-linux, build-deb, build-rpm]
680683
timeout-minutes: 20
681684
strategy:
682685
fail-fast: false
@@ -685,29 +688,61 @@ jobs:
685688
- name: ubuntu-22.04-deb-amd64
686689
runner: linux-amd64-cpu8
687690
image: ubuntu:22.04
691+
kind: deb
688692
artifact_arch: amd64
693+
rpm_arch: x86_64
689694
- name: ubuntu-22.04-deb-arm64
690695
runner: linux-arm64-cpu8
691696
image: ubuntu:22.04
697+
kind: deb
692698
artifact_arch: arm64
699+
rpm_arch: aarch64
700+
- name: fedora-rpm-amd64
701+
runner: linux-amd64-cpu8
702+
image: fedora:latest
703+
kind: rpm
704+
artifact_arch: amd64
705+
rpm_arch: x86_64
706+
- name: fedora-rpm-arm64
707+
runner: linux-arm64-cpu8
708+
image: fedora:latest
709+
kind: rpm
710+
artifact_arch: arm64
711+
rpm_arch: aarch64
693712
runs-on: ${{ matrix.runner }}
694713
container:
695714
image: ${{ matrix.image }}
696715
steps:
697716
- name: Download Debian package artifact
717+
if: matrix.kind == 'deb'
698718
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
699719
with:
700720
name: deb-linux-${{ matrix.artifact_arch }}
701721
path: package-input/
702722

703723
- name: Smoke Debian package on Ubuntu 22.04
724+
if: matrix.kind == 'deb'
704725
run: |
705726
set -euo pipefail
706727
apt-get update
707728
apt-get install -y --no-install-recommends ./package-input/*.deb
708-
openshell-gateway --version
729+
LD_BIND_NOW=1 openshell-gateway --version
709730
/usr/libexec/openshell/openshell-driver-vm --version
710731
732+
- name: Download RPM package artifacts
733+
if: matrix.kind == 'rpm'
734+
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
735+
with:
736+
name: rpm-linux-${{ matrix.rpm_arch }}
737+
path: package-input/
738+
739+
- name: Smoke RPM packages on Fedora
740+
if: matrix.kind == 'rpm'
741+
run: |
742+
set -euo pipefail
743+
dnf install -y ./package-input/openshell-[0-9]*.rpm ./package-input/openshell-gateway-*.rpm
744+
LD_BIND_NOW=1 openshell-gateway --version
745+
711746
# ---------------------------------------------------------------------------
712747
# Create / update the dev GitHub Release with CLI, gateway, driver, and wheels
713748
# ---------------------------------------------------------------------------

‎.github/workflows/release-tag.yml‎

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -409,7 +409,7 @@ jobs:
409409
retention-days: 5
410410

411411
# ---------------------------------------------------------------------------
412-
# Build standalone gateway binaries (Linux GNU — glibc 2.31 floor)
412+
# Build standalone gateway binaries (Linux GNU — glibc 2.28 floor)
413413
# ---------------------------------------------------------------------------
414414
build-gateway-binary-linux:
415415
name: Build Gateway Binary (Linux ${{ matrix.arch }})
@@ -420,11 +420,11 @@ jobs:
420420
- arch: amd64
421421
runner: linux-amd64-cpu8
422422
target: x86_64-unknown-linux-gnu
423-
zig_target: x86_64-unknown-linux-gnu.2.31
423+
zig_target: x86_64-unknown-linux-gnu.2.28
424424
- arch: arm64
425425
runner: linux-arm64-cpu8
426426
target: aarch64-unknown-linux-gnu
427-
zig_target: aarch64-unknown-linux-gnu.2.31
427+
zig_target: aarch64-unknown-linux-gnu.2.28
428428
runs-on: ${{ matrix.runner }}
429429
timeout-minutes: 60
430430
container:
@@ -453,7 +453,7 @@ jobs:
453453
- name: Cache Rust target and registry
454454
uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2
455455
with:
456-
shared-key: gateway-binary-gnu-${{ matrix.arch }}
456+
shared-key: gateway-binary-gnu-${{ matrix.arch }}-zig-wrapper-${{ hashFiles('tasks/scripts/setup-zig-cc-wrapper.sh') }}
457457
cache-directories: .cache/sccache
458458
cache-targets: "true"
459459

@@ -463,6 +463,9 @@ jobs:
463463
set -euo pipefail
464464
sed -i -E '/^\[workspace\.package\]/,/^\[/{s/^version[[:space:]]*=[[:space:]]*".*"/version = "'"${{ needs.compute-versions.outputs.cargo_version }}"'"/}' Cargo.toml
465465
466+
- name: Set up Zig C/C++ wrappers
467+
run: tasks/scripts/setup-zig-cc-wrapper.sh ${{ matrix.zig_target }} ${{ matrix.zig_target }} /tmp/zig-gnu
468+
466469
- name: Build ${{ matrix.zig_target }}
467470
env:
468471
OPENSHELL_IMAGE_TAG: ${{ needs.compute-versions.outputs.source_sha }}
@@ -481,12 +484,12 @@ jobs:
481484
grep -q '^openshell-gateway ' <<<"$OUTPUT"
482485
ldd artifacts/bin/openshell-gateway || true
483486
if ldd artifacts/bin/openshell-gateway | grep -q 'libz3'; then
484-
echo "gateway binary must not depend on shared libz3; build with bundled-z3" >&2
487+
echo "gateway binary must not require shared libz3; keep z3 bundled for portable release artifacts" >&2
485488
exit 1
486489
fi
487490
488491
- name: Verify glibc symbol floor
489-
run: tasks/scripts/verify-glibc-symbols.sh 2.31 artifacts/bin/openshell-gateway
492+
run: tasks/scripts/verify-glibc-symbols.sh 2.28 artifacts/bin/openshell-gateway
490493

491494
- name: sccache stats
492495
if: always()
@@ -782,10 +785,11 @@ jobs:
782785
if: matrix.kind == 'binary'
783786
run: |
784787
set -euo pipefail
788+
apt-get update
785789
mkdir -p smoke-bin
786790
tar -xzf smoke-input/openshell-gateway-${{ matrix.target }}.tar.gz -C smoke-bin
787791
tar -xzf smoke-input/openshell-driver-vm-${{ matrix.target }}.tar.gz -C smoke-bin
788-
smoke-bin/openshell-gateway --version
792+
LD_BIND_NOW=1 smoke-bin/openshell-gateway --version
789793
smoke-bin/openshell-driver-vm --version
790794
791795
- name: Download Debian package artifact
@@ -801,7 +805,7 @@ jobs:
801805
set -euo pipefail
802806
apt-get update
803807
apt-get install -y --no-install-recommends ./package-input/*.deb
804-
openshell-gateway --version
808+
LD_BIND_NOW=1 openshell-gateway --version
805809
/usr/libexec/openshell/openshell-driver-vm --version
806810
807811
- name: Download RPM package artifacts
@@ -816,7 +820,7 @@ jobs:
816820
run: |
817821
set -euo pipefail
818822
dnf install -y ./package-input/openshell-[0-9]*.rpm ./package-input/openshell-gateway-*.rpm
819-
openshell-gateway --version
823+
LD_BIND_NOW=1 openshell-gateway --version
820824
821825
# ---------------------------------------------------------------------------
822826
# Create a tagged GitHub Release with CLI, gateway, driver, and wheels

‎.github/workflows/rust-native-build.yml‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ name: Rust Image Binary Build (openshell-gateway / openshell-sandbox / openshell
77
# consumes them as prebuilt artifacts. Gateway images use GNU-linked binaries
88
# for the NVIDIA distroless C/C++ runtime; supervisor and cli images use musl/static
99
# binaries so the final image can remain scratch. Gateway GNU binaries are
10-
# built with an explicit glibc 2.31 floor so image, package, and tarball
10+
# built with an explicit glibc 2.28 floor so image, package, and tarball
1111
# artifacts share the same host portability contract.
1212

1313
on:
@@ -139,7 +139,7 @@ jobs:
139139
zig_target=x86_64-linux-musl
140140
else
141141
target=x86_64-unknown-linux-gnu
142-
zig_target=x86_64-unknown-linux-gnu.2.31
142+
zig_target=x86_64-unknown-linux-gnu.2.28
143143
fi
144144
;;
145145
arm64)
@@ -148,7 +148,7 @@ jobs:
148148
zig_target=aarch64-linux-musl
149149
else
150150
target=aarch64-unknown-linux-gnu
151-
zig_target=aarch64-unknown-linux-gnu.2.31
151+
zig_target=aarch64-unknown-linux-gnu.2.28
152152
fi
153153
;;
154154
*)
@@ -167,7 +167,7 @@ jobs:
167167
- name: Cache Rust target and registry
168168
uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2
169169
with:
170-
shared-key: rust-native-${{ inputs.component }}-${{ inputs.arch }}
170+
shared-key: rust-native-${{ inputs.component }}-${{ inputs.arch }}-zig-wrapper-${{ hashFiles('tasks/scripts/setup-zig-cc-wrapper.sh') }}
171171
cache-directories: .cache/sccache
172172
cache-targets: "true"
173173

@@ -211,6 +211,10 @@ jobs:
211211
echo "CARGO_TARGET_${TARGET_ENV_UPPER}_LINKER=/tmp/zig-musl/cc" >> "$GITHUB_ENV"
212212
echo "CARGO_TARGET_${TARGET_ENV_UPPER}_RUSTFLAGS=-Clink-self-contained=no" >> "$GITHUB_ENV"
213213
214+
- name: Set up zig glibc wrappers
215+
if: inputs.component == 'gateway'
216+
run: tasks/scripts/setup-zig-cc-wrapper.sh "${{ steps.target.outputs.zig_target }}" "${{ steps.target.outputs.zig_target }}" /tmp/zig-gnu
217+
214218
- name: Build ${{ steps.target.outputs.binary }} (${{ steps.target.outputs.zig_target || steps.target.outputs.target }})
215219
env:
216220
# Preserve the release-codegen setting used by the old Dockerfile
@@ -226,13 +230,17 @@ jobs:
226230
fi
227231
228232
mise x -- rustup target add "${{ steps.target.outputs.target }}"
233+
229234
cargo_cmd=(cargo build)
230235
build_target="${{ steps.target.outputs.target }}"
236+
args=()
237+
231238
if [[ "${{ inputs.component }}" == "gateway" ]]; then
232239
cargo_cmd=(cargo zigbuild)
233240
build_target="${{ steps.target.outputs.zig_target }}"
241+
args+=(--features bundled-z3)
234242
fi
235-
args=(
243+
args+=(
236244
--release
237245
--target "$build_target"
238246
-p "${{ steps.target.outputs.crate }}"
@@ -266,7 +274,7 @@ jobs:
266274
run: |
267275
set -euo pipefail
268276
BIN="target/${{ steps.target.outputs.target }}/release/${{ steps.target.outputs.binary }}"
269-
tasks/scripts/verify-glibc-symbols.sh 2.31 "$BIN"
277+
tasks/scripts/verify-glibc-symbols.sh 2.28 "$BIN"
270278
271279
- name: Stage binary for prebuilt layout
272280
run: |

‎architecture/build.md‎

Lines changed: 30 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -44,9 +44,11 @@ disable telemetry in a default (telemetry-enabled) build.
4444
OpenShell uses different Linux libc environments for different host artifacts.
4545
The standalone `openshell` CLI is built as a static musl binary so it can run on
4646
a wide range of Linux distributions without depending on the host's glibc. Host
47-
runtime binaries that use the GNU/Linux runtime environment, including
48-
`openshell-gateway` and `openshell-driver-vm`, are GNU-linked and built with a
49-
glibc 2.31 floor.
47+
runtime binaries that use the GNU/Linux runtime environment are GNU-linked.
48+
`openshell-gateway` and `openshell-driver-vm` are built with a glibc 2.28 floor.
49+
The gateway bundles z3 into the release binary so Linux packages, standalone
50+
tarballs, and gateway images do not depend on distro-specific z3 shared-library
51+
SONAMEs.
5052

5153
## Container Builds
5254

@@ -58,26 +60,37 @@ Dockerfile compiles Rust — both copy a staged binary out of
5860
`deploy/docker/.build/prebuilt-binaries/<arch>/` into the final image.
5961

6062
Binary staging is driven by `tasks/scripts/stage-prebuilt-binaries.sh`. Gateway
61-
binaries use `cargo zigbuild` with GNU targets pinned to glibc 2.31, including
63+
binaries use `cargo zigbuild` with GNU targets pinned to glibc 2.28, including
6264
native-architecture builds, so the gateway image, standalone tarballs, and Linux
63-
packages share the same host portability floor. Supervisor binaries remain
64-
static musl and use `cargo zigbuild` when available, including native CPU
65-
architectures, so C dependencies are compiled for the musl target instead of the
66-
host GNU libc target. Local Docker image tasks infer the target architecture from
67-
`DOCKER_PLATFORM` when set. Otherwise, they require valid container engine host
68-
metadata and fail when the engine query is unavailable or reports an unsupported
69-
architecture, avoiding host-kernel fallbacks that can target the wrong
70-
architecture. CI invokes the same staging step via the `rust-native-build.yml`
71-
workflow (per-architecture, per-component) and uploads the result as an artifact
72-
that the image build job downloads back into the staging directory before running
73-
Buildx.
65+
packages share the same host portability floor. The gateway build enables
66+
`bundled-z3`. Linux VM driver release artifacts use the same glibc floor so
67+
package-managed VM support does not raise the package runtime requirement.
68+
Gateway staging and release workflows set up the Zig C/C++ wrapper before
69+
bundled Z3 builds and verify the maximum referenced `GLIBC_*` symbol version
70+
before publishing or copying artifacts.
71+
Supervisor binaries remain static musl and use `cargo zigbuild` when available,
72+
including native CPU architectures, so C dependencies are compiled for the musl
73+
target instead of the host GNU libc target. Local Docker image tasks infer the
74+
target architecture from `DOCKER_PLATFORM` when set. Otherwise, they require
75+
valid container engine host metadata and fail when the engine query is
76+
unavailable or reports an unsupported architecture, avoiding host-kernel
77+
fallbacks that can target the wrong architecture. CI invokes the same staging
78+
step via the `rust-native-build.yml` workflow (per-architecture, per-component)
79+
and uploads the result as an artifact that the image build job downloads back
80+
into the staging directory before running Buildx.
7481

7582
Runtime layout:
7683

7784
- **Gateway**: `gcr.io/distroless/cc-debian13:nonroot` base, GNU-linked binary at
7885
`/usr/local/bin/openshell-gateway`, runs as UID/GID `1000:1000`. Linux GNU
79-
gateway and VM driver binaries must not reference `GLIBC_*` symbols newer than
80-
`GLIBC_2.31`; release workflows verify this before publishing artifacts.
86+
gateway binaries must not reference `GLIBC_*` symbols newer than
87+
`GLIBC_2.28`; release workflows verify this before publishing artifacts. The
88+
gateway bundles z3, so the image does not need a distro-provided z3 runtime.
89+
- **VM driver**: host GNU-linked binary installed at
90+
`/usr/libexec/openshell/openshell-driver-vm` in Linux packages and published
91+
as a release artifact. Linux GNU VM driver binaries must not reference
92+
`GLIBC_*` symbols newer than `GLIBC_2.28`; release workflows verify this
93+
before publishing artifacts.
8194
- **Supervisor**: `scratch` base, static musl binary at `/openshell-sandbox`.
8295
Static linkage is required because the image is mounted/extracted into
8396
sandbox environments (Docker extraction, Podman image volumes, Kubernetes

‎docs/about/installation.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ On Fedora and RHEL, the install script uses RPM packages. The RPM installs the `
5555

5656
On Debian and Ubuntu, the install script uses a Debian package. The Debian package installs the `openshell` CLI, the `openshell-gateway` daemon, VM sandbox support, and a systemd user service.
5757

58-
Linux packages require glibc 2.31 or newer. The installer checks libc before downloading packages and exits with an error on older glibc versions, Alpine, musl-based distributions, or unknown libc environments.
58+
Linux packages require glibc 2.28 or newer. The installer checks libc before downloading packages and exits with an error on older glibc versions, Alpine, musl-based distributions, or unknown libc environments.
5959

6060
The Linux user service listens on `https://127.0.0.1:17670`, starts from built-in defaults, and generates a local mTLS bundle before the gateway starts. Create `~/.config/openshell/gateway.toml` only when you need to override those defaults.
6161

0 commit comments

Comments
 (0)