Chapter 9. Automating Installations With RoboInst

RoboInst is an extension to the miniroot that automates miniroot installations and performs related tasks, such as disk and filesystem configuration, as an integral part of the installation process . RoboInst also allows a “live-mode” installation as described in “Additional RoboInst Command-Line Options”. The tasks performed during the installation are user-defined. RoboInst can be launched locally on the target host (RoboInst client) or from a network server (RoboInst server) to install any number of clients located anywhere on an internet. It can also be launched by a scheduler such as cron or from a batch queue.


Note: A RoboInst license is purchased separately. Refer to Chapter 10, “Licensing”, for information on acquiring a license to use RoboInst.

This chapter describes RoboInst fundamentals, how to prepare for using RoboInst, and how to customize miniroot installations with RoboInst scripts. The chapter contains these sections:

How RoboInst Works

Functionally, a RoboInst configuration server can be seen as four servers and any number of clients. The servers are:

  • RoboInst server—Runs roboinst command.

  • software distribution server—Contains distribution(s) to be installed.

  • configuration server—Contains RoboInst configuration file(s).

  • boot server—Contains sash and miniroot files.

The installation is initiated from a RoboInst server, which may also be a boot server, distribution server, or client. The distribution to be installed is provided by a software distribution server (also called an installation server) which may or may not also be a boot server and/or configuration server. The clients are any network hosts that receive the installation.

The sequence of events in a RoboInst installation are specified by various files that reside in the configuration directory; the host containing the configuration directory is the configuration server. The configuration directory must contain a master miniroot configuration file, mrconfig, but it can also contain additional files and scripts that support the installation process. All files and scripts in the configuration directory, including mrconfig, are user-created; they specify actions to be taken before, during, or after the miniroot installation. See “Creating a Miniroot Configuration File” for details.

Like other remote miniroot installations, RoboInst installations frequently rely on a boot server to load the miniroot from a remote source to the client system (see “About Miniroot Installations” in Chapter 3). The boot server contains a sash and IRIX miniroot boot files for all system models to be installed. In a simple RoboInst configuration, the boot server and the configuration server reside on the same host, but they can reside on separate hosts if necessary.

Figure 9-1 illustrates a simple RoboInst configuration.

Figure 9-1. Simple RoboInst Configuration

Simple RoboInst Configuration

Events in a RoboInst Installation

To perform an automatic miniroot installation on one or more clients, issue a roboinst command from the RoboInst server. This sequence of events occurs on the client after RoboInst is installed:

  1. RoboInst writes the network location of the miniroot (and a new IRIX 6.5 sash if the client is running an earlier release of IRIX than 6.5) in the disk volume header on the clients.

  2. RoboInst reboots the client using the new sash.

  3. RoboInst relocates the swap and root partitions on the client disk if a relocation is specified (see “Disk Partitions and RoboInst”, below).

  4. The sash sets an environment variable on the client to signal a RoboInst installation; then it loads the miniroot from its network location to the swap partition on the client.

  5. The miniroot configures networking via DHCP, BOOTP1533, or the PROM variables, as specified in the startup command.

  6. The miniroot copies the files in the configuration directory to the /custom directory in the miniroot filesystem.

  7. Actions specified in the mrconfig file (such as fx, inst, and postinst commands) are executed.

  8. The client system is returned to multiuser mode.

Disk Partitions and RoboInst

As Figure 9-1 illustrates, the physical location of the swap and root partitions on IRIX 6.5 systems are reversed from their traditional location in earlier IRIX versions. This relocation of swap and root permits arbitrary disk repartitioning during miniroot installations. When you upgrade a client system from an earlier IRIX version to IRIX 6.5, you can reverse swap and root automatically with an argument to the RoboInst command or with a configuration script (see “Launching RoboInst ”). This disk reconfiguration is not necessary unless you plan to do disk partitioning from the miniroot.


Note: Although the location of swap and root are reversed, their partition numbers remain the same (root remains partition 0 and swap remains partition 1).


Getting Ready for RoboInst

This list suggests what to do to prepare for using RoboInst for miniroot installations. The subsections that follow the list provide details for each task:

  1. Identify the client systems to be installed. See “The Client System List”.

  2. Select and prepare the servers. See “Software Distribution Server Setup”, “Boot Server Setup”, and “Configuration Server Setup”.

  3. Create the configuration directory. See “Configuration Directory Setup”.

  4. Configure DHCP if you plan to use it. See “Network Setup”.

The Client System List

To prepare for RoboInst installations, create a list of hostnames of the client systems for which a miniroot installation is needed. These hostnames will be used in the RoboInst command to launch the installations (see “Launching RoboInst ”).

In addition to hostnames, you should also make a list of the different system models of your clients. Use the list to verify that the boot server contains the boot file that is necessary for each system model (see Figure 9-1).

Software Distribution Server Setup

The software distribution server (or installation server) makes available the software images that Inst installs on other hosts. The images may be stored in directories on the hard disk or on CDs. If you plan to store the software distribution on a hard disk, plan on allocating approximately 0.5 GB for each CD in the original distribution. If you prefer, you can continue to use CDs as the software distribution source.

Instructions for configuring an installation server are given in Chapter 2, “Preparing for Installation” (see “Setting Up an Installation Server” in Chapter 2 for details). If you follow those instructions to set up the installation server for miniroot installations (this means enabling BOOTP and TFTP on the server), you can use the same host as the installation server, the configuration server, and the boot server. (See also “Enabling BOOTP Forwarding on Routers” in Chapter 2 and “Enabling TFTP Access on an Installation Server” in Chapter 2.)

Boot Server Setup

The boot server contains sash and miniroot boot files for each model of client systems that it serves. The total disk space required for miniroot files is approximately 50 to 100 MB, depending on the number of models represented in your client set. If your network contains subnets, installations will require less time if an installation server is located on each subnet where clients are located; and locating the boot server on the same subnet saves additional time.

You will find the sash file, sa, in the dist directory of the Installation Tools distribution—on CD or provided by a software installation server. Various miniroot kernels are stored in the miniroot subdirectory of the Installation distribution. You can run hinv on the clients to determine their IP number to install the correct kernel on each. You should copy the sa file, and the miniroot subdirectory into a directory on the boot server (see “Example Boot and Configuration Server” for an example.)

The server must be running BOOTP and TFTP to boot clients remotely. BOOTP is required to respond to client boot requests, and TFTP is required to transfer the boot files after the request is received. If you have not already done so, follow the instructions in “Enabling BOOTP Forwarding on Routers” in Chapter 2 and “Enabling TFTP Access on an Installation Server” in Chapter 2 to set up BOOTP and TFTP.


Note: If you combine the boot server with an installation server that is configured for miniroot installations, BOOTP and TFTP are already configured. See “Setting Up an Installation Server” in Chapter 2.


Configuration Server Setup

The configuration server contains miniroot configuration files in a special configuration directory. Because they occupy miniroot space during the installation process, the files in this directory are necessarily small; therefore, disk space is seldom a consideration when selecting a configuration server.

If you decide to create the configuration server and boot server on separate hosts (or are launching RoboInst from the PROM monitor as described in “Launching RoboInst From the PROM”), be sure to make a note of the configuration server's IP address. When the configuration server and boot server are on different hosts, you must specify the configuration server's IP address when launching RoboInst (see “Launching RoboInst ”).

The configuration server must permit access to files in the configuration directory. To allow this access, you can either enable TFTP on the configuration server if you have not already done so (see “Enabling TFTP Access on an Installation Server” in Chapter 2 for instructions); or, if you prefer, you can use an open guest account instead of TFTP (see “Configuring an Installation Account” in Chapter 2 for setup instructions).

Configuration Directory Setup

By convention, the configuration directory is /usr/local/boot/roboinst/custom on the configuration server. However, you can use a different directory if you specify the alternative name in RoboInst commands (see “Launching RoboInst ”). After you create the configuration directories, populate them with an  mrconfig file (see “Creating a Miniroot Configuration File”). You can also create and copy additional configuration files to control events before, during, or after the software installation process (see “Creating Additional Configuration Files”). After creating configuration files, run the roboinst_config command to generate a .index file .This file is used to confirm that all files are copied successfully to the client.

Network Setup

AfterRoboInst loads the miniroot, it checks the environment to determine which of the following three ways to start networking:

  1. (default) RoboInst uses netaddr, the PROM value for IP address, to make an extended BOOTP (RFC 1533) request for network parameters (that is, netmask, gateway(s), static route(s), and so on).

  2. RoboInst makes a Dynamic Host Configuration Protocol (DHCP) request for an IP address, hostname, and netmask parameters. If the responding server offers DHCP service, the server returns the requested parameter information.

  3. RoboInst does not ask the network for information, but rather uses the PROM values for IP address and netmask (if set). This is a fallback procedure if #1 and #2 (above) should fail.

If you prefer, you can create a custom script to set the client's IP address and other operating parameters (see the nvram(1M) reference page).

Customizing Miniroot Installations

To customize a miniroot installation, prepare a miniroot configuration file and any additional files that you want to execute as part of the installation session. If you use TFTP on the configuration server and the configuration directory contains additional files, it must also contain an index file that lists each file in the configuration directory.

Creating a Miniroot Configuration File

The miniroot configuration file, mrconfig, controls RoboInst installation sessions. This is an ASCII file in the configuration directory that contains keywords that RoboInst interprets to partition disks, install software, and so on, from the miniroot of the client system. Example configuration files that you can study and modify are located in /usr/share/src/RoboInst (if you have installed the examples from the RoboInst distribution, they are not installed by default).

 Each significant line of an mrconfig file begins with a keyword; blank lines and comments (lines beginning with the # character) are ignored. Keywords and arguments are described in Table 9-1.

Table 9-1. Keywords in an mrconfig File

Keyword

Arguments

Description

loghost

IP address (or hostname if boot server)

Specifies the host where log messages are sent in addition to the client system.

partition  

device size type name options

Specifies partitions to create and filesystems to mount.

setenv

variable, value

Sets the named variable in the RoboInst environment. This variable is also exported to subcommands, such as those executed before, during, and after the software installation phase.

disksetup

None

Reverses the location of the swap and root partitions on a disk that was partitioned before IRIX 6.5.

CAUTION: Any data contained on the disk is lost when you use this keyword.

init

/bin/sh command

Specifies shell commands to execute during the initialization phase of the installation.

fx

/bin/sh command

Specifies shell commands to execute during the disk partitioning phase (fx) of the installation (see the fx manual page).

mkfs

/bin/sh command

Specifies shell commands to execute during the filesystem creation phase (mkfs) of the installation (see the mkfs manual page).

preinst

/bin/sh command

Specifies shell commands to execute during the phase immediately preceding software installation (inst execution).

inst

inst command

Specifies a command recognized by the inst utility. Each inst command must be preceded by this keyword. Commands are collected in the order that they appear in the mrconfig file, copied to a temporary file, and issued to inst with this syntax:
inst -r/root -c tempfile 

onerror

wait, ignore

If set to wait, suspend the installation and display the Inst> prompt if an error occurs during the software installation process. If set to ignore, continue past error (still reported in INSTLOG and SYSLOG).

nokernel

None

Causes the autoconfiguration phase to be skipped so the IRIX kernel is not generated. If you use this keyword, you must create a script to build the IRIX kernel.

postinst

/bin/sh command

Specifies shell commands to be executed during the phase following software installation (inst execution).

if
...
endif

/bin/sh command

Similar to the if syntax in /bin/sh scripts. When an executed command exits with a status of zero, all lines up to the matching endif statement are evaluated. When an executed command exits with a nonzero status, the inclusion lines are ignored completely. Nesting is permitted.

if
...
else
...
endif

/bin/sh command

Similar to the if syntax in /bin/sh scripts. When an executed command exits with a status of zero, all lines up to the matching else statement are evaluated. When an executed command exits with a nonzero status, the lines between the else and endif statements are evaluated instead. Nesting is permitted.


Ordering Commands in an mrconfig File

Commands are parsed based on the keywords in the following order from the mrconfig file:

  1. loghost 

  2. init 

  3. partition 

  4. fx 

  5. mkfs 

  6. preinst 

  7. inst 

  8. nokernel 

  9. postinst 

While the convention of placing the commands in the mrconfig file in this order helps make it easy for users to read, it is not necessary for RoboInst.

Partition Keyword

Use the partition keyword to specify disk partitioning, filesystems and mount points. The syntax is as follows:

partition  device size type name options 

The device, size, and type arguments are used as input to the fx -s command (see the fx(1M) reference page) to perform the partitioning. Partitions are laid-out in the order specified, unless a start position is given.

device is a device name referring to a disk device in the /dev/rdsk directory, for example dks0d1s0. See dks(7M) for a full description of device names.

size is one of the following arguments:

  • existing—keep the same size.

  • standard—use a standard layout for the entire disk. Type root or option arguments must also be specified. When standard is used, it applies to the entire disk (the partition component in the device name is irrelevant). For most partitioning tasks, either standard root or standard option should be specified as the first partition statement for the given disk. If customizations are desired, additional partition statements for that disk may also be specified.

  • all—The entire disk.

  • start:size

    start is an integer that specifies the exact start address of the partition, in 512-byte blocks. Alternatively, start can be followspart# where # is the partition-number that this partition should immediately follow on the same disk. Note that the volume header is partition 8, so to use the first usable partition, you would normally use followspart8. 

    size is an integer that specifies the size of the partition in 512-byte blocks or the word remainder to use the entire remainder of the disk after making all of its other partitions. Note that partitions are processed in the order they appear in the file, so remainder should be used only in the last partition statement for a particular disk.

type is one of the foloowing arguments:

  • root—Valid only when standard is specified. A standard root disk is created, containing a swap partition and a root partition of maximum size containing an XFS filesystem.

  • option—Valid only when standard is specified. A standard option disk is created, consisting of a single partition of maximum size, containing an XFS filesystem.

  • xfs or xfs/blocksize 

    An XFS filesystem is created with the specified blocksize, and mounted at the directory name with the specified options. The blocksize must be an integer multiple of 512 and cannot exceed 65536. If omitted, a blocksize of 4096 is assumed.

  • efs—An EFS filesystem is created and mounted at the directory name with the specified options.


    Note: EFS filesystems will not be supported in future IRIX releases. Use XFS filesystems in nearly all situations.


  • swap—A swap partition of the specified size is created.

  • preserve—Any existing filesystem is preserved, and no new one is created.

name is ignored when type is swap. For other partition types, its value can be either of these:

  • pathname—indicating a local directory where the filesystem is to be mounted.

  • nomount—If nomount is specified, the filesystem is not mounted.

options are options to the mount -o command. This field is optional. Any options specified are to be passed along to the mount command as a single argument. Multiple options should be comma separated with no spaces. Refer to the mount(1M) reference page for more information.

For example, use this command to make disk (0,1) a standard system drive:

partition dks0d1s0 standard root / 

For example, use this to make disk (0,2) a standard option drive mounted at /d2:

partition dks0d2s0 standard option /d2 

Hostname Considerations

No name services, such as DNS or UNS, are available from the miniroot. The only source of hostnames is the /etc/hosts file and the hostname of the boot server. For this reason, all other remote host designations in the mrconfig file must be in the form of IP addresses, (unless you enter hostnames in the local /etc/hosts from a script, for example).

You can add hostnames to the miniroot's /etc/hosts file individually, for example:

init echo “192.1.2.3 fred1.acme.com fred1” >> /etc/hosts 

You can also copy in a host file from the configuration directory, for example:

init cat /custom/hosts >> /etc/hosts 

Environment Variables

RoboInst software sets the following variables in the environment of all shell commands defined in an mrconfig file:
 

SGI_ABI

SGI_BOOTDIR

SGI_BOOTSERVER

SGI_CAPACITY

SGI_CAP_dks#d#vol

SGI_CONFIGDIR

SGI_CONFIGSERVER

SGI_CPUARCH

SGI_CPUBOARD

SGI_CUSTOM

SGI_GFXBOARD

SGI_HOSTNAME

SGI_IPADDR

SGI_MACHINE

SGI_MEMSIZE

SGI_MODE

SGI_ROOT

SGI_SUBGR

SGI_SYSID

Refer to the roboinst_config(1M) reference page for details and the latest list of environment variables.

Creating Additional Configuration Files

If you use TFTP on the configuration server and the configuration directory contains files in addition to the mrconfig file, the configuration directory must also contain a .index file that lists each additional file. The /usr/etc/roboinst_config script, which is part of RoboInst software, creates a .index file automatically. When you have finished creating the configuration directory and all necessary files (or have just modified a file), run roboinst_config to create a new .index file (refer to the roboinst_config(1M) reference page for details).

The index file that roboinst_config creates lists the name, type, size, and checksum of each file in the configuration directory. RoboInst compares this information to verify that the configuration files copied to the client are identical to the files contained in the configuration server. If the files are not identical, they are not executed and the installation fails. For this reason, you should generate a .index file even if the configuration directory contains only an mrconfig file.

Example Boot and Configuration Server

Figure 9-2 shows an example of how a setup might look if your boot server and configuration server are the same host. A simple setup is shown in which the only configuration file is mrconfig, and the only boot files are the miniroot kernel, unix.IP22, and the sash, sa. 

Figure 9-2. Sample RoboInst Directory and File Setup

Sample RoboInst Directory and File Setup

Launching RoboInst

Launch RoboInst from a network host on which you have installed the RoboInst server software (refer to your release notes for client and server installation information). The command to launch RoboInst is roboinst, and basic command syntax is as follows:

roboinst [-n|-y] -b bootdir -c configdir -t time client(s)...

(Refer to the discussion below and the roboinst(1M) reference page for more command-line options and further details.)

Launching RoboInst From the Server

You can launch RoboInst from any supported IRIX server with the roboinst server software installed. You must specify a boot server (-b option) and a configuration server (-c option). You may specify a time (-t option) if at is enabled on the server, or else accept the default time “now.” You may also specify automatic installation (-y option), or just check the configuration without initiating installation (-n option). If you specify neither -y or -n you will be prompted before starting the installation.

In Example 9-1, a configuration test is made with the -n option, and an error is returned because the mrconfig file is not readable.

Example 9-1. RoboInst Configuration Test

bar1 1# roboinst -n -b fred1:/usr/local/boot \
-c fred1:/usr/local/boot/roboinst/custom foo1 foo2 foo3 foo4 
roboinst: submitting job on bar1
bar1: Size mismatch for /tmp/d.roboinst.3106/mrconfig 0 (expected 1719)
bar1: Try running roboinst_config
bar1: Unable to retrieve configuration from 192.1.2.3:/usr/local/boot/roboinst/custom
bar1 2# 

In Example 9-2, RoboInst proceeds automatically, stopping at an error if onerror is set to wait (see Table 9-1).

Example 9-2. RoboInst Configuration Launch With Prompting

bar1 1# roboinst -b fred1:/usr/local/boot \
-c fred1:/usr/local/boot/roboinst/custom foo1 foo2 foo3 foo4 


Launching RoboInst from the Client

To launch RoboInst from a client, install server and client software on the host and then run the roboinst command as with a server. If you are only installing on the client you run the roboinst command from, you do not specify the client name, as shown in Example 9-3.

Example 9-3. RoboInst Installation From the Client

bar1 1# roboinst -b fred1:/usr/local/boot \
-c fred1:/usr/local/boot/roboinst/custom 


Launching RoboInst From the PROM

If the client is not up and running on the network, you can initiate RoboInst from the PROM monitor of the client using a boot command with the argument mrmode=custom, as described in this section.


Caution: Pay special attention to the disksetup keyword. Use the disksetup keyword only if you plan to repartition the disk drive, because it causes all current contents of the root drive to be lost. (Subsequent to its first use, however, disksetup may not make any noticable changes. In particular, it will not “wipe” the disk. Rather, it rearranges partitions, causing them (if changed) to not appear to have filesystems. In fact, if they have already been rearranged, disksetup may appear to do nothing.)

The final argument, mrconfig=addr:/pathname is used to specify the IP address and pathname of the directory containing your mrconfig file. For example:

boot -f bootp()server:/path/sa(sashARCS) mrmode=custom disksetup=true mrconfig=130.62.51.86:/var/tmp/roboinst
boot -f bootp()server:/path/sa(sashARCS) mrmode=custom mrconfig=130.62.51.86:/var/tmp/roboinst
boot -f bootp()server:/path/sa(sashARCS) mrmode=custom
boot -f bootp()server:/path/sa(sash64) mrmode=custom mrconfig=130.62.51.86:/var/tmp/roboinst
boot -f bootp()server:/path/sa(sash64) mrmode=custom

In the examples above, it is necessary to use an IP address for the configuration server only if it is different from the boot server. If these two servers are the same, then a hostname can be specified:

boot -f bootp()server:/path/sa(sashARCS) mrmode=custom mrconfig=server:/var/tmp/roboinst 


Note: The PROM has a limit on the command line length. If you need to, you can work around this limit in any of several ways:


  1. User a shorter directory path on the server(s).

  2. Separate the command into multiple commands. For example, you can set most of the variables as separate commands:

    setenv mrconfig 130.62.51.86:/var/tmp/roboinst
    boot -f bootp()server:/path/sa(sashARCS) mrmode=custom \ disksetup=true
    

  3. Configure DHCP or BOOTP1533 to return the mrconfig path in the pro_extensions_pathname (proclaim configuration syntax) option. In this case, the file returned would contain the following:

    pro_roboinstdir=server-IP:/path/to/mrconfig/dir
    

  4. Use the default mrconfig paths (in the following order):

    dhcpserver:/usr/local/boot/roboinst/custom
    bootserver:/usr/local/boot/roboinst/custom
    


    Note: The boot command may fail if you have not properly set your netaddr variable. Use this PROM command to display the current value:


    printenv netaddr 
    netaddr=130.62.51.201
    

If it is not set correctly to the IP address of the host, use the setenv command to set it correctly, for example:

>> setenv netaddr 143.69.51.201 

Contact your network administrator if you are not sure what the appropriate address is. On some networks, if you have a properly configured bootp server with your machine listed in its /etc/bootptab file, your netaddr variable will be set automatically if you first unset it with this command:

unsetenv netaddr 

Then use the boot command.

Additional RoboInst Command-Line Options

A useful command option to know is the roboinst -L “live mode” option. With this option, RoboInst does not bring the client down to the miniroot to perform the automatic installation. Only the preinst, inst and postinst keywords in the mrconfig file are processed with this option, and it is not possible to perform disk reformatting or modify networking parameters in live mode.

Another useful command to consider is roboinst -f. With the -f option, you can automatically install the roboinst client software on the clients.

Refer to the roboinst(1M) reference page for more information on these and other options.