Configuração de proxy no terminal Linux e em CI: guia passo a passo para HTTP_PROXY, HTTPS_PROXY, NO_PROXY

Imagine: você abre o terminal, digita um comando de instalação de pacote e, como resposta, silêncio ou um erro de conexão. Muitas vezes, o motivo é que o acesso à rede passa apenas por um servidor proxy, e o sistema não sabe disso. Este guia vai te ensinar a configurar proxy em todos os lugares necessários no Linux e em CI.

Introdução: o que você vai conseguir e para quem é este guia

Ao final deste guia, você será capaz de configurar proxy no terminal Linux e em sistemas de integração contínua com confiança. Você entenderá como funcionam as variáveis de ambiente, como montar corretamente a URL do proxy e como fazer todos os principais instrumentos de desenvolvimento funcionarem através do proxy.

O que exatamente você vai conseguir:

• Uma configuração funcional de proxy na sessão atual do terminal.
• Uma configuração permanente que sobrevive a reinicializações.
• A configuração correta para apt, dnf, git, npm, pip, curl, wget, Docker.
• Pipelines de CI funcionando no GitHub Actions e GitLab Runner.
• Entender como verificar se o tráfego realmente está passando pelo proxy.
• Habilidades para armazenar a senha do proxy de forma segura.

Para quem é este guia: para administradores de sistemas iniciantes, desenvolvedores e engenheiros DevOps que trabalham em ambientes com proxy corporativo. Também há elementos para avançados: detalhes do systemd, ProxyCommand para SSH e mascaramento de segredos em CI.

O que você precisa saber de antemão: você deve saber abrir o terminal, digitar comandos e entender o que é um arquivo e uma pasta. Todo o resto é explicado ao longo do texto em linguagem simples.

Quanto tempo vai levar: a configuração básica leva cerca de 15 minutos. A conclusão completa do guia com configuração de todas as ferramentas e CI — aproximadamente 60-90 minutos. Não tenha pressa, é melhor fazer com calma.

Dica: mantenha este guia aberto em uma janela separada e execute os comandos um a um. Assim você não perderá nenhum passo importante.

Preparação inicial: endereço, porta, login e URL correta do proxy

Antes de configurar qualquer coisa, é preciso reunir os dados do seu servidor proxy. Sem eles, não é possível prosseguir.

Onde obter os dados do proxy

Geralmente, o proxy é fornecido por uma das seguintes partes:

• Administrador de sistemas da empresa — se você trabalha em uma rede corporativa. Peça a ele o endereço, a porta e os dados de autenticação.
• Serviço de aluguel de proxy — no painel de controle geralmente há um bloco com as configurações de acesso.
• Seu próprio servidor — se você montou o proxy por conta própria, você já sabe os dados.

Você precisa de quatro elementos: endereço (host), porta (port), login (username) e senha (password). Às vezes login e senha não são necessários — nesse caso, o proxy é sem autenticação.

Como montar a URL do proxy

O proxy é definido como uma única string — a URL. O formato geral é:

esquema://login:senha@endereco:porta

Vamos usar um exemplo. Suponha que o endereço do proxy seja proxy.exemplo.com, a porta 3128, o login ivan e a senha secret123. Então a URL ficaria assim:

http://ivan:secret123@proxy.exemplo.com:3128

Se não for necessária autenticação, a URL é mais simples:

http://proxy.exemplo.com:3128

Sobre o esquema: na maioria das vezes, o esquema http é usado mesmo para acessar sites HTTPS. Isso é normal — o esquema aqui indica o protocolo de comunicação com o próprio proxy, não com o site de destino. Às vezes existem proxies com esquema https ou socks5.

Por que caracteres especiais na senha devem ser codificados

Esta é uma das causas mais frequentes de erros misteriosos. Se a senha contiver caracteres especiais como @, :, /, #, ?, eles quebram a interpretação da URL. Por exemplo, o caractere @ separa os dados de autenticação do endereço. Se ele aparecer na senha, o sistema se confunde e não entende onde termina a senha e começa o endereço.

A solução é o percent-encoding (codificação percentual). Cada caractere problemático é substituído pelo sinal de porcentagem e seu código em hexadecimal.

Principais substituições:

• Caractere @ vira %40
• Caractere : vira %3A
• Caractere / vira %2F
• Caractere # vira %23
• Caractere ? vira %3F
• Caractere espaço vira %20
• Caractere % vira %25

Exemplo: se a senha é p@ss:word, na URL ela deve aparecer como p%40ss%3Aword. Então a URL completa será:

http://ivan:p%40ss%3Aword@proxy.exemplo.com:3128

Dica: para codificar a senha rapidamente, use o comando python3 -c "import urllib.parse, sys; print(urllib.parse.quote(sys.argv[1], safe=''))" 'sua_senha'. Ele retornará a string pronta para inserir na URL.

⚠️ Atenção: nunca digite a senha real diretamente na linha de comando em um computador compartilhado — ela vai parar no histórico. Falaremos sobre entrada segura separadamente no final do guia.

✅ Verificação: você deve ter em mãos uma ou mais URLs de proxy montadas, com todos os caracteres especiais na senha codificados. Anote-as em um local seguro, de preferência em um gerenciador de senhas.

Conceitos básicos: variáveis de ambiente, maiúsculas/minúsculas e formato do NO_PROXY

Para que a configuração não seja mágica, vamos entender três conceitos fundamentais. Isso leva cinco minutos, mas economiza horas de depuração.

O que são variáveis de ambiente

Variável de ambiente é um valor nomeado que o sistema operacional mantém na memória e passa para os programas em execução. Pense nisso como um bilhete que o sistema mostra para cada novo programa: aqui está o endereço do proxy, use-o.

Muitos utilitários de rede no Linux, ao serem iniciados, leem variáveis específicas e, se as encontrarem, direcionam automaticamente o tráfego pelo proxy. As mais importantes são:

• HTTP_PROXY — proxy para requisições HTTP não criptografadas.
• HTTPS_PROXY — proxy para requisições HTTPS criptografadas.
• NO_PROXY — lista de endereços que devem ser acessados diretamente, ignorando o proxy.
• FTP_PROXY — proxy para o protocolo FTP, atualmente raro.
• ALL_PROXY — proxy para todos os protocolos de uma vez, frequentemente usado para socks.

Diferença entre http_proxy e HTTP_PROXY quanto a maiúsculas/minúsculas

Este é um ponto sutil, mas importante. O Linux diferencia maiúsculas de minúsculas, então http_proxy e HTTP_PROXY são formalmente duas variáveis diferentes. Programas diferentes leem variantes diferentes.

Historicamente, ficou assim:

• O utilitário curl lê tanto a versão minúscula quanto a maiúscula, mas a versão minúscula http_proxy tem uma peculiaridade de segurança — a versão maiúscula HTTP_PROXY é ignorada pelo curl em ambientes CGI para evitar ataques.
• O utilitário wget tradicionalmente prefere nomes minúsculos.
• Muitos programas em diferentes linguagens leem as versões maiúsculas.

Conclusão prática: para não ter que adivinhar, defina ambas as versões — a minúscula e a maiúscula. Essa é a estratégia mais confiável, e é a que usaremos.

Formato do NO_PROXY e por que ele não entende CIDR

A variável NO_PROXY contém uma lista de endereços separados por vírgula que devem ser acessados diretamente. Isso é crítico para recursos internos: bancos de dados, serviços locais, metadados da nuvem.

Exemplo de valor correto:

localhost,127.0.0.1,.exemplo.com,.internal,169.254.169.254

Observe o ponto antes de exemplo.com. O ponto significa que todos os subdomínios se enquadram na regra: api.exemplo.com, git.exemplo.com e assim por diante.

⚠️ Atenção: o NO_PROXY, em geral, não entende notação CIDR nem máscaras de sub-rede. Uma entrada como 10.0.0.0/8 não funcionará na maioria das ferramentas. Algumas versões modernas de bibliotecas podem suportar, mas não se pode confiar. Liste endereços específicos e sufixos de domínio explicitamente.

Além disso, o NO_PROXY normalmente não suporta asteriscos como curinga universal. Não escreva *.exemplo.com — use o ponto no início: .exemplo.com.

Dica: sempre adicione ao NO_PROXY o endereço localhost e 127.0.0.1. Caso contrário, requisições locais passarão pelo proxy e provavelmente quebrarão.

✅ Verificação: você entende para que servem HTTP_PROXY, HTTPS_PROXY e NO_PROXY, sabe sobre a diferença de maiúsculas/minúsculas e lembra que o NO_PROXY não gosta de CIDR. Agora podemos partir para a prática.

Passo 1: ativar o proxy na sessão atual e testar com curl

Objetivo da etapa: aprender a ativar rapidamente o proxy no terminal aberto e verificar se ele funciona. Essas configurações duram apenas até o fechamento da janela do terminal — ideal para teste.

Definir variáveis com export

O comando export cria uma variável de ambiente na sessão atual. Execute os seguintes comandos, substituindo pela sua URL de proxy.

1. Abra o terminal.
2. Digite o comando para HTTP: export http_proxy="http://ivan:secret123@proxy.exemplo.com:3128"
3. Digite o comando para HTTPS: export https_proxy="http://ivan:secret123@proxy.exemplo.com:3128"
4. Duplique em maiúsculas: export HTTP_PROXY="$http_proxy"
5. E novamente: export HTTPS_PROXY="$https_proxy"
6. Defina as exceções: export no_proxy="localhost,127.0.0.1,.exemplo.com"
7. Duplique: export NO_PROXY="$no_proxy"

A construção "$http_proxy" insere o valor já definido da variável minúscula, para não precisar digitar a URL novamente.

Dica: observe que toda a URL está entre aspas duplas. Isso protege contra interpretação incorreta de caracteres especiais pelo seu shell bash.

Testar com curl

Agora vamos verificar se as variáveis estão sendo lidas. O utilitário curl é ótimo para isso.

1. Verifique se a variável está definida: echo $http_proxy — você deve ver a sua URL.
2. Faça uma requisição com saída detalhada: curl -v http://example.com
3. Na saída, procure a linha que menciona Connected to proxy.exemplo.com — isso significa que o curl passou pelo proxy.

Se a autenticação estiver correta e o proxy acessível, você receberá uma página HTML como resposta. Se vir erro 407, o problema está no login ou senha — volte para a seção sobre codificação de senha.

Dica: a flag -v (verbose) mostra detalhes da conexão. Essa é sua principal ferramenta para depuração de proxy. Sem ela, você não verá para onde a requisição está indo.

Para desativar o proxy na sessão atual, use o comando unset: unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY no_proxy NO_PROXY. Todas as variáveis desaparecerão.

✅ Verificação: o comando curl -v http://example.com mostra conexão através do seu servidor proxy e retorna o conteúdo da página. Se sim, o primeiro passo foi concluído com sucesso.

Passo 2: tornar a configuração permanente

Objetivo da etapa: fazer com que o proxy seja ativado automaticamente sempre que você fizer login no sistema e sobreviva a reinicializações. Aqui existem vários níveis; escolha o mais adequado.

Opção A: apenas para seu usuário, via ~/.bashrc

O arquivo ~/.bashrc é executado toda vez que você abre um terminal interativo como seu usuário. Esta é a opção mais segura — você não mexe nos outros usuários do sistema.

1. Abra o arquivo com um editor: nano ~/.bashrc
2. Role até o final do arquivo.
3. Adicione as mesmas linhas de export do Passo 1.
4. Salve o arquivo: pressione Ctrl+O, depois Enter, depois Ctrl+X para sair.
5. Aplique as alterações sem reinicializar: source ~/.bashrc

Dica: antes de editar, faça uma cópia de segurança com o comando cp ~/.bashrc ~/.bashrc.backup. Se algo der errado, você pode restaurar facilmente o original.

Opção B: para todo o sistema, via /etc/environment

O arquivo /etc/environment define variáveis para todos os usuários e funciona mesmo fora do bash. O formato aqui é especial: sem a palavra export, apenas NOME=valor.

1. Abra o arquivo com privilégios de administrador: sudo nano /etc/environment
2. Adicione linhas sem export, por exemplo: http_proxy="http://ivan:secret123@proxy.exemplo.com:3128"
3. Adicione de forma similar https_proxy, HTTP_PROXY, HTTPS_PROXY, no_proxy, NO_PROXY.
4. Salve e saia.
5. Para aplicar, faça logout e login novamente, ou reinicie.

Opção C: via /etc/profile.d

Uma forma mais flexível em nível de sistema é criar um script separado na pasta /etc/profile.d. Todos os arquivos .sh ali são executados no login.

1. Crie um arquivo: sudo nano /etc/profile.d/proxy.sh
2. Dentro, use os comandos export normais, como no Passo 1.
3. Salve o arquivo.
4. Torne-o executável: sudo chmod +x /etc/profile.d/proxy.sh

Esta opção é mais conveniente que /etc/environment porque suporta sintaxe completa do shell.

Opção D: para serviços do sistema, via systemd drop-in

Atenção, este é um detalhe importante. Serviços em segundo plano gerenciados pelo systemd não leem seu ~/.bashrc e muitas vezes ignoram /etc/environment. Para eles, é necessária uma abordagem separada — o arquivo drop-in.

Suponha que você precise que um serviço específico, por exemplo some-service, funcione através do proxy.

1. Crie o diretório e o arquivo drop-in com o comando: sudo systemctl edit some-service
2. Um editor será aberto. Insira o bloco de configurações.
3. Na seção [Service], adicione linhas como Environment="HTTP_PROXY=http://ivan:secret123@proxy.exemplo.com:3128"
4. Adicione linhas Environment semelhantes para HTTPS_PROXY e NO_PROXY.
5. Salve o arquivo.
6. Recarregue a configuração: sudo systemctl daemon-reload
7. Reinicie o serviço: sudo systemctl restart some-service

A diretiva Environment define a variável especificamente para aquele serviço. Esta é a única maneira correta para serviços do systemd.

⚠️ Atenção: em RHEL, CentOS, Fedora e AlmaLinux, os caminhos e ferramentas são os mesmos — o systemd funciona de forma idêntica. As diferenças aparecerão mais adiante, na seção sobre gerenciadores de pacotes.

✅ Verificação: abra um novo terminal (não aquele onde você fez export manualmente) e execute echo $http_proxy. Se você vir sua URL, a configuração permanente está funcionando.

Passo 3: configurar gerenciadores de pacotes e utilitários individualmente

Objetivo da etapa: muitas ferramentas não leem as variáveis de ambiente ou possuem seus próprios arquivos de configuração. Vamos configurar cada uma separadamente para que nada falhe.

apt no Ubuntu e Debian

O gerenciador de pacotes apt geralmente é executado via sudo e pode não enxergar suas variáveis. É mais seguro definir o proxy em seu próprio arquivo de configuração.

1. Crie um arquivo: sudo nano /etc/apt/apt.conf.d/95proxies
2. Adicione a linha: Acquire::http::Proxy "http://ivan:secret123@proxy.exemplo.com:3128";
3. Adicione a linha para HTTPS: Acquire::https::Proxy "http://ivan:secret123@proxy.exemplo.com:3128";
4. Salve o arquivo.
5. Teste: sudo apt update

Observe o ponto e vírgula no final de cada linha — é um elemento obrigatório na sintaxe do apt.

dnf e yum no RHEL, Fedora, AlmaLinux

Em sistemas da família RHEL, usamos dnf e yum no lugar do apt. O proxy é definido no arquivo de configuração principal.

1. Abra o arquivo: sudo nano /etc/dnf/dnf.conf (em sistemas antigos, /etc/yum.conf)
2. Na seção [main], adicione a linha: proxy=http://proxy.exemplo.com:3128
3. Se precisar de autenticação, adicione separadamente: proxy_username=ivan e proxy_password=secret123
4. Salve o arquivo.
5. Teste: sudo dnf makecache

No dnf, login e senha são mais convenientes como diretivas separadas, em vez de dentro da URL.

npm via .npmrc

1. Defina o proxy com o comando: npm config set proxy "http://ivan:secret123@proxy.exemplo.com:3128"
2. Defina para HTTPS: npm config set https-proxy "http://ivan:secret123@proxy.exemplo.com:3128"
3. As configurações serão salvas automaticamente no arquivo ~/.npmrc.
4. Verifique: npm config get proxy

pip via pip.conf

1. Crie o diretório: mkdir -p ~/.config/pip
2. Abra o arquivo: nano ~/.config/pip/pip.conf
3. Adicione a seção [global] e a linha proxy = http://ivan:secret123@proxy.exemplo.com:3128
4. Salve o arquivo.
5. Teste instalando qualquer pacote: pip install requests

Alternativamente, você pode especificar o proxy diretamente no comando: pip install requests --proxy http://proxy.exemplo.com:3128

git via http.proxy

1. Defina globalmente: git config --global http.proxy "http://ivan:secret123@proxy.exemplo.com:3128"
2. Se necessário, separadamente para HTTPS: git config --global https.proxy "http://ivan:secret123@proxy.exemplo.com:3128"
3. Verifique: git config --global --get http.proxy

Para remover a configuração: git config --global --unset http.proxy

git via SSH com ProxyCommand

Se você clona repositórios por SSH (endereço do tipo git@github.com), a configuração http.proxy não adianta — SSH é outro protocolo. Aqui é necessário o ProxyCommand.

1. Abra o arquivo: nano ~/.ssh/config
2. Adicione um bloco para o host desejado: linha Host github.com, depois, com indentação, a linha ProxyCommand nc -X connect -x proxy.exemplo.com:3128 %h %p
3. Salve o arquivo.
4. Instale o utilitário netcat, se não estiver presente: sudo apt install netcat-openbsd no Ubuntu, sudo dnf install nmap-ncat no RHEL.

Aqui, %h e %p são substituídos automaticamente pelo host e porta de destino. A flag -X connect indica ao netcat para usar um proxy HTTP.

curl via .curlrc

1. Abra o arquivo: nano ~/.curlrc
2. Adicione a linha: proxy = "http://ivan:secret123@proxy.exemplo.com:3128"
3. Salve o arquivo.

Agora, o curl usará o proxy sempre, mesmo sem as variáveis de ambiente.

wget via .wgetrc

1. Abra o arquivo: nano ~/.wgetrc
2. Adicione as linhas: http_proxy = http://proxy.exemplo.com:3128 e https_proxy = http://proxy.exemplo.com:3128
3. Adicione use_proxy = on
4. Salve o arquivo.

composer para PHP

O composer lê a variável de ambiente HTTP_PROXY, portanto, muitas vezes uma configuração separada não é necessária. Se quiser definir explicitamente, use a variável no momento da execução: HTTP_PROXY=http://proxy.exemplo.com:3128 composer install

Go e GOPROXY: um aviso importante

⚠️ Atenção: a variável GOPROXY NÃO é um servidor proxy no sentido que estamos tratando. Não se pode confundir. GOPROXY aponta para um espelho de módulos Go — um serviço de onde as bibliotecas são baixadas. É um endereço de repositório, não um proxy de rede.

Para que o Go acesse a internet através do seu proxy normal, use as variáveis HTTP_PROXY e HTTPS_PROXY padrão. E deixe GOPROXY com o valor padrão, a menos que haja uma tarefa específica de alterar o espelho de módulos.

Dica: lembre-se da regra: se o nome da variável contém a palavra PROXY, isso não significa necessariamente que ela se refere ao seu proxy de rede. GOPROXY, npm registry e similares são sobre fontes de pacotes.

✅ Verificação: execute uma operação de teste com cada ferramenta configurada: sudo apt update, npm install, git ls-remote, etc. Todas devem conseguir acessar a rede com sucesso.

Passo 4: configurar Docker e Kubernetes

Objetivo da etapa: Docker é um caso especial. Ele possui três locais diferentes para configuração de proxy, e confundi-los é um erro típico. Vamos examinar cada um.

Local 1: o daemon Docker via systemd drop-in

Essa configuração é necessária para que o próprio Docker possa baixar imagens do registro. O daemon Docker é gerenciado pelo systemd, portanto usaremos o mecanismo drop-in já conhecido.

1. Crie o diretório: sudo mkdir -p /etc/systemd/system/docker.service.d
2. Crie o arquivo: sudo nano /etc/systemd/system/docker.service.d/proxy.conf
3. Adicione a seção [Service].
4. Adicione a linha Environment="HTTP_PROXY=http://proxy.exemplo.com:3128"
5. Adicione linhas semelhantes para HTTPS_PROXY e NO_PROXY.
6. Recarregue a configuração: sudo systemctl daemon-reload
7. Reinicie o Docker: sudo systemctl restart docker

Para verificar, use: sudo systemctl show --property=Environment docker

Local 2: construção de imagem via build-arg

Ao construir uma imagem, os comandos dentro do Dockerfile (por exemplo, apt install) são executados em um ambiente isolado que não vê o proxy do host. É necessário passar o proxy explicitamente.

1. No Dockerfile, adicione as instruções ARG http_proxy e ARG https_proxy antes dos comandos RUN.
2. Construa a imagem passando os argumentos: docker build --build-arg http_proxy=http://proxy.exemplo.com:3128 --build-arg https_proxy=http://proxy.exemplo.com:3128 -t myimage .

⚠️ Atenção: não escreva a senha do proxy diretamente no Dockerfile com a instrução ENV. Ela permanecerá nas camadas da imagem, e qualquer pessoa que obtiver a imagem verá a senha. Use apenas build-arg, ou melhor, um proxy sem senha para a construção.

Local 3: contêineres em execução via ~/.docker/config.json

Para que os contêineres em execução recebam automaticamente as variáveis de proxy, configure o arquivo de configuração do cliente Docker.

1. Abra o arquivo: nano ~/.docker/config.json
2. Adicione o bloco proxies com a seção default.
3. Dentro, especifique httpProxy, httpsProxy e noProxy com seus valores.
4. Salve o arquivo.

Agora, sempre que você executar docker run, as variáveis serão automaticamente injetadas no contêiner.

Variáveis no manifesto do Kubernetes

No Kubernetes, o proxy é definido através de variáveis de ambiente na especificação do contêiner. Na seção env do manifesto do Pod ou Deployment, adicione itens com name HTTP_PROXY, HTTPS_PROXY, NO_PROXY e os respectivos value.

Dica: valores secretos no Kubernetes devem ser armazenados em objetos Secret e conectados via valueFrom, sem escrever a senha diretamente no manifesto. Assim, a senha não vai parar no sistema de controle de versão.

✅ Verificação: execute docker pull hello-world — a imagem deve ser baixada. Depois, docker run --rm alpine env | grep -i proxy — você verá as variáveis injetadas dentro do contêiner.

Passo 5: configurar proxy em CI — GitHub Actions e GitLab Runner

Objetivo da etapa: fazer com que os pipelines de CI funcionem através do proxy, armazenando o acesso de forma segura e sem expor a senha nos logs.

Armazenar o acesso em segredos

A regra principal em CI: nunca escreva a senha do proxy diretamente no arquivo YAML do pipeline. O arquivo fica no repositório e a senha será vista por todos. Use o mecanismo de segredos.

No GitHub Actions, os segredos são adicionados nas configurações do repositório, seção Settings, depois Secrets and variables, depois Actions. Crie um segredo com o nome PROXY_URL e cole a URL completa do proxy.

No GitLab, os segredos são chamados de CI/CD variables. Eles são adicionados em Settings, depois CI/CD, depois Variables. Certifique-se de marcar as opções Masked e Protected para valores sensíveis.

Configurar GitHub Actions

1. No arquivo do pipeline .github/workflows, adicione um bloco env no nível do job.
2. Defina HTTP_PROXY com o valor do segredo usando a sintaxe de chaves duplas com secrets.PROXY_URL.
3. Defina HTTPS_PROXY e NO_PROXY de forma similar.
4. Essas variáveis estarão disponíveis para todas as etapas do job.

Configurar GitLab Runner

No GitLab, existem dois níveis. Você pode definir variáveis no próprio arquivo .gitlab-ci.yml através do bloco variables, ou no nível do runner no arquivo de configuração config.toml, na seção environment.

1. Para o projeto: adicione no .gitlab-ci.yml um bloco variables com referências a variáveis protegidas.
2. Para todos os projetos do runner: abra o config.toml do runner e, na seção [[runners]], adicione o parâmetro environment com a lista de variáveis desejadas.

Mascarar a senha nos logs

Mesmo com segredos, a senha pode acidentalmente aparecer nos logs se algum comando a exibir. O GitHub Actions mascara automaticamente os valores dos segredos com asteriscos. No GitLab, isso é feito pela opção Masked — mas ela só funciona se o valor atender a certos requisitos (sem alguns caracteres especiais e com comprimento suficiente).

⚠️ Atenção: evite comandos com a flag -v ou echo que imprimam a URL completa do proxy nos logs. Mesmo com mascaramento, é melhor não arriscar. Para depuração, imprima apenas o endereço e a porta, sem login e senha.

Dica: armazene a URL do proxy sem a senha embutida, e mantenha login e senha como segredos separados. Assim, fica mais fácil mascarar e rotacionar.

✅ Verificação: execute o pipeline manualmente. A etapa que faz uma requisição de rede (por exemplo, instalação de dependências) deve ser concluída com sucesso. A senha não deve aparecer nos logs.

Verificação do resultado: garantir que o tráfego realmente passa pelo proxy

Não basta configurar — é preciso comprovar que o tráfego está realmente passando pelo proxy e não indo diretamente. Aqui está uma lista de verificação.

Lista de verificação: o que deve funcionar

• O comando echo $http_proxy em um novo terminal mostra sua URL.
• curl -v http://example.com mostra a linha Connected to proxy.
• sudo apt update atualiza as listas de pacotes com sucesso.
• git ls-remote para um repositório remoto funciona.
• docker pull baixa uma imagem.
• O pipeline de CI termina em verde.

Como testar de forma confiável

A maneira mais honesta é saber qual endereço IP externo o servidor de destino vê. Faça uma requisição a um serviço que mostre seu IP. Se estiver usando proxy, você verá o IP do servidor proxy, não o seu próprio.

1. Faça uma requisição sem proxy: env -u http_proxy -u https_proxy curl -s http://ifconfig.me — você verá seu IP real.
2. Faça com proxy: curl -s http://ifconfig.me — você verá o IP do proxy.
3. Se os dois endereços forem diferentes, o proxy está funcionando.

Outra forma é verificar os logs do próprio servidor proxy, se você tiver acesso a eles. Suas requisições devem aparecer lá.

Dica: o comando env -u remove temporariamente a variável apenas para um comando, sem afetar a sessão. É útil para comparar o comportamento com e sem proxy.

✅ Verificação: o IP com proxy é diferente do IP direto. Essa é a prova definitiva de que o tráfego está passando pelo proxy.

Erros típicos e suas soluções

Vamos analisar problemas comuns. Formato simples: problema, causa, solução.

Problema 1: sudo não herda as variáveis

Causa: o sudo, por padrão, limpa o ambiente por questões de segurança. Seus export não chegam ao comando executado com sudo.

Solução: use a flag -E para preservar o ambiente: sudo -E apt update. Ou configure a preservação permanente através do arquivo sudoers. Execute sudo visudo e adicione a linha Defaults env_keep += "http_proxy https_proxy HTTP_PROXY HTTPS_PROXY no_proxy NO_PROXY". Depois disso, o sudo sempre permitirá essas variáveis.

Problema 2: erros de certificado

Causa: alguns proxies corporativos interceptam HTTPS e substituem os certificados pelo seu próprio certificado raiz. O sistema não o conhece e reclama de conexão não confiável.

Solução: obtenha o certificado raiz do proxy com o administrador. No Ubuntu e Debian, copie-o para /usr/local/share/ca-certificates com extensão .crt e execute sudo update-ca-certificates. No RHEL, coloque em /etc/pki/ca-trust/source/anchors e execute sudo update-ca-trust. Depois disso, todas as ferramentas passarão a confiar no proxy.

Problema 3: curl funciona, apt não funciona

Causa: curl lê as variáveis de ambiente, mas o apt com sudo não as vê e não tem seu próprio arquivo de configuração de proxy.

Solução: configure o proxy em /etc/apt/apt.conf.d, conforme descrito no Passo 3. Essa é uma configuração separada das variáveis de ambiente e é exatamente a que o apt precisa.

Problema 4: senha com caracteres especiais

Causa: caracteres @, :, / na senha não codificada quebram a interpretação da URL.

Solução: aplique a codificação percentual da seção de Preparação. Substitua @ por %40, : por %3A e assim por diante.

Problema 5: erro 407 Proxy Authentication Required

Causa: login ou senha incorretos, ou o proxy exige autenticação e você não a forneceu.

Solução: verifique novamente o login e a senha. Certifique-se de que os dados de autenticação estão na URL. Verifique a codificação de caracteres especiais.

Problema 6: recursos internos inacessíveis

Causa: requisições para endereços locais e internos estão passando pelo proxy, que não os conhece.

Solução: adicione esses endereços ao NO_PROXY. Não se esqueça de localhost, 127.0.0.1 e domínios internos com ponto no início.

Problema 7: o daemon Docker não vê o proxy

Causa: você configurou as variáveis no bashrc, mas o daemon Docker é gerenciado pelo systemd e não as lê.

Solução: use o systemd drop-in do Passo 4, não se esqueça de daemon-reload e restart docker.

Problema 8: as configurações não foram aplicadas

Causa: você editou o bashrc, mas não reiniciou o terminal.

Solução: execute source ~/.bashrc ou abra uma nova janela de terminal.

Recursos adicionais e configurações avançadas

Quando a configuração básica estiver funcionando, você pode melhorar a conveniência e a flexibilidade.

Funções de ativar/desativar proxy

É útil criar no ~/.bashrc duas funções: proxy_on para ativar e proxy_off para desativar. Dentro de proxy_on, coloque os comandos export; dentro de proxy_off, os comandos unset. Assim, a alternância se torna um único comando.

Proxies diferentes para tarefas diferentes

Você pode definir um proxy apenas para um comando, sem alterar todo o ambiente. Exemplo: https_proxy=http://outro:3128 curl https://example.com. A variável vale apenas para esse comando.

Proxy SOCKS

Se você tem um proxy do tipo SOCKS5, use o esquema socks5 na URL e a variável ALL_PROXY. Para curl, existe a flag --socks5. Lembre-se de que nem todos os utilitários funcionam com SOCKS.

Dica: para ferramentas que simplesmente não suportam proxy, existem wrappers como proxychains. Mas use-os com consciência, pois eles alteram o comportamento das chamadas de rede do programa.

Tabela resumo de configurações

Mantenha este resumo à mão. Formato: ferramenta — arquivo de configuração — variável ou diretiva.

• Sessão shell — temporário na memória — export http_proxy e HTTP_PROXY.
• Usuário — ~/.bashrc — export das variáveis.
• Sistema todo — /etc/environment — http_proxy sem export.
• Sistema todo — /etc/profile.d/proxy.sh — export das variáveis.
• Serviço systemd — drop-in via systemctl edit — diretiva Environment.
• apt (Ubuntu, Debian) — /etc/apt/apt.conf.d/95proxies — Acquire::http::Proxy.
• dnf, yum (RHEL) — /etc/dnf/dnf.conf — proxy, proxy_username, proxy_password.
• npm — ~/.npmrc — proxy e https-proxy.
• pip — ~/.config/pip/pip.conf — proxy na seção global.
• git por HTTPS — config global do git — http.proxy.
• git por SSH — ~/.ssh/config — ProxyCommand.
• curl — ~/.curlrc — proxy.
• wget — ~/.wgetrc — http_proxy, https_proxy, use_proxy.
• composer — ambiente — HTTP_PROXY.
• Daemon Docker — /etc/systemd/system/docker.service.d/proxy.conf — Environment.
• Construção Docker — comando build — build-arg http_proxy.
• Contêineres Docker — ~/.docker/config.json — bloco proxies.
• Kubernetes — manifesto Pod — env com HTTP_PROXY.
• GitHub Actions — arquivo workflow — bloco env com secrets.
• GitLab — .gitlab-ci.yml ou config.toml — variables ou environment.

FAQ: perguntas frequentes sobre configuração de proxy

Preciso definir as variáveis tanto em minúsculas quanto em maiúsculas?

Sim, essa é a estratégia mais confiável. Programas diferentes leem maiúsculas ou minúsculas, portanto definir ambas elimina surpresas.

Por que o curl vê o proxy, mas o apt não?

Porque o apt com sudo não herda as variáveis de ambiente e tem seu próprio arquivo de configuração. Configure o apt separadamente através do arquivo em /etc/apt/apt.conf.d.

Como desativar temporariamente o proxy para um único comando?

Use env -u http_proxy -u https_proxy antes do comando. Isso remove as variáveis apenas para aquela execução.

Posso especificar uma sub-rede no NO_PROXY?

Em geral, não. O NO_PROXY não interpreta notação CIDR de forma confiável. Liste endereços específicos e sufixos de domínio com ponto no início.

GOPROXY é meu servidor proxy?

Não. GOPROXY aponta para um espelho de módulos Go, não para um proxy de rede. Para proxy de rede no Go, use HTTP_PROXY e HTTPS_PROXY.

Como armazenar a senha do proxy de forma segura?

Em CI, use segredos. Localmente, utilize o arquivo .netrc com permissões 600 ou um gerenciador de senhas. Evite que a senha apareça no histórico de comandos.

Por que o git via SSH não passa pelo http.proxy?

Porque SSH é um protocolo separado. Configure o ProxyCommand no arquivo ~/.ssh/config para o host desejado.

O que fazer em caso de erros de certificado através do proxy?

Instale o certificado raiz do proxy no repositório do sistema e atualize a confiança com o comando update-ca-certificates no Debian ou update-ca-trust no RHEL.

As configurações no bashrc não funcionam em uma nova sessão, por quê?

Possivelmente você editou o arquivo errado, não salvou as alterações ou não abriu um novo terminal. Verifique com echo e source.

Como verificar se o tráfego realmente está passando pelo proxy?

Compare o IP externo com e sem proxy usando o curl para um serviço de determinação de IP. Endereços diferentes confirmam o funcionamento do proxy.

Conclusão: o que você aprendeu e para onde ir a seguir

Parabéns, você percorreu um longo caminho. Vamos resumir o que você agora sabe fazer.

Você aprendeu a montar uma URL de proxy correta e a codificar caracteres especiais na senha. Entendeu as variáveis HTTP_PROXY, HTTPS_PROXY e NO_PROXY, incluindo as sutilezas de maiúsculas/minúsculas e formato das exceções. Você sabe ativar o proxy em uma sessão e tornar a configuração permanente de várias formas, incluindo systemd drop-in para serviços.

Você configurou proxy para todas as ferramentas principais: apt e dnf, npm e pip, git por HTTPS e SSH, curl e wget, composer, e também entendeu a importante diferença do GOPROXY. Você dominou os três locais de configuração do Docker e as variáveis no Kubernetes. Por fim, configurou proxy no GitHub Actions e GitLab com armazenamento seguro de segredos e mascaramento de senha.

O que fazer a seguir: consolide o conhecimento com a prática. Configure o proxy em uma máquina de teste do zero, seguindo o guia. Crie funções de alternância para conveniência. Estude os logs do seu servidor proxy para ver o tráfego com seus próprios olhos.

Para onde evoluir: o próximo passo é automatizar a configuração com ferramentas de gerenciamento de configuração como Ansible, para implantar o proxy em dezenas de máquinas com um único comando. Também é útil aprofundar o estudo sobre certificados e diferentes tipos de proxy.

Dica: salve a tabela resumo deste guia como uma cola. Ela economizará muito tempo quando você precisar se lembrar rapidamente de onde configurar o proxy para uma ferramenta específica.

Você se saiu muito bem. Agora, o proxy no terminal Linux e em CI não é mais mistério para você. Boas configurações e conexões estáveis.