code.delx.au - refind/blob - docs/man/refind-mkdefault.8

   1 .\" Copyright 2016 Roderick W. Smith (rodsmith@rodsbooks.com)
   2 .\" May be distributed under the GNU Free Documentation License version 1.3 or
   3 any later version
   4 .TH "REFIND-MKDEFAULT" "8" "0.10.3" "Roderick W. Smith" "rEFInd Manual"
   5 .SH "NAME"
   6 refind-mkdefault \- Set rEFInd as the default EFI boot option
   7 .SH "SYNOPSIS"
   8 .BI "refind-mkdefault "
   9 [ \-L|\-\-label <name> ]
  10
  11 .SH "DESCRIPTION"
  12
  13 EFI booting normally relies on boot manager entries stored in NVRAM, which
  14 describe the locations of EFI boot programs and the order in which the
  15 firmware will attempt to launch them. In Linux, these entries can be
  16 created, deleted, and manipulated with the \fIefibootmgr\fR utility.
  17
  18 Many OSes and Linux packages assume that they should control the boot
  19 process, and so both create NVRAM boot entries for themselves and set these
  20 entries first in the boot order. If you intend rEFInd to control the boot
  21 process, though, such changes are undesirable and require adjustment via
  22 \fIefibootmgr\fR. Such adjustments are annoying to make and can be
  23 intimidating to non-experts.
  24
  25 The \fIrefind-mkdefault\fR script simplifies matters: Running this script
  26 with no options sets rEFInd as the default boot program. The details of what
  27 the script does depends on the current state of the boot order list and
  28 existing boot entries:
  29
  30 .TP
  31 .B *
  32 If a rEFInd entry already exists in the boot order and is already first
  33 in the list, no changes are made.
  34
  35 .TP
  36 .B *
  37 If a rEFInd entry already exists in the boot order but is not first in
  38 the list, that entry is moved to the first position in the boot order.
  39
  40 .TP
  41 .B *
  42 If more than one rEFInd entry exists in the boot order,
  43 \fIrefind-mkdefault\fR moves the one that comes earliest to the front of the
  44 boot order list.
  45
  46 .TP
  47 .B *
  48 If no rEFInd entry exists in the boot order but a rEFInd boot entry
  49 can be found in the list of \fBBoot####\fR entries, it is added to the boot
  50 order and placed at the front of the list.
  51
  52 .TP
  53 .B *
  54 If multiple rEFInd boot entries exist but none is in the boot order, all the
  55 entries are added to the boot order, but which one is first is uncontrolled.
  56
  57 .PP
  58
  59 A rEFInd entry is defined as one that contains the string \fBrefind\fR
  60 (case-insensitive). This string could exist in the description or in the
  61 filename. The string used to define the rEFInd entry can be changed via the
  62 \fI\-\-label\fR (\fI\-L\fR) option.
  63
  64 The intent is that \fIrefind-mkdefault\fR can be called after booting via
  65 GRUB or some other means to restore rEFInd as the default boot program.  It
  66 can also be placed in a startup and/or shutdown script to restore rEFInd to
  67 its default position automatically. Because it does not re-write the boot
  68 order if rEFInd is listed as the first boot entry, this practice should be
  69 low in risk.
  70
  71 .SH "OPTIONS"
  72
  73 .TP
  74 .B \-L | \-\-label \fI<name>\fR
  75 Instead of searching for the string \fBrefind\fR in \fIefibootmgr\fR output
  76 as a way to identify rEFInd, search for the string \fBname\fR.
  77
  78 .SH "RETURN VALUES"
  79
  80 \fIrefind-mkdefault\fR returns the following values:
  81
  82 .TP
  83 .B 0
  84 The script completed successfully, which can mean either that no change was
  85 necessary or that the call to \fIefibootmgr\fR returned a success code.
  86
  87 .TP
  88 .B 1
  89 EFI boot order variables are available, and a rEFInd entry was found, but
  90 the call to \fIefibootmgr\fR returned a failure code.
  91
  92 .TP
  93 .B 2
  94 EFI boot entries are not available. This condition is often an indication of
  95 a buggy EFI or badly damaged NVRAM contents.
  96
  97 .TP
  98 .B 3
  99 No rEFInd entry could be found in the list of boot options, and so
 100 no changes were made to the boot order list.
 101
 102 .SH "LIMITATIONS"
 103
 104 .TP
 105 .B *
 106 \fIrefind-mkdefault\fR does not work when booted in BIOS mode (including
 107 via a Compatibility Support Module, or CSM, on an EFI-based computer).
 108 Similarly, it does not work if \fIefibootmgr\fR is not installed or fails
 109 to work for any reason.
 110
 111 .TP
 112 .B *
 113 The script uses a very simple algorithm to determine what to move to
 114 the start of the boot order list. This algorithm may fail if the system
 115 has redundant or non-functional rEFInd boot entries or if those entries
 116 are not named in an expected fashion. Cleaning up the boot entries by
 117 manual use of \fIefibootmgr\fR may be necessary in such cases.
 118
 119 .SH "AUTHORS"
 120 Primary author: Roderick W. Smith (rodsmith@rodsbooks.com)
 121
 122 .SH "SEE ALSO"
 123 \fBmvrefind (8)\fR,
 124 \fBmkrlconf (8)\fR,
 125 \fBrefind-install (8)\fR,
 126 \fBefibootmgr (8)\fR
 127
 128 \fIhttp://www.rodsbooks.com/refind/\fR
 129
 130 .SH "AVAILABILITY"
 131 The \fBrefind-mkdefault\fR command is part of the \fIrEFInd\fR package and is
 132 available from Roderick W. Smith.