Installation

sftproo can be deployed using Docker, which is the recommended method for most users. This guide will walk you through the installation process.

Prerequisites

• Docker and Docker Compose installed on your server
• A server with at least 2GB RAM and 10GB storage
• Ports 2222 (SFTP) and 8443 (Web UI) available
• A valid domain name (optional, but recommended for SSL)

Quick Start with Docker Compose

1. Create a directory for sftproo:

mkdir /opt/sftproo
cd /opt/sftproo

2. Create a docker-compose.yml file:

version: '3.8'

services:
  sftproo:
    image: sftproo/sftproo:latest
    container_name: sftproo
    ports:
      - "2222:2222"  # SFTP port
      - "8443:8443"  # Web UI port
    volumes:
      - ./data:/data
      - ./config:/config
      - ./backups:/backups
    environment:
      - SFTPROO_DB_HOST=mariadb
      - SFTPROO_DB_NAME=sftproo
      - SFTPROO_DB_USER=sftproo
      - SFTPROO_DB_PASSWORD=changeme
      - SFTPROO_SESSION_SECRET=changemetosomethingrandom
    depends_on:
      - mariadb
    restart: unless-stopped

  mariadb:
    image: mariadb:10.11
    container_name: sftproo-db
    environment:
      - MYSQL_ROOT_PASSWORD=rootpassword
      - MYSQL_DATABASE=sftproo
      - MYSQL_USER=sftproo
      - MYSQL_PASSWORD=changeme
    volumes:
      - ./database:/var/lib/mysql
    restart: unless-stopped

3. Start the services:

docker-compose up -d

4. Access the web interface at https://your-server:8443

AWS Marketplace Deployment

sftproo is available as a pre-configured AMI in the AWS Marketplace:

1. Search for "sftproo" in the AWS Marketplace
2. Select your instance type (t3.small or larger recommended)
3. Configure security groups to allow ports 22, 2222, and 8443
4. Launch the instance
5. Connect via SSH and run sudo sftproo-setup to complete configuration

Azure Marketplace Deployment

Deploy sftproo from the Azure Marketplace:

1. Search for "sftproo" in the Azure Marketplace
2. Choose your VM size (B2s or larger recommended)
3. Configure network security rules for ports 22, 2222, and 8443
4. Deploy the VM
5. SSH into the VM and run sudo sftproo-setup

Configuration

Initial Setup

After installation, access the web interface and log in with the default credentials:

• Username: admin
• Password: changeme

Environment Variables

sftproo can be configured using environment variables:

SSL/TLS Configuration

sftproo uses self-signed certificates by default. For production, you should use proper SSL certificates:

Option 1: Let's Encrypt (Recommended)

# Using Traefik (included in docker-compose)
services:
  traefik:
    image: traefik:v2.10
    command:
      - "--certificatesresolvers.letsencrypt.acme.email=your@email.com"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
      - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
    labels:
      - "traefik.http.routers.sftproo.tls.certresolver=letsencrypt"

Option 2: Custom Certificates

# Mount your certificates
volumes:
  - ./certs/server.crt:/config/sftproo-server.crt
  - ./certs/server.key:/config/sftproo-server.pem

Storage Configuration

By default, sftproo stores files locally. For cloud storage, configure S3:

SFTPROO_STORAGE_TYPE=s3
SFTPROO_S3_BUCKET=your-bucket-name
SFTPROO_S3_REGION=us-east-1
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key

User Management

Creating Users

To create a new user via the web interface:

1. Navigate to Users in the admin panel
2. Click Add User
3. Fill in the required fields:
   • Username: Unique identifier (alphanumeric, no spaces)
   • Email: User's email address
   • Password: Strong password (min 8 characters)
4. Select user role:
   • Admin: Full system access
   • User: SFTP access only
5. Click Create User

SSH Key Management

Users can authenticate using SSH keys for enhanced security:

Adding SSH Keys:

1. Edit the user in the admin panel
2. Click Manage SSH Keys
3. Either:
   • Paste an existing public key
   • Generate a new key pair (download the private key immediately!)
4. Save the changes

User Quotas and Limits

Set storage quotas and connection limits per user:

• Storage Quota: Maximum storage space (in GB)
• Max Connections: Concurrent SFTP connections allowed
• Bandwidth Limit: Upload/download speed restrictions

Bulk User Import

Import multiple users via CSV:

# CSV format
username,email,password,role,quota_gb
john.doe,john@example.com,TempPass123!,user,10
jane.smith,jane@example.com,TempPass456!,user,20

Upload the CSV file in Users → Import Users

Backup & Restore

Automated Backups

Configure automatic backups in the Settings panel:

1. Navigate to Settings → Backup
2. Enable Automated Backups
3. Set backup schedule (daily, weekly, monthly)
4. Configure retention policy (number of backups to keep)
5. Choose backup destination (local or S3)

Manual Backup

Create an immediate backup:

# Via CLI
docker exec sftproo sftproo-backup create

# Via Web UI
Settings → Backup → Create Backup Now

Backup Contents

Each backup includes:

• Database (users, settings, permissions)
• Configuration files
• SSH host keys
• User files (optional, can be large)

Restore Process

To restore from a backup:

1. Stop the sftproo service
2. Run the restore command:

   docker exec sftproo sftproo-backup restore backup-2025-01-15.tar.gz

3. Restart the service
4. Verify the restoration was successful

Backup Encryption

Backups are encrypted by default. To decrypt a backup manually:

# Use the decrypt_backup utility
./decrypt_backup -input backup-2025-01-15.tar.gz.enc -output backup.tar.gz

Security Settings

Access Control Lists (ACL)

Restrict access based on IP addresses:

1. Navigate to Settings → Security → ACL
2. Add allowed IP addresses or CIDR ranges
3. Enable Whitelist Mode to block all other IPs

Two-Factor Authentication

Enable 2FA for admin accounts:

1. Go to User Profile → Security
2. Click Enable 2FA
3. Scan the QR code with an authenticator app
4. Enter the verification code
5. Save the backup codes securely

Security Best Practices

• Use strong, unique passwords for all accounts
• Enable SSH key authentication and disable password auth
• Regularly update sftproo to the latest version
• Monitor logs for suspicious activity
• Use IP whitelisting for sensitive deployments
• Enable audit logging for compliance

Audit Logging

sftproo logs all important activities:

• User logins/logouts
• File uploads/downloads/deletions
• Configuration changes
• Failed authentication attempts

Access logs via Settings → Logs or:

docker logs sftproo

Getting Started

Welcome to sftproo! This guide will help you connect to the SFTP server and start transferring files.

Your Credentials

Your administrator should provide you with:

• Server Address: The hostname or IP of the SFTP server
• Port: Usually 2222 (not the standard SSH port 22)
• Username: Your unique username
• Password: Your initial password (change it on first login)
• SSH Key: (Optional) A private key file for authentication

First Connection

Using the command line:

sftp -P 2222 username@server.example.com

You'll be prompted to accept the server's host key on first connection. Type "yes" to continue.

Changing Your Password

To change your password via the web interface:

1. Log in to https://server.example.com:8443
2. Click your username in the top right
3. Select Change Password
4. Enter your current and new passwords
5. Click Update Password

File Management

Basic SFTP Commands

Once connected, use these commands to manage files:

Batch Transfers

Transfer multiple files at once:

# Upload all .pdf files
put *.pdf

# Download all files in a directory
get -r documents/

# Upload entire directory
put -r local_folder/

Resume Interrupted Transfers

If a transfer is interrupted, resume it:

# Resume upload
reput largefile.zip

# Resume download
reget largefile.zip

SSH Key Management

Generating SSH Keys

Create a new SSH key pair on your local machine:

On Linux/Mac:

ssh-keygen -t ed25519 -f ~/.ssh/sftproo_key -C "your_email@example.com"

On Windows (PowerShell):

ssh-keygen -t ed25519 -f $HOME\.ssh\sftproo_key -C "your_email@example.com"

Adding Your Public Key

Option 1: Via Web Interface

1. Log in to the web interface
2. Go to Profile → SSH Keys
3. Click Add SSH Key
4. Paste your public key (contents of sftproo_key.pub)
5. Give it a descriptive name
6. Click Save

Option 2: Ask your administrator to add it for you

Using SSH Keys for Authentication

Connect using your private key:

sftp -P 2222 -i ~/.ssh/sftproo_key username@server.example.com

SSH Agent

For convenience, add your key to the SSH agent:

# Start SSH agent
eval $(ssh-agent)

# Add your key
ssh-add ~/.ssh/sftproo_key

# Now connect without specifying the key
sftp -P 2222 username@server.example.com

SFTP Clients

While command-line SFTP is powerful, graphical clients can be more user-friendly.

Recommended Clients

Windows

• WinSCP (Free)
  1. Download from winscp.net
  2. Select "SFTP" as protocol
  3. Enter server, port 2222, username, and password
  4. For SSH keys, go to Advanced → SSH → Authentication
• FileZilla (Free)
  1. Download from filezilla-project.org
  2. Use sftp://server.example.com as host
  3. Set port to 2222
  4. Enter credentials and connect

macOS

• Cyberduck (Free)
  1. Download from cyberduck.io
  2. Choose "SFTP (SSH File Transfer Protocol)"
  3. Enter server details with port 2222
  4. Add SSH key in connection settings if needed
• Transmit (Paid)
  1. Premium option with advanced features
  2. Excellent integration with macOS
  3. Supports sync and automatic uploads

Linux

• FileZilla - Available in most package managers
• Nautilus/Dolphin - Built-in file managers support SFTP
  • Use address: sftp://username@server:2222

Mobile Clients

• iOS: FTPManager, Secure ShellFish
• Android: Total Commander, AndFTP

Troubleshooting

Common Connection Issues

Connection Refused

If you get "Connection refused" errors:

• Verify the server address and port (should be 2222, not 22)
• Check if you're behind a firewall that blocks port 2222
• Ensure the SFTP service is running (contact your admin)

Authentication Failed

If authentication fails:

• Double-check your username (case-sensitive)
• Verify your password or SSH key
• Ensure your account hasn't been locked
• Check if your IP is whitelisted (if ACL is enabled)

Permission Denied

If you can't access certain directories:

• You're restricted to your home directory
• Check file permissions with ls -la
• Contact admin if you need additional access

File Transfer Issues

Slow Transfers

• Check your internet connection speed
• Try transferring smaller files first
• Use compression for text files: put -z file.txt
• Consider using multiple concurrent connections

Incomplete Transfers

• Use resume capabilities: reput or reget
• Check available storage space
• Verify you haven't exceeded your quota

Getting Help

If you continue to experience issues:

1. Check the FAQ section
2. Contact your system administrator
3. Provide error messages and steps to reproduce

API Overview

sftproo provides a RESTful API for programmatic access to user management and system configuration.

Base URL

https://server.example.com:8443/api/v1

Authentication

All API requests require authentication using an API key:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://server.example.com:8443/api/v1/users

Response Format

All responses are in JSON format:

{
  "success": true,
  "data": {
    // Response data
  },
  "message": "Operation successful"
}

Error Handling

Errors return appropriate HTTP status codes:

{
  "success": false,
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "The requested user does not exist"
  }
}

API Authentication

Obtaining an API Key

1. Log in to the web interface as an admin
2. Navigate to Settings → API Keys
3. Click Generate New API Key
4. Copy the key immediately (it won't be shown again)

Using the API Key

Include the API key in the Authorization header:

# Using curl
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://server.example.com:8443/api/v1/users

# Using Python requests
import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://server.example.com:8443/api/v1/users',
    headers=headers
)

API Key Management

• API keys never expire but can be revoked
• Each key can have specific permissions
• Monitor API usage in the admin panel
• Rotate keys periodically for security

API Endpoints

Users

List Users

GET /api/v1/users

Response:
{
  "success": true,
  "data": {
    "users": [
      {
        "id": 1,
        "username": "john.doe",
        "email": "john@example.com",
        "role": "user",
        "created_at": "2025-01-15T10:00:00Z"
      }
    ]
  }
}

Create User

POST /api/v1/users

Request Body:
{
  "username": "jane.doe",
  "email": "jane@example.com",
  "password": "SecurePass123!",
  "role": "user"
}

Response:
{
  "success": true,
  "data": {
    "user": {
      "id": 2,
      "username": "jane.doe",
      "email": "jane@example.com"
    }
  }
}

Update User

PUT /api/v1/users/{id}

Request Body:
{
  "email": "newemail@example.com",
  "quota_gb": 50
}

Delete User

DELETE /api/v1/users/{id}

SSH Keys

List User's SSH Keys

GET /api/v1/users/{id}/ssh-keys

Add SSH Key

POST /api/v1/users/{id}/ssh-keys

Request Body:
{
  "name": "Work Laptop",
  "public_key": "ssh-ed25519 AAAAC3NzaC1... user@example.com"
}

System

Get System Status

GET /api/v1/system/status

Response:
{
  "success": true,
  "data": {
    "version": "1.0.19",
    "uptime": 86400,
    "users_online": 5,
    "disk_usage": {
      "used_gb": 45.2,
      "total_gb": 100
    }
  }
}

Create Backup

POST /api/v1/system/backup

Request Body:
{
  "include_user_files": true,
  "compress": true
}

Settings

Get Settings

GET /api/v1/settings

Update Settings

PUT /api/v1/settings

Request Body:
{
  "backup_enabled": true,
  "backup_schedule": "0 2 * * *",
  "ip_whitelist_enabled": true
}