🔐 asc api

Просмотр API демона и управление его bearer-токенами.

API защищают два вида токенов. Основной — бессрочный, лежит в /etc/asc/api.token; именно его платформа сохраняет при добавлении ноды, и дальше он работает как refresh-токен. Временный живёт 10 минут (по умолчанию), хранится только в памяти демона и выпускается по основному; он может управлять всем демоном, но не может читать, менять, выпускать и отзывать токены.

Все подкоманды ходят к демону через unix-сокет, поэтому демон должен быть запущен. Кто вправе управлять токенами, решает сам демон: на сокете это root — поэтому команды выполняются через sudo.

Использование

asc api <действие>

status

Показывает адрес слушателя, путь сокета, режим TLS и отпечаток сертификата, число живых временных токенов и то, ждёт ли подтверждения ротация. Основной токен виден только как усечённый SHA-256-дайджест — этого достаточно, чтобы сравнить с тем, что хранит платформа, и недостаточно, чтобы аутентифицироваться.

token show

Печатает основной токен. Только root и только через сокет.

Это путь восстановления, когда ротация на демоне прошла, а платформа новое значение не сохранила: прочитайте токен здесь и переподключите ноду из панели.

token issue

Выпускает временный токен и печатает его один раз.

sudo asc api token issue --ttl 300 --label "разбор инцидента"

--ttl — в секундах; демон ограничивает значение 3600 и по умолчанию берёт 600. --label — произвольная пометка, она остаётся в памяти демона.

WARNING

Временный токен — это полный контроль над машиной минус управление токенами: он может установить и запустить приложение, то есть склонировать и выполнить произвольный git-репозиторий от root. Выдавать его — то же самое, что выдать root-шелл с коротким предохранителем.

token revoke

Гасит все живые временные токены разом. Основной не затрагивается, поэтому платформа просто выпустит себе новый при следующем вызове. Это та кнопка, к которой стоит тянуться при утечке временного токена: она безопасна и не несёт риска блокировки, который есть у ротации.

token rotate

Заменяет основной токен и печатает новый. Все временные токены при этом отзываются.

sudo asc api token rotate --grace 300

--grace — сколько ещё работает заменяемый токен, чтобы его обладатель успел сохранить новое значение; 0 — переключиться сразу. Окно хранится только в памяти, поэтому перезапуск демона внутри него закрывает окно досрочно.

DANGER

Если нода подключена к платформе, ротация с машины оставляет платформе токен, который вот-вот перестанет работать — переподключите ноду из панели до закрытия окна или выполняйте ротацию из панели, где новый токен сохранится сам.

tls

Выбор того, как слушатель API терминирует TLS.

sudo asc api tls self_signed
sudo asc api tls files --cert /etc/letsencrypt/live/node.example.com/fullchain.pem \
                       --key  /etc/letsencrypt/live/node.example.com/privkey.pem

Режим	Что это значит
off	Обычный HTTP. Безопасен, пока слушатель остаётся на loopback.
self_signed	Демон выпускает сертификат сам, платформа закрепляет его отпечаток — как host key у SSH.
acme	Демон получает сертификат сам. Пока недоступно — в этом режиме демон не запустится; используйте files с сертификатом от certbot.
files	Сертификат и ключ, которые вы устанавливаете на ноду. Публично доверенная цепочка проверяется обычным образом, приватный CA — по отпечатку.

--domain задаёт имя, по которому к ноде обращаются платформа и операторы, — нода переживёт смену IP. В режиме self_signed имя вшивается в сертификат, который перевыпускается при следующем запуске.

Настройка записывается в config.toml; чтобы применить, перезапустите демон.

listen

Адрес, на котором слушает API.

sudo asc api listen 0.0.0.0:8420

Выход за loopback без TLS сопровождается предупреждением: bearer-токен даёт полный контроль над машиной и не должен ходить по сети открытым. Перезапустите демон, чтобы применить.

Смотрите также

• 📡 API — API, который защищают эти токены.
• 🔐 Токены безопасности — полная модель: виды, ротация, отзыв.
• 🔗 Платформа — подключение ноды и прямой доступ по TLS.