xFTP Server - TFTP, FTP, and SFTP for Network Device File Transfers

xFTP Server: Secure File Transfer for Network Devices

After reading this page, I can deploy and configure the rConfig xFTP server, choose the right protocol (TFTP, FTP, or SFTP) for my devices, and set up automated file uploads with device-matched processing and retention policies.

V8.1.2 release note

This release adds:

• Upload tracking in a new database table: xftp_uploads
• Retention and auto-clean targets: xftp_root and xftp_device_uploads
• File matching patterns to map filenames to devices (regex, prefix, suffix, contains, exact)
• Updated UI file tables: File name, Type, Device ID, File Size, Created, and Action columns with peek (text only), download, copy path, metadata info, and delete

All behavior described in this page applies from V8.1.2 unless explicitly noted as legacy.

---

How xFTP works

Network devices upload files via TFTP, FTP, or SFTP into a shared inbox directory (/srv/xftp/). A scheduled sweeper then moves matched files into each device’s xftpuploads/ directory and records the lifecycle in the xftp_uploads database table.

Protocols

Protocol	Port	Auth	Encryption	When to use
TFTP	69 (UDP)	None	None	Legacy or isolated environments
FTP	21 (TCP)	Username + password	None	Devices lacking SFTP support
SFTP/SCP	Configurable (e.g. 2222)	Username + password	SSH	Production and sensitive data

Tip

Use SFTP for any production environment. Use FTP when devices lack SFTP support but authentication is required. Reserve TFTP for isolated lab networks or legacy devices with no alternative.

Directory layout

• Inbox (raw uploads): /srv/xftp/
• Processed device storage (moved files):

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

Scheduled sweep

The sweeper runs on a configured schedule and moves matched inbox files to device storage:

php artisan rconfig:sweep-xftp-dir

Note

The sweeper may skip files modified in the last few seconds to avoid racing partially-uploaded files. Those files are picked up on the next run.

To trigger a sweep manually:

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

---

When to use xFTP

Use xFTP when devices need to push non-configuration files, binary data, firmware images, or archive content to rConfig for centralised storage. If you need only configuration backups, use the standard backup workflow instead.

---

Prerequisites

• Docker installed on the rConfig server (the setup wizard can install it automatically)
• Network firewall rules open for the protocol ports you plan to use (69/UDP, 21/TCP, and/or your chosen SFTP port)
• rConfig V8 installed and accessible
• Admin access to Settings in the rConfig UI

---

Managing xFTP services

Manage xFTP Docker microservices through the UI or CLI.

Web interface: Navigate to Platform → Network Services → XFTP

CLI:

php artisan rconfig:xftp-toggle

Check service status at any time:

php artisan rconfig:xftp-toggle --status

---

Deploying xFTP services

Note

Run all Artisan commands from the rConfig installation directory: cd /var/www/html/rconfig8/current

Run the interactive toggle command and choose which protocol to deploy:

php artisan rconfig:xftp-toggle

TFTP service deployment

TFTP provides basic file transfer without authentication. Suitable for legacy devices and isolated environments.

First-time setup

Initial deployment downloads the Docker image from Docker Hub (around 200 MB for TFTP). Subsequent deployments use the cached image and complete instantly.

1. Run php artisan rconfig:xftp-toggle and choose TFTP from the protocol list.

   

2. Docker pulls the TFTP image on first deployment.

3. The TFTP container starts automatically.

4. Verify the service shows TFTP running on port 69.

   

Default configuration: port 69 (UDP), no authentication, upload directory /srv/xftp/. Any device with network access to the rConfig server can upload files.

To stop: run php artisan rconfig:xftp-toggle, select TFTP, and confirm removal. Files already in /srv/xftp/ or device storage are not deleted.

---

FTP service deployment

FTP provides authenticated file transfer with credential-based access.

First-time setup

Initial deployment downloads the Docker image from Docker Hub (around 250 MB for FTP). Subsequent deployments use the cached image and complete instantly.

1. Run php artisan rconfig:xftp-toggle and choose FTP.

   

2. Enter the FTP username and password when prompted.

3. Docker pulls the FTP image on first deployment.

4. The FTP container starts with the configured credentials.

5. Verify the service shows FTP running on port 21.

   

Default configuration: port 21 (TCP), username and password authentication, active and passive transfer modes, upload directory /srv/xftp/.

Credential storage: FTP credentials are stored in .env and referenced in device commands using {ftpusername} and {ftppassword}. When redeploying, the wizard prompts to reuse existing credentials or enter new ones.

To stop: run php artisan rconfig:xftp-toggle, select FTP, and confirm removal. Credentials in .env are preserved.

---

SFTP/SCP service deployment

SFTP provides encrypted, authenticated file transfer over SSH. Use for production environments and sensitive data.

First-time setup

Initial deployment downloads the Docker image from Docker Hub (around 300 MB for SFTP). Subsequent deployments use the cached image and complete instantly.

1. Run php artisan rconfig:xftp-toggle and choose SFTP.

   

2. Enter the SFTP port (must not conflict with host SSH on port 22 — 2222 is a common choice).

3. Enter the SFTP username and password.

4. Docker pulls the SFTP image on first deployment.

5. The SFTP container starts with the configured port and credentials.

6. Verify the service shows SFTP running on your chosen port.

   

Default configuration: port configurable (recommended 2222, cannot be 22), SSH/TCP encryption, username and password authentication, upload directory /srv/xftp/. The same container handles both SFTP and SCP connections.

Port conflict warning

SFTP uses the SSH protocol, which defaults to port 22 on most systems. The SFTP microservice must use a different port to avoid conflicts with the host SSH daemon. Check availability first:

sudo netstat -tulpn | grep :2222
# No output means the port is free

SFTP vs SCP: SFTP is preferred for modern devices and supports directory listing and resumable transfers. SCP is simpler and suits legacy devices and scripting.

Connection syntax:

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

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

To stop: run php artisan rconfig:xftp-toggle, select SFTP, and confirm removal. Credentials and port settings in .env are preserved.

---

Uploading files from devices

File naming and device ID

For rConfig to associate an uploaded file with a device, the filename must include the device ID before a dash:

{deviceid}-filename.ext

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 (device ID not before the dash)
• ftp://server/{deviceid}config.log (no dash separator)

Find the device ID in the rConfig UI on the device list or device detail page. It is also available in the devices table (id column) and is automatically substituted when you use the {deviceid} variable in commands.

Manual upload examples

TFTP (Cisco IOS):

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

FTP (Cisco IOS):

Router#copy vlan.dat ftp://ftpuser:ftppass@192.168.1.131/1234-vlan.dat

Using credential variables (recommended):

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

SFTP (Cisco IOS):

Router#copy vlan.dat sftp://sftpuser:sftppass@192.168.1.131:2222/1234-vlan.dat

Using credential variables:

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

Tip

Use credential variables ({ftpusername}, {ftppassword}, {sftpusername}, {sftppassword}) in device commands rather than hardcoding credentials. rConfig substitutes the actual values from .env at execution time.

Automated uploads via command categories

Incorporate upload commands into rConfig command categories so files transfer automatically during device polling.

1. Navigate to Settings → Commands in the rConfig UI.

2. Create or open the command category used by the target devices.

3. Add the upload command with variables:

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

4. Assign the category to the relevant devices.

5. When rConfig runs a backup, the upload command executes automatically.

---

File matching patterns (V8.1.2+)

When filenames do not contain a numeric device ID, use pattern-based routing to map uploads to devices.

Where: Platform → Network Services → XFTP → File Matching Rules tab

Pattern types: regex, prefix, suffix, contains, exact

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

---

Viewing and managing uploaded files (V8.1.2+)

File Directory (raw /srv/xftp/ inbox)

Navigate to Platform → Network Services → XFTP → File Directory tab to see files physically present in /srv/xftp/ that are awaiting the sweep or were not yet matched to a device.

The table columns are: File name, Type, Device ID, File Size, Created, Action. rConfig infers file type (text, binary, archive) automatically.

Available actions per file: Download, Copy path, Peek (eye icon — text only, capped at 1 MB), Metadata info (info icon), Delete. A Delete all files button clears the entire inbox.

Device view: processed uploads

Navigate to Devices → [Device Name] and scroll to the uploaded files section.

The table shows a paginated, database-backed history of moved files. Actions are the same as the File Directory: download, copy path, peek (text only), metadata info, and delete.

V8.1.2 updates

• Smart file detection is included in this release.
• Text files can be opened directly in the browser via Peek (no download required).
• A metadata column has been added to the uploaded files table.

Click View All to access the full file management interface.

---

Backfilling upload tracking (V8.1.2+)

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

php artisan rconfig:xftp-backfill-uploads

# Dry run (no changes made)
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 (V8.1.2+)

xFTP retention integrates with the existing purge framework (settings_purge).

Targets:

Target	Covers	Default retention
xftp_root	Tracked inbox files (/srv/xftp/)	30 days
xftp_device_uploads	Tracked moved device uploads	90 days

Run via CLI:

# Run all purge targets
php artisan rconfig:data-purge

# Run only xFTP targets
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 only to files tracked in xftp_uploads. If you have existing untracked files, run the backfill command first.

---

Advanced configuration

Custom upload directory

Organizations can deploy their own FTP/SFTP services and configure rConfig to process files from a custom directory.

1. Edit .env to set the custom path:

   XFTP_ROOT_DIR=/path/to/custom/upload/directory

2. Create the directory with correct 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 rConfig can access it by running a manual sweep.

4. Point your external FTP/SFTP service to upload files into XFTP_ROOT_DIR.

Running multiple services

All three services can run simultaneously on separate ports. Deploy them one at a time using php artisan rconfig:xftp-toggle and selecting each protocol in turn.

Once deployed, assign protocols to device groups based on capability:

• Legacy switches: TFTP (port 69)
• Modern routers: FTP (port 21)
• Security appliances: SFTP (port 2222)

Security

Protocol comparison:

Protocol	Authentication	Encryption	Recommended for
TFTP	None	None	Isolated lab networks only
FTP	Username + password	None	Devices without SFTP
SFTP	SSH credentials	Full (SSH)	Production and compliance

Network-level restrictions:

# Limit 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

Credential management:

# Restrict .env file permissions
chmod 600 /var/www/html/rconfig8/current/.env
chown www-data:www-data /var/www/html/rconfig8/current/.env

To rotate credentials: update .env, redeploy the affected service, then update device configurations or rely on credential variables for automatic substitution.

---

Common gotchas

Common setup mistakes

• Files stuck in /srv/xftp/: Run php artisan rconfig:sweep-xftp-dir and confirm the filename matches the {deviceid}-filename.ext pattern or a configured File Matching Rule.
• Peek not working: Peek (eye icon) is text-only and capped at 1 MB. Download archives and binary files instead. Use the metadata info icon to inspect file details without downloading.
• SFTP port conflict: The SFTP container cannot use port 22 (reserved for host SSH). Choose a different port such as 2222 and verify it is free with sudo netstat -tulpn | grep :2222.
• Postgres duplicate key on xftp_uploads_pkey: (V8.1.2+) rConfig detects out-of-sync sequences (often from manual inserts), repairs the sequence automatically, and retries the insert.
• Retention not cleaning files: Retention applies to tracked rows only. Run the backfill command if files predate your upgrade to V8.1.2.

---

Troubleshooting

Files not appearing on the device page

1. Check the inbox for the file:

   ls -la /srv/xftp/

2. Verify the filename contains the device ID before a dash (e.g. 1234-vlan.dat).

3. Confirm the device ID exists in rConfig:

   mysql -u rconfig -p rconfig -e "SELECT id, device_name FROM devices WHERE id = 1234;"

4. Run a manual sweep:

   php artisan rconfig:sweep-xftp-dir

5. Check sweep logs for errors:

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

Upload failures

Service not running:

php artisan rconfig:xftp-toggle --status
php artisan rconfig:xftp-toggle  # restart if needed

Firewall blocking:

telnet <rconfig-server-ip> 69    # TFTP
telnet <rconfig-server-ip> 21    # FTP
telnet <rconfig-server-ip> 2222  # SFTP

# Open ports if blocked
sudo firewall-cmd --add-port=69/udp --permanent
sudo firewall-cmd --add-port=21/tcp --permanent
sudo firewall-cmd --add-port=2222/tcp --permanent
sudo firewall-cmd --reload

Authentication failure (FTP/SFTP):

grep -E 'FTP_USERNAME|FTP_PASSWORD|SFTP_USERNAME|SFTP_PASSWORD' /var/www/html/rconfig8/current/.env

# Test FTP manually
ftp <rconfig-server-ip>

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

Disk space:

df -h /srv/xftp/

Container fails to start

1. Check container logs:

   docker ps -a
   docker logs rconfig-tftp
   docker logs rconfig-ftp
   docker logs rconfig-sftp

2. Check for port conflicts:

   sudo netstat -tulpn | grep :69
   sudo netstat -tulpn | grep :21
   sudo netstat -tulpn | grep :2222

3. Check directory permissions:

   ls -la /srv/xftp/
   sudo chown -R www-data:www-data /srv/xftp/
   sudo chmod 755 /srv/xftp/

4. Restart Docker if needed:

   sudo systemctl restart docker
   sudo journalctl -u docker -n 50

After resolving the issue, remove the failed container and redeploy:

docker rm rconfig-<service>
php artisan rconfig:xftp-toggle

Sweep task not processing files

1. Navigate to Tasks → Scheduled Tasks and confirm the TFTP Directory Sweep task is enabled.

2. Check the task run history for errors.

3. Run manually and check output:

   php artisan rconfig:sweep-xftp-dir

4. Verify the Laravel scheduler cron is active:

   crontab -u www-data -l | grep schedule

---

What’s next

• Configure device backups - Set up automated configuration backups alongside xFTP file uploads
• Manage devices in rConfig - Add and configure the devices that will push files to xFTP
• Set up scheduled tasks - Configure the xFTP sweep frequency and other automated jobs