Network File Transfer Server - rConfig V8 xFTP Services

xFTP Server: Secure File Transfer for Network Devices

The xFTP Server provides secure, reliable file transfer capabilities enabling network devices to upload non-configuration files, binary data, and archive content to rConfig for centralized storage and management.

Note

8.1.2 release note (new behavior)

• Tracks xFTP uploads in a new database table: xftp_uploads
• Adds retention/auto-clean targets to purge: xftp_root and xftp_device_uploads
• Adds file matching patterns to map filenames to devices (regex/prefix/suffix/contains/exact)
• Updates UI file tables with: type/metadata, peek (text-only), download, delete, copy path

All other behavior in this document should be treated as legacy unless explicitly stated.

---

Quick Concepts

Protocols

• TFTP: legacy compatibility, no auth/encryption (UDP/69)
• FTP: username/password auth (TCP/21)
• SFTP/SCP: encrypted over SSH, configurable port (often 2222)

Tip

Use SFTP for production environments handling sensitive data. Use FTP when devices lack SFTP support but authentication is required. Use TFTP only for legacy or isolated environments.

Directory layout

• Inbox (raw uploads): /srv/xftp/
• Processed device storage (moved files): under rConfig data path (example):

/var/www/html/rconfig8/storage/app/rconfig/data/<Category>/<device-name>/xftpuploads/

---

How xFTP Processing Works (8.1.2)

1. Devices upload a file via TFTP/FTP/SFTP into the inbox directory: /srv/xftp/.
2. A scheduled sweeper moves matched files into a device’s xftpuploads/ directory.
3. rConfig tracks the lifecycle in the xftp_uploads table (source path, destination path, timestamps, metadata).

Scheduled sweep task

php artisan rconfig:sweep-xftp-dir

Note

The sweeper may skip files modified in the last few seconds to avoid racing partially-uploaded files. If skipped, the file is processed on the next run.

Manual sweep execution

cd /var/www/html/rconfig8
php artisan rconfig:sweep-xftp-dir

---

Managing xFTP Services (Docker)

You can manage the Docker microservices through:

• UI: Settings → xFTP Services
• CLI: php artisan rconfig:xftp-toggle

# Status
php artisan rconfig:xftp-toggle --status

---

Uploading Files (device examples)

TFTP

Router(config)#file prompt quiet
Router#copy vlan.dat tftp://192.168.1.131/1234-vlan.dat

FTP

Router#copy vlan.dat ftp://ftpuser:[email protected]/1234-vlan.dat

SFTP

Router#copy vlan.dat sftp://sftpuser:[email protected]:2222/1234-vlan.dat

Note

The exact copy syntax varies by vendor/OS. The critical requirement is ensuring the filename can be matched to a device (see next section).

---

Matching uploaded files to devices

Legacy matching

Legacy behavior expects filenames like:

• 1234-anything.ext (device ID is leading digits before a -)

File Matching Patterns (8.1.2)

8.1.2 adds optional pattern-based routing when filenames don’t contain the numeric device ID.

Where: Settings → xFTP Services → File Matching

Pattern types (8.1.2):

• regex
• prefix
• suffix
• contains
• exact

Rule precedence: first match wins (ordered by pattern ID). If no rule matches, rConfig falls back to legacy extraction.

---

Viewing and managing uploaded files (8.1.2 UI)

Settings: Inbox (raw /srv/xftp/ directory)

Shows files physically present in /srv/xftp/ (awaiting sweep or unmatched).

Actions:

• Peek (text-only preview; capped at 1MB)
• Download
• Delete (single file)
• Empty directory
• Copy path

Type/metadata:

• rConfig infers file type (text/binary/archive/etc.) and shows metadata in the table.

Device view: Processed uploads (tracked moved files)

Shows a paginated, DB-backed history of moved files for a device.

Actions match the Settings inbox: peek (text), download, delete, copy path, and metadata.

---

Backfilling upload tracking (8.1.2)

If you upgraded and already have files on disk, populate xftp_uploads from the filesystem:

php artisan rconfig:xftp-backfill-uploads

# Dry run
php artisan rconfig:xftp-backfill-uploads --dry-run

# Limit scanned files (0 = unlimited)
php artisan rconfig:xftp-backfill-uploads --limit=1000

---

Retention and auto-cleanup (8.1.2)

8.1.2 integrates xFTP retention into the existing purge framework (settings_purge).

Targets:

• xftp_root: retention for tracked inbox files (/srv/xftp/)
• xftp_device_uploads: retention for tracked moved device uploads (xftpuploads/)

Default values (seeded when xftp_uploads exists):

• xftp_root: 30 days
• xftp_device_uploads: 90 days

Run via CLI:

# Run everything
php artisan rconfig:data-purge

# Run only xFTP targets (option name is legacy: --table)
php artisan rconfig:data-purge --table=xftp_root
php artisan rconfig:data-purge --table=xftp_device_uploads

# Dry run
php artisan rconfig:data-purge --table=xftp_root --dry-run

Note

Retention applies to files that are tracked in xftp_uploads. If you have existing files with no tracking rows, run the backfill command first.

---

Troubleshooting

Files are stuck in /srv/xftp/

• Run php artisan rconfig:sweep-xftp-dir.
• Confirm the filename can be matched (legacy {deviceid}-... or a File Matching rule).

Peek doesn’t work

• Peek is text-only and capped at 1MB. Download archives/binaries instead.

Postgres duplicate key on xftp_uploads_pkey

8.1.2 includes a mitigation for out-of-sync Postgres sequences (often from manual inserts). When detected, rConfig repairs the sequence and retries the insert.

---

Summary

In 8.1.2, xFTP becomes fully trackable and manageable: inbox visibility, device history, file metadata, and retention/auto-clean via purge targets. Legacy behaviors still apply where not explicitly overridden.

Installation Workflow:

1. Detection: Setup wizard checks for Docker installation
2. Prompt: If Docker not found, prompts for automated installation
3. Confirmation: Select ‘Yes’ to proceed with Docker installation
4. Download and Install: Wizard downloads Docker packages and installs dependencies
5. Service Start: Automatically starts Docker daemon and enables at boot
6. Verification: Confirms Docker installation and displays version

Installation Duration: Docker installation typically completes in 1-3 minutes depending on internet connection speed and package repository responsiveness.

Manual Docker Installation

If you prefer manual Docker installation or have specific Docker configuration requirements:

Ubuntu/Debian:

# Update package index
sudo apt-get update

# Install prerequisites
sudo apt-get install ca-certificates curl gnupg

# Add Docker GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add Docker repository
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Start and enable Docker
sudo systemctl start docker
sudo systemctl enable docker

Rocky Linux/RHEL/CentOS:

# Install required packages
sudo dnf install -y yum-utils

# Add Docker repository
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# Install Docker
sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Start and enable Docker
sudo systemctl start docker
sudo systemctl enable docker

Verify Installation:

docker --version
sudo systemctl status docker

Once Docker is installed (automatically or manually), return to the xFTP setup wizard to deploy microservices.

Removing Docker

If you need to completely remove Docker and all xFTP services:

Ubuntu/Debian:

# Stop all containers
sudo docker stop $(sudo docker ps -aq)

# Remove all containers
sudo docker rm $(sudo docker ps -aq)

# Remove Docker packages
sudo apt-get purge docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Remove Docker data and configuration
sudo rm -rf /var/lib/docker
sudo rm -rf /var/lib/containerd
sudo rm -rf /etc/docker

Rocky Linux/RHEL/CentOS:

# Stop all containers
sudo docker stop $(sudo docker ps -aq)

# Remove all containers
sudo docker rm $(sudo docker ps -aq)

# Remove Docker packages
sudo dnf remove docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

# Remove Docker data and configuration
sudo rm -rf /var/lib/docker
sudo rm -rf /var/lib/containerd
sudo rm -rf /etc/docker

---

Deploying xFTP Services

Note

Running Commands: All command examples assume execution from the rConfig installation directory: bash cd /var/www/html/rconfig8/current

Accessing xFTP Management

The xFTP Server can be managed through two interfaces:

Web Interface: Navigate to Settings → xFTP Services in the rConfig UI

Command Line Interface: Use the xFTP toggle command for service deployment and management:

php artisan rconfig:xftp-toggle

Service Status Overview

Before deploying services, verify Docker status and existing xFTP service state:

Via Web UI: The xFTP Services page displays:

• Docker installation status and version
• Running xFTP services (TFTP, FTP, SFTP)
• Port configurations
• Credential status
• File count in xFTP directory

Via CLI:

php artisan rconfig:xftp-toggle --status

Deploying Services

TFTP Service

TFTP Service Deployment

TFTP provides basic file transfer without authentication, suitable for legacy devices and low-security environments.

Caution

First-Time Setup: Initial deployment downloads Docker images from Docker Hub (~200MB for TFTP). Subsequent deployments use cached images and complete instantly.

Installing TFTP

Interactive Setup:

cd /var/www/html/rconfig8/current
php artisan rconfig:xftp-toggle

Setup Workflow:

1. Service Selection: Choose TFTP from available protocols

2. Image Download: Docker pulls TFTP image (first time only)

3. Container Creation: TFTP container deploys and starts automatically

4. Verification: Service status shows TFTP running on port 69

   

TFTP Configuration

Default Settings:

• Port: 69 (standard TFTP port)
• Protocol: UDP
• Authentication: None (TFTP is unauthenticated by design)
• Upload Directory: /srv/xftp/

No Credentials Required: TFTP operates without username/password authentication. Any device with network access to the rConfig server can upload files.

Video Tutorial: TFTP Setup

Complete TFTP service deployment from Docker installation to first file upload

Stopping TFTP Service

To stop and remove the TFTP service:

php artisan rconfig:xftp-toggle

Removal Workflow:

1. Service Detection: Wizard detects running TFTP service
2. Removal Confirmation: Prompt to stop and remove container
3. Container Cleanup: TFTP container stopped and removed
4. Verification: Service status confirms TFTP no longer running

Note

Data Preservation: Removing the TFTP container does not delete uploaded files in /srv/xftp/ or device-specific storage. Only the TFTP service container is removed. Files remain accessible and can be processed when the service is redeployed.

FTP Service

FTP Service Deployment

FTP provides authenticated file transfer with credential-based access control, balancing security and device compatibility.

Caution

First-Time Setup: Initial deployment downloads Docker images from Docker Hub (~250MB for FTP). Subsequent deployments use cached images and complete instantly.

Installing FTP

Interactive Setup:

cd /var/www/html/rconfig8/current
php artisan rconfig:xftp-toggle

Setup Workflow:

1. Service Selection: Choose FTP from available protocols

2. Credential Configuration: Enter FTP username and password

3. Image Download: Docker pulls FTP image (first time only)

4. Container Creation: FTP container deploys with configured credentials

5. Verification: Service status shows FTP running on port 21

FTP Configuration

Default Settings:

• Port: 21 (standard FTP control port)
• Protocol: TCP
• Authentication: Username and password (configured during setup)
• Transfer Mode: Active and passive mode supported
• Upload Directory: /srv/xftp/

Credential Storage: FTP credentials are stored in the .env file and can be referenced in device commands using variables (detailed in upload procedures section).

Credential Management

Reusing Existing Credentials: When redeploying FTP service, the wizard prompts to reuse previously configured credentials:

Options:

• Reuse Credentials: Use existing username/password from .env file
• Update Credentials: Enter new username/password, overwriting previous values

Use Cases:

• Reuse credentials when restarting service without changes
• Update credentials for security rotation or policy compliance

Video Tutorial: FTP Setup

Step-by-step FTP service deployment including credential configuration and testing

Stopping FTP Service

To stop and remove the FTP service:

php artisan rconfig:xftp-toggle

Removal Workflow:

1. Service Detection: Wizard detects running FTP service
2. Removal Confirmation: Prompt to stop and remove container
3. Credential Preservation: FTP credentials remain in .env for future deployments
4. Container Cleanup: FTP container stopped and removed
5. Verification: Service status confirms FTP no longer running

SFTP/SCP Service

SFTP/SCP Service Deployment

SFTP provides encrypted, authenticated file transfer over SSH, offering enterprise-grade security for sensitive file uploads.

Caution

First-Time Setup: Initial deployment downloads Docker images from Docker Hub (~300MB for SFTP). Subsequent deployments use cached images and complete instantly.

Installing SFTP/SCP

Interactive Setup:

cd /var/www/html/rconfig8/current
php artisan rconfig:xftp-toggle

Setup Workflow:

1. Service Selection: Choose SFTP from available protocols

2. Port Configuration: Enter SFTP service port (must not conflict with host SSH port 22)

3. Credential Configuration: Enter SFTP username and password

4. Image Download: Docker pulls SFTP image (first time only)

5. Container Creation: SFTP container deploys with configured port and credentials

6. Verification: Service status shows SFTP running on configured port

SFTP Configuration

Default Settings:

• Port: Configurable (recommended: 2222, cannot be 22)
• Protocol: SSH/TCP (encrypted transport)
• Authentication: SSH username and password (configured during setup)
• Encryption: All data encrypted in transit via SSH
• Upload Directory: /srv/xftp/
• SCP Support: SFTP service also handles SCP connections

Caution

Port Conflict Warning: SFTP/SCP rely on SSH protocol, which defaults to port 22 on most systems. The SFTP microservice requires a different port to avoid conflicts with the host’s SSH daemon. Common alternatives: 2222, 10022, or any port above 1024 not already in use.

Verifying Port Availability:

# Check if proposed port is available
sudo netstat -tulpn | grep :2222

# No output = port available
# Output shows existing service = choose different port

Credential Management

Reusing Existing Credentials: When redeploying SFTP service, the wizard prompts to reuse previously configured credentials and port:

Options:

• Reuse Configuration: Use existing username/password/port from .env file
• Update Configuration: Enter new credentials or change port number

SFTP vs SCP

The SFTP service container handles both SFTP and SCP protocols:

SFTP (SSH File Transfer Protocol):

• Interactive file transfer protocol over SSH
• Supports directory listing, file management, resumable transfers
• More feature-rich than SCP
• Preferred for modern devices and manual transfers

SCP (Secure Copy Protocol):

• Simple file copy over SSH
• Non-interactive, command-line oriented
• Less overhead than SFTP for single file transfers
• Supported by legacy devices and scripting

Connection Syntax:

# SFTP connection
sftp -P 2222 username@rconfig-server-ip

# SCP upload
scp -P 2222 localfile.txt username@rconfig-server-ip:/remote/path/

Both protocols authenticate with the same credentials configured during SFTP service setup.

Video Tutorial: SFTP Setup

Complete SFTP service deployment including port selection, credential configuration, and testing both SFTP and SCP uploads

Stopping SFTP Service

To stop and remove the SFTP service:

php artisan rconfig:xftp-toggle

Removal Workflow:

1. Service Detection: Wizard detects running SFTP service
2. Removal Confirmation: Prompt to stop and remove container
3. Configuration Preservation: SFTP credentials and port settings remain in .env for future deployments
4. Container Cleanup: SFTP container stopped and removed
5. Verification: Service status confirms SFTP no longer running

---

Uploading Files to xFTP Services

Manual File Upload from Devices

Network devices upload files to xFTP services using protocol-specific commands. File naming must include the device ID for automated processing and device association.

TFTP Upload Example

Cisco IOS Devices:

# Suppress filename prompts (optional but recommended)
Router(config)#file prompt quiet

# Upload file to rConfig TFTP server
Router#copy vlan.dat tftp://192.168.1.131/1234-vlan.dat
!!
376 bytes copied in 0.004 secs (94000 bytes/sec)

Command Breakdown:

• copy vlan.dat - Source file on device local storage
• tftp://192.168.1.131 - rConfig server IP with TFTP protocol
• /1234-vlan.dat - Target filename with device ID (1234) properly delimited

FTP Upload Example

Cisco IOS Devices:

Router#copy vlan.dat ftp://ftpuser:[email protected]/1234-vlan.dat

Using Credential Variables (recommended for security):

Router#copy vlan.dat ftp://{ftpusername}:{ftppassword}@192.168.1.131/{deviceid}-vlan.dat

Variable Substitution:

• {ftpusername} - Replaced with FTP username from rConfig .env file
• {ftppassword} - Replaced with FTP password from rConfig .env file
• {deviceid} - Replaced with actual device ID when command executes

Tip

Secure Credential Handling: Using credential variables ({ftpusername}, {ftppassword}) prevents hardcoding sensitive credentials in device configurations. rConfig automatically substitutes actual values from .env when commands execute, maintaining security while enabling automation.

SFTP Upload Example

Cisco IOS Devices (supporting SFTP):

Router#copy vlan.dat sftp://sftpuser:[email protected]:2222/1234-vlan.dat

Using Credential Variables:

Router#copy vlan.dat sftp://{sftpusername}:{sftppassword}@192.168.1.131:2222/{deviceid}-vlan.dat

Note Port Specification: SFTP command must include custom port (:2222) if not using standard port 22.

Device ID Requirement

Note

Filename Format for Device ID: The {deviceid} parameter must be located between the last / and a - character followed by the filename:

Valid Patterns:

• tftp://192.168.1.131/{deviceid}-vlan.dat ✓
• ftp://server/{deviceid}-config.log ✓
• sftp://server/{deviceid}-firmware.bin ✓

Invalid Patterns:

• tftp://192.168.1.131/vlan-{deviceid}.dat ✗ (deviceid not before dash)
• ftp://server/{deviceid}config.log ✗ (no dash separator)
• sftp://server/1234config.log ✗ (no dash separator)

This format ensures single-digit device IDs don’t conflict with other numbers in filenames during pattern matching.

Finding Device ID:

• Visible in rConfig UI on device list and device detail pages
• Available in database devices table, id column
• Automatically substituted when using {deviceid} variable in commands

Automated File Upload via Commands

Files can be uploaded automatically during device polling by incorporating upload commands into rConfig command categories.

Configuring Automated Uploads

1. Navigate to Commands Section: Go to Settings → Commands in rConfig UI

2. Create or Edit Command Category: Select the command category used for target devices

3. Add Upload Command: Insert the copy command with variables:

Example Command:

copy vlan.dat tftp://192.168.1.131/{deviceid}-vlan.dat

4. Assign to Devices: Ensure devices use this command category in their configuration

5. Execution During Backup: When rConfig backs up device configuration, the upload command executes automatically, transferring the file to xFTP service

Automated Upload Benefits

Consistency: Upload commands execute identically across all devices in the category, eliminating manual command variations.

Scheduling: Files upload automatically on backup schedule without administrator intervention.

Audit Trail: Command execution logs provide record of file uploads for compliance and troubleshooting.

Scalability: Single command configuration applies to hundreds or thousands of devices, avoiding per-device manual setup.

Video Tutorial: File Upload Workflows

Demonstration of manual and automated file upload workflows including command configuration and troubleshooting

---

Viewing and Managing Uploaded Files

Accessing Device Files

Successfully processed files (those with valid device IDs) appear on the device’s page in the rConfig UI.

Navigation: Go to Devices → [Device Name] and scroll to the uploaded files section at the bottom of the page.

Files Table: Displays uploaded files with:

• Filename (with timestamp appended for versioning)
• Upload date and time
• File size
• File type/extension

View All Files: Click View All to access the complete file management interface

Note

8.1.2 Notice:

• Smart file detection is now included in this release.
• TXT files can now be opened directly in the browser for viewing (no download required).
• A new metadata column has been added to the uploaded files table. This column is currently a placeholder and will be populated with real file metadata in version 8.1.2+.

Available Actions:

View: Display file contents in browser (for text files) or download prompt (for binary files)

Download: Save file to local system for analysis, backup, or distribution

Delete: Remove file from device storage (with confirmation prompt)

Bulk Operations: Select multiple files for batch download or deletion

xFTP Directory Management

Note

8.1.2+ Notice: The default purge retention for xFTP directories is now set to 30 days. Files older than this will be automatically cleaned up unless configured otherwise.

The xFTP upload directory (/srv/xftp/) should remain empty under normal operation. Files persisting in this directory indicate processing issues.

Viewing Orphaned Files: Navigate to Settings → xFTP Services to see files in /srv/xftp/ that were not processed

Orphaned File Causes:

• Filename missing device ID
• Device ID not properly delimited (missing dash separator)
• Device ID doesn’t match any device in rConfig inventory
• Filename pattern doesn’t conform to requirements

Manual Cleanup: Delete orphaned files directly from the xFTP Services page or via CLI:

# List files in xFTP directory
ls -la /srv/xftp/

# Remove specific file
rm /srv/xftp/invalid-filename.dat

# Clear all orphaned files (use with caution)
rm /srv/xftp/*

---

Troubleshooting

Files Not Appearing on Device Page

Symptom: Files uploaded successfully but don’t appear in device file listing.

Diagnostic Steps:

1. Check xFTP Directory: Verify file present in /srv/xftp/

   ls -la /srv/xftp/

2. Verify Filename Pattern: Ensure device ID properly delimited in filename:

   • Valid: 1234-vlan.dat (device ID 1234 before dash)
   • Invalid: vlan1234.dat (no dash separator)
   • Invalid: vlan-1234.dat (device ID after dash)

3. Confirm Device ID Exists: Verify device ID in filename matches actual device in rConfig:

   # Check device exists with this ID
   mysql -u rconfig -p rconfig -e "SELECT id, device_name FROM devices WHERE id = 1234;"

4. Manual Sweep: Trigger sweep task manually to process files immediately:

   cd /var/www/html/rconfig8/current
   php artisan rconfig:sweep-tftp-dir

5. Check Sweep Task Logs: Review logs for processing errors:

   tail -50 /var/www/html/rconfig8/current/storage/logs/laravel.log | grep sweep

Resolution:

• If filename pattern incorrect: Re-upload with correct pattern
• If device doesn’t exist: Create device in rConfig or update filename with valid device ID
• If sweep task not running: Verify scheduled task enabled in Settings → Scheduled Tasks

Upload Failures

Symptom: Device reports upload error or times out during file transfer.

Common Causes and Resolutions:

Service Not Running:

# Check service status
php artisan rconfig:xftp-toggle --status

# If service stopped, restart
php artisan rconfig:xftp-toggle
# Select service to start

Firewall Blocking:

# Verify port accessibility from device
telnet <rconfig-server-ip> 69   # TFTP
telnet <rconfig-server-ip> 21   # FTP
telnet <rconfig-server-ip> 2222 # SFTP

# If blocked, add firewall rule
sudo firewall-cmd --add-port=69/udp --permanent   # TFTP
sudo firewall-cmd --add-port=21/tcp --permanent   # FTP
sudo firewall-cmd --add-port=2222/tcp --permanent # SFTP
sudo firewall-cmd --reload

Authentication Failure (FTP/SFTP):

# Verify credentials in .env file
grep -E 'FTP_USERNAME|FTP_PASSWORD|SFTP_USERNAME|SFTP_PASSWORD' /var/www/html/rconfig8/current/.env

# Test credentials manually
ftp <rconfig-server-ip>
# Enter username and password when prompted

# For SFTP
sftp -P 2222 username@<rconfig-server-ip>

Insufficient Disk Space:

# Check available space
df -h /srv/xftp/

# Clear old orphaned files if needed
rm /srv/xftp/*

# Increase disk allocation if persistently full

Container Fails to Start

Symptom: Docker container status shows exited or error state.

Diagnostic Steps:

1. Check Container Logs:

   # List all containers including stopped
   docker ps -a
   
   # View logs for specific service
   docker logs rconfig-tftp
   docker logs rconfig-ftp
   docker logs rconfig-sftp

2. Port Conflicts:

   # Check if port already in use
   sudo netstat -tulpn | grep :69    # TFTP
   sudo netstat -tulpn | grep :21    # FTP
   sudo netstat -tulpn | grep :2222  # SFTP
   
   # If port occupied, stop conflicting service or use different port

3. Permission Issues:

   # Verify xFTP directory permissions
   ls -la /srv/xftp/
   
   # Should be owned by appropriate user with write permissions
   sudo chown -R www-data:www-data /srv/xftp/
   sudo chmod 755 /srv/xftp/

4. Docker Service Issues:

   # Restart Docker service
   sudo systemctl restart docker
   
   # Check Docker daemon logs
   sudo journalctl -u docker -n 50

Resolution:

• Fix identified issue (port conflict, permissions, etc.)
• Remove failed container: docker rm rconfig-<service>
• Redeploy service via php artisan rconfig:xftp-toggle

Sweep Task Not Processing Files

Symptom: Files remain in /srv/xftp/ directory indefinitely despite scheduled sweep task.

Diagnostic Steps:

1. Verify Scheduled Task Enabled:

   • Navigate to Settings → Scheduled Tasks
   • Locate “TFTP Directory Sweep” task
   • Ensure status is “Enabled”

2. Check Task Execution History:

   • View task run history for errors or skipped executions
   • Review last successful run timestamp

3. Manual Execution:

   # Run sweep manually to check for errors
   cd /var/www/html/rconfig8/current
   php artisan rconfig:sweep-tftp-dir
   
   # Check output for errors or warnings

4. Laravel Scheduler Status:

   # Verify Laravel scheduler is running
   ps aux | grep schedule:run
   
   # Check cron configuration
   crontab -u www-data -l | grep schedule

Resolution:

• If task disabled: Enable in Scheduled Tasks settings
• If scheduler not running: Verify cron job configured correctly
• If errors in manual run: Review logs and fix identified issues
• Adjust task frequency if 15-minute interval insufficient for upload volume

---

Advanced Configuration

Custom Upload Directory (V8 Feature)

Note

V8 Flexible xFTP Services: Starting with rConfig V8, the Docker-based xFTP services become optional. Organizations can deploy their own FTP/SFTP services and configure rConfig to process files from custom directories.

Custom Directory Configuration:

1. Set Custom Path: Edit .env file to specify upload directory:

   nano /var/www/html/rconfig8/current/.env
   
   # Add or modify:
   XFTP_ROOT_DIR=/path/to/custom/upload/directory

2. Create Directory: Ensure custom directory exists with proper permissions:

   sudo mkdir -p /path/to/custom/upload/directory
   sudo chown www-data:www-data /path/to/custom/upload/directory
   sudo chmod 755 /path/to/custom/upload/directory

3. Verify Access: Test rConfig can access custom directory:

   cd /var/www/html/rconfig8/current
   php artisan rconfig:sweep-tftp-dir
   
   # Should show custom directory in output

4. Configure External FTP Service: Point your FTP/SFTP service to upload files to custom directory specified in XFTP_ROOT_DIR

Use Cases:

• Integration with existing enterprise FTP infrastructure
• Compliance requirements for specific storage locations
• Network segmentation requiring FTP services on separate hosts
• High-availability FTP configurations with load balancing

Multiple Service Deployment

All xFTP services can run simultaneously, providing multiple upload options for devices with different capabilities:

Parallel Service Configuration:

# Deploy TFTP for legacy devices
php artisan rconfig:xftp-toggle
# Select TFTP

# Deploy FTP for authenticated transfers
php artisan rconfig:xftp-toggle
# Select FTP, configure credentials

# Deploy SFTP for secure transfers
php artisan rconfig:xftp-toggle
# Select SFTP, configure port and credentials

All Services Active:

• TFTP listening on port 69 (no authentication)
• FTP listening on port 21 (with credentials)
• SFTP listening on port 2222 (encrypted with credentials)

Resource Allocation: Each service runs in isolated container with dedicated resources. Monitor overall server resource usage when running multiple services under high load.

Device Configuration: Different device groups can use different protocols based on capabilities:

• Legacy switches → TFTP
• Modern routers → FTP
• Security appliances → SFTP

Performance Optimization

For High-Volume Environments:

Increase Sweep Frequency: Reduce time files remain in upload directory:

• Navigate to Settings → Scheduled Tasks
• Edit “TFTP Directory Sweep” task
• Change frequency from 15 minutes to 5 or 10 minutes
• Save changes

Docker Resource Limits: Allocate additional resources to busy services:

# Edit docker-compose configuration (if using)
# Or manually specify resource limits when creating containers

docker run -d \
  --name rconfig-ftp \
  --memory="512m" \
  --cpus="1.0" \
  -p 21:21 \
  -v /srv/xftp:/home/ftpuser \
  rconfig/ftp-server

Storage Optimization: Implement retention policies for uploaded files:

• Regularly archive old device files to external storage
• Delete obsolete file versions per policy
• Monitor /srv/xftp size trends

Tip

Enterprise Support for High-Volume Deployments: Organizations with high file upload volumes (thousands of files per hour), custom FTP infrastructure requirements, or complex network architectures should contact rConfig support for optimization guidance. Our enterprise support team can provide architecture recommendations, performance tuning, and custom integration assistance tailored to your specific deployment requirements.

---

Security Considerations

Protocol Security Comparison

TFTP (Lowest Security):

• No authentication - any network-accessible device can upload
• No encryption - all data transmitted in plaintext
• No access control - cannot restrict upload sources
• Use Only: In isolated lab networks or with legacy devices lacking alternatives

FTP (Medium Security):

• Credential-based authentication prevents unauthorized uploads
• No encryption - credentials and data transmitted in plaintext
• Susceptible to credential sniffing on untrusted networks
• Use When: Authentication required but devices lack SFTP support

SFTP (Highest Security):

• SSH-based authentication with encrypted credentials
• Full encryption - all data encrypted in transit
• Protection against eavesdropping and man-in-the-middle attacks
• Use For: Production environments, sensitive data, compliance requirements

Access Control

Network-Level Restrictions:

# Firewall rules limiting upload sources to trusted networks
sudo firewall-cmd --permanent --add-rich-rule='
  rule family="ipv4"
  source address="10.0.0.0/8"
  port protocol="tcp" port="21"
  accept'

sudo firewall-cmd --permanent --add-rich-rule='
  rule family="ipv4"
  source address="10.0.0.0/8"
  port protocol="tcp" port="2222"
  accept'

sudo firewall-cmd --reload

Service Isolation: Docker containers provide isolation between xFTP services and core rConfig:

• Container compromise doesn’t directly expose rConfig application
• Resource limits prevent denial-of-service impact on other services
• Separate credential management per service

Credential Management

Secure Credential Storage:

• FTP/SFTP credentials stored in .env file (restrict file permissions)
• Never commit .env to version control
• Rotate credentials regularly per security policy

File Permissions:

# Ensure .env file is not world-readable
chmod 600 /var/www/html/rconfig8/current/.env
chown www-data:www-data /var/www/html/rconfig8/current/.env

Credential Rotation:

1. Update credentials in .env file
2. Redeploy affected service (FTP or SFTP)
3. Update device configurations with new credentials or use {ftppassword} variables for automatic substitution

Audit and Monitoring

Upload Activity Monitoring:

• Review /srv/xftp/ regularly for unexpected files
• Monitor device file upload patterns for anomalies
• Check container logs for authentication failures or unusual access patterns

Log Review:

# Review FTP service logs
docker logs rconfig-ftp | grep -i failed

# Review SFTP service logs
docker logs rconfig-sftp | grep -i auth

# Check system logs for security events
sudo journalctl -u docker | grep -i error

Automated Alerts: Configure monitoring to alert on:

• Multiple authentication failures (potential brute force)
• Uploads from unexpected IP addresses
• Abnormally large file uploads
• Services stopping unexpectedly

---

Enterprise Deployment Considerations

Tip

Enterprise Support Available: Organizations with specific requirements beyond the standard Docker-based xFTP deployment can contact rConfig support for consultation on custom FTP configurations, non-Docker deployments, high-availability architectures, and enterprise integration scenarios. Our support team provides architecture guidance, implementation assistance, and ongoing operational support tailored to enterprise environments.

Non-Docker Deployments

While Docker provides simplified deployment, some organizations prefer native FTP services:

Reasons for Non-Docker Deployment:

• Existing enterprise FTP infrastructure
• Security policies prohibiting container usage
• Integration with enterprise authentication (LDAP, Active Directory)
• Specific compliance or audit requirements

Custom FTP Service Integration:

1. Deploy FTP/SFTP service using preferred method (native packages, appliances)
2. Configure upload directory to match rConfig expectations
3. Set XFTP_ROOT_DIR in .env to custom upload location
4. Ensure rConfig has read/write access to upload directory
5. Verify sweep task can process files from custom location

Enterprise Support Scope:

• Architecture review and recommendations
• Integration with existing infrastructure
• Custom authentication mechanisms
• High-availability and load balancing configurations
• Performance optimization for high-volume environments
• Compliance and security consulting

High-Availability Configurations

HA FTP Service Design:

• Load-balanced FTP/SFTP services with shared backend storage
• Active-passive failover for service continuity
• Distributed file processing across multiple rConfig nodes
• Centralized credential management and rotation

Shared Storage Requirements:

• NFS or clustered filesystem for /srv/xftp/ across rConfig instances
• File locking mechanisms to prevent processing conflicts
• Distributed sweep task coordination

Compliance and Regulatory Requirements

Data Retention: Configure automated archival and deletion policies:

• Define retention periods for uploaded files
• Automated archival to compliant long-term storage
• Secure deletion ensuring data is unrecoverable

Audit Trail: Comprehensive logging for compliance:

• All upload events logged with source IP, timestamp, filename
• Authentication attempts and failures recorded
• File processing and movement tracked
• Regular audit log review and reporting

Encryption at Rest: Uploaded files encrypted on disk:

• Filesystem-level encryption (LUKS, dm-crypt)
• Application-level encryption before storage
• Key management for encrypted storage

---

Related Documentation

• Configuration Backup Implementation - Understanding backup workflows
• Device Management - Managing device inventory and connectivity
• Scheduled Tasks - Configuring automated system tasks
• Commands Configuration - Setting up device command categories

---

Quick Reference

Service Deployment Commands

Install/Manage Services:

cd /var/www/html/rconfig8/current
php artisan rconfig:xftp-toggle

Check Service Status:

php artisan rconfig:xftp-toggle --status

Manual File Sweep:

php artisan rconfig:sweep-tftp-dir

Upload Command Templates

TFTP Upload:

copy <source-file> tftp://<rconfig-ip>/{deviceid}-<filename>

FTP Upload with Variables:

copy <source-file> ftp://{ftpusername}:{ftppassword}@<rconfig-ip>/{deviceid}-<filename>

SFTP Upload with Variables:

copy <source-file> sftp://{sftpusername}:{sftppassword}@<rconfig-ip>:<port>/{deviceid}-<filename>

Service Ports

Service	Default Port	Protocol	Authentication
TFTP	69	UDP	None
FTP	21	TCP	Username/Password
SFTP	2222 (configurable)	TCP/SSH	Username/Password (encrypted)

Directory Locations

Upload Directory: /srv/xftp/

Device Storage: Configured in rConfig device storage settings

Configuration File: /var/www/html/rconfig8/current/.env

Credential Variables

Available for use in device commands:

• {ftpusername} - FTP username from .env
• {ftppassword} - FTP password from .env
• {sftpusername} - SFTP username from .env
• {sftppassword} - SFTP password from .env
• {deviceid} - Device ID for file association

Troubleshooting Quick Checks

Service Not Running:

docker ps | grep rconfig
systemctl status docker

Files Not Processing:

ls -la /srv/xftp/
php artisan rconfig:sweep-tftp-dir

Upload Fails:

telnet <rconfig-ip> <port>
sudo firewall-cmd --list-all

Container Issues:

docker ps -a
docker logs rconfig-<service>

---

Summary

The xFTP Server provides flexible, secure file transfer capabilities for network devices through Docker-based microservices. By supporting TFTP, FTP, and SFTP protocols in parallel, rConfig accommodates diverse device capabilities while maintaining centralized file management and automated processing.

Key Capabilities:

• Multi-Protocol Support: TFTP, FTP, and SFTP services available simultaneously
• Automated Processing: Files automatically organized by device with version tracking
• Security Options: From unauthenticated TFTP to encrypted SFTP based on requirements
• Flexible Deployment: Docker-based by default with custom infrastructure support
• Scalable Architecture: Microservices design enables independent service management and scaling

Deployment Best Practices:

• Use SFTP for production environments requiring security
• Implement automated file uploads via command categories for consistency
• Monitor /srv/xftp/ directory to ensure processing efficiency
• Configure appropriate sweep task frequency for upload volume
• Apply network-level access controls to restrict upload sources

For enterprise deployments requiring custom FTP infrastructure, non-Docker implementations, or high-availability architectures, contact rConfig support for specialized consultation and implementation assistance.