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

Ready-made push commands

The templates repository carries device-side push command starters for Cisco IOS, NX-OS and ASA, FortiGate, F5, PAN-OS, Junos, HP and Aruba ProCurve, and MikroTik, each with the platform quirk that usually catches people out. See also the xFTP notes covering the inbound-only template and which placeholder variables rConfig substitutes into device commands.

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.

---

xFTP-only devices (inbound-only connectivity)

A device can use inbound-only configuration collection: it pushes its configuration to xFTP instead of waiting for rConfig to retrieve it. rConfig skips the normal outbound SSH, Telnet, script, or TL1 download session for that device. This is the opposite direction from the pull-based protocols covered in Device Connectivity & Backup, and it’s useful for devices that only support pushing files out, or that sit somewhere rConfig can’t initiate a session to.

Enabling it

There’s no device-level toggle or database flag for this. The connect.protocol value in the assigned connection template is the source of truth:

1. Open Inventory → Templates and use the built-in xFTP Inbound Only - No Outbound Connection template. Alternatively, create or edit a template and set its connect: block as follows:

   # rConfig connection template
   ## Edition: pro
   ## Status: untested-starter
   ## Tested-on: rConfig V8
   ## Docs: https://docs.rconfig.com/device-management/connection-templates/
   ## Community: https://github.com/rconfig/rConfig-templates
   ## Note: all free-text values must be wrapped in double quotes " "
   
   main:
     name: 'XFTP Inbound Only - No Outbound Connection' # For devices that push their config into rConfig via xFTP
     desc: 'Marks a device as XFTP-only (inbound). rConfig never connects out to it; config arrives via an xFTP upload and reachability comes from ping.'
   
   connect:
     timeout: 30 # Unused: no outbound connection is ever attempted for this protocol
     # xftp is the canonical inbound-only protocol value from rConfig Pro V8.3.2 onwards.
     # Releases before V8.3.2 accept only ftp, which stays accepted for templates already
     # in the field.
     protocol: xftp # Inbound-only device: skips SSH/Telnet/script/tl1 outbound connection entirely
     port: 21 # Unused: no outbound connection is ever attempted for this protocol

   This template also ships ready-made in the xFTP templates folder in our templates repository.

2. Save the template and assign it to the device through the normal template assignment workflow.

3. Configure the device to push its configuration to xFTP. Ensure the uploaded filename contains its rConfig device ID or matches an enabled file matching pattern.

The reference template ships at storage/app/rconfig/templates/xftp-inbound-only.yml, alongside built-in templates such as ios-ssh-noenable.yml. The value must appear under connect:; a template name containing “xFTP” does not make a device inbound-only. Because rConfig does not start a CLI download session for this protocol, SSH/Telnet authentication, prompt, and command settings do not participate in configuration collection.

protocol: ftp still works

xftp is the canonical value, used by the built-in template and by the community templates repository going forward. Existing templates that still declare protocol: ftp keep resolving as inbound-only exactly as before: rConfig accepts both spellings. There’s no need to edit templates already in production.

xFTP-only describes direction, not the upload transport

The protocol: xftp (or ftp) template value is the inbound-only marker. The device can still upload through any enabled xFTP service (FTP, TFTP, SFTP, or SCP). It does not have to use unencrypted FTP.

rConfig flags inbound-only status wherever templates or devices are listed: a small xFTP icon with an “xFTP-only (inbound) device” tooltip appears next to the template in Inventory → Templates and next to the device in the device list and device pickers. Use the xFTP filter button on the device list to show only inbound-only devices.

What happens during download runs

xFTP-only devices are omitted from task, tag, category, and device outbound-download selections. If an xFTP-only record reaches the download service by another path, rConfig stops before creating the outbound connection.

As a result, a skipped outbound run:

• does not attempt SSH, Telnet, script, or TL1 configuration collection;
• does not change the device to Config Failed (STATUS_CONFIG_FAILED); and
• does not send the database or email connection-failure notifications used for failed outbound downloads.

Changing an existing device to inbound-only requires assigning a template whose connect.protocol is xftp (or ftp). Changing the template back to an outbound protocol restores the normal download behavior; no device column or UI flag needs to be changed.

Status lifecycle and reachability

An xFTP-only device is tracked with two related signals:

• Ping reachability: rConfig queues an ICMP reachability check for enabled xFTP-only devices every 15 minutes. A successful ping sets the device to Reachable; a failed ping sets it to Unreachable. The queue worker and scheduler must be running for these periodic checks to execute.
• Inbound arrival: when the xFTP sweeper successfully matches and moves an uploaded file into the device’s storage, it sets the device to Reachable and updates last_seen. Use the device’s xFTP upload history to confirm that configuration delivery is current.

No separate xFTP-only status is introduced. The latest completed ping or successful inbound upload determines the displayed reachable/unreachable state, so these signals can appear to disagree with upload history:

• A device can show Reachable (ping succeeds) with no uploads recorded yet, for example before its first scheduled push, or if the push command on the device itself is broken.
• A device can show Unreachable after a successful upload if a later scheduled ping fails because ICMP is blocked. The successful upload remains in its history and its arrival time remains available through last_seen.

Ping status alone doesn’t confirm the push pipeline is working, and a blocked ping doesn’t mean uploads have stopped. Check the device’s upload history when in doubt. If uploads aren’t appearing at all, work through Files not appearing on the device page below. See Basic Connectivity Verification for general ping diagnostics.

---

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.
• “Unsupported connection protocol” on an outbound download: the assigned template’s connect.protocol isn’t a value rConfig recognizes. The error names the exact value it read and lists the supported protocols: check for a typo in the template’s connect: block (for example xtp instead of xftp).

---

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