From 0bd58775072f1d221b426161de30be2559c4f8f6 Mon Sep 17 00:00:00 2001 From: Chris Lu Date: Wed, 25 Feb 2026 14:14:49 -0800 Subject: [PATCH] Add SFTP Server documentation - Comprehensive SFTP server setup and configuration guide - Covers user management, SSH authentication, and JWT integration - Includes production setup, security considerations, and troubleshooting - Add SFTP-Server link to sidebar navigation --- SFTP-Server.md | 358 +++++++++++++++++++++++++++++++++++++++++++++++++ _Sidebar.md | 2 + 2 files changed, 360 insertions(+) create mode 100644 SFTP-Server.md diff --git a/SFTP-Server.md b/SFTP-Server.md new file mode 100644 index 0000000..e56cbd4 --- /dev/null +++ b/SFTP-Server.md @@ -0,0 +1,358 @@ +# SFTP Server + +SeaweedFS includes a built-in SFTP (SSH File Transfer Protocol) server that allows users to interact with the filer using standard SFTP clients. The SFTP server bridges between standard SSH/SFTP protocols and the SeaweedFS filer, enabling secure file operations over SSH. + +## Overview + +The SFTP server provides: +- **SSH/SFTP access** to your SeaweedFS filer +- **User authentication** via passwords or SSH public keys +- **JWT integration** for secure filer authentication +- **File operations** including upload, download, rename, delete, and directory management +- **Home directory enforcement** with chroot-like behavior for security +- **Keep-alive support** for long-running connections + +## Quick Start + +### Starting the SFTP Server (Standalone) + +```bash +weed sftp -filer=localhost:8888 -port=2022 -userStoreFile=/path/to/users.json +``` + +### Starting SFTP with Filer + +The SFTP server can run alongside the filer: + +```bash +weed filer -sftp.port=2022 -sftp.userStoreFile=/path/to/users.json +``` + +## Configuration + +### User Store File + +Create a JSON file containing user credentials. Example: `users.json` + +```json +[ + { + "Username": "alice", + "Password": "secure_password_here", + "HomeDir": "/home/alice", + "Uid": 1000, + "Gid": 1000 + }, + { + "Username": "bob", + "Password": "another_password", + "HomeDir": "/home/bob", + "Uid": 1001, + "Gid": 1001 + } +] +``` + +**Important Notes:** +- `HomeDir`: The user's root directory within the filer (e.g., `/home/alice` means the user sees that as their `/`) +- `Uid` and `Gid`: User and group IDs for file ownership (currently must be 0 for proper functioning) +- `Password`: Will be used for password-based authentication + +### Command-Line Options + +#### Common Options + +| Flag | Default | Description | +|------|---------|-------------| +| `-filer` | `localhost:8888` | Filer server address (ip:port) | +| `-port` | `2022` | SFTP server listen port | +| `-ip.bind` | `0.0.0.0` | IP address to bind to | +| `-userStoreFile` | (required) | Path to JSON file with user credentials | + +#### SSH Configuration + +| Flag | Default | Description | +|------|---------|-------------| +| `-sshPrivateKey` | (empty) | Path to SSH private key file for host authentication | +| `-hostKeysFolder` | (empty) | Path to folder with SSH private key files for multiple algorithms | +| `-authMethods` | `password,publickey` | Comma-separated auth methods: password, publickey, keyboard-interactive | +| `-maxAuthTries` | `6` | Maximum authentication attempts per connection | +| `-bannerMessage` | SeaweedFS default | Message displayed before authentication | +| `-loginGraceTime` | `2m` | Timeout for authentication | + +#### Connection Management + +| Flag | Default | Description | +|------|---------|-------------| +| `-clientAliveInterval` | `5s` | Interval for sending keep-alive messages | +| `-clientAliveCountMax` | `3` | Max missed keep-alives before disconnect | + +#### Cluster Options + +| Flag | Default | Description | +|------|---------|-------------| +| `-dataCenter` | (empty) | Prefer to read/write to volumes in this data center | +| `-localSocket` | `/tmp/seaweedfs-sftp-.sock` | Unix socket for local connections (Unix only) | + +### Complete Example + +```bash +weed sftp \ + -filer=filer.example.com:8888 \ + -port=2022 \ + -ip.bind=0.0.0.0 \ + -userStoreFile=/etc/seaweedfs/sftp-users.json \ + -sshPrivateKey=/etc/seaweedfs/ssh_host_key \ + -authMethods=password,publickey \ + -maxAuthTries=5 \ + -clientAliveInterval=60s \ + -clientAliveCountMax=5 \ + -dataCenter=dc1 +``` + +## JWT Authentication with Filer + +When your filer is configured with JWT authentication, the SFTP server automatically uses JWT tokens for secure communication. This is **automatically configured** - no additional settings needed! + +### Filer JWT Configuration + +Ensure your `security.toml` includes JWT settings for the filer: + +```toml +[jwt.filer_signing] +key = "your-filer-signing-secret-key" +expires_after_seconds = 10 + +[jwt.filer_signing.read] +key = "your-filer-signing-read-secret-key" +expires_after_seconds = 60 +``` + +The SFTP server will: +1. Automatically load these JWT keys from security configuration +2. Generate temporary JWT tokens for each file operation +3. Include tokens in requests to the filer +4. Work seamlessly without additional configuration + +This is **required** if your filer has JWT authentication enabled. Without it, file uploads will fail with "Failure" errors. + +### Troubleshooting JWT Issues + +If you see upload errors like "close remote: Failure": + +1. **Verify filer JWT is enabled:** Check `security.toml` has `jwt.filer_signing.key` set +2. **Check JWT keys match:** The SFTP server must use the same keys as the filer +3. **Verify SFTP has JWT config:** Ensure `security.toml` is loaded when SFTP starts +4. **Check logs:** Look for JWT-related errors in verbose logs (`-glog.v=4`) + +## Client Usage + +### Using SFTP Client + +```bash +sftp -P 2022 alice@localhost +``` + +### Common SFTP Commands + +```bash +# List directory +ls + +# Create directory +mkdir projects + +# Upload file +put local-file.txt + +# Download file +get remote-file.txt + +# Rename file +rename old-name.txt new-name.txt + +# Delete file +rm file.txt + +# Change directory +cd projects + +# Print working directory +pwd +``` + +### Using SSH/Fuse Mount + +Mount the SFTP server using SSHFS (macOS/Linux): + +```bash +mkdir ~/seaweedfs-mount +sshfs -P 2022 alice@localhost:/ ~/seaweedfs-mount +``` + +## File Operations + +### Permissions and Ownership + +- Files are created with ownership based on user Uid/Gid from the user store +- The filer maintains file permissions and ownership through gRPC calls +- Directory creation respects the user's home directory boundaries (chroot-like) + +### Home Directory + +Each user's home directory is configured in the user store: +- A user with `HomeDir: "/home/alice"` sees that as their root (`/`) +- Attempting to escape the home directory (e.g., `../..`) is blocked +- The home directory is automatically created if it doesn't exist + +### File Upload with JWT + +When a file is uploaded: +1. SFTP server generates a JWT token using the filer signing key +2. Token is included in the HTTP request to the filer +3. Filer validates the JWT before accepting the upload +4. File is stored in the filer with proper ownership + +## Production Setup + +### Host Keys + +For production, generate proper SSH host keys: + +```bash +# Generate RSA key +ssh-keygen -t rsa -N "" -f /etc/seaweedfs/ssh_host_key + +# Run SFTP server +weed sftp -port=2022 -sshPrivateKey=/etc/seaweedfs/ssh_host_key ... +``` + +Or use multiple keys with `-hostKeysFolder`: + +```bash +# Create keys folder +mkdir -p /etc/seaweedfs/ssh_keys + +# Generate keys for different algorithms +ssh-keygen -t rsa -N "" -f /etc/seaweedfs/ssh_keys/ssh_host_rsa_key +ssh-keygen -t ed25519 -N "" -f /etc/seaweedfs/ssh_keys/ssh_host_ed25519_key + +# Run SFTP server +weed sftp -port=2022 -hostKeysFolder=/etc/seaweedfs/ssh_keys ... +``` + +### Systemd Service + +Create `/etc/systemd/system/seaweedfs-sftp.service`: + +```ini +[Unit] +Description=SeaweedFS SFTP Server +After=network.target + +[Service] +Type=simple +User=seaweedfs +ExecStart=/usr/local/bin/weed sftp \ + -filer=filer.example.com:8888 \ + -port=2022 \ + -userStoreFile=/etc/seaweedfs/sftp-users.json \ + -sshPrivateKey=/etc/seaweedfs/ssh_host_key +Restart=on-failure +RestartSec=10 + +[Install] +WantedBy=multi-user.target +``` + +Enable and start: + +```bash +systemctl enable seaweedfs-sftp +systemctl start seaweedfs-sftp +systemctl status seaweedfs-sftp +``` + +## Security Considerations + +### User Management + +- Store user credentials securely in the user store file +- Restrict file permissions: `chmod 600 users.json` +- Use strong passwords or SSH keys +- Regularly rotate credentials + +### Network Security + +- Run SFTP on a non-standard port (not 22) +- Firewall SFTP port to trusted networks only +- Use SSH certificates for key-based auth in production +- Consider running behind a VPN or bastion host + +### Home Directory Isolation + +- Each user sees only their home directory +- Path traversal attempts are blocked +- Files outside user's home dir are inaccessible + +### JWT Security + +- Store JWT secrets securely in `security.toml` +- Use different keys for read and write operations +- Rotate JWT keys periodically +- Monitor JWT expiration settings to balance security and performance + +## Troubleshooting + +### Connection Refused + +``` +ssh: connect to host localhost port 2022: Connection refused +``` + +**Solution:** Ensure SFTP server is running and listening on the correct port: + +```bash +netstat -tlnp | grep 2022 +# or on macOS: +lsof -i :2022 +``` + +### Authentication Failed + +``` +Permission denied (password). +``` + +**Solution:** +1. Verify user exists in JSON file +2. Check password is correct +3. Ensure file format is valid JSON +4. Check user JSON again for syntax errors + +### Upload Failures + +``` +Uploading file.txt to /file.txt +close remote: Failure +``` + +**Solution (with JWT enabled):** +1. Verify JWT key is configured in `security.toml` +2. Check JWT key matches between SFTP and filer +3. Enable verbose logging: `-glog.v=4` +4. Check filer logs for JWT validation errors + +### Slow Connections + +Increase keep-alive timeout: + +```bash +weed sftp ... -clientAliveInterval=30s -clientAliveCountMax=10 +``` + +## See Also + +- [Filer-JWT-Use.md](Filer-JWT-Use.md) - Detailed JWT authentication guide +- [Security-Configuration.md](Security-Configuration.md) - Security configuration options +- [Filer-Commands-and-Operations.md](Filer-Commands-and-Operations.md) - Filer operations reference diff --git a/_Sidebar.md b/_Sidebar.md index 160c756..6c4a924 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -59,6 +59,8 @@ ### [[WebDAV]] +### [[SFTP Server]] + ### Cloud Drive * [[Cloud Drive Benefits]] * [[Cloud Drive Architecture]]