mirivlad
/
sshkeeper
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity
sshkeeper/docs/guide.md

21 KiB
Raw Blame History

sshkeeper — Руководство пользователя

Содержание

  1. Что такое sshkeeper
  2. Установка
  3. Первый запуск
  4. TUI — основной интерфейс
  5. Управление серверами
  6. Маршруты и бастионы
  7. Port Forwards и Tunnels
  8. CLI команды
  9. Vault — хранилище секретов
  10. Сценарии использования
  11. Справка по клавишам

Что такое sshkeeper

sshkeeper — это консольный менеджер SSH-подключений для Linux. Он хранит профили серверов, секреты (пароли, фразы от ключей) и запускает системный ssh с нужными опциями.

Чем sshkeeper НЕ является:

  • Это не Ansible — он не настраивает серверы и не пушит файлы
  • Это не замена SSH — он использует системный /usr/bin/ssh

Что он делает:

  • Хранит профили серверов в локальной SQLite-базе
  • Хранит пароли в зашифрованном vault (XChaCha20-Poly1305)
  • Управляет маршрутами (бастионы, цепочки прыжков)
  • Управляет port forwards (локальные, удалённые, SOCKS)
  • Запускает туннели в фоне с отслеживанием PID
  • Предоставляет TUI (текстовый интерфейс) и CLI

Стек технологий:

  • Go 1.25+
  • Bubble Tea (TUI framework)
  • Cobra (CLI framework)
  • SQLite (modernc.org/sqlite)
  • XChaCha20-Poly1305 (шифрование vault)
  • Argon2id (KDF для мастер-пароля)

Исходники: git.mirv.top:mirivlad/sshkeeper

Установка

Из релиза

tar -xzf sshkeeper_v0.2.0_linux_amd64.tar.gz
chmod +x sshkeeper-linux-amd64
sudo install -m 0755 sshkeeper-linux-amd64 /usr/local/bin/sshkeeper

Из исходников

git clone git@git.mirv.top:mirivlad/sshkeeper.git
cd sshkeeper
go build -o ~/.local/bin/sshkeeper .

Или через скрипт:

./build.sh          # сборка в bin/
./release.sh        # сборка релизных архивов в dist/

Требования: Go 1.25+, Linux x86_64, системный OpenSSH.

Первый запуск

При первом запуске sshkeeper создаёт конфигурацию, базу данных и vault:

sshkeeper

Вы увидите приветствие и запрос на создание мастер-пароля:

Welcome to sshkeeper!
No vault found. Let's create one.

Create master password: ********
Repeat master password: ********

Vault created and unlocked for this command. You're ready to go!

Важно: запомните мастер-пароль. Без него секреты не восстановить.

После создания vault откроется главный экран TUI со списком серверов (пока пустым).

TUI — основной интерфейс

Запуск TUI — просто sshkeeper без аргументов.

Главный экран

sshkeeper  0 servers
Vault unlocked | 0 OK | 0 FAIL

  NAME                 ALIAS                ROUTE                              AUTH         GROUP      STATUS

  No servers yet. Press Ctrl+A to add one.

  Enter: connect | Ctrl+X: actions | Ctrl+A: add | Ctrl+E: edit
  Ctrl+F: search | Ins: select | ?: help | Ctrl+Q: quit

Столбцы:

  • NAME — отображаемое имя сервера
  • ALIAS — уникальный идентификатор
  • ROUTE — маршрут подключения:
    • direct → user@host:port — прямое подключение
    • → bastion → user@host:port — через бастион
    • → bastion → … → user@host:port — через цепочку
  • AUTH — метод аутентификации (key/password/agent/key+phrase)
  • GROUP — группа сервера
  • STATUS — результат последнего теста (OK/FAIL/?)

Навигация:

  • ↑/↓ — перемещение по списку
  • Enter — подключиться к серверу
  • Ctrl+A — добавить сервер
  • Ctrl+E — редактировать сервер
  • Ctrl+X — меню действий
  • Ctrl+F — поиск
  • Ins — выбрать/снять выбор (для групповых операций)
  • ? или F1 — полная справка
  • Ctrl+Q — выход

Экран помощи

Нажмите ? или F1 на любом экране:

sshkeeper — Help

  Enter         Connect to server
  ↑/↓           Navigate list
  Tab/↓         Next field
  Shift+Tab/↑   Previous field
  /             Open dropdown picker
  Esc           Back / Cancel
  Ctrl+A        Add server
  Ctrl+E        Edit server
  Ctrl+W        Manage port forwards
  Ctrl+X        Action menu
  ?             This help screen
  Ctrl+Q        Quit

Управление серверами

Добавление сервера

  1. Нажмите Ctrl+A на главном экране
  2. Заполните поля:
Add Server

  Alias:              mail.kp
  Display Name:       Production mail
  Host:               mail.example.org
  Port:               22
  User:               root
  Auth Method:        key
  Identity File:      ~/.ssh/id_ed25519
  Route hops:         bastion
  Group:              KP
  Notes:              Main mail server
  Startup Command:    tmux attach -t ops
  Tags:               prod, mail

  [ Test ]  [ Save ]

  Tab/↓: next | ↑: prev | /: pick list | Enter: select | Esc: back

Навигация по форме:

  • Tab или ↓ — следующее поле
  • Shift+Tab или ↑ — предыдущее поле
  • / на поле Auth Method — выбрать из списка (password/key/key_passphrase/agent)
  • / на поле Group — выбрать из существующих групп
  • Enter на кнопке Test — проверить подключение
  • Enter на кнопке Save — сохранить
  • Esc — отмена

Редактирование сервера

  1. Выберите сервер стрелками
  2. Нажмите Ctrl+E
  3. Отредактируйте поля
  4. Нажмите Enter на Save

Удаление сервера

  1. Выберите сервер стрелками
  2. Нажмите Ctrl+X (меню действий)
  3. Выберите "Delete"
  4. Подтвердите: Enter или Y — да, Esc или N — нет

Тест подключения

  1. Выберите сервер стрелками
  2. Нажмите Ctrl+X → "Test connection"
  3. Результат отобразится в столбце STATUS (OK/FAIL)

Поиск

  1. Нажмите Ctrl+F
  2. Введите запрос (поиск по alias, name, host, user, group, notes, tags)
  3. Enter — применить фильтр
  4. Esc — сбросить

Маршруты и бастионы

Прямое подключение

Сервер подключается напрямую:

ROUTE:   direct → root@web.example.org:22

Через бастион

Сервер доступен через один jump host:

ROUTE:   → bastion → root@internal.web:22

Цепочка прыжков

Сервер доступен через несколько jump hosts:

ROUTE:   → bastion → dmz-gw → … → root@secure.internal:22

Настройка маршрута

Через TUI:

  1. Добавьте/редактируйте сервер
  2. В поле "Route hops" введите бастионы через запятую: bastion,dmz-gw
  3. Или введите адрес напрямую: user@bastion.example.com:2222

Через CLI:

sshkeeper route set web --jumps bastion
sshkeeper route set prod --jumps bastion,dmz-gw
sshkeeper route show web
sshkeeper route clear web

Port Forwards и Tunnels

Ключевое различие

  • Port Forward — сохранённое правило проброса порода. Просто конфигурация, не запускает процесс.
  • Tunnel — запущенный SSH-процесс, который активирует один или несколько forwards.

Аналогия: forward — это рецепт, tunnel — это готовое блюдо.

Типы forwards

Тип Описание Пример
Local Порт на вашей машине → сервис за SSH-сервером Локальный 5432 → удалённый PostgreSQL
Remote Порт на SSH-сервере → сервис на вашей машине Удалённый 8080 → локальный dev-сервер
SOCKS Локальный SOCKS-прокси через SSH Браузер → SOCKS → интернет через SSH-сервер

Управление forwards через TUI

  1. Выберите сервер на главном экране
  2. Нажмите Ctrl+X → "Manage port forwards"
  3. Откроется список forwards:
Port Forwards — web

  NAME                 TYPE    LISTEN               TARGET               ON
  Local PostgreSQL     Local   127.0.0.1:15432      127.0.0.1:5432       yes
  Web Admin            Local   127.0.0.1:18080      internal.web:80      yes
  SOCKS Proxy          SOCKS   127.0.0.1:1080       SOCKS                yes

  Selected
  Port 127.0.0.1:15432 on this machine will be forwarded through web to 127.0.0.1:5432.
  -L 127.0.0.1:15432:127.0.0.1:5432
  -o ExitOnForwardFailure=yes

  Ctrl+A: add | Ctrl+E/Enter: edit | Ctrl+D: delete | Esc: back

Действия:

  • Ctrl+A — добавить forward
  • Enter или Ctrl+E — редактировать выбранный
  • Ctrl+D — удалить (с подтверждением)
  • Esc — назад

Добавление forward

  1. Нажмите Ctrl+A на экране forwards
  2. Выберите тип (1/2/3 или Tab):
Add Port Forward

  Name:               Local PostgreSQL
  Description:        optional

  Type
  ▸ 1. Local    port on my machine → service on SSH server
    2. Remote   port on SSH server → service on my machine
    3. SOCKS    local dynamic SOCKS proxy through SSH

  Listen Address:     127.0.0.1
  Listen Port:        15432
  Target Host:        127.0.0.1
  Target Port:        5432

  Preview
  -L 127.0.0.1:15432:127.0.0.1:5432
  -o ExitOnForwardFailure=yes

  [ Save ]

  Tab/↓: next | ↑: prev | 1/2/3: select type | Enter: save | Esc: back

Поля зависят от типа:

  • Local: Listen Address, Listen Port, Target Host, Target Port
  • Remote: Remote Listen Addr, Remote Listen Port, Local Target Host, Local Target Port
  • SOCKS: Listen Address, Listen Port (target поля скрыты)

По умолчанию Listen Address = 127.0.0.1 (только локальный доступ). Если введёте 0.0.0.0, появится предупреждение.

Запуск туннеля

Через TUI:

  1. Выберите сервер
  2. Нажмите Ctrl+X → один из вариантов:
    • Connect with tunnels — SSH-сессия + все активные forwards
    • Start tunnels only — туннель на переднем плане, без shell
    • Start tunnels in background — туннель в фоне с PID

Через CLI:

# SSH-сессия с туннелями
sshkeeper tunnel web

# Только туннель (foreground)
sshkeeper tunnel web --forward-only

# Туннель в фоне
sshkeeper tunnel web --background

Управление туннелями

Через TUI:

  1. Нажмите Ctrl+X → "Manage tunnels"
  2. Список запущенных туннелей:
Tunnel Manager

  Tunnel to web              PID 12345    running   2m30s
  Tunnel to prod             PID 12346    running   1m15s

  Ctrl+D: stop | Ctrl+R: refresh | Esc: back

Через CLI:

sshkeeper tunnel list
sshkeeper tunnel stop <id>

CLI команды

Серверы

# Добавление
sshkeeper add web --host 10.0.0.10 --user deploy --auth key
sshkeeper add prod --host 10.0.0.20 --user root --auth password
sshkeeper add bastion --host bastion.example.org --user admin --auth key_passphrase --identity-file ~/.ssh/id_rsa

# Интерактивный режим
sshkeeper add

# Просмотр
sshkeeper list
sshkeeper show web
sshkeeper search prod

# Подключение
sshkeeper connect web
sshkeeper c web          # короткая форма

# Выполнение команды
sshkeeper run web "uptime"

# Тест подключения
sshkeeper test web

# Редактирование
sshkeeper edit web --tags prod,web --startup-command "tmux attach -t ops"

# Удаление
sshkeeper delete web

Маршруты

sshkeeper route set web --jumps bastion
sshkeeper route set prod --jumps bastion,dmz-gw
sshkeeper route show web
sshkeeper route clear web

Port Forwards

# Добавление
sshkeeper forward add web --name "Local PostgreSQL" --type local --local-port 15432 --remote-addr 127.0.0.1 --remote-port 5432
sshkeeper forward add bastion --name "SOCKS Proxy" --type dynamic --local-port 1080

# Список
sshkeeper forward list web

# Удаление
sshkeeper forward delete web 1

Tunnels

sshkeeper tunnel web                    # SSH + туннели
sshkeeper tunnel web --forward-only     # Только туннель
sshkeeper tunnel web --background       # Фоновый туннель
sshkeeper tunnel list                   # Список туннелей
sshkeeper tunnel stop <id>              # Остановить

Группы и шаблоны

sshkeeper group list
sshkeeper group rename old new
sshkeeper group delete name

sshkeeper template list
sshkeeper template add uptime "uptime"
sshkeeper template delete uptime
sshkeeper run-template web uptime

Vault

sshkeeper vault status
sshkeeper vault unlock
sshkeeper vault list
sshkeeper vault delete web ssh_password
sshkeeper vault change-password

Импорт/Экспорт

sshkeeper import              # Импорт из ~/.ssh/config
sshkeeper export              # Экспорт в stdout

Vault — хранилище секретов

Vault хранит SSH-пароли и фразы от ключей в зашифрованном виде.

Шифрование: XChaCha20-Poly1305, KDF: Argon2id (64 MiB, 3 iterations)

Когда нужен мастер-пароль:

  • connect, c — для подключения с password/key_passphrase аутентификацией
  • run, run-template — для выполнения команд
  • test — для тестирования
  • edit, delete — для редактирования секретов
  • vault команды

Когда НЕ нужен:

  • list, show, search — только метаданные
  • add с auth=key или auth=agent
  • export, ssh-config

Сценарии использования

Сценарий 1: Подключение к серверу через бастион

# 1. Добавляем бастион
sshkeeper add bastion --host bastion.example.org --user admin --auth key

# 2. Добавляем внутренний сервер с маршрутом через бастион
sshkeeper add web --host 10.0.0.10 --user deploy --auth key
sshkeeper route set web --jumps bastion

# 3. Подключаемся
sshkeeper connect web
# Автоматически: ssh -J bastion deploy@10.0.0.10

Сценарий 2: Локальный доступ к удалённой базе данных

# 1. Добавляем сервер
sshkeeper add db --host db.internal --user postgres --auth key

# 2. Создаём forward
sshkeeper forward add db --name "PostgreSQL" --type local --local-port 15432 --remote-addr 127.0.0.1 --remote-port 5432

# 3. Запускаем туннель в фоне
sshkeeper tunnel db --background
# ✓ Tunnel started [12345] PID 67890 → db

# 4. Подключаемся локально
psql -h 127.0.0.1 -p 15432 -U myuser mydb

# 5. Когда не нужен — останавливаем
sshkeeper tunnel stop 12345

Сценарий 3: SOCKS-прокси для браузера

# 1. Добавляем сервер
sshkeeper add jump --host jump.example.org --user me --auth key

# 2. Создаём SOCKS forward
sshkeeper forward add jump --name "SOCKS" --type dynamic --local-port 1080

# 3. Запускаем туннель
sshkeeper tunnel jump --background

# 4. Настраиваем браузер: SOCKS5 127.0.0.1:1080

Сценарий 4: Цепочка прыжков

# Сервер за двумя бастионами
sshkeeper add secure --host 10.10.10.10 --user root --auth key
sshkeeper route set secure --jumps bastion,dmz-gw

# Подключение
sshkeeper connect secure
# Автоматически: ssh -J bastion,dmz-gw root@10.10.10.10

Сценарий 5: Групповые операции

# В TUI: выбрать несколько серверов (Ins), затем:
# Ctrl+X → Run template → выбрать шаблон
# Команда выполнится на всех выбранных серверах

Справка по клавишам

Главный экран

Клавиша Действие
Enter Подключиться к серверу
Ctrl+A Добавить сервер
Ctrl+E Редактировать сервер
Ctrl+F Поиск
Ctrl+X Меню действий
Ins Выбрать/снять выбор
? / F1 Помощь
Ctrl+Q Выход

Меню действий (Ctrl+X)

  • Connect — стандартное SSH-подключение
  • Connect with tunnels — SSH + все активные forwards
  • Start tunnels only — туннель без shell
  • Start tunnels in background — фоновый туннель
  • Manage port forwards — управление forwards
  • Manage tunnels — список туннелей
  • Manage route — настройка маршрута
  • Test connection — проверка подключения
  • Edit — редактирование сервера
  • Delete — удаление (с подтверждением)

Формы (добавление/редактирование)

Клавиша Действие
Tab / ↓ Следующее поле
Shift+Tab / ↑ Предыдущее поле
/ Выбрать из списка (Auth Method, Group)
Enter Действие / переход
Esc Назад / отмена

Список forwards

Клавиша Действие
↑/↓ Навигация
Ctrl+A Добавить
Enter / Ctrl+E Редактировать
Ctrl+D Удалить (с подтверждением)
Esc Назад

Список туннелей

Клавиша Действие
Ctrl+D / s Остановить туннель
Ctrl+R / r Обновить список
Esc Назад

Диалог подтверждения

Клавиша Действие
Enter / Y Да
Esc / N Нет

Расположение данных

Данные Путь
Конфиг ~/.config/sshkeeper/config.toml
База данных ~/.local/share/sshkeeper/sshkeeper.db
Vault ~/.local/share/sshkeeper/vault.bin
Туннели ~/.local/share/sshkeeper/tunnels.json
OpenSSH config ~/.ssh/config.d/sshkeeper.conf

Если заданы XDG_CONFIG_HOME или XDG_DATA_HOME, данные хранятся в соответствующих поддиректориях.

Сборка и тестирование

# Тесты
go test ./...

# Сборка
go build -o bin/sshkeeper .

# Или через скрипты
./build.sh          # сборка в bin/
./release.sh        # релизные архивы в dist/

Лицензия

MIT. См. LICENSE.