add custom port instructions

Author: seligj95

articles/app-service/app-service-hybrid-connections.md

@@ -4,7 +4,7 @@ description: Learn how to create and use hybrid connections in Azure App Service
 author: seligj95
 ms.assetid: 66774bde-13f5-45d0-9a70-4e9536a4f619
 ms.topic: how-to
-ms.date: 10/27/2025
+ms.date: 12/16/2025
 ms.update-cycle: 1095-days
 ms.author: jordanselig
 #customer intent: As an app developer, I want to understand the usage of Hybrid Connections to provide access to apps in Azure App Service.
@@ -175,8 +175,8 @@ To support the Hybrid Connections it's configured with, the Hybrid Connection Ma
 
 - TCP access to Azure over port 443.
 - TCP access to the Hybrid Connection endpoint.
-- Windows clients must have ports 4999-5001 available.
-- Linux clients must have port 5001 available.
+- Windows clients use ports 4999-5001 by default. These ports can be [modified if needed](#configure-custom-ports).
+- Linux clients use port 5001 by default. This port can be [modified if needed](#configure-custom-ports).
 - The ability to do DNS look-ups on the endpoint host and the Service Bus namespace. In other words, the hostname in the Azure relay connection should be resolvable from the machine that hosts the Hybrid Connection Manager.
 
 ### Getting started with the Hybrid Connection Manager GUI
@@ -221,7 +221,7 @@ On Windows, you can use the Hybrid Connection Manager CLI by searching for and o
 
 # [Linux](#tab/linux)
 
-On Linux, once installed, you can run `hcm help` to confirm the Hybrid Connection Manager is installed and to see the available commands.
+On Linux, once installed, you can run `hcm --help` to confirm the Hybrid Connection Manager is installed and to see the available commands.
 
 -----
 
@@ -245,6 +245,45 @@ You can also show the details of a specific Hybrid Connection with the `hcm show
 
 :::image type="content" source="media/app-service-hybrid-connections/hybrid-connections-hcm-details-cli.png" alt-text="Screenshot of Hybrid Connection Details in CLI.":::
 
+### Configure custom ports
+
+By default, the Hybrid Connection Manager uses ports 4999-5001 on Windows and port 5001 on Linux. You can configure custom ports if the default ports are unavailable or if your environment requires different port assignments.
+
+# [Windows](#tab/windows)
+
+To configure custom ports on Windows, navigate to **Edit the system environment variables** with Windows Search and add the following environment variables. Ensure you're editing the **System Variables** section, not the user variables.
+
+- `HCM_GUI_PORT`
+- `HCM_SERVICE_PORT`
+
+Set the value of each variable to the port number you want to use. For example, `HCM_GUI_PORT=1234`.
+
+> [!NOTE]
+> If you set these environment variables after the Hybrid Connection Manager is installed, you need to restart **HybridConnectionManagerService** through **Services** from Windows Search. We recommend setting these variables before you install the Hybrid Connection Manager to avoid issues with the service picking up these values.
+
+# [Linux](#tab/linux)
+
+To configure a custom port on Linux:
+
+1. Edit the `/etc/environment` file as root or with sudo and add the following line. Replace `<PORT-NUMBER>` with the port number you want to use for the Hybrid Connection Manager service:
+
+    ```bash
+    HCM_SERVICE_PORT=<PORT-NUMBER>
+    ```
+
+1. Re-run the Hybrid Connection Manager setup script to apply the new port configuration:
+
+    ```bash
+    sudo ./setup.sh
+    ```
+
+    If running the setup script with sudo doesn't apply the port change, try running it without sudo.
+
+> [!NOTE]
+> We recommend setting this environment variable before installing the Hybrid Connection Manager. If you set the variable after installation, you must re-run the setup script.
+
+----- 
+
 ### Configure proxy server settings
 
 If you need to configure proxy server settings for the Hybrid Connection Manager, edit the `ProxySettings` section in the `appsettings.json` file located at: