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),