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