Silicon Graphics

RoboInst Examples

This page lays out a number of examples of RoboInst installation configurations. The examples are presented as a directory for each example, complete with mrconfig file, and associated configuration support files. mrconfig syntax is in a separate document (The mrconfig file).

Configuration Files Overview
Common Script Descriptions
Some Useful Script Fragments
Example Configurations
Special configuration examples (including the use of RoboInst environment variables)
File Listings

Additional Tools

Included are some tools to simplify host configuration after a clean install. Note that server paths, hostnames, etc, change depending on environment, and those will have to be changed to be useful in a different environment.

Configuration Files

The scripts that you write need to know about SGI's miniroot environment. The miniroot is a minimal IRIX XFS filesystem that is loaded into the first portion of the swap partition (the rest of which is used as swap). The miniroot will copy the configuration files into the /custom directory in the miniroot filesystem. After optionally using fx to repartition the disk, and mkfs to create new filesystem(s), it will mount the normal root filesystem on /root. Therefore, you will find all your custom files in the /custom directory, and all operations on files in the standard filesystem will need to have /root pre-pended to them. The configuration tools can simplify handling these issues.

Common Script Descriptions

Files common to more than one example are kept in the base subdirectory, with symlinks from the other example configuration directories.

mrconfig

This is the ``master'' configuration file for RoboInst. It provides the partitioning, logging selection, inst selections, and specifies commands to run during different phases of the installation. All other scripts are optional, and tend to be pretty constant across a group of systems. See mrconfig documentation on the format of this file.

mypostinst

This script is executed as the postinst action of the mrconfig file. It will first do some basic host configuration, to ensure that it reboots on the net. Then if both Perl was installed on the system, and the miniconfig.pl script exists, it will run it to complete the host configuration.

miniconfig.pl and ConfigMR.pl

In the examples, miniconfig.pl is executed from the mypostinst script. It sets up the Perl environment and calls functions in ConfigMR.pl to perform the host configuration before restarting from the miniroot. Documentation for the functions usable in miniconfig.pl are in ConfigMR.pl documentation.

Because Perl is installed as a standard part of IRIX, it is used for the post-installation configuration, though of course it could be written as a /bin/sh script, too. The Perl script is divided into a library file ConfigMR.pl (separately documented) and a small driver script. The driver script, miniconfig.pl, shows the special initialization needed to run Perl from the mounted root filesystem. See examples/base/ConfigMR.pl for the Perl library file, and examples/base/miniconfig.pl for one version of the common configuration script.

The Perl scripts can be tested outside of the miniroot by overriding the values for the /custom and /root directories, normally in the miniconfig.pl file. See the supplied examples/base/miniconfig.pl for one method.

hist2selfile

hist2selfile generates a selections file from a running system.

Some Useful mrconfig Script Fragments

Adding to the /etc/hosts file

It can be a lot more convenient to refer to other hosts in the rest of the mrconfig file by hostname instead of by IP address. There are 2 ways to do this. One is to explicitely add hosts to the /etc/hosts file:

init  echo "192.26.80.118   dist.engr.sgi.com dist" >> /etc/hosts
init  echo "192.48.174.2    babylon.engr.sgi.com babylon" >> /etc/hosts

The other is to copy over the hosts file with mrconfig, and append it:

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

Minimum postinst Configuration

Sometimes all you need is to get the system back up on the net for final configuration. Just copy the hostname/IP address that the miniroot was using to the /root:

postinst sed 's/192.0.2.1.*IRIS/'`nvram netaddr`" "`hostname`/ < /root/etc/hosts > /root/etc/hosts.N
postinst mv /root/etc/hosts.N /root/etc/hosts
postinst echo `hostname` > /root/etc/sys_id

Setting netmask

While things usually work OK in the miniroot if the netmask is incorrect, it is more correct to have it set correctly. It should be set correctly from the previously running system, but if not, you can force it to be set explicitely. It may need to be set twice: once manually if starting RoboInst from the PROM prompt:

> boot -f bootp().... mrmode=custom netmask=0xffffff00 mrconfig=...

and once (more importantly) in the postinst phase. If you don't use the mypostinst script in the examples, then you should add this line to the postinst phase in mrconfig:

postinst echo netmask 0xffffff00 > /root/etc/config/ifconfig-1.options

Note that your netmask may vary from the example, and that if you have more than one network interface, you almost certainly need to set all of the networking configuration scripts in the postinst phase: /etc/config/netif.options, /etc/config/ifconfig-*.options, etc.

Setting the loghost

It is useful to send the syslog of the RoboInst activity to a central monitoring host. At the least, you have a log of what happened even if something catastrophic happens. The loghost needs to be given as the IP address:

loghost 130.62.51.110

Example Configurations

The following example configuration directories will be shipped under /usr/share/src/RoboInst (but "sanitized", by changing IP addresses, etc), and are available here as examples subdir. Unless otherwise specified, they wipe the disk(s) and install software from scratch. Most of the example directories include additional files for configuring the host before it leaves the miniroot.

CAUTIONS

Be sure to change the loghost to point to your own monitoring system! (the examples all have loghost 130.62.51.110, which is my desktop). (see the mrconfig file).
You probably don't want to configure your machines as my test machine, either. (see the miniconfig.pl file).

Minimum System

This is found in the subdirectory minimum.

This example mrconfig installs a bare-bones bootable system, with no graphics. It gets the machine booted onto the net in the shortest amount of time. Any further installs or configuration would be done ``live''.

Since only required subsystems are being installed, and Perl is not required, the Perl postinst configuration script will not work (the example mrpostinst script detects this condition and aborts with a warning). This example assumes that the DHCP hostname and IP address will be valid after it reboots. But you only really use this case if you want to finish the installation in some other manner anyway...

Standard User

This is found in the subdirectory user.

This example mrconfig loads up a standard amount of applications and documentation, as a starting point for a standard desktop configuration. It shows the use of a selections file to exactly mirror the installation on a base (or standard) system. A script to conveniently generate a selections file from a properly configured running system is hist2selfile.

This example mrconfig also shows how to select a different root disk depending on which host system type that the machine is.

Substantial configuration is performed via the miniconfig.pl script:

Customized versions of configuration files are installed into the /etc directory.
Standard user accounts are configured from files shipped in the =passwd= directory.

Software Developer

This example is found in the developer subdirectory.

This example mrconfig file loads up the standard set of C and C++ developers tools, installing a standard user environment, and enabling the host as a Network Dual Head slave (see details in the customizedminiconfig.pl file).

This example mrconfig file also shows off configuring the size of swap as a function of the size of main memory. Note that IRIX does not require swap to be larger than main memory. IRIX does not require any swap at all to run! Main memory should be sized to hold the maximum working set, since using swap (really page) space causes an immediate, significant slowdown of the system. A certain minimum amount of swap space is required to load the miniroot (about 40MB), and to hold crash dumps. Crash dumps are saved to disk in priority order, and compressed.

Substantial configuration is performed via the miniconfig.pl script:

Customized versions of configuration files are installed into the /etc directory.
Standard user accounts are configured from files shipped in the =passwd= directory. In addition, the primary user is specially configured.

File or Compute Server

This example is found in the server subdirectory.

This example mrconfig is a standard setup for a small application, file, or computer server. Desktop systems usually like to keep a minimum number of filesystems, for ease of administration and most efficient use of disk. Servers often partition disks and reorganize filesystems to better support scalability and protection. This example is based upon how I once setup a Challenge-S workgroup server. It also shows setting partition sizes depending on the size of the system disk.

Substantial configuration is performed via the miniconfig.pl script:

Customized versions of configuration files are installed into the /etc directory.
Standard user accounts are configured from files shipped in the =passwd= directory.

NFS Dependent Client

This example is found in the noshare subdirectory.

This example mrconfig is similar to the Standard User (above), except that the /usr/share filesystem will be NFS mounted, so inst is told to not install software there. To support minimal functionality if the NFS mount fails, a minimum of software is installed under the mount point anyway.

Because the Perl standard library is installed under /usr/share, it is not available for use by the configuration scripts. The Perl binary is on the base filesystem, so can be used. It is for cases like this that the configuration scripts are written to not use any Perl library files.

Substantial configuration is performed via the miniconfig.pl script:

Customized versions of configuration files are installed into the /etc directory.
Standard user accounts are configured from files shipped in the =passwd= directory.

Updating to Current Release

This example is found in the update subdirectory.

Rather than installing a system from scratch, this configuration just updates the installation to the latest version of each distribution (CD). You do have to individually specify all the distributions, but you can safely over-specify, as the mrconfig file will only install updated products, and no new ones. If overlays are present, it will use the default stream on that host.

Because this is an update, there is no postinst phase configuration.

non-inst SW installation 1

This example is in the copy subdirectory.

This example mrconfig file shows overriding the mrinst file to copy over a golden master disk, using xfsrestore. Compressing the filesystem image can greatly speed up the transfer over the network.

The normal reasons to choose this method over a selections file are that a large number of identical systems are being installed, and network bandwidth (and install time) becomes an issue. Note that gzip --best compresses about 50% better (60+% vs 40+%) than compress, at a (one-time!) cost of 6x CPU time (vs compress to compress the disk image. This is worth it for the reduction in network traffic if you are going to install a large number of systems this way. Note that since gzip is not part of the miniroot, you have to provide a copy in /custom. gzip can uncompress fast enough to (more-or-less) saturate the disk on a 133MHz Indy, rsh-ing over a shared 10baseT network.

preinst echo starting to copy filesystem: `date`
preinst rsh guest@dist-host cat /usr/dist/root.dump.Z | uncompress | xfsrestore -v silent - /root
preinst echo finished copying filesystem: `date`

To use gzip, change the one line to:

preinst rsh guest@dist-host cat /usr/dist/root.dump.gz | /custom/gzip -d | xfsrestore -v silent - /root

Note that there is no inst phase. The disk image should either be created to use autoconfig_ipaddress (DHCP, etc), or have a post-inst phase that updates the hostname:

postinst echo `hostname` > /root/etc/sys_id

assuming that a /root/etc/hosts file was installed with all the needed hostnames, and that the auto-booted hostname is acceptable to getting the machine up on the network.

Some of the tasks that inst normally does (such as installing sash in the volume header as an exitop()) need to be done in the mrpostinst script. Without sash in the volume header, the disk is not bootable. The easiest way is to be sure to put a copy of sash into /stand when the master disk image was created. The key element in the postinst phase is:

postinst dvhtool -v creat /root/stand/sash sash /dev/rdsk/dks0d1vh

You can put the sash into the filesystem of the master image by:

dvhtool -v get sash /stand/sash /dev/rdsk/dks0d1vh

before saving it to a file. Fortunately, when you install roboinst before a "live" upgrade, it installs a new sash into the volume header.

Creating a Filesystem Image

This is a (relatively) painless cook-book to create a minimum-sized filesystem image. It requires setting up one of the machines exactly as desired, except that it has an extra scratch disk available. A seperate filesystem image must be created for each distinct hardware (processor and graphics) type. The amount of disk, memory, and most other peripherals don't matter. The steps are:

Install software and configure normally for the target "golden" system. Obviously hostname and such must vary.
xfsdump the filesystem image to a file on another partition (NFS works, but may be slow):
```
xfsdump -l 0 -F -J - / | compress -v > /hosts/server/path/root.dump.Z
       
```
or, if using gzip:
```
xfsdump -l 0 -F -J - / | gzip --best -v > /hosts/server/path/root.dump.gz
       
```
Once the xfsdump is completed, move the resultant file to the distribution location.

non-inst SW installation 2

This example is in the dd subdirectory.

This example mrconfig file shows overriding the mrinst file to dd over a golden master disk. To save network bandwidth, the master disk partition is made only large enough for the files, then the filesystem is xfs_growfs-ed to fill the partition. Compressing the filesystem image can greatly speed up the transfer over the network.

This method is not recommended (use copy install instead), as it can confuse the various XFS utilities that the filesystems on the multiple machines are the same, when they are in fact different. See the end of the xfs man page for details. It is provided as an example for people who need to fastest possible installation, and can live with the limitations.

The normal reasons to choose this method over a selections file are that a large number of identical systems are being installed, and network bandwidth (and install time) becomes an issue. Note that gzip --best compresses about 50% better (60+% vs 40+%) than compress, at a (one-time!) cost of 6x CPU time to compress the disk image. This is worth it for the reduction in network traffic if you are going to install a large number of systems this way. Note that since gzip is not part of the miniroot, you have to provide a copy in /custom. gzip can uncompress fast enough to (more-or-less) saturate the disk on a 133MHz Indy, rsh-ing over a shared 10baseT network. As this process "creates" the filesystem, it replaces the standard mkfs phase:

mkfs echo starting to DD filesystem: `date`
mkfs rsh guest@dist-host cat /usr/dist/root.dd.Z | uncompress | dd bs=1024k of=/dev/dsk/dks0d1s0
mkfs echo finished DD-ing filesystem: `date`
mkfs mount /dev/dsk/dks0d1s0 /root
mkfs xfs_growfs /root

To use gzip, change the one line to:

mkfs rsh guest@dist-host cat /usr/dist/root.dd.gz | /custom/gzip -d | dd bs=1024k of=/dev/dsk/dks0d1s0

Another advantage of this method over dd-ing the full-size filesystem, is that this works on multiple different disk sizes, as long as the smallest one can hold the filesystem.

Note that there is no inst phase. The disk image should either be created to use autoconfig_ipaddress (DHCP, etc), or have a post-inst phase that updates the hostname:

postinst echo `hostname` > /root/etc/sys_id

assuming that a /root/etc/hosts file was installed with all the needed hostnames, and that the auto-booted hostname is acceptable to getting the machine up on the network.

postinst dvhtool -v creat /root/stand/sash sash /dev/rdsk/dks0d1vh

You can put the sash into the filesystem by:

dvhtool -v get sash /stand/sash /dev/rdsk/dks0d1vh

Fortunately, when you install roboinst before a "live" upgrade, it installs a new sash into the volume header.

Creating a Filesystem Image

Install software and configure normally for the target "golden" system. Obviously hostname and such must vary.
Determine the space actually occupied by the files:
```
/bin/df -k /
       
```
Create a partition on the spare disk about 5MB larger than the size returned in the previous step, and create an XFS filesystem on it. For best results, make sure that you use the same blocksize and logfile size. Also, to avoid some performance issues from xfs_growfs-ed filesystems, create it with a smaller than default agcount:
```
fx -x
fx> repartition/expert
...etc...
mkfs_xfs -l size=1000b,internal -d agcount=3 -b size=1024 /dev/dsk/dks0d?s0
mount /dev/dsk/dks0d?s0 /mnt
       
```
Using your favorite backup method, copy the installation to the new partition. Probably the fastest method is:
```
xfsdump -l 0 -F -J - / | xfsrestore -J - /mnt
       
```
For your own piece of mind, boot off of the new disk before proceding. Shutdown to the PROM monitor and:
```
>> sash
sash> dksc(0,?,0)unix root=dks0d?s0
       
```
Then shutdown and reboot back to normal. You want to dd off an idle filesystem. Leave it unmounted after rebooting.
Now you need about 40% free space somewhere. On the local disk:
```
dd bs=1024k if=/dev/dsk/dks0d?s0 | gzip -v --best > /var/tmp/root.dd.gz
       
```
This will take a while. When finished, copy it to the distribution host.

Install On a Second Disk

This example is in the 2nd-disk subdirectory.

Sometimes you want to install the new system onto a disk that is not your primary boot disk. You may need to be able to boot multiple OS versions, or you may be installing the OS for a remote machine without a CDROM drive. However, inst and the miniroot make a lot of assumptions about where they load and run and mount, so you have to be clever. The example mrconfig file shows installing onto SCSI bus 0, disk 3.

It would be a trivial change to one of the golden disk methods, but that would be a lot of extra work for just one or 2 machines...

The key changes are to override the filesystem targets. The relevant (different) portions of mrconfig:

partition  dks0d3s0 standard root

# mount the second disk
mkfs mkfs_xfs -l size=1000b,internal /dev/dsk/dks0d3s0
mkfs mount /dev/dsk/dks0d3s0 /root

You provide a special argument to roboinst to tell it to use a disk that is not the current system disk:

roboinst -P 3 ...

NOTE:

In order for this roboinst -P n command to work, a copy of sash (from the IRIX 6.5 or later release) must be installed into the volume header of the target disk. Once sash has been installed, subsequent partitionings and installations will not remove it, though it may possibly get downgraded.

When roboinst.sw.client is installed, it puts a new copy of sash into the volume header of the system disk if it is running an pre-IRIX-6.5 OS. The following commands (run as the user root) will copy that sash from the default system disk into the volume header on the 2nd disk:

dvhtool get sash /tmp/sash
dvhtool creat /tmp/sash sash /dev/rdsk/dks0d3vh
rm /tmp/sash

Install On an alternate partition

This example is in the alt_partition subdirectory.

Disks are getting large enough that you can put 2 full system images on a single disk. Normally they are 2 different versions of the OS for a dual-boot option. As above, inst and the miniroot make a lot of assumptions about where they load and run and mount, so you have to be clever. The example mrconfig file shows installing onto SCSI bus 0, disk 3, partition 5.

It is a small change to the preceding 2nd disk installation. There are some notable changes, to work around the IRIX assumptions that the root filesystem is on partition 0.

The key changes are to override the filesystem targets. The mrconfig file assumes that all the partitions are pre-made, and only partition 5 may be modifed. The relevant (different) portions of mrconfig:

# save the original root partition!
partition dks0d3s0 existing protect /mnt
partition dks0d3s5 existing xfs/512 /

# override the default mount!!
preinst umount -kv /root/hw /root
preinst mount /dev/dsk/dks0d3s5 /root

You provide a special argument to RoboInst to tell it to use a disk that is not the current system disk:

roboinst -P 'dksc(0,3,5)' ...

Restore From Backups

This example is in the restore subdirectory.

This example mrconfig file shows overriding the mrinst file to restore from backups to a clean system disk(s). This example shows using Networker recover as the backup service.

Some of the tasks that inst normally does (such as installing sash in the volume header) need to be done in the mrpostinst script. Without sash in the volume header, the disk is not bootable. You need to either ensure that /stand/sash exists in the backup, or copy it in with mrconfig to /custom/sash.

The important bits in the mrconfig file:

preinst recover -a -f -q -c $CLIENT_HOSTNAME -s $BACKUP_SERVER -d /root /

postinst dvhtool -v creat /root/stand/sash sash /dev/rdsk/dks0d1vh

Note that you are recovering /, but need to relocate it to /root. It would be best to hard-code the Networker server and the client hostname to be recovered, to avoid pitfalls. Note that if you haven't added the Networker server name to /etc/hosts, you need to use the IP address.

Clean-install of IRIX 6.2 client

New to RoboInst 1.1 and the 6.5.2 miniroot (installation tools) is the ability to install older OS versions (6.2, 6.3 and 6.4). This is an example of clean installing an IRIX 6.2 system.

This is found in the subdirectory new62.

A selections file based upon an existing system would probably be a better choice in the long run. NOTE: Since the 6.5 miniroot is used to create this system, the 6.x (x<5) kernel will not be able to mount the filesystem unless the appropriate patch (or its successor) is installed at the same time:

3289 XFS rollup #14 for IRIX 6.2
3290 XFS rollup #7 for IRIX 6.3
3291 XFS rollup #11 for IRIX 6.4

These patches also have prereq patches that are also needed. You must install roboinst.sw.client (v1.1 or later) last, in it's own go, to get a recent sash that makes the system bootable.

Clean-install of IRIX 6.3 client

This is an example of clean installing an IRIX 6.3 (O2) system. See the notes for a clean install of IRIX 6.2 above.

This is found in the subdirectory new63.

Clean-install of IRIX 6.4 client

This is an example of clean installing an IRIX 6.4 (Octane) system. See the notes for a clean install of IRIX 6.2 above.

This is found in the subdirectory new64.

File Listings

The following are the common files and scripts used with most of the examples.

hosts file

This is the common hosts file. In the init phase of mrconfig, it is appended to the miniroot /etc/hosts file to provide limited nameservice in the miniroot.

passwd file

This is the common passwd file. In the postinst phase, it is appended to the /root/etc/passwd file to provide a set of users to create accounts for.

The passwords in the file are the same as the account name.

mypostinst

This is the base version of the post-installation configuration file, mypostinst.

miniconfig.pl

Perl configuration script, called from mypostinst to do the actual configuration work, miniconfig.pl.

ConfigMR.pl

The Perl library file of miniroot host configuration functions. It's way too big to include here, but you can follow the link to view:

Please send us your comments, questions and bugs so we can improve the product.

Silicon Graphics/ $Date: 1998/03/19 00:17:35 $