--- trunk/grubby/grubby.8 2016/06/29 15:00:53 2967 +++ trunk/grubby/grubby.8 2017/06/27 14:33:29 3013 @@ -1,42 +1,70 @@ .TH GRUBBY 8 "Tue Jan 18 2005" + .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] - [--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. - -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. +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 + +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 @@ -44,9 +72,29 @@ with that title are used. .SH OPTIONS + +.SS Basic Options + .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 \fB-\-add-kernel\fR, in which case the new kernel being added will +never be removed. + +.TP +\fB-\-update-kernel\fR=\fIkernel-path\fR +The entries for kernels matching \fRkernel-path\fR are updated. Currently +the only items that can be updated is the kernel argument list, which is +modified via the \fB-\-args\fR and \fB-\-remove-args\fR options. .TP \fB-\-args\fR=\fIkernel-args\fR @@ -61,50 +109,68 @@ lilo.conf does). .TP -\fB-\-bad-image-okay\fR -When \fBgrubby\fR is looking for a entry to use for something (such -as a template or a default boot entry) it uses sanity checks, such as -ensuring that the kernel exists in the filesystem, to make sure -entries that obviously won't work aren't selected. This option overrides -that behavior, and is designed primarily for testing. +\fB-\-remove-args\fR=\fIkernel-args\fR +The arguments specified by \fIkernel-args\fR are removed from the +kernels specified by \fB-\-update-kernel\fR. The \fBroot\fR argument +gets special handling for configuration files that support separate root +filesystem configuration. .TP -\fB-\-boot-filesystem\fR=\fIbootfs\fR -The \fBgrub\fR boot loader expects file paths listed in it's 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 -is given \fBgrubby\fR acts as if the specified filesystem was the filesystem -containing the kernel (this option is designed primarily for testing). +\fB-\-copy-default\fR +\fBgrubby\fR will copy as much information (such as kernel arguments and +root device) as possible from the current default kernel. The kernel path +and initrd path will never be copied. .TP -\fB-\-bootloader-probe\fR -\fBgrubby\fR tries to determine if \fBgrub\fR or \fBlilo\fR is currently -installed. When one of those bootloaders is found the name of that bootloader -is displayed on stdout. Both could be installed (on different devices), and -grubby will print out the names of both bootloaders, one per line. The probe -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. +\fB-\-title\fR=\fIentry-title\fR +When a new kernel entry is added \fIentry-title\fR is used as the title +(\fBlilo\fR label) for the entry. If \fIentry-title\fR is longer then maximum +length allowed by the bootloader (15 for lilo, unlimited for grub and elilo) +the title is shortened to a (unique) entry. +.TP +\fB-\-initrd\fR=\fIinitrd-path\fR +Use \fIinitrd-path\fR as the path to an initial ram disk for a new kernel +being added. .TP -\fB-\-config-file\fR=\fIpath\fR -Use \fIpath\fR as the configuration file rather then the default. +\fB-\-efi\fR +Use linuxefi and initrdefi when constructing bootloader stanzas instead of linux and initrd. .TP -\fB-\-copy-default\fR -\fBgrubby\fR will copy as much information (such as kernel arguments and -root device) as possible from the current default kernel. The kernel path -and initrd path will never be copied. +\fB-\-set-default\fR=\fIkernel-path\fR +The first entry which boots the specified kernel is made the default +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. This may not +be invoked with \fB-\-set-default\fR. + +.TP +\fB-\-make-default\fR +Make the new kernel entry being added the default entry. + +.TP +\fB-\-set-index\fR=\fIentry-index\fR +Set the position at which to add a new entry created with \fB-\-add-kernel\fR. .TP \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. @@ -117,125 +183,211 @@ Display the title of the current default boot entry and exit. .TP -\fB-\-devtree\fR=\fIpath\fR -Use \fIpath\fR for device tree path in place of the path of any devicetree -directive found in the template stanza. +\fB-\-info\fR=\fIkernel-path\fR +Display information on all boot entries which match \fIkernel-path\fR. I + +.TP +\fB-\-bootloader-probe\fR +\fBgrubby\fR tries to determine if \fBgrub\fR or \fBlilo\fR is currently +installed. When one of those bootloaders is found the name of that bootloader +is displayed on stdout. Both could be installed (on different devices), and +grubby will print out the names of both bootloaders, one per line. The probe +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). + +\fIThis option is only available on i386 platforms.\fR + +.TP +\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-\-grub\fR -Use a \fBgrub\fR style configuration file instead of \fBlilo\fR style. This -is the default on ia32 platforms. +\fB-\-extlinux\fR +Use an \fBextlinux\fR style configuration file. This format is deprecated. .TP -\fB-\-info\fR=\fIkernel-path\fR -Display information on all boot entries which match \fIkernel-path\fR. I +\fB-\-grub\fR +Use a \fBgrub\fR style configuration file. This is the default on ia32 platforms. .TP -\fB-\-initrd\fR=\fIinitrd-path\fR -Use \fIinitrd-path\fR as the path to an initial ram disk for a new kernel -being added. +\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-\-make-default\fR -Make the new kernel entry being added the default entry. +\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-\-remove-args\fR=\fIkernel-args\fR -The arguments specified by \fIkernel-args\fR are removed from the -kernels specified by \fB-\-update-kernel\fR. The \fBroot\fR argument -gets special handling for configuration files that support separate root -filesystem configuration. +\fB-\-yaboot\fR +Use a \fByaboot\fR style configuration file. This is the default for +the \fBppc\fR architecture on on Power7 and earlier hardware. .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 -never be removed. +\fB-\-zipl\fR +Use a \fBzipl\fR style configuration file. This is the default on the +legacy s390 and current s390x architectures. + +.SS Override Options .TP -\fB-\-set-default\fR=\fIkernel-path\fR -The first entry which boots the specified kernel is made the default -boot entry. +\fB-\-bad-image-okay\fR +When \fBgrubby\fR is looking for a entry to use for something (such +as a template or a default boot entry) it uses sanity checks, such as +ensuring that the kernel exists in the filesystem, to make sure +entries that obviously won't work aren't selected. This option overrides +that behavior, and is designed primarily for testing. .TP -\fB-\-set-default-index\fR=\fIentry-index\fR -Makes the given entry number the default boot entry. +\fB-\-boot-filesystem\fR=\fIbootfs\fR +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 +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-\-title\fR=\fIentry-title\fR -When a new kernel entry is added \fIentry-title\fR is used as the title -(\fBlilo\fR label) for the entry. If \fIentry-title\fR is longer then maximum -length allowed by the bootloader (15 for lilo, unlimited for grub and elilo) -the title is shortened to a (unique) entry. +\fB-\-env\fR=\fIpath\fR +Path for the file where grub environment data is stored. .TP -\fB-\-update-kernel\fR=\fIkernel-path\fR -The entries for kernels matching \fRkernel-path\fR are updated. Currently -the only items that can be updated is the kernel argument list, which is -modified via the \fB-\-args\fR and \fB-\-remove-args\fR options. +\fB-c\fR, \fB-\-config-file\fR=\fIpath\fR +Use \fIpath\fR as the configuration file rather then the default. .TP -\fB-\-version\fR -Display the version of \fBgrubby\fR being run and then exit immediately. +\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-\-yaboot\fR -Use an \fByaboot\fR style configuration file. +\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-\-zipl\fR -Use an \fBzipl\fR style configuration file. +\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. -.SH MULTIBOOT OPTIONS -The Multiboot Specification provides a genreic interface for boot +.SS Multiboot Options + +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 -Removes all boot entries which match \fImultiboot-path\fR. +Removes all boot entries which match \fImultiboot-path\fR. .TP \fB-\-mbargs\fR=\fImultiboot-args\fR -When a new multiboot kernel is added, this specifies the command line -arguments which should be passed to that kernel by default +When a new multiboot kernel is added, this specifies the command line +arguments which should be passed to that kernel by default When \fB-\-update-kernel\fR is used, this specifies new arguments to add to the argument list. Multiple, space separated arguments may be used. If -an argument already exists the new value replaces the old values. +an argument already exists the new value replaces the old values. .TP \fB-\-remove-mbargs\fR=\fImultiboot-args\fR -The arguments specified by \fImultiboot-args\fR are removed from the -kernels specified by \fB-\-update-kernel\fR. - +The arguments specified by \fImultiboot-args\fR are removed from the +kernels specified by \fB-\-update-kernel\fR. .SH "BUGS" + 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 + .nf Erik Troan Jeremy Katz Peter Jones +Robert Marshall .fi