Для работы с агентом я использую прекрасный инструмент Orca, о котором узнал от Сережи Риса, читая его отличный блог.

Claude Code обновляется часто, Homebrew обновляет бинарник на диске, но старые процессы продолжают жить на старой версии; закрывать 20+ сессий вручную - много лишних операций.

Автоматизация обновления бинарника

Для того чтобы не обновлять бинарник руками Claude собрал мне такой шелл-скрипт:

~/.local/bin/claude-code-upgrade

В скрипте три решения, которые легко пропустить:

• launchd запускает задачи с минимальным PATH. Без строки export PATH=… brew не находит свои утилиты.
• brew upgrade обновляет метаданные не чаще одного раза за 24 часа. Ежедневная задача из-за этого может пропустить сборку. Поэтому скрипт сам вызывает brew update и отключает автообновление метаданных.
• При ошибке скрипт пишет в лог код возврата и весь вывод команды. При успехе пишет одну строку.

LaunchAgent

Для автозапуска скрипта использовал launchd:

~/Library/LaunchAgents/com.ihumster.claude-code-upgrade.plist

Установка и размещение

Скрипт обновления кладем в ~/.local/bin/, LaunchAgent складываем в ~/Library/LaunchAgents/.

chmod +x ~/.local/bin/claude-code-upgrade
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.ihumster.claude-code-upgrade.plist
launchctl print "gui/$(id -u)/com.ihumster.claude-code-upgrade" | grep -E 'state|last exit'

Если Mac спал в 08:00, launchd запускает пропущенную задачу после пробуждения. RunAtLoad добавляет запуск при входе в систему.

Лог за два дня:

2026-10-05 13:39:33 OK upgraded 2.1.288 -> 2.1.289
2026-10-06 08:00:52 OK upgraded 2.1.289 -> 2.1.290
2026-10-06 16:17:03 OK upgraded 2.1.290 -> 2.1.291

Часть 2. Проблема: бинарник новый, сессии старые

Brew меняет файл на диске. Запущенный процесс продолжает работать на том бинарнике, с которого стартовал. Каталог старой версии brew переименовывает в <версия>.upgrading, и процесс держит его открытым.

Команда показывает, на какой версии работает каждая сессия:

jq -r '[.status, .version] | @tsv' ~/.claude/sessions/*.json | sort | uniq -c

Результат на 2026-10-05, установлена версия 2.1.289:

   1 busy 2.1.288
   1 busy 2.1.289
   4 idle 2.1.276
   5 idle 2.1.280
   8 idle 2.1.283
   4 idle 2.1.288

Самые старые сессии работали с 2026-09-22. Закрыть вкладку и открыть новую нельзя, потому что в сессии лежит контекст задачи. Нет, Orca конечно позволяет открыть сессию из Agent Session History, для этого у нее есть отдельная вкладка на панели:

И даже более того у Orca теперь есть поиск по всем сессиям проекта - очень удобно порой. История сессий решает задачу восстановления, но для регулярного обновления десятков открытых вкладок это слишком много ручных действий.

Почему не автоматический перезапуск в 08:00

Первая идея была такой: после обновления скрипт сам перезапускает все простаивающие сессии. Я от неё отказался. Перезапуск убивает всё, что сессия держит в фоне: фоновые команды, субагентов, Monitor и запланированные пробуждения /loop. Статус idle в реестре этого не показывает. Сессия в статусе idle может ждать ответа на вопрос или окончания фоновой задачи.

Решение о перезапуске принимает человек, по одной вкладке. Значит, нужна кнопка.

Часть 3. Что известно о сессии снаружи

Для перезапуска нужны четыре вещи: идентификатор сессии, флаги запуска, вкладка Orca и способ ввести команду во вкладку. Все четыре можно получить без участия модели.

• Идентификатор сессии, статус и версия. Они лежат в файле ~/.claude/sessions/<pid>.json, в полях sessionId, status и version.
• Флаги запуска. Их показывает команда ps -o args= -p <pid>.
• Вкладка Orca. Её задают переменные ORCA_PANE_KEY и ORCA_TERMINAL_HANDLE в окружении процесса claude.
• Ввод во вкладку. Его делает команда orca terminal send --terminal <handle> --text … --enter.

Ещё один факт упрощает задачу. Родитель каждого процесса claude во вкладке Orca это zsh. После выхода из Claude Code вкладка остаётся открытой, в ней работает shell. В него можно ввести claude --resume <sessionId>.

ORCA_TERMINAL_HANDLE перестаёт работать после перезапуска Orca. ORCA_PANE_KEY в формате tabId:leafId остаётся верным, по нему скрипт ищет актуальный handle в orca terminal list --json.

Часть 4. Quick Commands в Orca

Quick Command это сохранённая строка текста с меткой. Команды создают в Settings → Quick Commands или кнопкой Add command в панели вкладок. У команды есть область Global или Project и флаг «нажать Enter после».

Способ запуска меняет поведение:

• Кнопка в панели вкладок открывает новую вкладку и выполняет команду в ней.

• Пункт контекстного меню терминала вставляет текст в текущий терминал.

Для перезапуска подходит только второй способ. В новой вкладке нет агента, которого нужно перезапустить.

У Quick Commands в версии Orca 1.4.220 три ограничения:

• В тексте команды нет переменных, sessionId подставить нельзя.
• Одна команда это одна строка. Последовательность «выйти, подождать, возобновить» в неё не помещается.
• Из CLI командами управлять нельзя. Группа orca quick-command есть только в открытом PR #20162.

Поэтому Quick Command содержит один вызов скрипта, а всю работу делает скрипт.

Часть 5. Скрипт claude-restart

Схема

Текст Quick Command: ! claude-restart. Знак ! в Claude Code (да и многих других харнесах) включает режим shell-команды.

1. Claude Code запускает claude-restart как дочерний процесс сессии.
2. Скрипт идёт вверх по дереву процессов и находит pid своего claude.
3. Скрипт читает sessionId из реестра, флаги запуска из ps и вкладку из окружения процесса.
4. Если у сессии есть фоновые shell-команды, скрипт отказывает с кодом 1.
5. Скрипт запускает помощника в новом сеансе процессов через setsid и завершается.
6. Помощник ждёт, пока статус сессии перестанет быть busy.
7. Помощник посылает процессу SIGTERM и ждёт его завершения до 30 секунд.
8. Помощник вводит во вкладку claude --resume <sessionId> с исходными флагами.

Помощник нужен потому, что скрипт работает внутри сессии и умирает вместе с ней. setsid выводит помощника из группы процессов Claude Code.

Код

Файл ~/.local/bin/claude-restart. Зависимости: orca, jq, perl.

Установка

1. Сохраните скрипт в ~/.local/bin/claude-restart.
2. Выполните chmod +x ~/.local/bin/claude-restart.
3. Откройте в Orca Settings → Quick Commands.
4. Создайте команду с меткой Restart Claude, областью Global и текстом ! claude-restart.
5. Включите флаг отправки Enter.

Сводка пробного запуска:

pid:        90335 (busy)
version:    2.1.289 -> 2.1.289
session:    2e7c11a7-ea70-4ac1-8a07-276f397aa29a
pane:       7fd32fe7-e7bf-4ff3-a972-fe2780610d5a:f2c231d4-218a-4889-b9bb-f2c47fca10d0
terminal:   term_62415b02-fb9a-4c85-ad3d-9e0879d7b063
resume:     claude --resume 2e7c11a7-ea70-4ac1-8a07-276f397aa29a
background: none
dry run: nothing sent

Лог боевого запуска в ~/Library/Logs/claude-restart.log:

2026-10-05 18:48:00 exit pid=86624 handle=term_9cf9f3f2-0e80-477b-b3de-a41395a4fe82
2026-10-05 18:48:02 resume: claude --resume 5fd45495-3a66-421f-9a3b-df09fba7bf0b
2026-10-05 18:48:04 OK

Часть 6. Три неочевидные проблемы

Ход модели после !

Вывод shell-команды попадает в контекст, и модель начинает ход: пересказывает сводку. В первой версии помощник ждал 2 секунды и посылал команду выхода. При длинном ходе команда пришла бы посреди ответа.

Теперь помощник читает поле status в реестре и ждёт, пока оно перестанет быть busy. Предел ожидания 120 секунд. После предела помощник ничего не посылает и пишет FAIL в лог.

Меню подсказок перехватывает /exit

Первая версия вводила в TUI текст /exit и Enter. Claude Code на символ / открывает меню команд и скиллов. Указатель мыши над меню меняет выбранный пункт, и Enter запускает другую команду. Так одна рабочая сессия получила чужую команду вместо выхода. Скрипт подождал 30 секунд и не стал вводить команду возобновления:

2026-10-05 17:48:04 exit pid=56293 handle=term_b861a059-2184-40b9-bb4a-17c8fb2ef4eb
2026-10-05 17:48:37 FAIL pid=56293 still alive after 30s, resume not sent

Теперь скрипт ничего не вводит в TUI. Он посылает процессу SIGTERM. Claude Code по этому сигналу завершается штатно и возвращает терминал в обычный режим.

Проверка на 30 секунд в этой истории сработала как задумано. Без неё команда claude --resume … попала бы в живую сессию как запрос к модели.

Вкладка без tabId

Из 22 сессий две не нашлись по ORCA_PANE_KEY. Их вкладки не были смонтированы в окне. Для таких вкладок orca terminal list возвращает tabId и leafId в виде pty:<worktree>@@<id>. Скрипт теперь ищет вкладку по ключу панели и по handle из окружения. После правки нашлись все 22.

Ограничения

• Не полагайтесь на предохранитель для субагентов, Monitor и /loop. Он видит только фоновые shell-команды. Перед нажатием проверьте их сами.
• Скрипт берёт флаги запуска из ps. Аргумент с пробелом внутри теряет кавычки.
• Команда ! claude-restart стоит один ход модели. В проверке это 6 секунд.
• Команду возобновления скрипт вводит в zsh как текст. Плагин автодополнения с выбором мышью может вмешаться так же, как меню Claude Code.
• Реестр ~/.claude/sessions и переменные ORCA_* это внутреннее устройство двух программ. Версии указаны в начале статьи.
• Запускайте Quick Command только из контекстного меню терминала. Кнопка в панели вкладок открывает новую вкладку, и скрипт завершается с ошибкой not running inside a claude session.

Итог

Вечером 2026-10-05 сессии работали на пяти версиях, от 2.1.276 до 2.1.289. На следующий день после двух обновлений осталось две версии: 12 сессий на 2.1.290 и 10 на 2.1.291. В логе claude-restart за это время 8 успешных перезапусков и 2 отказа. Один отказ это ошибка с меню подсказок. Второй это намеренный тест предела ожидания.

Скрипты

claude-code-upgrade

#!/bin/bash
# claude-code-upgrade — upgrades the claude-code@latest Homebrew cask.
# Runs from a LaunchAgent daily at 08:00 and at login:
#   ~/Library/LaunchAgents/com.ihumster.claude-code-upgrade.plist
set -uo pipefail

# launchd PATH is minimal; brew and its helpers need the full one.
export PATH=/opt/homebrew/bin:/opt/homebrew/sbin:/usr/bin:/bin:/usr/sbin:/sbin
export HOMEBREW_NO_ENV_HINTS=1
# Metadata is refreshed by the explicit `brew update` below.
export HOMEBREW_NO_AUTO_UPDATE=1

readonly CASK="claude-code@latest"

# --- Tunables (override via environment) ----------------------------------
BREW="${CCU_BREW:-/opt/homebrew/bin/brew}"
LOG_FILE="${CCU_LOG_FILE:-$HOME/Library/Logs/claude-code-upgrade.log}"

log() {
    printf '%s %s\n' "$(/bin/date '+%Y-%m-%d %H:%M:%S')" "$*" >>"$LOG_FILE"
}

# Prints the installed cask version, or "unknown" when brew cannot tell.
cask_version() {
    local version
    version=$("$BREW" list --cask --versions "$CASK" 2>/dev/null | /usr/bin/awk '{print $2}')
    printf '%s\n' "${version:-unknown}"
}

# Runs a command; on failure logs its exit code and output, returns non-zero.
run_step() {
    local name="$1" output rc
    shift
    output=$("$@" 2>&1)
    rc=$?
    if ((rc != 0)); then
        log "FAIL $name rc=$rc"
        while IFS= read -r line; do log "  $line"; done <<<"$output"
    fi
    return "$rc"
}

main() {
    local before after
    before=$(cask_version)
    # `brew upgrade` alone refreshes metadata at most once per
    # HOMEBREW_AUTO_UPDATE_SECS (24h), so a daily job could miss a build.
    run_step update "$BREW" update || exit 1
    run_step upgrade "$BREW" upgrade --cask "$CASK" || exit 1
    after=$(cask_version)
    if [[ "$before" == "$after" ]]; then
        log "OK up to date $after"
    else
        log "OK upgraded $before -> $after"
    fi
}

main "$@"

com.ihumster.claude-code-upgrade.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.ihumster.claude-code-upgrade</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/ihumster/.local/bin/claude-code-upgrade</string>
    </array>
    <key>StartCalendarInterval</key>
    <dict>
        <key>Hour</key>
        <integer>8</integer>
        <key>Minute</key>
        <integer>0</integer>
    </dict>
    <key>RunAtLoad</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/ihumster/Library/Logs/claude-code-upgrade.stderr.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/ihumster/Library/Logs/claude-code-upgrade.stderr.log</string>
    <key>ProcessType</key>
    <string>Background</string>
</dict>
</plist>

claude-restart

#!/bin/bash
# claude-restart — restarts the Claude Code session of one Orca tab on the
# currently installed binary: SIGTERM, then `claude --resume <id>`.
#
# Meant to be run from inside the session it restarts, as `! claude-restart`
# (Orca Quick Command, inserted into the agent tab). A detached helper does
# the typing through `orca terminal send`, because the script itself dies
# together with the session.
#
#   claude-restart [--dry-run] [--force] [--pid <claude-pid>]
#
#   --dry-run  print what would happen, change nothing
#   --force    restart even when background shell commands are running
#   --pid      target this claude process instead of the calling session
set -uo pipefail

export PATH=/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin

# --- Tunables (override via environment) ----------------------------------
ORCA="${CCR_ORCA:-orca}"
SESSIONS_DIR="${CCR_SESSIONS_DIR:-$HOME/.claude/sessions}"
LOG_FILE="${CCR_LOG_FILE:-$HOME/Library/Logs/claude-restart.log}"
EXIT_TIMEOUT="${CCR_EXIT_TIMEOUT:-30}"
IDLE_TIMEOUT="${CCR_IDLE_TIMEOUT:-120}"

log() {
    printf '%s %s\n' "$(/bin/date '+%Y-%m-%d %H:%M:%S')" "$*" >>"$LOG_FILE"
}

die() {
    echo "claude-restart: $*" >&2
    exit 1
}

comm_of() {
    basename "$(ps -o comm= -p "$1" 2>/dev/null)" 2>/dev/null
}

# Prints the pids from this process up to launchd, one per line.
ancestors() {
    local pid=$$
    while [[ -n "$pid" && "$pid" -gt 1 ]]; do
        echo "$pid"
        pid=$(ps -o ppid= -p "$pid" | tr -d ' ')
    done
}

# Prints the nearest ancestor that is a claude process.
calling_claude_pid() {
    local pid
    for pid in $(ancestors); do
        if [[ "$(comm_of "$pid")" == claude ]]; then
            echo "$pid"
            return 0
        fi
    done
    return 1
}

# Reads one variable from the environment of another process.
env_of() {
    ps eww -o command= -p "$1" | tr ' ' '\n' | sed -n "s/^$2=//p" | head -1
}

# Resolves the live terminal handle of a session. The pane key survives an
# Orca restart, the launch-time handle does not; a tab that is not mounted
# is listed without its pane key, so the handle is the fallback.
handle_of_session() {
    local pane="$1" launch_handle="$2"
    "$ORCA" terminal list --json --limit 500 2>/dev/null |
        jq -r --arg pane "$pane" --arg handle "$launch_handle" \
            '[.result.terminals[] | select(.tabId + ":" + .leafId == $pane or .handle == $handle)]
             | sort_by(.handle == $handle) | .[0].handle // empty'
}

# Prints the launch flags of a claude process without the session selectors.
launch_flags() {
    ps -o args= -p "$1" | awk '{
        out = ""
        for (i = 2; i <= NF; i++) {
            if ($i == "--resume" || $i == "-r") { i++; continue }
            if ($i == "--continue" || $i == "-c") continue
            out = out " " $i
        }
        print substr(out, 2)
    }'
}

# Prints shell children of the session that are not part of this call:
# those are background commands the restart would kill.
background_shells() {
    local claude_pid="$1" child mine
    mine=" $(ancestors | tr '\n' ' ')"
    for child in $(pgrep -P "$claude_pid"); do
        [[ "$mine" == *" $child "* ]] && continue
        case "$(comm_of "$child")" in
            zsh | bash | sh | -zsh | -bash) echo "$child $(ps -o args= -p "$child" | cut -c1-100)" ;;
        esac
    done
}

send() {
    "$ORCA" terminal send --terminal "$1" --text "$2" --enter --json >>"$LOG_FILE" 2>&1
}

# Detached part: runs after the calling shell command has returned.
helper() {
    local pid="$1" handle="$2" resume_cmd="$3" waited=0 idle_waited=0
    # The `!` output starts a model turn; the signal goes out once it is over.
    sleep 2
    while [[ "$(jq -r '.status // empty' "$SESSIONS_DIR/$pid.json" 2>/dev/null)" == busy ]]; do
        if ((idle_waited >= IDLE_TIMEOUT)); then
            log "FAIL pid=$pid still busy after ${IDLE_TIMEOUT}s, nothing sent"
            exit 1
        fi
        sleep 1
        idle_waited=$((idle_waited + 1))
    done
    # A signal, not a typed `/exit`: typed text opens the slash-command menu,
    # where a mouse hover can change which command Enter runs.
    log "exit pid=$pid handle=$handle"
    kill -TERM "$pid" 2>/dev/null || { log "FAIL kill -TERM $pid"; exit 1; }
    while kill -0 "$pid" 2>/dev/null; do
        if ((waited >= EXIT_TIMEOUT)); then
            # Typing the resume command now would land in the TUI as a prompt.
            log "FAIL pid=$pid still alive after ${EXIT_TIMEOUT}s, resume not sent"
            exit 1
        fi
        sleep 1
        waited=$((waited + 1))
    done
    sleep 1
    log "resume: $resume_cmd"
    send "$handle" "$resume_cmd" || { log "FAIL send resume"; exit 1; }
    log "OK"
}

main() {
    local dry_run=0 force=0 pid=""
    while (($#)); do
        case "$1" in
            --dry-run) dry_run=1 ;;
            --force) force=1 ;;
            --pid) pid="${2:-}"; shift ;;
            --helper) shift; helper "$@"; exit 0 ;;
            *) die "unknown argument: $1" ;;
        esac
        shift
    done

    [[ -n "$pid" ]] || pid=$(calling_claude_pid) || die "not running inside a claude session; pass --pid"
    [[ "$(comm_of "$pid")" == claude ]] || die "pid $pid is not a claude process"

    local registry="$SESSIONS_DIR/$pid.json" session_id status version
    [[ -r "$registry" ]] || die "no session registry entry: $registry"
    session_id=$(jq -r '.sessionId // empty' "$registry")
    status=$(jq -r '.status // "unknown"' "$registry")
    version=$(jq -r '.version // "unknown"' "$registry")
    [[ "$session_id" =~ ^[0-9a-f-]{36}$ ]] || die "bad sessionId in $registry"

    local pane handle
    pane=$(env_of "$pid" ORCA_PANE_KEY)
    [[ -n "$pane" ]] || die "pid $pid has no ORCA_PANE_KEY: not an Orca tab"
    handle=$(handle_of_session "$pane" "$(env_of "$pid" ORCA_TERMINAL_HANDLE)")
    [[ -n "$handle" ]] || die "no live Orca terminal for pane $pane"

    local flags resume_cmd shells installed
    flags=$(launch_flags "$pid")
    resume_cmd="claude --resume $session_id${flags:+ $flags}"
    shells=$(background_shells "$pid")
    installed=$(claude --version 2>/dev/null | awk '{print $1}')

    cat <<EOF
pid:        $pid ($status)
version:    $version -> ${installed:-unknown}
session:    $session_id
pane:       $pane
terminal:   $handle
resume:     $resume_cmd
background: ${shells:-none}
EOF

    if [[ -n "$shells" && "$force" -eq 0 ]]; then
        die "background shell commands are running; finish them or pass --force"
    fi
    if ((dry_run)); then
        echo "dry run: nothing sent"
        return 0
    fi

    # New session, so the helper outlives the claude process tree.
    /usr/bin/perl -MPOSIX -e 'fork and exit; POSIX::setsid(); exec @ARGV' \
        "$0" --helper "$pid" "$handle" "$resume_cmd" </dev/null >/dev/null 2>&1
    echo "restarting in 2s; log: $LOG_FILE"
}

main "$@"

Сначала я решил, что удаления идут последовательно, а тяжёлые запросы Django блокируют всю таблицу префиксов. Я выгрузил лог PostgreSQL с запросами дольше пяти секунд и попросил агента помочь разобраться. Агент поправил меня сразу в двух важных местах: запросы шли параллельно, а конкурировали они за блокировки строк. Когда мы сопоставили лог с данными NetBox и логами баласировщика, картина сложилась.

Ниже — разбор инцидента и того, какую часть расследования удалось поручить агенту. Адреса, имена хостов и учётных записей заменены; время и количественные данные сохранены.

Что происходило

NetBox работает на двух нодах, по 16 воркеров gunicorn на каждой. Примерно с 12:30 до 13:08 через HAProxy и nginx клиентам отдавались 502. В это время в PostgreSQL висели долгие запросы к ipam_prefix, а новые запросы к приложению некому было обслуживать.

Началось всё раньше. Первое удаление дубликатов попало в лог в 12:09:07, а уже в 12:09:30 PostgreSQL зафиксировал первую взаимоблокировку при обновлении _children. Между 12:10 и 12:19 таких случаев было 39, хотя приложение ещё отвечало. После очередной серии удалений около 12:30 число одновременных долгих запросов поднялось до 26–32 и держалось на этом уровне почти до 13:08.

Совпадение с числом воркеров выглядит убедительно, но само по себе не доказывает, что это был именно их потолок. Практический результат был виден и без них — запросы застряли, а пользователи получили 502.

Почему удаление одной записи оказалось дорогим

В таблице было много точных копий префиксов без VRF.

NetBox хранит для префикса денормализованные поля _depth и _children. После удаления обработчик post_delete пересчитывает иерархию в той же транзакции. Один запрос обновляет счётчики у содержащих удалённый префикс записей, другой — глубину у вложенных. В SQL используются операторы включения префиксов >>= и <<=, причём равные префиксы тоже попадают в выборку.

Вот где дубликаты становятся проблемой. При удалении префикса внутри вышестоящего префикса пересчёт затрагивает тысячи строк, включая копии этого же и общих предков. После выборки со счётчиками NetBox обновляет строки пачками по 100. Захваченные при обновлении блокировки удерживаются до завершения транзакции.

Одновременно началось несколько таких удалений. Транзакции пытались обновить пересекающиеся наборы строк, ждали друг друга и периодически попадали во взаимоблокировку. В логе за день набралось 84 записи о deadlock.

Это была не одна «тяжёлая команда», после которой всё сломалось. Множество запросов одновременно держали воркеры, ожидая возможности закончить транзакции.

Откуда взялись копии

Такое количество копий префиксов создала одна из наших интеграций, которая занимается инвентаризацией объектов различных систем, которые не имеют возможности поддерживать наш IPAM в актуальном состоянии. Ошибка в коде интеграции породила 54 тыс. дубликатов.

Как избавились от дубликатов

Для следующей очистки мы с агентом подготовили скрипт на Django ORM: он удаляет копии без запуска обработчика пересчёта на каждом удалении, а затем один раз перестраивает иерархию через manage.py rebuild_prefixes. Скрипт отключил как обработчик пересчета так и сигнал ORM для отправки вебхуков в сторону шины данных об удалении префиксов - получить 54 тыс.сообщений в Kafka при отстутвии (пока еще) потребителей этих сообщений мне не улыбалось. Такие работы позволили удалить 54к префикса без какой-либо значительной нагрузки на приложение или его БД.

Це была фабула. А дальше мой короткий рассказ. 😅

Понадобилось мне стало быть в логи nginx пихнуть кусок (именно кусок, а не всю строку ибо там чувствительные данные) строки из заголовка http запроса. Пошёл читать документацию. Понял что необходимое мне можно извлечь из одной переменной в другую через директиву map. И вот я два часа "беседовал" с perplexity/openai-o3 которые отчаянно меня убеждали что результат регулярки (match) или именованную группу нельзя использовать как результат map. И действительно приведенный пример конфига nginx не принимал за валидный конфиг. После чтения документации и пары статей на хабре, в комментариях я таки нашел пример, который натолкнул меня на решение моей задачи, которая в итоге решилась и оказалась простой и элегантной (ввиду простенькой регулярочки которую я уже накидал сам).

В качестве эпилога хочу вам пожелать не верить всяким ИИ, даже если они утверждают что что-то не будет работать. 😁 доверяйте своему инженерному чутью!

У меня всё.

Управление в интерактивном режиме

Чтобы запустить nbshell необходимо открыть в командной строке папку с дистрибутивом приложения и, активировав virtual environment, выполнить команду python netbox/manage.py nbshell

Что бы получить текущую ревизию конфигурации приложения (которая и содержит динамически конфигурируемые параметры) нам понадобится ID текущей (активной) конфигурации, ее можно получить из кэша приложения:

from django.core.cache import cache

activeRevision = ConfigRevision.objects.get(pk=cache.get('config_version'))

Объект activeRevision будет содержать объект типа ConfigRevision, являющийся активной конфигурацией в данный момент ("Curren configuration"). Объект простой, в поле data содержит словарь с динамически конфигурируемыми параметрами (список всех параметров и их значение можно подсмотреть в официальной документации). Однако просто изменить текущую конфигурацию нельзя, конфигурация будет применена только к новой ревизии конфигурации, а значит нам нужно ее создать.

Однако создавать мы ее будем не с нуля, а на базе предыдущей активной конфигурации.

Для примера мы включим параметр MAINTENANCE_MODE, переведя таким образом приложение в режим обслуживания.

# Хорошим тоном будет записать смысл новой ревизии конфига в комментарий
# Заполняем все параметры из текущей конфигурации
newRevsion = ConfigRevision(comment='Enable MM', data=activeRevision.data)
# Изменяем нужный нам параметр
newRevsion.data['MAINTENANCE_MODE'] = True
# Валидируем нашу модель конфигурации на соответствие модели данных,
# заложенных разработчиком
newRevsion.full_clean()
# Сохраняем новую конфигурацию (она автоматически станет активной)
newRevsion.save()

Управление в режиме скрипта

Данный код можно склеить в одну строку, разделив строки точкой с запятой ; и передать одним аргументом для nbshell.

python netbox/manage.py nbshell -c "from django.core.cache import cache; activeRevision = ConfigRevision.objects.get(pk=cache.get('config_version')); newRevsion = ConfigRevision(comment='Enable MM', data=activeRevision.data); newRevsion.data['MAINTENANCE_MODE'] = True; newRevsion.full_clean(); newRevsion.save();"

Для мультинодовых конфигураций

UPD: Работа с существующей конфигурацией

Если же хочется изменить какую-то текущую конфигурацию или просто сделать ее активной (например, откатиться на предыдущую), то сделать это можно через встроенный метод класса ConfigRevision - activate()

revision = ConfigRevision.object.get(pk=revisionNumber)
revision.activate()

Сложность, с которой я столкнулся, заключалась в том, что используемая нами инсталляция Netbox имеет множество активных пользователей импортированных из Active Directory, активную ролевую модель основанную на группах из Active Directory и потерять все эти ассоциации очень не хотелось бы.

Изучая документацию на модуль python-social-auth (а также код самого модуля и его бэкэнд к Keycloak) я наткнулся на раздел Extending the Piplene и понял что весь конвеер авторизации легко настраивается и изменяется, однако придётся немного по-питонить.

Проблемы с которыми я столкнулся

Собственно их было две:

1. Дефолтный Pipeline падает при наличии в Netbox пользователей с одинаковыми email (это специфический случай, который характерен для нашей организации и с которым вы можете никогда не столкнуться. Для снятия лишних вопросов скажу что, у нас есть правило записывать в поле email соответствующий email владельца технической учётной записи)
2. Дефолтный Pipeline не обновляет членство в группах (а вот это уже критично для ролевой модели доступа основанной на группах).

Дефолтный Pipeline

Дефолтный pipeline для Netbox определяется в модуле <your-netbox-folder>/netbox/netbox/settings.py и выглядит так:

SOCIAL_AUTH_PIPELINE = (
    'social_core.pipeline.social_auth.social_details',
    'social_core.pipeline.social_auth.social_uid',
    'social_core.pipeline.social_auth.social_user',
    'social_core.pipeline.user.get_username',
    'social_core.pipeline.social_auth.associate_by_email',
    'social_core.pipeline.user.create_user',
    'social_core.pipeline.social_auth.associate_user',
    'netbox.authentication.user_default_groups_handler',
    'social_core.pipeline.social_auth.load_extra_data',
    'social_core.pipeline.user.user_details',
)

Он содержит функции из дефолтного, для модуля python-social-auth, конвеера, за исключением функции user_default_groups_handler из модуля <your-netbox-folder>/netbox/netbox/authentication.py (строка 'netbox.authentication.user_default_groups_handler').

Решение проблемы №1

В первых трех функциях Pipeline происходит получение и декодирование JWT access_token из которого извлекаются различные поля, которые передаются клиенту (в нашем случае Netbox) от Keycloak, и помещаются в переменную details (dict содержащий данные о пользователе, на базе которых пайплайн должен будет создать или обновить данные пользователя Netbox).

Функция get_username создает на базе совокупности различных настроек приложения и модуля python-social-auth имя пользователя, а функция associate_by_email пытается по email найти в БД Netbox соответствующего пользователя.

Функция associate_by_email выглядит так:

def associate_by_email(backend, details, user=None, *args, **kwargs):
    """
    Associate current auth with a user with the same email address in the DB.

    This pipeline entry is not 100% secure unless you know that the providers
    enabled enforce email verification on their side, otherwise a user can
    attempt to take over another user account by using the same (not validated)
    email address on some provider.  This pipeline entry is disabled by
    default.
    """
    if user:
        return None

    email = details.get("email")
    if email:
        # Try to associate accounts registered with the same email address,
        # only if it's a single object. AuthException is raised if multiple
        # objects are returned.
        users = list(backend.strategy.storage.user.get_users_by_email(email))
        if len(users) == 0:
            return None
        elif len(users) > 1:
            raise AuthException(
                backend, "The given email address is associated with another account"
            )
        else:
            return {"user": users[0], "is_new": False}

Очевидно, что при наличии в в БД нескольких пользователей в одинаковым email эта функция упадёт.

Чтобы решить эту проблему я создал новый модуль и переписал эту функцию так, чтобы использовать для ассоциации не только поле email но username.

import re
from social_core.exceptions import AuthException


def associate_by_email_and_username(backend, details, user=None, *args, **kwargs):
    """
    Associate current auth with a user with the same email address and username in the DB.
    """
    if user:
        return None
    email = details.get("email")
    username = details.get("username")
    # If username in upn format, get username part
    if m:=re.match(r"^(?:(?P<username>[^@]+)@(?P<domain>.+))quot;, username):
        username = m.group('username')
    if email:
        users = list(backend.strategy.storage.user.get_users_by_email(email))
        if len(users) == 0:
            return None
        elif len(users) > 1:
            for u in users:
                if u.username == username:
                    return {"user": u, "is_new": False}
            raise AuthException(
                backend, "The given email address is associated with another account"
            )
        else:
            return {"user": users[0], "is_new": False}
    else:
        raise AuthException(backend, "No email address returned")

Функция извлекает из словаря details username, если он в формате userPrincipalName - извлекает из него username часть и при наличии в БД Netbox пользователей с одинаковым email проводит дополнительную проверку по полю username.

Остается только собрать пакет из модуля, импортировать его в venv окружение, в котором работает Netbox, и переопределить в настройках приложения Pipeline (об этом расскажу ниже).

Решение проблемы №2

Изучив встроенную функцию netbox.authentication.user_default_groups_handler я понял что она назначает пользователю только группы определенные в переменной REMOTE_AUTH_DEFAULT_GROUPS из configuration.py. Я принял решение заменить эту функцию в конвеере совместив с функциональностью обновления групп, полученных от Keycloak.

Код этой функции будет выглядеть так:

import logging
from django.conf import settings
from django.contrib.auth.models import Group

def update_user_groups(backend, response, user=None, *args, **kwargs):
    """
    Custom pipline handler with adds remote auth users to extist groups or
    create non-exist groups
    """
    logger = logging.getLogger(
        "netbox-social-auth-custom.auth_username.update_user_groups_handler"
    )
    if not user:
        return None
    else:
        user_groups = []
        auth_groups = response.get("groups", [])
        user.groups.clear()

        # Add or Create DEFAULT USER GROUPS defined in configuration.py
        for name in settings.REMOTE_AUTH_DEFAULT_GROUPS:
            group, created = Group.objects.get_or_create(name=name)
            user_groups.append(group)

        # Add or Create Social Auth user groups
        # groups should be added to access token as array (list) of names
        for name in auth_groups:
            group, created = Group.objects.get_or_create(name=name)
            user_groups.append(group)

        if user_groups:
            user.groups.add(*user_groups)
        else:
            logger.info(
                f"No any groups assignments for {user}. May be REMOTE_AUTH_DEFAULT_GROUPS incorrectly set\
                  or not returned from OAuth provider"
            )

Переопределение Pipeline

Итак, обе функции помещены в файл, который я назвал auth_username.py, сложены в папки netbox-social-auth-custom/pipeline (вторая папка больше для красоты в названии - обозначения что это часть pipeline по аналогии с модулем social_core) и из этого собран python package (как собирать python-пакеты я описывать не буду, т.к. для этого есть куча разного инструментария и соответствующих гайдов - например такой, разве что подскажу, что не плохо бы при сборке указать зависимость от social-auth-core>=4.5).

Пакет установлен в окружении venv нашего Netbox и остается только переопределить собственно сам Pipline. Для этого в файле configuration.py переопределяется переменная SOCIAL_AUTH_PIPELINE в виде вот такого массива:

SOCIAL_AUTH_PIPELINE = (
    'social_core.pipeline.social_auth.social_details',
    'social_core.pipeline.social_auth.social_uid',
    'social_core.pipeline.social_auth.social_user',
    'social_core.pipeline.user.get_username',
    'netbox_social_auth_custom.pipeline.auth_username.associate_by_email_and_username',
    'social_core.pipeline.user.create_user',
    'social_core.pipeline.social_auth.associate_user',
    'social_core.pipeline.social_auth.load_extra_data',
    'social_core.pipeline.user.user_details',
    'netbox_social_auth_custom.pipeline.auth_username.update_user_groups',
)

Собственно на этом всё. Спасибо что дочитали, надеюсь это кому-то пригодится.

UPD: Отладка Pipline

Забыл написать про отладку вашего (или вообще) конвеера авторизации. Чтобы в увидеть в логах или dev-консоли сервера Netbox

UPD: Отладка Pipline

Забыл написать про отладку вашего (или вообще) конвеера авторизации. Чтобы в увидеть в логах или dev-консоли сервера Netbox отладочную информацию добавьте в конец (или перед падающей функцией конвеера) строку

'social_core.pipeline.debug.debug',

С приятным удивлением обнаружил механизм, который в Ansible появился с релизом ansible-core 2.11 (апрель 2021) и называется он Role argument validation. Исходя из собственного опыта написания модулей Ansible, я предполагаю, что в данном механизме используется тот же самый код, что и при валидации аргументов модуля (по крайней мере, всё на это указывает).

Более того, этот механизм позволяет, помимо валидации аргументов, документировать вашу роль. После добавления файла, описывающего Ваш набор переменных, Вы получаете документированную роль, документацию по которой можно вызвать при помощи ansible-doc.

ansible-doc --type role --roles-path <you roles path> <role_name>

Пример вызова такой роли:

Реализация

Для создания подобной функциональности используется файл meta/argument_specs.yml. Его формат описан в документации и довольно прост. Более того, у Вашей роли может быть не одна точка входа (по умолчанию это main.yml) но и дополнительные, возможно для вызова через ansible.builtin.import_role или ansible.builtin.include_role, набор параметров для каждой точки входа можно описать в этом файле. Также параметры можно пометить обязательными, указать тип данных (набор типов данных, которые умеет проверять AnsibleModule тут), который должен содержаться в параметре, его значение по умолчанию (если оно находится в ../defaults/<entry-point>.yml, например) ну и, конечно же, описание (short_description и description для точки входа и description для каждого параметра).

В дальнейшем роль, имеющая такое описание параметров при вызове будет проверять набор необходимых параметров автоматически отдельным таском.

При вызове роли через ansible.builtin.import_role или ansible.builtin.include_role есть возможность отключить проверку аргументов, используя параметр rolespec_validate установленный в false.

Установить модуль можно из PowershellGallery:

Install-Module -Name Microsoft.PowerShell.TextUtility -AllowPrerelease

Пример использования:

PS> df | select -first 6 | convertfrom-texttable -ConvertPropertyValue | Format-Table

Filesystem 1K-blocks      Used Available Use% Mounted_on
---------- ---------      ---- --------- ---- ----------
none         8167564         4   8167560 1%   /mnt/wsl
none       498723140 443586308  55136832 89%  /usr/lib/wsl/drivers
none         8167564         0   8167564 0%   /usr/lib/wsl/lib
/dev/sdc   263112772  27894640 221779976 12%  /
rootfs       8164316      1936   8162380 1%   /init

Командлет позовляет указать где определяется строка заголовков или если ее нет просто брать табличные данные и превращать их в массив объектов.

PS> ls -l | select -First 5 | ConvertFrom-TextTable -Skip 1 -NoHeader | ft

Property_01 Property_02 Property_03 Property_04 Property_05 Property_06 Property_07 Property_08 Property_09
----------- ----------- ----------- ----------- ----------- ----------- ----------- ----------- -----------
drwxr-xr-x  3           ihumster    ihumster    4096        Aug         21          2022        aac-base
drwxr-xr-x  3           ihumster    ihumster    4096        Jul         20          23:48       ansible_collections
drwxr-xr-x  7           ihumster    ihumster    4096        Apr         30          15:43       ansible-module-vcloud-director
drwxr-xr-x  3           ihumster    docker      4096        Jun         14          2022        ansible-netbox-dev

Модуль еще находится в процессе разработки и если он вам понравился и пригодился, но вы нашли какую-либо ошибку, то оставить баг-репорт можно прямо в разделе Issues репозитория.

В 10.4.1 ужесточили еще один аспект инфраструктуры, а именно подключение к ESXi хостам. В результате, после обновления до 10.4.1 (и автоматическом переходе на новую консоль, старую выпилили таки, и слава богу), в VCD перестанут работать операции требующие прямого доступа к хосту, а именно доступ к консоли ВМ, ипорту OVF/ISO, Guest Customization.

В логах это может отобразиться в виде следующих сообщений:

[ 88fc5c17-f0c7-4021-922b-5dfe1b84b7cd ] PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
 - PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
 - PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
 - unable to find valid certification path to requested target

 2023-02-24 02:59:01,050 | ERROR    | pool-jetty-81             | ServerWebSocket                | Connecting to ESX esx01.lab.ihumster.ru [server: [L=/192.168.168.25:443 R=/192.168.168.30:60004]] [client: [id: 0x13240ef6, L:/192.168.168.25:52056 ! R:esx01.lab.ihumster.ru/192.168.168.101:443]] |
io.netty.handler.codec.DecoderException: javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Решение

Самый простой вариант - это запустить повторно CMT trust-infra-certs:

./cell-management-tool trust-infra-certs --vsphere --unattended
Downloading certificates for 2 host(s), including 1 vCenter(s):
        vc-mng.lab.ihumster.ru                                      [Download: SUCCESS] (VMCA)
        vc-mng.lab.ihumster.ru                                      [Download: SUCCESS] (VMCA)
        vc-mng.lab.ihumster.ru                                      [Download: SUCCESS]
        nsx.lab.ihumster.ru                                         [Download: SUCCESS]
Downloaded certificates for 3/2 host(s).
Trusting certificates for 2 host(s):
        vc-mng.lab.ihumster.ru                                       [Already Trusted: SUCCESS]
        nsx.lab.ihumster.ru                                          [Already Trusted: SUCCESS]
Trusting VMCA certificates for 1 vCenter(s):
        vc-mng.lab.ihumster.ru                                       [Add Trusted: SUCCESS] (VMCA) - alias=vc-mng.lab.ihumster.ru_vmca_2023-02-24-11-05-13
Trusted 3/3 downloaded certificates.

Или самостоятельно скачать с vCenters их сертификаты VMCA (<vcenter>/certs/download.zip) и вручную добавить VMCA сертификаты в Trusted Certificates вашего VCD.

Для VCD с большим количеством vCenters (или организаций с высокими требованиями к безопасности инфраструктурных компонентов) самым правильным путём, по моему мнению, будет вариант с заменой сертификата VMCA на vCenters на подписанный с внутреннего или внешнего CA и последующей регенерацией сертификатов ESXi.

Вооружившись DevTools я за несколько итераций записал все необходимые API вызовы, которые происходят при выполнении этапов Initial Setup Wizard и после, проверив возможность их воспроизведения сторонними средствами (воспроизводил в Postman) решил что хочу записать их в виде документации OpenAPI 3.0 что бы любой мог импортировать ее в Postman и ознакомиться с деталями запросов.

По этому спешу представить Вам первую версию документации к VCDA Initial Setup API. В репозиторий добавлена также готовая коллекция для Postman (на случай если вы не умеете генерировать коллекцию из OpenAPI спецификации).

В коллекции все запросы пронумерованы в порядке выполнения их в Wizard. Отдельно не пронумерован один Get запрос - он используется для проверки доступности той или иной системы (VCD, vCenter server, ReplicatorAppliance, Tunnel Appliance) из VCDA Manager, а также возвращает SSL-сертификат используемый системой (сам сертефикат в PEM-encoded формате, его thumbprint - используются в остальных запросах).

Конфигурация VCDA которую я изучал - это рекомендуемая в продуктивной среде конфигурация из отдельных "ролевых" аплайнсов - manager, replicator, tunnel. Для combined и vc_combined версии, последовательность и структура запросов скорее всего иная (в vc_combined например не используется VCD).

Также, если вы используете несколько replicator аплайнсов то соответствующие запросы необходимо будет проделать для каждого аплайнса последовательно.

Для работы с этим API вам необходимы минимум 3 задеплоенных удобным вам способом аплайнса.

Добавьте следующую строку между запросами версии и получением access_token, либо после них:

pm.request.headers.get('Accept').replace('application\/json;version=(?<version>\d{2}\.\d{1})','application/json;version={{apiVersion}}')