Difference between revisions of "Creating an Automated Installation with pc-sysinstall/9.2"

From PC-BSD Wiki
Jump to: navigation, search
(Documentation update to fix http://trac.pcbsd.org/ticket/597 from config file changes introduced by http://trac.pcbsd.org/ticket/598)
Line 80: Line 80:
 
|-
 
|-
 
{{tbl-cellg|content=netSaveDev=}}
 
{{tbl-cellg|content=netSaveDev=}}
{{tbl-cellg|AUTO-DHCP or FreeBSD interface name}}
+
{{tbl-cellg|AUTO-DHCP or FreeBSD interface name(s) (multiple allowed separated by spaces)}}
 
{{tbl-cellg|content=type of network configuration to enable on the installed system; can set multiple interfaces}}
 
{{tbl-cellg|content=type of network configuration to enable on the installed system; can set multiple interfaces}}
 
|-
 
|-
{{tbl-cellw|content=netSaveIP=}}
+
{{tbl-cellw|content=netSaveIP_''interface name''=}}
{{tbl-cellw|IP address of interface}}
+
{{tbl-cellw|IP address of interface ''interface name'' or DHCP}}
{{tbl-cellw|content=only use if netSaveDev= is set to an interface name}}
+
{{tbl-cellw|content=only use if netSaveDev= is set to an interface name or a list of interface names (repeat for each interface)}}
 
|-
 
|-
{{tbl-cellg|content=netSaveMask=}}
+
{{tbl-cellg|content=netSaveMask_''interface name''=}}
{{tbl-cellg|subnet mask of interface}}
+
{{tbl-cellg|subnet mask of interface ''interface name''}}
{{tbl-cellg|content=only use if netSaveDev= is set to an interface name}}
+
{{tbl-cellg|content=only use if netSaveDev= is set to an interface name or a list of interface names (repeat for each interface)}}
 
|-
 
|-
 
{{tbl-cellw|content=netSaveNameServer=}}
 
{{tbl-cellw|content=netSaveNameServer=}}
{{tbl-cellw|IP address of DNS server}}
+
{{tbl-cellw|IP address of DNS server (multiple allowed separated by spaces)}}
{{tbl-cellw|content=only use if netSaveDev= is set to an interface name}}
+
{{tbl-cellw|content=only use if netSaveDev= is set to an interface name or a list of interface names (do not repeat for each interface)}}
 
|-
 
|-
 
{{tbl-cellg|content=netSaveDefaultRouter=}}
 
{{tbl-cellg|content=netSaveDefaultRouter=}}
 
{{tbl-cellg|IP address of default gateway}}
 
{{tbl-cellg|IP address of default gateway}}
{{tbl-cellg|content=only use if netSaveDev= is set to an interface name}}
+
{{tbl-cellg|content=only use if netSaveDev= is set to an interface name or a list of interface names (do not repeat for each interface)}}
 
|-
 
|-
 
{{tbl-cellw|content=disk0=}}
 
{{tbl-cellw|content=disk0=}}

Revision as of 06:44, 5 April 2012

(Sorry for the inconvenience)

Contents

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/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've 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/share/pc-sysinstall/backend-partmanager/ contains the scripts which are used by the installer to create and delete partitions.
  • /usr/share/pc-sysinstall/backend-query/ contains the scripts which are used by the installer to detect (e.g. detect-nics.sh) and configure (e.g. enable-net.sh) hardware.
  • /usr/share/pc-sysinstall/conf/ contains the configuration file pc-sysinstall.conf. It also contains a file indicating which localizations are available (avail-langs), a list of files which aren't touched during an upgrade (exclude-from-upgrade), and a licenses/ subdirectory containing text files of applicable licenses (e.g. bsd-en.txt and nvidia-en.txt).
  • /usr/share/pc-sysinstall/doc/ contains the help text that is seen if you run pc-sysinstall without any arguments.
  • /usr/share/examples/pc-sysinstall/ 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.

NOTE: if you wish to start a customized installation from a non-PCBSD system, you can install pc-sysinstall by running the following command. Note that all files will be copied to the current directory. This command assumes that you are on a Unix-like system (e.g. Linux or Mac OS X) and that subversion is installed. You can install a Unix-like environment on a Windows system using Cygwin.

svn co svn://svn.pcbsd.org/pcbsd/stable/pc-sysinstall

To create a custom installation, perform the following steps:

1. Determine which variables you wish to customize.

2. Create a customized configuration.

3. 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/share/examples/pc-sysinstall/README and in Table 5.4a. 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.

Table 5.4a: Available Variables for Customizing a PC-BSD Installation

Variable Options Description
hostname= should be unique for the network optional as installer will auto-generate a hostname if empty
installMode= fresh, upgrade, or extract 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_interface name= 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_interface name= 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= disk device, such as ad0 see README for examples
partition= all, free, s1, s1, s3, s4, image see README for examples
partscheme= MBR or GPT partition scheme type
mirror= disk device such as ad1 sets the target disk for the mirror (e.g. the second disk)
mirrorbal= load, prefer, round-robin, split defaults to round-robin if the mirror balance method is not specified
bootManager= none, bsd
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.
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
installType= PCBSD, FreeBSD
installFile= e.g. fbsd-release.tbz only set if using a customized installer archive
packageType= tar, uzip, split the archive type on the installation media
ftpPath= e.g. ftp://ftp.pcbsd.org/pub/mirror/9.0/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
syncHost= 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/
upgradeKeepDesktopProfile= yes or no specify if you wish to keep your existing user's desktop profile data during an upgrade. The default is NO, and your existing profile will be moved to .kde4.preUpgrade automatically.
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= case sensitive value 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

Create a Customized Configuration

Read through the configuration examples in /usr/share/examples/pc-sysinstall/ 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.

If you wish to perform a fully automated installation that does not prompt for any user input, you will also need to review /usr/share/examples/pc-sysinstall/pc-autoinstall.conf and place a customized copy of that file into /boot/pc-autoinstall.conf on your installation media.

Table 5.4b summarizes the additional variables that are available for fully automatic installations. More detailed descriptions can be found in the /usr/share/examples/pc-sysinstall/pc-autoinstall.conf file. Note that the variables in this file use a different syntax than those in Table 5.4b (e.g. values follow a colon and space rather than the equals sign).

Table 5.4b.: Additional Variables for Automated Installations

Variable Options Description
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 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 IP address DNS server to use
nic_gateway IP address default gateway to use

Create a Custom Installation Media

The installation media can be a CD, DVD, USB, or a directory on an HTTP, FTP, or SSH+rsync 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 (CD or DVD) for the PC-BSD version that you wish to customize, the superuser can access the contents of the ISO as follows:

mdconfig -a -t vnode -f PCBSD9.0-x86-DVD.iso -u 1
mount -t cd9660 /dev/md1 /mnt

Make sure you have cd 'd into a directory where you would like to copy the contents of the ISO. In the following examples, /tmp/custominstall/ was created for this purpose:

cd /tmp/custominstall
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:

mount -t cd9660 /dev/cd0 /mnt
cp -R /mnt/* /tmp/custominstall/
umount /mnt

NOTE: if you are using an HTTP, FTP, or SSH server as the installation media, untar or copy the 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 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:

cd /tmp/custominstall
mkisofs -V mycustominstall -J -R -b boot/cdboot -no-emul-boot -o myinstall.iso

You can then use your favourite burning utility to burn the ISO to the CD or DVD 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.

In a PXE boot environment, cp your pc-sysinstall.conf file to /boot/. Then, setup a call in /etc/rc.local that runs this command:

pc-sysinstall start-autoinstall /boot/pc-autoinstall.conf

That will start the installation process, fetching your main configuration file and doing the actual installation.

Additional Reading

Installing FreeBSD with pc-sysinstall: pages 26-28, June 2011 issue of BSD Mag

Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox