(no commit message)
[ikiwiki.git] / docs / docs / newhandbook / serial_communications / index.mdwn
1 ## Chapter 18 Serial Communications 
2 [[!toc  levels=3]]
3
4 ***Reorganized, and parts rewritten by Ivailo Mladenov. ***
5
6 ## Synopsis 
7
8
9 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.
10
11
12
13 After reading this chapter, you will know:
14
15
16
17
18 * How to connect terminals to your DragonFly system.
19
20
21 * How to use a modem to dial out to remote hosts.
22
23
24 * How to allow remote users to login to your system with a modem.
25
26
27 * How to boot your system from a serial console.
28
29
30
31 Before reading this chapter, you should:
32
33
34
35
36 * Know how to configure and install a new kernel ([kernelconfig.html Chapter 10]).
37
38
39 * Understand UNIX permissions and processes ([basics.html Chapter 3]).
40
41
42 * Have access to the technical manual for the serial hardware (modem or multi-port card) that you would like to use with DragonFly.
43
44
45 ***
46
47
48 ## 18.1 Introduction 
49
50
51
52 ### 18.1.1 Terminology 
53
54
55
56 bps:: Bits per Second -- the rate at which data is transmitted;
57
58 DTE:: Data Terminal Equipment -- for example, your computer;
59
60 DCE:: Data Communications Equipment -- your modem;
61
62 RS-232:: EIA standard for hardware serial communications.
63
64
65
66 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).
67
68
69
70 ### 18.1.2 Cables and Ports 
71
72
73
74 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.
75
76
77
78 #### 18.1.2.1 Cables 
79
80
81
82 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.
83
84
85
86 ##### 18.1.2.1.1 Null-modem Cables 
87
88
89
90 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.
91
92
93
94 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.
95
96
97
98 [[!table  data="""
99 | Signal | Pin # |  | Pin # | Signal 
100  SG | 7 | connects to | 7 | SG 
101  TxD | 2 | connects to | 3 | RxD 
102  RxD | 3 | connects to | 2 | TxD 
103  RTS | 4 | connects to | 5 | CTS 
104  CTS | 5 | connects to | 4 | RTS 
105  DTR | 20 | connects to | 6 | DSR 
106  DCD | 8 |  | 6 | DSR 
107  DSR | 6 | connects to | 20 | DTR |
108
109 """]]
110
111  **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.
112
113
114
115 ##### 18.1.2.1.2 Standard RS-232C Cables 
116
117
118
119 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.
120
121
122
123 #### 18.1.2.2 Ports 
124
125
126
127 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.
128
129
130
131 ##### 18.1.2.2.1 Kinds of Ports 
132
133
134
135 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.
136
137
138
139 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.
140
141
142
143 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.
144
145
146
147 ##### 18.1.2.2.2 Port Names 
148
149
150
151 In DragonFly, you access each serial port through an entry in the `/dev` directory. There are two different kinds of entries:
152
153
154
155
156 * 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.
157
158
159 * 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.
160
161
162
163 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.
164
165
166
167 ### 18.1.3 Kernel Configuration 
168
169
170
171 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.
172
173
174
175 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`.
176
177
178
179  **Tip:** To view just the messages that have the word `sio`, use the command:
180
181
182
183     
184
185     # /sbin/dmesg | grep 'sio'
186
187
188
189
190
191 For example, on a system with four serial ports, these are the serial-port specific kernel boot messages:
192
193
194
195     
196
197     sio0 at 0x3f8-0x3ff irq 4 on isa
198
199     sio0: type 16550A
200
201     sio1 at 0x2f8-0x2ff irq 3 on isa
202
203     sio1: type 16550A
204
205     sio2 at 0x3e8-0x3ef irq 5 on isa
206
207     sio2: type 16550A
208
209     sio3 at 0x2e8-0x2ef irq 9 on isa
210
211     sio3: type 16550A
212
213
214
215
216
217 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 12].
218
219
220
221 The relevant device lines for your kernel configuration file would look like this:
222
223
224
225     
226
227     device              sio0    at isa? port IO_COM1 irq 4
228
229     device              sio1    at isa? port IO_COM2 irq 3
230
231     device              sio2    at isa? port IO_COM3 irq 5
232
233     device              sio3    at isa? port IO_COM4 irq 9
234
235
236
237
238
239  **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).
240
241
242
243 ### 18.1.4 Device Special Files 
244
245
246
247 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.
248
249
250
251 #### 18.1.4.1 Making Device Special Files 
252
253
254
255 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`.
256
257
258
259 `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.
260
261
262
263 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:
264
265
266
267     
268
269     crw-rw----    1 uucp     dialer    28, 129 Feb 15 14:38 /dev/cuaa1
270
271     crw-rw----    1 uucp     dialer    28, 161 Feb 15 14:38 /dev/cuaia1
272
273     crw-rw----    1 uucp     dialer    28, 193 Feb 15 14:38 /dev/cuala1
274
275
276
277
278
279 These permissions allow the user `uucp` and users in the group `dialer` to use the call-out devices.
280
281
282
283 ### 18.1.5 Serial Port Configuration 
284
285
286
287 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
288
289
290
291     
292
293     # stty -a -f /dev/ttyd1
294
295
296
297
298
299 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:
300
301
302
303     
304
305     # stty -f /dev/ttyid5 clocal cs8 ixon ixoff
306
307
308
309
310
311 System-wide initialization of the serial devices is controlled in `/etc/rc.serial`. This file affects the default settings of serial devices.
312
313
314
315 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:
316
317
318
319     
320
321     # stty -f /dev/ttyld5 57600
322
323
324
325
326
327 Now, an application that opens `ttyd5` and tries to change the speed of the port will be stuck with 57600 bps.
328
329
330
331 Naturally, you should make the initial state and lock state devices writable only by the `root` account.
332
333 ***
334
335 ## 18.2 Terminals 
336
337
338 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.
339
340
341
342 ### 18.2.1 Uses and Types of Terminals 
343
344
345
346 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.
347
348
349
350 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.
351
352
353
354 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.
355
356
357
358 For DragonFly, there are three kinds of terminals:
359
360
361 * [ Dumb terminals](term.html#TERM-DUMB)
362
363
364 * [ PCs acting as terminals](term.html#TERM-PCS)
365
366
367 * [ X terminals](term.html#TERM-X)
368
369
370
371
372 #### 18.2.1.1 Dumb Terminals 
373
374
375
376 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.
377
378
379
380 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.
381
382
383
384 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.
385
386
387
388 #### 18.2.1.2 PCs Acting as Terminals 
389
390
391
392 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.
393
394
395
396 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.
397
398
399
400 #### 18.2.1.3 X Terminals 
401
402
403
404 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.
405
406
407
408 We introduce X terminals just for the sake of completeness. However, this chapter does ***not*** cover setup, configuration, or use of X terminals.
409
410
411
412 ### 18.2.2 Configuration 
413
414
415
416 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.
417
418
419
420 Recall from [boot.html Chapter 10] 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.
421
422
423
424 Thus, to configure terminals for your DragonFly system the following steps should be taken as `root`:
425
426
427
428   1. Add a line to `/etc/ttys` for the entry in the `/dev` directory for the serial port if it is not already there.
429
430   1. Specify that `/usr/libexec/getty` be run on the port, and specify the appropriate `***getty***` type from the `/etc/gettytab` file.
431
432   1. Specify the default terminal type.
433
434   1. Set the port to ***on.***
435
436   1. Specify whether the port should be ***secure.***
437
438   1. Force `init` to reread the `/etc/ttys` file.
439
440
441
442 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.
443
444
445
446 #### 18.2.2.1 Adding an Entry to `/etc/ttys` 
447
448
449
450 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`).
451
452
453
454 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.
455
456
457
458  **Example 17-1. Adding Terminal Entries to `/etc/ttys`** 
459
460
461
462 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:
463
464
465
466     
467
468     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
469
470     ttyd5   "/usr/libexec/getty std.19200"  vt100  on  insecure
471
472     
473
474
475
476
477
478 [ ./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.
479
480
481
482 #### 18.2.2.2 Force `init` to Reread `/etc/ttys` 
483
484
485
486 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:
487
488
489
490     
491
492     # kill -HUP 1
493
494
495
496
497
498  **Note:** `init` is always the first process run on a system, therefore it will always have PID 1.
499
500
501
502 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.
503
504
505
506 ### 18.2.3 Troubleshooting Your Connection 
507
508
509
510 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.
511
512
513
514 #### 18.2.3.1 No Login Prompt Appears 
515
516
517
518 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.
519
520
521
522 Make sure the cable is connected firmly to both the terminal and the DragonFly computer. Make sure it is the right kind of cable.
523
524
525
526 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.
527
528
529
530 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:
531
532
533
534     
535
536     # ps -axww|grep getty
537
538
539
540
541
542 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`:
543
544
545
546     
547
548     22189  d1  Is+    0:00.03 /usr/libexec/getty std.38400 ttyd1
549
550
551
552
553
554 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.
555
556
557
558 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.
559
560
561
562 #### 18.2.3.2 If Garbage Appears Instead of a Login Prompt 
563
564
565 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`.
566
567
568
569 #### 18.2.3.3 Characters Appear Doubled, the Password Appears When Typed 
570
571
572
573 Switch the terminal (or the terminal emulation software) from ***half duplex*** or ***local echo*** to ***full duplex.***
574
575 ***
576
577 ## 18.3 Dial-in Service 
578
579
580 Configuring your DragonFly system for dial-in service is very similar to connecting terminals except that you are dealing with modems instead of terminals.
581
582
583
584 ### 18.3.1 External vs. Internal Modems 
585
586
587
588 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.
589
590
591
592 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.
593
594
595
596 #### 18.3.1.1 Modems and Cables 
597
598
599
600 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:
601
602
603
604
605 * Transmitted Data (SD)
606
607
608 * Received Data (RD)
609
610
611 * Request to Send (RTS)
612
613
614 * Clear to Send (CTS)
615
616
617 * Data Set Ready (DSR)
618
619
620 * Data Terminal Ready (DTR)
621
622
623 * Carrier Detect (CD)
624
625
626 * Signal Ground (SG)
627
628
629
630 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.
631
632
633
634 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.
635
636
637
638 ### 18.3.2 Serial Interface Considerations 
639
640
641
642 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.
643
644
645
646 ### 18.3.3 Quick Overview 
647
648
649
650 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:
651
652
653
654     
655
656      4850 ??  I      0:00.09 /usr/libexec/getty V19200 ttyd0
657
658
659
660
661
662 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.
663
664
665
666 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.
667
668
669
670 ### 18.3.4 Configuration Files 
671
672
673
674 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.
675
676
677
678 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.
679
680
681
682 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.
683
684
685
686 This section will try to give balanced configuration information, but is biased towards having the modem's data rate follow the connection rate.
687
688
689
690 #### 18.3.4.1 `/etc/gettytab` 
691
692
693
694 `/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.
695
696
697
698 ##### 18.3.4.1.1 Locked-speed Config 
699
700
701
702 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`.
703
704
705
706 ##### 18.3.4.1.2 Matching-speed Config 
707
708
709
710 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.
711
712
713
714     
715
716     #
717
718     # Fast dialup terminals, 2400/1200/300 rotary (can start either way)
719
720     #
721
722     D2400|d2400|Fast-Dial-2400:\
723
724             :nx#D1200:tc2400-baud:
725
726     3|D1200|Fast-Dial-1200:\
727
728             :nx#D300:tc1200-baud:
729
730     5|D300|Fast-Dial-300:\
731
732             :nx#D2400:tc300-baud:
733
734
735
736
737
738 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:
739
740
741
742     
743
744     #
745
746     # Additions for a V.32bis Modem
747
748     #
749
750     um|V300|High Speed Modem at 300,8-bit:\
751
752             :nx#V19200:tcstd.300:
753
754     un|V1200|High Speed Modem at 1200,8-bit:\
755
756             :nx#V300:tcstd.1200:
757
758     uo|V2400|High Speed Modem at 2400,8-bit:\
759
760             :nx#V1200:tcstd.2400:
761
762     up|V9600|High Speed Modem at 9600,8-bit:\
763
764             :nx#V2400:tcstd.9600:
765
766     uq|V19200|High Speed Modem at 19200,8-bit:\
767
768             :nx#V9600:tcstd.19200:
769
770
771
772
773
774 This will result in 8-bit, no parity connections.
775
776
777
778 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.
779
780
781
782 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:
783
784
785
786     
787
788     #
789
790     # Additions for a V.32bis or V.34 Modem
791
792     # Starting at 57.6 Kbps
793
794     #
795
796     vm|VH300|Very High Speed Modem at 300,8-bit:\
797
798             :nx#VH57600:tcstd.300:
799
800     vn|VH1200|Very High Speed Modem at 1200,8-bit:\
801
802             :nx#VH300:tcstd.1200:
803
804     vo|VH2400|Very High Speed Modem at 2400,8-bit:\
805
806             :nx#VH1200:tcstd.2400:
807
808     vp|VH9600|Very High Speed Modem at 9600,8-bit:\
809
810             :nx#VH2400:tcstd.9600:
811
812     vq|VH57600|Very High Speed Modem at 57600,8-bit:\
813
814             :nx#VH9600:tcstd.57600:
815
816
817
818
819
820 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.
821
822
823
824 #### 18.3.4.2 `/etc/ttys` 
825
826
827
828 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:
829
830
831
832     
833
834     ttyd0   "/usr/libexec/getty `***xxx***`"   dialup on
835
836
837
838
839
840 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).
841
842
843
844 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.
845
846
847
848 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
849
850
851
852     
853
854     # kill -HUP 1
855
856
857
858
859
860  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`.
861
862
863
864 ##### 18.3.4.2.1 Locked-speed Config 
865
866
867
868 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:
869
870
871
872     
873
874     ttyd0   "/usr/libexec/getty std.19200"   dialup on
875
876
877
878
879
880 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`.
881
882
883
884 ##### 18.3.4.2.2 Matching-speed Config 
885
886
887
888 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:
889
890
891
892     
893
894     ttyd0   "/usr/libexec/getty V19200"   dialup on
895
896
897
898
899
900 #### 18.3.4.3 `/etc/rc.serial` 
901
902
903
904 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.
905
906
907
908 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`:
909
910
911
912     
913
914     # Serial port initial configuration
915
916     stty -f /dev/ttyid1 crtscts
917
918     stty -f /dev/cuaia1 crtscts
919
920
921
922
923
924 ### 18.3.5 Modem Settings 
925
926
927
928 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:
929
930
931
932
933 * CD asserted when connected
934
935
936 * DTR asserted for operation; dropping DTR hangs up line and resets modem
937
938
939 * CTS transmitted data flow control
940
941
942 * Disable XON/XOFF flow control
943
944
945 * RTS received data flow control
946
947
948 * Quiet mode (no result codes)
949
950
951 * No command echo
952
953
954
955 Please read the documentation for your modem to find out what commands and/or DIP switch settings you need to give it.
956
957
958
959 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:
960
961
962
963     
964
965     ATZ
966
967     AT&C1&D2&H1&I0&R2&W
968
969
970
971
972
973 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.
974
975
976
977 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:
978
979
980
981
982 * Switch 1: UP -- DTR Normal
983
984
985 * Switch 2: N/A (Verbal Result Codes/Numeric Result Codes)
986
987
988 * Switch 3: UP -- Suppress Result Codes
989
990
991 * Switch 4: DOWN -- No echo, offline commands
992
993
994 * Switch 5: UP -- Auto Answer
995
996
997 * Switch 6: UP -- Carrier Detect Normal
998
999
1000 * Switch 7: UP -- Load NVRAM Defaults
1001
1002
1003 * Switch 8: N/A (Smart Mode/Dumb Mode)
1004
1005
1006
1007 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.
1008
1009
1010
1011 #### 18.3.5.1 Locked-speed Config 
1012
1013
1014
1015 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:
1016
1017
1018
1019     
1020
1021     ATZ
1022
1023     AT&B1&W
1024
1025
1026
1027
1028
1029 #### 18.3.5.2 Matching-speed Config 
1030
1031
1032
1033 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:
1034     
1035
1036     ATZ
1037
1038     AT&B2&W
1039
1040
1041 #### 18.3.5.3 Checking the Modem's Configuration 
1042
1043
1044
1045 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`.
1046
1047
1048
1049 If you have a different brand of modem, check your modem's manual to see how to double-check your modem's configuration parameters.
1050
1051
1052
1053 ### 18.3.6 Troubleshooting 
1054
1055
1056
1057 Here are a few steps you can follow to check out the dial-up modem on your system.
1058
1059
1060
1061 #### 18.3.6.1 Checking Out the DragonFly System 
1062
1063
1064
1065 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.
1066
1067
1068
1069 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:
1070
1071
1072
1073     
1074
1075       114 ??  I      0:00.10 /usr/libexec/getty V19200 ttyd0
1076
1077       115 ??  I      0:00.10 /usr/libexec/getty V19200 ttyd1
1078
1079
1080
1081
1082 If you see something different, like this:
1083
1084
1085     
1086
1087       114 d0  I      0:00.10 /usr/libexec/getty V19200 ttyd0
1088
1089
1090
1091
1092
1093 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.
1094
1095
1096
1097 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.
1098
1099
1100 #### 18.3.6.2 Try Dialing In 
1101
1102
1103
1104 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).
1105
1106
1107 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).
1108
1109
1110
1111 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.
1112
1113 ***
1114 ## 18.4 Dial-out Service 
1115
1116
1117
1118 The following are tips for getting your host to be able to connect over the modem to another computer. This is appropriate for establishing a terminal session with a remote host.
1119
1120
1121
1122 This is useful to log onto a BBS.
1123
1124
1125
1126 This kind of connection can be extremely helpful to get a file on the Internet if you have problems with PPP. If you need to FTP something and PPP is broken, use the terminal session to FTP it. Then use zmodem to transfer it to your machine.
1127
1128
1129
1130 ### 18.4.1 My Stock Hayes Modem Is Not Supported, What Can I Do? 
1131
1132
1133
1134 Actually, the manual page for `tip` is out of date. There is a generic Hayes dialer already built in. Just use `at=hayes` in your `/etc/remote` file.
1135
1136
1137
1138 The Hayes driver is not smart enough to recognize some of the advanced features of newer modems--messages like `BUSY`, `NO DIALTONE`, or `CONNECT 115200` will just confuse it. You should turn those messages off when you use `tip` (using `ATX0&W`).
1139
1140
1141
1142 Also, the dial timeout for `tip` is 60 seconds. Your modem should use something less, or else tip will think there is a communication problem. Try `ATS7=45&W`.
1143
1144
1145
1146  **Note:** As shipped, `tip` does not yet support Hayes modems fully. The solution is to edit the file `tipconf.h` in the directory `/usr/src/usr.bin/tip/tip`. Obviously you need the source distribution to do this.
1147
1148
1149
1150 Edit the line `#define HAYES 0` to `#define HAYES 1`. Then `make` and `make install`. Everything works nicely after that.
1151
1152
1153
1154 ### 18.4.2 How Am I Expected to Enter These AT Commands? 
1155
1156
1157
1158 Make what is called a ***direct*** entry in your `/etc/remote` file. For example, if your modem is hooked up to the first serial port, `/dev/cuaa0`, then put in the following line:
1159
1160
1161
1162     
1163
1164     cuaa0:dv#/dev/cuaa0:br#19200:panone
1165
1166
1167
1168
1169
1170 Use the highest bps rate your modem supports in the br capability. Then, type `tip cuaa0` and you will be connected to your modem.
1171
1172
1173
1174 If there is no `/dev/cuaa0` on your system, do this:
1175
1176
1177
1178     
1179
1180     # cd /dev
1181
1182     # sh MAKEDEV cuaa0
1183
1184
1185
1186
1187
1188 Or use `cu` as `root` with the following command:
1189
1190
1191
1192     
1193
1194     # cu -l`***line***` -s`***speed***`
1195
1196
1197
1198
1199
1200 `***line***` is the serial port (e.g.`/dev/cuaa0`) and `***speed***` is the speed (e.g.`57600`). When you are done entering the AT commands hit  **~.**  to exit.
1201
1202
1203
1204 ### 18.4.3 The `@` Sign for the pn Capability Does Not Work! 
1205
1206
1207
1208 The `@` sign in the phone number capability tells tip to look in `/etc/phones` for a phone number. But the `@` sign is also a special character in capability files like `/etc/remote`. Escape it with a backslash:
1209
1210
1211
1212     
1213
1214     pn=\@
1215
1216
1217
1218
1219
1220 ### 18.4.4 How Can I Dial a Phone Number on the Command Line? 
1221
1222
1223
1224 Put what is called a ***generic*** entry in your `/etc/remote` file. For example:
1225
1226
1227
1228     
1229
1230     tip115200|Dial any phone number at 115200 bps:\
1231
1232             :dv#/dev/cuaa0:br#115200:athayes:pa=none:du:
1233
1234     tip57600|Dial any phone number at 57600 bps:\
1235
1236             :dv#/dev/cuaa0:br#57600:athayes:pa=none:du:
1237
1238
1239
1240
1241
1242 Then you can do things like:
1243
1244
1245
1246     
1247
1248     # tip -115200 5551234
1249
1250
1251
1252
1253
1254 If you prefer `cu` over `tip`, use a generic `cu` entry:
1255
1256
1257
1258     
1259
1260     cu115200|Use cu to dial any number at 115200bps:\
1261
1262             :dv#/dev/cuaa1:br#57600:athayes:pa=none:du:
1263
1264
1265
1266
1267
1268 and type:
1269
1270
1271
1272     
1273
1274     # cu 5551234 -s 115200
1275
1276
1277
1278
1279
1280 ### 18.4.5 Do I Have to Type in the bps Rate Every Time I Do That? 
1281
1282
1283
1284 Put in an entry for `tip1200` or `cu1200`, but go ahead and use whatever bps rate is appropriate with the br capability. `tip` thinks a good default is 1200 bps which is why it looks for a `tip1200` entry. You do not have to use 1200 bps, though.
1285
1286
1287
1288 ### 18.4.6 I Access a Number of Hosts Through a Terminal Server 
1289
1290
1291
1292 Rather than waiting until you are connected and typing `CONNECT <host>` each time, use tip's `cm` capability. For example, these entries in `/etc/remote`:
1293
1294
1295
1296     
1297
1298     pain|pain.deep13.com|Forrester's machine:\
1299
1300             :cm#CONNECT pain\n:tcdeep13:
1301
1302     muffin|muffin.deep13.com|Frank's machine:\
1303
1304             :cm#CONNECT muffin\n:tcdeep13:
1305
1306     deep13:Gizmonics Institute terminal server:\
1307
1308             :dv#/dev/cuaa2:br#38400:athayes:du:pa=none:pn=5551234:
1309
1310
1311
1312
1313
1314 will let you type `tip pain` or `tip muffin` to connect to the hosts pain or muffin, and `tip deep13` to get to the terminal server.
1315
1316
1317
1318 ### 18.4.7 Can Tip Try More Than One Line for Each Site? 
1319
1320
1321
1322 This is often a problem where a university has several modem lines and several thousand students trying to use them.
1323
1324
1325
1326 Make an entry for your university in `/etc/remote` and use `@` for the `pn` capability:
1327
1328
1329
1330     
1331
1332     big-university:\
1333
1334             :pn#\@:tcdialout
1335
1336     dialout:\
1337
1338             :dv#/dev/cuaa3:br#9600:atcourier:du:pa=none:
1339
1340
1341
1342
1343
1344 Then, list the phone numbers for the university in `/etc/phones`:
1345
1346
1347
1348     
1349
1350     big-university 5551111
1351
1352     big-university 5551112
1353
1354     big-university 5551113
1355
1356     big-university 5551114
1357
1358
1359
1360
1361
1362 `tip` will try each one in the listed order, then give up. If you want to keep retrying, run `tip` in a while loop.
1363
1364
1365
1366 ### 18.4.8 Why Do I Have to Hit  **Ctrl** + **P**  Twice to Send  **Ctrl** + **P**  Once? 
1367
1368
1369
1370  **Ctrl** + **P**  is the default ***force*** character, used to tell `tip` that the next character is literal data. You can set the force character to any other character with the `~s` escape, which means ***set a variable.***
1371
1372
1373
1374 Type `~sforce=`***single-char****** followed by a newline. `***single-char***` is any single character. If you leave out `***single-char***`, then the force character is the nul character, which you can get by typing  **Ctrl** + **2**  or  **Ctrl** + **Space** . A pretty good value for `***single-char***` is  **Shift** + **Ctrl** + **6** , which is only used on some terminal servers.
1375
1376
1377
1378 You can have the force character be whatever you want by specifying the following in your `$HOME/.tiprc` file:
1379
1380
1381
1382     
1383
1384     force=<single-char>
1385
1386
1387
1388
1389
1390 ### 18.4.9 Suddenly Everything I Type Is in Upper Case?? 
1391
1392
1393
1394 You must have pressed  **Ctrl** + **A** , `tip`'s ***raise character,*** specially designed for people with broken caps-lock keys. Use `~s` as above and set the variable `raisechar` to something reasonable. In fact, you can set it to the same as the force character, if you never expect to use either of these features.
1395
1396
1397
1398 Here is a sample .tiprc file perfect for  **Emacs**  users who need to type  **Ctrl** + **2**  and  **Ctrl** + **A**  a lot:
1399
1400
1401
1402     
1403
1404     force=^^
1405
1406     raisechar=^^
1407
1408
1409
1410
1411
1412 The ^^ is  **Shift** + **Ctrl** + **6** .
1413
1414
1415
1416 ### 18.4.10 How Can I Do File Transfers with `tip`? 
1417
1418
1419 If you are talking to another UNIX® system, you can send and receive files with `~p` (put) and `~t` (take). These commands run `cat` and `echo` on the remote system to accept and send files. The syntax is:
1420
1421
1422
1423 `~p` local-file [remote-file]
1424
1425
1426
1427 `~t` remote-file [local-file]
1428
1429
1430
1431 There is no error checking, so you probably should use another protocol, like zmodem.
1432
1433
1434
1435 ### 18.4.11 How Can I Run zmodem with `tip`? 
1436
1437
1438
1439 To receive files, start the sending program on the remote end. Then, type `~C rz` to begin receiving them locally.
1440
1441
1442
1443 To send files, start the receiving program on the remote end. Then, type `~C sz `***files****** to send them to the remote system.
1444
1445 ***
1446
1447 ## 18.5 Setting Up the Serial Console 
1448
1449
1450 ### 18.5.1 Introduction 
1451
1452
1453
1454 DragonFly has the ability to boot on a system with only a dumb terminal on a serial port as a console. Such a configuration should be useful for two classes of people: system administrators who wish to install DragonFly on machines that have no keyboard or monitor attached, and developers who want to debug the kernel or device drivers.
1455
1456
1457
1458 As described in [boot.html Chapter 10], DragonFly employs a three stage bootstrap. The first two stages are in the boot block code which is stored at the beginning of the DragonFly slice on the boot disk. The boot block will then load and run the boot loader (`/boot/loader`) as the third stage code.
1459
1460
1461
1462 In order to set up the serial console you must configure the boot block code, the boot loader code and the kernel.
1463
1464
1465
1466 ### 18.5.2 Serial Console Configuration, Terse Version 
1467
1468
1469
1470 This section assumes that you are using the default setup, know how to connect serial ports and just want a fast overview of a serial console. If you encounter difficulty with these steps, please see the more extensive explaination of all the options and advanced settings in [serialconsole-setup.html#SERIALCONSOLE-HOWTO Section 18.5.3].
1471
1472
1473
1474   1. Connect the serial port. The serial console will be on COM1.
1475
1476   1. `echo -h > /boot.config` to enable the serial console for the boot loader and kernel.
1477
1478   1. Edit `/etc/ttys` and change `off` to `on` for the `ttyd0` entry. This enables a login prompt on the serial console, which mirrors how video consoles are typically setup.
1479
1480   1. `shutdown -r now` will reboot the system with the serial console.
1481
1482
1483
1484 ### 18.5.3 Serial Console Configuration 
1485
1486
1487
1488   1. Prepare a serial cable.
1489
1490   You will need either a null-modem cable or a standard serial cable and a null-modem adapter. See [ Section 18.1.2](serial.html#SERIAL-CABLES-PORTS) for a discussion on serial cables.
1491
1492   1. Unplug your keyboard.
1493
1494   Most PC systems probe for the keyboard during the Power-On Self-Test (POST) and will generate an error if the keyboard is not detected. Some machines complain loudly about the lack of a keyboard and will not continue to boot until it is plugged in.
1495
1496   If your computer complains about the error, but boots anyway, then you do not have to do anything special. (Some machines with Phoenix BIOS installed merely say ***`Keyboard failed`*** and continue to boot normally.)
1497
1498   If your computer refuses to boot without a keyboard attached then you will have to configure the BIOS so that it ignores this error (if it can). Consult your motherboard's manual for details on how to do this.
1499
1500    **Tip:** Setting the keyboard to ***Not installed*** in the BIOS setup does ***not*** mean that you will not be able to use your keyboard. All this does is tell the BIOS not to probe for a keyboard at power-on, so it will not complain if the keyboard is not plugged in. You can leave the keyboard plugged in even with this flag set to ***Not installed*** and the keyboard will still work.
1501
1502    **Note:** If your system has a PS/2® mouse, chances are very good that you may have to unplug your mouse as well as your keyboard. This is because PS/2 mice share some hardware with the keyboard and leaving the mouse plugged in can fool the keyboard probe into thinking the keyboard is still there. In general, this is not a problem since the mouse is not much good without the keyboard anyway.
1503
1504   1. Plug a dumb terminal into `COM1` (`sio0`).
1505
1506   If you do not have a dumb terminal, you can use an old PC/XT with a modem program, or the serial port on another UNIX® box. If you do not have a `COM1` (`sio0`), get one. At this time, there is no way to select a port other than `COM1` for the boot blocks without recompiling the boot blocks. If you are already using `COM1` for another device, you will have to temporarily remove that device and install a new boot block and kernel once you get DragonFly up and running. (It is assumed that `COM1` will be available on a file/compute/terminal server anyway; if you really need `COM1` for something else (and you cannot switch that something else to `COM2` (`sio1`)), then you probably should not even be bothering with all this in the first place.)
1507
1508   1. Make sure the configuration file of your kernel has appropriate flags set for `COM1` (`sio0`).
1509
1510   Relevant flags are:
1511
1512   `0x10`:: Enables console support for this unit. The other console flags are ignored unless this is set. Currently, at most one unit can have console support; the first one (in config file order) with this flag set is preferred. This option alone will not make the serial port the console. Set the following flag or use the `-h` option described below, together with this flag.`0x20`:: Forces this unit to be the console (unless there is another higher priority console), regardless of the `-h` option discussed below. This flag replaces the `COMCONSOLE` option in DragonFly versions 2.`***X***`. The flag `0x20` must be used together with the `0x10` flag.`0x40`:: Reserves this unit (in conjunction with `0x10`) and makes the unit unavailable for normal access. You should not set this flag to the serial port unit which you want to use as the serial console. This reserves this port for "low-level IO", i.e. kernel debugging.`0x80`:: This port will be used for remote kernel debugging.
1513
1514   Example:
1515
1516       
1517
1518       device sio0 at isa? port IO_COM1 flags 0x10 irq 4
1519
1520   
1521
1522   See the [sio(4)](http://leaf.dragonflybsd.org/cgi/web-man?command#sio&section4) manual page for more details.
1523
1524   If the flags were not set, you need to run UserConfig (on a different console) or recompile the kernel.
1525
1526   1. Create `boot.config` in the root directory of the `a` partition on the boot drive.
1527
1528   This file will instruct the boot block code how you would like to boot the system. In order to activate the serial console, you need one or more of the following options--if you want multiple options, include them all on the same line:
1529
1530   `-h`:: Toggles internal and serial consoles. You can use this to switch console devices. For instance, if you boot from the internal (video) console, you can use `-h` to direct the boot loader and the kernel to use the serial port as its console device. Alternatively, if you boot from the serial port, you can use the `-h` to tell the boot loader and the kernel to use the video display as the console instead.`-D`:: Toggles single and dual console configurations. In the single configuration the console will be either the internal console (video display) or the serial port, depending on the state of the `-h` option above. In the dual console configuration, both the video display and the serial port will become the console at the same time, regardless of the state of the `-h` option. However, note that the dual console configuration takes effect only during the boot block is running. Once the boot loader gets control, the console specified by the `-h` option becomes the only console.`-P`:: Makes the boot block probe the keyboard. If no keyboard is found, the `-D` and `-h` options are automatically set.
1531
1532    **Note:** Due to space constraints in the current version of the boot blocks, the `-P` option is capable of detecting extended keyboards only. Keyboards with less than 101 keys (and without F11 and F12 keys) may not be detected. Keyboards on some laptop computers may not be properly found because of this limitation. If this is the case with your system, you have to abandon using the `-P` option. Unfortunately there is no workaround for this problem.
1533
1534   Use either the `-P` option to select the console automatically, or the `-h` option to activate the serial console.
1535
1536   You may include other options described in [boot(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#boot&section8) as well.
1537
1538   The options, except for `-P`, will be passed to the boot loader (`/boot/loader`). The boot loader will determine which of the internal video or the serial port should become the console by examining the state of the `-h` option alone. This means that if you specify the `-D` option but not the `-h` option in `/boot.config`, you can use the serial port as the console only during the boot block; the boot loader will use the internal video display as the console.
1539
1540   1. Boot the machine.
1541
1542   When you start your DragonFly box, the boot blocks will echo the contents of `/boot.config` to the console. For example:
1543
1544       
1545
1546       /boot.config: -P
1547
1548       Keyboard: no
1549
1550   
1551
1552   The second line appears only if you put `-P` in `/boot.config` and indicates presence/absence of the keyboard. These messages go to either serial or internal console, or both, depending on the option in `/boot.config`.
1553
1554   || Options || Message goes to ||
1555
1556   || none || internal console ||
1557
1558   || `-h` || serial console ||
1559
1560   || `-D` || serial and internal consoles ||
1561
1562   || `-Dh` || serial and internal consoles ||
1563
1564   || `-P`, keyboard present || internal console ||
1565
1566   || `-P`, keyboard absent || serial console ||
1567
1568   After the above messages, there will be a small pause before the boot blocks continue loading the boot loader and before any further messages printed to the console. Under normal circumstances, you do not need to interrupt the boot blocks, but you may want to do so in order to make sure things are set up correctly.
1569
1570   Hit any key, other than Enter, at the console to interrupt the boot process. The boot blocks will then prompt you for further action. You should now see something like:
1571
1572       
1573
1574       >> DragonFly/i386 BOOT
1575
1576       Default: 0:ad(0,a)/boot/loader
1577
1578       boot:
1579
1580   
1581
1582   Verify the above message appears on either the serial or internal console or both, according to the options you put in `/boot.config`. If the message appears in the correct console, hit Enter to continue the boot process.
1583
1584   If you want the serial console but you do not see the prompt on the serial terminal, something is wrong with your settings. In the meantime, you enter `-h` and hit Enter/Return (if possible) to tell the boot block (and then the boot loader and the kernel) to choose the serial port for the console. Once the system is up, go back and check what went wrong.
1585
1586
1587
1588 After the boot loader is loaded and you are in the third stage of the boot process you can still switch between the internal console and the serial console by setting appropriate environment variables in the boot loader. See [serialconsole-setup.html#SERIALCONSOLE-LOADER Section 18.5.6].
1589
1590
1591
1592 ### 18.5.4 Summary 
1593
1594
1595
1596 Here is the summary of various settings discussed in this section and the console eventually selected.
1597
1598
1599
1600 #### 18.5.4.1 Case 1: You Set the Flags to 0x10 for `sio0` 
1601
1602
1603
1604     
1605
1606     device sio0 at isa? port IO_COM1 flags 0x10 irq 4
1607
1608
1609
1610
1611
1612 [[!table  data="""
1613 | Options in /boot.config | Console during boot blocks | Console during boot loader | Console in kernel 
1614  nothing | internal | internal | internal 
1615  `-h` | serial | serial | serial 
1616  `-D` | serial and internal | internal | internal 
1617  `-Dh` | serial and internal | serial | serial 
1618  `-P`, keyboard present | internal | internal | internal 
1619  `-P`, keyboard absent | serial and internal | serial | serial |
1620
1621 """]]
1622
1623 #### 18.5.4.2 Case 2: You Set the Flags to 0x30 for sio0 
1624
1625
1626
1627     
1628
1629     device sio0 at isa? port IO_COM1 flags 0x30 irq 4
1630
1631
1632
1633
1634
1635 [[!table  data="""
1636 | Options in /boot.config | Console during boot blocks | Console during boot loader | Console in kernel 
1637  nothing | internal | internal | serial 
1638  `-h` | serial | serial | serial 
1639  `-D` | serial and internal | internal | serial 
1640  `-Dh` | serial and internal | serial | serial 
1641  `-P`, keyboard present | internal | internal | serial 
1642  `-P`, keyboard absent | serial and internal | serial | serial |
1643
1644 """]]
1645
1646 ### 18.5.5 Tips for the Serial Console 
1647
1648
1649
1650 #### 18.5.5.1 Setting a Faster Serial Port Speed 
1651
1652
1653
1654 By default, the serial port settings are: 9600 baud, 8 bits, no parity, and 1 stop bit. If you wish to change the speed, you need to recompile at least the boot blocks. Add the following line to `/etc/make.conf` and compile new boot blocks:
1655
1656
1657
1658     
1659
1660     BOOT_COMCONSOLE_SPEED=19200
1661
1662
1663
1664
1665
1666 If the serial console is configured in some other way than by booting with `-h`, or if the serial console used by the kernel is different from the one used by the boot blocks, then you must also add the following option to the kernel configuration file and compile a new kernel:
1667
1668
1669
1670     
1671
1672     options CONSPEED=19200
1673
1674
1675
1676
1677
1678 #### 18.5.5.2 Using Serial Port Other Than `sio0` for the Console 
1679
1680
1681
1682 Using a port other than `sio0` as the console requires some recompiling. If you want to use another serial port for whatever reasons, recompile the boot blocks, the boot loader and the kernel as follows.
1683
1684
1685
1686   1. Get the kernel source.
1687
1688   1. Edit `/etc/make.conf` and set `BOOT_COMCONSOLE_PORT` to the address of the port you want to use (0x3F8, 0x2F8, 0x3E8 or 0x2E8). Only `sio0` through `sio3` (`COM1` through `COM4`) can be used; multiport serial cards will not work. No interrupt setting is needed.
1689
1690   1. Create a custom kernel configuration file and add appropriate flags for the serial port you want to use. For example, if you want to make `sio1` (`COM2`) the console:
1691
1692       
1693
1694       device sio1 at isa? port IO_COM2 flags 0x10 irq 3
1695
1696   
1697
1698   or
1699
1700       
1701
1702       device sio1 at isa? port IO_COM2 flags 0x30 irq 3
1703
1704   
1705
1706   The console flags for the other serial ports should not be set.
1707
1708   1. Recompile and install the boot blocks and the boot loader:
1709
1710       
1711
1712       # cd /sys/boot
1713
1714       # make
1715
1716       # make install
1717
1718   
1719
1720   1. Rebuild and install the kernel.
1721
1722   1. Write the boot blocks to the boot disk with [disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#disklabel&section8) and boot from the new kernel.
1723
1724
1725
1726 #### 18.5.5.3 Entering the DDB Debugger from the Serial Line 
1727
1728
1729
1730 If you wish to drop into the kernel debugger from the serial console (useful for remote diagnostics, but also dangerous if you generate a spurious BREAK on the serial port!) then you should compile your kernel with the following options:
1731
1732
1733
1734     
1735
1736     options BREAK_TO_DEBUGGER
1737
1738     options DDB
1739
1740
1741
1742
1743
1744 #### 18.5.5.4 Getting a Login Prompt on the Serial Console 
1745
1746
1747
1748 While this is not required, you may wish to get a ***login*** prompt over the serial line, now that you can see boot messages and can enter the kernel debugging session through the serial console. Here is how to do it.
1749
1750
1751
1752 Open the file `/etc/ttys` with an editor and locate the lines:
1753
1754
1755
1756     
1757
1758     ttyd0 "/usr/libexec/getty std.9600" unknown off secure
1759
1760     ttyd1 "/usr/libexec/getty std.9600" unknown off secure
1761
1762     ttyd2 "/usr/libexec/getty std.9600" unknown off secure
1763
1764     ttyd3 "/usr/libexec/getty std.9600" unknown off secure
1765
1766
1767
1768
1769
1770 `ttyd0` through `ttyd3` corresponds to `COM1` through `COM4`. Change `off` to `on` for the desired port. If you have changed the speed of the serial port, you need to change `std.9600` to match the current setting, e.g. `std.19200`.
1771
1772
1773
1774 You may also want to change the terminal type from `unknown` to the actual type of your serial terminal.
1775
1776
1777
1778 After editing the file, you must `kill -HUP 1` to make this change take effect.
1779
1780
1781
1782 ### 18.5.6 Changing Console from the Boot Loader 
1783
1784
1785
1786 Previous sections described how to set up the serial console by tweaking the boot block. This section shows that you can specify the console by entering some commands and environment variables in the boot loader. As the boot loader is invoked at the third stage of the boot process, after the boot block, the settings in the boot loader will override the settings in the boot block.
1787
1788
1789
1790 #### 18.5.6.1 Setting Up the Serial Console 
1791
1792
1793
1794 You can easily specify the boot loader and the kernel to use the serial console by writing just one line in `/boot/loader.rc`:
1795
1796
1797
1798     
1799
1800     set console=comconsole
1801
1802
1803
1804
1805
1806 This will take effect regardless of the settings in the boot block discussed in the previous section.
1807
1808
1809
1810 You had better put the above line as the first line of `/boot/loader.rc` so as to see boot messages on the serial console as early as possible.
1811
1812
1813
1814 Likewise, you can specify the internal console as:
1815
1816
1817
1818     
1819
1820     set console=vidconsole
1821
1822
1823
1824
1825
1826 If you do not set the boot loader environment variable `console`, the boot loader, and subsequently the kernel, will use whichever console indicated by the `-h` option in the boot block.
1827
1828
1829
1830 In versions 3.2 or later, you may specify the console in `/boot/loader.conf.local` or `/boot/loader.conf`, rather than in `/boot/loader.rc`. In this method your `/boot/loader.rc` should look like:
1831
1832
1833
1834     
1835
1836     include /boot/loader.4th
1837
1838     start
1839
1840
1841
1842
1843
1844 Then, create `/boot/loader.conf.local` and put the following line there.
1845
1846
1847
1848     
1849
1850     console=comconsole
1851
1852
1853
1854
1855
1856 or
1857
1858
1859
1860     
1861
1862     console=vidconsole
1863
1864
1865
1866
1867
1868
1869  **Note:** At the moment, the boot loader has no option equivalent to the `-P` option in the boot block, and there is no provision to automatically select the internal console and the serial console based on the presence of the keyboard.
1870
1871
1872
1873 #### 18.5.6.2 Using a Serial Port Other Than `sio0` for the Console 
1874
1875
1876
1877 You need to recompile the boot loader to use a serial port other than `sio0` for the serial console. Follow the procedure described in [serialconsole-setup.html#SERIALCONSOLE-COM2 Section 18.5.5.2].
1878
1879
1880
1881 ### 18.5.7 Caveats 
1882
1883
1884
1885 The idea here is to allow people to set up dedicated servers that require no graphics hardware or attached keyboards. Unfortunately, while most systems will let you boot without a keyboard, there are quite a few that will not let you boot without a graphics adapter. Machines with AMI BIOSes can be configured to boot with no graphics adapter installed simply by changing the ***graphics adapter*** setting in the CMOS configuration to ***Not installed.***
1886
1887
1888
1889 However, many machines do not support this option and will refuse to boot if you have no display hardware in the system. With these machines, you will have to leave some kind of graphics card plugged in, (even if it is just a junky mono board) although you will not have to attach a monitor. You might also try installing an AMI BIOS.
1890
1891 ***