From f0f0368bee314c4d2d4ca0a50504397ad726b2d5 Mon Sep 17 00:00:00 2001 From: hpa Date: Tue, 13 Nov 2001 23:26:29 +0000 Subject: [PATCH] Update man page to one written using traditional (-man) macros instead of mdoc. --- tftpd/tftpd.8 | 429 ++++++++++++++++++++++++-------------------------- 1 file changed, 206 insertions(+), 223 deletions(-) diff --git a/tftpd/tftpd.8 b/tftpd/tftpd.8 index 505bacf..84c0215 100644 --- a/tftpd/tftpd.8 +++ b/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 2001 H. Peter Anvin - All Rights Reserved .\" -.\" Copyright (c) 1983, 1991 The Regents of the University of California. -.\" All rights reserved. +.\" This program is free software available under the same license +.\" as the "OpenBSD" operating system, distributed at +.\" http://www.openbsd.org/. .\" -.\" 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 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 . 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).