7489f94560571e4d71f44fdd8cd8beceb8edb4be
[yaboot.git] / man / ybin.8
1 .\" Hey Emacs! This file is -*- nroff -*- source.
2 .\"
3 .\" ybin (YaBoot INstaller) installs/updates the yaboot boot loader.
4 .\" Copyright (C) 2000, 2001 Ethan Benson
5 .\"
6 .\" This program is free software; you can redistribute it and/or
7 .\" modify it under the terms of the GNU General Public License
8 .\" as published by the Free Software Foundation; either version 2
9 .\" of the License, or (at your option) any later version.
10 .\"
11 .\" This program is distributed in the hope that it will be useful,
12 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
13 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14 .\" GNU General Public License for more details.
15 .\"
16 .\" You should have received a copy of the GNU General Public License          
17 .\" along with this program; if not, write to the Free Software                
18 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
19 .\"
20 .TH YBIN 8 "27 April 2001" "GNU/Linux PowerPC" "System Manager's Manual"
21 .SH NAME
22 .B ybin
23 \- install the yaboot boot loader to a bootstrap partition.
24 .SH SYNOPSIS
25 .B ybin 
26 .RB [ \ \-b | \-\-boot\ \fIdevice\  ]
27 .RB [ \ \-o | \-\-ofboot\ \fIof-path\  ]
28 .RB [ \ \-i | \-\-install\ \fIboot-file\  ]
29 .RB [ \ \-C | \-\-config\ \fIconfig-file\  ]
30 .RB [ \ \-m | \-\-magicboot\ \fIchrp-file\  ]
31 .RB [ \ \-\-filesystem\ \fIhfs | \fImsdos | \fIraw\  ]
32 .RB [ \ \-\-nobless\  ]
33 .RB [ \ \-M | \-\-mount\  ]
34 .RB [ \ \-\-hide\  ]
35 .RB [ \ \-\-protect\  ]
36 .RB [ \ \-\-nonvram\  ]
37 .RB [ \ \-\-device\ \fIOF-dev\  ]
38 .RB [ \ \-\-partition\ \fIroot-part-#\  ]
39 .RB [ \ \-\-timeout\ \fItimeout\  ]
40 .RB [ \ \-\-image\ \fIkernel\  ]
41 .RB [ \ \-\-label\ \fIlabel\  ]
42 .RB [ \ \-\-root\ \fIroot-dev\  ]
43 .RB [ \ \-\-force\  ]
44 .RB [ \ \-v | \-\-verbose\  ]
45 .RB [ \ \-\-debug\  ]
46 .RB [ \ \-h | \-\-help\  ]
47 .RB [ \ \-V | \-\-version\  ]
48 .SH DESCRIPTION
49 This manual page explains 
50 .B ybin 
51 the installer for the  
52 .BR yaboot (8) 
53 boot loader enabling GNU/Linux to be booted by OpenFirmware.
54 Specifically it copies the 
55 .B yaboot
56 binary and 
57 .BR yaboot.conf (5)
58 and usually a \*(lqmagicboot\*(rq script to a 
59 .BR bootstrap (8)
60 partition.  
61
62 .B Ybin
63 will set attributes on the boot loader files and to the
64 .BR bootstrap (8)
65 partition itself to allow OpenFirmware to recognise it as bootable,
66 [usually] without requiring alterations to OpenFirmware's configuration.
67
68 .B Ybin
69 will also set the OpenFirmware boot-device variable to the device path
70 of the \fBbootstrap\fR(8) partition using \fBnvsetenv\fR(8) when a
71 NewWorld compatible version of \fBnvsetenv\fR(8) is available.
72
73 .B Ybin 
74 requires that the 
75 .BR bootstrap (8)
76 partition have an HFS or MSDOS filesystem already on it.  For IBM
77 hardware there is no filesystem on the \fBbootstrap\fR(8) partition,
78 in this case use fstype=raw.  When using the raw filesystem type
79 \fBybin\fR requires that an ELF binary have already been installed on
80 the \fBbootstrap\fR(8) partition.  Use the companion
81 .BR mkofboot (8) 
82 utility to install the boot loader onto a new 
83 .BR bootstrap (8)
84 partition. 
85
86 The \fBbootstrap\fR(8) need not and should not be mounted anywhere on
87 your filesystem, especially not on top of /boot.  \fBYaboot\fR is able
88 to load the kernels from the ext2fs root partition so that is where
89 they should be kept. \fBYbin\fR will refuse to operate on the
90 \fBbootstrap\fR(8) partition if it is mounted.
91 .SH OPTIONS
92 .TP
93 .BR \-b ,\  \-\-boot\ \fIdevice
94 Install the boot loader onto the specified device, this device should
95 be that of your \fBbootstrap\fR(8) partition. For example, if your
96 \fBbootstrap\fR partition is located on your first primary IDE drive in the 
97 second partition, your device would be: \fI/dev/hda2\fR.
98 .TP
99 .BR \-o ,\  \-\-ofboot\ \fIof-path
100 The OpenFirmware device path to the \fBbootstrap\fR(8) partition. This
101 is needed so the first stage \fIofboot\fR loader can be configured
102 properly.  It should include the OpenFirmware path including the
103 partition number (but not any filename).  Example: if your
104 \fBbootstrap\fR(8) partition is /dev/hda2 the OF path will likely be
105 hd:2.  As of \fBybin\fR 0.18 you no longer are required to specify this
106 option, if left undefined ybin will attempt to figure out the
107 OpenFirmware path automatically using the \fBofpath\fR(8) utility.
108 You should only need to define this option if \fBofpath\fR(8) fails.
109 .TP
110 .BR \-i ,\  \-\-install\ \fIboot-file
111 Use \fIboot-file\fR as the primary boot loader executable, instead of
112 the default \fI/usr/local/lib/yaboot/yaboot\fR.
113 .TP
114 .BR \-C ,\  \-\-config\ \fIconfig-file
115 Use \fIconfig-file\fR as the \fBybin\fR/\fByaboot\fR(8) configuration
116 file instead of the default \fI/etc/yaboot.conf\fR.
117 .TP
118 .BR \-m ,\  \-\-magicboot\ \fIchrp-script
119 Use \fIchrp-script\fR as the boot loader \*(lqwrapper\*(rq.  This
120 script is needed to either provide a boot menu for dual boot with
121 MacOS or to load yaboot (due to an OpenFirmware bug).
122 .TP
123 .BR \-\-filesystem\ \fIhfs\fR|\fImsdos\fR|\fIraw
124 Set the filesystem type that \fBybin\fR expects to find on the
125 \fBbootstrap\fR(8).  The \*(lqraw\*(rq filesystem type causes \fBybin\fR
126 to copy the bootloader (the value of \fIinstall=\fR directly to the
127 \fBbootstrap\fR(8) partition without creating a filesystem.
128 \*(lqraw\*(rq is required on IBM hardware.  CAUTION: this will destroy any data or
129 filesystem on the bootstrap partition (value of \fIboot=\fR) if you
130 specify something like \fIboot=/dev/sda\fR you will destroy the
131 partition table and lose ALL data on the disk.  The default is HFS.
132 .TP
133 .BR \-M ,\  \-\-mount
134 Do not use the userspace
135 .BR hfsutils (1)
136 to modify the \fBbootstrap\fR(8), instead try and mount the filesystem
137 directly.  NOTE: Attributes cannot be set on the filesystem or the
138 boot loader files using this method, your system will NOT be bootable
139 without modifying OpenFirmware's \*(lqboot-device\*(rq variable to
140 something like: \*(lqhd:2,ofboot\*(rq (no quotes).
141 .TP
142 .BR \-\-nobless
143 Do not \*(lqbless\*(rq the root directory of the \fBbootstrap\fR(8)
144 partition's filesystem.  Only use this option if the \fBbootstrap\fR(8)
145 partition is actually a MacOS boot partition.  This option is ignored
146 unless the filesystem is HFS, and is ignored when used with \-\-mount.
147 .TP
148 .BR \-\-hide
149 .br
150 Set the invisible bit on all the boot loader files once copied to the
151 \fBbootstrap\fR(8) partition.  This setting is useful if you must install
152 the boot loader onto a MacOS boot partition and do not with to see the
153 boot loader files cluttering up the MacOS root directory.  This option
154 is ignored unless the filesystem is HFS, and will not work with
155 \-\-mount.
156 .TP
157 .BR \-\-protect
158 Set the read-only bit on all boot loader files once copied to the
159 \fBbootstrap\fR(8) partition.  This setting is useful if you must install
160 the bootloader onto a MacOS boot partition and want to discourage
161 alterations/deletion of the boot loader.  This option works for both
162 HFS and MSDOS filesystems.
163 .TP
164 .BR \-\-nonvram
165 Prevent \fBybin\fR from setting the OpenFirmware boot-device
166 variable with \fBnvsetenv\fR(8).
167 .TP
168 .BR \-\-device\ \fIopenfirmware-dev-path
169 This option is used for auto-generation of a \fByaboot.conf\fR(5).  This
170 specifies the OpenFirmware device of the disk the system will boot
171 from.  The default is \*(lqhd:\*(rq.
172 .TP
173 .BR \-\-partition\ \fIroot-partition-number
174 This option is used for auto-generation of a \fByaboot.conf\fR(5).  This
175 specifies the partition number of the root filesystem.  Mac partition
176 tables are considered a partition themselves, so the first real
177 partition will be 2, usually the \fBbootstrap\fR(8) partition, followed
178 by the root partition, number 3.
179 .TP
180 .BR \-\-timeout\ \fItimeout
181 This option is used for auto-generation of a \fByaboot.conf\fR(5).  This
182 specifies the timeout value in tenths of a second.  The timeout is how
183 long \fByaboot\fR(8) will wait before booting the default (first listed)
184 image.
185 .TP
186 .BR \-\-image\ \fIkernel-image
187 This option is used for auto-generation of a \fByaboot.conf\fR(5).  This
188 specifies the path to the default kernel to be booted.
189 .TP
190 .BR \-\-label\ \fIlabel
191 This option is used for auto-generation of a \fByaboot.conf\fR(5).  This
192 specifies the label used to boot the above kernel image.  The default
193 is Linux.
194 .TP
195 .BR \-\-root\ \fIroot-device
196 This option is used for auto-generation of a \fByaboot.conf\fR(5).  This
197 specifies the Linux device for the root partition, this is passed to
198 the kernel at boot time.  The default is \fI/dev/hda3\fR.
199 .TP
200 .BR \-v ,\  \-\-verbose
201 This option causes \fBybin\fR to be more verbose as it proceeds.
202 .TP
203 .BR \-f ,\  \-\-force
204 This option suppresses any confirmation questions.
205 .TP
206 .BR \-\-debug
207 This option causes \fBybin\fR to output some boring details useful
208 only for debugging \fBybin\fR itself.
209 .TP
210 .BR \-h ,\  \-\-help
211 Print out usage information and exit.
212 .TP
213 .BR \-V ,\  \-\-version
214 Print out the version number and exit.
215 .SH FILES
216 .nf
217 /usr/local/lib/yaboot/yaboot \- boot loader executable
218 /usr/local/lib/yaboot/ofboot \- OpenFirmware boot script
219 /etc/yaboot.conf \- boot loader/ybin configuration file
220 .fi
221 .SH ENVIRONMENT
222 .TP
223 .B TMPDIR
224 .br
225 The temporary directory \fBybin\fR will use.
226 .SH SECURITY
227 The \fByaboot.conf\fR(5) auto generation requires a temporary file, this
228 file is created with
229 .BR mktemp (1).
230 It is important that your system use a secure 
231 .BR mktemp (1)
232 program, otherwise \fBybin\fR will be vulnerable to race conditions.
233 The Debian mktemp is derived from OpenBSD and thus should be secure.
234
235 \fI/usr/local/lib/yaboot/ofboot\fR now contains code executed by /bin/sh (by
236 \fBybin\fR). It is thus critical that it not be writable by anyone but
237 root.  It is also critical that \fI/etc/yaboot.conf\fR not be writable
238 by anyone but root since a different \fIofboot\fR script could be
239 specified there.
240 .SH BUGS
241 .B Ybin 
242 should be able to take care of OpenFirmware variables as needed on IBM
243 hardware.
244 .SH AUTHORS
245 .B ybin
246 and this man page was written by Ethan Benson. 
247 .br
248 .B yaboot
249 was written by Benjamin Herrenschmidt.
250 .SH REPORTING BUGS
251 Report bugs to <erbenson@alaska.net>
252 .br
253 Report bugs in \fByaboot\fR(8) to <benh@kernel.crashing.org>
254 .SH SEE ALSO
255 .BR bootstrap (8),
256 .BR hfsutils (1),
257 .BR mkofboot (8),
258 .BR mktemp (1),
259 .BR nvsetenv (8),
260 .BR ofpath (8),
261 .BR yaboot (8),
262 .BR yaboot.conf (5),