xref: /netbsd-src/usr.sbin/installboot/installboot.8 (revision e5548b402ae4c44fb816de42c7bba9581ce23ef5)
1.\"	$NetBSD: installboot.8,v 1.51 2005/11/12 16:44:07 wiz 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 November 12, 2005
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.Op Fl B Ar s2bno
48.Op Fl b Ar s1bno
49.Op Fl m Ar machine
50.Op Fl o Ar options
51.Op Fl t Ar fstype
52.Ar filesystem
53.Ar primary
54.Op Ar secondary
55.Nm
56.Fl c
57.Op Fl nv
58.Op Fl m Ar machine
59.Op Fl o Ar options
60.Op Fl t Ar fstype
61.Ar filesystem
62.Nm
63.Fl e
64.Op Fl nv
65.Op Fl m Ar machine
66.Op Fl o Ar options
67.Ar bootstrap
68.
69.Sh DESCRIPTION
70The
71.Nm
72utility installs and removes
73.Nx
74disk bootstrap software into a file system.
75.Nm
76can install
77.Ar primary
78into
79.Ar filesystem ,
80or disable an existing bootstrap in
81.Ar filesystem .
82.Pp
83Generally,
84.Nx
85disk bootstrap software consists of two parts: a
86.Dq primary
87bootstrap program usually written into the disklabel area of the
88file system by
89.Nm ,
90and a
91.Dq secondary
92bootstrap program that usually resides as an ordinary file in the file system.
93.Pp
94When booting, the primary bootstrap program is loaded and invoked by
95the machine's PROM or BIOS.
96After receiving control of the system it loads and runs the secondary
97bootstrap program, which in turn loads and runs the kernel.
98The secondary bootstrap may allow control over various boot parameters
99passed to the kernel.
100.Pp
101Perform the following steps to make a file system bootable:
102.Bl -enum
103.It
104Copy the secondary bootstrap (usually
105.Pa /usr/mdec/boot. Ns Sy MACHINE
106or
107.Pa /usr/mdec/boot )
108to the root directory of the target file system.
109.Pp
110.
111.It
112Use
113.Nm
114to install the primary bootstrap program
115(usually
116.Pa /usr/mdec/bootxx_ Ns Sy FSTYPE )
117into
118.Ar filesystem .
119.Pp
120The following platforms do not require this step if the primary bootstrap
121already exists and the secondary bootstrap file is just being updated:
122.Sy alpha ,
123.Sy amd64 ,
124.Sy amiga ,
125.Sy i386 ,
126.Sy pmax ,
127.Sy sparc64 ,
128and
129.Sy vax .
130.Pp
131The following platform does not require the first step since a
132single bootstrap file is used.
133The single bootstrap is installed like the primary bootstrap on
134other platforms:
135.Sy next68k .
136.Pp
137.El
138.Pp
139The options and arguments recognized by
140.Nm
141are as follows:
142.
143.Bl -tag -width "optionsxxx"
144.
145.It Fl B Ar s2bno
146When hard-coding the blocks of
147.Ar secondary
148into
149.Ar primary ,
150start from block
151.Ar s2bno
152instead of trying to determine the block numbers occupied by
153.Ar secondary
154by examining
155.Ar filesystem .
156If this option is supplied,
157.Ar secondary
158should refer to an actual secondary bootstrap (rather than the
159file name of the one present in
160.Ar filesystem )
161so that its size can be determined.
162.
163.It Fl b Ar s1bno
164Install
165.Ar primary
166at block number
167.Ar s1bno
168instead of the default location for the machine and file system type.
169.Sy [ alpha ,
170.Sy pmax ,
171.Sy vax ]
172.
173.It Fl c
174Clear (remove) any existing bootstrap instead of installing one.
175.
176.It Fl e
177Edit the options of an existing bootstrap.
178.Sy [ amd64 , i386 ]
179.
180.It Fl m Ar machine
181Use
182.Ar machine
183as the target machine type.
184The default machine is determined from
185.Xr uname 3
186and then
187.Ev MACHINE .
188The following machines are currently supported by
189.Nm :
190.Bd -ragged -offset indent
191.Sy alpha ,
192.Sy amd64 ,
193.Sy amiga ,
194.Sy hp300 ,
195.Sy hp700 ,
196.Sy i386 ,
197.Sy macppc ,
198.Sy news68k ,
199.Sy newsmips ,
200.Sy next68k ,
201.Sy pmax ,
202.Sy sparc ,
203.Sy sparc64 ,
204.Sy sun2 ,
205.Sy sun3 ,
206.Sy vax ,
207.Sy x68k
208.Ed
209.
210.
211.It Fl n
212Do not write to
213.Ar filesystem .
214.
215.It Fl o Ar options
216Machine specific
217.Nm
218options, comma separated.
219.Pp
220Supported options are (with the machines for they are valid in brackets):
221.
222.Bl -tag -offset indent -width alphasum
223.
224.It Sy alphasum
225.Sy [ alpha ]
226Recalculate and restore the Alpha checksum.
227This is the default for
228.Nx Ns Tn /alpha .
229.
230.It Sy append
231.Sy [ alpha ,
232.Sy pmax ,
233.Sy vax ]
234Append
235.Ar primary
236to the end of
237.Ar filesystem ,
238which must be a regular file in this case.
239.
240.It Sy command=\*[Lt]boot command\*[Gt]
241.Sy [ amiga ]
242Modify the default boot command line.
243.
244.It Sy console=\*[Lt]console name\*[Gt]
245.Sy [ amd64 ,
246.Sy i386 ]
247Set the console device, \*[Lt]console name\*[Gt] must be one of:
248pc, com0, com1, com2, com3, com0kbd, com1kbd, com2kbd or com3kbd.
249.
250.It Sy ioaddr=\*[Lt]ioaddr\*[Gt]
251.Sy [ amd64 ,
252.Sy i386 ]
253Set the IO address to be used for the console serial port.
254Defaults to the IO address used by the system BIOS for the specified port.
255.
256.It Sy keymap=\*[Lt]keymap\*[Gt]
257.Sy [ amd64 ,
258.Sy i386 ]
259Set a boot time keyboard translation map.
260Each character in \*[Lt]keymap\*[Gt] will be replaced by the one following it.
261For example, an argument of
262.Dq zyz
263would swap the lowercase letters
264.Sq y
265and
266.Sq z .
267.
268.It Sy password=\*[Lt]password\*[Gt]
269.Sy [ amd64 ,
270.Sy i386 ]
271Set the password which must be entered before the boot menu can be accessed.
272.
273.It Sy resetvideo
274.Sy [ amd64 ,
275.Sy i386 ]
276Reset the video before booting.
277.
278.It Sy speed=\*[Lt]baud rate\*[Gt]
279.Sy [ amd64 ,
280.Sy i386 ]
281Set the baud rate for the serial console.
282If a value of zero is specified, then the current baud rate (set by the
283BIOS) will be used.
284.
285.It Sy sunsum
286.Sy [ alpha ,
287.Sy pmax ,
288.Sy vax ]
289Recalculate and restore the Sun and
290.Nx Ns Tn /sparc
291compatible checksum.
292.Em Note :
293The existing
294.Nx Ns Tn /sparc
295disklabel should use no more than 4 partitions.
296.
297.It Sy timeout=\*[Lt]seconds\*[Gt]
298.Sy [ amd64 ,
299.Sy i386 ]
300Set the timeout before the automatic boot begins to the given number of seconds.
301.El
302.
303.It Fl t Ar fstype
304Use
305.Ar fstype
306as the type of
307.Ar filesystem .
308The default operation is to attempt to auto-detect this setting.
309The following file system types are currently supported by
310.Nm :
311.
312.Bl -tag -offset indent -width ffs
313.
314.It Sy ffs
315.Bx
316Fast File System.
317.
318.It Sy raw
319.Sq Raw
320image.
321Note: if a platform needs to hard-code the block offset of the secondary
322bootstrap, it cannot be searched for on this file system type, and must
323be provided with
324.Fl B Ar s2bno .
325.El
326.
327.It Fl v
328Verbose operation.
329.
330.It Ar filesystem
331The path name of the device or file system image that
332.Nm
333is to operate on.
334It is not necessary for
335.Ar filesystem
336to be a currently mounted file system.
337.
338.It Ar primary
339The path name of the
340.Dq primary
341boot block to install.
342.
343.It Ar secondary
344The path name of the
345.Dq secondary
346boot block,
347relative to the top of
348.Ar filesystem .
349Most systems require
350.Ar secondary
351to be in the
352.Dq root
353directory of the file system, so the leading
354.Dq Pa /
355is not necessary on
356.Ar secondary .
357.Pp
358Only certain combinations of
359platform
360.Pq Fl m Ar machine
361and file system type
362.Pq Fl t Ar fstype
363require that the name of the secondary bootstrap is
364supplied as
365.Ar secondary ,
366so that information such as the disk block numbers occupied
367by the secondary bootstrap can be stored in the primary bootstrap.
368These are:
369.Bl -column "Platform" "File systems" -offset indent
370.It Sy "Platform" Ta Sy "File systems"
371.It macppc Ta ffs, raw
372.It news68k Ta ffs, raw
373.It newsmips Ta ffs, raw
374.It sparc Ta ffs, raw
375.It sun2 Ta ffs, raw
376.It sun3 Ta ffs, raw
377.El
378.El
379.Pp
380.Nm
381exits 0 on success, and \*[Gt]0 if an error occurs.
382.
383.Sh ENVIRONMENT
384.Nm
385uses the following environment variables:
386.
387.Bl -tag -width "MACHINE"
388.
389.It Ev MACHINE
390Default value for
391.Ar machine ,
392overriding the result from
393.Xr uname 3 .
394.
395.El
396.
397.Sh FILES
398Most
399.Nx
400ports will contain variations of the following files:
401.Pp
402.Bl -tag -width /usr/mdec/bootxx_ustarfs
403.
404.It Pa /usr/mdec/bootxx_ Ns Sy FSTYPE
405Primary bootstrap for file system type
406.Sy FSTYPE .
407Installed into the bootstrap area of the file system by
408.Nm .
409.
410.It Pa /usr/mdec/bootxx_ffsv1
411Primary bootstrap for
412.Sy FFSv1
413file systems
414(the "traditional"
415.Nx
416file system).
417.
418.It Pa /usr/mdec/bootxx_ffsv2
419Primary bootstrap for
420.Sy FFSv2
421file systems.
422.
423.It Pa /usr/mdec/bootxx_lfsv1
424Primary bootstrap for
425.Sy LFSv1
426file systems.
427.
428.It Pa /usr/mdec/bootxx_lfsv2
429Primary bootstrap for
430.Sy LFSv2
431file systems
432(the default LFS version).
433.
434.It Pa /usr/mdec/bootxx_msdos
435Primary bootstrap for
436.Tn MS-DOS
437.Sy FAT
438file systems.
439.
440.It Pa /usr/mdec/bootxx_ustarfs
441Primary bootstrap for
442.Sy TARFS
443boot images.
444This is used by various install media.
445.
446.It Pa /usr/mdec/boot. Ns Sy MACHINE
447Secondary bootstrap for machine type
448.Sy MACHINE .
449This should be installed into the file system before
450.Nm
451is run.
452.
453.It Pa /usr/mdec/boot
454Synonym for
455.Pa /usr/mdec/boot. Ns Sy MACHINE
456.
457.It Pa /boot. Ns Sy MACHINE
458Installed copy of secondary bootstrap for machine type
459.Sy MACHINE .
460.
461.It Pa /boot
462Installed copy of secondary bootstrap.
463Searched for by the primary bootstrap if
464.Pa /boot. Ns Sy MACHINE
465is not found.
466.
467.El
468.
469.Ss NetBSD/next68k files
470.
471.Bl -tag -width /usr/mdec/bootxx_ustarfs
472.
473.It Pa /usr/mdec/boot
474.Nx Ns Tn /next68k
475bootstrap.
476.
477.El
478.
479.Ss NetBSD/sparc64 files
480.
481.Bl -tag -width /usr/mdec/bootxx_ustarfs
482.
483.It Pa /usr/mdec/bootblk
484.Nx Ns Tn /sparc64
485primary bootstrap.
486.
487.It Pa /usr/mdec/ofwboot
488.Nx Ns Tn /sparc64
489secondary bootstrap.
490.
491.It Pa /ofwboot
492Installed copy of
493.Nx Ns Tn /sparc64
494secondary bootstrap.
495.
496.El
497.
498.Sh EXAMPLES
499.
500.Ss common
501Verbosely install the Berkeley Fast File System primary bootstrap on to disk
502.Sq sd0 :
503.Dl Ic installboot -v /dev/rsd0c /usr/mdec/bootxx_ffs
504.Pp
505Remove the primary bootstrap from disk
506.Sq sd1 :
507.Dl Ic installboot -c /dev/rsd1c
508.
509.Ss NetBSD/amiga
510Modify the command line to change the default from "netbsd -ASn2" to
511"netbsd -S":
512.Dl Ic installboot -m amiga -o command="netbsd -S" /dev/rsd0a /usr/mdec/bootxx_ffs
513.
514.Ss NetBSD/i386 and NetBSD/amd64
515Install new boot blocks on an existing mounted root file system on
516.Sq wd0 ,
517setting the timeout to five seconds, after copying a new secondary
518bootstrap:
519.Dl Ic cp /usr/mdec/boot /boot
520.Dl Ic installboot -v -o timeout=5 /dev/rwd0a /usr/mdec/bootxx_ffsv1
521.
522.Pp
523Create a bootable CD-ROM with an ISO9660
524file system for a system with a serial console:
525.Dl Ic mkdir cdrom
526.Dl Ic cp sys/arch/i386/compile/mykernel/netbsd cdrom/netbsd
527.Dl Ic cp /usr/mdec/boot cdrom/boot
528.Dl Ic cp /usr/mdec/bootxx_cd9660 bootxx
529.Dl Ic installboot -t raw -o console=com0,speed=19200 bootxx \
530	/usr/mdec/bootxx_cd9660
531.Dl Ic makefs -t cd9660 -o 'bootimage=i386;bootxx,no-emul-boot' boot.iso \
532	cdrom
533.
534.Pp
535Create a bootable floppy disk with an FFSv1
536file system for a small custom kernel (note: bigger kernels needing
537multiple disks are handled with the ustarfs file system):
538.Dl Ic newfs -s 1440k /dev/rfd0a
539.Bd -ragged -offset indent-two -compact
540.Em Note :
541Ignore the warnings that
542.Xr newfs 8
543displays; it can not write a disklabel,
544which is not a problem for a floppy disk.
545.Ed
546.Dl Ic mount /dev/fd0a /mnt
547.Dl Ic cp /usr/mdec/boot /mnt/boot
548.Dl Ic gzip -9 \*[Lt] sys/arch/i386/compile/mykernel/netbsd \*[Gt] /mnt/netbsd.gz
549.Dl Ic umount /mnt
550.Dl Ic installboot -v /dev/rfd0a /usr/mdec/bootxx_ffsv1
551.
552.Pp
553Create a bootable FAT file system on
554.Sq wd1a ,
555which should have the same offset and size as a FAT primary partition
556in the Master Boot Record (MBR):
557.Dl Ic newfs_msdos -r 16 /dev/rwd1a
558.Bd -ragged -offset indent-two -compact
559.Em Notes :
560The
561.Fl r Ar 16
562is to reserve space for the primary bootstrap.
563.Xr newfs_msdos 8
564will display an
565.Dq MBR type
566such as
567.Ql 1 ,
568.Ql 4 ,
569or
570.Ql 6 ;
571the MBR partition type of the appropriate primary partition should be
572changed to this value.
573.Ed
574.Dl Ic mount -t msdos /dev/wd1a /mnt
575.Dl Ic cp /usr/mdec/boot /mnt/boot
576.Dl Ic cp path/to/kernel /mnt/netbsd
577.Dl Ic umount /mnt
578.Dl Ic installboot -t raw /dev/rwd1a /usr/mdec/bootxx_msdos
579.Bd -ragged -offset indent-two -compact
580.Em Note :
581It may be necessary to ensure that there is a valid
582.Nx
583disklabel on
584.Sq wd1
585for the primary bootstrap to function correctly.
586.Ed
587.
588.Ss NetBSD/next68k
589Install the bootstrap on to disk
590.Sq sd0 :
591.Dl Ic installboot /dev/rsd0c /usr/mdec/boot
592.Pp
593.
594.Ss NetBSD/pmax
595Install the Berkeley Fast File System primary bootstrap on to disk
596.Sq sd0 :
597.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx_ffs
598.Pp
599.Nx Ns Tn /pmax
600requires that this file system starts at block 0 of the disk.
601.Pp
602Install the ISO 9660 primary bootstrap in the file
603.Pa /tmp/cd-image :
604.Dl Ic installboot -m pmax /tmp/cd-image /usr/mdec/bootxx_cd9660
605.Pp
606Make an ISO 9660 filesystem in the file
607.Pa /tmp/cd-image
608and install the ISO 9660 primary bootstrap in the filesystem, where the
609source directory for the ISO 9660 filesystem contains a kernel, the
610primary bootstrap
611.Pa bootxx_cd9660
612and the secondary bootstrap
613.Pa boot.pmax :
614.Dl Ic mkisofs -o /tmp/cd-image -a -l -v iso-source-dir
615.Dl ...
616.Dl 48 51 iso-source-dir/bootxx_cd9660
617.Dl ...
618.Dl Ic installboot -b `expr 48 \e* 4` /tmp/cd-image /usr/mdec/bootxx_cd9660
619.
620.Ss NetBSD/sparc
621Install the Berkeley Fast File System primary bootstrap on to disk
622.Sq sd0 ,
623with the secondary bootstrap
624.Sq Pa /boot
625already present:
626.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx /boot
627.
628.Ss NetBSD/sparc64
629Install the Berkeley Fast File System primary bootstrap on to disk
630.Sq wd0 :
631.Dl Ic installboot /dev/rwd0c /usr/mdec/bootblk
632.Pp
633The secondary
634.Nx Ns Tn /sparc64
635bootstrap is located in
636.Pa /usr/mdec/ofwboot .
637.
638.Ss NetBSD/sun2 and NetBSD/sun3
639Install the Berkeley Fast File System primary bootstrap on to disk
640.Sq sd0 ,
641with the secondary bootstrap
642.Sq Pa /boot
643already present:
644.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx /boot
645.
646.Sh SEE ALSO
647.Xr uname 3 ,
648.Xr boot 8 ,
649.Xr disklabel 8
650.
651.Sh HISTORY
652This implementation of
653.Nm
654appeared in
655.Nx 1.6 .
656.
657.Sh AUTHORS
658The machine independent portion of this implementation of
659.Nm
660was written by Luke Mewburn.
661The following people contributed to the various machine dependent
662back-ends:
663Simon Burge (pmax),
664Chris Demetriou (alpha),
665Matthew Fredette (sun2, sun3),
666Matthew Green (sparc64),
667Ross Harvey (alpha),
668Michael Hitch (amiga),
669Paul Kranenburg (sparc),
670David Laight (i386),
671Christian Limpach (next68k),
672Luke Mewburn (macppc),
673Matt Thomas (vax),
674and
675Izumi Tsutsui (news68k, newsmips).
676.
677.Sh BUGS
678There are not currently primary bootstraps to support all file systems
679types which are capable of being the root file system.
680.
681.Ss NetBSD/alpha
682The
683.Nx Ns Tn /alpha
684primary bootstrap program can only load the secondary bootstrap program
685from file systems starting at the beginning (block 0) of disks.
686Similarly, the secondary bootstrap program can only load kernels from
687file systems starting at the beginning of disks.
688.Pp
689The size of primary bootstrap programs is restricted to 7.5KB, even
690though some file systems (e.g., ISO 9660) are able to accommodate larger
691ones.
692.
693.Ss NetBSD/hp300
694The disk must have a boot partition large enough to hold the bootstrap code.
695Currently the primary bootstrap must be a LIF format file.
696.
697.Ss NetBSD/i386 and NetBSD/amd64
698The bootstrap must be installed in the
699.Nx
700partition that starts at the beginning of the mbr partition.
701If that is a valid filesystem and contains the
702.Pa /boot
703program then it will be used as the root filesystem, otherwise the
704.Sq a
705partition will be booted.
706.Pp
707The size of primary bootstrap programs is restricted to 8KB, even
708though some file systems (e.g., ISO 9660) are able to accommodate larger
709ones.
710.
711.Ss NetBSD/next68k
712The size of bootstrap programs is restricted to the free space before
713the file system at the beginning of the disk minus 8KB.
714.
715.Ss NetBSD/pmax
716The
717.Nx Ns Tn /pmax
718secondary bootstrap program can only load kernels from file
719systems starting at the beginning of disks.
720.Pp
721The size of primary bootstrap programs is restricted to 7.5KB, even
722though some file systems (e.g., ISO 9660) are able to accommodate larger
723ones.
724.
725.Ss NetBSD/sun2 and NetBSD/sun3
726The
727.Nx Ns Tn /sun2
728and
729.Nx Ns Tn /sun3
730secondary bootstrap program can only load kernels from file
731systems starting at the beginning of disks.
732.
733.Ss NetBSD/vax
734The
735.Nx Ns Tn /vax
736secondary bootstrap program can only load kernels from file systems
737starting at the beginning of disks.
738.Pp
739The size of primary bootstrap programs is restricted to 7.5KB, even
740though some file systems (e.g., ISO 9660) are able to accommodate larger
741ones.
742