(no commit message)
[ikiwiki.git] / docs / docs / newhandbook / serial_communications / index.mdwn
1 ## Chapter 18 Serial Communications 
2 [[!toc  levels=3]]
3
4 ## Synopsis 
5
6
7
8 UNIX® has always had support for serial communications. In fact, the very first UNIX machines relied on serial lines for user input and output. Things have changed a lot from the days when the average ***terminal*** consisted of a 10-character-per-second serial printer and a keyboard. This chapter will cover some of the ways in which DragonFly uses serial communications.
9
10
11
12 After reading this chapter, you will know:
13
14
15
16
17 * How to connect terminals to your DragonFly system.
18
19
20 * How to use a modem to dial out to remote hosts.
21
22
23 * How to allow remote users to login to your system with a modem.
24
25
26 * How to boot your system from a serial console.
27
28
29
30 Before reading this chapter, you should:
31
32
33
34
35 * Know how to configure and install a new kernel ([kernelconfig.html Chapter 10]).
36
37
38 * Understand UNIX permissions and processes ([basics.html Chapter 3]).
39
40
41 * Have access to the technical manual for the serial hardware (modem or multi-port card) that you would like to use with DragonFly.
42
43
44 ***
45
46
47 ## 18.1 Introduction 
48
49
50
51 ### 18.1.1 Terminology 
52
53
54
55 bps:: Bits per Second -- the rate at which data is transmitted;
56
57 DTE:: Data Terminal Equipment -- for example, your computer;
58
59 DCE:: Data Communications Equipment -- your modem;
60
61 RS-232:: EIA standard for hardware serial communications.
62
63
64
65 When talking about communications data rates, this section does not use the term ***baud***. Baud refers to the number of electrical state transitions that may be made in a period of time, while ***bps*** (bits per second) is the ***correct*** term to use (at least it does not seem to bother the curmudgeons quite as much).
66
67
68
69 ### 18.1.2 Cables and Ports 
70
71
72
73 To connect a modem or terminal to your DragonFly system, you will need a serial port on your computer and the proper cable to connect to your serial device. If you are already familiar with your hardware and the cable it requires, you can safely skip this section.
74
75
76
77 #### 18.1.2.1 Cables 
78
79
80
81 There are several different kinds of serial cables. The two most common types for our purposes are null-modem cables and standard (***straight***) RS-232 cables. The documentation for your hardware should describe the type of cable required.
82
83
84
85 ##### 18.1.2.1.1 Null-modem Cables 
86
87
88
89 A null-modem cable passes some signals, such as ***signal ground***, straight through, but switches other signals. For example, the ***send data*** pin on one end goes to the ***receive data*** pin on the other end.
90
91
92
93 If you like making your own cables, you can construct a null-modem cable for use with terminals. This table shows the RS-232C signal names and the pin numbers on a DB-25 connector.
94
95
96
97 [[!table  data="""
98 | Signal | Pin # |  | Pin # | Signal 
99  SG | 7 | connects to | 7 | SG 
100  TxD | 2 | connects to | 3 | RxD 
101  RxD | 3 | connects to | 2 | TxD 
102  RTS | 4 | connects to | 5 | CTS 
103  CTS | 5 | connects to | 4 | RTS 
104  DTR | 20 | connects to | 6 | DSR 
105  DCD | 8 |  | 6 | DSR 
106  DSR | 6 | connects to | 20 | DTR |
107
108 """]]
109
110  **Note:** Connect ***Data Set Ready*** (DSR) and ***Data Carrier Detect*** (DCD) internally in the connector hood, and then to ***Data Terminal Ready*** (DTR) in the remote hood.
111
112
113
114 ##### 18.1.2.1.2 Standard RS-232C Cables 
115
116
117
118 A standard serial cable passes all the RS-232C signals straight-through. That is, the ***send data*** pin on one end of the cable goes to the ***send data*** pin on the other end. This is the type of cable to use to connect a modem to your DragonFly system, and is also appropriate for some terminals.
119
120
121
122 #### 18.1.2.2 Ports 
123
124
125
126 Serial ports are the devices through which data is transferred between the DragonFly host computer and the terminal. This section describes the kinds of ports that exist and how they are addressed in DragonFly.
127
128
129
130 ##### 18.1.2.2.1 Kinds of Ports 
131
132
133
134 Several kinds of serial ports exist. Before you purchase or construct a cable, you need to make sure it will fit the ports on your terminal and on the DragonFly system.
135
136
137
138 Most terminals will have DB25 ports. Personal computers, including PCs running DragonFly, will have DB25 or DB9 ports. If you have a multiport serial card for your PC, you may have RJ-12 or RJ-45 ports.
139
140
141
142 See the documentation that accompanied the hardware for specifications on the kind of port in use. A visual inspection of the port often works too.
143
144
145
146 ##### 18.1.2.2.2 Port Names 
147
148
149
150 In DragonFly, you access each serial port through an entry in the `/dev` directory. There are two different kinds of entries:
151
152
153
154
155 * Call-in ports are named `/dev/ttyd`***N****** where `***N***` is the port number, starting from zero. Generally, you use the call-in port for terminals. Call-in ports require that the serial line assert the data carrier detect (DCD) signal to work correctly.
156
157
158 * Call-out ports are named `/dev/cuaa`***N******. You usually do not use the call-out port for terminals, just for modems. You may use the call-out port if the serial cable or the terminal does not support the carrier detect signal.
159
160
161
162 If you have connected a terminal to the first serial port (`COM1` in MS-DOS®), then you will use `/dev/ttyd0` to refer to the terminal. If the terminal is on the second serial port (also known as `COM2`), use `/dev/ttyd1`, and so forth.
163
164
165
166 ### 18.1.3 Kernel Configuration 
167
168
169
170 DragonFly supports four serial ports by default. In the MS-DOS world, these are known as `COM1`, `COM2`, `COM3`, and `COM4`. DragonFly currently supports ***dumb*** multiport serial interface cards, such as the BocaBoard 1008 and 2016, as well as more intelligent multi-port cards such as those made by Digiboard and Stallion Technologies. However, the default kernel only looks for the standard COM ports.
171
172
173
174 To see if your kernel recognizes any of your serial ports, watch for messages while the kernel is booting, or use the `/sbin/dmesg` command to replay the kernel's boot messages. In particular, look for messages that start with the characters `sio`.
175
176
177
178  **Tip:** To view just the messages that have the word `sio`, use the command:
179
180
181
182     
183
184     # /sbin/dmesg | grep 'sio'
185
186
187
188
189
190 For example, on a system with four serial ports, these are the serial-port specific kernel boot messages:
191
192
193
194     
195
196     sio0 at 0x3f8-0x3ff irq 4 on isa
197
198     sio0: type 16550A
199
200     sio1 at 0x2f8-0x2ff irq 3 on isa
201
202     sio1: type 16550A
203
204     sio2 at 0x3e8-0x3ef irq 5 on isa
205
206     sio2: type 16550A
207
208     sio3 at 0x2e8-0x2ef irq 9 on isa
209
210     sio3: type 16550A
211
212
213
214
215
216 If your kernel does not recognize all of your serial ports, you will probably need to configure a custom DragonFly kernel for your system. For detailed information on configuring your kernel, please see [kernelconfig.html Chapter 10].
217
218
219
220 The relevant device lines for your kernel configuration file would look like this:
221
222
223
224     
225
226     device              sio0    at isa? port IO_COM1 irq 4
227
228     device              sio1    at isa? port IO_COM2 irq 3
229
230     device              sio2    at isa? port IO_COM3 irq 5
231
232     device              sio3    at isa? port IO_COM4 irq 9
233
234
235
236
237
238 You can comment-out or completely remove lines for devices you do not have. Please refer to the [sio(4)](http://leaf.dragonflybsd.org/cgi/web-man?command#sio&section4) manual page for more information on serial ports and multiport boards configuration.
239
240
241
242  **Note:** `port IO_COM1` is a substitution for `port 0x3f8`, `IO_COM2` is `0x2f8`, `IO_COM3` is `0x3e8`, and `IO_COM4` is `0x2e8`, which are fairly common port addresses for their respective serial ports; interrupts 4, 3, 5, and 9 are fairly common interrupt request lines. Also note that regular serial ports ***cannot*** share interrupts on ISA-bus PCs (multiport boards have on-board electronics that allow all the 16550A's on the board to share one or two interrupt request lines).
243
244
245
246 ### 18.1.4 Device Special Files 
247
248
249
250 Most devices in the kernel are accessed through ***device special files***, which are located in the `/dev` directory. The `sio` devices are accessed through the `/dev/ttyd`***N****** (dial-in) and `/dev/cuaa`***N****** (call-out) devices. DragonFly also provides initialization devices (`/dev/ttyid`***N****** and `/dev/cuaia`***N******) and locking devices (`/dev/ttyld`***N****** and `/dev/cuala`***N******). The initialization devices are used to initialize communications port parameters each time a port is opened, such as `crtscts` for modems which use `RTS/CTS` signaling for flow control. The locking devices are used to lock flags on ports to prevent users or programs changing certain parameters; see the manual pages [termios(4)](http://leaf.dragonflybsd.org/cgi/web-man?command#termios&section4), [sio(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=sio&section=4), and [stty(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=stty&section=1) for information on the terminal settings, locking and initializing devices, and setting terminal options, respectively.
251
252
253
254 #### 18.1.4.1 Making Device Special Files 
255
256
257
258 A shell script called `MAKEDEV` in the `/dev` directory manages the device special files. To use `MAKEDEV` to make dial-up device special files for `COM1` (port 0), `cd` to `/dev` and issue the command `MAKEDEV ttyd0`. Likewise, to make dial-up device special files for `COM2` (port 1), use `MAKEDEV ttyd1`.
259
260
261
262 `MAKEDEV` not only creates the `/dev/ttyd`***N****** device special files, but also the `/dev/cuaa`***N******, `/dev/cuaia`***N******, `/dev/cuala`***N******, `/dev/ttyld`***N******, and `/dev/ttyid`***N****** nodes.
263
264
265
266 After making new device special files, be sure to check the permissions on the files (especially the `/dev/cua*` files) to make sure that only users who should have access to those device special files can read and write on them -- you probably do not want to allow your average user to use your modems to dial-out. The default permissions on the `/dev/cua*` files should be sufficient:
267
268
269
270     
271
272     crw-rw----    1 uucp     dialer    28, 129 Feb 15 14:38 /dev/cuaa1
273
274     crw-rw----    1 uucp     dialer    28, 161 Feb 15 14:38 /dev/cuaia1
275
276     crw-rw----    1 uucp     dialer    28, 193 Feb 15 14:38 /dev/cuala1
277
278
279
280
281
282 These permissions allow the user `uucp` and users in the group `dialer` to use the call-out devices.
283
284
285
286 ### 18.1.5 Serial Port Configuration 
287
288
289
290 The `ttyd`***N****** (or `cuaa`***N******) device is the regular device you will want to open for your applications. When a process opens the device, it will have a default set of terminal I/O settings. You can see these settings with the command
291
292
293
294     
295
296     # stty -a -f /dev/ttyd1
297
298
299
300
301
302 When you change the settings to this device, the settings are in effect until the device is closed. When it is reopened, it goes back to the default set. To make changes to the default set, you can open and adjust the settings of the ***initial state*** device. For example, to turn on `CLOCAL` mode, 8 bit communication, and `XON/XOFF` flow control by default for `ttyd5`, type:
303
304
305
306     
307
308     # stty -f /dev/ttyid5 clocal cs8 ixon ixoff
309
310
311
312
313
314 System-wide initialization of the serial devices is controlled in `/etc/rc.serial`. This file affects the default settings of serial devices.
315
316
317
318 To prevent certain settings from being changed by an application, make adjustments to the ***lock state*** device. For example, to lock the speed of `ttyd5` to 57600 bps, type:
319
320
321
322     
323
324     # stty -f /dev/ttyld5 57600
325
326
327
328
329
330 Now, an application that opens `ttyd5` and tries to change the speed of the port will be stuck with 57600 bps.
331
332
333
334 Naturally, you should make the initial state and lock state devices writable only by the `root` account.
335
336 ***
337
338 ## 18.2 Terminals 
339
340
341 Terminals provide a convenient and low-cost way to access your DragonFly system when you are not at the computer's console or on a connected network. This section describes how to use terminals with DragonFly.
342
343
344
345 ### 18.2.1 Uses and Types of Terminals 
346
347
348
349 The original UNIX® systems did not have consoles. Instead, people logged in and ran programs through terminals that were connected to the computer's serial ports. It is quite similar to using a modem and terminal software to dial into a remote system to do text-only work.
350
351
352
353 Today's PCs have consoles capable of high quality graphics, but the ability to establish a login session on a serial port still exists in nearly every UNIX style operating system today; DragonFly is no exception. By using a terminal attached to an unused serial port, you can log in and run any text program that you would normally run on the console or in an `xterm` window in the X Window System.
354
355
356
357 For the business user, you can attach many terminals to a DragonFly system and place them on your employees' desktops. For a home user, a spare computer such as an older IBM PC or a Macintosh® can be a terminal wired into a more powerful computer running DragonFly. You can turn what might otherwise be a single-user computer into a powerful multiple user system.
358
359
360
361 For DragonFly, there are three kinds of terminals:
362
363
364 * [ Dumb terminals](term.html#TERM-DUMB)
365
366
367 * [ PCs acting as terminals](term.html#TERM-PCS)
368
369
370 * [ X terminals](term.html#TERM-X)
371
372
373 The remaining subsections describe each kind.
374
375
376
377 #### 18.2.1.1 Dumb Terminals 
378
379
380
381 Dumb terminals are specialized pieces of hardware that let you connect to computers over serial lines. They are called ***dumb*** because they have only enough computational power to display, send, and receive text. You cannot run any programs on them. It is the computer to which you connect them that has all the power to run text editors, compilers, email, games, and so forth.
382
383
384
385 There are hundreds of kinds of dumb terminals made by many manufacturers, including Digital Equipment Corporation's VT-100 and Wyse's WY-75. Just about any kind will work with DragonFly. Some high-end terminals can even display graphics, but only certain software packages can take advantage of these advanced features.
386
387
388
389 Dumb terminals are popular in work environments where workers do not need access to graphical applications such as those provided by the X Window System.
390
391
392
393 #### 18.2.1.2 PCs Acting as Terminals 
394
395
396
397 If a [ dumb terminal](term.html#TERM-DUMB) has just enough ability to display, send, and receive text, then certainly any spare personal computer can be a dumb terminal. All you need is the proper cable and some ***terminal emulation*** software to run on the computer.
398
399
400
401 Such a configuration is popular in homes. For example, if your spouse is busy working on your DragonFly system's console, you can do some text-only work at the same time from a less powerful personal computer hooked up as a terminal to the DragonFly system.
402
403
404
405 #### 18.2.1.3 X Terminals 
406
407
408
409 X terminals are the most sophisticated kind of terminal available. Instead of connecting to a serial port, they usually connect to a network like Ethernet. Instead of being relegated to text-only applications, they can display any X application.
410
411
412
413 We introduce X terminals just for the sake of completeness. However, this chapter does ***not*** cover setup, configuration, or use of X terminals.
414
415
416
417 ### 18.2.2 Configuration 
418
419
420
421 This section describes what you need to configure on your DragonFly system to enable a login session on a terminal. It assumes you have already configured your kernel to support the serial port to which the terminal is connected--and that you have connected it.
422
423
424
425 Recall from [boot.html Chapter 7] that the `init` process is responsible for all process control and initialization at system startup. One of the tasks performed by `init` is to read the `/etc/ttys` file and start a `getty` process on the available terminals. The `getty` process is responsible for reading a login name and starting the `login` program.
426
427
428
429 Thus, to configure terminals for your DragonFly system the following steps should be taken as `root`:
430
431
432
433   1. Add a line to `/etc/ttys` for the entry in the `/dev` directory for the serial port if it is not already there.
434
435   1. Specify that `/usr/libexec/getty` be run on the port, and specify the appropriate `***getty***` type from the `/etc/gettytab` file.
436
437   1. Specify the default terminal type.
438
439   1. Set the port to ***on.***
440
441   1. Specify whether the port should be ***secure.***
442
443   1. Force `init` to reread the `/etc/ttys` file.
444
445
446
447 As an optional step, you may wish to create a custom `***getty***` type for use in step 2 by making an entry in `/etc/gettytab`. This chapter does not explain how to do so; you are encouraged to see the [gettytab(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#gettytab&section5) and the [getty(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=getty&section=8) manual pages for more information.
448
449
450
451 #### 18.2.2.1 Adding an Entry to `/etc/ttys` 
452
453
454
455 The `/etc/ttys` file lists all of the ports on your DragonFly system where you want to allow logins. For example, the first virtual console `ttyv0` has an entry in this file. You can log in on the console using this entry. This file also contains entries for the other virtual consoles, serial ports, and pseudo-ttys. For a hardwired terminal, just list the serial port's `/dev` entry without the `/dev` part (for example, `/dev/ttyv0` would be listed as `ttyv0`).
456
457
458
459 A default DragonFly install includes an `/etc/ttys` file with support for the first four serial ports: `ttyd0` through `ttyd3`. If you are attaching a terminal to one of those ports, you do not need to add another entry.
460
461
462
463  **Example 17-1. Adding Terminal Entries to `/etc/ttys`** 
464
465
466
467 Suppose we would like to connect two terminals to the system: a Wyse-50 and an old 286 IBM PC running  **Procomm**  terminal software emulating a VT-100 terminal. We connect the Wyse to the second serial port and the 286 to the sixth serial port (a port on a multiport serial card). The corresponding entries in the `/etc/ttys` file would look like this:
468
469
470
471     
472
473     ttyd1./imagelib/callouts/1.png  "/usr/libexec/getty std.38400"./imagelib/callouts/2.png  wy50./imagelib/callouts/3.png  on./imagelib/callouts/4.png  insecure./imagelib/callouts/5.png
474
475     ttyd5   "/usr/libexec/getty std.19200"  vt100  on  insecure
476
477     
478
479
480
481
482
483 [ ./imagelib/callouts/1.png](term.html#CO-TTYS-LINE1COL1):: The first field normally specifies the name of the terminal special file as it is found in `/dev`.[ ./imagelib/callouts/2.png](term.html#CO-TTYS-LINE1COL2):: The second field is the command to execute for this line, which is usually [getty(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#getty&section8). `getty` initializes and opens the line, sets the speed, prompts for a user name and then executes the [login(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=login&section=1) program.The `getty` program accepts one (optional) parameter on its command line, the `***getty***` type. A `***getty***` type configures characteristics on the terminal line, like bps rate and parity. The `getty` program reads these characteristics from the file `/etc/gettytab`.The file `/etc/gettytab` contains lots of entries for terminal lines both old and new. In almost all cases, the entries that start with the text `std` will work for hardwired terminals. These entries ignore parity. There is a `std` entry for each bps rate from 110 to 115200. Of course, you can add your own entries to this file. The [gettytab(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=gettytab&section=5) manual page provides more information.When setting the `***getty***` type in the `/etc/ttys` file, make sure that the communications settings on the terminal match.For our example, the Wyse-50 uses no parity and connects at 38400 bps. The 286 PC uses no parity and connects at 19200 bps.[ ./imagelib/callouts/3.png](term.html#CO-TTYS-LINE1COL3):: The third field is the type of terminal usually connected to that tty line. For dial-up ports, `unknown` or `dialup` is typically used in this field since users may dial up with practically any type of terminal or software. For hardwired terminals, the terminal type does not change, so you can put a real terminal type from the [termcap(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=termcap&section=5) database file in this field.For our example, the Wyse-50 uses the real terminal type while the 286 PC running  **Procomm**  will be set to emulate at VT-100.[ ./imagelib/callouts/4.png](term.html#CO-TTYS-LINE1COL4):: The fourth field specifies if the port should be enabled. Putting `on` here will have the `init` process start the program in the second field, `getty`. If you put `off` in this field, there will be no `getty`, and hence no logins on the port.[ ./imagelib/callouts/5.png](term.html#CO-TTYS-LINE1COL5):: The final field is used to specify whether the port is secure. Marking a port as secure means that you trust it enough to allow the `root` account (or any account with a user ID of 0) to login from that port. Insecure ports do not allow `root` logins. On an insecure port, users must login from unprivileged accounts and then use [su(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=su&section=1) or a similar mechanism to gain superuser privileges.It is highly recommended that you use ***insecure*** even for terminals that are behind locked doors. It is quite easy to login and use `su` if you need superuser privileges.
484
485
486
487 #### 18.2.2.2 Force `init` to Reread `/etc/ttys` 
488
489
490
491 After making the necessary changes to the `/etc/ttys` file you should send a SIGHUP (hangup) signal to the `init` process to force it to re-read its configuration file. For example:
492
493
494
495     
496
497     # kill -HUP 1
498
499
500
501
502
503  **Note:** `init` is always the first process run on a system, therefore it will always have PID 1.
504
505
506
507 If everything is set up correctly, all cables are in place, and the terminals are powered up, then a `getty` process should be running on each terminal and you should see login prompts on your terminals at this point.
508
509
510
511 ### 18.2.3 Troubleshooting Your Connection 
512
513
514
515 Even with the most meticulous attention to detail, something could still go wrong while setting up a terminal. Here is a list of symptoms and some suggested fixes.
516
517
518
519 #### 18.2.3.1 No Login Prompt Appears 
520
521
522
523 Make sure the terminal is plugged in and powered up. If it is a personal computer acting as a terminal, make sure it is running terminal emulation software on the correct serial port.
524
525
526
527 Make sure the cable is connected firmly to both the terminal and the DragonFly computer. Make sure it is the right kind of cable.
528
529
530
531 Make sure the terminal and DragonFly agree on the bps rate and parity settings. If you have a video display terminal, make sure the contrast and brightness controls are turned up. If it is a printing terminal, make sure paper and ink are in good supply.
532
533
534
535 Make sure that a `getty` process is running and serving the terminal. For example, to get a list of running `getty` processes with `ps`, type:
536
537
538
539     
540
541     # ps -axww|grep getty
542
543
544
545
546
547 You should see an entry for the terminal. For example, the following display shows that a `getty` is running on the second serial port `ttyd1` and is using the `std.38400` entry in `/etc/gettytab`:
548
549
550
551     
552
553     22189  d1  Is+    0:00.03 /usr/libexec/getty std.38400 ttyd1
554
555
556
557
558
559 If no `getty` process is running, make sure you have enabled the port in `/etc/ttys`. Also remember to run `kill -HUP 1` after modifying the `ttys` file.
560
561
562
563 If the `getty` process is running but the terminal still does not display a login prompt, or if it displays a prompt but will not allow you to type, your terminal or cable may not support hardware handshaking. Try changing the entry in `/etc/ttys` from `std.38400` to `3wire.38400` remember to run `kill -HUP 1` after modifying `/etc/ttys`). The `3wire` entry is similar to `std`, but ignores hardware handshaking. You may need to reduce the baud rate or enable software flow control when using `3wire` to prevent buffer overflows.
564
565
566
567 #### 18.2.3.2 If Garbage Appears Instead of a Login Prompt 
568
569
570 Make sure the terminal and DragonFly agree on the bps rate and parity settings. Check the `getty` processes to make sure the correct `***getty***` type is in use. If not, edit `/etc/ttys` and run `kill -HUP 1`.
571
572
573
574 #### 18.2.3.3 Characters Appear Doubled, the Password Appears When Typed 
575
576
577
578 Switch the terminal (or the terminal emulation software) from ***half duplex*** or ***local echo*** to ***full duplex.***
579
580 ***
581
582 ## 18.3 Dial-in Service 
583
584
585 Configuring your DragonFly system for dial-in service is very similar to connecting terminals except that you are dealing with modems instead of terminals.
586
587
588
589 ### 18.3.1 External vs. Internal Modems 
590
591
592
593 External modems seem to be more convenient for dial-up, because external modems often can be semi-permanently configured via parameters stored in non-volatile RAM and they usually provide lighted indicators that display the state of important RS-232 signals. Blinking lights impress visitors, but lights are also very useful to see whether a modem is operating properly.
594
595
596
597 Internal modems usually lack non-volatile RAM, so their configuration may be limited only to setting DIP switches. If your internal modem has any signal indicator lights, it is probably difficult to view the lights when the system's cover is in place.
598
599
600
601 #### 18.3.1.1 Modems and Cables 
602
603
604
605 If you are using an external modem, then you will of course need the proper cable. A standard RS-232C serial cable should suffice as long as all of the normal signals are wired:
606
607
608
609
610 * Transmitted Data (SD)
611
612
613 * Received Data (RD)
614
615
616 * Request to Send (RTS)
617
618
619 * Clear to Send (CTS)
620
621
622 * Data Set Ready (DSR)
623
624
625 * Data Terminal Ready (DTR)
626
627
628 * Carrier Detect (CD)
629
630
631 * Signal Ground (SG)
632
633
634
635 DragonFly needs the RTS and CTS signals for flow-control at speeds above 2400 bps, the CD signal to detect when a call has been answered or the line has been hung up, and the DTR signal to reset the modem after a session is complete. Some cables are wired without all of the needed signals, so if you have problems, such as a login session not going away when the line hangs up, you may have a problem with your cable.
636
637
638
639 Like other UNIX® like operating systems, DragonFly uses the hardware signals to find out when a call has been answered or a line has been hung up and to hangup and reset the modem after a call. DragonFly avoids sending commands to the modem or watching for status reports from the modem. If you are familiar with connecting modems to PC-based bulletin board systems, this may seem awkward.
640
641
642
643 ### 18.3.2 Serial Interface Considerations 
644
645
646
647 DragonFly supports NS8250-, NS16450-, NS16550-, and NS16550A-based EIA RS-232C (CCITT V.24) communications interfaces. The 8250 and 16450 devices have single-character buffers. The 16550 device provides a 16-character buffer, which allows for better system performance. (Bugs in plain 16550's prevent the use of the 16-character buffer, so use 16550A's if possible). Because single-character-buffer devices require more work by the operating system than the 16-character-buffer devices, 16550A-based serial interface cards are much preferred. If the system has many active serial ports or will have a heavy load, 16550A-based cards are better for low-error-rate communications.
648
649
650
651 ### 18.3.3 Quick Overview 
652
653
654
655 As with terminals, `init` spawns a `getty` process for each configured serial port for dial-in connections. For example, if a modem is attached to `/dev/ttyd0`, the command `ps ax` might show this:
656
657
658
659     
660
661      4850 ??  I      0:00.09 /usr/libexec/getty V19200 ttyd0
662
663
664
665
666
667 When a user dials the modem's line and the modems connect, the CD (Carrier Detect) line is reported by the modem. The kernel notices that carrier has been detected and completes `getty`'s open of the port. `getty` sends a login: prompt at the specified initial line speed. `getty` watches to see if legitimate characters are received, and, in a typical configuration, if it finds junk (probably due to the modem's connection speed being different than `getty`'s speed), `getty` tries adjusting the line speeds until it receives reasonable characters.
668
669
670
671 After the user enters his/her login name, `getty` executes `/usr/bin/login`, which completes the login by asking for the user's password and then starting the user's shell.
672
673
674
675 ### 18.3.4 Configuration Files 
676
677
678
679 There are three system configuration files in the `/etc` directory that you will probably need to edit to allow dial-up access to your DragonFly system. The first, `/etc/gettytab`, contains configuration information for the `/usr/libexec/getty` daemon. Second, `/etc/ttys` holds information that tells `/sbin/init` what `tty` devices should have `getty` processes running on them. Lastly, you can place port initialization commands in the `/etc/rc.serial` script.
680
681
682
683 There are two schools of thought regarding dial-up modems on UNIX. One group likes to configure their modems and systems so that no matter at what speed a remote user dials in, the local computer-to-modem RS-232 interface runs at a locked speed. The benefit of this configuration is that the remote user always sees a system login prompt immediately. The downside is that the system does not know what a user's true data rate is, so full-screen programs like Emacs will not adjust their screen-painting methods to make their response better for slower connections.
684
685
686
687 The other school configures their modems' RS-232 interface to vary its speed based on the remote user's connection speed. For example, V.32bis (14.4 Kbps) connections to the modem might make the modem run its RS-232 interface at 19.2 Kbps, while 2400 bps connections make the modem's RS-232 interface run at 2400 bps. Because `getty` does not understand any particular modem's connection speed reporting, `getty` gives a login: message at an initial speed and watches the characters that come back in response. If the user sees junk, it is assumed that they know they should press the Enter key until they see a recognizable prompt. If the data rates do not match, `getty` sees anything the user types as ***junk***, tries going to the next speed and gives the login: prompt again. This procedure can continue ad nauseam, but normally only takes a keystroke or two before the user sees a good prompt. Obviously, this login sequence does not look as clean as the former ***locked-speed*** method, but a user on a low-speed connection should receive better interactive response from full-screen programs.
688
689
690
691 This section will try to give balanced configuration information, but is biased towards having the modem's data rate follow the connection rate.
692
693
694
695 #### 18.3.4.1 `/etc/gettytab` 
696
697
698
699 `/etc/gettytab` is a [termcap(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#termcap&section5)-style file of configuration information for [getty(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=getty&section=8). Please see the [gettytab(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=gettytab&section=5) manual page for complete information on the format of the file and the list of capabilities.
700
701
702
703 ##### 18.3.4.1.1 Locked-speed Config 
704
705
706
707 If you are locking your modem's data communications rate at a particular speed, you probably will not need to make any changes to `/etc/gettytab`.
708
709
710
711 ##### 18.3.4.1.2 Matching-speed Config 
712
713
714
715 You will need to set up an entry in `/etc/gettytab` to give `getty` information about the speeds you wish to use for your modem. If you have a 2400 bps modem, you can probably use the existing `D2400` entry.
716
717
718
719     
720
721     #
722
723     # Fast dialup terminals, 2400/1200/300 rotary (can start either way)
724
725     #
726
727     D2400|d2400|Fast-Dial-2400:\
728
729             :nx#D1200:tc2400-baud:
730
731     3|D1200|Fast-Dial-1200:\
732
733             :nx#D300:tc1200-baud:
734
735     5|D300|Fast-Dial-300:\
736
737             :nx#D2400:tc300-baud:
738
739
740
741
742
743 If you have a higher speed modem, you will probably need to add an entry in `/etc/gettytab`; here is an entry you could use for a 14.4 Kbps modem with a top interface speed of 19.2 Kbps:
744
745
746
747     
748
749     #
750
751     # Additions for a V.32bis Modem
752
753     #
754
755     um|V300|High Speed Modem at 300,8-bit:\
756
757             :nx#V19200:tcstd.300:
758
759     un|V1200|High Speed Modem at 1200,8-bit:\
760
761             :nx#V300:tcstd.1200:
762
763     uo|V2400|High Speed Modem at 2400,8-bit:\
764
765             :nx#V1200:tcstd.2400:
766
767     up|V9600|High Speed Modem at 9600,8-bit:\
768
769             :nx#V2400:tcstd.9600:
770
771     uq|V19200|High Speed Modem at 19200,8-bit:\
772
773             :nx#V9600:tcstd.19200:
774
775
776
777
778
779 This will result in 8-bit, no parity connections.
780
781
782
783 The example above starts the communications rate at 19.2 Kbps (for a V.32bis connection), then cycles through 9600 bps (for V.32), 2400 bps, 1200 bps, 300 bps, and back to 19.2 Kbps. Communications rate cycling is implemented with the `nx#` (***next table***) capability. Each of the lines uses a `tc` (***table continuation***) entry to pick up the rest of the ***standard*** settings for a particular data rate.
784
785
786
787 If you have a 28.8 Kbps modem and/or you want to take advantage of compression on a 14.4 Kbps modem, you need to use a higher communications rate than 19.2 Kbps. Here is an example of a `gettytab` entry starting a 57.6 Kbps:
788
789
790
791     
792
793     #
794
795     # Additions for a V.32bis or V.34 Modem
796
797     # Starting at 57.6 Kbps
798
799     #
800
801     vm|VH300|Very High Speed Modem at 300,8-bit:\
802
803             :nx#VH57600:tcstd.300:
804
805     vn|VH1200|Very High Speed Modem at 1200,8-bit:\
806
807             :nx#VH300:tcstd.1200:
808
809     vo|VH2400|Very High Speed Modem at 2400,8-bit:\
810
811             :nx#VH1200:tcstd.2400:
812
813     vp|VH9600|Very High Speed Modem at 9600,8-bit:\
814
815             :nx#VH2400:tcstd.9600:
816
817     vq|VH57600|Very High Speed Modem at 57600,8-bit:\
818
819             :nx#VH9600:tcstd.57600:
820
821
822
823
824
825 If you have a slow CPU or a heavily loaded system and do not have 16550A-based serial ports, you may receive ***`sio`*** ***silo*** errors at 57.6 Kbps.
826
827
828
829 #### 18.3.4.2 `/etc/ttys` 
830
831
832
833 Configuration of the `/etc/ttys` file was covered in [ Example 17-1](term.html#EX-ETC-TTYS). Configuration for modems is similar but we must pass a different argument to `getty` and specify a different terminal type. The general format for both locked-speed and matching-speed configurations is:
834
835
836
837     
838
839     ttyd0   "/usr/libexec/getty `***xxx***`"   dialup on
840
841
842
843
844
845 The first item in the above line is the device special file for this entry -- `ttyd0` means `/dev/ttyd0` is the file that this `getty` will be watching. The second item, `"/usr/libexec/getty `***xxx***`"` (`***xxx***` will be replaced by the initial `gettytab` capability) is the process `init` will run on the device. The third item, `dialup`, is the default terminal type. The fourth parameter, `on`, indicates to `init` that the line is operational. There can be a fifth parameter, `secure`, but it should only be used for terminals which are physically secure (such as the system console).
846
847
848
849 The default terminal type (`dialup` in the example above) may depend on local preferences. `dialup` is the traditional default terminal type on dial-up lines so that users may customize their login scripts to notice when the terminal is `dialup` and automatically adjust their terminal type. However, the author finds it easier at his site to specify `vt102` as the default terminal type, since the users just use VT102 emulation on their remote systems.
850
851
852
853 After you have made changes to `/etc/ttys`, you may send the `init` process a HUP signal to re-read the file. You can use the command
854
855
856
857     
858
859     # kill -HUP 1
860
861
862
863
864
865  to send the signal. If this is your first time setting up the system, you may want to wait until your modem(s) are properly configured and connected before signaling `init`.
866
867
868
869 ##### 18.3.4.2.1 Locked-speed Config 
870
871
872
873 For a locked-speed configuration, your `ttys` entry needs to have a fixed-speed entry provided to `getty`. For a modem whose port speed is locked at 19.2 Kbps, the `ttys` entry might look like this:
874
875
876
877     
878
879     ttyd0   "/usr/libexec/getty std.19200"   dialup on
880
881
882
883
884
885 If your modem is locked at a different data rate, substitute the appropriate value for `std.`***speed****** instead of `std.19200`. Make sure that you use a valid type listed in `/etc/gettytab`.
886
887
888
889 ##### 18.3.4.2.2 Matching-speed Config 
890
891
892
893 In a matching-speed configuration, your `ttys` entry needs to reference the appropriate beginning ***auto-baud*** (sic) entry in `/etc/gettytab`. For example, if you added the above suggested entry for a matching-speed modem that starts at 19.2 Kbps (the `gettytab` entry containing the `V19200` starting point), your `ttys` entry might look like this:
894
895
896
897     
898
899     ttyd0   "/usr/libexec/getty V19200"   dialup on
900
901
902
903
904
905 #### 18.3.4.3 `/etc/rc.serial` 
906
907
908
909 High-speed modems, like V.32, V.32bis, and V.34 modems, need to use hardware (`RTS/CTS`) flow control. You can add `stty` commands to `/etc/rc.serial` to set the hardware flow control flag in the DragonFly kernel for the modem ports.
910
911
912
913 For example to set the `termios` flag `crtscts` on serial port #1's (`COM2`) dial-in and dial-out initialization devices, the following lines could be added to `/etc/rc.serial`:
914
915
916
917     
918
919     # Serial port initial configuration
920
921     stty -f /dev/ttyid1 crtscts
922
923     stty -f /dev/cuaia1 crtscts
924
925
926
927
928
929 ### 18.3.5 Modem Settings 
930
931
932
933 If you have a modem whose parameters may be permanently set in non-volatile RAM, you will need to use a terminal program (such as Telix under MS-DOS® or `tip` under DragonFly) to set the parameters. Connect to the modem using the same communications speed as the initial speed `getty` will use and configure the modem's non-volatile RAM to match these requirements:
934
935
936
937
938 * CD asserted when connected
939
940
941 * DTR asserted for operation; dropping DTR hangs up line and resets modem
942
943
944 * CTS transmitted data flow control
945
946
947 * Disable XON/XOFF flow control
948
949
950 * RTS received data flow control
951
952
953 * Quiet mode (no result codes)
954
955
956 * No command echo
957
958
959
960 Please read the documentation for your modem to find out what commands and/or DIP switch settings you need to give it.
961
962
963
964 For example, to set the above parameters on a U.S. Robotics® Sportster® 14,400 external modem, one could give these commands to the modem:
965
966
967
968     
969
970     ATZ
971
972     AT&C1&D2&H1&I0&R2&W
973
974
975
976
977
978 You might also want to take this opportunity to adjust other settings in the modem, such as whether it will use V.42bis and/or MNP5 compression.
979
980
981
982 The U.S. Robotics Sportster 14,400 external modem also has some DIP switches that need to be set; for other modems, perhaps you can use these settings as an example:
983
984
985
986
987 * Switch 1: UP -- DTR Normal
988
989
990 * Switch 2: N/A (Verbal Result Codes/Numeric Result Codes)
991
992
993 * Switch 3: UP -- Suppress Result Codes
994
995
996 * Switch 4: DOWN -- No echo, offline commands
997
998
999 * Switch 5: UP -- Auto Answer
1000
1001
1002 * Switch 6: UP -- Carrier Detect Normal
1003
1004
1005 * Switch 7: UP -- Load NVRAM Defaults
1006
1007
1008 * Switch 8: N/A (Smart Mode/Dumb Mode)
1009
1010
1011
1012 Result codes should be disabled/suppressed for dial-up modems to avoid problems that can occur if `getty` mistakenly gives a login: prompt to a modem that is in command mode and the modem echoes the command or returns a result code. This sequence can result in a extended, silly conversation between `getty` and the modem.
1013
1014
1015
1016 #### 18.3.5.1 Locked-speed Config 
1017
1018
1019
1020 For a locked-speed configuration, you will need to configure the modem to maintain a constant modem-to-computer data rate independent of the communications rate. On a U.S. Robotics Sportster 14,400 external modem, these commands will lock the modem-to-computer data rate at the speed used to issue the commands:
1021
1022
1023
1024     
1025
1026     ATZ
1027
1028     AT&B1&W
1029
1030
1031
1032
1033
1034 #### 18.3.5.2 Matching-speed Config 
1035
1036
1037
1038 For a variable-speed configuration, you will need to configure your modem to adjust its serial port data rate to match the incoming call rate. On a U.S. Robotics Sportster 14,400 external modem, these commands will lock the modem's error-corrected data rate to the speed used to issue the commands, but allow the serial port rate to vary for non-error-corrected connections:
1039     
1040
1041     ATZ
1042
1043     AT&B2&W
1044
1045
1046 #### 18.3.5.3 Checking the Modem's Configuration 
1047
1048
1049
1050 Most high-speed modems provide commands to view the modem's current operating parameters in a somewhat human-readable fashion. On the U.S. Robotics Sportster 14,400 external modems, the command `ATI5` displays the settings that are stored in the non-volatile RAM. To see the true operating parameters of the modem (as influenced by the modem's DIP switch settings), use the commands `ATZ` and then `ATI4`.
1051
1052
1053
1054 If you have a different brand of modem, check your modem's manual to see how to double-check your modem's configuration parameters.
1055
1056
1057
1058 ### 18.3.6 Troubleshooting 
1059
1060
1061
1062 Here are a few steps you can follow to check out the dial-up modem on your system.
1063
1064
1065
1066 #### 18.3.6.1 Checking Out the DragonFly System 
1067
1068
1069
1070 Hook up your modem to your DragonFly system, boot the system, and, if your modem has status indication lights, watch to see whether the modem's DTR indicator lights when the login: prompt appears on the system's console -- if it lights up, that should mean that DragonFly has started a `getty` process on the appropriate communications port and is waiting for the modem to accept a call.
1071
1072
1073
1074 If the DTR indicator does not light, login to the DragonFly system through the console and issue a `ps ax` to see if DragonFly is trying to run a `getty` process on the correct port. You should see lines like these among the processes displayed:
1075
1076
1077
1078     
1079
1080       114 ??  I      0:00.10 /usr/libexec/getty V19200 ttyd0
1081
1082       115 ??  I      0:00.10 /usr/libexec/getty V19200 ttyd1
1083
1084
1085
1086
1087 If you see something different, like this:
1088
1089
1090     
1091
1092       114 d0  I      0:00.10 /usr/libexec/getty V19200 ttyd0
1093
1094
1095
1096
1097
1098 and the modem has not accepted a call yet, this means that `getty` has completed its open on the communications port. This could indicate a problem with the cabling or a mis-configured modem, because `getty` should not be able to open the communications port until CD (carrier detect) has been asserted by the modem.
1099
1100
1101
1102 If you do not see any `getty` processes waiting to open the desired `ttyd`***N****** port, double-check your entries in `/etc/ttys` to see if there are any mistakes there. Also, check the log file `/var/log/messages` to see if there are any log messages from `init` or `getty` regarding any problems. If there are any messages, triple-check the configuration files `/etc/ttys` and `/etc/gettytab`, as well as the appropriate device special files `/dev/ttydN`, for any mistakes, missing entries, or missing device special files.
1103
1104
1105
1106 #### 18.3.6.2 Try Dialing In 
1107
1108
1109
1110 Try dialing into the system; be sure to use 8 bits, no parity, and 1 stop bit on the remote system. If you do not get a prompt right away, or get garbage, try pressing Enter about once per second. If you still do not see a login: prompt after a while, try sending a `BREAK`. If you are using a high-speed modem to do the dialing, try dialing again after locking the dialing modem's interface speed (via `AT&B1` on a U.S. Robotics Sportster modem, for example).
1111
1112
1113 If you still cannot get a login: prompt, check `/etc/gettytab` again and double-check that
1114
1115
1116
1117 * The initial capability name specified in `/etc/ttys` for the line matches a name of a capability in `/etc/gettytab`
1118
1119
1120 * Each `nx=` entry matches another `gettytab` capability name
1121
1122
1123 * Each `tc=` entry matches another `gettytab` capability name
1124
1125
1126 If you dial but the modem on the DragonFly system will not answer, make sure that the modem is configured to answer the phone when DTR is asserted. If the modem seems to be configured correctly, verify that the DTR line is asserted by checking the modem's indicator lights (if it has any).
1127
1128
1129
1130 If you have gone over everything several times and it still does not work, take a break and come back to it later. If it still does not work, perhaps you can send an electronic mail message to the [DragonFly User related mailing list](http://leaf.dragonflybsd.org/mailarchive/) describing your modem and your problem, and the good folks on the list will try to help.
1131
1132 ***