Introduction#

This guide assumes you have read the formal documentation that comes with the Linux-Unix Fanout 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.

IMPORTANT:#

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.

The Scripts#

addgroup.sh#

PurposeAdd a new group to a platform.

Methodology Build a command to add the group named by TARGETGROUP, with the gid ASSOCIATEDGIDNUMBER. Return 0 for success, non-zero for failure.

adduser.sh#

PurposeAdd a new user to a platform.

Methodology Build a command to add the user named by TARGETUSER, with the uid ASSOCIATEDUIDNUMBER. Set the gcos-field from any name related information that might be available in GIVENNAME or SURNAME.Return 0 for success, non-zero for failure.

addusertogroup.sh #

PurposeAdd a user to a group.

Methodology The methodology for this script varies from platform to platform. On Solaris, for example, there is no command to add a single user to a particular group, rather, an argument to the usermod command is available to specify a user's entire supplementary group affiliation.

AIX, on the other hand, has a chgrpmem command that can add and delete users from specified groups. Return 0 for success, non-zero for failure. In order to facilitate writing scripts in diverse environments, all the following environment variables are available:

  • PGLISTlist of platform groups user is in.
  • ASAMGLIST list of Census groups user is in.
  • DELGLISTlist of platform groups user should be deleted from.
  • ADDGLISTlist of platform groups user should be added to.
  • TARGETGLISTlist of platform groups user will ultimately be in.

delgroup.sh #

PurposeRemove a group from a platform.

Methodology Build a command to delete the group named by TARGETGROUP. Return 0 for success, non-zero for failure.

deluser.sh#

PurposeDelete a user from a platform.

Methodology Build a command to delete the user named by TARGETUSER. Return 0 for success, non-zero for failure.

disableuser.sh#

PurposePrevent a user from logging onto a platform.

Methodology Different for some platforms, and usually somewhat problematic. Read the script for your platform. Return 0 for success, non-zero for failure.

does_group.exist.sh#

PurposeDetermine if a group exists on a platform.

Methodology Look in in /etc/group for TARGETGROUP. Return 1 for group exists, 0 for group does not exist.

does_user_exist.sh#

PurposeDetermine if a user exists on a platform.

Methodology Look in in /etc/passwd for TARGETUSER. Return 1 for user exists, 0 for user does not exist.

enableuser.sh#

PurposeEnable a user to log on to a platform.

Methodology Different for some platforms, and usually somewhat problematic. Read the script for your platform. Return 0 for success, non-zero for failure.

modgroup.sh#

PurposeChange attributes of a group.

Methodology Build a command to change the gid of the group named by TARGETGROUP to ASSOCIATEDGIDNUMBER. Return 0 for success, non-zero for failure.

moduser.sh#

PurposeChange attributes of a user.

Methodology Build a command to change the uid of the user named by TARGETUSER to ASSOCIATEDUIDNUMBER, and/or reset gcos-field with name related information in GIVENNAME and/or SURNAME.

Return 0 for success, non-zero for failure, or 254 for NOTHINGTODO. On AIX return 126 for NOTHINGTODO.

pendelgroup.sh#

PurposePrepare a group for future deletion.

Methodology The default script does nothing. Return 0 for success, non-zero for failure.

pendeluser.sh#

PurposePrepare a user for future deletion.

Methodology Build a command to prevent the user from logging on. Return 0 for success, non-zero for failure.

platformgetgrnam.sh#

PurposeRecord platform gid of TARGETGROUP in PARMFILE

Methodology Find the gid of TARGETGROUP in /etc/group and output three lines into PARMFILE. The first line is the groupname, the second line is the gid. The third line is EOFMARKER.

The Receiver uses this script to assure that the driver and the platform agree on TARGETGROUP's gid. Gid = -1 causes the Receiver to bypass gid checking. Return 0 for success, non-zero for failure.

platformgetpwnam.sh#

PurposeRecord platform uid of TARGETUSER in PARMFILE

Methodology Find the uid of TARGETUSER in /etc/passwd and output three lines into PARMFILE. The first line is the user name, the second line is the uid. The third line is EOFMARKER.

The Receiver user this script to assure that the driver and the platform agree on TARGETUSER's uid. Uid = -1 causes the Receiver to bypass uid checking. Return 0 for success, non-zero for failure.

platformgroupaff.sh#

Purpose Record platform group-membership information about TARGETUSER.

MethodologyUse groups(1) to find TARGETUSER's group membership. Ignore primary group, focus only on supplementary groups. The Receiver uses this script to assure that the driver and the platform agree on the gids of the groups that TARGETUSER is a member of. GID = -1 causes the Receiver to bypass this check. Output TARGETUSER's groupmembership information (supplementary groupnames and gids) like this:

 gname1,gnum1 
 gname2,gnum2 
 gname3,gnum3 
 ...
 gnameN,gnumN
 EOFMARKER

platformgroupmem.sh#

Purpose Record user names and uids of platform members of TARGETGROUP.

Methodologygrep for group members in /etc/group. Get uid for each groupmember from /etc/passwd. Record one user,uid pair per line. Last line should be EOFMARKER. The Receiver uses this script to assure that the driver and the platform agree on the uids of the users who are members of TARGETGROUP. UID = -1 causes the Receiver to bypass this check.

platformverifyandmapname.sh#

Purpose Check to see that the username or groupname in VERIFY is acceptable for the platform. Check length and character types. Map VERIFY to PlatformAssociation (PA).

MethodologyReject names longer than MAXL. Make sure first character in name is alpha, except on AIX. Make sure that all characters in name are valid. Map uppercase characters to lowercase, except on Linux. Output PlatformAssociation to PARMFILE. Return 0 for success, non-zero for failure.

PlatformAssociation is a mapping of EnterpriseUsername (or EnterpriseGroupname).

PlatformAssociation is very important, and is controlled in this script.

Examples:

| PlatformAssociation
|
 eDir User|SolarisLinux AIX 
 ________ |_________________
|
joe|joe joejoe
Bob|bob Bobbob
7sam|(Rejected) (Rejected)7sam
LongUserName |(Rejected)LongUserName(Rejected) 
|

You have the ability in this script to create algorithms to map names that would otherwise be rejected, if you need to support them, but there are many caveats. If you choose to map the user LongUserName to LongUser, then you would not be able to use the driver to authenticate LongUser. There would also be collision issues to consider.

populategroup.sh#

Purpose Populate a group, taking into account who might currently be in the group, who the driver thinks should be in the group, and who is managed.

Methodology ASAMULIST, PULIST and MANAGED are supplied byt he Receiver.

  • ASAMULISTlist of Census users in TARGETGROUP.
  • PULIST list of platform users in TARGETGROUP.
  • MANAGEDlist of users from ASAMULIST and PULIST who are managed and not excluded.
TARGETULIST and DELETEULIST are calulated by populategroup.sh.

TARGETULIST list of users who should ultimately be in TARGETGROUP.

DELETEULIST list of platform users who need to be deleted from TARGETGROUP.

The methodology varies from platform to platform, depending on the native UNIX commands available. Here's one example:

 
is PULIST in MANAGED?
 no ----> TARGETULIST
 yes ---> in ASAMULIST?
no ----> DELETEULIST

is ASAMULIST in MANAGED?
 yes ---> TARGETULIST

removeuserfromgroup.sh#

Purposeremove TARGETUSER from group.

Methodology There's no need for the default script to do anything. Return 0 for success, non-zero for failure.

renamegroup.sh

PurposeRename a platform group.

Methodology build a command that renames PLATFORMASSOCIATION to TARGETGROUP. Return 0 for success, non-zero for failure.

renameuser.sh#

PurposeRename a platform user.

Methodology Build a command to rename PLATFORMASSOCIATION to TARGETUSER. Rename user's home directory too. Return 0 for success, non-zero for failure.

More Information#

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

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-3) was last changed on 26-Aug-2012 11:34 by jim