Contents of /trunk/grubby/grubby.8
Parent Directory | Revision Log
Revision 3013 -
(show annotations)
(download)
Tue Jun 27 14:33:29 2017 UTC (7 years, 2 months ago) by niro
File size: 13455 byte(s)
Tue Jun 27 14:33:29 2017 UTC (7 years, 2 months ago) by niro
File size: 13455 byte(s)
Update grubby man page contents (#bz1232168)
1 | .TH GRUBBY 8 "Tue Jan 18 2005" |
2 | |
3 | .SH NAME |
4 | |
5 | grubby \- command line tool used to configure bootloader menu entries across multiple architectures |
6 | |
7 | .SH SYNOPSIS |
8 | |
9 | \fBgrubby\fR [\fIOPTIONS...\fR] |
10 | |
11 | .SH DESCRIPTION |
12 | |
13 | .SS General Information |
14 | |
15 | \fBgrubby\fR is a command line tool for updating and displaying information |
16 | about the configuration files for various architecture specific bootloaders. |
17 | It is primarily designed to be used from scripts which install new kernels |
18 | and need to find information about the current boot environment. |
19 | |
20 | .SS Architecture Support |
21 | |
22 | The \fBgrubby\fR executable has full support for the \fBgrub2\fR |
23 | bootloader on \fBx86_64\fR systems using legacy BIOS or modern |
24 | UEFI firmware and \fBppc64\fR and \fBppc64le\fR hardware using |
25 | OPAL or SLOF as firmware. |
26 | |
27 | Legacy \fBs390\fR and the current \fBs390x\fR architectures |
28 | and their \fBzipl\fR bootloader are fully supported. |
29 | |
30 | Support for \fByaboot\fR has been deprecated as all ppc architecture |
31 | hardware since the Power8 system uses \fBgrub2\fR or petitboot |
32 | which both use the grub2 configuration file format. |
33 | |
34 | Legacy bootloaders \fBLILO\fR, \fBSILO\fR, and \fBELILO\fR |
35 | are deprecated in favor of previously mentioned bootloaders. The |
36 | \fBSILO\fR bootloader should also be considered unsupported. |
37 | |
38 | .SS Default Behavior |
39 | |
40 | The default architecture is chosen at compile time. The grubby executable |
41 | has a series of built in assumptions about what bootloader is being used and |
42 | where its configuration file lives. If no output format option is specified |
43 | on the command line then grubby will use these default settings to first |
44 | search for an existing configuration and, if it is not found, assume that |
45 | it should be placed in the standard location. These default assumptions are |
46 | listed in the table below. |
47 | |
48 | .TS |
49 | allbox; |
50 | lbw6 lbw10 lbw18 |
51 | l l l. |
52 | Arch Bootloader Configuration File |
53 | x86_64 [BIOS] grub2 /boot/grub2/grub.cfg |
54 | x86_64 [UEFI] grub2 /boot/efi/EFI/redhat/grub.cfg |
55 | i386 grub2 /boot/grub2/grub.cfg |
56 | ia64 elilo /boot/efi/EFI/redhat/elilo.conf |
57 | ppc [>=Power8] grub2 /boot/grub2/grub.cfg |
58 | ppc [<=Power7] yaboot /etc/yaboot.conf |
59 | s390 zipl /etc/zipl.conf |
60 | s390x zipl /etc/zipl.conf |
61 | .TE |
62 | |
63 | |
64 | .SS Special Arguments |
65 | |
66 | There are a number of ways to specify the kernel used for \fB-\-info\fR, |
67 | \fB-\-remove-kernel\fR, and \fB-\-update-kernel\fR. Specifying \fBDEFAULT\fR |
68 | or \fBALL\fR selects the default entry and all of the entries, respectively. |
69 | If a comma separated list of numbers is given, the boot entries indexed |
70 | by those numbers are selected. Finally, the title of a boot entry may |
71 | be specified by using \fBTITLE=\fItitle\fR as the argument; all entries |
72 | with that title are used. |
73 | |
74 | .SH OPTIONS |
75 | |
76 | .SS Basic Options |
77 | |
78 | .TP |
79 | \fB-\-add-kernel\fR=\fIkernel-path\fR |
80 | Add a new boot entry for the kernel located at \fIkernel-path\fR. A title for |
81 | the boot entry must be set using \fB-\-title\fR. Most invocations should also |
82 | include \fB-\-initrd\fR with memtest86 as a notable exception. |
83 | |
84 | The \fB-\-update-kernel\fR |
85 | option may not be used in the same invocation. |
86 | |
87 | .TP |
88 | \fB-\-remove-kernel\fR=\fIkernel-path\fR |
89 | Removes all boot entries which match \fIkernel-path\fR. This may be used |
90 | along with \fB-\-add-kernel\fR, in which case the new kernel being added will |
91 | never be removed. |
92 | |
93 | .TP |
94 | \fB-\-update-kernel\fR=\fIkernel-path\fR |
95 | The entries for kernels matching \fRkernel-path\fR are updated. Currently |
96 | the only items that can be updated is the kernel argument list, which is |
97 | modified via the \fB-\-args\fR and \fB-\-remove-args\fR options. |
98 | |
99 | .TP |
100 | \fB-\-args\fR=\fIkernel-args\fR |
101 | When a new kernel is added, this specifies the command line arguments |
102 | which should be passed to the kernel by default (note they are merged |
103 | with the arguments from the template if \fB-\-copy-default\fR is used). |
104 | When \fB-\-update-kernel\fR is used, this specifies new arguments to add |
105 | to the argument list. Multiple, space separated arguments may be used. If |
106 | an argument already exists the new value replaces the old values. The |
107 | \fBroot=\fR kernel argument gets special handling if the configuration |
108 | file has special handling for specifying the root filesystem (like |
109 | lilo.conf does). |
110 | |
111 | .TP |
112 | \fB-\-remove-args\fR=\fIkernel-args\fR |
113 | The arguments specified by \fIkernel-args\fR are removed from the |
114 | kernels specified by \fB-\-update-kernel\fR. The \fBroot\fR argument |
115 | gets special handling for configuration files that support separate root |
116 | filesystem configuration. |
117 | |
118 | .TP |
119 | \fB-\-copy-default\fR |
120 | \fBgrubby\fR will copy as much information (such as kernel arguments and |
121 | root device) as possible from the current default kernel. The kernel path |
122 | and initrd path will never be copied. |
123 | |
124 | .TP |
125 | \fB-\-title\fR=\fIentry-title\fR |
126 | When a new kernel entry is added \fIentry-title\fR is used as the title |
127 | (\fBlilo\fR label) for the entry. If \fIentry-title\fR is longer then maximum |
128 | length allowed by the bootloader (15 for lilo, unlimited for grub and elilo) |
129 | the title is shortened to a (unique) entry. |
130 | |
131 | .TP |
132 | \fB-\-initrd\fR=\fIinitrd-path\fR |
133 | Use \fIinitrd-path\fR as the path to an initial ram disk for a new kernel |
134 | being added. |
135 | |
136 | .TP |
137 | \fB-\-efi\fR |
138 | Use linuxefi and initrdefi when constructing bootloader stanzas instead of linux and initrd. |
139 | |
140 | .TP |
141 | \fB-\-set-default\fR=\fIkernel-path\fR |
142 | The first entry which boots the specified kernel is made the default |
143 | boot entry. This may not be invoked with \fB-\-set-default-index\fR. |
144 | |
145 | .TP |
146 | \fB-\-set-default-index\fR=\fIentry-index\fR |
147 | Makes the given entry number the default boot entry. This may not |
148 | be invoked with \fB-\-set-default\fR. |
149 | |
150 | .TP |
151 | \fB-\-make-default\fR |
152 | Make the new kernel entry being added the default entry. |
153 | |
154 | .TP |
155 | \fB-\-set-index\fR=\fIentry-index\fR |
156 | Set the position at which to add a new entry created with \fB-\-add-kernel\fR. |
157 | |
158 | .TP |
159 | \fB-\-debug\fR |
160 | Display extra debugging information for failures. |
161 | |
162 | .TP |
163 | \fB-i\fR, \fB-\-extra-initrd\fR=\fIinitrd-path\fR |
164 | Use \fIinitrd-path\fR as the path for an auxiliary initrd image. |
165 | |
166 | .SS Display Options |
167 | |
168 | Passing the display option to grubby will cause it to print out the |
169 | requested information about the current bootloader configuration and |
170 | then immediately exit. These options should not be used in any |
171 | script intended to update the bootloader configuration. |
172 | |
173 | .TP |
174 | \fB-\-default-kernel\fR |
175 | Display the full path to the current default kernel and exit. |
176 | |
177 | .TP |
178 | \fB-\-default-index\fR |
179 | Display the numeric index of the current default boot entry and exit. |
180 | |
181 | .TP |
182 | \fB-\-default-title\fR |
183 | Display the title of the current default boot entry and exit. |
184 | |
185 | .TP |
186 | \fB-\-info\fR=\fIkernel-path\fR |
187 | Display information on all boot entries which match \fIkernel-path\fR. I |
188 | |
189 | .TP |
190 | \fB-\-bootloader-probe\fR |
191 | \fBgrubby\fR tries to determine if \fBgrub\fR or \fBlilo\fR is currently |
192 | installed. When one of those bootloaders is found the name of that bootloader |
193 | is displayed on stdout. Both could be installed (on different devices), and |
194 | grubby will print out the names of both bootloaders, one per line. The probe |
195 | for \fBgrub\fR requires a commented out boot directive \fBgrub.conf\fR |
196 | identical to the standard directive in the lilo configuration file. If this |
197 | is not present \fBgrubby\fR will assume grub is not installed (note |
198 | that \fBanaconda\fR places this directive in \fBgrub.conf\fR files it creates). |
199 | |
200 | \fIThis option is only available on i386 platforms.\fR |
201 | |
202 | .TP |
203 | \fB-v\fR, \fB-\-version\fR |
204 | Display the version of \fBgrubby\fR being run and then exit immediately. |
205 | |
206 | .SS Output Format Options |
207 | |
208 | Sane default options for the current platform are compiled into grubby on |
209 | a per platform basis. These defaults determine the format and layout of |
210 | the generated bootloader configuration file. A different configuration file |
211 | format may be specified on the command line if the system uses a supported |
212 | alternative bootloader. |
213 | |
214 | .TP |
215 | \fB-\-elilo\fR |
216 | Use an \fBelilo\fR style configuration file. This is the default on ia64 platforms. This format is deprecated. |
217 | |
218 | .TP |
219 | \fB-\-extlinux\fR |
220 | Use an \fBextlinux\fR style configuration file. This format is deprecated. |
221 | |
222 | .TP |
223 | \fB-\-grub\fR |
224 | Use a \fBgrub\fR style configuration file. This is the default on ia32 platforms. |
225 | |
226 | .TP |
227 | \fB-\-grub2\fR |
228 | Use a \fBgrub2\fR style configuration file. This is the default on \fBx86_64\fR |
229 | architecture as well as the \fBppc64\fR and \fBppc64le\fR architectures |
230 | running on Power8 or later hardware. |
231 | |
232 | .TP |
233 | \fB-\-lilo\fR |
234 | Use a \fBlilo\fR style configuration file. |
235 | |
236 | .TP |
237 | \fB-\-silo\fR |
238 | Use a \fBsilo\fR style configuration file. This is the default on SPARC systems. This format is legacy, deprecated, and unsupported. |
239 | |
240 | .TP |
241 | \fB-\-yaboot\fR |
242 | Use a \fByaboot\fR style configuration file. This is the default for |
243 | the \fBppc\fR architecture on on Power7 and earlier hardware. |
244 | |
245 | .TP |
246 | \fB-\-zipl\fR |
247 | Use a \fBzipl\fR style configuration file. This is the default on the |
248 | legacy s390 and current s390x architectures. |
249 | |
250 | .SS Override Options |
251 | |
252 | .TP |
253 | \fB-\-bad-image-okay\fR |
254 | When \fBgrubby\fR is looking for a entry to use for something (such |
255 | as a template or a default boot entry) it uses sanity checks, such as |
256 | ensuring that the kernel exists in the filesystem, to make sure |
257 | entries that obviously won't work aren't selected. This option overrides |
258 | that behavior, and is designed primarily for testing. |
259 | |
260 | .TP |
261 | \fB-\-boot-filesystem\fR=\fIbootfs\fR |
262 | The \fBgrub\fR boot loader expects file paths listed in its configuration |
263 | path to be relative to the top of the filesystem they are on, rather then |
264 | relative to the current root filesystem. By default \fBgrubby\fR searches |
265 | the list of currently mounted filesystems to determine this. If this option |
266 | is given \fBgrubby\fR acts as if the specified filesystem was the filesystem |
267 | containing the kernel (this option is designed primarily for testing). |
268 | |
269 | .TP |
270 | \fB-\-env\fR=\fIpath\fR |
271 | Path for the file where grub environment data is stored. |
272 | |
273 | .TP |
274 | \fB-c\fR, \fB-\-config-file\fR=\fIpath\fR |
275 | Use \fIpath\fR as the configuration file rather then the default. |
276 | |
277 | .TP |
278 | \fB-o\fR, \fB-\-output-file\fR=\fIfile_path\fR |
279 | The destination path for the updated configuration file. Use "-" to |
280 | send it to stdout. |
281 | |
282 | .TP |
283 | \fB-\-devtree\fR=\fIfile_path\fR |
284 | Use \fIpath\fR for device tree path in place of the path of any devicetree |
285 | directive found in the template stanza. |
286 | |
287 | .TP |
288 | \fB-\-devtreedir\fR=\fIfile_path\fR |
289 | Use the specified \fIfile path\fR to load the devicetree definition. This is for |
290 | platforms where a flat file is used instead of firmware to instruct the kernel |
291 | how to communicate with devices. |
292 | |
293 | .SS Multiboot Options |
294 | |
295 | The Multiboot Specification provides a generic interface for boot |
296 | loaders and operating systems. It is supported by the GRUB bootloader. |
297 | |
298 | .TP |
299 | \fB-\-add-multiboot\fR=\fImultiboot-path\fR |
300 | Add a new boot entry for the multiboot kernel located at |
301 | \fImultiboot-path\fR. Note that this is generally accompanied with a |
302 | \fB--add-kernel\fR option. |
303 | |
304 | .TP |
305 | \fB-\-remove-multiboot\fR=\fImultiboot-path\fR |
306 | Removes all boot entries which match \fImultiboot-path\fR. |
307 | |
308 | .TP |
309 | \fB-\-mbargs\fR=\fImultiboot-args\fR |
310 | When a new multiboot kernel is added, this specifies the command line |
311 | arguments which should be passed to that kernel by default |
312 | When \fB-\-update-kernel\fR is used, this specifies new arguments to add |
313 | to the argument list. Multiple, space separated arguments may be used. If |
314 | an argument already exists the new value replaces the old values. |
315 | |
316 | .TP |
317 | \fB-\-remove-mbargs\fR=\fImultiboot-args\fR |
318 | The arguments specified by \fImultiboot-args\fR are removed from the |
319 | kernels specified by \fB-\-update-kernel\fR. |
320 | |
321 | .SH "BUGS" |
322 | |
323 | The command line syntax is more than a little baroque. This probably |
324 | won't be fixed as \fBgrubby\fR is only intended to be called from shell |
325 | scripts which can get it right. |
326 | |
327 | .SH EXAMPLE |
328 | |
329 | The following examples assume the following: |
330 | |
331 | .TS |
332 | allbox; |
333 | rbw15 l. |
334 | cfg_file Full path to bootloader config file |
335 | new_kernel Full path to kernel image to be installed |
336 | old_kernel Full path to old kernel image to be removed |
337 | current_kernel Full path to a currently installed kernel |
338 | entry_title Title that appears on bootloader menu |
339 | new_initrd Full path to initrd for a new kernel |
340 | kernel_args Set of arguments for the kernel |
341 | menu_index Index number of a menu entry |
342 | .TE |
343 | |
344 | The examples below quote strings that may have spaces or other whitespace in them. It is also |
345 | perfectly valid to backslash escape these strings if that is more convenient. |
346 | |
347 | .PP |
348 | Add a new kernel entry and copy all options from the current default kernel. This is the behavior |
349 | that most users will want. |
350 | .IP |
351 | \fBgrubby\fR --add-kernel=\fInew_kernel\fR --title="\fIentry_title\fR" --initrd="\fInew_initrd\fR" --copy-default |
352 | .PP |
353 | Add a new kernel entry with custom arguments |
354 | .IP |
355 | \fBgrubby\fR --add-kernel=\fInew_kernel\fR --title="\fIentry_title\fR" --initrd="\fInew_initrd\fR" --args=\fIkernel_args\fR |
356 | .PP |
357 | Remove \fBall menu entries\fR for a specified kernel. |
358 | .IP |
359 | \fBgrubby\fR --remove-kernel=\fIold_kernel\fR |
360 | .PP |
361 | Target a single menu entry to remove without targetting other entries with the same kernel. |
362 | .IP |
363 | \fBgrubby\fR --info=\fIold_kernel\fR |
364 | |
365 | \fBgrubby\fR --remove-kernel=\fImenu_index\fR |
366 | .PP |
367 | Update the arguments for all entries of a specific kernel. New arguments get added while existing arguments get updated values. |
368 | .IP |
369 | \fBgrubby\fR --update-kernel=\fIcurrent_kernel\fR --args="\fIkernel_args\fR" |
370 | .PP |
371 | Remove the arguments for a single entry of a specific kernel. |
372 | .IP |
373 | \fBgrubby\fR --info=\fIcurrent_kernel\fR |
374 | |
375 | \fBgrubby\fR --remove-args=\fImenu_index\fR --args="\fIkernel_args\fR" |
376 | |
377 | .SH "SEE ALSO" |
378 | |
379 | .BR grub (8), |
380 | .BR lilo (8), |
381 | .BR yaboot (8), |
382 | .BR zipl (8), |
383 | .BR dracut (8), |
384 | .BR mkinitrd (8) |
385 | |
386 | .SH AUTHORS |
387 | |
388 | .nf |
389 | Erik Troan |
390 | Jeremy Katz |
391 | Peter Jones |
392 | Robert Marshall |
393 | .fi |