Консольная оболочка nsgsh представляет собой пользовательский интерфейс к демону nsgconfd, предназначенный для управления устройством в режиме командной строки. nsgsh устанавливается в качестве единственно доступной командной оболочки для пользователя nsg и для всех дополнительных пользователей при подключении через Telnet, SSH или консольный порт. Интерактивная работа пользователя в nsgsh подробно описана в общей части данной справки.

nsgsh может быть запущена из bash в интерактивном режиме (без параметров, либо с ключом -i) или в пакетном режиме. При запуске в пакетном режиме операндами команды являются узлы меню, вплоть до значения конечного параметра. Список команд, доступных в каждом узле, можно просмотреть по нажатию одной лишь клавиши Enter в интерактивном режиме; важно помнить, однако, что он может формироваться динамически.

ВНИМАНИЕ! При исполнении nsgsh из-под bash запускается отдельная сессия пользователя root, на которую распространяются общие правила открытия сессий для nsgsh и Web-управления. В частности, если в этот момент на устройстве уже имеется сессия со статусом администратора, а скрипт также содержит команды, для которых требуются права администратора, то возникает конфликт между ними. Грубые способы разрешения этого конфликта — по принципу "если не ты — то тебя", как принято в нашем животном мире. Либо скрипт не будет исполнен из-за отсутствия необходимых прав доступа, либо перед его исполнением следует принудительно завершить сессию администратора:

nsgsh .system.sessions.close=admin; nsgsh опции команды ...

и потерять при этом все сделанные, но не сохранённые изменения.
Более щадящий выход предлагается опцией --force (см. ниже).

Формат командной строки:

nsgsh опции путь.параметр=значение [[путь.параметр=значение]  ... ]

При вызове без каких-либо опций и параметров nsgsh запускается в интерактивном режиме.

Опции командной строки:

-С

Запуск в экранном режиме вместо консольного.

-с

Пустая опция для совместимости с синтаксисом других оболочек. Позволяет, в частности, исполнять команды nsgsh при входе по SSH под именем пользователя nsg, например:

ssh nsg@1.2.3.4 "_p"
ssh nsg@1.2.3.4 ".ip.route.show"
ssh nsg@1.2.3.4 ".port.m1.restart"

-f, --force=секунды

"Заморозить" текущую сессию администратора и выполнить скрипт с правами администратора. При этом:

• Если в момент запуска скрипта не открыта интерактивная сессия с правами администратора, то скрипт выполняется как обычно.
• Если открыта интерактивная сессия с правами администратора, то она временно переходит в режим read-only. Затем выполняется скрипт в контексте последней сохраненной конфигурации. (То есть изменения, которые администратор успел сделать, но ещё не сохранил — для скрипта не видны. В том числе, изменения применённые, но не сохранённые — также игнорируются.)
• По завершении скрипта основная сессия восстанавливает права read-write и продолжает работать в своем обычном режиме. Все изменения, сделанные администратором до прерывания работы скриптом, сохраняются в его сессии и могут быть применены и сохранены обычным образом.
• Если во время работы скрипта администратор попытается выполнить привилегированную команду (требующую прав read-write), то он получит сообщение "Сессия приостановлена". Это означает, что команда не выполнена и надо повторить через некоторое время. Непривилегированные команды выполняются в обычном режиме.
• Если в момент работы скрипта будет запущен другой скрипт с опцией --force, то он не прервёт текущий скрипт, а встанет в очередь и начнет выполняться только после завершения текущего.

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

-r, --readonly

Запуск в режиме read-only. Настоятельно рекомендуется использовать во всех скриптах, где это возможно — чтобы не создавать конфликта с сессией администратора, которая может существовать в этот момент. В частности, все команды restart для портов, туннелей и т.п. доступны в режиме read-only, поскольку не затрагивают конфигурацию устройства.

-i

После исполнения команд, указанных в строке запуска, остаться в интерактивном режиме.

-q

"Молчаливый" режим исполнения скрипта. Выводятся только ответы на команды; сами команды не выводятся.

-t, --timeout=секунды

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

--sid=SID

Открыть для исполнения скрипта существующую сессию с идентификатором SID. При ручном управлении и в пользовательских скриптах не используется.

-h, --help

Вывод справки.

Помимо команд, выводимых подсказкой Enter в каждом узле, nsgsh имеет также три специальные команды. Они недоступны для работы в интерактивном режиме и работают только при пакетном запуске nsgsh из-под bash. (Что, в свою очередь, доступно вручную только для пользователя root.) Команды информационные и не требуют для nsgsh прав администратора. Они могут быть полезны в скриптах:

.system.get-iface-name=имя_порта

Вывод информации об имени IP-интерфейса, соответствующего указанному порту. Как правило, эти имена совпадают, но в некоторых важных случаях (PPP, WLAN) имена назначаются системой динамически и априори неизвестны, например:

ip route add default dev $(nsgsh -q .system.get-iface-name=m1)

.port.имя.get-port-parms

Только для портов, представляющих собой символьное устройство: вывод информации о физическом интерфейсе данного порта. Выводит тип интерфейса, системное имя (в терминах Linux) основного устройства для передачи данных, вспомогательного устройства для управления, режим обработчиков SMS и т.п., в зависимости от типа порта.

.system.getTty=имя_порта

Аналогично .port.имя.get-port-parms, но выводит только системное имя порта в формате текстовой строки, а не таблицы Lua.

При запуске nsgsh из-под bash следует обратить внимание на следующие особенности:

Спецсимволы. К перечню спецсимволов nsgsh, которые требуют указания особым образом, добавляются спецсимволы bash ($ > < | & ` и т.п.) — в путях, параметрах и значениях. Символ / в данном случае специальным не является.

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

nsgsh .port.eth0.link.adm.down .port.eth0._apply .po.eth1.li.ad.u .port.eth1._a

Применение изменений. Изменения параметров автоматически не применяются ни в пакетном режиме, ни в интерактивном. Чтобы они вступили в силу, необходимо завершить командную строку командой _apply в нужном узле, например:

nsgsh .port.3g.main.attempts.1 .port.3g.aux.attempts.0 .port.3g._apply

Разовые команды исполняются немедленно и не требуют завершающего _apply.

ВНИМАНИЕ! При написании скриптов необходимо учитывать алгоритмы работы bash и двойной разбор esc-последовательностей: сначала в bash, потом в nsgsh. Пример:

# nsgsh .port.eth0.vlan.eth0\.101._print

Последовательность \. преобразуется bash в точку, и в nsgsh передаётся

# nsgsh .port.eth0.vlan.eth0.101._print

Далее каждый узел в указанном пути разрешается в полное имя:

 port → port
 eth0 → eth0
 vlan → vlan
 eth0 → eth0.101 (если он единственный)

узел 101 оказывается лишним, и в результате выдаётся ошибка. Правильная нотация:

# nsgsh .port.eth0.vlan.eth0\\\.101._print

Другой пример:

nsgsh .port.eth0.vlan.eth0\\\.101\(_apply _print\)

В этом случае nsgsh получит .port.eth0.vlan.eth0\\\.101\(_apply и _print\) как два последовательных операнда (и оба некорректные, с непарными скобками). Правильная нотация — необходимо закрыть пробел между ними:

nsgsh .port.eth0.vlan.eth0\\\.101\(_apply\ _print\)

Обязательные и необязательные значения для команд. Если разовая команда требует подтверждения, то при исполнении её в пакетном режиме необходимо ввести это подтверждение в конце операнда, например:

nsgsh .system.reboot.yes

Это же относится и к некоторым другим случаям, когда команда может требовать какого-либо ввода — например, для рестарта сотового интерфейса:

nsgsh .port.m1.restart.main

В данном случае ввод параметра предусмотрен, но для интерактивного режима он не является обязательным. Рестарт порта 3G можно выполнить с явным выбором той либо другой SIM-карты, либо с текущей в зависимости от настроек самого порта. При вызове таких команд в пакетном режиме необходимо всегда указывать параметр явным образом: либо одно из возможных значений (main или aux), либо ключевое слово nil для того, чтобы выполнить команду с пустым значением параметра.

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

Обойти это ограничение, будучи твёрдо уверенным в своих действиях, можно путём принудительного вызова nsgsh в интерактивном режиме, например:

nsgsh -i system.configurations.etc-store=file:///tmp/backup.tgz _quit

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