sysinstall(8)

NAME

sysinstall - system installation and configuration tool

SYNOPSIS

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

DESCRIPTION

The sysinstall utility is used for installing and configur

ing FreeBSD
systems. It is the first utility invoked by the FreeBSD in

stallation
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 argu

ments 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 commandline 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 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 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 col

or 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
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 environment (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
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 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
explicit request (e.g. calling the shutdown direc

tive), upon
reaching the end of the argument list or on error.

For example:

/usr/sbin/sysinstall _ftpPath=ftp://ziggy/pub/ medi

aSetFTP configPackages

Would initialize sysinstall for FTP installation me

dia (using the
server `ziggy') and then bring up the package in

stallation 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 directive must be by itself on a single line, functions taking

their arguments
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 it

self 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, poten

tially loading
any required 3rd-party routing daemons as necessary.

Variables:

router can be set to the name of the desired rout

ing 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 Proto

col.

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
(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. 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, final

ly, somenumber
to allocate somenumber blocks of available

free space to a
new FreeBSD partition. Default: Interactive

mode.

bootManager

is set to one of boot to signify the instal

lation of a
boot manager, standard to signify installa

tion of a "standard" non-boot MGR DOS MBR or none to indi

cate that no
change to the boot manager is desired. De

fault: none.

diskInteractive

If set, bring up the interactive disk parti

tion 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 trick

ier from a
script since you need to essentially label every

thing 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 automati

cally 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 prima

ry 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 involve 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 en

abled (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 addition

al 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-op

tional).

You can also set the diskInteractive variable to re

quest that the
disk label editor use an interactive dialog to par

tition 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 distributions 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 in

teraction.

Variables:

dists List of distributions to load. Possible

distribution

values are:

base 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.

lib32 (amd64 only) 32-bit runtime com

patibility

libraries.

ports The ports collection.

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

skrb5 /usr/src/kerberos5

slib /usr/src/lib

slibexec /usr/src/libexec

srelease /usr/src/release

srescue /usr/src/rescue

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

Xbin X.Org client applications.

Xlib X.Org libraries.

Xman X.Org manual pages.

Xdoc X.Org protocol and library docu

mentation.

Xprog X.Org imake distribution.

Xsrv X.Org X server.

Xnest X.Org nested X server.

Xprt X.Org print server.

Xvfb X.Org virtual frame-buffer X serv

er.

Xfmsc X.Org miscellaneous font set.

Xf75 X.Org 75DPI font set.

Xf100 X.Org 100DPI font set.

Xfcyr X.Org Cyrillic font set.

Xft1 X.Org Type 1 font set.

Xftt X.Org TrueType font set.

Xfs X.Org 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 distribu

tions.

Variables: None

distSetSrc

Interactively select source subcomponents.

Variables: None

distSetXOrg

Interactively select X.Org subcomponents.

Variables: None

distExtractAll

Install all currently selected distributions (re

quires 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
necessary. Defaults to latest links pack

age.

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

installExpress

Start an "express" installation, asking few ques

tions of the
user.

Variables: None

installStandard

Start a "standard" installation, the most user

friendly installation 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
installation 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, overrid

ing any previous 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 in

stallation
media.

Variables: None

mediaSetDOS

Select an existing DOS primary partition as the in

stallation
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-op

tional).

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
(optional).

ipaddr The IP address for the selected host inter

face (non

optional).

netmask

The netmask for the selected host interface

(nonoptional).

_ftpPath

The fully qualified URL of the FTP site con

taining 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 distribu

tion 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-op

tional).

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
(optional).

ipaddr The IP address for the selected host inter

face (non

optional).

netmask

The netmask for the selected host interface

(nonoptional).

nfs full hostname:/path specification for direc

tory contain

ing the FreeBSD distribution you are inter

ested 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 ex

tractions 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 (re

quires 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 is available until/unless a rela

tively 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 architecture of

the contents
on this volume.

This property
is normally only

used with
FreeBSD products

that contain
CDs for different

architectures,
to provide better

error messages
if users try to in

stall Alpha
packages on an i386

machine.
For example,

``CD_MACHINE_ARCH =
alpha''.

CD_VOLUME In a multi-volume

collection

(such as the FreeB

SD 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 vol

ume 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
required dependencies. This index is

generated by
``make index'' from the ports(7) collec

tion. When
multi-volume support is enabled, an ad

ditional 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 net

work configuration.

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 in

stallation
script.

HISTORY

This version of sysinstall first appeared in FreeBSD 2.0.

AUTHORS

Jordan K. Hubbard <jkh@FreeBSD.org>

BUGS

This utility is a prototype which lasted several years past

its expiration date and is greatly in need of death.

BSD June 14, 2005

BSD