2 .\" Jordan Hubbard <jkh@FreeBSD.org>. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY Jordan Hubbard AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL Jordan Hubbard OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .Nd system installation and configuration tool
40 is a utility for installing and configuring
43 It is the first utility invoked by the
46 floppy and is also copied into
50 systems for use in later configuring the system.
54 program is generally invoked without arguments for the default
55 behavior, where the main installation/configuration menu is presented.
57 On those occasions where it is deemed necessary to invoke a subsystem
58 of sysinstall directly, however, it is also possible to do so by
59 naming the appropriate function entry points on the command line.
60 Since this action is essentially identical to running an installation
61 script, each command-line argument corresponding to a line of script,
62 the reader is encouraged to read the section on scripting for more
63 information on this feature.
67 is essentially nothing more than a monolithic C program with
68 the ability to write MBRs and disk labels (through the services
71 library) and install distributions or packages onto new and
74 systems. It also contains some extra intelligence
75 for running as a replacement for
77 when it's invoked by the
79 installation boot procedure. It
80 assumes very little in the way of additional utility support and
81 performs most file system operations by calling the relevant syscalls
89 library to do user interaction with simple ANSI line graphics, color
90 support for which is enabled by either running on a syscons VTY or some
91 other color-capable terminal emulator (newer versions of xterm will support
96 This product is currently at the end of its life cycle and will
97 eventually be replaced.
100 may be either driven interactively through its various internal menus
101 or run in batch mode, driven by an external script. Such a script may
102 be loaded and executed in one of 3 ways:
104 .Bl -tag -width Ds -compact
105 .It Sy "LOAD_CONFIG_FILE"
108 is compiled with LOAD_CONFIG_FILE set in the environment
109 (or in the Makefile) to some value, then that value will
110 be used as the filename to automatically look for and load
113 starts up and with no user interaction required.
114 This option is aimed primarily at large sites who wish to create a
115 single prototype install for multiple machines with largely identical
116 configurations and/or installation options.
121 is run interactively, that is to say in the default manner, it will
122 bring up a main menu which contains a "load config file" option.
123 Selecting this option will prompt for the name of a script file which
124 it then will attempt to load from a DOS or UFS formatted floppy.
126 .It Sy "COMMAND LINE"
127 Each command line argument is treated as a script directive
130 is run in multi-user mode. Execution ends either by explicit request
133 directive), upon reaching the end of the argument list or on error.
138 /stand/sysinstall _ftpPath=ftp://ziggy/pub/ mediaSetFTP configPackages
143 for FTP installation media (using the server `ziggy') and then
144 bring up the package installation editor, exiting when finished.
148 A script is a list of one or more directives, each directive taking
160 is the assignment of some internal
162 variable, e.g. "ftpPass=FuNkYChiKn", and
164 is the name of an internal
166 function, e.g. "mediaSetFTP", and
168 is a single-line comment for documentation purposes (ignored by
169 sysinstall). Each directive must be by itself on a single line,
170 functions taking their arguments by examining known variable names.
171 This requires that you be sure to assign the relevant variables before
172 calling a function which requires them. When and where a function
173 depends on the settings of one or more variables will be noted in the
177 \fBFunction Glossary:\fR
179 .Bl -tag -width indent
181 Invoke the Anonymous FTP configuration menu.
183 \fBVariables:\fR None
185 Select which routing daemon you wish to use, potentially
186 loading any required 3rd-party routing daemons as necessary.
189 .Bl -tag -width indent
191 can be set to the name of the desired routing daemon,
196 otherwise it is prompted for.
199 Configure host as an NFS server.
201 \fBVariables:\fR None
203 Configure host as a user of the Network Time Protocol.
206 .Bl -tag -width indent
210 that is to say the name of the server to sync from.
213 Configure host to support PC NFS.
216 .Bl -tag -width indent
218 The name of the PCNFSD package to load if necessary (defaults to hard coded
222 Bring up the interactive package management menu.
224 \fBVariables:\fR None
226 Add users and/or groups to the system.
228 \fBVariables:\fR None
229 .It configXEnvironment
230 Configure the X display subsystem.
232 \fBVariables:\fR None
233 .It diskPartitionEditor
234 Invokes the disk partition (MBR) editor.
237 .Bl -tag -width findx
239 The disk geometry, as a cyls/heads/sectors formatted string. Default: no
242 Set to disk partitioning type or size, its value being
244 in order to use only remaining free space for
247 to use the entire disk for
249 but maintain a proper partition
254 partition (first found),
257 .Dq dangerously dedicated
262 blocks of available free space to a new
265 Default: Interactive mode.
269 to signify the installation of a boot manager,
271 to signify installation of a "standard" non-boot MGR DOS
274 to indicate that no change to the boot manager is desired.
278 Note: Nothing is actually written to disk by this function, a explicit call to
279 .Ar diskPartitionWrite
280 being required for that to happen.
281 .It diskPartitionWrite
282 Causes any pending MBR changes (typically from the
283 .Ar diskPartitionEditor
284 function) to be written out.
286 \fBVariables:\fR None
288 Invokes the disk label editor. This is a bit trickier from a script
289 since you need to essentially label everything inside each
291 (type 0xA5) partition created by the
292 .Ar diskPartitionEditor
293 function, and that requires knowing a few rules about how things are
294 laid out. When creating a script to automatically allocate disk space
295 and partition it up, it is suggested that you first perform the
296 installation interactively at least once and take careful notes as to
297 what the slice names will be, then and only then hardwiring them into
300 For example, let's say you have a SCSI disk on which you've created a new
302 partition in slice 2 (your DOS partition residing in slice 1).
303 The slice name would be
309 being your DOS primary
310 partition). Now let's further assume that you have 500MB in this
311 partition and you want to sub-partition that space into root, swap,
312 var and usr file systems for
314 Your invocation of the
316 function might involve setting the following variables:
317 .Bl -tag -width findx
318 .It Li "da0s2-1=ufs 40960 /"
319 A 20MB root file system (all sizes are in 512 byte blocks).
320 .It Li "da0s2-2=swap 131072 /"
321 A 64MB swap partition.
322 .It Li "da0s2-3=ufs 204800 /var"
323 A 100MB /var file system.
324 .It Li "da0s2-4=ufs 0 /usr"
325 With the balance of free space (around 316MB) going to the /usr
331 for mounting or erasing existing partitions as well as creating new
332 ones. Using the previous example again, let's say that we also wanted
333 to mount our DOS partition and make sure that an
335 entry is created for it in the new installation. Before calling the
337 function, we simply add an additional line:
342 before the call. This tells the label editor that you want to mount
345 and not to attempt to newfs it (not that
347 would attempt this for a DOS partition in any case, but it could just
348 as easily be an existing UFS partition being named here and the 2nd
349 field is non-optional).
351 Note: No file system data is actually written to disk until an
356 Writes out all pending disklabel information and creates and/or mounts any
357 file systems which have requests pending from the
361 \fBVariables:\fR None
363 Resets all selected distributions to the empty set (no distributions selected).
365 \fBVariables:\fR None
367 Allows the selection of a custom distribution set (e.g. not just on of the
368 existing "canned" sets) with no user interaction.
371 .Bl -tag -width indent
373 List of distributions to load. Possible distribution values are:
374 .Bl -tag -width indentxx
376 The base binary distribution.
378 Miscellaneous documentation
382 Manual pages (unformatted)
384 Pre-formatted manual pages
386 Profiled libraries for developers.
388 Dictionary information (for tools like spell).
390 GNU info files and other extra docs.
392 DES encryption binaries and libraries.
406 a.out binary compatibility
414 The ports collection.
420 /usr/src/[top level files]
450 /usr/src/usr.sbin/sendmail/cf
452 XFree86 official sources.
454 XFree86 contributed sources.
456 XFree86 3.3.5 binaries.
458 XFree86 3.3.5 configuration files.
460 XFree86 3.3.5 documentation.
462 XFree86 3.3.5 HTML documentation.
464 XFree86 3.3.5 libraries.
466 XFree86 3.3.5 server link-kit for PC98 machines.
468 XFree86 3.3.5 server link-kit for standard machines.
470 XFree86 3.3.5 manual pages.
472 XFree86 3.3.5 programmer's distribution.
474 XFree86 3.3.5 postscript documentation.
476 XFree86 3.3.5 graphical setup tool.
478 XFree86 3.3.5 8514 server.
480 XFree86 3.3.5 PC98 8-bit (256 color) PEGC-480 server.
482 XFree86 3.3.5 PC98 4-bit (16 color) EGC server.
484 XFree86 3.3.5 PC98 GA-968V4/PCI (S3 968) server.
486 XFree86 3.3.5 PC98 GANB-WAP (cirrus) server.
488 XFree86 3.3.5 PC98 PowerWindowLB (S3) server.
490 XFree86 3.3.5 PC98 NKV-NEC (cirrus) server.
492 XFree86 3.3.5 PC98 NEC (S3) server.
494 XFree86 3.3.5 PC98 SKB-PowerWindow (S3) server.
496 XFree86 3.3.5 PC98 Cyber9320 and TGUI9680 server.
498 XFree86 3.3.5 PC98 WAB-EP (cirrus) server.
500 XFree86 3.3.5 PC98 WABS (cirrus) server.
502 XFree86 3.3.5 PC98 WSN-A2F (cirrus) server.
504 XFree86 3.3.5 8 bit AGX server.
506 XFree86 3.3.5 #9 Imagine I128 server.
508 XFree86 3.3.5 ATI Mach8 server.
510 XFree86 3.3.5 ATI Mach32 server.
512 XFree86 3.3.5 ATI Mach64 server.
514 XFree86 3.3.5 monochrome server.
516 XFree86 3.3.5 P9000 server.
518 XFree86 3.3.5 S3 server.
520 XFree86 3.3.5 S3 Virge server.
522 XFree86 3.3.5 SVGA server.
524 XFree86 3.3.5 VGA16 server.
526 XFree86 3.3.5 ET4000/W32, /W32i and /W32p server.
528 Server for TGA cards (alpha architecture only).
530 XFree86 3.3.5 nested X server.
532 XFree86 3.3.5 virtual frame-buffer X server.
534 XFree86 3.3.5 base font set.
536 XFree86 3.3.5 100DPI font set.
538 XFree86 3.3.5 Cyrillic font set.
540 XFree86 3.3.5 scalable font set.
542 XFree86 3.3.5 non-english font set.
544 XFree86 3.3.5 font server.
547 Selects the standard Developer's distribution set.
549 \fBVariables:\fR None
550 .It distSetXDeveloper
551 Selects the standard X Developer's distribution set.
553 \fBVariables:\fR None
554 .It distSetKernDeveloper
555 Selects the standard kernel Developer's distribution set.
557 \fBVariables:\fR None
559 Selects the standard user distribution set.
561 \fBVariables:\fR None
563 Selects the standard X user's distribution set.
565 \fBVariables:\fR None
567 Selects the very minimum distribution set.
569 \fBVariables:\fR None
570 .It distSetEverything
571 Selects the full whack - all available distributions.
573 \fBVariables:\fR None
575 Interactively select DES subcomponents.
577 \fBVariables:\fR None
579 Interactively select source subcomponents.
581 \fBVariables:\fR None
583 Interactively select XFree86 3.3.5 subcomponents.
585 \fBVariables:\fR None
587 Install all currently selected distributions (requires that
588 media device also be selected).
590 \fBVariables:\fR None
592 Install (if necessary) an HTML documentation browser and go to the
593 HTML documentation submenu.
596 .Bl -tag -width indent
598 The name of the browser package to try and install as necessary.
599 Defaults to latest lynx package.
601 The name of the browser binary itself (if overriding the
603 variable). Defaults to lynx.
607 Commit any and all pending changes to disk. This function
608 is essentially shorthand for a number of more granular "commit"
611 \fBVariables:\fR None
613 Start an "express" installation, asking few questions of
616 \fBVariables:\fR None
618 Start a "novice" installation, the most user-friendly
619 installation type available.
621 \fBVariables:\fR None
623 Start an upgrade installation.
625 \fBVariables:\fR None
626 .It installFixitHoloShell
627 Start up the "emergency holographic shell" over on VTY4
630 \fBVariables:\fR None
631 .It installFixitCDROM
632 Go into "fixit" mode, assuming a live file system CDROM
633 currently in the drive.
635 \fBVariables:\fR None
636 .It installFixitFloppy
637 Go into "fixit" mode, assuming an available fixit floppy
638 disk (user will be prompted for it).
640 \fBVariables:\fR None
641 .It installFilesystems
642 Do just the file system initialization part of an install.
644 \fBVariables:\fR None
645 .It installVarDefaults
646 Initialize all variables to their defaults, overriding any
649 \fBVariables:\fR None
651 Sort of like an #include statement, it allows you to load one
652 configuration file from another.
655 .Bl -tag -width indent
657 The fully pathname of the file to load.
662 CDROM as the installation media.
664 \fBVariables:\fR None
666 Select a pre-made floppy installation set as the installation media.
668 \fBVariables:\fR None
670 Select an existing DOS primary partition as the installation media.
671 The first primary partition found is used (e.g. C:).
673 \fBVariables:\fR None
675 Select a tape device as the installation media.
677 \fBVariables:\fR None
679 Select an FTP site as the installation media.
682 .Bl -tag -width indent
684 The name of the host being installed (non-optional).
686 The domain name of the host being installed (optional).
688 The default router for this host (non-optional).
690 Which host interface to use
694 for example. Non-optional).
696 If set, bring up the interactive network setup form even
697 if all relevant configuration variables are already set (optional).
699 The IP address for the selected host interface (non-optional).
701 The netmask for the selected host interface (non-optional).
703 The fully qualified URL of the FTP site containing the
705 distribution you're interested in, e.g.
706 .Ar ftp://ftp.FreeBSD.org/pub/FreeBSD/ .
708 .It mediaSetFTPActive
711 using "active" FTP transfer mode.
713 \fBVariables:\fR Same as for
715 .It mediaSetFTPPassive
718 using "passive" FTP transfer mode.
720 \fBVariables:\fR Same as for
723 Select an existing UFS partition (mounted with the label editor) as
724 the installation media.
727 .Bl -tag -width indent
729 full /path to directory containing the
737 .Bl -tag -width indent
739 The name of the host being installed (non-optional).
741 The domain name of the host being installed (optional).
743 The default router for this host (non-optional).
745 Which host interface to use
749 for example. Non-optional).
751 If set, bring up the interactive network setup form even
752 if all relevant configuration variables are already set (optional).
754 The IP address for the selected host interface (non-optional).
756 The netmask for the selected host interface (non-optional).
758 full hostname:/path specification for directory containing
761 distribution you're interested in.
763 .It mediaSetFTPUserPass
766 .Bl -tag -width indent
768 The username to log in as on the ftp server site.
771 The password to use for this username on the ftp
775 .It mediaSetCPIOVerbosity
778 .Bl -tag -width indent
780 Can be used to set the verbosity of cpio extractions to low, medium or
784 Interactively get the user to specify some type of media.
786 \fBVariables:\fR None
788 Invoke the interactive options editor.
790 \fBVariables:\fR None
792 Try to fetch and add a package to the system (requires
793 that a media type be set),
796 .Bl -tag -width indent
798 The name of the package to add, e.g. bash-1.14.7 or ncftp-2.4.2.
801 Invoke the interactive group editor.
803 \fBVariables:\fR None
805 Invoke the interactive user editor.
807 \fBVariables:\fR None
809 Stop the script and terminate sysinstall.
811 \fBVariables:\fR None
813 Execute an arbitrary command with
817 .Bl -tag -width indent
819 The name of the command to execute. When running
820 from a boot floppy, very minimal expectations should
821 be made as to what's available until/unless a relatively
822 full system installation has just been done.
826 This utility may edit the contents of
831 as necessary to reflect changes in the network configuration.
833 If you have a reasonably complete source tree online, take
835 .Pa /usr/src/release/sysinstall/install.cfg
836 for a sample installation script.
838 This utility is a prototype which lasted several years past
839 its expiration date and is greatly in need of death.
841 .An Jordan K. Hubbard Aq jkh@FreeBSD.org