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