如何在 Linux 設定 Chroot SFTP-only 帳號

在維護 Linux 伺服器時,我們常常需要為外部合作夥伴、客戶或特定團隊開設檔案上傳帳號。但基於資安考量,我們通常有兩大訴求:

  1. 只能傳檔案(SFTP-only):禁止透過 SSH 取得互動式 Shell 終端機權限。
  2. 囚禁在家目錄(Chroot Jail):只能存取自己的家目錄,看不到更不能存取系統其他層級(如 /etc、/var、其他人的 /home)。

過去的做法可能需要額外安裝 vsftpd、pure-ftpd 等獨立服務,或者在使用者家目錄複製一套極為繁瑣的 /bin 與動態函式庫(.so)。

事實上,現代 OpenSSH 內建的 internal-sftp 與 ChrootDirectory 機制,就能以最輕量、原生且安全的方式完美滿足這個需求。


步驟一:設定 OpenSSH Daemon

編輯 SSH 設定檔:

sudo vim /etc/ssh/sshd_config

提示:在現代 Linux 發行版中,也可以直接建立獨立設定檔 /etc/ssh/sshd_config.d/sftp.conf,避免日後套件升級時被覆蓋。

1. 確認啟用 internal-sftp

找到原先的 Subsystem sftp 設定,確認或修改為:

Subsystem sftp internal-sftp

internal-sftp 是 OpenSSH 內建的處理程式,與傳統外部的 /usr/lib/openssh/sftp-server 相比,它在 Chroot 環境下完全不需要任何額外的檔案系統支援或系統函式庫。

2. 加入 Match Group 規則

將以下區塊放在 sshd_config 的最尾端(注意:Match 條件後的規則會套用直到檔案結尾或下一個 Match,切勿放在全域設定之前):

# 針對 sftponly 群組的限制規則(必須放在設定檔最底部)
Match Group sftponly
	ChrootDirectory %h
	ForceCommand internal-sftp
	AllowTcpForwarding no
	X11Forwarding no
	AllowAgentForwarding no
  • Match Group sftponly:只要屬於 sftponly 群組的使用者即套用以下規則。
  • ChrootDirectory %h:將連線根目錄鎖定在該使用者的家目錄(%h 代表 home directory)。
  • ForceCommand internal-sftp:強制僅能執行 SFTP 子系統,禁止任何互動 Shell 命令。
  • AllowTcpForwarding no / X11Forwarding no / AllowAgentForwarding no:停用所有網路埠轉發、X11 轉發與代理轉發,徹底封鎖隧道通道。

步驟二:建立群組與 SFTP 使用者

1. 建立專用群組

sudo groupadd sftponly

2. 建立新使用者

建立一個禁止 Shell 登入、屬於 sftponly 群組的新使用者:

sudo useradd -g sftponly -d /home/{username} -s /usr/sbin/nologin -m {username}
sudo passwd {username}

若是現有使用者,可透過以下指令調整:

sudo usermod -g sftponly {username}
sudo usermod -s /usr/sbin/nologin {username}
sudo usermod -d /home/{username} {username}

註:部分較舊的系統可使用 -s /bin/false。


步驟三:權限配置(最關鍵的 Chroot 避坑點)

這是配置 Chroot SFTP 最常失敗的一步。

OpenSSH 的安全規範非常嚴格:

ChrootDirectory 所指定的目錄(以及其路徑上的所有父目錄),其擁有者必須是 root,且不可賦予群組或其他使用者寫入權限(權限最高只能為 755,絕對不能是 775 或 777)。

若目錄屬於一般使用者或權限過大,連線時會立刻斷線並出現 Write failed: Broken pipe 或 fatal: bad ownership or modes for chroot directory 錯誤。

請執行以下指令將權限修正:

# 家目錄的父目錄與本身必須屬於 root:root(或 root:sftponly)且為 755
sudo chown root:root /home/{username}
sudo chmod 755 /home/{username}

步驟四:建立可寫入的子目錄(Uploads)

因為 /home/{username} 屬於 root 且權限是 755,這意味著使用者登入後對自己的根目錄只有讀取權限,無法直接上傳任何檔案。

標準做法是在其家目錄下建立一個專門供上傳的子目錄:

# 建立上傳資料夾
sudo mkdir -p /home/{username}/uploads

# 將子目錄擁有者交給該使用者
sudo chown {username}:sftponly /home/{username}/uploads
sudo chmod 755 /home/{username}/uploads

這樣一來,使用者登入後會被限制在 /home/{username},且能將檔案自由上傳與寫入到 uploads/ 目錄中。


步驟五:測試設定並重新啟動 SSH

在重啟前,務必先測試 SSH 設定檔語法是否正確:

sudo sshd -t

若無任何輸出,表示語法正確。

接著使用 systemd 重啟 SSH 服務:

  • Ubuntu / Debian:
    sudo systemctl restart ssh
  • RHEL / CentOS / Alma / Rocky Linux:
    sudo systemctl restart sshd

步驟六:連線驗證

1. 測試 SFTP 上傳

在客戶端執行:

sftp {username}@{server_ip}

成功登入後,執行 pwd 會顯示根目錄 /(實際上是伺服器的 /home/{username})。 進入 uploads 資料夾,即可順利上傳與下載檔案:

sftp> cd uploads
sftp> put test.txt
Uploading test.txt to /uploads/test.txt
sftp> ls
test.txt

2. 測試 SSH Shell 阻擋

嘗試以 SSH 登入終端機:

ssh {username}@{server_ip}

系統應會顯示提示訊息並直接切斷連線:

This service allows sftp connections only.
Connection to server_ip closed.

這代表 Shell 阻擋已正確生效,伺服器安全無虞。


常見錯誤排查(Troubleshooting)

  • 錯誤訊息:Write failed: Broken pipe 或 Connection reset by peer
    • 原因:幾乎 99% 都是 Chroot 目錄擁有權不合規範。
    • 檢查:檢查 /home 與 /home/{username} 是否真的屬於 root,且權限沒有超過 755:
      ls -ld /home /home/{username}
      # 正確輸出應類似:drwxr-xr-x root root ...
  • 查看即時錯誤記錄:
    # Debian / Ubuntu
    sudo journalctl -u ssh -e
    # 或檢視傳統日誌
    sudo tail -f /var/log/auth.log