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
|
<!--
The FreeBSD Documentation Project
$FreeBSD$
-->
<chapter id="kernelconfig">
<chapterinfo>
<authorgroup>
<author>
<firstname>Jim</firstname>
<surname>Mock</surname>
<contrib>Updated and restructured by </contrib>
<!-- Mar 2000 -->
</author>
</authorgroup>
<authorgroup>
<author>
<firstname>Jake</firstname>
<surname>Hamby</surname>
<contrib>Originally contributed by </contrib>
<!-- 6 Oct 1995 -->
</author>
</authorgroup>
</chapterinfo>
<title>Configuring the FreeBSD Kernel</title>
<sect1>
<title>Synopsis</title>
<indexterm>
<primary>kernel</primary>
<secondary>building a custom kernel</secondary>
</indexterm>
<para>The kernel is the core of the FreeBSD operating system. It is
responsible for managing memory, enforcing security controls,
networking, disk access, and much more. While more and more of FreeBSD
becomes dynamically configurable it is still occasionally necessary to
reconfigure and recompile your kernel.</para>
<para>After reading this chapter, you will know:</para>
<itemizedlist>
<listitem>
<para>Why you might need to build a custom kernel.</para>
</listitem>
<listitem>
<para>How to write a kernel configuration file, or alter an existing
configuration file.</para>
</listitem>
<listitem>
<para>How to use the kernel configuration file to create and build a
new kernel.</para>
</listitem>
<listitem>
<para>How to install the new kernel.</para>
</listitem>
<listitem>
<para>How to create any entries in <filename>/dev</filename> that may
be required.</para>
</listitem>
<listitem>
<para>How to troubleshoot if things go wrong.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Why Build a Custom Kernel?</title>
<para>Traditionally, FreeBSD has had what is called a
<quote>monolithic</quote> kernel. This means that the kernel was one
large program, supported a fixed list of devices, and if you wanted to
change the kernel's behavior then you had to compile a new kernel, and
then reboot your computer with the new kernel.</para>
<para>Today, FreeBSD is rapidly moving to a model where much of the
kernel's functionality is contained in modules which can be dynamically
loaded and unloaded from the kernel as necessary. This allows the
kernel to adapt to new hardware suddenly becoming available (such as
PCMCIA cards in a laptop), or for new functionality to be brought in to
the kernel that was not necessary when the kernel was originally
compiled. Colloquially these are called KLDs.</para>
<para>Despite this, it is still necessary to carry out some static kernel
configuration. In some cases this is because the functionality is so
tied to the kernel that it can not be made dynamically loadable. In
others it may simply be because no one has yet taken the time to write a
dynamic loadable kernel module for that functionality yet.</para>
<para>Building a custom kernel is one of the most important rites of
passage nearly every Unix user must endure. This process, while
time consuming, will provide many benefits to your FreeBSD system.
Unlike the <filename>GENERIC</filename> kernel, which must support a
wide range of hardware, a custom kernel only contains support for
<emphasis>your</emphasis> PC's hardware. This has a number of
benefits, such as:</para>
<itemizedlist>
<listitem>
<para>Faster boot time. Since the kernel will only probe the
hardware you have on your system, the time it takes your system to
boot will decrease dramatically.</para>
</listitem>
<listitem>
<para>Less memory usage. A custom kernel often uses less memory
than the <literal>GENERIC</literal> kernel, which is important
because the kernel must always be present in real
memory. For this reason, a custom kernel is especially useful
on a system with a small amount of RAM.</para>
</listitem>
<listitem>
<para>Additional hardware support. A custom kernel allows you to
add in support for devices such as sound cards, which are not
present in the <literal>GENERIC</literal> kernel.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="kernelconfig-building">
<title>Building and Installing a Custom Kernel</title>
<indexterm>
<primary>kernel</primary>
<secondary>building / installing</secondary>
</indexterm>
<para>First, let us take a quick tour of the kernel build directory.
All directories mentioned will be relative to the main
<filename>/usr/src/sys</filename> directory, which is also
accessible through <filename>/sys</filename>. There are a number of
subdirectories here representing different parts of the kernel, but
the most important, for our purposes, are
<filename><replaceable>arch</replaceable>/conf</filename>, where you
will edit your custom kernel configuration, and
<filename>compile</filename>, which is the staging area where your
kernel will be built. <replaceable>arch</replaceable> represents
either <filename>i386</filename>, <filename>alpha</filename>, or
<filename>pc98</filename> (an alternative development branch of PC
hardware, popular in Japan). Everything inside a particular
architecture's directory deals with that architecture only; the rest
of the code is common to all platforms to which FreeBSD could
potentially be ported. Notice the logical organization of the
directory structure, with each supported device, filesystem, and
option in its own subdirectory.</para>
<note>
<para>If there is <emphasis>not</emphasis> a
<filename>/usr/src/sys</filename> directory on your system, then
the kernel source has not been installed. The easiest way to
do this is by running <command>/stand/sysinstall</command> as
<username>root</username>, choosing <literal>Configure</literal>,
then <literal>Distributions</literal>, then
<literal>src</literal>, then <literal>sys</literal>. If you
have an aversion to <application>sysinstall</application> and
you have access to an <quote>official</quote> FreeBSD CDROM, then
you can also install the source from the command line :</para>
<screen>&prompt.root; <userinput>mount</userinput> /cdrom
&prompt.root; <userinput>mkdir -p</userinput> <filename>/usr/src/sys</filename>
&prompt.root; <userinput>ln -s</userinput> /usr/src/sys /sys
&prompt.root; <userinput>cat /cdrom/sys/ssys.[a-d]* | tar -xzvf</userinput></screen>
</note>
<para>Next, move to the
<filename><replaceable>arch</replaceable>/conf</filename> directory
and copy the <filename>GENERIC</filename> configuration file to the
name you want to give your kernel. For example:</para>
<screen>&prompt.root; <userinput>cd /usr/src/sys/i386/conf</userinput>
&prompt.root; <userinput>cp GENERIC MYKERNEL</userinput></screen>
<para>Traditionally, this name is in all capital letters and, if you
are maintaining multiple FreeBSD machines with different hardware,
it is a good idea to name it after your machine's hostname. We will
call it <filename>MYKERNEL</filename> for the purpose of this
example.</para>
<tip>
<para>Storing your kernel config file directly under
<filename>/usr/src</filename> can be a bad idea. If you are
experiencing problems it can be tempting to just delete
<filename>/usr/src</filename> and start again. Five seconds after
you do that you realize that you have deleted your custom kernel
config file.</para>
<para>You might want to keep your kernel config file elsewhere, and then
create a symbolic link to the file in the <filename>i386</filename>
directory.</para>
<para>For example:</para>
<screen>&prompt.root; <userinput>cd /usr/src/sys/i386/conf</userinput>
&prompt.root; <userinput>mkdir /root/kernels</userinput>
&prompt.root; <userinput>cp GENERIC /root/kernels/<replaceable>MYKERNEL</replaceable></userinput>
&prompt.root; <userinput>ln -s /root/kernels/<replaceable>MYKERNEL</replaceable></userinput></screen>
</tip>
<note>
<para>You must execute these and all of the following commands under
the root account or you will get <errortype>permission
denied</errortype> errors.</para>
</note>
<para>Now, edit <filename>MYKERNEL</filename> with your favorite text
editor. If you are just starting out, the only editor available
will probably be <command>vi</command>, which is too complex to
explain here, but is covered well in many books in the <link
linkend="bibliography">bibliography</link>. However, FreeBSD does
offer an easier editor called <quote>ee</quote> which, if you are a
beginner, should be your editor of choice. Feel free to change the
comment lines at the top to reflect your configuration or the
changes you have made to differentiate it from
<filename>GENERIC</filename>.</para>
<indexterm><primary>SunOS</primary></indexterm>
<para>If you have built a kernel under SunOS or some other BSD
operating system, much of this file will be very familiar to you.
If you are coming from some other operating system such as DOS, on
the other hand, the <filename>GENERIC</filename> configuration file
might seem overwhelming to you, so follow the descriptions in the
<link linkend="kernelconfig-config">Configuration File</link>
section slowly and carefully.</para>
<note>
<para>Be sure to always check the file
<filename>/usr/src/UPDATING</filename>, before you perform any update
steps, in the case you <link
linkend="cutting-edge">sync your source-tree</link> with the
latest sources of the FreeBSD project.
In this file all important issues with updating FreeBSD
are written down. <filename>/usr/src/UPDATING</filename> always fits
to your version of the FreeBSD source, and is therefore more accurate
for those information than the handbook.</para>
</note>
<para>You must now compile the source code for the kernel. There are two
procedures you can use to do this, and the one you will use depends on
why you are rebuilding the kernel, and the version of FreeBSD you are
running.</para>
<itemizedlist>
<listitem>
<para>If you have installed <emphasis>only</emphasis> the kernel
source code, use procedure 1.</para>
</listitem>
<listitem>
<para>If you are running a FreeBSD version prior to 4.0, and you are
<emphasis>not</emphasis> upgrading to FreeBSD 4.0 or higher using
the <quote>make world</quote> procedure, use procedure 1.</para>
</listitem>
<listitem>
<para>If you are building a new kernel without updating the source
code (perhaps just to add a new option, such as
<literal>IPFIREWALL</literal>) you can use either procedure.</para>
</listitem>
<listitem>
<para>If you are rebuilding the kernel as part of a <quote>make
world</quote> process, use procedure 2.</para>
</listitem>
</itemizedlist>
<procedure>
<title>Procedure 1. Building a kernel the <quote>traditional</quote> way</title>
<step>
<para>Run &man.config.8; to generate the kernel source code.</para>
<screen>&prompt.root; <userinput>/usr/sbin/config <replaceable>MYKERNEL</replaceable></userinput></screen>
</step>
<step>
<para>Change in to the build directory.</para>
<screen>&prompt.root; <userinput>cd ../../compile/<replaceable>MYKERNEL</replaceable></userinput></screen>
</step>
<step>
<para>Compile the kernel.</para>
<screen>&prompt.root; <userinput>make depend</userinput>
&prompt.root; <userinput>make</userinput></screen>
</step>
<step>
<para>Install the new kernel.</para>
<screen>&prompt.root; <userinput>make install</userinput></screen>
</step>
</procedure>
<procedure>
<title>Procedure 2. Building a kernel the <quote>new</quote>
way</title>
<step>
<para>Change to the <filename>/usr/src</filename> directory</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>
</step>
<step>
<para>Compile the kernel.</para>
<screen>&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
</step>
<step>
<para>Install the new kernel.</para>
<screen>&prompt.root; <userinput>make installkernel KERNCONF=MYKERNEL</userinput></screen>
</step>
</procedure>
<note>
<para>In FreeBSD 4.2 and older you must replace
<literal>KERNCONF=</literal> with <literal>KERNEL=</literal>.
4.2-STABLE that was fetched after Feb 2nd, 2001 does
recognize <literal>KERNCONF=</literal></para>
</note>
<indexterm>
<primary><command>cvsup</command></primary>
</indexterm>
<indexterm><primary>anonymous CVS</primary></indexterm>
<indexterm><primary>CTM</primary></indexterm>
<indexterm>
<primary>CVS</primary>
<secondary>anonymous</secondary>
</indexterm>
<para>If you have <emphasis>not</emphasis> upgraded your source
tree in any way (you have not run <application>CVSup</application>,
<application>CTM</application>, or used
<application>anoncvs</application>), then you should use the
<command>config</command>, <command>make depend</command>,
<command>make</command>, <command>make install</command> sequence.</para>
<indexterm>
<primary><filename>kernel.old</filename></primary>
</indexterm>
<para>The new kernel will be copied to the root directory as
<filename>/kernel</filename> and the old kernel will be moved to
<filename>/kernel.old</filename>. Now, shutdown the system and
reboot to use your kernel. In case something goes wrong, there are
some <link linkend="kernelconfig-trouble">troubleshooting</link>
instructions at the end of this chapter. Be sure to read the
section which explains how to recover in case your new kernel <link
linkend="kernelconfig-noboot">does not boot</link>.</para>
<note>
<para>If you have added any new devices (such as sound cards) you
may have to add some <link linkend="kernelconfig-nodes">device
nodes</link> to your <filename>/dev</filename> directory before
you can use them. For more information, take a look at "Making
Device Nodes" later on in this chapter.</para>
</note>
</sect1>
<sect1 id="kernelconfig-config">
<title>The Configuration File</title>
<indexterm>
<primary>kernel</primary>
<secondary>LINT</secondary>
</indexterm>
<indexterm><primary>LINT</primary></indexterm>
<indexterm>
<primary>kernel</primary>
<secondary>config file</secondary>
</indexterm>
<para>The general format of a configuration file is quite simple.
Each line contains a keyword and one or more arguments. For
simplicity, most lines only contain one argument. Anything
following a <literal>#</literal> is considered a comment and
ignored. The following sections describe each keyword, generally in
the order they are listed in <filename>GENERIC</filename>, although
some related keywords have been grouped together in a single section
(such as Networking) even though they are actually scattered
throughout the <filename>GENERIC</filename> file. <anchor
id="kernelconfig-options"> An exhaustive list of options and more
detailed explanations of the device lines is present in the
<filename>LINT</filename> configuration file, located in the same
directory as <filename>GENERIC</filename>. If you are in doubt as
to the purpose or necessity of a line, check first in
<filename>LINT</filename>.</para>
<important>
<title>Quoting numbers</title>
<para>In all versions of FreeBSD up to and including 3.X,
&man.config.8; required that any strings in the configuration file
that contained numbers used as text had to be enclosed in double
quotes.</para>
<para>This requirement was removed in the 4.X branch, which this
book covers, so if you are on a pre-4.X system, see the
<filename>/usr/src/sys/i386/conf/LINT</filename> and
<filename>/usr/src/sys/i386/conf/GENERIC</filename>
files on your system for examples.</para>
</important>
<indexterm>
<primary>kernel</primary>
<secondary>example config file</secondary>
</indexterm>
<para>The following is an example <filename>GENERIC</filename> kernel
configuration file with various additional comments where needed for
clarity. This example should match your copy in
<filename>/usr/src/sys/i386/conf/GENERIC</filename> fairly
closely. For details of all the possible kernel options, see
<filename>/usr/src/sys/i386/conf/LINT</filename>.</para>
<programlisting>#
# GENERIC -- Generic kernel configuration file for FreeBSD/i386
#
# For more information on this file, please read the handbook section on
# Kernel Configuration Files:
#
# http://www.FreeBSD.org/handbook/kernelconfig-config.html
#
# The handbook is also available locally in /usr/share/doc/handbook
# if you've installed the doc distribution, otherwise always see the
# FreeBSD World Wide Web server (http://www.FreeBSD.ORG/) for the
# latest information.
#
# An exhaustive list of options and more detailed explanations of the
# device lines is also present in the ./LINT configuration file. If you are
# in doubt as to the purpose or necessity of a line, check first in LINT.
#
# $FreeBSD: src/sys/i386/conf/GENERIC,v 1.246 2000/03/09 16:32:55 jlemon Exp $</programlisting>
<para>The following are the mandatory keywords required in
<emphasis>every</emphasis> kernel you build:</para>
<indexterm>
<primary>kernel options</primary>
<secondary>machine</secondary>
</indexterm>
<programlisting>machine i386</programlisting>
<para>This is the machine architecture. It must be either
<literal>i386</literal>, <literal>alpha</literal>, or
<literal>pc98</literal>.</para>
<indexterm>
<primary>kernel options</primary>
<secondary>cpu</secondary>
</indexterm>
<programlisting>cpu I386_CPU
cpu I486_CPU
cpu I586_CPU
cpu I686_CPU</programlisting>
<para>The above specifies the type of CPU you have in your system.
You may have multiple instances of the CPU line (i.e., you are not
sure whether you should use <literal>I586_CPU</literal> or
<literal>I686_CPU</literal>), however, for a custom kernel, it is
best to specify only the CPU you have. If you are unsure of your CPU type,
you can use the <command>dmesg</command> command to
view your boot up messages.</para>
<indexterm>
<primary>kernel options</primary>
<secondary>cpu type</secondary>
</indexterm>
<para>The Alpha architecture has different values for
<literal>cpu</literal>. They include:</para>
<programlisting>cpu EV4
cpu EV5</programlisting>
<para>If you are using an Alpha machine, you should be using one of
the above CPU types.</para>
<indexterm>
<primary>kernel options</primary>
<secondary>ident</secondary>
</indexterm>
<programlisting>ident GENERIC</programlisting>
<para>This is the identification of the kernel. You should change
this to whatever you named your kernel, as in our previous example,
<literal>MYKERNEL</literal>. The value you put in the
<literal>ident</literal> string will print when you boot up the
kernel, so it is useful to give the new kernel a different name if you
want to keep it separate from your usual kernel (i.e., you want to
build an experimental kernel).</para>
<indexterm>
<primary>kernel options</primary>
<secondary>maxusers</secondary>
</indexterm>
<programlisting>maxusers <replaceable>n</replaceable></programlisting>
<para>The <literal>maxusers</literal> option sets the size of a number
of important system tables. This number is supposed to be roughly
equal to the number of simultaneous users you expect to have on your
machine.</para>
<para>Starting with FreeBSD 4.5, the system will auto-tune this setting
for you if you explicitly set it to <literal>0</literal><footnote>
<para>The auto-tuning algorithm sets <literal>maxuser</literal> equal
to the amount of memory in the system, with a minimum of 32, and a
maximum of 384.</para></footnote>. If you are
using an earlier version of FreeBSD, or you want to manage it
yourself you will want to set
<literal>maxusers</literal> to at least 4, especially if you are
using the X Window System or compiling software. The reason is that
the most important table set by <literal>maxusers</literal> is the
maximum number of processes, which is set to <literal>20 + 16 *
maxusers</literal>, so if you set <literal>maxusers</literal> to 1,
then you can only have 36 simultaneous processes, including the 18
or so that the system starts up at boot time, and the 15 or so you
will probably create when you start the X Window System. Even a
simple task like reading a manual page will start up nine processes to
filter, decompress, and view it. Setting
<literal>maxusers</literal> to 64 will allow you to have up to 1044
simultaneous processes, which should be enough for nearly all uses.
If, however, you see the dreaded <errortype>proc table
full</errortype> error when trying to start another program, or are
running a server with a large number of simultaneous users (like
<hostid role="fqdn">ftp.FreeBSD.org</hostid>), you can always
increase the number and rebuild.</para>
<note>
<para><literal>maxusers</literal> does <emphasis>not</emphasis>
limit the number of users which can log into your machine. It
simply sets various table sizes to reasonable values considering
the maximum number of users you will likely have on your system
and how many processes each of them will be running. One keyword
which <emphasis>does</emphasis> limit the number of simultaneous
<emphasis>remote logins</emphasis> is <link
linkend="kernelconfig-ptys"><literal>pseudo-device pty
16</literal></link>.</para>
</note>
<programlisting># Floating point support - do not disable.
device npx0 at nexus? port IO_NPX irq 13</programlisting>
<para><literal>npx0</literal> is the interface to the floating point
math unit in FreeBSD, which is either the hardware co-processor or
the software math emulator. This is <emphasis>not</emphasis>
optional.</para>
<programlisting># Pseudo devices - the number indicates how many units to allocate.
pseudo-device loop # Network loopback</programlisting>
<para>This is the generic loopback device for TCP/IP. If you telnet
or FTP to <hostid>localhost</hostid> (a.k.a., <hostid
role="ipaddr">127.0.0.1</hostid>) it will come back at you through
this pseudo-device. This is <emphasis>mandatory</emphasis>.</para>
<para>Everything that follows is more or less optional. See the notes
underneath or next to each option for more information.</para>
<programlisting>#makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols
options MATH_EMULATE #Support for x87 emulation</programlisting>
<para>This line allows the kernel to simulate a math co-processor if
your computer does not have one (386 or 486SX). If you have a
486DX, or a 386 or 486SX (with a separate 387 or 487 chip), or
higher (Pentium, Pentium II, etc.), you can comment this line
out.</para>
<note>
<para>The normal math co-processor emulation routines that come with
FreeBSD are <emphasis>not</emphasis> very accurate. If you do not
have a math co-processor, and you need the best accuracy, it is
recommended that you change this option to
<literal>GPL_MATH_EMULATE</literal> to use the GNU math support,
which is not included by default for licensing reasons.</para>
</note>
<programlisting>options INET #InterNETworking</programlisting>
<para>Networking support. Leave this in, even if you do not plan to
be connected to a network. Most programs require at least loopback
networking (i.e., making network connections within your PC), so
this is essentially mandatory.</para>
<programlisting>options INET6 #IPv6 communications protocols</programlisting>
<para>This enables the IPv6 communication protocols.</para>
<programlisting>options FFS #Berkeley Fast Filesystem
options FFS_ROOT #FFS usable as root device [keep this!]</programlisting>
<para>This is the basic hard drive filesystem. Leave it in if you
boot from the hard disk.</para>
<programlisting>options UFS_DIRHASH #Improve performance on big directories</programlisting>
<para>This option includes some code to speed up disk operations on large
directories, at the expense of using a some additional memory. You
would normally keep this for a large server, or interactive workstation,
and remove it if you are using FreeBSD on a smaller system where memory
is at a premium and disk access speed is less important, such as a
firewall.</para>
<programlisting>options MFS #Memory Filesystem
options MD_ROOT #MD is a potential root device</programlisting>
<para>This is the memory-mapped filesystem. This is basically a RAM
disk for fast storage of temporary files, useful if you have a lot
of swap space that you want to take advantage of. A perfect place
to mount an MFS partition is on the <filename>/tmp</filename>
directory, since many programs store temporary data here. To mount
an MFS RAM disk on <filename>/tmp</filename>, add the following line
to <filename>/etc/fstab</filename>:</para>
<informalexample>
<programlisting>/dev/ad1s2b /tmp mfs rw 0 0</programlisting>
</informalexample>
<para>Now you simply need to either reboot, or run the command
<command>mount /tmp</command>.</para>
<indexterm>
<primary>kernel options</primary>
<secondary>NFS</secondary>
</indexterm>
<indexterm>
<primary>kernel options</primary>
<secondary>NFS_ROOT</secondary>
</indexterm>
<programlisting>options NFS #Network Filesystem
options NFS_ROOT #NFS usable as root device, NFS required</programlisting>
<para>The network filesystem. Unless you plan to mount partitions
from a Unix file server over TCP/IP, you can comment these
out.</para>
<indexterm>
<primary>kernel options</primary>
<secondary>MSDOSFS</secondary>
</indexterm>
<programlisting>options MSDOSFS #MSDOS Filesystem</programlisting>
<para>The MS-DOS filesystem. Unless you plan to mount a DOS formatted
hard drive partition at boot time, you can safely comment this out.
It will be automatically loaded the first time you mount a DOS
partition, as described above. Also, the excellent
<application>mtools</application> software (in the ports collection)
allows you to access DOS floppies without having to mount and
unmount them (and does not require <literal>MSDOSFS</literal> at
all).</para>
<programlisting>options CD9660 #ISO 9660 Filesystem
options CD9660_ROOT #CD-ROM usable as root, CD9660 required</programlisting>
<para>The ISO 9660 filesystem for CDROMs. Comment it out if you do
not have a CDROM drive or only mount data CDs occasionally (since it
will be dynamically loaded the first time you mount a data CD).
Audio CDs do not need this filesystem.</para>
<programlisting>options PROCFS #Process filesystem</programlisting>
<para>The process filesystem. This is a <quote>pretend</quote>
filesystem mounted on <filename>/proc</filename> which allows
programs like &man.ps.1; to give you more information on what
processes are running.</para>
<programlisting>options COMPAT_43 #Compatible with BSD 4.3 [KEEP THIS!]</programlisting>
<para>Compatibility with 4.3BSD. Leave this in; some programs will
act strangely if you comment this out.</para>
<programlisting>options SCSI_DELAY=15000 #Delay (in ms) before probing SCSI</programlisting>
<para>This causes the kernel to pause for 15 seconds before probing
each SCSI device in your system. If you only have IDE hard drives,
you can ignore this, otherwise you will probably want to lower this
number, perhaps to 5 seconds, to speed up booting. Of course, if
you do this, and FreeBSD has trouble recognizing your SCSI devices,
you will have to raise it back up.</para>
<programlisting>options UCONSOLE #Allow users to grab the console</programlisting>
<para>Allow users to grab the console, which is useful for X users.
For example, you can create a console xterm by typing <command>xterm
-C</command>, which will display any <command>write</command>,
<command>talk</command>, and any other messages you receive, as well
as any console messages sent by the kernel.</para>
<programlisting>options USERCONFIG #boot -c editor</programlisting>
<para>This option allows you to boot the configuration editor from the
boot menu.</para>
<programlisting>options VISUAL_USERCONFIG #visual boot -c editor</programlisting>
<para>This option allows you to boot the visual configuration editor
from the boot menu.</para>
<programlisting>options KTRACE #ktrace(1) support</programlisting>
<para>This enables kernel process tracing, which is useful in
debugging.</para>
<programlisting>options SYSVSHM #SYSV-style shared memory</programlisting>
<para>This option provides for System V shared memory. The most
common use of this is the XSHM extension in X, which many
graphics-intensive programs will automatically take advantage of for
extra speed. If you use X, you will definitely want to include
this.</para>
<programlisting>options SYSVSEM #SYSV-style semaphores</programlisting>
<para>Support for System V semaphores. Less commonly used but only
adds a few hundred bytes to the kernel.</para>
<programlisting>options SYSVMSG #SYSV-style message queues</programlisting>
<para>Support for System V messages. Again, only adds a few hundred
bytes to the kernel.</para>
<note>
<para>The &man.ipcs.1; command will list any processes using each of
these System V facilities.</para>
</note>
<programlisting>options P1003_1B #Posix P1003_1B real-time extensions
options _KPOSIX_PRIORITY_SCHEDULING</programlisting>
<para>Real-time extensions added in the 1993 POSIX. Certain
applications in the ports collection use these (such as Star
Office).</para>
<indexterm>
<primary>kernel options</primary>
<secondary>ICMP_BANDLIM</secondary>
</indexterm>
<indexterm>
<primary>Denial of Service (DoS)</primary>
</indexterm>
<programlisting>options ICMP_BANDLIM #Rate limit bad replies</programlisting>
<para>This option enables ICMP error response bandwidth limiting. You
typically want this option as it will help protect the machine from
denial of service packet attacks.</para>
<indexterm>
<primary>kernel options</primary>
<secondary>SMP</secondary>
</indexterm>
<programlisting># To make an SMP kernel, the next two are needed
#options SMP # Symmetric MultiProcessor Kernel
#options APIC_IO # Symmetric (APIC) I/O</programlisting>
<para>The above are both required for SMP support.</para>
<programlisting>device isa</programlisting>
<para>All PCs supported by FreeBSD have one of these. If you have an
IBM PS/2 (Micro Channel Architecture), you cannot run FreeBSD at
this time (support is being worked on).</para>
<programlisting>device eisa</programlisting>
<para>Include this if you have an EISA motherboard. This enables
auto-detection and configuration support for all devices on the EISA
bus.</para>
<programlisting>device pci</programlisting>
<para>Include this if you have a PCI motherboard. This enables
auto-detection of PCI cards and gatewaying from the PCI to ISA
bus.</para>
<programlisting># Floppy drives
device fdc0 at isa? port IO_FD1 irq 6 drq 2
device fd0 at fdc0 drive 0
device fd1 at fdc0 drive 1</programlisting>
<para>This is the floppy drive controller. <literal>fd0</literal> is
the <devicename>A:</devicename> floppy drive, and
<literal>fd1</literal> is the <devicename>B:</devicename>
drive.</para>
<programlisting>device ata</programlisting>
<para>This driver supports all ATA and ATAPI devices. You only need
one <literal>device ata</literal> line for the kernel to detect all
PCI ATA/ATAPI devices on modern machines.</para>
<programlisting>device atadisk # ATA disk drives</programlisting>
<para>This is needed along with <literal>device ata</literal> for
ATAPI disk drives.</para>
<programlisting><anchor id="kernelconfig-atapi">
device atapicd # ATAPI CDROM drives</programlisting>
<para>This is needed along with <literal>device ata</literal> for
ATAPI CDROM drives.</para>
<programlisting>device atapifd # ATAPI floppy drives</programlisting>
<para>This is needed along with <literal>device ata</literal> for
ATAPI floppy drives.</para>
<programlisting>device atapist # ATAPI tape drives</programlisting>
<para>This is needed along with <literal>device ata</literal> for
ATAPI tape drives.</para>
<programlisting>options ATA_STATIC_ID #Static device numbering</programlisting>
<para>This makes the controller number static (like the old driver) or
else the device numbers are dynamically allocated.</para>
<programlisting># ATA and ATAPI devices
device ata0 at isa? port IO_WD1 irq 14
device ata1 at isa? port IO_WD2 irq 15</programlisting>
<para>Use the above for older, non-PCI systems.</para>
<programlisting># SCSI Controllers
device ahb # EISA AHA1742 family
device ahc # AHA2940 and onboard AIC7xxx devices
device amd # AMD 53C974 (Teckram DC-390(T))
device dpt # DPT Smartcache - See LINT for options!
device isp # Qlogic family
device ncr # NCR/Symbios Logic
device sym # NCR/Symbios Logic (newer chipsets)
device adv0 at isa?
device adw
device bt0 at isa?
device aha0 at isa?
device aic0 at isa?</programlisting>
<para>SCSI controllers. Comment out any you do not have in your
system. If you have an IDE only system, you can remove these
altogether.</para>
<programlisting># SCSI peripherals
device scbus # SCSI bus (required)
device da # Direct Access (disks)
device sa # Sequential Access (tape etc)
device cd # CD
device pass # Passthrough device (direct SCSI
access)</programlisting>
<para>SCSI peripherals. Again, comment out any you do not have, or if
you have only IDE hardware, you can remove them completely.</para>
<programlisting># RAID controllers
device ida # Compaq Smart RAID
device amr # AMI MegaRAID
device mlx # Mylex DAC960 family</programlisting>
<para>Supported RAID controllers. If you do not have any of these,
you can comment them out or remove them.</para>
<programlisting># atkbdc0 controls both the keyboard and the PS/2 mouse
device atkbdc0 at isa? port IO_KBD</programlisting>
<para>The keyboard controller (<literal>atkbdc</literal>) provides I/O
services for the AT keyboard and PS/2 style pointing devices. This
controller is required by the keyboard driver
(<literal>atkbd</literal>) and the PS/2 pointing device driver
(<literal>psm</literal>).</para>
<programlisting>device atkbd0 at atkbdc? irq 1</programlisting>
<para>The <literal>atkbd</literal> driver, together with
<literal>atkbdc</literal> controller, provides access to the AT 84
keyboard or the AT enhanced keyboard which is connected to the AT
keyboard controller.</para>
<programlisting>device psm0 at atkbdc? irq 12</programlisting>
<para>Use this device if your mouse plugs into the PS/2 mouse
port.</para>
<programlisting>device vga0 at isa?</programlisting>
<para>The video card driver.</para>
<programlisting># splash screen/screen saver
pseudo-device splash</programlisting>
<para>Splash screen at start up! Screen savers require this
too.</para>
<programlisting># syscons is the default console driver, resembling an SCO console
device sc0 at isa?</programlisting>
<para><literal>sc0</literal> is the default console driver, which
resembles a SCO console. Since most full-screen programs access the
console through a terminal database library like
<filename>termcap</filename>, it should not matter whether you use
this or <literal>vt0</literal>, the <literal>VT220</literal>
compatible console driver. When you log in, set your
<envar>TERM</envar> variable to <literal>scoansi</literal> if
full-screen programs have trouble running under this console.</para>
<programlisting># Enable this and PCVT_FREEBSD for pcvt vt220 compatible console driver
#device vt0 at isa?
#options XSERVER # support for X server on a vt console
#options FAT_CURSOR # start with block cursor
# If you have a ThinkPAD, uncomment this along with the rest of the PCVT lines
#options PCVT_SCANSET=2 # IBM keyboards are non-std</programlisting>
<para>This is a VT220-compatible console driver, backward compatible to
VT100/102. It works well on some laptops which have hardware
incompatibilities with <literal>sc0</literal>. Also set your
<envar>TERM</envar> variable to <literal>vt100</literal> or
<literal>vt220</literal> when you log in. This driver might also
prove useful when connecting to a large number of different machines
over the network, where <filename>termcap</filename> or
<filename>terminfo</filename> entries for the <literal>sc0</literal>
device are often not available — <literal>vt100</literal>
should be available on virtually any platform.</para>
<programlisting># Power management support (see LINT for more options)
device apm0 at nexus? disable flags 0x20 # Advanced Power Management</programlisting>
<para>Advanced Power Management support. Useful for laptops.</para>
<programlisting># PCCARD (PCMCIA) support
device card
device pcic0 at isa? irq 10 port 0x3e0 iomem 0xd0000
device pcic1 at isa? irq 11 port 0x3e2 iomem 0xd4000 disable</programlisting>
<para>PCMCIA support. You want this if you are using a
laptop.</para>
<programlisting># Serial (COM) ports
device sio0 at isa? port IO_COM1 flags 0x10 irq 4
device sio1 at isa? port IO_COM2 irq 3
device sio2 at isa? disable port IO_COM3 irq 5
device sio3 at isa? disable port IO_COM4 irq 9</programlisting>
<para>These are the four serial ports referred to as COM1 through COM4
in the MS-DOS/Windows world.</para>
<note>
<para>If you have an internal modem on COM4 and a serial port at
COM2, you will have to change the IRQ of the modem to 2 (for
obscure technical reasons, IRQ2 = IRQ 9) in order to access it
from FreeBSD. If you have a multiport serial card, check the
manual page for &man.sio.4; for more information on the proper
values for these lines. Some video cards (notably those based on
S3 chips) use IO addresses in the form of
<literal>0x*2e8</literal>, and since many cheap serial cards do
not fully decode the 16-bit IO address space, they clash with
these cards making the COM4 port practically unavailable.</para>
<para>Each serial port is required to have a unique IRQ (unless you
are using one of the multiport cards where shared interrupts are
supported), so the default IRQs for COM3 and COM4 cannot be
used.</para>
</note>
<programlisting># Parallel port
device ppc0 at isa? irq 7</programlisting>
<para>This is the ISA-bus parallel port interface.</para>
<programlisting>device ppbus # Parallel port bus (required)</programlisting>
<para>Provides support for the parallel port bus.</para>
<programlisting>device lpt # Printer</programlisting>
<para>Support for parallel port printers.</para>
<note>
<para>All three of the above are required to enable parallel printer
support.</para>
</note>
<programlisting>device plip # TCP/IP over parallel</programlisting>
<para>This is the driver for the parallel network interface.</para>
<programlisting>device ppi # Parallel port interface device</programlisting>
<para>The general-purpose I/O (<quote>geek port</quote>) + IEEE1284
I/O.</para>
<programlisting>#device vpo # Requires scbus and da</programlisting>
<indexterm><primary>zip drive</primary></indexterm>
<para>This is for an Iomega Zip drive. It requires
<literal>scbus</literal> and <literal>da</literal> support. Best
performance is achieved with ports in EPP 1.9 mode.</para>
<programlisting># PCI Ethernet NICs.
device de # DEC/Intel DC21x4x (<quote>Tulip</quote>)
device fxp # Intel EtherExpress PRO/100B (82557, 82558)
device tx # SMC 9432TX (83c170 <quote>EPIC</quote>)
device vx # 3Com 3c590, 3c595 (<quote>Vortex</quote>)
device wx # Intel Gigabit Ethernet Card (<quote>Wiseman</quote>)</programlisting>
<para>Various PCI network card drivers. Comment out or remove any of
these not present in your system.</para>
<programlisting># PCI Ethernet NICs that use the common MII bus controller code.
device miibus # MII bus support</programlisting>
<para>MII bus support is required for some PCI 10/100 Ethernet NICs,
namely those which use MII-compliant transceivers or implement
transceiver control interfaces that operate like an MII. Adding
<literal>device miibus</literal> to the kernel config pulls in
support for the generic miibus API and all of the PHY drivers,
including a generic one for PHYs that are not specifically handled
by an individual driver</para>
<programlisting>device dc # DEC/Intel 21143 and various workalikes
device rl # RealTek 8129/8139
device sf # Adaptec AIC-6915 (<quote>Starfire</quote>)
device sis # Silicon Integrated Systems SiS 900/SiS 7016
device ste # Sundance ST201 (D-Link DFE-550TX)
device tl # Texas Instruments ThunderLAN
device vr # VIA Rhine, Rhine II
device wb # Winbond W89C840F
device xl # 3Com 3c90x (<quote>Boomerang</quote>, <quote>Cyclone</quote>)</programlisting>
<para>Drivers that use the MII bus controller code.</para>
<programlisting># ISA Ethernet NICs.
device ed0 at isa? port 0x280 irq 10 iomem 0xd8000
device ex
device ep
# WaveLAN/IEEE 802.11 wireless NICs. Note: the WaveLAN/IEEE really
# exists only as a PCMCIA device, so there is no ISA attachment needed
# and resources will always be dynamically assigned by the pccard code.
device wi
# Aironet 4500/4800 802.11 wireless NICs. Note: the declaration below will
# work for PCMCIA and PCI cards, as well as ISA cards set to ISA PnP
# mode (the factory default). If you set the switches on your ISA
# card for a manually chosen I/O address and IRQ, you must specify
# those parameters here.
device an
# The probe order of these is presently determined by i386/isa/isa_compat.c.
device ie0 at isa? port 0x300 irq 10 iomem 0xd0000
device fe0 at isa? port 0x300
device le0 at isa? port 0x300 irq 5 iomem 0xd0000
device lnc0 at isa? port 0x280 irq 10 drq 0
device cs0 at isa? port 0x300
device sn0 at isa? port 0x300 irq 10
# requires PCCARD (PCMCIA) support to be activated
#device xe0 at isa?</programlisting>
<para>ISA Ethernet drivers. See
<filename>/usr/src/sys/i386/conf/LINT</filename> for which cards are
supported by which driver.</para>
<programlisting>pseudo-device ether # Ethernet support</programlisting>
<para><literal>ether</literal> is only needed if you have an Ethernet
card. It includes generic Ethernet protocol code.</para>
<programlisting>pseudo-device sl 1 # Kernel SLIP</programlisting>
<para><literal>sl</literal> is for SLIP support. This has been almost
entirely supplanted by PPP, which is easier to set up, better suited
for modem-to-modem connection, and more powerful. The
<replaceable>number</replaceable> after <literal>sl</literal>
specifies how many simultaneous SLIP sessions to support.</para>
<programlisting>pseudo-device ppp 1 # Kernel PPP</programlisting>
<para>This is for kernel PPP support for dial-up connections. There
is also a version of PPP implemented as a userland application that
uses <literal>tun</literal> and offers more flexibility and features
such as demand dialing. The <replaceable>number</replaceable> after
<literal>ppp</literal> specifies how many simultaneous PPP
connections to support.</para>
<programlisting>pseudo-device tun # Packet tunnel.</programlisting>
<para>This is used by the userland PPP software. A
<replaceable>number</replaceable> after <literal>tun</literal>
specifies the number of simultaneous PPP sessions to support. See
the <link linkend="userppp">PPP</link> section of this book for more
information.</para>
<programlisting><anchor id="kernelconfig-ptys">
pseudo-device pty # Pseudo-ttys (telnet etc)</programlisting>
<para>This is a <quote>pseudo-terminal</quote> or simulated login port.
It is used by incoming <command>telnet</command> and
<command>rlogin</command> sessions,
<application>xterm</application>, and some other applications such
as <application>emacs</application>. A
<replaceable>number</replaceable> after <literal>pty</literal> indicates the number of
<literal>pty</literal>s to create. If you need more than the
default of 16 simultaneous <application>xterm</application> windows
and/or remote logins, be sure to increase this number accordingly,
up to a maximum of 256.</para>
<programlisting>pseudo-device md # Memory <quote>disks</quote></programlisting>
<para>Memory disk pseudo-devices.</para>
<programlisting>pesudo-device gif</programlisting>
<para>or</para>
<programlisting>pseudo-device gif 4 # IPv6 and IPv4 tunneling</programlisting>
<para>This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling,
IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling. Beginning with
FreeBSD 4.4 the <literal>gif</literal> device is
<quote>auto-cloning</quote>, and you should use the first example
(without the number after <literal>gif</literal>). Earlier versions of
FreeBSD require the number.</para>
<programlisting>pseudo-device faith 1 # IPv6-to-IPv4 relaying (translation)</programlisting>
<para>This pseudo-device captures packets that are sent to it and
diverts them to the IPv4/IPv6 translation daemon.</para>
<programlisting># The `bpf' pseudo-device enables the Berkeley Packet Filter.
# Be aware of the administrative consequences of enabling this!
pseudo-device bpf # Berkeley packet filter</programlisting>
<para>This is the Berkeley Packet Filter. This pseudo-device allows
network interfaces to be placed in promiscuous mode, capturing every
packet on a broadcast network (e.g., an Ethernet). These packets
can be captured to disk and or examined with the &man.tcpdump.1;
program.</para>
<note>
<para>The <literal>bpf pseudo-device</literal> is also used by
&man.dhclient.8; to obtain the IP address of the default router
(gateway) and so on. If you use DHCP, leave this
uncommented.</para>
</note>
<programlisting># USB support
#device uhci # UHCI PCI->USB interface
#device ohci # OHCI PCI->USB interface
#device usb # USB Bus (required)
#device ugen # Generic
#device uhid # <quote>Human Interface Devices</quote>
#device ukbd # Keyboard
#device ulpt # Printer
#device umass # Disks/Mass storage - Requires scbus and da
#device ums # Mouse
# USB Ethernet, requires mii
#device aue # ADMtek USB ethernet
#device cue # CATC USB ethernet
#device kue # Kawasaki LSI USB ethernet</programlisting>
<para>Support for various USB devices.</para>
<para>For more information and additional devices supported by
FreeBSD, see
<filename>/usr/src/sys/i386/conf/LINT</filename>.</para>
</sect1>
<sect1 id="kernelconfig-nodes">
<title>Making Device Nodes</title>
<indexterm><primary>device nodes</primary></indexterm>
<indexterm>
<primary><command>MAKEDEV</command></primary>
</indexterm>
<para>Almost every device in the kernel has a corresponding
<quote>node</quote> entry in the <filename>/dev</filename> directory.
These nodes look like regular files, but are actually special
entries into the kernel which programs use to access the device.
The shell script <filename>/dev/MAKEDEV</filename>, which is
executed when you first install the operating system, creates
nearly all of the device nodes supported. However, it does not
create <emphasis>all</emphasis> of them, so when you add support for
a new device, it pays to make sure that the appropriate entries are
in this directory, and if not, add them. Here is a simple
example:</para>
<para>Suppose you add the IDE CD-ROM support to the kernel. The line
to add is:</para>
<programlisting>device acd0</programlisting>
<para>This means that you should look for some entries that start with
<filename>acd0</filename> in the <filename>/dev</filename>
directory, possibly followed by a letter, such as
<literal>c</literal>, or preceded by the letter
<literal>r</literal>, which means a <quote>raw</quote> device. It
turns out that those files are not there, so you must change to the
<filename>/dev</filename> directory and type:</para>
<indexterm>
<primary><command>MAKEDEV</command></primary></indexterm>
<screen>&prompt.root; <userinput>sh MAKEDEV acd0</userinput></screen>
<para>When this script finishes, you will find that there are now
<filename>acd0c</filename> and <filename>racd0c</filename> entries
in <filename>/dev</filename> so you know that it executed
correctly.</para>
<para>For sound cards, the following command creates the appropriate
entries:</para>
<screen>&prompt.root; <userinput>sh MAKEDEV snd0</userinput></screen>
<note>
<para>When creating device nodes for devices such as sound cards, if
other people have access to your machine, it may be desirable to
protect the devices from outside access by adding them to the
<filename>/etc/fbtab</filename> file. See &man.fbtab.5; for more
information.</para>
</note>
<para>Follow this simple procedure for any other
non-<filename>GENERIC</filename> devices which do not have
entries.</para>
<note>
<para>All SCSI controllers use the same set of
<filename>/dev</filename> entries, so you do not need to create
these. Also, network cards and SLIP/PPP pseudo-devices do not
have entries in <filename>/dev</filename> at all, so you do not
have to worry about these either.</para>
</note>
</sect1>
<sect1 id="kernelconfig-trouble">
<title>If Something Goes Wrong</title>
<para>There are five categories of trouble that can occur when
building a custom kernel. They are:</para>
<variablelist>
<varlistentry>
<term><command>config</command> fails:</term>
<listitem>
<para>If the <command>config</command> command fails when you
give it your kernel description, you have probably made a
simple error somewhere. Fortunately,
<command>config</command> will print the line number that it
had trouble with, so you can quickly skip to it with
<command>vi</command>. For example, if you see:</para>
<screen>config: line 17: syntax error</screen>
<para>You can skip to the problem in <command>vi</command> by
typing <command>17G</command> in command mode. Make sure the
keyword is typed correctly, by comparing it to the
<filename>GENERIC</filename> kernel or another
reference.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>make</command> fails:</term>
<listitem>
<para>If the <command>make</command> command fails, it usually
signals an error in your kernel description, but not severe
enough for <command>config</command> to catch it. Again, look
over your configuration, and if you still cannot resolve the
problem, send mail to the &a.questions; with your kernel
configuration, and it should be diagnosed very quickly.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Installing the new kernel fails</term>
<listitem>
<para>If the kernel compiled fine, but failed to install
(the <command>make install</command> or
<command>make installkernel</command> command failed),
the first thing to check is if your system is running at
securelevel 1 or higher (see &man.init.8;). The kernel
installation tries to remove the immutable flag from
your kernel and set the immutable flag on the new one.
Since securelevel 1 or higher prevents unsetting the immutable
flag for any files on the system, the kernel installation needs
to be performed at securelevel 0 or lower.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>The kernel will not boot:<anchor
id="kernelconfig-noboot"></term>
<listitem>
<para>If your new kernel does not boot, or fails to
recognize your devices, do not panic! Fortunately, BSD has
an excellent mechanism for recovering from incompatible
kernels. Simply choose the kernel you want to boot from at
the FreeBSD boot loader. You can access this when the system
counts down from 10. Hit any key except for the enter key,
type <command>unload</command> and then type
<command>boot
<replaceable>kernel.old</replaceable></command>, or the
filename of any other kernel that will boot properly. When
reconfiguring a kernel, it is always a good idea to keep a
kernel that is known to work on hand.</para>
<para>After booting with a good kernel you can check over your
configuration file and try to build it again. One helpful
resource is the <filename>/var/log/messages</filename> file
which records, among other things, all of the kernel messages
from every successful boot. Also, the &man.dmesg.8; command
will print the kernel messages from the current boot.</para>
<note>
<para>If you are having trouble building a kernel, make sure
to keep a <filename>GENERIC</filename>, or some other kernel
that is known to work on hand as a different name that will
not get erased on the next build. You cannot rely on
<filename>kernel.old</filename> because when installing a
new kernel, <filename>kernel.old</filename> is overwritten
with the last installed kernel which may be non-functional.
Also, as soon as possible, move the working kernel to the
proper <filename>kernel</filename> location or commands such
as &man.ps.1; will not work properly. The proper command to
<quote>unlock</quote> the kernel file that
<command>make</command> installs (in order to move another
kernel back permanently) is:</para>
<screen>&prompt.root; <userinput>chflags noschg /kernel</userinput></screen>
<para>If you find you cannot do this, you are probably running
at a &man.securelevel.8; greater than zero. Edit
<literal>kern_securelevel</literal> in
<filename>/etc/rc.conf</filename> and set it to
<literal>-1</literal>, then reboot. You can change it back
to its previous setting when you are happy with your new
kernel.</para>
<para>And, if you want to <quote>lock</quote> your new kernel
into place, or any file for that matter, so that it cannot
be moved or tampered with:</para>
<screen>&prompt.root; <userinput>chflags schg /kernel</userinput></screen>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>The kernel works, but <command>ps</command> does not work
any more!:</term>
<listitem>
<para>If you have installed a different version of the kernel
from the one that the system utilities have been built with,
for example, a 4.X kernel on a 3.X system, many system-status
commands like &man.ps.1; and &man.vmstat.8; will not work any
more. You must recompile the <filename>libkvm</filename>
library as well as these utilities. This is one reason it is
not normally a good idea to use a different version of the
kernel from the rest of the operating system.</para>
</listitem>
</varlistentry>
</variablelist>
</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:
-->
|