.. _gs3_ssh: SSH =============== Введение ----------- :term:`Сервер приложений` Global ERP включает в себя SSH (Secure Shell) сервер, к которому возможно подключиться любым SSH-терминалом. С помощью команд командной строки возможно: - Управлять клиентскими сессиями - Обновлять и перезагружать код прикладных приложений - Перезапускать Web-приложения - Выполнять SQL и Jexl-скрипты .. _configuration: Конфигурирование ------------------- Конфигурационный файл :ref:`global3.config.xml` может содержать секцию ````: .. code-block:: xml .. seealso:: :xsd:class:`Configuration.Ssh` Учётные данные пользователей, имеющих права на ssh-соединения, указываются в секции конфигурационного файл global3.config.xml: .. code-block:: xml .. seealso:: :xsd:class:`Configuration.Security`, :xsd:class:`Configuration.Users.User` Шифрование пароля `````````````````````` Для шифрования пароля необходимо запустить Global 3 Server c парамерами. .. code-block:: bat start.bat -encryptPassword password -masterPassword masterpassword Где: - ``encryptPassword`` - пароль который необходимо зашифровать. - ``masterPassword`` - ключ шифрования. Результатом выполнения будет вывод в консоль строки, полученной в результате шифрования пароля переданного параметром ``-encryptPassword``. Криптографический ключ SSH-сервера `````````````````````````````````````` Приватный ключ SSH-сервера используется для удостоверения подлинности узла при установке защищённого SSL-соединения. Дистрибутив сервера приложений содержит в себе ключ SSH-сервера по умолчанию, что бы он не менялся при каждом перезапуске сервера. .. versionchanged:: 1.22.0-rc16 Добавлена возможность замены ключа. Для изменения ключа SSH-сервера, разместите/замените файл ``./ssh/ssh_host_key`` в каталоге с конфигурационными файлами сервера. .. code-block:: {G3_HOME} └── application └── config └── ssh └── ssh_host_key .. tip:: Для создания или конвертации ключей можно воспользоваться графической утилитой ``C:\Program Files\PuTTY\puttygen.exe`` ``ssh_host_key`` - файл содержит приватный RSA-ключ в формате PEM. .. code-block:: -----BEGIN RSA PRIVATE KEY----- AAGHJJKKKLLJGKLYGKJHGLKJGHLKJHLKJHLKJHKJH... -----END RSA PRIVATE KEY----- или .. code-block:: -----BEGIN OPENSSH PRIVATE KEY----- c2gtcnNhAAAAAwEAAQAAAQEAgZFF5/IE3G6Ccw5jd... -----END OPENSSH PRIVATE KEY----- Криптографические ключи SSH-пользователей ````````````````````````````````````````` Для аутентификации пользователя, при подключении к SSH-серверу, вместо пароля может быть использован публичный криптографический ключ. Публичный ключ пользователя должен быть добавлен в файл ``authorized_keys``, соответсвующий пользователю, в каталоге с конфигурационными файлами сервера приложений. .. versionchanged:: 1.22.0-rc16 Добавлена возможность замены ключа для пользователя `admin` и добавление ключей других пользователей. Структура хранения публичных ключей пользователей для аутентификации в ssh. .. code-block:: {G3_HOME} └── application └── config └── users ├── admin | └── .ssh | └── authorized_keys └── user └── .ssh └── authorized_keys .. note:: Криптографический ключ пользователя является дополнительной информацией к учётной записи пользователя, определенной в :ref:`конфигурации ` сервера приложений. Подключение ------------ Подключиться к SSH-серверу возможно любым SSH-терминалом. Putty `````` `PuTTY `_. .. seealso:: `Документация PuTTY `_ Основные параметры .................... Для подключения необходимо указать: - **Host Name:** ``host`` или ``user@host`` - **Port:** ``22`` или пользовательский - **Connection type:** ``SSH`` Что бы не вводить значения полей при повторном запуске PuTTY, можно сохранить параметры подключения по умолчанию, нажав кнопку «Save». Пример запуска из командной строки: .. code-block:: bat "C:\Program Files\PuTTY\putty.exe" -ssh localhost -P 22 -l admin -pw admin Сохранение логов .................... Для сохранения всего текстового вывода в файл, на вкладке ``Logging`` диалога подключения необходимо указать: - **Session Logging:** All session output - **Log file name::** полный путь к файлу .. warning:: | В путях символ ``\`` необходимо экранировать удвоением. Пример: ``C:\\directory\\log.txt``. | Символ `/` экранировать не требуется. Пример: ``C:/directory/log.txt``. Подключение с использованием RSA ключа ............................................ При подключении к SSH из \*.bat иил \*.sh можно воспользоваться RSA-ключом вместо пароля. .. code-block:: bat "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`` Windows 10 Shell `````````````````` .. code-block:: bat ssh admin@localhost -p 22 .. _ssh_commands: Команды ------------ - 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-файлы в текущем каталоге дистрибутива и каталоге {release_path}. - copy applib {release_path} Копирует jar-файлы из каталога {release_path} в текущий каталог . - copy applib force {release_path} [DEPRECTED] Копирует jar-файлы из каталога {release_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] Перезагружает образ решения по умолчанию или образ с указанным именем ''. - reload sbt safe [sbt] [DEPRECATED: Use `reload sbt [name]`] Перезагружает образ решения по умолчанию или образ с указанным именем. - reload solution Перезагружает образ решения по умолчанию или с указанным именем. Опции: --name Имя решения ''. --path Путь к каталогу с дистрибутивом '' или '' в зависимости от ''. Имеет значение если аргумент `--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 Ожидает разблокировки каталога с дистрибутивом решения (````). Используется для проверки, что сервер приложений сейчас не копирует из этого каталога. Поместите файл ``solution.lock`` в каталог перед выполнением этой команды. Не забудьте удалить ``solution.lock`` в конце работы с каталогом. Сервер не начнёт копирование, пока существует файл ``solution.lock``. Опции: .. option:: --name Имя решения '' .. option:: --path Путь к каталогу с дистрибутивом '' или '' в зависимости от ''. Имеет значение если аргумент `--name` не указан. .. option:: --timeout-mills Таймаут ожидания, в миллисекундах. .. option:: --format | Формат ответа. | По умолчанию: TEXT | Возможные значения: [TEXT, JSON] Выполнение командного файла ssh ````````````````````````````````` Для выполнения командного файла из командной строки можно выполнить: .. code-block:: "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-серверу. Пути к файлам в скрипте, являются локальными для сервера. .. code-block:: :caption: 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 Выполнение SQL ---------------- Для выполнения sql-скрипта: 1. Подключитесь к сессии командами ``login``, ``attach`` или ``set sid``. #. Перейдите в режим ввода скрипта командой ``sql``. #. Введите текст скрипта. #. | Выполните скрипт. | Для этого введите символ ``/`` с новой строки. #. | Выйдите из режима ввода скрипта. | Для этого введите символ ``/`` с новой строки. Пример: .. code-block:: sql login admin/admin@postgres sql INSERT INTO gs3_roottest ( id, idClass ) VALUES ( (select nextval('GS3_ROOTTEST_SEQ')) , 12351 ) ON CONFLICT DO NOTHING; / / Выполнение SQL скрипта из файла ``````````````````````````````````` Для выполнения sql-скрипта из файла: - Подключитесь к сессии. - | Выполните команду ``sql {file}``. | Где {file} – путь к файлу к файлу **на сервере**. .. attention:: Файл должен находится на локальном диске сервера. Пример: .. code-block:: login admin/admin@postgres sql D:\\globalerp\\scripts\\my_sql_script.sql Содержимое файла. .. code-block:: sql :caption: 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; / / Jexl скрипты ---------------- Для выполнения Jexl-скрипта необходимо: 1. Подключитесь к сессии командой ``login``, ``attach`` или ``set sid``. #. Переключитесь в режим ввода скрипта командой ''jexl''. #. Введите текст скрипта. #. | Выполните скрипт | Для этого введите символ ''/'' с новой строки. #. | Выйдите из режима ввода | Для этого введите символ ''/'' с новой строки. Пример: .. code-block:: login admin/admin@postgres jexl var name = Btk_ClassApi.getCanonicalClassName("Btk_Object"); Btk_ClassApi.getApiByCanonicalClassName(name); / / Выполнение Jexl скрипта из файла `````````````````````````````````` Для выполнения sql-скрипта из файла: - Подключитесь к сессии. - | Выполните команду ``jexl {file}``. | Где {file} – путь к файлу к файлу **на сервере**. .. attention:: Файл должен находится на локальном диске сервера. Пример: .. code-block:: login admin/admin@postgres jexl D:\\globalerp\\scripts\\my_jexl_script.sql Содержимое файла. .. code-block:: :caption: my_jexl_script.sql var name = Btk_ClassApi.getCanonicalClassName("Btk_Object"); Btk_ClassApi.getApiByCanonicalClassName(name); / / Контексты выполнения Jexl скрипта ``````````````````````````````````` Возможны следующие контексты выполнения Jexl-скрипта: - jexl - Пользовательская сессия - jexldb - База данных - jexlsys - Сервер приложений Пользовательская сессия ............................. В данном контексте доступны все Api-классы, присутствующие в :term:`решении `, соответствующем пользовательской сессии. .. code-block:: login user/password@alias jexl {текст скрипта} / / База данных ....................... В данном контексте доступны методы управления экземпляром базы данных: - initschema() Выполняет инициализацию/обновление схемы БД в соответствии с текущей прикладной кодовой базой решения. .. code-block:: attach db {alias} jexl {текст скрипта} / / Сервер приложений .............................. В данном контексте доступны методы управления решениями. Данный контекст является административным и предназначен для управления сервером приложений. Доступны следующие методы: - upgrade({release_path}) | Выполняет обновление кодовой базы решения и схемы БД в соответствии с новой прикладной кодовой базой. | Где: | {release_path} – путь к каталогу или zip-архиву, на жёстком диске сервера, с релизом прикладных модулей. .. code-block:: attach db {alias} as sys jexl {текст скрипта} / / Логирование --------------- При выполнении скрипта, по умолчанию, в ssh-консоль выводится результат выполнения команды или сообщение об ошибке со стеком вызова. Для вывода в ssh-консоль дополнительных логов, необходимо их включить. В консоль можно вывести логи следующих типов. Типы логов `````````````` - oper Логи из классов с namespace ru.bitec.engine.model.operation. - sql Логи sql-вызовов с уровня jdbc-соединения с базой. - script Логи из скриптового языка в режиме совместимости с Global 1. При работе со Scala не имеют смысла. - app | Логи из классов прикладной логики с namespace ru.bitec.app.*. | Пример отправки сообщения: .. code-block:: Logger.Factory.get(Xxx_XxxApi.class).info("Текст сообщения") - el Логи из инфраструктуры EclipseLink. В основном, это sql-вызовы, в более компактном виде, чем логи jdbc. - all Все выше перечисленные типы логов. Для переключения уровней логирования используются команды: - log-off - log-error - log-warn - log-info - log-debug - log-trace Команды указаны в порядке уменьшения уровня логов. В результате выполнения этой команды: .. code-block:: log-info app el В ssh-лог будут попадать сообщения типов ``app`` и ``el`` для уровней логирования: ``error``, ``warn``, ``info``. Для отключения вывода сообщений в ssh-лог необходимо вызвать команду: .. code-block:: log-off all Перенаправление ssh-лога Putty в файл ````````````````````````````````````````` При выполнении скриптов из командной строки, часто необходимо перенаправить вывод в файл. Для ssh-консоли Putty, это выполняется передачей параметра ``-sessionlog {имя_файла.txt}`` FAQ ----- Зависает ssh-терминал на этапе подключения к серверу. При запуске Putty из скрипта при первом подключении к серверу выдается сообщение PuTTY Security Alert, что может приводить к зависанию скрипта. Необходимо дополнительно передать подтверждение при запуске: .. code-block:: echo yes | %plink% -ssh localhost -P 2222 -l admin -i ssh_admin_private.ppk .. note:: Plink входит в состав дистрибутива PuTTY.