Chapter 9. Automating Installations With RoboInst
Prev |  | Next

## 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”

- “Getting Ready for RoboInst”

- “Customizing Miniroot Installations”

- “Launching RoboInst ”

## 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

### 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

## 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.

Prev | Table of Contents | Next
Chapter 8. Customizing Installations |  | Chapter 10. Licensing