uuxo/hmac-file-server
1
1
Fork 0
Code Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
b2b9c179c27316358cec7f5c0564a91068dc24b0
hmac-file-server/ejabberd-module/INSTALLATION_GUIDE.md

9.0 KiB
Raw Blame History

📖 INSTALLATION GUIDE: mod_http_upload_hmac

Ejabberd Module for HMAC File Server Integration

🎯 Overview

This module enables seamless file uploads in XMPP clients by integrating ejabberd with HMAC File Server 3.2.2. Users get zero-configuration file sharing with automatic authentication.

🔧 ADMINISTRATOR INSTALLATION

Prerequisites

  • ejabberd server (version 20.01 or later)
  • Erlang/OTP (version 22 or later)
  • HMAC File Server 3.2.2 with Bearer token support
  • Network connectivity between ejabberd and HMAC server

Step 1: Install HMAC File Server 3.2.2

# Download and install HMAC File Server
wget https://github.com/your-repo/hmac-file-server/releases/v3.2.2/hmac-file-server-linux-amd64
chmod +x hmac-file-server-linux-amd64
sudo mv hmac-file-server-linux-amd64 /usr/local/bin/hmac-file-server

# Create configuration
sudo mkdir -p /etc/hmac-file-server
sudo cat > /etc/hmac-file-server/config.toml << EOF
[server]
interface = "0.0.0.0"
port = 8080
upload_path = "/var/lib/hmac-uploads"
log_file = "/var/log/hmac-file-server.log"
log_level = "info"

[auth]
shared_secret = "YOUR-SECURE-SECRET-HERE"
bearer_tokens_enabled = true
token_expiry = 3600
jwt_enabled = true
hmac_enabled = true

[upload]
max_file_size = "100MB"
max_files_per_user = 1000
allowed_mime_types = ["image/*", "video/*", "audio/*", "application/pdf"]

[storage]
cleanup_interval = "24h"
retention_days = 30
EOF

# Create upload directory
sudo mkdir -p /var/lib/hmac-uploads
sudo chown hmac:hmac /var/lib/hmac-uploads

# Create systemd service
sudo cat > /etc/systemd/system/hmac-file-server.service << EOF
[Unit]
Description=HMAC File Server 3.2.2
After=network.target

[Service]
Type=simple
User=hmac
Group=hmac
ExecStart=/usr/local/bin/hmac-file-server -config /etc/hmac-file-server/config.toml
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

# Start service
sudo systemctl enable hmac-file-server
sudo systemctl start hmac-file-server

Step 2: Install ejabberd Module

# Copy module to ejabberd
sudo cp mod_http_upload_hmac.erl /opt/ejabberd/lib/ejabberd-*/ebin/

# Compile module
cd /opt/ejabberd/lib/ejabberd-*/ebin/
sudo erlc mod_http_upload_hmac.erl

# Verify compilation
ls -la mod_http_upload_hmac.beam

Step 3: Configure ejabberd

Add to /etc/ejabberd/ejabberd.yml:

modules:
  mod_http_upload_hmac:
    hmac_server_url: "http://localhost:8080"
    hmac_shared_secret: "YOUR-SECURE-SECRET-HERE"  # Must match HMAC server
    max_size: 104857600  # 100MB
    quota_per_user: 1073741824  # 1GB per user
    token_expiry: 3600  # 1 hour
    iqdisc: one_queue

# Disable default mod_http_upload if enabled
# mod_http_upload: false

Step 4: Restart ejabberd

sudo systemctl restart ejabberd

# Check logs
sudo tail -f /var/log/ejabberd/ejabberd.log

Step 5: Configure Reverse Proxy (Optional but Recommended)

For HTTPS support with nginx:

server {
    listen 443 ssl http2;
    server_name files.yourdomain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    client_max_body_size 100M;
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300;
        proxy_send_timeout 300;
    }
}

Update ejabberd config:

modules:
  mod_http_upload_hmac:
    hmac_server_url: "https://files.yourdomain.com"
    # ... other settings

👤 USER GUIDE

What This Enables

  • Automatic file uploads in XMPP clients (Conversations, Dino, Gajim, etc.)
  • No manual configuration required in clients
  • Secure authentication using your XMPP credentials
  • Large file support up to configured limits

Supported XMPP Clients

✅ Conversations (Android)
✅ Dino (Linux/Desktop)
✅ Gajim (Cross-platform)
✅ ChatSecure (iOS)
✅ Monal (iOS/macOS)
✅ Movim (Web)
✅ Any XEP-0363 compatible client

How to Use

  1. No setup required - your XMPP client will automatically discover the upload service
  2. Send files normally - use your client's attachment/file sharing feature
  3. Files upload automatically - authentication handled transparently
  4. Recipients get download links - works across different clients and servers

File Limits (Default Configuration)

  • Maximum file size: 100MB per file
  • Storage quota: 1GB per user
  • File retention: 30 days
  • Supported types: Images, videos, audio, documents

Troubleshooting for Users

Problem: File uploads fail
Solution: Check with your server administrator - the service may be temporarily unavailable

Problem: Files too large
Solution: Compress files or ask administrator about size limits

Problem: Client doesn't show upload option
Solution: Ensure your client supports XEP-0363 HTTP File Upload

🔍 TESTING AND VALIDATION

Quick Health Check

# Test HMAC server
curl http://localhost:8080/health

# Test ejabberd module loading
sudo ejabberdctl modules_available | grep http_upload

# Check ejabberd logs
sudo tail /var/log/ejabberd/ejabberd.log

Integration Test

# Run comprehensive test suite
cd /path/to/ejabberd-module/
./comprehensive_integration_test.sh

Manual Upload Test

# Generate test token (simulate ejabberd)
USER="testuser@yourdomain.com"
FILENAME="test.txt"
SECRET="YOUR-SECURE-SECRET-HERE"

# Test upload endpoint
curl -X POST "http://localhost:8080/upload/test-uuid/test.txt" \
     -H "Authorization: Bearer $(echo -n "$USER\0$FILENAME\0$(date +%s)" | openssl dgst -sha256 -hmac "$SECRET" -binary | base64)" \
     -H "Content-Type: text/plain" \
     -d "Test upload content"

🔒 SECURITY CONSIDERATIONS

For Administrators

  • Use strong shared secrets (minimum 32 characters)
  • Enable HTTPS for production deployments
  • Configure appropriate file size limits
  • Set up log monitoring for upload activities
  • Regular security updates for both ejabberd and HMAC server
  • Network isolation - HMAC server doesn't need internet access

Network Security

# Firewall configuration example
sudo ufw allow from [ejabberd-ip] to any port 8080  # HMAC server
sudo ufw allow 5222/tcp  # XMPP client connections
sudo ufw allow 5269/tcp  # XMPP server-to-server
sudo ufw allow 443/tcp   # HTTPS file uploads (if using reverse proxy)

📊 MONITORING AND MAINTENANCE

Log Monitoring

# HMAC server logs
sudo tail -f /var/log/hmac-file-server.log

# ejabberd logs  
sudo tail -f /var/log/ejabberd/ejabberd.log

# nginx logs (if using reverse proxy)
sudo tail -f /var/log/nginx/access.log

Performance Monitoring

  • Monitor disk usage in upload directory
  • Check memory usage of HMAC server process
  • Monitor ejabberd performance impact
  • Track upload/download statistics

Backup Recommendations

  • Configuration files: /etc/ejabberd/, /etc/hmac-file-server/
  • Upload data: /var/lib/hmac-uploads/ (optional, based on retention policy)
  • ejabberd database: Standard ejabberd backup procedures

🆘 TROUBLESHOOTING

Common Issues

Module fails to load

# Check Erlang compilation
sudo erlc /opt/ejabberd/lib/ejabberd-*/ebin/mod_http_upload_hmac.erl

# Check ejabberd syntax
sudo ejabberdctl check_config

HMAC server not responding

# Check service status
sudo systemctl status hmac-file-server

# Check port binding
sudo netstat -tlnp | grep :8080

# Test connectivity
curl -v http://localhost:8080/health

Token authentication fails

  • Verify shared secrets match between ejabberd and HMAC server
  • Check system time synchronization
  • Review token expiry settings

Debug Mode

Enable debug logging in ejabberd:

loglevel: debug
log_modules_fully: [mod_http_upload_hmac]

📈 SCALING AND PRODUCTION

High Availability Setup

  • Run multiple HMAC server instances behind load balancer
  • Use shared storage (NFS/GlusterFS) for upload directory
  • Configure ejabberd clustering if needed

Performance Optimization

  • Tune Erlang VM parameters for ejabberd
  • Configure nginx caching for downloads
  • Use SSD storage for upload directory
  • Monitor and adjust file retention policies

🔄 UPDATES AND MAINTENANCE

Updating the Module

  1. Download new mod_http_upload_hmac.erl
  2. Backup existing module
  3. Replace and recompile
  4. Restart ejabberd

Updating HMAC File Server

  1. Stop service: sudo systemctl stop hmac-file-server
  2. Backup configuration and data
  3. Replace binary
  4. Start service: sudo systemctl start hmac-file-server

📞 SUPPORT

  • GitHub Issues: Report bugs and feature requests
  • Documentation: Check project wiki for updates
  • Community: Join XMPP development discussions
  • Security Issues: Report privately to security contact

Last updated: August 25, 2025
Version: HMAC File Server 3.2.2 + ejabberd integration