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

NAME
     sysinstall -- system installation and configuration tool

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

DESCRIPTION
     sysinstall is a utility for installing and configuring FreeBSD systems.  It
     is the first utility invoked by the FreeBSD installation boot floppy and is
     also  copied  into /stand/sysinstall on newly installed FreeBSD systems for
     use in later configuring the system.

     The sysinstall program 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
     sysinstall is essentially nothing more than a monolithic C program with the
     ability  to  write  MBRs  and disk labels (through the services of the lib-
     disk(3) library) and install distributions or packages onto new and  exist-
     ing  FreeBSD systems.  It also contains some extra intelligence for running
     as a replacement for init(8) when it's 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.

     sysinstall 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 using the "xterm-color"
     termcap entry).

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

RUNNING SCRIPTS
     sysinstall  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 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:

	     /stand/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_flags
		     The flags to ntpdate(8), that is to say  the  name  of  the
		     server 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

     configXEnvironment
	     Configure the X display subsystem.

	     Variables: None

     diskPartitionEditor
	     Invokes the disk partition (MBR) editor.

	     Variables:

	     geometry
		    The disk geometry, as a cyls/heads/sectors formatted string.
		    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.

	     Note: Nothing is actually written to disk by this function,  a  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've 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 par-
	     tition (da0s1 being your DOS primary partition).  Now let's further
	     assume  that  you have 500MB 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 function might in-
	     volve setting the following variables:

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

	     da0s2-2=swap 131072 /
		    A 64MB swap partition.

	     da0s2-3=ufs 204800 /var
		    A 100MB /var file system.

	     da0s2-4=ufs 0 /usr 1
		    With  the  balance of free space (around 316MB) 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).

	     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 on
	     of the existing "canned" sets) with no user interaction.

	     Variables:

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

		     bin       The base binary distribution.

		     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.

		     crypto    Encryption binaries and libraries.

		     compat1x  Compatibility with FreeBSD 1.x

		     compat20  Compatibility with FreeBSD 2.0

		     compat21  Compatibility with FreeBSD 2.1

		     compat22  FreeBSD 2.2 and FreeBSD 3.0 a.out binary compati-
			       bility

		     compat3x  Compatibility with  FreeBSD  3.x  (available  for
			       FreeBSD 4.0 systems only)

		     compat4x  Compatibility  with  FreeBSD  4.x  (available for
			       earlier releases of FreeBSD 4.x)

		     ports     The ports collection.

		     krb4      KerberosIV binaries.

		     krb5      Kerberos5 binaries.

		     ssecure   /usr/src/secure

		     sbase     /usr/src/[top level files]

		     scontrib  /usr/src/contrib

		     sgnu      /usr/src/gnu

		     setc      /usr/src/etc

		     sgames    /usr/src/games

		     sinclude  /usr/src/include

		     slib      /usr/src/lib

		     slibexec  /usr/src/libexec

		     srelease  /usr/src/release

		     sbin      /usr/src/bin

		     ssbin     /usr/src/sbin

		     sshare    /usr/src/share

		     ssys      /usr/src/sys

		     subin     /usr/src/usr.bin

		     susbin    /usr/src/usr.sbin

		     ssmailcf  /usr/src/usr.sbin/sendmail/cf

		     XF86-xc   XFree86 official sources.

		     XF86-co   XFree86 contributed sources.

		     Xbin      XFree86 binaries.

		     Xcfg      XFree86 configuration files.

		     Xdoc      XFree86 documentation.

		     Xhtml     XFree86 HTML documentation.

		     Xlib      XFree86 libraries.

		     Xlk98     XFree86 server link-kit for PC98 machines.

		     Xlkit     XFree86 server link-kit for standard machines.

		     Xman      XFree86 manual pages.

		     Xprog     XFree86 programmer's distribution.

		     Xps       XFree86 postscript documentation.

		     Xset      XFree86 graphical setup tool.

		     PC98-Servers/X9480
			       XFree86 PC98 8-bit (256 color) PEGC-480 server.

		     PC98-Servers/X9EGC
			       XFree86 PC98 4-bit (16 color) EGC server.

		     PC98-Servers/X9GA9
			       XFree86 PC98 GA-968V4/PCI (S3 968) server.

		     PC98-Servers/X9GAN
			       XFree86 PC98 GANB-WAP (cirrus) server.

		     PC98-Servers/X9LPW
			       XFree86 PC98 PowerWindowLB (S3) server.

		     PC98-Servers/X9MGA
			       [DESCRIPTION MISSING]

		     PC98-Servers/X9NKV
			       XFree86 PC98 NKV-NEC (cirrus) server.

		     PC98-Servers/X9NS3
			       XFree86 PC98 NEC (S3) server.

		     PC98-Servers/X9SPW
			       XFree86 PC98 SKB-PowerWindow (S3) server.

		     PC98-Servers/X9SVG
			       [DESCRIPTION MISSING]

		     PC98-Servers/X9TGU
			       XFree86 PC98 Cyber9320 and TGUI9680 server.

		     PC98-Servers/X9WEP
			       XFree86 PC98 WAB-EP (cirrus) server.

		     PC98-Servers/X9WS
			       XFree86 PC98 WABS (cirrus) server.

		     PC98-Servers/X9WSN
			       XFree86 PC98 WSN-A2F (cirrus) server.

		     Servers/X3DL
			       XFree86 3D Labs server.

		     Servers/X8514
			       XFree86 8514 server.

		     Servers/XAGX
			       XFree86 8 bit AGX server.

		     Servers/XI128
			       XFree86 #9 Imagine I128 server.

		     Servers/XMa8
			       XFree86 ATI Mach8 server.

		     Servers/XMa32
			       XFree86 ATI Mach32 server.

		     Servers/XMa64
			       XFree86 ATI Mach64 server.

		     Servers/XMono
			       XFree86 monochrome server.

		     Servers/XP9K
			       XFree86 P9000 server.

		     Servers/XS3
			       XFree86 S3 server.

		     Servers/XS3V
			       XFree86 S3 Virge server.

		     Servers/XSVGA
			       XFree86 SVGA server.

		     Servers/XVG16
			       XFree86 VGA16 server.

		     Servers/XW32
			       XFree86 ET4000/W32, /W32i and /W32p server.

		     Servers/XTGA
			       Server for TGA cards (alpha architecture only).

		     Servers/Xnest
			       XFree86 nested X server.

		     Servers/Xvfb
			       XFree86 virtual frame-buffer X server.

		     Xfnts     XFree86 base font set.

		     Xf100     XFree86 100DPI font set.

		     Xfcyr     XFree86 Cyrillic font set.

		     Xfscl     XFree86 scalable font set.

		     Xfnon     XFree86 non-english font set.

		     Xfsrv     XFree86 font server.

     distSetDeveloper
	     Selects the standard Developer's distribution set.

	     Variables: None

     distSetXDeveloper
	     Selects the standard X Developer's distribution set.

	     Variables: None

     distSetKernDeveloper
	     Selects the standard kernel Developer's distribution set.

	     Variables: None

     distSetUser
	     Selects the standard user distribution set.

	     Variables: None

     distSetXUser
	     Selects the standard X user's distribution set.

	     Variables: None

     distSetMinimum
	     Selects the very minimum distribution set.

	     Variables: None

     distSetEverything
	     Selects the full whack - all available distributions.

	     Variables: None

     distSetCRYPTO
	     Interactively select encryption subcomponents.

	     Variables: None

     distSetSrc
	     Interactively select source subcomponents.

	     Variables: None

     distSetXF86
	     Interactively select XFree86 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 lynx package.

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

     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

     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.

     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

     mediaSetTape
	     Select a tape device as the installation media.

	     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're	 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're 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're 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, medium 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 and terminate sysinstall.

	     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's  available until/unless a relatively full system in-
		     stallation has just been done.

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/release/sysinstall/install.cfg for a sample installation script.

BUGS
     This  utility is a prototype which lasted several years past its expiration
     date and is greatly in need of death.

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

HISTORY
     This version of sysinstall first appeared in FreeBSD 2.0.

FreeBSD 4.6			 August 9, 1997 		   SYSINSTALL(8)

home | help