Linux / Comando sftp: baixar, enviar e automatizar arquivos por SSH

sftp transfere e gerencia arquivos remotos por uma conexão criptografada SSH (Secure Shell). SFTP significa SSH File Transfer Protocol; para conectar, use sftp user@host, com verificação da chave do servidor e autenticação compatível com SSH.

sftp user@example.com

Instale o cliente OpenSSH se sftp não estiver disponível. As linhas marcadas como Bash são digitadas no terminal local; as linhas de texto com get, put e outros comandos são digitadas depois da conexão, no prompt SFTP. Digite bye para sair.

SFTP é diferente de FTP e de FTPS, a variante de FTP protegida por TLS (Transport Layer Security). O servidor precisa oferecer o subsistema SFTP, normalmente na mesma porta TCP usada pelo SSH. Nos exemplos, user, example.com e outros nomes de servidor são ilustrativos: substitua-os pela conta e pelo servidor autorizado que você utiliza.

Recursos do SFTP e preparação da conexão

O sftp do OpenSSH realiza transferências de arquivos por uma conexão SSH criptografada e pode usar recursos do SSH, como autenticação por chave pública, arquivos de configuração SSH e hosts de salto. As opções completas e comandos interativos podem ser encontrados no manual oficial do sftp do OpenSSH.

• Endereço do servidor e porta SSH
• Conta de usuário para login
• Senha ou chave privada SSH
• Canal confiável para confirmar a impressão digital da chave do servidor
• Permissões de leitura e escrita no diretório remoto

Compare a impressão digital da chave do host exibida ao conectar-se pela primeira vez com o valor recebido do administrador do servidor ou de uma interface de gerenciamento confiável. A impressão digital identifica a chave pública do servidor. Aprová-la sem conferir pode permitir uma conexão com o servidor errado ou uma interceptação por um intermediário.

Como conectar ao servidor

Conexão básica

sftp user@example.com

Uma vez conectado, o prompt sftp> aparecerá, permitindo que você insira comandos interativos. Este prompt é apenas para fins ilustrativos, e apenas os próprios comandos são exibidos nos exemplos de código abaixo.

Usar outra porta SSH

sftp -P 2222 user@example.com

A porta é definida com -P maiúsculo. A opção -p, minúscula, solicita a preservação dos horários de modificação e acesso e das permissões dos arquivos transferidos.

Especificar uma chave privada

sftp -i ~/.ssh/id_ed25519 user@example.com

Restrinja a leitura do arquivo de chave privada à sua conta. Proteja a chave com uma frase secreta (passphrase), distinta da senha da conta remota, e use um agente SSH quando apropriado. Não copie sua chave privada para servidores ou diretórios compartilhados.

Como distinguir caminhos locais e remotos

No modo interativo do SFTP, alguns comandos consultam ou alteram caminhos no servidor remoto; outros operam no computador local. Isso não significa que exista um shell remoto disponível para executar qualquer programa.

É um bom hábito verificar pwd e lpwd antes de começar o trabalho para evitar enviar arquivos para o local errado.

Como baixar arquivos

Os caminhos remotos são relativos ao diretório mostrado por pwd; os locais, ao mostrado por lpwd. Os exemplos pressupõem que reports/daily.csv existe no servidor e que a conta tem permissão para lê-lo. Confira também se o nome local já existe, pois uma transferência pode sobrescrevê-lo.

Baixar um arquivo

get reports/daily.csv

Sem um segundo caminho, o arquivo é salvo como daily.csv no diretório local atual. Antes do exemplo seguinte, prepare a pasta local download, por exemplo com lmkdir download se ela não existir. Ao terminar, confira o resultado com lls -l download/daily.csv.

Você pode especificar o caminho local de salvamento como o segundo argumento.

get reports/daily.csv ./download/daily.csv

Baixar vários arquivos e diretórios

get reports/*.csv
get -R reports

Curingas podem corresponder a nomes de arquivos remotos. Ao baixar diretórios de forma recursiva, o SFTP não segue links simbólicos dentro da árvore, e as opções disponíveis podem variar dependendo das versões do servidor e do cliente.

Retomar um download interrompido

reget archive.tar.zst

Ou você pode retomar transferências parciais com get -a. Isso pressupõe que o arquivo local parcial corresponda exatamente ao início do arquivo remoto, então se o arquivo remoto foi alterado, o resultado pode ficar corrompido. Para arquivos importantes, compare as somas de verificação (checksums) após a transferência.

Como enviar arquivos

Confirme com lls que os arquivos de origem existem no diretório local. Os exemplos usam o diretório remoto uploads, que precisa existir e permitir escrita; crie-o com mkdir uploads somente se isso fizer parte da sua tarefa e ele ainda não existir.

Enviar um arquivo

put ./release.tar.zst

Você pode especificar o caminho ou nome remoto como o segundo argumento.

put ./release.tar.zst uploads/release.tar.zst

Depois do envio, consulte ls -l uploads/release.tar.zst no SFTP e compare o tamanho com o arquivo local. O tamanho igual é uma verificação inicial, mas não substitui uma comparação de hash quando a integridade é importante.

Enviar um diretório recursivamente

put -R ./assets uploads/assets

Como arquivos existentes podem ser sobrescritos, verifique o caminho remoto primeiro. Se várias pessoas ou tarefas publicam no mesmo diretório, use um nome temporário exclusivo por execução e uma etapa de renomeação compatível com o servidor. Isso evita compartilhar o mesmo arquivo parcial entre transferências concorrentes.

Retomar um upload interrompido

reput ./large-image.img

put -a também tenta retomar uploads parciais. Se o arquivo parcial remoto não corresponder ao início do arquivo local, um arquivo corrompido pode ser criado, então confira se o arquivo mudou e confirme o hash após a conclusão.

Caminhos com espaços e caracteres especiais

Coloque caminhos com espaços entre aspas.

get "Monthly Reports/September Report.csv"
put "./Release Files/app package.tar.zst" uploads/

A interpretação de comandos interativos no SFTP não é exatamente a mesma que em um shell comum. Para nomes de arquivos que contenham curingas ou barras invertidas, primeiro verifique o nome exato na lista e, para automação, é mais seguro usar nomes de arquivos simples e previsíveis.

Como organizar conexões no arquivo SSH

Agrupar opções em uma entrada Host

Defina um apelido, usuário, porta e caminho da chave em ~/.ssh/config. O manual oficial de ssh_config descreve essas diretivas; o guia de SSH, em inglês, apresenta o uso geral da conexão.

Host fileserver
    HostName sftp.example.com
    User deploy
    Port 2222
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

sftp fileserver

Substitua sftp.example.com, deploy, a porta e a chave pelos seus valores. Não coloque senhas nem o conteúdo da chave privada nesse arquivo. Segundo as regras de SSH, as opções da linha de comando precedem a configuração do usuário, que precede a configuração do sistema; em geral, o primeiro valor obtido é usado. Coloque entradas específicas antes de padrões gerais, como Host *.

Conectar por um host de salto

sftp -J bastion.example.com user@internal.example.com

-J usa ProxyJump: um servidor intermediário encaminha a conexão até o destino. Verifique as chaves do host tanto do host de salto quanto do servidor alvo separadamente, e use o encaminhamento de agente apenas quando necessário.

Envio automático em modo de lote

Criar o arquivo de lote

Por exemplo, salve os seguintes comandos SFTP em upload.sftp.

Prepare o diretório remoto incoming com permissão de escrita e, no computador local, ./exports/report.csv. Execute a partir da pasta que contém exports e upload.sftp. No exemplo abaixo, os nomes report.tmp e report.csv devem estar livres no destino; em produção, use nomes temporários exclusivos e trate explicitamente um destino já existente.

cd incoming
lcd ./exports
put report.csv report.tmp
rename report.tmp report.csv
bye

Fazer upload com um nome temporário primeiro e depois renomeá-lo pode reduzir o risco de outros processos lerem um arquivo em andamento como se fosse um arquivo concluído. A renomeação atômica, que apresenta o nome final de uma só vez, depende do suporte do servidor e do sistema de arquivos; não é uma garantia de durabilidade nem de coordenação entre várias publicações.

Executar o arquivo de lote

sftp -b upload.sftp fileserver

O resultado esperado é report.csv em incoming, com o mesmo conteúdo do arquivo local, após a transferência e a renomeação concluírem. Se a execução falhar, examine o erro antes de repetir: o lote não é uma transação e operações anteriores podem ter sido aplicadas. Uma tentativa interrompida pode deixar report.tmp.

O modo em lote não deve depender da interação do usuário pedindo uma senha. Use uma conta dedicada restrita e autenticação por chave pública, e limite privilégios da chave, origens de acesso e caminhos permitidos de acordo com a política do servidor. Não coloque senhas em scripts ou linhas de comando.

Tratar falhas

No modo em lote, se comandos como get, put ou rename falharem, a operação geralmente para. Você pode ignorar falhas colocando um - antes do comando, mas use isso seletivamente, pois pode fazer a operação parecer bem-sucedida mesmo que arquivos necessários estejam ausentes.

Na automação, você deve verificar o status de saída do processo SFTP, o tamanho dos arquivos transferidos e os checksums, se possível, e estabelecer políticas de notificação e nova tentativa em caso de falha.

Verificações de segurança e operação

• Chave do servidor: Verifique a impressão digital através de um canal confiável durante conexões pela primeira vez e alterações de chave.
• Autenticação: Para automação, use uma chave pública de escopo limitado e uma conta dedicada em vez de senhas.
• Chave privada: Limite as permissões de leitura e não publique a chave em repositórios, pastas compartilhadas de backup ou servidores de destino.
• Permissões de caminho: Restrinja o acesso para que a conta de upload só possa alcançar os diretórios necessários.
• Sobrescrita: Verifique o caminho de destino e os arquivos existentes, e use nomes temporários e uma política de retenção de versões.
• Integridade: Para transferências importantes, gere e compare checksums confiáveis em ambos os lados.
• Registro: Registre o resultado e o destino das transferências sem registrar senhas, chaves privadas ou o conteúdo de arquivos sensíveis.

Comparação entre sftp, scp e rsync

A interface e o protocolo são aspectos diferentes: desde OpenSSH 9.0, scp usa SFTP por padrão. Mesmo assim, a interface de cópia de scp continua diferente do gerenciamento interativo de sftp.

Usar apenas o SSH não torna automaticamente seguras as permissões de conta e os procedimentos de implantação. Escolha com base no propósito da transmissão e no método de recuperação de falhas.

Perguntas frequentes

O SFTP é FTP com TLS aplicado?

Não. SFTP é o Protocolo de Transferência de Arquivos SSH e opera sobre uma conexão SSH. FTPS é um método separado que aplica TLS ao FTP, com diferentes configurações de servidor e estruturas de portas.

Por que aparece Connection refused (conexão recusada)?

O endereço ou a porta podem estar incorretos, o serviço SSH pode não estar em escuta ou um firewall pode rejeitar a conexão. Confira o endereço do servidor, a opção de porta -P em maiúscula, o estado do serviço SSH e as políticas de rede.

O que fazer se aparecer Permission denied (permissão negada)?

Distinga uma falha de autenticação de uma falta de permissão sobre arquivos após o login. Use sftp -v para consultar o diagnóstico da conexão, mas não exponha nomes de usuário, caminhos ou detalhes do servidor em logs públicos.

Como verifico se o upload está completo?

Verifique o status de saída e o tamanho dos arquivos remotos, e calcule e compare os checksums, como SHA-256, para arquivos importantes tanto nos sistemas locais quanto remotos. Se o servidor SFTP usar uma conta restrita que não permita a execução arbitrária de comandos, pode ser necessário um procedimento separado de verificação por API ou processamento no lado do servidor.

Uma soma de verificação é um resumo calculado do conteúdo. Em um terminal local com GNU Coreutils, sha256sum release.tar.zst calcula SHA-256; no servidor, a comparação exige um shell autorizado ou outro mecanismo fornecido pelo administrador. Não digite sha256sum como se fosse um comando SFTP padrão.

Resumo

Após conectar com sftp user@host, use get para download e put para upload. Distinguir pwd e lpwd, assim como cd e lcd, pode ajudar a reduzir erros com caminhos remotos e locais.

Na automação operacional, os pontos-chave são a autenticação por chave pública, a verificação da chave do host e a checagem do status de saída de lotes e da integridade dos arquivos. Não armazene senhas em scripts; limite o alcance da transferência com uma conta dedicada e privilégios mínimos.