OneAgent настройка через интерфейс командной строки

Используйте интерфейс командной строки oneagentctl для выполнения некоторых настроек ЕдиногоАгента после установки на уровне отдельного хоста.

Расположение

Расположение инструмента зависит от того, настроили ли вы установку ЕдиногоАгента с помощью параметра <INSTALL_PATH>:

Linux или AIX:

<INSTALL_PATH>/agent/tools

Вам нужны root-права.

Развертывание на основе Docker

<INSTALL_PATH>/agent/tools

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

Windows:

<INSTALL_PATH>\agent\tools

Вам нужны права администратора. Если вы попытаетесь запустить oneagentctl в консоли Windows без прав администратора, Windows отобразит всплывающее окно контроля учетных записей и завершится ошибкой.

Типы параметров

Команда oneagentctl принимает параметр get для проверки состояния или значения параметра и параметр set для изменения параметра. Обратите внимание, что вы можете использовать несколько заданных параметров в одной команде.

Перезапуск OneAgent

При использовании set параметров необходимо перезапустить службу ЕдиногоАгента, чтобы изменения вступили в силу. Вы можете использовать параметр --restart-service с командой, которая автоматически запускает перезагрузку. В некоторых случаях вам также потребуется перезапустить отслеживаемые приложения. Вы также можете использовать параметр перезапуска сам по себе, без других параметров. См. пример команды ниже.

Linux или AIX:

./oneagentctl --set-proxy=my-proxy.com --restart-service

Windows:

.\oneagentctl.exe --set-proxy=my-proxy.com --restart-service

Показать справку

Используйте параметр --help для отображения всех поддерживаемых параметров.

Linux или AIX:

./oneagentctl --help

Windows:

.\oneagentctl.exe --help

Показать версию ЕдиногоАгента

Используйте параметр --version для отображения версии ЕдиногоАгента.

Linux или AIX:

./oneagentctl --version

Windows:

.\oneagentctl.exe --version

Связь с ЕдинымАгентом

Изменить настройки связи с ЕдинымАгентом

ЕдиныйАгент версии 1.185

• Используйте параметр --set-server, чтобы задать конечную точку связи ЕдиногоАгента. Используйте IP-адрес или имя. В зависимости от вашего развертывания это может быть сервер Ключ-Астром, управляемый кластер Ключ-Астром или АктивныйШлюз.
• Используйте параметр --set-tenant, чтобы задать идентификатор среды. По умолчанию для него уже установлено правильное значение. Если вы продаете услуги на основе Ключ-Астром, используйте этот параметр, чтобы установить идентификаторы ваших клиентов из пула идентификаторов, приобретенных вами у Ключ-Астром. Всегда используйте в сочетании с параметром --set-tenant-token, который определяет токен клиента для внутренней проверки подлинности.
• Используйте параметр --set-tenant-token, чтобы установить токен клиента, который используется для аутентификации связи с определенной конечной точкой. Всегда используйте в сочетании с --set-tenant
• Используйте параметр --set-proxy для установки прокси-сервера.

Выполните следующую команду, чтобы настроить параметры подключения ЕдиногоАгента:

Linux или AIX:

./oneagentctl --set-server=https://my-server.com:443 --set-tenant=abc123456 --set-tenant-token=abcdefg123456790 --set-proxy=my-proxy.com

Windows:

.\oneagentctl.exe --set-server=https://my-server.com:443 --set-tenant=abc123456 --set-tenant-token=abcdefg123456790 --set-proxy=my-proxy.com

Эти параметры требуют перезапуска ЕдиногоАгента, а также перезапуска всех приложений, отслеживаемых модулями глубокого кода. Добавьте --restart-service в команду для автоматического перезапуска ЕдиногоАгента(версия 1.189+) или для остановки и запуска процесса ЕдиногоАгента вручную. Инструкции для конкретных ОС см. в Linux, Windows или AIX.

Эта команда немедленно изменит конечную точку подключения модуля ОС, но модули кода не смогут прочитать новую настройку до следующего перезапуска.

ЕдиныйАгент и Ключ-Астром Кластер автоматически поддерживают рабочее соединение. Если детали конечной точки изменяются, кластер уведомляет ЕдиныйАгент об изменении, и ЕдиныйАгент автоматически обновляет конечную точку, которую вы установили с помощью --set-server, до нового рабочего значения.

Показать текущие конечные точки связи

ЕдиныйАгент версии 1.185

Используйте параметр --get-server, чтобы отобразить конечные точки, на которые ЕдиныйАгент должен отправлять данные. Это может быть сервер Ключ-Астром, управляемый кластер Ключ-Астром или АктивныйШлюз.

Linux или AIX:

./oneagentctl --get-server

Windows:

.\oneagentctl.exe --get-сервер

Начиная с ЕдиногоАгента версии 1.207, конечные точки представляются в формате, в котором конечные точки с одинаковым приоритетом группируются с помощью фигурных скобок ({...}) и сортируются в соответствии с приоритетом подключения. Звездочка (*) указывает конечную точку, на которую ЕдиныйАгент в данный момент отправляет данные. Конечные точки разделяются точкой с запятой (;). Например:

{https://endpoint1.com/communication;https:/10.0.0.0/communication;*https://endpoint3.com/communication}{https://endpoint4.com:443/communication}

Показать идентификатор среды

Идентификатор среды Ключ-Астром, который вы получили по электронной почте с активацией.

Используйте параметр --get-tenant для отображения идентификатора среды:

Linux или AIX:

./oneagentctl --get-tenant

Windows:

.\oneagentctl.exe --get-tenant

Показать токен арендатора

Используйте параметр --get-tenant-token для отображения текущего определенного токена:

Linux или AIX:

./oneagentctl --get-tenant-token

Windows:

.\oneagentctl.exe --get-tenant-token

Показать текущий прокси

ЕдиныйАгент версии 1.185

Используйте параметр --get-proxy, чтобы отобразить текущий определенный прокси, через который ЕдиныйАгент подключается:

Linux или AIX:

./oneagentctl --get-proxy

Windows:

.\oneagentctl.exe --get-proxy

Очистить конфигурацию прокси

Используйте для параметра --set-proxy пустое значение, чтобы очистить конфигурацию прокси:

Linux или AIX:

./oneagentctl --set-proxy=

Windows:

.\oneagentctl.exe --set-proxy= Перезапустите службу ЕдиногоАгента, чтобы изменения вступили в силу.

Проверить текущий диапазон портов

ЕдиныйАгент состоит из различных процессов, которые обмениваются данными через TCP-порт со сторожевым таймером. При запуске, сторожевой таймер ЕдиногоАгента пытается открыть первый доступный порт между портами 50000 и 50100. В некоторых случаях вам может понадобиться этот порт для ваших собственных приложений, которые запускаются после ЕдиногоАгента.

Используйте параметр --get-watchdog-portrange, чтобы проверить текущий диапазон портов, определенный для сторожевого таймера.

Linux или AIX:

./oneagentctl --get-watchdog-portrange

Windows:

.\oneagentctl.exe --get-watchdog-portrange

Установить новый диапазон портов

Используйте параметр --set-watchdog-portrange=arg, чтобы изменить диапазон портов прослушивания сторожевого таймера на <arg>. <arg> должен содержать два номера порта, разделенных двоеточием (:). Например 50000:50100. Максимальный поддерживаемый диапазон портов — от 1024 до 65535. Диапазон портов должен охватывать не менее 4 портов. Номер порта, начиная с диапазона, должен быть меньше.

Linux или AIX:

./oneagentctl --set-watchdog-portrange=50000:50100

Windows:

.\oneagentctl.exe --set-watchdog-portrange=50000:50100

Автоматические обновления

ЕдиныйАгент версии 1.213

Дополнительные сведения см. в разделах по обновлению ЕдиногоАгента для Linux, Windows и AIX.

Проверьте, включено ли автоматическое обновление

Используйте параметр get-auto-update-enabled, чтобы проверить, включено ли автоматическое обновление ЕдиногоАгента:

Linux или AIX:

./oneagentctl --get-auto-update-enabled

Windows:

.\oneagentctl.exe --get-auto-update-enabled

Включить или отключить автообновление

Установите для параметра --set-auto-update-enabled значение true или false, чтобы отключить или включить автоматическое обновление ЕдиногоАгента :

Linux или AIX:

./oneagentctl --set-auto-update-enabled=true

Windows:

.\oneagentctl.exe --set-auto-update-enabled=true

Предупреждение: после того, как вы используете эту команду для отключения автообновлений, вы не сможете управлять автоматическими обновлениями ЕдиногоАгента с помощью веб-интерфейса Ключ-Астром в меню Настройки > Предпочтения > Обновления ЕдиногоАгента.

Мониторинг логов

Дополнительные сведения см. в разделе Мониторинг логов. Примечание. Мониторинг логов не поддерживается в AIX.

Проверьте, включен ли Мониторинг логов

Используйте параметр --get-app-log-content-access, чтобы проверить, включен ли мониторинг журналов:

Linux:

./oneagentctl --get-app-log-content-access

Windows:

.\oneagentctl.exe --get-app-log-content-access

Включить или отключить мониторинг журналов

Установите для параметра --set-app-log-content-access значение true или false, чтобы отключить или включить Мониторинг логов:

Linux:

./oneagentctl --set-app-log-content-access=true

Windows:

.\oneagentctl.exe --set-app-log-content-access=true Перезапустите службу ЕдиногоАгента, чтобы применить изменения.

Создать архив поддержки

ЕдиныйАгент версии 1.225+

Если у вас нет доступа к веб-интерфейсу Ключ-Астром или вы хотите создать скрипт для сбора диагностических данных, вы можете использовать команду oneagentctl для сбора подмножества полных диагностических данных ЕдиногоАгента прямо на хосте, где установлен ЕдиныйАгент. С помощью диагностических данных, собранных для ЕдиногоАгента, вы можете:

• легко собирать диагностические данные для конкретного хоста
• напрямую предоставить службе поддержки Ключ-Астром детали, необходимые для диагностики проблемы

Команда требует, чтобы служба ЕдиногоАгента была запущена.

Чтобы создать архив поддержки с диагностическими данными, запустите oneagentctl с параметром --create-support-archive. По умолчанию архив поддержки содержит данные за 7-дневный период времени и создается в текущем рабочем каталоге. При желании вы можете установить собственный каталог и временной интервал с параметрами каталога и дней. Примечание: onegentctl не создает каталог; вы должны указать его на существующий каталог с относительным или абсолютным путем. Например:

Linux или AIX:

./oneagentctl --create-support-archive directory=/data/support-archive days=30

Windows:

.\oneagentctl.exe --create-support-archive directory=C:\data\support-archive days=30

Команда сохраняет архив как файл support_archive_agent_YYYY-MM-DD_hhmmss.zip. Например:

Creating support archive from last 30 days in C:\data\support-archive
Waiting 30s for archive request to be processed
Processing archive, waiting up to 15m 0s
Archive saved as C:\data\support-archive\support_archive_agent_2021-09-07_121619.zip

Содержание диагностических данных

Все собранные диагностические данные сжимаются в архив support_archive_agent_YYYY-MM-DD_hhmmss.zip, который включает следующее подмножество полных диагностических данных ЕдиногоАгента:

Папка или файл	Описание
support_archive (ZIP)	Содержит локальную конфигурацию агента ЕдиногоАгента, установленного на узле или в процессе, в котором выполнялась процедура устранения неполадок, а также файлы журналов, связанные с ЕдинымАгентом.
diagnostic_files (ZIP)	Содержит информацию об обнаружении группы процессов, проблемах автоматического внедрения и конфигурации расширения ЕдиногоАгента.

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

ЕдиныйАгент загружает определенные системные журналы, чтобы Ключ-Астром мог диагностировать проблемы, которые могут быть вызваны условиями в вашей среде. Журналы также сохраняются в архиве поддержки. Чаще всего такие проблемы связаны с глубоким мониторингом или установками автоматического обновления.

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

Используйте параметр --get-system-logs-access-enabled, чтобы проверить, включен ли доступ к системным журналам:

Linux или AIX:

./oneagentctl --get-system-logs-access-enabled

Windows:

.\oneagentctl.exe --get-system-logs-access-enabled

Включить или отключить доступ к системным журналам

Установите для параметра --set-system-logs-access-enabled значение true или false, чтобы отключить или включить доступ к системным журналам:

Linux или AIX:

./oneagentctl --set-system-logs-access-enabled=true

Windows:

.\oneagentctl.exe --set-system-logs-access-enabled=true Перезапустите службу ЕдиногоАгента, чтобы изменения вступили в силу.

Обратите внимание, что параметры --set-system-logs-access-enabled и --get-system-logs-access-enabled относятся к настройке самодиагностики и не связаны с мониторингом журналов.

Примечание:
Отключение доступа к системному журналу ограничивает наши возможности по упреждающей диагностике и устранению проблем. Если доступ к системным журналам закрыт, вам может потребоваться вручную предоставить Ключ-Астром содержимое ваших системных журналов, чтобы мы могли диагностировать проблемы в вашей среде.

Идентификатор хоста

Ключ-Астром присваивает уникальный идентификатор каждому отслеживаемому узлу в вашей среде. Идентификаторы хостов можно использовать в качестве параметров в запросах Ключ-Астром API, например, Topology и Smartscape API — Hosts API. Идентификатор хоста также представляет собой URL-адрес страницы обзора хоста, например, https://environment.org/#newhosts/hostdetails;id=HOST-6E56EE455C84E232.

Показать свой идентификатор хоста

ЕдиныйАгент версии 1.197

Чтобы найти идентификатор хоста, используйте параметр --get-host-id. Например:

Linux или AIX:

./oneagentctl --get-host-id

Windows:

.\oneagentctl.exe --get-host-id

Определите источник идентификатора хоста

Доступно на всех поддерживаемых платформах для ЕдиногоАгента версии 1.223+. Для ЕдиногоАгента версии 1.221 и более ранних эта функция поддерживается только для Citrix Virtual Apps and Desktops.

Особенно важно сохранять статический идентификатор хоста в динамических виртуальных средах, где хосты воссоздаются ежедневно.

Чтобы определить источник для генерации идентификатора хоста, используйте --set-host-id-source и установите для него одно из предопределенных значений:

• auto — разрешить Ключ-Астром автоматически генерировать идентификатор хоста.
• ip-addresses — Сгенерируйте идентификатор хоста на основе IP-адреса хоста
• mac-addresses — Сгенерируйте идентификатор хоста на основе MAC-адреса сетевого адаптера хоста.
• fqdn — создание идентификатора узла на основе полного доменного имени узла (FQDN) в формате host.domain. Если полное доменное имя не содержит символа точки, вместо него используется MAC-адрес сетевой карты.
• Если вы отслеживаете несколько сред, вы можете разделить узлы с одинаковыми IP-адресами, MAC-адресами или полными доменными именами, используя разные пространства имен для каждой среды. Пространство имен может содержать только буквенно-цифровые символы, дефисы, символы подчеркивания и точки; максимальная длина составляет 256 символов.
  • ip-адреса;namespace=<пространство имен>
  • mac-адреса; namespace=<пространство имен>
  • fqdn;namespace=<пространство имен>

Например, чтобы установить в качестве источника идентификатора хоста ip-адреса и назначить его пространству имен с именем test, запустите oneagentctl со следующим параметром:

Linux или AIX:

./oneagentctl --set-host-id-source="ip-addresses;namespace=test"

Windows:

.\oneagentctl.exe --set-host-id-source="ip-addresses;namespace=test"

После изменения источника идентификатора хоста необходимо перезапустить все отслеживаемые приложения, а затем перезапустить службу ЕдиногоАгента, чтобы создать новый объект хоста в вашей среде. Вы можете использовать параметр --restart-service с oneagentctl для автоматического перезапуска ЕдиногоАгента или остановки и запуска процесса ЕдиногоАгента вручную. Инструкции для конкретных ОС см. в Linux, Windows или AIX.

Чтобы проверить источник идентификатора хоста, используйте параметр --get-host-id-source:

Linux или AIX:

./oneagentctl --get-host-id-source

Windows:

.\oneagentctl.exe --get-host-id-source

Для источника идентификатора хоста, заданного для ip-адресов и пространства имен test, команда вернет следующий результат:

ip-addresses;namespace=test

Группы хостов

Обзор того, как использовать группы узлов, см. в разделе Организация среды с помощью групп узлов.

Изменить назначение группы хостов

Используйте параметр --set-host-group, чтобы изменить назначение группы хостов.

Чтобы назначить хост MyHostGroup:

Linux или AIX:

./oneagentctl --set-host-group=MyHostGroup

Windows:

.\oneagentctl.exe --set-host-group=MyHostGroup

Требования к строке группы хостов:

• Может содержать только буквенно-цифровые символы, дефисы, символы подчеркивания и точки.
• Не должен начинаться с dt.
• Максимальная длина – 100 символов.

Использование --set-host-group требует перезапуска ЕдиногоАгента, а также перезапуска всех отслеживаемых служб. Добавьте --restart-service в команду для автоматического перезапуска ЕдиногоАгента(версия 1.189+) или для остановки и запуска процесса ЕдиногоАгента вручную. Инструкции для конкретных ОС см. в Linux, Windows или AIX.

Очистить назначение группы хостов

Используйте параметр --set-host-group с пустым значением, чтобы очистить назначение группы хостов:

Linux или AIX:

./oneagentctl --set-host-group=

Windows:

.\oneagentctl.exe --set-host-group=

Показать назначение группы хостов

Используйте параметр --get-host-group для отображения текущего назначения группы хостов:

Linux или AIX:

./oneagentctl --get-host-group

Windows:

.\oneagentctl.exe --get-host-group

Теги хоста и метаданные

В динамических или больших средах ручная пометка узлов может оказаться нецелесообразной. Для динамических развертываний, включающих часто меняющиеся экземпляры и имена хостов (например, AWS или MS Azure), вы можете использовать выделенные параметры oneagentctl для применения пользовательских тегов, имен и метаданных к вашим хостам.

Перечисленные ниже методы oneagentctl позволяют редактировать только метаданные, добавленные с помощью самого oneagentctl или ранее с помощью файлов конфигурации. Теги и метаданные, добавленные с помощью веб-интерфейса Ключ-Астром, а также извлеченные из контролируемой среды (например, теги AWS), не редактируются с помощью oneagentctl и не будут отображаться с помощью параметров--get-host-tags и --get-host-properties.

Пользовательское имя хоста

Используйте инструмент командной строки oneagentctl с параметром --set-host-name, чтобы переопределить автоматически обнаруженное имя хоста. Имя хоста не должно содержать символы <, >, &, CR (возврат каретки) или LF (перевод строки). Максимальная длина 256 символов.

Важно: Эта команда добавляет пользовательское имя хоста для отображения в пользовательском интерфейсе, но обнаруженное имя хоста не изменяется. Дополнительные сведения см. в разделе Установка пользовательских имен хостов.

Чтобы изменить имя хоста:

Linux или AIX: ./oneagentctl --set-host-name=myhostname

Windows: .\oneagentctl.exe --set-host-name=myhostname

Чтобы вернуться к автоматически определенному имени хоста, установите для параметра --set-host-name пустое значение, как в --set-host-name="". Например:

Linux или AIX: ./oneagentctl --set-host-name=""

Windows: .\oneagentctl.exe --set-host-name=""

Изменение может не отображаться в веб-интерфейсе Ключ-Астром до 6 минут.

Использование --set-host-name требует перезапуска ЕдиногоАгента. Добавьте --restart-service в команду для автоматического перезапуска ЕдиногоАгента (версия 1.189+) или для остановки и запуска процесса OneAgent вручную. Инструкции для конкретных ОС см. в Linux, Windows или AIX.

Чтобы показать имя хоста:

Linux или AIX:

./oneagentctl --get-host-name

Windows:

.\oneagentctl.exe --get-host-name

Пользовательские метаданные хоста

После настройки настраиваемые метаданные отображаются в виде набора свойств в нижней части раздела «Свойства и теги» на странице обзора хоста. Значения свойств не должны содержать символ = (если только он не используется в качестве разделителя значения ключа) или пробельные символы. Максимальная длина — 256 символов, включая разделитель «ключ-значение». Имя ключа не должно начинаться с символа #.

Для версий до 1.189 используйте файл конфигурации метаданных хоста.

Чтобы добавить или изменить свойства хоста, выполните следующую команду:

Linux или AIX:

./oneagentctl --set-host-property=AppName --set-host-property=Environment=Dev

Windows:

.\oneagentctl.exe --set-host-property=AppName --set-host-property Environment=Dev

Вы можете добавить или изменить более одного свойства в одной команде.

Чтобы удалить свойства хоста, выполните следующую команду:

Linux или AIX:

./oneagentctl --remove-host-property=AppName --remove-host-property=Environment=Dev

Windows:

.\oneagentctl.exe --remove-host-property=AppName --remove-host-property=Environment=Dev

Вы можете удалить более одного свойства с помощью одной команды. Если ключ свойства, переданный в команду, не существует, будет возвращен ненулевой код выхода, но все существующие свойства, переданные в команде, будут удалены. После удаления свойств хоста они остаются видимыми в веб-интерфейсе Ключ-Астром до 7 часов.

Чтобы отобразить все свойства, настроенные для хоста, выполните следующую команду:

Linux или AIX:

./oneagentctl --get-host-properties

Windows:

.\oneagentctl.exe --get-host-properties

Пользовательские теги хоста

После настройки пользовательских тегов хоста они отображаются в верхней части раздела «Свойства и теги» на странице обзора хоста. Значение свойства не должно содержать = (если только оно не используется в качестве разделителя значений ключа) или пробельные символы. Максимальная длина — 256 символов, включая разделитель «ключ-значение». Имя ключа не должно начинаться с #.

Чтобы добавить или изменить теги хоста, выполните следующую команду:

Linux или AIX:

./oneagentctl --set-host-tag=TestHost --set-host-tag=role=fallback --set-host-tag=Gdansk

Windows:

.\oneagentctl.exe --set-host-tag=TestHost --set-host-tag=role=fallback --set-host-tag=Gdansk

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

Чтобы удалить теги, выполните следующую команду:

Linux или AIX:

./oneagentctl --remove-host-tag=role=fallback --remove-host-tag=Gdansk

Windows:

.\oneagentctl.exe --remove-host-tag=role=fallback --remove-host-tag=Gdansk

Вы можете удалить более одного тега с помощью одной и той же команды. Если тег, переданный в команде, не существует, возвращается ненулевой код выхода, но все существующие теги, переданные в команде, удаляются. После удаления теги остаются видимыми в веб-интерфейсе Ключ-Астромдо 6 часов.

Чтобы отобразить все теги, настроенные для хоста, выполните следующую команду:

Linux или AIX:

./oneagentctl --get-host-tags

Windows:

.\oneagentctl.exe --get-host-tags