On this page:

Your Rating:
Results:
PatheticBadOKGoodOutstanding!
14 rates
You can perform administrative tasks and configuration changes for a Universal Agent using the Universal Agent command line interface (CLI), as described in this topic.

Running the Universal Agent CLI Tool

You can start the Universal Agent, or administer and configure a running Universal Agent, from the command line by invoking the /opt/appdynamics/universal-agent/ua program. 

Configuration changes you make with the Universal Agent command line tool do not impact the content of the Controller rulebook. All rulebook changes affect only the local copy of the rulebook, local.json. Command line arguments that cause rulebook changes also direct the background Universal Agent daemon task to switch to Local mode, so that it operates from the local.json rulebook rather than the Controller rulebook.

CLI Tool Command Syntax

The following listing shows the CLI tool syntax: 

/opt/appdynamics/universal-agent/ua [ --daemon] [ --start-rule <rule_names> ]  [ --stop-rule <rule_names> ] [ --display-mode ] [ --set-mode [local | controller ] [ --modify-config <rule.attribute=value> ] [ --show-java-arguments <process_ids> ] [ --check-config ] [ --show-daemon-status ] [ --setup-win-service [ --data-dir <data-directory-path>] ] [ --restart-service ] [ --start-service ] [ --enable-auto-java ] [ --disable-auto-java ] [ --uninstall ] 

You can pass more than one argument to the command. For example:  

/opt/appdynamics/universal-agent/ua --start-rule rule1 rule2  --stop-rule rule3  --display-mode

Command Line Arguments

Quotes are necessary if the rule name contains spaces, otherwise quotes are optional.  This is true for all commands that reference rule names.

--daemon

Starts the Universal Agent as a daemon process. It is mutually exclusive with all other command line arguments.

--start-rule <rule_names>

Changes the state of one or more rules in the rulebook to a value of started. The rules to be modified are identified by their rule names. The use of the --start-rule argument switches the operation mode of the Universal Agent to Local. You can change the state of multiple rules within a single invocation. For example,  /opt/appdynamics/universal-agent/ua --start-rule rule1 rule2 changes the state of both rule1 and rule2 to started.

The meaning of this state change varies from one monitoring agent to another. 

  • Machine Agent and Network Agent: A state value of started causes the Universal Agent background task to start the specified agent.
  • Java Agent: A value of started activates the Java Agent within a matching JVM when that JVM starts. If the JVM has already started, it needs to be restarted for the Java Agent start to take effect.
  • .NET Agent: Changing the state of the rule to started rules causes the specified rule to become `started` and installs and starts the .NET agent on the machine. 
  • Analytics Agent
    • For Linux platforms, the Analytics Agent runs as a Machine Agent extension. A value of started causes the Machine Agent to be configured to start the analytics extension the next time it is started.
    • For Windows platforms, the Analytics Agent runs in a standalone JVM.  A value of started causes this JVM to be started if it is not already running.

--stop-rule <rule_names>

Changes the state of one or more rules in the rulebook to a value of installed. The rules to be modified are identified by their rule names. Using the --stop-rule argument switches the operation mode of the Universal Agent to Local. You can change the state of multiple rules within a single invocation. For example, /opt/appdynamics/universal-agent/ua --stop-rule rule1 rule2  changes the state of both rule1 and rule2 to installed.

 

The meaning of this state change varies from one monitoring agent to another.
  • Machine Agent and Network Agent: A state value of installed causes the Universal Agent background task to stop the specified agent if it is running.
  • Java Agent: The Universal Agent cannot stop a Java Agent because it runs as part of an application JVM. A state value of installed prevents the auto-java feature (if enabled) from activating the Java Agent within a matching application JVM.
  • .NET Agent: Changing the state of the rule to installed stops the .NET agent and uninstalls it.
  • Analytics Agent:
    • For Linux platforms, the Analytics Agent runs as a Machine Agent extension. A value of installed causes the Machine Agent to be configured to not start the analytics extension the next time it is started.
    • For Windows platforms, Analytics Agent runs in a standalone JVM.  A value of installed causes this JVM to be stopped, if it is currently running.

--display-mode

Displays the operation mode of the background Universal Agent daemon.  It does not change anything.

--set-mode [ local | controller ]

Changes the operation mode of the background Universal Agent daemon to the specified mode.

If local is specified, and the daemon is currently in controller mode, then the current controller rulebook (as saved in the controller-book.json file) is renamed local.json.

If controller is specified, and the daemon is currently in local mode, then the local.json file is renamed local.json.backup (if possible).

--modify-config <rule_name>  <attribute_name>=<new_value>

Changes an arbitrary attribute within the current rulebook to a new value. The use of the --modify-config argument switches the operation mode of the Universal Agent to Local.

You can specify the attribute in two ways:

  • <rule_name>  <attribute_name>=<new_value>  this form changes a non-config attribute within the rule.  <rule_name> identifies the name of the rule to be changed; <attribute_name> identifies the specific attribute; and <new_value> specifies the new value to be assigned to the attribute.  
    For example:  /opt/appdynamics/universal-agent/ua --modify-config rule1 condition=False changes the condition attribute of rule1 to a value of False.
  • <rule_name>  config.<attribute_name>=<new_value>  this form changes a config attribute within the rule. A config attribute is a monitor-specific attribute that is defined within the "config" attribute set for the rule.  <rule_name> identifies the name of the rule to be changed; <attribute_name> identifies the specific config attribute; and <new_value> specifies the new value to be assigned to the attribute. For example:    /opt/appdynamics/universal-agent/ua --modify-config rule1 config.state=started has the effect of changing the state config attribute of rule1 to a value of started.

--show-java-arguments [ <process_ids> | all ]

Displays the changes that need to be made to a Java command line to correctly deploy the Java app agent. This command is helpful if you need to manually configure one or more Java startup scripts.

One or more arguments can be provided for this option. If a single all argument is provided, then this command displays the command line arguments that need to be defined for each JVM in the system that matches at least one of the Java rules. Otherwise, the arguments following ua --show-java-arguments should be the process ids for the processes that should be tested. If a process id represents a Java process, then the process is tested against the current Java monitoring rules. If the process matches at least one rule, the command line arguments that should be added to the process startup script are displayed.

Example:    

Example of --show-java-arguments
ua --show-java-arguments 123
 
Java arguments for pid 123
    -javaagent:/opt/appdynamics/universal-agent/monitor/java/javaagent.jar
    -Dappdynamics.agent.applicationName=MyApp,-Dappdynamics.agent.tierName=MyTier,-Dappdynamics.agent.reuse.nodeName=true,-Dappdynamics.ua.appagent.version=4.3.0.0 

--check-config

Enables the Universal Agent to validity check the conf/universalagent.yaml configuration file for syntax errors. Reports if there are errors in the file that would cause the ua daemon process to fail initialization. The Universal Agent install script uses this argument to ensure a valid configuration file prior to installing the Universal Agent as a system service.

--show-daemon-status

Reports the status of the ua daemon process by scanning the processes running in the current OS and reporting the process ids of all the processes that are running the Universal Agent as a daemon. Run this command as the root user or by using sudo.

 Linux only: When the Universal Agent daemon runs as a system service, it is normal for two process ids to be reported

--setup-win-service

Configures the Universal Agent as a service in the Windows environment. This command starts the Windows service (if it is not already running), and configures the registry so that the service starts automatically when the system is rebooted.
The --data-dir command line option can be specified with --setup-win-service. The <data-directory-path> argument specifies the path name of the directory where the Universal Agent's data directories reside. These directories include log, conf, download, and rulebook. If the --data-dir option is not specified, then these directories must be located in the main installation directory of the Universal Agent.

--restart-service

Stops and starts the Windows Universal Agent service.

--start-service

Starts the Windows Universal Agent service, unless it is already started.

--enable-auto-java

Usage: Windows only.

Enables the "auto-java" feature. The auto-java feature enables automatic start of the Java app agent for all new JVMs. It directs the Universal Agent to inspect the command line arguments of each new process and add the "-javaagent:..." argument to all new Java processes. This option only modifies the command lines for processes that are recognized as JVMs. This option does not directly impact the background Universal Agent daemon.

This is an optional facility that is disabled by default. For Windows systems, this interface can potentially be used to deploy viruses or other types of potentially dangerous software. The intent of the feature is to ease the deployment of the AppDynamics Java agent when it is installed by the Universal Agent, by eliminating the requirement for users to modify Java startup scripts. The code has been thoroughly tested and peer-reviewed, as is the case of all of our product code.

This feature is not supported on Windows 2008 SP2 32-bit and 64-bit.

--disable-auto-java

Disables the auto-java feature that was previously enabled with the  --enable-auto-java argument. This command line option does not directly impact the background Universal Agent daemon.

--enable-ldpreload

Usage: Linux only. Exactly like --enable-auto-java, but on Linux.

--disable-ldpreload

Usage: Linux only. Exactly like --disable-auto-java. Disables the auto-java feature that was previously enabled with the  --enable-ldpreload argument. This command line option does not directly impact the background Universal Agent daemon.

--uninstall

Uninstalls the Universal Agent. The Universal Agent Daemon process is stopped and, if the Universal Agent is defined as a service, the service definition is deleted. On Windows, the Universal Agent definition is removed from the registry. Requires reboot of the machine.

  • No labels