370 lines
14 KiB
Diff
370 lines
14 KiB
Diff
From e08236e8d15ff0fc581d56efaf4d855c57d6d994 Mon Sep 17 00:00:00 2001
|
|
From: Robert Marshall <rmarshall@redhat.com>
|
|
Date: Fri, 1 Jul 2016 15:03:13 -0400
|
|
Subject: [PATCH 26/55] Update grubby man page contents (#bz1232168)
|
|
|
|
The grubby man page was missing several options that were added in
|
|
previous releases. Added those to the man page as well as updated the
|
|
text on others to provide further clarity.
|
|
|
|
Added an EXAMPLE section containing some basic use cases.
|
|
|
|
Resolves: rhbz#1232168
|
|
---
|
|
grubby.8 | 218 +++++++++++++++++++++++++++++++++++++++++++------------
|
|
1 file changed, 173 insertions(+), 45 deletions(-)
|
|
|
|
diff --git a/grubby.8 b/grubby.8
|
|
index a3033d87254..64a6984fba0 100644
|
|
--- a/grubby.8
|
|
+++ b/grubby.8
|
|
@@ -2,51 +2,69 @@
|
|
|
|
.SH NAME
|
|
|
|
-grubby \- command line tool for configuring grub, lilo, elilo, yaboot and zipl
|
|
+grubby \- command line tool used to configure bootloader menu entries across multiple architectures
|
|
|
|
.SH SYNOPSIS
|
|
|
|
-\fBgrubby\fR [--add-kernel=\fIkernel-path\fR] [--args=\fIargs\fR]
|
|
- [--bad-image-okay] [--boot-filesystem=\fIbootfs\fR]
|
|
- [--bootloader-probe] [--config-file \fIpath\fR] [--copy-default]
|
|
- [--debug] [--default-kernel] [--default-index] [--default-title]
|
|
- [--devtree=\fIdevicetree.dtb\fR] [--set-index=\fIentry-index\fR]
|
|
- [--grub] [--lilo] [--yaboot] [--silo] [--zipl]
|
|
- [--info=\fIkernel-path\fR] [--initrd=\fIinitrd-path\fR]
|
|
- [--make-default] [-o path] [--version]
|
|
- [--remove-kernel=\fIkernel-path\fR] [--remove-args=\fIargs\fR]
|
|
- [--set-default=\fIkernel-path\fR] [--set-default-index=\fIentry-index\fR]
|
|
- [--title=entry-title] [--add-multiboot=\fImultiboot-path\fR]
|
|
- [--mbargs=\fIargs\fR] [--remove-multiboot=\fImultiboot-path\fR]
|
|
- [--remove-mbargs=\fIargs\fR]
|
|
+\fBgrubby\fR [\fIOPTIONS...\fR]
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.SS General Information
|
|
|
|
\fBgrubby\fR is a command line tool for updating and displaying information
|
|
-about the configuration files for the \fBgrub\fR, \fBlilo\fR, \fBelilo\fR
|
|
-(ia64), \fByaboot\fR (powerpc) and \fBzipl\fR (s390) boot loaders. It
|
|
-is primarily designed to be used from scripts which install new
|
|
-kernels and need to find information about the current boot environment.
|
|
+about the configuration files for various architecture specific bootloaders.
|
|
+It is primarily designed to be used from scripts which install new kernels
|
|
+and need to find information about the current boot environment.
|
|
|
|
.SS Architecture Support
|
|
|
|
-On BIOS-based Intel x86 platforms, \fBgrub2\fR is the default bootloader and
|
|
-the configuration file is in \fB/boot/grub2/grub.cfg\fR. On UEFI-based Intel
|
|
-x86 platforms, \fBgrub2\fR is the default bootloader, and the configuration
|
|
-file is in \fB/boot/efi/EFI/redhat/grub.cfg\fR. On Intel ia64 platforms,
|
|
-\fBelilo\fR mode is used and the default location for the configuration file
|
|
-is \fB/boot/efi/EFI/redhat/elilo.conf\fR. On PowerPC platforms, systems based
|
|
-on Power8 now support \fBgrub2\fR as a bootloader and store using a default
|
|
-config stored in \fB/boot/grub2/grub.cfg\fR. The earlier Power7 systems use \fByaboot\fR
|
|
-parsing and the configuration file should be in \fB/etc/yaboot.conf\fR. On
|
|
-s390 platforms the \fBzipl bootloader\fR will read from \fB/etc/zipl.conf\fR.
|
|
+The \fBgrubby\fR executable has full support for the \fBgrub2\fR
|
|
+bootloader on \fBx86_64\fR systems using legacy BIOS or modern
|
|
+UEFI firmware and \fBppc64\fR and \fBppc64le\fR hardware using
|
|
+OPAL or SLOF as firmware.
|
|
+
|
|
+Legacy \fBs390\fR and the current \fBs390x\fR architectures
|
|
+and their \fBzipl\fR bootloader are fully supported.
|
|
+
|
|
+Support for \fByaboot\fR has been deprecated as all ppc architecture
|
|
+hardware since the Power8 system uses \fBgrub2\fR or petitboot
|
|
+which both use the grub2 configuration file format.
|
|
+
|
|
+Legacy bootloaders \fBLILO\fR, \fBSILO\fR, and \fBELILO\fR
|
|
+are deprecated in favor of previously mentioned bootloaders. The
|
|
+\fBSILO\fR bootloader should also be considered unsupported.
|
|
+
|
|
+.SS Default Behavior
|
|
+
|
|
+The default architecture is chosen at compile time. The grubby executable
|
|
+has a series of built in assumptions about what bootloader is being used and
|
|
+where its configuration file lives. If no output format option is specified
|
|
+on the command line then grubby will use these default settings to first
|
|
+search for an existing configuration and, if it is not found, assume that
|
|
+it should be placed in the standard location. These default assumptions are
|
|
+listed in the table below.
|
|
+
|
|
+.TS
|
|
+allbox;
|
|
+lbw6 lbw10 lbw18
|
|
+l l l.
|
|
+ Arch Bootloader Configuration File
|
|
+ x86_64 [BIOS] grub2 /boot/grub2/grub.cfg
|
|
+ x86_64 [UEFI] grub2 /boot/efi/EFI/redhat/grub.cfg
|
|
+ i386 grub2 /boot/grub2/grub.cfg
|
|
+ ia64 elilo /boot/efi/EFI/redhat/elilo.conf
|
|
+ ppc [>=Power8] grub2 /boot/grub2/grub.cfg
|
|
+ ppc [<=Power7] yaboot /etc/yaboot.conf
|
|
+ s390 zipl /etc/zipl.conf
|
|
+ s390x zipl /etc/zipl.conf
|
|
+.TE
|
|
+
|
|
|
|
.SS Special Arguments
|
|
|
|
There are a number of ways to specify the kernel used for \fB-\-info\fR,
|
|
-\fB-\-remove-kernel\fR, and \fB-\-update-kernel\fR. Specificying \fBDEFAULT\fR
|
|
+\fB-\-remove-kernel\fR, and \fB-\-update-kernel\fR. Specifying \fBDEFAULT\fR
|
|
or \fBALL\fR selects the default entry and all of the entries, respectively.
|
|
If a comma separated list of numbers is given, the boot entries indexed
|
|
by those numbers are selected. Finally, the title of a boot entry may
|
|
@@ -59,12 +77,17 @@ with that title are used.
|
|
|
|
.TP
|
|
\fB-\-add-kernel\fR=\fIkernel-path\fR
|
|
-Add a new boot entry for the kernel located at \fIkernel-path\fR.
|
|
+Add a new boot entry for the kernel located at \fIkernel-path\fR. A title for
|
|
+the boot entry must be set using \fB-\-title\fR. Most invocations should also
|
|
+include \fB-\-initrd\fR with memtest86 as a notable exception.
|
|
+
|
|
+The \fB-\-update-kernel\fR
|
|
+option may not be used in the same invocation.
|
|
|
|
.TP
|
|
\fB-\-remove-kernel\fR=\fIkernel-path\fR
|
|
Removes all boot entries which match \fIkernel-path\fR. This may be used
|
|
-along with -\-add-kernel, in which case the new kernel being added will
|
|
+along with \fB-\-add-kernel\fR, in which case the new kernel being added will
|
|
never be removed.
|
|
|
|
.TP
|
|
@@ -110,14 +133,19 @@ the title is shortened to a (unique) entry.
|
|
Use \fIinitrd-path\fR as the path to an initial ram disk for a new kernel
|
|
being added.
|
|
|
|
+.TP
|
|
+\fB-\-efi\fR
|
|
+Use linuxefi and initrdefi when constructing bootloader stanzas instead of linux and initrd.
|
|
+
|
|
.TP
|
|
\fB-\-set-default\fR=\fIkernel-path\fR
|
|
The first entry which boots the specified kernel is made the default
|
|
-boot entry.
|
|
+boot entry. This may not be invoked with \fB-\-set-default-index\fR.
|
|
|
|
.TP
|
|
\fB-\-set-default-index\fR=\fIentry-index\fR
|
|
-Makes the given entry number the default boot entry.
|
|
+Makes the given entry number the default boot entry. This may not
|
|
+be invoked with \fB-\-set-default\fR.
|
|
|
|
.TP
|
|
\fB-\-make-default\fR
|
|
@@ -131,8 +159,17 @@ Set the position at which to add a new entry created with \fB-\-add-kernel\fR.
|
|
\fB-\-debug\fR
|
|
Display extra debugging information for failures.
|
|
|
|
+.TP
|
|
+\fB-i\fR, \fB-\-extra-initrd\fR=\fIinitrd-path\fR
|
|
+Use \fIinitrd-path\fR as the path for an auxiliary initrd image.
|
|
+
|
|
.SS Display Options
|
|
|
|
+Passing the display option to grubby will cause it to print out the
|
|
+requested information about the current bootloader configuration and
|
|
+then immediately exit. These options should not be used in any
|
|
+script intended to update the bootloader configuration.
|
|
+
|
|
.TP
|
|
\fB-\-default-kernel\fR
|
|
Display the full path to the current default kernel and exit.
|
|
@@ -159,34 +196,56 @@ for \fBgrub\fR requires a commented out boot directive \fBgrub.conf\fR
|
|
identical to the standard directive in the lilo configuration file. If this
|
|
is not present \fBgrubby\fR will assume grub is not installed (note
|
|
that \fBanaconda\fR places this directive in \fBgrub.conf\fR files it creates).
|
|
-This option is only available on ia32 platforms.
|
|
+
|
|
+\fIThis option is only available on i386 platforms.\fR
|
|
|
|
.TP
|
|
-\fB-\-version\fR
|
|
+\fB-v\fR, \fB-\-version\fR
|
|
Display the version of \fBgrubby\fR being run and then exit immediately.
|
|
|
|
.SS Output Format Options
|
|
|
|
+Sane default options for the current platform are compiled into grubby on
|
|
+a per platform basis. These defaults determine the format and layout of
|
|
+the generated bootloader configuration file. A different configuration file
|
|
+format may be specified on the command line if the system uses a supported
|
|
+alternative bootloader.
|
|
+
|
|
.TP
|
|
\fB-\-elilo\fR
|
|
-Use an \fBelilo\fR style configuration file.
|
|
+Use an \fBelilo\fR style configuration file. This is the default on ia64 platforms. This format is deprecated.
|
|
+
|
|
+.TP
|
|
+\fB-\-extlinux\fR
|
|
+Use an \fBextlinux\fR style configuration file. This format is deprecated.
|
|
|
|
.TP
|
|
\fB-\-grub\fR
|
|
-Use a \fBgrub\fR style configuration file instead of \fBlilo\fR style. This
|
|
-is the default on ia32 platforms.
|
|
+Use a \fBgrub\fR style configuration file. This is the default on ia32 platforms.
|
|
+
|
|
+.TP
|
|
+\fB-\-grub2\fR
|
|
+Use a \fBgrub2\fR style configuration file. This is the default on \fBx86_64\fR
|
|
+architecture as well as the \fBppc64\fR and \fBppc64le\fR architectures
|
|
+running on Power8 or later hardware.
|
|
|
|
.TP
|
|
\fB-\-lilo\fR
|
|
Use a \fBlilo\fR style configuration file.
|
|
|
|
+.TP
|
|
+\fB-\-silo\fR
|
|
+Use a \fBsilo\fR style configuration file. This is the default on SPARC systems. This format is legacy, deprecated, and unsupported.
|
|
+
|
|
.TP
|
|
\fB-\-yaboot\fR
|
|
-Use an \fByaboot\fR style configuration file.
|
|
+Use a \fByaboot\fR style configuration file. This is the default for
|
|
+the \fBppc\fR architecture on on Power7 and earlier hardware.
|
|
|
|
.TP
|
|
\fB-\-zipl\fR
|
|
-Use an \fBzipl\fR style configuration file.
|
|
+Use a \fBzipl\fR style configuration file. This is the default on the
|
|
+legacy s390 and current s390x architectures.
|
|
|
|
.SS Override Options
|
|
|
|
@@ -200,7 +259,7 @@ that behavior, and is designed primarily for testing.
|
|
|
|
.TP
|
|
\fB-\-boot-filesystem\fR=\fIbootfs\fR
|
|
-The \fBgrub\fR boot loader expects file paths listed in it's configuration
|
|
+The \fBgrub\fR boot loader expects file paths listed in its configuration
|
|
path to be relative to the top of the filesystem they are on, rather then
|
|
relative to the current root filesystem. By default \fBgrubby\fR searches
|
|
the list of currently mounted filesystems to determine this. If this option
|
|
@@ -208,23 +267,39 @@ is given \fBgrubby\fR acts as if the specified filesystem was the filesystem
|
|
containing the kernel (this option is designed primarily for testing).
|
|
|
|
.TP
|
|
-\fB-\-config-file\fR=\fIpath\fR
|
|
+\fB-\-env\fR=\fIpath\fR
|
|
+Path for the file where grub environment data is stored.
|
|
+
|
|
+.TP
|
|
+\fB-c\fR, \fB-\-config-file\fR=\fIpath\fR
|
|
Use \fIpath\fR as the configuration file rather then the default.
|
|
|
|
-\fB-\-devtree\fR=\fIpath\fR
|
|
+.TP
|
|
+\fB-o\fR, \fB-\-output-file\fR=\fIfile_path\fR
|
|
+The destination path for the updated configuration file. Use "-" to
|
|
+send it to stdout.
|
|
+
|
|
+.TP
|
|
+\fB-\-devtree\fR=\fIfile_path\fR
|
|
Use \fIpath\fR for device tree path in place of the path of any devicetree
|
|
directive found in the template stanza.
|
|
|
|
+.TP
|
|
+\fB-\-devtreedir\fR=\fIfile_path\fR
|
|
+Use the specified \fIfile path\fR to load the devicetree definition. This is for
|
|
+platforms where a flat file is used instead of firmware to instruct the kernel
|
|
+how to communicate with devices.
|
|
+
|
|
.SS Multiboot Options
|
|
|
|
-The Multiboot Specification provides a genreic interface for boot
|
|
+The Multiboot Specification provides a generic interface for boot
|
|
loaders and operating systems. It is supported by the GRUB bootloader.
|
|
|
|
.TP
|
|
\fB-\-add-multiboot\fR=\fImultiboot-path\fR
|
|
Add a new boot entry for the multiboot kernel located at
|
|
\fImultiboot-path\fR. Note that this is generally accompanied with a
|
|
-\fI--add-kernel\fR option.
|
|
+\fB--add-kernel\fR option.
|
|
|
|
.TP
|
|
\fB-\-remove-multiboot\fR=\fImultiboot-path\fR
|
|
@@ -249,11 +324,63 @@ The command line syntax is more than a little baroque. This probably
|
|
won't be fixed as \fBgrubby\fR is only intended to be called from shell
|
|
scripts which can get it right.
|
|
|
|
+.SH EXAMPLE
|
|
+
|
|
+The following examples assume the following:
|
|
+
|
|
+.TS
|
|
+allbox;
|
|
+rbw15 l.
|
|
+cfg_file Full path to bootloader config file
|
|
+new_kernel Full path to kernel image to be installed
|
|
+old_kernel Full path to old kernel image to be removed
|
|
+current_kernel Full path to a currently installed kernel
|
|
+entry_title Title that appears on bootloader menu
|
|
+new_initrd Full path to initrd for a new kernel
|
|
+kernel_args Set of arguments for the kernel
|
|
+menu_index Index number of a menu entry
|
|
+.TE
|
|
+
|
|
+The examples below quote strings that may have spaces or other whitespace in them. It is also
|
|
+perfectly valid to backslash escape these strings if that is more convenient.
|
|
+
|
|
+.PP
|
|
+Add a new kernel entry and copy all options from the current default kernel. This is the behavior
|
|
+that most users will want.
|
|
+.IP
|
|
+\fBgrubby\fR --add-kernel=\fInew_kernel\fR --title="\fIentry_title\fR" --initrd="\fInew_initrd\fR" --copy-default
|
|
+.PP
|
|
+Add a new kernel entry with custom arguments
|
|
+.IP
|
|
+\fBgrubby\fR --add-kernel=\fInew_kernel\fR --title="\fIentry_title\fR" --initrd="\fInew_initrd\fR" --args=\fIkernel_args\fR
|
|
+.PP
|
|
+Remove \fBall menu entries\fR for a specified kernel.
|
|
+.IP
|
|
+\fBgrubby\fR --remove-kernel=\fIold_kernel\fR
|
|
+.PP
|
|
+Target a single menu entry to remove without targetting other entries with the same kernel.
|
|
+.IP
|
|
+\fBgrubby\fR --info=\fIold_kernel\fR
|
|
+
|
|
+\fBgrubby\fR --remove-kernel=\fImenu_index\fR
|
|
+.PP
|
|
+Update the arguments for all entries of a specific kernel. New arguments get added while existing arguments get updated values.
|
|
+.IP
|
|
+\fBgrubby\fR --update-kernel=\fIcurrent_kernel\fR --args="\fIkernel_args\fR"
|
|
+.PP
|
|
+Remove the arguments for a single entry of a specific kernel.
|
|
+.IP
|
|
+\fBgrubby\fR --info=\fIcurrent_kernel\fR
|
|
+
|
|
+\fBgrubby\fR --remove-args=\fImenu_index\fR --args="\fIkernel_args\fR"
|
|
+
|
|
.SH "SEE ALSO"
|
|
|
|
.BR grub (8),
|
|
.BR lilo (8),
|
|
.BR yaboot (8),
|
|
+.BR zipl (8),
|
|
+.BR dracut (8),
|
|
.BR mkinitrd (8)
|
|
|
|
.SH AUTHORS
|
|
@@ -262,4 +389,5 @@ scripts which can get it right.
|
|
Erik Troan
|
|
Jeremy Katz
|
|
Peter Jones
|
|
+Robert Marshall
|
|
.fi
|
|
--
|
|
2.17.1
|
|
|