Configuração de proxy no macOS

A configuração de proxy em nível de sistema no macOS direciona todo o tráfego de rede dos aplicativos que respeitam as configurações de proxy do sistema através de um servidor proxy especificado, normalmente gerenciado pelos Ajustes do Sistema ou pelo utilitário de linha de comando networksetup.

O macOS oferece um mecanismo centralizado de configuração de proxy que a maioria dos aplicativos — incluindo navegadores (Safari, Chrome, Firefox por padrão), ferramentas de linha de comando (curl, wget) e outros softwares que usam rede — adota automaticamente. Isso garante um comportamento de rede consistente em todo o sistema operacional, sem configuração por aplicativo.

Métodos de configuração

Existem dois métodos principais para configurar proxies em nível de sistema no macOS:

1. Interface gráfica (GUI): uso do aplicativo Ajustes do Sistema. Adequado para configurações interativas e pontuais.
2. Interface de linha de comando (CLI): uso do utilitário networksetup. Este método é preferível para scripts, automação ou administração remota.

Configuração pela GUI: Ajustes do Sistema

Para configurar o proxy pelos Ajustes do Sistema do macOS:

1. Abra os Ajustes do Sistema.
2. Vá até Rede na barra lateral.
3. Selecione na lista a interface de rede ativa (por exemplo, Wi-Fi, Ethernet).
4. Clique no botão Detalhes... da interface selecionada.
5. Na nova janela, selecione Proxies na barra lateral.

No painel Proxies há várias opções disponíveis:

• Configuração automática de proxy:

  • Descoberta automática de proxy: ativa a descoberta das configurações de proxy pelo protocolo Web Proxy Auto-Discovery (WPAD).
  • Configuração automática de proxy: especifica a URL de um arquivo Proxy Auto-Configuration (PAC).

• Configuração manual de proxy:

  • Proxy web (HTTP): configura um proxy HTTP para tráfego web não criptografado.
  • Proxy web seguro (HTTPS): configura um proxy HTTPS (SSL/TLS) para tráfego web criptografado.
  • Proxy FTP: configura um proxy para o File Transfer Protocol.
  • Proxy SOCKS: configura um proxy SOCKS, capaz de lidar com diversos tipos de tráfego de rede.
  • Proxy Gopher: (legado) configura um proxy para o protocolo Gopher.
  • Proxy de streaming (RTSP/RTSP): configura proxies para o Real-Time Streaming Protocol.

Para cada tipo de proxy manual:

• Servidor: informe o endereço IP ou o hostname do servidor proxy.
• Porta: informe o número da porta em que o servidor proxy escuta.
• O servidor proxy exige senha: marque esta opção se a autenticação for necessária. Informe o Usuário e a Senha.

Configurações de bypass do proxy

O campo "Ignorar ajustes de proxy para estes hosts e domínios" permite indicar destinos que não devem usar o proxy configurado. Informe hostnames, nomes de domínio ou endereços IP, separados por vírgulas. Curingas (*) são suportados para correspondência de domínios.

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

Configuração pela CLI: networksetup

O utilitário de linha de comando networksetup oferece controle completo sobre as configurações de rede, inclusive proxies. Ele opera sobre "serviços de rede", que correspondem às interfaces listadas nos Ajustes do Sistema (por exemplo, "Wi-Fi", "Ethernet").

Listar os serviços de rede

Antes de configurar, identifique o nome exato do seu serviço de rede:

networksetup -listallnetworkservices

Exemplo de saída:

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

Use o nome exatamente como aparece (por exemplo, "Wi-Fi").

Configurar proxy HTTP/HTTPS

Para definir um proxy web (HTTP) e um proxy web seguro (HTTPS) para um serviço:

# Define o proxy HTTP (endereço IP:porta)
networksetup -setwebproxy "Wi-Fi" 192.168.1.100 8080

# Define o proxy HTTPS (endereço IP:porta)
networksetup -setsecurewebproxy "Wi-Fi" 192.168.1.100 8080

Para incluir autenticação:

# Define o proxy HTTP com autenticação
networksetup -setwebproxy "Wi-Fi" 192.168.1.100 8080 username password

# Define o proxy HTTPS com autenticação
networksetup -setsecurewebproxy "Wi-Fi" 192.168.1.100 8080 username password

Observação: informar credenciais diretamente na linha de comando costuma ser inseguro, pois elas podem ficar gravadas no histórico do shell. Em scripts, considere alternativas como variáveis de ambiente ou o Keychain para credenciais sensíveis.

Configurar proxy SOCKS

Para definir um proxy SOCKS:

networksetup -setsocksfirewallproxy "Wi-Fi" 192.168.1.100 1080

Com autenticação (vale a mesma observação de segurança acima):

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

Desativar proxies

Para desativar proxies específicos:

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

Para desativar todos os proxies manuais de um serviço:

networksetup -setwebproxystate "Wi-Fi" off
networksetup -setsecurewebproxystate "Wi-Fi" off
networksetup -setftpproxystate "Wi-Fi" off
networksetup -setsocksfirewallproxystate "Wi-Fi" off
# ... e assim por diante para os demais tipos de proxy

Configurar a configuração automática de proxy (arquivo PAC)

Para especificar a URL de um arquivo PAC:

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

Para ativar a descoberta automática de proxy (WPAD):

networksetup -setautoproxydiscovery "Wi-Fi" on

Configurar domínios de bypass do proxy

Para configurar os domínios que ignoram o proxy:

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

Os argumentos após o nome do serviço são as entradas de bypass. Para limpar as entradas de bypass existentes:

networksetup -setproxybypassdomains "Wi-Fi" ""

Tipos de proxy explicados

| Tipo de proxy | Protocolo tratado | Descrição

Arquivos de configuração automática de proxy (PAC)

Um arquivo PAC é um arquivo JavaScript que define como navegadores e outros user agents escolhem o servidor proxy adequado para uma determinada URL. Isso dá flexibilidade, permitindo configurações de proxy diferentes conforme o host de destino, o domínio ou até o horário do dia.

Especificar um arquivo PAC

Como indicado nas seções de GUI e CLI, é possível especificar a URL de um arquivo PAC. O macOS baixa e usa esse script para determinar o uso do proxy.

Estrutura básica de um arquivo PAC

Um arquivo PAC precisa conter uma função chamada FindProxyForURL(url, host). Essa função retorna uma string indicando qual proxy usar.

function FindProxyForURL(url, host) {
    // Conexão direta para hosts internos
    if (isPlainHostName(host) ||
        shExpMatch(host, "*.local") ||
        isInNet(host, "192.168.1.0", "255.255.255.0")) {
        return "DIRECT";
    }

    // Usa um proxy específico para determinados domínios
    if (shExpMatch(host, "*.example.com")) {
        return "PROXY proxy.example.com:8080";
    }

    // Padrão: proxy principal para todo o restante do tráfego
    return "PROXY mainproxy.yourcompany.com:8080; DIRECT";
    // O fallback "DIRECT" é usado se o proxy estiver indisponível.
}

Funções PAC comuns:
* isPlainHostName(host): retorna true se o host não contiver pontos.
* dnsDomainIs(host, domain): retorna true se o host pertencer ao domínio indicado.
* shExpMatch(host, pattern): retorna true se o host corresponder ao padrão de expressão de shell.
* isInNet(host, pattern, mask): retorna true se o endereço IP do host estiver dentro da sub-rede indicada.
* myIpAddress(): retorna o endereço IP da máquina.
* dnsResolve(host): resolve um hostname DNS para um endereço IP.

Configurações de bypass do proxy

A configuração "Ignorar ajustes de proxy para estes hosts e domínios" permite indicar destinos cujo tráfego não deve passar pelo proxy configurado. Isso é essencial para acessar recursos internos diretamente, evitar sobrecarga desnecessária do proxy ou contornar incompatibilidades do proxy com serviços específicos.

Sintaxe das entradas:
* Hostnames: localhost, myinternalserver
* Nomes de domínio: *.local, example.com, sub.example.net
* * funciona como curinga. *.domain.com corresponde a host.domain.com e a sub.host.domain.com.
* Endereços IP: 192.168.1.10
* Sub-redes IP: 192.168.1.0/24, 10.0.0.0/8
* A notação CIDR é suportada.

Normalmente as entradas são separadas por vírgula na GUI ou passadas como argumentos separados para networksetup -setproxybypassdomains.

Verificação e diagnóstico

Verificar as configurações de proxy atuais

Para conferir pela CLI as configurações de proxy ativas de um serviço de rede:

# Obtém todas as informações de proxy de um serviço
networksetup -getwebproxy "Wi-Fi"
networksetup -getsecurewebproxy "Wi-Fi"
networksetup -getsocksfirewallproxy "Wi-Fi"
networksetup -getautoproxyurl "Wi-Fi"
networksetup -getautoproxydiscovery "Wi-Fi"
networksetup -getproxybypassdomains "Wi-Fi"

Problemas comuns

• IP/porta incorretos: confirme se o endereço e a porta do servidor proxy estão corretos.
• Falha de autenticação: verifique se o usuário e a senha estão corretos. Consulte os logs do servidor proxy para ver as tentativas de autenticação.
• Bloqueio de firewall: um firewall local no cliente macOS ou um firewall de rede entre o cliente e o servidor proxy pode estar bloqueando o tráfego na porta do proxy.
• Servidor proxy inacessível: o próprio servidor proxy pode estar fora do ar ou inacessível a partir do segmento de rede do cliente.
• Erros no arquivo PAC: ao usar um arquivo PAC, erros de sintaxe no JavaScript impedem seu funcionamento. Teste o arquivo PAC com um validador ou simplifique-o para isolar o problema. Garanta que a URL do PAC esteja acessível.
• Resolução de DNS: garanta que o cliente macOS consiga resolver o hostname do servidor proxy (se usado) e os hostnames externos.
• Sobrescrita por aplicativo: alguns aplicativos têm configurações próprias de proxy que se sobrepõem às do sistema. Verifique os ajustes específicos do aplicativo se o tráfego não estiver seguindo o caminho esperado.