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
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.
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.
:/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=0Note 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.
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.
Methodology Build a command to add the group named by TARGETGROUP, with the gid ASSOCIATEDGIDNUMBER. Return 0 for success, non-zero for failure.
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.
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:
Methodology Build a command to delete the group named by TARGETGROUP. Return 0 for success, non-zero for failure.
Methodology Build a command to delete the user named by TARGETUSER. Return 0 for success, non-zero for failure.
Methodology Different for some platforms, and usually somewhat problematic. Read the script for your platform. Return 0 for success, non-zero for failure.
Methodology Look in in /etc/group for TARGETGROUP. Return 1 for group exists, 0 for group does not exist.
Methodology Look in in /etc/passwd for TARGETUSER. Return 1 for user exists, 0 for user does not exist.
Methodology Different for some platforms, and usually somewhat problematic. Read the script for your platform. Return 0 for success, non-zero for failure.
Methodology Build a command to change the gid of the group named by TARGETGROUP to ASSOCIATEDGIDNUMBER. Return 0 for success, non-zero for failure.
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.
Methodology The default script does nothing. Return 0 for success, non-zero for failure.
Methodology Build a command to prevent the user from logging on. Return 0 for success, non-zero for failure.
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.
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.
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
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.
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.
Methodology ASAMULIST, PULIST and MANAGED are supplied byt he Receiver.
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
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.
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: