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

FreeBSD Manual Pages

  
 
  

home | help
SYSINSTALL(8)		    System Manager's Manual		 SYSINSTALL(8)

NAME
       sysinstall -- system installation and configuration tool

SYNOPSIS
       sysinstall [var=value] [function] [...]

DESCRIPTION
       The  sysinstall	utility	is used	for installing and configuring FreeBSD
       systems.	 It is the first utility invoked by the	 FreeBSD  installation
       boot  floppy and	is also	available as /usr/sbin/sysinstall on newly in-
       stalled FreeBSD systems for use in later	configuring the	system.

       The sysinstall utility is generally invoked without arguments  for  the
       default	behavior,  where  the  main installation/configuration menu is
       presented.

       On those	occasions where	it is deemed necessary to invoke  a  subsystem
       of sysinstall directly, however,	it is also possible to do so by	naming
       the  appropriate	function entry points on the command line.  Since this
       action is essentially identical to running an installation script, each
       command-line argument corresponding to a	line of	script,	the reader  is
       encouraged  to  read  the  section on scripting for more	information on
       this feature.

NOTES
       The sysinstall utility is essentially nothing more than a monolithic  C
       program	with  the  ability  to write MBRs and disk labels (through the
       services	of the libdisk(3) library) and install distributions or	 pack-
       ages  onto new and existing FreeBSD systems.  It	also contains some ex-
       tra intelligence	for running as a replacement for init(8)  when	it  is
       invoked	by  the	 FreeBSD installation boot procedure.  It assumes very
       little in the way of additional utility support and performs most  file
       system  operations  by calling the relevant syscalls (such as mount(2))
       directly.

       The sysinstall utility currently	uses the dialog(3) library to do  user
       interaction  with simple	ANSI line graphics, color support for which is
       enabled by either running on a syscons VTY or some other	 color-capable
       terminal	 emulator (newer versions of xterm will	support	color when us-
       ing the "xterm-color" termcap entry).

       This product is currently at the	end of its life	cycle and will eventu-
       ally be replaced.

RUNNING	SCRIPTS
       The sysinstall utility may be either driven interactively  through  its
       various	internal  menus	 or  run  in batch mode, driven	by an external
       script.	Such a script may be loaded and	executed in one	of 3 ways:

       LOAD_CONFIG_FILE
	       If sysinstall is	compiled with LOAD_CONFIG_FILE set in the  en-
	       vironment  (or  in the Makefile)	to some	value, then that value
	       will be used as the filename to automatically look for and load
	       when sysinstall starts up and  with  no	user  interaction  re-
	       quired.	This option is aimed primarily at large	sites who wish
	       to create a single prototype install for	multiple machines with
	       largely identical configurations	and/or installation options.

       MAIN MENU
	       If  sysinstall  is run interactively, that is to	say in the de-
	       fault manner, it	will bring up a	main  menu  which  contains  a
	       "load  config  file" option.  Selecting this option will	prompt
	       for the name of a script	file which it  then  will  attempt  to
	       load from a DOS or UFS formatted	floppy.

       COMMAND LINE
	       Each  command  line  argument  is treated as a script directive
	       when sysinstall is run in multi-user mode.  Execution ends  ei-
	       ther by explicit	request	(e.g. calling the shutdown directive),
	       upon reaching the end of	the argument list or on	error.

	       For example:

	       /usr/sbin/sysinstall _ftpPath=ftp://ziggy/pub/ mediaSetFTP configPackages

	       Would  initialize  sysinstall for FTP installation media	(using
	       the server `ziggy') and then bring up the package  installation
	       editor, exiting when finished.

SCRIPT SYNTAX
       A script	is a list of one or more directives, each directive taking the
       form of:

       var=value

       function

       or #somecomment

       Where var=value is the assignment of some internal sysinstall variable,
       e.g.  "ftpPass=FuNkYChiKn",  and	 function  is  the name	of an internal
       sysinstall function, e.g. "mediaSetFTP",	and #comment is	a  single-line
       comment	for  documentation purposes (ignored by	sysinstall).  Each di-
       rective must be by itself on a single line, functions taking their  ar-
       guments	by  examining known variable names.  This requires that	you be
       sure to assign the relevant variables before calling a  function	 which
       requires	them.

       The  noError  variable can be assigned before each directive: this will
       cause any error detected	while processing the directive	itself	to  be
       ignored.	  The value of noError will automatically reset	to the default
       "unassigned" every time a directive is processed.

       When and	where a	function depends on the	settings of one	or more	 vari-
       ables will be noted in the following table:

       Function	Glossary:

       configAnonFTP
	       Invoke the Anonymous FTP	configuration menu.

	       Variables: None

       configRouter
	       Select  which routing daemon you	wish to	use, potentially load-
	       ing any required	3rd-party routing daemons as necessary.

	       Variables:

	       router  can be set to the name of the desired  routing  daemon,
		       e.g. "routed" or	"gated", otherwise it is prompted for.

       configNFSServer
	       Configure host as an NFS	server.

	       Variables: None

       configNTP
	       Configure host as a user	of the Network Time Protocol.

	       Variables:

	       ntpdate_hosts
		       Whitespace-separated list of ntpdate(8) servers to sync
		       from.

       configPCNFSD
	       Configure host to support PC NFS.

	       Variables:

	       pcnfsd_pkg
		       The  name  of  the  PCNFSD package to load if necessary
		       (defaults to hard coded version).

       configPackages
	       Bring up	the interactive	package	management menu.

	       Variables: None

       configUsers
	       Add users and/or	groups to the system.

	       Variables: None

       diskPartitionEditor
	       Invokes the disk	partition (MBR)	editor.

	       Variables:

	       geometry
		      The disk geometry,  as  a	 cyls/heads/sectors  formatted
		      string.	The word "sane"	instructs sysinstall to	calcu-
		      late a safe (not necessarily optimal)  geometry  if  the
		      current one has more than	65535 cylinders, more than 256
		      heads  or	more than 63 sectors per track (255 sectors on
		      the PC98 architecture).  Default:	no change to geometry.

	       partition
		      Set to disk partitioning type or size, its  value	 being
		      free  in	order  to  use	only  remaining	free space for
		      FreeBSD, all to use the  entire  disk  for  FreeBSD  but
		      maintain	a  proper  partition table, existing to	use an
		      existing FreeBSD partition (first	found),	 exclusive  to
		      use  the	disk  in  "dangerously dedicated" mode or, fi-
		      nally,  somenumber  to  allocate	somenumber  blocks  of
		      available	 free  space  to a new FreeBSD partition.  De-
		      fault: Interactive mode.

	       bootManager
		      is set to	one of boot to signify the installation	 of  a
		      boot  manager,  standard	to  signify  installation of a
		      "standard" non-boot MGR DOS MBR or none to indicate that
		      no change	to the	boot  manager  is  desired.   Default:
		      none.

	       diskInteractive
		      If set, bring up the interactive disk partition editor.

	       Note:  Nothing is actually written to disk by this function, an
	       explicit	call to	diskPartitionWrite being required for that  to
	       happen.

       diskPartitionWrite
	       Causes	any   pending	MBR   changes	(typically   from  the
	       diskPartitionEditor function) to	be written out.

	       Variables: None

       diskLabelEditor
	       Invokes the disk	label editor.  This is a bit trickier  from  a
	       script  since  you  need	to essentially label everything	inside
	       each   FreeBSD	(type	0xA5)	partition   created   by   the
	       diskPartitionEditor  function,  and that	requires knowing a few
	       rules about how things are laid out.  When creating a script to
	       automatically allocate disk space and partition it  up,	it  is
	       suggested that you first	perform	the installation interactively
	       at least	once and take careful notes as to what the slice names
	       will be,	then and only then hardwiring them into	the script.

	       For  example,  let's say	you have a SCSI	disk on	which you have
	       created a new FreeBSD partition in slice	2 (your	DOS  partition
	       residing	 in  slice  1).	 The slice name	would be da0s2 for the
	       whole FreeBSD partition (da0s1 being your  DOS  primary	parti-
	       tion).  Now let's further assume	that you have 4GB in this par-
	       tition  and  you	 want  to  sub-partition that space into root,
	       swap, var and usr file systems for FreeBSD.  Your invocation of
	       the diskLabelEditor function might involve setting the  follow-
	       ing variables:

	       da0s2-1=ufs 2097152 /
		      A	 1GB  root  file  system  (all	sizes  are in 512 byte
		      blocks).

	       da0s2-2=swap 1048576 /
		      A	512MB swap partition.

	       da0s2-3=ufs 524288 /var
		      A	256MB /var file	system.

	       da0s2-4=ufs 0 /usr 1
		      With the balance of free space (around 2.25GB) going  to
		      the  /usr	file system and	with soft-updates enabled (the
		      argument following the mount point, if  non-zero,	 means
		      to set the soft updates flag).

	       One  can	 also  use the diskLabelEditor for mounting or erasing
	       existing	partitions as well as creating new  ones.   Using  the
	       previous	 example again,	let's say that we also wanted to mount
	       our DOS partition and make sure that  an	 /etc/fstab  entry  is
	       created	for  it	 in  the new installation.  Before calling the
	       diskLabelEditor function, we simply add an additional line:

		     da0s1=/dos_c N

	       before the call.	 This tells the	label editor that you want  to
	       mount  the first	slice on /dos_c	and not	to attempt to newfs it
	       (not that sysinstall would attempt this for a DOS partition  in
	       any case, but it	could just as easily be	an existing UFS	parti-
	       tion being named	here and the 2nd field is non-optional).

	       You  can	 also set the diskInteractive variable to request that
	       the disk	label editor use an interactive	 dialog	 to  partition
	       the  disk  instead  of using variables to explicitly layout the
	       disk as described above.

	       Note: No	file system data is actually written to	disk until  an
	       explicit	call to	diskLabelCommit	is made.

       diskLabelCommit
	       Writes out all pending disklabel	information and	creates	and/or
	       mounts  any  file  systems which	have requests pending from the
	       diskLabelEditor function.

	       Variables: None

       distReset
	       Resets all selected distributions to the	empty set (no distrib-
	       utions selected).

	       Variables: None

       distSetCustom
	       Allows the selection of a custom	 distribution  set  (e.g.  not
	       just  one  of the existing "canned" sets) with no user interac-
	       tion.

	       Variables:

	       dists   List of distributions to	load.	Possible  distribution
		       values are:

		       base	 The base binary distribution.

		       GENERIC	 The GENERIC kernel.

		       SMP	 A kernel suitable for multiple	processor sys-
				 tems.

		       doc	 Miscellaneous documentation

		       games	 Games

		       manpages	 Manual	pages (unformatted)

		       catpages	 Pre-formatted manual pages

		       proflibs	 Profiled libraries for	developers.

		       dict	 Dictionary   information   (for   tools  like
				 spell).

		       info	 GNU info files	and other extra	docs.

		       lib32	 (amd64	only) 32-bit runtime compatibility li-
				 braries.

		       ports	 The ports collection.

		       ssecure	 /usr/src/secure

		       sbase	 /usr/src/[top level files]

		       scontrib	 /usr/src/contrib

		       scrypto	 /usr/src/crypto

		       sgnu	 /usr/src/gnu

		       setc	 /usr/src/etc

		       sgames	 /usr/src/games

		       sinclude	 /usr/src/include

		       skrb5	 /usr/src/kerberos5

		       slib	 /usr/src/lib

		       slibexec	 /usr/src/libexec

		       srelease	 /usr/src/release

		       srescue	 /usr/src/rescue

		       stools	 /usr/src/tools

		       sbin	 /usr/src/bin

		       ssbin	 /usr/src/sbin

		       sshare	 /usr/src/share

		       ssys	 /usr/src/sys

		       stools	 /usr/src/tools

		       subin	 /usr/src/usr.bin

		       susbin	 /usr/src/usr.sbin

		       local	 Local additions collection.

       distSetDeveloper
	       Selects the standard Developer's	distribution set.

	       Variables: None

       distSetUser
	       Selects the standard user distribution set.

	       Variables: None

       distSetMinimum
	       Selects the very	minimum	distribution set.

	       Variables: None

       distSetEverything
	       Selects the full	whack -	all available distributions.

	       Variables: None

       distSetSrc
	       Interactively select source subcomponents.

	       Variables: None

       distExtractAll
	       Install all currently selected distributions (requires that me-
	       dia device also be selected).

	       Variables: None

       docBrowser
	       Install (if necessary) an HTML documentation browser and	go  to
	       the HTML	documentation submenu.

	       Variables:

	       browserPackage
		       The  name  of the browser package to try	and install as
		       necessary.  Defaults to latest links package.

	       browserBinary
		       The name	of the browser binary  itself  (if  overriding
		       the browserPackage variable).  Defaults to links.

       installCommit
	       Commit  any  and	all pending changes to disk.  This function is
	       essentially shorthand for a number of  more  granular  "commit"
	       functions.

	       Variables: None

       installConfigure
	       Commit any rc.conf changes to disk.

	       Variables:

	       keeprcconf
		       Preserve	 existing  rc.conf parameters.	This is	useful
		       if  you	have  a	 post-install  script  which  modifies
		       rc.conf.

       installExpress
	       Start  an  "express"  installation, asking few questions	of the
	       user.

	       Variables: None

       installStandard
	       Start a "standard" installation,	the most user-friendly instal-
	       lation type available.

	       Variables: None

       installUpgrade
	       Start an	upgrade	installation.

	       Variables: None

       installFixitHoloShell
	       Start up	the "emergency holographic shell" over on VTY4 if run-
	       ning as init.  This will	also happen automatically as  part  of
	       the installation	process	unless noHoloShell is set.

	       Variables: None

       installFixitCDROM
	       Go  into	 "fixit"  mode,	assuming a live	file system CDROM cur-
	       rently in the drive.

	       Variables: None

       installFixitFloppy
	       Go into "fixit" mode, assuming an available fixit  floppy  disk
	       (user will be prompted for it).

	       Variables: None

       installFilesystems
	       Do just the file	system initialization part of an install.

	       Variables: None

       installVarDefaults
	       Initialize all variables	to their defaults, overriding any pre-
	       vious settings.

	       Variables: None

       loadConfig
	       Sort  of	 like an #include statement, it	allows you to load one
	       configuration file from another.

	       Variables:

	       configFile
		       The fully qualified pathname of the file	to load.

       mediaOpen
	       If a media device is set, mount it.

	       Variables: None

       mediaClose
	       If a media device is open, close	it.

	       Variables: None

       mediaSetCDROM
	       Select a	FreeBSD	CDROM as the installation media.

	       Variables: None

       mediaSetFloppy
	       Select a	pre-made floppy	installation set as  the  installation
	       media.

	       Variables: None

       mediaSetDOS
	       Select  an  existing  DOS primary partition as the installation
	       media.  The first primary partition found is used (e.g. C:).

	       Variables: None

       mediaSetFTP
	       Select an FTP site as the installation media.

	       Variables:

	       hostname
		       The name	of the host being installed (non-optional).

	       domainname
		       The domain name of the host being installed (optional).

	       defaultrouter
		       The default router for this host	(non-optional).

	       netDev  Which host interface to use (ed0	or ep0,	 for  example.
		       Non-optional).

	       netInteractive
		       If  set,	 bring	up  the	interactive network setup form
		       even if all relevant configuration  variables  are  al-
		       ready set (optional).

	       ipaddr  The IP address for the selected host interface (non-op-
		       tional).

	       netmask
		       The  netmask  for  the selected host interface (non-op-
		       tional).

	       _ftpPath
		       The fully qualified URL of the FTP site containing  the
		       FreeBSD	 distribution  you  are	 interested  in,  e.g.
		       ftp://ftp.FreeBSD.org/pub/FreeBSD/.

       mediaSetFTPActive
	       Alias for mediaSetFTP using "active" FTP	transfer mode.

	       Variables: Same as for mediaSetFTP.

       mediaSetFTPPassive
	       Alias for mediaSetFTP using "passive" FTP transfer mode.

	       Variables: Same as for mediaSetFTP.

       mediaSetHTTP
	       Alias for mediaSetFTP using an HTTP proxy.

	       Variables: See mediaSetFTP, plus

	       _httpPath
		       The proxy to use	(host:port) (non-optional).

       mediaSetUFS
	       Select an existing UFS partition	(mounted with the  label  edi-
	       tor) as the installation	media.

	       Variables:

	       ufs     full /path to directory containing the FreeBSD distrib-
		       ution you are interested	in.

       mediaSetNFS

	       Variables:

	       hostname
		       The name	of the host being installed (non-optional).

	       domainname
		       The domain name of the host being installed (optional).

	       defaultrouter
		       The default router for this host	(non-optional).

	       netDev  Which  host  interface to use (ed0 or ep0, for example.
		       Non-optional).

	       netInteractive
		       If set, bring up	the  interactive  network  setup  form
		       even  if	 all  relevant configuration variables are al-
		       ready set (optional).

	       ipaddr  The IP address for the selected host interface (non-op-
		       tional).

	       netmask
		       The netmask for the selected  host  interface  (non-op-
		       tional).

	       nfs     full  hostname:/path  specification  for	directory con-
		       taining the FreeBSD distribution	you are	interested in.

       mediaSetFTPUserPass

	       Variables:

	       ftpUser
		       The username to log in as on the	ftp server site.   De-
		       fault: ftp

	       ftpPass
		       The password to use for this username on	the ftp	server
		       site.  Default: user@host

       mediaSetCPIOVerbosity

	       Variables:

	       cpioVerbose
		       Can be used to set the verbosity	of cpio	extractions to
		       low or high.

       mediaGetType
	       Interactively get the user to specify some type of media.

	       Variables: None

       optionsEditor
	       Invoke the interactive options editor.

	       Variables: None

       packageAdd
	       Try  to	fetch and add a	package	to the system (requires	that a
	       media type be set),

	       Variables:

	       package
		       The name	of the package to  add,	 e.g.  bash-1.14.7  or
		       ncftp-2.4.2.

       addGroup
	       Invoke the interactive group editor.

	       Variables: None

       addUser
	       Invoke the interactive user editor.

	       Variables: None

       shutdown
	       Stop  the  script,  terminate sysinstall	and reboot the system.
	       On the sparc64 platform,	the system is halted rather  than  re-
	       booted.

	       Variables: None

       system  Execute an arbitrary command with system(3)

	       Variables:

	       command
		       The  name of the	command	to execute.  When running from
		       a boot floppy, very minimal expectations	should be made
		       as to what is available until/unless a relatively  full
		       system installation has just been done.

       tcpMenuSelect
	       Configure a network device.

	       Variables:  Same	as for mediaSetFTP except that _ftpPath	is not
	       used.

DISTRIBUTION MEDIA
       The following files can be used to affect the operation	of  sysinstall
       when used during	initial	system installation.

       cdrom.inf       A  text	file  of properties, listed one	per line, that
		       describe	the contents of	the media in use.  The	syntax
		       for each	line is	simply "property = value".  Currently,
		       only the	following properties are recognized.

		       CD_VERSION	This  property	should	be  set	to the
					FreeBSD	version	on the	current	 media
					volume.	  For  example,	 "CD_VERSION =
					5.3".

		       CD_MACHINE_ARCH	This property should be	set to the ar-
					chitecture of  the  contents  on  this
					volume.	  This	property  is  normally
					only used with FreeBSD	products  that
					contain	 CDs  for  different architec-
					tures, to provide  better  error  mes-
					sages if users try to install packages
					built for the wrong architecture.  For
					example, "CD_MACHINE_ARCH = amd64".

		       CD_VOLUME	In  a multi-volume collection (such as
					the FreeBSD 4-CD set), the ports/INDEX
					file on	each disc should  contain  the
					full  package  index for the set.  The
					last field of the INDEX	 file  denotes
					which  volume  the package appears on,
					and the	CD_VOLUME  property  here  de-
					fines  the  volume  ID	of the current
					disc.

       packages/INDEX  The package index file.	Each package is	 listed	 on  a
		       separate	line with additional meta-data such as the re-
		       quired  dependencies.  This index is generated by "make
		       index" from the ports(7)	collection.  When multi-volume
		       support is enabled, an additional field should be added
		       to each line indicating which media volume contains the
		       given package.

       For information about building a	full release of	 FreeBSD,  please  see
       release(7).

FILES
       This  utility  may  edit	 the contents of /etc/rc.conf, /etc/hosts, and
       /etc/resolv.conf	as necessary to	reflect	changes	in the network config-
       uration.

SEE ALSO
       If you have a reasonably	complete source	tree online, take  a  look  at
       /usr/src/usr.sbin/sysinstall/install.cfg	  for  a  sample  installation
       script.

HISTORY
       This version of sysinstall first	appeared in FreeBSD 2.0.

AUTHORS
       Jordan K. Hubbard <jkh@FreeBSD.org>

BUGS
       Editing slice and partition tables on disks which are currently mounted
       by the system is	not allowed.  This is generally	only  a	 problem  when
       sysinstall  is run on a system that is already installed.  Use fdisk(8)
       and bsdlabel(8) for these tasks.

       This utility is a prototype which lasted	several	years past its expira-
       tion date and is	greatly	in need	of death.

       There are a (great) number of undocumented variables.  UTSL.

GNU			       February	18, 2007		 SYSINSTALL(8)

NAME | SYNOPSIS | DESCRIPTION | NOTES | RUNNING SCRIPTS | SCRIPT SYNTAX | DISTRIBUTION MEDIA | FILES | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=sysinstall&manpath=FreeBSD+8.2-RELEASE+and+Ports>

home | help