.\" Copyright (c) 1983 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
.\"	@(#)tftpd.8c	6.2 (Berkeley) 5/26/86
.\"
.TH TFTPD 8C "August 10, 1992"
.UC 5
.SH NAME
tftpd \- DARPA Trivial File Transfer Protocol server
.SH SYNOPSIS
.B /etc/tftpd
[
.B \-d
]
[
config_file
]
.SH DESCRIPTION
.I Tftpd
is a server which supports the DARPA Trivial File Transfer
Protocol.
The TFTP server operates
at the port indicated in the ``tftp'' service description;
see
.IR services (5).
The server is normally started by
.IR inetd (8),
but if the optional
.B \-d
flag is specified, it will startup and bind directly to the tftp
port.  This option is for debugging.
Using this option will require disabling tftp service in the
inetd configuration file.
.PP
The use of
.I tftp
does not require an account or password on the remote system.
Due to the lack of authentication information, 
.I tftpd
is a potential security hole in any system which provides it.
The default access rules
will allow only publicly readable files to be
read.
Note that this extends the concept of ``public'' to include
all users on all hosts that can be reached through the network;
this may not be appropriate on all systems, and its implications
should be considered before enabling tftp service.
The server should have the user ID with the lowest possible privilege.
.PP
Where the default access rules are too public,
.B tftpd
supports access control lists, which permit finer control, although
not true security.
.PP
.SH "CONFIGURATION COMMANDS"
When started
.B tftpd
reads its configuration file for options.
If the optional configuration file argument is provided on the command
line,
.B tftpd
will use that, otherwise the default file is ``/usr/local/etc/tftpd.conf''.
.sp
Configuration commands are:
.IP defaultDirectory
This command takes an argument which names a default directory to look
in for file requests which don't specify a fully-qualified filename
(i.e., starting at the root directory).
.IP rootDirectory
This command takes an argument which names a virtual
.I root
directory.
For file requests which do start at the root,
this directory will be used instead of ``/''.
The effect of this command is that all files not contained
in the specified directory or subdirectories are completely inaccessable.
In processing file requests, the effects of any ``.'' or ``..'' components
are taken into account to prevent access outside the specified root
directory.  However the effects of any symbolic links are not.
.IP debugLevel
This command takes an integer argument which sets the verbosity level for
debugging messages.  Diagnostic messages are logged via
.IR syslog (3),
both
.B LOG_DEBUG
and
.B LOG_INFO
type messages are logged; you will need to enable both to see all output.
.IP accessList
This command is used to define an access list specifying which systems
have what rights to a file;
it takes either three or four arguments.
The first is the list number (a positive integer greater than 1).
The second is one of
.BR permit ,
.BR deny ,
.BR readonly ,
or
.BR readwrite ;
or a reference to include another list by ``+''
.IR listNumber .
The third is in internet address in either dotted decimal
or hex format (if hex, there must be a leading "0x").
The optional fourth argument is also an internet address which specifies
a mask of bits which are
.B not
significant in the comparison.
.sp
Multiple
.B accessList
commands can apply to the same list number; the results are additive.
.sp
Those familiar with access lists used on Cisco routers will find this
scheme the same except that (1) the clauses in each access list are
separated into those which specify a non-zero mask and those which
don't -- those which don't are examined first.  (2) The clauses from
one access list can be included in another one using
.I +listNumber
as the second argument.
.IP restrict
This command takes a filename and an access list number as arguments.
Access to the specfied file will be controlled by the definition of the
supplied access list.
.IP defaultAccessList
This command names a default access list to use for all files which don't
name an explicit access list using the ``restrict'' command.
.IP inputWait
This command takes an integer argument which specifies the number of
seconds for the
.B tftpd
daemon to wait for input before exiting.
Once started, the daemon will continue to wait for new requests until
this time has expired.
This reduces system overhead where many requests come closely-spaced,
but doesn't make the daemon hang around forever.
The default input wait is 5 minutes.
.SH "ACCESS CONTROL"
Access to files is governed by several factors.
.IP 1)
If the
.I defaultDirectory
has not been specified in the configuration file, all file requests must
specify a fully-qualified pathname (i.e., starting with ``/'').
Any requests for not fully qualified pathnames will be denied.
.IP 2)
If there is no access list specified for a particular file, or if the
specified access list is never defined, the default access list will be used.
If there is no default access list, or if the specified default access
list is never defined, access is governed by the default access rules.
.IP 3)
The default access rules are that read requests must name files which are
generally readable (UNIX mode ??4, or "o+r").
Similarly, write requests must name files which are generally writable
(UNIX mode ??2, or "o+w").
.IP 4)
If an access list governs a file and the request is a read, then the
permission granted for the requesting host must be one of
.BR permit ,
.BR readonly ,
or
.BR readwrite .
If the request is a write, then the permission for the requesting host
must be
.BR readwrite .
In addition, the named file must already exist.
If the permission granted is
.BR permit ,
then the default access rules apply.
.sp
The permission
.B readonly
allows reading a file which is
.I not
generally readable.
Similarly the permission
.B readwrite
allows writing a file which is not generally writable.
Both are refinements on the permission
.BR permit ,
which imposes the default access rules.
You can thus have files which can only be accessed by the TFTP process
itself and still permit appropriate network access to them.
.IP 7)
Access of any sort from any system to the configuration file is
forbidden, regardless of the foregoing rules.
.SH EXAMPLE
Below is a sample configuration file:
.PP
.ne 20
.nr @1 \w'defaultAccessList~~'
.nr @2 \n(@1+\w'4~~'
.nr @3 \n(@2+\w'readWrite~~'
.nr @4 \n(@3+\w'333.333.333.333~~'
.ta \n(@1u \n(@2u \n(@3u \n(@4u
.nf
#
# Lines starting with '#' are ignored
#

# search here for unqualified file names
defaultDirectory	/usr/spool/tftpboot

# Don't search anywhere else but here 
rootDirectory		/usr/spool/tftpboot

# access list 1 is OK for everyone on 132.130.1 net
# except 132.130.1.15;  132.130.1.17 is allowed to
# write files.
accessList	1	permit	132.130.1.0	0.0.0.255
accessList	1	deny	132.130.1.15
accessList	1	readwrite	132.130.1.17

# access list 2 is OK for everyone on 132.130.1 net
accessList	2	permit	132.130.1.0	0x000000ff

# access list 3 is readonly for everyone in the world
accessList	3	readonly	0.0.0.0	255.255.255.255

# access list 4 is just like 1, except allow write access to 21 subnet
accessList	4	+1
accessList	4	readwrite	130.132.21.0	0.0.0.255

# access to 'bootfile' controlled by access list 1
restrict	bootfile	1
defaultAccessList	3
.PP
.fi
Note that access according to the list is checked in the same order
the clauses of that list were specified, and the permission of the
list is the permission given in the first clause which matches the
requesting address.
However, clauses which give non-zero mask values are collected
and checked at the end of the list.  Thus any clause requiring
an exact match will be examined before any clause permitting a
wildcard.  All clauses requiring exact matches will be examined
in the order given, as will all clauses permitting wildcards.
The order should therefore be the most particular condition first.
For example:
.IP
.nf
.ta 1.7i 2.00i 2.5 3.75i
accessList	1	permit	132.130.0.0	0.0.255.255
accessList	1	deny	132.130.1.0	0.0.0.255
.PP
.fi
will not do what is expected because the first clause will
pre-empt the second.
The default permission in any access list is
.BR deny .
.SH BUGS
The access control system used here is intended to
avoid confusion where diskless client systems on the
same network are managed by different authorities.
Each authority can maintain a tftp server which only supplies
files to a specific set of clients.
This system should not be relied upon for genuine security
concerns as IP addresses can be faked.
.PP
There is no special check for the filename ``.'' in access lists
to permit some systems rights to create new files in the default
directory.
.SH "SEE ALSO"
tftp(1C),
syslog(3),
services(5),
inetd(8)
.SH "FILES"
.ta \w'/usr/local/etc/tftpd.conf~~'u
/usr/local/etc/tftpd.conf	default tftpd configuration file
.br
/etc/inetd.conf	inetd configuration file