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 sys-
     tems.  It is the first utility invoked by	the  FreeBSD  installation  boot
     floppy  and  is  also  available as /usr/sbin/sysinstall on newly installed
     FreeBSD systems for use in later configuring the system.

     The sysinstall utility is generally invoked without arguments for	the  de-
     fault  behavior,  where  the  main  installation/configuration menu is pre-
     sented.

     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 pro-
     gram  with  the ability to write MBRs and disk labels (through the services
     of the libdisk(3) library) and install distributions or packages  onto  new
     and existing FreeBSD systems.  It also contains some extra intelligence for
     running  as a replacement for init(8) when it is invoked by the FreeBSD in-
     stallation 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 in-
     teraction with simple ANSI line graphics, color support for  which  is  en-
     abled by either running on a syscons VTY or some other color-capable termi-
     nal  emulator  (newer  versions  of xterm will support color when using the
     "xterm-color" termcap entry).

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

RUNNING SCRIPTS
     The sysinstall utility may be either driven interactively through its vari-
     ous  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 environ-
	     ment (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	required.   This
	     option  is aimed primarily at large sites who wish to create a sin-
	     gle 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 default
	     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 either by ex-
	     plicit 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 com-
     ment  for	documentation  purposes (ignored by sysinstall).  Each directive
     must be by itself on a single line, functions taking their arguments by ex-
     amining 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  variables
     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 loading
	     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  (de-
		     faults 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 calculate 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 parti-
		    tion  (first  found),  exclusive  to   use	 the   disk   in
		    "dangerously  dedicated" mode or, finally, somenumber to al-
		    locate somenumber blocks of available free space  to  a  new
		    FreeBSD partition.	Default: 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  ex-
	     plicit  call  to diskPartitionWrite being required for that to hap-
	     pen.

     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 per-
	     form the installation interactively at least once and take  careful
	     notes  as to what the slice names will be, then and only then hard-
	     wiring them into the script.

	     For example, let's say you have a SCSI disk on which you have  cre-
	     ated  a new FreeBSD partition in slice 2 (your DOS partition resid-
	     ing in slice 1).  The slice name  would  be  da0s2  for  the  whole
	     FreeBSD  partition  (da0s1  being your DOS primary partition).  Now
	     let's further assume that you have 4GB in this  partition	and  you
	     want  to sub-partition that space into root, swap, var and usr file
	     systems for FreeBSD.  Your invocation of the diskLabelEditor  func-
	     tion might involve setting the following 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 exist-
	     ing  partitions  as  well as creating new ones.  Using the previous
	     example again, let's say that we also wanted to mount our DOS  par-
	     tition  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 partition 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  de-
	     scribed above.

	     Note:  No file system data is actually written to disk until an ex-
	     plicit 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  distribu-
	     tions 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 interaction.

	     Variables:

	     dists   List of distributions to load.  Possible distribution  val-
		     ues are:

		     base      The base binary distribution.

		     GENERIC   The GENERIC kernel.

		     SMP       A kernel suitable for multiple processor systems.

		     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  media
	     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  nec-
		     essary.  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  es-
	     sentially	shorthand  for	a number of more granular "commit" func-
	     tions.

	     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 installa-
	     tion type available.

	     Variables: None

     installUpgrade
	     Start an upgrade installation.

	     Variables: None

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

	     Variables: None

     installFixitCDROM
	     Go into "fixit" mode, assuming a live file system	CDROM  currently
	     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 previous
	     settings.

	     Variables: None

     loadConfig
	     Sort  of like an #include statement, it allows you to load one con-
	     figuration 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  me-
	     dia.

	     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 already set (op-
		     tional).

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

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

	     _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 editor) as
	     the installation media.

	     Variables:

	     ufs     full /path to directory containing the FreeBSD distribution
		     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 already set (op-
		     tional).

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

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

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

     mediaSetFTPUserPass

	     Variables:

	     ftpUser
		     The username to log in as on the ftp server site.	Default:
		     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 rebooted.

	     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 in-
		     stallation 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  de-
		     scribe  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  archi-
				      tecture  of  the	contents on this volume.
				      This property is normally only  used  with
				      FreeBSD products that contain CDs for dif-
				      ferent  architectures,  to  provide better
				      error messages 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  pack-
				      age appears on, and the CD_VOLUME property
				      here  defines the volume ID of the current
				      disc.

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

     For  information  about  building a full release of FreeBSD, please see re-
     lease(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 configura-
     tion.

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  expiration
     date and is greatly in need of death.

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

FreeBSD 8.3			February 18, 2007		   SYSINSTALL(8)
home | help