Agent skill
managing-ssh
Configure SSH, Tailscale VPN, mosh, sudo auth. Trigger: 'SSH 인증 실패', 'Tailscale', 'ssh-agent 문제', 'MagicDNS', 'mosh', 'authorized_keys 설정'. NOT for tmux (use managing-tmux). NOT for Atuin (use syncing-atuin).
Install this agent skill to your Project
npx add-skill https://github.com/greenheadHQ/nixos-config/tree/main/.claude/skills/managing-ssh
SKILL.md
SSH 및 Tailscale 관리
SSH 키, ssh-agent, Tailscale VPN 관련 가이드입니다.
목적과 범위
SSH 인증, ssh-agent 로드, Tailscale 접속, sudo 환경변수 이슈를 통합적으로 다룬다.
Known Issues
sudo에서 SSH_AUTH_SOCK 유실
sudo실행 시 환경변수가 초기화되어 SSH 키 인증 실패- 해결:
sudo -E또는 sudoers에서SSH_AUTH_SOCK유지 설정
재부팅 후 SSH 키 미로드
- launchd agent로 자동 로드 설정되어 있지만 실패할 수 있음
- 수동 로드:
ssh-add $HOME/.ssh/id_ed25519
NixOS에서 SSH 키 자동 로드 방식 혼동
- NixOS는 launchd가 아니라
services.ssh-agent+programs.keychain으로 키 로드 - 수동 로드:
ssh-add $HOME/.ssh/id_ed25519
빠른 참조
SSH 키 상태 확인
# 로드된 키 확인
ssh-add -l
# 키 로드
ssh-add $HOME/.ssh/id_ed25519
# 키 언로드
ssh-add -d $HOME/.ssh/id_ed25519
Tailscale 상태
# 연결 상태 확인
tailscale status
# 재인증 (만료 시)
tailscale up
# IP 확인
tailscale ip -4
SSH 설정 파일
| 파일 | 용도 |
|---|---|
$HOME/.ssh/config |
SSH 호스트 설정 |
$HOME/.ssh/id_ed25519 |
개인 키 |
$HOME/.ssh/id_ed25519.pub |
공개 키 |
$HOME/.ssh/authorized_keys |
인증된 키 (서버) |
modules/darwin/programs/ssh/default.nix |
macOS SSH/launchd 설정 |
modules/nixos/programs/ssh-client/default.nix |
NixOS SSH 클라이언트 설정 |
modules/nixos/programs/tailscale.nix |
NixOS Tailscale VPN + 방화벽 설정 |
modules/nixos/programs/mosh.nix |
NixOS mosh 설정 (Tailscale 전용, LAN 비노출) |
modules/nixos/home.nix |
NixOS services.ssh-agent/programs.keychain 설정 |
authorizedKeys 추가 (NixOS)
# hosts/<hostname>/default.nix
users.users.<username>.openssh.authorizedKeys.keys = [
"ssh-ed25519 AAAA... user@host"
];
핵심 절차
ssh-add -l과 Tailscale 상태를 먼저 확인한다.- 실패 증상을 키 형식/agent/sudo 환경변수 문제로 분류한다.
- NixOS는
home.nix의services.ssh-agent와programs.keychain설정을 점검한다. - 서버 키 배포는
authorizedKeys선언 후 재적용으로 처리한다.
자주 발생하는 문제
- SSH 키 invalid format: 키 파일 끝에 개행 문자 필요
- GitHub SSH 접근 실패:
ssh-add -l로 키 로드 확인 - Tailscale 만료:
tailscale up으로 재인증 - sudo 인증 실패:
sudo -E또는 SSH_AUTH_SOCK 유지
레퍼런스
- 트러블슈팅: references/troubleshooting.md
- Tailscale 설정: references/tailscale.md
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
greenheadHQ/nixos-config
managing-mise
Manage mise runtime: Node.js, pnpm, shims. Trigger: 'mise 설정', 'pnpm not found', '.nvmrc', 'mise shims', 'mise activate', '런타임 버전 불일치'.
greenheadHQ/nixos-config
configuring-git
Configure Git via Home Manager: delta, lazygit, rerere. Trigger: 'git 설정 충돌', 'delta 설정', 'lazygit', 'rerere', 'git-cleanup', 'git 브랜치 정리'.
greenheadHQ/nixos-config
managing-tmux
Configure tmux: plugins (resurrect, thumbs, yank), Pane Notepad. Trigger: 'tmux 설정', 'tmux 플러그인', 'pane notepad', 'tmux-resurrect', 'tmux 단축키', 'tmux 세션 복원'. NOT for SSH (use managing-ssh). NOT for Atuin (use syncing-atuin).
greenheadHQ/nixos-config
configuring-neovim
Configure Neovim (LazyVim) via Nix: plugins, LSP, formatters, linters, themes, treesitter, im-select. Default editor skill — generic '에디터', '편집기', '코드 편집기' queries route here unless the request is explicitly about Zed or another editor-specific path. Trigger: 'neovim', 'LSP', 'lazy.nvim', 'treesitter', '한영 전환', 'im-select', '에디터', '코드 편집기', '편집기 설정', 'colorscheme', 'catppuccin', 'formatter', 'linter', 'extraPackages', '자동완성', 'syntax highlighting', 'language server', '코드 편집'. NOT for Zed/확장 (→ modules/darwin/programs/zed/). NOT for VSCode (제거됨, #329).
greenheadHQ/nixos-config
managing-secrets
Manage encrypted secrets with agenix: .age files, re-encryption, decryption failures. Trigger: '시크릿', '암호화', '복호화', 'agenix', 'secrets.nix', 'age key', '.age', '토큰 추가', 're-encrypt', '/run/agenix'. NOT for Vaultwarden 비밀번호 관리자 (use hosting-vaultwarden).
greenheadHQ/nixos-config
managing-macos
Configure macOS/nix-darwin: Dock, Finder, Homebrew Cask, Folder Actions. Trigger: 'darwin-rebuild', 'shottr 설정', 'Folder Actions', 'compress-video', 'upload-immich'.
Didn't find tool you were looking for?