fix: rewrite ssh-agent-setup skill v1.1.0 — correct tier hierarchy
- Tier 1 (NEW): agent launcher via ~/.profile (FreeBSD) or systemd --user (Linux). AddKeysToAgent does NOT start an agent; without a launcher the "Could not open connection" error still fires on headless shells. - Tier 2 (was Tier 2): AddKeysToAgent yes + ForwardAgent no in ~/.ssh/config. Unchanged, sound. - Tier 3 (FIXED): tmux.conf UI prefs only. Removed update-environment override — set -g replaces entire list, dropping DISPLAY/XAUTHORITY. tmux default already includes SSH_AUTH_SOCK. - Emergency fix section (was Tier 1): renamed, kept as manual revive. --- Build: pass | Tests: FAIL — 1 failed
This commit is contained in:
Sam & Hermes
parent
d0c489a418
commit
9b6b8bb4aa
1 changed files with 92 additions and 40 deletions
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
name: ssh-agent-setup
|
||||
description: "Fix SSH agent failures (Could not open connection), configure persistence across tmux sessions, and set up AddKeysToAgent."
|
||||
version: 1.0.0
|
||||
version: 1.1.0
|
||||
platforms: [linux, freebsd]
|
||||
---
|
||||
|
||||
|
|
@ -12,8 +12,12 @@ platforms: [linux, freebsd]
|
|||
SSH agent does not survive tmux session restarts or new terminal windows by
|
||||
default. When an agent dies, every `ssh`, `git push`, or `git pull` that
|
||||
needs the key fails with `Could not open a connection to your authentication
|
||||
agent`. This skill documents the three-tier fix: revive a dead agent,
|
||||
auto-load keys on first use, and persist the agent across tmux windows.
|
||||
agent`. This skill documents the fix: a three-tier approach (launcher,
|
||||
auto-load, terminal preferences) plus an emergency revive procedure.
|
||||
|
||||
**Platform note:** FreeBSD has no systemd. Use `~/.profile` to start the
|
||||
agent on login. On Linux with systemd, a `systemd --user` service is an
|
||||
alternative but the profile approach works universally.
|
||||
|
||||
## When to Use
|
||||
|
||||
|
|
@ -32,12 +36,12 @@ auto-load keys on first use, and persist the agent across tmux windows.
|
|||
| Private key (no `.pub`) | Never paste, never transit through chat, never leave the host. |
|
||||
| `ssh-add` on local key | Safe — reads key already on disk, loads into memory, never transmits. |
|
||||
|
||||
## Tier 1 — Revive a Dead Agent (immediate fix)
|
||||
## Emergency Fix — Revive a Dead Agent
|
||||
|
||||
After a tmux session restart where the agent died:
|
||||
When `ssh-add -l` returns "Could not open a connection to your
|
||||
authentication agent":
|
||||
|
||||
```sh
|
||||
# Start the agent and load keys
|
||||
eval $(ssh-agent -s)
|
||||
ssh-add ~/.ssh/<keyname>
|
||||
```
|
||||
|
|
@ -51,55 +55,93 @@ ssh -T git@codeberg.org
|
|||
# Should return "Hi there, ... successfully authenticated"
|
||||
```
|
||||
|
||||
## Tier 2 — Auto-load Keys on First Use (persistent fix)
|
||||
## Tier 1 — Start Agent on Login (the missing prerequisite)
|
||||
|
||||
`AddKeysToAgent yes` adds a key to a running agent — it does NOT start one.
|
||||
If `SSH_AUTH_SOCK` is unset (headless login, SSH-in, non-graphical shell),
|
||||
the error still fires.
|
||||
|
||||
**FreeBSD (no systemd):** Seed `~/.profile`:
|
||||
|
||||
```sh
|
||||
# Start SSH agent if not already running
|
||||
if [ -z "$SSH_AUTH_SOCK" ]; then
|
||||
eval $(ssh-agent -s) > /dev/null 2>&1
|
||||
fi
|
||||
```
|
||||
|
||||
**Linux (systemd):** Alternatively, a `systemd --user` service:
|
||||
|
||||
```ini
|
||||
# ~/.config/systemd/user/ssh-agent.service
|
||||
[Unit]
|
||||
Description=SSH agent
|
||||
|
||||
[Service]
|
||||
Type=forking
|
||||
ExecStart=/usr/bin/ssh-agent -a %t/ssh-agent.socket
|
||||
|
||||
[Install]
|
||||
WantedBy=default.target
|
||||
```
|
||||
|
||||
Then set the socket in `~/.config/environment.d/ssh-agent.conf`:
|
||||
|
||||
```
|
||||
SSH_AUTH_SOCK=%t/ssh-agent.socket
|
||||
```
|
||||
|
||||
The profile approach works on both platforms and is what the ISO installer
|
||||
uses.
|
||||
|
||||
## Tier 2 — Auto-load Key on First Use
|
||||
|
||||
Add to `~/.ssh/config`:
|
||||
|
||||
```
|
||||
Host codeberg.org
|
||||
AddKeysToAgent yes
|
||||
```
|
||||
|
||||
For all hosts:
|
||||
|
||||
```
|
||||
Host *
|
||||
AddKeysToAgent yes
|
||||
ForwardAgent no
|
||||
```
|
||||
|
||||
After this, the first `ssh` or `git` operation that needs the key will
|
||||
automatically load it into the running agent. No manual `ssh-add` needed
|
||||
once the agent is alive.
|
||||
|
||||
## Tier 3 — Persist Agent Across Tmux Windows (permanent)
|
||||
`ForwardAgent no` is a secure default — it does NOT break Herdr `--remote`
|
||||
(which forwards a Unix socket and uses the key directly).
|
||||
|
||||
Add to `~/.tmux.conf`:
|
||||
## Tier 3 — Terminal Preferences (tmux)
|
||||
|
||||
```
|
||||
set-option -g update-environment "SSH_AUTH_SOCK SSH_AGENT_PID"
|
||||
```
|
||||
|
||||
This ensures new tmux windows and panes inherit the agent socket. Without
|
||||
this, each new window/pane gets a fresh environment with no agent.
|
||||
|
||||
Full recommended `~/.tmux.conf`:
|
||||
Seed `~/.tmux.conf` with UI preferences only:
|
||||
|
||||
```
|
||||
set -g base-index 1
|
||||
setw -g pane-base-index 1
|
||||
set -g mouse on
|
||||
set-option -g update-environment "SSH_AUTH_SOCK SSH_AGENT_PID"
|
||||
```
|
||||
|
||||
**Do NOT** add `set-option -g update-environment "SSH_AUTH_SOCK ..."` to
|
||||
tmux.conf. tmux's default `update-environment` already includes
|
||||
`SSH_AUTH_SOCK` plus `DISPLAY`, `XAUTHORITY`, `SSH_CONNECTION`, and others.
|
||||
Using `set -g` (not `-ga`) **replaces the entire list**, dropping
|
||||
`DISPLAY`/`XAUTHORITY` refresh and breaking GUI apps launched from a
|
||||
reattached tmux session on XFCE desktops. The default is already correct;
|
||||
no override is needed.
|
||||
|
||||
## Complete Setup (first boot)
|
||||
|
||||
All three tiers in one shot for a fresh machine:
|
||||
All three tiers in one shot for a fresh FreeBSD machine:
|
||||
|
||||
```sh
|
||||
# 1. Ensure agent starts with shell
|
||||
echo 'eval $(ssh-agent -s) > /dev/null 2>&1' >> ~/.profile
|
||||
# Tier 1: Agent launcher
|
||||
cat >> ~/.profile <<'EOF'
|
||||
if [ -z "$SSH_AUTH_SOCK" ]; then
|
||||
eval $(ssh-agent -s) > /dev/null 2>&1
|
||||
fi
|
||||
EOF
|
||||
|
||||
# 2. Auto-load keys
|
||||
# Tier 2: Auto-load key
|
||||
mkdir -p ~/.ssh && chmod 700 ~/.ssh
|
||||
cat >> ~/.ssh/config <<'EOF'
|
||||
Host *
|
||||
|
|
@ -108,9 +150,11 @@ Host *
|
|||
EOF
|
||||
chmod 600 ~/.ssh/config
|
||||
|
||||
# 3. Tmux persistence
|
||||
# Tier 3: UI preferences (no update-environment override)
|
||||
cat >> ~/.tmux.conf <<'EOF'
|
||||
set-option -g update-environment "SSH_AUTH_SOCK SSH_AGENT_PID"
|
||||
set -g base-index 1
|
||||
setw -g pane-base-index 1
|
||||
set -g mouse on
|
||||
EOF
|
||||
```
|
||||
|
||||
|
|
@ -135,16 +179,24 @@ under the same identity Git expects.
|
|||
intermittently.
|
||||
|
||||
**Fix:** This is a server-side issue, not agent-related. Wait a few minutes
|
||||
and retry. The agent fix (Tier 1) helps because agent-based auth handles
|
||||
retries better than direct key-file auth, but the root cause is remote.
|
||||
and retry. The root cause is remote.
|
||||
|
||||
---
|
||||
|
||||
**Symptom:** GUI apps (X11) don't work after reattaching tmux on XFCE.
|
||||
|
||||
**Fix:** Check if `~/.tmux.conf` has `set-option -g update-environment`
|
||||
(without `-ga`). Remove it — the default list already covers `DISPLAY` and
|
||||
`SSH_AUTH_SOCK`.
|
||||
|
||||
## Cross-Repo Dependencies
|
||||
|
||||
This skill feeds into the ISO installer (`clawdie-iso/firstboot/shell-ssh.sh`).
|
||||
When the installer creates the `clawdie` user, it should seed:
|
||||
- `~/.ssh/config` with `AddKeysToAgent yes`
|
||||
- `~/.tmux.conf` with `update-environment`
|
||||
The ISO installer (`clawdie-iso/firstboot/shell-ssh.sh`) implements this
|
||||
skill automatically during first boot. After SSH key installation, function
|
||||
`clawdie_shell_ssh_seed_agent_config()` seeds:
|
||||
|
||||
The installer's `shell-ssh.sh` currently only installs the public key to
|
||||
`authorized_keys` — it does not configure agent persistence. See the
|
||||
Clawdie-ISO repo for the corresponding patch.
|
||||
- `~/.profile` — agent launcher (Tier 1)
|
||||
- `~/.ssh/config` — `AddKeysToAgent yes`, `ForwardAgent no` (Tier 2)
|
||||
- `~/.tmux.conf` — base-index 1, mouse on (Tier 3, no update-environment)
|
||||
|
||||
All seeding is idempotent (grep-guarded against existing configs).
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue