TrueNAS Apps: Tutorials
Application maintenance is independent from TrueNAS version release cycles.
App versions, features, options, and installation behavior at time of access might vary from documented tutorials and UI reference.

TFTP Server

5 minute read.

Last Modified 2024-10-28 11:58 EDT

Documentation for applications within the Community train is created and maintained by members of the TrueNAS community. The TrueNAS Documentation Hub hosts but does not validate or maintain articles within this section.
Community contributions are highly encouraged! Please see Contributing to TrueNAS Application Documentation to learn how you can assist.

Needs Improvement
This community application tutorial is suspected to be out of date or inaccurate. Please help the TrueNAS community improve it or discuss these issues in the TrueNAS Community forum.

The new TFTP Server application provides Trivial File Transfer Protocol (TFTP) server functions. The TFTP Server application is a lightweight TFTP-server container in TrueNAS. It is not intended for use as a standalone container.

The app runs as root and drops privileges to the tftp (9069) user for the TFTP service. Every application start launches a container with root privileges. This checks the parent directory permissions and ownership. If it finds a mismatch, the container applies the correct permissions to the TFTP directories. If Allow Create is selected, the container also checks and chmods TFTP directories to 757 or to 555 if not checked. Afterwards, the TFTP container runs as root user, dropping privileges to the tftp (9069) user for the TFTP service.

First Steps

Configure your DHCP server for network boot to work.

To grant access to a specific user (and group) different from defaults, add the new non-root administrative user and note the UID and GID for this user.

To use a specific dataset or volume for files, create this in the Storage screen first.

Installing the TFTP Service App

You can install the application using all default settings, or you can customize setting to suit your use case.

To install the TFTP Server app, go to Apps, click Discover Apps. Either begin typing TFTP into the search field or scroll down to locate the TFTP Server application widget.

Figure 1: TFTP Server Application Widget

Click on the widget to open the *TFTP Server information screen.

Click Install to open the TFTP Server configuration screen.

Application configuration settings are presented in several sections. To find specific fields click in the Search Input Fields search field, scroll down to a particular section or click on the section heading on the navigation area in the upper-right corner.

After accepting or changing the default settings explained in the sections below, click Install to start the installation process. The TFTP Server application displays on the Installed applications screen when the installation completes.

Application Name Settings

Accept the default values or enter a name in Application Name. Accept the default Version.

TFTP Configuration Settings

Select the location of the TrueNAS server in Timezone.

Figure 5: TFTP Configuration Add Environment Variables

Select Allow Create to allow creating new files. This sets CREATE to 1 and MAPFILE to "". This changes the permissions of the tftpboot directory to 757, otherwise the tftpboot directory permissiong is 555.

Click Add to the right of Additional Environmental Variables to display the Name and Value fields. Enter the name as shown in the environment variables table below. Do not enter variables that have setting fields or the system displays an error.

TFTP Server Environment Variables

This table lists docker environmental variables for the TFTP Server (tftpd-hpa) application.

Variable	Default	Description
BLOCKSIZE	n/a	Specifies the maximum permitted blocksize.
CREATE	0	Use Allow Create to set to 1. 0 means only upload files if they exist. 1 allows creating new files.
MAPFILE	""	Specifies whether to use filename remapping. Enter as /mapfile or leave empty "" if not using a mapfile. If entering a mapfile, set ownership to uid/gid 9096.
PERMISSIVE	0	Performs no additional permission checks.
PORTRANGE	4096:32736	Force the server port number (transaction ID) to be in the specified range of port numbers. Docker container default range is 4096:32760.
REFUSE	""	Indicates that a specific RFC 2347 option should be accepted.
RETRANSMIT	1 second	Determines the default timeout in micro-seconds before the first packet retransmits.
SECURE	“1”	Changes root directory on startup.
TIMEOUT	900 seconds	Specifies the number of seconds to wait for a second connection before transmitting the server.
UMASK	“020”	Sets the umask for newly created files.
VERBOSE	“1”	Increases the logging verbosity of tftpd.
VERBOSITY	3	Sets the verbosity value from 0 to 4.

Network Configuration Settings

When selected, Host Network sets the app to use the default port 69, otherwise the default port is 30031.

To change the default port number, clear the Host Network checkmark to display the TFTP Port field. Enter a new port number in TFTP Port within the range 9000-65535. Refer to the TrueNAS default port list for a list of assigned port numbers.

Storage Configuration Settings

Storage sets the path to store TFTP boot files. The default storage type is ixVolume (Dataset created automatically by the system) where the system automatically creates a dataset named tftpboot. Select Host Path (Path that already exists on the system) to show the Host Path field. Enter or browse to select a dataset you created on the system for the application to use.