4. Advanced Installation Topics

The topics discussed in this chapter are intended for users that have a sound understanding with installing and manipulating open source software.

If the intent is to install a graphical desktop using the graphical installer, refer instead to the Install section.

4.1. Server Installation

The System Selection screen of the TrueOS® installer can be used to install a FreeBSD-based command-line server operating system rather than a graphical desktop operating system. A TrueOS® server installation includes the SysAdm™ API and SysAdm™ Client for managing the server locally or remotely.

For a server installation, using the TrueOS® installer rather than the FreeBSD installer offers several benefits:

  • The ability to easily configure ZFS during installation.
  • The ability to configure multiple boot environments.
  • A wizard (described in this section) is provided during installation to configure the server for first use.

To perform a server installation, start the TrueOS® installation as usual. At the System Selection screen of the installer, select TrueOS Server (console interface only).

Click Next to start the Server Setup Wizard, then click Next again to see the screen shown in Figure 4.1.1.

_images/server2b.png

Fig. 4.1.1 Root Password Creation

Input and confirm the root password then click Next to proceed to the screen shown in Figure 4.1.2.

_images/server3b.png

Fig. 4.1.2 Primary User Account Creation

For security reasons, do not login as the root user. The wizard requires creating a primary user account for logging into the server. This account is automatically added to the wheel group, allowing the user to su to the root account when administrative access is required.

Create an account by filling in these fields:

  • Name: Can contain capital letters and spaces.
  • Username: The name to use for logging in. It cannot contain spaces and is case sensitive (e.g. Kris is a different username than kris).
  • Password: The password to use for logging in. Type it twice to confirm it.
  • Default shell: Use the drop-down menu to select the csh, tcsh, sh, or bash login shell.

When finished, click Next to proceed to Figure 4.1.3.

_images/server4b.png

Fig. 4.1.3 Hostname Creation

Input the system’s hostname. If using ssh to connect to the system, check Enable remote SSH login. Click Next to proceed to the network configuration screen shown in Figure 4.1.4.

_images/server5b.png

Fig. 4.1.4 Network Configuration

Use the Network Interface drop-down menu to choose the desired interface:

  • AUTO-DHCP-SLAAC: (default) Will configure every active interface for DHCP and for both IPv4 and IPv6.
  • AUTO-DHCP: Will configure every active interface for DHCP and for IPv4.
  • IPv6-SLAAC: Will configure every active interface for DHCP and for IPv6.

Alternately, use the drop-down menu to select the device name for the interface and manually configure and input the IPv4 and/or IPv6 addressing information. When finished, click Next to access the screen shown in Figure 4.1.5.

_images/server6b.png

Fig. 4.1.5 Optional Install Features

To install the FreeBSD ports collection, check Install ports tree then click Finish to exit the wizard and access the summary screen shown in Disk Selection.

If installing the server to a system with ZFS already installed, you can choose to Install to disk or Install into boot Environment.

When installing to disk, click Customize Disk Settings to configure the system’s disk(s). When installing into a Boot Environment, you can select the ZFS Pool for installation using the drop-down menu.

To save the install configuration for re-use at a later time, insert a MSDOSFS or FAT32 formatted USB stick and click Save Config to USB.

When ready to continue, click Next. A new window asks if you are ready to begin the installation. Click Yes to continue or No to continue modifying the install configuration.

Once the system is installed, it boots to a command-line login prompt. Login using the primary user account configured during installation. Now the server can be configured like any other FreeBSD server installation. The FreeBSD Handbook is an excellent reference for performing common FreeBSD server tasks.

4.2. Restore from Life Preserver backup

If you have replicated the system’s snapshots to a remote backup server, you can use a TrueOS® installation media to perform an operating system restore or to clone another system. Start the installation as usual and select to Restore from Life Preserver backup in the System Selection Screen.

Before you can perform a restore, the network interface must be configured. Click the Network Connectivity (blue circle) icon in order to determine if the network connection was automatically detected. If not, refer to the instructions in the Network Manager section of this handbook and ensure networking is functional before continuing.

Once you are ready, click Restore from Life Preserver backup and Next. This starts the Restore Wizard. In the SSH Restore shown in Figure 4.2.1, type the IP address of the backup server and the name of the user account that replicated the snapshots. If the server is listening on a non-standard SSH port, change the SSH port number.

_images/restore2a.png

Fig. 4.2.1 : Beginning a SSH Restore

Click Next and the wizard provides a summary of your selections. If correct, click Finish. Otherwise, click Back to correct them.

Once the connection to the backup server succeeds, you can select which host to restore. After making your selection, click Next. The restore wizard provides a summary of which host it restores from, the name of the user account associated with the replication, and the hostname of the target system. Click Finish and the installer proceeds to the Disk Selection Screen. At this point, you can click Customize to customize the disk options. However, any ZFS datasets will be greyed out as they are to be recreated from the backup during the restore. Once you are finished with any further customizations, click Next to perform the restore.

4.3. Using the System Utilities Menu

The System Utilities menu is available from the “Emergency Shell” icon (see Installer icons) in the various TrueOS® installer screens. Once opened, you’ll see the menu shown in Figure 4.3.1.

_images/util1a.png

Fig. 4.3.1 System Utilities Menu

This screen provides several options:

  • shell: This option is useful when troubleshooting a TrueOS® system that no longer boots. It opens a shell with administrative access, including the base FreeBSD utilities. Advanced users can use this shell to identify a problem, create a backup or copy essential files to another system, or alter configuration files with an editor like ee or vi. When finished using the shell, type exit to return to the System Utilities Menu.
  • zimport This option displays the names of available ZFS pools. Type the name of an available pool and the utility imports the pool then displays the available boot environments (BEs). Type the name of the desired BE and zimport mounts the BE then offers to open a chroot shell so the environment’s contents can be viewed and edited as needed in order to perform maintenance on the boot environment. When finished, type exit to leave the boot environment and return to the System Utilities Menu.
  • fixgrub: This option is scheduled for removal as GRUB is no longer supported by TrueOS®.
  • exit: This option returns the user to the main TrueOS® Installation Menu.

4.4. Automated Installations

TrueOS® provides a set of Bourne shell scripts to allow advanced users to create automatic or customized TrueOS® installations. pc-sysinstall is the name of the master script. The script reads a customizable configuration file and uses dozens of backend scripts to perform the installation. 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 TrueOS® installer. Scripts have been divided by function, such as functions-bsdlabel.sh and functions-installcomponents.sh. To learn more about how the TrueOS® 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-query/ contains the scripts 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), an exclude-from-upgrade file, and a licenses/ subdirectory containing text files of applicable licenses.
  • /usr/local/share/pc-sysinstall/doc/ contains the help text seen if pc-sysinstall is run without any arguments.
  • /usr/local/share/pc-sysinstall/examples/ contains several example configuration files for different scenarios (e.g. upgrade and fbsd-netinstall). The README in this directory should be considered as mandatory reading before using pc-sysinstall.
  • /usr/sbin/pc-sysinstall is the script used to perform a customized installation.

This section discusses the steps needed to create a custom installation.

First, determine which variables to customize. A list of possible variables can be found in /usr/local/share/pc-sysinstall/examples/README and are summarized in Table 4.4.1.

Note

This table is meant as a quick reference to determine which variables are available. The README in /usr/local/share/pc-sysinstall/examples/ contains more complete descriptions for each variable.

Table 4.4.1 Customizing a TrueOS® Installation
Variable Options Description
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 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 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”, or “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”, or “split” defaults to “round-robin” if the mirrorbal method is not specified
bootManager= “none” or “bsd”  
image= /path/to/image /mountpoint 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”, or “image” source to be used for installation
localPath= /path/to/files location of directory containing installation files
installType= “PCBSD” or “FreeBSD” determines whether this is a desktop or a server install
installQuiet “yes” or “no” set to “yes” for automatic installations
installFile= e.g. “fbsd-release.tbz” only set if using a customized installer archive
packageType= “tar”, “uzip”, “split”, “dist”, or “pkg” the archive type on the installation media
distFiles= e.g. “base src kernel” list of FreeBSD distribution files to install when using packageType=dist
ftpPath= ftp://ftp_path 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 pkg packages to install; requires pkgExt=
pkgExt= “.txz” 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 new user
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
defaultGroup= e.g. “wheel” default group
userGroups= e.g. “wheel, operator” comma separated (no spaces) list of additional groups
commitUser   mandatory, must be last line in each user block
runCommand= full path to command run the specified command within chroot of the installed system, after the installation is complete
runScript= full path to script runs specified script within chroot of the installed system, after the installation is complete
runExtCommand= full path to command runs a command outside the chroot
runPrePkgCommand= full path to command runs the specified command before starting the pkg installation
runPrePkgScript= full path to command runs the specified sript before starting the pkg installation
runPrePkgExtCommand= full path to command runs the specified command before extracting the pkg
runPreExtractCommand= full path to command runs the specified command before extracting
runPreExtractScript= full path to command runs the specified command before starting the pkg installation
runPreExtractExtCommand= full path to command runs the specified command before starting the pkg installation
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 log 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= username 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

Next, 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/ and follow the most relevant example. Copy the file to any location and customize it so it includes the desired variables and values in the 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). Use the saved configuration file as-is, or customize it to meet an installation’s needs. This method may prove easier when performing complex disk layouts.

To perform a fully automated installation which does not prompt for any user input, review /usr/local/share/pc-sysinstall/examples/pc-autoinstall.conf and place a customized copy of the file into /boot/pc-autoinstall.conf on the installation media.

Table 4.4.2 summarizes the additional variables available for fully automatic installations. More detailed descriptions can be found in the /usr/local/share/pc-sysinstall/examples/pc-autoinstall.conf file.

Note

The variables in this file use a different syntax than those in Customizing a TrueOS® Installation as the values follow a colon (:) and a space rather than an = sign.

Table 4.4.2 Automated Installation Variables
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”, or booting the wrong disk will result in a system wipe
shutdown_cmd e.g. shutdown -p now running a shutdown is recommended, but this can be any command/script to execute post-install
nic_config “dhcp-all” or <interface name> <IP address> <subnet mask> attempts DHCP on all found NICs until the installation file is fetched or will setup a specified interface
nic_dns IP address DNS server to use
nic_gateway IP address default gateway to use

Finally, create a custom installation media or installation server. pc-sysinstall supports two installation methods:

  1. From CD, DVD, or USB media.
  2. From an installation 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 an ISO for the TrueOS® version to customize is downloaded, the superuser can access the contents of the ISO with a few commands:

[name@example] mdconfig -a -t vnode -f TrueOS-Desktop-2016-08-11-x64-DVD.iso.md5 -u 1

[name@example] mount -t cd9660 /dev/md1 /mnt

Make sure to cd into the desired destination directory for the copied ISO contents. In the next examples, /tmp/custominstall/ was created for this purpose:

[name@example] cd /tmp/custominstall

[name@example] tar -C /mnt -cf - . | tar -xvf -

[name@example] umount /mnt

Alternately, if an installation CD or DVD is inserted, mount the media and copy its contents to the desired directory


[name@example] mount -t cd9660 /dev/cd0 /mnt

[name@example] cp -R /mnt/* /tmp/custominstall/

[name@example] umount /mnt

If creating an automated installation, copy the customized pc-autoinstall.conf to /tmp/custominstall/boot/.

Copy the customized configuration file to /tmp/custominstall/. Double-check the installMedium= variable in the customized configuration file is set to the correct installation media.

Adding extra files may be necessary if certain variables are set in the custom configuration file:

  • installComponents= Any extra components to install must exist in extras/components/.
  • runCommand= The command must exist in the specified path.
  • runScript= Make sure the script exists in the specified path.
  • runExtCommand= Ensure the command exists in the specified path.

If the installation media is a CD or DVD, create a bootable media containing the files in the directory. To create a bootable ISO:

[name@example] cd /tmp/custominstall

[name@example] mkisofs -V mycustominstall -J -R -b boot/cdboot -no-emul-boot -o myinstall.iso

Use a preferred burning utility to burn the ISO to the media.

To begin an installation that requires user interaction, type pc-sysinstall -c /path_to_your_config_file

To begin a fully automated installation, insert the installation media and reboot.

If using an HTTP, FTP, or SSH server as the installation media, untar or copy the required files to a directory on the server accessible to users. Be sure to configure the server so installation files are accessible to the systems to install.