xref: /netbsd-src/usr.sbin/installboot/installboot.8 (revision eb7c1594f145c931049e1fd9eb056a5987e87e59)
1.\"	$NetBSD: installboot.8,v 1.28 2003/04/20 00:38:31 lukem Exp $
2.\"
3.\" Copyright (c) 2002-2003 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Luke Mewburn of Wasabi Systems.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\" 3. All advertising materials mentioning features or use of this software
18.\"    must display the following acknowledgement:
19.\"	This product includes software developed by the NetBSD
20.\"	Foundation, Inc. and its contributors.
21.\" 4. Neither the name of The NetBSD Foundation nor the names of its
22.\"    contributors may be used to endorse or promote products derived
23.\"    from this software without specific prior written permission.
24.\"
25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35.\" POSSIBILITY OF SUCH DAMAGE.
36.\"
37.Dd April 20, 2003
38.Dt INSTALLBOOT 8
39.Os
40.Sh NAME
41.Nm installboot
42.Nd install disk bootstrap software
43.
44.Sh SYNOPSIS
45.Nm
46.Op Fl nv
47.Bk -words
48.Op Fl m Ar machine
49.Ek
50.Bk -words
51.Op Fl o Ar options
52.Ek
53.Bk -words
54.Op Fl t Ar fstype
55.Ek
56.Bk -words
57.Op Fl b Ar s1bno
58.Ek
59.Bk -words
60.Op Fl B Ar s2bno
61.Ek
62.Ar filesystem
63.Ar primary
64.Op Ar secondary
65.Nm
66.Fl c
67.Op Fl nv
68.Bk -words
69.Op Fl m Ar machine
70.Ek
71.Bk -words
72.Op Fl o Ar options
73.Ek
74.Bk -words
75.Op Fl t Ar fstype
76.Ek
77.Ar filesystem
78.
79.Sh DESCRIPTION
80The
81.Nm
82utility installs and removes
83.Nx
84disk bootstrap software into a file system.
85.Nm
86can install
87.Ar primary
88into
89.Ar filesystem ,
90or disable an existing bootstrap in
91.Ar filesystem .
92.Pp
93Generally,
94.Nx
95disk bootstrap software consists of two parts: a
96.Dq primary
97bootstrap program usually written into the disklabel area of the
98file system by
99.Nm ,
100and a
101.Dq secondary
102bootstrap program that usually resides as an ordinary file in the file system.
103.Pp
104When booting, the primary bootstrap program is loaded and invoked by
105the machine's PROM or BIOS.
106After receiving control of the system it loads and runs the secondary
107bootstrap program, which in turn loads and runs the kernel.
108The secondary bootstrap may allow control over various boot parameters
109passed to the kernel.
110.Pp
111Perform the following steps to make a file system bootable:
112.Bl -enum
113.It
114Copy the secondary bootstrap (usually
115.Pa /usr/mdec/boot. Ns Sy MACHINE
116or
117.Pa /usr/mdec/boot )
118to the root directory of the target file system.
119.Pp
120.
121.It
122Use
123.Nm
124to install the primary bootstrap program
125(usually
126.Pa /usr/mdec/bootxx_ Ns Sy FSTYPE )
127into
128.Ar filesystem .
129.Pp
130The following platforms do not require this step if the primary bootstrap
131already exists and the secondary bootstrap file is just being updated:
132.Sy alpha ,
133.Sy amiga ,
134.Sy i386 ,
135.Sy pmax ,
136.Sy sparc64 ,
137and
138.Sy vax .
139.Pp
140.El
141.Pp
142The options and arguments recognized by
143.Nm
144are as follows:
145.
146.Bl -tag -width "optionsxxx"
147.
148.It Fl b Ar s1bno
149Install
150.Ar primary
151at block number
152.Ar s1bno
153instead of the default location for the machine and file system type.
154.Sy [ alpha ,
155.Sy pmax ,
156.Sy vax ]
157.
158.It Fl B Ar s2bno
159When hard-coding the blocks of
160.Ar secondary
161into
162.Ar primary ,
163start from block
164.Ar s2bno
165instead of trying to determine the block numbers occupied by
166.Ar secondary
167by examining
168.Ar filesystem .
169If this option is supplied,
170.Ar secondary
171should refer to an actual secondary bootstrap (rather than the
172file name of the one present in
173.Ar filesystem )
174so that its size can be determined.
175.
176.It Fl c
177Clear (remove) any existing bootstrap instead of installing one.
178.
179.It Fl m Ar machine
180Use
181.Ar machine
182as the target machine type.
183The default machine is determined from
184.Xr uname 3
185and then
186.Ev MACHINE .
187The following machines are currently supported by
188.Nm :
189.Bd -ragged -offset indent
190.Sy alpha ,
191.Sy amiga ,
192.Sy i386 ,
193.Sy macppc ,
194.Sy news68k ,
195.Sy newsmips ,
196.Sy pmax ,
197.Sy sparc ,
198.Sy sparc64 ,
199.Sy sun2 ,
200.Sy sun3 ,
201.Sy vax ,
202.Sy x68k
203.Ed
204.
205.
206.It Fl n
207Do not write to
208.Ar filesystem .
209.
210.It Fl o Ar options
211Machine specific
212.Nm
213options, comma separated.
214.Pp
215Supported options are (with the machines for they are valid in brackets):
216.
217.Bl -tag -offset indent -width alphasum
218.
219.It Sy alphasum
220.Sy [ alpha ]
221Recalculate and restore the Alpha checksum.
222This is the default for
223.Nx Ns Tn /alpha .
224.
225.It Sy append
226.Sy [ alpha ,
227.Sy pmax ,
228.Sy vax ]
229Append
230.Ar primary
231to the end of
232.Ar filesystem ,
233which must be a regular file in this case.
234.
235.It Sy command=<boot command>
236.Sy [ amiga ]
237Modify the default boot command line.
238.
239.It Sy console=<console name>
240.Sy [ i386 ]
241Set the console device, <console name> must be one of:
242pc, com0, com1, com2, com3, com0kbd, com1kbd, com2kbd or com3kbd.
243.
244.It Sy password=<password>
245.Sy [ i386 ]
246Set the password which must be entered before the boot menu can be accessed.
247.
248.It Sy resetvideo
249.Sy [ i386 ]
250Reset the video before booting.
251.
252.It Sy speed=<baud rate>
253.Sy [ i386 ]
254Set the baud rate for the serial console.
255.
256.It Sy sunsum
257.Sy [ alpha ,
258.Sy pmax ,
259.Sy vax ]
260Recalculate and restore the Sun and
261.Nx Ns Tn /sparc
262compatible checksum.
263.Em Note :
264The existing
265.Nx Ns Tn /sparc
266disklabel should use no more than 4 partitions.
267.
268.It Sy timeout=<seconds>
269.Sy [ i386 ]
270Set the timeout before the automatic boot begins to the given number of seconds.
271.El
272.
273.It Fl t Ar fstype
274Use
275.Ar fstype
276as the type of
277.Ar filesystem .
278The default operation is to attempt to auto-detect this setting.
279The following file system types are currently supported by
280.Nm :
281.
282.Bl -tag -offset indent -width ffs
283.
284.It Sy ffs
285.Bx
286Fast File System.
287.
288.It Sy raw
289.Sq Raw
290image.
291Note: if a platform needs to hard-code the block offset of the secondary
292bootstrap, it cannot be searched for on this file system type, and must
293be provided with
294.Fl B Ar s2bno .
295.El
296.
297.It Fl v
298Verbose operation.
299.
300.It Ar filesystem
301The path name of the device or file system image that
302.Nm
303is to operate on.
304It is not necessary for
305.Ar filesystem
306to be a currently mounted file system.
307.
308.It Ar primary
309The path name of the
310.Dq primary
311boot block to install.
312.
313.It Ar secondary
314The path name of the
315.Dq secondary
316boot block,
317relative to the top of
318.Ar filesystem .
319Most systems require
320.Ar secondary
321to be in the
322.Dq root
323directory of the file system, so the leading
324.Dq Pa /
325is not necessary on
326.Ar secondary .
327.Pp
328Only certain combinations of
329platform
330.Pq Fl m Ar machine
331and file system type
332.Pq Fl t Ar fstype
333require that the name of the secondary bootstrap is
334supplied as
335.Ar secondary ,
336so that information such as the disk block numbers occupied
337by the secondary bootstrap can be stored in the primary bootstrap.
338These are:
339.Bl -column "Platform" "File systems" -offset indent
340.It Sy "Platform" Ta Sy "File systems"
341.It macppc Ta ffs, raw
342.It news68k Ta ffs, raw
343.It newsmips Ta ffs, raw
344.It sparc Ta ffs, raw
345.It sun2 Ta ffs, raw
346.It sun3 Ta ffs, raw
347.El
348.El
349.Pp
350.Nm
351exits 0 on success, and \*[Gt]0 if an error occurs.
352.
353.Sh ENVIRONMENT
354.Nm
355uses the following environment variables:
356.
357.Bl -tag -width "MACHINE"
358.
359.It Ev MACHINE
360Default value for
361.Ar machine ,
362overriding the result from
363.Xr uname 3 .
364.
365.El
366.
367.Sh FILES
368Most
369.Nx
370ports will contain variations of the following files:
371.Pp
372.Bl -tag -width /usr/mdec/boot.$MACHINE
373.
374.It Pa /usr/mdec/bootxx_ Ns Sy FSTYPE
375Primary bootstrap for file system type
376.Sy FSTYPE .
377Installed into the bootstrap area of the file system by
378.Nm .
379.
380.It Pa /usr/mdec/boot. Ns Sy MACHINE
381Secondary bootstrap for machine type
382.Sy MACHINE .
383This should be installed into the file system before
384.Nm
385is run.
386.
387.It Pa /boot. Ns Sy MACHINE
388Installed copy of secondary bootstrap for machine type
389.Sy MACHINE .
390.
391.It Pa /boot
392Installed copy of secondary bootstrap.
393Searched for by the primary bootstrap if
394.Pa /boot. Ns Sy MACHINE
395is not found.
396.
397.El
398.
399.Ss NetBSD/sparc64 files
400.
401.Bl -tag -width /usr/mdec/boot.$MACHINE
402.
403.It Pa /usr/mdec/bootblk
404.Nx Ns Tn /sparc64
405primary bootstrap.
406.
407.It Pa /usr/mdec/ofwboot
408.Nx Ns Tn /sparc64
409secondary bootstrap.
410.
411.It Pa /ofwboot
412Installed copy of
413.Nx Ns Tn /sparc64
414secondary bootstrap.
415.
416.El
417.
418.Sh EXAMPLES
419.
420.Ss common
421Verbosely install the Berkeley Fast File System primary bootstrap on to disk
422.Sq sd0 :
423.Dl Ic installboot -v /dev/rsd0c /usr/mdec/bootxx_ffs
424.Pp
425Remove the primary bootstrap from disk
426.Sq sd1 :
427.Dl Ic installboot -c /dev/rsd1c
428.
429.Ss NetBSD/pmax
430Install the Berkeley Fast File System primary bootstrap on to disk
431.Sq sd0 :
432.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx_ffs
433.Pp
434.Nx Ns Tn /pmax
435requires that this file system starts at block 0 of the disk.
436.Pp
437Install the ISO 9660 primary bootstrap in the file
438.Pa /tmp/cd-image :
439.Dl Ic installboot -m pmax /tmp/cd-image /usr/mdec/bootxx_cd9660
440.Pp
441Make an ISO 9660 filesystem in the file
442.Pa /tmp/cd-image
443and install the ISO 9660 primary bootstrap in the filesystem, where the
444source directory for the ISO 9660 filesystem contains a kernel, the
445primary bootstrap
446.Pp
447.Pa bootxx_cd9660
448and the secondary bootstrap
449.Pa boot.pmax :
450.Dl Ic mkisofs -o /tmp/cd-image -a -l -v iso-source-dir
451.Dl ...
452.Dl 48 51 iso-source-dir/bootxx_cd9660
453.Dl ...
454.Dl Ic installboot -b `expr 48 \e* 4` /tmp/cd-image /usr/mdec/bootxx_cd9660
455.
456.Ss NetBSD/sparc
457Install the Berkeley Fast File System primary bootstrap on to disk
458.Sq sd0 ,
459with the secondary bootstrap
460.Sq Pa /boot
461already present:
462.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx /boot
463.
464.Ss NetBSD/sparc64
465Install the Berkeley Fast File System primary bootstrap on to disk
466.Sq wd0 :
467.Dl Ic installboot /dev/rwd0c /usr/mdec/bootblk
468.Pp
469The secondary
470.Nx Ns Tn /sparc64
471bootstrap is located in
472.Pa /usr/mdec/ofwboot .
473.
474.Ss NetBSD/sun2 and NetBSD/sun3
475Install the Berkeley Fast File System primary bootstrap on to disk
476.Sq sd0 ,
477with the secondary bootstrap
478.Sq Pa /boot
479already present:
480.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx /boot
481.
482.Ss NetBSD/amiga examples
483Modify the command line to change the default from "netbsd -ASn2" to
484"netbsd -S":
485.Dl Ic installboot -m amiga -o command="netbsd -S" /dev/rsd0a /usr/mdec/bootxx_ffs
486.
487.Sh SEE ALSO
488.Xr uname 3 ,
489.Xr boot 8 ,
490.Xr disklabel 8
491.
492.Sh HISTORY
493This implementation of
494.Nm
495appeared in
496.Nx 1.6 .
497.
498.Sh AUTHORS
499The machine independent portion of this implementation of
500.Nm
501was written by Luke Mewburn.
502The following people contributed to the various machine dependent
503back-ends:
504Simon Burge (pmax),
505Chris Demetriou (alpha),
506Matthew Fredette (sun2, sun3),
507Matthew Green (sparc64),
508Ross Harvey (alpha),
509Michael Hitch (amiga),
510Paul Kranenburg (sparc),
511David Laight (i386),
512Luke Mewburn (macppc),
513Matt Thomas (vax),
514and
515Izumi Tsutsui (news68k, newsmips).
516.
517.Sh BUGS
518There are not currently primary bootstraps to support all file systems
519types which are capable of being the root file system.
520.
521.Ss NetBSD/alpha
522The
523.Nx Ns Tn /alpha
524primary bootstrap program can only load the secondary bootstrap program
525from file systems starting at the beginning (block 0) of disks.
526Similarly, the secondary bootstrap program can only load kernels from
527file systems starting at the beginning of disks.
528.Pp
529The size of primary bootstrap programs is restricted to 7.5KB, even
530though some file systems (e.g., ISO 9660) are able to accommodate larger
531ones.
532.
533.Ss NetBSD/i386
534The size of primary bootstrap programs is restricted to 8KB, even
535though some file systems (e.g., ISO 9660) are able to accommodate larger
536ones.
537.
538.Ss NetBSD/pmax
539The
540.Nx Ns Tn /pmax
541secondary bootstrap program can only load kernels from file
542systems starting at the beginning of disks.
543.Pp
544The size of primary bootstrap programs is restricted to 7.5KB, even
545though some file systems (e.g., ISO 9660) are able to accommodate larger
546ones.
547.
548.Ss NetBSD/sun2 and NetBSD/sun3
549The
550.Nx Ns Tn /sun2
551and
552.Nx Ns Tn /sun3
553secondary bootstrap program can only load kernels from file
554systems starting at the beginning of disks.
555.
556.Ss NetBSD/vax
557The
558.Nx Ns Tn /vax
559secondary bootstrap program can only load kernels from file systems
560starting at the beginning of disks.
561.Pp
562The size of primary bootstrap programs is restricted to 7.5KB, even
563though some file systems (e.g., ISO 9660) are able to accommodate larger
564ones.
565