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

25 KiB
Raw Permalink 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 и macOS; Windows-сборка пока экспериментальная. Он хранит профили серверов, секреты (пароли, фразы от ключей) и запускает системный 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 для мастер-пароля)

Исходники:

  • Основной публичный репозиторий: github.com/mirivlad/sshkeeper
  • Self-hosted зеркало: git@git.mirv.top:mirivlad/sshkeeper

Установка

Из исходников (основной способ)

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

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

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

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

Статус платформ:

Платформа Статус Примечание
Linux Основная релизная платформа Архивы linux/amd64 и linux/arm64.
macOS Основная релизная платформа Архивы darwin/amd64 и darwin/arm64, нужен системный ssh. Homebrew formula запланирована.
Windows Experimental Нужен OpenSSH Client как ssh.exe в PATH; password/key-passphrase PTY-сценарии на Windows пока не подтверждены.

На Windows OpenSSH Client можно установить через Windows Optional Features или PowerShell:

Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0

Из релиза (после публикации v0.2.0)

tar -xzf sshkeeper_v0.2.0_linux_amd64.tar.gz
sudo install -m 0755 sshkeeper_v0.2.0_linux_amd64/sshkeeper /usr/local/bin/sshkeeper

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

При первом запуске 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 | ?: hotkeys | F1: help | Ctrl+Q: quit

Столбцы:

Столбец Описание
NAME Отображаемое имя сервера
ALIAS Уникальный идентификатор
ROUTE Маршрут подключения (● direct, → via, ⇒ chain)
AUTH Метод аутентификации (key/password/agent/key+phrase)
GROUP Группа сервера
STATUS Результат последнего теста (OK/FAIL/?)

Навигация:

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

Быстрая справка по клавишам

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

sshkeeper — Quick Help

  Navigation
  ↑/↓             Move through list
  PgUp/PgDn       Scroll page
  Home/End        Jump to start/end

  Actions
  Enter           Select / Confirm / Open
  Esc             Back / Cancel / Close
  Tab / ↓         Next field
  Shift+Tab / ↑   Previous field
  /               Open dropdown picker

  Server list
  Enter           Connect to server
  Ctrl+A          Add server
  Ctrl+E          Edit server
  Ctrl+F          Search
  Ctrl+X          Action menu
  Ins             Select / deselect

  Port forwards
  Ctrl+A          Add forward
  Enter / Ctrl+E  Edit forward
  Ctrl+D          Delete forward

  Other
  ?               This quick help
  F1              Full documentation

  Esc / Enter / ? / q — close

Полная справка по приложению

Нажмите F1 на любом экране. Это полная документация по sshkeeper:

sshkeeper — Full Help

  What is sshkeeper
  sshkeeper is a console SSH connection manager.
  Linux and macOS are primary release targets; Windows is experimental.
  It stores server profiles, secrets, and launches the system ssh client.

  Navigation
  ↑/↓             Move through list
  Tab/↓           Next field
  Shift+Tab/↑     Previous field
  /               Open dropdown picker

  Global actions
  Enter           Select / Confirm / Open
  Esc             Back / Cancel / Close
  ?               Quick help (hotkeys)
  F1              Full documentation
  Ctrl+Q          Quit

  Server list
  Enter           Connect to server
  Ctrl+A          Add server
  Ctrl+E          Edit server
  Ctrl+F          Search
  Ctrl+X          Action menu
  Ins             Select / deselect

  ...

  ↑/↓ scroll — q/Esc/Enter close

Навигация по полной справке:

Клавиша Действие
↑/↓ Прокрутка
PgUp/PgDn Прокрутка по странице
q / Esc / Enter Закрыть справку

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

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

  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, route hops, forward ports)
  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. Добавьте/редактируйте сервер или выберите Ctrl+X → "Manage route"
  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

  Opens a local port on this machine and forwards it through SSH to the target address.

  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

Фоновый туннель запускается как ssh -N, требует хотя бы один включённый forward и сейчас поддерживает только key или agent auth. Для password/key_passphrase используйте foreground-режим (sshkeeper tunnel web или --forward-only), чтобы sshkeeper мог обработать PTY prompt и передать секрет из vault.

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

Через 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>
sshkeeper tunnel stop-all

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 edit 1 --enabled=false

# Удаление
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 tunnel stop-all               # Остановить все tracked туннели

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

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
  • tunnel list, tunnel stop, tunnel stop-all
  • tunnel <alias> --background
  • 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 Удаление (с подтверждением)
Import Импорт из ~/.ssh/config и обновление списка
Export Выход в терминал и печать экспорта
Vault: lock Заблокировать vault в текущем процессе
Vault: change password Выход в терминал и смена master password

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

Клавиша Действие
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 .

# Проверка релизной кросс-сборки
make release-check

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

Лицензия

MIT. См. LICENSE.