1.\" Copyright (c) 2011-2013 Devin Teske 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd August 6, 2013 28.Dt MENU.4TH 8 29.Os 30.Sh NAME 31.Nm menu.4th 32.Nd FreeBSD dynamic menu boot module 33.Sh DESCRIPTION 34The file that goes by the name of 35.Nm 36is a set of commands designed to display a dynamic menu system managed through 37a system of carefully named environment variables. 38The commands of 39.Nm 40by themselves are not enough for most uses. 41Please refer to the 42examples below for the most common situations, and to 43.Xr loader 8 44for additional commands. 45.Pp 46Before using any of the commands provided in 47.Nm , 48it must be included 49through the command: 50.Pp 51.Dl include menu.4th 52.Pp 53This line is present in the default 54.Pa /boot/menu.rc 55file, so it is not needed (and should not be re-issued) in a normal setup. 56.Pp 57The commands provided by it are: 58.Pp 59.Bl -tag -width disable-module_module -compact -offset indent 60.It Ic menu-init 61Draws the menu bounding box and initializes some internal state variables. 62This should be called before any other menu-related functions. 63.It Ic menu-display 64Displays the menu (configured via the below documented environment variables) 65and blocks on keyboard input, awaiting user action. 66.It Ic menu-erase 67Clears the screen area within the menu bounding box. 68.It Ic menu-redraw 69Calls 70.Ic menu-erase 71and then redraws the menu. 72.It Ic menu-unset 73Unsets the environment variables associated with individual menu items, 74clearing the way for a new menu. 75.It Ic menu-clear 76Calls 77.Ic menu-unset 78and then 79.Ic menu-erase . 80.El 81.Pp 82The environment variables that effect its behavior are: 83.Bl -tag -width bootfile -offset indent 84.It Va loader_color 85If set to 86.Dq Li NO 87(case-insensitive) or 88.Dq Li 0 , 89causes the menu to be displayed without color. 90The default is to use ANSI coloring whenever possible. 91If serial boot is enabled, color is disabled by default. 92Color features include the use of ANSI bold for numbers appearing to the left 93of menuitems and the use of special 94.Dq Li ansi 95variables described below. 96.It Va autoboot_delay 97Number of seconds 98.Ic menu-display 99will wait before executing 100.Va menu_timeout_command 101.Ic ( boot 102by default) unless a key is pressed. 103If set to 104.Dq Li NO 105(case-insensitive) 106.Ic menu-display 107will wait for user input and never execute 108.Ic menu_timeout_command . 109If set to 110.Dq Li -1 , 111.Ic menu-display 112will boot immediately, preventing both interruption of the 113.Ic autoboot 114process and escaping to the loader prompt. 115Default is 116.Dq Li 10 . 117See 118.Xr loader 8 119for additional information. 120.It Va menu_timeout_command 121The command to be executed after 122.Va autoboot_delay 123seconds if a key is not pressed. 124The default is 125.Ic boot . 126.It Va loader_menu_frame 127Sets the desired box style to draw around the boot menu. 128Possible values are: 129.Dq Li single 130.Pq the default , 131.Dq Li double , 132and 133.Dq Li none . 134.It Va loader_menu_timeout_x 135Sets the desired column position of the timeout countdown text. 136Default is 4. 137.It Va loader_menu_timeout_y 138Sets the desired row position of the timeout countdown text. 139Default is 23. 140.It Va loader_menu_title 141The text to display above the menu. 142Default is 143.Dq Li "Welcome to FreeBSD" . 144.It Va loader_menu_title_align 145Default is to align 146.Ic loader_menu_title 147centered above the menu. This can be set to 148.Dq Li left 149or 150.Dq Li right 151to instead display the title left-or-right justified 152.Pq respectively . 153.It Va loader_menu_x 154Sets the desired column position of the boot menu. 155Default is 5. 156.It Va loader_menu_y 157Sets the desired row position of the boot menu. 158Default is 10. 159.It Va menu_caption[x] 160The text to be displayed for the numbered menuitem 161.Dq Li x . 162.It Va menu_command[x] 163The command to be executed when the number associated with menuitem 164.Dq Li x 165is pressed. 166See the list of included FICL words below for some ideas. 167.It Va menu_keycode[x] 168An optional decimal ASCII keycode to be associated with menuitem 169.Dq Li x . 170When pressed, will cause the execution of 171.Va menu_command[x] . 172.It Va ansi_caption[x] 173If 174.Va loader_color 175is set 176.Pq enabled by default , 177use this caption for menuitem 178.Dq Li x 179instead of 180.Va menu_caption[x] . 181.It Va toggled_text[x] 182For menuitems where 183.Va menu_command[x] 184is set to 185.Dq Li toggle_menuitem 186(or a derivative thereof), the text displayed 187will toggle between this and 188.Va menu_caption[x] . 189.It Va toggled_ansi[x] 190Like 191.Va toggled_text[x] 192except used when 193.Va loader_color 194is enabled 195.Pq default . 196.It Va menu_caption[x][y] 197For menuitems where 198.Va menu_command[x] 199is set to 200.Dq Li cycle_menuitem 201(or a derivative thereof), the text displayed will cycle between this and other 202.Va menu_caption[x][y] 203entries. 204.It Va ansi_caption[x][y] 205Like 206.Va menu_caption[x][y] 207except used when 208.Va loader_color 209is enabled 210.Pq default . 211.It Va menu_acpi 212When set to a number 213.Dq Li x 214associated with a given menuitem, that menuitem will only appear when 215running on i386-compatible hardware, 216.Va hint.acpi.0.rsdp 217is set (indicating the presence of hardware ACPI support as detected by 218.Xr loader 8 ) , 219and 220.Va hint.acpi.0.disabled 221is not set. 222On non-i386 hardware, menuitems configured after the 223.Dq Li menu_acpi 224menuitem will use a lower number (to compensate for the missing ACPI menuitem) 225but continue to function as expected. 226On i386-compatible hardware lacking ACPI support (as detected by 227.Xr loader 8 ) , 228subsequent menuitems will retain their associated numbers. 229.It Va hint.acpi.0.rsdp 230Set automatically by 231.Xr loader 8 232on i386-compatible hardware when ACPI support is detected at boot time. 233Effects the display of the 234.Dq Li menu_acpi 235menuitem (if configured). 236.It Va hint.acpi.0.disabled 237Effects the display of the 238.Va menu_acpi 239menuitem. 240If set, the menuitem will display 241.Va toggled_text[x] 242.Va ( toggled_ansi[x] 243if 244.Va loader_color 245is set), otherwise 246.Va menu_caption[x] 247.Va ( ansi_caption[x] 248if 249.Va loader_color 250is set). 251.It Va menu_options 252When set to a number 253.Dq Li x , 254a single blank-line and an 255.Dq Li Options 256header are inserted between 257.Va menu_caption[x-1] 258and 259.Va menu_caption[x] 260(if configured). 261.It Va menu_reboot 262If set, adds a built-in 263.Dq Li Reboot 264menuitem to the end of the last configured menuitem. 265If 266.Va menu_options 267is configured, the 268.Dq Li Reboot 269menuitem will be inserted before the 270.Dq Options 271separator. 272.El 273.Pp 274In addition, it provides the following FICL words: 275.Pp 276.Bl -tag -width disable-module_module -compact -offset indent 277.It Ic arch-i386? ( -- BOOL ) 278Returns true (-1) on i386 and false (0) otherwise. 279.It Ic acpipresent? ( -- BOOL ) 280Returns true (-1) if ACPI is present and false (0) otherwise. 281.It Ic acpienabled? ( -- BOOL ) 282Returns true (-1) if ACPI is enabled and false (0) otherwise. 283.It Ic toggle_menuitem ( N -- N ) 284Toggles menuitem 285.Dq Li N 286between 287.Va menu_caption[x] 288and 289.Va toggled_text[x] 290(where 291.Dq Li N 292represents the ASCII decimal value for 293.Dq Li x ) . 294.It Ic cycle_menuitem ( N -- N ) 295Cycles menuitem 296.Dq Li N 297between 298.Va menu_caption[x][y] 299entries (where 300.Va N 301represents the ASCII decimal value for 302.Va x ) . 303.El 304.Pp 305For all values of 306.Dq Li x 307above, use any number between 1 through 9. Sorry, double-digits are not 308currently supported. 309.Sh FILES 310.Bl -tag -width /boot/loader.4th -compact 311.It Pa /boot/loader 312The 313.Xr loader 8 . 314.It Pa /boot/menu.4th 315.Nm 316itself. 317.It Pa /boot/loader.rc 318.Xr loader 8 319bootstrapping script. 320.El 321.Sh EXAMPLES 322A simple boot menu: 323.Pp 324.Bd -literal -offset indent -compact 325include /boot/menu.4th 326menu-init 327set menu_caption[1]="Boot" 328set menu_command[1]="boot" 329set menu_options=2 330set menu_caption[2]="Option: NO" 331set toggled_text[2]="Option: YES" 332set menu_command[2]="toggle_menuitem" 333set menu_timeout_command="boot" 334set menu_reboot 335menu-display 336.Ed 337.Sh SEE ALSO 338.Xr loader.conf 5 , 339.Xr beastie.4th 8 , 340.Xr loader 8 , 341.Xr loader.4th 8 342.Sh HISTORY 343The 344.Nm 345set of commands first appeared in 346.Fx 9.0 . 347.Sh AUTHORS 348The 349.Nm 350set of commands was written by 351.An -nosplit 352.An Devin Teske Aq dteske@FreeBSD.org . 353