Усталяванне з каманднага радка

Звычайнае ўсталяванне ключоў не патрабуе: скрыпт сам вызначае платформу і працэсар, спампоўвае апошні выпуск, правярае подпіс і ставіць праграму. Гэтая старонка — даведнік па ключах усталёўшчыка. Ён спатрэбіцца, калі ўсталяванне вядзе не чалавек (скрыпт, 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>        # пиннинг конкретного выпуска

Что дальше

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

Сумежныя раздзелы: Усталяванне · Выдаленне Квас Про з роўтара · Абнаўленні · Калі штосьці не так