aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
blob: 3c9d8c9bf9d8dc65530c59ca4cb3c1fb51327693 (plain) (blame)
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
<?xml version="1.0" encoding="iso-8859-1"?>
<!--
     The FreeBSD Documentation Project

     $FreeBSD$
-->
<chapter xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
  xml:id="updating-upgrading">

  <info>
    <title>Updating and Upgrading &os;</title>

    <authorgroup>
      <author>
	<personname>
	  <firstname>Jim</firstname>
	  <surname>Mock</surname>
	</personname>
	<contrib>Restructured, reorganized, and parts updated
	  by </contrib>
      </author>
      <!-- Mar 2000 -->
    </authorgroup>

    <authorgroup>
      <author>
	<personname>
	  <firstname>Jordan</firstname>
	  <surname>Hubbard</surname>
	</personname>
	<contrib>Original work by </contrib>
      </author>

      <author>
	<personname>
	  <firstname>Poul-Henning</firstname>
	  <surname>Kamp</surname>
	</personname>
      </author>

      <author>
	<personname>
	  <firstname>John</firstname>
	  <surname>Polstra</surname>
	</personname>
      </author>

      <author>
	<personname>
	  <firstname>Nik</firstname>
	  <surname>Clayton</surname>
	</personname>
      </author>
    </authorgroup>
  </info>

  <sect1 xml:id="updating-upgrading-synopsis">
    <title>Synopsis</title>

    <para>&os; is under constant development between releases.  Some
      people prefer to use the officially released versions, while
      others prefer to keep in sync with the latest developments.
      However, even official releases are often updated with security
      and other critical fixes.  Regardless of the version used, &os;
      provides all the necessary tools to keep the system updated, and
      allows for easy upgrades between versions.  This chapter
      describes how to track the development system and the basic
      tools for keeping a &os; system up-to-date.</para>

    <para>After reading this chapter, you will know:</para>

    <itemizedlist>
      <listitem>
	<para>How to keep a &os; system up-to-date with
	  <application>freebsd-update</application> or
	  <application>Subversion</application>.</para>
      </listitem>

      <listitem>
	<para>How to compare the state of an installed system against
	  a known pristine copy.</para>
      </listitem>

      <listitem>
	<para>How to keep the installed documentation up-to-date with
	  <application>Subversion</application> or documentation
	  ports<!--, and <application>Docsnap</application>-->.</para>
      </listitem>

      <listitem>
	<para>The difference between the two development
	  branches: &os.stable; and &os.current;.</para>
      </listitem>

      <listitem>
	<para>How to rebuild and reinstall the entire base
	  system.</para>
      </listitem>
    </itemizedlist>

    <para>Before reading this chapter, you should:</para>

    <itemizedlist>
      <listitem>
	<para>Properly set up the network connection
	  (<xref linkend="advanced-networking"/>).</para>
      </listitem>

      <listitem>
	<para>Know how to install additional third-party
	  software (<xref linkend="ports"/>).</para>
      </listitem>
    </itemizedlist>

    <note>
      <para>Throughout this chapter, <command>svnlite</command> is used to
	obtain and update &os; sources.  Optionally, the
	<package>devel/subversion</package> port or
	package may be used.</para>
    </note>
  </sect1>

  <sect1 xml:id="updating-upgrading-freebsdupdate">
    <info>
      <title>&os; Update</title>

      <authorgroup>
	<author>
	  <personname>
	    <firstname>Tom</firstname>
	    <surname>Rhodes</surname>
	  </personname>
	  <contrib>Written by </contrib>
	</author>
      </authorgroup>

      <authorgroup>
	<author>
	  <personname>
	    <firstname>Colin</firstname>
	    <surname>Percival</surname>
	  </personname>
	  <contrib>Based on notes provided by </contrib>
	</author>
      </authorgroup>
    </info>

    <indexterm>
      <primary>Updating and Upgrading</primary>
    </indexterm>
    <indexterm>
      <primary>freebsd-update</primary>
      <see>updating-upgrading</see>
    </indexterm>

    <para>Applying security patches in a timely manner and upgrading
      to a newer release of an operating system are important aspects
      of ongoing system administration.  &os; includes a utility
      called <command>freebsd-update</command> which can be used to
      perform both these tasks.</para>

    <para>This utility supports binary security and errata updates to
      &os;, without the need to manually compile and install the patch
      or a  new kernel.  Binary updates are available for all
      architectures and releases currently supported by the security
      team.  The list of supported releases and their estimated
      end-of-life dates are listed at <uri
	xlink:href="https://www.FreeBSD.org/security/">https://www.FreeBSD.org/security/</uri>.</para>

    <para>This utility also supports operating system upgrades to
      minor point releases as well as upgrades to another release
      branch.  Before upgrading to a new release, review its release
      announcement as it contains important information pertinent to
      the release.  Release announcements are available from <uri
	xlink:href="https://www.FreeBSD.org/releases/">https://www.FreeBSD.org/releases/</uri>.</para>

    <note>
      <para>If a <command>crontab</command> utilizing the features of
	&man.freebsd-update.8; exists, it must be disabled before
	upgrading the operating system.</para>
    </note>

    <para>This section describes the configuration file used by
      <command>freebsd-update</command>, demonstrates how to apply a
      security patch and how to upgrade to a minor or major operating
      system release, and discusses some of the considerations when
      upgrading the operating system.</para>

    <sect2 xml:id="freebsdupdate-config-file">
      <title>The Configuration File</title>

      <para>The default configuration file for
	<command>freebsd-update</command> works as-is.  Some users may
	wish to tweak the default configuration in
	<filename>/etc/freebsd-update.conf</filename>, allowing
	better control of the process.  The comments in this file
	explain the available options, but the following may require a
	bit more explanation:</para>

      <programlisting># Components of the base system which should be kept updated.
Components world kernel</programlisting>

      <para>This parameter controls which parts of &os; will be kept
	up-to-date.  The default is to update the entire base system
	and the kernel.  Individual components can instead be
	specified, such as <literal>src/base</literal> or
	<literal>src/sys</literal>.  However, the best option is to
	leave this at the default as changing it to include specific
	items requires every needed item to be listed.  Over time,
	this could have disastrous consequences as source code and
	binaries may become out of sync.</para>

      <programlisting># Paths which start with anything matching an entry in an IgnorePaths
# statement will be ignored.
IgnorePaths /boot/kernel/linker.hints</programlisting>

      <para>To leave specified directories, such as
	<filename>/bin</filename> or <filename>/sbin</filename>,
	untouched during the update process, add their paths to this
	statement.  This option may be used to prevent
	<command>freebsd-update</command> from overwriting local
	modifications.</para>

      <programlisting># Paths which start with anything matching an entry in an UpdateIfUnmodified
# statement will only be updated if the contents of the file have not been
# modified by the user (unless changes are merged; see below).
UpdateIfUnmodified /etc/ /var/ /root/ /.cshrc /.profile</programlisting>

      <para>This option will only update unmodified configuration
	files in the specified directories.  Any changes made by the
	user will prevent the automatic updating of these files.
	There is another option,
	<literal>KeepModifiedMetadata</literal>, which will instruct
	<command>freebsd-update</command> to save the changes during
	the merge.</para>

      <programlisting># When upgrading to a new &os; release, files which match MergeChanges
# will have any local changes merged into the version from the new release.
MergeChanges /etc/ /var/named/etc/ /boot/device.hints</programlisting>

      <para>List of directories with configuration files that
	<command>freebsd-update</command> should attempt to merge.
	The file merge process is a series of &man.diff.1; patches
	similar to &man.mergemaster.8;, but with fewer options.
	Merges are either accepted, open an editor, or cause
	<command>freebsd-update</command> to abort.  When in doubt,
	backup <filename>/etc</filename> and just accept the merges.
	See &man.mergemaster.8; for more information about
	<command>mergemaster</command>.</para>

      <programlisting># Directory in which to store downloaded updates and temporary
# files used by &os; Update.
# WorkDir /var/db/freebsd-update</programlisting>

      <para>This directory is where all patches and temporary files
	are placed.  In cases where the user is doing a version
	upgrade, this location should have at least a gigabyte of disk
	space available.</para>

      <programlisting># When upgrading between releases, should the list of Components be
# read strictly (StrictComponents yes) or merely as a list of components
# which *might* be installed of which &os; Update should figure out
# which actually are installed and upgrade those (StrictComponents no)?
# StrictComponents no</programlisting>

      <para>When this option is set to <literal>yes</literal>,
	<command>freebsd-update</command> will assume that the
	<literal>Components</literal> list is complete and will not
	attempt to make changes outside of the list.  Effectively,
	<command>freebsd-update</command> will attempt to update
	every file which belongs to the <literal>Components</literal>
	list.</para>
    </sect2>

    <sect2 xml:id="freebsdupdate-security-patches">
      <title>Applying Security Patches</title>

      <para>The process of applying &os; security patches has been
	simplified, allowing an administrator to keep a system fully
	patched using <command>freebsd-update</command>.  More
	information about &os; security advisories can be found in
	<xref linkend="security-advisories"/>.</para>

      <para>&os; security patches may be downloaded and installed
	using the following commands.  The first command will
	determine if any outstanding patches are available, and if so,
	will list the files that will be modifed if the patches are
	applied.  The second command will apply the patches.</para>

      <screen>&prompt.root; <userinput>freebsd-update fetch</userinput>
&prompt.root; <userinput>freebsd-update install</userinput></screen>

      <para>If the update applies any kernel patches, the system will
	need a reboot in order to boot into the patched kernel.  If
	the patch was applied to any running binaries, the affected
	applications should be restarted so that the patched version
	of the binary is used.</para>

      <note>
	<para>Usually, the user needs to be prepared to reboot the
	  system.  To know if a reboot is required by a kernel update,
	  execute the commands <command>freebsd-version -k</command>
	  and <command>uname -r</command> and if it differs a reboot
	  is required.</para>
      </note>

      <para>The system can be configured to automatically check for
	updates once every day by adding this entry to
	<filename>/etc/crontab</filename>:</para>

      <programlisting>@daily                                  root    freebsd-update cron</programlisting>

      <para>If patches exist, they will automatically be downloaded
	but will not be applied.  The <systemitem
	  class="username">root</systemitem> user will be sent an
	email so that the patches may be reviewed and manually
	installed with
	<command>freebsd-update install</command>.</para>

      <para>If anything goes wrong, <command>freebsd-update</command>
	has the ability to roll back the last set of changes with the
	following command:</para>

      <screen>&prompt.root; <userinput>freebsd-update rollback</userinput>
Uninstalling updates... done.</screen>

      <para>Again, the system should be restarted if the kernel or any
	kernel modules were modified and any affected binaries should
	be restarted.</para>

      <para>Only the <filename>GENERIC</filename> kernel can be
	automatically updated by <command>freebsd-update</command>.
	If a custom kernel is installed, it will have to be rebuilt
	and reinstalled after <command>freebsd-update</command>
	finishes installing the updates.  The default kernel name
	is <emphasis>GENERIC</emphasis>.  The &man.uname.1; command
	may be used to verify its installation.</para>

      <note>
	<para>Always keep a copy of the <filename>GENERIC</filename>
	  kernel in <filename>/boot/GENERIC</filename>.  It will be
	  helpful in diagnosing a variety of problems and in
	  performing version upgrades.  Refer to <xref
	    linkend="freebsd-update-custom-kernel-9x"/> for
	  instructions on how to get a copy of the
	  <filename>GENERIC</filename> kernel.</para>
      </note>

      <para>Unless the default configuration in
	<filename>/etc/freebsd-update.conf</filename> has been
	changed, <command>freebsd-update</command> will install the
	updated kernel sources along with the rest of the updates.
	Rebuilding and reinstalling a new custom kernel can then be
	performed in the usual way.</para>

      <para>The updates distributed by
	<command>freebsd-update</command> do not always involve the
	kernel.  It is not necessary to rebuild a custom kernel if the
	kernel sources have not been modified by
	<command>freebsd-update install</command>.  However,
	<command>freebsd-update</command> will always update
	<filename>/usr/src/sys/conf/newvers.sh</filename>.  The
	current patch level, as indicated by the <literal>-p</literal>
	number reported by <command>uname -r</command>, is obtained
	from this file.  Rebuilding a custom kernel, even if nothing
	else changed, allows <command>uname</command> to accurately
	report the current patch level of the system.  This is
	particularly helpful when maintaining multiple systems, as it
	allows for a quick assessment of the updates installed in each
	one.</para>
    </sect2>

    <sect2 xml:id="freebsdupdate-upgrade">
      <title>Performing Major and Minor Version Upgrades</title>

      <para>Upgrades from one minor version of &os; to another, like
	from &os;&nbsp;9.0 to &os;&nbsp;9.1, are called
	<firstterm>minor version</firstterm> upgrades.
	<firstterm>Major version</firstterm> upgrades occur when &os;
	is upgraded from one major version to another, like from
	&os;&nbsp;9.X to &os;&nbsp;10.X.  Both types of upgrades can
	be performed by providing <command>freebsd-update</command>
	with a release version target.</para>

      <note>
	<para>If the system is running a custom kernel, make sure that
	  a copy of the <filename>GENERIC</filename> kernel exists in
	  <filename>/boot/GENERIC</filename> before starting the
	  upgrade.  Refer to <xref
	    linkend="freebsd-update-custom-kernel-9x"/> for
	  instructions on how to get a copy of the
	  <filename>GENERIC</filename> kernel.</para>
      </note>

      <para>The following command, when run on a &os;&nbsp;9.0 system,
	will upgrade it to &os;&nbsp;9.1:</para>

       <screen>&prompt.root; <userinput>freebsd-update -r 9.1-RELEASE upgrade</userinput></screen>

      <para>After the command has been received,
	<command>freebsd-update</command> will evaluate the
	configuration file and current system in an attempt to gather
	the information necessary to perform the upgrade.  A screen
	listing will display which components have and have not been
	detected.  For example:</para>

      <screen>Looking up update.FreeBSD.org mirrors... 1 mirrors found.
Fetching metadata signature for 9.0-RELEASE from update1.FreeBSD.org... done.
Fetching metadata index... done.
Inspecting system... done.

The following components of FreeBSD seem to be installed:
kernel/smp src/base src/bin src/contrib src/crypto src/etc src/games
src/gnu src/include src/krb5 src/lib src/libexec src/release src/rescue
src/sbin src/secure src/share src/sys src/tools src/ubin src/usbin
world/base world/info world/lib32 world/manpages

The following components of FreeBSD do not seem to be installed:
kernel/generic world/catpages world/dict world/doc world/games
world/proflibs

Does this look reasonable (y/n)? <userinput>y</userinput></screen>

      <para>At this point, <command>freebsd-update</command> will
	attempt to download all files required for the upgrade.  In
	some cases, the user may be prompted with questions regarding
	what to install or how to proceed.</para>

      <para>When using a custom kernel, the above step will produce a
	warning similar to the following:</para>

      <screen>WARNING: This system is running a "<replaceable>MYKERNEL</replaceable>" kernel, which is not a
kernel configuration distributed as part of FreeBSD 9.0-RELEASE.
This kernel will not be updated: you MUST update the kernel manually
before running "/usr/sbin/freebsd-update install"</screen>

      <para>This warning may be safely ignored at this point.  The
	updated <filename>GENERIC</filename> kernel will be used as an
	intermediate step in the upgrade process.</para>

      <para>Once all the patches have been downloaded to the local
	system, they will be applied.  This process may take a while,
	depending on the speed and workload of the machine.
	Configuration files will then be merged.  The merging process
	requires some user intervention as a file may be merged or an
	editor may appear on screen for a manual merge.  The results
	of every successful merge will be shown to the user as the
	process continues.  A failed or ignored merge will cause the
	process to abort.  Users may wish to make a backup of
	<filename>/etc</filename> and manually merge important files,
	such as <filename>master.passwd</filename> or
	<filename>group</filename> at a later time.</para>

      <note>
	<para>The system is not being altered yet as all patching and
	  merging is happening in another directory.  Once all patches
	  have been applied successfully, all configuration files have
	  been merged and it seems the process will go smoothly, the
	  changes can be committed to disk by the user using the
	  following command:</para>

	<screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>
      </note>

      <para>The kernel and kernel modules will be patched first.  If
	the system is running with a custom kernel, use
	&man.nextboot.8; to set the kernel for the next boot to the
	updated <filename>/boot/GENERIC</filename>:</para>

      <screen>&prompt.root; <userinput>nextboot -k GENERIC</userinput></screen>

      <warning>
	<para>Before rebooting with the <filename>GENERIC</filename>
	  kernel, make sure it contains all the drivers required for
	  the system to boot properly and connect to the network, if
	  the machine being updated is accessed remotely.  In
	  particular, if the running custom kernel contains built-in
	  functionality usually provided by kernel modules, make sure
	  to temporarily load these modules into the
	  <filename>GENERIC</filename> kernel using the
	  <filename>/boot/loader.conf</filename> facility.  It is
	  recommended to disable non-essential services as well as any
	  disk and network mounts until the upgrade process is
	  complete.</para>
      </warning>

      <para>The machine should now be restarted with the updated
	kernel:</para>

      <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>

      <para>Once the system has come back online, restart
	<command>freebsd-update</command> using the following command.
	Since the state of the process has been saved,
	<command>freebsd-update</command> will not start from the
	beginning, but will instead move on to the next phase and
	remove all old shared libraries and object files.</para>

      <screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>

      <note>
	<para>Depending upon whether any library version numbers were
	  bumped, there may only be two install phases instead of
	  three.</para>
      </note>

      <para>The upgrade is now complete.  If this was a major version
	upgrade, reinstall all ports and packages as described in
	<xref linkend="freebsdupdate-portsrebuild"/>.</para>

      <sect3 xml:id="freebsd-update-custom-kernel-9x">
	<title>Custom Kernels with &os;&nbsp;9.X and Later</title>

	<para>Before using <command>freebsd-update</command>, ensure
	  that a copy of the <filename>GENERIC</filename> kernel
	  exists in <filename>/boot/GENERIC</filename>.  If a custom
	  kernel has only been built once, the kernel in
	  <filename>/boot/kernel.old</filename> is the
	  <literal>GENERIC</literal> kernel.  Simply rename this
	  directory to <filename>/boot/kernel</filename>.</para>

	<para>If a custom kernel has been built more than once or if
	  it is unknown how many times the custom kernel has been
	  built, obtain a copy of the <literal>GENERIC</literal>
	  kernel that matches the current version of the operating
	  system.  If physical access to the system is available, a
	  copy of the <literal>GENERIC</literal> kernel can be
	  installed from the installation media:</para>

	<screen>&prompt.root; <userinput>mount /cdrom</userinput>
&prompt.root; <userinput>cd /cdrom/usr/freebsd-dist</userinput>
&prompt.root; <userinput>tar -C/ -xvf kernel.txz boot/kernel/kernel</userinput></screen>

	<para>Alternately, the <literal>GENERIC</literal> kernel may
	  be rebuilt and installed from source:</para>

	<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null</userinput></screen>

	<para>For this kernel to be identified as the
	  <literal>GENERIC</literal> kernel by
	  <command>freebsd-update</command>, the
	  <filename>GENERIC</filename> configuration file must not
	  have been modified in any way.  It is also suggested that
	  the kernel is built without any other special
	  options.</para>

	<para>Rebooting into the <filename>GENERIC</filename> kernel
	  is not required as <command>freebsd-update</command> only
	  needs <filename>/boot/GENERIC</filename> to exist.</para>
      </sect3>

      <sect3 xml:id="freebsdupdate-portsrebuild">
	<title>Upgrading Packages After a Major Version
	  Upgrade</title>

	<para>Generally, installed applications will continue to work
	  without problems after minor version upgrades.  Major
	  versions use different Application Binary Interfaces
	  (<acronym>ABI</acronym>s), which will break most
	  third-party applications.  After a major version upgrade,
	  all installed packages and ports need to be upgraded.
	  Packages can be upgraded using <command>pkg
	    upgrade</command>.  To upgrade installed ports, use a
	  utility such as
	  <package>ports-mgmt/portmaster</package>.</para>

	<para>A forced upgrade of all installed packages will replace
	  the packages with fresh versions from the repository even if
	  the version number has not increased.  This is required
	  because of the ABI version change when upgrading between
	  major versions of &os;.  The forced upgrade can be
	  accomplished by performing:</para>

	<screen>&prompt.root; <userinput>pkg-static upgrade -f</userinput></screen>

	<para>A rebuild of all installed applications can be
	  accomplished with this command:</para>

	<screen>&prompt.root; <userinput>portmaster -af</userinput></screen>

	<para>This command will display the configuration screens for
	  each application that has configurable options and wait for
	  the user to interact with those screens.  To prevent this
	  behavior, and use only the default options, include
	  <option>-G</option> in the above command.</para>

	<para>Once the software upgrades are complete, finish the
	  upgrade process with a final call to
	  <command>freebsd-update</command> in order to tie up all the
	  loose ends in the upgrade process:</para>

	<screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>

	<para>If the <filename>GENERIC</filename> kernel was
	  temporarily used, this is the time to build and install a
	  new custom kernel using the instructions in <xref
	    linkend="kernelconfig"/>.</para>

	<para>Reboot the machine into the new &os; version.  The
	  upgrade process is now complete.</para>
      </sect3>
    </sect2>

    <sect2 xml:id="freebsdupdate-system-comparison">
      <title>System State Comparison</title>

      <para>The state of the installed &os; version against a known
	good copy can be tested using
	<command>freebsd-update IDS</command>.  This command evaluates
	the current version of system utilities, libraries, and
	configuration files and can be used as a built-in Intrusion
	Detection System (<acronym>IDS</acronym>).</para>

      <warning>
	<para>This command is not a replacement for a real
	  <acronym>IDS</acronym> such as
	  <package>security/snort</package>.  As
	  <command>freebsd-update</command> stores data on disk, the
	  possibility of tampering is evident.  While this possibility
	  may be reduced using <varname>kern.securelevel</varname> and
	  by storing the <command>freebsd-update</command> data on a
	  read-only file system when not in use, a better solution
	  would be to compare the system against a secure disk, such
	  as a <acronym>DVD</acronym> or securely stored external
	  <acronym>USB</acronym> disk device.  An alternative method
	  for providing <acronym>IDS</acronym> functionality using a
	  built-in utility is described in <xref
	    linkend="security-ids"/></para>
      </warning>

      <para>To begin the comparison, specify the output file to save
	the results to:</para>

      <screen>&prompt.root; <userinput>freebsd-update IDS &gt;&gt; outfile.ids</userinput></screen>

      <para>The system will now be inspected and a lengthy listing of
	files, along with the <acronym>SHA256</acronym> hash values
	for both the known value in the release and the current
	installation, will be sent to the specified output
	file.</para>

      <para>The entries in the listing are extremely long, but the
	output format may be easily parsed.  For instance, to obtain a
	list of all files which differ from those in the release,
	issue the following command:</para>

      <screen>&prompt.root; <userinput>cat outfile.ids | awk '{ print $1 }' | more</userinput>
/etc/master.passwd
/etc/motd
/etc/passwd
/etc/pf.conf</screen>

      <para>This sample output has been truncated as many more files
	exist.  Some files have natural modifications.  For example,
	<filename>/etc/passwd</filename> will be modified if users
	have been added to the system.  Kernel modules may differ as
	<command>freebsd-update</command> may have updated them.  To
	exclude specific files or directories, add them to the
	<literal>IDSIgnorePaths</literal> option in
	<filename>/etc/freebsd-update.conf</filename>.</para>
    </sect2>
  </sect1>

  <sect1 xml:id="updating-upgrading-documentation">
    <title>Updating the Documentation Set</title>

    <indexterm><primary>Updating and Upgrading</primary></indexterm>

    <indexterm>
      <primary>Documentation</primary>
      <see>Updating and Upgrading</see>
    </indexterm>

    <para>Documentation is an integral part of the &os; operating
      system.  While an up-to-date version of the &os; documentation
      is always available on the &os; web site (<link
	xlink:href="&url.base;/doc/">https://www.freebsd.org/doc/</link>),
      it can be handy to have an up-to-date, local copy of the &os;
      website, handbooks, <acronym>FAQ</acronym>, and articles.</para>

    <para>This section describes how to use either source or the &os;
      Ports Collection to keep a local copy of the &os; documentation
      up-to-date.</para>

    <para>For information on editing and submitting corrections to the
      documentation, refer to the &os; Documentation Project Primer
      for New Contributors (<link
	xlink:href="&url.books.fdp-primer;">https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/</link>).</para>

    <sect2 xml:id="updating-installed-documentation">
      <title>Updating Documentation from Source</title>

      <para>Rebuilding the &os; documentation from source requires a
	collection of tools which are not part of the &os; base
	system.  The required tools can be installed from the
	<package>textproc/docproj</package> package or port developed
	by the &os; Documentation Project.</para>

      <para>Once installed, use <application>svnlite</application> to
	fetch a clean copy of the documentation source:</para>

      <screen>&prompt.root; <userinput>svnlite checkout https://svn.FreeBSD.org/doc/head /usr/doc</userinput></screen>

      <para>The initial download of the documentation sources may take
	a while.  Let it run until it completes.</para>

      <para>Future updates of the documentation sources may be fetched
	by running:</para>

      <screen>&prompt.root; <userinput>svnlite update /usr/doc</userinput></screen>

      <para>Once an up-to-date snapshot of the documentation sources
	has been fetched to <filename>/usr/doc</filename>, everything
	is ready for an update of the installed documentation.</para>

      <para>A full update of all available languages may be performed
	by typing:</para>

      <screen>&prompt.root; <userinput>cd /usr/doc</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>

      <para>If an update of only a specific language is desired,
	<command>make</command> can be invoked in a language-specific
	subdirectory of
	<filename>/usr/doc</filename>:</para>

      <screen>&prompt.root; <userinput>cd /usr/doc/en_US.ISO8859-1</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>

      <para>An alternative way of updating the documentation is to run
	this command from <filename>/usr/doc</filename> or the desired
	language-specific subdirectory:</para>

      <screen>&prompt.root; <userinput>make update</userinput></screen>

      <para>The output formats that will be installed may be specified
	by setting <varname>FORMATS</varname>:</para>

      <screen>&prompt.root; <userinput>cd /usr/doc</userinput>
&prompt.root; <userinput>make FORMATS='html html-split' install clean</userinput></screen>

      <para>Several options are available to ease the process of
	updating only parts of the documentation, or the build of
	specific translations.  These options can be set either as
	system-wide options in <filename>/etc/make.conf</filename>, or
	as command-line options passed to
	<command>make</command>.</para>

      <para>The options include:</para>

      <variablelist>
	<varlistentry>
	  <term><varname>DOC_LANG</varname></term>

	  <listitem>
	    <para>The list of languages and encodings to build and
	      install, such as <literal>en_US.ISO8859-1</literal> for
	      English documentation.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><varname>FORMATS</varname></term>

	  <listitem>
	    <para>A single format or a list of output formats to be
	      built.  Currently, <literal>html</literal>,
	      <literal>html-split</literal>, <literal>txt</literal>,
	      <literal>ps</literal>, and <literal>pdf</literal> are
	      supported.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><varname>DOCDIR</varname></term>

	  <listitem>
	    <para>Where to install the documentation.  It defaults to
	      <filename>/usr/share/doc</filename>.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>For more <command>make</command> variables supported as
	system-wide options in &os;, refer to
	&man.make.conf.5;.</para>
    </sect2>

    <sect2 xml:id="doc-ports-install-package">
      <info>
	<title>Updating Documentation from Ports</title>

	<authorgroup>
	  <author>
	    <personname>
	      <firstname>Marc</firstname>
	      <surname>Fonvieille</surname>
	    </personname>
	    <contrib>Based on the work of </contrib>
	  </author>
	</authorgroup>
      </info>

      <indexterm>
	<primary>Updating and Upgrading</primary>
      </indexterm>

      <indexterm>
	<primary>documentation package</primary>
	<see>Updating and Upgrading</see>
      </indexterm>

      <para>The previous section presented a method for updating the
	&os; documentation from sources.  This section describes an
	alternative method which uses the Ports Collection and makes
	it possible to:</para>

      <itemizedlist>
	<listitem>
	  <para>Install pre-built packages of the documentation,
	    without having to locally build anything or install the
	    documentation toolchain.</para>
	</listitem>

	<listitem>
	  <para>Build the documentation sources through the ports
	    framework, making the checkout and build steps a bit
	    easier.</para>
	</listitem>
      </itemizedlist>

      <para>This method of updating the &os; documentation is
	supported by a set of documentation ports and packages which
	are updated by the &a.doceng; on a monthly basis.  These are
	listed in the &os; Ports&nbsp;Collection, under the docs
	category (<link
	  xlink:href="http://www.freshports.org/docs/">http://www.freshports.org/docs/</link>).</para>

      <para>Organization of the documentation ports is as
	follows:</para>

      <itemizedlist>
	<listitem>
	  <para>The <package>misc/freebsd-doc-en</package> package or
	    port installs all of the English documentation.</para>
	</listitem>

	<listitem>
	  <para>The <package>misc/freebsd-doc-all</package>
	    meta-package or port installs all documentation in all
	    available languages.</para>
	</listitem>

	<listitem>
	  <para>There is a package and port for each translation, such
	    as <package>misc/freebsd-doc-hu</package> for the
	    Hungarian documentation.</para>
	</listitem>
      </itemizedlist>

      <para>When binary packages are used, the &os; documentation will
	be installed in all available formats for the given language.
	For example, the following command will install the latest
	package of the Hungarian documentation:</para>

      <screen>&prompt.root; <userinput>pkg install hu-freebsd-doc</userinput></screen>

      <note>
	<para>Packages use a format that differs from the
	  corresponding port's name:
	  <literal><replaceable>lang</replaceable>-freebsd-doc</literal>,
	  where <replaceable>lang</replaceable> is the short format of
	  the language code, such as <literal>hu</literal> for
	  Hungarian, or <literal>zh_cn</literal> for Simplified
	  Chinese.</para>
      </note>

      <para>To specify the format of the documentation, build the port
	instead of installing the package.  For example, to build and
	install the English documentation:</para>

      <screen>&prompt.root; <userinput>cd /usr/ports/misc/freebsd-doc-en</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>

      <para>The port provides a configuration menu where the format to
	build and install can be specified.  By default, split
	<acronym>HTML</acronym>, similar to the format used on <uri
	  xlink:href="http://www.FreeBSD.org">http://www.FreeBSD.org</uri>,
	and <acronym>PDF</acronym> are selected.</para>

      <para>Alternately, several <command>make</command> options can
	be specified when building a documentation port,
	including:</para>

      <variablelist>
	<varlistentry>
	  <term><varname>WITH_HTML</varname></term>

	  <listitem>
	    <para>Builds the HTML format with a single HTML file per
	      document.  The formatted documentation is saved to a
	      file called <filename>article.html</filename>, or
	      <filename>book.html</filename>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><varname>WITH_PDF</varname></term>

	  <listitem>
	    <para>The formatted documentation is saved to a file
	      called <filename>article.pdf</filename> or
	      <filename>book.pdf</filename>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><varname>DOCBASE</varname></term>

	  <listitem>
	    <para>Specifies where to install the documentation.  It
	      defaults to
	      <filename>/usr/local/share/doc/freebsd</filename>.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>This example uses variables to install the Hungarian
	documentation as a <acronym>PDF</acronym> in the specified
	directory:</para>

      <screen>&prompt.root; <userinput>cd /usr/ports/misc/freebsd-doc-hu</userinput>
&prompt.root; <userinput>make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install clean</userinput></screen>

      <para>Documentation packages or ports can be updated using the
	instructions in <xref linkend="ports"/>.  For example, the
	following command updates the installed Hungarian
	documentation using <package>ports-mgmt/portmaster</package>
	by using packages only:</para>

      <screen>&prompt.root; <userinput>portmaster -PP hu-freebsd-doc</userinput></screen>
    </sect2>
  </sect1>

  <sect1 xml:id="current-stable">
    <title>Tracking a Development Branch</title>

    <indexterm><primary>-CURRENT</primary></indexterm>
    <indexterm><primary>-STABLE</primary></indexterm>

    <para>&os; has two development branches: &os.current; and
      &os.stable;.</para>

    <para>This section provides an explanation of each branch and its
      intended audience, as well as how to keep a system up-to-date
      with each respective branch.</para>

    <sect2 xml:id="current">
      <title>Using &os.current;</title>

      <para>&os.current; is the <quote>bleeding edge</quote> of &os;
	development and  &os.current; users are expected to have a
	high degree of technical skill.  Less technical users who wish
	to track a development branch should track &os.stable;
	instead.</para>

      <para>&os.current; is the very latest source code for &os; and
	includes works in progress, experimental changes, and
	transitional mechanisms that might or might not be present in
	the next official release.  While many &os; developers compile
	the &os.current; source code daily, there are short periods of
	time when the source may not be buildable.  These problems are
	resolved as quickly as possible, but whether or not
	&os.current; brings disaster or new functionality can be a
	matter of when the source code was synced.</para>

      <para>&os.current; is made available for three primary interest
	groups:</para>

      <orderedlist>
	<listitem>
	  <para>Members of the &os; community who are actively
	    working on some part of the source tree.</para>
	</listitem>

	<listitem>
	  <para>Members of the &os; community who are active testers.
	    They are willing to spend time solving problems, making
	    topical suggestions on changes and the general direction
	    of &os;, and submitting patches.</para>
	</listitem>

	<listitem>
	  <para>Users who wish to keep an eye on things, use the
	    current source for reference purposes, or make the
	    occasional comment or code contribution.</para>
	</listitem>
      </orderedlist>

      <para>&os.current; should <emphasis>not</emphasis> be
	considered a fast-track to getting new features before the
	next release as pre-release features are not yet fully tested
	and most likely contain bugs.  It is not a quick way of
	getting bug fixes as any given commit is just as likely to
	introduce new bugs as to fix existing ones.  &os.current; is
	not in any way <quote>officially supported</quote>.</para>

      <indexterm>
	<primary>-CURRENT</primary>
	<secondary>using</secondary>
      </indexterm>

      <para>To track &os.current;:</para>

      <orderedlist>
	<listitem>
	  <para>Join the &a.current.name; and the
	    &a.svn-src-head.name; lists.  This is
	    <emphasis>essential</emphasis> in order to see the
	    comments that people are making about the current state
	    of the system and to receive important bulletins about
	    the current state of &os.current;.</para>

	  <para>The &a.svn-src-head.name; list records the commit log
	    entry for each change as it is made, along with any
	    pertinent information on possible side effects.</para>

	  <para>To join these lists, go to &a.mailman.lists.link;,
	    click on the list to subscribe to, and follow the
	    instructions.  In order to track changes to the whole
	    source tree, not just the changes to &os.current;,
	    subscribe to the &a.svn-src-all.name; list.</para>
	</listitem>

	<listitem>
	  <para>Synchronize with the &os.current; sources.  Typically,
	    <link linkend="svn">svnlite</link> is used to check out the
	    -CURRENT code from the <literal>head</literal> branch of
	    one of the Subversion mirror sites listed in
	    <xref linkend="svn-mirrors"/>.</para>
	</listitem>

	<listitem>
	  <para>Due to the size of the repository, some users choose
	    to only synchronize the sections of source that interest
	    them  or which they are contributing patches to.  However,
	    users that plan to compile the operating system from
	    source must download <emphasis>all</emphasis> of
	    &os.current;, not just selected portions.</para>

	  <para>Before compiling &os.current;
	    <indexterm>
	      <primary>-CURRENT</primary>
		<secondary>compiling</secondary>
	    </indexterm>, read <filename>/usr/src/Makefile</filename>
	    very carefully and follow the instructions in
	    <xref linkend="makeworld"/>.
	    Read the &a.current; and
	    <filename>/usr/src/UPDATING</filename> to stay
	    up-to-date on other bootstrapping procedures that
	    sometimes become necessary on the road to the next
	    release.</para>
	</listitem>

	<listitem>
	  <para>Be active! &os.current; users are encouraged to
	    submit their suggestions for enhancements or bug fixes.
	    Suggestions with accompanying code are always
	    welcome.</para>
	</listitem>
      </orderedlist>
    </sect2>

    <sect2 xml:id="stable">
      <title>Using &os.stable;</title>

      <para>&os.stable; is the development branch from which major
	releases are made.  Changes go into this branch at a slower
	pace and with the general assumption that they have first been
	tested in &os.current;.  This is <emphasis>still</emphasis> a
	development branch and, at any given time, the sources for
	&os.stable; may or may not be suitable for general use.  It is
	simply another engineering development track, not a resource
	for end-users.  Users who do not have the resources to perform
	testing should instead run the most recent release of
	&os;.</para>

      <para>Those interested in tracking or contributing to the &os;
	development process, especially as it relates to the next
	release of &os;, should consider following &os.stable;.</para>

      <para>While the &os.stable; branch should compile and run at all
	times, this cannot be guaranteed.  Since more people run
	&os.stable; than &os.current;, it is inevitable that bugs and
	corner cases will sometimes be found in &os.stable; that were
	not apparent in &os.current;.  For this reason, one should not
	blindly track &os.stable;.  It is particularly important
	<emphasis>not</emphasis> to update any production servers to
	&os.stable; without thoroughly testing the code in a
	development or testing environment.</para>

      <para>To track &os.stable;:</para>

      <indexterm>
	<primary>-STABLE</primary>
	  <secondary>using</secondary>
      </indexterm>
      <orderedlist>
	<listitem>
	  <para>Join the &a.stable.name; list in order to stay
	    informed of build dependencies that may appear in
	    &os.stable; or any other issues requiring special
	    attention.  Developers will also make announcements in
	    this mailing list when they are contemplating some
	    controversial fix or update, giving the users a chance to
	    respond if they have any issues to raise concerning the
	    proposed change.</para>

	  <para>Join the relevant <application>svn</application> list
	    for the branch being tracked.  For example, users
	    tracking the 9-STABLE branch should join the
	    &a.svn-src-stable-9.name; list.  This list records the
	    commit log entry for each change as it is made, along
	    with any pertinent information on possible
	    side effects.</para>

	  <para>To join these lists, go to &a.mailman.lists.link;,
	    click on the list to subscribe to, and follow the
	    instructions.  In order to track changes for the whole
	    source tree, subscribe to &a.svn-src-all.name;.</para>
	</listitem>

	<listitem>
	  <para>To install a new &os.stable; system, install the most
	    recent &os.stable; release from the <link
	      linkend="mirrors">&os; mirror sites</link> or use a
	    monthly snapshot built from &os.stable;.  Refer to <link
	      xlink:href="&url.base;/snapshots/">www.freebsd.org/snapshots</link>
	    for more information about snapshots.</para>

	  <para>To compile or upgrade to an existing &os; system to
	    &os.stable;, use <link linkend="svn">svn</link>
	      <indexterm>
		<primary>Subversion</primary>
	      </indexterm> to check out the source for the desired
	    branch.  Branch names, such as
	    <literal>stable/9</literal>, are listed at <link
	      xlink:href="&url.base;/releng/">www.freebsd.org/releng</link>.</para>
	</listitem>

	<listitem>
	  <para>Before compiling or upgrading to &os.stable;
	    <indexterm>
	      <primary>-STABLE</primary>
		<secondary>compiling</secondary>
	    </indexterm>, read <filename>/usr/src/Makefile</filename>
	    carefully and follow the instructions in <xref
	      linkend="makeworld"/>.  Read the &a.stable; and
	    <filename>/usr/src/UPDATING</filename> to keep up-to-date
	    on other bootstrapping procedures that sometimes become
	    necessary on the road to the next release.</para>
	</listitem>
      </orderedlist>
    </sect2>
  </sect1>

  <sect1 xml:id="makeworld">
    <title xml:id="updating-src">Updating &os; from Source</title>

    <para>Updating &os; by compiling from source offers several
      advantages over binary updates.  Code can be built with options
      to take advantage of specific hardware.  Parts of the base
      system can be built with non-default settings, or left out
      entirely where they are not needed or desired.  The build
      process takes longer to update a system than just installing
      binary updates, but allows complete customization to produce
      a tailored version of &os;.</para>

    <sect2 xml:id="updating-src-quick-start">
      <title>Quick Start</title>

      <para>This is a quick reference for the typical steps used to
	update &os; by building from source.  Later sections describe
	the process in more detail.</para>

      <procedure>
	<step>
	  <title>Update and Build</title>

	  <screen>&prompt.root; <userinput>svnlite update /usr/src</userinput>  <co xml:id="updating-src-qs-svnup"/>
<emphasis>check <filename>/usr/src/UPDATING</filename></emphasis>  <co xml:id="updating-src-qs-review-updating"/>
&prompt.root; <userinput>cd /usr/src</userinput>          <co xml:id="updating-src-qs-cd"/>
&prompt.root; <userinput>make -j<replaceable>4</replaceable> buildworld</userinput>  <co xml:id="updating-src-qs-buildworld"/>
&prompt.root; <userinput>make -j<replaceable>4</replaceable> kernel</userinput>      <co xml:id="updating-src-qs-kernel"/>
&prompt.root; <userinput>shutdown -r now</userinput>      <co xml:id="updating-src-qs-reboot"/>
&prompt.root; <userinput>cd /usr/src</userinput>          <co xml:id="updating-src-qs-cd2"/>
&prompt.root; <userinput>make installworld</userinput>    <co xml:id="updating-src-qs-installworld"/>
&prompt.root; <userinput>mergemaster -Ui</userinput>      <co xml:id="updating-src-qs-mergemaster"/>
&prompt.root; <userinput>shutdown -r now</userinput>      <co xml:id="updating-src-qs-shutdown"/></screen>

	  <calloutlist>
	    <callout arearefs="updating-src-qs-svnup">
	      <para>Get the latest version of the source.  See
		<xref linkend="updating-src-obtaining-src"/> for
		more information on obtaining and updating
		source.</para>
	    </callout>

	    <callout arearefs="updating-src-qs-review-updating">
	      <para>Check <filename>/usr/src/UPDATING</filename>
		for any manual steps required before or after building
		from source.</para>
	    </callout>

	    <callout arearefs="updating-src-qs-cd">
	      <para>Go to the source directory.</para>
	    </callout>

	    <callout arearefs="updating-src-qs-buildworld">
	      <para>Compile the world, everything except the
		kernel.</para>
	    </callout>

	    <callout arearefs="updating-src-qs-kernel">
	      <para>Compile and install the kernel.  This is
		equivalent to <command>make buildkernel
		  installkernel</command>.</para>
	    </callout>

	    <callout arearefs="updating-src-qs-reboot">
	      <para>Reboot the system to the new kernel.</para>
	    </callout>

	    <callout arearefs="updating-src-qs-cd2">
	      <para>Go to the source directory.</para>
	    </callout>

	    <callout arearefs="updating-src-qs-installworld">
	      <para>Install the world.</para>
	    </callout>

	    <callout arearefs="updating-src-qs-mergemaster">
	      <para>Update and merge configuration files in
		<filename>/etc/</filename>.</para>
	    </callout>

	    <callout arearefs="updating-src-qs-shutdown">
	      <para>Restart the system to use the newly-built world
		and kernel.</para>
	    </callout>
	  </calloutlist>
	</step>
      </procedure>
    </sect2>

    <sect2 xml:id="updating-src-preparing">
      <title>Preparing for a Source Update</title>

      <para>Read <filename>/usr/src/UPDATING</filename>.  Any manual
	steps that must be performed before or after an update are
	described in this file.</para>
    </sect2>

    <sect2 xml:id="updating-src-obtaining-src">
      <title>Updating the Source</title>

      <para>&os; source code is located in
	<filename>/usr/src/</filename>.  The preferred method of
	updating this source is through the
	<application>Subversion</application> version control system.
	Verify that the source code is under version control:</para>

      <screen>&prompt.root; <userinput>svnlite info /usr/src</userinput>
Path: /usr/src
Working Copy Root Path: /usr/src
...</screen>

      <para>This indicates that <filename>/usr/src/</filename>
	is under version control and can be updated with
	&man.svnlite.1;:</para>

      <screen xml:id="synching">&prompt.root; <userinput>svnlite update /usr/src</userinput></screen>

      <para>The update process can take some time if the directory has
	not been updated recently.  After it finishes, the source code
	is up to date and the build process described in the next
	section can begin.</para>

      <note xml:id="updating-src-obtaining-src-checkout">
	<title>Obtaining the Source</title>

	<para>If the output says
	  <literal>'/usr/src' is not a working copy</literal>, the
	  files there are missing or were installed with a different
	  method.  A new checkout of the source is required.</para>

	<table xml:id="updating-src-obtaining-src-repopath">
	  <title>&os; Versions and Repository Paths</title>

	  <tgroup cols="3">
	    <thead>
	      <row>
		<entry><command>uname -r</command> Output</entry>
		<entry>Repository Path</entry>
		<entry>Description</entry>
	      </row>
	    </thead>

	    <tbody>
	      <row>
		<entry><literal><replaceable>X.Y</replaceable>-RELEASE</literal></entry>
		<entry><literal>base/releng/</literal><replaceable>X.Y</replaceable></entry>
		<entry>The Release version plus only critical security
		  and bug fix patches.  This branch is recommended
		  for most users.</entry>
	      </row>

	      <row xml:id="STABLE">
		<entry><literal><replaceable>X.Y</replaceable>-STABLE</literal></entry>
		<entry><literal>base/stable/</literal><replaceable>X</replaceable></entry>
		<entry>
		  <para>The Release version plus all additional
		    development on that branch.
		    <emphasis>STABLE</emphasis> refers to the
		    Applications Binary Interface
		    (<acronym>ABI</acronym>) not changing, so software
		    compiled for earlier versions still runs.  For
		    example, software compiled to run on &os; 10.1
		    will still run on &os; 10-STABLE compiled
		    later.</para>

		  <para>STABLE branches occasionally have bugs or
		    incompatibilities which might affect users,
		    although these are typically fixed quickly.</para>
		</entry>
	      </row>

	      <row>
		<entry><literal><replaceable>X</replaceable>-CURRENT</literal></entry>
		<entry><literal>base/head/</literal></entry>
		<entry>The latest unreleased development version of
		  &os;.  The CURRENT branch can have major bugs or
		  incompatibilities and is recommended only for
		  advanced users.</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>

	<para>Determine which version of &os; is being used with
	  &man.uname.1;:</para>

	<screen>&prompt.root; <userinput>uname -r</userinput>
10.3-RELEASE</screen>

	<para>Based on
	  <xref linkend="updating-src-obtaining-src-repopath"/>, the
	  source used to update <literal>10.3-RELEASE</literal> has
	  a repository path of <literal>base/releng/10.3</literal>.
	  That path is used when checking out the source:</para>

	<screen>&prompt.root; <userinput>mv /usr/src /usr/src.bak</userinput>  <co xml:id="updating-src-obtaining-src-mv"/>
&prompt.root; <userinput>svnlite checkout https://svn.freebsd.org/base/<replaceable>releng/10.3</replaceable> /usr/src</userinput>  <co xml:id="updating-src-obtaining-src-checkout-cmd"/></screen>

	<calloutlist>
	  <callout arearefs="updating-src-obtaining-src-mv">
	    <para>Move the old directory out of the way.  If there are
	      no local modifications in this directory, it can be
	      deleted.</para>
	  </callout>

	  <callout arearefs="updating-src-obtaining-src-checkout-cmd">
	    <para>The path from
	      <xref linkend="updating-src-obtaining-src-repopath"/> is
	      added to the repository <acronym>URL</acronym>.  The
	      third parameter is the destination directory for the
	      source code on the local system.</para>
	  </callout>
	</calloutlist>
      </note>
    </sect2>

    <sect2 xml:id="updating-src-building">
      <title>Building from Source</title>

      <para>The <emphasis>world</emphasis>, or all
	of the operating system except the kernel, is compiled.  This
	is done first to provide up-to-date tools to build the kernel.
	Then the kernel itself is built:</para>

      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make buildworld</userinput>
&prompt.root; <userinput>make buildkernel</userinput></screen>

      <para>The compiled code is written to
	<filename>/usr/obj</filename>.</para>

      <para>These are the basic steps.  Additional options to control
	the build are described below.</para>

      <sect3 xml:id="updating-src-building-clean-build">
	<title>Performing a Clean Build</title>

	<para>Some versions of the &os; build system leave
	  previously-compiled code in the temporary object directory,
	  <filename>/usr/obj</filename>.  This can speed up later
	  builds by avoiding recompiling code that has not changed.
	  To force a clean rebuild of everything, use
	  <buildtarget>cleanworld</buildtarget> before starting
	  a build:</para>

	<screen>&prompt.root; <userinput>make cleanworld</userinput></screen>
      </sect3>

      <sect3 xml:id="updating-src-building-jobs">
	<title>Setting the Number of Jobs</title>

	<para>Increasing the number of build jobs on multi-core
	  processors can improve build speed.  Determine the number of
	  cores with <command>sysctl hw.ncpu</command>.  Processors
	  vary, as do the build systems used with different versions
	  of &os;, so testing is the only sure method to tell how a
	  different number of jobs affects the build speed.  For a
	  starting point, consider values between half and double the
	  number of cores.  The number of jobs is specified with
	  <option>-j</option>.</para>

	<example xml:id="updating-src-building-jobs-example">
	  <title>Increasing the Number of Build Jobs</title>

	  <para>Building the world and kernel with four jobs:</para>

	  <screen>&prompt.root; <userinput>make -j4 buildworld buildkernel</userinput></screen>
	</example>
      </sect3>

      <sect3 xml:id="updating-src-building-only-kernel">
	<title>Building Only the Kernel</title>

	<para>A <buildtarget>buildworld</buildtarget> must be
	  completed if the source code has changed.  After that, a
	  <buildtarget>buildkernel</buildtarget> to build a kernel can
	  be run at any time.  To build just the kernel:</para>

	<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make buildkernel</userinput></screen>
      </sect3>

      <sect3 xml:id="updating-src-building-custom-kernel">
	<title>Building a Custom Kernel</title>

	<para>The standard &os; kernel is based on a
	  <emphasis>kernel config file</emphasis> called
	  <filename>GENERIC</filename>.  The
	  <filename>GENERIC</filename> kernel includes the most
	  commonly-needed device drivers and options.  Sometimes it
	  is useful or necessary to build a custom kernel, adding or
	  removing device drivers or options to fit a specific
	  need.</para>

	<para>For example, someone developing a small embedded
	  computer with severely limited <acronym>RAM</acronym> could
	  remove unneeded device drivers or options to make the kernel
	  slightly smaller.</para>

	<para>Kernel config files are located in
	  <filename>/usr/src/sys/<replaceable>arch</replaceable>/conf/</filename>,
	  where <replaceable>arch</replaceable> is the output from
	  <command>uname -m</command>.  On most computers, that is
	  <literal>amd64</literal>, giving a config file directory of
	  <filename>/usr/src/sys/<replaceable>amd64</replaceable>/conf/</filename>.</para>

	<tip>
	  <para><filename>/usr/src</filename> can be deleted or
	    recreated, so it is preferable to keep custom kernel
	    config files in a separate directory, like
	    <filename>/root</filename>.  Link the kernel config file
	    into the <filename>conf</filename> directory.  If that
	    directory is deleted or overwritten, the kernel config
	    can be re-linked into the new one.</para>
	</tip>

	<para>A custom config file can be created by copying the
	  <filename>GENERIC</filename> config file.  In this example,
	  the new custom kernel is for a storage server, so is named
	  <filename>STORAGESERVER</filename>:</para>

	<screen>&prompt.root; <userinput>cp /usr/src/sys/amd64/conf/GENERIC /root/STORAGESERVER</userinput>
&prompt.root; <userinput>cd /usr/src/sys/amd64/conf</userinput>
&prompt.root; <userinput>ln -s /root/STORAGESERVER .</userinput></screen>

	<para><filename>/root/STORAGESERVER</filename> is then edited,
	  adding or removing devices or options as shown in
	  &man.config.5;.</para>

	<para>The custom kernel is built by setting
	  <varname>KERNCONF</varname> to the kernel config file on the
	  command line:</para>

	<screen>&prompt.root; <userinput>make buildkernel KERNCONF=STORAGESERVER</userinput></screen>
      </sect3>
    </sect2>

    <sect2 xml:id="updating-src-installing">
      <title>Installing the Compiled Code</title>

      <para>After the <buildtarget>buildworld</buildtarget> and
	<buildtarget>buildkernel</buildtarget> steps have been
	completed, the new kernel and world are installed:</para>

      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make installkernel</userinput>
&prompt.root; <userinput>shutdown -r now</userinput>
&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make installworld</userinput>
&prompt.root; <userinput>shutdown -r now</userinput></screen>

      <para>If a custom kernel was built, <varname>KERNCONF</varname>
	must also be set to use the new custom kernel:</para>

      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make installkernel KERNCONF=STORAGESERVER</userinput>
&prompt.root; <userinput>shutdown -r now</userinput>
&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make installworld</userinput>
&prompt.root; <userinput>shutdown -r now</userinput></screen>
    </sect2>

    <sect2 xml:id="updating-src-completing">
      <title>Completing the Update</title>

      <para>A few final tasks complete the update.  Any modified
	configuration files are merged with the new versions, outdated
	libraries are located and removed, then the system is
	restarted.</para>

      <sect3 xml:id="updating-src-completing-merge-mergemaster">
	<title>Merging Configuration Files with
	  &man.mergemaster.8;</title>

	<para>&man.mergemaster.8; provides an easy
	  way to merge changes that have been made to system
	  configuration files with new versions of those files.</para>

	<para>With <option>-Ui</option>, &man.mergemaster.8;
	  automatically updates files that have not been user-modified
	  and installs new files that are not already present:</para>

	<screen>&prompt.root; <userinput>mergemaster -Ui</userinput></screen>

	<para>If a file must be manually merged, an interactive
	  display allows the user to choose which portions of the
	  files are kept.  See &man.mergemaster.8; for more
	  information.</para>
      </sect3>

      <sect3 xml:id="updating-src-completing-check-old">
	<title>Checking for Outdated Files and Libraries</title>

	<para>Some obsolete files or directories can remain after an
	  update.  These files can be located:</para>

	<screen>&prompt.root; <userinput>make check-old</userinput></screen>

	<para>and deleted:</para>

	<screen>&prompt.root; <userinput>make delete-old</userinput></screen>

	<para>Some obsolete libraries can also remain.  These can be
	  detected with:</para>

	<screen>&prompt.root; <userinput>make check-old-libs</userinput></screen>

	<para>and deleted with</para>

	<screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>

	<para>Programs which were still using those old libraries will
	  stop working when the library has been deleted.  These
	  programs must be rebuilt or replaced after deleting the old
	  libraries.</para>

	<tip>
	  <para>When all the old files or directories are known to be
	    safe to delete, pressing <keycap>y</keycap> and
	    <keycap>Enter</keycap> to delete each file can be avoided
	    by setting <varname>BATCH_DELETE_OLD_FILES</varname> in
	    the command.  For example:</para>

	  <screen>&prompt.root; <userinput>make BATCH_DELETE_OLD_FILES=yes delete-old-libs</userinput></screen>
	</tip>
      </sect3>

      <sect3 xml:id="updating-src-completing-restart">
	<title>Restarting After the Update</title>

	<para>The last step after updating is to restart the computer
	  so all the changes take effect:</para>

	<screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
      </sect3>
    </sect2>
  </sect1>

  <sect1 xml:id="small-lan">
    <info>
      <title>Tracking for Multiple Machines</title>

      <authorgroup>
	<author>
	  <personname>
	    <firstname>Mike</firstname>
	    <surname>Meyer</surname>
	  </personname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
    </info>

    <indexterm>
      <primary>NFS</primary>
      <secondary>installing multiple machines</secondary>
    </indexterm>

    <para>When multiple machines need to track the same source tree,
      it is a waste of disk space, network bandwidth, and
      <acronym>CPU</acronym> cycles to have each system download the
      sources and rebuild everything.  The solution is to have one
      machine do most of the work, while the rest of the machines
      mount that work via <acronym>NFS</acronym>.  This section
      outlines a method of doing so.  For more information about using
      <acronym>NFS</acronym>, refer to <xref
	linkend="network-nfs"/>.</para>

    <para>First, identify a set of machines which will run the same
      set of binaries, known as a <firstterm>build set</firstterm>.
      Each machine can have a custom kernel, but will run the same
      userland binaries.  From that set, choose a machine to be the
      <firstterm>build machine</firstterm> that the world and kernel
      are built on.  Ideally, this is a fast machine that has
      sufficient spare <acronym>CPU</acronym> to run <command>make
	buildworld</command> and <command>make
	buildkernel</command>.</para>

    <para>Select a machine to be the <firstterm>test
	machine</firstterm>, which will test software updates before
      they are put into production.  This <emphasis>must</emphasis> be
      a machine that can afford to be down for an extended period of
      time.  It can be the build machine, but need not be.</para>

    <para>All the machines in this build set need to mount
      <filename>/usr/obj</filename> and <filename>/usr/src</filename>
      from the build machine via <acronym>NFS</acronym>.  For multiple
      build sets, <filename>/usr/src</filename> should be on one build
      machine, and <acronym>NFS</acronym> mounted on the rest.</para>

    <para>Ensure that <filename>/etc/make.conf</filename> and
      <filename>/etc/src.conf</filename> on all the machines in the
      build set agree with the build machine.  That means that the
      build machine must build all the parts of the base system that
      any machine in the build set is going to install.  Also, each
      build machine should have its kernel name set with
      <varname>KERNCONF</varname> in
      <filename>/etc/make.conf</filename>, and the build machine
      should list them all in its <varname>KERNCONF</varname>,
      listing its own kernel first.  The build machine must have the
      kernel configuration files for each machine in its <filename
	>/usr/src/sys/<replaceable>arch</replaceable>/conf</filename>.</para>

    <para>On the build machine, build the kernel and world as
      described in <xref linkend="makeworld"/>, but do not install
      anything on the build machine.  Instead, install the built
      kernel on the test machine.  On the test machine, mount
      <filename>/usr/src</filename> and
      <filename>/usr/obj</filename> via <acronym>NFS</acronym>.  Then,
      run <command>shutdown now</command> to go to single-user mode in
      order to install the new kernel and world and run
      <command>mergemaster</command> as usual.  When done, reboot to
      return to normal multi-user operations.</para>

    <para>After verifying that everything on the test machine is
      working properly, use the same procedure to install the new
      software on each of the other machines in the build set.</para>

    <para>The same methodology can be used for the ports tree.  The
      first step is to share <filename>/usr/ports</filename> via
      <acronym>NFS</acronym> to all the machines in the build set.  To
      configure <filename>/etc/make.conf</filename> to share
      distfiles, set <varname>DISTDIR</varname> to a common shared
      directory that is writable by whichever user <systemitem
	class="username">root</systemitem> is mapped to by the
      <acronym>NFS</acronym> mount.  Each machine should set
      <varname>WRKDIRPREFIX</varname> to a local build directory, if
      ports are to be built locally.  Alternately, if the build system
      is to build and distribute packages to the machines in the build
      set, set <varname>PACKAGES</varname> on the build system to a
      directory similar to <varname>DISTDIR</varname>.</para>
  </sect1>
</chapter>