Web Agents 2023.11.2

agentadmin command

The agentadmin command manages Web Agent installation. It returns EXIT_SUCCESS (or 0) when it completes successfully, and EXIT_FAILURE (or a code greater than zero) when it fails.

The following options are supported:

--i

Install a new agent instance.

Usage: agentadmin --i

--s

Silently, non-interactively, install a new agent instance.

Usage: agentadmin --s web-server-config-file openam-url agent-url realm agent-profile-name agent-profile-password [--changeOwner] [--acceptLicense] [--forceInstall]

web-server-config-file

(Apache HTTP Server) The full path to the server configuration file. The installer modifies this file to include the agent configuration and module.

(Microsoft IIS) The ID number of the IIS site in which to install the web agent. To list the available sites in an IIS server and the relevant ID numbers, run agentadmin.exe --n.

am-url

The full URL of the AM instance that the agent will use. Ensure the deployment URI is specified.

Example: https://am.example.com:8443/am

If a reverse proxy is configured between AM and the agent, set the AM URL to the proxy URL, for example, https://proxy.example.com:443/am. For information about setting up an environment for reverse proxies, refer to Apache as a reverse proxy.
agent-url

The full URL of the server on which the agent is running.

Example: http://www.example.com:80

realm

The AM realm containing the agent profile.

agent-profile-name

The name of the agent profile in AM.

agent-profile-password

The full path to the agent profile password file.

--changeOwner

Apache web agent for Unix only: Change the ownership of created directories to the user and group as specified in the Apache configuration file.

To use this option, you must run the agentadmin command as the root user or with the sudo command. If you cannot run the agentadmin command as the root user or with the sudo command, you must change the ownership manually.

--acceptLicense

Do not display the license during installation.

--forceInstall

If the agent cannot connect to the specified AM server during installation, proceed with a silent installation instead of exiting.

--n

(IIS web agent only) List the sites available in an IIS server.

Example:

c:\web_agents\iis_agent\bin> agentadmin.exe --nIIS Server Site configuration:
     ====================================
     id       details
     ====================================

     Default Web Site
     application path:/, pool DefaultAppPool
     1.1.1    virtualDirectory path:/, configuration: C:\inetpub\wwwroot\web.config

     MySite
     application path:/, pool: MySite
     2.1.1    virtualDirectory path:/, configuration C:\inetpub\MySite\web.config
     application path:/MyApp1, pool: MySite

--l

List existing configured agent instances.

Usage: agentadmin --l

Example:

$ ./agentadmin --l
AM Web Agent configuration instances:

      id:            agent_1
      configuration: /opt/web_agents/apache24_agent/bin/../instances/agent_1
      server/site:   /etc/httpd/conf/httpd.conf

      id:            agent_2
      configuration: /opt/web_agents/apache24_agent/bin/../instances/agent_2
      server/site:   /etc/httpd/conf/httpd.conf

      id:            agent_3
      configuration: /opt/web_agents/apache24_agent/bin/../instances/agent_3
      server/site:   /etc/httpd/conf/httpd.conf

--g

(IIS web agent only) Remove all web agent instances and libraries from an IIS installation.

Usage: agentadmin.exe --g

For more information, refer to To remove Web Agents from IIS.

--e

(IIS web agent only) Enable an existing agent instance.

Usage: agentadmin.exe --e agent-instance

For more information, refer to To disable and enable Web Agents.

--d

(IIS web agent only) Disable an existing agent instance.

Usage: agentadmin.exe --d agent-instance

For more information, refer to To disable and enable Web Agents.

--o

(IIS web agent only) Modify Access Control Lists (ACLs) for files and folders related to a web agent instance.

Usage: agentadmin.exe --o "identity_or_siteID" "directory" [--siteId]

Usage: agentadmin.exe --o "directory" --addAll --removeAll

"identity_or_siteID"

Specify the identity to be added to the directory’s ACLs. When used with the --siteId option, this option specifies an IIS site ID.

"directory"

Specify the directory that would be modified.

[--siteId]

Specify that the agentadmin should use identity_or_siteID as an IIS site ID.

--addAll

Add all IIS application pool identities to the directory’s ACLs. This option is not compatible with the --removeAll option.

--removeAll

Remove all IIS application pool identities from the directory’s ACLs. This option is not compatible with the --addAll option.

Example:

C:\web_agents\iis_agent\bin> agentadmin.exe --o "IIS_user1" "C:\web_agents\iis_agent\lib"
C:\web_agents\iis_agent\bin> agentadmin.exe --o "2" "C:\web_agents\iis_agent\lib" --siteId
C:\web_agents\iis_agent\bin> agentadmin.exe --o  "C:\web_agents\iis_agent\lib" --addAll

--r

Remove an existing agent instance.

Usage: agentadmin --r agent-instance

agent-instance

The ID of the agent configuration instance to remove.

Respond yes when prompted to confirm removal.

On IIS web agents, the --r option does not remove the web agent libraries since they can be in use by other web agent instances configured on the same site. To remove all web agent instances and libraries, use the --g option instead.

--k

Generate a new signing key.

Usage: agentadmin --k

Example:

  • Unix

  • Windows

$ cd /web_agents/apache24_agent/bin/
$ ./agentadmin --k
Encryption key value: YWM…​5Nw==
C:\> cd web_agents{apache_agent_version}\bin
C:\web_agents{apache_agent_version}\bin> agentadmin --k
Encryption key value: YWM…​5Nw==

--p

Use a generated encryption key to encrypt a new password.

Usage: agentadmin --p encryption-key password

encryption-key

An encryption key, generated by the agentadmin --k command.

password

The password to encrypt.

Examples:

  • Unix

  • Windows

$ ./agentadmin --p "YWM0OThlMTQtMzMxOS05Nw==" "cat newpassword.file"
Encrypted password value: 07b…​dO4=
C:\path\to\web_agents{apache_agent_version}\bin> agentadmin.exe --p "YWM0OThlMTQtMzMxOS05Nw==" "newpassword"
Encrypted password value: 07b…​dO4=

--V[i]

Validate the installation. Use this command in conjunction with sustaining to troubleshoot installations.

This command validates the following points:

  • The agent can reach the AM server(s) configured in AM Connection URL.

  • Critical bootstrap properties are set. For more information, see Configuration location.

  • TLS/SSL libraries are available and that SSL configuration properties are set, if the agent is configured for SSL communication.

  • The agent can log in to AM to fetch the agent profile.

  • The system has enough RAM and shared memory.

  • The agent can log in to AM with the provided user and password credentials.

  • The agent can decrypt the agent profile password using the encryption key in the agent.conf file.

  • WebSocket connections are available between the agent and AM.

  • The core init and shutdown agent sequences are working as expected. This validation requires the --Vi flag.

  • (IIS agent only) IIS is configured for running application pools in Integrated mode.

  • To prevent service outage or an unresponsive agent, run the command only when the agent instance is not actively protecting a website.

  • On Unix, run the command as the same user or group that runs the web server. For example, to use the Apache HTTP Server daemon user:

    $ sudo -u daemon ./bin/agentadmin --V agent_1

    Running the command as a different user can cause the log/system_0.log and log/monitor_0.pipe files to be created with permissions that prevent the agent from writing to them, causing an error such as:

    …​ GMT ERROR   [0x7f0c9cf05700:22420]: unable to open event channel

  • Make sure the user running the command has execute permission on the following directories:

    • /web_agents/apache24_agent/instances/agent_nnn

    • /web_agents/apache24_agent/log

Usage:

agentadmin --V[i] agent_instance [user name] [password file] [realm]

[i]

(Optional) Ensure that the core init and shutdown agent sequences are working as expected.

agent_instance

(Required) The agent instance where to run the validation tests. For example, agent_1.

user name

(Optional) A user ID that exists in the AM server. Required only for the validate_session_profile test. For example, demo.

password file

(Optional) A file containing the password of the user ID used for the validate_session_profile test. For example, /secure-directory/passwd.txt

realm

(Optional) The realm of the user ID used for the validate_session_profile test. For example, /customers.

Example:

$ ./agentadmin --Vi agent_1 demo passwd.txt /
Saving output to /web_agents/apache24_agent/bin/../log/validate_xxx.log

Running configuration validation for agent_1:

Agent instance is configured with 1 naming.url value(s):
1. https://am.example.com:8443/am is valid
selected https://am.example.com:8443/am as naming.url value
validate_bootstrap_configuration: ok
validate_ssl_libraries: ok
validate_agent_login: ok
get_allocator_blockspace_sz(): trying for configured cache size 16777216 bytes
validate_system_resources: ok
validate_session_profile: ok
validate_websocket_connection: ok
validate_worker_init_shutdown: ok

Result: 7 out of 7 tests passed, 0 skipped.

--v

Display information about agentadmin build and version numbers, and available system resources.

Example:

AM Web Agent for IIS Server
     Version: 2023.11
     Revision: xxx
     Build machine: xxx
     Build date: xxx

     System Resources:
     total memory size: 7.7GB
     pre-allocated session/policy cache size: 1.0GB
     log buffer size: 128.5MB
     min audit log buffer size: 2MB, max 2.0GB
     total disk size: 162.4GB
     free disk space size: 89.6GB

     System contains sufficient resources (with remote audit log feature enabled).