Linux / 명령어 / sftp - SSH로 안전하게 파일 전송

sftp는 SSH(Secure Shell) 연결 위에서 파일을 전송하고 원격 파일을 관리하는 프로그램입니다. 기본 접속 형식은 sftp 사용자@호스트이며, SSH 호스트 키 검증과 공개 키 인증을 그대로 활용할 수 있습니다.

sftp user@example.com

SFTP는 이름이 비슷한 FTP 또는 FTPS와 다른 프로토콜입니다. 서버에서 SSH의 SFTP 서브시스템이 활성화되어 있어야 하며, 일반적으로 SSH와 같은 TCP 포트를 사용합니다.

SFTP의 특징과 접속 전 확인 사항

OpenSSH의 sftp는 파일 전송을 암호화된 SSH 연결로 수행하고, 공개 키 인증, SSH 설정 파일, 점프 호스트 같은 SSH 기능을 사용할 수 있습니다. 전체 옵션과 대화형 명령은 OpenSSH sftp 공식 매뉴얼에서 확인할 수 있습니다.

• 서버 주소와 SSH 포트
• 로그인할 사용자 계정
• 비밀번호 또는 SSH 개인 키
• 서버 호스트 키 지문을 확인할 신뢰할 수 있는 경로
• 원격 디렉터리에 대한 읽기·쓰기 권한

처음 연결할 때 표시되는 호스트 키 지문은 서버 관리자나 신뢰할 수 있는 관리 화면에서 받은 값과 비교하세요. 확인하지 않고 승인하면 중간자 공격이나 잘못된 서버 접속을 놓칠 수 있습니다.

서버에 접속하는 방법

기본 접속

sftp user@example.com

연결되면 sftp> 프롬프트가 나타나고 대화형 명령을 입력할 수 있습니다. 이 프롬프트는 설명을 위한 것이며 아래 코드 예제에는 명령 자체만 표시합니다.

다른 SSH 포트 사용하기

sftp -P 2222 user@example.com

SFTP의 포트 옵션은 대문자 -P입니다. 소문자 -p는 전송 파일의 수정 시각, 접근 시각과 권한을 보존하도록 요청하는 다른 옵션이므로 혼동하지 마세요.

개인 키 지정하기

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

개인 키 파일은 다른 사용자가 읽을 수 없도록 권한을 제한하고, 가능하면 암호문(passphrase)을 설정해 SSH 에이전트와 함께 사용하세요. 개인 키를 서버나 공유 디렉터리에 복사하지 않습니다.

로컬 경로와 원격 경로 구분하기

SFTP 대화형 모드에는 원격 서버에서 실행되는 명령과 로컬 컴퓨터에서 실행되는 명령이 따로 있습니다.

파일을 잘못된 위치에 전송하지 않도록 작업 전 pwd와 lpwd를 확인하는 습관이 좋습니다.

파일 내려받기

파일 하나 다운로드하기

get reports/daily.csv

로컬 저장 경로를 두 번째 인수로 지정할 수 있습니다.

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

여러 파일과 디렉터리 다운로드하기

get reports/*.csv
get -R reports

와일드카드는 원격 파일명과 일치할 수 있습니다. 디렉터리를 재귀적으로 내려받을 때 SFTP는 트리 안의 심볼릭 링크를 따라가지 않으며, 서버와 클라이언트 버전에 따라 지원 옵션이 다를 수 있습니다.

중단된 다운로드 이어받기

reget archive.tar.zst

또는 get -a로 부분 전송을 이어받을 수 있습니다. 로컬의 부분 파일이 원격 파일의 앞부분과 정확히 같다는 전제이므로 원격 파일이 변경됐다면 결과가 손상될 수 있습니다. 중요한 파일은 전송 후 체크섬을 비교하세요.

파일 올리기

파일 하나 업로드하기

put ./release.tar.zst

원격 저장 경로나 이름을 두 번째 인수로 지정할 수 있습니다.

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

디렉터리 재귀 업로드하기

put -R ./assets uploads/assets

기존 파일을 덮어쓸 수 있으므로 원격 경로를 먼저 확인하세요. 여러 사용자가 동시에 배포하는 디렉터리라면 임시 이름으로 올린 뒤 서버가 지원하는 원자적 이름 변경 절차를 사용하는 편이 안전합니다.

중단된 업로드 이어 보내기

reput ./large-image.img

put -a도 부분 업로드 재개를 시도합니다. 원격의 부분 파일이 로컬 파일의 앞부분과 일치하지 않으면 손상된 파일이 만들어질 수 있으므로 변경 여부를 확인하고 완료 후 해시를 검증하세요.

경로, 공백과 파일명 다루기

공백이 있는 경로는 따옴표로 감쌉니다.

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

SFTP의 대화형 명령 해석은 일반 셸과 완전히 같지 않습니다. 와일드카드나 백슬래시가 포함된 파일명은 먼저 목록에서 정확한 이름을 확인하고, 자동화에서는 단순하고 예측 가능한 파일명을 사용하는 편이 안전합니다.

SSH 설정 파일로 접속 정보 관리하기

반복 옵션을 Host 항목으로 묶기

~/.ssh/config에 별칭, 사용자, 포트와 키 경로를 적으면 짧게 접속할 수 있습니다.

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

sftp fileserver

설정 파일에는 비밀번호나 개인 키 내용 자체를 넣지 않습니다. 파일 권한을 제한하고 시스템 전체 설정과 사용자 설정의 우선순위를 확인하세요.

점프 호스트를 통해 접속하기

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

-J는 SSH의 ProxyJump 기능을 사용합니다. 점프 호스트와 대상 서버 양쪽의 호스트 키를 각각 검증하고, 에이전트 전달은 꼭 필요한 경우에만 사용하세요.

배치 모드로 자동 전송하기

배치 파일 작성하기

예를 들어 upload.sftp에 다음과 같은 SFTP 명령을 저장합니다.

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

임시 이름으로 업로드한 뒤 이름을 바꾸면 다른 프로세스가 전송 중인 파일을 완성본으로 읽는 위험을 줄일 수 있습니다. 원자성은 서버 파일시스템과 동일 파일시스템 내 이름 변경 여부에 따라 달라집니다.

배치 파일 실행하기

sftp -b upload.sftp fileserver

배치 모드는 사용자에게 비밀번호를 묻는 상호작용에 의존하지 않아야 합니다. 제한된 전용 계정과 공개 키 인증을 사용하고, 키 권한·접속 원본·허용 경로를 서버 정책으로 제한하세요. 스크립트나 명령행에 비밀번호를 넣지 않습니다.

실패 처리 이해하기

배치 모드는 get, put, rename 등 주요 명령이 실패하면 일반적으로 중단됩니다. 명령 앞의 -로 실패를 무시할 수 있지만, 필요한 파일이 누락된 채 작업이 성공한 것처럼 보일 수 있으므로 선택적으로만 사용하세요.

자동화에서는 SFTP 프로세스의 종료 상태, 전송된 파일 크기와 가능하면 체크섬까지 확인하고 실패 시 알림과 재시도 정책을 마련해야 합니다.

보안과 운영 점검 목록

• 호스트 키: 최초 접속과 키 변경 시 신뢰할 수 있는 경로로 지문을 검증합니다.
• 인증: 자동화에는 비밀번호 대신 범위가 제한된 공개 키와 전용 계정을 사용합니다.
• 개인 키: 읽기 권한을 최소화하고 저장소, 백업 공유 폴더나 서버에 업로드하지 않습니다.
• 경로 권한: 업로드 계정이 필요한 디렉터리에만 접근하도록 제한합니다.
• 덮어쓰기: 대상 경로와 기존 파일을 확인하고 임시 이름과 버전 보관 정책을 사용합니다.
• 무결성: 중요한 전송은 양쪽에서 신뢰할 수 있는 체크섬을 생성해 비교합니다.
• 로그: 전송 성공·실패와 대상은 기록하되 비밀번호, 개인 키, 민감한 파일 내용은 남기지 않습니다.

SFTP, SCP, rsync 비교

어떤 도구든 SSH를 사용한다는 이유만으로 계정 권한과 배포 절차가 자동으로 안전해지는 것은 아닙니다. 전송 목적과 실패 복구 방식에 맞춰 선택하세요.

자주 묻는 질문

SFTP는 FTP에 TLS를 적용한 것인가요?

아닙니다. SFTP는 SSH File Transfer Protocol이며 SSH 연결 위에서 동작합니다. FTPS는 FTP에 TLS를 적용한 별도의 방식으로 서버 설정과 포트 구조가 다릅니다.

Connection refused 오류가 발생하는 이유는 무엇인가요?

주소나 포트가 틀렸거나 SSH 서비스가 수신하지 않거나 방화벽이 연결을 거부할 수 있습니다. 서버 주소, 대문자 -P 포트, SSH 서비스 상태와 네트워크 정책을 확인하세요.

Permission denied가 나오면 어떻게 하나요?

인증 자체가 실패한 것인지 로그인 후 파일 권한이 부족한 것인지 구분해야 합니다. sftp -v로 접속 진단 정보를 확인하되 공개 로그에 사용자명, 경로와 서버 정보를 그대로 공유하지 마세요.

업로드가 완료됐는지 어떻게 검증하나요?

종료 상태와 원격 파일 크기를 확인하고, 중요한 파일은 로컬과 원격에서 SHA-256 같은 체크섬을 계산해 비교하세요. SFTP 서버가 임의 명령 실행을 허용하지 않는 제한 계정이라면 별도의 검증 API나 서버 측 처리 절차가 필요할 수 있습니다.

정리

sftp 사용자@호스트로 접속한 뒤 get은 다운로드, put은 업로드에 사용합니다. pwd와 lpwd, cd와 lcd를 구분하면 원격과 로컬 경로 실수를 줄일 수 있습니다.

운영 자동화에서는 공개 키 인증, 호스트 키 검증, 배치 종료 상태와 파일 무결성 확인이 핵심입니다. 비밀번호를 스크립트에 저장하지 말고, 전용 계정과 최소 권한으로 전송 범위를 제한하세요.