TFTP Broadband Reference

images/wsi-logo-broken.png

1. Introduction

TFTP Broadband is a high-performance TFTP server for corporations and broadband providers. Designed for high-volume environments such as VOIP networks, TFTP Broadband incorporates a unique Asynchronous Client Interleaving feature (ACI) which allows it to process thousands of simultaneous transfers without the overhead of threading.

TFTP Broadband has a wide array of features and enhancements that makes it attractive in mission critical environments.

1.1. Features

ACI architecture enables the server to handle extreme TFTP loads
Full support for IPv6, the next generation Internet protocol
View file transfers in realtime
Evaluate TFTP requests at runtime for dynamic access rights and dynamic file-overwrite protection
Evaluate TFTP requests at runtime and assign virtual roots to individual transfers (200 node version and larger)
Firewall friendly: requires only a single UDP port for all transfers
Handles very large files (does not suffer from 16/32MB file size bug)
Central point of administration for multiple TFTP servers and platforms
TFTP option extension support offers faster and more reliable transfers
Chroot-jail supports added security on Unix & Linux

1.2. What Is TFTP?

The Trivial File Transfer Protocol (TFTP) is a lightweight UDP/IP based protocol designed to support non-interactive file transfers, which makes it ideal for communication with embedded systems and network servers. TFTP is the recommended method for remote booting, upgrading or configuring various types of networked devices, including X-terminals, routers, switches, SIP-phones, print servers and more.

1.3. Standards Compliance

TFTP Broadband complies with the following RFC’s:

RFC 1350, Basic TFTP protocol
RFC 2347, Option Extensions
RFC 2348, Block size option
RFC 2349, Timeout & Transfer size Options

1.4. Supported Platforms

Linux

RHEL x86_64
RHEL i686

Solaris

Solaris 10 Ultra Sparc

Microsoft Windows

XP - W7, x86 or IA64

1.5. System Requirements

Recommended

Processor: x86, IA64 or Ultra Sparc
RAM: 2MB minimum
DISK: 50MB after operating system is installed
Networking: TCP/IP & Network Interface Card

1.6. Installing on Linux®

images/linux_install.png The software ships as a single tar.gz file containing RPMs for the gui and daemon. You may elect to install both packages, or just one or the other depending on your requirements.

The daemon is automatically registered and started during installation. To manually start or stop the daemon, use the /etc/init.d/tftptd init script.

1.7. Installing on Solaris®

images/cde_install.png Before installing this product you must ensure that the libgcc package is installed. The libgcc package can be obtained from www.sunfreeware.com.

The software ships as a single tar.gz file containing Solaris package for the daemon and the command line interface. The graphical interface is not a available on Solaris, but may be independently installed on a Windows or Linux workstation for managing your Solaris server.

To install the package, first untar the distribution file, then install the packages using the pkgadd command.

You may want to create a startup script to launch the daemon (tftptd) each time the machine is started.

1.8. Installing on Windows®

images/win_install.png

1.8.1. If you received a CD

Insert the CD into the drive. The installation should start automatically. Alternatively, run SETUP.EXE to begin installation.

1.8.2. If you received the software electronically

The TFTP Broadband software package is transmitted as a single file. Copy this file to a temporary directory on your hard drive, then double-click the file to start the installation process. Setup allows you to specify Full or Custom installations. If this is your first time installing the TFTP Broadband package you’ll want to choose a Full install.

After selecting the installation directory and program group, the setup program copies the necessary files to your hard disk and registers the services. Once this is complete you should configure the software by clicking the TFTP Broadband icon on your desktop.

1.9. Uninstalling the software

1.9.1. Linux

Use the distribution specific add/remove software utility or open a super-user terminal window and use rpm -e to remove each of the packages.

1.9.2. Solaris

Open a su terminal and use pkgrm to remove each of the packages.

1.9.3. Windows

Click the uninstall icon in the TFTP Broadband program group, or, alternately, use the Control Panel’s Add/Remove Programs applet.

2. Configuration

2.1. User Interface

The TFTP server is configured through the Server Manager user interface. This program allows you to easily connect to and manage multiple TFTP servers by presenting all available servers as nodes in the left column. Server Manager works equally well with local and remote TFTP servers, and can be installed separately on an administrator’s workstation.

There are two different views available once you are connected:

The Summary view (server node) shows information about the currently selected TFTP server.

The Activity view displays realtime information about ongoing transfers.

Activity View

2.2. Login

The Server Manager user interface requires the user to login before administering a selected TFTP server. All communication between the TFTP server and the user interface is encrypted using 56-bit Blowfish encryption to secure the communication.

Because there is no password when the software is first installed, leave the password box blank the first time you login. You can then set a new password by choosing Tools→Change Password… from the menu.

If you forget your password, refer to the Troubleshooting section for instructions on how to reset the login to accept an empty password.

2.3. Server Properties

The TFTP server’s main configuration settings are accessible from the Server Manager user interface. To access these settings, first connect to your server, then select the server name and choose Edit→Properties… from the main menu.

This rest of this section introduces you to security rules and covers techniques for using them.

2.4. Security Overview

The TFTP server is versatile and secure, and can be configured to safeguard TFTP traffic on your network. Using expressions, an administrator can set rules for:

Managing client access
Assigning a secure Virtual Root
Deciding on overwrite permissions

Since network environments and requirements differ, all parameters can be set independently. It’s also possible to bypass security rules altogether for smaller networks where high security is not a requirement.

This flow diagram illustrates how the security rules work together to provide a secure TFTP environment on the network:

Security Flow

Explanation:

Access: You can allow full access to the TFTP server, or set a conditional access rule using an expression.
Virtual Root Assignment: Restrict incoming clients to files in a secured directory using a single static Virtual Root, or assign Run-time roots, where incoming clients are assigned a virtual root based on criteria you specify.
Overwriting Files: Can be a simple yes or no setting, or an expression that decides at runtime based on criteria you define.

Other settings:

Option Extensions TFTP extensions offer clients faster and more reliable transfers. Note that your TFTP client must support option extensions. If in doubt, check the documentation for your client.

Error handling These parameters control the server’s behavior in the event of communication errors.

Data transfer port The TFTP server needs only two UDP port for all file transfers: the standard TFTP port 69, and the port you specify here. The default value for this setting is 0, which instructs the TFTP server to pick any available port on startup.

2.5. Overview

The TFTP server handles device configuration management. The server can deliver statically created configuration files or it can create configuration files dynamically by leveraging the domain membership system. The TFTP server can work in conjunction with the DHCP server to completely configure any kind of device that uses TFTP for initial configuration.

2.6. Configuration Files

A configuration file is a file that configures specific features of a CPE device during device initialization. The TFTP server can deliver either pre-built "static" configuration files or dynamically generated files that are built from one or more policies.

2.7. Policies

A TFTP policy is a collection of configuration settings. A single configuration is decomposed into a set of policies, where each policy holds a set of configuration values that enable certain features of the CPE. The TFTP server creates configuration files by gathering multiple policies, post-processing the configuration settings they hold (if necessary), and delivering the file to the CPE.

The system administrator will initially define a set of domains for each feature to be provisioned, then create one policy for each domain, and finally fill out the policies with device-specific configuration settings.

Changing a device configuration is then simply a matter of moving the device from one domain to another.

2.8. Virtual File Systems

The TFTP server supports a plugin-based virtual file system architecture. Virtual file systems allow the server to accept requests for files that do not necessarily exist, but instead are created or managed by a file system handler.

Virtual file systems are handled by plugins. When installing the TFTP server you can choose to install any combination of these virtual file systems:

tftp_fdmanager: A virtual file system that allows access to the real local file system
tftp_docsisfdmanager: A virtual file system that manages files by processing TFTP policies from a database

When requesting a file from the TFTP server, the file name may be prepended with a virtual file system designator in much the same way as a URL is prefixed with a protocol designator. Any requested file that does not contain a file system designator implicitly refers to the virtual file system handler for the local file system.

To download a file from a virtual file system, enter the full URL of the file into your TFTP client. Some examples of virtual file system requests are:

myfile.bin: Implicitly requests a file from the local file system
file://myfile.bin: Explicitly requests a file from the local file system
d://myfile.bin: Requests a DOCSIS® file from the database virtual file system
db://myfile.bin: Requests a regular ASCII file from the database virtual file system

2.9. Virtual Root

The virtual root is the root directory that will be used by the TFTP server to store files. Once you’ve populated this directory with files, your TFTP devices will be able to download them. When you upload files, they will be saved in this directory. The TFTP server will only allow access to files from the virtual root folder.

2.9.1. Virtual Root Security

The TFTP server is configured to limit clients to the assigned virtual root directory. Both rooted and non-rooted path names are always extended from the virtual root directory.

A runtime virtual root is a virtual root path specification that is dynamically calculated for each transfer request. To enable runtime virtual roots, use an expression for your virtual root folder instead of a literal path.

For Example

By using this sample expression as the virtual root path, the TFTP server will put uploaded files into the "upload" folder root and will look for download files in the "download" folder.

[$UPLOAD() ? "upload" : "download"]

The $UPLOAD function returns true or false. The conditional operator ? evaluates its left-hand side, $UPLOAD ,and returns the first value on the right hand side if $UPLOAD is true, or the second value on its right hand side if $UPLOAD is false.

The section on expressions covers all available functions.

2.10. Configuring

The TFTP server is versatile and secure, and can be configured to safeguard TFTP traffic on your network. Using the built-in expression evaluator, an administrator can set rules for:

managing client access
assigning a secure Virtual Root
deciding on overwrite permissions

Since network environments and requirements differ, all parameters can be set independently. It’s also possible to bypass security rules altogether for where high security is not a requirement. To access the server settings, go to the Settings menu in the user interface.

The security rules work together to provide a secure TFTP environment on the network. When a client attempts a TFTP upload or download, the server:

Checks the Access rule
Assigns a Virtual root
If uploading, checks the Overwrite permission

The Access rule is defined by setting the tftp.access.allow key in the system configuration. You can allow full access to the TFTP server by setting this value to true, or you can enable conditional access using an expression.

After the access rule is checked, the server then decides on the virtual root to be used during the transfer. The virtual root is set with the tftp.virtual_root configuration setting. You can specify a literal virtual root, such as /var/tftp, or a conditional virtual root using an expression.

If the client is attempting to upload a file that would overwrite an existing file on the server, the server checks to see if the client has overwrite permission. Overwrite permission is decided by the tftp.overwrite.allow configuration key. This setting can be a literal value (true or false) or an expression.

2.11. Binary and ASCII Transfers

The TFTP server accepts requests for read and write of files in either binary or ASCII mode (referred to as octet and netascii modes in the RFC standard). Files that are transferred in binary mode are transferred byte by byte, resulting in a mirror image of the original file. This mode should be used for transferring any file that is not in a readable text format.

Note that your TFTP client may report a number of bytes transferred that does not correspond to the actual file size when transferring a file in ASCII mode. This is due to the extra overhead associated with the netascii translation.

2.12. TFTP Clients

TFTP clients are typically embedded in hardware devices and may not be directly accessible to an operator or end user. An embedded system that requires the use of TFTP can often receive the address of its TFTP server and the name of the download file from the DHCP server. Refer to the DHCP server’s options for information about configuring an embedded system to perform TFTP downloads.

2.13. TFTP Option Extensions

TFTP option extensions are useful additional parameters that offer enhanced TFTP clients more efficient transfers. These extensions are only used if your TFTP client supports them.

Block size: An enhanced TFTP client can request a larger block size than the default 512 bytes. Having a larger block size can result in much faster data transfers. The TFTP server configuration allows you to disable this specific extension, or to set minimum and maximum allowable block size values.
Timeout: An enhanced TFTP client may request a specific timeout value if it has an indication of the network latency or reliability. The TFTP server configuration allows you to disable this specific extension, or to set minimum and maximum allowable timeout values.
Transfer size: An enhanced client may request to receive the size of a file before downloading. This is useful for clients that may not be able to receive files larger than a certain size.

2.14. Event Notifications

The TFTP server can be configured to notify external services when internal events occur. This external notification operates over the UDP protocol and is handled by the UDP Publisher plugin.

On startup, the UDP publisher reads a list of event subscribers from a configuration file and starts publishing events to those subscribers. The subscribers file consists of a set of subscriptions, where each subscription includes a destination ip:port (on which the subscriber must be listening) as well as a set of event classes the subscriber is interested in.

The UDP publisher is configured through the main configuration file with the settings shown here:

udp_publisher.latency = 300: The publish interval, in microseconds
udp_publisher.max_history = 500: The maximum number of historical events that cen be held. Events older than this are discarded.
udp_publisher.subscribers.file = udp_subscribers.txt: The name of the file which holds subscriber configurations

The default subscribers file is udp_subscribers.txt, and it’s located in the application’s var dir. (/var/lib/tftptd, /var/tftptd or the Windows program folder)

A sample UDP subscriber file is:

# notifies of changes to configuration, domains and policies
endpoint=10.0.0.1:5400
classes=config,domain,policy

# notifies of all changes except configuration
endpoint=10.1.2.20:5500
classes=*,!config

If no classes are specified, or the wildcard symbol (*) is specified, the subscriber will be notified of all server events. Receiving all event notifications from a loaded server can be taxing on the TFTP server. This configuration should be avoided if possible.

The tables below show the classes of events that can be published as well as the types of events types (event types in this case are actually more akin to verbs):

Table 1. Event Classes
Class	Description
*	All events
subscription	Any change to a udp subscriber’s state
config	Any change to the application’s configuration settings
transfer	Changes in the state of a file transfer

Table 2. Event Types (Verbs)
Type	Description
add	A new object has been added
del	An object has been deleted
modify	An existing object has been modified

When subscribing to the transfer class of events, each event will also contain keys and values for the following properties of the transfer:

Property	Description
id	The server’s unique id for this transfer
fd	The file descriptor used for this transfer
block	The current block number of the transfer
tsize	The size of the file being transferred
offset	The current position in the file from which data is being read
blksize	The block size in use for this transfer
timeout	The timeout in use for this transfer
port	The client’s port number
eof	`true` or `false` depending on whether or not the transfer has completed
overwrite	Whether or not the client is allowed to overwrite on upload during this transfer
start_time	The UTC time when this transfer started
ip	The ip address of the client
file	The fully qualified path name of the file being transferred
req_file	The name of the file the client requested when the transfer was initiated
protocol	The protocol used for this tranfer. This indicates the virtual file system being used.
state	The current state of the transfer: `need_ack`, `need_data`, `send_ack`, `send_data`, `complete`, `send_oack` or `unknown`
operation	Either `download` or `upload`
mode	Either `binary` or `ascii`
status	A status message concerning this transfer

2.14.1. Permanent Subscriptions

All subscribers listed in the udp_subscribers file are permanent subscribers. The server will continue to publish events to these subscribers even if the network indicates that the subscriber is not listening.

2.14.2. Temporary Subscriptions

A temporary subscription can be made through the command line interface. Temporary subscriptions are valid as long as the subscriber is receiving the server’s event messages.

2.14.3. Event notification format

A subscriber will receive event notifications from the server over the UDP protocol to the ip:port listed in the subscription. Each packet received corresponds to one event, and uses an ASCII-based key=value format. Multiple key/values are separated with a single newline character (\n).

A sample event from the TFTP server:

event_type=modify
event_class=domain
event_instance=My Domain
event_time=Mon Jul 28 14:45:26 CEST 2008

Some events may contain more key/value pairs, but the pairs listed above are guaranteed to always be present in any event notification. The order of key/value pairs is not guaranteed, and may change in the future.

2.15. Common Solutions

Logging Transfers

To log file transfers to an ASCII file, by date:

set the system.log.levels to audit
set the system.log.targets to file
set the system.log.target.file to [ $DATE() + ".log" ]

Disable Uploads

To allow only uploads to the TFTP server, place this expression in the tftp.access.allow setting:

[ $DOWNLOAD() ]

Upload vs. Download Roots

To specify one virtual root for uploads and another for downloads, place this expression in the tftp.virtual_root setting:

[ $DOWNLOAD() ? "downloads" : "uploads" ]

File Redirection

To redirect a transfer to a different file, call the $FILE.NAME(x) function in the tftp.preprocessor setting. For example:

[ $FILE.NAME() == "text.txt" && $FILE.NAME ("newfile.txt") ]

NAT Support

To enable support for TFTP through Network-Address-Translation, enter the value 69 for the tftp.transfer_port setting in your configuration file.

2.16. Expressions

TFTP expressions can be used to make runtime decisions about:

Access to the server
Ability to overwrite a file when uploading
The virtual root to be used for the transfer
The file name to use when creating an ascii log file

The expression evaluator module is used to parse expressions and execute them at runtime. Expressions can be used to implement business-specific logic that allows the server to vary its response or to make specific runtime decisions at key processing points.

An expression can be used at any place where the Build button images/build-expression.png is presented. Clicking this button opens the expression editor:

images/expression-editor.png

To denote that a value should be an expression instead of a literal, enclose the value in block characters [ ].

2.16.1. Data Types

The expression evaluator recognizes the following data types:

Type	Description
string	Strings are always enclosed in double quotes. `"My name is"` is an example of a string.
time	The time type is an ISO-standard string representation of a date specified in a rigid month/day/year format. `Oct 1 1992` is an example of a date.
ip address	An ip address is specified in dotted-decimal notation. `192.168.1.1` is an example of an ip address.
integer	An integer is signed number specified in decimal form. `-1000` is an example of an integer.
boolean	A boolean represents true or false. Booleans are specified using true or false.
byte sequence	A byte sequence is a sequence of 8-bit values that together represent a single unit. `00-A0-24-2F-10-26` is an example of a byte sequence.
endpoint	An endpoint is a string representation of an ip:port pair. `"192.168.1.1:80"` is an example of an endpoint.

2.16.2. Operator Reference

The following operators can be used in your expressions:

Operator	Description
( )	Used to change the natural order of precedence among the operators
[ ]	Opening and closing tags for an expression
'	Enclosing literal operands forces interpretation as a native data type
+	addition
-	subtraction
/	division
*	multiplication
<	less than
>	greater than
⇐	less than or equal
>=	greater than or equal
==	is equal
!=	is not equal
? :	conditional if…else
&&	logical AND
\|\|	logical OR
!	logical NOT
&	bitwise AND

bitwise OR	+
bitwise XOR	^
bitwise inverse	-

2.16.3. Function Reference

The expression evaluator supports a wide range of functions that you can use in your expressions.

Date and Time

$DATE ([format])

Arguments: Optional ISO-standard strftime arguments
Returns: Current date as a string
Description: This function returns the current date. The optional format argument allows you to specify an ISO-C strftime format for the returned value. Information about strftime can be found at various sites on the Internet.

Examples

$DATE ()

Returns a string of the form "2002-01-25".
$DATE ("%c")

Returns a string with date and time in the current locale format, e.g. "Thu Jul 25 16:56:18 CEST 2007".

$YEAR ([format])

Arguments: Optional ISO-standard strftime arguments
Returns: Current year as a string
Description: This function returns the current year. The optional format argument allows you to specify an ISO-C strftime format for the returned value. Information about strftime can be found at various sites on the Internet.

Examples

$YEAR ()

Returns a string of the form "2007".
$YEAR ("%y")

Returns a string containing the year without century, e.g. "07".

$MONTH ([format])

Arguments: Optional ISO-standard strftime arguments
Returns: Current month as a string
Description: This function returns the current month. The optional format argument allows you to specify an ISO-C strftime format for the returned value. Information about strftime can be found at various sites on the Internet.

Examples

$MONTH ()

Returns a string of the form "January".
$MONTH ("%b")

Returns a string containing the abbreviated month name, e.g. "Jan".

$DAY ([format])

Arguments: Optional ISO-standard strftime arguments
Returns: Current month as a string
Description: This function returns the current day of the week. The optional format argument allows you to specify an ISO-C strftime format for the returned value. Information about strftime can be found at various sites on the Internet.

Examples

$DAY ()

Returns a string of the form "Thursday".
$DAY ("%j")

Returns a string containing the julian day, e.g. "206".

$TIME.UTC ()

Arguments: None
Returns: Current UTC time as an integer
Description: This function returns the current UTC (GMT) time as an integer.

Examples

$TIME.UTC()

Returns an integer representing the current UTC time.

$TIME.FORMAT.UTC (integer, [format])

Arguments: Current UTC time as an integer
Returns: Current UTC time as a string
Description: This function returns the current UTC time as a string. The optional format argument allows you to specify an ISO-C strftime format for the returned value. Information about strftime can be found at various sites on the Internet.

Examples

$TIME.FORMAT.UTC($TIME.UTC())

Returns a string of the form "04:58:26 PM".

$TIME.FORMAT.LOCAL (integer, [format])

Arguments: Current UTC time as an integer
Returns: Current local time as a string
Description: This function returns the current local time as a string. The optional format argument allows you to specify an ISO-C strftime format for the returned value. Information about strftime can be found at various sites on the Internet.

Examples

$TIME.FORMAT.LOCAL($TIME.UTC())

Returns a string of the form "04:58:26 PM".

File IO

$FILE.EXISTS (file)

Arguments: File name as a string
Returns: true if the file exists, false otherwise
Description: This function checks for the existence of a file on the local file system.

$VALUE (file,key)

Arguments

File name as a string, key to search on as a string

Returns

The value associated with the key

Description

This function retrieves a single value from a file, using the key argument as an index. The format of the file is:

    <default>=some value
    key1=some other value
    key2=yet another value
    ...

The key and value can be any data type. The special <default> key can also be listed in this file. If it exists, all non-matching lookups return this value.

Examples

$VALUE ("valid_macs.txt",$HWADDR ())

This expression implies that your file uses hardware addresses as the key.

Conditional

$IF (value,result1,result2)

Arguments: Any values
Returns: result1 or result2 depending on whether value evaluates to true or false
Description: This function is the equivalent of an if…then…else construct.

Examples

$IF (true,"yes","no")

Returns the string "yes".

$COND (expression,expression,…)

Arguments

Any number of sub-expressions

Returns

The first true sub-expression, or the last false if all sub-expressions are false.

Description

This function is somewhat similar to the LISP COND function. The first sub-expression that returns any valid value except false will be the return value of this function. The invalid data type always evaluates to false, so a function that returns invalid does not stop the processing of sub-expressions.

Generally the last subexpression listed should be the default value in case all other subexpressions are false.

Examples

$COND ($STARTSWITH ("haystack","hello"),STARTSWITH("haystack","hay")

Returns the string "hay".

Type Conversion

$BOOL (value)

Arguments: Any value
Returns: true or false
Description: This function converts any type to a boolean result.

Examples

$BOOL ("true")

This returns a boolean value of true.

$INT (value)

Arguments: Any value
Returns: integer
Description: This function attempts to convert value to an integer. value can be any data type, but the conversion is not guaranteed to succeed because the type or format of value may not facilitate conversion.

Examples

$INT ("206")

Returns an integer whose value is 206.

$IP (value)

Arguments: Any value
Returns: ip address
Description: This function attempts to convert value to an ip address. value can be any data type, but the conversion is not guaranteed to succeed because the type or format of value may not facilitate conversion.

Examples

$IP ("192.168.1.1")

Returns an IP address having the value 192.168.1.1.

$BYTES (value)

Arguments: Any value
Returns: byte sequence
Description: This function attempts to convert value to a byte sequence. value can be any data type, but the conversion is not guaranteed to succeed because the type or format of value may not facilitate conversion.

Examples

$BYTES ("00-A0-24-2F-10-26")

Returns a sequence of bytes having the value 00-A0-24-2F-10-26.

$STR (value, [delimiter])

Arguments: Any value
Returns: string
Description: This function converts value to a string. It is always possible to convert a non-string type to a string. Use the optional delimiter argument to specify your own delimiter for data types that support them.

Examples

$STR (00-A0-24-2F-10-26)

Returns a string whose value is "00-A0-24-2F-10-26".
$STR ($HWADDR(),"_")

Returns a string whose value is "00_A0_24_2F_10_26".

$TEXT(bytes)

Arguments: Byte sequence
Returns: string
Description: This function converts a byte sequence to a human-readable string. This function is not the same as the $STRING function, which simply gives a text representation of the bytes.

Examples

$TEXT ('68-65-6C-6C-6F-00')

Returns a string whose value is "hello".

String Manipulation

$UCASE (string)

Arguments: source string
Returns: string in upper case
Description: This function returns the input string as all upper case. If this function is called with an argument that is not of type string, the argument is returned unmodified.

Examples

$UCASE ("hello, world")

Returns a string whose value is "HELLO, WORLD".

$LCASE (string)

Arguments: source string
Returns: string in lower case
Description: This function returns the input string as all lower case. If this function is called with an argument that is not of type string, the argument is returned unmodified.

Examples

$UCASE ("HELLO, WORLD")

Returns a string whose value is "hello, world".

$LEFT (string, count)

Arguments: source string, number of elements
Returns: string
Description: This function returns the left-most count elements from string. The string argument need not be of type string; it may be any type that can be converted to a string.

Examples

$LEFT ("hello, world",5)

Returns a string whose value is "hello".
$BYTES ( $LEFT ('00-A0-24-2F-10-26',5) )

The result is a hardware address containing two bytes, 00 and 0A.

$RIGHT (string, count)

Arguments: source string, number of elements
Returns: string
Description: This function returns the right-most count elements from string. The string argument need not be of type string; it may be any type that can be converted to a string.

Examples

$RIGHT ("hello, world",5)

Returns a string whose value is "world".
$BYTES ( $RIGHT ('00-A0-24-2F-10-26',5) )

The result is a hardware address containing two bytes, 00 and 0A.

$MID (string, count, pos)

Arguments: source string, number of elements, starting position
Returns: string
Description: This function returns count elements from string, starting at position pos. The pos argument specifies the zero-based index of the starting character.

Examples

$MID ("hello, world",1,4)

Returns a string containing "ello".
$MAC ( $MID (00-A0-24-2F-10-26,3,5) )

The result is a hardware address containing two bytes, A0 and 24.

$LEN (value)

Arguments: any value
Returns: integer
Description: This function computes the length of the input value, in bytes

Examples

$LEN ("hello, world")

Returns the integer valule 12.

$INSTR (string, substring)

Arguments: string, search string
Returns: integer
Description: This function searches string for the first occurence of substring and returns the zero-based index of the position at which substring appears in string. Returns -1 if substring doesn’t appear in string.

Examples

$INSTR ("hello, world","wo")

Returns the integer valule 7.

$BASE64.ENCODE (byte sequence)

Arguments: byte sequence
Returns: string
Description: This function encodes the byte sequence argument as a base-64 string.

Examples

$BASE64.ENCODE (01-11-11-11-11-11-11)

Returns a string containing "AREREREREQ==".

$BASE64.DECODE (string)

Arguments: string
Returns: byte sequence
Description: This function decodes the string from base-64 to a byte sequence.

Examples

$BASE64.DECODE ("AREREREREQ==")

Returns the byte sequence 01-11-11-11-11-11-11.

$STARTSWITH (haystack, needle)

Arguments: string, string
Returns: string or invalid
Description: This function returns needle if haystack begins with needle, otherwise it returns invalid. This function is useful in conjunction with the LISP-style COND function for creating flow control.

Examples

$STARTSWITH ("haystack","hay")

Returns the string "hay"

Encryption and Decryption

$ENCRYPT (byte sequence)

Arguments: byte sequence
Returns: byte sequence
Description: This function encodes the byte sequence with the server’s shared system key. The encoded value is an even multiple of 8 bytes with an 8-bit length prefix.

Examples

$ENCRYPT (01-A0-24-20-2F)

Returns a byte sequence representing the encrypted input argument.

$DECRYPT (byte sequence)

Arguments: byte sequence
Returns: byte sequence
Description: This function decodes the byte sequence with the server’s shared system key. The length of the input argument must be an even multiple of 8 bytes with an 8-bit length prefix.

Examples

$DECRYPT (01-A0-24-20-2F)

Returns a byte sequence representing the unencrypted input argument.

$SENCRYPT (string)

Arguments: string
Returns: byte sequence
Description: This function encodes the string argument with the server’s shared system key. The encoded value is an even multiple of 8 bytes with an 8-bit length prefix.

Examples

$SENCRYPT ("hello, world")

Returns a byte sequence representing the encrypted string.

$SDECRYPT (byte sequence)

Arguments: byte sequence
Returns: string
Description: This function decodes the byte sequence with the server’s shared system key. The length of the input argument must be an even multiple of 8 bytes with an 8-bit length prefix.

Examples

$SDECRYPT (01-A0-24-20-2F)

Returns the decrypted string.

$MD5 (byte sequence)

Arguments: byte sequence
Returns: byte sequence
Description: This function computes an MD5 hash of the input argument.

Examples

$MD5 (01-A0-24-20-2F)

Returns the md5 hash.

Miscellaneous

$USLEEP (usec)

Arguments: integer
Returns: nothing
Description: This function causes the server to pause for usec microseconds.

Examples

$USLEEP (1000)

Pauses for 1000 microseconds and returns no value.

$EVAL (string)

Arguments: any valid expression syntax
Returns: result of expression execution
Description: This function parses and executes the input string as an expression.

Examples

$EVAL ("DATE()")

Calls the $DATE() function and returns its value.

$LOG (value)

Arguments: any value
Returns: nothing
Description: This function prints an audit message in the system log containing value.

Examples

$LOG ("Hello, World")

Logs "Hello, World" to the system log.

$MATCH (haystack, needle)

Arguments: A haystack and a needle
Returns: haystack if needle is found, otherwise unknown
Description: This function performs wildcard matching on haystack using needle. The result can always be evaluated as a boolean, but in some cases it may be preferable to use the native result type such as with the COND function.

Examples

$MATCH ("Hello, World","Hello*")

Returns "Hello, World".

$UNKNOWN ()

Arguments: None
Returns: The unknown data type
Description: This function returns data type unknown. This can be useful to explicitly induce an expression to fail.

Examples

$UNKNOWN ()

Returns the unknown data type.

Identification

$SRC.HOSTNAME()

Arguments: None
Returns: string
Description: This function returns the unqualified name of the host requesting service from this TFTP server. This function can cause a perform degradation because it performs a reverse DNS lookup.

Examples

$SRC.HOSTNAME ()

The result is the short name of the host requesting service.

$SRC.FQDN()

Arguments: None
Returns: string
Description: This function returns the fully qualified name of the host requesting service from this TFTP server. This function can cause a perform degradation because it performs a reverse DNS lookup.

Examples

$SRC.FQDN()

The result is the fully qualified name of the host requesting service.

$SRC.IP()

Arguments: None
Returns: ip address
Description: This function returns the ip address of the host requesting service from this TFTP server.

Examples

$SRC.IP ()

The result is the ip address of the host requesting service.

$SRC.PORT()

Arguments: None
Returns: integer
Description: This function returns the port number in use by the host requesting service from this TFTP server.

Examples

$SRC.PORT()

The result is the port number used by the remote host.

$DST.IP()

Arguments: None
Returns: ip address
Description: This function returns the ip address of the interface on which the transfer request was received. Unless you specifically configure an address using the tftp.engine.listen_on setting in the configuration file, the returned address will always be zero.

Examples

$DST.IP ()

The result is the ip address on which the transfer request was received.

$DST.PORT()

Arguments: None
Returns: integer
Description: This function returns the port number on which the initial transfer request was received. Unless you specifically configure a port using the tftp.engine.listen_on setting in the configuration file, this value will always be zero.

Examples

$DST.PORT()

The result is the port on which the initial transfer was received.

$FILE.NAME([optional name])

Arguments: None or string
Returns: string or nothing
Description: When called with no arguments, this function returns the name of the file requested by the TFTP client. When called with a string argument, this function changes the name of the file requested by the TFTP client.

You can use this function in the tftp.preprocessor expression to dynamically redirect clients to a different file.

Examples

$FILE.NAME()

The result is the name of the file requested by the TFTP client.
$FILE.NAME(somefile)

Changes the requested file name to somefile.

$FILE.FQPN()

Arguments: None
Returns: string
Description: This function returns the fully qualified path name of the file to be used in the transfer.

Examples

$FILE.FQPN()

The result is the fully qualified name of the file to be transferred.

$FILE.SIZE()

Arguments: None
Returns: integer
Description: This function returns the size of the file to be transferred.

Examples

$FILE.SIZE()

The result is the size of the transfer file.

$TSIZE()

Arguments: None
Returns: integer
Description: This function returns the transfer size reported by the TFTP client. If no transfer size was provided, this function returns 0.

Examples

$TSIZE()

The result is the size of the file to be transferred.

$BLKSIZE()

Arguments: None
Returns: integer
Description: This function returns the block size requested by the TFTP client. If no block size was requested, this function returns the default size of 512.

Examples

$BLKSIZE()

The result is the block size requested.

$TIMEOUT()

Arguments: None
Returns: integer
Description: This function returns the timeout requested by the TFTP client. If no timeout was was requested, this function returns the system default timeout.

Examples

$TIMEOUT()

The result is the block size requested.

$BINARY()

Arguments: None
Returns: boolean
Description: This function returns true if the transfer is to use binary mode, false if the transfer is to use ASCII mode.

Examples

$BINARY()

The result is true or false.

$ASCII()

Arguments: None
Returns: boolean
Description: This function returns true if the transfer is to use ASCII mode, false if the transfer is to use binary mode.

Examples

$ASCII()

The result is true or false.

$UPLOAD()

Arguments: None
Returns: boolean
Description: This function returns true if the transfer is an upload, false if the transfer is a download.

Examples

$UPLOAD()

The result is true or false.

$DOWNLOAD()

Arguments: None
Returns: boolean
Description: This function returns true if the transfer is a download, false if the transfer is an upload.

Examples

$DOWNLOAD()

The result is true or false.

Database Inspection

$DB.KEYVALUE(class, subclass, key)

Arguments: A class, subclass and key. class and subclass can be any value, and key should be unique within class and subclass unless you explicitly want multiple values for a single key.
Returns: The value associated with the key
Description: This function allows you to find a value associated with a key in the associations table. Associations are useful for assigning arbitrary values for use by the server.

The value stored in an association is always a string, but the return value of this function will be automatically converted to the required data type where possible.

Examples

$DB.KEYVALUE ("geolocation","gps",$RELAY.IP())

The result is a string containing the gps coordinates of the relay agent.
$DB.KEYVALUE ("VLAN","VLAN-ID",$HWADDR())

Returns a vlan identifier for the specified hardware address.

$DB.KEYVALUE.EXISTS(class, subclass, key, return)

Arguments: A class, subclass, key and return value
Returns: return if the association exists, otherwise unknown
Description: This function allows you to check if an association exists. It does not return the value of the association, but rather it returns return if the association exists.

Examples

$DB.KEYVALUE.EXISTS ("VLAN","VLAN-ID",$HWADDR(),16777215)

Returns 16777215 if the association exists, otherwise unknown.

$DB.KEYVALUE.MANAGED_RANGE(class, subclass, key, start, end)

Arguments: A class, subclass and key for creating and managing associations. Start and end values for the range to be created and managed.
Returns: The value associated with the key. If no value is associated, one is created.
Description: This function lets the server manage associations for you. By specifying a start and end range, the server can create associations as needed and return the value. If an association exists but is disabled, this function returns unknown.

Examples

$DB.KEYVALUE.MANAGED_RANGE ("VLAN","VLAN-ID",$HWADDR(),0,100)

Returns a persistent vlan id between 0 and 100, inclusive.

2.17. Performance Tuning

The TFTP server includes many configuration settings that can be used to increase the performance of the server. Changing these settings can result in drastic performance improvements, but care should be taken to keep the system as a whole in balance. In particular, all high throughput sub-systems should be tuned to process data fast enough to keep up with the other high throughput sub-systems.

One tell-tale sign of a sub-system not keeping up with another sub-system is when your system event log shows the error "Failed to send command X to task Y. Command queue overflow."

2.17.1. Engine

The TFTP server is designed for extremely low latency, but generating dynamic configuration files detracts from the server’s performance. The fastest possible speed is obtained with static configuration files.

2.17.2. Hardware

We have specific hardware recommendations (available separately), but in general the following specifications should be considered:

CPU speed
Number of CPUs and CPU cores
Hard drive throughput
Amount of RAM
L1 and L2 cache size
Number of memory controllers
NIC speed

All of these factors make a difference in the speed of the TFTP engine.

2.17.3. Software

Linux® and Solaris® perform better than Windows®
Other processes should minimize use of CPU and memory
Real hardware is faster than virtualized hardware

2.18. System Configuration

The TFTP server stores process-wide configuration settings in an ASCII test file. Most of these settings are available through the user interface, but some can only be accessed by directly editing the text file with an external editor. If you edit this file with an external editor you must restart the TFTP server process.

On Windows: The configuration file is located in the TFTP server’s program directory
On Linux: The configuration file is located under the /etc/tftpt directory
On Solaris: The configuration file is located under the /usr/local/etc/tftpt directory

It’s possible to tell the service to use a different configuration file by passing a command line parameter when starting the service. See the Service Startup section for more information.

The table below shows the complete set of configuration file settings for the TFTP server.

Table 3. Configuration Settings
Key	Data Type	Description
rconsole.encryption	boolean	When true, specifies that the remote console should encryption all traffic.
rconsole.listen_on	endpoints	A list of address:port endpoints the remote console should listen on.
rconsole.password	byte sequence	The administrator password, in encrypted form.
rconsole.port	integer	The default port the remote console should listen on.
rconsole.private_key_path	string	The path to the private key file.
rconsole.max_select_count	integer	Specifies the maximum number of records that can be returned in a command line query.
rconsole.force_commit_after_select	boolean	When true, forces a commit after every select. The default is false.
system.db.path	string	The path where the database is located.
system.db.cache_buffers	integer	The number of cache buffers to use for database access.
system.db.name	string	The name of the database this application should use.
system.db.page_size	integer	The page size to use (in bytes) when connecting to the database.
system.db.password	string	The password to use when connecting to the database.
system.db.secondary_files.count	integer	The maximum number of secondary files the database should use (if supported by the database).
system.db.soft_vs_hard_commit_ratio	integer	The maximum soft commits to the database before a hard commit is required.
system.db.statements.file	string	The path name of the file containing SQL select statements to be precompiled.
system.db.table_groups.file	string	The name of the file containing mappings between SQL tables and precompiled statement groups.
system.db.user	string	The user name to use when connecting to the database.
system.db.versions_path	string	The path containing the dsql version files.
system.limits.max_open_files	integer	The maximum number of files that may be opened at one time.
system.log.facility	string	The facility with which syslog messages are logged.
system.log.levels	string	A list of names specifying the types of messages to log (error,warning,info,audit,debug,verbose).
system.log.targets	string	A list of output devices for logging (stdout,eventlog,rsyslog,file).
system.log.target.file	string	The fully qualified path to a log file. Used when system.log.targets includes file.
system.log.target.rsyslog	endpoint	The hostname or address of a remote syslog server. Used when system.log.targets includes rsyslog.
system.plugins	string	A list of plugins this process should load. This can be any combination of directories, relative paths or fully qualified paths.
system.priv.chroot_path	string	The path to use when changing the process root.
system.priv.gid	integer	The group id this process should assume.
system.priv.uid	integer	The user id this process should assume.
system.shared_key	byte sequence	A secret key used to authenticate cooperating servers.
system.storage.path	string	The path to use for general-purpose storage.
udp_publisher.latency	integer	The interval, in msec, at which the UDP publisher should publish historical events.
udp_publisher.max_history	integer	The maximum number of historical events the UDP publisher may hold at any time.
udp_publisher.subscribers.file	string	The name of a file that holds a list of subscribers to receive event notifications over udp.
ipv6.enable	boolean	When true, the server’s general communication subsystems will attempt to use ipv6 if available.
provisioner.account.name	expression	An expression that produces an account name for use by the provisioner.
tftp.virtual_root	string/expr	The virtual root directory.
tftp.virtual_root.enforce	boolean	Deprecated; vroot is always enforced.
tftp.transfer_port	integer	The port on which to multiplex tftp file transfers.
tftp.overwrite.allow	boolean/expr	Whether or not an upload may overwite an existing file.
tftp.access.allow	boolean/expr	Whether or not a given client is allowed access to this service.
tftp.upload.delete_partial	boolean	Whether or not to delete partial files after a failed upload.
tftp.upload.create_paths	boolean	Whether or not the server will create any needed paths in order to accept an upload.
tftp.upload.permissions	integer	The permissions to be set for an uploaded file.
tftp.timeout	integer	The default timeout to use when transferring files.
tftp.min_timeout	integer	The minimum timeout a client is allowed to negotiate.
tftp.max_timeout	integer	The maximum timeout a client is allowed to negotiate.
tftp.min_blocksize	integer	The minimum block size a client is allowed to negotiate.
tftp.max_blocksize	integer	The maximum block size a client is allowed to negotiate.
tftp.max_retransmits	integer	The maximum number of retransmits before aborting a transfer.
tftp.allow_timeout_option	integer	Whether or not a client is allowed to negotiate for a timeout value.
tftp.allow_blocksize_option	integer	Whether or not a client is allowed to negotiate for a block size value.
tftp.allow_tsize_option	integer	Whether or not a client is allowed to receive the file size before starting a download.
tftp.preprocessor	string/expr	Expressions for modifying client requests at runtime.
tftp.massage_filenames	boolean	Whether or not the server should check for suspicious-looking file names.
tftp.engine.listen_on	string	A list of endpoints the tftp engine should listen on.
tftp.engine.port	integer	The default port the engine should listen on if one is not specified.
tftp.fdm.db.docsis_defs	string	An alternate directory for locating docsis definition files.

2.19. Command-line Reference

The TFTP server package includes tftpti, a utility that provides a remote command line interface for the TFTP server. You can use tftpti to remotely administer most aspects of the TFTP server, including provisioning devices.

The tftpti program defaults to connecting to the TFTP server on localhost, but can also be used to connect to a TFTP server across a network. Run tftpti --help for a list of available arguments.

Once connected, the server accepts single or multi-line text commands and issues responses. To issue a command, simply type the command on a line and press ENTER on a new line to have the command executed.

Commands come in three forms: commands without arguments, commands with one argument, and multi-argument commands.

Commands without an argument can be executed by simply typing in the command name and pressing ENTER on a new line, as shown below:

info
[ENTER]

Commands with one argument usually include the argument as part of the command. The admin_password command is an example of this:

admin_password=mynewpassword
[ENTER]

Commands that can potentially accept multiple arguments are specified with the command first, followed by zero or more arguments. For example, the set_properties command accepts multiple arguments:

set_properties
system.log.targets=file
system.log.target.file=myfile.log
[ENTER]

The server always responds after each command with a set of key=value pairs. When the response includes multiple records, each record is delimited by a dash character (-) on a line by itself.

The server always appends a return code to the end of its output using a key=value pair. For example, when an operation succeeds, the last data returned is code=ack. If an error occured during processing, the server code=nak and message=x, where x is an error message.

The rest of this chapter contains documentation for all commands the TFTP server accepts.

2.19.1. Commands

get_properties

Description: This command returns all configuration values from the server’s main configuration file.
Shorthand: None
Arguments: None
Returns: Server configuration settings
Example

    get_properties
    [ENTER]

    ipv6.enable=true
    provisioner.account.name=[$DECRYPT ($BASE64.DECODE ($FILE.NAME())) ]
    rconsole.encryption=false
    rconsole.password=
    <output clipped for brevity>
    code=ack

set_properties

Description: This command sets one or more configuration values in the server’s main configuration file. Changes take effect immediately.
Shorthand: None
Arguments: Key/values to change
Returns: Nothing
Example

    set_properties
    provisioner.account.name=[$DECRYPT ($BASE64.DECODE ($FILE.NAME())) ]
    [ENTER]

    code=ack

get_config_names

Description: Display a list of configuration keys supported by the application.
Shorthand: None
Arguments: None
Returns: A list of supported configuration keys
Example

    get_config_names
    [ENTER]

    ddns.default_server=name or address - The hostname or address of the default dns server to use for ddns updates.
    ddns.default_ttl=int - The default ttl to use for ddns updates.
    <output clipped for brevity>
    code=ack

info

Description: Display various data about the product, machine and software registration.
Shorthand: None
Arguments: None
Returns: Various data
Example

    info
    [ENTER]

    _activation_code=
    _company=XYZ Corporation
    _edition=NFR Edition - NOT FOR RESALE
    _name=TFTP Turbo
    _product_id=20
    _user=John Doe
    build=1503
    max_bindings=10000
    name=offset-vm
    platform=Windows NT 5.1
    version=4.1
    code=ack

get_functions

Description: Display a list of functions that can be used in expressions.
Shorthand: None
Arguments: None
Returns: A list of supported functions
Example

    get_functions
    [ENTER]

    BASE64.DECODE=No description
    BASE64.ENCODE=No description
    BOOL=No description
    BOOTFILE=No description
    <output clipped for brevity>
    code=ack

get_query_responses

Description: Displays a list of acceptable queries the TFTP engine will accept and their pre-determined responses.
Shorthand: None
Arguments: None
Returns: A set of queries and responses
Example

    get_query_responses
    [ENTER]

    config_port=3079,clear
    query_ping=pong
    query_rconsole_port=3079,clear
    code=ack

refresh_config

Description: Re-reads the configuration settings from the application’s configuration file.
Shorthand: None
Arguments: None
Returns: Nothing
Example

    refresh_config
    [ENTER]

    code=ack

Description: Create a new temporary subscription for receiving notifications of file transfers. When subscribing, the tag value can be anything you want; it will be reflected back to you with each publication. The endpoint argument can be either an IPv4 or IPv6 endpoint.
Shorthand: <none>
Arguments: endpoint, class, tag
Returns: Nothing
Example

    subscribe
    endpoint=192.168.1.50:20000
    class=transfer
    tag=mytag
    [ENTER]

    code=ack

unsubscribe

Description: Cancels a temporary subscription. The subscriber is notified of the subscription cancellation.
Shorthand: <none>
Arguments: endpoint
Returns: Nothing
Example

    unsubscribe
    endpoint=192.168.1.50:20000
    [ENTER]

    code=ack

abort

Description: Cancels a transfer. The TFTP client is notified of the cancellation.
Shorthand: <none>
Arguments: id
Returns: Nothing
Example

    abort
    id=256
    [ENTER]

    code=ack

archive_count

Description: View the total number of events in the event archive.
Shorthand: <none>
Arguments: none
Returns: Nothing
Example

    archive_count
    count=50
    [ENTER]

    code=ack

clear_archive

Description: Clear all events in the event archive.
Shorthand: <none>
Arguments: none
Returns: Nothing
Example

    clear_archive
    [ENTER]

    code=ack

3. Contact

Weird Solutions
Box 101
18622 Vallentuna
SWEDEN
tel: +46 8 758 3700
e-mail: info at weird-solutions.com
Copyright© 1997-2015, Weird Solutions, Inc.