macOS Proxy Setup

System-level proxy configuration on macOS directs all network traffic from applications respecting system proxy settings through a specified proxy server, typically managed via System Settings or the networksetup command-line utility.

macOS provides a centralized mechanism for configuring proxy settings that most applications, including web browsers (Safari, Chrome, Firefox by default), command-line tools (curl, wget), and other network-aware software, will automatically adopt. This ensures consistent network behavior across the operating system without per-application configuration.

Methods of Configuration

There are two primary methods for configuring system-level proxies on macOS:

1. Graphical User Interface (GUI): Utilizing the System Settings application. This is suitable for interactive, one-time setups.
2. Command Line Interface (CLI): Employing the networksetup utility. This method is preferred for scripting, automation, or remote administration.

GUI Configuration: System Settings

To configure proxy settings via the macOS System Settings:

1. Open System Settings.
2. Navigate to Network in the sidebar.
3. Select the active network interface (e.g., Wi-Fi, Ethernet) from the list.
4. Click the Details... button for the selected interface.
5. In the new window, select Proxies from the sidebar.

Within the Proxies pane, several options are available:

• Automatic Proxy Configuration:

  • Auto Proxy Discovery: Enables discovery of proxy settings via Web Proxy Auto-Discovery Protocol (WPAD).
  • Automatic Proxy Configuration: Specifies a URL to a Proxy Auto-Configuration (PAC) file.

• Manual Proxy Configuration:

  • Web Proxy (HTTP): Configures an HTTP proxy for unencrypted web traffic.
  • Secure Web Proxy (HTTPS): Configures an HTTPS (SSL/TLS) proxy for encrypted web traffic.
  • FTP Proxy: Configures a proxy for File Transfer Protocol.
  • SOCKS Proxy: Configures a SOCKS proxy, which can handle various types of network traffic.
  • Gopher Proxy: (Legacy) Configures a proxy for the Gopher protocol.
  • Streaming Proxy (RTSP/RTSP): Configures proxies for Real-Time Streaming Protocol.

For each manual proxy type:

• Server: Enter the IP address or hostname of the proxy server.
• Port: Enter the port number the proxy server listens on.
• Proxy server requires password: Check this box if authentication is required. Enter the Username and Password.

Proxy Bypass Settings

The "Bypass proxy settings for these Hosts & Domains" field allows specifying destinations that should not use the configured proxy. Enter hostnames, domain names, or IP addresses, separated by commas. Wildcards (*) are supported for domain matching.

Example:
*.local, 192.168.1.0/24, localhost, 127.0.0.1

CLI Configuration: networksetup

The networksetup command-line utility provides comprehensive control over network settings, including proxies. It operates on "network services" which correspond to the interfaces listed in System Settings (e.g., "Wi-Fi", "Ethernet").

Listing Network Services

Before configuring, identify the exact name of your network service:

networksetup -listallnetworkservices

Output example:

An asterisk (*) denotes that a network service is disabled.
Wi-Fi
Ethernet
Bluetooth PAN
Thunderbolt Bridge

Use the name exactly as it appears (e.g., "Wi-Fi").

Setting HTTP/HTTPS Proxy

To set a Web Proxy (HTTP) and Secure Web Proxy (HTTPS) for a service:

# Set HTTP proxy (IP address:port)
networksetup -setwebproxy "Wi-Fi" 192.168.1.100 8080

# Set HTTPS proxy (IP address:port)
networksetup -setsecurewebproxy "Wi-Fi" 192.168.1.100 8080

To include authentication:

# Set HTTP proxy with authentication
networksetup -setwebproxy "Wi-Fi" 192.168.1.100 8080 username password

# Set HTTPS proxy with authentication
networksetup -setsecurewebproxy "Wi-Fi" 192.168.1.100 8080 username password

Note: Providing credentials directly on the command line is generally insecure as they may be stored in shell history. Consider alternative methods like environment variables or Keychain for sensitive credentials in scripts.

Setting SOCKS Proxy

To set a SOCKS proxy:

networksetup -setsocksfirewallproxy "Wi-Fi" 192.168.1.100 1080

With authentication (similar security note as above):

networksetup -setsocksfirewallproxy "Wi-Fi" 192.168.1.100 1080 username password

Disabling Proxies

To disable specific proxies:

networksetup -setwebproxystate "Wi-Fi" off
networksetup -setsecurewebproxystate "Wi-Fi" off
networksetup -setsocksfirewallproxystate "Wi-Fi" off

To disable all manual proxies for a service:

networksetup -setwebproxystate "Wi-Fi" off
networksetup -setsecurewebproxystate "Wi-Fi" off
networksetup -setftpproxystate "Wi-Fi" off
networksetup -setsocksfirewallproxystate "Wi-Fi" off
# ... and so on for other proxy types

Setting Automatic Proxy Configuration (PAC File)

To specify a PAC file URL:

networksetup -setautoproxyurl "Wi-Fi" http://proxy.example.com/proxy.pac

To enable Auto Proxy Discovery (WPAD):

networksetup -setautoproxydiscovery "Wi-Fi" on

Setting Proxy Bypass Domains

To configure domains that bypass the proxy:

networksetup -setproxybypassdomains "Wi-Fi" "*.local" "192.168.1.0/24" "localhost"

The arguments after the service name are the bypass entries. To clear existing bypass entries:

networksetup -setproxybypassdomains "Wi-Fi" ""

Proxy Types Explained

| Proxy Type | Protocol Handled | Description

Proxy Auto-Configuration (PAC) Files

A PAC file is a JavaScript file that defines how web browsers and other user agents can choose the appropriate proxy server for a given URL. This offers flexibility, allowing different proxy configurations based on the destination host, domain, or even the time of day.

Specifying a PAC File

As noted in the GUI and CLI sections, you can specify a PAC file URL. macOS will download and use this script to determine proxy usage.

Basic PAC File Structure

A PAC file must contain a function named FindProxyForURL(url, host). This function returns a string indicating the proxy to use.

function FindProxyForURL(url, host) {
    // Direct connection for internal hosts
    if (isPlainHostName(host) ||
        shExpMatch(host, "*.local") ||
        isInNet(host, "192.168.1.0", "255.255.255.0")) {
        return "DIRECT";
    }

    // Use a specific proxy for certain domains
    if (shExpMatch(host, "*.example.com")) {
        return "PROXY proxy.example.com:8080";
    }

    // Default to a main proxy for all other traffic
    return "PROXY mainproxy.yourcompany.com:8080; DIRECT";
    // The "DIRECT" fallback is used if the proxy is unavailable.
}

Common PAC functions:
* isPlainHostName(host): Returns true if the host contains no dots.
* dnsDomainIs(host, domain): Returns true if the host is within the specified domain.
* shExpMatch(host, pattern): Returns true if the host matches the shell expression pattern.
* isInNet(host, pattern, mask): Returns true if the IP address of the host is within the specified subnet.
* myIpAddress(): Returns the IP address of the machine.
* dnsResolve(host): Resolves a DNS hostname to an IP address.

Bypass Proxy Settings

The "Bypass proxy settings for these Hosts & Domains" configuration allows specifying destinations that should not route traffic through the configured proxy. This is crucial for accessing internal resources directly, preventing unnecessary proxy overhead, or resolving issues with proxy incompatibility for specific services.

Syntax for entries:
* Hostnames: localhost, myinternalserver
* Domain Names: *.local, example.com, sub.example.net
* * acts as a wildcard. *.domain.com matches host.domain.com and sub.host.domain.com.
* IP Addresses: 192.168.1.10
* IP Subnets: 192.168.1.0/24, 10.0.0.0/8
* CIDR notation is supported.

Entries are typically comma-separated in the GUI or provided as separate arguments to networksetup -setproxybypassdomains.

Verifying and Troubleshooting

Checking Current Proxy Settings

To verify the currently active proxy settings for a network service using the CLI:

# Get all proxy information for a service
networksetup -getwebproxy "Wi-Fi"
networksetup -getsecurewebproxy "Wi-Fi"
networksetup -getsocksfirewallproxy "Wi-Fi"
networksetup -getautoproxyurl "Wi-Fi"
networksetup -getautoproxydiscovery "Wi-Fi"
networksetup -getproxybypassdomains "Wi-Fi"

Common Issues

• Incorrect IP/Port: Verify the proxy server address and port are accurate.
• Authentication Failure: Ensure the username and password are correct. Check proxy server logs for authentication attempts.
• Firewall Blocks: A local firewall on the macOS client or a network firewall between the client and the proxy server may be blocking traffic on the proxy port.
• Proxy Server Unreachable: The proxy server itself might be down or inaccessible from the client's network segment.
• PAC File Errors: If using a PAC file, syntax errors within the JavaScript can prevent it from working. Test the PAC file with a validator or simplify it to isolate issues. Ensure the PAC file URL is reachable.
• DNS Resolution: Ensure the macOS client can resolve the proxy server's hostname (if used) and external hostnames.
• Application-Specific Overrides: Some applications may have their own proxy settings that override system-level configurations. Verify the application's specific settings if traffic is not routing as expected.