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