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