Creating an Automated Installation with pc-sysinstall/10.0
(Sorry for the inconvenience)
PC-BSD® provides a set of Bourne shell scripts that allow advanced users to create automatic or customized PC-BSD® installations. pc-sysinstall is the name of the master script; it reads a customizable configuration file and uses dozens of backend scripts to perform the installation. You can read more about this utility by typing man pc-sysinstall.
Here is a quick overview of the components used by pc-sysinstall:
- /usr/local/share/pc-sysinstall/backend/ contains the scripts used by the PC-BSD® installer. Scripts have been divided by function, such as functions-bsdlabel.sh and functions-installcomponents.sh. If you have ever wondered how the PC-BSD® installer works, read through these scripts. This directory also contains the parseconfig.sh and startautoinstall.sh scripts which pc-sysinstall uses to parse the configuration file and begin the installation.
- /usr/local/share/pc-sysinstall/backend-partmanager/ contains the scripts which are used by the installer to create and delete partitions.
- /usr/local/share/pc-sysinstall/backend-query/ contains the scripts which are used by the installer to detect and configure hardware.
- /usr/local/share/pc-sysinstall/conf/ contains the configuration file pc-sysinstall.conf. It also contains a file indicating which localizations are available (avail-langs), and a licenses/ subdirectory containing text files of applicable licenses.
- /usr/local/share/pc-sysinstall/doc/ contains the help text that is seen if you run pc-sysinstall without any arguments.
- /usr/local/share/pc-sysinstall/examples/ contains several example configuration files for different scenarios (e.g. upgrade, fbsd-netinstall). The README file in this directory should be considered as mandatory reading before using pc-sysinstall.
- /usr/sbin/pc-sysinstall this is the script that is used to perform a customized installation.
To create a custom installation, perform the following steps:
- Determine which variables you wish to customize.
- Create a customized configuration.
- Create a custom installation media.
These steps are discussed in more detail below.
Determine Which Variables you Wish to Customize
A list of possible variables can be found in /usr/local/share/pc-sysinstall/examples/README and in Table 5.6a. Note that the Table is meant as a quick reference to determine which variables are available. The README file contains more complete descriptions for each variable.
|hostname=||should be unique for the network||optional as installer will auto-generate a hostname if empty|
|installMode=||fresh, upgrade, extract, or zfsrestore||sets the installation type|
|installLocation=||/path/to/location||used only when installMode is extract and should point to an already mounted location|
|installInteractive=||yes or no||set to no for automated installs without user input|
|netDev=||AUTO-DHCP or FreeBSD interface name||type of network connection to use during the installation|
|netIP=||IP address of interface used during installation||only use if netDev is set to an interface name|
|netMask=||subnet mask of interface||only use if netDev is set to an interface name|
|netNameServer=||IP address of DNS server||only use if netDev is set to an interface name|
|netDefaultRouter=||IP address of default gateway||only use if netDev is set to an interface name|
|netSaveDev=||AUTO-DHCP or FreeBSD interface name(s) (multiple allowed separated by spaces)||type of network configuration to enable on the installed system; can set multiple interfaces|
|netSaveIP=||IP address of interface <interface_name> or DHCP||only use if netSaveDev is set to an interface name or a list of interface names (repeat for each interface)|
|netSaveMask=||subnet mask of interface <interface_name>||only use if netSaveDev is set to an interface name or a list of interface names (repeat for each interface)|
|netSaveNameServer=||IP address of DNS server (multiple allowed separated by spaces)||only use if netSaveDev is set to an interface name or a list of interface names (do not repeat for each interface)|
|netSaveDefaultRouter=||IP address of default gateway||only use if netSaveDev is set to an interface name or a list of interface names (do not repeat for each interface)|
|disk0=||FreeBSD disk device Name, (e.g. ad0)||see README for examples|
|partition=||all, free, s1, s2, s3, s4, image||see README for examples|
|partscheme=||MBR or GPT||partition scheme type|
|mirror=||FreeBSD disk device name (e.g. ad1)||sets the target disk for the mirror (i.e. the second disk)|
|mirrorbal=||load, prefer, round-robin, split||defaults to round-robin if the mirrorbal method is not specified|
|bootManager=||none, bsd, GRUB||when using GRUB, include its package in installPackages=|
|image=||/path/to/image||will write specified image file|
|commitDiskPart||this variable is mandatory and must be placed at the end of each diskX section; create a diskX section for each disk you wish to configure.|
|encpass=||password value||at boot time, system will prompt for this password in order to mount the associated GELI encrypted partition|
|commitDiskLabel||this variable is mandatory and must be placed at the end of disk's partitioning settings; see the README for examples on how to set the <File System Type> <Size> <Mountpoint> entries for each disk|
|installMedium=||dvd, usb, ftp, rsync, image||source to be used for installation|
|localPath=||/path/to/files||location of directory containing installation files|
|installType=||PCBSD, FreeBSD||determines whether this is a desktop or a server install|
|installFile=||e.g. fbsd-release.tbz||only set if using a customized installer archive|
|packageType=||tar, uzip, split, dist||the archive type on the installation media|
|distFiles=||base src kernel doc games||list of FreeBSD distribution files to install when using packageType=dist|
|ftpPath=||e.g. ftp://iso.cdn.pcbsd.org/9.1/amd64/netinstall/||location of the installer archive when using installMedium=ftp|
|rsyncPath=||e.g. life-preserver/back-2011-09-12T14_53_14||location of the rsync data on the remote server when using installMedium=rsync|
|rsyncUser=||username||set when using installMedium=rsync|
|rsyncHost=||IP address of rsync server||set when using installMedium=rsync|
|rsyncPort=||port number||set when using installMedium=rsync|
|installComponents=||e.g. amarok,firefox,ports||components must exist in /PCBSD/pc-sysinstall/components/; typically, installPackages= is used instead|
|installPackages=||e.g. Xorg cabextract||list of traditional or pkgng packages to install; requires pkgExt=|
|pkgExt=||txz, tbz||specify the extension used by the type of package to be installed|
|upgradeKeepDesktopProfile=||yes or no||specify if you wish to keep your existing user's desktop profile data during an upgrade|
|rootPass=||password||set the root password of the installed system to the specified string|
|rootEncPass=||encrypted string||set root password to specified encrypted string|
|userName=||case sensitive value||create a separate block of user values for each user you wish to create|
|userComment=||description||description text can include spaces|
|userPass=||password of user|
|userEncPass||encrypted string||set user password to specified encrypted string|
|userShell=||e.g. /bin/csh||path to default shell|
|userHome=||e.g. /home/username||path to home directory|
|userGroups=||e.g. wheel,operator||comma separated (no spaces) list of groups|
|commitUser||mandatory, must be last line in each user block|
|runCommand=||path to command||run the specified command within chroot of the installed system, after the installation is complete|
|runScript=||path to script||runs specified script within chroot of the installed system, after the installation is complete|
|runExtCommand=||path to command||runs a command outside the chroot|
|timeZone=||e.g. America/New_York||location must exist in /usr/share/zoneinfo/|
|enableNTP=||yes or no||enable/disable NTP|
|localizeLang=||e.g. en||sets the system console and Desktop to the target language|
|localizeKeyLayout=||e.g. en||updates the system's Xorg config to set the keyboard layout|
|localizeKeyModel=||e.g. pc104||updates the system's Xorg config to set the keyboard model|
|localizeKeyVariant=||e.g. intl||updates the Xorg config to set the keyboard variant|
|autoLoginUser=||username||user will be logged in automatically without entering a password|
|sshHost=||hostname or IP address||the address of the remote server when using installMode=zfsrestore|
|sshPort=||e.g 22||the SSH port number of the remote server when using installMode=zfsrestore|
|sshUser=||string||the username on the remote server when using installMode=zfsrestore|
|sshKey=||e.g. /root/id_rsa||path to the SSH key file on the remote server when using installMode=zfsrestore|
|zfsProps=||e.g. .lp-props-tank#backups#mybackup||location of dataset properties file created by Life Preserver during replication when using installMode=zfsrestore|
|zfsRemoteDataset=||e.g. tank/backups/mybackup||location of remote dataset to restore from when using installMode=zfsrestore|
Create a Customized Configuration
One way to create a customized configuration file is to read through the configuration examples in /usr/local/share/pc-sysinstall/examples/ to find the one that most closely matches your needs. Copy that file to any location and customize it so that it includes the variables and values you would like to use in your installation.
An alternate way to create this file is to start an installation, configure the system as desired, and save the configuration to a USB stick (with or without actually performing the installation). You can use that saved configuration file as-is or customize it to meet an installation's needs. This method may prove easier to use if you are performing complex disk layouts.
If you wish to perform a fully-automated installation that does not prompt for any user input, you will also need to review /usr/local/share/pc-sysinstall/examples/pc-autoinstall.conf and place a customized copy of that file into /boot/pc-autoinstall.conf on your installation media.
Table 5.6b summarizes the additional variables that are available for fully automatic installations. More detailed descriptions can be found in the /usr/local/share/pc-sysinstall/examples/pc-autoinstall.conf file. Note that the variables in this file use a different syntax than those in Table 5.6a, in that the values follow a colon and a space rather than an equal sign.
|pc_config||URL or /path/to/file||location of customized pc-sysinstall.conf|
|confirm_install||yes or no||should be set to yes, otherwise booting the wrong disk will result in a system wipe|
|shutdown_cmd||e.g. shutdown -p now||good idea to run a shutdown, but can be any command/script you wish to execute post-install|
|nic_config||dhcp-all or <interface name> <IP address> <subnet mask>||will attempt dhcp on all found NICs until the installation file can be fetched or will setup specified interface|
|nic_dns||DNS server to use|
|nic_gateway||IP address||default gateway to use|
Create a Custom Installation Media or Installation Server
pc-sysinstall supports the following installation methods:
- from a CD, DVD, or USB media
- from an installation directory on an HTTP, FTP, SSH+rsync, or a PXE Boot Install server
The easiest way to create a custom installation media is to modify an existing installation image. For example, if you have downloaded an ISO for the PC-BSD® version that you wish to customize, the superuser can access the contents of the ISO as follows:
Make sure you have changed into a directory (use cd) where you would like to copy the contents of the ISO. In the following examples, /tmp/custominstall/ was created as the directory for this purpose:
tar -C /mnt -cf - . | tar -xvf -umount /mnt
Alternately, if you have inserted an installation CD or DVD, you can mount the media and copy its contents to your desired directory:
cp -R /mnt/* /tmp/custominstall/umount /mnt
If you are creating an automated installation, copy your customized pc-autoinstall.conf to /tmp/custominstall/boot/.
Copy your customized configuration file to /tmp/custominstall/. Double-check that the "installMedium=" variable in your customized configuration file is set to the type of media that you will be installing from.
You may also need to add some extra files if you set the following variables in your custom configuration file:
- installComponents= make sure that any extra components you wish to install exist in extras/PBI/ (if they end in the .pbi extension) or extras/components/ (if they end in .tbz)
- runCommand= make sure the command exists in the specified path
- runScript= make sure the script exists in the specified path
- runExtCommand= make sure the command exists in the specified path
If the installation media is a CD or DVD, you will need to create a bootable media that contains the files in your directory. To create a bootable ISO:
You can then use your favorite burning utility to burn the ISO to the media.
To begin an installation that requires user interaction:
pc-sysinstall -c /path_to_your_config_file
To begin a fully automated installation, insert the installation media and reboot.
If you are using an HTTP, FTP, or SSH server as the installation media, untar or copy the required files to a directory on the server that is accessible to users. Be sure to configure the server so that the installation files are accessible to the systems that you wish to install. If you are using a PXE Boot Install server, follow the instructions at Connecting to and Customizing the PXE Boot Install Server.
List of Tables
- Table 5.6a: Available Variables for Customizing a PC-BSD® Installation
- Table 5.6b: Additional Variables for Automated Installations