Debian Codegraph @

doc/inetutils.texi

raw
1 \input texinfo @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename inetutils.info
4 @settitle @sc{gnu} Inetutils
5 @c %**end of header
6
7 @include version.texi
8
9 @c Define new indices for file names and options.
10 @defcodeindex op
11 @defcodeindex fl
12
13 @c Put everything in one index (arbitrarily chosen to be the concept
14 @c index).
15 @syncodeindex fl cp
16 @syncodeindex fn cp
17 @syncodeindex ky cp
18 @syncodeindex op cp
19 @syncodeindex pg cp
20 @syncodeindex vr cp
21
22 @dircategory Basics
23 @direntry
24 * Inetutils: (inetutils). GNU networking utilities.
25 * Common options: (inetutils)Common options. Common options.
26 @end direntry
27
28 @dircategory Individual utilities
29 @direntry
30 * dnsdomainname: (inetutils)dnsdomainname invocation. Show DNS domain name.
31 * ftp: (inetutils)ftp invocation. FTP client.
32 * ftpd: (inetutils)ftpd invocation. FTP Daemon.
33 * hostname: (inetutils)hostname invocation. Show or set system host name.
34 * ifconfig: (inetutils)ifconfig invocation. Configure network interfaces.
35 * inetd: (inetutils)inetd invocation. Internet super-server.
36 * logger: (inetutils)logger invocation. Send messages to the system log.
37 * ping6: (inetutils)ping6 invocation. Packets to IPv6 network hosts.
38 * ping: (inetutils)ping invocation. Packets to network hosts.
39 * rcp: (inetutils)rcp invocation. Remote copy
40 * rexec: (inetutils)rexec invocation. Remote execution client.
41 * rexecd: (inetutils)rexecd invocation. Remote execution server.
42 * rlogin: (inetutils)rlogin invocation. Remote login.
43 * rlogind: (inetutils)rlogind invocation. Remote login server.
44 * rsh: (inetutils)rsh invocation. Remote shell.
45 * rshd: (inetutils)rshd invocation. Remote shell server.
46 * syslogd: (inetutils)syslogd invocation. Syslog server.
47 * talk: (inetutils)talk invocation. Talk client.
48 * talkd: (inetutils)talkd invocation. Talk server.
49 * telnet: (inetutils)telnet invocation. User interface to TELNET.
50 * telnetd: (inetutils)telnetd invocation. Telnet server.
51 * tftp: (inetutils)tftp invocation. TFTP client.
52 * tftpd: (inetutils)tftpd invocation. TFTP server.
53 * traceroute: (inetutils)traceroute invocation. Trace the route to a host.
54 * uucpd: (inetutils)uucpd invocation. Unix to Unix Copy.
55 * whois: (inetutils)whois invocation. Whois user interface.
56 @end direntry
57
58 @copying
59 This manual documents version @value{VERSION} of the @sc{gnu} networking
60 utilities.
61
62 Copyright @copyright{} 2000--2026 Free Software Foundation, Inc.
63
64 @quotation
65 Permission is granted to copy, distribute and/or modify this document
66 under the terms of the GNU Free Documentation License, Version 1.3 or
67 any later version published by the Free Software Foundation; with no
68 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
69 copy of the license is included in the section entitled ``GNU Free
70 Documentation License''.
71 @end quotation
72 @end copying
73
74 @titlepage
75 @title @sc{gnu} @code{inetutils}
76 @subtitle GNU networking utilities
77 @subtitle for version @value{VERSION}, @value{UPDATED}
78 @author Alain Magloire et al.
79
80 @page
81 @vskip 0pt plus 1filll
82 @insertcopying
83 @end titlepage
84 @shortcontents
85 @contents
86
87 @ifnottex
88 @node Top
89 @top GNU Inetutils
90
91 @insertcopying
92 @end ifnottex
93
94 @menu
95 * Introduction:: Caveats, overview, and authors.
96 * Common options:: Common options.
97
98 Diagnostic programs
99
100 * dnsdomainname invocation:: Show DNS domain name.
101 * hostname invocation:: Show or set system host name.
102 * ifconfig invocation:: Configure network interfaces.
103 * logger invocation:: Send messages to system log.
104 * ping invocation:: Packets to network hosts.
105 * ping6 invocation:: Packets to IPv6 network hosts.
106 * traceroute invocation:: Trace the route to a host.
107 * whois invocation:: Whois user interface.
108
109 Clients
110
111 * ftp invocation:: FTP client.
112 * rcp invocation:: Remote copy
113 * rexec invocation:: Remote execution client.
114 * rlogin invocation:: Remote login.
115 * rsh invocation:: Remote shell.
116 * talk invocation:: Talk client.
117 * telnet invocation:: User interface to TELNET.
118 * tftp invocation:: TFTP client.
119
120 Daemons
121
122 * inetd invocation:: Internet super-server.
123 * syslogd invocation:: Syslog server.
124 * ftpd invocation:: FTP Daemon.
125 * rexecd invocation:: Remote execution server.
126 * rlogind invocation:: Remote login server.
127 * rshd invocation:: Remote shell server.
128 * talkd invocation:: Talk server.
129 * telnetd invocation:: Telnet server.
130 * tftpd invocation:: TFTP server.
131 * uucpd invocation:: Unix to Unix Copy.
132
133 Appendix
134
135 * GNU Free Documentation License:: The license for this manual.
136 * Index:: Index of manual.
137 @end menu
138
139 @c OK -- 2009-04-27
140 @node Introduction
141 @chapter Introduction
142 @cindex introduction
143
144 The GNU Networking Utilities is a distribution of common networking
145 utilities and servers, including for example ping, traceroute and ftp.
146
147 This manual is a work in progress: many sections make no attempt to
148 explain basic concepts in a way suitable for novices. Thus, if you
149 are interested, please get involved in improving this manual. The
150 entire @sc{gnu} community will benefit.
151
152 @cindex bug, reporting
153 Please report bugs to @email{bug-inetutils@@gnu.org}. Remember to
154 include the version number, machine architecture, input files, and any
155 other information needed to reproduce the bug: your input, what you
156 expected, what you got, and why it is wrong. Diffs are welcome, but
157 please include a description of the problem as well, since this is
158 sometimes difficult to infer.
159
160 The individual utilities were originally derived from the 4.4BSDLite2
161 distribution, although some of them have more or less been rewritten.
162 What you are reading now is the authoritative and complete
163 documentation for these utilities; the man pages are now automatically
164 generated.
165
166 Many features were integrated from NetBSD, OpenBSD, FreeBSD and
167 GNU/Linux, the merges were done by a group of dedicated hackers (in no
168 particular order): Jeff Bailey, Marcus Brinkmann, Michael Vogt,
169 Bernhard Rosenkraenzer, Kaveh R. Ghazi, NIIBE Yutaka, Nathan
170 Neulinger, Jeff Smith, Dan Stromberg, David O'Shea, Frederic Goudal,
171 Gerald Combs, Joachim Gabler, Marco D'Itri, Sergey Poznyakoff, and
172 many more.
173
174 @node Common options
175 @chapter Common options
176 @cindex common options
177
178 Certain options are available in all these programs. Rather than
179 writing identical descriptions for each of the programs, they are
180 described here. (In fact, every @sc{gnu} program accepts, or should
181 accept, these options.)
182
183 Many of these programs take arbitrary strings as arguments. In those
184 cases, @option{--help} and @option{--version} are taken as these
185 options only if there is one and exactly one command line argument.
186
187 @table @option
188 @item --help
189 @opindex --help
190 @cindex help, online
191 Print a usage message, listing all available options, then exit
192 successfully.
193
194 @item --usage
195 @opindex --usage
196 @cindex usage, online
197 Print a condensed usage message, displaying all available options
198 formatted like a command line call, then exit successfully.
199
200 @item --version
201 @opindex --version
202 @cindex version number, finding
203 Print the version number, then exit successfully.
204
205 @item --
206 @opindex --
207 @cindex option delimiter
208 Delimit the option list. Later arguments, if any, are treated as
209 operands even if they begin with @samp{-}.
210 @end table
211
212 @menu
213 * Exit status:: Indicating program success or failure.
214 @end menu
215
216 @node Exit status
217 @section Exit status
218
219 @macro exitstatus
220 An exit status of zero indicates success, and a nonzero value
221 indicates failure.
222 @end macro
223
224 Nearly every command invocation yields an integral @dfn{exit status}
225 that can be used to change how other commands work. For the vast
226 majority of commands, an exit status of zero indicates success.
227 Failure is indicated by a nonzero value --- typically @samp{1}, though
228 it may differ on unusual platforms, as POSIX requires only that it be
229 nonzero.
230
231 @node dnsdomainname invocation
232 @chapter @command{dnsdomainname}: Show DNS domain name
233 @pindex dnsdomainname
234
235 @command{dnsdomainname} is a program to show the domain part of the
236 system's fully qualified domain name. For example, if the FQDN of the
237 system is @code{name.example.org} the command will show
238 @code{example.org}.
239 The output is not necessarily related to the NIS/YP domain name.
240
241 The tool uses gethostname to get the host name of the system and
242 then getaddrinfo to resolve it into a canonical name.
243 The domain part of the canonical name is shown, i.e., the part
244 after the first period@tie{}(@code{.}) of the official name.
245
246 @noindent
247 Synopsis:
248
249 @example
250 dnsdomainname [@var{option}@dots{}]
251 @end example
252
253 @noindent
254 There is no command specific option.
255
256 @node hostname invocation
257 @chapter @command{hostname}: Show or set system host name.
258 @pindex hostname
259
260 @command{hostname} is a program to show or to set the name of a
261 host system.
262
263 @noindent
264 Synopsis:
265
266 @example
267 hostname [@var{option}@dots{}]
268 hostname @var{name}
269 @end example
270
271 @noindent
272 where @var{name} is the name to be used by the running host.
273
274 @section Command line options
275 @anchor{hostname options}
276
277 @table @option
278 @item -a
279 @itemx --aliases
280 @opindex -a
281 @opindex --aliases
282 Get alias names.
283
284 @item -d
285 @itemx --domain
286 @opindex -d
287 @opindex --domain
288 Get DNS domain name.
289
290 @item -f
291 @itemx --fqdn
292 @itemx --long
293 @opindex -f
294 @opindex --fqdn
295 @opindex --long
296 Get DNS host name or Fully Qualified Domain Name.
297
298 @item -F @var{file}
299 @itemx --file=@var{file}
300 @opindex -F
301 @opindex --file
302 Set host name or NIS domain name from FILE.
303
304 @item -i
305 @itemx --ip-addresses
306 @opindex -i
307 @opindex --ip-addresses
308 Get addresses for the host name.
309
310 @item -s
311 @itemx --short
312 @opindex -s
313 @opindex --short
314 Get short host name.
315
316 @item -y
317 @itemx --yp
318 @itemx --nis
319 @opindex -y
320 @opindex --yp
321 @opindex --nis
322 Get NIS/YP domain name.
323 @end table
324
325 @node ifconfig invocation
326 @chapter @command{ifconfig}: Configure network interfaces
327 @pindex ifconfig
328
329 @command{ifconfig} is a program to retrieve and to set selected
330 properties of network interfaces. It is best viewed as a tool to
331 get information, rather than for changing the behaviour of adapters,
332 since it is hard to support property setting in a portable manner.
333
334 @noindent
335 Synopsis:
336
337 @example
338 ifconfig @var{iface} [@var{arg}@dots{}]
339 ifconfig -i @var{iface} [@var{option}@dots{}] [-i @var{iface2} [@var{option}@dots{}]]
340 @end example
341
342 @section Command line options
343 @anchor{ifconfig options}
344
345 @table @option
346 @item -a
347 @itemx --all
348 @opindex -a
349 @opindex --all
350 Display all available interfaces, including those that not are
351 marked as `up', i.e., also the inactive interfaces.
352
353 @item -A @var{addr}
354 @itemx --address=@var{addr}
355 @opindex -A
356 @opindex --address
357 Set address of selected interface to @var{addr}.
358
359 @item -b @var{addr}
360 @itemx -B @var{addr}
361 @itemx --brdaddr=@var{addr}
362 @itemx --broadcast=@var{addr}
363 @opindex -b
364 @opindex -B
365 @opindex --brdaddr
366 @opindex --broadcast
367 Set broadcast address of selected interface to @var{addr}.
368
369 @item -d @var{addr}
370 @itemx -p @var{addr}
371 @itemx --dstaddr=@var{addr}
372 @itemx --peer=@var{addr}
373 @opindex -d
374 @opindex -p
375 @opindex --dstaddr
376 @opindex --peer
377 Set destination (peer) address of selected interface.
378
379 @item --down
380 @opindex --down
381 Deactivate the selected interface.
382
383 @item -F @var{list}
384 @itemx --flags=@var{list}
385 @opindex -F
386 @opindex --flags
387 Change those interface flags mentioned in @var{list}.
388 The argument is a comma separated list of one or more
389 flag names to be set, or in case the name is prepended
390 with @samp{no}, the corresponding flag is cleared.
391 The output of @command{ifconfig} with the option @option{--help}
392 contains a list of available flag names.
393
394 @item --format=@var{format}
395 @opindex --format
396 Select output format; the value @samp{help} prints a list
397 of all available formats.
398
399 @item -i @var{name}
400 @itemx --interface=@var{name}
401 @opindex -i
402 @opindex --interface
403 Select the named interface for any following action.
404
405 @item -l
406 @itemx --list
407 @opindex -l
408 @opindex --list
409 List, with name only, all available interfaces, or only those
410 selected should at least one option @option{-i} have specified.
411
412 @item -m @var{mask}
413 @itemx --netmask=@var{mask}
414 @opindex -m
415 @opindex --netmask
416 Set netmask of selected interface to @var{mask}.
417
418 @item --metric=@var{n}
419 @opindex --metric
420 Set the metric of selected interface to the number @var{n}.
421
422 @item -M @var{n}
423 @itemx --mtu=@var{n}
424 @opindex -M
425 @opindex --mtu
426 Set MTU of selected interface to the number @var{n}.
427
428 @item -s
429 @itemx --short
430 @opindex -s
431 @opindex --short
432 Use short output format. This is identical to specifying
433 @samp{--format=netstat}.
434
435 @item --up
436 @opindex --up
437 Activate the selected interface.
438
439 @item -v
440 @itemx --verbose
441 @opindex -v
442 @opindex --verbose
443 Print informational messages when configuring an interface.
444 @end table
445
446 Observe that the use of program options is the only manner
447 in which @command{ifconfig} is able to handle multiple
448 interfaces in one invocation. Once a particular interface
449 has been selected using @option{-i}, it is affected by any
450 following option until replaced by another interface selector.
451 This is also the main cause, that @command{ifconfig} is
452 unable to treat options independently of their order, as is
453 mostly the case in other GNU software.
454
455 @section Formatted status output
456 @anchor{ifconfig formats}
457
458 The status of one or more interfaces can be presented in a number
459 of different formats. A list of them is printed by the option
460 @option{--format=help}. In the following table the valid formats
461 are given, each is used in the form @option{--format=@var{name}}.
462
463 @table @asis
464 @item check
465 @itemx check-existence
466 @itemx ?
467 Place holders for the ability to check whether the interfaces
468 selected by one or more options @option{-i} are determining
469 existing interfaces in the running system. No output in case
470 of success, an error message in case of a failure.
471
472 @item gnu
473 @itemx default
474 Standard GNU output format.
475
476 @item gnu-one-entry
477 Like the previous format, but with intermediary newlines removed.
478
479 @item help
480 Display a list of valid formats, together with a short description
481 for each choice.
482
483 @item net-tools
484 Imitation of presentation used by the implementation in @samp{net-tools}.
485 Default format for GNU/Linux.
486
487 @item netstat
488 Terse output with statistics, similar to that of @code{netstat -i}.
489
490 @item osf
491 Format variant of @samp{unix} preferred by OSF's implementation.
492
493 @item unix
494 Traditional UNIX type format. Default for BSD, HPUX and Solaris.
495 @end table
496
497 @section Legacy syntax
498 @anchor{ifconfig legacy syntax}
499
500 The traditional mode of invoking @command{ifconfig} is via
501 a parsed command line, without all use of program switches
502 and options, relying fully on argument parsing. This mode
503 of use is supported also in the present implementation,
504 but keep in mind that only one interface can be manipulated
505 using this legacy syntax.
506
507 @example
508 ifconfig NAME [ADDR [DSTADDR]] [broadcast BRDADDR] [netmask MASK]
509 [metric N] [mtu N] [up|down]
510 @end example
511
512 As is conventional, only the primary address and possibly the
513 peer destination address are stated as bare arguments, without
514 a specifying keyword.
515 Some slight variation on this syntax will depend on the target
516 system for which the program is being built, as not all platforms
517 support identical abilities.
518 The best information is found via the usage massage
519 @samp{ifconfig --usage}.
520
521 @node logger invocation
522 @chapter @command{logger}: Send messages to system log
523 @pindex logger
524
525 @command{logger} is a program to send entries to system log. It
526 provides a shell command interface similar to the system log module.
527 For background information,
528 @pxref{Syslog, , Syslog, libc, The GNU C Library Reference Manual}.
529
530 @noindent
531 Synopsis:
532
533 @example
534 logger [@var{option}@dots{}] [@var{message}]
535 @end example
536
537 @section Command line options
538 @anchor{logger options}
539
540 @table @option
541 @item -4
542 @itemx --ipv4
543 @opindex -4
544 @opindex --ipv4
545 Use IPv4 as transport when logging to a host. The default behaviour
546 is to use whatever IP version that matches the host.
547
548 @item -6
549 @itemx --ipv6
550 @opindex -6
551 @opindex --ipv6
552 Use IPv6 as transport when logging to a host. The option is present
553 also on systems without support for IPv6, but will then issue a warning
554 and then fall back to IPv4 when delivering the message.
555
556 Both options are most influential when the target host is named using
557 a symbolic name, but numerical addresses for host or source must also
558 match if either of @option{--ipv4} or @option{--ipv6} is stated.
559
560 @item -f @var{file}
561 @itemx --file=@var{file}
562 @opindex -f
563 @opindex --file
564 Log the content of the specified file. If @var{file} is @samp{-} then
565 standard input is assumed.
566
567 @item -h @var{host}
568 @itemx --host=@var{host}
569 @opindex -h
570 @opindex --host
571 Send messages to the given host or socket. The @var{host} argument
572 can be either a local UNIX socket name (containing a slash @samp{/}),
573 or be of the form
574
575 @example
576 @var{host}[:@var{port}]
577 @end example
578
579 @noindent
580 where @var{host} is the remote host name or IP address, and the
581 optional @var{port} is a decimal port number or symbolic service
582 name from @file{/etc/services}. If @var{port} is not specified,
583 the port number corresponding to the @samp{syslog} service is used.
584 If a numerical IPv6 address is given without a port specification,
585 then the address must be enclosed within brackets (like [::1]).
586
587 @item -i[@var{pid}]
588 @itemx --id=[@var{pid}]
589 @opindex -i
590 @opindex --id
591 Add process ID to each message. If @var{pid} is not supplied, use the
592 process ID of the logger process with each line. Notice, that
593 @var{pid} is an optional argument. When supplied to the @option{-i}
594 option, it must follow the @samp{i} letter immediately, without any
595 separating whitespace. When supplied to the @option{--id} form, it
596 must be separated from it by exactly one equals sign.
597
598 @item -p @var{priority}
599 @itemx --priority=@var{priority}
600 @opindex -p
601 @opindex --priority
602 Enter the message with the specified priority. The priority may be
603 specified numerically or as a @samp{facility.level} pair. For
604 example, @option{-p local3.info} logs the message at the informational
605 level in the @samp{local3} facility. The default is
606 @samp{user.notice}.
607
608 The actual list of supported facilities and levels is system specific.
609
610 @item -s
611 @itemx --stderr
612 @opindex -s
613 @opindex --stderr
614 Log the message to standard error, as well as to the system log.
615
616 @item -S @var{addr}
617 @itemx --source=@var{addr}
618 @opindex -S
619 @opindex --source
620 Supply the source IP address for INET connections. This option is
621 useful in conjunction with @option{--host} (see above). The kind of
622 address specified here (IPv4 or IPv6) will propagate to influence
623 the resolution of the host address, if it is a symbolic name.
624
625 @item -t @var{tag}
626 @itemx --tag=@var{tag}
627 @opindex -t
628 @opindex --tag
629 Mark every line in the log with the specified tag.
630
631 @item -u @var{socket}
632 @itemx --unix=@var{socket}
633 @opindex -h
634 @opindex --host
635 Send messages to the given local UNIX socket. The @var{socket} argument
636 can be either an absolute path (starting with a slash @samp{/}), or a relative
637 path understood relative to the current working directory.
638 @end table
639
640 The options are followed by the message which should be written to the
641 log. If not specified, and the @option{-f} flag is not provided,
642 standard input is logged.
643
644 @section Examples
645 @anchor{logger examples}
646
647 The following examples illustrate the usage of the @command{logger}
648 command:
649
650 @enumerate 1
651 @item Log the message @samp{System rebooted} to the local syslog.
652 Use default facility and priority:
653
654 @example
655 logger System rebooted
656 @end example
657
658 @item Run command and send its error output to the channel
659 @samp{local0.err}. Mark each message with tag @samp{cmd}:
660
661 @example
662 command 2>&1 | logger -p local0.err -t cmd
663 @end example
664
665 @item Log each line from file @file{warnings} to channel
666 @samp{daemon.warn} on host @samp{logger.runasimi.org},
667 using the source IP @samp{10.10.10.1}:
668
669 @example
670 logger -p daemon.warn -h logger.runasimi.org -S 10.10.10.1 \
671 @verb{| |}--file warnings
672 @end example
673 @end enumerate
674
675 @node ping invocation
676 @chapter @command{ping}: Packets to network hosts
677 @pindex ping
678
679 @c FIXME: The text is far to detailed about the actual implementation
680 @c of ping. A user doesn't need to know that we are using TIMEVAL, or
681 @c how things are padded.
682
683 @command{ping} uses ICMP datagrams to provoke a response
684 from the chosen destination host, mainly intending to probe
685 whether it is alive.
686
687 The used datagram, of type @code{ECHO_REQUEST}, contains some header
688 information and some additional payload, usually a time stamp.
689 By a suitable choice of payload, different host or router properties
690 are detectable, as the emitted datagram travels to its destination.
691
692 @ignore %* Too detailed for end user.
693 @command{ping} uses the ICMP protocol's mandatory
694 @code{ECHO_REQUEST} datagram to elicit an ICMP type @code{ECHO_REPLY}
695 packet from a host or gateway.
696 @code{ECHO_REQUEST} datagrams (@dfn{pings}) have an IP and
697 an ICMP header, followed by a @dfn{struct timeval} and then
698 an arbitrary number of @dfn{padding} bytes used to fill out the packet.
699 @end ignore
700
701 @noindent
702 Synopsis:
703
704 @example
705 ping [@var{option}@dots{}] @var{host}
706 @end example
707
708 @noindent
709 Sending echo requests is the standard use of @command{ping},
710 but by far not the only use case.
711
712 @menu
713 * Ping options::
714 * Fault isolation::
715 * Duplicate and damaged packets::
716 * Data patterns::
717 * TTL details::
718 * Further remarks::
719 @end menu
720
721 @node Ping options
722 @section Command line options
723 @anchor{ping options}
724
725 @c Options controlling ICMP request types:
726 @c --address Send ICMP_ADDRESS packets (root only)
727 @c --echo Send ICMP_ECHO packets (default)
728 @c --mask Same as --address
729 @c --timestamp Send ICMP_TIMESTAMP packets
730 @c -t, --type=TYPE Send TYPE packets
731
732 Selection of packet type is handled by these first options:
733
734 @table @option
735 @item --address
736 @opindex --address
737 Send ICMP_ADDRESS packets, thus requesting the address netmask
738 in use by the targeted host.
739
740 @item --echo
741 @opindex --echo
742 Send ICMP_ECHO requests.
743 This is the default action.
744
745 @item --mask
746 @opindex --mask
747 Identical to @option{--address}.
748
749 @item --timestamp
750 @opindex --timestamp
751 Send ICMP_TIMESTAMP packets, thereby requesting a timed response
752 from the targeted host.
753
754 In successful cases three time values are returned.
755 All are expected to state the number of milliseconds since
756 midnight@tie{}UTC.
757 The first of these, @samp{icmp_otime}, contains the original
758 time of sending the request.
759 Then comes @samp{icmp_rtime}, the time of reception by the target,
760 and finally, @samp{icmp_ttime}, the time of transmitting an answer
761 back to the originator.
762
763 @item -t @var{type}
764 @itemx --type=@var{type}
765 @opindex --type
766 @opindex -t
767 Send @var{type} packets. Accepted values are @samp{address},
768 @samp{echo}, @samp{mask}, and @samp{timestamp}.
769 @end table
770
771 @c Options valid for all request types:
772 @c -c, --count=NUMBER Stop after sending NUMBER packets
773 @c -d, --debug Set the SO_DEBUG option
774 @c -i, --interval=NUMBER Wait NUMBER seconds between sending each packet
775 @c -n, --numeric Do not resolve host addresses
776 @c -r, --ignore-routing Send directly to a host on an attached network
777 @c -T, --tos=NUM Set type-of-service to NUM
778 @c --ttl=NUMBER Set specified time-to-live on packet
779
780 @noindent
781 The following options are available for all packet types:
782
783 @table @option
784 @item -c @var{n}
785 @itemx --count=@var{n}
786 @opindex -c
787 @opindex --count
788 Stop after sending and receiving answers to a total of
789 @var{n} packets.
790
791 @item -d
792 @itemx --debug
793 @opindex -d
794 @opindex --debug
795 Set the SO_DEBUG option on the socket being used.
796
797 @item -i @var{n}
798 @itemx --interval=@var{n}
799 @opindex -i
800 @opindex --interval
801 Wait @var{n} seconds until sending next packet.
802 The default is to wait for one second between packets.
803 This option is incompatible with the option @option{-f}.
804
805 @item -n
806 @itemx --numeric
807 @opindex -n
808 @opindex --numeric
809 Numeric output only. No attempt will be made to resolve
810 symbolic names for host addresses.
811
812 @item -r
813 @itemx --ignore-routing
814 @opindex -r
815 @opindex --ignore-routing-log
816 Bypass the normal routing tables and send directly to a host on an
817 attached network. If the host is not on a directly attached network,
818 an error is returned. This option can be used to ping a local host
819 through an interface that has no route through it (e.g., after the
820 interface was dropped by @command{routed}).
821
822 @item -T @var{num}
823 @itemx --tos=@var{num}
824 @opindex -T
825 @opindex --tos
826 Set type-of-service, TOS field, to @var{num} on
827 transmitted packets.
828
829 @item --ttl=@var{n}
830 @opindex --ttl
831 Set the specified number @var{n} as value of time-to-live when
832 transmitting packets. Acceptable values are 1 to 255, inclusive.
833
834 @item -v
835 @itemx --verbose
836 @opindex -v
837 @opindex --verbose
838 Produce more verbose output, giving more statistics.
839
840 @item -w @var{n}
841 @itemx --timeout=@var{n}
842 @opindex -w
843 @opindex --timeout
844 Stop after @var{n} seconds.
845
846 @item -W @var{n}
847 @itemx --linger=@var{n}
848 @opindex -W
849 @opindex --linger
850 Maximum number of seconds @var{n} to wait for a response.
851 @end table
852
853 @c Options valid for --echo requests:
854 @c -f, --flood Flood ping (root only)
855 @c --ip-timestamp=FLAG Timestamp IP option of types tsonly,
856 @c tsaddr, or (not yet implemented) prespec.
857 @c -l, --preload=NUMBER Send NUMBER packets as fast as possible before
858 @c falling into normal mode of behavior (root only)
859 @c -p, --pattern=PATTERN Fill ICMP packet with given pattern (hex)
860 @c -q, --quiet no packet message
861 @c -R, --route Record route IP option
862 @c -s, --size=NUMBER Send NUMBER data octets
863
864 Finally, these last options are relevant only for sending echo requests,
865 allowing many variations in order to detect various peculiarities of
866 the targeted host, or the intermediary routers for that matter.
867
868 @table @option
869 @item -f
870 @itemx --flood
871 @opindex -f
872 @opindex --flood
873 Flood ping. Outputs packets as fast as they come back or one hundred
874 times per second, whichever is more. For every ECHO_REQUEST packet
875 sent, a period @samp{.} is printed, while for every ECHO_REPLY
876 received in reply, a backspace is printed.
877 This provides a rapid display of how many packets are being dropped.
878 Only the super-user may use this option.
879 This can be very hard on a network and should be used with caution.
880
881 @item --ip-timestamp=@var{flag}
882 @opindex --ip-timestamp
883 Include IP option Timestamp in transmitted packets.
884 The value @var{flag} is either @samp{tsonly}, which only records up
885 to nine time stamps, or @samp{tsaddr}, which records IP
886 addresses as well as time stamps, but for at most four hosts.
887
888 @item -l @var{n}
889 @itemx --preload=@var{n}
890 @opindex -l
891 @opindex --preload
892 If @var{n} is specified, ping sends that many packets as fast as
893 possible before falling into its normal mode of operation.
894
895 @item -p @var{pat}
896 @itemx --pattern=@var{pat}
897 @opindex -p
898 @opindex --pattern
899 You may specify up to 16 pad bytes to fill out the packet you send.
900 This is useful for diagnosing data-dependent problems in a network.
901 For example, @option{-p ff} will cause the sent packet to be filled
902 with all ones.
903
904 @item -q
905 @itemx --quiet
906 @opindex -q
907 @opindex --quiet
908 Do not print timing for each transmitted packet.
909 @item -R
910 @itemx --route
911 @opindex -R
912 @opindex --route
913 Record route. Includes the @code{RECORD_ROUTE} field in the
914 ECHO_REQUEST packet and displays the route buffer on returned packets.
915 Note that the IP header is only large enough for nine
916 such routes.
917 Many hosts ignore or discard this option.
918
919 @item -s @var{n}
920 @itemx --size=@var{n}
921 @opindex -s
922 @opindex --size
923 Specifies the number of data bytes to be sent. The default is 56,
924 which translates into 64@tie{}ICMP data bytes, taking
925 the 8@tie{}bytes of ICMP header data into account.
926 @end table
927
928 @node Fault isolation
929 @section Using ping for network fault isolation
930
931 When using @command{ping} for fault isolation, it should first be run
932 on the local host, to verify that the local network interface is up
933 and running. Then, hosts and gateways further and further away should
934 be pinged. Round-trip times and packet loss statistics are computed.
935 If duplicate packets are received, they are not included in the packet
936 loss calculation, although the round trip time of these packets is
937 used in calculating the minimum/average/maximum round-trip time
938 numbers. When the specified number of packets have been sent (and
939 received) or if the program is terminated with a @samp{SIGINT}, a
940 brief summary is displayed.
941
942 This program is intended for use in network testing, measurement and
943 management. Because of the load it can impose on the network, it is
944 unwise to use ping during normal operations or from automated scripts.
945
946 @ignore
947 @section ICMP Packet Details
948
949 An IP header without options consists of 20 bytes.
950 An ICMP type ECHO_REQUEST packet contains an additional
951 8 bytes worth of ICMP header followed by an arbitrary
952 amount of data.
953 When a packet size is stated, that indicates
954 the size of the extra piece of data (the default is 56).
955 Thus the amount of data received as an IP packet
956 with an ICMP type ECHO_REPLY, will always be 8 bytes larger
957 than the requested data space (the ICMP header).
958
959 If the data space is at least eight bytes large, ping uses the first
960 eight bytes of this space to include a timestamp which it uses in the
961 computation of round trip times. If less than eight bytes of pad are
962 specified, no round trip times are given.
963 @end ignore
964
965 @node Duplicate and damaged packets
966 @section Duplicate and damaged packets
967
968 Ping will report duplicate and damaged packets. Duplicate packets
969 should never occur, and seem to be caused by inappropriate link-level
970 retransmissions. Duplicates may occur in many situations and are
971 rarely (if ever) a good sign, although the presence of low levels of
972 duplicates may not always be cause for alarm.
973
974 Damaged packets are obviously serious cause for alarm and often
975 indicate broken hardware somewhere in the ping packet's path (in the
976 network or in the hosts).
977
978 @node Data patterns
979 @section Trying different data patterns
980
981 The (inter)network layer should never treat packets differently
982 depending on the data contained in the data portion. Unfortunately,
983 data-dependent problems have been known to sneak into networks and
984 remain undetected for long periods of time. In many cases the
985 particular pattern that will have problems is something that doesn't
986 have sufficient ``transitions'', such as all ones or all zeros, or a
987 pattern right at the edge, such as almost all zeros. It isn't
988 necessarily enough to specify a data pattern of all zeros (for
989 example) on the command line because the pattern that is of interest
990 is at the data link level, and the relationship between what you type
991 and what the controllers transmit can be complicated.
992
993 This means that if you have a data-dependent problem you will probably
994 have to do a lot of testing to find it. If you are lucky, you may
995 manage to find a file that either can't be sent across your network or
996 that takes much longer to transfer than other similar length files.
997 You can then examine this file for repeated patterns that you can test
998 using the @option{-p} option of ping.
999
1000 @node TTL details
1001 @section TTL details
1002
1003 The TTL field, @dfn{Time To Live}, of an IP
1004 packet represents the maximum number of IP routers
1005 that the packet can go through before being discarded.
1006 In current practice you can expect each router on the
1007 Internet to decrement the TTL field by exactly one.
1008
1009 The TCP/IP specification states that the TTL field
1010 of a new TCP packet should be set to 60,
1011 but many systems use smaller values (4.3BSD used 30
1012 and 4.2BSD used 15).
1013
1014 The maximum possible value of this field is 255, and most UNIX systems
1015 set the TTL field of ICMP (type @code{ECHO_REQUEST})
1016 packets to 255. This is why you will find you can ping some hosts,
1017 but not reach them with @command{telnet} or @command{ftp}.
1018
1019 During normal operation, @command{ping} prints the TTL value
1020 for every packet it receives.
1021 When a remote system receives an ICMP packet,
1022 it can do one of three things to the TTL field
1023 in its response packet:
1024
1025 @itemize @bullet
1026 @item
1027 Not to change it. This is what Berkeley UNIX systems did before the
1028 4.3BSD-Tahoe release. In this case the TTL value in the
1029 received packet will be 255 minus the number of routers in the
1030 round-trip path.
1031
1032 @item
1033 Set it to 255. This is what current Berkeley UNIX systems do. In this
1034 case the TTL value in the received packet will be 255 minus the
1035 number of routers in the path from the remote system to the pinging
1036 host.
1037
1038 @item
1039 Set it to some other value. Some machines use the same value for
1040 ICMP packets that they use for TCP packets,
1041 for example either 30 or 60.
1042 Others may use completely arbitrary values.
1043
1044 @end itemize
1045
1046 @node Further remarks
1047 @section Further observations
1048 Many hosts and gateways ignore the @code{RECORD_ROUTE} field, since
1049 the maximum IP header length is far to small to hold all
1050 the routes.
1051 There is not much that can be done about this.
1052
1053 Flood pinging is not recommended in general, and flood pinging the
1054 broadcast address should only be done under very controlled
1055 conditions.
1056
1057 Some BSD variants offer a kernel setting to inhibit all replies
1058 to ICMP_MASKREQ packets, but in general, Unices are designed either
1059 to answer the request with a valid netmask, or to drop the request,
1060 causing @command{ping} to wait for a timeout condition.
1061
1062 @node ping6 invocation
1063 @chapter @command{ping6}: Packets to IPv6 network hosts
1064 @pindex ping6
1065
1066 @command{ping6} uses ICMPv6 datagrams to get a response
1067 from the chosen destination host.
1068 The most common use is to probe whether the remote
1069 system is responsive.
1070 Observe that this program only uses IPv6 datagrams.
1071
1072 Each datagram, of type @code{ECHO_REQUEST}, carries some header
1073 information and some additional payload, usually a time stamp.
1074 Making a suitable choice of payload, it is possible to probe
1075 different host or router properties on the way as the emitted
1076 datagram travels to its destination.
1077
1078 @noindent
1079 Synopsis:
1080
1081 @example
1082 ping6 [@var{option}@dots{}] @var{host}
1083 @end example
1084
1085 @noindent
1086 Sending simple, timed echo requests is the standard use
1087 of @command{ping6}, but is by far not the only use case.
1088
1089 This command is a close parallel to @command{ping},
1090 except that it handles IPv6 and is thus not able
1091 to handle peculiarities of IPv4.
1092
1093 @section Command line options
1094 @anchor{ping6 options}
1095
1096 @table @option
1097 @item -c @var{n}
1098 @itemx --count=@var{n}
1099 @opindex -c
1100 @opindex --count
1101 Stop after sending and receiving answers to a total of
1102 @var{n} packets.
1103
1104 @item -d
1105 @itemx --debug
1106 @opindex -d
1107 @opindex --debug
1108 Set the SO_DEBUG option on the socket being used.
1109
1110 @item -f
1111 @itemx --flood
1112 @opindex -f
1113 @opindex --flood
1114 Flood ping.
1115 Outputs packets as fast as they come back,
1116 or one hundred times per second, whichever is more.
1117 For every ECHO_REQUEST packet sent, a period @samp{.} is printed,
1118 while for every ECHO_REPLY received in reply, a backspace is printed.
1119
1120 This provides a rapid display of how many packets are being dropped.
1121 Only the super-user may use this option.
1122 This mode can be very hard on a network.
1123 It should be used with caution!
1124
1125 @item --hoplimit=@var{n}
1126 @opindex --hoplimit
1127 Limit maximal distance to @var{n}.
1128 Acceptable values are 1 to 255, inclusive.
1129
1130 @item -i @var{n}
1131 @itemx --interval=@var{n}
1132 @opindex -i
1133 @opindex --interval
1134 Wait @var{n} seconds until sending next packet.
1135 The default is to wait for one second between packets.
1136 This option is incompatible with the option @option{-f}.
1137
1138 @item -l @var{n}
1139 @itemx --preload=@var{n}
1140 @opindex -l
1141 @opindex --preload
1142 Sends @var{n} packets as fast as possible before falling
1143 back to the normal mode of operation.
1144
1145 @item -n
1146 @itemx --numeric
1147 @opindex -n
1148 @opindex --numeric
1149 Numeric output only.
1150 No attempt will be made to resolve symbolic names for host addresses.
1151
1152 @item -p @var{pattern}
1153 @itemx --pattern=@var{pattern}
1154 @opindex -p
1155 @opindex --pattern
1156 Up to 16 hexadecimal pad bytes are given as @var{pattern}.
1157 These are use for filling out the packets you send.
1158 This option is useful for diagnosing data-dependent problems
1159 within a network.
1160 As an example, @option{-p ff} will cause the sent packets
1161 to have payloads with every bit set to one.
1162
1163 @item -q
1164 @itemx --quiet
1165 @opindex -q
1166 @opindex --quiet
1167 Do not print timing result of each transmitted packet.
1168
1169 @item -r
1170 @itemx --ignore-routing
1171 @opindex -r
1172 @opindex --ignore-routing-log
1173 Bypass the normal routing tables and send directly
1174 to a host on an attached network.
1175 If the host is not on a directly attached network,
1176 an error is returned.
1177 This option can be used to ping a local host
1178 through an interface, for which there is no
1179 assigned route, such as when the interface
1180 was dropped by @command{routed}.
1181
1182 @item -s @var{n}
1183 @itemx --size=@var{n}
1184 @opindex -s
1185 @opindex --size
1186 Specifies the number of data bytes to be sent. The default is 56,
1187 which translates into 64@tie{}ICMP data bytes, taking
1188 the 8@tie{}bytes of ICMP header data into account.
1189
1190 @item -T @var{num}
1191 @itemx --tos=@var{num}
1192 @opindex -T
1193 @opindex --tos
1194 Set the traffic class to @var{num} on transmitted packets.
1195
1196 @item --ttl=@var{n}
1197 @opindex --ttl
1198 Synonym for @option{--hoplimit}.
1199
1200 @item -v
1201 @itemx --verbose
1202 @opindex -v
1203 @opindex --verbose
1204 Produce more verbose output, giving more statistics.
1205
1206 @item -w @var{n}
1207 @itemx --timeout=@var{n}
1208 @opindex -w
1209 @opindex --timeout
1210 Stop after @var{n} seconds.
1211 @end table
1212
1213 The documentation of @command{ping} provides several
1214 pieces of information, and discussions, relevant to
1215 the use of @command{ping6}.
1216 Keep in mind, though, that the differing address family
1217 causes some discrepancy.
1218 @xref{ping invocation}.
1219
1220 @node traceroute invocation
1221 @chapter @command{traceroute}: Trace the route to a host
1222 @pindex traceroute
1223
1224 @command{traceroute} prints a trace of the route
1225 IP@tie{}packets are travelling to a remote host.
1226
1227 @noindent
1228 Synopsis:
1229
1230 @example
1231 traceroute [@var{option}@dots{}] @var{host}
1232 @end example
1233
1234 @section Command line options
1235 @anchor{traceroute options}
1236
1237 @table @option
1238 @item -f @var{num}
1239 @itemx --first-hop=@var{num}
1240 @opindex -f
1241 @opindex --first-hop
1242 Set the initial hop distance to @var{num}, instead of the default 1.
1243 This immediately allows probing packets to sense routing
1244 properties closer to the target host, skipping routers close
1245 to the local host. Quicker analysis of problems known to lie
1246 at some routing distance is the outcome.
1247
1248 @item -g @var{gates}
1249 @itemx --gateways=@var{gates}
1250 @opindex -g
1251 @opindex --gateways
1252 Set intermediary hosts used in loose source routing.
1253 The argument @var{gates} is a list of gateways,
1254 using space, comma, or semicolon as separators.
1255 These hosts must be traversed in the given order
1256 before the intended host receives any datagram.
1257 At most eight host names or addresses may be specified.
1258 Multiple uses of @option{-g} produce a concatenated list.
1259
1260 @item -I
1261 @itemx --icmp
1262 @opindex -I
1263 @opindex --icmp
1264 Use ICMP ECHO datagrams for probing the remote host.
1265
1266 @item -m @var{num}
1267 @itemx --max-hop=@var{num}
1268 @opindex -m
1269 @opindex --max-hop
1270 Set the maximum time-to-live allowed for probing.
1271 In other words, stop probing when the hop distance
1272 is in excess of @var{num}.
1273 The default limit is 64.
1274
1275 @item -M @var{method}
1276 @itemx --type=@var{method}
1277 @opindex -M
1278 @opindex --type
1279 Use @var{method} as carrier packets for traceroute operations.
1280 Supported choices are @samp{icmp} and @samp{udp}, where @samp{udp}
1281 is the default type.
1282
1283 @item -p @var{port}
1284 @itemx --port=@var{port}
1285 @opindex -p
1286 @opindex --port
1287 Set destination port of target to @var{port}.
1288 The default value is 33434.
1289
1290 @item -q @var{num}
1291 @itemx --tries=@var{num}
1292 @opindex -q
1293 @opindex --tries
1294 Send a total of @var{num} probe packets per hop, defaulting to 3.
1295
1296 @item --resolve-hostnames
1297 @opindex --resolve-hostnames
1298 Attempt to resolve all addresses as hostnames.
1299
1300 @item -t @var{num}
1301 @itemx --tos=@var{num}
1302 @opindex -t
1303 @opindex --tos
1304 Set type-of-service, TOS field, to @var{num} on
1305 transmitted packets.
1306
1307 @item -w @var{num}
1308 @itemx --wait=@var{num}
1309 @opindex -w
1310 @opindex --wait
1311 Set timeout in seconds, within which a returning response
1312 packet is accepted as such.
1313 Default waiting time is three seconds.
1314 @end table
1315
1316 @section Diagnostic tokens
1317 @anchor{traceroute printing}
1318
1319 During execution, @command{traceroute} sends three datagrams
1320 for each value for the TTL field, printing a diagnostic line
1321 of output for these. The TTL field is then steadily increased
1322 until the intended host responds, or some intermediary gateway
1323 returns a datagram to the effect that the target cannot be
1324 reached due to one reason or another.
1325
1326 Each line of output displays a sequence number, followed by
1327 diagnostic annotation. Any responding host has its address
1328 printed without repetition, together with a measured timing.
1329 In case there is no response within a time period of three seconds,
1330 an asterisque @samp{*} is printed.
1331
1332 When an intermediate router responds with an exceptional state,
1333 the time elapsed since emitting the original datagram is printed,
1334 followed by an additional short hand hint of the reason:
1335
1336 @table @samp
1337 @item !F
1338 Fragmentation needed by gateway.
1339
1340 @item !H
1341 Host not reachable from gateway.
1342
1343 @item !N
1344 Network not reachable from gateway.
1345
1346 @item !P
1347 Protocol not usable at host, or within network.
1348
1349 @item !S
1350 Source routing failed at gateway.
1351
1352 @item !T
1353 Host or network not reachable for stated type of service, TOS.
1354
1355 @item !U
1356 Isolated host, not reachable.
1357
1358 @item !X
1359 Forbidden by remote administration.
1360 @end table
1361
1362 @node whois invocation
1363 @chapter @command{whois}: User interface to WHOIS data bases.
1364 @pindex whois
1365
1366 The functionality of a world wide Internet is dependent on
1367 stored node information of different kinds.
1368 Registrars keep much relevant material in WHOIS data bases.
1369 This utility @command{whois} is able to query those sources
1370 for general and for particular properties of most domains.
1371
1372 For many domains there are names of suitable data base servers
1373 hard coded into @command{whois}, ready to query for domain
1374 relevant information.
1375 Since servers' names do change from time to time,
1376 this utility might occasionally need some guidance using
1377 a suitable command line option.
1378
1379 @noindent
1380 Synopsis:
1381
1382 @example
1383 whois [@var{OPTION}@dots{}] @var{OBJECT}@dots{}
1384 @end example
1385
1386 @section Command line options
1387 @anchor{whois options}
1388
1389 @table @option
1390 @item -a
1391 @opindex -a
1392 Search all data bases.
1393
1394 @item -F
1395 @opindex -F
1396 Fast and raw output. Implies @option{-r}.
1397
1398 @item -g @var{source}:@var{first}-@var{last}
1399 @opindex -g
1400 Find updates for an object from provider @var{source},
1401 starting from the version with serial key @var{first},
1402 and ending with serial key @var{last}.
1403
1404 @item -h @var{host}
1405 @itemx --server=@var{host}
1406 @opindex -h
1407 @opindex --server
1408 Connect to server @var{host}.
1409
1410 @item -H
1411 @opindex -H
1412 Hide legal disclaimers.
1413
1414 @item -i @var{attr}[,@var{attr2}@dots{}]
1415 @opindex -i
1416 Do an inverse lookup for specified attributes.
1417 Use a comma separated list for multiple attributes.
1418
1419 @item -l
1420 @opindex -l
1421 One level less specific lookup.
1422 Applies to RPSL only.
1423
1424 @item -L
1425 @opindex -L
1426 Find all less specific matches.
1427
1428 @item -m
1429 @opindex -m
1430 Find more specific matches, one level deeper.
1431
1432 @item -M
1433 @opindex -M
1434 Find all more specific matches.
1435
1436 @item -p @var{port}
1437 @opindex -p
1438 Connect to server port @var{port}.
1439
1440 @item -q @{version|sources@}
1441 @opindex -q
1442 Query specified server info.
1443 Applies to RPSL only.
1444
1445 @item -r
1446 @opindex -r
1447 Turn off recursive lookups.
1448
1449 @item -R
1450 @opindex -R
1451 Force output to show local copy of the domain object,
1452 even if it contains a referral.
1453
1454 @item -s @var{source}[,@var{source2}@dots{}]
1455 @opindex -s
1456 Search the data base at @var{source}.
1457 A comma separated list queries multiple providers.
1458
1459 @item -S
1460 @opindex -S
1461 Tell server to refrain from syntactic sugar.
1462
1463 @item -t @var{type}
1464 @opindex -t
1465 Request a template for objects of type @var{type}.
1466 Use the value @samp{all} for a list of possible types.
1467
1468 @item -T @var{type}[,@var{type2}@dots{}]
1469 @opindex -T
1470 Search only for objects of type @var{type}.
1471 A comma separated list allows for multiple types.
1472
1473 @item -V
1474 @itemx --verbose
1475 @opindex -V
1476 @opindex --verbose
1477 Verbosely explain all actions taken.
1478
1479 @item -x
1480 @opindex -x
1481 Search only for exact matches.
1482 Applicable only to RPSL.
1483 @end table
1484
1485 @section Environment variables
1486 @anchor{whois environment}
1487
1488 @command{whois} holds an internal list of information servers
1489 and their assigned data bases.
1490 Queries are examined against this list to select the most
1491 plausible server, but the hint can always be overruled on
1492 the command line by use of the option @option{-h}.
1493 If neither of these have a say, then the default server to ask
1494 is @samp{whois.internic.net}, but this name is in turn overruled
1495 by a server name in the environment variable @env{WHOIS_SERVER}.
1496
1497 @table @env
1498 @item LANG
1499 When the server @samp{whois.nic.ad.jp} is queried, and only then,
1500 any non-Japanese locale in @env{LANG} will ask the server to reply
1501 with English text, not Japanese.
1502
1503 @item WHOIS_HIDE
1504 When set, the effect on @command{whois} is as if the
1505 option @option{-H} had been given.
1506
1507 @item WHOIS_SERVER
1508 Data base server to query when internal hinting is inconclusive.
1509 When unset, @samp{whois.internic.net} is used as default server.
1510
1511 @end table
1512
1513 @node ftp invocation
1514 @chapter @command{ftp}: FTP client
1515 @pindex ftp
1516
1517 @command{ftp} is the user interface to FTP,
1518 the File Transfer Protocol.
1519 The program allows a user to transfer files to and from a remote
1520 network site.
1521
1522 @noindent
1523 Synopsis:
1524
1525 @example
1526 ftp [@var{option}@dots{}] [@var{host} [@var{port}]]
1527 pftp [@var{option}@dots{}] [@var{host} [@var{port}]]
1528
1529 ftp [@var{option}@dots{}] @var{user@@host} [@var{port}]
1530 pftp [@var{option}@dots{}] @var{user@@host} [@var{port}]
1531 @end example
1532
1533 @noindent
1534 The alternate name @command{pftp} is starting in passive mode,
1535 but is otherwise identical to @command{ftp}.
1536
1537 The client host with which @command{ftp} is to communicate may be
1538 specified on the command line.
1539 If this is done, @command{ftp} will immediately attempt to establish
1540 a connection to the FTP server running on that host.
1541 Optionally, a remote user name can be specified at will.
1542 Otherwise, the program will start a command interpreter and will await
1543 further instructions from the user.
1544 Commands can either be entered interactively,
1545 or piped as a batched job read from standard input.
1546 @command{ftp} is able to distinguish between these two modes
1547 of operation.
1548
1549 @menu
1550 * Ftp options::
1551 * Ftp commands::
1552 * Ftp environment::
1553 * Aborting a file transfer::
1554 * File naming conventions::
1555 * File transfer parameters::
1556 * The .netrc file::
1557 @end menu
1558
1559 @node Ftp options
1560 @section Command line options
1561 @anchor{ftp options}
1562
1563 Many command line options have counterparts among the
1564 commands handled by the internal interpreter.
1565
1566 @table @option
1567 @item -4
1568 @itemx --ipv4
1569 @opindex -4
1570 @opindex --ipv4
1571 Initially set addressing to IPv4 only.
1572
1573 @item -6
1574 @itemx --ipv6
1575 @opindex -6
1576 @opindex --ipv6
1577 Initially set addressing to IPv6 only.
1578
1579 @item -A
1580 @itemx --active
1581 @opindex -A
1582 @opindex --active
1583 Enable active mode transfer. Default mode for @command{ftp}.
1584
1585 @item -d
1586 @itemx --debug
1587 @opindex -d
1588 @opindex --debug
1589 Enable debugging output and possibly also socket debugging.
1590
1591 @item -e
1592 @itemx --no-edit
1593 @opindex -e
1594 @opindex --no-edit
1595 Disables the editing of commands. This is default setting for batch
1596 mode, without a TTY, or when the environment variable @env{TERM} is not
1597 set or its value is @samp{dumb}.
1598
1599 @item -g
1600 @itemx --no-glob
1601 @opindex -g
1602 @opindex --no-glob
1603 Disables file name globbing.
1604
1605 @item -i
1606 @itemx --no-prompt
1607 @opindex -i
1608 @opindex --no-prompt
1609 Turns off interactive prompting during multiple file transfers.
1610
1611 @item -N @var{netrc}
1612 @itemx --netrc=@var{netrc}
1613 @opindex -N
1614 @opindex --netrc
1615 Set a preferred location of the @file{.netrc} file,
1616 thus overriding any environment setting in @env{NETRC},
1617 as well as the default location @file{$HOME/.netrc},
1618 @pxref{The .netrc file}.
1619
1620 @item -n
1621 @itemx --no-login
1622 @opindex -n
1623 @opindex --no-login
1624 Restrains @command{ftp} from attempting @dfn{auto-login} upon initial
1625 connection. If auto-login is enabled, @command{ftp} will check the
1626 @file{.netrc} (@pxref{The .netrc file}) file in the user's home
1627 directory for an entry describing an account on the remote machine.
1628 If no entry exists, @command{ftp} will prompt for the remote machine
1629 login name (default is the user identity on the local machine), and,
1630 if necessary, prompt for a password and an account with which to
1631 login.
1632
1633 @item -p
1634 @itemx --passive
1635 @opindex -p
1636 @opindex --passive
1637 Enable passive mode transfer. Default mode when invoked
1638 as @command{pftp}.
1639
1640 @item --prompt[=@var{prompt}]
1641 @opindex --prompt
1642 Print a command-line prompt, even if not on a tty. If @var{prompt} is
1643 supplied, its value is used instead of the default @samp{ftp> }.
1644 Notice, that the argument is optional.
1645
1646 @item -t
1647 @itemx --trace
1648 @opindex -t
1649 @opindex --trace
1650 Enable packet tracing (not implemented).
1651
1652 @item -v
1653 @itemx --verbose
1654 @opindex -v
1655 @opindex --verbose
1656 Start in verbose mode, printing informational messages.
1657 This is default for interactive mode.
1658 @end table
1659
1660 @node Ftp commands
1661 @section Commands interpreted by @command{ftp}
1662
1663 When @command{ftp} is awaiting commands from the user,
1664 a prompt is displayed.
1665 The default string is @samp{ftp>}, but it can been
1666 changed with a command line option, perhaps to enhance
1667 uniqueness while recording a session.
1668
1669 Be aware that correct execution of many commands depends upon
1670 a proper behavior of the remote server.
1671 The following commands are recognized by @command{ftp} itself.
1672 Command names can be abbreviated to the shortest unique
1673 string with identical beginning.
1674
1675 @table @code
1676 @item ! [@var{command} [@var{args}]]
1677 Invoke an interactive shell on the local machine. If there are
1678 arguments, the first is taken to be a command to execute directly,
1679 with the rest of the arguments as its arguments.
1680
1681 @item $ @var{macro-name} [@var{args}]
1682 Execute the macro @var{macro-name} that was defined with the macdef
1683 command. Arguments are passed to the macro unglobbed.
1684
1685 @item account [@var{passwd}]
1686 Supply a supplemental password required by a remote system for access
1687 to resources, once a login has been successfully completed. If no
1688 argument is included, the user will be prompted for an account
1689 password in non-echoing input mode.
1690
1691 @item append @var{local-file} [@var{remote-file}]
1692 Append a local file to a file on the remote machine. If
1693 @var{remote-file} is left unspecified, the local file name is used in
1694 naming the remote file after being altered by any @code{ntrans} or
1695 @code{nmap} setting. File transfer uses the current settings for
1696 type, format, mode, and structure.
1697
1698 @item ascii
1699 Set the file transfer type to network ASCII. This is the default
1700 type, except when two unices are communicating.
1701
1702 @item bell
1703 Arrange that a bell be sounded after each file transfer command is
1704 completed.
1705
1706 @item binary
1707 Set the file transfer type to support binary image transfer.
1708 This transfer type is selected during initial handshake, should
1709 the client on a Unix system recognize that the server is also
1710 running on a Unix system.
1711
1712 @item bye
1713 @itemx quit
1714 Terminate the FTP session with the remote server and exit
1715 @command{ftp}. An end of file will also terminate the session and
1716 exit.
1717
1718 @item case
1719 Toggle the remote computer's use of letter case mapping during
1720 @code{mget} commands.
1721 When @code{case} is @samp{on},
1722 a file name at the remote site whose every letter appear
1723 in upper case, will be renamed in such a way that all letters
1724 are changed to lower case for a local copy of the same file.
1725 The default setting is @samp{off},
1726
1727 @item cd @var{remote-directory}
1728 Change the working directory on the remote machine to
1729 @var{remote-directory}.
1730
1731 @item cdup
1732 Change the remote machine's working directory to the parent of the
1733 current working directory.
1734
1735 @item chmod @var{mode} @var{file-name}
1736 Change the access permission of the file @var{file-name} on the remote
1737 system to @var{mode}.
1738
1739 @item close
1740 @itemx disconnect
1741 Terminate the FTP session with the present remote server,
1742 and return to the command interpreter.
1743 Any defined macros are erased.
1744
1745 @item cr
1746 Toggle carriage return stripping during ASCII type file retrieval.
1747 Records are denoted by a carriage return/linefeed sequence during
1748 ASCII type file transfer. When @code{cr} is @samp{on} (the default),
1749 carriage returns are stripped from this sequence to conform with the
1750 UNIX single linefeed record delimiter. Records on non-UNIX remote
1751 systems may contain single linefeeds; when an ASCII type transfer is
1752 made, these linefeeds may be distinguished from a record delimiter
1753 only when @code{cr} is @samp{off}.
1754
1755 @item delete @var{remote-file}
1756 Delete the file @var{remote-file} on the remote machine.
1757
1758 @item debug [@var{debug-value}]
1759 Toggle debugging mode. If an optional @var{debug-value} is specified
1760 it is used to set the debugging level. When debugging is on,
1761 @command{ftp} prints each command sent to the remote machine, preceded
1762 by the string @samp{-->}.
1763
1764 @item dir [@var{remote-directory}] [@var{local-file}]
1765 Print a listing of the contents in the directory
1766 @var{remote-directory}, and, optionally, place the output in
1767 @var{local-file}. If interactive prompting is set, @command{ftp} will
1768 prompt the user to verify that the last argument is the intended
1769 local file to receive output. If no directory is specified,
1770 the current working directory on the remote machine is used. If no
1771 local file is specified, or if @var{local-file} is a dash @samp{-},
1772 then output is displayed on the terminal.
1773
1774 @item epsv4
1775 Toggle the use of EPSV/EPRT for IPv4 addressing. Default is off.
1776
1777 @item form @var{format}
1778 Set the file transfer form to @var{format}. The only supported
1779 format is @samp{non-print}.
1780
1781 @item get @var{remote-file} [@var{local-file}]
1782 @itemx recv @var{remote-file} [@var{local-file}]
1783 Retrieve the @var{remote-file} and store it on the local machine.
1784 If a local file name is not specified, the local copy is given the
1785 same name as is stated for the remote original, subject to alteration
1786 by the current @code{case}, @code{ntrans}, and @code{nmap} settings.
1787 The current settings for @code{type}, @code{form}, @code{mode},
1788 and @code{structure} are effective during file transfer.
1789
1790 @item glob
1791 Toggle file name expansion for @code{mdelete}, @code{mget}, and
1792 @code{mput}. If globbing is turned off with @code{glob}, the file
1793 name arguments are taken literally and are not expanded. Globbing for
1794 @code{mput} is done as in @command{csh} syntax.
1795 For @code{mdelete} and
1796 @code{mget}, each remote file name is expanded separately on the
1797 remote machine and the lists are not merged. Expansion of a directory
1798 name is likely to be different from expansion of the name of an
1799 ordinary file: the exact result depends on the remote operating
1800 system and on the FTP server, and can be previewed by
1801 issuing @samp{mls remote-files -}.
1802
1803 Note: @code{mget} and @code{mput} are not meant to transfer entire
1804 directory subtrees of files. That can be achieved by transferring
1805 an already created @command{tar} or @command{cpio} archive of the
1806 subtree, then making certain that @command{ftp} uses binary mode.
1807
1808 @item hash [@var{size}]
1809 In the absence of an argument, toggle the state of hash-sign (@samp{#})
1810 printing after each transferred data block.
1811 The optional argument selects the size of data blocks,
1812 and unconditionally activates printing.
1813 The default size is 1024 bytes.
1814 For convenience, the size can be written with postfix multipliers
1815 'k', 'K', 'm', 'M', and 'g', 'G', to specify kilobytes, Megabytes,
1816 and Gigabytes, respectively.
1817
1818 @item help [@var{command}]
1819 @itemx ? [@var{command}]
1820 Print an informative message about the meaning of command. If no
1821 argument is given, @command{ftp} prints a list of the known commands.
1822
1823 @item idle [@var{seconds}]
1824 Set the inactivity timer on the remote server to @var{seconds}
1825 seconds. If seconds is omitted, the current inactivity timer is
1826 printed.
1827
1828 @item ipv4
1829 Select IPv4 as the only addressing scheme.
1830
1831 @item ipv6
1832 Select IPv6 as the only addressing scheme.
1833
1834 @item ipany
1835 Allow IPv4 as well as IPv6 addressing.
1836
1837 @item lcd [@var{directory}]
1838 Change the working directory on the local machine. If no directory is
1839 specified, the user's home directory is used.
1840
1841 @item lpwd
1842 Print the name of the current working directory on the local machine.
1843
1844 @item ls [@var{remote-directory}] [@var{local-file}]
1845 Print a listing of the contents of a directory on the remote machine.
1846 The listing includes any system-dependent information that the server
1847 chooses to include; for example, most UNIX systems will produce output
1848 like the command @command{ls -l} does.
1849 Use @code{nlist} for a simple file listing.
1850
1851 If @var{remote-directory} is left unspecified, the current working
1852 directory is used. With interactive prompting set,
1853 @command{ftp} will prompt the user to verify that the
1854 last argument is indeed the intended local file for storing output.
1855 Should no local file be specified, or if @var{local-file} is a
1856 dash@tie{}@samp{-}, then output is sent to the terminal.
1857
1858 @item macdef @var{macro-name}
1859 Define a macro called @var{macro-name}, with subsequent lines as the
1860 macro definition. A null line (consecutive newline characters in a
1861 file, or carriage returns at a terminal) terminates macro input
1862 mode. There is a limit of 16 macros and a total of 4096 characters
1863 shared by all defined macros. Only the first eight characters in
1864 @var{macro-name} are significant when determining which
1865 macro to execute.
1866 Macros remain defined until a close command is executed.
1867
1868 The macro processor interprets @samp{$} and @samp{\} as
1869 special characters. A @samp{$} followed by a number (one or more
1870 digits) is replaced by the corresponding argument on the macro's
1871 invocation command line.
1872 A @samp{$} followed by the letter @samp{i} tells the macro processor
1873 that the macro is to perform a loop.
1874 On the first pass, @samp{$i} is replaced by the first argument on
1875 the macro's invocation command line, while on the second pass it is
1876 replaced by the second argument, and so forth.
1877 Iteration proceeds until all arguments have been consumed.
1878
1879 A backslash @samp{\} followed by any character is replaced by that
1880 character. Use the backslash @samp{\} to prevent special treatment
1881 of the dollar sign @samp{$}, as was just explained.
1882
1883 A macro can execute a macro, allowing recursion. In order to avoid
1884 exhausting the stack and thus crashing @command{ftp}, the nesting
1885 depth of macro execution is limited to a compile time constant.
1886
1887 @item mdelete [@var{remote-files}]
1888 Delete all @var{remote-files} on the remote machine.
1889
1890 @item mdir @var{remote-files} @var{local-file}
1891 Like @code{dir}, except multiple remote files may be specified. If
1892 interactive prompting is on, @command{ftp} will prompt the user to
1893 verify that the last argument is indeed the intended local file for
1894 storing any output from @code{mdir}.
1895
1896 @item mget @var{remote-files}
1897 Expand the @var{remote-files} on the remote machine and execute
1898 a @code{get} for each file name thus produced.
1899 Resulting file names will then be processed according to
1900 @code{case}, @code{ntrans}, and @code{nmap} settings.
1901 Files are transferred to the local working directory,
1902 which can be changed with @code{lcd directory}; new local directories
1903 can be created with @code{! mkdir directory}.
1904
1905 @item mkdir @var{directory-name}
1906 Make a directory on the remote machine.
1907
1908 @item mls @var{remote-files} @var{local-file}
1909 Like @code{nlist}, except multiple remote files may be specified, and
1910 the @var{local-file} must be specified. If interactive prompting is
1911 on, @command{ftp} will prompt the user to verify that the last
1912 argument is the intended local file for storing output.
1913 A dash @samp{-} is accepted as last argument without check!
1914
1915 @item mode [@var{mode-name}]
1916 Set the file transfer mode to @var{mode-name}. The default mode is
1917 @samp{stream}, and it is also the only implemented mode.
1918
1919 @item modtime @var{file-name}
1920 Show the last modification time of the file on the remote machine.
1921
1922 @item mput @var{local-files}
1923 Consider the arguments to be local names and expand any wild card.
1924 Execute a @code{put} for each file in the resulting list.
1925 The remote file names are then computed by use of
1926 @code{ntrans} and @code{nmap} settings.
1927
1928 @item newer @var{file-name}
1929 Get the file only if the modification time of the remote file is more
1930 recent than the file on the current system. If the file does not
1931 exist on the current system, the remote file is considered newer.
1932 In other respects, this command is identical to @code{get}.
1933
1934 @item nlist [@var{remote-directory}] [@var{local-file}]
1935 Print a list of the files in a directory on the remote machine. If
1936 @var{remote-directory} is left unspecified, the current working
1937 directory is used. If interactive prompting is on, @command{ftp} will
1938 prompt the user to verify that the last argument is the intended
1939 local file for storing output. If no local file is specified,
1940 or if @var{local-file} is @samp{-}, the output is sent to the
1941 terminal.
1942
1943 @item nmap [@var{inpattern} @var{outpattern}]
1944 Set or unset the file name mapping mechanism. If no arguments are
1945 specified, the file name mapping mechanism is unset.
1946 Name mapping is applied during @code{mput} and
1947 @code{put} commands issued without a specified remote target filename.
1948 It as also applied to local file names during
1949 @code{mget} and @code{get} commands issued without
1950 local target file name. This command is useful when
1951 connecting to a non-UNIX remote computer with different file naming
1952 conventions or practices.
1953
1954 The mapping follows the pattern set by @var{inpattern} and
1955 @var{outpattern}. The template @var{inpattern} is used on incoming
1956 filenames (which may have already been processed according to the
1957 @code{ntrans} and @code{case} settings).
1958 Variable templating is accomplished
1959 by including the sequences @samp{$1}, @samp{$2}, @dots{}, @samp{$9} in
1960 @var{inpattern}. Use @samp{\} to prevent this special treatment of
1961 the character @samp{$}. All other characters are treated literally,
1962 and must be matched in a file name for @var{inpattern}
1963 to bind substrings to variables.
1964
1965 For example, take a pattern @samp{$1.$2} and a file name
1966 @file{mydata.data}.
1967 Then @samp{$1} would have the value @samp{mydata}, and
1968 @samp{$2} would be @samp{data}.
1969
1970 @var{outpattern} determines the final file name.
1971 The sequences @samp{$1} to @samp{$9} are
1972 replaced by any values bound to them by @var{inpattern}.
1973 A special sequence @samp{$0} always contains the original filename.
1974 In addition, a bracketted sequence @samp{[@var{seq1},@var{seq2}]}
1975 expands to @var{seq1} if @var{seq1} contains a non-empty string,
1976 and expands to @var{seq2} otherwise. For example, the command
1977
1978 @example
1979 nmap $1.$2.$3 [$1,$2].[$2,file]
1980 @end example
1981
1982 would yield the output file name @file{myfile.data} for input names
1983 @file{myfile.data} and @file{myfile.data.old},
1984 but produces @file{myfile.file} from the input @file{myfile},
1985 and @file{myfile.myfile} from @file{.myfile}.
1986
1987 Spaces may be included in @var{outpattern}, but are easily removed:
1988
1989 @example
1990 nmap $1 |sed "s/ *$//" > $1
1991 @end example
1992
1993 Use a backslash @samp{\} to escape the characters
1994 @samp{$}, @samp{[}, @samp{]}, and @samp{,}.
1995
1996 @item ntrans [@var{inchars} [@var{outchars}]]
1997 Set or unset the filename character translation mechanism. If no
1998 arguments are specified, the filename character translation mechanism
1999 is unset. If arguments are specified, characters in remote filenames
2000 are translated during @code{mput} commands and @code{put} commands
2001 issued without a specified remote target filename. If arguments are
2002 specified, characters in local filenames are translated during
2003 @code{mget} commands and @code{get} commands issued without a
2004 specified local target filename. This command is useful when
2005 connecting to a non-UNIX remote computer with different file naming
2006 conventions or practices.
2007
2008 Characters in a filename matching a character in @var{inchars} are
2009 replaced with the corresponding character in @var{outchars}. If the
2010 character's position in @var{inchars} is longer than the length of
2011 @var{outchars}, the character is deleted from the file name.
2012
2013 @item open @var{host} [@var{port}]
2014 @itemx open @var{user@@host} [@var{port}]
2015 Establish a connection to the specified FTP server
2016 at @var{host}. An optional port number may be supplied,
2017 in which case, @command{ftp} will attempt to contact the server
2018 at that specific TCP port. If the @code{autologin} option
2019 is on (is so by default), @command{ftp} will also attempt to
2020 automatically log the user in to the FTP server.
2021
2022 The second form of invocation sets the remote user name to @var{user},
2023 which otherwise is taken as identical to the user identity owning the
2024 local session.
2025
2026 @item passive
2027 Toggle passive mode. If passive mode is turned on (default is off),
2028 the @command{ftp} client will send a @code{PASV} command for all data
2029 connections instead of the usual @code{PORT} command. The @code{PASV}
2030 command requests that the remote server open a port for the data
2031 connection and return the address of that port. The remote server
2032 listens on that port and the client connects to it. When using the
2033 more traditional @code{PORT} command, the client listens on a port and
2034 sends that address to the remote server, who connects back to it.
2035 Passive mode is useful when using @command{ftp} through a gateway
2036 router or host that controls the directionality of traffic. (Note
2037 that though @command{ftp} servers are required to support the
2038 @code{PASV} command by RFC 1123, some do not.) If @command{epsv4}
2039 has been set to on, the client will attempt @code{EPSV} before
2040 @code{PASV} for IPv4. As a last resort @code{LPSV} is attempted.
2041 With IPv6 only @code{EPSV} and @code{LPSV} are possible.
2042
2043 @item prompt
2044 Toggle interactive prompting. Interactive prompting occurs during
2045 multiple file transfers to allow the user to selectively retrieve or
2046 store files. If prompting is turned off (default is on), any
2047 @code{mget} or @code{mput} will transfer all files, and any
2048 @code{mdelete} will delete all files.
2049
2050 @item proxy @var{ftp-command}
2051 Execute an @command{ftp} command on a secondary control connection.
2052 This command allows simultaneous connection to two remote FTP servers
2053 for transferring files between the two servers. The first proxy
2054 command should be @code{open}, to establish the secondary control
2055 connection. Enter the command @code{proxy ?} to see other
2056 commands usable for the secondary connection. The following
2057 commands behave differently when prefaced by @code{proxy}: @code{open}
2058 will not define new macros during the auto-login process, @code{close}
2059 will not erase existing macro definitions, @code{get} and @code{mget}
2060 transfer files from the host on the primary control connection to the
2061 host on the secondary control connection, and @code{put}, @code{mput},
2062 and @code{append} transfer files from the host on the secondary
2063 control connection to the host on the primary control connection.
2064
2065 Note that the protocol command @code{PASV} must be understood
2066 by the server on the secondary control connection for this kind
2067 of file transfer to succeed.
2068
2069 @item put @var{local-file} [@var{remote-file}]
2070 @itemx send @var{local-file} [@var{remote-file}]
2071 Store a local file on the remote machine. If @var{remote-file} is
2072 left unspecified, the local file name is used after processing
2073 according to any @code{ntrans} or @code{nmap} settings in naming the
2074 remote file. File transfer uses the current settings for type,
2075 format, mode, and structure.
2076
2077 @item pwd
2078 Print the name of the current working directory on the remote machine.
2079
2080 @item quote @var{arg}@dots{}
2081 The arguments specified are sent, verbatim, to the remote FTP server.
2082
2083 @item reget @var{remote-file} [@var{local-file}]
2084 @code{reget} acts like @code{get}, except that if @var{local-file}
2085 exists and is smaller than @var{remote-file}, then @var{local-file} is
2086 presumed to be a partially transferred copy of @var{remote-file} and
2087 the transfer is continued from the apparent point of failure. This
2088 command is useful when transferring very large files over networks
2089 that are prone to dropping connections.
2090
2091 @item rhelp [@var{command-name}]
2092 Request help from the remote FTP server.
2093 If @var{command-name} is specified it is passed to the server as well.
2094
2095 @item rstatus [@var{file-name}]
2096 With no arguments, show status of remote machine. If filename is
2097 specified, show status of @var{file-name} on remote machine.
2098
2099 @item rename [@var{from}] [@var{to}]
2100 Rename the file @var{from} on the remote machine as @var{to}.
2101 Name mapping takes effect without @var{to}.
2102
2103 @item reset
2104 Clear reply queue. This command re-synchronizes command/reply
2105 sequencing with the remote FTP server. Resynchronization may be
2106 necessary following a violation of the FTP protocol by the remote
2107 server.
2108
2109 @item restart @var{marker}
2110 Restart the immediately following @code{get} or @code{put} at the
2111 indicated marker. On UNIX systems, @code{marker} is usually
2112 a byte offset into the file.
2113
2114 @item rmdir @var{directory-name}
2115 Delete a directory on the remote machine.
2116
2117 @item runique
2118 Toggle the storing of files on the local system with unique filenames.
2119 If a file already exists with a name equal to the intended local file
2120 name for a @code{get} or @code{mget} command,
2121 then a string @samp{.1} is appended to the name.
2122 If the resulting name matches another existing file,
2123 @samp{.2} is appended to the original name. If this process continues
2124 up to @samp{.99}, an error message is printed, and the transfer does
2125 not take place. The generated unique filename will be reported. Note
2126 that @code{runique} will not affect local files generated from a shell
2127 command. The default value is off.
2128
2129 @item sendport
2130 Toggle the use of @code{PORT} commands. By default, @command{ftp}
2131 will attempt to use a @code{PORT} command when establishing a
2132 connection for each data transfer. The use of @code{PORT} commands
2133 can prevent delays when performing multiple file transfers. If the
2134 @code{PORT} command fails, @command{ftp} will use the default data
2135 port. When the use of @code{PORT} commands is disabled, no attempt
2136 will be made to use @code{PORT} commands for each data transfer. This
2137 is useful for certain FTP implementations which do ignore @code{PORT}
2138 commands but, incorrectly, indicate they've been accepted.
2139
2140 @item site @var{arg}@dots{}
2141 The arguments specified are sent, verbatim, to the remote FTP server
2142 as a @code{SITE} command.
2143
2144 @item size @var{file-name}
2145 Return size of @var{file-name} on remote machine.
2146
2147 @item status
2148 Show the current status of @command{ftp}.
2149
2150 @item struct [@var{struct-name}]
2151 Set the file transfer structure to @var{struct-name}. By default
2152 @samp{file} structure is used, which also is the only supported
2153 value.
2154
2155 @item sunique
2156 Toggle storing of files on remote machine under unique file names.
2157 Remote FTP server must support FTP protocol @code{STOU} command for
2158 successful completion. The remote server will report unique name.
2159 Default value is off.
2160
2161 @item system
2162 Show the type of operating system running on the remote machine.
2163
2164 @item tenex
2165 Set the file transfer type to that needed to talk to TENEX machines.
2166
2167 @item trace
2168 Toggle packet tracing (feature is not implemented).
2169
2170 @item type [@var{type-name}]
2171 Set the file transfer type to @var{type-name}. If no type is
2172 specified, the current type is printed.
2173 The recognized type names are @samp{ascii}, @samp{binary},
2174 @samp{ebcdic}, @samp{image}, and @samp{tenex}.
2175 The default type is network ASCII.
2176
2177 @item umask [@var{newmask}]
2178 Set the default umask on the remote server to @var{newmask}. If
2179 @var{newmask} is omitted, the current umask is printed.
2180
2181 @item user @var{user-name} [@var{password}] [@var{account}]
2182 Identify yourself to the remote FTP server. If the password is not
2183 specified and the server requires it, @command{ftp} will prompt the
2184 user for it (after disabling local echo). If an account field is not
2185 specified, and the FTP server requires it, the user will be prompted
2186 for it. If an account field is specified, an account command will be
2187 relayed to the remote server after the login sequence is completed if
2188 the remote server did not require it for logging in. Unless
2189 @command{ftp} is invoked with @code{auto-login} disabled, this process
2190 is done automatically on initial connection to the FTP server.
2191
2192 @item verbose
2193 Toggle verbose mode. In verbose mode, all responses from the FTP
2194 server are displayed to the user. In addition, if verbose is on, when
2195 a file transfer completes, statistics regarding the efficiency of the
2196 transfer are reported. By default, verbose is on.
2197 @end table
2198
2199 Command arguments which have embedded spaces may be inclosed within
2200 citation characters @samp{"}.
2201
2202 @node Ftp environment
2203 @section Environment variables in use
2204
2205 @command{ftp} accesses the following environment variables.
2206
2207 @table @env
2208 @item HOME
2209 Used for locating a @file{.netrc} file, if one exists.
2210
2211 @item NETRC
2212 Alternate location of the @file{.netrc} file,
2213 taking precedence over the standard location.
2214
2215 @item SHELL
2216 For determining the default shell interpreter.
2217 @end table
2218
2219 @node Aborting a file transfer
2220 @section Aborting a file transfer
2221
2222 To abort a file transfer, use the terminal interrupt key (usually
2223 @kbd{C-c}). Sending transfers will be immediately halted.
2224 Receiving transfers will be halted by sending a FTP
2225 protocol command @code{ABOR} to the remote server,
2226 discarding any further data received. The speed at
2227 which this is accomplished depends upon the remote server's support
2228 for @code{ABOR} processing. If the remote server does not support the
2229 @code{ABOR} command, an @samp{ftp>} prompt will not appear until the
2230 remote server has completed sending the requested file.
2231
2232 The terminal interrupt key sequence will be ignored when @command{ftp}
2233 has completed any local processing and is awaiting a reply from the
2234 remote server. A long delay in this mode may result from the
2235 @code{ABOR} processing described above, or from unexpected behavior by
2236 the remote server, including violations of the FTP protocol.
2237 If the
2238 delay results from unexpected remote server behavior, the local
2239 @command{ftp} program must be killed by hand.
2240
2241 @node File naming conventions
2242 @section File naming conventions
2243
2244 Files specified as arguments to @command{ftp} commands are processed
2245 according to the following rules.
2246
2247 @enumerate
2248 @item
2249 If the file name @samp{-} is specified, standard input (for reading)
2250 or standard output (for writing) is used.
2251
2252 @item
2253 If the first character of the file name is @samp{|}, the remainder of
2254 the argument is interpreted as a shell command. @command{ftp} then
2255 forks a shell, using @code{popen} with the argument supplied, and
2256 reads/writes from standard input/output. If the shell command
2257 includes spaces, the argument must be quoted; e.g. @samp{"ls -lt"}.
2258
2259 A particularly useful example of this mechanism in action, is
2260
2261 @example
2262 ftp> dir . |less
2263 @end example
2264
2265 which allows the user to scroll through a long directory listing.
2266
2267 @item
2268 Failing the above checks, if @dfn{globbing} is enabled, local file
2269 names are expanded according to the rules used by @command{csh};
2270 c.f. the @code{glob} command. If the @command{ftp} command expects a
2271 single local file (e.g. @code{put}), only the first filename
2272 generated by the globbing operation is used.
2273
2274 @item
2275 For the commands @code{mget} and @code{get} with unspecified
2276 local file name, the local file name is set to the remote file name,
2277 which may be altered by a @code{case}, @code{ntrans}, or @code{nmap}
2278 settings.
2279 The resulting file name may then be modified if @code{runique} is set.
2280
2281 @item
2282 For the commands @code{mput} and @code{put} with unspecified
2283 remote file name, the remote file name is copied from the local
2284 file name, which may be altered by a @code{ntrans} or @code{nmap}
2285 settings.
2286 The resulting file name may also be modified by the remote server if
2287 @code{sunique} is set.
2288 @end enumerate
2289
2290 @node File transfer parameters
2291 @section File transfer parameters
2292
2293 The FTP specification includes many parameters which may affect a
2294 file transfer. The type may be one of @samp{ascii}, @samp{image}
2295 (binary), @samp{ebcdic}, and @samp{local} byte size (for PDP-10's and
2296 PDP-20's mostly). @command{ftp} supports the @samp{ascii} and
2297 @samp{image} types of file transfer, plus local byte size 8 for tenex
2298 mode transfers.
2299
2300 @command{ftp} supports only the default values for the remaining file
2301 transfer parameters: @code{mode}, @code{form}, and @code{struct}.
2302
2303 An error in the treatment of carriage returns in the 4.2BSD ascii-mode
2304 transfer code has been corrected by the present implementation.
2305 This correction may result in corrupt transfers of binary files
2306 to and from 4.2BSD servers, when done using the ascii type.
2307 Avoid this problem by using the binary image type.
2308
2309 @node The .netrc file
2310 @section The @file{.netrc} file
2311 @flindex .netrc
2312
2313 The @file{.netrc} file contains login and initialization information
2314 used by the auto-login process. It generally resides in the user's
2315 home directory, but a location outside of the home directory
2316 can be set using the environment variable @env{NETRC}.
2317 Both locations are overridden by the command line option @option{-N}.
2318 The selected file must be a regular file, or access will be denied.
2319
2320 The following tokens are recognized; they may be separated
2321 by spaces, tabs, or new-lines:
2322
2323 @table @samp
2324 @item machine name
2325 Identify a remote machine name. The auto-login process searches the
2326 @file{.netrc} file for a machine token that matches the remote machine
2327 specified on the @command{ftp} command line or as an open command
2328 argument. Once a match is made, the subsequent @file{.netrc} tokens
2329 are processed, stopping when the end of file is reached or another
2330 machine or a default token is encountered.
2331
2332 @item default
2333 This is the same as machine name except that default matches any name.
2334 There can be only one default token, and it must be after all machine
2335 tokens. This is normally used as:
2336
2337 @example
2338 default login anonymous password user@@site
2339 @end example
2340
2341 thereby giving the user automatic anonymous ftp login to machines not
2342 specified in @file{.netrc}. This can be overridden by using the
2343 @option{-n} flag to disable auto-login.
2344
2345 @item login name
2346 Identify a user on the remote machine. If this token is present, the
2347 auto-login process will initiate a login using the specified name.
2348
2349 @item password string
2350 Supply a password. If this token is present, the auto-login process
2351 will supply the specified string if the remote server requires a
2352 password as part of the login process. Note that if this token is
2353 present in the @file{.netrc} file for any user other than anonymous,
2354 @command{ftp} will abort the auto-login process if the @file{.netrc}
2355 is readable by anyone besides the user.
2356
2357 @item account string
2358 Supply an additional account password. If this token is present, the
2359 auto-login process will supply the specified string if the remote
2360 server requires an additional account password, or the auto-login
2361 process will initiate an @code{ACCT} command if it does not.
2362
2363 @item macdef name
2364 Define a macro. This token functions like the @command{ftp}
2365 @code{macdef} command functions. A macro is defined with the
2366 specified name; its contents begin with the next @file{.netrc} line
2367 and continue until a null line (consecutive new-line characters) is
2368 encountered. If a macro named init is defined, it is automatically
2369 executed as the last step in the auto-login process.
2370 @end table
2371
2372 @node rcp invocation
2373 @chapter @command{rcp}: Copy files between machines
2374 @pindex rcp
2375
2376 @command{rcp} copies files between machines. Each file or directory
2377 argument is either a remote file name of the form
2378 @samp{rname@@rhost:path}, or a local file name (containing no @samp{:}
2379 characters, or a @samp{/} before any @samp{:}s).
2380
2381 @noindent
2382 Synopsis:
2383
2384 @example
2385 rcp [@var{option}]@dots{} @var{old-file} @var{new-file}
2386 rcp [@var{option}]@dots{} @var{files}@dots{} @var{directory}
2387 @end example
2388
2389 @section Command line options
2390 @anchor{rcp options}
2391
2392 @table @option
2393 @item -4
2394 @itemx --ipv4
2395 @opindex -4
2396 @opindex --ipv4
2397 Use only IPv4.
2398
2399 @item -6
2400 @itemx --ipv6
2401 @opindex -6
2402 @opindex --ipv6
2403 Use only IPv6.
2404
2405 @item -d @var{directory}
2406 @itemx --target-directory=@var{directory}
2407 @opindex -d
2408 @opindex --target-directory
2409 Copy all source arguments into @var{directory}.
2410
2411 @item -f
2412 @itemx --from
2413 @opindex -f
2414 @opindex --from
2415 (Server mode only.) Copying from remote host.
2416
2417 @item -k @var{realm}
2418 @itemx --realm=@var{realm}
2419 @opindex -k
2420 @opindex --realm
2421 The option requests rcp to obtain tickets for the remote host in
2422 realm @var{realm} instead of the remote host's realm.
2423
2424 @item -K
2425 @itemx --kerberos
2426 @opindex -K
2427 @opindex --kerberos
2428 Turns off all Kerberos authentication.
2429
2430 @item -p
2431 @itemx --preserve
2432 @opindex -p
2433 @opindex --preserve
2434 Causes @code{rcp} to attempt to preserve (duplicate) in its copies the
2435 modification times and modes of the source files, ignoring the umask.
2436 By default, the mode and owner of the target file are preserved
2437 if the target itself already exists; otherwise the mode of the source
2438 file is modified by the @code{umask} setting on the destination host.
2439
2440 @item -r
2441 @itemx --recursive
2442 @opindex -r
2443 @opindex --recursive
2444 If any of the source files are directories, @command{rcp} copies each
2445 subtree rooted at that name; in this case the destination must be a
2446 directory.
2447
2448 @item -t
2449 @itemx --to
2450 @opindex -t
2451 @opindex --to
2452 (Server mode only.) Copying to remote host.
2453
2454 @item -x
2455 @itemx --encrypt
2456 @opindex -x
2457 @opindex --encrypt
2458 Turns on encryption for all data passed via the @command{rcp} session.
2459 This may impact response time and CPU utilization, but provides increased
2460 security.
2461
2462 @end table
2463
2464 @command{rcp} doesn't detect all cases where the target of a copy
2465 might be a file in cases where only a directory should be legal.
2466
2467 @command{rcp} can be confused by any output generated by commands in a
2468 @file{.login}, @file{.profile}, or @file{.cshrc} file on the remote
2469 host.
2470
2471 The destination user and hostname may have to be specified as
2472 @samp{rhost.rname} when the destination machine is running the 4.2BSD
2473 version of @command{rcp}.
2474
2475 @node rexec invocation
2476 @chapter @command{rexec}: a remote execution program
2477 @pindex rexec
2478
2479 @command{rexec} is a program that executes a program on another host.
2480
2481 @noindent
2482 Synopsis:
2483
2484 @example
2485 rexec --user=@var{login} --password=@var{pass} --host=@var{host} \
2486 @verb{| |}[OPTION] @var{command}
2487 @end example
2488
2489 @section Command line options
2490 @anchor{rexec options}
2491
2492 @table @option
2493 @item -4
2494 @itemx --ipv4
2495 @opindex -4
2496 @opindex --ipv4
2497 Use only IPv4 connections as all times.
2498
2499 @item -6
2500 @itemx --ipv6
2501 @opindex -6
2502 @opindex --ipv6
2503 Use only IPv6 connections.
2504
2505 @item -a
2506 @itemx --ipany
2507 @opindex -a
2508 @opindex --ipany
2509 Allow any address family for connections. This is the default.
2510
2511 @item -e
2512 @itemx --error=@var{port}
2513 @opindex -e
2514 @opindex --error
2515 Specify the TCP port to use for stderr redirection, in case it is not
2516 specified a random port will be used.
2517
2518 @item -h
2519 @item --host=@var{name}
2520 @opindex -h
2521 @opindex --host
2522 Specify the host with whom to connect: symbolic name or address.
2523
2524 @item -n
2525 @itemx --noerr
2526 @opindex -n
2527 @opindex --noerr
2528 If specified, an error stream will not be created.
2529
2530 @item -p
2531 @itemx --password=@var{passwd}
2532 @opindex -p
2533 @opindex --password
2534 Specify the password for logging-in. The special value
2535 consisting of a single dash @samp{-} will make @command{rexec}
2536 read a single line from stdin. This input is then used
2537 as password and is passed as such to the remote server.
2538 Thus it is possible to hide vital access information
2539 slightly better than the full disclosure implicit in
2540 the text of a command line option.
2541
2542 @item -P
2543 @itemx --port=@var{num}
2544 @opindex -P
2545 @opindex --port
2546 Specify to which numerical port a connection shall be sought.
2547 If it is not specified, then use port 512/tcp by default.
2548
2549 @item -u
2550 @itemx --user=@var{name}
2551 @opindex -u
2552 @opindex --user
2553 Specify the user with whom to log into the server.
2554 @end table
2555
2556 @node rlogin invocation
2557 @chapter @command{rlogin}: Remote login
2558 @pindex rlogin
2559
2560 The @command{rlogin} command starts a terminal session on the
2561 specified remote host, provided the required authentication
2562 is successful. The remote terminal type is the same as that
2563 given in the @env{TERM} local environment variable.
2564 The terminal and the window size stay the same, if the remote
2565 host supports them, and any changes in size are transferred
2566 as need may be.
2567
2568 When using the @command{rlogin} command, you can create a link
2569 in your path, using a host name as the link name. For example:
2570
2571 @example
2572 # ln -s /usr/bin/rlogin @var{hostname}
2573 # @var{hostname} -8
2574 @end example
2575
2576 @noindent
2577 Afterwards, the use of @var{hostname} will automatically invoke
2578 @command{rlogin} to direct a log in request to the remote host
2579 named @var{hostname}.
2580
2581 @command{rlogin} allows access to the remote host without the use of a
2582 password. The prerequisite is a suitable specification in @file{~/.rhosts}.
2583 For details, @xref{rcmd, , rcmd, libc, The GNU C Library Reference Manual}.
2584
2585 @section Command line options
2586 @anchor{rlogin options}
2587
2588 The options are as follows :
2589
2590 @table @option
2591 @item -4
2592 @itemx --ipv4
2593 @opindex -4
2594 @opindex --ipv4
2595 Use only IPv4.
2596
2597 @item -6
2598 @itemx --ipv6
2599 @opindex -6
2600 @opindex --ipv6
2601 Use only IPv6.
2602
2603 @item -8
2604 @itemx --8-bit
2605 @opindex -8
2606 @opindex --8-bit
2607 Allows an eight-bit input data path at all times; otherwise parity
2608 bits are stripped except when the remote side's stop and start
2609 characters are other than @kbd{C-S}/@kbd{C-Q}.
2610
2611 @item -d
2612 @itemx --debug
2613 @opindex -d
2614 @opindex --debug
2615 Turns on socket debugging on the TCP sockets used for communication
2616 with the remote host.
2617
2618 @item -e @var{char}
2619 @itemx --escape=@var{char}
2620 @opindex -e
2621 @opindex --escape
2622 Allows user specification of the escape character, which is @samp{~}
2623 by default. This specification may be as a literal character, or as
2624 an octal value in the form @samp{\nnn}.
2625
2626 @item -E
2627 @itemx --no-escape
2628 @opindex -E
2629 @opindex --no-escape
2630 Stops any character from being recognized as an escape character.
2631 When used with the @option{-8} option, this provides a completely
2632 transparent connection.
2633
2634 @item -l @var{user}
2635 @itemx --user=@var{user}
2636 @opindex -l
2637 @opindex --user
2638 By default, the remote username is the same as the local username.
2639 This option, and the @samp{user@@host} format, allow the remote
2640 user name to be made explicit, or changed.
2641 @end table
2642
2643 @noindent
2644 The next three options are available only if the program
2645 has been compiled with support for Kerberos authentication.
2646
2647 @table @option
2648 @item -k @var{realm}
2649 @itemx --realm=@var{realm}
2650 @opindex -k
2651 @opindex --realm
2652 The option requests rlogin to obtain tickets for the remote host in
2653 realm @var{realm} instead of the remote host's realm.
2654
2655 @item -K
2656 @itemx --kerberos
2657 @opindex -K
2658 @opindex --kerberos
2659 Turns off all Kerberos authentication.
2660
2661 @item -x
2662 @itemx --encrypt
2663 @opindex -x
2664 @opindex --encrypt
2665 Turns on encryption for all data passed via the rlogin session.
2666 This may impact response time and CPU utilization, but provides
2667 increased security.
2668 @end table
2669
2670 @section Escape characters and flow control
2671
2672 As long as the connection stands, the client program @command{rsh}
2673 is observing the input stream in order to detect so called
2674 escape sequences, allowing the user to execute some local
2675 actions without having to tear down the remote connection.
2676
2677 The sequences consist of two characters, the first of which
2678 always is the distinguished character @var{escape-char}.
2679 The following sequences are supported:
2680
2681 @c An input line of the form of the two-character sequence
2682 @itemize @bullet
2683 @item
2684 @kbd{@var{escape-char} .} disconnects from the remote host.
2685
2686 @item
2687 @kbd{@var{escape-char} C-d} does the same.
2688 (Termios character @samp{VEOF}.)
2689
2690 @item
2691 @kbd{@var{escape-char} C-z} suspends the session, halting the
2692 remote process, but keeping it ready for resumed processing.
2693 The user is given access to a local shell.
2694 (Termios character @samp{VSUSP}.)
2695
2696 @item
2697 @kbd{@var{escape-char} @var{delayed-suspend-char}} implements
2698 a half-way suspend, in the sense of stopping local input from
2699 reaching the remote side, but still displaying all output from
2700 the remote host on the local terminal. The remote process is
2701 still running, but the local user is given a local shell until
2702 the resuming the original command.
2703 Normally, only BSD systems offer this mode.
2704 (Termios character @samp{VDSUSP}.)
2705 @end itemize
2706
2707 @noindent
2708 By default, the character tilde @samp{~} is assigned to @var{escape-char},
2709 but it can be changed using the option @option{--escape}.
2710 The processing of escape sequences can even be disable using
2711 the option @option{--no-escape}.
2712 On BSD systems, @var{delayed-suspend-char} is usually set to @kbd{C-Y}.
2713 It displays as @samp{dsusp} using @command{stty}.
2714
2715 All echoing takes place at the remote site, so that the @command{rlogin}
2716 is transparent except possibly for transmission delays.
2717 Flow control via @kbd{C-S} and @kbd{C-Q}, if at all supported,
2718 will stop and start the flow of data on the local terminal.
2719 Flushing of input and output on interrupts is also
2720 handled properly.
2721
2722 On the server side the @code{iruserok} and @code{ruserok} functions
2723 are used to authenticate the connection request, unless Kerberised
2724 mode is in effect. See the appropriate man pages for more information.
2725
2726 @section Kerberos Authentication
2727
2728 If @command{rlogin} was compiled with kerberos support, options
2729 @option{-x}, @option{-k}, @option{-K} are available. Each user may
2730 have a private authorization list in the file @file{.k5login} in their
2731 home directory. Each line in this file should contain a Kerberos
2732 principal name of the form @samp{principal/instance@@realm}. If the
2733 originating user is authenticated to one of the principals named in
2734 @file{.k5login}, access is granted to the account. The principal
2735 @samp{accountname@@localrealm} is granted access if there is no
2736 @file{.k5login} file. Otherwise a login and password will be prompted
2737 for on the remote machine as in @command{login}. To avoid certain
2738 security problems, the @file{.k5login} file must be owned by the remote
2739 user. If Kerberos authentication fails, a warning message is printed
2740 and the standard Berkeley rlogin is used instead.
2741
2742 @node rsh invocation
2743 @chapter @command{rsh}: Remote shell
2744 @pindex rsh
2745
2746 @command{rsh} executes commands on a remote host and copies its local
2747 standard input to that of the remote command, as well as the remote
2748 standard output to the local standard output, and the remote standard
2749 error to the local standard error. Locally raised interrupt, quit and
2750 terminate signals are all propagated to the remote command. Normally
2751 @command{rsh} terminates when the remote command does so.
2752
2753 When using the @command{rsh} command, you can for convenience create
2754 a link in your path, using a host name as name of the link. For example:
2755
2756 @example
2757 # ln -s /usr/bin/rsh @var{hostname}
2758 # @var{hostname} ls
2759 @end example
2760
2761 @noindent
2762 Afterwards, @var{hostname} will be passed to @command{rsh} as host name
2763 whenever the command @var{hostname} is issued.
2764
2765 @command{rsh} allows access to the remote host without the use of a
2766 password. The prerequisite is a suitable specification in @file{~/.rhosts}.
2767 For details, @xref{rcmd, , rcmd, libc, The GNU C Library Reference Manual}.
2768
2769 If no command is specified for @command{rsh} ar argument following the
2770 host name, then you will be logged in on the remote host using @command{rlogin}.
2771
2772 @section Command line options
2773 @anchor{rsh options}
2774
2775 The options are as follows :
2776
2777 @table @option
2778 @item -4
2779 @itemx --ipv4
2780 @opindex -4
2781 @opindex --ipv4
2782 Use only IPv4.
2783
2784 @item -6
2785 @itemx --ipv6
2786 @opindex -6
2787 @opindex --ipv6
2788 Use only IPv6.
2789
2790 @item -d
2791 @itemx --debug
2792 @opindex -d
2793 @opindex --debug
2794 Turns on socket debugging used for communication with the remote host.
2795
2796 @item -l @var{user}
2797 @itemx --user=@var{user}
2798 @opindex -l
2799 @opindex --user
2800 By default, the remote username is the same as the local username.
2801 The @option{-l} option and the @samp{username@@host} format allow the
2802 remote user name to be specified. Kerberos authentication is used,
2803 whenever available, and authorization is determined as in @command{rlogin}
2804 (@pxref{rlogin invocation}).
2805
2806 @item -n
2807 @itemx --no-input
2808 @opindex -n
2809 @opindex --no-input
2810 Use @file{/dev/null} for all input, telling the server side that
2811 we send no material. This can prevent the remote process from
2812 blocking, should it optionally accept more input.
2813 The option is void together with encryption.
2814 @end table
2815
2816 @noindent
2817 The next three options are available only if the program
2818 has been compiled with support for Kerberos authentication.
2819
2820 @table @option
2821 @item -k @var{realm}
2822 @itemx --realm=@var{realm}
2823 @opindex -k
2824 @opindex --realm
2825 The option requests rsh to obtain tickets for the remote host in
2826 realm @var{realm} instead of the remote host's realm.
2827
2828 @item -K
2829 @itemx --kerberos
2830 @opindex -K
2831 @opindex --kerberos
2832 Turns off all Kerberos authentication.
2833
2834 @item -x
2835 @itemx --encrypt
2836 @opindex -x
2837 @opindex --encrypt
2838 Turns on encryption for all data passed via the rsh session. This
2839 may impact response time and CPU utilization, but provides increased
2840 security.
2841 @end table
2842
2843 @noindent
2844 Finally, some compatibility options are present:
2845
2846 @table @option
2847 @item -8
2848 @itemx --8-bit
2849 @itemx -e @var{char}
2850 @itemx --escape=@var{char}
2851 @itemx -E
2852 @itemx --no-escape
2853 Ignored during normal operation, but passed on to @command{rlogin}
2854 when @command{rsh} is invoked without a command argument.
2855 @end table
2856
2857 @section Note on stream redirections
2858
2859 Beware that non-quoted shell metacharacters are interpreted on the local
2860 machine, while quoted metacharacters are interpreted on the remote
2861 machine. For example:
2862
2863 @example
2864 rsh otherhost cat remotefile >> localfile
2865 rsh otherhost cat remotefile ">>" otherfile
2866 @end example
2867
2868 @noindent
2869 The first command appends the contents of @file{remotefile}, as found
2870 on the remote host, to the file @file{localfile} on the local host,
2871 since the local shell will intercept the redirection and will thus
2872 receive whatever the remote process directs to stdout.
2873
2874 In contrast, the second command will append the contents of the same
2875 file @file{remotefile} to a file named @file{otherfile} again, but this
2876 time the file is located on the remote host. The effect of quoting
2877 the redirection operator is to execute the command
2878
2879 @example
2880 cat remotefile >> localfile
2881 @end example
2882
2883 @noindent
2884 entirely on the remote most, whence stdout at the remote host will
2885 have nothing to transmit to the listening local host!.
2886
2887 @node talk invocation
2888 @chapter @command{talk}: a communication program
2889 @pindex talk
2890
2891 @command{talk} is a visual communication program which copies lines
2892 from your terminal to that of another user.
2893
2894 @noindent
2895 Synopsis:
2896
2897 @example
2898 talk @var{person} [@var{ttyname}]
2899 @end example
2900
2901 @section Invoking
2902
2903 The command line arguments are as follows:
2904
2905 @table @var
2906 @item person
2907 If you wish to talk to someone on your own machine, then @var{person}
2908 is just the other person's login name.
2909 If you wish to talk to a user on another host,
2910 then @var{person} is of the form @samp{user@@host}.
2911
2912 @item ttyname
2913 If you wish to talk to a local user who is logged in more than once,
2914 the argument @var{ttyname} may be used to indicate the appropriate
2915 terminal name, where @var{ttyname} typically is of the form @samp{ttyXX},
2916 or @samp{pts/X}.
2917 @end table
2918
2919 When first called, @command{talk} sends a message to
2920 the addressed user:
2921
2922 @example
2923 Message from TalkDaemon@@his_machine@dots{}
2924 talk: connection requested by your_name@@your_machine.
2925 talk: respond with: talk your_name@@your_machine
2926 @end example
2927
2928 @noindent
2929 At this point, the recipient of the message could elect
2930 to accept the call and to establish a connection by typing:
2931
2932 @example
2933 talk @var{your_name}@@@var{your_machine}
2934 @end example
2935
2936 It doesn't matter from which machine the recipient replies, as long as
2937 his login-name is the same. Once communication is established, the
2938 two parties may type text simultaneously, with their output appearing
2939 in separate windows.
2940 Typing @kbd{C-L} will cause the screen to be
2941 reprinted, while erase, kill, and word kill characters will
2942 behave normally.
2943 In addition, @kbd{C-D} will cause both windows to be
2944 locally cleared of all text.
2945 This keystroke will appear as a simple @samp{^D} on the remote
2946 terminal, though.
2947 It signals to the other party that you yourself have just
2948 cleared your terminal of all text.
2949
2950 To exit, just type an interrupt character @kbd{C-C};
2951 @command{talk} then moves the cursor to the bottom of the screen
2952 and restores the terminal to its previous state.
2953
2954 The ability to talk may be enabled or disabled by use of the
2955 @command{mesg} command. It is system dependent whether
2956 this message passing is enabled at the outset of a terminal session.
2957 Certain commands, in particular @command{nroff} and @command{pr},
2958 disable messages in order to prevent messy output.
2959
2960 @node telnet invocation
2961 @chapter @command{telnet}: User interface to TELNET
2962 @pindex telnet
2963
2964 Login to a remote system HOST, optionally using a (non-standard)
2965 service port PORT.
2966
2967 @noindent
2968 Synopsis:
2969
2970 @example
2971 telnet [@var{OPTION}...] [@var{HOST} [@var{PORT}]]
2972 @end example
2973
2974 @section Command line options
2975 @anchor{telnet options}
2976
2977 @table @option
2978 @item -4
2979 @itemx --ipv4
2980 @opindex -4
2981 @opindex --ipv4
2982 Use only IPv4.
2983
2984 @item -6
2985 @itemx --ipv6
2986 @opindex -6
2987 @opindex --ipv6
2988 Use only IPv6.
2989
2990 @item -8
2991 @itemx --binary
2992 @opindex -8
2993 @opindex --binary
2994 Use an 8-bit data path.
2995
2996 @item -a
2997 @itemx --login
2998 @opindex -a
2999 @opindex --login
3000 Attempt automatic login.
3001
3002 @item -b @var{address}
3003 @itemx --bind=@var{address}
3004 @opindex -b
3005 @opindex --bind
3006 Bind to specific local @var{address}.
3007
3008 @item -c
3009 @itemx --no-rc
3010 @opindex -c
3011 @opindex --no-rc
3012 Do not read the user's file @file{$HOME/.telnetrc}.
3013
3014 @item -d
3015 @itemx --debug
3016 @opindex -d
3017 @opindex --debug
3018 Turn on socket level debugging.
3019
3020 @item -e @var{char}
3021 @itemx --escape=@var{char}
3022 @opindex -e
3023 @opindex --escape
3024 Use @var{char} as escape character.
3025
3026 @item -E
3027 @itemx --no-escape
3028 @opindex -E
3029 @opindex --no-escape
3030 Do not use an escape character.
3031
3032 @item -k @var{realm}
3033 @itemx --realm=@var{realm}
3034 @opindex -k
3035 @opindex --realm
3036 Request Kerberos realm @var{realm} instead of whatever is
3037 declared as default realm in the system's or user's settings.
3038
3039 @item -K
3040 @itemx --no-login
3041 @opindex -K
3042 @opindex --no-login
3043 Do not automatically login to the remote system.
3044
3045 @item -l @var{user}
3046 @itemx --user=@var{user}
3047 @opindex -l
3048 @opindex --user
3049 Attempt automatic login as @var{user}.
3050
3051 @item -L
3052 @itemx --binary-output
3053 @opindex -L
3054 @opindex --binary-output
3055 Use an 8-bit data path for output only.
3056
3057 @item -n @var{file}
3058 @itemx --trace=@var{file}
3059 @opindex -n
3060 @opindex --trace
3061 Record trace information into @var{file}.
3062
3063 @item -r
3064 @itemx --rlogin
3065 @opindex -r
3066 @opindex --rlogin
3067 Display a user-interface similar to that of @command{rlogin}.
3068
3069 @item -x
3070 @itemx --encrypt
3071 @opindex -x
3072 @opindex --encrypt
3073 If possible, encrypt the data stream.
3074
3075 @item -X @var{atype}
3076 @itemx --disable-auth=@var{atype}
3077 @opindex -X
3078 @opindex --disable-auth
3079 Disable authentication of type @var{atype}.
3080 Use this option multiple times if more than one type
3081 is to be disabled. Standard choices are @samp{null},
3082 @samp{kerberos_v4}, and @samp{kerberos_v5}.
3083 @end table
3084
3085 @node tftp invocation
3086 @chapter @command{tftp}: TFTP client
3087 @pindex tftp
3088
3089 @command{tftp} is the user interface to the Internet TFTP, Trivial
3090 File Transfer Protocol, which allows users to transfer files to and
3091 from a remote machine. The remote host may be specified on the
3092 command line, in which case @command{tftp} uses host as the default
3093 host for future transfers.
3094
3095 @noindent
3096 Synopsis:
3097
3098 @example
3099 tftp [@var{option}]@dots{} @var{host}
3100 @end example
3101
3102 @section Commands
3103
3104 Once @command{tftp} is running, it issues the prompt and recognizes
3105 the following commands:
3106
3107 @table @code
3108 @item ? @var{command-name}
3109 Print help information.
3110
3111 @item ascii
3112 Shorthand for @code{mode ascii}
3113
3114 @item binary
3115 Shorthand for @code{mode binary}
3116
3117 @item connect @var{host-name} [@var{port}]
3118 Set the host (and optionally port) for transfers. Note that the TFTP
3119 protocol, unlike the FTP protocol, does not maintain connections
3120 between transfers; thus, the connect command does not actually create
3121 a connection, but merely remembers what host is to be used for
3122 transfers. You do not have to use the connect command; the remote
3123 host can be specified as part of the get or put commands.
3124
3125 @item get @var{file-name}
3126 @itemx get @var{remotename} @var{localname}
3127 @itemx get @var{file}@dots{}
3128 Get a file, or a set of files, from the specified sources. The source can
3129 be in one of two forms: a file name on the remote host, if the host has
3130 already been specified, or a string of the form @samp{host:filename}
3131 to specify both a host and file name at the same time. If the latter
3132 form is used, the last hostname specified becomes the default for
3133 future transfers. When specifying a numeric IPv6 address as host
3134 part, then this address must be enclosed between square brackets,
3135 since it contains colons and would interfere with the delimiter
3136 before the file name. Brackets are optional for IPv4 addresses.
3137
3138 @example
3139 tftp> get [2001:1234::12]:issue
3140 @end example
3141
3142 @item mode @var{transfer-mode}
3143 Set the mode for transfers; @var{transfer-mode} may be one of
3144 @samp{ascii} or @samp{binary}. The default is @samp{ascii}.
3145
3146 @item put @var{file}
3147 @itemx put @var{localfile} @var{remotefile}
3148 @itemx put @var{file}@dots{} @var{remote-directory}
3149 Put a file or set of files to the specified remote file or directory.
3150 The destination can be in one of two forms: a filename on the remote
3151 host, if the host has already been specified, or a string of the form
3152 @samp{host:filename} to specify both a host and filename at the same
3153 time. If the latter form is used, the hostname specified becomes the
3154 default for future transfers. If the @file{remote-directory} form is
3155 used, the remote host is assumed to be a UNIX machine. The same use
3156 of square brackets for enclosing numeric IPv6 addresses applies here,
3157 as was mentioned for the command @command{get}.
3158
3159 @item quit
3160 Exit @command{tftp}. An end of file also exits.
3161
3162 @item rexmt @var{retransmission-timeout}
3163 Set the per-packet retransmission timeout, in seconds.
3164
3165 @item status
3166 Show current status.
3167
3168 @item timeout @var{total-transmission-timeout}
3169 Set the total transmission timeout, in seconds.
3170
3171 @item trace
3172 Toggle packet tracing.
3173
3174 @item verbose
3175 Toggle verbose mode.
3176 @end table
3177
3178 Because there is no user-login or validation within the @command{tftp}
3179 protocol, the remote site will probably have some sort of file-access
3180 restrictions in place. The exact methods are specific to each site
3181 and therefore difficult to document here.
3182
3183 @node inetd invocation
3184 @chapter @command{inetd}: Internet super-server
3185 @pindex inetd
3186
3187 @command{inetd} program should be run at boot time by /etc/rc. It
3188 then listens for connections on certain internet sockets. When a
3189 connection is found on one of its sockets, it decides what service the
3190 socket corresponds to, and invokes a program to service the request.
3191 The server program is invoked with the service socket as its standard
3192 input, output and error descriptors. After the program is finished,
3193 inetd continues to listen on the socket (except in some cases which
3194 will be described below). Essentially, inetd allows running one
3195 daemon to invoke several others, reducing load on the system.
3196
3197 There are two types of services that inetd can start: standard and
3198 TCPMUX. A standard service has a well-known port assigned to it; it
3199 may be a service that implements an official Internet standard or is a
3200 BSD-specific service. As described in RFC 1078, TCPMUX services are
3201 nonstandard services that do not have a well-known port assigned to
3202 them. They are invoked from inetd when a program connects to the
3203 ``tcpmux'' well-known port and specifies the service name. This
3204 feature is useful for adding locally-developed servers.
3205
3206 @menu
3207 * Invocation::
3208 * Configuration file::
3209 * Built-in services::
3210 * TCPMUX::
3211 * Inetd Environment::
3212 * Error Messages::
3213 @end menu
3214
3215 @node Invocation
3216 @section Invocation
3217
3218 Normally, @command{inetd} is invoked without any arguments. It does,
3219 however, support several command line options. These are:
3220
3221 @table @option
3222 @opindex -d
3223 @opindex --debug
3224 @item -d
3225 @itemx --debug
3226 Turns on debugging. With this option, @command{inetd} stays in
3227 foreground and prints additional debugging information of stderr.
3228
3229 @item --environment
3230 @opindex --environment
3231 Pass local and remote socket information in environment variables.
3232 @xref{Inetd Environment}.
3233
3234 @item --foreground
3235 @opindex --foreground
3236 Run in foreground mode. Similar to debug mode, but does not enable
3237 debug messages.
3238
3239 @item -p[@var{file}]
3240 @itemx --pidfile[=@var{file}]
3241 @opindex -p
3242 @opindex --pidfile
3243 Use @var{file} as location to store process ID of the running server
3244 process, thus overriding the default location. Setting an empty
3245 argument will disable the use of a file for storing the process ID.
3246
3247 @item --resolve
3248 @opindex --resolve
3249 Resolve IP addresses when setting environment variables.
3250 @xref{Inetd Environment}.
3251
3252 @item -R @var{rate}
3253 @itemx --rate=@var{rate}
3254 @opindex --r
3255 @opindex --rate
3256 Specify the maximum number of times a service can be invoked in one
3257 minute; the default is 1000.
3258 @end table
3259
3260 @node Configuration file
3261 @section Configuration file
3262
3263 Upon execution, inetd reads its configuration information from
3264 configuration files and directories named on the command line.
3265 By default these are @file{/etc/inetd.conf} and @file{/etc/inetd.d}.
3266 If the configuration pathname is a directory, all files in the
3267 directory are read and interpreted like a configuration file.
3268 All of the configuration files are read and the results are merged.
3269
3270 There must be an entry for each field in the configuration file,
3271 with entries for each field separated by a tab or a space.
3272 Comments are denoted by a ``#'' at the beginning of a line.
3273 The available fields of the configuration file are summarized
3274 in the table below (optional parts are enclosed in square brackets):
3275
3276 @table @asis
3277 @item [service node:]service name
3278 The service-name entry is the name of a valid service in the file
3279 @file{/etc/services}. For ``internal'' services (@pxref{Built-in
3280 services}), the service name must be the official name of the service
3281 (that is, the first entry in @file{/etc/services}), or a numeric
3282 representation thereof. For TCPMUX services, the value of the
3283 @samp{service name} field consists of the string @samp{tcpmux}
3284 followed by a slash and the locally-chosen service name
3285 (@pxref{TCPMUX}).
3286
3287 An optional @samp{service node} prefix is allowed for internet services.
3288 When present, it supplies the local addresses @command{inetd} should
3289 use when listening for that service. @samp{Service node} consists of
3290 a comma-separated list of addresses. Both symbolic host names and
3291 numeric IP addresses are allowed. Symbolic hostnames are looked up in
3292 DNS service. If a hostname has multiple address mappings,
3293 @command{inetd} creates a socket to listen on each address.
3294
3295 To avoid repeating an address that occurs frequently, a line with a
3296 host address specifier and colon, but no further fields is allowed,
3297 e.g.:
3298
3299 @example
3300 127.0.0.1,192.168.0.5:
3301 @end example
3302
3303 The address specifier from such a line is remembered and used for all
3304 further lines lacking an explicit host specifier. Such a default
3305 address remains in effect until another such line or end of the
3306 configuration is encountered, whichever occurs first.
3307
3308 A special hostname @samp{*} stands for the wildcard address.
3309 When used in a normal configuration line, it causes the default address
3310 specifier to be ignored for that line. When used in a default address
3311 specification, e.g.:
3312
3313 @example
3314 *:
3315 @end example
3316
3317 it causes any previous default address specifier to be forgotten.
3318
3319 @item socket type
3320 The socket type should be one of @samp{stream}, @samp{dgram},
3321 @samp{raw}, @samp{rdm}, or @samp{seqpacket}, depending on whether the
3322 socket is a stream, datagram, raw, reliably delivered message, or
3323 sequenced packet socket. TCPMUX services must use @samp{stream}.
3324
3325 @item protocol
3326 The protocol must be a valid protocol as given in
3327 @file{/etc/protocols}. Examples might be @samp{tcp} or @samp{udp}.
3328 TCPMUX services must use @samp{tcp}. If IPv6 support is enabled the
3329 sockets will accept both IPv4 and IPv6 connections if that is
3330 supported by the OS. If inetd should only accept IPv4 or IPv6
3331 connections, add @samp{4} or @samp{6} to the protocol name. For
3332 example @samp{tcp4} will only accept IPv4 tcp connections and
3333 @samp{udp6} will only accept IPv6 udp connections.
3334
3335 @item wait/nowait[.max]
3336 The @samp{wait/nowait} entry specifies whether the server that is
3337 invoked by @command{inetd} will take over the socket associated with
3338 the service access point, and thus whether inetd should wait for the
3339 server to exit before listening for new service requests. Datagram
3340 servers must use @samp{wait}, as they are always invoked with the
3341 original datagram socket bound to the specified service address.
3342 These servers must read at least one datagram from the socket before
3343 exiting. If a datagram server connects to its peer, freeing the
3344 socket so inetd can received further messages on the socket, it is
3345 said to be a ``multi-threaded'' server; it should read one datagram
3346 from the socket and create a new socket connected to the peer. It
3347 should fork, and the parent should then exit to allow inetd to check
3348 for new service requests to spawn new servers. Datagram servers which
3349 process all incoming datagrams on a socket and eventually time out are
3350 said to be ``single-threaded''. @command{comsat} and @command{talkd} are
3351 both examples of the latter type of datagram server. @command{tftpd} is an
3352 example of a multi-threaded datagram server.
3353
3354 Servers using stream sockets generally are multi-threaded and use the
3355 @samp{nowait} entry. Connection requests for these services are
3356 accepted by inetd, and the server is given only the newly-accepted
3357 socket connected to a client of the service. Most stream-based
3358 services and all TCPMUX services operate in this manner. For such
3359 services, the number of running instances of the server can be
3360 limited by specifying optional @samp{max} suffix (a decimal number),
3361 e.g.: @samp{nowait.15}.
3362
3363 Stream-based servers that use @samp{wait} are started with the
3364 listening service socket, and must accept at least one connection
3365 request before exiting. Such a server would normally accept and
3366 process incoming connection requests until a timeout.
3367 Other services must use @samp{nowait}.
3368
3369 @item user
3370 The user entry should contain the user name of the user as whom the
3371 server should run. This allows for servers to be given less
3372 permission than root. An optional form includes also a group name
3373 as a suffix, separated from the user name by colon or a period, i.e.,
3374 @samp{user:group} or @samp{user.group}.
3375
3376 @item server program
3377 The server-program entry should contain the pathname of the program
3378 which is to be executed by inetd when a request is found on its
3379 socket. If inetd provides this service internally, this entry should
3380 be @samp{internal}.
3381
3382 It is common usage to specify @file{/usr/sbin/tcpd} in this field.
3383
3384 @item server program arguments
3385 The server program arguments should be just as arguments normally are,
3386 starting with @code{argv[0]}, which is the name of the program. If
3387 the service is provided internally, this entry must contain the word
3388 @samp{internal}, or be empty.
3389 @end table
3390
3391 @node Built-in services
3392 @section Built-in services
3393
3394 The @command{inetd} program provides several ``trivial'' services
3395 internally by use of routines within itself. All these services can
3396 operate both in @samp{stream} and in @samp{dgram} mode. They are:
3397
3398 @table @asis
3399 @item echo
3400 Send back to the originating source any data received from it. This
3401 is a debugging and measurement tool.
3402
3403 @item discard
3404 Silently throw away any data received.
3405
3406 @item chargen
3407 This is a character generator service. It can be operated as both
3408 stream or dgram service. When operating in @samp{stream} mode, once a
3409 connection is established a stream of data is sent out the connection
3410 (and any data received is thrown away). This continues until the
3411 calling user terminates the connection. When operating in
3412 @samp{dgram} mode, @command{inetd} listens for UDP datagrams, and for
3413 each received datagram, answers with a datagram containing a random
3414 number (between 0 and 512) of characters. Any data in the received
3415 datagram are ignored.
3416
3417 @item daytime
3418 Send back the current date and time in a human readable form. Any
3419 input is discarded.
3420
3421 @item time
3422 Send back the current date and time as a 32-bit integer number,
3423 nrepresenting the number of seconds since midnight, January 1, 1900.
3424 @end table
3425
3426 @node TCPMUX
3427 @section TCPMUX
3428 The TCPMUX protocol.
3429
3430 @quotation
3431 A TCP client connects to a foreign host on TCP port 1. It sends the
3432 service name followed by a carriage-return line-feed <CRLF>. The
3433 service name is never case sensitive. The server replies with a
3434 single character indicating positive (+) or negative (-)
3435 acknowledgment, immediately followed by an optional message of
3436 explanation, terminated with a <CRLF>. If the reply was positive, the
3437 selected protocol begins; otherwise the connection is closed.'' The
3438 program is passed the TCP connection as file descriptors 0 and 1.
3439 @end quotation
3440
3441 If the TCPMUX service name begins with a ``+'', @command{inetd}
3442 returns the positive reply for the program. This allows you to invoke
3443 programs that use stdin/stdout without putting any special server code
3444 in them.
3445
3446 The special service name @samp{help} causes inetd to list TCPMUX
3447 services in @file{inetd.conf}.
3448
3449 To define TCPMUX services, the configuration file must contain a
3450 @samp{tcpmux internal} definition.
3451
3452 Here are several example service entries for the various types of
3453 services:
3454
3455 @example
3456 ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l
3457 ntalk dgram udp wait nobody:tty /usr/libexec/talkd talkd
3458 tcpmux stream tcp nowait root internal
3459 tcpmux/+date stream tcp nowait guest /bin/date date
3460 tcpmux/phonebook stream tcp nowait guest /usr/bin/phonebook phonebook
3461 @end example
3462
3463 @node Inetd Environment
3464 @section Inetd Environment
3465
3466 If a connection is made with a streaming protocol (@samp{stream}) and
3467 if @option{--environment} option has been given, @command{inetd} will
3468 set the following environment variables before starting the program:
3469
3470 @table @env
3471 @item PROTO
3472 Always @samp{TCP}.
3473
3474 @item TCPLOCALIP
3475 Local IP address of the interface which accepted the connection.
3476
3477 @item TCPLOCALPORT
3478 Port number on which the TCP connection was established.
3479
3480 @item TCPREMOTEIP
3481 IP address of the remote client.
3482
3483 @item TCPREMOTEPORT
3484 Port number on the client side of the TCP connection.
3485 @end table
3486
3487 Additionally, if given the @option{--remote} option, @command{inetd}
3488 sets the following environment variables:
3489
3490 @table @env
3491 @item TCPLOCALHOST
3492 DNS name of @env{TCPLOCALIP}.
3493
3494 @item TCPREMOTEHOST
3495 DNS name of @env{TCPREMOTEIP}.
3496 @end table
3497
3498 @node Error Messages
3499 @section Error Messages
3500
3501 The inetd server logs error messages using syslog. Important error
3502 messages and their explanations are:
3503
3504 @table @samp
3505 @item service/protocol server failing (looping), service terminated.
3506 The number of requests for the specified service in the past minute
3507 exceeded the limit. The limit exists to prevent a broken program or a
3508 malicious user from swamping the system. This message may occur for
3509 several reasons:
3510
3511 @enumerate 1
3512 @item there are lots of hosts requesting the service within a short time period,
3513 @item a ``broken'' client program is requesting the service too frequently,
3514 @item a malicious user is running a program to invoke the service in a ``denial of service'' attack,
3515 @item the invoked service program has an error that causes clients to retry quickly.
3516 @end enumerate
3517
3518 Use the @option{-R} option, as described above, to change the rate
3519 limit. Once the limit is reached, the service will be re-enabled
3520 automatically in 10 minutes.
3521
3522 @item service/protocol: No such user 'user', service ignored
3523 @itemx service/protocol: getpwnam: user: No such user
3524 No entry for user exists in the passwd file. The first message occurs
3525 when inetd (re)reads the configuration file. The second message
3526 occurs when the service is invoked.
3527
3528 @item service/protocol: No such user 'user', service ignored
3529 @itemx service/protocol: getpwnam: user: No such user
3530 No entry for user exists in the passwd file. The first message occurs
3531 when inetd (re)reads the configuration file. The second message
3532 occurs when the service is invoked.
3533
3534 @item service: can't set uid number
3535 @itemx service: can't set gid number
3536 The user or group ID for the entry's user is invalid.
3537 @end table
3538
3539 @node syslogd invocation
3540 @chapter @command{syslogd}: system service logging faclity
3541 @pindex syslogd
3542
3543 @command{syslogd} is a system service that provides error logging
3544 facility. Messages are read from the UNIX domain socket
3545 @file{/dev/log}, from an Internet domain socket specified in
3546 @file{/etc/services}, and from the special device @file{/dev/klog} (to
3547 read kernel messages).
3548
3549 @command{syslogd} creates the file @file{/var/run/syslog.pid}, and
3550 stores its process id there. This can be used to kill or reconfigure
3551 @command{syslogd}.
3552
3553 The message sent to @command{syslogd} should consist of a single line.
3554 The message can contain a priority code, which should be a preceding
3555 decimal number in angle braces, for example, @code{<5>}. This
3556 priority code should map into the priorities defined in the include
3557 file @code{sys/syslog.h}.
3558
3559 @example
3560 syslogd [@var{options}]@dots{}
3561 @end example
3562
3563 @table @option
3564 @item -f @var{file}
3565 @itemx --rcfile=@var{file}
3566 @opindex -f
3567 @opindex --rcfile
3568 Override configuration (the default file is @file{/etc/syslog.conf}).
3569
3570 @item -D @var{dir}
3571 @itemx --rcdir=@var{dir}
3572 @opindex -D
3573 @opindex --rcdir
3574 Override configuration directory (the default is @file{/etc/syslog.d}).
3575
3576 @item -P @var{file}
3577 @itemx --pidfile=@var{file}
3578 @opindex -P
3579 @opindex --pidfile
3580 Override pidfile (the default file is @file{/var/run/syslogd.pid}).
3581
3582 @item -n
3583 @itemx --no-detach
3584 @opindex -n
3585 @opindex --no-detach
3586 Do not enter daemon mode.
3587
3588 @item -d
3589 @itemx --debug
3590 @opindex -d
3591 @opindex --debug
3592 Print debug information (implies @option{-n}).
3593
3594 @item -p @var{file}
3595 @itemx --socket=@var{file}
3596 @opindex -p
3597 @opindex --socket
3598 Override default UNIX domain socket @file{/dev/log}.
3599
3600 @item -a @var{socket}
3601 Add UNIX socket to listen. An unlimited number of sockets is allowed.
3602
3603 @item -r
3604 @itemx --inet
3605 @opindex -r
3606 @opindex --inet
3607 Receive remote messages via Internet domain socket.
3608 Without this option no remote massages are received,
3609 since there is no listening socket. Yet sockets for
3610 forwarding are created on the fly as needed,
3611 which might cause performance issues on busy systems.
3612
3613 @item -b @var{address}
3614 @itemx --bind=@var{address}
3615 @opindex -b
3616 @opindex --bind
3617 Restrict the listening Internet domain socket to a single address.
3618 The default (given the use of @option{-r}) is a wildcard address,
3619 implying that the server listens at every available address.
3620 Any name will be resolved, and the lookup result will depend
3621 on the options @option{-4}, @option{-6}, and @option{--ipany}.
3622
3623 @item --no-unixaf
3624 @opindex --no-unixaf
3625 Do not listen on UNIX domain sockets (overrides @option{-a} and
3626 @option{-p}).
3627
3628 @item --no-klog
3629 @opindex --no-klog
3630 Do not listen to the kernel log device @file{/dev/klog}.
3631
3632 @item --ipany
3633 @opindex --ipany
3634 Allow both address families: IPv4 and IPv6.
3635
3636 @item -4
3637 @itemx --ipv4
3638 @opindex -4
3639 @opindex --ipv4
3640 Use only IPv4 for Internet domain sockets.
3641
3642 @item -6
3643 @itemx --ipv6
3644 @opindex -6
3645 @opindex --ipv6
3646 Use only IPv6 for Internet domain sockets.
3647
3648 @item --no-forward
3649 @opindex --no-forward
3650 Do not forward any messages (overrides @option{-h}).
3651 This disables even temporary creation of forwarding
3652 sockets, an ability which is otherwise active when
3653 the option @option{-r} is left out.
3654
3655 @item -h
3656 @itemx --hop
3657 @opindex -h
3658 @opindex --hop
3659 Forward messages from remote hosts.
3660
3661 @item -m @var{interval}
3662 @itemx --mark=@var{interval}
3663 @opindex -m
3664 @opindex --mark
3665 Specify timestamp interval expressed in minutes (0 for no timestamping).
3666
3667 @item -l @var{hostlist}
3668 @opindex -l
3669 Log hosts in @var{hostlist} by their hostname. Multiple lists are
3670 allowed.
3671
3672 @item -s @var{domainlist}
3673 @opindex -s
3674 List of domains which should be stripped from the FQDN of hosts before
3675 logging their name. Multiple lists are allowed.
3676
3677 @item -T
3678 @itemx --local-time
3679 @opindex -T
3680 @opindex --local-time
3681 Ignore any time contained in a received message.
3682 In its stead, record the time of reception on the local
3683 system. This circumvents problems caused by remote hosts
3684 with skewed clocks.
3685 @end table
3686
3687 @section Configuration file
3688
3689 @command{syslogd} reads its configuration file when it starts up and
3690 whenever it receives a hangup signal. The @file{syslog.conf} file is
3691 the main configuration file for the @command{syslogd} program.
3692 In addition, the server looks below the directory @file{syslog.d/}
3693 for further configuration files, making it easy to arrange a common
3694 set of logging conventions in @file{syslog.conf}, augmented by
3695 system and service specific drop-in configuration in @file{syslog.d/}.
3696
3697 Each configuration file consists of lines with two fields:
3698 a @dfn{selector} field which specifies the
3699 types of messages and priorities to which the line applies, and an
3700 @dfn{action} field which specifies the action to be taken if a message
3701 @command{syslogd} receives matches the selection criteria. The
3702 selector field is separated from the action field by one or more tab
3703 or space characters. A rule can be split in several lines if all
3704 lines except the last are terminated with a backslash @samp{\}.
3705
3706 There are two exceptional forms of line content.
3707 The first is the @dfn{tagged selector}, and the second is a comment.
3708 The latter begins with an octothorp (@samp{#}), also called hash,
3709 and continues until end-of-line.
3710
3711 A tagged selector commences with an exclamation mark,
3712 as in @samp{!name}, or with a shebang, like @samp{#! name},
3713 and continues with a program name, a @dfn{tag} in the sense
3714 used by @command{logger}.
3715 It has the effect of applying the following configuration rules
3716 only to messages submitted with the specified tag.
3717 This selection remains in effect until another tag is selected,
3718 or until it is reset by means of stating the program name as
3719 an asterisque @samp{*}.
3720
3721 The selector fields are encoded as a facility, followed by
3722 a period (@samp{.}), and a level, with no intervening white-space.
3723 The facility as well as the level are case insensitive.
3724
3725 The facility describes the part of the system generating the message,
3726 and is one of the following keywords: @samp{auth}, @samp{authpriv},
3727 @samp{cron}, @samp{daemon}, @samp{ftp}, @samp{kern}, @samp{lpr}, @samp{mail},
3728 @samp{mark}, @samp{news}, @samp{syslog}, @samp{user}, @samp{uucp} and
3729 @samp{local0} through @samp{local7}. These keywords (with the
3730 exception of @samp{mark}) correspond to the similar @samp{LOG_} values
3731 specified to the @samp{openlog} and @samp{syslog} library routines.
3732 @xref{Syslog, , Syslog, libc, The GNU C Library Reference Manual}, for
3733 details.
3734
3735 The level describes the severity of the message, and is a keyword from
3736 the following ordered list (higher to lower): @samp{emerg},
3737 @samp{alert}, @samp{crit}, @samp{err, warning}, @samp{notice}, @samp{info}
3738 and @samp{debug}. These keywords correspond to the similar @samp{LOG_}
3739 values specified to the syslog library routine.
3740
3741 @xref{syslog; vsyslog, , syslog and vsyslog, libc, The GNU C Library
3742 Reference Manual}, for a further descriptions of both the facility and
3743 level keywords and their significance.
3744
3745 If a received message matches the specified facility and is of the
3746 specified level (or a higher level), the action specified in the
3747 action field will be taken.
3748
3749 Multiple selectors may be specified for a single action by separating
3750 them with semicolon (@samp{;}) characters. It is important to note,
3751 however, that each selector can modify the ones preceding it.
3752
3753 Multiple facilities may be specified for a single level by separating
3754 them with comma (@samp{,}) characters.
3755
3756 An asterisk (@samp{*}) can be used to specify all facilities or all
3757 levels. Two asterisks (@samp{**}) specifie all facilities not named
3758 previously in the configuration file.
3759
3760 By default, a level applies to all messages with the same or higher
3761 level. The equal (@samp{=}) character can be prepended to a level to
3762 restrict this line of the configuration file to messages with the very
3763 same level.
3764
3765 An exclamation mark (@samp{!}) prepended to a level or the asterisk
3766 means that this line of the configuration file does not apply to the
3767 specified level (and higher ones). In conjunction with the equal
3768 sign, you can exclude single levels as well.
3769
3770 The special facility @samp{mark} receives a message at priority
3771 @samp{info} every 20 minutes. This is not enabled by a facility field
3772 containing an asterisk.
3773
3774 The special level @samp{none} disables a particular facility.
3775
3776 The action field of each line specifies the action to be taken when
3777 the selector field selects a message. There are five forms:
3778
3779 @itemize @bullet
3780 @item
3781 A pathname (beginning with a leading slash). Selected messages are
3782 appended to the file.
3783
3784 You may prepend a minus (@samp{-}) to the path to omit syncing the
3785 file after each message log. This can cause data loss at system
3786 crashes, but increases performance for programs which use logging
3787 extensively.
3788
3789 @item
3790 A named pipe, beginning with a vertical bar (@samp{|}) followed by a
3791 pathname. The pipe must be created with @command{mkfifo} before
3792 @command{syslogd} reads its configuration file. This feature is
3793 especially useful for debugging.
3794
3795 @item
3796 A hostname (preceded by an at (@samp{@@}) sign). Selected messages
3797 are forwarded to @command{syslogd} on the named host.
3798
3799 @item
3800 A comma separated list of users. Selected messages are written to
3801 those users if they are logged in.
3802
3803 @item
3804 An asterisk. Selected messages are written to all logged-in users.
3805
3806 Blank lines and lines whose first non-blank character is a hash
3807 (@samp{#}) character are ignored.
3808 @end itemize
3809
3810 A configuration file might appear as follows:
3811
3812 @example
3813 # Log all kernel messages, authentication messages of
3814 # level notice or higher and anything of level err or
3815 # higher to the console.
3816 # Don't log private authentication messages!
3817 *.err;kern.*;auth.notice;authpriv.none /dev/console
3818
3819 # Log anything (except mail) of level info or higher.
3820 # Don't log private authentication messages!
3821 *.info;mail.none;authpriv.none /var/log/messages
3822
3823 # The authpriv file has restricted access.
3824 authpriv.* /var/log/secure
3825
3826 # Log all the mail messages in one place.
3827 mail.* /var/log/maillog
3828
3829 # Everybody gets emergency messages, plus log them on another
3830 # machine.
3831 *.emerg *
3832 *.emerg @@arpa.berkeley.edu
3833
3834 # Root and Eric get alert and higher messages.
3835 *.alert root,eric
3836
3837 # Simplify security auditing, by collecting sudo uses.
3838 ! sudo
3839 *.info /var/log/sudo
3840
3841 # Collect time server reports.
3842 #! ntpd
3843 *.* /var/log/ntpd
3844
3845 # Stop selecting on message tags.
3846 !*
3847
3848 # Save mail and news errors of level err and higher in a
3849 # special file.
3850 uucp,news.crit /var/log/spoolerr
3851 @end example
3852
3853 The effects of multiple selectors are sometimes not intuitive. For
3854 example @samp{mail.crit,*.err} will select the @samp{mail} facility
3855 messages at the level of @samp{err} or higher, not at the level of
3856 @samp{crit} or higher.
3857
3858 @node ftpd invocation
3859 @chapter @command{ftpd}: FTP daemon
3860 @pindex ftpd
3861
3862 @command{ftpd} is the Internet File Transfer Protocol server process.
3863 The server uses the TCP protocol and listens at the port specified in
3864 the @samp{ftp} service specification.
3865
3866 @example
3867 ftpd [@var{option}]@dots{}
3868 @end example
3869
3870 @table @option
3871 @item -4
3872 @itemx --ipv4
3873 @opindex -4
3874 @opindex --ipv4
3875 Daemon uses only IPv4 addressing. Ignored in inetd mode.
3876
3877 @item -6
3878 @itemx --ipv6
3879 @opindex -6
3880 @opindex --ipv6
3881 Daemon uses only IPv6 addressing. Ignored in inetd mode.
3882
3883 @item -A
3884 @itemx --anonymous-only
3885 @opindex -A
3886 @opindex --anonymous-only
3887 Only anonymous login is allowed.
3888
3889 @item -a @var{auth}
3890 @itemx --auth=@var{auth}
3891 @opindex -a
3892 @opindex --auth
3893 Specify what authentication mechanism to use for incoming connections.
3894 Possible values are: @samp{kerberos}, @samp{kerberos5}, @samp{opie},
3895 @samp{pam}, and @samp{default}.
3896
3897 Anonymous logins will continue to work when this option is used,
3898 unless the user @samp{ftp} is removed from the system.
3899
3900 @item -D
3901 @itemx --daemon
3902 @opindex -D
3903 @opindex --daemon
3904 @command{ftpd} enters daemon-mode. That allows @command{ftpd} to be
3905 run without @command{inetd}.
3906
3907 @item -d
3908 @itemx --debug
3909 @opindex -d
3910 @opindex --debug
3911 Debugging information is written to the @code{syslog} using facility
3912 @samp{LOG_FTP}.
3913
3914 @item -l
3915 @itemx --logging
3916 @opindex -l
3917 @opindex --logging
3918 Each successful and failed ftp session is logged using @code{syslog}
3919 with a facility of @samp{LOG_FTP}. If this option is specified twice,
3920 the retrieve (@code{get}), store (@code{put}), append, delete, make
3921 directory, remove directory and rename operations and their filename
3922 arguments are also logged.
3923
3924 @item --non-rfc2577
3925 @opindex --non-rfc2577
3926 Do not follow the suggestion of RFC 2577 to suppress messages
3927 that could help an attacker to conduct user name enumeration.
3928 This option allows the server to return with an error message
3929 immediately upon receipt of a user name.
3930 Such information includes non-existence claims and expiration claims.
3931 The ideal mode would otherwise be to fake the relevance of asking
3932 for a password, and only thereafter report an invalid login.
3933
3934 @item -p @var{pidfile}
3935 @itemx --pidfile=@var{pidfile}
3936 @opindex -p
3937 @opindex --pidfile
3938 Change default location of @var{pidfile}.
3939
3940 @item -q
3941 @itemx --no-version
3942 @opindex -q
3943 @opindex --no-version
3944 Quiet mode. No information about the version of the @command{ftpd} is
3945 given to the client.
3946
3947 @item -T
3948 @itemx --max-timeout
3949 @opindex -T
3950 @opindex --max-timeout
3951 A client may also request a different timeout period; the maximum
3952 period allowed may be set to timeout seconds with the @option{-T}
3953 option. The default limit is 2 hours.
3954
3955 @item -t @var{timeout}
3956 @itemx --timeout=@var{timeout}
3957 @opindex -t
3958 @opindex --timeout
3959 The inactivity timeout period is set to timeout seconds (the default
3960 is 15 minutes).
3961
3962 @item -u @var{umask}
3963 @itemx --umask=@var{umask}
3964 @opindex -u
3965 @opindex --umask
3966 Set default umask, expressed in base 8.
3967 @end table
3968
3969 The file @file{/etc/nologin} can be used to disable FTP access. If
3970 the file exists, @command{ftpd} displays it and exits. If the file
3971 @file{/etc/ftpwelcome} exists, @command{ftpd} prints it before issuing
3972 the @samp{ready} message. If the file @file{/etc/motd} exists,
3973 @command{ftpd} prints it after a successful login.
3974
3975 If this server was compiled with PAM support, then any non-anonymous
3976 connection request will also be checked for settings pertaining to
3977 the PAM service @samp{ftp}, before finally being accepted.
3978
3979 Linux-PAM is particular in that it also provides a module
3980 @samp{pam_ftp.so} influencing even anonymous access.
3981 By convention the present server relies on the functionality
3982 in that module when built on relevant systems.
3983 However, the module is known to be partially broken since
3984 ten years back, when one compares the claims in its manual page,
3985 so not all claimed trickery is available!
3986
3987 @section Standards
3988 @anchor{ftpd standards}
3989
3990 The FTP server currently supports the following FTP requests.
3991 The letter case of any request is ignored.
3992
3993 @multitable @columnfractions 0.3 0.7
3994 @headitem Request @tab Description
3995 @item ABOR @tab abort previous command
3996 @item ACCT @tab specify account (ignored)
3997 @item ALLO @tab allocate storage (vacuously)
3998 @item APPE @tab append to a file
3999 @item CDUP @tab change to parent of current working directory
4000 @item CWD @tab change working directory
4001 @item DELE @tab delete a file
4002 @item EPSV @tab extended passive transfer request
4003 @item EPRT @tab specify data connection port
4004 @item HELP @tab give help information
4005 @item LIST @tab give list files in a directory (``ls -lgA'')
4006 @item LPRT @tab specify data connection port
4007 @item LPSV @tab long passive transfer request
4008 @item MKD @tab make a directory
4009 @item MDTM @tab show last modification time of file
4010 @item MODE @tab specify data transfer mode
4011 @item NLST @tab give name list of files in directory
4012 @item NOOP @tab do nothing
4013 @item PASS @tab specify password
4014 @item PASV @tab prepare for server-to-server transfer
4015 @item PORT @tab specify data connection port
4016 @item PWD @tab print the current working directory
4017 @item QUIT @tab terminate session
4018 @item REST @tab restart incomplete transfer
4019 @item RETR @tab retrieve a file
4020 @item RMD @tab remove a directory
4021 @item RNFR @tab specify rename-from file name
4022 @item RNTO @tab specify rename-to file name
4023 @item SITE @tab non-standard commands
4024 @item SIZE @tab return size of file
4025 @item STAT @tab return status of server
4026 @item STOR @tab store a file
4027 @item STOU @tab store a file with a unique name
4028 @item STRU @tab specify data transfer structure
4029 @item SYST @tab show operating system type of server system
4030 @item TYPE @tab specify data transfer type
4031 @item USER @tab specify user name
4032 @item XCUP @tab change to parent of current working directory (deprecated)
4033 @item XCWD @tab change working directory (deprecated)
4034 @item XMKD @tab make a directory (deprecated)
4035 @item XPWD @tab print the current working directory (deprecated)
4036 @item XRMD @tab remove a directory (deprecated)
4037 @end multitable
4038
4039 The following non-standard, or UNIX specific, commands are supported by
4040 the @code{SITE} request.
4041
4042 @multitable @columnfractions 0.3 0.7
4043 @item Request @tab Description
4044 @item UMASK @tab change umask, e.g. @code{SITE UMASK 002}
4045 @item IDLE @tab set idle-timer, e.g. @code{SITE IDLE 60}
4046 @item CHMOD @tab change mode of a file, e.g. @code{SITE CHMOD0 0CHMOD1 1CHMOD2}
4047 @item HELP @tab give help information.
4048 @end multitable
4049
4050 The remaining FTP requests specified in RFC 959 are recognized, but
4051 not implemented. The extensions @code{MDTM}, @code{REST},
4052 and @code{SIZE} are specified in RFC 3659, while @code{EPRT}
4053 and @code{EPSV} appear in RFC 2428, @code{LPRT} and @code{LPSV}
4054 in RFC 1639.
4055
4056 The ftp server will abort an active file transfer only when the
4057 @code{ABOR} command is preceded by a Telnet @samp{Interrupt Process}
4058 (IP) signal and a Telnet @samp{Synch} signal in the command Telnet
4059 stream, as described in Internet RFC 959. If a @code{STAT} command is
4060 received during a data transfer, preceded by a Telnet IP and Synch,
4061 transfer status will be returned.
4062
4063 @code{ftpd} interprets file names according to the globbing
4064 conventions used by @command{csh}. This allows users to utilize the
4065 metacharacters @samp{*?[]@{@}~}.
4066
4067 The server applies the suggestions in RFC 2577, but the legacy
4068 behaviour with informational content in denials can be restored
4069 using the option @option{--non-rfc2577}.
4070
4071 @section Authentication
4072 @anchor{ftpd authentication}
4073
4074 @command{ftpd} authenticates users according to four rules.
4075
4076 @enumerate
4077 @item
4078 The login name must be in the password data base, @file{/etc/passwd},
4079 and must not have a null password. In this case a password must be
4080 provided by the client before any file operations can be performed.
4081
4082 @item
4083 The login name must not appear in the file @file{/etc/ftpusers}.
4084
4085 @item
4086 The user must have a standard shell. If the file @file{/etc/shells}
4087 exists and is readable, only programs listed there are considered standard
4088 shells. @command{ftpd} uses the C library function @code{getusershell}
4089 to enumerate standard shells. Standard shells are also known as valid
4090 login shells, valid user shells, or permitted user shells.
4091
4092 @item
4093 If the user name is @samp{anonymous} or @samp{ftp}, an anonymous ftp
4094 account must be present in the password file (user @samp{ftp}). In
4095 this case the user is allowed to log in by specifying any password (by
4096 convention an email address for the user should be used as the
4097 password).
4098 @end enumerate
4099
4100 A further access mechanism is provided by the file
4101 @file{/etc/ftpchroot}.
4102 A user mentioned therein will have all access confined to the subtree
4103 rooted at the home directory specified in @file{/etc/passwd}.
4104
4105 In the case of anonymous access, @command{ftpd} takes special measures
4106 to restrict the client's access privileges. The server always performs
4107 a chroot to the home directory of the @samp{ftp} user.
4108
4109 In order that system security is not breached,
4110 it is recommended that the @samp{ftp} subtree be
4111 constructed with care, following these rules:
4112
4113 @table @file
4114 @item ~ftp
4115 Make the home directory owned by @samp{root} and not writable by anyone.
4116
4117 @item ~ftp/bin
4118 Make this directory owned by @samp{root} and not writable by anyone
4119 (mode 555). The program @command{ls} must be present to support the
4120 list command, unless the server was compiled with libls support.
4121 This program should be mode 111.
4122
4123 @item ~ftp/etc
4124 Make this directory owned by @samp{root} and not writable by anyone
4125 (mode 555). The files @file{passwd} and @file{group} must be present
4126 for the @command{ls} command to be able to produce owner names rather
4127 than numbers. The password field in @file{passwd} is not used, and
4128 should not contain real passwords. The file @file{motd}, if present,
4129 will be printed after a successful login. These files should be mode
4130 444.
4131
4132 @item ~ftp/pub
4133 Make this directory mode 777 and owned by @samp{ftp}. Guests can then
4134 place files which are to be accessible via the anonymous account in
4135 this directory.
4136 @end table
4137
4138 @section Configuration files
4139 @anchor{ftpd files}
4140
4141 @table @samp
4142 @item @file{/etc/ftpchroot}
4143 List of users to enclose in a chrooted directory.
4144 The anonymous user @samp{ftp} is always considered
4145 to be a member of this list, explicit or not.
4146
4147 @item @file{/etc/ftpusers}
4148 List of unwelcome/restricted users, always to be denied access.
4149
4150 @item @file{/etc/ftpwelcome}
4151 Welcome notice printed before server identification
4152 and any authentication exchange.
4153
4154 @item @file{/etc/motd}
4155 Welcome notice presented after completed login.
4156
4157 @item @file{/etc/nologin}
4158 If present, the contents are displayed and all further
4159 access is refused.
4160 @end table
4161
4162 @section File format of ftpusers and ftpchroot
4163 @anchor{ftpusers file format}
4164
4165 The files @file{/etc/ftpusers} and @file{/etc/ftpchroot}
4166 share a common file format.
4167 For better conformity with other implementations,
4168 each line is understood as consisting of fields separated
4169 by spaces, or by horizontal tabulators.
4170 Only the first non-empty field is examined at present.
4171 Both files are used for matching against a user name,
4172 desiring to use the FTP service.
4173
4174 Whenever the first printable character is a hash @samp{#},
4175 the input line is taken as a comment, and is ignored.
4176 Lines lacking non-empty fields are likewise ignored.
4177
4178 A field consisting of a single at-sign @samp{@@},
4179 is treated as a wildcard and matches every input.
4180
4181 A field commencing with an at-sign @samp{@@} and then
4182 continuing with an identifier, is understood as giving
4183 the name of a group.
4184 Should this name exist in @file{/etc/groups}, and the
4185 user name be a member of this same group, then the user
4186 name matches.
4187
4188 In all other cases, the field is taken as the identifier
4189 of a user, with which the requesting user is compared
4190 for verbatim match.
4191
4192 It is worthwhile to observe from the above cases,
4193 that a single @samp{@@} on a line by itself in
4194 @file{/etc/ftpchroot}, will enforce chrooting
4195 upon every user allowed to access the FTP service.
4196 This gives a Draconian, protective configuration.
4197
4198 @node rexecd invocation
4199 @chapter @command{rexecd}: server for @code{rexec}
4200 @pindex rexecd
4201
4202 @command{rexecd} is the server for the @code{rexec} routine. The
4203 server provides remote execution facilities with authentication based
4204 on user names and passwords. It passes error messages and notices
4205 to the @code{syslog} facility @samp{LOG_DAEMON}.
4206
4207 @example
4208 rexecd [@var{option}]@dots{}
4209 @end example
4210
4211 @command{rexecd} listens for service requests at the port indicated in
4212 the @samp{exec} service specification. When a service request is
4213 received the following protocol is initiated:
4214
4215 @enumerate
4216 @item
4217 The server reads characters from the socket up to a NUL (@samp{\0})
4218 byte. The resultant string is interpreted as an ASCII number, base
4219 10.
4220
4221 @item
4222 If the number received in step 1 is non-zero, it is interpreted as the
4223 port number of a secondary stream to be used for the stderr. A second
4224 connection is then created to the specified port on the client's
4225 machine.
4226
4227 @item
4228 A NUL terminated user name of at most 16 characters is retrieved on
4229 the initial socket.
4230
4231 @item
4232 A NUL terminated, unencrypted password of at most 16 characters is
4233 retrieved on the initial socket.
4234
4235 @item
4236 A NUL terminated command to be passed to a shell is retrieved on the
4237 initial socket. The length of the command is limited by the upper
4238 bound on the size of the system's argument list.
4239
4240 @item
4241 @command{rexecd} then validates the user as is done at login time and,
4242 if the authentication was successful, changes to the user's home
4243 directory, and establishes the user and group protections of the user.
4244 If any of these steps fail the connection is aborted with a diagnostic
4245 message returned.
4246
4247 @item
4248 A NUL byte is returned on the initial socket and the command line is
4249 passed to the normal login shell of the user. The shell inherits the
4250 network connections established by rexecd.
4251 @end enumerate
4252
4253 @section Invoking
4254
4255 The only option is as follows:
4256
4257 @table @option
4258 @item -l
4259 @itemx --logging
4260 @opindex -l
4261 @opindex --logging
4262 Raise logging level for this service; use more than once for
4263 increased verbosity. The @code{syslog} facility in use is
4264 @samp{LOG_DAEMON}.
4265
4266 @end table
4267
4268 Should @command{rexecd} have been built with PAM support,
4269 it reads any setting specified for a service named @samp{rexec}.
4270
4271 @section Diagnostics
4272
4273 Except for the last one listed below, all diagnostic messages are
4274 returned on the initial socket, after which any network connections
4275 are closed. An error is indicated by a leading byte with a value of 1
4276 (0 is returned in step 7 above upon successful completion of all the
4277 steps prior to the command execution).
4278
4279 @table @samp
4280 @item username too long
4281 The name is longer than 16 characters.
4282
4283 @item password too long
4284 The password is longer than 16 characters.
4285
4286 @item command too long
4287 The command line passed exceeds the size of the argument list (as
4288 configured into the system).
4289
4290 @item Login incorrect.
4291 No password file entry for the user name existed.
4292
4293 @item Password incorrect.
4294 The wrong password was supplied.
4295
4296 @item No remote directory.
4297 The chdir command to the home directory failed.
4298
4299 @item Try again.
4300 A fork by the server failed.
4301
4302 @item <shellname>: @dots{}
4303 The user's login shell could not be started. This message is returned
4304 on the connection associated with the stderr, and is not ...
4305 @c FIXME: Fill this out.
4306 @end table
4307
4308 @emph{Note}, that indicating @samp{Login incorrect} as opposed to
4309 @samp{Password incorrect} is a security breach which allows people to
4310 probe a system for users with null passwords.
4311
4312 @node rlogind invocation
4313 @chapter @command{rlogind}: Remote login server
4314 @pindex rlogind
4315
4316 @command{rlogind} is the server for the @command{rlogin} client program
4317 (@pxref{rlogin invocation}). The server provides a remote login
4318 facility with authentication based on privileged port numbers from
4319 trusted hosts, or using authentication according to a Kerberos
4320 protocol.
4321
4322 @command{rlogind} in daemon mode listens for service requests at the
4323 port indicated in the @samp{login} service specification. A common
4324 alternative is to have the super-server @command{inetd} listen at
4325 the same port, which then invokes @command{rlogind} as demand arises.
4326 In Kerberised mode, the port is either @samp{eklogin}, or
4327 @samp{klogin}, depending on preset encryption, or none.
4328
4329 The standard authentication procedure assumes the integrity of each
4330 client machine and of the connecting medium. This is insecure, since
4331 it transmits credentials in clear text, but is useful in an ``open''
4332 environment. This weakness is reduced when running the service
4333 in Kerberised version, at the price of a larger complexity of the
4334 supporting infrastructure. Using an encrypting Kerberised service
4335 even avoids all clear text processing.
4336
4337 @section Invoking
4338
4339 The available options are as follows:
4340
4341 @table @option
4342 @item -4
4343 @itemx --ipv4
4344 @opindex -4
4345 @opindex --ipv4
4346 Accept only IPv4 connections in daemon mode.
4347
4348 @item -6
4349 @itemx --ipv6
4350 @opindex -6
4351 @opindex --ipv6
4352 Only IPv6 connections in daemon mode.
4353
4354 @item -a
4355 @itemx --verify-hostname
4356 @opindex -a
4357 @opindex --verify-hostname
4358 Ask hostname for verification.
4359
4360 @item -d[@var{max}]
4361 @itemx --daemon[=@var{max}]
4362 @opindex -d
4363 @opindex --daemon
4364 Run in background daemon mode, optionally setting the maximal
4365 number of simultaneously running client sessions. The default
4366 limit is 10.
4367
4368 @item -D[@var{level}]
4369 @itemx --debug[=@var{level}]
4370 @opindex -D
4371 @opindex -debug
4372 Set debug level, not implemented.
4373
4374 @item -l
4375 @itemx --no-rhosts
4376 @opindex -l
4377 @opindex --no-rhosts
4378 Ignore client's @file{.rhosts} file.
4379
4380 @item -L @var{name}
4381 @itemx --local-domain=@var{name}
4382 @opindex -L
4383 @opindex --local-domain
4384 Set local domain name, to which the server host belongs. By default
4385 the domain is recovered from the canonical name of the host.
4386
4387 @item -n
4388 @itemx --no-keepalive
4389 @opindex -n
4390 @opindex --no-keepalive
4391 Do not set SO_KEEPALIVE on sockets. This decreases the ability
4392 to close lost connections to once active clients.
4393
4394 @item -o
4395 @itemx --allow-root
4396 @opindex -o
4397 @opindex --allow-root
4398 Allow the root user to login, which is disallowed by default.
4399
4400 @item -p @var{port}
4401 @itemx --port=@var{port}
4402 @opindex -p
4403 @opindex --port
4404 Listen on given port. Applicable only in daemon mode.
4405
4406 @item -r
4407 @itemx --reverse-required
4408 @opindex -r
4409 @opindex --reverse-required
4410 Require reverse resolvability of remote host's numerical IP.
4411 @end table
4412
4413 For sites requiring improved authentication, Kerberos
4414 authentication is a viable decision, and possibly even
4415 with encryption for enhanced integrity. Three additional
4416 options are available for an executable @command{rlogind}
4417 compiled with Kerberos support.
4418
4419 @table @option
4420 @item -k
4421 @itemx --kerberos
4422 @opindex -k
4423 @opindex --kerberos
4424 Activate Kerberos authentication on all incoming requests.
4425
4426 @item -S @var{name}
4427 @itemx --server-principal=@var{name}
4428 @opindex -S
4429 @opindex --server-principal
4430 Set Kerberos server name, overriding canonical hostname.
4431
4432 @item -x
4433 @itemx --encrypt
4434 @opindex -x
4435 @opindex --encrypt
4436 Activate encryption of all data passed via the @command{rlogind} session.
4437 This may impact response time and CPU utilization, but provides
4438 increased security. Only for Kerberised mode of operation.
4439 @end table
4440
4441 Should @command{rlogind} have been built with PAM support,
4442 it reads any setting specified for a service named either
4443 @samp{rlogin} or @samp{krlogin}, the latter name for clients
4444 using Kerberised authentication.
4445
4446 @section Kerberos specific details
4447
4448 The option @option{-k} is mandatory for Kerberised operation mode,
4449 while addition of the option @option{-x} will also demand encryption
4450 of every request to this particular server.
4451
4452 @command{rlogind} will, in Kerberised operation mode, as default
4453 instantiate itself using the principal name
4454 @samp{host/canonical_name@@DEFAULT_REALM}, a compound arranged
4455 from the running host's canonical name, and from the default realm
4456 configured for the system. Either of these can be overridden
4457 using the option @option{--server-principal}, as follows:
4458
4459 @example
4460 rlogind -k -S alias.server.our
4461 rlogind --kerberos --server-principal=@@NEW.REALM
4462 rlogind -k -x -S rlogin/backup.ex.org@@OUR.REALM
4463 @end example
4464
4465 When overriding only the realm, with the option @option{-S},
4466 an initial at-sign is mandatory.
4467
4468 @section Protocol details
4469
4470 When a service request is received, in non-Kerberised mode,
4471 the following protocol is initiated:
4472
4473 @enumerate
4474 @item
4475 The server checks the client's source port. If the port is not in the
4476 range 512-1023, the server aborts the connection.
4477
4478 @item
4479 The server next checks the client's source address and requests the
4480 corresponding host name. If the hostname cannot be determined, the
4481 numerical representation of the host address is used. If the
4482 hostname is in the same domain as the server (according to the last
4483 two components of the domain name), or if the option @option{-a} is
4484 in effect, the address for the hostname is requested, verifying that
4485 the name and address correspond. Normal authentication is considered
4486 as failed, should this address verification fail.
4487 @end enumerate
4488
4489 Once the source port and address have been checked, @command{rlogind}
4490 proceeds
4491 with the authentication process as described in @ref{rshd invocation}.
4492 The server
4493 then allocates a pseudo terminal, and manipulates file descriptors so
4494 that the slave half of the pseudo terminal becomes the stdin, stdout,
4495 and stderr for a login process. The login process is an instance of
4496 the @command{login} program, invoked with the option @option{-f} if
4497 authentication had succeeded. If automatic authentication had failed,
4498 the user is prompted to log in as if on a standard terminal line.
4499
4500 The parent of the login process manipulates the master side of the
4501 pseudo terminal, operating as an intermediary between the login
4502 process and the client instance of the rlogin program. In normal
4503 operation, the packet protocol described in @samp{PTY} is invoked to
4504 provide flow control using @kbd{C-S}/@kbd{C-Q}, and to propagate interrupt
4505 signals to the remote program. The login process transmits the
4506 client terminal's baud rate, and its terminal type, as found in the
4507 environment variable @env{TERM}. The screen or window size of the
4508 terminal is requested from the client, and any later window size changes
4509 at the client's side are propagated to the pseudo terminal as well.
4510
4511 Transport-level keepalive messages are enabled unless the
4512 option @option{-n} was in effect when starting @code{rlogind}.
4513 The use of keepalive messages allows sessions to be timed out,
4514 should the client crash, or otherwise become unreachable.
4515
4516 @xref{ruserok, , ruserok, libc, The GNU C Library Reference Manual},
4517 for details.
4518
4519 @section Diagnostics
4520
4521 The exchange protocol states that a negotiation reaches a successful
4522 completion as soon as the server @command{rlogind} transmits back to
4523 the client a single null byte, marking the completion of all
4524 information exchange.
4525
4526 Error conditions are instead transmitted back to the client as
4527 a message containing an initial byte value 1, followed by a C-string
4528 indicating the cause of failure. All network connections are closed
4529 at the server side after this message. Some common messages follow:
4530
4531 @table @samp
4532 @item Permission denied.
4533 The client presented insufficient credentials,
4534 or the client's address is not sufficiently resolvable
4535 to pass the checks induced by options @option{-a} or @option{-r}.
4536
4537 @item Try again.
4538 A fork by the server failed.
4539 @end table
4540
4541 @node rshd invocation
4542 @chapter @command{rshd}: Remote shell server
4543 @pindex rshd
4544
4545 The @command{rshd} server is the server for the @code{rcmd} routine
4546 and, consequently, for the @command{rsh} (@pxref{rsh invocation})
4547 program. The server provides remote execution facilities with
4548 authentication based on privileged port numbers from trusted hosts.
4549 The @command{rshd} server listens for service requests at the port
4550 indicated in the @samp{cmd} service specification. When a service
4551 request is received the following protocol is initiated:
4552
4553 @enumerate
4554 @item
4555 The server checks the client's source port. If the port is not in the
4556 range 512--1023, the server aborts the connection. However, this
4557 condition is not applied for Kerberized service.
4558
4559 @item
4560 The server reads characters from the socket up to a NUL (@samp{\0})
4561 byte. The resultant string is interpreted as an ASCII number, base
4562 10.
4563
4564 @item
4565 If the number received in step 2 is non-zero, it is interpreted as the
4566 port number of a secondary stream to be used for the stderr. A second
4567 connection is then created to the specified port on the client's
4568 machine. The source port of this second connection is also in the
4569 range 512--1023.
4570
4571 @item
4572 The server checks the client's source address and requests the
4573 corresponding host name. If the hostname cannot be determined, the
4574 dot-notation representation of the host address is used. If the
4575 hostname is in the same domain as the server (according to the last
4576 two components of the domain name), or if the @option{-a} option is
4577 given, the addresses for the hostname are requested, verifying that
4578 the name and address correspond. If address verification fails, the
4579 connection is aborted with the message, @samp{Host address mismatch.}
4580
4581 @item
4582 A null terminated user name of at most 16 characters is retrieved on
4583 the initial socket. This user name is interpreted as the user
4584 identity on the client's machine.
4585
4586 @item
4587 A null terminated user name of at most 16 characters is retrieved on
4588 the initial socket. This user name is interpreted as a user identity
4589 to use on the server's machine.
4590
4591 @item
4592 A null terminated command to be passed to a shell is retrieved on the
4593 initial socket. The length of the command is limited by the upper
4594 bound on the size of the system's argument list.
4595
4596 @item
4597 Rshd then validates the user using @code{ruserok}, which uses the file
4598 @file{/etc/hosts.equiv} and the @file{.rhosts} file found in the
4599 user's home directory. The @option{-l} option prevents @code{ruserok}
4600 from doing any validation based on the user's @file{.rhosts} file,
4601 unless the user is the superuser.
4602
4603 @item
4604 If the file @file{/etc/nologin} exists and the user is not the
4605 superuser, the connection is closed.
4606
4607 @item
4608 A null byte is returned on the initial socket and the command line is
4609 passed to the normal login shell of the user. The shell inherits the
4610 network connections established by @command{rshd}.
4611
4612 @item
4613 Transport-level keepalive messages are enabled unless the @option{-n}
4614 option is present. The use of keepalive messages allows sessions to
4615 be timed out if the client crashes or becomes unreachable.
4616
4617 @item
4618 The @option{-L} option causes all successful accesses to be logged to
4619 @command{syslogd} (@pxref{syslogd invocation}) as @samp{auth.info}
4620 messages.
4621 @end enumerate
4622
4623 @xref{ruserok, , ruserok, libc, The GNU C Library Reference Manual},
4624 for details.
4625
4626 @section Invoking
4627
4628 The options are as follows:
4629
4630 @table @option
4631 @item -a
4632 @itemx --verify-hostname
4633 @opindex -a
4634 @opindex --verify-hostname
4635 Ask hostname for verification.
4636
4637 @c @item -d
4638 @c @itemx --daemon
4639 @c @opindex -d
4640 @c @opindex --daemon
4641 @c Daemon mode.
4642
4643 @item -k
4644 @itemx --kerberos
4645 @opindex -k
4646 @opindex --kerberos
4647 Use Kerberos authentication.
4648
4649 @item -l
4650 @itemx --no-rhosts
4651 @opindex -l
4652 @opindex --no-rhosts
4653 Ignore @file{.rhosts} file.
4654
4655 @item -L
4656 @itemx --log-sessions
4657 @opindex -L
4658 @opindex --log-sessions
4659 Log successful logins.
4660
4661 @item -n
4662 @itemx --no-keepalive
4663 @opindex -n
4664 @opindex --no-keepalive
4665 Do not set SO_KEEPALIVE.
4666
4667 @item -S @var{name}
4668 @itemx --servername=@var{name}
4669 @opindex -S
4670 @opindex --servername
4671 Set Kerberos server name, overriding canonical hostname.
4672
4673 @item -v
4674 @itemx --vacuous
4675 @opindex -v
4676 @opindex --vacuous
4677 Fail any call asking for non-Kerberos authentication.
4678
4679 @c OBSOLETE?
4680 @c @item -x
4681 @c @itemx --encrypt
4682 @c @opindex -x
4683 @c @opindex --encrypt
4684 @c Turns on DES encryption for all data passed via the @command{rshd}
4685 @c session. This may impact response time and CPU utilization, but
4686 @c provides increased security.
4687
4688 @c @item -D[@var{level}]
4689 @c @itemx --debug[=@var{level}]
4690 @c @opindex -D
4691 @c @opindex -debug
4692 @c Set debug level, not implemented.
4693
4694 @c @item -o
4695 @c @itemx --allow-root
4696 @c @opindex -o
4697 @c @opindex --allow-root
4698 @c Allow uid == 0 to login, disabled by default
4699
4700 @c @item -p @var{port}
4701 @c @itemx --port=@var{port}
4702 @c @opindex -p
4703 @c @opindex --port
4704 @c Listen on given port (valid only in daemon mode).
4705
4706 @item -r
4707 @itemx --reverse-required
4708 @opindex -r
4709 @opindex --reverse-required
4710 Demand that the client's IP address be resolvable
4711 as a host name.
4712 @end table
4713
4714 Should @command{rshd} have been built with PAM support,
4715 it reads any setting specified for a service named either
4716 @samp{rsh} or @samp{krsh}, the latter name for clients
4717 seeking Kerberised authentication.
4718
4719 @section Diagnostics
4720
4721 Except for the last one listed below, all diagnostic messages are
4722 returned on the initial socket, after which any network connections
4723 are closed. An error is indicated by a leading byte with a value of 1
4724 (0 is returned in step 10 above upon successful completion of all the
4725 steps prior to the execution of the login shell).
4726
4727 @table @samp
4728 @item Locuser too long
4729 The name of the user on the client's machine is longer than 16
4730 characters.
4731
4732 @item Ruser too long
4733 The name of the user on the remote machine is longer than 16
4734 characters.
4735
4736 @item Command too long
4737 The command line passed exceeds the size of the argument list (as
4738 configured into the system).
4739
4740 @item Login incorrect
4741 No password file entry for the user name existed.
4742
4743 @item Remote directory
4744 The chdir command to the home directory failed.
4745
4746 @item Permission denied
4747 The authentication procedure described above failed,
4748 or address resolution was insufficient.
4749
4750 @item Can't make pipe.
4751 The pipe needed for the stderr, wasn't created.
4752
4753 @item Can't fork; try again.
4754 A fork by the server failed.
4755
4756 @item <shellname>: @dots{}
4757 The user's login shell could not be started. This message is returned
4758 on the connection associated with the stderr, and is not preceded by a
4759 flag byte.
4760 @end table
4761
4762 The authentication procedure used here assumes the integrity of each
4763 client machine and the connecting medium. This is insecure, but is
4764 useful in an ``open'' environment.
4765
4766 @node talkd invocation
4767 @chapter @command{talkd}: a server for communication between users
4768 @pindex talkd
4769
4770 @command{talkd} is a server that notifies users that someone else
4771 wants to initiate a conversation. It acts as a repository of
4772 invitations, responding to requests by clients wishing to rendezvous
4773 for a conversation.
4774
4775 This implementation uses the newer protocol @samp{ntalk/udp},
4776 and is intended to be invoked by a super-server
4777 @command{inetd} at that datagram port.
4778 It is recommended that @command{inetd} launch @command{talkd}
4779 with ownership @samp{nobody:tty}, or with @samp{tty:tty}.
4780 However, this works with ACL only if @file{.talkrc} can be assumed
4781 to be world readable for all users.
4782 This failing, the process ownership will need to be @samp{root:tty}
4783 if the ACL-mechanism is to be usable and trustworthy.
4784
4785 Keep in mind that this service is usable with IPv4 only,
4786 since the exchange protocol was conceived to handle only
4787 this particular address family.
4788 This fact is independent of the abilities of @command{inetd}.
4789
4790 Observe also that the server @command{talkd} depends
4791 on the name returned by @command{hostname}, for establishing
4792 connections between interested parties.
4793 A server @command{talkd} running on a multi-homed host
4794 is not able to respond to invitations for a valid host name
4795 that differs from the name reported by @command{hostname}.
4796
4797 The present implementation offers ACL-mechanisms for fine
4798 grained access control.
4799
4800 @section Invoking
4801
4802 The following switches and options are available.
4803
4804 @table @option
4805 @item -a @var{file}
4806 @itemx --acl=@var{file}
4807 @opindex -a
4808 @opindex --acl
4809 Read site-wide ACLs from @var{file}.
4810
4811 @item -d
4812 @itemx --debug
4813 @opindex --debug
4814 @opindex --d
4815 Enable debugging.
4816
4817 @item -i @var{seconds}
4818 @itemx --idle-timeout=@var{seconds}
4819 @opindex -i
4820 @opindex --idle-timeout
4821 Set idle timeout length
4822
4823 @item -l
4824 @itemx --logging
4825 @opindex -i
4826 @opindex --logging
4827 Enable a somewhat enhanced logging verbosity, reporting
4828 attempted and dropped connections, as well as
4829 some more unexpected events that might arise.
4830
4831 @item -r @var{seconds}
4832 @itemx --request-ttl=@var{seconds}
4833 @opindex -r
4834 @opindex --request-ttl
4835 Set time-to-live length for requests.
4836
4837 @item -S
4838 @itemx --strict-policy
4839 @opindex -S
4840 @opindex --strict-policy
4841 Apply strict ACL policy on this system. This means that
4842 the site-wide ACL must provide explicit @samp{allow}
4843 rules for admitting traffic at all.
4844
4845 @item -t @var{seconds}
4846 @itemx --timeout=@var{seconds}
4847 @opindex -t
4848 @opindex --timeout
4849 Set timeout length.
4850 @end table
4851
4852 @section Modus operandi
4853
4854 In normal operation, a client, the caller, initiates a rendezvous by
4855 sending a @code{CTL_MSG} of type @samp{LOOK_UP} to the server (see
4856 @file{protocols/talkd.h}). This causes the server to search its
4857 invitation tables to check whether an invitation currently exists for the
4858 caller (wanting to talk to the callee specified in the message). If the
4859 lookup fails, the caller then sends an @samp{ANNOUNCE} message causing
4860 the server to broadcast an announcement on the callee's login ports
4861 requesting contact. When the callee responds, the local server uses
4862 the recorded invitation to respond with the appropriate rendezvous
4863 address and the caller and callee client programs establish a stream
4864 connection through which the conversation takes place.
4865
4866 This implementation offers an additional mechanism, whereby a site-wide
4867 access control list can be used to limit service access in general.
4868 For any local user, i.e., present on the server's system, a further user
4869 owned file @file{.talkrc} is parsed, if at all present, in order to even
4870 further fine tune access to this particular user.
4871
4872 @section Access control in talkd
4873
4874 The server can be run in a mode with additional access control,
4875 beyond the legacy capabilities of @command{ntalkd}. This is activated
4876 using the option @option{-a}, or equivalently @option{--acl}.
4877
4878 The format of this access control list is shared with the user specific
4879 file @file{.talkrc}. Normally the site-wide setting operates with
4880 a default value @samp{allow}, but specifying the option @option{-S},
4881 or @option{--strict-policy}, changes this default action to @samp{deny}.
4882 In addition, the strict policy disables the possibility that an
4883 allowing action from the user specific ACL be able to override
4884 a denial resulting from the system-wide ACL setting.
4885
4886 As is usual, indentation, empty lines, and lines whose first printable
4887 character is the hash character, are all ignored.
4888 The general line format is
4889
4890 @example
4891 action user-exp [net-exp @dots{}]
4892 @end example
4893
4894 @noindent
4895 Each active line must contain at least two fields:
4896 an @code{action} and a @code{user-exp}.
4897
4898 The first field, @code{action}, must be either of @samp{allow} and @samp{deny}.
4899 Any other value will lead to the line being ignored,
4900 but reported in the system log.
4901 Of course, the two values represent admitting and rejecting
4902 interpretations for the resulting rule.
4903
4904 The second field, @code{user-exp}, is a POSIX regular expression
4905 crafted to match user names.
4906 Remember that the regular expression would need anchors in order
4907 to test not only substrings.
4908
4909 It is important to note that in a site-wide ACL, the file selected
4910 by the switch @option{-a}, the expression @code{user-exp} is matched
4911 against the requested local user name, that of the callee.
4912
4913 While checking the callee's private ACL-file @file{.talkrc},
4914 the matching of @code{user-exp} is done against the remote
4915 caller's name. Any other interpretation is plainly futile.
4916
4917 Each line may be augmented by a net list, containing one or more
4918 expressions @code{net-exp}. Each of these is either the simple
4919 word @samp{any}, a numeric IPv4 address, or a full IPv4 address with
4920 an appended netmask. The effect is to restrict the applicability
4921 of the rule to the specified address range, or to set an explicit
4922 wildcard match @samp{any}.
4923 The absence of a net list is equivalent to specifying
4924 a single @samp{any}. The netmask can be specified as a CIDR mask
4925 length, or as an explicit address mask.
4926
4927 The actual evaluation is made separately for the site-wide ACL,
4928 and for the requested local user ACL, contained in the callee's
4929 private file @file{.talkrc}. This latter file must be a regular
4930 file and must be owned by the very same user, have his primary
4931 group ownership, and not be group or world writeable. Should
4932 any of these prerequisites be violated, the user's ACL is replaced
4933 by a single deny-all rule.
4934
4935 All rules in each set are evaluated, in the sense that whenever
4936 an expression @code{net-exp} matches the incoming IPv4 address,
4937 then the regular expression @code{user-exp} is tested for a match.
4938 That being the case, the corresponding action is recorded. The last
4939 match in each set determines the outcome in its category.
4940
4941 In the most common case, a system wide @samp{deny} is overridden
4942 if the local user has specified at least one valid and applicable rule,
4943 admitting access.
4944 In the contrary case, where no admitting user rule could be established
4945 at all, then a resulting @samp{deny}, from a system wide ACL,
4946 will be used as the final action.
4947
4948 In strict policy mode, a site-wide @samp{deny} is always final,
4949 ignoring any user's desire.
4950 The administrator must explicitly arrange some admitting rule,
4951 with an action @samp{allow}, and some suitable net list.
4952 Still, the individual user can arrange his private file
4953 for an even narrower selection of friends.
4954
4955 @node telnetd invocation
4956 @chapter @command{telnetd}: Telnet server
4957 @pindex telnetd
4958
4959 @example
4960 telnetd [@var{option}]@dots{}
4961 @end example
4962
4963 @table @option
4964 @item --accept-env @var{VAR}
4965 @opindex --accept-env
4966 Allow clients to define the @var{VAR} environment variable. GNU
4967 @command{telnetd} removes all environment variables by default since
4968 many of them can be used to escalate privileges.
4969
4970 @item -a @var{authmode}
4971 @itemx --authmode=@var{authmode}
4972 @opindex -a
4973 @opindex --authmode
4974 Specify what mode to use for authentication. Allowed values are:
4975 @samp{none}, @samp{other}, @samp{user}, @samp{valid}, and @samp{off}.
4976
4977 @item -E @var{string}
4978 @itemx --exec-login=@var{string}
4979 @opindex -E
4980 @opindex --exec-login
4981 Set program to be executed instead of @command{/bin/login}.
4982
4983 @item -h
4984 @itemx --no-hostinfo
4985 @opindex -h
4986 @opindex --no-hostinfo
4987 Do not print host information before login has been completed.
4988
4989 @item -l[@var{mode}]
4990 @itemx --linemode=[@var{mode}]
4991 @opindex -l
4992 @opindex --linemode
4993 Set line mode. An empty argument will force line read mode at all times.
4994 The only recognised value is otherwise @samp{nokludge}.
4995
4996 @item -n
4997 @itemx --no-keepalive
4998 @opindex -n
4999 @opindex --no-keepalive
5000 Disable TCP keep-alive.
5001
5002 @item -S @var{principal}
5003 @itemx --server-principal=@var{principal}
5004 @opindex -S
5005 @opindex --server-principal
5006 Set principal name for the server, to be used in Kerberos
5007 authentication. The value @var{principal} can be set
5008 to provide full specification like @samp{srv.local@@REALM}
5009 and @samp{tnt/localhost@@REALM}, where the first uses the
5010 standard prefix `host/'. Or @var{principal} can override
5011 default settings in part only, like @samp{srv.local},
5012 @samp{tnt/srv.local}, or @samp{@@REALM}.
5013
5014 @item -U
5015 @itemx --reverse-lookup
5016 @opindex -U
5017 @opindex --reverse-lookup
5018 Refuse connections from addresses that cannot be mapped back into a
5019 symbolic name.
5020 A client is accepted only if the IP address can be resolved as
5021 a host name, and the same name is resolvable to addresses among
5022 which the clients's address is included.
5023
5024 @item -X @var{authtype}
5025 @itemx --disable-auth-type=@var{authtype}
5026 @opindex -X
5027 @opindex --disable-auth-type
5028 Disable the use of the given authentication type.
5029 Use this option multiple times if more than one type
5030 is to be disabled. Standard choices are @samp{null},
5031 @samp{kerberos_v4}, and @samp{kerberos_v5}.
5032 @end table
5033
5034 @section Crafting an execution string
5035
5036 The server @command{telnetd} contains a built-in execution string
5037 which invokes @command{login} with arguments suitable for the
5038 operating system at hand. This preset choice corresponds to the
5039 standard use case of the service. For specialized purposes
5040 this implementation also offers a command line option @option{-E},
5041 or @option{--exec-login}, to override the built-in execution of
5042 @command{login}, thus allowing almost any choice of handler.
5043
5044 @noindent
5045 A custom execution string could look like
5046
5047 @example
5048 telnetd -h -E '/usr/local/sbin/avrop %t %U'
5049 @end example
5050
5051 @noindent
5052 The execution string must as its first part provide an absolute
5053 path to an executable file. After that may follow arbitrary
5054 additional arguments.
5055 For this latter part, @command{telnetd} offers some replacement
5056 tokens that dynamically are replaced by content. All are of
5057 the form @code{%<var>}, where @samp{<var>} is a single letter
5058 from the following collection of selectors.
5059 A valid letter is called @dfn{variable}.
5060 The mark @emph{conditional}, appearing below, indicates that the
5061 corresponding variable is conditionally assigned a value.
5062
5063 @table @code
5064 @item %a
5065 @opindex %a
5066 Returns @samp{ok} whenever authentication is complete. @emph{conditional}
5067
5068 @item %d
5069 @opindex %d
5070 Produces a time and date string.
5071
5072 @item %h
5073 @opindex %h
5074 Gives the remote host name in canonical form.
5075
5076 @item %l
5077 @opindex %l
5078 States the local host name, also in canonical form.
5079
5080 @item %L
5081 @opindex %L
5082 Returns the path of the pseudo terminal assigned to the client.
5083
5084 @item %t
5085 @opindex %t
5086 Gives the terminal device stripped of the leading @samp{/dev/}.
5087
5088 @item %T
5089 @opindex %T
5090 States the terminal type, like @samp{xterm}. @emph{conditional}
5091
5092 @item %u
5093 @opindex %u
5094 Provides the authenticated user name. @emph{conditional}
5095
5096 @item %U
5097 @opindex %U
5098 Returns the user name passed as an environment variable @env{USER}
5099 by the remote client software. The value is empty, should the
5100 environment not provide a value.
5101
5102 @end table
5103
5104 In addition, a conditional construct is able to take one action
5105 in case a variable has an assigned value, and optionally to take
5106 another action in the opposite case. The construct is
5107
5108 @example
5109 %?<var>@{true-stmt@}[@{false-stmt@}]
5110 @end example
5111
5112 @noindent
5113 The braces are here mandatory, while the brackets enclose the optional
5114 else-clause and are not included in actual use.
5115 The initial, motivating example, could thus be expanded to read
5116
5117 @example
5118 telnetd -h -E '/usr/local/sbin/avrop %t %?a@{%u krb5@}@{%U@}'
5119 @end example
5120
5121 @noindent
5122 In case authentication was completed as user @samp{sigge},
5123 the execution string would resolve to
5124
5125 @example
5126 /usr/local/sbin/avrop pts/1 sigge krb5
5127 @end example
5128
5129 @noindent
5130 In all other cases the result would be
5131
5132 @example
5133 /usr/local/sbin/avrop pts/1 $USER
5134 @end example
5135
5136 @noindent
5137 where @code{$USER} is the value of the corresponding environment
5138 variable and could possibly be empty.
5139
5140 @node tftpd invocation
5141 @chapter @command{tftpd}: TFTP server
5142 @pindex tftpd
5143
5144 @command{tftpd} is intended to be invoked via @command{inetd}
5145 at all times.
5146
5147 @noindent
5148 Synopsis:
5149
5150 @example
5151 tftpd [@var{options}] [@var{directory} @dots{}]
5152 @end example
5153
5154 @table @option
5155 @item -g @var{group}
5156 @itemx --group=@var{group}
5157 @opindex -g
5158 @opindex --group
5159 Specify group membership of the process owner.
5160 This is used only along with the option @option{-s},
5161 and replaces the group membership that comes from
5162 the process owner himself.
5163
5164 @item -l
5165 @itemx --logging
5166 @opindex -l
5167 @opindex --logging
5168 Enable logging.
5169
5170 @item -n
5171 @itemx --nonexistent
5172 @opindex -n
5173 @opindex --nonexistent
5174 Suppress negative acknowledgement of requests for nonexistent relative
5175 filenames.
5176
5177 @item -s @var{dir}
5178 @itemx --secure-dir=@var{dir}
5179 @opindex -s
5180 @opindex --secure-dir
5181 Let the serving process change its root directory to @var{dir}
5182 before attending to any requests.
5183 This directory is not observable by any client, but improves
5184 server isolation, since servable contents must be located
5185 below this chrooted directory @var{dir}.
5186
5187 @item -u @var{user}
5188 @itemx --user=@var{user}
5189 @opindex -u
5190 @opindex --user
5191 Specify the process owner for serving requests.
5192 Only relevant along with the option @option{-s}.
5193 The default name is @samp{nobody}.
5194 @end table
5195
5196 @section Directory prefixes
5197 @anchor{tftpd validation}
5198
5199 In addition to options, an invocation of @command{tftpd} can
5200 specify an optional list of directory prefixes.
5201 These are approved of according to two principles:
5202
5203 @itemize @bullet
5204 @item
5205 Relative pathnames are ignored.
5206
5207 @item
5208 At most twenty prefixes are approved, the rest is discarded.
5209 @end itemize
5210
5211 @noindent
5212 A request for a file is decided upon as a consequence
5213 of evaluating these criteria:
5214
5215 @itemize @bullet
5216 @item
5217 Every file request containing the substring @samp{/../} is denied,
5218 as is a file name beginning with @samp{../}.
5219
5220 @item
5221 Write requests must specify absolute locations.
5222
5223 @item
5224 A file request, if specified as an @emph{absolute} pathname,
5225 must begin with one of the approved directory prefixes,
5226 should at least one such prefix have been accepted.
5227
5228 @item
5229 In the absence of a prefix collection, any absolute pathname is
5230 accepted, should the corresponding file exist.
5231
5232 @item
5233 A file request, if specified as a @emph{relative} name,
5234 will only be searched for below the acceptable prefixes,
5235 should at least one such prefix have been approved.
5236
5237 @item
5238 A request for a relatively named file, is denied in the absence
5239 of approved directory prefixes.
5240
5241 @item
5242 The resulting file must be world readable, or world writable,
5243 for a read request, or a write request, to succeed.
5244 @end itemize
5245
5246 @section Use cases
5247 @anchor{tftpd setup cases}
5248
5249 The standard use case is an entry in @file{/etc/inetd.conf} like
5250
5251 @example
5252 tftp dgram udp4 wait root /usr/sbin/tftpd \
5253 @verb{ } tftpd /tftpboot /altboot
5254 @end example
5255
5256 @noindent
5257 This would allow the TFTP client to use any of
5258
5259 @example
5260 get kernel
5261 get /tftpboot/kernel
5262 get kernel.alt
5263 get /altboot/kernel.alt
5264 get /etc/motd
5265 @end example
5266
5267 @noindent
5268 given that @file{/tftpboot/kernel} and @file{/altboot/kernel.alt} exist.
5269 Observe that also @file{/etc/motd} is accessible, in spite of there
5270 being no explicit mention of standard file locations.
5271
5272 A stronger mode of running a TFTP server is to use the `secure mode',
5273 meaning that the serving process is running in a chrooted mode.
5274 Then a suitable configuration could be
5275
5276 @example
5277 tftp dgram udp4 wait root /usr/sbin/tftpd \
5278 @verb{ } tftpd --secure-dir=/srv/tftp-root /tftpboot /altboot
5279 @end example
5280
5281 @noindent
5282 Supposing the files @file{kernel} and @file{kernel.alt} to exist
5283 in the common directory @file{/srv/tftp-root/altboot/},
5284 all the previously suggested client requests for a kernel would
5285 still be granted, but now any request for @file{/etc/motd}
5286 would be declined, and would get a reply `File not found' back.
5287
5288 The chrooted setting is denying access outside of
5289 @file{/srv/tftp-root}, yet is not indicating this lock-in
5290 to the client, and is thus improving server isolation.
5291 Since neither of @option{-u} and @option{-g} were specified,
5292 the configuration reproduced above will in fact have the
5293 transmitting server process running with the default
5294 owner set to @samp{nobody:nogroup}.
5295
5296 @node uucpd invocation
5297 @chapter @command{uucpd}: Unix to Unix Copy relay daemon.
5298 @pindex uucpd
5299
5300 @command{uucpd} is a relay daemon responsible for accepting
5301 TCP transported connections for @command{uucico}. It is started
5302 by @command{inetd}, conducts any authentication, and then hands
5303 acceptable requests over to @command{uucico}.
5304
5305 @example
5306 uucpd [@var{option}]...
5307 @end example
5308
5309 @section Options
5310
5311 There is a single, specific option available:
5312
5313 @table @option
5314 @item -u @var{location}
5315 @itemx --uucico=@var{location}
5316 @opindex -u
5317 @opindex --uucico
5318 Replace the hard coded location of @command{uucico} with the
5319 value specified as @var{location}.
5320 @end table
5321
5322 @section Authentication steps
5323
5324 Invocation is expected to be conducted by a protocol described
5325 exchange of user name and password; unfortunately in clear text.
5326 If those agree with existing local entries, then @command{uucpd}
5327 verifies that the stated user also has user shell location
5328 identical to the full file system location of @command{uucico}.
5329 Should that not be the case, the request is declined.
5330
5331 For this latter check, the option @option{--uucico} is useful
5332 when setting the configuration for @command{inetd}. It is
5333 recommended to wrap the invocation line of @command{uucpd}
5334 within a call to @command{tcpd} in the standard fashion.
5335
5336 @node GNU Free Documentation License
5337 @appendix GNU Free Documentation License
5338 @include fdl-1.3.texi
5339
5340 @page
5341 @node Index
5342 @unnumbered Index
5343
5344 @printindex cp
5345
5346 @bye