Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SYSLINUX(1)		    General Commands Manual		   SYSLINUX(1)

       syslinux	- install the SYSLINUX bootloader on a FAT filesystem

       syslinux	[OPTIONS] device

       Syslinux	is a boot loader for the Linux operating system	which operates
       off a FAT filesystem. It	is intended to simplify	 first-time  installa-
       tion  of	 Linux,	 and  for creation of rescue and other special-purpose
       boot disks.

       In order	to create a bootable Linux disk	using Syslinux,	prepare	a nor-
       mal FAT formatted disk (or file image), and execute the command:

	      syslinux --install /dev/fd0

       This  will  alter  the  boot  sector  on	 the  disk,  copy a file named
       LDLINUX.SYS into	its root directory  and	 patch	the  boot  sector  and
       LDLINUX.SYS (see	NOTES).

       On boot time, by	default, the boot loader will try to load a linux ker-
       nel from	the image named	LINUX on the boot floppy.  This	default	can be
       changed,	see the	section	on the syslinux	configuration file.

       If  the	Shift  or  Alt	keys are held down during boot,	or the Caps or
       Scroll locks are	set, syslinux will display a  lilo(8)  -style  "boot:"
       prompt.	The user can then type a kernel	file name followed by any ker-
       nel parameters. The SYSLINUX bootloader does not	need to	know about the
       kernel  file  in	advance; all that is required is that it is a file lo-
       cated in	the root directory on the disk.

       Syslinux	supports the loading of	initial	ramdisks (initrd) and the  bz-
       Image kernel format.

       The  boot  sector  and LDLINUX.SYS rely heavily on the operation	of the
       syslinux	program	to run correctly. In particular, syslinux patches  the
       boot  sector with the exact location on the disk	of the first sector of
       LDLINUX.SYS, and	also it	patches	the file LDLINUX.SYS  with  the	 exact
       location	on the disk of each additional sector of LDLINUX.SYS itself.

       This  means  that if you	want to	prepare	a new bootable disk, it	is not
       enough to duplicate the boot sector and	LDLINUX.SYS,  but  you	really
       need to run syslinux to update the sectors addresses.

       The version of syslinux used on FreeBSD makes use of the	mtools port to
       modify the FAT filesystem.

       -i, --install
	      Install SYSLINUX on a new	medium,	overwriting any	previously in-
	      stalled bootloader.

       -U, --update
	      Install  SYSLINUX	 on  a	new medium if and only if a version of
	      SYSLINUX is already installed.

       -s, --stupid
	      Install a	"safe, slow and	stupid"	version	of SYSLINUX. This ver-
	      sion  may	work on	some very buggy	BIOSes on which	SYSLINUX would
	      otherwise	fail.  If you find a machine on	which the -s option is
	      required	to  make  it  boot  reliably, please send as much info
	      about your machine as you	can, and include the failure mode.

       -f, --force
	      Force install even if it appears unsafe.

       -r, --raid
	      RAID mode.  If boot fails, tell the BIOS to boot the next	device
	      in  the  boot  sequence  (usually	the next hard disk) instead of
	      stopping with an error message.  This is useful for RAID-1 boot-

       -d, --directory subdirectory
	      Install  the  SYSLINUX  control files in a subdirectory with the
	      specified	name (relative to the root directory on	the device).

       -t, --offset offset
	      Indicates	that the filesystem is at an offset from the  base  of
	      the device or file.

       --once command
	      Declare a	boot command to	be tried on the	first boot only.

       -O, --clear-once
	      Clear the	boot-once command.

       -H, --heads head-count
	      Override the detected number of heads for	the geometry.

       -S, --sectors sector-count
	      Override the detected number of sectors for the geometry.

       -z, --zipdrive
	      Assume zipdrive geometry (--heads	64 --sectors 32).

   Configuration file
       All  the	 configurable defaults in SYSLINUX can be changed by putting a
       file called syslinux.cfg	in the install directory  of  the  boot	 disk.
       This  is	 a  text  file in either UNIX or DOS format, containing	one or
       more of the following items (case is insensitive	for keywords).

       This list is out	of date.

       In the configuration file blank lines and comment lines beginning  with
       a hash mark (#) are ignored.

       default kernel [	options	... ]
	      Sets  the	default	command	line. If syslinux boots	automatically,
	      it will act just as if the  entries  after  "default"  had  been
	      typed in at the "boot:" prompt.

	      If  no  DEFAULT  or  UI statement	is found, or the configuration
	      file is missing entirely,	SYSLINUX drops	to  the	 boot:	prompt
	      with an error message (if	NOESCAPE is set, it stops with a "boot
	      failed" message; this is also the	case for PXELINUX if the  con-
	      figuration file is not found.)

       NOTE: Until SYSLINUX 3.85, if no	configuration file is present, or no
	      "default"	 entry	is  present in the configuration file, the de-
	      fault is "linux auto".

       Even earlier versions of	SYSLINUX used to automatically
	      append the string	"auto" to whatever the	user  specified	 using
	      the  DEFAULT  command.   As  of  version 1.54, this is no	longer
	      true, as it caused problems when using a shell as	 a  substitute
	      for "init."  You may want	to include this	option manually.

       append options ...
	      Add  one	or  more options to the	kernel command line. These are
	      added both for automatic and manual boots. The options are added
	      at  the  very beginning of the kernel command line, usually per-
	      mitting explicitly entered kernel	options	to override them. This
	      is the equivalent	of the lilo(8)
	       "append"	option.

       label label
	 kernel	image
	 append	options	...
	      Indicates	 that  if label	is entered as the kernel to boot, sys-
	      linux should instead boot	image, and the specified "append"  op-
	      tions should be used instead of the ones specified in the	global
	      section of the file (before the first "label" command.) The  de-
	      fault  for  image	 is  the  same as label, and if	no "append" is
	      given the	default	is to use the global entry (if any).  Use "ap-
	      pend -" to use no	options	at all.	 Up to 128 "label" entries are

		     The "image" doesn't have to be a Linux kernel; it can  be
		     a boot sector (see	below.)

       implicit	flag_val
	      If  flag_val is 0, do not	load a kernel image unless it has been
	      explicitly named in a "label" statement.	The default is 1.

       timeout timeout
	      Indicates	how long to wait at the	"boot:"	prompt	until  booting
	      automatically,  in  units	of 1/10	s. The timeout is cancelled as
	      soon as the user types anything on the keyboard, the  assumption
	      being  that  the user will complete the command line already be-
	      gun. A timeout of	zero will disable the timeout completely, this
	      is  also	the  default.  The  maximum  possible timeout value is
	      35996; corresponding to just below one hour.

       serial port [ baudrate ]
	      Enables a	serial port to act as the console. "port" is a	number
	      (0  =  /dev/ttyS0	 =  COM1, etc.); if "baudrate" is omitted, the
	      baud rate	defaults to 9600 bps.  The serial parameters are hard-
	      coded to be 8 bits, no parity, 1 stop bit.

	      For  this	directive to be	guaranteed to work properly, it	should
	      be the first directive in	the configuration file.

       font filename
	      Load a font in .psf format before	displaying any output  (except
	      the  copyright  line,  which  is output as ldlinux.sys itself is
	      loaded.) syslinux	only loads the font onto the  video  card;  if
	      the .psf file contains a Unicode table it	is ignored.  This only
	      works on EGA and VGA cards; hopefully it should  do  nothing  on

       kbdmap keymap
	      Install  a  simple  keyboard  map. The keyboard remapper used is
	      very simplistic (it simply remaps	the keycodes received from the
	      BIOS, which means	that only the key combinations relevant	in the
	      default layout - usually U.S.  English  -	 can  be  mapped)  but
	      should  at least help people with	AZERTY keyboard	layout and the
	      locations	of = and , (two	special	characters used	heavily	on the
	      Linux kernel command line.)

	      The included program from the lilo(8)
	       distribution can	be used	to create such keymaps.

       display filename
	      Displays	the  indicated file on the screen at boot time (before
	      the boot:	prompt,	if displayed). Please see the section below on
	      DISPLAY files. If	the file is missing, this option is simply ig-

       prompt flag_val
	      If flag_val is 0,	display	the "boot:" prompt only	if  the	 Shift
	      or  Alt key is pressed, or Caps Lock or Scroll lock is set (this
	      is the default).	If flag_val is 1, always display  the  "boot:"

       f1 filename
       f2 filename
       f9 filename
       f10 filename
       f11 filename
       f12 filename
	      Displays the indicated file on the screen	when a function	key is
	      pressed at the "boot:" prompt. This can  be  used	 to  implement
	      pre-boot online help (presumably for the kernel command line op-

	      When using the serial console, press _Ctrl-F__digit_ to  get  to
	      the  help	 screens, e.g. _Ctrl-F_2 to get	to the f2 screen.  For
	      f10-f12, hit _Ctrl-F_A, _Ctrl-F_B, _Ctrl-F_C.  For  compatiblity
	      with earlier versions, f10 can also be entered as	_Ctrl-F_0.

   Display file	format
       DISPLAY	and  function-key  help	 files are text	files in either	DOS or
       UNIX format (with or without _CR_). In addition,	the following  special
       codes are interpreted:

       _FF_ = _Ctrl-L_ = ASCII 12
	      Clear  the  screen,  home	 the  cursor.  Note that the screen is
	      filled with the current display color.

       _SI__bg__fg_, _SI_ = _Ctrl-O_ = ASCII 15
	      Set the display colors to	the  specified	background  and	 fore-
	      ground colors, where _bg_	and _fg_ are hex digits, corresponding
	      to the standard PC display attributes:

	      0	= black		 8 = dark grey
	      1	= dark blue	 9 = bright blue
	      2	= dark green	 a = bright green
	      3	= dark cyan	 b = bright cyan
	      4	= dark red	 c = bright red
	      5	= dark purple	 d = bright purple
	      6	= brown		 e = yellow
	      7	= light	grey	 f = white

	      Picking a	bright color (8-f) for the background results  in  the
	      corresponding dark color (0-7), with the foreground flashing.

	      colors are not visible over the serial console.

       _CAN_filename_newline_, _CAN_ = _Ctrl-X_	= ASCII	24
	      If a VGA display is present, enter graphics mode and display the
	      graphic included in the specified	file.  The file	format	is  an
	      ad  hoc  format  called  LSS16;  the included Perl program "ppm-
	      tolss16" can be used to produce these images.  This Perl program
	      also includes the	file format specification.

	      The image	is displayed in	640x480	16-color mode.	Once in	graph-
	      ics mode,	the display attributes (set by	_SI_  code  sequences)
	      work  slightly differently: the background color is ignored, and
	      the foreground colors are	the 16 colors specified	in  the	 image
	      file.   For  that	 reason, ppmtolss16 allows you to specify that
	      certain colors should be assigned	to specific color indicies.

	      Color indicies 0 and 7, in particular,  should  be  chosen  with
	      care: 0 is the background	color, and 7 is	the color used for the
	      text printed by SYSLINUX itself.

       _EM_, _EM_ = _Ctrl-U_ = ASCII 25
	      If we are	currently in graphics mode, return to text mode.

       _DLE_.._ETB_, _Ctrl-P_.._Ctrl-W_	= ASCII	16-23
	      These codes can be used to select	which modes to print a certain
	      part  of	the message file in.  Each of these control characters
	      select a specific	set of modes (text  screen,  graphics  screen,
	      serial port) for which the output	is actually displayed:

	      Character			      Text    Graph   Serial
	      <DLE> = <Ctrl-P> = ASCII 16     No      No      No
	      <DC1> = <Ctrl-Q> = ASCII 17     Yes     No      No
	      <DC2> = <Ctrl-R> = ASCII 18     No      Yes     No
	      <DC3> = <Ctrl-S> = ASCII 19     Yes     Yes     No
	      <DC4> = <Ctrl-T> = ASCII 20     No      No      Yes
	      <NAK> = <Ctrl-U> = ASCII 21     Yes     No      Yes
	      <SYN> = <Ctrl-V> = ASCII 22     No      Yes     Yes
	      <ETB> = <Ctrl-W> = ASCII 23     Yes     Yes     Yes

	      For example:
	      <DC1>Text	mode<DC2>Graphics mode<DC4>Serial port<ETB>
	       ... will	actually print out which mode the console is in!

       _SUB_ = _Ctrl-Z_	= ASCII	26
	      End of file (DOS convention).

   Other operating systems
       This version of syslinux	supports chain loading of other	operating sys-
       tems (such as MS-DOS and	its derivatives, including Windows 95/98).

       Chain loading requires the boot sector of the foreign operating	system
       to  be  stored  in a file in the	root directory of the filesystem.  Be-
       cause neither Linux kernels, nor	boot sector images have	reliable magic
       numbers,	syslinux will look at the file extension. The following	exten-
       sions are recognised:

       none or other	Linux kernel image
       BSS		Boot sector (DOS superblock will be patched in)
       BS		Boot sector

       For filenames given on the command line,	syslinux will search  for  the
       file  by	adding extensions in the order listed above if the plain file-
       name is not found. Filenames in KERNEL statements must be fully	quali-

   Novice protection
       Syslinux	 will attempt to detect	if the user is trying to boot on a 286
       or lower	class machine, or a machine with less than 608K	of low ("DOS")
       RAM  (which  means  the Linux boot sequence cannot complete).  If so, a
       message is displayed and	the boot sequence aborted.  Holding  down  the
       Ctrl key	while booting disables this feature.

       The  compile  time  and	date of	a specific syslinux version can	be ob-
       tained by the DOS command "type ldlinux.sys". This is also used as  the
       signature for the LDLINUX.SYS file, which must match the	boot sector

       Any file	that syslinux uses can be marked hidden, system	or readonly if
       so is convenient; syslinux ignores all file attributes.	 The  SYSLINUX
       installed automatically sets the	readonly attribute on LDLINUX.SYS.

   Bootable CD-ROMs
       SYSLINUX	can be used to create bootdisk images for El Torito-compatible
       bootable	CD-ROMs. However, it appears that many BIOSes are  very	 buggy
       when  it	 comes	to  booting CD-ROMs. Some users	have reported that the
       following steps are helpful in making a CD-ROM that is bootable on  the
       largest possible	number of machines:

       o      Use the -s (safe,	slow and stupid) option	to SYSLINUX

       o      Put  the	boot  image  as	close to the beginning of the ISO 9660
	      filesystem as possible.

       A CD-ROM	is so much faster than a floppy	that the -s  option  shouldn't
       matter from a speed perspective.

       Of course, you probably want to use ISOLINUX instead.  See the documen-
       tation file isolinux.doc.

   Booting from	a FAT partition	on a hard disk
       SYSLINUX	can boot from a	FAT filesystem partition on a hard  disk  (in-
       cluding	FAT32).	 The installation procedure is identical to the	proce-
       dure for	installing it on a floppy, and should work under either	DOS or
       Linux.  To  boot	from a partition, SYSLINUX needs to be launched	from a
       Master Boot Record or another boot loader, just like DOS	itself	would.
       A sample	master boot sector (mbr.bin) is	included with SYSLINUX.

       I  would	 appreciate hearing of any problems you	have with SYSLINUX.  I
       would also like to hear from you	if you	have  successfully  used  SYS-
       LINUX, especially if you	are using it for a distribution.

       If  you are reporting problems, please include all possible information
       about your system and your BIOS;	the vast majority of all problems  re-
       ported  turn out	to be BIOS or hardware bugs, and I need	as much	infor-
       mation as possible in order to diagnose the problems.

       There is	a mailing list for discussion among SYSLINUX users and for an-
       nouncements of new and test versions. To	join, send a message to	major- with the line:

       subscribe syslinux

       in  the	body  of  the  message.	 The  submission   address   is	  sys-

       lilo(8),, fdisk(8), newfs_msdos(8), mtools(1),	super-

       This manual page	is a modified version of the original  syslinux	 docu-
       mentation  by  H. Peter Anvin <>. The conversion to	a man-
       page was	made by	Arthur Korn <>.  FreeBSD-specific	 notes
       added by	Luigi Rizzo.

SYSLINUX			 19 July 2010			   SYSLINUX(1)


Want to link to this manual page? Use this URL:

home | help