| 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 |