Configure proxy settings for Azure Stack HCI, version 23H2

Article
04/16/2024

Applies to: Azure Stack HCI, version 23H2

This article describes how to configure proxy settings for Azure Stack HCI, version 23H2 if your network uses a proxy server for internet access.

For information about firewall requirements for outbound endpoints and internal rules and ports for Azure Stack HCI, see Firewall requirements for Azure Stack HCI.

Before you begin

Before you configure proxy settings, make sure that:

You know the proxy server name or IP address and port (optional). If you don’t have this information, contact your network administrator.
You configure the proxy server before you Register to Arc and assign permissions.

Note

Authenticated and certificate-based proxies are not supported in this release.

Configure proxy settings for Azure Stack HCI operating system

Use the following steps to configure proxy settings:

Step 1: Configure proxy settings for the Azure Stack HCI operating system.
Step 2: Configure proxy settings for Azure Arc-enabled servers.
Step 3: Configure proxy settings for Winhttp.

Step 1: Configure proxy settings for the Azure Stack HCI operating system

You must configure the proxy for Azure Stack HCI operating system before you Register the servers with Azure Arc.

Install the WinInetProxy module to run the commands in this section. For information about the module and how to install it, see WinInetProxy 0.1.0 in the PowerShell Gallery. For information about the WinInetProxy PowerShell script, see WinInetProxy.psm1 in the PowerShell Gallery.

Note

If you can't install the WinInetProxy module to a cluster node because of no internet access, we recommend that you download the module to your management computer, and then manually transfer it to the cluster node where you want to run the module.

You can also use the Start-BitsTransfer PowerShell cmdlet to transfer one or more files between your management computer and a server.

To configure the proxy settings for the Azure Stack HCI operating system, run the following PowerShell command as administrator on each server in the cluster:

Connect to the server via remote desktop protocol (RDP) or remote PowerShell.
Run the following cmdlet to configure proxy settings after you've installed the WinInetProxy module:
```
Set-WinInetProxy -ProxySettingsPerUser 0 -ProxyServer <Proxy_Server_Address:Proxy_Port> -ProxyBypass <URLs to bypass>
```
where:
- ProxySettingsPerUser specifies if the proxy settings are per machine or per user.
  - 0 - Proxy settings are per machine.
  - 1 (default) - Proxy settings are per user.
  - If no value is specified, use the environment variable ProxySettingsPerUser instead, if present.
- ProxyServer specifies the proxy server endpoint in the format [Proxy_Server_Address]:[Proxy_Port]. For example, proxy.contoso.com:8080.
- ProxyBypass specifies the list of host URLs that bypass proxy server set by the -ProxyServer parameter. The list must include:
  - IP address of each cluster member server.
  - Netbios name of each server.
  - Netbios cluster name.
  - contoso.com.
  - Second IP address of the infrastructure pool.
    
    Note
    
    The use of "<local>" is not supported in the proxy bypass list.
Here's an example of the command usage:
```
Set-WinInetProxy -ProxySettingsPerUser 0 -ProxyServer proxy.contoso.com:8080 -ProxyBypass "localhost,127.0.0.1,svc,node1,node2,s-cluster,192.168.0.2,192.168.0.3,contoso.com,192.168.0.10"
```

To remove the proxy configuration, run the PowerShell cmdlet Set-WinInetProxy without arguments.

Step 2: Configure proxy settings for Azure Arc-enabled servers

You must configure the proxy for Azure Arc-enabled servers before you register your server with Azure Arc.

To set the proxy server environment variable, run the following commands as administrator on each server in the cluster:

# If a proxy server is needed, run these commands with the proxy URL and port.
[Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://ProxyServerFQDN:port", "Machine")
$env:HTTPS_PROXY = [System.Environment]::GetEnvironmentVariable("HTTPS_PROXY", "Machine")
[Environment]::SetEnvironmentVariable("HTTP_PROXY", "http://ProxyServerFQDN:port", "Machine")
$env:HTTP_PROXY = [System.Environment]::GetEnvironmentVariable("HTTP_PROXY", "Machine")

$no_proxy = "localhost,127.0.0.1,.svc,node1,node2,scluster,192.168.0.2,192.168.0.3,*.contoso.com,192.168.0.10" 
[Environment]::SetEnvironmentVariable("NO_PROXY", $no_proxy, "Machine")
$env:NO_PROXY = [System.Environment]::GetEnvironmentVariable("NO_PROXY", "Machine")

# For the changes to take effect, restart the agent services after the proxy environment variable is set.  This is only required if the agent is already installed
Restart-Service -Name himds, ExtensionService, GCArcService

Confirm that the settings were applied by running the following command:
```
echo "https :" $env:https_proxy "http :" $env:http_proxy
```
Note that No_proxy specifies the list of host URLs that bypass the proxy server; the list must include:
- IP address of each cluster member server.
- Netbios name of each server.
- Netbios cluster name.
- *.contoso.com.
- Second IP address of the infrastructure pool.

To remove the proxy configuration, run the following commands as administrator on each server in the cluster:

[Environment]::SetEnvironmentVariable("HTTPS_PROXY", $null, "Machine") 
$env:HTTPS_PROXY = [System.Environment]::GetEnvironmentVariable("HTTPS_PROXY", "Machine")
[Environment]::SetEnvironmentVariable("HTTP_PROXY", $null, "Machine")  
$env:HTTP_PROXY = [System.Environment]::GetEnvironmentVariable("HTTP_PROXY", "Machine") 
$no_proxy = "" 
[Environment]::SetEnvironmentVariable("NO_PROXY", $no_proxy, "Machine") 
$env:NO_PROXY = [System.Environment]::GetEnvironmentVariable("NO_PROXY", "Machine")

# For the changes to take effect, restart the agent services after the proxy environment variable is removed. 
Restart-Service -Name himds, ExtensionService, GCArcService

For more information about proxy configuration for Azure Arc-enabled servers, see Managing and maintaining the Connected Machine agent.

Step 3: Configure proxy settings for Winhttp

You can configure proxy settings for Winhttp using the netsh command line utility.

Run the following command from the command prompt to manually configure the proxy server:

netsh winhttp set proxy Proxy_Server_Address:Proxy_Port bypass-list="localhost;127.0.0.1;.svc;node1;node2;scluster;192.168.0.2;192.168.0.3;*.contoso.com;192.168.0.10"

Run the following command from the command prompt to view or verify the current WinHTTP proxy server configuration:
```
netsh winhttp show proxy
```
Note that No_proxy specifies the list of host URLs that bypass the proxy server; the list must include:
- IP address of each cluster member server.
- Netbios name of each server.
- Netbios cluster name.
- *.contoso.com.
- Second IP address of the infrastructure pool.
  
  Note
  
  The use of "<local>" is not supported in the proxy bypass list.
Run the following command from the command prompt to remove the proxy server configuration for Winhttp:
```
netsh winhttp reset proxy
```

Next steps

For more information, see:

Firewall requirements for Azure Stack HCI.

After the proxy is configured, you can continue cluster deployment and: