diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 000000000..9e26dfeeb --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1 @@ +{} \ No newline at end of file diff --git a/runtime-manager/modules/ROOT/assets/image-source-files/mule-registered.graffle b/runtime-manager/modules/ROOT/assets/image-source-files/mule-registered.graffle new file mode 100644 index 000000000..42d2e9e78 Binary files /dev/null and b/runtime-manager/modules/ROOT/assets/image-source-files/mule-registered.graffle differ diff --git a/runtime-manager/modules/ROOT/assets/image-source-files/mule-running.graffle b/runtime-manager/modules/ROOT/assets/image-source-files/mule-running.graffle new file mode 100644 index 000000000..00dfad7fd Binary files /dev/null and b/runtime-manager/modules/ROOT/assets/image-source-files/mule-running.graffle differ diff --git a/runtime-manager/modules/ROOT/assets/image-source-files/traffic-add-server.graffle b/runtime-manager/modules/ROOT/assets/image-source-files/traffic-add-server.graffle new file mode 100644 index 000000000..ff82336fc Binary files /dev/null and b/runtime-manager/modules/ROOT/assets/image-source-files/traffic-add-server.graffle differ diff --git a/runtime-manager/modules/ROOT/assets/images/mule-registered.png b/runtime-manager/modules/ROOT/assets/images/mule-registered.png new file mode 100644 index 000000000..6edd9d7d1 Binary files /dev/null and b/runtime-manager/modules/ROOT/assets/images/mule-registered.png differ diff --git a/runtime-manager/modules/ROOT/assets/images/mule-running.jpg b/runtime-manager/modules/ROOT/assets/images/mule-running.jpg new file mode 100644 index 000000000..463e3f1b6 Binary files /dev/null and b/runtime-manager/modules/ROOT/assets/images/mule-running.jpg differ diff --git a/runtime-manager/modules/ROOT/assets/images/mule-running.png b/runtime-manager/modules/ROOT/assets/images/mule-running.png new file mode 100644 index 000000000..2df27cad9 Binary files /dev/null and b/runtime-manager/modules/ROOT/assets/images/mule-running.png differ diff --git a/runtime-manager/modules/ROOT/assets/images/traffic-add-server.png b/runtime-manager/modules/ROOT/assets/images/traffic-add-server.png new file mode 100644 index 000000000..bb669a451 Binary files /dev/null and b/runtime-manager/modules/ROOT/assets/images/traffic-add-server.png differ diff --git a/runtime-manager/modules/ROOT/pages/rtm-agent-proxy-config.adoc b/runtime-manager/modules/ROOT/pages/rtm-agent-proxy-config.adoc index 403ee1e94..f3db02106 100644 --- a/runtime-manager/modules/ROOT/pages/rtm-agent-proxy-config.adoc +++ b/runtime-manager/modules/ROOT/pages/rtm-agent-proxy-config.adoc @@ -95,6 +95,7 @@ add your proxy server information to the following properties: * `wrapper.java.additional.=-Danypoint.platform.proxy_password={password}` [IMPORTANT] + These are additional parameters to pass to Java when it is launched. The element refers to the number of additional parameters in the configuration. It is indicated with an integer number counting up from `1` and must follow a sequence without any gaps. == Verify That the Proxy Server Does Not Modify the Runtime Manager Certificate diff --git a/runtime-manager/modules/ROOT/pages/rtm-traffic-inspection.adoc b/runtime-manager/modules/ROOT/pages/rtm-traffic-inspection.adoc new file mode 100644 index 000000000..a981ea87b --- /dev/null +++ b/runtime-manager/modules/ROOT/pages/rtm-traffic-inspection.adoc @@ -0,0 +1,128 @@ += Traffic Inspection for Standalone Mule Instances +ifndef::env-site,env-github[] +include::_attributes.adoc[] +endif::[] +:keywords: agent, runtime manager, traffic inspection, standalone +:page-deployment-options: hybrid + +The traffic inspection feature for standalone Mule instances adds support to the Runtime Manager agent for a forward proxy that is deployed in your environment. This proxy acts as a man-in-the-middle between Mule and the control plane, intercepting and inspecting all HTTPS traffic. + +To enable traffic inspection, you must install the Mule instance and the Runtime Manager agent from scratch using the following instructions. + +[NOTE] +Upgrading from a standalone Mule deployed in a PCE environment is not supported. + +== Before You Begin + +* Build an HTTP proxy with support for TLS connections to the runtime client and mTLS connections to the control plane server. ++ +The inspection proxy server does not require the Runtime Manager agent to present a client certificate. Communication between the agent and the inspection proxy is TLS, not mTLS. + +* Provision this inspection proxy to send a customer-private certificate to the Runtime Manager agent. ++ +The agent uses a Certificate Authority from the Java Virtual Machine (JVM) keystore to validate the public certificate presented by the inspection proxy. ++ +The inspection proxy and the MuleSoft control plane communicate via mTLS. The two certificates involved are: ++ +** The control plane presents a MuleSoft public server certificate to the inspection proxy. The proxy must be provisioned with the correct Certificate Authority to validate the server certificate presented by the MuleSoft control plane. +** The control plane requires a client certificate from the inspection proxy. The customer must provide this certificate to MuleSoft. ++ +[NOTE] +Communication with the control plane fails if the certificate does not match the specified serial number and common name. + +== Provision the Truststore of the JVM with the Proxy Root CA + +. Identify the folder location of the JVM. +. Insert the root CA of the proxy in the truststore of the Mule JVM: ++ +In the terminal window, run the following command, replacing `$JAVA_HOME` with the actual path: ++ +[source,console,linenums] +---- +sudo keytool -import -alias testCert -keystore $JAVA_HOME/jre/lib/security/cacerts -file proxy_cacert.pem +---- ++ +. Enter the provided password. +. If you have multiple versions of Java, insert the certificate in the version of Java that the Mule instance uses. + +== Install Mule + +Install the latest available Mule version. You can skip this step if already installed. + +For instructions about how to install Mule, see xref:mule-runtime::runtime-installation-task.adoc[]. + +Using an earlier version might result in some functionalities not working as expected. To check the latest Mule version, see xref:release-notes::mule-runtime/mule-esb.adoc[]. + +[NOTE] +The Mule runtime installation bundle includes both Mule runtime engine and the Runtime Manager agent. + +== Upgrade the Runtime Manager Agent + +Make sure that the version of Runtime Manager agent is 2.5.6 or later. For instructions about how to check your agent version, see xref:debugging-the-runtime-manager-agent.adoc#troubleshoot-connection-issues-between-the-agent-and-mule[Troubleshoot the Runtime Manager Agent]. + +If you have an earlier version, update the agent by following these steps: + +. Download the `agent-setup-2.5.6.zip` file. +. Extract the downloaded ZIP file to `$MULE_HOME/bin`. +. If prompted, overwrite any conflicting files. ++ +Do not run `amc_setup -U`. + +== Check Your Server Certificates + +Registering a Mule server requires a valid certificate to secure communication between Runtime Manager and the Runtime Manager agent. + +Certificates are valid for two years. To check a certificate expiration date, follow the steps in xref:servers-cert-renewal.adoc#view-a-certificate-expiration-date[View a Certificate Expiration Date]. + +=== Renew Your Server Certificates + +To renew your certificates from Runtime Manager, follow the instructions in xref:servers-cert-renewal.adoc#renew-a-certificate-from-runtime-manager[Renew a Certificate from Runtime Manager]. You need to update to the latest Mule agent to renew your certificates through Runtime Manager. + +Alternatively, you can xref:servers-cert-renewal.adoc#renew-a-certificate-via-the-command-line[Renew a Certificate via the Command Line]. Use version 2.4.37 of the certificate renewal JAR file. + +For agent version 2.5.6, you cannot renew your certificates from Runtime Manager. If you need to renew your certificates, follow the instructions in xref:servers-cert-renewal.adoc#renew-a-certificate-via-the-command-line[Renew a Certificate via the Command Line]. Use version 2.4.37 of the certificate renewal JAR file. + +== Register Mule + +. Update the `wrapper.conf` file with the IP and port of the traffic inspection proxy by following the instructions in xref:rtm-agent-proxy-config.adoc#set-up-proxy-server-configuration-in-the-wrapper-conf-file[Set Up Proxy Server Configuration in the wrapper.conf File]. +. Log in to Anypoint Platform. +. From Anypoint Platform, select *Runtime Manager* > *Servers*. +. Click *Add Server*. ++ +image::traffic-add-server.png[Add server] ++ +. In a terminal window, change the `$MULE_HOME/bin` directory to the Mule instance that you're registering. +. Paste the command on the command line and append the proxy's IP address or domain name and port, and the `--enable-traffic-inspection` configuration flag. ++ +[source,console,linenums] +---- +./amc_setup -H {registrationToken} {serverName} -P {proxy ip or hostname} {proxyPort} --enable-traffic-inspection +---- ++ +[NOTE] +Make sure to leave a space between the proxy's domain name and port number. ++ +. Confirm that the Mule instance registered successfully by checking that the runtime appears as *Created* in the Anypoint Platform console: ++ +image::mule-registered.png[The Mule instance appears as created] ++ +. Edit the file `$MULE_HOME/conf/mule-agent.yml` and set the property `authenticationProxy.endpoint` to `null`. +. Start the Mule instance. ++ +See xref:mule-runtime::starting-and-stopping-mule-esb.adoc[]. + +== Check that the Mule Instance is Connected to the Control Plane + +If the connection is successful, the status of the Mule instance appears as *Running* in the Anypoint Platform console: + +image::mule-running.png[The Mule instance appears as running] + +If the connection is established, the agent terminal window displays the following message: + +[source,console,linenums] +---- +INFO 2023-04-19 17:27:41,307 [WebSocketInboundExecutor] [processor: ; event: ] com.mulesoft.agent.transport.handlers.GenericWebSocketHandler: Opening Mule Agent WebSocket +INFO 2023-04-19 17:27:41,316 [WebSocketInboundExecutor] [processor: ; event: ] com.mulesoft.agent.transport.handlers.GenericWebSocketHandler: Mule Agent WebSocket opened +INFO 2023-04-19 17:27:41,316 [pool-12-thread-1] [processor: ; event: ] com.mulesoft.agent.transport.connections.AsyncHttpWSConnectionThread: Mule Agent WebSocket connection was initialized after: 1 attempts +INFO 2023-04-19 17:27:42,179 [WebSocketInboundExecutor] [processor: ; event: ] com.mulesoft.agent.services.security.HandshakeAuthorizationService: WebSocket Client connection authorized +----