5.6. SSH#

5.6.1. Введение#

Сервер приложений Global ERP включает в себя SSH (Secure Shell) сервер, к которому возможно подключиться любым SSH-терминалом.

С помощью команд командной строки возможно:

  • Управлять клиентскими сессиями

  • Обновлять и перезагружать код прикладных приложений

  • Перезапускать Web-приложения

  • Выполнять SQL и Jexl-скрипты

5.6.2. Конфигурирование#

Конфигурационный файл global3.config.xml может содержать секцию <ssh/>:

<ssh defaultDb="PostgreSql" port="22"/>

See also

Configuration.Ssh

Учётные данные пользователей, имеющих права на ssh-соединения, указываются в секции <security/> конфигурационного файл global3.config.xml:

<security>
  <users>
    <user name="admin" password="admin" roles="ssh"/>
  </users>
</security>

See also

Configuration.Security, Configuration.Users.User

5.6.2.1. Шифрование пароля#

Для шифрования пароля необходимо запустить Global 3 Server c парамерами.

start.bat -encryptPassword password -masterPassword masterpassword

Где:

  • encryptPassword - пароль который необходимо зашифровать.

  • masterPassword - ключ шифрования.

Результатом выполнения будет вывод в консоль строки, полученной в результате шифрования пароля переданного параметром -encryptPassword.

5.6.2.2. Криптографический ключ SSH-сервера#

Приватный ключ SSH-сервера используется для удостоверения подлинности узла при установке защищённого SSL-соединения. Дистрибутив сервера приложений содержит в себе ключ SSH-сервера по умолчанию, что бы он не менялся при каждом перезапуске сервера.

Changed in version 1.22.0-rc16: Добавлена возможность замены ключа.

Для изменения ключа SSH-сервера, разместите/замените файл ./ssh/ssh_host_key в каталоге с конфигурационными файлами сервера.

{G3_HOME}
└── application
  └── config
    └── ssh
       └── ssh_host_key

Tip

Для создания или конвертации ключей можно воспользоваться графической утилитой C:\Program Files\PuTTY\puttygen.exe

ssh_host_key - файл содержит приватный RSA-ключ в формате PEM.

-----BEGIN RSA PRIVATE KEY-----
AAGHJJKKKLLJGKLYGKJHGLKJGHLKJHLKJHLKJHKJH...
-----END RSA PRIVATE KEY-----

или

-----BEGIN OPENSSH PRIVATE KEY-----
c2gtcnNhAAAAAwEAAQAAAQEAgZFF5/IE3G6Ccw5jd...
-----END OPENSSH PRIVATE KEY-----

5.6.2.3. Криптографические ключи SSH-пользователей#

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

Changed in version 1.22.0-rc16: Добавлена возможность замены ключа для пользователя admin и добавление ключей других пользователей.

Структура хранения публичных ключей пользователей для аутентификации в ssh.

{G3_HOME}
└── application
  └── config
    └── users
      ├── admin
      | └── .ssh
      |   └── authorized_keys
      └── user
        └── .ssh
          └── authorized_keys

Note

Криптографический ключ пользователя является дополнительной информацией к учётной записи пользователя, определенной в конфигурации сервера приложений.

5.6.3. Подключение#

Подключиться к SSH-серверу возможно любым SSH-терминалом.

5.6.3.1. Putty#

PuTTY.

See also

Документация PuTTY

5.6.3.1.1. Основные параметры#

Для подключения необходимо указать:

  • Host Name: host или user@host

  • Port: 22 или пользовательский

  • Connection type: SSH

Что бы не вводить значения полей при повторном запуске PuTTY, можно сохранить параметры подключения по умолчанию, нажав кнопку «Save».

Пример запуска из командной строки:

"C:\Program Files\PuTTY\putty.exe" -ssh localhost -P 22 -l admin -pw admin

5.6.3.1.2. Сохранение логов#

Для сохранения всего текстового вывода в файл, на вкладке Logging диалога подключения необходимо указать:

  • Session Logging: All session output

  • Log file name:: полный путь к файлу

    Warning

    В путях символ \ необходимо экранировать удвоением. Пример: C:\\directory\\log.txt.
    Символ / экранировать не требуется. Пример: C:/directory/log.txt.

5.6.3.1.3. Подключение с использованием RSA ключа#

При подключении к SSH из *.bat иил *.sh можно воспользоваться RSA-ключом вместо пароля.

"C:\Program Files\PuTTY\putty.exe" -ssh localhost -P 22 -l admin -i ssh_admin_private_key.ppk

Tip

Для создания или конвертации ключей можно воспользоваться графической утилитой C:\Program Files\PuTTY\puttygen.exe

5.6.3.2. Windows 10 Shell#

ssh admin@localhost -p 22

5.6.4. Команды#

  • add license

    Переключает терминал в режим ввода текста лицензии.

  • alter server mode normal

    Переключает сервер из сервисного режима в рабочий рабочий режим.

    Опции:
    --format
    Формат ответа.
    По умолчанию: TEXT
    Возможные значения: [TEXT, JSON]
  • alter server mode service

    Переводит сервер в режим обслуживания. Используется для обновления схемы. При переключении в этот режим все пользовательские сеансы, кроме SSH, завершаются. Служба isAlive возвращает ошибку 503.

    Опции:
    --format
    Формат ответа.
    По умолчанию: TEXT
    Возможные значения: [TEXT, JSON]
  • attach db {dbAlias} [as sys]

    Устанавливает соединение с базой данных решения по умолчанию или указанной {dbAlias}.

  • clear

    Очищает окно терминала.

  • clear persistence cache [{dbAlias}]

    Очищает JPA-кэши решения по умолчанию или для указанной {dbAlias}.

  • compare applib {release_path}

    Сравнивает jar-файлы в текущем каталоге дистрибутива <sbt jarFolder=”{distributive_path}”/> и каталоге {release_path}.

  • copy applib {release_path}

    Копирует jar-файлы из каталога {release_path} в текущий каталог <sbt jarFolder=”{distributive_path}”/>.

  • copy applib force {release_path}

    [DEPRECTED] Копирует jar-файлы из каталога {release_path} в текущий каталог <sbt jarFolder=”{distributive_path}”/> без проверки совпадения версий.

  • detach

    Закрывает соединение с базой данных, установленное командой attach.

  • dump all session threads

    Печатает трассировку стека всех потоков сеанса.

  • dump all threads

    Печатает трассировку стека всех потоков.

  • dump session thread {sid}

    Печатает трассировку стека потока рабочего сеанса {sid}.

  • echo {message}

    Печатает сообщение {message}.

  • execute {expression}

    Выполняет выражение Jexl.

  • exit

    Закрывает SSH сеанс и разрывает соединение.

  • help

    Печатает список доступных команд.

  • init schema

    Инициализирует схему базы данных. Перед этим требуется подключиться к базе командой ‘attach db as sys’.

  • init data

    Инициализирует данные по умолчанию. Перед этим требуется подключиться к базе командой ‘attach db as sys’.

  • jexl

    Переключает терминал в режим ввода JEXL скрипта.

  • kill sessions

    Закрывает рабочие сеансы.

    Опции:
    --all

    Все рабочие сеансы.

    --with-obsolete-solution

    Использующие устаревшие версии кода решения.

    --format
    Формат ответа.
    По умолчанию: TEXT
    Возможные значения: [TEXT, JSON]
  • kill session {sid}

    Закрывает рабочий сеанс и идентификатором {sid}.

  • kill classloader {mills} | [{sbtName} {mills}]

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

  • list license

    Печатает список лицензий.

  • list sessions

    Печатает список рабочих сеансов.

  • list sbt

    Печатает список образов решений.

  • list web

    Печатает список веб-приложений, содержащихся в образах решений.

  • list session

    [DEPRECATED] Печатает список рабочих сеансов.

  • list solutions

    Печатает список решений.

  • log-debug sql|app|el|oper|script|all

    Устанавливает уровень логирования DEBUG указанному источнику логов.

  • log-error sql|app|el|oper|script|all

    Устанавливает уровень логирования ERROR указанному источнику логов.

  • log-info sql|app|el|oper|script|all

    Устанавливает уровень логирования INFO указанному источнику логов.

  • log-off sql|app|el|oper|script|all

    Устанавливает уровень логирования OFF указанному источнику логов.

  • log-trace sql|app|el|oper|script|all

    Устанавливает уровень логирования TRACE указанному источнику логов.

  • log-warn sql|app|el|oper|script|all

    Устанавливает уровень логирования WARN указанному источнику логов.

  • logattach

    Подключает поток вывода консоли сервера в ssh-терминал.

  • login {user/password@dbAlias}|{}

    Запускает рабочий сеанс к указанному решению, для выполнения SQL и JEXL скриптов.

  • logout

    Закрывает сеанс пользователя запущенный командой login или отключает от подключенного командой attach сеанса.

  • notify sessions

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

    Опции:
    --all

    Всем сессиям.

    --with-obsolete-solution

    Использующим устаревшие версии кода решения.

    --message

    Текст сообщения.

    --format
    Формат ответа.
    По умолчанию: TEXT
    Возможные значения: [TEXT, JSON]
  • print license request

    Печатает запрос лицензии для базы данных решения.

  • print current license

    Печатает агрегированную информацию из всех установленных лицензиях.

  • refresh web {web}

    [DEPRECATED] Перезапускает веб-приложение с указанным именем.

  • reload sbt [sbt]

    Перезагружает образ решения по умолчанию или образ с указанным именем ‘<sbt name=”{sbt}”/>’.

  • reload sbt safe [sbt]

    [DEPRECATED: Use reload sbt [name]] Перезагружает образ решения по умолчанию или образ с указанным именем.

  • reload solution

    Перезагружает образ решения по умолчанию или с указанным именем.

    Опции:
    --name

    Имя решения ‘<database alias={name}/>’.

    --path

    Путь к каталогу с дистрибутивом ‘<sbt source={path}/>’ или ‘<sbt jarFolder={path}/>’ в зависимости от ‘<sbt mode=[DEV|JAR]/>’. Имеет значение если аргумент –name не указан.

    --format
    Формат ответа.
    По умолчанию: TEXT
    Возможные значения: [TEXT, JSON]
  • reload persistence [{dbAlias}]

    Перезагружает описания JPA сущностей.

  • remove license {ID}

    Удаляет лицензию с идентификатором {ID} из таблицы лицензий.

  • reset upgrade {idSession}

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

  • restart web {web}

    [DEPRECATED] Перезапускает веб-приложение с указанным именем.

  • run {file}

    Выполняет последовательность ssh-команд, содержащихся в указанном файле.

  • save sessions

    Сохраняет состояния всех рабочих сеансов с пользовательским интерфейсом в БД координатора кластера.

  • save session {sid}

    Сохраняет состояние рабочего сеанса с пользовательским интерфейсом в БД координатора кластера. {sid} - строка в формате “E-n”.

  • set web {web}

    [DEPRECATED] Set environment variable web.

  • set db {dbAlias}

    [DEPRECATED] Set environment variable defaultDb.

  • set sid {sid}

    [DEPRECATED] Set environment variable sid.

  • shutdown server

    Выключает сервер через {delay} секунд. Используется для мягкого выключения. Всем пользователям предлагается завершить свою работу в течение указанного интервала времени. Страница входа возвращает ошибку 404.

    Опции:
    --delay

    Задержка выключения сервера (в секундах).

    --format
    Формат ответа.
    По умолчанию: TEXT
    Возможные значения: [TEXT, JSON]
  • shutdown server immediate

    Выключает сервер немедленно.

    Опции:
    --format
    Формат ответа.
    По умолчанию: TEXT
    Возможные значения: [TEXT, JSON]
  • sql

    Переключает терминал в режим ввода SQL скрипта.

  • stack trace

    Печатает трассировку стека всех потоков сеанса.

  • start web {web}

    [DEPRECATED] Запускает веб-приложение с именем {web}.

  • stop web {web}

    [DEPRECATED] Останавливает веб-приложение с именем {web}.

  • update acobjects

    Инициализирует данные по умолчанию. Перед этим выполните команду attach db as sys.

  • upgrade

    Запускает обновление схемы. Перед этим выполните команду attach db as sys.

  • upgrade force

    Запускает обновление схемы. Все ошибки миграции будут игнорированы.

  • wait solution distributive unlock

    Ожидает разблокировки каталога с дистрибутивом решения (<sbt jarFolder={path}/>). Используется для проверки, что сервер приложений сейчас не копирует из этого каталога. Поместите файл solution.lock в каталог перед выполнением этой команды. Не забудьте удалить solution.lock в конце работы с каталогом. Сервер не начнёт копирование, пока существует файл ``solution.lock`. Опции:

    --name

    Имя решения ‘<database alias={name}/>’.

    --path

    Путь к каталогу с дистрибутивом ‘<sbt source={path}/>’ или ‘<sbt jarFolder={path}/>’ в зависимости от ‘<sbt mode=[DEV|JAR]/>’. Имеет значение если аргумент –name не указан.

    --timeout-mills

    Таймаут ожидания, в миллисекундах.

    --format
    Формат ответа.
    По умолчанию: TEXT
    Возможные значения: [TEXT, JSON]

5.6.4.1. Выполнение командного файла ssh#

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

"C:\Program Files\PuTTY\putty.exe" -ssh localhost -P 22 -l admin -pw admin -m shh_logger_test_script.txt

Attention

В данном примере файл shh_logger_test_script.txt размещён на диске клиентской машины, он считывается в момент подключения к SSH-серверу. Пути к файлам в скрипте, являются локальными для сервера.

shh_logger_test_script.txt#
login
log-info app el

execute Btk_ClassApi.getCanonicalClassName("Btk_Object")

jexl
var name = Btk_ClassApi.getCanonicalClassName("Btk_Object");
Btk_ClassApi.getApiByCanonicalClassName(name);
/
/

jexl D:/svn/depot/ASSource/sysapplication/ssh/src/test/java/ru/bitec/app/ssh/shh_jexl_exams.txt
jexl D:\\svn\\depot\\ASSource\\sysapplication\\ssh\\src\\test\\java\\ru\\bitec\\app\\ssh\\shh_jexl_exams.txt

sql
INSERT INTO gs3_roottest (id, idClass) VALUES ((select nextval('GS3_ROOTTEST_SEQ')), 12351) ON CONFLICT DO NOTHING;
/
/

sql D:\\svn\\depot\\ASSource\\sysapplication\\ssh\\src\\test\\java\\ru\\bitec\\app\\ssh\\shh_sql_exams.txt

log-off all
logout

5.6.5. Выполнение SQL#

Для выполнения sql-скрипта:

  1. Подключитесь к сессии командами login, attach или set sid.

  2. Перейдите в режим ввода скрипта командой sql.

  3. Введите текст скрипта.

  4. Выполните скрипт.
    Для этого введите символ / с новой строки.
  5. Выйдите из режима ввода скрипта.
    Для этого введите символ / с новой строки.

Пример:

login admin/admin@postgres
sql
INSERT INTO gs3_roottest (
    id,
    idClass
  ) VALUES (
  (select
    nextval('GS3_ROOTTEST_SEQ'))
    , 12351
  ) ON CONFLICT DO NOTHING;
/
/

5.6.5.1. Выполнение SQL скрипта из файла#

Для выполнения sql-скрипта из файла:

  • Подключитесь к сессии.

  • Выполните команду sql {file}.
    Где {file} – путь к файлу к файлу на сервере.

    Attention

    Файл должен находится на локальном диске сервера.

Пример:

login admin/admin@postgres
sql D:\\globalerp\\scripts\\my_sql_script.sql

Содержимое файла.

my_sql_script.sql#
INSERT INTO gs3_roottest (id, idClass) VALUES ((select nextval('GS3_ROOTTEST_SEQ')), 12351) ON CONFLICT DO NOTHING;
INSERT INTO gs3_roottest (id, idClass) VALUES ((select nextval('GS3_ROOTTEST_SEQ')), 12351) ON CONFLICT DO NOTHING;
/
INSERT INTO gs3_roottest (id, idClass) VALUES ((select nextval('GS3_ROOTTEST_SEQ')), 12351) ON CONFLICT DO NOTHING;
INSERT INTO gs3_roottest (id, idClass) VALUES ((select nextval('GS3_ROOTTEST_SEQ')), 12351) ON CONFLICT DO NOTHING;
/
/

5.6.6. Jexl скрипты#

Для выполнения Jexl-скрипта необходимо:

  1. Подключитесь к сессии командой login, attach или set sid.

  2. Переключитесь в режим ввода скрипта командой ‘’jexl’’.

  3. Введите текст скрипта.

  4. Выполните скрипт
    Для этого введите символ ‘’/’’ с новой строки.
  5. Выйдите из режима ввода
    Для этого введите символ ‘’/’’ с новой строки.

Пример:

login admin/admin@postgres
jexl
var name = Btk_ClassApi.getCanonicalClassName("Btk_Object");
Btk_ClassApi.getApiByCanonicalClassName(name);
/
/

5.6.6.1. Выполнение Jexl скрипта из файла#

Для выполнения sql-скрипта из файла:

  • Подключитесь к сессии.

  • Выполните команду jexl {file}.
    Где {file} – путь к файлу к файлу на сервере.

    Attention

    Файл должен находится на локальном диске сервера.

Пример:

login admin/admin@postgres
jexl D:\\globalerp\\scripts\\my_jexl_script.sql

Содержимое файла.

my_jexl_script.sql#
var name = Btk_ClassApi.getCanonicalClassName("Btk_Object");
Btk_ClassApi.getApiByCanonicalClassName(name);
/
/

5.6.6.2. Контексты выполнения Jexl скрипта#

Возможны следующие контексты выполнения Jexl-скрипта:

  • jexl - Пользовательская сессия

  • jexldb - База данных

  • jexlsys - Сервер приложений

5.6.6.2.1. Пользовательская сессия#

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

login user/password@alias
jexl
{текст скрипта}
/
/

5.6.6.2.2. База данных#

В данном контексте доступны методы управления экземпляром базы данных:

  • initschema()

    Выполняет инициализацию/обновление схемы БД в соответствии с текущей прикладной кодовой базой решения.

attach db {alias}
jexl
{текст скрипта}
/
/

5.6.6.2.3. Сервер приложений#

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

  • upgrade({release_path})
    Выполняет обновление кодовой базы решения и схемы БД в соответствии с новой прикладной кодовой базой.
    Где:
    {release_path} – путь к каталогу или zip-архиву, на жёстком диске сервера, с релизом прикладных модулей.
attach db {alias} as sys
jexl
{текст скрипта}
/
/

5.6.7. Логирование#

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

Для вывода в ssh-консоль дополнительных логов, необходимо их включить. В консоль можно вывести логи следующих типов.

5.6.7.1. Типы логов#

  • oper

    Логи из классов с namespace ru.bitec.engine.model.operation.

  • sql

    Логи sql-вызовов с уровня jdbc-соединения с базой.

  • script

    Логи из скриптового языка в режиме совместимости с Global 1. При работе со Scala не имеют смысла.

  • app
    Логи из классов прикладной логики с namespace ru.bitec.app.*.
    Пример отправки сообщения:
    Logger.Factory.get(Xxx_XxxApi.class).info("Текст сообщения")
  • el

    Логи из инфраструктуры EclipseLink. В основном, это sql-вызовы, в более компактном виде, чем логи jdbc.

  • all

    Все выше перечисленные типы логов.

Для переключения уровней логирования используются команды:

  • log-off

  • log-error

  • log-warn

  • log-info

  • log-debug

  • log-trace

Команды указаны в порядке уменьшения уровня логов.

В результате выполнения этой команды:

log-info app el

В ssh-лог будут попадать сообщения типов app и el для уровней логирования: error, warn, info.

Для отключения вывода сообщений в ssh-лог необходимо вызвать команду:

log-off all

5.6.7.2. Перенаправление ssh-лога Putty в файл#

При выполнении скриптов из командной строки, часто необходимо перенаправить вывод в файл. Для ssh-консоли Putty, это выполняется передачей параметра -sessionlog {имя_файла.txt}

5.6.8. FAQ#

Зависает ssh-терминал на этапе подключения к серверу.

При запуске Putty из скрипта при первом подключении к серверу выдается сообщение PuTTY Security Alert, что может приводить к зависанию скрипта.

Необходимо дополнительно передать подтверждение при запуске:

echo yes | %plink% -ssh localhost -P 2222 -l admin -i ssh_admin_private.ppk

Note

Plink входит в состав дистрибутива PuTTY.