libexec/telnetd/telnetd.8

   1 .\"     $NetBSD: telnetd.8,v 1.30 2004/07/17 18:34:01 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1983, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     from: @(#)telnetd.8     8.3 (Berkeley) 3/1/94
  31 .\"
  32 .Dd July 17, 2004
  33 .Dt TELNETD 8
  34 .Os
  35 .Sh NAME
  36 .Nm telnetd
  37 .Nd DARPA
  38 .Tn TELNET
  39 protocol server
  40 .Sh SYNOPSIS
  41 .Nm /usr/libexec/telnetd
  42 .Op Fl Uhlkns46
  43 .Op Fl D Ar debugmode
  44 .Op Fl S Ar tos
  45 .Op Fl X Ar authtype
  46 .Op Fl a Ar authmode
  47 .Op Fl edebug
  48 .Op Fl g Ar gettyent
  49 .Op Fl u Ar len
  50 .Op Fl debug Op Ar port
  51 .Sh DESCRIPTION
  52 The
  53 .Nm
  54 command is a server which supports the
  55 .Tn DARPA
  56 standard
  57 .Tn TELNET
  58 virtual terminal protocol.
  59 .Nm
  60 is normally invoked by the internet server (see
  61 .Xr inetd 8 )
  62 for requests to connect to the
  63 .Tn TELNET
  64 port as indicated by the
  65 .Pa /etc/services
  66 file (see
  67 .Xr services 5 ) .
  68 The
  69 .Fl debug
  70 option may be used to start up
  71 .Nm
  72 manually, instead of through
  73 .Xr inetd 8 .
  74 If started up this way,
  75 .Ar port
  76 may be specified to run
  77 .Nm
  78 on an alternate
  79 .Tn TCP
  80 port number.
  81 .Pp
  82 The
  83 .Nm
  84 command accepts the following options:
  85 .Bl -tag -width "-a authmode"
  86 .It Fl a Ar authmode
  87 This option may be used for specifying what mode should
  88 be used for authentication.
  89 Note that this option is only useful if
  90 .Nm
  91 has been compiled with support for the
  92 .Dv AUTHENTICATION
  93 option.
  94 There are several valid values for
  95 .Ar authmode :
  96 .Bl -tag -width debug
  97 .It debug
  98 Turns on authentication debugging code.
  99 .It user
 100 Only allow connections when the remote user
 101 can provide valid authentication information
 102 to identify the remote user,
 103 and is allowed access to the specified account
 104 without providing a password.
 105 .It valid
 106 Only allow connections when the remote user
 107 can provide valid authentication information
 108 to identify the remote user.
 109 The
 110 .Xr login 1
 111 command will provide any additional user verification
 112 needed if the remote user is not allowed automatic
 113 access to the specified account.
 114 .It other
 115 Only allow connections that supply some authentication information.
 116 This option is currently not supported
 117 by any of the existing authentication mechanisms,
 118 and is thus the same as specifying
 119 .Fl a
 120 .Cm valid .
 121 .It none
 122 This is the default state.
 123 Authentication information is not required.
 124 If no or insufficient authentication information
 125 is provided, then the
 126 .Xr login 1
 127 program will provide the necessary user
 128 verification.
 129 .It off
 130 This disables the authentication code.
 131 All user verification will happen through the
 132 .Xr login 1
 133 program.
 134 .El
 135 .It Fl D Ar debugmode
 136 This option may be used for debugging purposes.
 137 This allows
 138 .Nm
 139 to print out debugging information
 140 to the connection, allowing the user to see what
 141 .Nm
 142 is doing.
 143 There are several possible values for
 144 .Ar debugmode :
 145 .Bl -tag -width exercise
 146 .It Cm options
 147 Prints information about the negotiation of
 148 .Tn TELNET
 149 options.
 150 .It Cm report
 151 Prints the
 152 .Cm options
 153 information, plus some additional information
 154 about what processing is going on.
 155 .It Cm netdata
 156 Displays the data stream received by
 157 .Nm .
 158 .It Cm ptydata
 159 Displays data written to the pty.
 160 .It Cm exercise
 161 Has not been implemented yet.
 162 .El
 163 .It Fl debug
 164 Enables debugging on each socket created by
 165 .Nm
 166 (see
 167 .Dv SO_DEBUG
 168 in
 169 .Xr socket 2 ) .
 170 .It Fl edebug
 171 If
 172 .Nm
 173 has been compiled with support for data encryption, then the
 174 .Fl edebug
 175 option may be used to enable encryption debugging code.
 176 .It Fl g Ar gettyent
 177 Specifies which entry from
 178 .Pa /etc/gettytab
 179 should be used to get banner strings, login program and
 180 other information.
 181 The default entry is
 182 .Dv default .
 183 .It Fl h
 184 Disables the printing of host-specific information before
 185 login has been completed.
 186 .It Fl k
 187 This option is only useful if
 188 .Nm
 189 has been compiled with both linemode and kludge linemode support.
 190 If the
 191 .Fl k
 192 option is specified,
 193 then if the remote client does not support the
 194 .Dv LINEMODE
 195 option, then
 196 .Nm
 197 will operate in character at a time mode.
 198 It will still support kludge linemode, but will only
 199 go into kludge linemode if the remote client requests it.
 200 (This is done by by the client sending
 201 .Dv DONT SUPPRESS-GO-AHEAD
 202 and
 203 .Dv DONT ECHO . )
 204 The
 205 .Fl k
 206 option is most useful when there are remote clients
 207 that do not support kludge linemode, but pass the heuristic
 208 (if they respond with
 209 .Dv WILL TIMING-MARK
 210 in response to a
 211 .Dv DO TIMING-MARK )
 212 for kludge linemode support.
 213 .It Fl l
 214 Specifies line mode.
 215 Tries to force clients to use line-at-a-time mode.
 216 If the
 217 .Dv LINEMODE
 218 option is not supported, it will go
 219 into kludge linemode.
 220 .It Fl n
 221 Disable
 222 .Dv TCP
 223 keep-alives.
 224 Normally
 225 .Nm
 226 enables the
 227 .Tn TCP
 228 keep-alive mechanism to probe connections that
 229 have been idle for some period of time to determine
 230 if the client is still there, so that idle connections
 231 from machines that have crashed or can no longer
 232 be reached may be cleaned up.
 233 .It Fl s
 234 This option is only enabled if
 235 .Nm
 236 is compiled with support for secure logins.
 237 It causes the
 238 .Fl s
 239 option to be passed on to
 240 .Xr login 1 ,
 241 and thus is only useful if
 242 .Xr login 1
 243 supports the
 244 .Fl s
 245 flag to indicate that only Kerberos or S/Key
 246 validated logins are allowed, and is
 247 usually useful for controlling remote logins
 248 from outside of a firewall.
 249 .It Fl S Ar tos
 250 This option sets the IP Type-of Service (TOS) option
 251 on the connection to the value tos, which may be a
 252 numeric TOS value or a symbolic TOS name found in the
 253 .Pa /etc/iptos
 254 file.
 255 This option has no effect on
 256 .Nx .
 257 .\"The option has no effect on systems that do not
 258 .\"support
 259 .\".Xr parsetos 3
 260 .\"routine and the
 261 .\".Pa /etc/iptos
 262 .\"file.
 263 .It Fl u Ar len
 264 This option is used to specify the size of the field
 265 in the
 266 .Dv utmp
 267 structure that holds the remote host name.
 268 If the resolved host name is longer than
 269 .Ar len ,
 270 the dotted decimal value will be used instead.
 271 This allows hosts with very long host names that
 272 overflow this field to still be uniquely identified.
 273 Specifying
 274 .Fl u0
 275 indicates that only dotted decimal addresses
 276 should be put into the
 277 .Pa utmp
 278 file.
 279 .It Fl U
 280 This option causes
 281 .Nm
 282 to refuse connections from addresses that
 283 cannot be mapped back into a symbolic name via the
 284 .Xr getnameinfo 3
 285 routine.
 286 .It Fl X Ar authtype
 287 This option is only valid if
 288 .Nm
 289 has been built with support for the authentication option.
 290 It disables the use of
 291 .Ar authtype
 292 authentication, and can be used to temporarily disable
 293 a specific authentication type without having to recompile
 294 .Nm .
 295 .It Fl 4
 296 .It Fl 6
 297 Specifies address family to be used on
 298 .Fl debug
 299 mode.
 300 During normal operation
 301 .Po
 302 called from
 303 .Xr inetd 8
 304 .Pc
 305 .Nm
 306 will use the file descriptor passed from
 307 .Xr inetd 8 .
 308 .El
 309 .Pp
 310 .Nm
 311 operates by allocating a pseudo-terminal device (see
 312 .Xr pty 4 )
 313 for a client, then creating a login process which has
 314 the slave side of the pseudo-terminal as
 315 .Dv stdin ,
 316 .Dv stdout
 317 and
 318 .Dv stderr .
 319 .Nm
 320 manipulates the master side of the pseudo-terminal,
 321 implementing the
 322 .Tn TELNET
 323 protocol and passing characters
 324 between the remote client and the login process.
 325 .Pp
 326 When a
 327 .Tn TELNET
 328 session is started up,
 329 .Nm
 330 sends
 331 .Tn TELNET
 332 options to the client side indicating
 333 a willingness to do the following
 334 .Tn TELNET
 335 options, which are described in more detail below:
 336 .Bd -literal -offset indent
 337 DO AUTHENTICATION
 338 WILL ENCRYPT
 339 DO TERMINAL TYPE
 340 DO TSPEED
 341 DO XDISPLOC
 342 DO NEW-ENVIRON
 343 DO ENVIRON
 344 WILL SUPPRESS GO AHEAD
 345 DO ECHO
 346 DO LINEMODE
 347 DO NAWS
 348 WILL STATUS
 349 DO LFLOW
 350 DO TIMING-MARK
 351 .Ed
 352 .Pp
 353 The pseudo-terminal allocated to the client is configured
 354 to operate in \*(lqcooked\*(rq mode, and with
 355 .Dv XTABS and
 356 .Dv CRMOD
 357 enabled (see
 358 .Xr tty 4 ) .
 359 .Pp
 360 .Nm
 361 has support for enabling locally the following
 362 .Tn TELNET
 363 options:
 364 .Bl -tag -width "DO AUTHENTICATION"
 365 .It "WILL ECHO"
 366 When the
 367 .Dv LINEMODE
 368 option is enabled, a
 369 .Dv WILL ECHO
 370 or
 371 .Dv WONT ECHO
 372 will be sent to the client to indicate the
 373 current state of terminal echoing.
 374 When terminal echo is not desired, a
 375 .Dv WILL ECHO
 376 is sent to indicate that
 377 .Tn telnetd
 378 will take care of echoing any data that needs to be
 379 echoed to the terminal, and then nothing is echoed.
 380 When terminal echo is desired, a
 381 .Dv WONT ECHO
 382 is sent to indicate that
 383 .Tn telnetd
 384 will not be doing any terminal echoing, so the
 385 client should do any terminal echoing that is needed.
 386 .It "WILL BINARY"
 387 Indicates that the client is willing to send a
 388 8 bits of data, rather than the normal 7 bits
 389 of the Network Virtual Terminal.
 390 .It "WILL SGA"
 391 Indicates that it will not be sending
 392 .Dv IAC GA ,
 393 go ahead, commands.
 394 .It "WILL STATUS"
 395 Indicates a willingness to send the client, upon
 396 request, of the current status of all
 397 .Tn TELNET
 398 options.
 399 .It "WILL TIMING-MARK"
 400 Whenever a
 401 .Dv DO TIMING-MARK
 402 command is received, it is always responded
 403 to with a
 404 .Dv WILL TIMING-MARK
 405 .It "WILL LOGOUT"
 406 When a
 407 .Dv DO LOGOUT
 408 is received, a
 409 .Dv WILL LOGOUT
 410 is sent in response, and the
 411 .Tn TELNET
 412 session is shut down.
 413 .It "WILL ENCRYPT"
 414 Only sent if
 415 .Nm
 416 is compiled with support for data encryption, and
 417 indicates a willingness to decrypt the data stream.
 418 .El
 419 .Pp
 420 .Nm
 421 has support for enabling remotely the following
 422 .Tn TELNET
 423 options:
 424 .Bl -tag -width "DO AUTHENTICATION"
 425 .It "DO BINARY"
 426 Sent to indicate that
 427 .Tn telnetd
 428 is willing to receive an 8 bit data stream.
 429 .It "DO LFLOW"
 430 Requests that the client handle flow control
 431 characters remotely.
 432 .It "DO ECHO"
 433 This is not really supported, but is sent to identify a
 434 .Bx 4.2
 435 .Xr telnet 1
 436 client, which will improperly respond with
 437 .Dv WILL ECHO .
 438 If a
 439 .Dv WILL ECHO
 440 is received, a
 441 .Dv DONT ECHO
 442 will be sent in response.
 443 .It "DO TERMINAL-TYPE"
 444 Indicates a desire to be able to request the
 445 name of the type of terminal that is attached
 446 to the client side of the connection.
 447 .It "DO SGA"
 448 Indicates that it does not need to receive
 449 .Dv IAC GA ,
 450 the go ahead command.
 451 .It "DO NAWS"
 452 Requests that the client inform the server when
 453 the window (display) size changes.
 454 .It "DO TERMINAL-SPEED"
 455 Indicates a desire to be able to request information
 456 about the speed of the serial line to which
 457 the client is attached.
 458 .It "DO XDISPLOC"
 459 Indicates a desire to be able to request the name
 460 of the X windows display that is associated with
 461 the telnet client.
 462 .It "DO NEW-ENVIRON"
 463 Indicates a desire to be able to request environment
 464 variable information, as described in RFC 1572.
 465 .It "DO ENVIRON"
 466 Indicates a desire to be able to request environment
 467 variable information, as described in RFC 1408.
 468 .It "DO LINEMODE"
 469 Only sent if
 470 .Nm
 471 is compiled with support for linemode, and
 472 requests that the client do line by line processing.
 473 .It "DO TIMING-MARK"
 474 Only sent if
 475 .Nm
 476 is compiled with support for both linemode and
 477 kludge linemode, and the client responded with
 478 .Dv WONT LINEMODE .
 479 If the client responds with
 480 .Dv WILL TM ,
 481 the it is assumed that the client supports kludge linemode.
 482 Note that the
 483 .Op Fl k
 484 option can be used to disable this.
 485 .It "DO AUTHENTICATION"
 486 Only sent if
 487 .Nm
 488 is compiled with support for authentication, and
 489 indicates a willingness to receive authentication
 490 information for automatic login.
 491 .It "DO ENCRYPT"
 492 Only sent if
 493 .Nm
 494 is compiled with support for data encryption, and
 495 indicates a willingness to decrypt the data stream.
 496 .El
 497 .Pp
 498 At the end of a login session,
 499 .Nm
 500 invokes the
 501 .Xr ttyaction 3
 502 facility with an action of "telnetd" and user "root"
 503 to execute site-specific commands.
 504 .Sh FILES
 505 .Bl -item -compact
 506 .It
 507 .Pa /etc/services
 508 .It
 509 .Pa /etc/iptos
 510 (if supported)
 511 .El
 512 .Sh SEE ALSO
 513 .Xr login 1 ,
 514 .Xr skey 1 ,
 515 .Xr telnet 1 ,
 516 .Xr ttyaction 3
 517 .Sh STANDARDS
 518 .Bl -tag -compact -width "RFC 1572  "
 519 .It RFC 854
 520 .Tn TELNET
 521 PROTOCOL SPECIFICATION
 522 .It RFC 855
 523 TELNET OPTION SPECIFICATIONS
 524 .It RFC 856
 525 TELNET BINARY TRANSMISSION
 526 .It RFC 857
 527 TELNET ECHO OPTION
 528 .It RFC 858
 529 TELNET SUPPRESS GO AHEAD OPTION
 530 .It RFC 859
 531 TELNET STATUS OPTION
 532 .It RFC 860
 533 TELNET TIMING MARK OPTION
 534 .It RFC 861
 535 TELNET EXTENDED OPTIONS - LIST OPTION
 536 .It RFC 885
 537 TELNET END OF RECORD OPTION
 538 .It RFC 1073
 539 Telnet Window Size Option
 540 .It RFC 1079
 541 Telnet Terminal Speed Option
 542 .It RFC 1091
 543 Telnet Terminal-Type Option
 544 .It RFC 1096
 545 Telnet X Display Location Option
 546 .It RFC 1123
 547 Requirements for Internet Hosts -- Application and Support
 548 .It RFC 1184
 549 Telnet Linemode Option
 550 .It RFC 1372
 551 Telnet Remote Flow Control Option
 552 .It RFC 1416
 553 Telnet Authentication Option
 554 .It RFC 1411
 555 Telnet Authentication: Kerberos Version 4
 556 .It RFC 1412
 557 Telnet Authentication: SPX
 558 .It RFC 1571
 559 Telnet Environment Option Interoperability Issues
 560 .It RFC 1572
 561 Telnet Environment Option
 562 .El
 563 .Sh BUGS
 564 Some
 565 .Tn TELNET
 566 commands are only partially implemented.
 567 .Pp
 568 Because of bugs in the original
 569 .Bx 4.2
 570 .Xr telnet 1 ,
 571 .Nm
 572 performs some dubious protocol exchanges to try to discover if the remote
 573 client is, in fact, a
 574 .Bx 4.2
 575 .Xr telnet 1 .
 576 .Pp
 577 Binary mode
 578 has no common interpretation except between similar operating systems
 579 .Po
 580 .Ux
 581 in this case
 582 .Pc .
 583 .Pp
 584 The terminal type name received from the remote client is converted to
 585 lower case.
 586 .Pp
 587 .Nm
 588 never sends
 589 .Tn TELNET
 590 .Dv IAC GA
 591 (go ahead) commands.