--- schema_version: "1" id: 98c998efc5e4a3c29e73f77b00c57544dca803d1fc267d46f9050c890530725b title: Configure REST Connections With amc_setup Parameters collection: mulesoft version: current locale: en-us portal_url: https://docs.salesforce.com/mulesoft/current/en-us/runtime-manager/rtm-agent-REST-connections.md canonical_url: https://docs.mulesoft.com/runtime-manager/rtm-agent-REST-connections source_site: docs.mulesoft.com content_type: documentation content_hash: 9ca8c30acf0aef8388816e2deed5afc29481390b140bc7c5c9f5ec999dcef0c4 description: MuleSoft Documentation Site latest: true --- --- product: Runtime Manager keywords: agent, runtime manager, mule, esb, servers, monitor, notifications, external systems, third party, get status, metrics --- # Configure REST Connections With amc\_setup Parameters > For the full documentation index, see: https://docs.mulesoft.com/llms.txt [![logo hybrid active](/mulesoft/current/en-us/_/img/icons/hybrid-cloud.svg "Hybrid")Hybrid](deployment-strategies#hybrid-deployments)[ ![logo server active](/mulesoft/current/en-us/_/img/icons/server-cloud.svg "Anypoint Platform PCE")Private Cloud Edition](deployment-strategies#anypoint-platform-private-cloud-edition) The REST connection `amc_setup` parameters work in both versions of Anypoint Platform (cloud and on-premises) to allow direct REST connections between Mule runtime engine and any external client. This enables external clients to access and manage a Mule runtime engine directly via the [Runtime Manager agent REST API](https://docs.mulesoft.com/runtime-manager/runtime-manager-agent-api). You can configure the Runtime Manager agent to allow either insecure or secure connections. With a secure REST configuration, configure the Runtime Manager agent with a valid digital certificate. The insecure REST configuration option allows you to skip this step. ## Insecure Connection Channel To configure the Runtime Manager agent to use an unencrypted connection, use the `-I` parameter on the installation command line. It is only valid for the REST transport. You can interact with the API using a browser or other tool for making HTTP requests.
ParameterDescription

-I

--insecure

Configures the Runtime Manager agent to use an unencrypted connection.

The default TCP port is 9999, so you can connect to the Runtime Manager agent at the base URL http://localhost:9999/mule/agent/.

Here is an example `mule-agent.yml` file generated by the `-I` parameter: ```yaml transports: websocket.transport: enabled: false rest.agent.transport: port: 9999 services: mule.agent.jmx.publisher.service: enabled: true frequency: 15 frequencyTimeUnit: MINUTES ``` ## Secure Connection Channel You can configure the Runtime Manager agent to establish a TLS connection by using the `-S` argument on the installation command line. This option enables a TLS channel for REST communications only. You can use this option when managing the agent manually. For detailed steps, see [Configure Two-Way TLS for Mule Runtime Engine Without the Control Plane](#configure-two-way-tls-for-mule-runtime-engine-without-the-control-plane). If you’re using the Anypoint Platform Runtime Manager cloud console to manage the agent, see [Configure Two-Way TLS for Mule Runtime Engine Managed by Control Plane](#configure-two-way-tls-for-mule-runtime-engine-managed-by-control-plane).
ParameterDescription

-S

--secure

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

Provide the keystore (public-private key pair) and truststore files in JKS format.

After you select the secure connection channel mode, you see this menu: The communication channel for the agent will be encrypted using public/private key certificates. The following steps prompt you for the keystore and truststore. Both keystore and truststore format must be JKS. Keystore location (?): Truststore location (?): Keystore Password (?): Keystore Alias (?): Keystore Alias Password (?): INFO: Mule agent was successfully configured to use a TLS channel for REST communications. - **Keystore location** (Required) Specifies the location of the keystore file to encrypt the communication channel. The keystore file must be in JKS format. - **Truststore location** Specifies the location of the truststore file that you want to accept incoming requests from the administration console. The truststore must be in JKS format and must not have a password. - **Keystore Password** Provides the password that the agent uses to read the keystore. The agent uses the password to open the keystore. - **Keystore Alias** Specifies the alias of the key stored in the keystore. - **Keystore Alias Password** The alias password in the keystore. Here is an example `mule-agent.yml` file generated by the `-S` parameter: ```yaml transports: websocket.transport: enabled: false rest.agent.transport: restSecurity: keyStoreFile: server.jks keyStorePassword: P@ssword keyStoreAlias: serverkey keyStoreAliasPassword: P@ssword port: 9999 services: mule.agent.jmx.publisher.service: enabled: true frequency: 15 frequencyTimeUnit: MINUTES ``` ### Configure Two-Way TLS for Mule Runtime Engine Without the Control Plane To configure two-way TLS when Mule is not connected to the control plane, use the `amc_setup -S` option. 1. Generate a keystore (public-private key pair) to identify the Runtime Manager agent (server). Set the CN to match the Runtime Manager agent hostname or IP address: ```console echo "Generate a new keystore to identify the Runtime Manager agent. Use CN=localhost" keytool -keystore rmakeystore.jks -genkey -keyalg RSA -keypass mulesoft -storepass mulesoft -noprompt \ -alias rma \ -dname "CN=localhost, OU=Runtime Manager Agent, O=MuleSoft, L=San Francisco, S=Califorina, C=US" ``` 2. Export the Runtime Manager agent certificate (only the public key) to a DES-formatted certificate file. ```console echo "Export the rma alias' certificate from the rmakeystore.jks key store" keytool -export -alias rma -file rma.crt -keystore rmakeystore.jks -storepass mulesoft ``` 3. For each REST client that connects to the Runtime Manager agent, generate a keystore (public-private key pair) to identify the REST client. ```console echo "Generate a new keystore to be used by client requestors. Use CN=localhost" keytool -keystore clientkeystore.jks -storepass mulesoft -genkey -keyalg RSA -keypass mulesoft -noprompt \ -alias client \ -dname "CN=localhost, OU=RMA Client, O=MuleSoft, L=San Francisco, S=California, C=US" ``` 4. Export the REST client certificate (the public key only) to a DES-formatted certificate file. ```console echo "Export the client alias' certificate from the clientkeystore.jks key store" keytool -export -alias client -file client.crt -keystore clientkeystore.jks -storepass mulesoft ``` 5. Create the truststore file. ```console echo "Import client and server public keys into a common cacerts.jks truststore file" keytool -import -v -trustcacerts -alias rma -file rma.crt -keystore cacerts.jks -keypass mulesoft -storepass mulesoft -noprompt keytool -import -v -trustcacerts -alias client -file client.crt -keystore cacerts.jks -keypass mulesoft -storepass mulesoft -noprompt ``` Because the certificate files are self-signed, the client can’t validate them with a Certificate Authority (CA). To emulate CA signing the certificates, you must create a truststore file containing both the client and RMA certificates (public keys). In a production environment, the server and client certificates are both signed by a trusted CA, and then published or shared with the client and server machines. 6. Configure Mule runtime engine with the `rmakeystore.jks` file and the `cacerts.jks` truststore. From the `$MULE_HOME/bin` folder, run `./amc_setup -S`. 7. When prompted, enter the values you generated. For example, if you run the previous commands from the `/security` folder, enter these values: ```console -> Mule Agent Unpacked The communication channel for the agent will be encrypted using public/private key certificates. The following steps prompt you for the keystore and truststore. Both keystore and truststore formats must be JKS. Keystore location (?):/security/rmakeystore.jks Keystore Password (?): mulesoft Truststore location (?):/security/cacerts.jks Keystore Alias (?):rma Keystore Alias Password (?): mulesoft INFO: Mule agent was successfully configured to use a TLS channel for REST communications. > more ..\conf\mule-agent.yml transports: websocket.transport: enabled: false rest.agent.transport: restSecurity: keyStoreFile: clientkeystore.jks keystorePassword: mulesoft keyStoreAlias: client keyStoreAliasPassword: mulesoft port: 9999 services: mule.agent.jmx.publisher.service: enabled: true frequency: 15 frequencyTimeUnit: MINUTES ``` This command imports the `/security/cacerts.jks` truststore file into the `$MULE_HOME/conf` folder and renames it `anypoint-truststore.jks`. > [!NOTE] In the Runtime Manager agent version 1.11.0 and later, the name of the default > truststore is `anypoint-truststore.jks`. In earlier versions of the Runtime Manager agent, the > name is `truststore.jks`. 8. Restart Mule runtime engine and verify that the Runtime Manager agent REST interface starts successfully. 9. Add SSL debugging to the Mule runtime engine logging: `./mule -M-Djavax.net.debug=all` ### Configure Two-Way TLS for Mule Runtime Engine Managed by Control Plane To configure two-way TLS when Mule is connected to the control plane: 1. Generate a keystore (public-private key pair) to identify the Runtime Manager agent (server). Set the CN to match the Runtime Manager agent hostname or IP address. ```console echo "Generate a new keystore to identify the Runtime Manager agent. Use CN=localhost" keytool -keystore rmakeystore.jks -genkey -keyalg RSA -keypass mulesoft -storepass mulesoft -noprompt \ -alias rma \ -dname "CN=localhost, OU=Runtime Manager Agent, O=MuleSoft, L=San Francisco, S=Califorina, C=US" ``` 2. Export the Runtime Manager agent certificate (only the public key) to a DES-formatted certificate file. ```console echo "Export the rma alias' certificate from the rmakeystore.jks key store" keytool -export -alias rma -file rma.crt -keystore rmakeystore.jks -storepass mulesoft ``` 3. For each REST client that connects to the Runtime Manager agent, generate a keystore (public-private key pair) to identify the REST client. ```console echo "Generate a new keystore to be used by client requestors. Use CN=localhost" keytool -keystore clientkeystore.jks -storepass mulesoft -genkey -keyalg RSA -keypass mulesoft -noprompt \ -alias client \ -dname "CN=localhost, OU=RMA Client, O=MuleSoft, L=San Francisco, S=California, C=US" ``` 4. Export the REST client certificate (the public key only) to a DES-formatted certificate file. ```console echo "Export the client alias' certificate from the clientkeystore.jks key store" keytool -export -alias client -file client.crt -keystore clientkeystore.jks -storepass mulesoft ``` 5. Create the truststore file containing both the client and RMA certificates. ```console echo "Import client and server public keys into a common cacerts.jks truststore file" keytool -import -v -trustcacerts -alias rma -file rma.crt -keystore cacerts.jks -keypass mulesoft -storepass mulesoft -noprompt keytool -import -v -trustcacerts -alias client -file client.crt -keystore cacerts.jks -keypass mulesoft -storepass mulesoft -noprompt ``` Because the certificate files are self-signed, the client can’t validate them with a Certificate Authority (CA). To emulate CA signing the certificates, you must create a truststore file containing both the client and RMA certificates (public keys). In a production environment, the server and client certificates are both signed by a trusted CA, and then published or shared with the client and server machines. 6. Back up the `anypoint-truststore.jks` and `mule-agent.yml` files. ```console cp anypoint-truststore.jks anypoint-truststore.jks.bkp cp mule-agent.yml mule-agent.yml.bkp ``` 7. Export the Anypoint Platform certificate to a DES-formatted certificate file. If prompted for a password, press Enter. ```console keytool -export -alias hybrid -file hybrid.crt -keystore anypoint-truststore.jks ``` 8. Create the truststore file containing these certificates: client, RMA, and Anypoint Platform. keytool -import -v -trustcacerts -alias rma -file rma.crt -keystore cacerts.jks -keypass mulesoft -storepass mulesoft -noprompt keytool -import -v -trustcacerts -alias client -file client.crt -keystore cacerts.jks -keypass mulesoft -storepass mulesoft -noprompt keytool -import -v -trustcacerts -alias hybrid -file hybrid.crt -keystore cacerts.jks -keypass mulesoft -storepass mulesoft -noprompt Because the certificate files are self-signed, the client can’t validate them with a Certificate Authority (CA). To emulate CA signing these certificates, you must create a truststore file containing both the client and RMA certificates. The truststore file must also contain the Anypoint Platform certificate to retain connectivity with the control plane. In a production environment, the server and client certificates are both signed by a trusted CA, and then published or shared with the client and server machines. 9. Shut down Mule runtime engine and modify the `mule-agent.yml` file to configure the secure REST API endpoint. transports: rest.agent.transport: restSecurity: keyStoreFile: rmakeystore.jks keyStorePassword: mulesoft keyStoreAlias: rma keyStoreAliasPassword: mulesoft port: 9995 10. Rename the newly created `cacerts.jks` file to `anypoint-truststore.jks`. This file is your new truststore for the Runtime Manager agent as well as Anypoint Platform connectivity. mv cacerts.jks anypoint-truststore.jks > [!NOTE] In the Runtime Manager agent version 1.10.0 and later, the name of the default > truststore is `anypoint-truststore.jks`. In earlier versions of the Runtime Manager agent, the > name is `truststore.jks`. 11. Start Mule runtime engine, and verify the Runtime Manager agent REST interface starts up successfully and verify that it is still connected to Runtime Manager in Anypoint Platform. 12. Add SSL debugging to the Mule logging: `./mule -M-Djavax.net.debug=all` ### Submit Two-Way TLS REST Requests To submit two-way TLS REST requests: 1. Convert the JKS keystore to a P12 keystore. ```console echo "Export client keystore PKCS12 format from JKS" keytool -importkeystore -srckeystore clientkeystore.jks -srcstoretype JKS -srcstorepass mulesoft \ -destkeystore clientkeystore.p12 -deststoretype PKCS12 -deststorepass mulesoft \ -srcalias client -destalias client ``` 2. Use the `openssl` tool to export a base64 encoded text file of the full client certificate (public and private keys): ```console echo "Export full PEM (public and private keys) for use by client requests (cURL)" openssl pkcs12 -in clientkeystore.p12 -passin pass:mulesoft \ -out clientkeystore.pem -passout pass:mulesoft ``` You can view the `clientkeystore.pem` file to verify both the public and private keys were exported to this file. 3. Submit a REST request from the client host to the Runtime Manager agent host. Verify you do not see any SSL errors and you get a response back from the Runtime Manager agent. Use the `--insecure` option to skip verifying the server (Runtime Manager agent) certificate. ```console $ curl -X GET https://localhost:9999/mule/agent/components --cert clientkeystore.pem --insecure Enter PEM pass phrase: [{"componentId":"components.configure.request.handler","enabled":true},{"componentId":"clustering.request.handler","enab led":true},{"componentId":"applications.request.handler","enabled":true},{"componentId":"domains.request.handler","enabl ed":true},{"componentId":"flows.request.handler","enabled":true},{"componentId":"installer.request.handler","enabled":tr ue},{"componentId":"logging.request.handler","enabled":true},{"componentId":"monitoring.request.handler","enabled":true} ,{"componentId":"properties.request.handler","enabled":true},{"componentId":"tracking.request.handler","enabled":true},{ "componentId":"application.deployment.notification.internal.message.handler","enabled":true},{"componentId":"domain.depl oyment.notification.internal.message.handler","enabled":true},{"componentId":"flow.status.notification.internal.message. handler","enabled":true},{"componentId":"membership.change.notification.internal.message.handler","enabled":true},{"comp onentId":"primary.node.notification.internal.message.handler","enabled":true},{"componentId":"tracking.notification.inte rnal.message.handler","enabled":false},{"componentId":"mule.agent.tracking.handler.log","enabled":false},{"componentId": "mule.agent.gw.http.handler.log","enabled":false},{"componentId":"mule.agent.nagios.jmx.internal.handler","enabled":fals e},{"componentId":"mule.agent.tracking.handler.splunk","enabled":false},{"componentId":"mule.agent.gw.http.handler.splun k","enabled":false},{"componentId":"mule.agent.application.service","enabled":true},{"componentId":"mule.agent.clusterin g.service","enabled":true},{"componentId":"mule.agent.domain.service","enabled":true},{"componentId":"mule.agent.gw.http .service","enabled":false},{"componentId":"mule.agent.installer.service","enabled":true},{"componentId":"mule.agent.logg ing.service","enabled":true},{"componentId":"mule.agent.application.metrics.publisher.service","enabled":true},{"compone ntId":"mule.agent.jmx.publisher.service","enabled":true},{"componentId":"mule.agent.properties.service","enabled":true}, {"componentId":"mule.agent.tracking.service","enabled":true}] ```