1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
|
<!--
The FreeBSD Documentation Project
$FreeBSD: doc/en_US.ISO_8859-1/books/handbook/serialcomms/chapter.sgml,v 1.18 2000/06/08 01:56:19 jim Exp $
-->
<chapter id="serialcomms">
<title>Serial Communications</title>
<sect1>
<title>Synopsis</title>
<para>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
<quote>terminal</quote> consisted of a 10-character-per-second serial
printer and a keyboard. This chapter will cover some of the ways in
which FreeBSD uses serial communications.</para>
</sect1>
<sect1 id="serial">
<title>Serial Basics</title>
<para><emphasis>Assembled from FAQ.</emphasis></para>
<para>This section should give you some general information about serial
ports. If you do not find what you want here, check into the Terminal
and Dial-up sections of the handbook.</para>
<para>The <filename>ttyd<replaceable>X</replaceable></filename> (or
<filename>cuaa<replaceable>X</replaceable></filename>) 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</para>
<screen>&prompt.root; <userinput>stty -a -f /dev/ttyd1</userinput></screen>
<para>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 <quote>initial state</quote> device. For
example, to turn on <acronym>CLOCAL</acronym> mode, 8 bits, and
<emphasis>XON/XOFF</emphasis> flow control by default for ttyd5,
do:</para>
<screen>&prompt.root; <userinput>stty -f /dev/ttyid5 clocal cs8 ixon ixoff</userinput></screen>
<para>A good place to do this is in <filename>/etc/rc.serial</filename>.
Now, an application will have these settings by default when it opens
<filename>ttyd5</filename>. It can still change these settings to its
liking, though.</para>
<para>You can also prevent certain settings from being changed by an
application by making adjustments to the <quote>lock state</quote>
device. For example, to lock the speed of <filename>ttyd5</filename> to
57600 bps, do</para>
<screen>&prompt.root; <userinput>stty -f /dev/ttyld5 57600</userinput></screen>
<para>Now, an application that opens <filename>ttyd5</filename> and tries
to change the speed of the port will be stuck with 57600 bps.</para>
<para>Naturally, you should make the initial state and lock state devices
writable only by <username>root</username>. The
<filename>MAKEDEV</filename> script does <emphasis>not</emphasis> do
this when it creates the device entries.</para>
</sect1>
<sect1 id="term">
<title>Terminals</title>
<para><emphasis>Contributed by &a.kelly; 28 July 1996</emphasis></para>
<para>Terminals provide a convenient and low-cost way to access the power
of your FreeBSD system when you are not at the computer's console or on
a connected network. This section describes how to use terminals with
FreeBSD.</para>
<sect2 id="term-uses">
<title>Uses and Types of Terminals</title>
<para>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
some terminal software to dial into a remote system to do text-only
work.</para>
<para>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; FreeBSD is no
exception. By using a terminal attached to a unused serial port, you
can log in and run any text program that you would normally run on the
console or in an <command>xterm</command> window in the X Window
System.</para>
<para>For the business user, you can attach many terminals to a FreeBSD
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 FreeBSD. You can
turn what might otherwise be a single-user computer into a powerful
multiple user system.</para>
<para>For FreeBSD, there are three kinds of terminals:</para>
<itemizedlist>
<listitem>
<para><link linkend="term-dumb">Dumb terminals</link></para>
</listitem>
<listitem>
<para><link linkend="term-pcs">PCs acting as terminals</link></para>
</listitem>
<listitem>
<para><link linkend="term-x">X terminals</link></para>
</listitem>
</itemizedlist>
<para>The remaining subsections describe each kind.</para>
<sect3 id="term-dumb">
<title>Dumb Terminals</title>
<para>Dumb terminals are specialized pieces of hardware that let you
connect to computers over serial lines. They are called
<quote>dumb</quote> 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.</para>
<para>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 FreeBSD. Some
high-end terminals can even display graphics, but only certain
software packages can take advantage of these advanced
features.</para>
<para>Dumb terminals are popular in work environments where workers do
not need access to graphic applications such as those provided by
the X Window System.</para>
</sect3>
<sect3 id="term-pcs">
<title>PCs Acting As Terminals</title>
<para>If a <link linkend="term-dumb">dumb terminal</link> 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 <emphasis>terminal emulation</emphasis>
software to run on the computer.</para>
<para>Such a configuration is popular in homes. For example, if your
spouse is busy working on your FreeBSD 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 FreeBSD system.</para>
</sect3>
<sect3 id="term-x">
<title>X Terminals</title>
<para>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.</para>
<para>We introduce X terminals just for the sake of completeness.
However, this chapter does <emphasis>not</emphasis> cover setup,
configuration, or use of X terminals.</para>
</sect3>
</sect2>
<sect2 id="term-cables-ports">
<title>Cables and Ports</title>
<para>To connect a terminal to your FreeBSD system, you need the right
kind of cable and a serial port to which to connect it. This section
tells you what to do. If you are already familiar with your terminal
and the cable it requires, skip to <link
linkend="term-config">Configuration</link>.</para>
<sect3 id="term-cables">
<title>Cables</title>
<para>Because terminals use serial ports, you need to use
serial—also known as RS-232C—cables to connect the
terminal to the FreeBSD system.</para>
<para>There are a couple of kinds of serial cables. Which one
you'll use depends on the terminal you want to connect:</para>
<itemizedlist>
<listitem>
<para>If you are connecting a personal computer to act as a
terminal, use a <link linkend="term-null">null-modem</link>
cable. A null-modem cable connects two computers or terminals
together.</para>
</listitem>
<listitem>
<para>If you have an actual terminal, your best source of
information on what cable to use is the documentation that
accompanied the terminal. If you do not have the documentation,
then try a <link linkend="term-null">null-modem</link> cable.
If that does not work, then try a <link
linkend="term-std">standard</link> cable.</para>
</listitem>
</itemizedlist>
<para>Also, the serial port on <emphasis>both</emphasis> the terminal
and your FreeBSD system must have connectors that will fit the cable
you are using.</para>
<sect4 id="term-null">
<title>Null-modem cables</title>
<para>A null-modem cable passes some signals straight through, like
<quote>signal ground,</quote> but switches other signals. For
example, the <quote>send data</quote> pin on one end goes to the
<quote>receive data</quote> pin on the other end.</para>
<para>If you like making your own cables, here is a table showing a
recommended way to 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.</para>
<informaltable frame="none">
<tgroup cols="5">
<thead>
<row>
<entry>Signal</entry>
<entry>Pin #</entry>
<entry></entry>
<entry>Pin #</entry>
<entry>Signal</entry>
</row>
</thead>
<tbody>
<row>
<entry>TxD</entry>
<entry>2</entry>
<entry>connects to</entry>
<entry>3</entry>
<entry>RxD</entry>
</row>
<row>
<entry>RxD</entry>
<entry>3</entry>
<entry>connects to</entry>
<entry>2</entry>
<entry>TxD</entry>
</row>
<row>
<entry>DTR</entry>
<entry>20</entry>
<entry>connects to</entry>
<entry>6</entry>
<entry>DSR</entry>
</row>
<row>
<entry>DSR</entry>
<entry>6</entry>
<entry>connects to</entry>
<entry>20</entry>
<entry>DTR</entry>
</row>
<row>
<entry>SG</entry>
<entry>7</entry>
<entry>connects to</entry>
<entry>7</entry>
<entry>SG</entry>
</row>
<row>
<entry>DCD</entry>
<entry>8</entry>
<entry>connects to</entry>
<entry>4</entry>
<entry>RTS</entry>
</row>
<row>
<entry>RTS</entry>
<entry>4</entry>
<entry></entry>
<entry>5</entry>
<entry>CTS</entry>
</row>
<row>
<entry>CTS</entry>
<entry>5</entry>
<entry>connects to</entry>
<entry>8</entry>
<entry>DCD</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<note>
<para>For DCD to RTS, connect pins 4 to 5 internally in the
connector hood, and then to pin 8 in the remote
hood.</para>
</note>
</sect4>
<sect4 id="term-std">
<title>Standard RS-232C Cables</title>
<para>A standard serial cable passes all the RS-232C signals
straight-through. That is, the <quote>send data</quote> pin on one
end of the cable goes to the <quote>send data</quote> pin on the
other end. This is the type of cable to connect a modem to your
FreeBSD system, and the type of cable needed for some
terminals.</para>
</sect4>
</sect3>
<sect3 id="term-ports">
<title>Ports</title>
<para>Serial ports are the devices through which data is transferred
between the FreeBSD host computer and the terminal. This section
describes the kinds of ports that exist and how they are addressed
in FreeBSD.</para>
<sect4 id="term-portkinds">
<title>Kinds of Ports</title>
<para>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 FreeBSD system.</para>
<para>Most terminals will have DB25 ports. Personal computers,
including PCs running FreeBSD, 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.</para>
<para>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.</para>
</sect4>
<sect4 id="term-portnames">
<title>Port Names</title>
<para>In FreeBSD, you access each serial port through an entry in
the <filename>/dev</filename> directory. There are two different
kinds of entries:</para>
<itemizedlist>
<listitem>
<para>Call-in ports are named
<filename>/dev/ttyd<replaceable>X</replaceable></filename>
where <replaceable>X</replaceable> 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.</para>
</listitem>
<listitem>
<para>Call-out ports are named
<filename>/dev/cuaa<replaceable>X</replaceable></filename>.
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.</para>
</listitem>
</itemizedlist>
<para>See the &man.sio.4; manual page for more information.</para>
<para>If you have connected a terminal to the first serial port
(<devicename>COM1</devicename> in DOS parlance), then you want to
use <filename>/dev/ttyd0</filename> to refer to the terminal. If
it is on the second serial port (also known as
<devicename>COM2</devicename>), it is
<filename>/dev/ttyd1</filename>, and so forth.</para>
<para>Note that you may have to configure your kernel to support
each serial port, especially if you have a multiport serial card.
See <link linkend="kernelconfig">Configuring the FreeBSD
Kernel</link> for more information.</para>
</sect4>
</sect3>
</sect2>
<sect2 id="term-config">
<title>Configuration</title>
<para>This section describes what you need to configure on your FreeBSD
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.</para>
<para>In a nutshell, you need to tell the <command>init</command>
process, which is responsible for process control and initialization,
to start a <command>getty</command> process, which is responsible for
reading a login name and starting the <command>login</command>
program.</para>
<para>To do so, you have to edit the <filename>/etc/ttys</filename>
file. First, use the <command>su</command> command to become root.
Then, make the following changes to
<filename>/etc/ttys</filename>:</para>
<procedure>
<step>
<para>Add an line to <filename>/etc/ttys</filename> for the entry in
the <filename>/dev</filename> directory for the serial port if it
is not already there.</para>
</step>
<step>
<para>Specify that <filename>/usr/libexec/getty</filename> be run on
the port, and specify the appropriate
<replaceable>getty</replaceable> type from the
<filename>/etc/gettytab</filename> file.</para>
</step>
<step>
<para>Specify the default terminal type.</para>
</step>
<step>
<para>Set the port to <quote>on.</quote></para>
</step>
<step>
<para>Specify whether the port should be
<quote>secure.</quote></para>
</step>
<step>
<para>Force <command>init</command> to reread the
<filename>/etc/ttys</filename> file.</para>
</step>
</procedure>
<para>As an optional step, you may wish to create a custom
<replaceable>getty</replaceable> type for use in step 2 by making an
entry in <filename>/etc/gettytab</filename>. This document does
not explain how to do so; you are encouraged to see the
&man.gettytab.5; and the &man.getty.8; manual pages for more
information.</para>
<para>The remaining sections detail how to do these steps. We will use
a running example throughout these sections to illustrate what we need
to do. In our example, we will connect two terminals to the system: a
Wyse-50 and a 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).</para>
<para>For more information on the <filename>/etc/ttys</filename>
file, see the &man.ttys.5; manual page.</para>
<sect3 id="term-etcttys">
<title>Adding an Entry to <filename>/etc/ttys</filename></title>
<para>First, you need to add an entry to the
<filename>/etc/ttys</filename> file, unless one is already
there.</para>
<para>The <filename>/etc/ttys</filename> file lists all of the ports
on your FreeBSD system where you want to allow logins. For example,
the first virtual console <filename>ttyv0</filename> has an entry in
this file. You can log in on the console using this entry. This
file contains entries for the other virtual consoles, serial ports,
and pseudo-ttys. For a hardwired terminal, just list the serial
port's <filename>/dev</filename> entry without the
<filename>/dev</filename> part.</para>
<para>When you installed your FreeBSD system, the
<filename>/etc/ttys</filename> file included entries for the first
four serial ports: <filename>ttyd0</filename> through
<filename>ttyd3</filename>. If you are attaching a terminal on one
of those ports, you do not need to add an entry.</para>
<para>In our example, we attached a Wyse-50 to the second serial port,
<filename>ttyd1</filename>, which is already in the file. We need
to add an entry for the 286 PC connected to the sixth serial port.
Here is an excerpt of the <filename>/etc/ttys</filename> file after
we add the new entry:</para>
<programlisting>
ttyd1 "/usr/libexec/getty std.9600" unknown off secure
ttyd5</programlisting>
</sect3>
<sect3 id="term-getty">
<title>Specifying the <replaceable>getty</replaceable> Type</title>
<para>Next, we need to specify what program will be run to handle the
logins on a terminal. For FreeBSD, the standard program to do that
is <filename>/usr/libexec/getty</filename>. It is what provides the
<prompt>login:</prompt> prompt.</para>
<para>The program <command>getty</command> takes one (optional)
parameter on its command line, the <replaceable>getty</replaceable>
type. A <replaceable>getty</replaceable> type tells about
characteristics on the terminal line, like bps rate and parity. The
<command>getty</command> program reads these characteristics from
the file <filename>/etc/gettytab</filename>.</para>
<para>The file <filename>/etc/gettytab</filename> contains lots of
entries for terminal lines both old and new. In almost all cases,
the entries that start with the text <literal>std</literal> will
work for hardwired terminals. These entries ignore parity. There is
a <literal>std</literal> entry for each bps rate from 110 to 115200.
Of course, you can add your own entries to this file. The manual
page &man.gettytab.5; provides more
information.</para>
<para>When setting the <replaceable>getty</replaceable> type in the
<filename>/etc/ttys</filename> file, make sure that the
communications settings on the terminal match.</para>
<para>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.
Here is the <filename>/etc/ttys</filename> file so far (showing just
the two terminals in which we are interested):</para>
<programlisting>
ttyd1 "/usr/libexec/getty std.38400" unknown off secure
ttyd5 "/usr/libexec/getty std.19200"</programlisting>
<para>Note that the second field—where we specify what program
to run—appears in quotes. This is important, otherwise the
type argument to <command>getty</command> might be interpreted as
the next field.</para>
</sect3>
<sect3 id="term-deftermtype">
<title>Specifying the Default Terminal Type</title>
<para>The third field in the <filename>/etc/ttys</filename> file lists
the default terminal type for the port. For dial-up ports, you
typically put <literal>unknown</literal> or
<literal>dialup</literal> in this field because users may dial up
with practically any kind of terminal or software. For hardwired
terminals, the terminal type does not change, so you can put a real
terminal type in this field.</para>
<para>Users will usually use the <command>tset</command> program in
their <filename>.login</filename> or <filename>.profile</filename>
files to check the terminal type and prompt for one if necessary.
By setting a terminal type in the <filename>/etc/ttys</filename>
file, users can forego such prompting.</para>
<para>To find out what terminal types FreeBSD supports, see the
file <filename>/usr/share/misc/termcap</filename>. It lists
about 600 terminal types. You can add more if you wish. See
the &man.termcap.5; manual page for information.</para>
<para>In our example, the Wyse-50 is a Wyse-50 type of terminal
(although it can emulate others, we will leave it in Wyse-50 mode).
The 286 PC is running Procomm which will be set to emulate a VT-100.
Here are the pertinent yet unfinished entries from the
<filename>/etc/ttys</filename> file:</para>
<programlisting>
ttyd1 "/usr/libexec/getty std.38400" wy50 off secure
ttyd5 "/usr/libexec/getty std.19200" vt100</programlisting>
</sect3>
<sect3 id="term-enable">
<title>Enabling the Port</title>
<para>The next field in <filename>/etc/ttys</filename>, the fourth
field, tells whether to enable the port. Putting
<literal>on</literal> here will have the <command>init</command>
process start the program in the second field,
<command>getty</command>, which will prompt for a login. If you put
<literal>off</literal> in the fourth field, there will be no
<command>getty</command>, and hence no logins on the port.</para>
<para>So, naturally, you want an <literal>on</literal> in this field.
Here again is the <filename>/etc/ttys</filename> file. We have
turned each port <literal>on</literal>.</para>
<programlisting>
ttyd1 "/usr/libexec/getty std.38400" wy50 on secure
ttyd5 "/usr/libexec/getty std.19200" vt100 on</programlisting>
</sect3>
<sect3 id="term-secure">
<title>Specifying Secure Ports</title>
<para>We have arrived at the last field (well, almost: there is an
optional <literal>window</literal> specifier, but we will ignore
that). The last field tells whether the port is secure.</para>
<para>What does <quote>secure</quote> mean?</para>
<para>It means that the root account (or any account with a user ID of
0) may login on the port. Insecure ports do not allow root to
login.</para>
<para>How do you use secure and insecure ports?</para>
<para>By marking a port as insecure, the terminal to which it is
connected will not allow root to login. People who know the root
password to your FreeBSD system will first have to login using a
regular user account. To gain superuser privileges, they will then
have to use the <command>su</command> command.</para>
<para>Because of this, you will have two records to help track down
possible compromises of root privileges: both the
<command>login</command> and the <command>su</command> command make
records in the system log (and logins are also recorded in the
<filename>wtmp</filename> file).</para>
<para>By marking a port as secure, the terminal will allow root in.
People who know the root password will just login as root. You will
not have the potentially useful login and <command>su</command>
command records.</para>
<para>Which should you use?</para>
<para>Just use <quote>insecure.</quote> Use <quote>insecure</quote>
<emphasis>even</emphasis> for terminals <emphasis>not</emphasis> in
public user areas or behind locked doors. It is quite easy to login
and use <command>su</command> if you need superuser
privileges.</para>
<para>Here finally are the completed entries in the
<filename>/etc/ttys</filename> file, with comments added to describe
where the terminals are:</para>
<programlisting>
ttyd1 "/usr/libexec/getty std.38400" wy50 on insecure # Kitchen
ttyd5 "/usr/libexec/getty std.19200" vt100 on insecure # Guest bathroom</programlisting>
</sect3>
<sect3 id="term-hup">
<title>Force <command>init</command> to Reread
<filename>/etc/ttys</filename></title>
<para>When you boot FreeBSD, the first process,
<command>init</command>, will read the
<filename>/etc/ttys</filename> file and start the programs listed
for each enabled port to prompt for logins.</para>
<para>After you edit <filename>/etc/ttys</filename>, you do not want
to have to reboot your system to get <command>init</command> to see
the changes. So, <command>init</command> will reread
<filename>/etc/ttys</filename> if it receives a SIGHUP (hangup)
signal.</para>
<para>So, after you have saved your changes to
<filename>/etc/ttys</filename>, send <literal>SIGHUP</literal> to
<command>init</command> by typing:</para>
<screen>&prompt.root; <userinput>kill -HUP 1</userinput></screen>
<para>(The <command>init</command> process <emphasis>always</emphasis>
has process ID 1.)</para>
<para>If everything is set up correctly, all cables are in place, and
the terminals are powered up, you should see login prompts. Your
terminals are ready for their first logins!</para>
</sect3>
</sect2>
<sect2 id="term-debug">
<title>Debugging your connection</title>
<para>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.</para>
<variablelist>
<varlistentry>
<term>No login prompt appears</term>
<listitem>
<para>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.</para>
<para>Make sure the cable is connected firmly to both the terminal
and the FreeBSD computer. Make sure it is the right kind of
cable.</para>
<para>Make sure the terminal and FreeBSD 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.</para>
<para>Make sure that a <command>getty</command> process is running
and serving the terminal. Type <screen>&prompt.root;
<userinput>ps -axww|grep getty</userinput></screen> to get a
list of running <command>getty</command> processes. You should
see an entry for the terminal. For example, the display
<screen>22189 d1 Is+ 0:00.03 /usr/libexec/getty std.38400 ttyd1</screen>
shows that a <command>getty</command> is running on the second
serial port <literal>ttyd1</literal> and is using the
<literal>std.38400</literal> entry in
<filename>/etc/gettytab</filename>.</para>
<para>If no <command>getty</command> process is running, make sure
you have enabled the port in <filename>/etc/ttys</filename>.
Make sure you have run <command>kill -HUP 1</command>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Garbage appears instead of a login prompt</term>
<listitem>
<para>Make sure the terminal and FreeBSD agree on the bps rate and
parity settings. Check the getty processes to make sure the
correct <replaceable>getty</replaceable> type is in use. If
not, edit <filename>/etc/ttys</filename> and run <command>kill
-HUP 1</command>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Characters appear doubled; the password appears when
typed</term>
<listitem>
<para>Switch the terminal (or the terminal emulation software)
from <quote>half duplex</quote> or <quote>local echo</quote> to
<quote>full duplex.</quote></para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
<sect1 id="dialup">
<title>Dial-in Service</title>
<para><emphasis>Contributed by &a.ghelmer;.</emphasis></para>
<para>This document provides suggestions for configuring a FreeBSD system
to handle dial-up modems. This document is written based on the author's
experience with FreeBSD versions 1.0, 1.1, and 1.1.5.1 (and experience
with dial-up modems on other UNIX-like operating systems); however, this
document may not answer all of your questions or provide examples
specific enough to your environment. The author cannot be responsible if
you damage your system or lose data due to attempting to follow the
suggestions here.</para>
<sect2 id="dialup-prereqs">
<title>Prerequisites</title>
<para>To begin with, the author assumes you have some basic knowledge of
FreeBSD. You need to have FreeBSD installed, know how to edit files
in a UNIX-like environment, and how to look up manual pages on the
system. As discussed below, you will need certain versions of
FreeBSD, and knowledge of some terminology & modem and
cabling.</para>
<sect3>
<title>FreeBSD Version</title>
<para>First, it is assumed that you are using FreeBSD version 1.1 or
higher (including versions 2.x). FreeBSD version 1.0 included two
different serial drivers, which complicates the situation. Also,
the serial device driver (<devicename>sio</devicename>) has improved
in every release of FreeBSD, so more recent versions of FreeBSD are
assumed to have better and more efficient drivers than earlier
versions.</para>
</sect3>
<sect3>
<title>Terminology</title>
<para>A quick rundown of terminology:</para>
<variablelist>
<varlistentry>
<term>bps</term>
<listitem>
<para>Bits per Second — the rate at which data is
transmitted</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DTE</term>
<listitem>
<para>Data Terminal Equipment — for example, your
computer</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DCE</term>
<listitem>
<para>Data Communications Equipment — your modem</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RS-232</term>
<listitem>
<para>EIA standard for serial communications via hardware</para>
</listitem>
</varlistentry>
</variablelist>
<para>If you need more information about these terms and data
communications in general, the author remembers reading that
<emphasis>The RS-232 Bible</emphasis> (anybody have an ISBN?) is a
good reference.</para>
<para>When talking about communications data rates, the author does
not use the term <quote>baud</quote>. Baud refers to the number of
electrical state transitions that may be made in a period of time,
while <quote>bps</quote> (bits per second) is the
<quote>correct</quote> term to use (at least it does not seem to
bother the curmudgeons quite a much).</para>
</sect3>
<sect3>
<title>External v.s. Internal Modems</title>
<para>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.</para>
<para>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.</para>
</sect3>
<sect3>
<title>Modems and Cables</title>
<para>A background knowledge of these items is assumed</para>
<itemizedlist>
<listitem>
<para>You know how to connect your modem to your computer so that
the two can communicate (unless you have an internal modem,
which does not need such a cable)</para>
</listitem>
<listitem>
<para>You are familiar with your modem's command set, or know
where to look up needed commands</para>
</listitem>
<listitem>
<para>You know how to configure your modem (probably via a
terminal communications program) so you can set the non-volatile
RAM parameters</para>
</listitem>
</itemizedlist>
<para>The first, connecting your modem, is usually simple — most
straight-through serial cables work without any problems. You need
to have a cable with appropriate connectors (DB-25 or DB-9, male or
female) on each end, and the cable must be a DCE-to-DTE cable with
these signals wired:</para>
<itemizedlist>
<listitem>
<para>Transmitted Data (<acronym>SD</acronym>)</para>
</listitem>
<listitem>
<para>Received Data (<acronym>RD</acronym>)</para>
</listitem>
<listitem>
<para>Request to Send (<acronym>RTS</acronym>)</para>
</listitem>
<listitem>
<para>Clear to Send (<acronym>CTS</acronym>)</para>
</listitem>
<listitem>
<para>Data Set Ready (<acronym>DSR</acronym>)</para>
</listitem>
<listitem>
<para>Data Terminal Ready (<acronym>DTR</acronym>)</para>
</listitem>
<listitem>
<para>Carrier Detect (<acronym>CD</acronym>)</para>
</listitem>
<listitem>
<para>Signal Ground (<acronym>SG</acronym>)</para>
</listitem>
</itemizedlist>
<para>FreeBSD needs the <acronym>RTS</acronym> and
<acronym>CTS</acronym> signals for flow-control at speeds above
2400bps, the <acronym>CD</acronym> signal to detect when a call has
been answered or the line has been hung up, and the
<acronym>DTR</acronym> 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.</para>
<para>The second prerequisite depends on the modem(s) you use. If you
do not know your modem's command set by heart, you will need to have
the modem's reference book or user's guide handy. Sample commands
for USR Sportster 14,400 external modems will be given, which you
may be able to use as a reference for your own modem's
commands.</para>
<para>Lastly, you will need to know how to setup your modem so that it
will work well with FreeBSD. Like other UNIX-like operating
systems, FreeBSD 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. FreeBSD 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.</para>
</sect3>
<sect3>
<title>Serial Interface Considerations</title>
<para>FreeBSD 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.</para>
</sect3>
</sect2>
<sect2>
<title>Quick Overview</title>
<para>Here is the process that FreeBSD follows to accept dial-up logins.
A <command>getty</command> process, spawned by
<command>init</command>, patiently waits to open the assigned serial
port (<filename>/dev/ttyd0</filename>, for our example). The command
<command>ps ax</command> might show this:</para>
<screen> 4850 ?? I 0:00.09 /usr/libexec/getty V19200 ttyd0</screen>
<para>When a user dials the modem's line and the modems connect, the
<acronym>CD</acronym> line is asserted by the modem. The kernel
notices that carrier has been detected and completes
<command>getty</command>'s open of the port. <command>getty</command>
sends a <prompt>login:</prompt> prompt at the specified initial line
speed. <command>getty</command> 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 <command>getty</command>'s speed), <command>getty</command> tries
adjusting the line speeds until it receives reasonable
characters.</para>
<para>We hope <command>getty</command> finds the correct speed and the
user sees a <prompt>login:</prompt> prompt. After the user enters
his/her login name, <command>getty</command> executes
<filename>/usr/bin/login</filename>, which completes the login by
asking for the user's password and then starting the user's
shell.</para>
<para>Let's dive into the configuration...</para>
</sect2>
<sect2>
<title>Kernel Configuration</title>
<para>FreeBSD kernels typically come prepared to search for four serial
ports, known in the PC-DOS world as <devicename>COM1:</devicename>,
<devicename>COM2:</devicename>, <devicename>COM3:</devicename>, and
<devicename>COM4:</devicename>. FreeBSD can presently also handle
<quote>dumb</quote> multiport serial interface cards, such as the Boca
Board 1008 and 2016 (please see the manual page &man.sio.4; for kernel
configuration information if you have a multiport serial card). The
default kernel only looks for the standard COM ports, though.</para>
<para>To see if your kernel recognizes any of your serial ports, watch
for messages while the kernel is booting, or use the
<command>/sbin/dmesg</command> command to replay the kernel's boot
messages. In particular, look for messages that start with the
characters <literal>sio</literal>. Hint: to view just the messages
that have the word <literal>sio</literal>, use the command:</para>
<screen>&prompt.root; <userinput>/sbin/dmesg | grep 'sio'</userinput></screen>
<para>For example, on a system with four serial ports, these are the
serial-port specific kernel boot messages:</para>
<screen>sio0 at 0x3f8-0x3ff irq 4 on isa
sio0: type 16550A
sio1 at 0x2f8-0x2ff irq 3 on isa
sio1: type 16550A
sio2 at 0x3e8-0x3ef irq 5 on isa
sio2: type 16550A
sio3 at 0x2e8-0x2ef irq 9 on isa
sio3: type 16550A</screen>
<para>If your kernel does not recognize all of your serial ports, you
will probably need to configure a custom FreeBSD kernel for your
system.</para>
<para>Please see the BSD System Manager's Manual chapter on
<quote>Building Berkeley Kernels with Config</quote> [the source for
which is in <filename>/usr/src/share/doc/smm</filename>] and
<quote>FreeBSD Configuration Options</quote> [in
<filename>/sys/conf/options</filename> and in
<filename>/sys/<replaceable>arch</replaceable>/conf/options.<replaceable>arch</replaceable></filename>,
with <emphasis>arch</emphasis> for example being
<filename>i386</filename>] for more information on configuring and
building kernels. You may have to unpack the kernel source
distribution if have not installed the system sources already
(<filename>srcdist/srcsys.??</filename> in FreeBSD 1.1,
<filename>srcdist/sys.??</filename> in FreeBSD 1.1.5.1, or the entire
source distribution in FreeBSD 2.0) to be able to configure and build
kernels.</para>
<para>Create a kernel configuration file for your system (if you have
not already) by <command>cd</command>ing to
<filename>/sys/i386/conf</filename>. Then, if you are creating a new
custom configuration file, copy the file
<filename>GENERICAH</filename> (or <filename>GENERICBT</filename>, if
you have a BusTek SCSI controller on FreeBSD 1.x) to
<filename>YOURSYS</filename>, where <filename>YOURSYS</filename> is
the name of your system, but in upper-case letters. Edit the file,
and change the device lines:</para>
<programlisting>
device sio0 at isa? port "IO_COM1" tty irq 4 vector siointr
device sio1 at isa? port "IO_COM2" tty irq 3 vector siointr
device sio2 at isa? port "IO_COM3" tty irq 5 vector siointr
device sio3 at isa? port "IO_COM4" tty irq 9 vector siointr</programlisting>
<para>You can comment-out or completely remove lines for devices you do
not have. If you have a multiport serial board, such as the Boca
Board BB2016, please see the &man.sio.4; man page for complete
information on how to write configuration lines for multiport boards.
Be careful if you are using a configuration file that was previously
used for a different version of FreeBSD because the device flags have
changed between versions.</para>
<note>
<para><literal>port "IO_COM1"</literal> is a substitution for
<literal>port 0x3f8</literal>, <literal>IO_COM2</literal> is
<literal>0x2f8</literal>, <literal>IO_COM3</literal> is
<literal>0x3e8</literal>, and <literal>IO_COM4</literal> is
<literal>0x2e8</literal>, 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
<emphasis>cannot</emphasis> 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).</para>
</note>
<para>When you are finished adjusting the kernel configuration file, use
the program <command>config</command> as documented in <quote>Building
Berkeley Kernels with Config</quote> and the
&man.config.8; manual page to prepare a kernel building directory,
then build, install, and test the new kernel.</para>
</sect2>
<sect2>
<title>Device Special Files</title>
<para>Most devices in the kernel are accessed through <quote>device
special files</quote>, which are located in the
<filename>/dev</filename> directory. The <devicename>sio</devicename>
devices are accessed through the
<filename>/dev/ttyd<replaceable>?</replaceable></filename> (dial-in)
and <filename>/dev/cua0<replaceable>?</replaceable></filename>
(call-out) devices. On FreeBSD version 1.1.5 and higher, there are
also initialization devices
(<filename>/dev/ttyid<replaceable>?</replaceable></filename> and
<filename>/dev/cuai0<replaceable>?</replaceable></filename>) and
locking devices
(<filename>/dev/ttyld<replaceable>?</replaceable></filename> and
<filename>/dev/cual0<replaceable>?</replaceable></filename>). The
initialization devices are used to initialize communications port
parameters each time a port is opened, such as
<literal>crtscts</literal> for modems which use
<literal>CTS/RTS</literal> 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 &man.termios.4;,
&man.sio.4;, and &man.stty.1; for
information on the terminal settings, locking & initializing
devices, and setting terminal options, respectively.</para>
<sect3>
<title>Making Device Special Files</title>
<para>A shell script called <command>MAKEDEV</command> in the
<filename>/dev</filename> directory manages the device special
files. (The manual page for &man.MAKEDEV.8; on FreeBSD 1.1.5 is
fairly bogus in its discussion of <acronym>COM</acronym> ports, so
ignore it.) To use <command>MAKEDEV</command> to make dial-up device
special files for <devicename>COM1:</devicename> (port 0),
<command>cd</command> to <filename>/dev</filename> and issue the
command <command>MAKEDEV ttyd0</command>. Likewise, to make dial-up
device special files for <devicename>COM2:</devicename> (port 1),
use <command>MAKEDEV ttyd1</command>.</para>
<para><command>MAKEDEV</command> not only creates the
<filename>/dev/ttyd<replaceable>?</replaceable></filename> device
special files, but also creates the
<filename>/dev/cua0<replaceable>?</replaceable></filename> (and all
of the initializing and locking special files under FreeBSD 1.1.5
and up) and removes the hardwired terminal special file
<filename>/dev/tty0<replaceable>?</replaceable></filename>, if it
exists.</para>
<para>After making new device special files, be sure to check the
permissions on the files (especially the
<filename>/dev/cua*</filename> files) to make sure that only users
who should have access to those device special files can read &
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
<filename>/dev/cua*</filename> files should be sufficient:</para>
<screen>crw-rw---- 1 uucp dialer 28, 129 Feb 15 14:38 /dev/cua01
crw-rw---- 1 uucp dialer 28, 161 Feb 15 14:38 /dev/cuai01
crw-rw---- 1 uucp dialer 28, 193 Feb 15 14:38 /dev/cual01</screen>
<para>These permissions allow the user <username>uucp</username> and
users in the group <username>dialer</username> to use the call-out
devices.</para>
</sect3>
</sect2>
<sect2>
<title>Configuration Files</title>
<para>There are three system configuration files in the
<filename>/etc</filename> directory that you will probably need to
edit to allow dial-up access to your FreeBSD system. The first,
<filename>/etc/gettytab</filename>, contains configuration information
for the <filename>/usr/libexec/getty</filename> daemon. Second,
<filename>/etc/ttys</filename> holds information that tells
<filename>/sbin/init</filename> what <filename>tty</filename> devices
should have <command>getty</command> processes running on them.
Lastly, you can place port initialization commands in the
<filename>/etc/rc.serial</filename> script if you have FreeBSD 1.1.5.1
or higher; otherwise, you can initialize ports in the
<filename>/etc/rc.local</filename> script.</para>
<para>There are two schools of thought regarding dial-up modems on UNIX.
One group likes to configure their modems and system 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.</para>
<para>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
<command>getty</command> does not understand any particular modem's
connection speed reporting, <command>getty</command> gives a
<prompt>login:</prompt> 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
<literal><Enter></literal> key until they see a recognizable
prompt. If the data rates do not match, <command>getty</command> sees
anything the user types as <quote>junk</quote>, tries going to the next
speed and gives the <prompt>login:</prompt> prompt again. This
procedure can continue ad nauseum, 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
<quote>locked-speed</quote> method, but a user on a low-speed
connection should receive better interactive response from full-screen
programs.</para>
<para>The author will try to give balanced configuration information,
but is biased towards having the modem's data rate follow the
connection rate.</para>
<sect3>
<title><filename>/etc/gettytab</filename></title>
<para><filename>/etc/gettytab</filename> is a &man.termcap.5;-style
file of configuration information for &man.getty.8;. Please see the
&man.gettytab.5; manual page for complete information on the
format of the file and the list of capabilities.</para>
<sect4>
<title>Locked-Speed Config</title>
<para>If you are locking your modem's data communications rate at a
particular speed, you probably will not need to make any changes
to <filename>/etc/gettytab</filename>.</para>
</sect4>
<sect4>
<title>Matching-Speed Config</title>
<para>You will need to setup an entry in
<filename>/etc/gettytab</filename> to give
<command>getty</command> information about the speeds you wish to
use for your modem. If you have a 2400 bps modem, you can
probably use the existing <literal>D2400</literal> entry. This
entry already exists in the FreeBSD 1.1.5.1
<filename>gettytab</filename> file, so you do not need to add it
unless it is missing under your version of FreeBSD:</para>
<programlisting>
#
# Fast dialup terminals, 2400/1200/300 rotary (can start either way)
#
D2400|d2400|Fast-Dial-2400:\
:nx=D1200:tc=2400-baud:
3|D1200|Fast-Dial-1200:\
:nx=D300:tc=1200-baud:
5|D300|Fast-Dial-300:\
:nx=D2400:tc=300-baud:</programlisting>
<para>If you have a higher speed modem, you will probably need to
add an entry in <filename>/etc/gettytab</filename>; here is an
entry you could use for a 14.4 Kbps modem with a top interface
speed of 19.2 Kbps:</para>
<programlisting>
#
# Additions for a V.32bis Modem
#
um|V300|High Speed Modem at 300,8-bit:\
:nx=V19200:tc=std.300:
un|V1200|High Speed Modem at 1200,8-bit:\
:nx=V300:tc=std.1200:
uo|V2400|High Speed Modem at 2400,8-bit:\
:nx=V1200:tc=std.2400:
up|V9600|High Speed Modem at 9600,8-bit:\
:nx=V2400:tc=std.9600:
uq|V19200|High Speed Modem at 19200,8-bit:\
:nx=V9600:tc=std.19200:</programlisting>
<para>On FreeBSD 1.1.5 and later, this will result in 8-bit, no
parity connections. Under FreeBSD 1.1, add
<literal>:np:</literal> parameters to the
<literal>std.<replaceable>xxx</replaceable></literal> entries at
the top of the file for 8 bits, no parity; otherwise, the default
is 7 bits, even parity.</para>
<para>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
<literal>nx=</literal> (<quote>next table</quote>) capability.
Each of the lines uses a <literal>tc=</literal> (<quote>table
continuation</quote>) entry to pick up the rest of the
<quote>standard</quote> settings for a particular data rate.</para>
<para>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 <filename>gettytab</filename> entry starting a 57.6 Kbps:</para>
<programlisting>
#
# Additions for a V.32bis or V.34 Modem
# Starting at 57.6 Kbps
#
vm|VH300|Very High Speed Modem at 300,8-bit:\
:nx=VH57600:tc=std.300:
vn|VH1200|Very High Speed Modem at 1200,8-bit:\
:nx=VH300:tc=std.1200:
vo|VH2400|Very High Speed Modem at 2400,8-bit:\
:nx=VH1200:tc=std.2400:
vp|VH9600|Very High Speed Modem at 9600,8-bit:\
:nx=VH2400:tc=std.9600:
vq|VH57600|Very High Speed Modem at 57600,8-bit:\
:nx=VH9600:tc=std.57600:</programlisting>
<para>If you have a slow CPU or a heavily loaded system and you do
not have 16550A-based serial ports, you may receive sio
<quote>silo</quote> errors at 57.6 Kbps.</para>
</sect4>
</sect3>
<sect3 id="dialup-ttys">
<title><filename>/etc/ttys</filename></title>
<para><filename>/etc/ttys</filename> is the list of
<filename>ttys</filename> for <command>init</command> to monitor.
<filename>/etc/ttys</filename> also provides security information to
<command>login</command> (user <username>root</username> may only
login on ttys marked <literal>secure</literal>). See the manual
page for
&man.ttys.5; for more information.</para>
<para>You will need to either modify existing lines in
<filename>/etc/ttys</filename> or add new lines to make
<command>init</command> run <command>getty</command> processes
automatically on your new dial-up ports. The general format of the
line will be the same, whether you are using a locked-speed or
matching-speed configuration:</para>
<programlisting>
ttyd0 "/usr/libexec/getty xxx" dialup on</programlisting>
<para>The first item in the above line is the device special file for
this entry — <literal>ttyd0</literal> means
<filename>/dev/ttyd0</filename> is the file that this
<command>getty</command> will be watching. The second item,
<literal>"/usr/libexec/getty
<replaceable>xxx</replaceable>"</literal>
(<replaceable>xxx</replaceable> will be replaced by the initial
<filename>gettytab</filename> capability) is the process
<command>init</command> will run on the device. The third item,
<literal>dialup</literal>, is the default terminal type. The fourth
parameter, <literal>on</literal>, indicates to
<command>init</command> that the line is operational. There can be
a fifth parameter, <literal>secure</literal>, but it should only be
used for terminals which are physically secure (such as the system
console).</para>
<para>The default terminal type (<literal>dialup</literal> in the
example above) may depend on local preferences.
<literal>dialup</literal> is the traditional default terminal type
on dial-up lines so that users may customize their login scripts to
notice when the terminal is <literal>dialup</literal> and
automatically adjust their terminal type. However, the author finds
it easier at his site to specify <literal>vt102</literal> as the
default terminal type, since the users just use VT102 emulation on
their remote systems.</para>
<para>After you have made changes to <filename>/etc/ttys</filename>,
you may send the <command>init</command> process a
<acronym>HUP</acronym> signal to re-read the file. You can use the
command <screen>&prompt.root; <userinput>kill -1
1</userinput></screen> to send the signal. If this is your
first time setting up the system, though, you may want to wait until
your modem(s) are properly configured and connected before signaling
<command>init</command>.</para>
<sect4>
<title>Locked-Speed Config</title>
<para>For a locked-speed configuration, your
<filename>ttys</filename> entry needs to have a fixed-speed entry
provided to <command>getty</command>. For a modem whose port
speed is locked at 19.2 Kbps, the <filename>ttys</filename> entry
might look like this:</para>
<programlisting>
ttyd0 "/usr/libexec/getty std.19200" dialup on</programlisting>
<para>If your modem is locked at a different data rate, substitute
the appropriate name for the
<literal>std.<replaceable>speed</replaceable></literal> entry for
<literal>std.19200</literal> from
<filename>/etc/gettytab</filename> for your modem's data
rate.</para>
</sect4>
<sect4>
<title>Matching-Speed Config</title>
<para>In a matching-speed configuration, your
<filename>ttys</filename> entry needs to reference the appropriate
beginning <quote>auto-baud</quote> (sic) entry in
<filename>/etc/gettytab</filename>. For example, if you added the
above suggested entry for a matching-speed modem that starts at
19.2 Kbps (the <filename>gettytab</filename> entry containing the
<literal>V19200</literal> starting point), your
<filename>ttys</filename> entry might look like this:</para>
<programlisting>
ttyd0 "/usr/libexec/getty V19200" dialup on</programlisting>
</sect4>
</sect3>
<sect3>
<title><filename>/etc/rc.serial</filename> or
<filename>/etc/rc.local</filename></title>
<para>High-speed modems, like V.32, V.32bis, and V.34 modems, need to
use hardware (<filename>RTS/CTS</filename>) flow control. You can
add <command>stty</command> commands to
<filename>/etc/rc.serial</filename> on FreeBSD 1.1.5.1 and up, or
<filename>/etc/rc.local</filename> on FreeBSD 1.1, to set the
hardware flow control flag in the FreeBSD kernel for the modem
ports.</para>
<para>For example, on a sample FreeBSD 1.1.5.1 system,
<filename>/etc/rc.serial</filename> reads:</para>
<programlisting>
#!/bin/sh
#
# Serial port initial configuration
stty -f /dev/ttyid1 crtscts
stty -f /dev/cuai01 crtscts</programlisting>
<para>This sets the <literal>termios</literal> flag
<literal>crtscts</literal> on serial port #1's
(<devicename>COM2:</devicename>) dial-in and dial-out initialization
devices.</para>
<para>On an old FreeBSD 1.1 system, these entries were added to
<filename>/etc/rc.local</filename> to set the
<literal>crtscts</literal> flag on the devices:</para>
<programlisting>
# Set serial ports to use RTS/CTS flow control
stty -f /dev/ttyd0 crtscts
stty -f /dev/ttyd1 crtscts
stty -f /dev/ttyd2 crtscts
stty -f /dev/ttyd3 crtscts</programlisting>
<para>Since there is no initialization device special file on FreeBSD
1.1, one has to just set the flags on the sole device special file
and hope the flags are not cleared by a miscreant.</para>
</sect3>
</sect2>
<sect2>
<title>Modem Settings</title>
<para>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 PC-DOS or <command>tip</command> under FreeBSD) to set the
parameters. Connect to the modem using the same communications speed
as the initial speed <command>getty</command> will use and configure
the modem's non-volatile RAM to match these requirements:</para>
<itemizedlist>
<listitem>
<para><acronym>CD</acronym> asserted when connected</para>
</listitem>
<listitem>
<para><acronym>DTR</acronym> asserted for operation; dropping DTR
hangs up line & resets modem</para>
</listitem>
<listitem>
<para><acronym>CTS</acronym> transmitted data flow control</para>
</listitem>
<listitem>
<para>Disable <acronym>XON/XOFF</acronym> flow control</para>
</listitem>
<listitem>
<para><acronym>RTS</acronym> received data flow control</para>
</listitem>
<listitem>
<para>Quiet mode (no result codes)</para>
</listitem>
<listitem>
<para>No command echo</para>
</listitem>
</itemizedlist>
<para>Please read the documentation for your modem to find out what
commands and/or DIP switch settings you need to give it.</para>
<para>For example, to set the above parameters on a USRobotics
Sportster 14,400 external modem, one could give these commands to
the modem:</para>
<programlisting>
ATZ
AT&C1&D2&H1&I0&R2&W</programlisting>
<para>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.</para>
<para>The USR 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:</para>
<itemizedlist>
<listitem>
<para>Switch 1: UP — DTR Normal</para>
</listitem>
<listitem>
<para>Switch 2: Do not care (Verbal Result Codes/Numeric Result
Codes)</para>
</listitem>
<listitem>
<para>Switch 3: UP — Suppress Result Codes</para>
</listitem>
<listitem>
<para>Switch 4: DOWN — No echo, offline commands</para>
</listitem>
<listitem>
<para>Switch 5: UP — Auto Answer</para>
</listitem>
<listitem>
<para>Switch 6: UP — Carrier Detect Normal</para>
</listitem>
<listitem>
<para>Switch 7: UP — Load NVRAM Defaults</para>
</listitem>
<listitem>
<para>Switch 8: Do not care (Smart Mode/Dumb Mode)</para>
</listitem>
</itemizedlist>
<para>Result codes should be disabled/suppressed for dial-up modems to
avoid problems that can occur if <command>getty</command> mistakenly
gives a <prompt>login:</prompt> prompt to a modem that is in command
mode and the modem echoes the command or returns a result code. I
have heard this sequence can result in a extended, silly conversation
between <command>getty</command> and the modem.</para>
<sect3>
<title>Locked-speed Config</title>
<para>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 USR Sportster 14,400 external
modem, these commands will lock the modem-to-computer data rate at
the speed used to issue the commands:</para>
<programlisting>
ATZ
AT&B1&W</programlisting>
</sect3>
<sect3>
<title>Matching-speed Config</title>
<para>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 USR 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:</para>
<programlisting>
ATZ
AT&B2&W</programlisting>
</sect3>
<sect3>
<title>Checking the Modem's Configuration</title>
<para>Most high-speed modems provide commands to view the modem's
current operating parameters in a somewhat human-readable fashion.
On the USR Sportster 14,400 external modems, the command
<command>ATI5</command> displays the settings that are stored in the
non-volatile RAM. To see the true operating parameters of the modem
(as influenced by the USR's DIP switch settings), use the commands
<command>ATZ</command> and then <command>ATI4</command>.</para>
<para>If you have a different brand of modem, check your modem's
manual to see how to double-check your modem's configuration
parameters.</para>
</sect3>
</sect2>
<sect2>
<title>Troubleshooting</title>
<para>Here are a few steps you can follow to check out the dial-up modem
on your system.</para>
<sect3>
<title>Checking out the FreeBSD system</title>
<para>Hook up your modem to your FreeBSD system, boot the system, and,
if your modem has status indication lights, watch to see whether the
modem's <acronym>DTR</acronym> indicator lights when the
<prompt>login:</prompt> prompt appears on the system's console
— if it lights up, that should mean that FreeBSD has started a
<command>getty</command> process on the appropriate communications
port and is waiting for the modem to accept a call.</para>
<para>If the <acronym>DTR</acronym> indicator doesn't light, login to
the FreeBSD system through the console and issue a <command>ps
ax</command> to see if FreeBSD is trying to run a
<command>getty</command> process on the correct port. You should see
a lines like this among the processes displayed:</para>
<screen> 114 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd0
115 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd1</screen>
<para>If you see something different, like this:</para>
<screen> 114 d0 I 0:00.10 /usr/libexec/getty V19200 ttyd0</screen>
<para>and the modem has not accepted a call yet, this means that
<command>getty</command> has completed its open on the
communications port. This could indicate a problem with the cabling
or a mis-configured modem, because <command>getty</command> should
not be able to open the communications port until
<acronym>CD</acronym> (carrier detect) has been asserted by the
modem.</para>
<para>If you do not see any <command>getty</command> processes waiting
to open the desired
<filename>ttyd<replaceable>?</replaceable></filename> port,
double-check your entries in <filename>/etc/ttys</filename> to see
if there are any mistakes there. Also, check the log file
<filename>/var/log/messages</filename> to see if there are any log
messages from <command>init</command> or <command>getty</command>
regarding any problems. If there are any messages, triple-check the
configuration files <filename>/etc/ttys</filename> and
<filename>/etc/gettytab</filename>, as well as the appropriate
device special files <filename>/dev/ttyd?</filename>, for any
mistakes, missing entries, or missing device special files.</para>
</sect3>
<sect3>
<title>Try Dialing In</title>
<para>Try dialing into the system; be sure to use 8 bits, no parity, 1
stop bit on the remote system. If you do not get a prompt right
away, or get garbage, try pressing <literal><Enter></literal>
about once per second. If you still do not see a
<prompt>login:</prompt> prompt after a while, try sending a
<command>BREAK</command>. If you are using a high-speed modem to do
the dialing, try dialing again after locking the dialing modem's
interface speed (via <command>AT&B1</command> on a USR
Sportster, for example).</para>
<para>If you still cannot get a <prompt>login:</prompt> prompt, check
<filename>/etc/gettytab</filename> again and double-check
that</para>
<itemizedlist>
<listitem>
<para>The initial capability name specified in
<filename>/etc/ttys</filename> for the line matches a name of a
capability in <filename>/etc/gettytab</filename></para>
</listitem>
<listitem>
<para>Each <literal>nx=</literal> entry matches another
<filename>gettytab</filename> capability name</para>
</listitem>
<listitem>
<para>Each <literal>tc=</literal> entry matches another
<filename>gettytab</filename> capability name</para>
</listitem>
</itemizedlist>
<para>If you dial but the modem on the FreeBSD system will not answer,
make sure that the modem is configured to answer the phone when
<acronym>DTR</acronym> is asserted. If the modem seems to be
configured correctly, verify that the <acronym>DTR</acronym> line is
asserted by checking the modem's indicator lights (if it has
any).</para>
<para>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
&a.questions;describing your modem and your problem, and the good
folks on the list will try to help.</para>
</sect3>
</sect2>
<sect2>
<title>Acknowledgments</title>
<para>Thanks to these people for comments and advice:</para>
<variablelist>
<varlistentry>
<term>&a.kelly;</term>
<listitem>
<para>for a number of good suggestions</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
<sect1 id="dialout">
<title>Dial-out Service</title>
<para><emphasis>Information integrated from FAQ.</emphasis></para>
<para>The following are tips to 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.</para>
<para>This is useful to log onto a BBS.</para>
<para>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.</para>
<sect2>
<title>Why cannot I run <command>tip</command> or
<command>cu</command>?</title>
<para>On your system, the programs <command>tip</command> and
<command>cu</command> are probably executable only by
<username>uucp</username> and group <username>dialer</username>. You
can use the group <username>dialer</username> to control who has
access to your modem or remote systems. Just add yourself to group
dialer.</para>
<para>Alternatively, you can let everyone on your system run
<command>tip</command> and <command>cu</command> by typing:</para>
<screen>&prompt.root; <userinput>chmod 4511 /usr/bin/tip</userinput></screen>
<para>You do not have to run this command for <command>cu</command>,
since <command>cu</command> is just a hard link to
<command>tip</command>.</para>
</sect2>
<sect2>
<title>My stock Hayes modem is not supported, what can I do?</title>
<para>Actually, the man page for <command>tip</command> is out of date.
There is a generic Hayes dialer already built in. Just use
<literal>at=hayes</literal> in your <filename>/etc/remote</filename>
file.</para>
<para>The Hayes driver is not smart enough to recognize some of the
advanced features of newer modems—messages like
<literal>BUSY</literal>, <literal>NO DIALTONE</literal>, or
<literal>CONNECT 115200</literal> will just confuse it. You should
turn those messages off when you use <command>tip</command> (using
<command>ATX0&W</command>).</para>
<para>Also, the dial timeout for <command>tip</command> is 60 seconds.
Your modem should use something less, or else tip will think there is
a communication problem. Try <command>ATS7=45&W</command>.</para>
<para>Actually, as shipped <command>tip</command> does not yet support
it fully. The solution is to edit the file
<filename>tipconf.h</filename> in the directory
<filename>/usr/src/usr.bin/tip/tip</filename> Obviously you need the
source distribution to do this.</para>
<para>Edit the line <literal>#define HAYES 0</literal> to
<literal>#define HAYES 1</literal>. Then <command>make</command> and
<command>make install</command>. Everything works nicely after
that.</para>
</sect2>
<sect2 id="direct-at">
<title>How am I expected to enter these AT commands?</title>
<para>Make what is called a <quote>direct</quote> entry in your
<filename>/etc/remote</filename> file. For example, if your modem is
hooked up to the first serial port, <filename>/dev/cuaa0</filename>,
then put in the following line:</para>
<programlisting>
cuaa0:dv=/dev/cuaa0:br#19200:pa=none</programlisting>
<para>Use the highest bps rate your modem supports in the br capability.
Then, type <command>tip cuaa0</command> and you will be connected to
your modem.</para>
<para>If there is no <filename>/dev/cuaa0</filename> on your system, do
this:</para>
<screen>&prompt.root; <userinput>cd /dev</userinput>
&prompt.root; <userinput>MAKEDEV cuaa0</userinput></screen>
<para>Or use cu as root with the following command:</para>
<screen>&prompt.root; <userinput>cu -l<replaceable>line</replaceable> -s<replaceable>speed</replaceable></userinput></screen>
<para><replaceable>line</replaceable> is the serial port
(e.g.<filename>/dev/cuaa0</filename>) and
<replaceable>speed</replaceable> is the speed
(e.g.<literal>57600</literal>). When you are done entering the AT
commands hit <command>~.</command> to exit.</para>
</sect2>
<sect2>
<title>The <literal>@</literal> sign for the pn capability does not
work!</title>
<para>The <literal>@</literal> sign in the phone number capability tells
tip to look in <filename>/etc/phones</filename> for a phone number.
But the <literal>@</literal> sign is also a special character in
capability files like <filename>/etc/remote</filename>. Escape it
with a backslash:</para>
<programlisting>
pn=\@</programlisting>
</sect2>
<sect2>
<title>How can I dial a phone number on the command line?</title>
<para>Put what is called a <quote>generic</quote> entry in your
<filename>/etc/remote</filename> file. For example:</para>
<programlisting>
tip115200|Dial any phone number at 115200 bps:\
:dv=/dev/cuaa0:br#115200:at=hayes:pa=none:du:
tip57600|Dial any phone number at 57600 bps:\
:dv=/dev/cuaa0:br#57600:at=hayes:pa=none:du:</programlisting>
<para>Then you can things like:</para>
<screen>&prompt.root; <userinput>tip -115200 5551234</userinput></screen>
<para>If you prefer <command>cu</command> over <command>tip</command>,
use a generic cu entry:</para>
<programlisting>
cu115200|Use cu to dial any number at 115200bps:\
:dv=/dev/cuaa1:br#57600:at=hayes:pa=none:du:</programlisting>
<para>and type:</para>
<screen>&prompt.root; <userinput>cu 5551234 -s 115200</userinput></screen>
</sect2>
<sect2>
<title>Do I have to type in the bps rate every time I do that?</title>
<para>Put in an entry for <literal>tip1200</literal> or
<literal>cu1200</literal>, but go ahead and use whatever bps rate is
appropriate with the br capability. <command>tip</command> thinks a
good default is 1200 bps which is why it looks for a
<literal>tip1200</literal> entry. You do not have to use 1200 bps,
though.</para>
</sect2>
<sect2>
<title>I access a number of hosts through a terminal server.</title>
<para>Rather than waiting until you are connected and typing
<command>CONNECT <host></command> each time, use tip's
<literal>cm</literal> capability. For example, these entries in
<filename>/etc/remote</filename>:</para>
<programlisting>
pain|pain.deep13.com|Forrester's machine:\
:cm=CONNECT pain\n:tc=deep13:
muffin|muffin.deep13.com|Frank's machine:\
:cm=CONNECT muffin\n:tc=deep13:
deep13:Gizmonics Institute terminal server:\
:dv=/dev/cua02:br#38400:at=hayes:du:pa=none:pn=5551234:</programlisting>
<para>will let you type <command>tip pain</command> or <command>tip
muffin</command> to connect to the hosts pain or muffin; and
<command>tip deep13</command> to get to the terminal server.</para>
</sect2>
<sect2>
<title>Can tip try more than one line for each site?</title>
<para>This is often a problem where a university has several modem lines
and several thousand students trying to use them...</para>
<para>Make an entry for your university in
<filename>/etc/remote</filename> and use <literal>@</literal> for the
<literal>pn</literal> capability:</para>
<programlisting>
big-university:\
:pn=\@:tc=dialout
dialout:\
:dv=/dev/cuaa3:br#9600:at=courier:du:pa=none:</programlisting>
<para>Then, list the phone numbers for the university in
<filename>/etc/phones</filename>:</para>
<programlisting>
big-university 5551111
big-university 5551112
big-university 5551113
big-university 5551114</programlisting>
<para><command>tip</command> will try each one in the listed order, then
give up. If you want to keep retrying, run <command>tip</command> in
a while loop.</para>
</sect2>
<sect2>
<title>Why do I have to hit CTRL+P twice to send CTRL+P once?</title>
<para>CTRL+P is the default <quote>force</quote> character, used to tell
<command>tip</command> that the next character is literal data. You
can set the force character to any other character with the
<command>~s</command> escape, which means <quote>set a
variable.</quote></para>
<para>Type
<command>~sforce=<replaceable>single-char</replaceable></command>
followed by a newline. <replaceable>single-char</replaceable> is any
single character. If you leave out
<replaceable>single-char</replaceable>, then the force character is
the nul character, which you can get by typing CTRL+2 or CTRL+SPACE.
A pretty good value for <replaceable>single-char</replaceable> is
SHIFT+CTRL+6, which I have seen only used on some terminal
servers.</para>
<para>You can have the force character be whatever you want by
specifying the following in your <filename>$HOME/.tiprc</filename>
file:</para>
<programlisting>
force=<single-char></programlisting>
</sect2>
<sect2>
<title>Suddenly everything I type is in UPPER CASE??</title>
<para>You must have pressed CTRL+A, <command>tip</command>'s
<quote>raise character,</quote> specially designed for people with
broken caps-lock keys. Use <command>~s</command> as above and set the
variable <literal>raisechar</literal> 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.</para>
<para>Here is a sample .tiprc file perfect for Emacs users who need to
type CTRL+2 and CTRL+A a lot:</para>
<programlisting>
force=^^
raisechar=^^</programlisting>
<para>The ^^ is SHIFT+CTRL+6.</para>
</sect2>
<sect2>
<title>How can I do file transfers with <command>tip</command>?</title>
<para>If you are talking to another UNIX system, you can send and
receive files with <command>~p</command> (put) and
<command>~t</command> (take). These commands run
<command>cat</command> and <command>echo</command> on the remote
system to accept and send files. The syntax is:</para>
<cmdsynopsis>
<command>~p</command>
<arg choice="plain">local-file</arg>
<arg choice="opt">remote-file</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>~t</command>
<arg choice="plain">remote-file</arg>
<arg choice="opt">local-file</arg>
</cmdsynopsis>
<para>There is no error checking, so you probably should use another
protocol, like zmodem.</para>
</sect2>
<sect2>
<title>How can I run zmodem with <command>tip</command>?</title>
<para>To receive files, start the sending program on the remote end.
Then, type <command>~C rz</command> to begin receiving them
locally.</para>
<para>To send files, start the receiving program on the remote end.
Then, type <command>~C sz <replaceable>files</replaceable></command>
to send them to the remote system.</para>
</sect2>
</sect1>
<sect1 id="serialconsole-setup">
<title>Setting Up the Serial Console</title>
<para><emphasis>&a.yokota; and &a.wpaul;:</emphasis></para>
<para><emphasis>The text is heavily based on
<filename>/sys/i386/boot/biosboot/README.serial</filename> written by
&a.wpaul;.</emphasis></para>
<sect2 id="serialconsole-intro">
<title>Introduction</title>
<para>The FreeBSD/i386 operating system can 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 FreeBSD on a dedicated file/compute/terminal server
machines that have no keyboard or monitor attached, and developers who
want to debug the kernel or device drivers.</para>
<para>Starting from version 3.1, FreeBSD/i386 employs a three stage
bootstrap. The first two stages are in the boot block code which is
stored at the beginning of the FreeBSD slice on the boot disk. The
boot block will then load and run the boot loader
(<filename>/boot/loader</filename>) as the third stage code. (See
&man.boot.8; and &man.loader.8; for more details on the boot
process.)</para>
<para>In order to set up the serial console you must configure the boot
block code, the boot loader code and the kernel.</para>
<para>In FreeBSD version 3.0, the boot loader does not exist and there
are only two stages in the bootstrap; the boot blocks directly load
the kernel into memory. If you are using FreeBSD 3.0, then you should
disregard any reference to the boot loader in this section. You can
still use the serial port as a console.</para>
<para>FreeBSD versions 2.X are quite different from 3.X, in that the
serial port driver, &man.sio.4;, must be configured in a different
way. This chapter will not describe the settings for version 2.X
systems. If you are using these older versions of FreeBSD, please
consult <filename>/sys/i386/boot/biosboot/README.serial</filename>
instead.</para>
</sect2>
<sect2 id="serialconsole-howto">
<title>6 Steps to Set up the Serial Console</title>
<procedure>
<step>
<para>Prepare a serial cable.</para>
<para>You will need either a null-modem cable or a standard serial
cable and a null-modem adapter. See <xref linkend="term"> for
a discussion on serial cables.</para>
</step>
<step>
<para>Unplug your keyboard.</para>
<para>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.</para>
<para>If your computer complains about the error, but boots anyway,
then you do not have to do anything special. (One machine with a
Phoenix BIOS that I have here merely says <errorname>Keyboard
failed</errorname> then continues to boot normally.)</para>
<para>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.</para>
<tip>
<para>Setting the keyboard to <quote>Not installed</quote> in the
BIOS setup does <emphasis>not</emphasis> 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 that it will not
complain if the keyboard is not plugged in. You can leave the
keyboard plugged in even with this flag set to <quote>Not
installed</quote> and the keyboard will still work.</para>
</tip>
<note>
<para>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. It is said that a
Gateway 2000 Pentium 90Mhz system with an AMI BIOS that behaves
this way. In general this is not a problem since the mouse is
not much good without the keyboard anyway.</para>
</note>
</step>
<step>
<para>Plug a dumb terminal into <devicename>COM1:</devicename>
(<devicename>sio0</devicename>).</para>
<para>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 <devicename>COM1:</devicename>
(<devicename>sio0</devicename>), get one. At this time, there is
no way to select a port other than <devicename>COM1:</devicename>
for the boot blocks without recompiling the boot blocks. If you
are already using <devicename>COM1:</devicename> for another
device, you will have to temporarily remove that device and
install a new boot block and kernel once you get FreeBSD up and
running. (It is assumed that <devicename>COM1:</devicename> will
be available on a file/compute/terminal server anyway; if you
really need <devicename>COM1:</devicename> for something else
(and you can not switch that something else to
<devicename>COM2:</devicename> (<devicename>sio1</devicename>)),
then you probably should not even be bothering with all this in
the first place.)</para>
</step>
<step>
<para>Make sure the configuration file of your kernel has
appropriate flags set for <devicename>COM1:</devicename>
(<devicename>sio0</devicename>).</para>
<para>Relevant flags are:</para>
<variablelist>
<varlistentry>
<term><literal>0x10</literal></term>
<listitem>
<para>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 <option>-h</option> option
described below, together with this flag.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>0x20</literal></term>
<listitem>
<para>Forces this unit to be the console (unless there is
another higher priority console), regardless of the
<option>-h</option> option discussed below. This flag
replaces the <literal>COMCONSOLE</literal> option in FreeBSD
versions 2.X. The flag <literal>0x20</literal> must be used
together with the <option>0x10</option> flag.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>0x40</literal></term>
<listitem>
<para>Reserves this unit (in conjunction with
<literal>0x10</literal>) 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. The
only use of this flag is to designate the unit for kernel
remote debugging. See <xref linkend="kerneldebug"> for more
information on remote debugging.</para>
<note>
<para>In FreeBSD 4.0-CURRENT or later the semantics of the
flag <literal>0x40</literal> are slightly different and
there is another flag to specify a serial port for remote
debugging.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
<para>Example:</para>
<programlisting>
device sio0 at isa? port "IO_COM1" tty flags 0x10 irq 4</programlisting>
<para>See &man.sio.4; for more details.</para>
<para>If the flags were not set, you need to run UserConfig (on a
different console) or recompile the kernel.</para>
</step>
<step>
<para>Create <filename>boot.config</filename> in the root directory
of the <literal>a</literal> partition on the boot drive.</para>
<para>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:</para>
<variablelist>
<varlistentry>
<term><option>-h</option></term>
<listitem>
<para>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
<option>-h</option> 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
<option>-h</option> to tell the boot loader and the kernel
to use the video display as the console instead.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-D</option></term>
<listitem>
<para>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 <option>-h</option> 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 <option>-h</option> option.
However, 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
<option>-h</option> option becomes the only console.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-P</option></term>
<listitem>
<para>Makes the boot block probe the keyboard. If no keyboard
is found, the <option>-D</option> and <option>-h</option>
options are automatically set.</para>
<note>
<para>Due to space constraints in the current version of the
boot blocks, the <option>-P</option> 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 to
be the case with your system, you have to abandon using
the <option>-P</option> option. Unfortunately there is no
workaround for this problem.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
<para>Use either the <option>-P</option> option to select the
console automatically, or the <option>-h</option> option to
activate the serial console.</para>
<para>You may include other options described in &man.boot.8; as
well.</para>
<para>The options, except for <option>-P</option>, will be passed to
the boot loader (<filename>/boot/loader</filename>). The boot
loader will determine which of the internal video or the serial
port should become the console by examining the state of the
<option>-h</option> option alone. This means that if you specify
the <option>-D</option> option but not the <option>-h</option>
option in <filename>/boot.config</filename>, 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.</para>
</step>
<step>
<para>Boot the machine.</para>
<para>When you start your FreeBSD box, the boot blocks will echo the
contents of <filename>/boot.config</filename> to the console. For
example;</para>
<screen>/boot.config: -P
Keyboard: no</screen>
<para>The second line appears only if you put <option>-P</option> in
<filename>/boot.config</filename> and indicates presence/absence
of the keyboard. These messages go to either serial or internal
console, or both, depending on the option in
<filename>/boot.config</filename>.</para>
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Options</entry>
<entry>Message goes to</entry>
</row>
</thead>
<tbody>
<row>
<entry>none</entry>
<entry>internal console</entry>
</row>
<row>
<entry><option>-h</option></entry>
<entry>serial console</entry>
</row>
<row>
<entry><option>-D</option></entry>
<entry>serial and internal consoles</entry>
</row>
<row>
<entry><option>-Dh</option></entry>
<entry>serial and internal consoles</entry>
</row>
<row>
<entry><option>-P</option>, keyboard present</entry>
<entry>internal console</entry>
</row>
<row>
<entry><option>-P</option>, keyboard absent</entry>
<entry>serial console</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>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.</para>
<para>Hit any key, other than Enter/Return, at the console to
interrupt the boot process. The boot blocks will then prompt you
for further action. You should now see something like:</para>
<screen>>> FreeBSD/i386 BOOT
Default: 0:wd(0,a)/boot/loader
boot:</screen>
<para>Verify the above message appears on either the serial or
internal console or both, according to the options you put in
<filename>/boot.config</filename>. If the message appears in the
correct console, hit Enter/Return to continue the boot
process.</para>
<para>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 <option>-h</option> 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.</para>
</step>
</procedure>
<para>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 <xref linkend="serialconsole-loader">.</para>
</sect2>
<sect2 id="serialconsole-summary">
<title>Summary</title>
<para>Here is the summary of various settings discussed in this section
and the console eventually selected.</para>
<sect3>
<title>Case 1: You set the flags to 0x10 for sio0</title>
<programlisting>device sio0 at isa? port "IO_COM1" tty flags 0x10 irq 4</programlisting>
<informaltable frame="none">
<tgroup cols="4">
<thead>
<row>
<entry>Options in /boot.config</entry>
<entry>Console during boot blocks</entry>
<entry>Console during boot loader</entry>
<entry>Console in kernel</entry>
</row>
</thead>
<tbody>
<row>
<entry>nothing</entry>
<entry>internal</entry>
<entry>internal</entry>
<entry>internal</entry>
</row>
<row>
<entry><option>-h</option></entry>
<entry>serial</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-D</option></entry>
<entry>serial and internal</entry>
<entry>internal</entry>
<entry>internal</entry>
</row>
<row>
<entry><option>-Dh</option></entry>
<entry>serial and internal</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-P</option>, keyboard present</entry>
<entry>internal</entry>
<entry>internal</entry>
<entry>internal</entry>
</row>
<row>
<entry><option>-P</option>, keyboard absent</entry>
<entry>serial and internal</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect3>
<sect3>
<title>Case 2: You set the flags to 0x30 for sio0</title>
<programlisting>device sio0 at isa? port "IO_COM1" tty flags 0x30 irq 4</programlisting>
<informaltable frame="none">
<tgroup cols="4">
<thead>
<row>
<entry>Options in /boot.config</entry>
<entry>Console during boot blocks</entry>
<entry>Console during boot loader</entry>
<entry>Console in kernel</entry>
</row>
</thead>
<tbody>
<row>
<entry>nothing</entry>
<entry>internal</entry>
<entry>internal</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-h</option></entry>
<entry>serial</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-D</option></entry>
<entry>serial and internal</entry>
<entry>internal</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-Dh</option></entry>
<entry>serial and internal</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-P</option>, keyboard present</entry>
<entry>internal</entry>
<entry>internal</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-P</option>, keyboard absent</entry>
<entry>serial and internal</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect3>
</sect2>
<sect2 id="serialconsole-tips">
<title>Tips for the Serial Console</title>
<sect3>
<title>Setting A Faster Serial Port Speed</title>
<para>By default the serial port settings are set to 9600 baud, 8
bits, no parity, 1 stop bit. If you wish to change the speed, you
need to recompile at least the boot blocks. Add the following line
to <filename>/etc/make.conf</filename> and compile new boot
blocks:</para>
<programlisting>BOOT_COMCONSOLE_SPEED=19200</programlisting>
<para>If the serial console is configured in some other way than by
booting with <option>-h</option>, 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:</para>
<programlisting>options CONSPEED=19200</programlisting>
</sect3>
<sect3 id="serialconsole-com2">
<title>Using Serial Port Other Than <devicename>sio0</devicename> For
The Console</title>
<para>Using a port other than <devicename>sio0</devicename> 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.</para>
<procedure>
<step>
<para>Get the kernel source.</para>
</step>
<step>
<para>Edit <filename>/etc/make.conf</filename> and set
<literal>BOOT_COMCONSOLE_PORT</literal> to the address of the
port you want to use (0x3F8, 0x2F8, 0x3E8 or 0x2E8). Only
<devicename>sio0</devicename> through
<devicename>sio3</devicename> (<devicename>COM1:</devicename>
through <devicename>COM4:</devicename>) can be used; multiport
serial cards will not work. No interrupt setting is
needed.</para>
</step>
<step>
<para>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 <devicename>sio1</devicename>
(<devicename>COM2:</devicename>) the console:</para>
<programlisting>device sio1 at isa? port "IO_COM2" tty flags 0x10 irq 3</programlisting>
<para>or</para>
<programlisting>device sio1 at isa? port "IO_COM2" tty flags 0x30 irq 3</programlisting>
<para>The console flags for the other serial ports should not be
set.</para>
</step>
<step>
<para>Recompile and install the boot blocks:</para>
<screen>&prompt.root; <userinput>cd /sys/boot/i386/boot2</userinput>
&prompt.root; <userinput>make</userinput>
&prompt.root; <userinput>make install</userinput></screen>
</step>
<step>
<para>Recompile and install the boot loader:</para>
<screen>&prompt.root; <userinput>cd /sys/boot/i386/loader</userinput>
&prompt.root; <userinput>make</userinput>
&prompt.root; <userinput>make install</userinput></screen>
</step>
<step>
<para>Rebuild and install the kernel.</para>
</step>
<step>
<para>Write the boot blocks to the boot disk with
&man.disklabel.8; and boot from the new kernel.</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Entering the DDB Debugger from the Serial Line</title>
<para>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:</para>
<programlisting>options BREAK_TO_DEBUGGER
options DDB</programlisting>
</sect3>
<sect3>
<title>Getting a Login Prompt on the Serial Console</title>
<para>While this is not required, you may wish to get a
<emphasis>login</emphasis> 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.</para>
<para>Open the file <filename>/etc/ttys</filename> with an editor
and locate the lines:</para>
<programlisting>ttyd0 "/usr/libexec/getty std.9600" unknown off secure
ttyd1 "/usr/libexec/getty std.9600" unknown off secure
ttyd2 "/usr/libexec/getty std.9600" unknown off secure
ttyd3 "/usr/libexec/getty std.9600" unknown off secure</programlisting>
<para><literal>ttyd0</literal> through <literal>ttyd3</literal>
corresponds to <devicename>COM1</devicename> through
<devicename>COM4</devicename>. Change <literal>off</literal> to
<literal>on</literal> for the desired port. If you have changed the
speed of the serial port, you need to change
<literal>std.9600</literal> to match the current setting, e.g.
<literal>std.19200</literal>.</para>
<para>You may also want to change the terminal type from
<literal>unknown</literal> to the actual type of your serial
terminal.</para>
<para>After editing the file, you must <command>kill -HUP 1</command>
to make this change take effect.</para>
</sect3>
</sect2>
<sect2 id="serialconsole-loader">
<title>Changing Console from the Boot Loader</title>
<para>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 as 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.</para>
<sect3>
<title>Setting Up the Serial Console</title>
<para>You can easily specify the boot loader and the kernel to use the
serial console by writing just one line in
<filename>/boot/loader.rc</filename>:</para>
<programlisting>set console=comconsole</programlisting>
<para>This will take effect regardless of the settings in the boot
block discussed in the previous section.</para>
<para>You had better put the above line as the first line of
<filename>/boot/loader.rc</filename> so as to see boot messages on
the serial console as early as possible.</para>
<para>Likewise, you can specify the internal console as:</para>
<programlisting>set console=vidconsole</programlisting>
<para>If you do not set the boot loader environment variable
<envar>console</envar>, the boot loader, and subsequently the
kernel, will use whichever console indicated by the
<option>-h</option> option in the boot block.</para>
<para>In versions 3.2 or later, you may specify the console in
<filename>/boot/loader.conf.local</filename> or
<filename>/boot/loader.conf</filename>, rather than in
<filename>/boot/loader.rc</filename>. In this method your
<filename>/boot/loader.rc</filename> should look like:</para>
<programlisting>include /boot/loader.4th
start</programlisting>
<para>Then, create <filename>/boot/loader.conf.local</filename> and
put the following line there.</para>
<programlisting>console=comconsole</programlisting>
<para>or</para>
<programlisting>console=vidconsole</programlisting>
<para>See &man.loader.conf.5; for more information.</para>
<note>
<para>At the moment, the boot loader has no option equivalent to the
<option>-P</option> 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.</para>
</note>
</sect3>
<sect3>
<title>Using Serial Port Other than <devicename>sio0</devicename> for
the Console</title>
<para>You need to recompile the boot loader to use a serial port other
than <devicename>sio0</devicename> for the serial console. Follow the
procedure described in <xref linkend="serialconsole-com2">.</para>
</sect3>
</sect2>
<sect2 id="serialconsole-caveats">
<title>Caveats</title>
<para>The idea here is to allow people to set up dedicated servers that
require no graphics hardware or attached keyboards. Unfortunately,
while (most?) every system 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.'</para>
<para>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'll have to leave some kind of graphics card plugged in,
(even if it's just a junky mono board) although you will not have to
attach a monitor into it. You might also try installing an AMI
BIOS.</para>
</sect2>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->
|