aboutsummaryrefslogtreecommitdiffstats
path: root/doc/menu.txt
blob: c912c1dfa8b4813f9e448ca222d22c25f51d5381 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
There are two menu systems included with Syslinux, the advanced menu
system, and the simple menu system.


+++ THE ADVANCED MENU SYSTEM +++

The advanced menu system, written by Murali Krishnan Ganapathy, is
located in the menu/ subdirectly.  It allows the user to create
hierarchial submenus, dynamic options, checkboxes, and just about
anything you want.  It requires that the menu is compiled from a
simple C file, see menu/simple.c and menu/complex.c for examples.

The advanced menu system doesn't support serial console at this time.

See menu/README for more information.


+++ THE SIMPLE MENU SYSTEM +++

The simple menu system is a single module located at
com32/modules/vesamenu.c32 (graphical) or com32/modules/menu.c32 (text
mode only).  It uses the same configuration file as the regular
Syslinux command line, and displays all the LABEL statements.

To use the menu system, simply make sure [vesa]menu.c32 is in the
appropriate location for your boot medium (the same directory as the
configuration file for SYSLINUX, EXTLINUX and ISOLINUX, and the same
directory as pxelinux.0 for PXELINUX), and put the following options
in your configuration file:

UI menu.c32


There are a few menu additions to the configuration file, all starting
with the keywords MENU or TEXT; like the rest of the Syslinux config
file language, it is case insensitive:


MENU TITLE title

	Give the menu a title.  The title is presented at the top of
	the menu.


MENU HIDDEN

	Do not display the actual menu unless the user presses a key.
	All that is displayed is a timeout message.


MENU CLEAR

	Clear the screen when exiting the menu, instead of leaving the
	menu displayed.  For vesamenu, this means the graphical
	background is still displayed without the menu itself for as
	long as the screen remains in graphics mode.


MENU SHIFTKEY

	Exit the menu system immediately unless either the Shift or Alt
	key is pressed, or Caps Lock or Scroll Lock is set.


MENU SEPARATOR

	Insert an empty line in the menu.


MENU LABEL label

	(Only valid after a LABEL statement.)
	Changes the label displayed for a specific entry.  This allows
	you to have a label that isn't suitable for the command line,
	for example:

	# Soft Cap Linux
	LABEL softcap
		MENU LABEL Soft Cap ^Linux 9.6.36
		KERNEL softcap-9.6.36.bzi
		APPEND whatever

	# A very dense operating system
	LABEL brick
		MENU LABEL ^Windows CE/ME/NT
		KERNEL chain.c32
		APPEND hd0 2

	The ^ symbol in a MENU LABEL statement defines a hotkey.
	The hotkey will be highlighted in the menu and will move the
	menu cursor immediately to that entry.

	Reusing hotkeys is disallowed, subsequent entries will not be
	highlighted, and will not work.

	Keep in mind that the LABELs, not MENU LABELs, must be unique,
	or odd things will happen to the command-line.


MENU INDENT count

	(Only valid after a LABEL statement.)
	Will add "count" spaces in front of the displayed menu entry.


MENU DISABLE

	(Only valid after a LABEL statement.)
	Makes the entry unselectable.  This allows you to make a
	section in your menu with different options below it.
	for example:

	# Entries for network boots
	LABEL -
		MENU LABEL Network:
		MENU DISABLE

	# Soft Cap Linux
	LABEL softcap
		MENU LABEL Soft Cap ^Linux 9.6.36
		MENU INDENT 1
		KERNEL softcap-9.6.36.bzi
		APPEND whatever

	# Dos 6.22
	LABEL dos
		MENU LABEL ^Dos 6.22
		MENU INDENT 1
		KERNEL memdisk
		APPEND initrd=dos622.imz

	# Separator
	MENU SEPARATOR

	# Entries for local boots
	LABEL -
		MENU LABEL Local:
		MENU DISABLE

	# Windows 2000
	LABEL w2k
		MENU LABEL ^Windows 2000
		MENU INDENT 1
		KERNEL chain.c32
		APPEND hd0 1

	# Windows XP
	LABEL xp
		MENU LABEL Windows ^XP
		MENU INDENT 1
		KERNEL chain.c32
		APPEND hd0 2

MENU HIDE

	(Only valid after a LABEL statement.)
	Suppresses a particular LABEL entry from the menu.


MENU DEFAULT

	(Only valid after a LABEL statement.)

	Indicates that this entry should be the default for this
	particular submenu.  See also the DEFAULT directive below.


TEXT HELP
Help text ...
... which can span multiple lines
ENDTEXT

	(Only valid after a LABEL statement.)

	Specifies a help text that should be displayed when a particular
	selection is highlighted.


MENU PASSWD passwd

	(Only valid after a LABEL statement.)

	Sets a password on this menu entry.  "passwd" can be either a
	cleartext password or a password encrypted with one of the
	following algorithms:

	MD5		(Signature: $1$)
	SHA-1		(Signature: $4$)
	SHA-2-256	(Signature: $5$)
	SHA-2-512	(Signature: $6$)

	Use the included Perl scripts "sha1pass" or "md5pass" to
	encrypt passwords.  MD5 passwords are compatible with most
	Unix password file utilities; SHA-1 passwords are probably
	unique to Syslinux; SHA-2 passwords are compatible with very
	recent Linux distributions.  Obviously, if you don't encrypt
	your passwords they will not be very secure at all.

	If you are using passwords, you want to make sure you also use
	the settings "NOESCAPE 1", "PROMPT 0", and either set
	"ALLOWOPTIONS 0" or use a master password (see below.)

	If passwd is an empty string, this menu entry can only be
	unlocked with the master password.


MENU MASTER PASSWD passwd

	Sets a master password.  This password can be used to boot any
	menu entry, and is required for the [Tab] and [Esc] keys to
	work.


MENU RESOLUTION height width

	Requests a specific screen resolution when in graphics mode.
	The default is "640 480" corresponding to a resolution of
	640x480 pixels, which all VGA-compatible monitors should be
	able to display.

	If the selected resolution is unavailable, the text mode menu
	is displayed instead.


MENU BACKGROUND background

	For vesamenu.c32, sets the background image.  The background
	can either be a color (see MENU COLOR) or the name of an image
	file, which should be the size of the screen (normally 640x480
	pixels, but see MENU RESOLUTION) and either in PNG, JPEG or
	LSS16 format.


MENU BEGIN [tagname]
MENU END

	Begin/end a submenu.  The entries between MENU BEGIN and MENU
	END form a submenu, which is marked with a > mark on the right
	hand of the screen.  Submenus inherit the properties of their
	parent menus, but can override them, and can thus have their
	own backgrounds, master passwords, titles, timeouts, messages
	and so forth.


MENU GOTO tagname

	(Only valid after a LABEL statement.)

	This label will transfer to the named submenu instead of
	booting anything.  To transfer to the top-level menu, specify
	"menu goto .top".


MENU EXIT [tagname]

	(Only valid after a label statement inside MENU BEGIN ...
	MENU END)

	Exit to the next higher menu, or, if tagname is specified, to
	the named menu.


MENU QUIT

	(Only valid after a LABEL statement.)

	This label quits the menu system.

	WARNING: if MENU MASTER PASSWD or ALLOWOPTIONS 0 is set, this
	will still allow exiting to the CLI; however, a separate MENU
	PASSWD can of course be set for this label.


MENU START

	(Only valid inside MENU BEGIN ... MENU END)

	Indicates that the menu system should start at the menu being
	defined instead of at the top-level menu.  See also the
	DEFAULT directive below.


DEFAULT label

	Set the global default.  If "label" points into a submenu,
	that menu becomes the start menu; in other words, this
	directive has the same effect as both MENU DEFAULT and MENU
	START.

	For backwards compatibility with earlier versions of Syslinux,
	this directive is ignored unless the configuration file also
	contains a UI directive.

	Note: the CLI accepts options after the label, or even a
	non-label.  The menu system does not support that.


MENU SAVE
MENU NOSAVE

	Remember the last entry selected and make that the default for
	the next boot.  A password-protected menu entry is *not*
	saved.  This requires the ADV data storage mechanism, which is
	currently only implemented for EXTLINUX, although the other
	Syslinux derivatives will accept the command (and ignore it.)

	NOTE: MENU SAVE stores the LABEL tag of the selected entry;
	this mechanism therefore relies on LABEL tags being unique.
	On the other hand, it handles changes in the configuration
	file gracefully.

	The MENU SAVE information can be cleared with
	"extlinux --reset-adv <bootdir>".

	A MENU SAVE or MENU NOSAVE at the top of a (sub)menu affects
	all entries underneath that (sub)menu except those that in
	turn have MENU SAVE or MENU NOSAVE declared.  This can be used
	to only save certain entires when selected.


INCLUDE filename [tagname]
MENU INCLUDE filename [tagname]

	Include the contents of the configuration file filename at
	this point.

	In the case of MENU INCLUDE, the included data is only seen by
	the menu system; the core syslinux code does not parse this
	command, so any labels defined in it are unavailable.

	If a tagname is included, the whole file is considered to have
	been bracketed with a MENU BEGIN tagname ... MENU END pair,
	and will therefore show up as a submenu.


MENU AUTOBOOT message

	Replaces the message "Automatic boot in # second{,s}...".  The
	symbol # is replaced with the number of seconds remaining.
	The syntax "{singular,[dual,]plural}" can be used to conjugate
	appropriately.


MENU TABMSG message

	Replaces the message "Press [Tab] to edit options".


MENU NOTABMSG message

	Takes the place of the TABMSG message if option editing is
	disabled.  Defaults to blank.


MENU PASSPROMPT message

	Replaces the message "Password required".


MENU COLOR element ansi foreground background shadow

	Sets the color of element "element" to the specified color
	sequence:

	screen          Rest of the screen
	border          Border area
	title           Title bar
	unsel           Unselected menu item
	hotkey          Unselected hotkey
	sel             Selection bar
	hotsel          Selected hotkey
	disabled	Disabled menu item
	scrollbar       Scroll bar
	tabmsg          Press [Tab] message
	cmdmark         Command line marker
	cmdline         Command line
	pwdborder       Password box border
	pwdheader       Password box header
	pwdentry        Password box contents
	timeout_msg     Timeout message
	timeout         Timeout counter
	help		Help text
	msgXX		Message (F-key) file attribute XX

	... where XX is two hexadecimal digits (the "plain text" is 07).

	"ansi" is a sequence of semicolon-separated ECMA-48 Set
	Graphics Rendition (<ESC>[m) sequences:

	0     reset all attributes to their defaults
	1     set bold
	4     set underscore (simulated with color on a color display)
	5     set blink
	7     set reverse video
	22    set normal intensity
	24    underline off
	25    blink off
	27    reverse video off
	30    set black foreground
	31    set red foreground
	32    set green foreground
	33    set brown foreground
	34    set blue foreground
	35    set magenta foreground
	36    set cyan foreground
	37    set white foreground
	38    set underscore on, set default foreground color
	39    set underscore off, set default foreground color
	40    set black background
	41    set red background
	42    set green background
	43    set brown background
	44    set blue background
	45    set magenta background
	46    set cyan background
	47    set white background
	49    set default background color

	These are used (a) in text mode, and (b) on the serial
	console.

	"foreground" and "background" are color codes in #AARRGGBB
	notation, where AA RR GG BB are hexadecimal digits for alpha
	(opacity), red, green and blue, respectively.  #00000000
	represents fully transparent, and #ffffffff represents opaque
	white.

	"shadow" controls the handling of the graphical console text
	shadow.  Permitted values are "none" (no shadowing), "std" or
	"standard" (standard shadowing - foreground pixels are
	raised), "all" (both background and foreground raised), and
	"rev" or "reverse" (background pixels are raised.)

	If any field is set to "*" or omitted (at the end of the line)
	then that field is left unchanged.


	The current defaults are:

	menu color screen	37;40      #80ffffff #00000000 std
	menu color border	30;44      #40000000 #00000000 std
	menu color title	1;36;44    #c00090f0 #00000000 std
	menu color unsel	37;44      #90ffffff #00000000 std
	menu color hotkey	1;37;44    #ffffffff #00000000 std
	menu color sel		7;37;40    #e0000000 #20ff8000 all
	menu color hotsel	1;7;37;40  #e0400000 #20ff8000 all
	menu color disabled	1;30;44    #60cccccc #00000000 std
	menu color scrollbar	30;44      #40000000 #00000000 std
	menu color tabmsg	31;40      #90ffff00 #00000000 std
	menu color cmdmark	1;36;40    #c000ffff #00000000 std
	menu color cmdline	37;40      #c0ffffff #00000000 std
	menu color pwdborder	30;47      #80ffffff #20ffffff std
	menu color pwdheader	31;47      #80ff8080 #20ffffff std
	menu color pwdentry	30;47      #80ffffff #20ffffff std
	menu color timeout_msg	37;40      #80ffffff #00000000 std
	menu color timeout	1;37;40    #c0ffffff #00000000 std
	menu color help		37;40      #c0ffffff #00000000 std
	menu color msg07	37;40      #90ffffff #00000000 std


MENU MSGCOLOR fg_filter bg_filter shadow

	Sets *all* the msgXX colors to a color scheme derived from the
	fg_filter and bg_filter values.  Background color zero is
	always treated as transparent.  The default corresponds to:

	menu msgcolor #90ffffff #80ffffff std

	This directive should come before any directive that
	customizes individual msgXX colors.


MENU WIDTH 80
MENU MARGIN 10
MENU PASSWORDMARGIN 3
MENU ROWS 12
MENU TABMSGROW 18
MENU CMDLINEROW 18
MENU ENDROW -1
MENU PASSWORDROW 11
MENU TIMEOUTROW 20
MENU HELPMSGROW 22
MENU HELPMSGENDROW -1
MENU HIDDENROW -2
MENU HSHIFT 0
MENU VSHIFT 0

	These options control the layout of the menu on the screen.
	The values above are the defaults.

	A negative value is relative to the calculated length of the
	screen (25 for text mode, 28 for VESA graphics mode.)


F1 textfile background
...
F12 textfile background

	Displays full-screen help (also available at the command line.)
	The same control code sequences as in the command line
	interface are supported, although some are ignored.

	Additionally, a second argument allows a different background
	image (see MENU BACKGROUND for supported formats) to be displayed.


The menu system honours the TIMEOUT command; if TIMEOUT is specified
it will execute the ONTIMEOUT command if one exists, otherwise it will
pick the default menu option.  WARNING: the timeout action will bypass
password protection even if one is set for the specified or default
entry!

Normally, the user can press [Tab] to edit the menu entry, and [Esc]
to return to the Syslinux command line.  However, if the configuration
file specifies ALLOWOPTIONS 0, these keys will be disabled, and if
MENU MASTER PASSWD is set, they require the master password.

The simple menu system supports serial console, using the normal
SERIAL directive.  However, it can be quite slow over a slow serial
link; you probably want to set your baudrate to 38400 or higher if
possible.  It requires a Linux/VT220/ANSI-compatible terminal on the
other end.


	+++ USING AN ALTERNATE CONFIGURATION FILE +++


It is also possible to load a secondary configuration file, to get to
another menu.  To do that, invoke menu.c32 with the name of the
secondary configuration file.

LABEL othermenu
	MENU LABEL Another Menu
	KERNEL menu.c32
	APPEND othermenu.conf

If you specify more than one file, they will all be read, in the order
specified.  The dummy filename ~ (tilde) is replaced with the filename
of the main configuration file.

# The file graphics.conf contains common color and layout commands for
# all menus.
LABEL othermenu
	MENU LABEL Another Menu
	KERNEL vesamenu.c32
	APPEND graphics.conf othermenu.conf

# Return to the main menu
LABEL mainmenu
	MENU LABEL Return to Main Menu
	KERNEL vesamenu.c32
	APPEND graphics.conf ~

See also the MENU INCLUDE directive above.