julien/apf_portal
1
0
Fork 0
Code Issues 1 Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs(setup): use ~/.bashrc hand-off instead of chsh for zsh switch #221

Merged
julien merged 1 commits from docs/setup-chsh-bashrc-fix into main 2026-05-24 19:55:33 +02:00
Conversation 0 Commits 1 Files Changed 3
+48 -30
julien commented 2026-05-24 19:45:50 +02:00
Owner
Copy Link
Copy Source

Summary

Follow-up fix on #220. The corp infra locks the default shell at user-provisioning time on the dev VM (10.100.201.21) — chsh is denied at the PAM level, so the sudo chsh -s block in 20-zsh.sh fails on every fresh VM.

Switch to the ~/.bashrc exec-zsh hand-off — the same proven pattern used in the legacy 02-wsl-terminal-setup.md. UX-identical for the dev, zero infra escalation required.

What lands

File Change
docs/setup/scripts/20-zsh.sh Drop the sudo chsh -s block. Append a guarded exec zsh -l block to ~/.bashrc instead, marked with a managed-by comment for idempotency on re-runs.
docs/setup/01-dev-debian-vm-setup.md Table row for 20-zsh.sh updated — "set as default shell" → "~/.bashrc (exec zsh on interactive shells — chsh is blocked on the corp VM)".
docs/setup/README.md Same descriptor adjustment.

The hand-off block

# Managed by docs/setup/scripts/20-zsh.sh — apf-portal zsh hand-off.
# Hand off to zsh on interactive shells. The `case $-` guard avoids
# breaking non-interactive bash (scp, rsync, cron, …), and the
# ZSH_VERSION check prevents an infinite re-exec loop.
case $- in
  *i*)
    if command -v zsh >/dev/null 2>&1 && [ -z "${ZSH_VERSION-}" ]; then
      exec zsh -l
    fi
    ;;
esac

Two safety nets in the block:

  • case $- in *i*) — only runs the hand-off when the shell flag set contains i (interactive). scp / rsync / non-interactive ssh executions go through bash and are not hijacked.
  • [ -z "${ZSH_VERSION-}" ] — ZSH_VERSION is set by zsh itself; if it's already set we're already in zsh and a re-exec would loop.

Test plan

  • On the dev VM, run 20-zsh.sh on a fresh state: bash, no existing ~/.bashrc zsh hand-off → script exits without chsh error, ~/.bashrc gets the block appended, exit + reconnect lands in zsh.
  • Re-run 20-zsh.sh → reports ↪ skip zsh hand-off already in ~/.bashrc (idempotency).
  • scp some-file vm-dev:/tmp/ from the workstation still works (non-interactive bash not hijacked).
  • pnpm exec prettier --check clean on the touched markdown files.
  • bash -n docs/setup/scripts/20-zsh.sh (syntax check) clean.

Why not amend #220

#220 has already merged. Squash-merge collapsed it to 8a04540 on main; a force-push to amend would rewrite that commit and break anyone who's pulled it. The fix lands as a separate commit on the same setup-doc family.

## Summary Follow-up fix on [#220](https://git.unespace.com/julien/apf_portal/pulls/220). The corp infra locks the default shell at user-provisioning time on the dev VM (`10.100.201.21`) — `chsh` is denied at the PAM level, so the `sudo chsh -s` block in [`20-zsh.sh`](docs/setup/scripts/20-zsh.sh) fails on every fresh VM. Switch to the `~/.bashrc` exec-zsh hand-off — the same proven pattern used in the legacy [`02-wsl-terminal-setup.md`](docs/setup/02-wsl-terminal-setup.md). UX-identical for the dev, zero infra escalation required. ## What lands | File | Change | | --- | --- | | `docs/setup/scripts/20-zsh.sh` | Drop the `sudo chsh -s` block. Append a guarded `exec zsh -l` block to `~/.bashrc` instead, marked with a managed-by comment for idempotency on re-runs. | | `docs/setup/01-dev-debian-vm-setup.md` | Table row for `20-zsh.sh` updated — "set as default shell" → "`~/.bashrc` (exec zsh on interactive shells — `chsh` is blocked on the corp VM)". | | `docs/setup/README.md` | Same descriptor adjustment. | ## The hand-off block ```bash # Managed by docs/setup/scripts/20-zsh.sh — apf-portal zsh hand-off. # Hand off to zsh on interactive shells. The `case $-` guard avoids # breaking non-interactive bash (scp, rsync, cron, …), and the # ZSH_VERSION check prevents an infinite re-exec loop. case $- in *i*) if command -v zsh >/dev/null 2>&1 && [ -z "${ZSH_VERSION-}" ]; then exec zsh -l fi ;; esac ``` Two safety nets in the block: - **`case $- in *i*)`** — only runs the hand-off when the shell flag set contains `i` (interactive). `scp` / `rsync` / non-interactive ssh executions go through bash and are not hijacked. - **`[ -z "${ZSH_VERSION-}" ]`** — `ZSH_VERSION` is set by zsh itself; if it's already set we're already in zsh and a re-exec would loop. ## Test plan - [ ] On the dev VM, run `20-zsh.sh` on a fresh state: bash, no existing `~/.bashrc` zsh hand-off → script exits without `chsh` error, `~/.bashrc` gets the block appended, `exit` + reconnect lands in zsh. - [ ] Re-run `20-zsh.sh` → reports `↪ skip zsh hand-off already in ~/.bashrc` (idempotency). - [ ] `scp some-file vm-dev:/tmp/` from the workstation still works (non-interactive bash not hijacked). - [x] `pnpm exec prettier --check` clean on the touched markdown files. - [x] `bash -n docs/setup/scripts/20-zsh.sh` (syntax check) clean. ## Why not amend #220 #220 has already merged. Squash-merge collapsed it to `8a04540` on main; a force-push to amend would rewrite that commit and break anyone who's pulled it. The fix lands as a separate commit on the same setup-doc family.
julien added 1 commit 2026-05-24 19:45:51 +02:00
docs(setup): use ~/.bashrc hand-off instead of chsh for zsh switch
CI / commits (pull_request) Successful in 3m1s
Details
CI / check (pull_request) Successful in 3m11s
Details
CI / scan (pull_request) Successful in 3m17s
Details
CI / a11y (pull_request) Successful in 3m23s
Details
Docs site / build (pull_request) Successful in 3m42s
Details
CI / perf (pull_request) Successful in 5m11s
Details
5821c60195 
chsh is blocked on the corp dev VM (PAM-level restriction at user-
provisioning time). Drop the sudo chsh -s call from 20-zsh.sh and
append a guarded `exec zsh -l` block to ~/.bashrc instead — same UX
without needing infra escalation, also matches the legacy WSL setup
pattern in 02-wsl-terminal-setup.md.

The hand-off is guarded by `case $- in *i*)` so non-interactive bash
flows (scp, rsync, cron) are unaffected, and by a ZSH_VERSION absence
check to prevent re-exec loops.

Main doc and README table descriptions updated to match.
julien merged commit c77313c693 into main 2026-05-24 19:55:33 +02:00
julien deleted branch docs/setup-chsh-bashrc-fix 2026-05-24 19:55:33 +02:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adastra-bot (AdAstra Bot) julien (Julien Gautier)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: julien/apf_portal#221
Delete Branch "docs/setup-chsh-bashrc-fix"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?