Contact Us 1-800-596-4880
  1. Homepage
  2. Runtime Manager
  3. Runtime Manager Agent

  4. Install or Update the Runtime Manager Agent

Install or Update the Runtime Manager Agent

logo hybrid active Hybrid logo server active Private Cloud Edition

Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

The Anypoint Runtime Manager agent registers Mule runtime engine (Mule) with Runtime Manager. After Mule is registered, you can manage it using Runtime Manager within the specific environment and Anypoint Platform business group in which Mule was registered. You cannot register Mule with multiple Runtime Manager business groups or environments.

Use the amc_setup command to install and configure the agent, using different parameters depending on the type of console to which you are connecting the agent:

When you run amc_setup, the agent creates the $MULE_HOME/conf/mule-agent.yml with the configuration options you specified.

After initial installation, you can:

  • Rerun amc_setup to change the agent configuration or to update the agent version.

  • Modify mule-agent.yml to change the agent configuration.

    Some configuration options, such as extending JMX monitoring to other external services, are not possible using amc_setup. You must manually add them to mule-agent.yml. See Update Agent Configuration in mule-agent.yml.

$MULE_HOME is environment variable that specifies the location where you installed Mule. These instructions use paths for Mac or Linux. If you are using Windows, replace the $MULE_HOME path with %MULE_HOME%.

Requirements and Restrictions

  • Do not register a single Mule runtime engine with more than one Runtime Manager business group or environment.

  • Do not register Mule with Runtime Manager more than once.

  • Do not register a Mule runtime engine with both an older Mule Management Console (MMC) and Runtime Manager.

    If Mule is currently managed in MMC, first unregister it with MMC before running amc_setup.

    MuleSoft support provides migration scripts to migrate from MMC to Runtime Manager.

Runtime Manager agent can’t run in a separate JVM.

Compatibility

The version of Runtime Manager agent must support the version of Mule and Runtime Manager you are using. To determine compatibility, check the Runtime Manager Agent Release Notes.

Mule 3.7.x and earlier and the API gateway 2.x and earlier include an earlier version of the Runtime Manager agent, which doesn’t provide support for exporting data to external analytics tools. If you are running these earlier versions, you can download and update the agent to the latest version.

Runtime Manager Agent Compatibility

Mule version Runtime Manager Agent version Java version

4.3.0

2.4.3 or later

8

4.4.0

2.4.27 or later

8

4.4.0

2.4.28 or later

8,11

4.5.0

2.5.6 or later

8,11

4.6.0

2.6.0 or later

8,11,17
Using a Runtime Manager Agent version earlier than the ones provided in the compatibility table can result in incompatibilities or introduce inconsistencies.

For more information on Java compatibility, see Java Support.

Prerequisites

  • Your enterprise license is current.

  • You are running Mule 3.6.0 and later, and the API gateway 2.1 and later.

  • If you must download the agent, you must have an Enterprise support account.

Install the Agent from a Mule Installation

The agent is bundled with the Mule runtime engine installation.

To install the agent:

  1. Download and install Mule.

  2. Run $MULE_HOME/bin/amc_setup and specify parameters for your installation.

    See amc_setup Parameters.

Install the Agent From a .zip File

If you need a different version of the agent than the version included in the software distribution, you can download it from the Support Portal.

Download the Agent from the Support Portal

To verify compatibility with your Mule runtime engine and Runtime Manager, check the corresponding Runtime Manager Agent Release Notes.

To download the agent:

  1. Open MuleSoft Help Center.

  2. Click the Support tile.

  3. Click Login in the upper right and log in using your Anypoint Platform credentials.

    You must have an Enterprise support account to download the agent.

  4. In the MuleSoft Support page, click the Downloads tab.

  5. Click Mule Agent.

  6. Locate the agent to install and click Download in the Action column.

Install the Agent

To install the agent from the downloaded .zip file:

  1. Stop Mule or the API gateway runtime.

  2. Extract the downloaded agent-setup-VERSION.zip file to $MULE_HOME/bin.

    If prompted, overwrite any conflicting files.

  3. Run $MULE_HOME/bin/amc_setup and specify parameters for your installation.

    See amc_setup Parameters.

  4. Restart Mule or the API gateway runtime.

Update the Agent

If you previously installed the agent with an earlier version of amc_setup, you can update the agent and retain your existing agent configuration in $MULE_HOME/conf/mule-agent.yml.

If you keep your mule-agent.yml file, ensure that these changes are applied:

To update an existing Runtime Manager agent:

  1. Stop Mule or the API gateway runtime.

  2. Extract the downloaded agent-setup-VERSION.zip file to $MULE_HOME/bin.

  3. When prompted, overwrite any conflicting files.

  4. Run $MULE_HOME/bin/amc_setup -U.

    When you run amc_setup with the -U parameter, you can’t include other parameters on the command line.

  5. Restart Mule or the API gateway runtime.

If you update the Runtime Manager agent, you must also run the Anypoint Monitoring agent uninstall script and then re-install the Anypoint Monitoring agent. See Update the Anypoint Monitoring Agent.

What Happens When You Update the Agent

When you update the agent, the amc_setup script:

  • Backs up the current version of the agent:

    • Archives the $MULE_HOME/server-plugins/mule-agent-plugin to $MULE_HOME/tools/mule-agent-backup.zip

    • Archives any custom modules (usually located in $MULE_HOME/server-plugins/mule-agent-plugin/lib/modules) to $MULE_HOME/tools/mule-agent-modules-backup.zip

  • Updates agent libraries in $MULE_HOME/server-plugins/mule-agent-plugin/lib

  • Retains the current $MULE_HOME/conf/mule-agent.yml configuration file

  • Leaves modules in $MULE_HOME/server-plugins/mule-agent-plugin/lib/modules unchanged

    This directory contains all custom modules added to the agent (not included in the agent distribution).

  • Updates the default agent truststore name from truststore.jks to anypoint-truststore.jks (for updates to versions 1.11.0 or 2.1.4 and later).

Roll Back the Agent

If you need to roll back the agent, for example, if problems occur when you update the agent, restore the previous version from the mule-agent-backup.zip file. This ZIP file includes libraries, configuration files, and compiled classes for the agent.

To roll back the agent:

  1. Stop Mule or the API gateway runtime.

  2. Change to the mule-agent-plugin directory:

    cd $MULE_HOME/server-plugins/mule-agent-plugin

  3. Ensure that you are in the mule-agent-plugin directory:

    pwd

  4. Remove the existing agent files:

    rm -r *

  5. Copy the backup ZIP file to the mule-agent-plugin directory:

    cp $MULE_HOME/tools/mule-agent-backup.zip .

  6. Restore the previous version of the agent from the backup ZIP file:

    unzip mule-agent-backup.zip

  7. Remove the backup ZIP file:

    rm mule-agent-backup.zip

  8. Restart Mule or the API gateway runtime.

Disable the Agent

To disable the agent:

  1. Stop Mule or the API gateway runtime.

  2. Remove these files:

    $MULE_HOME/conf/mule-agent.jks
$MULE_HOME/conf/mule-agent.yml

  3. Restart Mule or the API gateway runtime.

The agent still starts up when disabled, but it does not perform any operation.

amc_setup Parameters

Parameters to amc_setup enable you to:

To see available options, run ./amc_setup --help.

Parameter Value Description

--help

Displays help for the command on the command line.

-U

--update

Updates the agent, preserving the existing mule-agent.yml configuration file.

When you update a previous agent installation using -U, you can’t include other parameters on the command line.

-E

--encrypt

Encrypts the passwords in an existing mule-agent.yml file.

Use this option alone to encrypt passwords. For information, see Encrypt Passwords in an Existing mule-agent.yml File.

--decrypt

Decrypts the passwords in an existing mule-agent.yml file, for example, before changing the main password.

Use this option alone to decrypt passwords. For information, see Update the Main Password and Display Passwords in mule-agent.yml in Plain Text.

--mule-home

mule-home-directory

Specifies the location of the $MULE_HOME directory.

Use this option if you are running the installation script from a location other than $MULE_HOME/bin.

The amc_setup script reads the mule-agent.yml file from ../conf, relative to the directory specified by --mule-home. For example, if the value of --mule-home is /tmp/Mule/bin, amc_setup reads mule-agent.yml from /tmp/Mule/conf.

--skip-gateway-clientid

Skips configuration of the API gateway client_id and client_secret.

-I

--insecure

Configures the agent to use an unencrypted REST connection.

See Insecure Connection Channel.

Do not use this parameter with the PCE amc_setup parameters.

This option replaces the contents of $MULE_HOME/conf/mule-agent.yml.

-S

--secure

Configures the agent to establish a TLS connection with an on-premises administration console.

See Secure Connection Channel

Do not use this parameter with the PCE amc_setup parameters.

This option replaces the contents of $MULE_HOME/conf/mule-agent.yml.

-H

--hybrid

token

server-name

Configures the agent to connect with either Anypoint Platform PCE or cloud-based Anypoint Platform managed by MuleSoft.

  • token is a base64 encoded string that specifies the exact business group and environment with which to register Mule with Runtime Manager.

  • server-name is the instance name used to identify Mule in the Runtime Manager console.

    This name must be unique within the business group’s environment.

-P

--proxy

proxy-host

proxy-port

proxy-user

proxy-password

Specifies the proxy configuration to use when registering with the connection.

See Connect the Agent Through a Proxy Server.

-R

--region

region

Specifies the region to deploy to. Available regions are prod, eu1, and us_gov.

--fips

Enables FIPS 140-2 compliance on Mule 4 runtime on *nix-based servers.

Register Mule with the Cloud-Based Runtime Manager

logo hybrid active

To register Mule with the Anypoint Platform Runtime Manager cloud-based console, you need:

  • A valid registration token, which identifies a specific environment for a specific business group in Anypoint Platform

  • An instance name, which identifies Mule in the Runtime Manager console

To register Mule:

  1. In Runtime Manager, click Servers in the left menu.

  2. Click the Add Server button.

  3. Enter a unique name for your server.

    Server names can contain up to 60 alphanumeric characters (a-z, A-Z, 0-9), periods (.), hyphens (-), and underscores (_), but not spaces or other special characters. Runtime Manager supports Unicode characters in server names.

    The server name must be unique in the environment, but it can be the same for the same organization in different environments.

    Runtime Manager generates the amc_setup command. This command includes the server name you specified (server-name) and the registration token (token) required to register Mule in your environment. The registration token includes your organization ID and the current environment.

    amc_setup command in the Add Server window
    Figure 1. The arrow shows the amc_setup command in the Add Server window.

  4. Click Copy command to copy the command.

  5. In a terminal window:

    1. Change to the $MULE_HOME/bin directory for the Mule instance that you’re registering.

    2. If you want to encrypt passwords in the mule-agent.yml file, set the AGENT_VAR_master_password environment variable to the main password:

      export AGENT_VAR_master_password=myPassword

    3. Paste the command on the command line.

    4. Include any other parameters on the amc_setup command line.

      See amc_setup Parameters.

      Here is an example amc_setup command:

      ./amc_setup -H myToken myMuleServer --proxy myProxy-host myProxy-port myProxy-user myProxy-password

The amc_setup command generates the $MULE_HOME/conf/mule-agent.yml file.

Example mule-agent.yml File

Here is an example mule-agent.yml file generated by the -H option, with encrypted passwords:

transports:
  rest.agent.transport:
    enabled: false
  websocket.transport:
    consoleUri: wss://runtime-manager.anypoint.mulesoft.com:443/mule
    handshake:
      enabled: true
      body:
globalConfiguration:
  security:
    keyStorePassword: "![PBEWITHSHA1ANDDESEDE,WdPmAQMIC8Atr5iK4phjmbZbs9XFLLiH1eDhA7AmnpKUaPDhp40OB4uKZ6JUMW44]"
    keyStoreAlias: agent
    keyStoreAliasPassword: "![PBEWITHSHA1ANDDESEDE,WdPmAQMIC8Atr5iK4phjmbZbs9XFLLiH1eDhA7AmnpKUaPDhp40OB4uKZ6JUMW44]"
  authenticationProxy:
    endpoint: https://data-authenticator.anypoint.mulesoft.com:443
  proxyConfiguration:
    password: '![PBEWITHSHA1ANDDESEDE,VIs82yFDp66lnsL/Rss8q8js/zPDQ8+HJpdNepdZtA9obeDj5u+z4HIocsbLvXow]'

Register Mule with Anypoint Platform PCE Runtime Manager

logo server active

With Anypoint Platform Private Cloud Edition (Anypoint Platform PCE), all Runtime Manager services run on-premises rather than in a cloud environment managed by MuleSoft.

To register Mule with PCE Runtime Manager:

  1. Log in to an Anypoint Platform PCE account.

  2. Ensure that you have correctly set up the DNS entry for your platform.

    See DNS or IP.

  3. Select a business group and environment with which to register Mule.

  4. Within the selected environment, click Servers in the left menu.

  5. Click the Add Server button.

    Runtime Manager generates the amc_setup command, including token and server-name, to use to register Mule in your environment.

    The registration token includes your organization’s ID and the current environment.

  6. Click Copy to copy the command.

  7. In a terminal window, change to the $MULE_HOME/bin directory for the Mule instance that you’re registering.

  8. Paste the command on the command line.

  9. Change the instance name server-name to the unique name to use to label Mule in the Runtime Manager console.

  10. Include any other parameters on the amc_setup command line.

    See amc_setup Parameters.

  11. Append parameters to the command line to specify the URLs of services used by Runtime Manager to manage your Mule instance.

    See PCE Runtime Manager amc_setup Parameters.

    Here is an example amc_setup command:

    ./amc_setup -H myToken myMuleServer -A +http://$DOCKER_IP_ADDRESS:443/hybrid/api/v1+ -W "wss://AnypointPlatformHost:8889/mule" -C https://AnypointPlatformHost/accounts -F https://AnypointPlatformHost/apiplatform

The amc_setup command generates the $MULE_HOME/conf/mule-agent.yml file.

PCE Runtime Manager amc_setup Parameters

This table lists additional parameters required to register Mule with Anypoint Platform PCE Runtime Manager. Append these parameters to the ./amc_setup -H token server-name command.

Do not use these parameters with the -I or S parameters to configure REST API connections.

Parameter Value Description

-A

--amc-host

amc-host

Specifies the service location URL of your local instance of Runtime Manager, for example, https://10.0.0.1:443/hybrid/v1.

You can test whether the service is available at AMC_HOST/hybrid/v1.

-W

--mcm-host

mcm-host

Specifies the service location URL of your local instance of MCM, for example, wss://10.0.0.2:8889/mule.

You can test whether the service is available at MCM_HOST/mule.

-C

--cs-host

core-services-host

Specifies the service location URL of your local instance of Access Management, for example, https://10.0.0.3:443/accounts.

You can test whether the service is available at core-services-host/accounts.

-D

--contract-caching-service-host

contract-caching-service-host

Specifies the service location (URL) of your local instance of Contract Caching Service, for example, https://10.0.0.4:8080.

-F

--api-platform-host

api-platform-host

Specifies the service location URL of your local instance of API Manager, for example, https://10.0.0.5:443/apiplatform.

You can test whether the service is available at API_PLATFORM_HOST/apiplatform.

-Z

--auth-proxy-host

auth-proxy-host

Specifies the service location URL of your Auth Proxy, for example, https://10.0.0.3:8080.

Encrypt Passwords in an Existing mule-agent.yml File

If you didn’t set the AGENT_VAR_master_password environment variable when registering the agent with Runtime Manager, you can encrypt the following passwords later in the mule-agent.yml file:

  • keystorePassword: Keystore password used to access the mule-agent.jks file

  • keystoreAliasPassword: Keystore alias password used to access the mule-agent.jks file

  • password: Password used for authenticating with a proxy server

Prerequisites

  • Runtime Manager agent version 2.4.17

    To update previous versions of the agent, see Update the Agent.

Encrypt Passwords

To encrypt passwords in your mule-agent.yml file:

  1. Set the AGENT_VAR_master_password environment variable to the main password:

    export AGENT_VAR_master_password=myPassword

  2. Run the encryption utility:

    $MULE_HOME/bin/amc_setup --encrypt

    The encryption utility replaces the passwords in the keystorePassword, keystoreAliasPassword, and password fields in the mule-agent.yml file with the encrypted passwords, for example:

    globalConfiguration:
  security:
    keyStorePassword: '![PBEWITHSHA1ANDDESEDE,Fe4kl2UBnGRoyh7H2v9lq+QSG7Pe6ZP8k34xmZEHmcAb1jABAwPLk2xWrGtSt1iE]'
    keyStoreAlias: agent
    keyStoreAliasPassword: '![PBEWITHSHA1ANDDESEDE,EtqRDPq7UTxDHzZGpOGazfcveEi832Pqm1mqhlwYRGLZGh9NSNXie6nAZr09b3iT]'
  authenticationProxy:
    endpoint: https://data-authenticator.anypoint.mulesoft.com:443
  proxyConfiguration:
    password: '![PBEWITHSHA1ANDDESEDE,VIs82yFDp66lnsL/Rss8q8js/zPDQ8+HJpdNepdZtA9obeDj5u+z4HIocsbLvXow]'

The encrypted passwords start with ! and are enclosed in square brackets [ ].

Update and Reencrypt Passwords

To update an encrypted password in the mule-agent.yml file:

  1. Edit mule-agent.yml.

  2. Replace the encrypted password with the new plain-text password.

  3. Set the AGENT_VAR_master_password environment variable:

    export AGENT_VAR_master_password=myPassword

  4. Run the encryption utility:

    $MULE_HOME/bin/amc_setup --encrypt

Display Passwords in mule-agent.yml in Plain Text

To display the passwords in mule-agent.yml in plain text, run the decryption utility:

$MULE_HOME/bin/amc_setup --decrypt

This command outputs the contents of the mule-agent.yml file with plain-text passwords.

Update the Main Password

To update the main password:

  1. Run the decryption utility:

    $MULE_HOME/bin/amc_setup --decrypt

  2. Set the AGENT_VAR_master_password environment variable to the new main password:

    export AGENT_VAR_master_password=myNewPassword

  3. Run the encryption utility:

    $MULE_HOME/bin/amc_setup --encrypt

See Also