Update man page to one written using traditional (-man) macros instead of

mdoc.

tftpd/tftpd.8

@@ -1,262 +1,245 @@
-.\"   tftp-hpa: $Id$
+.\" -*- nroff -*- --------------------------------------------------------- *
-.\"   $OpenBSD: tftpd.8,v 1.7 1999/07/09 13:35:51 aaron Exp $
 .\"  
-.\" Copyright (c) 1983, 1991 The Regents of the University of California.
+.\"  Copyright 2001 H. Peter Anvin - All Rights Reserved
-.\" All rights reserved.
 .\"
-.\" Redistribution and use in source and binary forms, with or without
+.\"  This program is free software available under the same license
-.\" modification, are permitted provided that the following conditions
+.\"  as the "OpenBSD" operating system, distributed at
-.\" are met:
+.\"   http://www.openbsd.org/.
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\"    notice, this list of conditions and the following disclaimer in the
-.\"    documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\"    must display the following acknowledgement:
-.\"	This product includes software developed by the University of
-.\"	California, Berkeley and its contributors.
-.\" 4. Neither the name of the University nor the names of its contributors
-.\"    may be used to endorse or promote products derived from this software
-.\"    without specific prior written permission.
 .\"
-.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\"----------------------------------------------------------------------- */
-.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" $Id$
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.TH TFTPD 8 "13 November 2001" "tftp-hpa" "UNIX System Manager's Manual"
-.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.SH NAME
-.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.B tftpd
-.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+\- IPv4 Trivial File Transfer Protocol server
-.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.SH SYNOPSIS
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.B in.tftpd
-.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.RI [ options... ]
-.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.I directory...
-.\" SUCH DAMAGE.
+.SH DESCRIPTION
-.\"
+.B tftpd
-.\"	from: @(#)tftpd.8	6.7 (Berkeley) 5/13/91
+is a server for the IPv4 Trivial File Transfer Protocol.  The TFTP
-.\"	$OpenBSD: tftpd.8,v 1.7 1999/07/09 13:35:51 aaron Exp $
+protocol is extensively used to support remote booting of diskless
-.\"
+devices.  The server is normally started by
-.Dd August 6, 2001
+.BR inetd ,
-.Dt TFTPD 8
-.Os
-.Sh NAME
-.Nm tftpd
-.Nd
-IPv4 Trivial File Transfer Protocol server
-.Sh SYNOPSIS
-.Nm in.tftpd
-.Op Fl v
-.Op Fl c
-.Op Fl l
-.Op Fl a Ar [address][:port]
-.Op Fl m Ar mapfile
-.Op Fl u Ar userid
-.Op Fl t Ar timeout
-.Op Fl r Ar option...
-.Op Fl s
-.Op Ar directory
-.Sh DESCRIPTION
-.Nm
-is a server which supports the
-.Tn DARPA
-Trivial File Transfer
-Protocol.
-The
-.Tn TFTP
-server operates
-at the port indicated in the
-.Ql tftp
-service description;
-see
-.Xr services 5 .
-The server is normally started by
-.Xr inetd 8 ,
 but can also run standalone.
-.Pp
+.PP
-The use of
+The use of TFTP services does not require an account or password on
-.Xr tftp 1
+the server system.  Due to the lack of authentication information,
-does not require an account or password on the remote system.
+.B tftpd
-Due to the lack of authentication information,
+will allow only publicly readable files (o+r) to be accessed.  Files
-.Nm
+may be written only if they already exist and are publicly writable.
-will allow only publicly readable files to be
+Note that this extends the concept of ``public'' to include all users
-accessed.
+on all hosts that can be reached through the network; this may not be
-Files may be written only if they already exist and are publicly writable.
+appropriate on all systems, and its implications should be considered
-Note that this extends the concept of
+before enabling TFTP service.  The server should have the user ID with
-.Dq public
+the lowest possible privilege; see the
-to include
+.B \-u
-all users on all hosts that can be reached through the network;
+flag below.
-this may not be appropriate on all systems, and its implications
+.PP
-should be considered before enabling tftp service.
+Access to files can, and should, be restricted by invoking
-The server should have the user ID with the lowest possible privilege
+.B tftpd
-(see the
+with a list of directories by including pathnames as server program
-.Fl u
+arguments on the command line.  In this case access is restricted to
-flag below.)
+files whole names are prefixed by one of the given directories.  See
-.Pp
+also the
-Access to files may be restricted by invoking
+.B \-s
-.Nm
+flag below.
-with a list of directories by including pathnames
+.SH OPTIONS
-as server program arguments in
+.TP
-.Pa /etc/inetd.conf
+.B \-l
-or on the standalone server command line.  In this case access is
+Run the server in standalone (listen) mode, rather than run from
-restricted to files whose names are prefixed by the one of the given
+.BR inetd .
-directories.
+In listen mode, the
-.Pp
+.B \-t
-If the
-.Fl l
-flag is used, the server runs in standalone (listen) mode.  In listen
-mode, the
-.Fl t
 option is ignored, and the
-.Fl a
+.B \-a
 option can be used to specify a specific local address or port to
 listen to.
-.Pp
+.TP
-If the
+\fB\-a\fP \fI[address][:port]\fP
-.Fl c
+Specify a specific
-flag is used,
+.I address
-.Nm
+and
-will allow new files to be created; otherwise uploaded files must already
+.I port
-exist.  Files are created with default permissions allowing anyone to read
+to listen to when called with the
-or write to them.
+.B \-l
-.Pp
+option.  The default is to listen to the
-When using the
+.I tftp
-.Fl s
+port specified in
-flag with a directory name,
+.I /etc/services
-.Nm
+on all local addresses.
-will
+.TP
-.Xr chroot 2
+.B \-c
-on startup; therefore the remote host is not expected to pass the
+Allow new files to be created.  By default,
-directory as part of the file name to transfer.  This option is
+.B tftpd
-recommended for security, as well as compatibility with boot ROMs
+will only allow upload of files that already exist.  Files are created
-which do not include a directory name.
+with default permissions allowing anyone to read or write them.
-.Pp
+.TP
-The
+.B \-s
-.Fl u
+Change root directory on startup.  This means the remote host does not
-option can be used to specify a user ID which
+need to pass along the directory as part of the transfer, and may add
-.Nm
+security.  When
-will run as; the default is ``nobody''.
+.B \-s
-.Pp
+is specified, exactly one
-The
+.I directory
-.Fl t
+should be specified on the command line.  The use of this option is
-option specifies the server timeout in inetd mode.
+recommended for security as well as compatibility with some boot ROMs
-.Pp
+which cannot be easily made to include a directory name in its request.
-The
+.TP
-.Fl m
+\fB\-u\fP \fIusername\fP
-flag specifies a file which contains filename remapping rules.
+Specify the username which
-.Pp
+.B tftpd
-The
+will run as; the default is "nobody".
-.Fl v
+.TP
-flag increases the logging verbosity of
+\fB\-t\fP \fItimeout\fP
-.Nm tftpd ,
+When run from
-it can be specified multiple times.
+.B inetd
-.Pp
+this specifies how long, in seconds, to wait for a second connection
+before terminating the server.
+.B inetd
+will then respawn the server when another request comes in.  The
+default is 900 (15 minutes.)
+.TP
+\fB\-m\fP \fIremap-file\fP
+Specify the use of filename remapping.  The
+.I remap-file
+is a file containing the remapping rules.  See the section on filename
+remapping below.
+.TP
+.B \-v
+Increase the logging verbosity of
+.BR tftpd .
+This flag can be specified multiple times for even higher verbosity.
+.TP
+\fB\-r\fP \fItftp-option\fP
+Indicate that a specific RFC 2347 TFTP option should never be
+accepted.
+.TP
+.B \-V
+Print the version number to standard output, then exit gracefully.
+.SH "RFC 2347 OPTION NEGOTIATION"
 This version of
-.Nm
+.B tftpd
-supports RFC 2347 option negotiation; the current version supports the
+supports RFC 2347 option negotation.  Currently implemented options
-.Pa blksize
+are
+\f(CWblksize\fP
 (RFC 2348),
-.Pa tsize ,
+\f(CWblksize2\fP
+(nonstandard),
+\f(CWtsize\fP
 (RFC 2349), and
-.Pa timeout
+\f(CWtimeout\fP
-(RFC 2349) options.  The
+(RFC 2349).  The
-.Fl r
+.B \-r
-flag can be used to disable options individually; this may allow
+option can be used to disable specific options; this may be necessary
-working around client bugs.
+to work around bugs in specific TFTP client implementations.
-.Sh FILENAME REMAPPING
+.SH "FILENAME REMAPPING"
 The
-.Fl m
+.B \-m
 option specifies a file which contains filename remapping rules.  Each
-non-comment line (comments begin with hash marks, #) contains an
+non-comment line (comments begin with hash marks,
-.Ar operation ,
+\f(CW#\fP)
-a
+contains an
-.Ar regex ,
+.IR operation ,
+specified below; a
+.IR regex ,
 a regular expression in the style of
-.Xr egrep 1 ,
+.BR egrep ;
 and optionally a
-.Ar "replacement pattern" .
+.IR "replacement pattern" .
 The operation indicated by
-.Ar operation
+.I operation
 is performed if the
-.Ar regex
+.I regex
 matches all or part of the filename.  Rules are processed from the top
 down, and by default, all rules are processed even if there is a
 match.
-.Pp
+.PP
 The
-.Ar operation
+.I operation
 can be any combination of the following letters:
-.Pp
+.TP
-.Bl -tag -width verbose -compact
+.B r
-.It Ic r
 Replace the substring matched by
-.Ar regex
+.I regex
 by the
-.Ar "replacement pattern" .
+.IR "replacement pattern" .
 The escape sequence
 \\0
 can be used to copy the entire matched string, and the sequences
 \\1 to \\9
 copies parenthesized subexpressions.  To specify a backslash, white
 space or hash mark, you need to \\-escape it.
-.Pp
+.TP
-.It Ic g
+.B g
 Repeat this rule until it no longer matches.  This is always used with
-.Ic r .
+.BR r .
-.Pp
+.TP
-.It Ic i
+.B i
 Match the
-.Ar regex
+.I regex
 case-insensitively.  By default it is case sensitive.
-.Pp
+.TP
-.It Ic e
+.B e
 If this rule matches, end rule processing after executing the rule.
-.Pp
+.TP
-.It Ic s
+.B s
 If this rule matches, start rule processing over from the very first
 rule after executing this rule.
-.Pp
+.TP
-.It Ic a
+.B a
 If this rule matches, refuse the request and send an access denied
 error to the client.
-.Pp
+.TP
-.It Ic G
+.B G
 This rule applies to GET (RRQ) requests only.
-.Pp
+.TP
-.It Ic P
+.B P
 This rule applies to PUT (WRQ) requests only.
-.El
+.PP
-.Pp
+If the mapping file is changed, you need to send
-If the mapping file is changed, you need to send SIGHUP
+.B SIGHUP
-(kill -HUP) to any outstanding
+to any outstanding
-.Nm
+.B tftpd
 process.
-.Sh SEE ALSO
+.SH "BUGS"
-.Xr tftp 1 ,
+It is unclear at this point if the retransmission algorithm used is
-.Xr egrep 1 ,
+sufficient to satisfy the RFC 1123 requirement that TFTP
-.Xr regex 7 ,
+implementations use adaptive retransmission timeout.  Furthermore, it
-.Xr inetd 8
+is unclear how to combine the adaptive timeout of RFC 1123 with the
-.Sh HISTORY
+\f(CWtimeout\fP
-The
+option specified by RFC 2348.
-.Nm
+.SH "CONFORMING TO"
-command appeared in
+RFC 1123,
-.Bx 4.2 .
+.IR "Requirements for Internet Hosts \- Application and Support" .
-.Pp
+.br
-The
+RFC 1350,
-.Fl s
+.IR "The TFTP Protocol (revision 2)" .
-flag appeared in NetBSD 0.9a.
+.br
-.Pp
+RFC 2347,
-The
+.IR "TFTP Option Extension" .
-.Fl c
+.br
-flag was added in OpenBSD 2.1 .
+RFC 2348,
-.Pp
+.IR "TFTP Blocksize Option" .
-The
+.br
-.Fl r
+RFC 2349,
-flag and RFC 2347 options were added by H. Peter Anvin based on
+.IR "TFTP Timeout Interval and Transfer Size Options" .
-patches by Markus Gutschke and Gero Kulhman.
+.PP
-.Pp
+The nonstandard
-The
+\f(CWblksize2\fP
-.Fl u ,
+TFTP option is functionally identical to the
-.Fl v
+\f(CWblksize\fP
-and
+option specified in RFC 2349, with the additional constraint that the
-.Fl m
+blocksize is constrained to be a power of 2.
-flags were added by H. Peter Anvin.
+.SH "AUTHOR"
-
+This version of
+.B tftpd
+is maintained by H. Peter Anvin <hpa@zytor.com>.  It was derived from,
+but has substantially diverged from, an OpenBSD source base, with
+added patches by Markus Gutschke and Gero Kulhman.
+.SH "SEE ALSO"
+.BR tftp (1),
+.BR egrep (1),
+.BR regex (7),
+.BR inetd (8).