Skip to content

TFTP Server

The TFTP server hands out files to devices on the local network, for example a fallback boot image for devices whose own firmware partition has failed, or configuration files for IP phones and similar equipment. It is read-only, so clients cannot upload files.

Files are served from a root directory, by default /var/lib/tftpboot. This directory is persistent on all supported boards and writable by admin users, so files can be placed there from the CLI or a shell. A directory on USB media, e.g., /media/usb/tftp, can be used instead.

Important

Only world-readable files are served. Files copied with the CLI copy command are made world-readable automatically, files copied from a shell must be given mode 0644 or similar.

Caution

TFTP has no authentication. Every file below the root can be read by any client that reaches the server, so never keep a saved system configuration there -- it carries password hashes, keys, and other secrets. Limit the server to the interfaces facing the clients.

Basic Configuration

admin@example:/> configure
admin@example:/config/> set tftp enabled true
admin@example:/config/> leave

The server listens on all interfaces by default. To restrict it to a subset, list the interfaces to serve on:

admin@example:/config/> edit tftp
admin@example:/config/tftp/> set interface eth1
admin@example:/config/tftp/> set interface eth2
admin@example:/config/tftp/> leave

When the firewall is enabled, the tftp service must also be allowed in the zone facing the clients, see Firewall.

Uploading Files

Files can be fetched to the TFTP root with the copy command from any of the supported remote sources, or copied from USB media. A directory destination keeps the source file name:

admin@example:/> copy tftp://192.168.1.1/fallback.itb /var/lib/tftpboot/
admin@example:/> copy /media/usb/phones.cfg /var/lib/tftpboot/
admin@example:/> dir /var/lib/tftpboot
/var/lib/tftpboot directory
fallback.itb   phones.cfg

Files are removed with the remove command, which asks for confirmation:

admin@example:/> remove /var/lib/tftpboot/phones.cfg
Remove /var/lib/tftpboot/phones.cfg, are you sure? (y/N)? y

Per-Client Directories

Some devices, IP phones in particular, expect a configuration file with a fixed name that differs per device. With client-directory set, the server first looks for the requested file in a subdirectory of the root named after the client, and falls back to the root itself if there is none:

admin@example:/config/tftp/> set client-directory mac

With this setting a request for config.xml from the device with MAC address 00:11:22:33:44:55 is answered with /var/lib/tftpboot/00-11-22-33-44-55/config.xml if that file exists, otherwise with /var/lib/tftpboot/config.xml. Use ip instead of mac to name the directories after the client IP address.

Network Boot

Devices that boot over the network learn the boot file name and TFTP server address from the DHCP server. See Network Boot in the DHCP server documentation for how to hand these out.

Monitoring

admin@example:/> show tftp
Root directory   : /var/lib/tftpboot
Interfaces       : all
Client directory : none

NAME          SIZE  MODIFIED        
fallback.itb  7.0M  2026-09-18 05:18
phones.cfg    812B  2026-09-17 12:00

The file list is the operational view of the root directory and shows only files the server can actually hand out. A file missing from the list is either not world-readable or outside the configured root.