Configure REST Connections With amc_setup Parameters

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.

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.

Parameter Description

Parameter	Description
`-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/`.

-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:

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.

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.

Parameter Description

Parameter	Description
`-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.

-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:

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.

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:

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"

Export the Runtime Manager agent certificate (only the public key) to a DES-formatted certificate file.

echo "Export the rma alias' certificate from the rmakeystore.jks key store"
keytool -export -alias rma -file rma.crt -keystore rmakeystore.jks -storepass mulesoft

For each REST client that connects to the Runtime Manager agent, generate a keystore (public-private key pair) to identify the REST client.

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"

Export the REST client certificate (the public key only) to a DES-formatted certificate file.

echo "Export the client alias' certificate from the clientkeystore.jks key store"
keytool -export -alias client -file client.crt -keystore clientkeystore.jks -storepass mulesoft

Create the truststore file.
```
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.
Configure Mule runtime engine with the rmakeystore.jks file and the cacerts.jks truststore.

From the $MULE_HOME/bin folder, run ./amc_setup -S.

When prompted, enter the values you generated.

For example, if you run the previous commands from the /security folder, enter these values:

-> 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.

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.

Restart Mule runtime engine and verify that the Runtime Manager agent REST interface starts successfully.
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:

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.

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"

Export the Runtime Manager agent certificate (only the public key) to a DES-formatted certificate file.

echo "Export the rma alias' certificate from the rmakeystore.jks key store"
keytool -export -alias rma -file rma.crt -keystore rmakeystore.jks -storepass mulesoft

For each REST client that connects to the Runtime Manager agent, generate a keystore (public-private key pair) to identify the REST client.

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"

Export the REST client certificate (the public key only) to a DES-formatted certificate file.

echo "Export the client alias' certificate from the clientkeystore.jks key store"
keytool -export -alias client -file client.crt -keystore clientkeystore.jks -storepass mulesoft

Create the truststore file containing both the client and RMA certificates.
```
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.

Back up the anypoint-truststore.jks and mule-agent.yml files.

cp anypoint-truststore.jks anypoint-truststore.jks.bkp
cp mule-agent.yml mule-agent.yml.bkp

Export the Anypoint Platform certificate to a DES-formatted certificate file.

If prompted for a password, press Enter.
```
keytool -export -alias hybrid -file hybrid.crt -keystore anypoint-truststore.jks
```
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.

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

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

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.

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.
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:

Convert the JKS keystore to a P12 keystore.

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

Use the openssl tool to export a base64 encoded text file of the full client certificate (public and private keys):
```
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.

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.

$ 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}]