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

mdoc.

tftpd/tftpd.8

@@ -1,262 +1,245 @@
-.\"   tftp-hpa: $Id$
-.\"   $OpenBSD: tftpd.8,v 1.7 1999/07/09 13:35:51 aaron Exp $
+.\" -*- nroff -*- --------------------------------------------------------- *
 .\"  
-.\" Copyright (c) 1983, 1991 The Regents of the University of California.
-.\" All rights reserved.
+.\"  Copyright 2001 H. Peter Anvin - All Rights Reserved
 .\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 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 program is free software available under the same license
+.\"  as the "OpenBSD" operating system, distributed at
+.\"   http://www.openbsd.org/.
 .\"
-.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
-.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
-.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-.\" SUCH DAMAGE.
-.\"
-.\"	from: @(#)tftpd.8	6.7 (Berkeley) 5/13/91
-.\"	$OpenBSD: tftpd.8,v 1.7 1999/07/09 13:35:51 aaron Exp $
-.\"
-.Dd August 6, 2001
-.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 ,
+.\"----------------------------------------------------------------------- */
+.\" $Id$
+.TH TFTPD 8 "13 November 2001" "tftp-hpa" "UNIX System Manager's Manual"
+.SH NAME
+.B tftpd
+\- IPv4 Trivial File Transfer Protocol server
+.SH SYNOPSIS
+.B in.tftpd
+.RI [ options... ]
+.I directory...
+.SH DESCRIPTION
+.B tftpd
+is a server for the IPv4 Trivial File Transfer Protocol.  The TFTP
+protocol is extensively used to support remote booting of diskless
+devices.  The server is normally started by
+.BR inetd ,
 but can also run standalone.
-.Pp
-The use of
-.Xr tftp 1
-does not require an account or password on the remote system.
-Due to the lack of authentication information,
-.Nm
-will allow only publicly readable files to be
-accessed.
-Files may be written only if they already exist and are publicly writable.
-Note that this extends the concept of
-.Dq 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
-(see the
-.Fl u
-flag below.)
-.Pp
-Access to files may be restricted by invoking
-.Nm
-with a list of directories by including pathnames
-as server program arguments in
-.Pa /etc/inetd.conf
-or on the standalone server command line.  In this case access is
-restricted to files whose names are prefixed by the one of the given
-directories.
-.Pp
-If the
-.Fl l
-flag is used, the server runs in standalone (listen) mode.  In listen
-mode, the
-.Fl t
+.PP
+The use of TFTP services does not require an account or password on
+the server system.  Due to the lack of authentication information,
+.B tftpd
+will allow only publicly readable files (o+r) to be accessed.  Files
+may be written only if they already exist and are publicly writable.
+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; see the
+.B \-u
+flag below.
+.PP
+Access to files can, and should, be restricted by invoking
+.B tftpd
+with a list of directories by including pathnames as server program
+arguments on the command line.  In this case access is restricted to
+files whole names are prefixed by one of the given directories.  See
+also the
+.B \-s
+flag below.
+.SH OPTIONS
+.TP
+.B \-l
+Run the server in standalone (listen) mode, rather than run from
+.BR inetd .
+In listen mode, the
+.B \-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
-If the
-.Fl c
-flag is used,
-.Nm
-will allow new files to be created; otherwise uploaded files must already
-exist.  Files are created with default permissions allowing anyone to read
-or write to them.
-.Pp
-When using the
-.Fl s
-flag with a directory name,
-.Nm
-will
-.Xr chroot 2
-on startup; therefore the remote host is not expected to pass the
-directory as part of the file name to transfer.  This option is
-recommended for security, as well as compatibility with boot ROMs
-which do not include a directory name.
-.Pp
-The
-.Fl u
-option can be used to specify a user ID which
-.Nm
-will run as; the default is ``nobody''.
-.Pp
-The
-.Fl t
-option specifies the server timeout in inetd mode.
-.Pp
-The
-.Fl m
-flag specifies a file which contains filename remapping rules.
-.Pp
-The
-.Fl v
-flag increases the logging verbosity of
-.Nm tftpd ,
-it can be specified multiple times.
-.Pp
+.TP
+\fB\-a\fP \fI[address][:port]\fP
+Specify a specific
+.I address
+and
+.I port
+to listen to when called with the
+.B \-l
+option.  The default is to listen to the
+.I tftp
+port specified in
+.I /etc/services
+on all local addresses.
+.TP
+.B \-c
+Allow new files to be created.  By default,
+.B tftpd
+will only allow upload of files that already exist.  Files are created
+with default permissions allowing anyone to read or write them.
+.TP
+.B \-s
+Change root directory on startup.  This means the remote host does not
+need to pass along the directory as part of the transfer, and may add
+security.  When
+.B \-s
+is specified, exactly one
+.I directory
+should be specified on the command line.  The use of this option is
+recommended for security as well as compatibility with some boot ROMs
+which cannot be easily made to include a directory name in its request.
+.TP
+\fB\-u\fP \fIusername\fP
+Specify the username which
+.B tftpd
+will run as; the default is "nobody".
+.TP
+\fB\-t\fP \fItimeout\fP
+When run from
+.B inetd
+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
-supports RFC 2347 option negotiation; the current version supports the
-.Pa blksize
+.B tftpd
+supports RFC 2347 option negotation.  Currently implemented options
+are
+\f(CWblksize\fP
 (RFC 2348),
-.Pa tsize ,
+\f(CWblksize2\fP
+(nonstandard),
+\f(CWtsize\fP
 (RFC 2349), and
-.Pa timeout
-(RFC 2349) options.  The
-.Fl r
-flag can be used to disable options individually; this may allow
-working around client bugs.
-.Sh FILENAME REMAPPING
+\f(CWtimeout\fP
+(RFC 2349).  The
+.B \-r
+option can be used to disable specific options; this may be necessary
+to work around bugs in specific TFTP client implementations.
+.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
-.Ar operation ,
-a
-.Ar regex ,
+non-comment line (comments begin with hash marks,
+\f(CW#\fP)
+contains an
+.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
-.Bl -tag -width verbose -compact
-.It Ic r
+.TP
+.B 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
-.It Ic g
+.TP
+.B g
 Repeat this rule until it no longer matches.  This is always used with
-.Ic r .
-.Pp
-.It Ic i
+.BR r .
+.TP
+.B i
 Match the
-.Ar regex
+.I regex
 case-insensitively.  By default it is case sensitive.
-.Pp
-.It Ic e
+.TP
+.B e
 If this rule matches, end rule processing after executing the rule.
-.Pp
-.It Ic s
+.TP
+.B s
 If this rule matches, start rule processing over from the very first
 rule after executing this rule.
-.Pp
-.It Ic a
+.TP
+.B a
 If this rule matches, refuse the request and send an access denied
 error to the client.
-.Pp
-.It Ic G
+.TP
+.B G
 This rule applies to GET (RRQ) requests only.
-.Pp
-.It Ic P
+.TP
+.B P
 This rule applies to PUT (WRQ) requests only.
-.El
-.Pp
-If the mapping file is changed, you need to send SIGHUP
-(kill -HUP) to any outstanding
-.Nm
+.PP
+If the mapping file is changed, you need to send
+.B SIGHUP
+to any outstanding
+.B tftpd
 process.
-.Sh SEE ALSO
-.Xr tftp 1 ,
-.Xr egrep 1 ,
-.Xr regex 7 ,
-.Xr inetd 8
-.Sh HISTORY
-The
-.Nm
-command appeared in
-.Bx 4.2 .
-.Pp
-The
-.Fl s
-flag appeared in NetBSD 0.9a.
-.Pp
-The
-.Fl c
-flag was added in OpenBSD 2.1 .
-.Pp
-The
-.Fl r
-flag and RFC 2347 options were added by H. Peter Anvin based on
-patches by Markus Gutschke and Gero Kulhman.
-.Pp
-The
-.Fl u ,
-.Fl v
-and
-.Fl m
-flags were added by H. Peter Anvin.
-
+.SH "BUGS"
+It is unclear at this point if the retransmission algorithm used is
+sufficient to satisfy the RFC 1123 requirement that TFTP
+implementations use adaptive retransmission timeout.  Furthermore, it
+is unclear how to combine the adaptive timeout of RFC 1123 with the
+\f(CWtimeout\fP
+option specified by RFC 2348.
+.SH "CONFORMING TO"
+RFC 1123,
+.IR "Requirements for Internet Hosts \- Application and Support" .
+.br
+RFC 1350,
+.IR "The TFTP Protocol (revision 2)" .
+.br
+RFC 2347,
+.IR "TFTP Option Extension" .
+.br
+RFC 2348,
+.IR "TFTP Blocksize Option" .
+.br
+RFC 2349,
+.IR "TFTP Timeout Interval and Transfer Size Options" .
+.PP
+The nonstandard
+\f(CWblksize2\fP
+TFTP option is functionally identical to the
+\f(CWblksize\fP
+option specified in RFC 2349, with the additional constraint that the
+blocksize is constrained to be a power of 2.
+.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).