Remove remainings of the oltr(4).
[dragonfly.git] / share / doc / smm / 01.setup / 2.t
1 .\" Copyright (c) 1988, 1993 The Regents of the University of California.
2 .\" All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\"    must display the following acknowledgement:
14 .\"     This product includes software developed by the University of
15 .\"     California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\"    may be used to endorse or promote products derived from this software
18 .\"    without specific prior written permission.
19 .\"
31 .\"
32 .\"     @(#)2.t 8.1 (Berkeley) 7/27/93
33 .\" $FreeBSD: src/share/doc/smm/01.setup/2.t,v 1.7 1999/08/28 00:18:35 peter Exp $
34 .\" $DragonFly: src/share/doc/smm/01.setup/2.t,v 1.2 2003/06/17 04:36:57 dillon Exp $
35 .\"
36 .ds lq ``
37 .ds rq ''
38 .ds LH "Installing/Operating \*(4B
39 .ds RH Bootstrapping
40 .ds CF \*(Dy
41 .Sh 1 "Bootstrap procedure"
42 .PP
43 This section explains the bootstrap procedure that can be used
44 to get the kernel supplied with this distribution running on your machine.
45 If you are not currently running \*(Ps you will
46 have to do a full bootstrap.
47 Section 3 describes how to upgrade a \*(Ps system.
48 An understanding of the operations used in a full bootstrap
49 is helpful in doing an upgrade as well.
50 In either case, it is highly desirable to read and understand
51 the remainder of this document before proceeding.
52 .PP
53 The distribution supports a somewhat wider set of machines than
54 those for which we have built binaries.
55 The architectures that are supported only in source form include:
56 .IP \(bu
57 Intel 386/486-based machines (ISA/AT or EISA bus only)
58 .IP \(bu
59 Sony News MIPS-based workstations
60 .IP \(bu
61 Omron Luna 68000-based workstations
62 .LP
63 If you wish to run one of these architectures,
64 you will have to build a cross compilation environment.
65 Note that the distribution does
66 .B not
67 include the machine support for the Tahoe and VAX architectures
68 found in previous BSD distributions.
69 Our primary development environment is the HP9000/300 series machines.
70 The other architectures are developed and supported by
71 people outside the university.
72 Consequently, we are not able to directly test or maintain these 
73 other architectures, so cannot comment on their robustness,
74 reliability, or completeness.
75 .Sh 2 "Bootstrapping from the tape"
76 .LP
77 The set of files on the distribution tape are as follows:
78 .IP 1)
79 A
80 .Xr dd (1)
81 (HP300),
82 .Xr tar (1)
83 (DECstation), or
84 .Xr dump (8)
85 (SPARC) image of the root filesystem
86 .IP 2)
87 A
88 .Xr tar
89 image of the
90 .Pn /var
91 filesystem
92 .IP 3)
93 A
94 .Xr tar
95 image of the
96 .Pn /usr
97 filesystem
98 .IP 4)
99 A
100 .Xr tar
101 image of
102 .Pn /usr/src/sys
103 .IP 5)
104 A
105 .Xr tar
106 image of
107 .Pn /usr/src
108 except sys and contrib
109 .IP 6)
110 A
111 .Xr tar
112 image of
113 .Pn /usr/src/contrib
114 .IP 7)
115 (8mm Exabyte tape distributions only)
116 A
117 .Xr tar
118 image of
119 .Pn /usr/src/X11R5
120 .LP
121 The tape bootstrap procedure used to create a
122 working system involves the following major steps:
123 .IP 1)
124 Transfer a bootable root filesystem from the tape to a disk
125 and get it booted and running.
126 .IP 2)
127 Build and restore the
128 .Pn /var
129 and
130 .Pn /usr
131 filesystems from tape with
132 .Xr tar (1).
133 .IP 3)
134 Extract the system and utility source files as desired.
135 .PP
136 The following sections describe the above steps in detail.
137 The details of the first step vary between architectures.
138 The specific steps for the HP300, SPARC, and DECstation are
139 given in the next three sections respectively.
140 You should follow the instructions for your particular architecture.
141 In all sections,
142 commands you are expected to type are shown in italics, while that
143 information printed by the system is shown emboldened.
144 .Sh 2 "Booting the HP300"
145 .Sh 3 "Supported hardware"
146 .LP
147 The hardware supported by \*(4B for the HP300/400 is as follows:
148 .TS
149 center box;
150 lw(1i) lw(4i).
151 CPU's   T{
152 68020 based (318, 319, 320, 330 and 350),
153 68030 based (340, 345, 360, 370, 375, 400) and
154 68040 based (380, 425, 433).
155 T}
156 _
157 DISK's  T{
158 HP-IB/CS80 (7912, 7914, 7933, 7936, 7945, 7957, 7958, 7959, 2200, 2203)
159 and SCSI-I (including magneto-optical).
160 T}
161 _
162 TAPE's  T{
163 Low-density CS80 cartridge (7914, 7946, 9144),
164 high-density CS80 cartridge (9145),
165 HP SCSI DAT and
166 SCSI Exabyte.
167 T}
168 _
169 RS232   T{
170 98644 built-in single-port, 98642 4-port and 98638 8-port interfaces.
171 T}
172 _
174 98643 internal and external LAN cards.
175 T}
176 _
177 GRAPHICS        T{
178 Terminal emulation and raw frame buffer support for
179 98544 / 98545 / 98547 (Topcat color & monochrome),
180 98548 / 98549 / 98550 (Catseye color & monochrome),
181 98700 / 98710 (Gatorbox),
182 98720 / 98721 (Renaissance),
183 98730 / 98731 (DaVinci) and
184 A1096A (Hyperion monochrome).
185 T}
186 _
187 INPUT   T{
188 General interface supporting all HIL devices.
189 (e.g. keyboard, 2 and 3 button mice, ID module, ...)
190 T}
191 _
192 MISC    T{
193 Battery-backed real time clock,
194 builtin and 98625A/B HP-IB interfaces,
195 builtin and 98658A SCSI interfaces,
196 serial printers and plotters on HP-IB,
197 and SCSI autochanger device.
198 T}
199 .TE
200 .LP
201 Major items that are not supported
202 include the 310 and 332 CPU's, 400 series machines
203 configured for Domain/OS, EISA and VME bus adaptors, audio, the centronics
204 port, 1/2" tape drives (7980), CD-ROM, and the PVRX/TVRX 3D graphics displays.
205 .Sh 3 "Standalone device file naming"
206 .LP
207 The standalone system device name syntax on the HP300 is of the form:
208 .DS
209 xx(a,c,u,p)
210 .DE
211 where
212 \fIxx\fP is the device type,
213 \fIa\fP specifies the adaptor to use,
214 \fIc\fP the controller,
215 \fIu\fP the unit, and
216 \fIp\fP a partition.
217 The \fIdevice type\fP differentiates the various disks and tapes and is one of:
218 ``rd'' for HP-IB CS80 disks,
219 ``ct'' for HP-IB CS80 cartridge tapes, or
220 ``sd'' for SCSI-I disks
221 (SCSI-I tapes are currently not supported).
222 The \fIadaptor\fP field is a logical HP-IB or SCSI bus adaptor card number.
223 This will typically be
224 0 for SCSI disks,
225 0 for devices on the ``slow'' HP-IB interface (usually tapes) and
226 1 for devices on the ``fast'' HP-IB interface (usually disks).
227 To get a complete mapping of physical (select-code) to logical card numbers
228 just type a ^C at the standalone prompt.
229 The \fIcontroller\fP field is the disk or tape's target number on the
230 HP-IB or SCSI bus.
231 For SCSI the range is 0 to 6 (7 is the adaptor address) and
232 for HP-IB the range is 0 to 7.
233 The \fIunit\fP field is unused and should be 0.
234 The \fIpartition\fP field is interpreted differently for tapes
235 and disks: for disks it is a disk partition (in the range 0-7),
236 and for tapes it is a file number offset on the tape.
237 Thus, partition 2 of a SCSI disk drive at target 3 on SCSI bus 1
238 would be ``sd(1,3,0,2)''.
239 If you have only one of any type bus adaptor, you may omit the adaptor
240 and controller numbers;
241 e.g. ``sd(0,2)'' could be used instead of ``sd(0,0,0,2)''.
242 The following examples always use the full syntax for clarity.
243 .Sh 3 "The procedure"
244 .LP
245 The basic steps involved in bringing up the HP300 are as follows:
246 .IP 1)
247 Obtain a second disk and format it, if necessary.
248 .IP 2)
249 Copy a root filesystem from the
250 tape onto the beginning of the disk.
251 .IP 3)
252 Boot the UNIX system on the new disk.
253 .IP 4)
254 (Optional) Build a root filesystem optimized for your disk.
255 .IP 5)
256 Label the disks with the
257 .Xr disklabel (8)
258 program.
259 .Sh 4 "Step 1: selecting and formatting a disk"
260 .PP
261 For your first system you will have to obtain a formatted disk
262 of a type given in the ``supported hardware'' list above.
263 If you want to load an entire binary system
264 (i.e., everything except
265 .Pn /usr/src ),
266 on the single disk you will need a minimum of 290MB,
267 ruling out anything smaller than a 7959B/S disk.
268 The disklabel included in the bootstrap root image is laid out
269 to accommodate this scenario.
270 Note that an HP SCSI magneto-optical disk will work fine for this case.
271 \*(4B will boot and run (albeit slowly) using one.
272 If you want to load source on a single disk system,
273 you will need at least 640MB (at least a 2213A SCSI or 2203A HP-IB disk).
274 A disk as small as the 7945A (54MB) can be used for the bootstrap
275 procedure but will hold only the root and primary swap partitions.
276 If you plan to use multiple disks,
277 refer to section 2.5 for suggestions on partitioning.
278 .PP
279 After selecting a disk, you may need to format it.
280 Since most HP disk drives come pre-formatted
281 (except optical media)
282 you probably will not, but if necessary,
283 you can format a disk under HP-UX using the
284 .Xr mediainit (1m)
285 program.
286 Once you have \*(4B up and running on one machine you can use the
287 .Xr scsiformat (8)
288 program to format additional SCSI disks.
289 Any additional HP-IB disks will have to be formatted using HP-UX.
290 .Sh 4 "Step 2: copying the root filesystem from tape to disk"
291 .PP
292 Once you have a formatted second disk you can use the
293 .Xr dd (1)
294 command under HP-UX to copy the root filesystem image from
295 the tape to the beginning of the second disk.
296 For HP's, the root filesystem image is the first file on the tape.
297 It includes a disklabel and bootblock along with the root filesystem.
298 An example command to copy the image from tape to the beginning of a disk is:
299 .DS
300 .ft CW
301 dd if=/dev/rmt/0m of=/dev/rdsk/1s0 bs=\*(Bzb
302 .DE
303 The actual special file syntax may vary depending on unit numbers and
304 the version of HP-UX that is running.
305 Consult the HP-UX
306 .Xr mt (7)
307 and
308 .Xr disk (7)
309 man pages for details.
310 .PP
311 Note that if you have a SCSI disk, you don't necessarily have to use
312 HP-UX (or an HP) to create the boot disk.
313 Any machine and operating system that will allow you to copy the
314 raw disk image out to block 0 of the disk will do.
315 .PP
316 If you have only a single machine with a single disk,
317 you may still be able to install and boot \*(4B if you have an
318 HP-IB cartridge tape drive.
319 If so, you can use a more difficult approach of booting a
320 standalone copy program from the tape, and using that to copy the
321 root filesystem image from the tape to the disk.
322 To do this, you need to extract the first file of the distribution tape
323 (the root image), copy it over to a machine with a cartridge drive
324 and then copy the image onto tape.
325 For example:
326 .DS
327 .ft CW
328 dd if=/dev/rst0 of=bootimage bs=\*(Bzb
329 rcp bootimage foo:/tmp/bootimage
330 <login to foo>
331 dd if=/tmp/bootimage of=/dev/rct/0m bs=\*(Bzb
332 .DE
333 Once this tape is created you can boot and run the standalone tape
334 copy program from it.
335 The copy program is loaded just as any other program would be loaded
336 by the bootrom in ``attended'' mode:
337 reset the CPU,
338 hold down the space bar until the word ``Keyboard'' appears in the
339 installed interface list, and
340 enter the menu selection for SYS_TCOPY.
341 Once loaded and running:
342 .DS
343 .TS
344 lw(2i) l.
345 \fBFrom:\fP \fI^C\fP    (control-C to see logical adaptor assignments)
346 \fBhpib0 at sc7\fP
347 \fBscsi0 at sc14\fP
348 \fBFrom:\fP \fIct(0,7,0,0)\fP   (HP-IB tape, target 7, first tape file)
349 \fBTo:\fP \fIsd(0,0,0,2)\fP     (SCSI disk, target 0, third partition)
350 \fBCopy completed: 1728 records copied\fP
351 .TE
352 .DE
353 .LP
354 This copy will likely take 30 minutes or more.
355 .Sh 4 "Step 3: booting the root filesystem"
356 .PP
357 You now have a bootable root filesystem on the disk.
358 If you were previously running with two disks,
359 it would be best if you shut down the machine and turn off power on
360 the HP-UX drive.
361 It will be less confusing and it will eliminate any chance of accidentally
362 destroying the HP-UX disk.
363 If you used a cartridge tape for booting you should also unload the tape
364 at this point.
365 Whether you booted from tape or copied from disk you should now reboot
366 the machine and do another attended boot (see previous section),
367 this time with SYS_TBOOT.
368 Once loaded and running the boot program will display the CPU type and
369 prompt for a kernel file to boot:
370 .DS
371 .B
372 HP433 CPU
373 Boot
374 .R
375 \fB:\fP \fI/kernel\fP
376 .DE
377 .LP
378 After providing the kernel name, the machine will boot \*(4B with
379 output that looks about like this:
380 .DS
381 .B
382 597480+34120+139288 start 0xfe8019ec
383 Copyright (c) 1982, 1986, 1989, 1991, 1993
384         The Regents of the University of California.
385 Copyright (c) 1992 Hewlett-Packard Company
386 Copyright (c) 1992 Motorola Inc.
387 All rights reserved.
389 4.4BSD UNIX #1: Tue Jul 20 11:40:36 PDT 1993
390     mckusick@vangogh.CS.Berkeley.EDU:/usr/obj/sys/compile/GENERIC.hp300
391 HP9000/433 (33MHz MC68040 CPU+MMU+FPU, 4k on-chip physical I/D caches)
392 real mem = xxx
393 avail mem = ###
394 using ### buffers containing ### bytes of memory
395 (... information about available devices ...)
396 root device?
397 .R
398 .DE
399 .PP
400 The first three numbers are printed out by the bootstrap program and
401 are the sizes of different parts of the system (text, initialized and
402 uninitialized data).  The system also allocates several system data
403 structures after it starts running.  The sizes of these structures are
404 based on the amount of available memory and the maximum count of active
405 users expected, as declared in a system configuration description.  This
406 will be discussed later.
407 .PP
408 UNIX itself then runs for the first time and begins by printing out a banner
409 identifying the release and
410 version of the system that is in use and the date that it was compiled. 
411 .PP
412 Next the
413 .I mem
414 messages give the
415 amount of real (physical) memory and the
416 memory available to user programs
417 in bytes.
418 For example, if your machine has 16Mb bytes of memory, then
419 \fBxxx\fP will be 16777216.
420 .PP
421 The messages that come out next show what devices were found on
422 the current processor.  These messages are described in
423 .Xr autoconf (4).
424 The distributed system may not have
425 found all the communications devices you have
426 or all the mass storage peripherals you have, especially
427 if you have more than
428 two of anything.  You will correct this when you create
429 a description of your machine from which to configure a site-dependent
430 version of UNIX.
431 The messages printed at boot here contain much of the information
432 that will be used in creating the configuration.
433 In a correctly configured system most of the information
434 present in the configuration description
435 is printed out at boot time as the system verifies that each device
436 is present.
437 .PP
438 The \*(lqroot device?\*(rq prompt was printed by the system
439 to ask you for the name of the root filesystem to use.
440 This happens because the distribution system is a \fIgeneric\fP
441 system, i.e., it can be bootstrapped on a cpu with its root device
442 and paging area on any available disk drive.
443 You will most likely respond to the root device question with ``sd0''
444 if you are booting from a SCSI disk,
445 or with ``rd0'' if you are booting from an HP-IB disk.
446 This response shows that the disk it is running
447 on is drive 0 of type ``sd'' or ``rd'' respectively.
448 If you have other disks attached to the system,
449 it is possible that the drive you are using will not be configured
450 as logical drive 0.
451 Check the autoconfiguration messages printed out by the kernel to
452 make sure.
453 These messages will show the type of every logical drive
454 and their associated controller and slave addresses.
455 You will later build a system tailored to your configuration
456 that will not prompt you for a root device when it is bootstrapped.
457 .DS
458 \fBroot device?\fP \fI\*(Dk0\fP
459 \fBWARNING: preposterous time in filesystem \-\- CHECK AND RESET THE DATE!\fP
460 \fBerase ^?, kill ^U, intr ^C\fP
461 \fB#\fP
462 .DE
463 .PP
464 The \*(lqerase ...\*(rq message is part of the
465 .Pn /.profile
466 that was executed by the root shell when it started.  This message
467 tells you about the settings of the character erase,
468 line erase, and interrupt characters.
469 .PP
470 UNIX is now running,
471 and the \fIUNIX Programmer's Manual\fP applies.  The ``#'' is the prompt
472 from the Bourne shell, and lets you know that you are the super-user,
473 whose login name is \*(lqroot\*(rq.
474 .PP
475 At this point, the root filesystem is mounted read-only.
476 Before continuing the installation, the filesystem needs to be ``updated''
477 to allow writing and device special files for the following steps need
478 to be created.
479 This is done as follows:
480 .DS
481 .TS
482 lw(2i) l.
483 \fB#\fP \fImount_mfs -s 1000 -T type /dev/null /tmp\fP  (create a writable filesystem)
484 (\fItype\fP is the disk type as determined from /etc/disktab)
485 \fB#\fP \fIcd /tmp\fP   (connect to that directory)
486 \fB#\fP \fI../dev/MAKEDEV \*(Dk#\fP     (create special files for root disk)
487 (\fI\*(Dk\fP is the disk type, \fI#\fP is the unit number)
488 (ignore warning from ``sh'')
489 \fB#\fP \fImount \-uw /tmp/\*(Dk#a /\fP (read-write mount root filesystem)
490 \fB#\fP \fIcd /dev\fP   (go to device directory)
491 \fB#\fP \fI./MAKEDEV \*(Dk#\fP  (create permanent special files for root disk)
492 (again, ignore warning from ``sh'')
493 .TE
494 .DE
495 .Sh 4 "Step 4: (optional) restoring the root filesystem"
496 .PP
497 The root filesystem that you are currently running on is complete,
498 however it probably is not optimally laid out for the disk on
499 which you are running.
500 If you will be cloning copies of the system onto multiple disks for
501 other machines, you are advised to connect one of these disks to
502 this machine, and build and restore a properly laid out root filesystem
503 onto it.
504 If this is the only machine on which you will be running \*(4B
505 or peak performance is not an issue, you can skip this step and
506 proceed directly to step 5.
507 .PP
508 Connect a second disk to your machine.
509 If you bootstrapped using the two disk method, you can
510 overwrite your initial HP-UX disk, as it will no longer
511 be needed (assuming you have no plans to run HP-UX again).
512 .PP
513 To really create the root filesystem on drive 1
514 you should first label the disk as described in step 5 below.
515 Then run the following commands:
516 .DS
517 \fB#\fP \fIcd /dev\fP
518 \fB#\fP \fI./MAKEDEV \*(Dk1a\fP
519 \fB#\fP\|\fInewfs /dev/r\*(Dk1a\fP
520 \fB#\fP\|\fImount /dev/\*(Dk1a /mnt\fP
521 \fB#\fP\|\fIcd /mnt\fP
522 \fB#\fP\|\fIdump 0f \- /dev/r\*(Dk0a | restore xf \-\fP
523 (Note: restore will ask if you want to ``set owner/mode for '.'''
524 to which you should reply ``yes''.)
525 .DE
526 .PP
527 When this completes,
528 you should then shut down the system, and boot on the disk that
529 you just created following the procedure in step (3) above.
530 .Sh 4 "Step 5: placing labels on the disks"
531 .PP
532 For each disk on the HP300, \*(4B places information about the geometry
533 of the drive and the partition layout at byte offset 1024.
534 This information is written with
535 .Xr disklabel (8).
536 .PP
537 The root image just loaded includes a ``generic'' label intended to allow
538 easy installation of the root and
539 .Pn /usr
540 and may not be suitable for the actual
541 disk on which it was installed.
542 In particular,
543 it may make your disk appear larger or smaller than its real size.
544 In the former case, you lose some capacity.
545 In the latter, some of the partitions may map non-existent sectors
546 leading to errors if those partitions are used.
547 It is also possible that the defined geometry will interact poorly with
548 the filesystem code resulting in reduced performance.
549 However, as long as you are willing to give up a little space,
550 not use certain partitions or suffer minor performance degradation,
551 you might want to avoid this step;
552 especially if you do not know how to use
553 .Xr ed (1).
554 .PP
555 If you choose to edit this label,
556 you can fill in correct geometry information from
557 .Pn /etc/disktab .
558 You may also want to rework the ``e'' and ``f'' partitions used for loading
559 .Pn /usr
560 and
561 .Pn /var .
562 You should not attempt to, and
563 .Xr disklabel
564 will not let you, modify the ``a'', ``b'' and ``d'' partitions.
565 To edit a label:
566 .DS
567 \fB#\fP \fIEDITOR=ed\fP
568 \fB#\fP \fIexport EDITOR\fP
569 \fB#\fP \fIdisklabel  -r  -e  /dev/r\fBXX#\fPd
570 .DE
571 where \fBXX\fP is the type and \fB#\fP is the logical drive number; e.g.
572 .Pn /dev/rsd0d
573 or
574 .Pn /dev/rrd0d .
575 Note the explicit use of the ``d'' partition.
576 This partition includes the bootblock as does ``c''
577 and using it allows you to change the size of ``c''.
578 .PP
579 If you wish to label any additional disks, run the following command for each:
580 .DS
581 \fB#\|\fP\fIdisklabel  -rw  \fBXX#  type\fP  \fI"optional_pack_name"\fP
582 .DE
583 where \fBXX#\fP is the same as in the previous command
584 and \fBtype\fP is the HP300 disk device name as listed in
585 .Pn /etc/disktab .
586 The optional information may contain any descriptive name for the
587 contents of a disk, and may be up to 16 characters long.  This procedure
588 will place the label on the disk using the information found in
589 .Pn /etc/disktab
590 for the disk type named.
591 If you have changed the disk partition sizes,
592 you may wish to add entries for the modified configuration in
593 .Pn /etc/disktab
594 before labeling the affected disks.
595 .PP
596 You have now completed the HP300 specific part of the installation.
597 Now proceed to the generic part of the installation
598 described starting in section 2.5 below.
599 Note that where the disk name ``sd'' is used throughout section 2.5,
600 you should substitute the name ``rd'' if you are running on an HP-IB disk.
601 Also, if you are loading on a single disk with the default disklabel,
602 .Pn /var
603 should be restored to the ``f'' partition and
604 .Pn /usr
605 to the ``e'' partition.
606 .Sh 2 "Booting the SPARC"
607 .Sh 3 "Supported hardware"
608 .LP
609 The hardware supported by \*(4B for the SPARC is as follows:
610 .TS
611 center box;
612 lw(1i) lw(4i).
613 CPU's   T{
614 SPARCstation 1 series (1, 1+, SLC, IPC) and
615 SPARCstation 2 series (2, IPX).
616 T}
617 _
618 DISK's  T{
619 SCSI.
620 T}
621 _
622 TAPE's  T{
623 none.
624 T}
625 _
627 SPARCstation Lance (le).
628 T}
629 _
630 GRAPHICS        T{
631 bwtwo and cgthree.
632 T}
633 _
634 INPUT   T{
635 Keyboard and mouse.
636 T}
637 _
638 MISC    T{
639 Battery-backed real time clock,
640 built-in serial devices,
641 Sbus SCSI controller,
642 and audio device.
643 T}
644 .TE
645 .LP
646 Major items that are not supported include
647 anything VME-based,
648 the GX (cgsix) display,
649 the floppy disk, and SCSI tapes.
650 .Sh 3 "Limitations"
651 .LP
652 There are several important limitations on the \*(4B distribution
653 for the SPARC:
654 .IP 1)
655 You
656 .B must
657 have SunOS 4.1.x or Solaris to bring up \*(4B.
658 There is no SPARCstation bootstrap code in this distribution.  The
659 Sun-supplied boot loader will be used to boot \*(4B; you must copy
660 this from your SunOS distribution.  This imposes several
661 restrictions on the system, as detailed below.
662 .IP 2)
663 The \*(4B SPARC kernel does not remap SCSI IDs.  A SCSI disk at
664 target 0 will become ``sd0'', where in SunOS the same disk will
665 normally be called ``sd3''.  If your existing SunOS system is
666 diskful, it will be least painful to have SunOS running on the disk
667 on target 0 lun 0 and put \*(4B on the disk on target 3 lun 0.  Both
668 systems will then think they are running on ``sd0'', and you can
669 boot either system as needed simply by changing the EEPROM's boot
670 device.
671 .IP 3)
672 There is no SCSI tape driver.
673 You must have another system for tape reading and backups.
674 .IP 4)
675 Although the \*(4B SPARC kernel will handle existing SunOS shared
676 libraries, it does not use or create them itself, and therefore
677 requires much more disk space than SunOS does.
678 .IP 5)
679 It is currently difficult (though not completely impossible) to
680 run \*(4B diskless.  These instructions assume you will have a local
681 boot, swap, and root filesystem.
682 .IP 6)
683 When using a serial port rather than a graphics display as the console,
684 only port
685 .Pn ttya
686 can be used.
687 Attempts to use port
688 .Pn ttyb
689 will fail when the kernel tries
690 to print the boot up messages to the console.
691 .Sh 3 "The procedure"
692 .PP
693 You must have a spare disk on which to place \*(4B.
694 The steps involved in bootstrapping this tape are as follows:
695 .IP 1)
696 Bring up SunOS (preferably SunOS 4.1.x or Solaris 1.x, although
697 Solaris 2 may work \(em this is untested).
698 .IP 2)
699 Attach auxiliary SCSI disk(s).  Format and label using the
700 SunOS formatting and labeling programs as needed.
701 Note that the root filesystem currently requires at least 10 MB; 16 MB
702 or more is recommended.  The b partition will be used for swap;
703 this should be at least 32 MB.
704 .IP 3)
705 Use the SunOS
706 .Xr newfs
707 to build the root filesystem.  You may also
708 want to build other filesystems at the same time.  (By default, the
709 \*(4B
710 .Xr newfs
711 builds a filesystem that SunOS will not handle; if you
712 plan to switch OSes back and forth you may want to sacrifice the
713 performance gain from the new filesystem format for compatibility.)
714 You can build an old-format filesystem on \*(4B by giving the \-O
715 option to
716 .Xr newfs (8).
717 .Xr Fsck (8)
718 can convert old format filesystems to new format
719 filesystems, but not vice versa,
720 so you may want to initially build old format filesystems so that they
721 can be mounted under SunOS,
722 and then later convert them to new format filesystems when you are
723 satisfied that \*(4B is running properly.
724 In any case,
725 .B
726 you must build an old-style root filesystem
727 .R
728 so that the SunOS boot program will work.
729 .IP 4)
730 Mount the new root, then copy the SunOS
731 .Pn /boot
732 into place and use the SunOS ``installboot'' program
733 to enable disk-based booting.
734 Note that the filesystem must be mounted when you do the ``installboot'':
735 .DS
736 .ft CW
737 # mount /dev/sd3a /mnt
738 # cp /boot /mnt/boot
739 # cd /usr/kvm/mdec
740 # installboot /mnt/boot bootsd /dev/rsd3a
741 .DE
742 The SunOS
743 .Pn /boot
744 will load \*(4B kernels; there is no SPARCstation
745 bootstrap code on the distribution.  Note that the SunOS
746 .Pn /boot
747 does not handle the new \*(4B filesystem format.
748 .IP 5)
749 Restore the contents of the \*(4B root filesystem.
750 .DS
751 .ft CW
752 # cd /mnt
753 # rrestore xf tapehost:/dev/nrst0
754 .DE
755 .IP 6)
756 Boot the supplied kernel:
757 .DS
758 .ft CW
759 # halt
760 ok boot sd(0,3)kernel -s                [for old proms] OR
761 ok boot disk3 -s                        [for new proms]
762 \&... [\*(4B boot messages]
763 .DE
764 .LP
765 To install the remaining filesystems, use the procedure described
766 starting in section 2.5.
767 In these instructions,
768 .Pn /usr
769 should be loaded into the ``e'' partition and
770 .Pn /var
771 in the ``f'' partition.
772 .LP
773 After completing the filesystem installation you may want
774 to set up \*(4B to reboot automatically:
775 .DS
776 .ft CW
777 # halt
778 ok setenv boot-from sd(0,3)kernel       [for old proms] OR
779 ok setenv boot-device disk3             [for new proms]
780 .DE
781 If you build backwards-compatible filesystems, either with the SunOS
782 newfs or with the \*(4B ``\-O'' option, you can mount these under
783 SunOS.  The SunOS fsck will, however, always think that these filesystems
784 are corrupted, as there are several new (previously unused)
785 superblock fields that are updated in \*(4B.  Running ``fsck \-b32''
786 and letting it ``fix'' the superblock will take care of this.
787 .sp 0.5
788 If you wish to run SunOS binaries that use SunOS shared libraries, you
789 simply need to copy all the dynamic linker files from an existing
790 SunOS system:
791 .DS
792 .ft CW
793 # rcp sunos-host:/etc/ /etc/
794 # rcp sunos-host:'/usr/lib/*.so*' /usr/lib/
795 .DE
796 The SunOS compiler and linker should be able to produce SunOS binaries
797 under \*(4B, but this has not been tested.  If you plan to try it you
798 will need the appropriate .sa files as well.
799 .Sh 2 "Booting the DECstation"
800 .Sh 3 "Supported hardware"
801 .LP
802 The hardware supported by \*(4B for the DECstation is as follows:
803 .TS
804 center box;
805 lw(1i) lw(4i).
806 CPU's   T{
807 R2000 based (3100) and
808 R3000 based (5000/200, 5000/20, 5000/25, 5000/1xx).
809 T}
810 _
811 DISK's  T{
812 SCSI-I (tested RZ23, RZ55, RZ57, Maxtor 8760S).
813 T}
814 _
815 TAPE's  T{
816 SCSI-I (tested DEC TK50, Archive DAT, Emulex MT02).
817 T}
818 _
819 RS232   T{
820 Internal DEC dc7085 and AMD 8530 based interfaces.
821 T}
822 _
824 TURBOchannel PMAD-AA and internal LANCE based interfaces.
825 T}
826 _
827 GRAPHICS        T{
828 Terminal emulation and raw frame buffer support for
829 3100 (color & monochrome),
831 T}
832 _
833 INPUT   T{
834 Standard DEC keyboard (LK201) and mouse.
835 T}
836 _
837 MISC    T{
838 Battery-backed real time clock,
839 internal and TURBOchannel PMAZ-AA SCSI interfaces.
840 T}
841 .TE
842 .LP
843 Major items that are not supported include the 5000/240
844 (there is code but not compiled in or tested),
845 R4000 based machines, FDDI and audio interfaces.
846 Diskless machines are not supported but booting kernels and bootstrapping
847 over the network is supported on the 5000 series.
848 .Sh 3 "The procedure"
849 .PP
850 The first file on the distribution tape is a tar file that contains
851 four files.
852 The first step requires a running UNIX (or ULTRIX) system that can
853 be used to extract the tar archive from the first file on the tape.
854 The command:
855 .DS
856 .ft CW
857 tar xf /dev/rmt0
858 .DE
859 will extract the following four files:
860 .DS
861 A) root.image: \fIdd\fP image of the root filesystem
862 B) kernel.tape: \fIdd\fP image for creating boot tapes
863 C) file for booting over the network
864 D) root.dump: \fIdump\fP image of the root filesystem
865 .DE
866 There are three basic ways a system can be bootstrapped corresponding to the
867 first three files.
868 You may want to read the section on bootstrapping the HP300
869 since many of the steps are similar.
870 A spare, formatted SCSI disk is also useful.
871 .Sh 4 "Procedure A: copy root filesystem to disk"
872 .PP
873 This procedure is similar to the HP300.
874 If you have an extra disk, the easiest approach is to use \fIdd\fP\|(1)
875 under ULTRIX to copy the root filesystem image to the beginning
876 of the spare disk. 
877 The root filesystem image includes a disklabel and bootblock along with the
878 root filesystem.
879 An example command to copy the image to the beginning of a disk is:
880 .DS
881 .ft CW
882 dd if=root.image of=/dev/rz1c bs=\*(Bzb
883 .DE
884 The actual special file syntax will vary depending on unit numbers and
885 the version of ULTRIX that is running.
886 This system is now ready to boot. You can boot the kernel with one of the
887 following PROM commands. If you are booting on a 3100, the disk must be SCSI
888 id zero because of a bug.
889 .DS
890 .ft CW
891 DEC 3100:    boot \-f rz(0,0,0)kernel
892 DEC 5000:    boot 5/rz0/kernel
893 .DE
894 You can then proceed to section 2.5
895 to create reasonable disk partitions for your machine
896 and then install the rest of the system.
897 .Sh 4 "Procedure B: bootstrap from tape"
898 .PP
899 If you have only a single machine with a single disk,
900 you need to use the more difficult approach of booting a
901 kernel and mini-root from tape or the network, and using it to restore
902 the root filesystem.
903 .PP
904 First, you will need to create a boot tape. This can be done using
905 \fIdd\fP as in the following example.
906 .DS
907 .ft CW
908 dd if=kernel.tape of=/dev/nrmt0 bs=1b
909 dd if=root.dump of=/dev/nrmt0 bs=\*(Bzb
910 .DE
911 The actual special file syntax for the tape drive will vary depending on
912 unit numbers, tape device and the version of ULTRIX that is running.
913 .PP
914 The first file on the boot tape contains a boot header, kernel, and
915 mini-root filesystem that the PROM can copy into memory.
916 Installing from tape has only been tested
917 on a 3100 and a 5000/200 using a TK50 tape drive. Here are two example
918 PROM commands to boot from tape.
919 .DS
920 .ft CW
921 DEC 3100:    boot \-f tz(0,5,0) m    # 5 is the SCSI id of the TK50
922 DEC 5000:    boot 5/tz6 m           # 6 is the SCSI id of the TK50
923 .DE
924 The `m' argument tells the kernel to look for a root filesystem in memory.
925 Next you should proceed to section 2.4.3 to build a disk-based root filesystem.
926 .Sh 4 "Procedure C: bootstrap over the network"
927 .PP
928 You will need a host machine that is running the \fIbootp\fP server 
929 with the
930 .Pn
931 file installed in the default directory defined by the
932 configuration file for
933 .Xr bootp .
934 Here are two example PROM commands to boot across the net:
935 .DS
936 .ft CW
937 DEC 3100:       boot \-f tftp() m
938 DEC 5000:       boot 6/tftp/ m
939 .DE
940 This command should load the kernel and mini-root into memory and
941 run the same as the tape install (procedure B).
942 The rest of the steps are the same except
943 you will need to start the network
944 (if you are unsure how to fill in the <name> fields below,
945 see sections 4.4 and 5).
946 Execute the following to start the networking:
947 .DS
948 .ft CW
949 # mount \-uw /
950 # echo localhost >> /etc/hosts
951 # echo <> myname >> /etc/hosts
952 # echo <> myfriend >> /etc/hosts
953 # ifconfig le0 inet myname
954 .DE
955 Next you should proceed to section 2.4.3 to build a disk-based root filesystem.
956 .Sh 3 "Label disk and create the root filesystem"
957 .LP
958 There are five steps to create a disk-based root filesystem.
959 .IP 1)
960 Label the disk.
961 .DS
962 .ft CW
963 # disklabel -W /dev/rrz?c               # This enables writing the label
964 # disklabel -w -r -B /dev/rrz?c $DISKTYPE
965 # newfs /dev/rrz?a
966 \&...
967 # fsck /dev/rrz?a
968 \&...
969 .DE
970 Supported disk types are listed in
971 .Pn /etc/disktab .
972 .IP 2)
973 Restore the root filesystem.
974 .DS
975 .ft CW
976 # mount \-uw /
977 # mount /dev/rz?a /a
978 # cd /a
979 .DE
980 .ti +0.4i
981 If you are restoring locally (procedure B), run:
982 .DS
983 .ft CW
984 # mt \-f /dev/nrmt0 rew
985 # restore \-xsf 2 /dev/rmt0
986 .DE
987 .ti +0.4i
988 If you are restoring across the net (procedure c), run:
989 .DS
990 .ft CW
991 # rrestore xf myfriend:/path/to/root.dump
992 .DE
993 .ti +0.4i
994 When the restore finishes, clean up with:
995 .DS
996 .ft CW
997 # cd /
998 # sync
999 # umount /a
1000 # fsck /dev/rz?a
1001 .DE
1002 .IP 3)
1003 Reset the system and initialize the PROM monitor to boot automatically.
1004 .DS
1005 .ft CW
1006 DEC 3100:       setenv bootpath boot \-f rz(0,?,0)kernel
1007 DEC 5000:       setenv bootpath 5/rz?/kernel -a
1008 .DE
1009 .IP 4)
1010 After booting UNIX, you will need to create
1011 .Pn /dev/mouse
1012 to run X Window System as in the following example.
1013 .DS
1014 .ft CW
1015 rm /dev/mouse
1016 ln /dev/xx /dev/mouse
1017 .DE
1018 The 'xx' should be one of the following:
1019 .DS
1020 pm0     raw interface to PMAX graphics devices
1021 cfb0    raw interface to TURBOchannel PMAG-BA color frame buffer
1022 xcfb0   raw interface to maxine graphics devices
1023 mfb0    raw interface to mono graphics devices
1024 .DE
1025 You can then proceed to section 2.5 to install the rest of the system.
1026 Note that where the disk name ``sd'' is used throughout section 2.5,
1027 you should substitute the name ``rz''.
1028 .Sh 2 "Disk configuration"
1029 .PP
1030 All architectures now have a root filesystem up and running and
1031 proceed from this point to layout filesystems to make use
1032 of the available space and to balance disk load for better system
1033 performance.
1034 .Sh 3 "Disk naming and divisions"
1035 .PP
1036 Each physical disk drive can be divided into up to 8 partitions;
1037 UNIX typically uses only 3 or 4 partitions.
1038 For instance, the first partition, \*(Dk0a,
1039 is used for a root filesystem, a backup thereof,
1040 or a small filesystem like,
1041 .Pn /var/tmp ;
1042 the second partition, \*(Dk0b,
1043 is used for paging and swapping; and
1044 a third partition, typically \*(Dk0e,
1045 holds a user filesystem.
1046 .PP
1047 The space available on a disk varies per device.
1048 Each disk typically has a paging area of 30 to 100 megabytes
1049 and a root filesystem of about 17 megabytes.
1050 .\" XXX check
1051 The distributed system binaries occupy about 150 (180 with X11R5) megabytes
1052 .\" XXX check
1053 while the major sources occupy another 250 (340 with X11R5) megabytes.
1054 The
1055 .Pn /var
1056 filesystem as delivered on the tape is only 2Mb,
1057 however it should have at least 50Mb allocated to it just for
1058 normal system activity.
1059 Usually it is allocated the last partition on the disk
1060 so that it can provide as much space as possible to the
1061 .Pn /var/users
1062 filesystem.
1063 See section 2.5.4 for further details on disk layouts.
1064 .PP
1065 Be aware that the disks have their sizes
1066 measured in disk sectors (usually 512 bytes), while the UNIX filesystem
1067 blocks are variable sized.
1068 If
1069 .Sm BLOCKSIZE=1k
1070 is set in the user's environment, all user programs report
1071 disk space in kilobytes, otherwise,
1072 disk sizes are always reported in units of 512-byte sectors\**.
1073 .FS
1074 You can thank System V intransigence and POSIX duplicity for
1075 requiring that 512-byte blocks be the units that programs report.
1076 .FE
1077 The
1078 .Pn /etc/disktab
1079 file used in labelling disks and making filesystems
1080 specifies disk partition sizes in sectors.
1081 .Sh 3 "Layout considerations"
1082 .PP
1083 There are several considerations in deciding how
1084 to adjust the arrangement of things on your disks.
1085 The most important is making sure that there is adequate space
1086 for what is required; secondarily, throughput should be maximized.
1087 Paging space is an important parameter.
1088 The system, as distributed, sizes the configured
1089 paging areas each time the system is booted.  Further,
1090 multiple paging areas of different sizes may be interleaved.
1091 .PP
1092 Many common system programs (C, the editor, the assembler etc.)
1093 create intermediate files in the
1094 .Pn /tmp
1095 directory, so the filesystem where this is stored also should be made
1096 large enough to accommodate most high-water marks.
1097 Typically,
1098 .Pn /tmp
1099 is constructed from a memory-based filesystem (see
1100 .Xr mount_mfs (8)).
1101 Programs that want their temporary files to persist
1102 across system reboots (such as editors) should use
1103 .Pn /var/tmp .
1104 If you plan to use a disk-based
1105 .Pn /tmp
1106 filesystem to avoid loss across system reboots, it makes
1107 sense to mount this in a ``root'' (i.e. first partition)
1108 filesystem on another disk.
1109 All the programs that create files in
1110 .Pn /tmp
1111 take care to delete them, but are not immune to rare events
1112 and can leave dregs.
1113 The directory should be examined every so often and the old
1114 files deleted.
1115 .PP
1116 The efficiency with which UNIX is able to use the CPU
1117 is often strongly affected by the configuration of disk controllers;
1118 it is critical for good performance to balance disk load.
1119 There are at least five components of the disk load that you can
1120 divide between the available disks:
1121 .IP 1)
1122 The root filesystem.
1123 .IP 2)
1124 The
1125 .Pn /var
1126 and
1127 .Pn /var/tmp
1128 filesystems.
1129 .IP 3)
1130 The
1131 .Pn /usr
1132 filesystem.
1133 .IP 4)
1134 The user filesystems.
1135 .IP 5)
1136 The paging activity.
1137 .LP
1138 The following possibilities are ones we have used at times
1139 when we had 2, 3 and 4 disks:
1140 .TS
1141 center doublebox;
1142 l | c s s
1143 l | lw(5) | lw(5) | lw(5).
1144         disks
1145 what    2       3       4
1146 _
1147 root    0       0       0
1148 var     1       2       3
1149 usr     1       1       1
1150 paging  0+1     0+2     0+2+3
1151 users   0       0+2     0+2
1152 archive x       x       3
1153 .TE
1154 .PP
1155 The most important things to consider are to
1156 even out the disk load as much as possible, and to do this by
1157 decoupling filesystems (on separate arms) between which heavy copying occurs.
1158 Note that a long term average balanced load is not important; it is
1159 much more important to have an instantaneously balanced
1160 load when the system is busy.
1161 .PP
1162 Intelligent experimentation with a few filesystem arrangements can
1163 pay off in much improved performance.  It is particularly easy to
1164 move the root, the
1165 .Pn /var
1166 and
1167 .Pn /var/tmp
1168 filesystems and the paging areas.  Place the
1169 user files and the
1170 .Pn /usr
1171 directory as space needs dictate and experiment
1172 with the other, more easily moved filesystems.
1173 .Sh 3 "Filesystem parameters"
1174 .PP
1175 Each filesystem is parameterized according to its block size,
1176 fragment size, and the disk geometry characteristics of the
1177 medium on which it resides.  Inaccurate specification of the disk
1178 characteristics or haphazard choice of the filesystem parameters
1179 can result in substantial throughput degradation or significant
1180 waste of disk space.  As distributed,
1181 filesystems are configured according to the following table.
1182 .DS
1183 .TS
1184 center;
1185 l l l.
1186 Filesystem      Block size      Fragment size
1187 _
1188 root    8 kbytes        1 kbytes
1189 usr     8 kbytes        1 kbytes
1190 users   4 kbytes        512 bytes
1191 .TE
1192 .DE
1193 .PP
1194 The root filesystem block size is
1195 made large to optimize bandwidth to the associated disk.
1196 The large block size is important as many of the most
1197 heavily used programs are demand paged out of the
1198 .Pn /bin
1199 directory.
1200 The fragment size of 1 kbyte is a ``nominal'' value to use
1201 with a filesystem.  With a 1 kbyte fragment size
1202 disk space utilization is about the same
1203 as with the earlier versions of the filesystem.
1204 .PP
1205 The filesystems for users have a 4 kbyte block
1206 size with 512 byte fragment size.  These parameters
1207 have been selected based on observations of the
1208 performance of our user filesystems.  The 4 kbyte
1209 block size provides adequate bandwidth while the
1210 512 byte fragment size provides acceptable space compaction
1211 and disk fragmentation.
1212 .PP
1213 Other parameters may be chosen in constructing filesystems,
1214 but the factors involved in choosing a block
1215 size and fragment size are many and interact in complex
1216 ways.  Larger block sizes result in better
1217 throughput to large files in the filesystem as
1218 larger I/O requests will then be done by the
1219 system.  However,
1220 consideration must be given to the average file sizes
1221 found in the filesystem and the performance of the
1222 internal system buffer cache.   The system
1223 currently provides space in the inode for
1224 12 direct block pointers, 1 single indirect block
1225 pointer, 1 double indirect block pointer,
1226 and 1 triple indirect block pointer.
1227 If a file uses only direct blocks, access time to
1228 it will be optimized by maximizing the block size.
1229 If a file spills over into an indirect block,
1230 increasing the block size of the filesystem may
1231 decrease the amount of space used
1232 by eliminating the need to allocate an indirect block.
1233 However, if the block size is increased and an indirect
1234 block is still required, then more disk space will be
1235 used by the file because indirect blocks are allocated
1236 according to the block size of the filesystem.
1237 .PP
1238 In selecting a fragment size for a filesystem, at least
1239 two considerations should be given.  The major performance
1240 tradeoffs observed are between an 8 kbyte block filesystem
1241 and a 4 kbyte block filesystem.  Because of implementation
1242 constraints, the block size versus fragment size ratio can not
1243 be greater than 8.  This means that an 8 kbyte filesystem
1244 will always have a fragment size of at least 1 kbytes.  If
1245 a filesystem is created with a 4 kbyte block size and a
1246 1 kbyte fragment size, then upgraded to an 8 kbyte block size
1247 and 1 kbyte fragment size, identical space compaction will be
1248 observed.  However, if a filesystem has a 4 kbyte block size
1249 and 512 byte fragment size, converting it to an 8K/1K
1250 filesystem will result in 4-8% more space being
1251 used.  This implies that 4 kbyte block filesystems that
1252 might be upgraded to 8 kbyte blocks for higher performance should
1253 use fragment sizes of at least 1 kbytes to minimize the amount
1254 of work required in conversion.
1255 .PP
1256 A second, more important, consideration when selecting the
1257 fragment size for a filesystem is the level of fragmentation
1258 on the disk.  With an 8:1 fragment to block ratio, storage fragmentation
1259 occurs much sooner, particularly with a busy filesystem running
1260 near full capacity.  By comparison, the level of fragmentation in a
1261 4:1 fragment to block ratio filesystem is one tenth as severe.  This
1262 means that on filesystems where many files are created and
1263 deleted, the 512 byte fragment size is more likely to result in apparent
1264 space exhaustion because of fragmentation.  That is, when the filesystem
1265 is nearly full, file expansion that requires locating a
1266 contiguous area of disk space is more likely to fail on a 512
1267 byte filesystem than on a 1 kbyte filesystem.  To minimize
1268 fragmentation problems of this sort, a parameter in the super
1269 block specifies a minimum acceptable free space threshold.  When
1270 normal users (i.e. anyone but the super-user) attempt to allocate
1271 disk space and the free space threshold is exceeded, the user is
1272 returned an error as if the filesystem were really full.  This
1273 parameter is nominally set to 5%; it may be changed by supplying
1274 a parameter to
1275 .Xr newfs (8),
1276 or by updating the super block of an existing filesystem using
1277 .Xr tunefs (8).
1278 .PP
1279 Finally, a third, less common consideration is the attributes of
1280 the disk itself.  The fragment size should not be smaller than the
1281 physical sector size of the disk.  As an example, the HP magneto-optical
1282 disks have 1024 byte physical sectors.  Using a 512 byte fragment size
1283 on such disks will work but is extremely inefficient.
1284 .PP
1285 Note that the above discussion considers block sizes of up to only 8k.
1286 As of the 4.4 release, the maximum block size has been increased to 64k.
1287 This allows an entirely new set of block/fragment combinations for which
1288 there is little experience to date.
1289 In general though, unless a filesystem is to be used
1290 for a special purpose application (for example, storing
1291 image processing data), we recommend using the
1292 values supplied above.
1293 Remember that the current
1294 implementation limits the block size to at most 64 kbytes
1295 and the ratio of block size versus fragment size must be 1, 2, 4, or 8.
1296 .PP
1297 The disk geometry information used by the filesystem
1298 affects the block layout policies employed.  The file
1299 .Pn /etc/disktab ,
1300 as supplied, contains the data for most
1301 all drives supported by the system.  Before constructing
1302 a filesystem with
1303 .Xr newfs (8)
1304 you should label the disk (if it has not yet been labeled,
1305 and the driver supports labels).
1306 If labels cannot be used, you must instead
1307 specify the type of disk on which the filesystem resides;
1308 .Xr newfs
1309 then reads
1310 .Pn /etc/disktab
1311 instead of the pack label.
1312 This file also contains the default
1313 filesystem partition
1314 sizes, and default block and fragment sizes.  To
1315 override any of the default values you can modify the file,
1316 edit the disk label,
1317 or use an option to
1318 .Xr newfs .
1319 .Sh 3 "Implementing a layout"
1320 .PP
1321 To put a chosen disk layout into effect, you should use the
1322 .Xr newfs (8)
1323 command to create each new filesystem.
1324 Each filesystem must also be added to the file
1325 .Pn /etc/fstab
1326 so that it will be checked and mounted when the system is bootstrapped.
1327 .PP
1328 First we will consider a system with a single disk.
1329 There is little real choice on how to do the layout;
1330 the root filesystem goes in the ``a'' partition,
1331 .Pn /usr
1332 goes in the ``e'' partition, and
1333 .Pn /var
1334 fills out the remainder of the disk in the ``f'' partition.
1335 This is the organization used if you loaded the disk-image root filesystem.
1336 With the addition of a memory-based
1337 .Pn /tmp
1338 filesystem, its fstab entry would be as follows:
1339 .TS
1340 center;
1341 lfC lfC l l n n.
1342 /dev/\*(Dk0a    /       ufs     rw      1       1
1343 /dev/\*(Dk0b    none    swap    sw      0       0
1344 /dev/\*(Dk0b    /tmp    mfs     rw,-s=14000,-b=8192,-f=1024,-T=sd660    0       0
1345 /dev/\*(Dk0e    /usr    ufs     ro      1       2
1346 /dev/\*(Dk0f    /var    ufs     rw      1       2
1347 .TE
1348 .PP
1349 If we had a second disk, we would split the load between the drives.
1350 On the second disk, we place the
1351 .Pn /usr
1352 and
1353 .Pn /var
1354 filesystems in their usual \*(Dk1e and \*(Dk1f
1355 partitions respectively.
1356 The \*(Dk1b partition would be used as a second paging area,
1357 and the \*(Dk1a partition left as a spare root filesystem
1358 (alternatively \*(Dk1a could be used for
1359 .Pn /var/tmp ).
1360 The first disk still holds the
1361 the root filesystem in \*(Dk0a, and the primary swap area in \*(Dk0b.
1362 The \*(Dk0e partition is used to hold home directories in
1363 .Pn /var/users .
1364 The \*(Dk0f partition can be used for
1365 .Pn /usr/src
1366 or alternately the \*(Dk0e partition can be extended to cover
1367 the rest of the disk with
1368 .Xr disklabel (8).
1369 As before, the
1370 .Pn /tmp
1371 directory is a memory-based filesystem.
1372 Note that to interleave the paging between the two disks
1373 you must build a system configuration that specifies:
1374 .DS
1375 config  kernel  root on \*(Dk0 swap on \*(Dk0 and \*(Dk1
1376 .DE
1377 The
1378 .Pn /etc/fstab
1379 file would then contain
1380 .TS
1381 center;
1382 lfC lfC l l n n.
1383 /dev/\*(Dk0a    /       ufs     rw      1       1
1384 /dev/\*(Dk0b    none    swap    sw      0       0
1385 /dev/\*(Dk1b    none    swap    sw      0       0
1386 /dev/\*(Dk0b    /tmp    mfs     rw,-s=14000,-b=8192,-f=1024,-T=sd660    0       0
1387 /dev/\*(Dk1e    /usr    ufs     ro      1       2
1388 /dev/\*(Dk0f    /usr/src        ufs     rw      1       2
1389 /dev/\*(Dk1f    /var    ufs     rw      1       2
1390 /dev/\*(Dk0e    /var/users      ufs     rw      1       2
1391 .TE
1392 .PP
1393 To make the
1394 .Pn /var
1395 filesystem we would do:
1396 .DS
1397 \fB#\fP \fIcd /dev\fP
1398 \fB#\fP \fIMAKEDEV \*(Dk1\fP
1399 \fB#\fP \fIdisklabel -wr \*(Dk1 "disk type" "disk name"\fP
1400 \fB#\fP \fInewfs \*(Dk1f\fP
1401 (information about filesystem prints out)
1402 \fB#\fP \fImkdir /var\fP
1403 \fB#\fP \fImount /dev/\*(Dk1f /var\fP
1404 .DE
1405 .Sh 2 "Installing the rest of the system"
1406 .PP
1407 At this point you should have your disks partitioned.
1408 The next step is to extract the rest of the data from the tape.
1409 At a minimum you need to set up the
1410 .Pn /var
1411 and
1412 .Pn /usr
1413 filesystems.
1414 You may also want to extract some or all the program sources.
1415 Since not all architectures support tape drives or don't support the
1416 correct ones, you may need to extract the files indirectly using
1417 .Xr rsh (1).
1418 For example, for a directly connected tape drive you might do:
1419 .DS
1420 \fB#\fP \fImt -f /dev/nr\*(Mt0 fsf\fP
1421 \fB#\fP \fItar xbpf \*(Bz /dev/nr\*(Mt0\fP
1422 .DE
1423 The equivalent indirect procedure (where the tape drive is on machine ``foo'')
1424 is:
1425 .DS
1426 \fB#\fP \fIrsh foo mt -f /dev/nr\*(Mt0 fsf\fP
1427 \fB#\fP \fIrsh foo dd if=/dev/nr\*(Mt0 bs=\*(Bzb | tar xbpf \*(Bz -\fP
1428 .DE
1429 Obviously, the target machine must be connected to the local network
1430 for this to work.
1431 To do this:
1432 .DS
1433 \fB#\fP \fIecho  localhost >> /etc/hosts\fP
1434 \fB#\fP \fIecho  \  myname\fI >> /etc/hosts\fP
1435 \fB#\fP \fIecho  \  myfriend\fI >> /etc/hosts\fP
1436 \fB#\fP \fIifconfig  le0  inet  \fPmyname
1437 .DE
1438 where the ``host.inet.number'' fields are the IP addresses for your host and
1439 the host with the tape drive
1440 and the ``my.domain'' fields are the names of your machine and the tape-hosting
1441 machine.
1442 See sections 4.4 and 5 for more information on setting up the network.
1443 .PP
1444 Assuming a directly connected tape drive, here is how to extract and
1445 install
1446 .Pn /var
1447 and
1448 .Pn /usr :
1449 .br
1450 .ne 5
1451 .TS
1452 lw(2i) l.
1453 \fB#\fP \fImount \-uw /dev/\*(Dk#a /\fP (read-write mount root filesystem)
1454 \fB#\fP \fIdate yymmddhhmm\fP   (set date, see \fIdate\fP\|(1))
1455 \&....
1456 \fB#\fP \fIpasswd -l root\fP    (set password for super-user)
1457 \fBNew password:\fP     (password will not echo)
1458 \fBRetype new password:\fP
1459 \fB#\fP \fIpasswd -l toor\fP    (set password for super-user)
1460 \fBNew password:\fP     (password will not echo)
1461 \fBRetype new password:\fP
1462 \fB#\fP \fIhostname mysitename\fP       (set your hostname)
1463 \fB#\fP \fInewfs r\*(Dk#p\fP    (create empty user filesystem)
1464 (\fI\*(Dk\fP is the disk type, \fI#\fP is the unit number,
1465 \fIp\fP is the partition; this takes a few minutes)
1466 \fB#\fP \fImount /dev/\*(Dk#p /var\fP   (mount the var filesystem)
1467 \fB#\fP \fIcd /var\fP   (make /var the current directory)
1468 \fB#\fP \fImt -f /dev/nr\*(Mt0 fsf\fP   (space to end of previous tape file)
1469 \fB#\fP \fItar xbpf \*(Bz /dev/nr\*(Mt0\fP      (extract all of var)
1470 (this takes a few minutes)
1471 \fB#\fP \fInewfs r\*(Dk#p\fP    (create empty user filesystem)
1472 (as before \fI\*(Dk\fP is the disk type, \fI#\fP is the unit number,
1473 \fIp\fP is the partition)
1474 \fB#\fP \fImount /dev/\*(Dk#p /mnt\fP   (mount the new /usr in temporary location)
1475 \fB#\fP \fIcd /mnt\fP   (make /mnt the current directory)
1476 \fB#\fP \fImt -f /dev/nr\*(Mt0 fsf\fP   (space to end of previous tape file)
1477 \fB#\fP \fItar xbpf \*(Bz /dev/nr\*(Mt0\fP      (extract all of usr except usr/src)
1478 (this takes about 15-20 minutes)
1479 \fB#\fP \fIcd /\fP      (make / the current directory)
1480 \fB#\fP \fIumount /mnt\fP       (unmount from temporary mount point)
1481 \fB#\fP \fIrm -r /usr/*\fP      (remove excess bootstrap binaries)
1482 \fB#\fP \fImount /dev/\*(Dk#p /usr\fP   (remount /usr)
1483 .TE
1484 If no disk label has been installed on the disk, the
1485 .Xr newfs
1486 command will require a third argument to specify the disk type,
1487 using one of the names in
1488 .Pn /etc/disktab .
1489 If the tape had been rewound or positioned incorrectly before the
1490 .Xr tar ,
1491 to extract
1492 .Pn /var
1493 it may be repositioned by the following commands.
1494 .DS
1495 \fB#\fP \fImt -f /dev/nr\*(Mt0 rew\fP
1496 \fB#\fP \fImt -f /dev/nr\*(Mt0 fsf 1\fP
1497 .DE
1498 The data on the second and third tape files has now been extracted.
1499 If you are using 6250bpi tapes, the first reel of the
1500 distribution is no longer needed; you should now mount the second
1501 reel instead.  The installation procedure continues from this
1502 point on the 8mm tape.
1503 The next step is to extract the sources.
1504 As previously noted,
1505 .Pn /usr/src
1506 .\" XXX Check
1507 requires about 250-340Mb of space.
1508 Ideally sources should be in a separate filesystem;
1509 if you plan to put them into your
1510 .Pn /usr
1511 filesystem, it will need at least 500Mb of space.
1512 Assuming that you will be using a separate filesystem on \*(Dk0f for
1513 .Pn /usr/src ,
1514 you will start by creating and mounting it:
1515 .DS
1516 \fB#\fP \fInewfs \*(Dk0f\fP
1517 (information about filesystem prints out)
1518 \fB#\fP \fImkdir /usr/src\fP
1519 \fB#\fP \fImount /dev/\*(Dk0f /usr/src\fP
1520 .DE
1521 .LP
1522 First you will extract the kernel source:
1523 .DS
1524 .TS
1525 lw(2i) l.
1526 \fB#\fP \fIcd /usr/src\fP
1527 \fB#\fP \fImt -f /dev/nr\*(Mt0 fsf\fP   (space to end of previous tape file)
1528 (this should only be done on Exabyte distributions)
1529 \fB#\fP \fItar xpbf \*(Bz /dev/nr\*(Mt0\fP      (extract the kernel sources)
1530 (this takes about 15-30 minutes)
1531 .TE
1532 .DE
1533 .LP
1534 The next tar file contains the sources for the utilities.
1535 It is extracted as follows:
1536 .DS
1537 .TS
1538 lw(2i) l.
1539 \fB#\fP \fIcd /usr/src\fP
1540 \fB#\fP \fImt -f /dev/nr\*(Mt0 fsf\fP   (space to end of previous tape file)
1541 \fB#\fP \fItar xpbf \*(Bz /dev/rmt12\fP         (extract the utility source)
1542 (this takes about 30-60 minutes)
1543 .TE
1544 .DE
1545 .PP
1546 If you are using 6250bpi tapes, the second reel of the
1547 distribution is no longer needed; you should now mount the third
1548 reel instead.  The installation procedure continues from this
1549 point on the 8mm tape.
1550 .PP
1551 The next tar file contains the sources for the contributed software.
1552 It is extracted as follows:
1553 .DS
1554 .TS
1555 lw(2i) l.
1556 \fB#\fP \fIcd /usr/src\fP
1557 \fB#\fP \fImt -f /dev/nr\*(Mt0 fsf\fP   (space to end of previous tape file)
1558 (this should only be done on Exabyte distributions)
1559 \fB#\fP \fItar xpbf \*(Bz /dev/rmt12\fP         (extract the contributed software source)
1560 (this takes about 30-60 minutes)
1561 .TE
1562 .DE
1563 .PP
1564 If you received a distribution on 8mm Exabyte tape,
1565 there is one additional tape file on the distribution tape
1566 that has not been installed to this point; it contains the
1567 sources for X11R5 in
1568 .Xr tar (1)
1569 format.  As distributed, X11R5 should be placed in
1570 .Pn /usr/src/X11R5 .
1571 .DS
1572 .TS
1573 lw(2i) l.
1574 \fB#\fP \fIcd /usr/src\fP
1575 \fB#\fP \fImt -f /dev/nr\*(Mt0 fsf\fP   (space to end of previous tape file)
1576 \fB#\fP \fItar xpbf \*(Bz /dev/nr\*(Mt0\fP      (extract the X11R5 source)
1577 (this takes about 30-60 minutes)
1578 .TE
1579 .DE
1580 Many of the X11 utilities search using the path
1581 .Pn /usr/X11 ,
1582 so be sure that you have a symbolic link that points at
1583 the location of your X11 binaries (here, X11R5).
1584 .PP
1585 Having now completed the extraction of the sources, 
1586 you may want to verify that your
1587 .Pn /usr/src
1588 filesystem is consistent.
1589 To do so, you must unmount it, and run
1590 .Xr fsck (8);
1591 assuming that you used \*(Dk0f you would proceed as follows:
1592 .DS
1593 .TS
1594 lw(2i) l.
1595 \fB#\fP \fIcd /\fP      (change directory, back to the root)
1596 \fB#\fP \fIumount /usr/src\fP   (unmount /usr/src)
1597 \fB#\fP \fIfsck /dev/r\*(Dk0f\fP
1598 .TE
1599 .DE
1600 The output from
1601 .Xr fsck
1602 should look something like:
1603 .DS
1604 .B
1605 ** /dev/r\*(Dk0f
1606 ** Last Mounted on /usr/src
1607 ** Phase 1 - Check Blocks and Sizes
1608 ** Phase 2 - Check Pathnames
1609 ** Phase 3 - Check Connectivity
1610 ** Phase 4 - Check Reference Counts
1611 ** Phase 5 - Check Cyl groups
1612 23000 files, 261000 used, 39000 free (2200 frags, 4600 blocks)
1613 .R
1614 .DE
1615 .PP
1616 If there are inconsistencies in the filesystem, you may be prompted
1617 to apply corrective action; see the
1618 .Xr fsck (8)
1619 or \fIFsck \(en The UNIX File System Check Program\fP (SMM:3) for more details.
1620 .PP
1621 To use the
1622 .Pn /usr/src
1623 filesystem, you should now remount it with:
1624 .DS
1625 \fB#\fP \fImount /dev/\*(Dk0f /usr/src\fP
1626 .DE
1627 or if you have made an entry for it in
1628 .Pn /etc/fstab
1629 you can remount it with:
1630 .DS
1631 \fB#\fP \fImount /usr/src\fP
1632 .DE
1633 .Sh 2 "Additional conversion information"
1634 .PP
1635 After setting up the new \*(4B filesystems, you may restore the user
1636 files that were saved on tape before beginning the conversion.
1637 Note that the \*(4B
1638 .Xr restore
1639 program does its work on a mounted filesystem using normal system operations.
1640 This means that filesystem dumps may be restored even
1641 if the characteristics of the filesystem changed.
1642 To restore a dump tape for, say, the
1643 .Pn /a
1644 filesystem something like the following would be used:
1645 .DS
1646 \fB#\fP \fImkdir /a\fP
1647 \fB#\fP \fInewfs \*(Dk#p\fI
1648 \fB#\fP \fImount /dev/\*(Dk#p /a\fP
1649 \fB#\fP \fIcd /a\fP
1650 \fB#\fP \fIrestore x\fP
1651 .DE
1652 .PP
1653 If
1654 .Xr tar
1655 images were written instead of doing a dump, you should
1656 be sure to use its `\-p' option when reading the files back.  No matter
1657 how you restore a filesystem, be sure to unmount it and check its
1658 integrity with
1659 .Xr fsck (8)
1660 when the job is complete.