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. Built on Docker microservices architecture, xFTP supports multiple protocols (TFTP, FTP, SFTP) with automated file processing and device-specific organization.

---

Understanding xFTP Services

What is xFTP?

xFTP (Extended File Transfer Protocol) is rConfig’s collective term for multiple file transfer protocols operating in parallel to serve different network device requirements and security policies. The xFTP Server enables network devices to upload files that fall outside standard configuration backup workflows:

Binary Files: Device firmware images, licensing files, cryptographic certificates, and other non-text content that cannot be captured via SSH/Telnet configuration retrieval.

Archive Files: Compressed archives (tar, zip, gzip) containing multiple files, logs, or configuration bundles that devices export as single packages.

Supplementary Data: VLAN databases, MAC address tables, routing table exports, or any device-generated files requiring centralized storage and version tracking.

Log Files: Device-generated logs, diagnostics, or troubleshooting outputs uploaded for analysis and retention.

Protocol Options

The xFTP Server supports three file transfer protocols, each addressing specific use cases and security requirements:

TFTP (Trivial File Transfer Protocol):

• Use Case: Legacy device compatibility, simple file transfers
• Security: No authentication or encryption (plaintext transmission)
• Transport: UDP-based (unreliable, no guaranteed delivery)
• Best For: Older network devices without FTP/SFTP support, low-security environments
• Port: 69 (standard)

FTP (File Transfer Protocol):

• Use Case: Authenticated file transfers with broad device support
• Security: Credential-based authentication (username/password)
• Transport: TCP-based (reliable delivery with error correction)
• Best For: Modern devices supporting FTP, environments requiring authentication
• Port: 21 (standard)
• Data Transfer: Active or passive mode support

SFTP (SSH File Transfer Protocol):

• Use Case: Secure, encrypted file transfers for sensitive environments
• Security: SSH-based encryption and authentication
• Transport: TCP-based over SSH (encrypted, authenticated, reliable)
• Best For: Security-conscious deployments, compliance requirements, sensitive data
• Port: Configurable (typically 2222 to avoid conflict with host SSH on port 22)
• Note: Can also service SCP (Secure Copy Protocol) connections

Tip

Protocol Selection Guidance: Use SFTP for production environments handling sensitive data. Use FTP when devices lack SFTP support but authentication is required. Use TFTP only for legacy devices without FTP/SFTP capabilities or in isolated lab environments.

Microservices Architecture

The xFTP Server implements each protocol as an independent Docker container, providing operational and architectural benefits:

Service Isolation: Each protocol runs in a dedicated container with allocated resources. TFTP, FTP, and SFTP operate independently—failures in one service don’t impact others or core rConfig functionality.

Parallel Operation: All three protocols can run simultaneously on the same rConfig server, enabling devices with different capabilities to upload files concurrently. A TFTP-only device and an SFTP-capable device can both transfer files without conflict.

Resource Management: Docker provides resource limits and allocation per container. High FTP traffic doesn’t starve TFTP or SFTP services of CPU, memory, or network bandwidth.

Simplified Deployment: Docker abstracts infrastructure complexity. Services deploy with single commands without manual FTP daemon configuration, SSH server setup, or TFTP listener management.

Version Control and Rollback: Container images provide versioned deployments. Service updates apply consistently, and rollback to previous versions is straightforward if issues arise.

---

How xFTP File Processing Works

File Upload and Storage

When network devices upload files to xFTP services, a multi-stage processing workflow ensures files are organized, versioned, and associated with the correct devices:

Stage 1: File Reception

Upload Initiation: Network device executes file transfer command (copy tftp, copy ftp, copy sftp) specifying rConfig server IP and target filename.

Protocol Handling: Docker container for the selected protocol (TFTP, FTP, SFTP) receives the connection and file transfer request.

Initial Storage: Uploaded files are stored in the centralized xFTP directory on the rConfig server:

/srv/xftp/

Temporary Holding: Files remain in /srv/xftp/ temporarily until the automated sweep process identifies and moves them to device-specific storage locations.

Stage 2: Automated File Processing

Scheduled Sweep Task: rConfig runs an automated task every 15 minutes (configurable) that scans the xFTP directory for uploaded files:

php artisan rconfig:sweep-tftp-dir

Device ID Detection: The sweep task examines each filename for a device ID pattern. Device IDs are numeric identifiers assigned to each device in rConfig (visible in the UI and database devices table, id column).

Filename Pattern Matching: Valid filenames must contain the device ID between the last / and a - character:

• Valid: vlan-1234.dat (device ID: 1234)
• Valid: /path/20003-config.log (device ID: 20003)
• Invalid: config1234.log (device ID not properly delimited)
• Invalid: 1234config.log (device ID not properly delimited)

File Organization: When a valid device ID is detected:

1. File moved from /srv/xftp/ to device-specific storage directory
2. Timestamp appended to filename for version tracking
3. File becomes visible on the device’s page in rConfig UI
4. Database record created linking file to device

Orphaned Files: Files without valid device IDs remain in /srv/xftp/ and are not processed. These require manual review and removal via the xFTP settings page or CLI.

Stage 3: File Presentation

Device View Integration: Successfully processed files appear in the device’s file table on the Device View page, alongside configuration backups and other device-specific content.

Version Tracking: Each upload creates a new timestamped file version, maintaining complete upload history for audit trails and troubleshooting.

File Actions: Users can view, download, or delete uploaded files directly from the device page, providing centralized management of all device-related content.

Note

Empty xFTP Directory: The /srv/xftp/ directory should remain empty at all times under normal operation. Files appearing in this directory are either awaiting processing by the next sweep cycle or are orphaned files lacking valid device IDs. Persistent files in /srv/xftp/ indicate processing issues or incorrect filename patterns from devices.

Manual Sweep Execution

While the automated sweep task runs every 15 minutes, administrators can trigger manual sweeps for immediate file processing:

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

# Expected output:
Found 1 valid file in TFTP directory.

Use Cases for Manual Sweeps:

• Immediate file processing after testing device uploads
• Troubleshooting upload workflows without waiting for scheduled task
• Verifying device ID patterns in filenames before production deployment
• Clearing xFTP directory after bulk device file uploads

---

Prerequisites

System Requirements

Docker Installation: xFTP microservices require Docker for container deployment and management. Docker must be installed and running on the rConfig server.

Supported Operating Systems:

• Ubuntu 20.04/22.04/24.04 LTS
• Rocky Linux 8/9
• RHEL 8/9
• CentOS 8/9

Network Connectivity:

• Internet access for Docker image downloads from Docker Hub (first-time setup)
• Network access from devices to rConfig server on configured xFTP ports
• Firewall rules permitting inbound traffic on TFTP (69), FTP (21), and SFTP (custom port) as needed

Disk Space:

• Docker images: ~500MB combined for all xFTP services
• File storage: Adequate space in /srv/xftp/ for uploaded files (depends on upload volume and retention policies)

Permissions: Root or sudo access required for Docker installation and container management.

Verifying Prerequisites

Check Docker Installation:

docker --version
# Expected output: Docker version 24.x.x or higher

Check Docker Service Status:

systemctl status docker
# Should show: active (running)

Verify Disk Space:

df -h /srv/xftp/
# Ensure adequate available space for uploaded files

Test Network Connectivity:

# From a network device, ping rConfig server
ping <rconfig-server-ip>

# Verify no firewall blocking target ports

---

Installing Docker

If Docker is not already installed on your rConfig server, the xFTP setup wizard provides automated Docker installation.

Automated Docker Installation

Navigate to the xFTP management interface or use the CLI command:

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

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:

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

File Actions

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

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

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.