--- title: agentadmin command description: The agentadmin command manages Web Agents installation. It returns EXIT_SUCCESS (or 0) when it completes successfully, and EXIT_FAILURE (or a code greater than zero) when it fails. component: web-agents version: 2023.11 page_id: web-agents:installation-guide:agentadmin canonical_url: https://docs.pingidentity.com/web-agents/2026/installation-guide/agentadmin.html llms_txt: https://docs.pingidentity.com/web-agents/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md superseded_by: https://docs.pingidentity.com/web-agents/2026/installation-guide/agentadmin.html section_ids: i: "--i" agentadmin-s: "--s" n: "--n" l: "--l" g: "--g" e: "--e" d: "--d" o: "--o" r: "--r" k: "--k" p: "--p" vi: "--V[i]" v: "--v" --- # agentadmin command The `agentadmin` command manages Web Agents 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](configure-apache.html#configure-apache-server). | * 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](uninstallation.html#proc-uninstall-iis-web-policy-agent). ## `--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](install-iis.html#proc-enable-disable-iis-web-policy-agent). ## `--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](install-iis.html#proc-enable-disable-iis-web-policy-agent). ## `--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](../properties-reference/com.sun.identity.agents.config.naming.url.html). * Critical bootstrap properties are set. For more information, see [Configuration location](../user-guide/about.html#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). ```