Протокол VCLI — Скриптинг интерфейса командной строки
Использование Varnish CLI в качестве API предоставляет ряд возможностей.
Во-первых: vcli.h содержит магические числа.
Во-вторых: если вы используете varnishadm для подключения к varnishd в целях API, используйте аргумент -p, чтобы получить режим «pass».
В режиме «pass» или при прямых подключениях к командной строке (подробнее ниже), первая строка ответа всегда имеет длину ровно 13 байт, включая символ новой строки, и содержит два числа: код состояния и количество байт в «теле» ответа:
200␣19␣␣␣␣␣␣ PONG␣1613397488␣1.0
Это делает парсинг ответа однозначным, даже в таких случаях, когда ответ не заканчивается символом новой строки.
Библиотека varnishapi содержит функции для реализации основ протокола командной строки. Для более подробной информации см. файл include vcli.h.
Локальные и удаленные подключения к командной строке
Процесс varnishd получает команды командной строки через TCP-соединения, которые требуют аутентификации по предварительно разделенному ключу (см. ниже), но не обеспечивают конфиденциальности.
«Отсутствие конфиденциальности» означает, что если вы настраиваете эти TCP-соединения для работы через сеть, любой, кто может перехватывать пакеты, сможет увидеть ваши команды командной строки. Если вам нужна конфиденциальность, используйте ssh для запуска varnishadm или для туннелирования TCP-соединения.
По умолчанию varnishd привязывается к localhost и просит ядро назначить случайный номер порта. Результирующий адрес прослушивания сохраняется в общей памяти, где программа varnishadm его находит.
Вы можете настроить varnishd для прослушивания определенного адреса с помощью аргумента -T, это также будет записано в общую память, поэтому varnishadm продолжает работать:
# Bind to internal network varnishd -T 192.168.10.21:3245
Вы также можете настроить varnishd на активное открытие TCP-соединения с другой программой-«контроллером» с помощью аргумента -M.
Наконец, при запуске в «отладочном режиме» с аргументом -d, varnishd останется в фоновом режиме и превратит stdin/stdout в подключение к командной строке.
Аутентификация подключений к командной строке
Подключения к командной строке varnishd аутентифицируются с помощью схемы аутентификации «предварительно разделенного ключа», где другая сторона должна доказать, что знает содержимое секретного файла, который использует varnishd.
Им не обязательно читать один и тот же файл на конкретном компьютере; они могут прочитать совершенно другой файл на другом компьютере или получить секрет с сервера.
Имя файла можно настроить с помощью опции -S, и varnishd записывает имя в общую память, чтобы varnishadm мог его найти.
В минимальном варианте varnishd должен иметь возможность читать файл, но помимо этого его можно ограничить любым образом.
Поскольку важен не сам файл, а только его содержимое, вы можете сделать файл недоступным для всех и вместо этого поместить копию файла в домашние каталоги авторизованных пользователей.
Файл считывается только в момент выполнения команды командной строки auth, и содержимое не кэшируется в varnishd, поэтому вы можете изменять его так часто, как вам нужно.
Аутентифицированное сеанс выглядит так:
critter phk> telnet localhost 1234 Trying ::1... Trying 127.0.0.1... Connected to localhost. Escape character is '^]'. 107 59 ixslvvxrgkjptxmcgnnsdxsvdmvfympg Authentication required. auth 455ce847f0073c7ab3b1465f74507b75d3dc064c1e7de3b71e00de9092fdc89a 200 279 ----------------------------- Varnish Cache CLI 1.0 ----------------------------- FreeBSD,13.0-CURRENT,amd64,-jnone,-sdefault,-sdefault,-hcritbit varnish-trunk revision 89a558e56390d425c52732a6c94087eec9083115 Type 'help' for command list. Type 'quit' to close CLI session. Type 'start' to launch worker process.
Код состояния CLI 107 указывает на необходимость аутентификации. Первые 32 символа текста ответа — это запрос «ixsl…mpg». Запрос генерируется случайным образом для каждого подключения к командной строке и меняется каждый раз, когда отправляется 107.
Для вычисления аутентификатора «455c…c89a» должен использоваться самый последний отправленный запрос.
Аутентификатор вычисляется путем применения функции SHA256 к следующей последовательности байтов:
- Строка запроса
- Символ новой строки (0x0a)
- Содержимое секретного файла
- Строка запроса
- Символ новой строки (0x0a)
и вывода полученного дайджеста в нижнем регистре в шестнадцатеричном формате.
В приведенном выше примере секретный файл содержит foo\n, и, следовательно:
critter phk> hexdump secret 00000000 66 6f 6f 0a |foo.| 00000004 critter phk> cat > tmpfile ixslvvxrgkjptxmcgnnsdxsvdmvfympg foo ixslvvxrgkjptxmcgnnsdxsvdmvfympg ^D critter phk> hexdump -C tmpfile 00000000 69 78 73 6c 76 76 78 72 67 6b 6a 70 74 78 6d 63 |ixslvvxrgkjptxmc| 00000010 67 6e 6e 73 64 78 73 76 64 6d 76 66 79 6d 70 67 |gnnsdxsvdmvfympg| 00000020 0a 66 6f 6f 0a 69 78 73 6c 76 76 78 72 67 6b 6a |.foo.ixslvvxrgkj| 00000030 70 74 78 6d 63 67 6e 6e 73 64 78 73 76 64 6d 76 |ptxmcgnnsdxsvdmv| 00000040 66 79 6d 70 67 0a |fympg.| 00000046 critter phk> sha256 tmpfile SHA256 (tmpfile) = 455ce847f0073c7ab3b1465f74507b75d3dc064c1e7de3b71e00de9092fdc89a critter phk> openssl dgst -sha256 < tmpfile 455ce847f0073c7ab3b1465f74507b75d3dc064c1e7de3b71e00de9092fdc89a
Файл исходного кода lib/libvarnish/cli_auth.c содержит полезную функцию, которая вычисляет ответ, имея открытый дескриптор файла секретного файла и строку запроса.
См. также:
Copyright © 2006 Verdens Gang AS
Copyright © 2006–2020 Varnish Software AS
Licensed under the BSD-2-Clause License.
https://varnish-cache.org/docs/7.4/reference/cli_protocol.html
