init

docs/ADMIN_GUIDE.md

@@ -0,0 +1,133 @@
+# Руководство администратора
+
+Практическое руководство по экранам `ssh-access-tui` и типовым сценариям.
+Архитектурные решения и модель угроз — в [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Запуск
+
+```sh
+sudo ssh-access-tui
+```
+
+Требует root (создаёт/блокирует системных пользователей, правит
+`authorized_keys`). Инструмент рассчитан на **одного** администратора
+одновременно на хосте — если кто-то ещё уже открыл TUI, вторая сессия
+получит ошибку про занятую блокировку состояния (`state.lock`), а не молча
+перезапишет чужие изменения.
+
+Навигация везде: стрелки/`j`/`k` — перемещение по списку, `enter` —
+выбрать/подтвердить, `esc` — назад, `ctrl+c` — выход в любой момент.
+
+## Главное меню
+
+```
+Пользователи        — создать / заблокировать / разблокировать / удалить
+Группы и хосты       — какие внутренние хосты кому разрешены
+Экспорт архивов      — сгенерировать ключи и .7z для доставки
+Аудит / кто в сети   — активные сессии и журнал подключений
+Выход
+```
+
+## Сценарий 1: новый сотрудник, у которого уже есть роль/группа доступа
+
+Обычно сначала настраивают группу (один раз), потом заводят пользователей в
+неё пачками.
+
+1. **Группы и хосты** → `n` → ввести имя группы (например `team-billing`) →
+   `enter`.
+2. Выбрать группу → `enter`, попасть в список хостов группы (изначально
+   пуст).
+3. `n` → заполнить: имя хоста (короткий алиас, например `db-prod-1`), адрес
+   (как виден с jump-хоста), порт, описание (необязательно) → `tab` между
+   полями → `enter` сохранить. Повторить для каждого внутреннего хоста,
+   который должен быть доступен этой группе.
+4. `esc` дважды — назад в главное меню.
+5. **Пользователи** → `n` → имя пользователя (латиницей, будущий Linux-логин)
+   и комментарий (например ФИО) → `enter`.
+6. Отметить `space` нужные группы (можно несколько — эффективный список
+   хостов пользователя = объединение хостов всех отмеченных групп) → `enter`.
+
+Это уже создаёт системный Linux-аккаунт (без пароля, без интерактивного
+шелла) и запись в состоянии. **Ключ ещё не выдан** — статус в списке
+пользователей покажет «ключ не выдан».
+
+7. **Экспорт архивов** → отметить `space` только что созданного пользователя
+   (или `a` — отметить всех, удобно при пакетном найме) → `enter`.
+8. Инструмент сгенерирует ключ, пропишет `permitopen=` под текущие хосты
+   группы, соберёт `.7z` и покажет **один общий пароль на всю партию** — он
+   показывается один раз, запишите/скопируйте сразу.
+9. Передайте каждому пользователю его архив (файл, путь показан на экране,
+   лежит в `export_dir`) любым каналом, а пароль от архива — **отдельным**
+   каналом (голосом, в личку) и по возможности не всем одним и тем же
+   сообщением в общем чате.
+10. Пользователь распаковывает архив на Windows по инструкции
+    `INSTRUCTIONS.txt` внутри архива (она уже сгенерирована под его
+    конкретные разрешённые хосты).
+
+## Сценарий 2: добавили новый разрешённый хост существующей группе
+
+1. **Группы и хосты** → выбрать группу → `enter`.
+2. `n` → заполнить новый хост → `enter`.
+
+Это сразу обновляет `permitopen=` в `authorized_keys` **всех активных
+пользователей** этой группы — доступ появляется немедленно, без каких-либо
+действий на стороне пользователя. Клиентский конфиг пользователя (его
+`~/.ssh/config`) при этом не обновляется автоматически — если хотите, чтобы
+у пользователя появился готовый алиас для нового хоста, а не только "голый"
+доступ, повторно прогоните его через **Экспорт архивов** (это заодно
+ротирует его ключ — считайте это плановой ротацией, не проблемой).
+
+Удаление хоста из группы (`d` в списке хостов) действует так же немедленно
+и в обратную сторону.
+
+## Сценарий 3: сотрудник уволился
+
+1. **Пользователи** → выбрать пользователя → `l` (заблокировать).
+
+Это одновременно: блокирует пароль аккаунта, устанавливает немедленный срок
+истечения аккаунта (`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](ARCHITECTURE.md#бэкап-и-аварийное-восстановление).
+Коротко: состояние (`groups`, `users`, публичные ключи, статусы) —
+git-репозиторий, бэкапится часовым таймером в удалённый git. На новом хосте:
+поднять `ssh-access-tui`, влить `state.yaml` из бэкапа, создать системные
+Linux-аккаунты для активных пользователей, выпустить им новые ключи через
+**Экспорт архивов** (старые приватные ключи специально нигде не хранятся —
+это не баг, см. архитектурный документ).
+
+## Что не делает эта версия (нужно руками)
+
+- Не удаляет `.7z` из `export_dir` после доставки — сделайте это сами,
+  когда получатель подтвердил, что распаковал архив.
+- Не обновляет клиентский `~/.ssh/config` пользователя автоматически при
+  появлении нового хоста в его группе — только права доступа на сервере
+  обновляются немедленно (см. сценарий 2).
+- Не поддерживает одновременную работу нескольких администраторов —
+  рассчитан на одного за раз (см. «Конкурентность» в ARCHITECTURE.md).