Scriptwriters README

Writing UNIX Platform Receiver Scripts#

For The Novell Linux/Unix Fan-Out Driver


This guide assumes you have read the formal documentation that comes with the Novell Nsure Identity Manager Fan-Out driver, and that you are familiar with the concepts and facilities of the driver.

A default set of scripts is provided with each Platform Receiver. The default script set uses native UNIX commands to manage users and groups in traditional flat-files, such as /etc/group and /etc/passwd. Using the default script set as a guide, you can write custom script sets to manage groups and users in diverse environments.

The default scripts use environment variables set by the Receiver as input. Scripts that you write will have access to these environment variables. None of the the default scripts use all the environment variables they have access to. Your custom scripts can use as many of the environment variables as you see fit, or none at all.

All of the default scripts set return codes, and some of the default scripts produce output files that adhere to strict formats. Your custom scripts must produce corresponding return codes and output files.

Each time a Platform Receiver receives a provisioning event from Event Journal Services, some scripts are executed. Which scripts are called, and the order in which they are called, is dependent upon the Event type. Sometimes a script is called more than once during the processing of an Event. Invoking the receiver with the asam_scripts flag causes each script's name to be printed to standard out when it is run. For example:

   asamrcvr -r -d asam_scripts

Getting Started#

Set up a test environment by creating a Platform Set with one platform in it. Create a special Census Search object that is associated only with your new Platform Set.

Secure the target platform by running "asamrcvr -s".

Perform a full sync on the target platform by running "asamrcvr -f".

Use iManager to create an eDirectory user associated with your test Platform Set.

Use iManager to create an eDirectory group associated with your test Platform Set, and add the previously created user to the new group.

Launch an interactive login session on the target platform in a terminal window, and use the UNIX script command to make a record of your terminal session. Enter "man script" if you aren't familiar with the UNIX script command.

Launch another interactive login session on the target platform in another terminal window and run "tail -f" on the syslog file where the Receiver logs its messages.

Type the following line into the terminal window where you are recording your terminal session and press return:

   asamrcvr -r -d "dom asam_scripts asam_platrcvr"

Many lines of output are produced and saved in your typescript file.

There are many combinations of add, modify and delete Events you may study in this manner.

Debug flag meanings:#

  • dom: print the dom documents exchanged between the Receiver and core driver. Many will be protocol documents, the most interesting documents to a script writer will be the eventType "Populate" or "Delete" documents.
  • asam_scripts: trigger the UNIX Receiver to print a script's name to stdout prior to executing the script.
  • asam_platrcvr: cause the UNIX Receiver to create an environment variable called DEBUGMODE and set it to TRUE.Each of the default scripts are designed to go into verbose mode (set -x) when DEBUGMODE is set to TRUE.

Other debug options: #

Perhaps asam_platrcvr will trigger an overwhelming amount of debug output. Instead, you can edit the scripts themselves and surround interesting sections of code with "set -x" and "set +x".

The Receiver maps all the attributes in the Populate and Delete dom documents to environment variables. The Receiver also sets some other environment variables. You can see all of these environment variables by including "printenv" in any script.

Evaluating the Output#

The syslog output should show the UNIX commands that were run from the scripts, along with their return codes. If everything went okay, you should see that the user and group got added to the target platform, and that the user got added to the group. Here's an example of what you might see:
  :/usr/sbin/useradd -m -u 10016 -c 'se user1' seuser1: RC=0
  :/usr/sbin/usermod -G segrp1 seuser1: RC=3
  :/usr/sbin/groupadd -g 10017 segrp1: RC=0
  :/usr/sbin/usermod -g other -G segrp1 seuser1: RC=0
Note that the first usermod command failed, since the group didn't exist yet.

By comparing the output saved in your typescript file to the source of the scripts themselves, you can see, in tedious detail, exactly what happened when each script ran and the order in which the scripts ran. If you choose, you can also see all of the environment variables available to the scripts. Unfortunately, you will also see all the non-driver-related environment variables that are always associated with your login shell. If you find them distracting you can use vi (or your favorite editor) to edit them out of your typescript file.


The coding logic in the default scripts is important only as a means of mapping the available input to the required output. You can modify the logic in the default scripts, or totally replace it, whatever suits your needs, as long as your scripts produce the required output and return codes.

Scripts can only return a byte back to the Receiver, so return values are limited to the range from 0 to 255. Scripts typically return 0 for success and non-zero for failure. A script sometimes need to return a value that signifies that it didn't need to do anything in response to the event that triggered it, typically the NOTHINGTODO return code is 254. High valued return codes (more than 200) are favored for script failures caused by problems internal to the script.

Low valued return codes are typically returned through the scripts from native UNIX commands, and you can interpret these as the native UNIX command's man page specifies, or look them up in errno.h. AIX seems to return a signed value, so there are only seven bits to work with.

Scripts that need to return information that cannot be encoded in a one byte return code write their information into a temporary file. A boilerplate block of code is included in each script that attempts to ensure the safety of the temporary file: temporary files must exist in /tmp, they must not be symbolic links, and they must not exist prior to script execution. End-of-file must be marked with a line containing EOFMARKER.

More Information#

There might be more information for this subject on one of the following: