Режим агента конфигуратора

Что еще за режим агента?

Данный режим был представлен год назад в зазеркалье: https://wonderland.v8.1c.ru/blog/rezhim-agenta-konfiguratora/

Если коротко, то данный режим позволяет запустить конфигуратор в фоне и посылать ему различные команды по протоколу SSH (в том числе по сети с другой машины). Команды в режиме агента в основном повторяют параметры командной строки запуска.

Где можно найти описание команд?

Параметры запуска конфигуратора в режиме агента описаны в приложении 7 к руководству администратора (ИТС: 7.3.4. Параметры работы в режиме агента).
Описание команд в режиме агента находится в приложении 4 к руководству администратора (ИТС: 4.6. Работа конфигуратора в режиме агента).

Как этим пользоваться?

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

В зазеркалье приводится пример на языке Python. Я пробовал подключаться на PowerShell и на Go. Со вторым возникли проблемы, о которых я кратко расскажу в конце.

Есть пример кода?

Конечно! Сейчас мы с вами рассмотрим по шагам сквозной пример на PowerShell, который выполняет следующие действия:

1. Запускает конфигуратор в режиме Агента;
2. Подключается к нему по протоколу SSH под конкретным пользователем;
3. Выполняет несколько команд;
4. Завершает SSH сессию и закрывает конфигуратор.

Допустим, у нас есть папка, в которой находятся обработки, выгруженные в формат XML. И мы хотим конвертировать их в файлы .epf.

Шаг #1 (запускаем консоль)

Открываем в проводнике подопытную папку. Будем считать для простоты что обработка у нас только одна и находится она в подпапке /src.

Добавим еще папку build, в которой скрипт будет формировать файл .epf, и папку temp, в которой нужно создать пустую базу с одной админской ролью и одним пользователем с логином admin без пароля.

Запускаем PowerShell:

Шаг #2 (устанавливаем модуль SSH)

примечание: команды вводите в консоли как есть и нажимаете Enter

Обязательно выполняем такую команду (иначе ничего не сработает): 

Function prompt {"1C: "}

Далее нужно установить модуль для работы с SSH (это нужно сделать только один раз для текущего пользователя Windows).
Для этого выполняем следующую команду:

Find-Module Posh-SSH | Install-Module -Scope CurrentUser

Если ошибок не возникло, то мы готовы к работе с конфигуратором. В противном случае гуглим решение тут: https://stackoverflow.com/

Шаг #3 (запускаем конфигуратор в режиме агента)

Создаем массив параметров запуска конфигуратора в режиме агента следующей командой:

$ArgList = @('DESIGNER', '/F .	emp', '/AgentMode', '/AgentSSHHostKeyAuto', '/AgentBaseDir .', '/Visible')

Расшифровка параметров по порядку:

• DESIGNER — указывает, что нужно запустить конфигуратор;

• /F . emp — указывает каталог файловой базы (знаки ‘.‘ означают, что путь указан относительно текущей папки);

• /AgentMode — указывает, что конфигуратор должен быть запущен в режиме агента (ну вы и сами догадались);

• /AgentSSHHostKeyAuto — какая-то магия с ключами SSH. Просто надо в нашем случае (я не настоящий сварщик);

• /AgentBaseDir . — это специальная папка, относительно которой мы будем задавать пути в командах SSH;

• /Visible — делает конфигуратор видимым (скриншот будет ниже).

Теперь запускаем конфигуратор командой:

Start-Process 'C:Program Files (x86)1cv8common1cestart.exe' -ArgumentList $ArgList

Должно появиться такое окошко:

Шаг #4 (подключаемся по SSH)

Указываем параметры подключения (логин пользователя ИБ):

$UserName = 'admin'
$EmptyPassword = New-object System.Security.SecureString
$Credential = New-Object System.Management.Automation.PSCredential($UserName, $EmptyPassword)

Эти строки не совсем типовые для PowerShell. Правильнее было бы воспользоваться такой командой:

$Credential = Get-Credential -UserName "admin" -Message "Введите пароль:"

Но она всегда выводит окно ввода пароля, а у нас он пустой в этом демонстрационном примере. 

Подключаемся!

$1c = New-SSHSession 127.0.0.1 -Port 1543 -Credential $Credential

Подключились к локальной машине на порт 1543 (это дефолтный порт для агента конфигуратора).

Шаг #5 (получаем поток для команд)

Получаем поток, в который будем писать команды:

$ssh = $1c | New-SSHShellStream

Ожидаем данные (в данном случае приглашение):

while (-not $ssh.DataAvailable) { Start-Sleep -m 100 }

Читаем пришедшие данные:

$ssh.Read()

Видим на экране такое приглашение:

Теперь можно посылать конфигуратору команды!

Шаг #6 (подготовительные команды)

Сначала установим параметры ответа:

$ssh.WriteLine('options set --output-format=json --show-prompt=no')

Эта команда говорит конфигуратору, что мы хотим получать ответ в формате JSON, и не хотим получать в ответе приглашение ‘designer>’.
Ведь скорее всего мы поручим в итоге разбирать ответ машине, да?

Внимание! Не забываем ждать ответ как в шаге #5 перед тем как прочитать его. В интерактивной сессии это конечно не обязательно, но внутри скрипта все будет происходить слишком быстро и попытка прочитать ответ сразу скорее всего не прокатит.

Ответ вы получите такой:

Перед выполнением остальных (делающих полезную работу) команд обязательно нужно послать команду подключения к ИБ

$ssh.WriteLine('common connect-ib')

Шаг #7 (команда конвертации обработки из XML в EPF)

При написании команды нужно учитывать, что все пути указываются относительно папки, которую мы указали в ключе AgentBaseDir при запуске конфигуратора в режиме агента + подпапка с именем пользователя под которым мы подключаемся (ее создаст конфигуратор). При этом абсолютные пути не работают!

Мы в AgentBaseDir указали текущую папку. Из этого следует, что нам нужно в относительных путях подняться на один уровень. (см. две точки в начале путей):

$ssh.WriteLine('config load-ext-files --file="..srcTest.xml" --ext-file="..uildTest.epf"')

В ответ вы получите следующее:

Шаг #8 (завершаем работу)

Отключаемся от ИБ. Закрываем конфигуратор. Удаляем сессию SSH. Гасим свет.

$ssh.WriteLine('common disconnect-ib')
$ssh.WriteLine('common shutdown')
$1c | Remove-SSHSession | Out-Null

Чтобы вернуть нормальное приглашение PowerShell введите:

Function prompt {"PS $PWD> "}

А что там с Go?

В Go библиотека для работы с SSH устроена таким образом, что за один сеанс можно выполнить только одну команду. Но конфигуратор позволяет создать только один сеанс SSH (официальное ограничение) и при этом не дает разорвать существующий сеанс (что-то не то возвращает на уровне протокола). В итоге стиль библиотеки Go неосуществим на практике. В принципе можно как и на PowerShell получить поток, и слать команды в него, но я не нашел корректного способа узнать пришел ответ или нет. В итоге нормально работать на Go не получилось. Как обстоят дела в Python не проверял.

PS> Пример "боевого" скрипта с логированием и индикацией выполнения приложен к публикации

Про SFTP (дополнение от 13.12.17)

Помимо выполнения команд по протоколу SSH есть возможность обмениваться с агентом файлами по протоколу SFTP. При подключении вам будет доступно содержимое папки, которая была указана в параметре /AgentBaseDir при запуске конфигуратора в режиме агента.

Это довольно полезная возможность, так как у вас может быть полностью закрыт доступ к удаленной машине (кроме порта агента). А с помощью SFTP вы сможете закачать файлы, необходимые для выполнения конкретной команды, и обратно можно забрать результат работы команды (такое тоже вероятно потребуется).

Пример в три строчки (если агент запущен на локальной машине):

$sftp = New-SFTPSession 127.0.0.1 -Port 1543 -Credential $Credential
New-SFTPItem -Session $sftp -Path '/data' -ItemType Directory
Set-SFTPFile -SFTPSession $sftp -LocalFile ".1CV8.cf" -RemotePath "/data" -Overwrite

По порядку:

1. Подключились на локальную машину на порт 1543 (логин и пароль как для SSH)
2. Создали папку data внутри папки /<AgentBaseDir>/<имя пользователя>
3. Закачали файл 1CV8.cf из текущей папки в созданную на шаге 2 папку data

Обратите внимание, что пути на удаленной машине нужно указывать со знаком `/` как принято в среде unix.

Для обмена файлами еще можно воспользоваться SFTP-клиентом с графическим интерфейсом. Рекомендую WinSCP