Установка из командной строки

Обычная установка ключей не требует: скрипт сам определяет платформу и процессор, скачивает последний выпуск, проверяет подпись и ставит программу. Эта страница — справочник по ключам установщика. Он пригодится, когда установку ведёт не человек (скрипт, Ansible, cron), когда нужен конкретный выпуск, а не последний, или когда автоопределение платформы и процессора ошиблось.

Первая установка по шагам — в разделе Установка, обновление уже работающей программы — в разделе Обновления.

Как передать ключи

Если установщик уже лежит на роутере, ключи пишутся после имени файла:

sh install.sh --dry-run --verbose

Если установщик запускается прямо из сети, ключи идут после sh -s --:

curl -fsSL https://kvaspro.su/install.sh | sh -s -- --dry-run

Порядок ключей значения не имеет, а запись через знак равенства равнозначна записи через пробел: --version=0.22.45 — то же самое, что --version 0.22.45. Незнакомый ключ установщик называет вслух и завершает работу, ничего на роутере не меняя.

Все ключи

Ключи подробно

--clean: установка «начисто»

Ключ удаляет всё, что оставила прежняя установка: службу и её автозапуск, правила сети, исполняемый файл и каталог данных целиком — конфигурацию, базу, токен входа, реестр РКН и geoip. После этого программа ставится как на новом роутере: с новым токеном и пустой базой. Прежние настройки не сохраняются, откатиться будет некуда — поэтому ключ и назван явно.

sing-box при этом остаётся на месте: это внешняя зависимость, а не часть Квас Про; установщик обновит её, только если версия несовместима. Если прежней установки нет, ключ ничего не делает — установщик просто сообщает об этом.

--version <номер|latest>: конкретный выпуск

Без ключа ставится последний выпуск раздачи. Ключ нужен, когда нужен именно определённый номер — например, для возврата на прежнюю сборку или для повторения установки на нескольких роутерах с одинаковой версией. Номер пишется с ведущей «v» или без неё: v0.22.45 и 0.22.45 — одно и то же. Слово latest равнозначно отсутствию ключа.

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

--platform entware|openwrt: платформа вручную

Платформа определяется сама, и вручную её задают редко — когда автоопределение ошиблось. Допустимы два значения: entware (Keenetic/Netcraze с Entware) и openwrt. Любое другое значение установщик отвергает, ничего не устанавливая.

--arch <вариант>: какой вариант указывать

Скрипт определяет процессор сам: по имени из uname -m, а на MIPS — ещё и по порядку байт (он смотрит заголовок исполняемого файла и, если есть opkg, спрашивает opkg print-architecture). Вручную вариант нужен, только если определение ошибочно. Доступны три варианта:

Как узнать свой: выполните на роутере opkg print-architecture (нужен вход по SSH) — хранилище Entware называет архитектуру так, как её видит само: aarch64-k3.10, armv7sf-k3.2, mipsel-3.4. На OpenWrt ту же роль играет строка DISTRIB_ARCH в файле /etc/openwrt_release (например, mipsel_24kc или aarch64_cortex-a53). Команда uname -m для ARM подходит, но на MIPS показывает просто mips и не отличает прямой порядок байт от обратного. Готовые пакеты публикуются под aarch64, armv7 и mipsel: пакет под mipsel выходит вместе с остальными, а если в текущем выпуске его нет, установщик сообщит об этом и ничего на роутере не изменит. Если указать вручную вариант, которого среди них нет, скрипт предупредит, что готового пакета может не быть, и всё равно попробует скачать.

--base-url <адрес>: чужой источник раздачи

По умолчанию скрипт берёт все файлы выпуска с сайта проекта — https://kvaspro.su. Другой источник раздачи — это зеркало: копия тех же файлов на другом сервере. Оно нужно, когда роутер не может открыть сайт проекта: доступ закрыт из вашей сети, канал слишком медленный, или у вас во внутренней сети есть свой веб-сервер.

Чтобы поднять зеркало, скопируйте с сайта проекта те же файлы, сохранив пути:

• /install.sh и /install.sh.sha256 — сам установщик и его контрольная сумма;
• /releases/latest.json — указатель последней версии;
• /releases/index.json — список выпусков раздачи: сам установщик его не скачивает, он нужен человеку, чтобы найти номер нужного выпуска (установщик подсказывает этот адрес, когда выпуск не найден);
• /releases/<версия>/manifest-<платформа>-<архитектура>.json — описание выпуска, например manifest-entware-aarch64.json: в нём хэш и подпись архива;
• сам архив выпуска и файл подписи, на которые ссылается манифест.

Затем укажите адрес зеркала:

sh install.sh --base-url https://mirror.example.ru

Примерить зеркало без установки: добавьте --dry-run — установщик скачает и проверит выпуск, но ничего не изменит.

--sha256 <хэш>: жёсткое закрепление выпуска

Ожидаемая контрольная сумма архива. Если она не совпадёт с той, что записана в описании выпуска (манифесте), установка остановится. Так выпуск закрепляют жёстко — например, при массовой установке одной и той же сборки на парк устройств: подменить архив на раздаче незаметно не получится.

--staging <каталог>: если мало места

Скачанный архив распаковывается в рабочий каталог рядом с данными программы, а по окончании установки этот каталог удаляется. Если в каталоге данных мало места, укажите другой каталог на диске, например --staging /opt/kvaspro-install (на OpenWrt подойдёт другой раздел — скажем, подготовленный USB-накопитель).

Раздел в оперативной памяти (tmpfs) не подойдёт: установщик откажется, чтобы крупный архив не занял память роутера. Каталог нельзя указывать как каталог данных, каталог программ или корень, и он не должен быть символической ссылкой.

--dry-run: примерка без изменений

Установщик делает всё, кроме изменений на роутере: определяет платформу, скачивает выпуск, проверяет контрольные суммы и криптоподпись, проверяет свободное место — и печатает план: что именно было бы сделано. Ни служба, ни файлы, ни сеть не затрагиваются.

Примерка полезна перед обновлением на новую версию и при проверке зеркала. В конце установщик прямо предлагает повторить запуск без ключа, чтобы установить по-настоящему.

--quiet, --verbose, --log-file: сколько рассказывать

• --quiet (-q) — только итог и ошибки: удобно, когда вывод читает машина.
• --verbose (-v) — печатает выполняемые команды: удобно при разборе проблем.
• --log-file <путь> — журнал диагностики по своему пути. По умолчанию журнал пишется во временный каталог, а его путь печатается вместе с сообщением об ошибке. Журнал остаётся на диске и после неудачной установки: в нём видно, на каком шаге что произошло.

--no-progress и --no-color: оформление вывода

• --no-progress — без бегунка и индикатора загрузки: для журналов, записи экрана и медленных консолей.
• --no-color — без цвета. То же самое делает переменная окружения NO_COLOR (это общий стандарт no-color.org, его понимают многие программы).

--print-token: токен в журнале

При обычной установке скрипт печатает токен входа (ваш ключ-пароль к панели). Если вывод перенаправлен в файл или в журнал, токен не печатается — иначе он навсегда остался бы там, где его сможет прочитать кто угодно. Ключ --print-token печатает токен даже при перенаправлении вывода: он нужен автоматике, которая сама сохраняет токен в защищённое место.

Посмотреть токен позже можно на роутере командой kvaspro --key.

-h, --help: справка

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

Переменные окружения

Служебные переменные стенда (KVASPRO_PATH_EXTRA, KVASPRO_BIN_DIR, KVASPRO_CFG_DIR, KVASPRO_INIT_SCRIPT) переопределяют пути установки и порядок поиска утилит. Они нужны при обкатке установщика на стенде — на роутере их задавать не следует.

Коды возврата

Автоматике стоит считать успехом только код 0: при 1 и 2 на роутере ничего не изменено, при 130 работу можно просто повторить.

Примеры для автоматики

Примерка обновления — увидеть, что будет сделано, и ничего не менять:

sh install.sh --dry-run

Тихая установка конкретного выпуска с журналом — для скрипта или Ansible:

sh install.sh --version 0.22.45 --quiet --log-file /tmp/kvaspro-install.log

Закрепление выпуска по контрольной сумме — одна и та же сборка на парке роутеров:

sh install.sh --sha256 <хэш архива из описания выпуска>

Переустановка «начисто» — когда прежние настройки не нужны:

sh install.sh --clean

Установка с зеркала, когда сайт проекта недоступен из вашей сети:

sh install.sh --base-url https://mirror.example.ru --dry-run

Справка установщика целиком

Так выглядит вывод sh install.sh --help (установщик версии 2.9.19). Ширина рамок подстраивается под окно терминала; на узком экране строки переносятся.

────────────────────────────────────────────────────────────────────────────────

 ██╗  ██╗ ██████╗   █████╗   ██████╗
 ██║ ██╔╝ ██╔══██╗ ██╔══██╗ ██╔════╝
 █████╔╝  ██████╔╝ ███████║ ██║ ПРО
 ██╔═██╗  ██╔══██╗ ██╔══██║ ██║
 ██║  ██╗ ██████╔╝ ██║  ██║ ╚██████╗
 ╚═╝  ╚═╝ ╚═════╝  ╚═╝  ╚═╝  ╚═════╝
 Курс добра        установщик v2.9.19
────────────────────────────────────────────────────────────────────────────────
Использование:
  sh install.sh [параметры]
  curl -fsSL https://kvaspro.su/install.sh | sh

Параметры:
  --clean                     установить начисто: прежняя установка удаляется
  --version <номер|latest>    выпуск для установки (по умолчанию последний);
                              номер — с ведущей «v» или без: v0.22.45 = 0.22.45
  --platform entware|openwrt  задать платформу вручную (иначе автоопределение)
  --arch <target>             задать архитектуру вручную (иначе автоопределение)
  --base-url <url>            другой источник раздачи (по умолчанию сайт)
  --staging <dir>             рабочий каталог на диске (не в оперативной памяти)
  --sha256 <hex>              ожидаемая контрольная сумма архива (пиннинг)
  --quiet, -q                 печатать только итог и ошибки
  --verbose, -v               показывать выполняемые команды
  --dry-run                   показать план: скачать и проверить, не меняя
  --log-file <путь>           журнал диагностики
  --no-color                  без цвета (то же делает переменная NO_COLOR)
  --no-progress               без бегунка и индикатора загрузки
  --print-token               печатать токен даже при перенаправлении вывода
  -h, --help                  эта справка (с баннером между разделителями)

Без ключа --version ставится последний выпуск раздачи; если указанного выпуска
нет, установщик сообщает об этом и ничего на устройстве не меняет. Вопросов
установщик не задаёт — установка ни на чём не останавливается.

Переменные окружения:
  NO_COLOR=1                  без цвета (стандарт no-color.org)
  KVASPRO_ASCII=1             ASCII-знаки вместо юникодных
  TMPDIR                      каталог для журнала диагностики

Примеры:
  sh install.sh                       # обычная установка (последний выпуск)
  sh install.sh --clean               # стереть прежнюю и поставить заново
  sh install.sh --version 0.22.45     # поставить указанный выпуск
  sh install.sh --dry-run             # только проверка и план
  sh install.sh --sha256 <hex>        # пиннинг конкретного выпуска

Что дальше

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

Смежные разделы: Установка · Удаление Квас Про с роутера · Обновления · Если что-то не так