/[grub]/grub/docs/grub.texi
ViewVC logotype

Diff of /grub/docs/grub.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.81 by jeroen, Tue Apr 27 21:32:28 2004 UTC revision 1.82 by okuji, Sun Jun 20 13:48:46 2004 UTC
# Line 27  Line 27 
27  * grub-terminfo: (grub)Invoking grub-terminfo.  Generate a terminfo  * grub-terminfo: (grub)Invoking grub-terminfo.  Generate a terminfo
28                                                  command from a                                                  command from a
29                                                  terminfo name                                                  terminfo name
30    * grub-set-default: (grub)Invoking grub-set-default.    Set a default boot
31                                                            entry
32  * mbchk: (grub)Invoking mbchk.  Check for the format of a Multiboot kernel  * mbchk: (grub)Invoking mbchk.  Check for the format of a Multiboot kernel
33  @end direntry  @end direntry
34    
# Line 113  This edition documents version @value{VE Line 115  This edition documents version @value{VE
115  * Invoking grub-install::       How to use the GRUB installer  * Invoking grub-install::       How to use the GRUB installer
116  * Invoking grub-md5-crypt::     How to generate a cryptic password  * Invoking grub-md5-crypt::     How to generate a cryptic password
117  * Invoking grub-terminfo::      How to generate a terminfo command  * Invoking grub-terminfo::      How to generate a terminfo command
118    * Invoking grub-set-default::   How to set a default boot entry
119  * Invoking mbchk::              How to use the Multiboot checker  * Invoking mbchk::              How to use the Multiboot checker
120  * Obtaining and Building GRUB:: How to obtain and build GRUB  * Obtaining and Building GRUB:: How to obtain and build GRUB
121  * Reporting bugs::              Where you should send a bug report  * Reporting bugs::              Where you should send a bug report
# Line 475  if, by any chance, your hard drive becom Line 478  if, by any chance, your hard drive becom
478  GRUB comes with boot images, which are normally put in the directory  GRUB comes with boot images, which are normally put in the directory
479  @file{/usr/share/grub/i386-pc}. If you do not use grub-install, then  @file{/usr/share/grub/i386-pc}. If you do not use grub-install, then
480  you need to copy the files @file{stage1}, @file{stage2}, and  you need to copy the files @file{stage1}, @file{stage2}, and
481  @file{*stage1_5} to the directory @file{/boot/grub}. Hereafter, the  @file{*stage1_5} to the directory @file{/boot/grub}, and run the
482  directory where GRUB images are initially placed (normally  @command{grub-set-default} (@pxref{Invoking grub-set-default}) if you
483  @file{/usr/share/grub/i386-pc}) will be called the @dfn{image  intend to use @samp{default saved} (@pxref{default}) in your
484  directory}, and the directory where the boot loader needs to find them  configuration file. Hereafter, the directory where GRUB images are
485  (usually @file{/boot/grub}) will be called the @dfn{boot directory}.  initially placed (normally @file{/usr/share/grub/i386-pc}) will be
486    called the @dfn{image directory}, and the directory where the boot
487    loader needs to find them (usually @file{/boot/grub}) will be called
488    the @dfn{boot directory}.
489    
490  @menu  @menu
491  * Creating a GRUB boot floppy::  * Creating a GRUB boot floppy::
# Line 734  magic. Line 740  magic.
740  @menu  @menu
741  * General boot methods::        How to boot OSes with GRUB generally  * General boot methods::        How to boot OSes with GRUB generally
742  * OS-specific notes::           Notes on some operating systems  * OS-specific notes::           Notes on some operating systems
743    * Making your system robust::   How to make your system robust
744  @end menu  @end menu
745    
746    
# Line 1068  grub> @kbd{boot} Line 1075  grub> @kbd{boot}
1075  @end example  @end example
1076    
1077    
1078    @node Making your system robust
1079    @section How to make your system robust
1080    
1081    When you test a new kernel or a new OS, it is important to make sure
1082    that your computer can boot even if the new system is unbootable. This
1083    is crucial especially if you maintain servers or remote systems. To
1084    accomplish this goal, you need to set up two things:
1085    
1086    @enumerate
1087    @item
1088    You must maintain a system which is always bootable. For instance, if
1089    you test a new kernel, you need to keep a working kernel in a
1090    different place. And, it would sometimes be very nice to even have a
1091    complete copy of a working system in a different partition or disk.
1092    
1093    @item
1094    You must direct GRUB to boot a working system when the new system
1095    fails. This is possible with the @dfn{fallback} system in GRUB.
1096    @end enumerate
1097    
1098    The former requirement is very specific to each OS, so this
1099    documentation does not cover that topic. It is better to consult some
1100    backup tools.
1101    
1102    So let's see the GRUB part. There are two possibilities: one of them
1103    is quite simple but not very robust, and the other is a bit complex to
1104    set up but probably the best solution to make sure that your system
1105    can start as long as GRUB itself is bootable.
1106    
1107    @menu
1108    * Booting once-only::
1109    * Booting fallback systems::
1110    @end menu
1111    
1112    
1113    @node Booting once-only
1114    @subsection Booting once-only
1115    
1116    You can teach GRUB to boot an entry only at next boot time. Suppose
1117    that your have an old kernel @file{old_kernel} and a new kernel
1118    @file{new_kernel}. You know that @file{old_kernel} can boot
1119    your system correctly, and you want to test @file{new_kernel}.
1120    
1121    To ensure that your system will go back to the old kernel even if the
1122    new kernel fails (e.g. it panics), you can specify that GRUB should
1123    try the new kernel only once and boot the old kernel after that.
1124    
1125    First, modify your configuration file. Here is an example:
1126    
1127    @group
1128    @example
1129    default saved        # This is important!!!
1130    timeout 10
1131    
1132    title the old kernel
1133    root (hd0,0)
1134    kernel /old_kernel
1135    savedefault
1136    
1137    title the new kernel
1138    root (hd0,0)
1139    kernel /new_kernel
1140    savedefault 0         # This is important!!!
1141    @end example
1142    @end group
1143    
1144    Note that this configuration file uses @samp{default saved}
1145    (@pxref{default}) at the head and @samp{savedefault 0}
1146    (@pxref{savedefault}) in the entry for the new kernel. This means
1147    that GRUB boots a saved entry by default, and booting the entry for the
1148    new kernel saves @samp{0} as the saved entry.
1149    
1150    With this configuration file, after all, GRUB always tries to boot the
1151    old kernel after it booted the new one, because @samp{0} is the entry
1152    of @code{the old kernel}.
1153    
1154    The next step is to tell GRUB to boot the new kernel at next boot
1155    time. For this, execute @command{grub-set-default} (@pxref{Invoking
1156    grub-set-default}):
1157    
1158    @example
1159    # @kbd{grub-set-default 1}
1160    @end example
1161    
1162    This command sets the saved entry to @samp{1}, that is, to the new
1163    kernel.
1164    
1165    This method is useful, but still not very robust, because GRUB stops
1166    booting, if there is any error in the boot entry, such that the new
1167    kernel has an invalid executable format. Thus, it it even better to
1168    use the @dfn{fallback} mechanism of GRUB. Look at next subsection for
1169    this feature.
1170    
1171    
1172    @node Booting fallback systems
1173    @subsection Booting fallback systems
1174    
1175    GRUB supports a fallback mechanism of booting one or more other
1176    entries if a default boot entry fails. You can specify multiple
1177    fallback entries if you wish.
1178    
1179    Suppose that you have three systems, @samp{A}, @samp{B} and
1180    @samp{C}. @samp{A} is a system which you want to boot by
1181    default. @samp{B} is a backup system which is supposed to boot
1182    safely. @samp{C} is another backup system which is used in case where
1183    @samp{B} is broken.
1184    
1185    Then you may want GRUB to boot the first system which is bootable
1186    among @samp{A}, @samp{B} and @samp{C}. A configuration file can be
1187    written in this way:
1188    
1189    @group
1190    @example
1191    default saved        # This is important!!!
1192    timeout 10
1193    fallback 1 2         # This is important!!!
1194    
1195    title A
1196    root (hd0,0)
1197    kernel /kernel
1198    savedefault fallback # This is important!!!
1199    
1200    title B
1201    root (hd1,0)
1202    kernel /kernel
1203    savedefault fallback # This is important!!!
1204    
1205    title C
1206    root (hd2,0)
1207    kernel /kernel
1208    savedefault
1209    @end example
1210    @end group
1211    
1212    Note that @samp{default saved} (@pxref{default}), @samp{fallback 1 2}
1213    and @samp{savedefault fallback} are used. GRUB will boot a saved entry
1214    by default and save a fallback entry as next boot entry with this
1215    configuration.
1216    
1217    When GRUB tries to boot @samp{A}, GRUB saves @samp{1} as next boot
1218    entry, because the command @command{fallback} specifies that @samp{1}
1219    is the first fallback entry. The entry @samp{1} is @samp{B}, so GRUB
1220    will try to boot @samp{B} at next boot time.
1221    
1222    Likewise, when GRUB tries to boot @samp{B}, GRUB saves @samp{2} as
1223    next boot entry, because @command{fallback} specifies @samp{2} as next
1224    fallback entry. This makes sure that GRUB will boot @samp{C} after
1225    booting @samp{B}.
1226    
1227    It is noteworthy that GRUB uses fallback entries both when GRUB
1228    itself fails in booting an entry and when @samp{A} or @samp{B} fails
1229    in starting up your system. So this solution ensures that your system
1230    is started even if GRUB cannot find your kernel or if your kernel
1231    panics.
1232    
1233    However, you need to run @command{grub-set-default} (@pxref{Invoking
1234    grub-set-default}) when @samp{A} starts correctly or you fix @samp{A}
1235    after it crashes, since GRUB always sets next boot entry to a fallback
1236    entry. You should run this command in a startup script such as
1237    @file{rc.local} to boot @samp{A} by default:
1238    
1239    @example
1240    # @kbd{grub-set-default 0}
1241    @end example
1242    
1243    where @samp{0} is the number of the boot entry for the system
1244    @samp{A}.
1245    
1246    If you want to see what is current default entry, you can look at the
1247    file @file{/boot/grub/default} (or @file{/grub/default} in
1248    some systems). Because this file is plain-text, you can just
1249    @command{cat} this file. But it is strongly recommended @strong{not to
1250    modify this file directly}, because GRUB may fail in saving a default
1251    entry in this file, if you change this file in an unintended
1252    manner. Therefore, you should use @command{grub-set-default} when you
1253    need to change the default entry.
1254    
1255    
1256  @node Configuration  @node Configuration
1257  @chapter Configuration  @chapter Configuration
1258    
# Line 1952  default entry is the entry saved with th Line 2137  default entry is the entry saved with th
2137  @node fallback  @node fallback
2138  @subsection fallback  @subsection fallback
2139    
2140  @deffn Command fallback num  @deffn Command fallback num...
2141  Go into unattended boot mode: if the default boot entry has any errors,  Go into unattended boot mode: if the default boot entry has any errors,
2142  instead of waiting for the user to do something, immediately start  instead of waiting for the user to do something, immediately start
2143  over using the @var{num} entry (same numbering as the @code{default}  over using the @var{num} entry (same numbering as the @code{default}
2144  command (@pxref{default})). This obviously won't help if the machine was  command (@pxref{default})). This obviously won't help if the machine was
2145  rebooted by a kernel that GRUB loaded.  rebooted by a kernel that GRUB loaded. You can specify multiple
2146    fallback entry numbers.
2147  @end deffn  @end deffn
2148    
2149    
# Line 2962  derived from attempting the mount will @ Line 3148  derived from attempting the mount will @
3148  @node savedefault  @node savedefault
3149  @subsection savedefault  @subsection savedefault
3150    
3151  @deffn Command savedefault  @deffn Command savedefault num
3152  Save the current menu entry as a default entry. Here is an example:  Save the current menu entry or @var{num} if specified as a default
3153    entry. Here is an example:
3154    
3155  @example  @example
3156  @group  @group
# Line 2984  savedefault Line 3171  savedefault
3171  @end example  @end example
3172    
3173  With this configuration, GRUB will choose the entry booted previously as  With this configuration, GRUB will choose the entry booted previously as
3174  the default entry. See also @ref{default}.  the default entry.
3175    
3176    You can specify @samp{fallback} instead of a number. Then, next
3177    fallback entry is saved. Next fallback entry is chosen from fallback
3178    entries. Normally, this will be the first entry in fallback ones.
3179    
3180    See also @ref{default} and @ref{Invoking grub-set-default}.
3181  @end deffn  @end deffn
3182    
3183    
# Line 3559  You must specify one argument to this co Line 3752  You must specify one argument to this co
3752  @end example  @end example
3753    
3754    
3755    @node Invoking grub-set-default
3756    @chapter Invoking grub-set-default
3757    
3758    The program @command{grub-set-default} sets the default boot entry for
3759    GRUB. This automatically creates a file named @file{default} under
3760    your GRUB directory (i.e. @file{/boot/grub}), if it is not
3761    present. This file is used to determine the default boot entry when
3762    GRUB boots up your system when you use @samp{default saved} in your
3763    configuration file (@pxref{default}), and to save next default boot
3764    entry when you use @samp{savedefault} in a boot entry
3765    (@pxref{savedefault}).
3766    
3767    @command{grub-set-default} accepts the following options:
3768    
3769    @table @option
3770    @item --help
3771    Print a summary of the command-line options and exit.
3772    
3773    @item --version
3774    Print the version information and exit.
3775    
3776    @item --root-directory=@var{dir}
3777    Use the directory @var{dir} instead of the root directory
3778    (i.e. @file{/}) to define the location of the default file. This
3779    is useful when you mount a disk which is used for another system.
3780    @end table
3781    
3782    You must specify a single argument to @command{grub-set-default}. This
3783    argument is normally the number of a default boot entry. For example,
3784    if you have this configuration file:
3785    
3786    @group
3787    @example
3788    default saved
3789    timeout 10
3790    
3791    title GNU/Hurd
3792    root (hd0,0)
3793    ...
3794    
3795    title GNU/Linux
3796    root (hd0,1)
3797    ...
3798    @end example
3799    @end group
3800    
3801    and if you want to set the next default boot entry to GNU/Linux, you
3802    may execute this command:
3803    
3804    @example
3805    @kbd{grub-set-default 1}
3806    @end example
3807    
3808    Because the entry for GNU/Linux is @samp{1}. Note that entries are
3809    counted from zero. So, if you want to specify GNU/Hurd here, then you
3810    should specify @samp{0}.
3811    
3812    This feature is very useful if you want to test a new kernel or to
3813    make your system quite robust. @xref{Making your system robust}, for
3814    more hints about how to set up a robust system.
3815    
3816    
3817  @node Invoking mbchk  @node Invoking mbchk
3818  @chapter Invoking mbchk  @chapter Invoking mbchk
3819    
# Line 3695  Once we get your report, we will try to Line 3950  Once we get your report, we will try to
3950  @node Future  @node Future
3951  @chapter Where GRUB will go  @chapter Where GRUB will go
3952    
3953  Here are some ideas of what might happen in the future:  We started the next generation of GRUB, GRUB 2. This will include
3954    internationalization, dynamic module loading, real memory management,
3955  @itemize @bullet  multiple architecture support, a scripting language, and many other
3956  @item  nice feature. If you are interested in the development of GRUB 2, take
3957  Support dynamic loading.  a look at @uref{http://www.gnu.org/software/grub/grub.html, the
3958    homepage}.
 @item  
 Add real memory management.  
   
 @item  
 Add a real scripting language.  
   
 @item  
 Support internationalization.  
   
 @item  
 Support other architectures than i386-pc.  
 @end itemize  
   
 See the file @file{TODO} in the source distribution, for more  
 information.  
3959    
3960    
3961  @c Separate the programming guide.  @c Separate the programming guide.

Legend:
Removed from v.1.81  
changed lines
  Added in v.1.82

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26