ssh-access-tui/docs/ADMIN_GUIDE.md

Руководство администратора

Практическое руководство по экранам ssh-access-tui и типовым сценариям. Архитектурные решения и модель угроз — в ARCHITECTURE.md.

Запуск

sudo ssh-access-tui

Требует root (создаёт/блокирует системных пользователей, правит authorized_keys). Инструмент рассчитан на одного администратора одновременно на хосте — если кто-то ещё уже открыл TUI, вторая сессия получит ошибку про занятую блокировку состояния (state.lock), а не молча перезапишет чужие изменения.

Навигация везде: стрелки/j/k — перемещение по списку, enter — выбрать/подтвердить, esc — назад, ctrl+c — жёсткий выход в любой момент (без каких-либо предупреждений — только для аварийных случаев). Обычный выход через пункт меню «Выход» или q в главном меню предупредит, если есть созданные, но ни разу не экспортированные пользователи (у них ещё нет ключа) — можно выйти всё равно (enter/y) или вернуться (esc/n).

Любое деструктивное действие (блокировка/удаление пользователя, удаление хоста/сервиса/группы, перевыпуск уже выданного ключа) требует не enter/y, а набрать вручную короткую случайную строку, которую инструмент показывает на экране подтверждения (например kqzvm-482) — она каждый раз новая. Неверный ввод просто откатывает к полю ввода с пояснением «не совпадает», ничего не меняя; esc отменяет действие полностью в любой момент. Это защита именно от «промахнулся мимо enter» — набрать чужую случайную строку по ошибке невозможно.

Главное меню

Пользователи        — создать / заблокировать / разблокировать / удалить
Хосты и сервисы      — общий каталог адресов и портов (один раз на всех)
Группы               — какие хосты из каталога входят в каждую группу
Экспорт архивов      — сгенерировать ключи и .7z для доставки
Аудит / кто в сети   — активные сессии и журнал подключений
Выход

Имена хостов, сервисов и групп должны быть без пробелов (латиница, цифры, . _ -) — они попадают в конфиг и в authorized_keys; инструмент откажет с понятной ошибкой, если ввести имя с пробелом.

Модель: каталог → группы → пользователи

Хосты и их сервисы (порты) описываются один раз в общем каталоге («Хосты и сервисы»), а не заново для каждой группы. Группа — это просто отметка галочками, какие хосты каталога в неё входят (все сервисы такого хоста включаются целиком). Если у вас в разных группах фигурируют одни и те же хосты/сервисы — их не нужно набивать повторно, только отметить нужные для очередной группы. Пользователь состоит в одной или нескольких группах; его реальный доступ — объединение сервисов всех хостов всех его групп.

Сценарий 1: новый сотрудник, у которого уже есть роль/группа доступа

Обычно каталог и группы настраивают заранее (или один раз добавляют то, чего не хватает), потом заводят пользователей пачками.

1. Хосты и сервисы → n → имя хоста (например db-prod-1), адрес (как виден с jump-хоста), описание (необязательно) → enter. Сразу открывается список сервисов этого хоста (изначально пуст).
2. n → имя сервиса (например ssh или web-api), порт на хосте (например 22 или 7888), описание (необязательно) → enter. Повторите n для каждого сервиса на этом хосте.
3. esc — назад к списку хостов; повторите шаги 1-2 для остальных хостов, затем esc — в главное меню. Если хост/сервис уже существует и нужно только поправить адрес/порт/описание — e вместо n на нужной записи (можно поменять и имя — все группы, которые ссылались на старое имя, автоматически обновятся).
4. Группы → n → имя группы (например team-billing), описание (необязательно) → enter.
5. Выбрать группу → enter → отметить space нужные хосты из каталога → enter сохранить. Список сервисов этих хостов достаётся группе целиком.
6. Пользователи → n → имя пользователя (латиницей, будущий Linux-логин) и комментарий (например ФИО) → enter.
7. Отметить space нужные группы (можно несколько) → enter.

Это уже создаёт системный Linux-аккаунт (без пароля, без интерактивного шелла) и запись в состоянии. Ключ ещё не выдан — статус в списке пользователей покажет «ключ не выдан».

8. Экспорт архивов → отметить space только что созданного пользователя (или a — отметить всех, удобно при пакетном найме) → enter. Для пользователей без ключа архив генерируется сразу, без лишних вопросов — это не деструктивное действие. Инструмент сгенерирует ключ, пропишет permitopen= под текущие сервисы группы и соберёт .7z, показав один общий пароль на всю партию — он показывается один раз, запишите/скопируйте сразу.
9. Передайте каждому пользователю его архив (файл, путь показан на экране, лежит в export_dir) любым каналом, а пароль от архива — отдельным каналом (голосом, в личку) и по возможности не всем одним и тем же сообщением в общем чате.
10. Пользователь распаковывает архив на Windows по инструкции INSTRUCTIONS.txt внутри архива — она на простом русском языке, без технических терминов: положить файлы в папку, ввести одну команду и держать окно открытым, дальше список «такой адрес у вас локально → что это → где реально находится», составленный под конкретные сервисы этого пользователя.

Сценарий 1а: изменить группы уже существующего пользователя

Пользователи → выбрать пользователя → g → отметить/снять space нужные группы → enter. Если у пользователя уже выдан ключ, инструмент сразу пересоберёт его permitopen= под новый набор сервисов — доступ меняется немедленно, без переотправки архива и без замены ключа (изменение групп никогда не ротирует ключ).

Если хотите, чтобы у пользователя появился ещё и обновлённый клиентский config с новыми адресами для новых сервисов (иначе он про них просто не узнает, хотя доступ уже есть) — Пользователи → выбрать пользователя → c («обновить конфиг»). Это генерирует маленький архив только с config + INSTRUCTIONS.txt (без ключа — ключ у пользователя уже есть и остаётся тем же), пользователю нужно только подменить файл config. Не требует подтверждения — ключ и доступ этим действием не меняются, это не деструктивно.

Полный экспорт (сценарий 1, шаги 8-9) тоже сработает и даст то же самое плюс заново выпустит ключ (с подтверждением строкой, раз это перевыпуск) — используйте c, когда переиздание ключа не нужно.

Сценарий 2: добавили новый сервис/хост, поменялся адрес или порт

• Новый сервис на существующем хосте: Хосты и сервисы → выбрать хост → enter → n.
• Новый хост: Хосты и сервисы → n, затем добавить ему сервисы.
• Хост сменил адрес, сервис — порт, нужно поправить описание, или переименовать: e на нужной записи. Переименование хоста автоматически обновляет ссылки на него во всех группах, которые его используют — группы не «отваливаются» молча.

Любое из этих изменений сразу обновляет permitopen= в authorized_keys всех активных пользователей всех групп, ссылающихся на этот хост, — доступ появляется немедленно, без каких-либо действий на стороне пользователя. Клиентский конфиг пользователя (его ~/.ssh/config) при этом не обновляется автоматически — для этого используйте Пользователи → c («обновить конфиг», см. сценарий 1а).

Группы → выбрать группу → enter — там же можно снять/добавить привязку группы к хостам каталога (не создавая и не удаляя сами хосты).

Удаление хоста из каталога, сервиса на хосте или целой группы (d в соответствующем списке) — все три действия деструктивны (мгновенно отбирают доступ у всех затронутых пользователей) и требуют набрать случайную строку подтверждения: экран покажет, что именно удаляется, сколько пользователей это коснётся, и в каких группах используется (для хоста/сервиса).

Сценарий 3: сотрудник уволился

1. Пользователи → выбрать пользователя → l (заблокировать) → набрать строку подтверждения, которую покажет экран → enter.

Блокировка — это одновременно: блокирует пароль аккаунта, устанавливает немедленный срок истечения аккаунта (chage -E 1) и комментирует его ключ в authorized_keys — три независимых механизма, чтобы блокировка не зависела от одного из них. Статус в списке сменится на locked. Это обратимо.

Если сотрудник вернулся — u (разблокировать) на том же пользователе: снимает блокировку аккаунта и восстанавливает его ключ в authorized_keys с текущими правами групп. Разблокировка не деструктивна — подтверждения не требует, срабатывает сразу.

Полное удаление аккаунта (d) — необратимо (userdel -r, домашняя папка стирается) и тоже требует подтверждения строкой (экран явно предупредит, что это необратимо и что для временного отключения лучше использовать блокировку). Используйте удаление только для окончательного оффбординга, не для временной блокировки.

Сценарий 4: проверить, кто сейчас подключён / посмотреть историю

Аудит / кто в сети показывает:

• «Сейчас в сети» — список активных SSH-сессий (по процессам sshd: user [priv], а не по who, потому что форвардинг-сессии без интерактивного терминала не создают обычных login-записей);
• «Последние события» — журнал подключений/отключений, который в фоне собирает ssh-access-tui-audit.service из journalctl, независимо от ротации системного журнала.

r — обновить оба списка. Если журнал подключений пуст, хотя пользователи явно заходили — проверьте, что фоновый сервис запущен: systemctl status ssh-access-tui-audit.service.

Сценарий 5: перенос на новый хост / хост умер

См. подробности в ARCHITECTURE.md. Коротко: состояние (каталог хостов/сервисов, группы, пользователи, публичные ключи, статусы) — git-репозиторий, бэкапится часовым таймером в удалённый git. На новом хосте: поднять ssh-access-tui, влить state.yaml из бэкапа, создать системные Linux-аккаунты для активных пользователей, выпустить им новые ключи через Экспорт архивов (старые приватные ключи специально нигде не хранятся — это не баг, см. архитектурный документ).

Что не делает эта версия (нужно руками)

• Не удаляет .7z из export_dir после доставки — сделайте это сами, когда получатель подтвердил, что распаковал архив (это касается и архивов от «обновить конфиг», хоть они и не содержат ключ).
• Не обновляет клиентский ~/.ssh/config пользователя автоматически при появлении нового сервиса/хоста в его группе — это ручной шаг («обновить конфиг», сценарий 1а), права доступа на сервере при этом обновляются немедленно и без участия администратора (см. сценарий 2).
• Не поддерживает одновременную работу нескольких администраторов — рассчитан на одного за раз (см. «Конкурентность» в ARCHITECTURE.md).