Solaris 10 6/06 Installation Guide: Custom JumpStart and Advanced Installations

Chapter 8 Creating Custom Rule and Probe Keywords (Tasks)

This chapter provides information and procedures for creating your own custom rule and probe keywords.

Probe Keywords

To understand what a probe keyword is, you first need to recall what a rule keyword is. A rule keyword is a predefined lexical unit or word that describes a general system attribute, such as host name, hostname, or memory size, memsize. Rule keywords and the values that are associated with them enable you to match a system that has the same attribute to a profile. This match of a system's attributes defines how the Solaris software is to be installed on each system in the group.

Custom JumpStart environment variables, which you use in begin and finish scripts, are set on demand. For example, information about which operating system is already installed on a system is only available in SI_INSTALLED after the installed rule keyword is used.

In some situations, you might need to extract the same information in a begin or finish script for a purpose other than to match a system and run a profile. Probe keywords provide the solution. Probe keywords extract attribute information and remove the need for you to set up a matching condition and run a profile.

For a list of probe keywords and values, see Probe Keywords and Values.

Creating a custom_probes File

The rule and probe keywords that are described in Rule Keywords and Values and Probe Keywords and Values might not be precise enough for your needs. You can define your own custom rule or probe keywords by creating a custom_probes file.

The custom_probes file is a Bourne shell script that contains two types of functions. You must save the custom_probes file in the same JumpStart directory where you saved the rules file. The two types of functions that you can define in a custom_probes file are as follows:

Syntax of the custom_probes File

The custom_probes file can contain any valid Bourne shell command, variable, or algorithm.


Note –

You can define probe and comparison functions that require a single argument in the custom_probes file. When you use the corresponding custom probe keyword in the rules file, the argument after the keyword is interpreted (as $1).

When you use the corresponding custom rule keyword in the rules file, the arguments are interpreted in sequence. The sequence starts after the keyword and ends before the next && or begin script, whichever comes first.


The custom_probes file must meet the following requirements:

To improve clarity and organization, define all probe functions first, at the top of the file, followed by all comparison functions.

Syntax of Function Names in custom_probes

The name of a probe function must begin with probe_. The name of a comparison function must begin with cmp_.

Functions that begin with probe_ define new probe keywords. For example, the function probe_tcx defines the new probe keyword tcx. Functions that begin with cmp_ define new rule keywords. For example, cmp_tcx defines the new rule keyword tcx.

ProcedureTo Create a custom_probes File

Steps
  1. Use a text editor to create a Bourne shell script text file. Name the file custom_probes.

  2. In the custom_probes text file, define your probe and comparison functions.


    Note –

    You can define probe and comparison functions that require arguments in the custom_probes file. When you use the corresponding custom probe keyword in the rules file, the arguments after the keyword are interpreted in sequence (as $1, $2, and so on).

    When you use the corresponding custom rule keyword in the rules file, the arguments are interpreted in sequence. The sequence starts after the keyword and ends before the next && or begin script, whichever comes first.


  3. Save the custom_probes file in the JumpStart directory next to the rules file.

  4. Ensure that root owns the rules file and that the permissions are set to 644.

Examples of a custom_probes File and Keyword

You can find additional examples of probe and comparison functions in the following directories:

The following custom_probes file contains a probe and comparison function that tests for the presence of a TCX graphics card.


Example 8–1 custom_probes File

#!/bin/sh
# 
# custom_probe script to test for the presence of a TCX graphics card.
# 

# 
# PROBE FUNCTIONS
# 
probe_tcx() {
  SI_TCX=`modinfo | grep tcx | nawk '{print $6}'`
  export SI_TCX
}

# 
# COMPARISON FUNCTIONS
# 
cmp_tcx() {
  probe_tcx

  if [ "X${SI_TCX}" = "X${1}" ]; then
     return 0
  else
     return 1
  if
}

The following example rules file shows the use of the probe keyword that is defined in the preceding example, tcx. If a TCX graphics card is installed and found in a system, profile_tcx is run. Otherwise, profile is run.


Note –

Always place probe keywords at or near the beginning of the rules file. This placement ensures that the keywords are read and run before other rule keywords that might rely on the probe keywords.



Example 8–2 Custom Probe Keyword Used in a rules File

probe tcx
tcx     tcx     -     profile_tcx     -
any     any     -     profile         -

Validating the custom_probes File

Before you can use a profile, rules, and custom_probes file, you must run the check script to validate that the files are set up correctly. If all profiles, rules, and probe and comparison functions are correctly set up, the rules.ok and custom_probes.ok files are created. Table 8–1 describes what the check script does.

Table 8–1 What Happens When You Use the check Script

Stage 

Description 

check searches for a custom_probes file.

If the file exists, check creates the custom_probes.ok file from the custom_probes file, removes all comments and blank lines, and retains all Bourne shell commands, variables, and algorithms. Then, check adds the following comment line at the end:

# version=2 checksum=num

ProcedureTo Validate the custom_probes File

Steps
  1. Verify that the check script is located in the JumpStart directory.


    Note –

    The check script is in the Solaris_10_606/Misc/jumpstart_sample directory on the Solaris Operating System DVD or on the Solaris Software - 1 CD.


  2. Change to the JumpStart directory.

  3. Run the check script to validate the rules and custom_probes files.


    $ ./check -p path -r file_name
    
    -p path

    Validates the custom_probes file by using the check script from the Solaris software image for your platform instead of the check script from the system you are using. path is the image on a local disk or a mounted Solaris Operating System DVD or Solaris Software - 1 CD.

    Use this option to run the most recent version of check if your system is running a previous version of Solaris.

    -r file_name

    Specifies a file name other than the one that is named custom_probes. By using the -r option, you can test the validity of a set of functions before integrating the functions into the custom_probes file.

    As the check script runs, the script reports the validity of the rules and custom_probes files and each profile. If no errors are encountered, the script reports: “The custom JumpStart configuration is ok” and creates the rules.ok and custom_probes.ok files in the JumpStart directory.

  4. Determine if the custom_probes.ok file is executable.

    • If yes, go to Step 5.

    • If no, type the following command.


      # chmod +x custom_probes
      
  5. Ensure that root owns the custom_probes.ok file and that the permissions are set to 755.