2.1.1 Core Driver Component Details

The software architecture of the Core Driver includes eight main components. Five of the components are collectively referred to as the Provisioning Manager:

2.2.1 User and Group Management

Management of users and groups on the platform is carried out by Receiver scripts, which are called by the Platform Receiver based on provisioning events obtained from the Core Driver.

2.2.2 User Authentication

Authentication redirection is handled by the Platform Services Process, which is called by the System Intercept. The Platform Services Process is also called by applications using the AS Client API.

Platforms that use password replication receive notification of password changes in eDirectory through the Platform Receiver and send notification of local password changes detected by the password change intercept to the Core Driver using the Platform Services Process.

Account redirection is handled by the Platform Services Cache Daemon, which is called by the Name Service Switch. Platforms that are configured for account redirection use a local memory cache pool for account records and retrieve all account and password information from this cache.

2.2.3 Platform Configuration File

You use the platform configuration file to specify Platform Services configuration information, such as

2.3.1 The ASAM Master User Object

The Core Driver processes perform an LDAP Bind as the ASAM Master User to gain access to eDirectory. The ASAM Master User object can be specified during installation.

The ASAM Master User must have Supervisor rights to the container in eDirectory that holds the users and groups that can be added to the Census. This is known as the User and Group Subtree. These rights are granted during installation.

To use the AS Client API to access objects outside of the User and Group Subtree, you must grant additional rights to the ASAM Master User.

2.3.2 Configuration-Oriented Objects

Configuration information for Identity Manager Fan-Out Driver components is stored in objects that correspond to them.

Identity Manager Fan-Out Driver program component configuration objects list each of their host server network addresses. Before accepting a communication connection from another component, driver components verify that the connection originates from a network address listed in the corresponding configuration object.

2.3.3 Census Container

Based on your specifications, Object Services maintains a Census of users and groups of users for use with target platforms. Users in the Census are represented by Enterprise User (eUser) objects. Groups of users in the Census are represented by Enterprise Group (eGroup) objects.

Object Services uses events from the Event Subsystem to maintain the Census. Object services of the primary Core Driver also periodically trawls eDirectory for information to ensure the validity of the Census.

Authentication Services uses eUser objects in the Census to locate the corresponding User objects in eDirectory for password verification and other functions. For information about associating eUsers and eGroups from the Census with sets of platforms for provisioning purposes, see Section 2.3.5, Platform Set Objects.

You use the Web interface to specify Census Search objects that identify the users and groups that are to be included in the Census.

Search objects can get Enterprise Users from

Search objects can get Enterprise Groups from

2.3.4 Platform Objects

A Platform object represents a specific target platform that runs Platform Services.

2.3.5 Platform Set Objects

Platform Set objects provide the relationship between Search objects and Platform objects. You can use Platform Sets to group together multiple platforms that share the same user and group population.

The following example illustrates how you can fan out your user and group population to platforms that are grouped into Platform Sets.

4.2.1 eDirectory

Tuning eDirectory on your network is beyond the scope of this document. Much documentation on this subject is available elsewhere, including NetIQ Technical Information Documents (TIDs), which are available at the NetIQ Support Web site. The health and performance of eDirectory is critical to the ability of the driver to respond to Authentication Services requests and to deliver provisioning events in a timely manner. Therefore, the health and performance of eDirectory should be your starting point in doing any performance planning and troubleshooting with the driver.

Factors in driver performance relative to eDirectory include

The driver interfaces with eDirectory through LDAP. For LDAP tuning guidance, see the NetIQ eDirectory Administration Guide.

4.2.2 Object Services and the Event Subsystem

The Object Services component of the Core Driver is primarily responsible for maintaining the Census and other objects in the ASAM System container. Object Services receives provisioning events from the Event Subsystem, updates the Census as required, and passes the provisioning events to Event Journal Services. It is important for Identity Provisioning that the Core Driver be running at all times, but it is mostly a background process that does not require a great deal of processing power and is, for the most part, not a time-critical process.

Object Services performs Trawls to initially build and to verify the Census by performing a series of requests based on the Census Search objects defined in your configuration. For each Organizational Unit represented in the configuration, Object Services issues a single request to eDirectory to return all the objects contained in the given Organizational Unit.

Focus your Search objects to the specific directory locations of your users and groups rather than specifying a top level container object. This provides better feedback information during a Trawl and reduces the likelihood of an LDAP time-out because of slow servers or slow network links.

The Event Subsystem uses Identity Manager to provide events to Object Services. The Event Subsystem requires minimal processing power, but it does require replicas for all objects that are monitored. Network connectivity and eDirectory synchronization are the primary performance factors for the Event Subsystem.

For optimal performance, a writable partition of all replicas containing objects contained in the Census should reside on the same server as the LDAP host server used by a Core Driver. However, be aware that operations that lock the directory on the local server, such as running NDSRepair, sometimes delay requests or cause them to fail.

4.2.3 Event Journal Services

Event Journal Services waits for Platform Receivers to connect, then provides pending events and a snapshot of User and Group objects for processing. Network connectivity to the platforms, and proximity of the Core Driver to servers holding replicas of managed User and Group objects are the primary performance factors for Event Journal Services.

Platforms with very large numbers of managed users and groups should be connected to Event Journal Services with connections of adequate bandwidth to ensure that Full Sync Mode and Check Mode processing will complete within an acceptable time.

To reduce the number of concurrent connections that must be serviced by a Core Driver host, avoid using Persistent Mode on Platform Receivers.

4.2.4 Authentication Services

Authentication Services is responsible for processing requests made by Platform Services.

For optimal performance, LDAP host servers used by Core Drivers should hold a writable replica that contains the User objects represented in the Census, and other objects that might be referenced often by Authentication Services.

4.2.5 Platform Systems

Platform Services sends requests to the Core Driver. The systems on which Platform Services reside can be anything from a desktop workstation to a high-end mainframe system. The inherent performance of these systems is based on a number of factors, including

Consider each of these as you configure each platform and as you select the location of the Core Drivers.

4.2.6 Platform Services / Authentication Services Relationship

The performance of the Platform Services / Authentication Services transaction is the most important performance relationship in the driver. The communication relies on the TCP/IP stack of the platform and Authentication Services server. TCP/IP configuration on the platform, the Authentication Services server, and the routers in between is the most important factor in the performance of servicing Authentication Services requests. Guidelines for configuring TCP/IP are beyond the scope of this section. Refer to appropriate NetIQ and platform operating system documentation and TIDs for further information.

Platform system planners should be aware of a mandatory three-second delay in reporting a bad password on a password check request. This delay is in eDirectory itself. It cannot be configured by the driver.

4.3.1 User Rights Requirements

The installation and configuration of the driver requires a user with full administrative rights and privileges in eDirectory and on the target systems. You can grant more limited rights to other users to use the Fan-Out Driver Web interface for administrative functions. For details of rights needed for administrative functions, see Rights Required for Web Application Use.

4.3.2 Password Replication Requirements

If you use password replication, you must ensure that the driver is notified of changes to passwords.

For information about installing and configuring the password intercepts, see Section IV, Platform Services Administration.

4.3.3 Core Driver Requirements

4.3.4 Requirements for Workstations Used for Installation and Administration

The workstations used to install, configure, and administer the driver must meet the following requirements.

4.3.5 Platform Services Requirements

For information about required systems and software, as well as supported platforms and operating environments, see the Identity Manager 4.7 Drivers Documentation Web site. From this index page, you can select a Readme file associated with the platform(s) for which you need Fan-Out Driver support.

5.1.1 Essentials

5.1.2 Other Advance Considerations

Topics in this section include:

5.1.3 General Installation Sequence

Following is a general overview of the process for installing the Core Driver.

5.2.1 Installing the Driver Shim on Linux or Solaris

Core Driver installation on Linux and UNIX begins with one of the following tasks, depending on your scenario:

5.2.2 Installing the Driver Shim on Windows Systems

Core Driver installation on Windows begins with one of the following tasks, depending on your scenario:

5.2.3 Setting Up the Core Driver in iManager

You will use the Fan-Out Driver’s Web application to complete the Core Driver installation. This application resides in recent versions of iManager as a standard plug-in. If your version of iManager does not include the plug-in, you can install it from the software that comes with the Core Driver.

After you have installed or upgraded a Driver Shim, the installation process continues in iManager with the following tasks, depending on your scenario:

If your version of iManager does not include the plug-in or if you are not familiar with iManager, you can refer to two additional topics at the end of this section before starting:

5.2.4 Other Tasks Following Installation

After the initial installation or upgrade of a Core Driver, other tasks that you may need to perform from time to time include the following:

  ASAM/data/CoreDriver/certs/ca_cert.pem
  ASAM/data/CoreDriver/certs/ca_key.pem
  ASAM/data/CoreDriver/certs/ca.pem

chkconfig asamcdrvd on

5.4.1 Secondary Drivers

Adding secondary Drivers can provide your Fan-Out platform clients with failover and load balancing. If you have multiple eDirectory servers and plan to deploy the Fan-Out Platform Services to many different systems, it’s recommended that you install and deploy the Fan-Out driver to more than one server.

5.4.2 Platform Operation Modes

The Fan-Out Platform Receiver, the component that connects to the Core Driver to receive events from Identity Manager, can be configured to run in five different operation modes (see Section 8.8.1, Modes of Operation). Three of these modes, in particular, may have an impact on the performance of the Core Driver Shim, as described in Table 5-1.

6.1.1 Core Driver Configuration

Core Driver configuration information is maintained in the Driver object and in objects in the ASAM System container. The Core Driver installation process creates the initial configuration.

You use iManager to maintain the configuration information.

You also can use the Driver Shim configuration file to make setting about how the Core Driver communicates with Platform Services. For information about options in the fanout.conf file see Section 6.6, The Driver Shim Configuration File.

6.1.2 Platform Services Configuration

The Core Driver maintains configuration objects that represent each target platform for its own use in the ASAM System container.

Target platforms each obtain local configuration information from their respective platform configuration file. For more information about the platform configuration file, see Section III, Platform Services Planning.

6.2.1 Connection Security

The connections between Core Driver components and between Event Journal Services and Platform Receivers use Secure Sockets Layer (SSL). Some types of the Platform Services Process use SSL for their connections to Authentication Services, and others use DES encryption. SSL connections are authenticated through the use of certificates.

The certificates used by the Identity Manager Fan-Out Driver are minted by the Certificate Services component of the Core Driver. When you install and configure a new component, you obtain a certificate.

Because platforms cannot examine the configuration objects for the Core Driver in the ASAM System container, Core Driver network address information is included in their certificates under the X.509 Alternate Subject field. This address is specified at installation time and must contain a reverse-lookup DNS record for the Platform Services components to establish trust to the Core Driver. If the address is not resolvable, the Platform Services installation will fail. Likewise, if the address associated with the Platform object does not have a reverse-resolvable DNS record, the Core Driver will not trust the Platform component and therefore will not establish an SSL connection.

The Core Driver certificate is minted when you start the Core Driver for the first time. When you update network address information for a Core Driver, a new certificate is automatically minted for it. You must restart a Core Driver after changing its network address information in order for the new certificate to take effect.

Obtain a new certificate for a platform by starting the Platform Receiver with the appropriate command line parameter. For details, see Section IV, Platform Services Administration.

Identity Manager Fan-Out Driver components store their security certificates and related information in their certs directory. Ensure that access to the certs directory is restricted to the driver system itself and to its administrators.

6.2.2 ASAM Master User Security

The Core Driver performs an LDAP bind as the ASAM Master User to gain access to eDirectory. You must not place restrictions on the ASAM Master User object that would interfere with its use by the driver. Set maximum password length for the ASAM Master User to at least 32 characters. Disable intruder detection for the ASAM Master User object so that it cannot be disabled by someone without the appropriate rights.

The ASAM Master User must have Supervisor rights to the container in eDirectory that holds the users and groups that can be added to the Census. This is known as the User and Group Subtree. These rights are granted during installation.

To use the AS Client API to access objects outside of the User and Group subtree, you must grant additional rights to the ASAM Master User.

Because the ASAM Master User is granted significant rights, you must ensure that its password remains secure.

The Core Driver obtains the password of the ASAM Master User from the Driver object. If your security practices prescribe periodic password changes, you can create a second User object to be used as an alternate ASAM Master User. Then you can swap back and forth between these User objects when it is necessary to change the password.

6.3.1 Monitoring Core Drivers

You can use the Fan-Out Driver Web application to view component status. For additional information, see Section 6.5.10, Displaying Component Status.

From time to time, depending on the size of the organization and the amount of activity, a system administrator should review the logs written by Core Driver components in order to check the health of the system. For example, you might want to investigate the cause of a large number of denied SSL connection requests. For more information about viewing logs, see Section 6.5.12, Viewing Logs.

The Fan-Out Driver also generates its own messages for purposes of monitoring and troubleshooting. These messages, which are documented in Section D.0, Messages. can also be redirected into your own custom programs and status documents to free your administrators from manual Fan-Out log-tracking.

6.3.2 Monitoring Platform Services

It is a good idea to monitor the logs written by Platform Services. For details about these logs, see the administration guide for your platform operating system.

6.3.3 Maintaining the Census

Administrative personnel should periodically use the Web interface to monitor naming exceptions and inactive users and groups. The frequency at which this is done is a function of the size of the organization being managed, the rate at which changes take place, and the rules in place within the organization concerning unique user IDs in eDirectory. If the organizational structure is appropriate, the same people who manage User objects also maintain the Census.

The actions taken depend on the policies of the individual organization. Some lines follow. For a review of the concepts, see the Section I, Concepts and Facilities.

6.4.1 Using iManager With the Fan-Out Driver Plug-In

For detailed information about using iManager, refer to the iManager Administration Guide for your version of the product at the NetIQ Documentation site.

You configure and administer the Identity Manager Fan-Out Driver using iManager Roles and Tasks. The left side of the display lists actions you can take. Information pertaining to the action you select is displayed on the right side.

Obtaining Additional Information

Figure 6-1 Additional Information Icon

Additional information is available for the items and procedures in the Web application. To display this information, click the Additional Information icon.

Maintaining Lists

Figure 6-2 List of Items

Many items in the Fan-Out Driver Web application are grouped into lists.

To add an item to a list, click the Add button.

To view or change the attributes of an item, click its name in the list.

To remove an item from a list, click the Remove button for that item. A confirmation page is displayed. Click Yes to confirm removal, or click your Web browser’s Back button to abort.

6.4.2 Using Designer With the Fan-Out Driver Plug-In

NetIQ Designer is a graphical user interface tool that allows you to model and deploy Identity Manager installations. Designer includes a Fan-Out Driver plug-in that enables you to configure Fan-Out data (such as Search Objects, Platforms, and Platform Sets) before deploying the Driver to eDirectory. With Designer you can also perform mass imports much more efficiently than with iManager.

Figure 6-3 Identity Manager Designer Interface with Fan-Out Driver Plug-in.

6.5.1 Configuring the Census

Configuring the Census includes the following tasks:

6.5.2 Configuring Core Drivers

Core Drivers provide the Web interface, perform Census maintenance functions, and provide Authentication Services and Identity Provisioning to platforms.

6.5.3 Configuring the iManager Plug-In

Each administrative user must configure the iManager plug-in to use the primary Core Driver.

6.5.4 Configuring Logs

Audit Services maintains the Operational Log and Audit Log files written by the Core Driver. You can use the Web interface to manage log files. You can choose to have log messages kept for a given number of days, or you can choose to have log messages kept permanently. You can also specify the components whose messages are written to the logs.

You can use the Web interface to view log messages. For more information, see Section 6.5.12, Viewing Logs.

The Log Configuration page is also used to configure debugging logging. For more information, see Section 7.1, Obtaining Debugging Output.

6.5.5 Configuring Platform Sets

A Platform Set contains one or more Platform objects that share the same users and groups.

When you add a new Platform Set, you first need to give it a name and associate it with a UID/GID Set. If the Platform Set is for Linux or UNIX systems, you have the option of using Posix attributes instead of a UID/GID set.

You also may specify an Alternate Naming Attribute. When a user or group is provisioned to a Platform within this Platform Set, the Alternate Naming Attribute indicates the name that will be used. Then you add Search objects that describe what users and groups are provisioned to the platforms that belong to the Platform Set.

After you have defined a Platform Set, you can create the Platform objects that represent its target platforms. For information about creating Platform objects, see Section 6.5.6, Configuring Platforms.

The Platform Set object's user and group population is described by one or more Search objects. For details about Search objects, see Section 6.5.8, Configuring Search Objects.

6.5.6 Configuring Platforms

A Platform object contains the configuration information the Core Driver uses to serve a platform for Authentication Services and Identity Provisioning. Additional configuration of Platform Services is performed on the platform. For detailed information about configuring and administering Platform Services, see the Section III, Platform Services Planning.

6.5.7 Configuring Provisioning

Provisioning configuration involves three attributes.

6.5.8 Configuring Search Objects

Search objects determine the users and groups that are included in the Census and Platform Set populations.

Start a Trawl after you make Search object changes. For details about starting a Trawl, see Starting a Census Trawl.

6.5.9 Configuring Linux/UNIX UID/GID Sets

A UID/GID Set contains entries for users and groups, together with their corresponding Linux/UNIX UID and GID numbers.

A UID/GID Set is associated with each Platform Set so that the UID and GID numbers of users and groups managed by driver are the same on all Linux/UNIX platforms within the Platform Set.

When a new user or group is added to a Platform Set, it receives the next available UID/GID number.

You can reserve a range of numbers for local use by the platform administrators. The driver does not assign UID or GID numbers within the reserved range.

Leave this option empty to use the posixAccount and posixGroup uidNumber and gidNumber attributes.

6.5.10 Displaying Component Status

To display a status overview of your Identity Manager Fan-Out Driver system, click Fan-Out Driver Utilities > Component Status in the Web interface.

To display status details for a component, click the component name on the Status Overview page.

6.5.11 Viewing Driver Documentation

You can use the Web interface to view documentation for the Identity Manager Fan-Out Driver. To view the documentation, click Fan-Out Driver Utilities > Documentation.

6.5.12 Viewing Logs

You can use the Web interface to view log files. You can also use Audit to view log information.

6.5.13 Displaying Provisioning Details

You can use the Web interface to search for and display objects in the Census and in the user and group population of a Platform Set.

6.5.14 Reviewing Naming Exceptions

Naming exceptions are produced when a new User or Group object covered by a Census Search object is found with the same name as an Enterprise User or Enterprise Group object that is already present in the Census.

To review naming exceptions in the Web interface, click Fan-Out Driver Utilities > Review Naming Exceptions.

6.5.15 Reviewing Platform Errors

The Platform Receiver can return an error indication for its processing of a provisioning event. Such events remain pending for the platform, but are marked in an error state. You can use the Web interface to clear these events or to mark them to be sent to the Platform Receiver again.

If additional events for a user or group associated with a platform are created (by a Trawl or by the Event Subsystem), pending events that are in error are cleared for that user or group.

6.5.16 Managing Trawls

Object Services examines portions of eDirectory specified by Census Search objects to build and maintain the Census. This process is known as a Trawl. Only the primary Core Driver performs Trawls. For information about setting the primary Core Driver, see Designating the Primary Core Driver.

You can use the Web interface to display information about the last Trawl, to start a Trawl, and to stop a Trawl that is in progress.

6.7.1 Certificate Properties

Each certificate can be viewed in plaintext, using the OpenSSL command:

    openssl x509 -in <path to certificate.pem> -text

    Certificate:
        Data:
            Version: 3 (0x2)
            Serial Number: 1002 (0x3ea)
            Signature Algorithm: sha1WithRSAEncryption
            Issuer: CN=Novell Account Management 3.1 Certificate Authority
            Validity
                Not Before: Sep 30 15:30:42 2014 GMT
                Not After : Oct  1 15:30:42 2015 GMT
            Subject: CN=localhost, OU=localhost, OU=platform sets, 
        OU=event driven objects, OU=asam system, O=system
              .  .  .

The contents contain important fields, such as the Subject Name, DNS Alternate Subject Names, Serial Number, Before and After Dates, and Issuer. A combination of these fields are used to verify access during communication.

Alternatively, you can find the Certificate Expirations for everything in the Fan-Out Driver iManager Plug-In:

6.7.2 Certificate Configuration

Certificates are created for Core Drivers during Core Driver startup, and for Platforms during the Platform Services installation and secure task. During this process, the Core Driver uses two attributes on the cn=Certificate Services,ou=Manager Services,ou=ASAM System object:

  <definition display-name="Verify serial number of incoming platform connection: " 
       id="111" 
       name="verifySerialNumber" 
       type="boolean">
    <description>During the SSL handshake between the driver and the connecting platform, the serial number can be verified against the last serial number generated by the core driver.  Enter a value of "true" if you wish to verify this serial number upon connecting.</description>
    <value>false</value>
	  </definition>

The definition above configures whether this Core Driver should validate Platform serial numbers when attempting to establish a connection.

6.7.3 Renewing Platform Certificates

When a Platform Services is installed, a platform certificate is issued and an expiration date is stamped on the certificate “Not Before” field. The duration of this certificate depends upon the Certificate Services attribute “ASAM-certDelayExpireTime” value. This is global for all platforms and core drivers. When a certificate is approaching expiration, a message may be displayed and logged to the system syslog to indicate:

  CRT012A Platform Certificate will expire on 20151001153042Z

You can renew the platform certificate by running the following command:

  /usr/local/ASAM/bin/PlatformServices/PlatformReceiver/asamrcvr -t

After obtaining the new certificates, simply re-start any services that are using it, such as asampsp or asamrcvr.

6.7.4 Renewing Core Driver Certificates

When a Core Driver is installed, a certificate is issued and an expiration date is stamped on the certificate Not Before field during shim startup. The duration of this certificate depends upon the Certificate Services attribute ASAM-certExpirationDelay value. This is global for all platforms and core drivers. When a certificate is approaching expiration, a message may be displayed and logged to the system syslog to indicate:

  CRT013A Core Driver Certificate will expire on 20151001153042Z

You can recreate the Core Driver certificates with a couple methods. Changing any of the Core Driver object properties, such as Network Address and restarting the Core Driver will automatically regenerate a new certificate. Alternatively, you may simply delete the ca.pem file and restart the Core Driver to allow it to regenerate a new certificate.

6.7.5 Renewing the Root CA

The Root CA for the Fan-Out driver is the most important certificate, as it is used to issue and sign all certificate files for Platforms and Core Drivers. This certificate has a duration of 10 years. However, when it is renewed, a few steps must be followed. This procedure preserves the Root CA’s key, which is necessary to keep platform and core driver certificates valid, so do not delete the ca_key.pem:

7.1.1 Debugging the Core Driver

7.2.1 Rights Issues

Ensure that rights are properly set to enable the driver to perform its functions.

7.2.2 Platform Services Process / Authentication Services Issues

7.2.3 Platform Receiver / Event Journal Services Issues

7.2.4 Census Issues

7.3.1 IP Connections

To verify IP Connections between platforms and the Core Driver, use the ping command. From a command prompt on the Linux, UNIX or Windows system, use a command prompt to enter ping ipaddr, where ipaddr is the IP address of the remote computer.

7.3.2 Firewalls

Firewalls can disrupt connectivity between the Core Driver and its connected systems. To verify that the TCP port is reachable, use a command prompt to enter telnet ipaddr 3451, where ipaddr is the IP address of the remote computer. The TCP port 3451 is used by the Core Driver for communication with the connected platforms.

7.3.3 DNS

Check DNS if you are using named hosts in your platform or Core Driver address configurations. DNS resolution is necessary to verify certificates for SSL communication.

8.8.1 Modes of Operation

The Platform Receiver can be configured to obtain and process provisioning events in five different modes.

8.8.2 Selecting a Mode of Operation

You specify the mode of operation for the Platform Receiver through the RUNMODE statement in the platform configuration file or through a command line parameter. For details about specifying the RUNMODE statement, see Section 10.3.24, RUNMODE Statement.

You can periodically run the Platform Receiver in Full Sync Mode to ensure that accounts on the platform are consistent with eDirectory.

For routine operations, we recommend that, unless you need the real-time processing of events provided by Persistent Mode, you run the Platform Receiver in Polling Mode or Scheduled Mode. This reduces the number of concurrent connections that must be serviced by the Core Driver host. The frequency of change activity in the population, the operating schedule of the platform, and the nature of the connection between the platform and the Core Driver should help you determine which of these modes to use.

You can use Check Mode for testing extensions to Receiver scripts.

9.2.1 Users, Passwords, and Groups

In order for users to be able to log in to the operating system using Authentication Services, they must be defined to the operating system on the platform. You can automate account maintenance through the use of provisioning events. For details about managing accounts, see Section 8.3, Identity Provisioning.

Users, passwords, and groups in eDirectory™ that do not conform to the character set and length restrictions imposed by your operating system cannot participate in Authentication Services or Identity Provisioning on your platform.

The Identity Manager Fan-Out Driver does not support authentication or password change for users having a null password.

In some cases, a system other than eDirectory might contain the users that you want to participate with the Identity Manager Fan-Out Driver. There are tools, such as LDIF, that you can use to import these users into eDirectory. If you cannot extract the passwords for the affected user accounts, you can use the Password Migration component of the Fan-Out Driver. This component can help you accomplish a smooth transition to basing your user accounts in eDirectory.

9.2.2 Connection Security

The connection between the Platform Receiver and Event Journal Services uses Secure Sockets Layer (SSL). SSL connections are authenticated through the use of certificates. Some types of the Platform Services Process use SSL for their connections to the Core Drivers for Authentication Services, and others use DES encryption.

Obtaining a security certificate for your platform from the Core Driver requires that you supply the fully distinguished name and password of an eDirectory user with Read and Create object rights to the ASAM System container.

Identity Manager Fan-Out Driver platform certificates are stored in the data\ platformservices\certs subdirectory of the ASAM directory of their host server file system. Ensure that access to the certs directory is limited to the appropriate users.

9.2.3 Administrative Password Resets

Administrative password resets must be done through an eDirectory utility, such as iManager, or through a program that uses the AS Client API.

9.2.4 Securing the AS Client API

Use of the AS Client API is secured on IBM i and UNIX platforms through SSL and a token that is stored in the asam\data\platformservices\certs directory by the Platform Services Process. Ensure that access to the certs directory is limited to the appropriate users.

Use of the AS Client API is secured on z/OS Platforms through the Authorized Program Facility (APF). Ensure that access to the z/OS Platform Services Load Library is limited to the appropriate users.

10.3.1 ADMINPASSWORD Statement

The ADMINPASSWORD statement specifies the password of the administrative user specified by the ADMINUSER statement. If there is no ADMINPASSWORD statement, you are prompted to enter the password when obtaining a platform security certificate.

Syntax:

ADMINPASSWORD Pswd

Pswd specifies the password of the administrative user.

Example:

ADMINPASSWORD 18emf25dhf

10.3.2 ADMINUSER Statement

The ADMINUSER statement specifies the fully distinguished name of an eDirectory user with Read and Create object rights to the ASAM System container. If there is no ADMINUSER statement, you are prompted to enter a user object name when obtaining a platform security certificate.

Syntax:

ADMINUSER Fdn

Fdn specifies the fully distinguished name of an eDirectory user with Read and Create object rights to the ASAM System container.

Example:

ADMINUSER .Admin.DigitalAirlines

10.3.3 AM.GROUP.INCLUDE Statement / AM.GROUP.EXCLUDE Statement

AM.GROUP.INCLUDE and AM.GROUP.EXCLUDE provide a list of specific groups or group masks to be included or excluded from Identity Provisioning. This can be useful for installation verification and early implementation and for special groups that should be managed locally. Multiple AM.GROUP.INCLUDE and AM.GROUP.EXCLUDE statements can be coded, and they can be mixed together. There is no limit to the number of groups that can be included or excluded.

Syntax:

AM.GROUP.INCLUDE GroupMask[ GroupMask, GroupMask ...]

AM.GROUP.EXCLUDE GroupMask[ GroupMask, GroupMask ...]

GroupMask can be a single complete group name, or it can include masking characters to represent more than one group. If more than one GroupMask matches a given group, the most specific GroupMask is used. GroupMask is case-insensitive. For more information, see Section 10.4.1, Mask Characters and Examples.

Unless AM.GROUP.EXCLUDE * is coded, AM.GROUP.INCLUDE * is always assumed. Certain special groups are always excluded unless the IGNORESTANDARDEXCLUDES statement is specified. For details, see Section 10.3.13, IGNORESTANDARDEXCLUDES Statement.

Do not code both an AM.GROUP.INCLUDE statement and an AM.GROUP.EXCLUDE statement.

For more information, see Section 10.4, Using Include and Exclude Configuration Statements.

Example:

AM.GROUP.EXCLUDE sales, mkt*

10.3.4 AM.USER.INCLUDE Statement / AM.USER.EXCLUDE Statement

AM.USER.INCLUDE and AM.USER.EXCLUDE provide a list of specific user IDs or user ID masks to be included or excluded from Identity Provisioning. This can be useful for installation verification and early implementation and for special user IDs that should be managed locally. Multiple AM.USER.INCLUDE and AM.USER.EXCLUDE statements can be coded, and they can be mixed together. There is no limit to the number of users that can be included or excluded.

Syntax:

AM.USER.INCLUDE UserMask[ UserMask, UserMask ...]

AM.USER.EXCLUDE UserMask[ UserMask, UserMask ...]

UserMask can be a single complete user ID, or it can include masking characters to represent more than one user ID. If more than one UserMask matches a given user ID, the most specific UserMask is used. UserMask is case-insensitive. For more information, see Section 10.4.1, Mask Characters and Examples.

Unless AM.USER.EXCLUDE * is coded, AM.USER.INCLUDE * is always assumed. Certain special users are always excluded unless the INGORESTANDARDEXCLUDES statement is specified. For details, see Section 10.3.13, IGNORESTANDARDEXCLUDES Statement.

Do not code both an AM.USER.INCLUDE * statement and an AM.USER.EXCLUDE * statement.

Identity Manager Fan-Out Driver Linux/UNIX platforms always manage root locally.

For more information, see Section 10.4, Using Include and Exclude Configuration Statements.

Example:

AM.USER.EXCLUDE act*, billing%, sys*, sales48

10.3.5 AS.USER.INCLUDE Statement / AS.USER.EXCLUDE Statement

AS.USER.INCLUDE and AS.USER.EXCLUDE provide a list of specific user IDs or user ID masks to be included or excluded from Authentication Services. This can be useful for installation verification and early implementation and for special user IDs that should be authenticated locally. Multiple AS.USER.INCLUDE and AS.USER.EXCLUDE statements can be coded, and they can be mixed together. There is no limit to the number of users that can be included or excluded, although a large list can cause a performance impact because it must be searched for every user login. These statements apply to system authentications only and are not used by the AS Client API routines (although there is an API call to test whether a user ID is excluded).

Syntax:

AS.USER.INCLUDE UserMask[ UserMask, UserMask ...]

AS.USER.EXCLUDE UserMask[ UserMask, UserMask ...]

UserMask can be a single complete user ID, or it can include masking characters to represent more than one user ID. If more than one UserMask matches a given user ID, the most specific UserMask is used. UserMask is case-insensitive. For more information, see Section 10.4.1, Mask Characters and Examples.

Unless AS.USER.EXCLUDE * is coded, AS.USER.INCLUDE * is always assumed. Certain special users are always excluded unless the INGORESTANDARDEXCLUDES statement is specified. For details, see Section 10.3.13, IGNORESTANDARDEXCLUDES Statement.

Do not code both an AS.USER.INCLUDE * statement and an AS.USER.EXCLUDE * statement.

For more information, see Section 10.4, Using Include and Exclude Configuration Statements.

Example:

AS.USER.EXCLUDE act*, billing%, sys*, sales48

10.3.6 ASAMDIR Statement

The ASAMDIR statement specifies the file path where the Identity Manager Fan-Out Driver is installed. Fan-Out Driver components use ASAMDIR to find files needed for execution.

Syntax:

ASAMDIR FilePath

FilePath specifies the location in file system where the component is installed. If there is no ASAMDIR statement, FilePath defaults as follows:

Example:

ASAMDIR c:\novell\asam

10.3.7 AUTHENTICATION Statement

The AUTHENTICATION statement specifies the network address and port of one Core Driver used for Authentication Services. In order to use Authentication Services, you must have at least one AUTHENTICATION statement in your configuration file.

A maximum of 100 AUTHENTICATION statements can be coded.

Syntax:

AUTHENTICATION Address [PORT PortNumber] [PREF PrefGroup]

Address specifies the DNS name or IP address of a Core Driver used for Authentication Services.

PortNumber specifies the TCP port number that is to be used to communicate with this Core Driver. PORT is optional. PortNumber defaults to 3451.

PrefGroup specifies the Preference Group Number that determines the way a Core Driver is selected. It is optional, and the default is for all Core Drivers listed to be in Preference Group 1. Core Drivers within a Preference Group are selected equally for load balancing. Core Drivers with the lowest Preference Group Number are always tried first, followed by the Core Drivers with the next Preference Group Number, and so on, until a Core Driver can be contacted. Preference Group Number must be coded as a positive integer.

Examples:

AUTHENTICATION cdriver1.digitalairlines.com
AUTHENTICATION cdriver2.digitalairlines.com
AUTHENTICATION cdriver5.digitalairlines.com PORT 5009 PREF 2

10.3.8 CODEPAGE Statement

The CODEPAGE statement specifies a code page to be used by the Platform Receiver. Data received and sent by the Platform Receiver is encoded in UTF-8.

Syntax:

CODEPAGE   CodepageID

CodepageID specifies the code page to be used by the Platform Receiver for converting values from and to UTF-8. For information about the available choices for CodepageID, see the man page for iconv on your system.

If no CODEPAGE statement is present, UTF-8 values are used without conversion.

Example:

CODEPAGE iso88591

10.3.9 DEBUGLOGFILE Statement

The DEBUGLOGFILE statement specifies a destination file for debugging data written when the -d command line parameter is present for a component.

Syntax:

DEBUGLOGFILE FilePath

FilePath specifies the location in file system where the debugging output is to be written.

Example:

DEBUGLOGFILE /usr/local/ASAM/debug.txt

10.3.10 DEBUGTOSTDOUT Statement

The DEBUGTOSTDOUT statement specifies that debugging data is to be written to the standard output channel stdout when the -d command line parameter is present for a component.

Syntax:

DEBUGTOSTDOUT

Example:

DEBUGTOSTDOUT

10.3.11 DIRECTTOAUTHENTICATION Statement

The DIRECTTOAUTHENTICATION statement causes Authentication Services to connect directly to a Core Driver for Authentication Services without using the Platform Services Process. Use the DIRECTTOAUTHENTICATION statement on platforms where the volume of traffic with Core Drivers is so low that running the Platform Services Process is not justified.

Platforms using the DIRECTTOAUTHENTICATION statement do not perform Core Driver load balancing, although failover support is available if you specify multiple AUTHENTICATION statements.

Syntax:

DIRECTTOAUTHENTICATION

Example:

DIRECTTOAUTHENTICATION

10.3.12 ENTROPY Statement

The ENTROPY statement specifies the file where components obtain entropy for SSL.

Syntax:

ENTROPY   FilePath

FilePath specifies the file that contains entropy.

If no ENTROPY statement is coded, the default is to use the /dev/random device for entropy. If there is no /dev/random device, the default entropy file is /etc/entropy.

If your platform has a /dev/random device, you do not need to code an ENTROPY statement.

Example:

ENTROPY /etc/entropy

10.3.13 IGNORESTANDARDEXCLUDES Statement

The IGNORESTANDARDEXCLUDES statement specifies that the standard list of users and groups excluded from Identity Provisioning and Authentication Services processing is not used. If this statement is not present, the standard list of excludes is used. For the standard list of excluded users and groups, see Section 8.10, Standard Exclude List.

Syntax:

IGNORESTANDARDEXCLUDES

Example:

IGNORESTANDARDEXCLUDES

10.3.14 LOCALE Statement

The LOCALE statement identifies the language to be used by the component.

Syntax:

LOCALE Id

Id specifies the two-character ISO 639 language identifier.

Example:

LOCAL en

10.3.15 PASSWORDPROMPT Statement

The PASSWORDPROMPT statement specifies the prompt issued by the PAM module to request the user's password for authentication.

Syntax:

PASSWORDPROMPT Text

If there is no PASSWORDPROMPT statement, Text defaults to

"NDS Password: "

Example:

PASSWORDPROMPT "Password: "

10.3.16 PASSWORDPROMPTCURRENT Statement

The PASSWORDPROMPTCURRENT statement specifies the prompt issued by the PAM module to request the user's current password for password changes.

Syntax:

PASSWORDPROMPTCURRENT Text

If there is no PASSWORDPROMPTCURRENT statement, Text defaults to

"Current NDS Password: "

Example:

PASSWORDPROMPTCURRENT "Enter Current Password: "

10.3.17 PASSWORDPROMPTCHANGE Statement

The PASSWORDPROMPTCHANGE statement specifies the prompt issued by the PAM module to request the user's new password for password changes.

Syntax:

PASSWORDPROMPTCHANGE Text

If there is no PASSWORDPROMPTCHANGE statement, Text defaults to

"New NDS Password: "

Example:

PASSWORDPROMPTCHANGE "New Password: "

10.3.18 PASSWORDPROMPTCHANGEAGAIN Statement

The PASSWORDPROMPTCHANGEAGAIN statement specifies the prompt issued by the PAM module to verify the user's new password for password changes.

Syntax:

PASSWORDPROMPTCHANGEAGAIN Text

If there is no PASSWORDPROMPTCHANGEAGAIN statement, Text defaults to

"Re-enter New NDS Password: "

Example:

PASSWORDPROMPTCHANGEAGAIN "Verify New Password: "

10.3.19 PLATFORMNAME Statement

The PLATFORMNAME statement specifies the common name of the Platform object. If there is no PLATFORMNAME statement, you are prompted to enter the name when obtaining a platform security certificate.

Syntax:

PLATFORMNAME Cn

Cn specifies the common name of the Platform configuration object that was specified in the Web interface when platform was defined.

Example:

PLATFORMNAME WestCentral

10.3.20 PASSWORDSOURCE Statement

The PASSWORDSOURCE statement allows you to specify where encrypted passwords should be stored. For example, on older UNIX systems, encrypted password information is stored in /etc/passwd. On most modern UNIX systems, this information is stored in /etc/shadow. On non-trusted HP-UX, the PASSWORDSOURCE statement should be used to specify whether the HP-UX system is using /etc/passwd or /etc/shadow for encrypted password information. By default, the installer package will determine which source to use; however, if you are running HP-UX in Trusted Computing Base (TCB) mode, where there is no /etc/shadow file, then you should omit the PASSWORDSOURCE statement and let Platform Services use standard HP API hooks to manage the encrypted password storage.

Syntax:

PASSWORDSOURCE fully-qualified-path-to-file

An important example of the PASSWORDSOURCE statement’s use is on HP-UX, when shadow passwords are enabled. The default location to look for encrypted passwords on non-trusted-mode HP-UX is /etc/passwd. When shadow passwords are enabled on HP-UX, PASSWORDSOURCE should be set as follows:

PASSWORDSOURCE /etc/shadow

10.3.21 POLLINT Statement

The POLLINT statement specifies the interval in number of seconds between polling cycles. It can be used to spread the amount of traffic and load placed on the Core Driver during event processing. The default for the polling interval is 300 seconds (5 minutes), which, in some circumstances, may be too frequent.

Syntax:

POLLINT seconds

Example:

POLLINT 600

In the above example, POLLINT will set the polling interval to 600 seconds (10 minutes).

10.3.22 POLLRAND Statement

The POLLRAND statement specifies the minimum and maximum polling interval in seconds from which to choose a random interval between polling cycles. It can be used to spread the amount of traffic and load placed on the Core Driver during event processing. The default for the polling interval is 300 seconds (5 minutes), which, in some circumstances, may be too frequent.

Syntax:

POLLRAND minsec maxsec

Example:

POLLRAND 300 1200

In the above example, POLLRAND will set the platform receiver (asamrcvr) to select a random integer between 300 and 1200 to represent the interval in number of seconds before the next polling cycle begins.

10.3.23 PROVISIONING Statement

The PROVISIONING statement specifies the network address and port of one Provisioning Manager Core Driver. A PROVISIONING statement must appear in the configuration file for the Platform Receiver and when obtaining a security certificate.

You can code more than one PROVISIONING statement. The first PROVISIONING statement in the file identifies the Provisioning Manager that is tried first. If a connection with the Provisioning Manager identified by the first PROVISIONING statement fails, the Provisioning Managers identified by any other PROVISIONING statements are tried, in the order the PROVISIONING statements appear in the configuration file, until a connection is successful or there are no more PROVISIONING statements.

Syntax:

PROVISIONING Address [PORT PortNumber]

Address specifies the DNS name or IP address of a Provisioning Manager.

PortNumber specifies the TCP port number that is to be used to communicate with the Provisioning Manager. PORT is optional. The default port number for the Provisioning Manager is 3451.

Example:

PROVISIONING cdriver1.digitalairlines.com
PROVISIONING cdriver4.digitalairlines.com

10.3.24 RUNMODE Statement

The RUNMODE statement specifies the mode of operation the Platform Receiver uses. Command line parameters that specify a mode of operation override the mode specified on the RUNMODE statement.

Syntax:

RUNMODE Mode

Mode specifies the mode of operation for the Platform Receiver. Possible values follow.

If no RUNMODE statement or mode-related command line parameter is present, the Platform Receiver uses persistent Mode.

For more information about Platform Receiver modes of operation, see Section 8.8.1, Modes of Operation.

Example:

RUNMODE polling

10.3.25 SYSLOGFACILITY Statement

The SYSLOGFACILITY statement specifies the SYSLOG facility name to use for message logging on Linux/UNIX systems.

Syntax:

SYSLOGFACILITY   FacilityName

FacilityName specifies the SYSLOG facility to use for logging messages. The possible values for a specific Linux/UNIX system are mapped by the syslog.h file of that particular system.

If no SYSLOGFACILITY statement is coded, the default value is LOG_DAEMON.

Example:

SYSLOGFACILITY LOG_DAEMON    

10.3.26 TRACEFILE Statement

The TRACEFILE statement specifies that debugging output is generated and the file path where it is written. If the TRACEFILE statement is present in the platform configuration file, full debugging output is generated even if the -d command line parameter is not present.

To obtain debugging output from the system intercepts when you use the DIRECTTOAUTHENTICATION statement, you must use either the TRACEFILE or the TRACETOSTDOUT statement.

Syntax:

TRACEFILE FilePath

FilePath specifies the location in the file system where debugging output is written.

Example:

TRACEFILE c:\novell\asam\debug.txt

10.3.27 TRACETOSTDOUT Statement

The TRACETOSTDOUT statement specifies that debugging output is generated and that it is written to the standard output channel stdout. If the TRACETOSTDOUT statement is present in the platform configuration file, full debugging output is generated even if the -d command line parameter is not present.

To obtain debugging output from the system intercepts when you use the DIRECTTOAUTHENTICATION statement, you must use either the TRACEFILE or the TRACETOSTDOUT statement.

Syntax:

TRACETOSTDOUT

Example:

TRACETOSTDOUT

10.3.28 UPDATEPASSWORD Statement

The UPDATEPASSWORD statement specifies that the driver updates the local security system upon a successful check password or change password operation, or when password replication information is received from the Core Driver. This allows a user to log in using the last password that worked on the system if the driver, eDirectory, or the network is not available, and the local security system is appropriately configured.

If there is no UPDATEPASSWORD statement present in the platform configuration file, the driver does not store passwords in the local security system.

Syntax:

UPDATEPASSWORD

Example:

UPDATEPASSWORD

10.3.29 CRYPTTYPE Statement

The CRYPTTYPE statement specifies the format to use for storing passwords if the Fan-Out driver is configured to update local passwords. Therefore, the CRYPTTYPE statement works only if the platform configuration file (asamplat.conf) also contatins the UPDATEPASSWORD statement.

When the Fan-Out driver is configured to update local Linux or UNIX passwords, the driver can automatically choose from the available password storage formats of the target operating system. The CRYPTTYPE statement allows you to override this choice with a specific format you prefer.

The Fan-Out driver supports many different operating systems which, in turn, support many different formats for locally stored passwords.

Syntax:

CRYPTTYPE format rounds

Possible values for format are DES, MD5, BLOWFISH, SHA256, SHA512 and SUN_MD5.

Since its version 9 (12/02) release, Solaris has supported DES, MD5, BLOWFISH and SUN_MD5. Linux support is based on the version of glibc. Most recent Linux distributions support DES, MD5, SHA256 and SHA512. Blowfish is not in the mainline of glibc, but has been added in some Linux distributions, including SUSE® Linux.

The value for rounds only applies to BLOWFISH, SHA256 or SHA512. This second argument can be used to indicate the number of rounds, or repetitions, of transformation to be used. For BLOWFISH, possible values for rounds are 04, 05, 06, 07, 08, 09, 10, 11 or 12. For SHA256 and SHA512 any number within the range of 1000-999999999 is a possible value for rounds.

Example (MD5 format):

CRYPTTYPE MD5

Example (BLOWFISH format):

CRYPTTYPE BLOWFISH 09

Example (SHA512 format):

CRYPTTYPE SHA512 7000

10.3.30 UPDATESAMBA Statement

The UPDATESAMBA statement specifies that the driver updates the Samba password file upon a successful check password or change password operation, or when password replication information is received from the Core Driver.

If there is no UPDATESAMBA statement present in the platform configuration file, the driver does not store passwords in the Samba password file.

Syntax:

UPDATESAMBA FilePath

FilePath specifies the location of the smbpasswd program in file system.

Example:

UPDATESAMBA /usr/local/samba/bin/smbpasswd

10.3.31 USEFILEIPC Statement

The USEFILEIPC statement specifies that data from the Platform Receiver should be made accessible by the Platform Receiver scripts by using file Input/Output rather than environment variables.

While environment variables are a convenient method for communicating data between the Platform Receiver and the scripts, they have size limitations, based on the operationg system parameter ARG_MAX, that make it impossible to process events when they become too large. For example, a group that contains many users could exceed this size limit. The value of ARG_MAX varies on different operating systems.

Syntax:

USEFILEIPC

Example:

USEFILEIPC

10.3.32 EXCLUDEUNMANAGED Statement

The EXCLUDEUNMANAGED statement specifies that the Platform Receiver should query the Fan-Out Driver Census (in the Identity Vault) if it cannot reconcile a user’s membership in a group account on a local system with a corresponding group account managed in Identity Manager.

Not all group accounts on a local system need to be replicated and tracked centrally from the Identity Vault. For example, Linux and UNIX often place users in certain default groups that are of no consequence to security and therefore not added to the Identity Vault.

The Fan-Out driver does not make this distinction between groups managed by Identity Manager and groups relevant only to the local system. If the Platform Receiver detects that a user is member to a local group that does not also exist in the Identity Vault, it reverses the membership in its charge to maintain parity with Identity Manager.

The EXCLUDEUNMANAGED statement bypasses this default behavior. When it is specified, the Platform Receiver will first query the Census to see if the group account in question also exists in the Identity Vault. If the group is not found in the Census, it is excluded automatically and the local unmanaged group membership can be preserved.

Syntax:

EXCLUDEUNMANAGED

Example:

EXCLUDEUNMANAGED

10.4.1 Mask Characters and Examples

You can use masks to match more than one user ID or group in Include and Exclude statements. The following tables list mask characters and provide examples of masks.

10.4.2 Rules by Which Masks Are Matched Against User IDs and Groups

11.1.1 Secure Sockets Layer Entropy Requirements

Secure Sockets Layer (SSL), used by Platform Services for communication with Core Drivers, requires a source of entropy. Some Linux/UNIX implementations provide a /dev/random device for entropy. If your Linux/UNIX implementation does not include a /dev/random device, you must install an entropy daemon. You must also include an ENTROPY statement in your platform configuration file to specify the source of entropy. For information about the platform configuration file, see Section 10.0, The Platform Configuration File.

The PRNGD entropy daemon can be installed from the /prngd directory of the distribution media.

Solaris versions before Solaris 9 do not include a /dev/random device. Sun has released this functionality for versions 2.6 onward in Patch ID 112438-01.

11.1.2 The Platform Services Process

The Platform Services Process provides an interface for the System Intercept and the AS Client API to one or more Core Drivers for Authentication Services.

The Platform Services Process is called whenever a user attempts to enter the system using a user ID and password or when a user attempts to change the password. Such a request is passed from the system intercept to the Platform Services Process, which then communicates with a Core Driver and returns a response.

The Platform Services Process performs the following tasks:

The Platform Services Process communicates with Core Drivers using Secure Sockets Layer (SSL).

Start the Platform Services Process during system startup and stop it during system shutdown.

The Platform Services Process reads its configuration information from ASAM/data/asamplat.conf, the platform configuration file. The Platform Services Process logs messages to the SYSLOG facility specified by the SYSLOGFACILITY statement in the platform configuration file. For details about the platform configuration file, see. Section 10.0, The Platform Configuration File.

11.1.3 The System Intercept

The Platform Services System Intercept communicates with the Platform Services Process for password verification and password changes.

The System Intercept is implemented in most Linux/UNIX systems using a Pluggable Authentication Module (PAM). Platform Services for AIX uses the Loadable Authentication Module (LAM) system provided by AIX. AIX 5.3 and later also supports PAM.

11.1.4 The Platform Receiver

The Platform Receiver processes provisioning events received from the Event Journal Services component of the Core Driver.

The Platform Receiver communicates with Event Journal Services using Secure Sockets Layer (SSL). Data is encoded using UTF-8. You can use the CODEPAGE statement in the platform configuration file to configure the Platform Receiver to convert data using a specified code page. For details about the platform configuration file, see Section 10.0, The Platform Configuration File.

Run the Platform Receiver on a schedule that is appropriate for your requirements. For details about Platform Receiver operation, see Section 8.8, The Platform Receiver.

The Platform Receiver reads its configuration information from ASAM/data/asamplat.conf, the platform configuration file. It logs messages to the SYSLOG facility specified by the SYSLOGFACILITY statement in the platform configuration file.

When the Platform Receiver successfully updates a password in the local security system or Samba password file, it logs a message to SYSLOG.

11.1.5 Receiver Scripts

Receiver scripts for Linux/UNIX platforms are implemented as shell scripts. The Platform Receiver (asamrcvr) runs the scripts from ASAM/bin/PlatformServices/PlatformReceiver/scripts.

Provisioning events are received as groupings of name-value pairs as shown in the following example:

enterpriseUserName  bob

The Platform Receiver calls a Receiver script whenever it is necessary to obtain information about users or groups on the platform and whenever it is appropriate to take an action for a user or group on the platform.

platformverifyandmapname.sh
does_user_exist.sh
adduser.sh
addusertogroup.sh
enableuser.sh
disableuser.sh

platformverifyandmapname.sh
doesgroupexist.sh
adduser.sh
addgroup.sh
populategroup.sh

platformgetgrnam.sh
platformgetpwnam.sh
doesgroupexist.sh
platformverifyandmapname.sh
doesgroupexist.sh
platformgroupmem.sh

modgroup.sh
populategroup.sh

platformgetgrnam.sh
platformgetpwnam.sh
does_user_exist.sh
platformverifyandmapname.sh
does_user_exist.sh
platformgroupaff.sh
enableuser.sh
disableuser.sh
moduser.sh
addusertogroup.sh
removeuserfromgroup.sh

11.1.6 The Name Service Switch

The Name Service Switch communicates with the Platform Services Cache Daemon for account information defined by the RFC 2307 Posix Profile attributes. This library module may be installed on any Linux or UNIX system for complete account redirection, providing an alternative to storing user and group accounts and passwords locally. This information is delivered from eDirectory™ and updated live through Identity Management event mechanisms.

11.1.7 The Platform Services Cache Daemon

The Platform Services Cache Daemon processes provisioning events received from the Event Journal Services component of the Core Driver. These events are stored in local memory for quick access and the cache is updated live when new events are processed. The daemon communicates with Event Journal Services using Secure Sockets Layer (SSL). Data is encoded using UTF-8. You can use the CODEPAGE statement in the platform configuration file to configure the Platform Services Cache Daemon to convert data using a specified code page. For details about the platform configuration file, see Section 10.0, The Platform Configuration File. Run the daemon on system startup. For details about the daemon's operation, see Section 8.6, The Platform Services Cache Daemon.

The daemon reads its configuration information from ASAM/data/asamplat.conf, the platform configuration file. The daemon logs messages to the SYSLOG facility specified by the SYSLOGFACILITY statement in the platform configuration file.

11.1.8 Authentication Services

Authentication Services for Linux/UNIX redirects authentication requests to eDirectory and can replicate passwords from eDirectory.

When a password for a user associated with a Linux/UNIX system that uses password replication is changed in eDirectory, a provisioning event is generated by the Core Driver and given to the Platform Receiver for processing. By default, the Core Driver converts passwords to lowercase before sending them to the Platform Receiver. For more information about password case, see Lower Password Case.

Because password replication information travels in both directions, it is affected by the Include/Exclude lists of both Authentication Services and Identity Provisioning. It is important therefore, to configure the Include/Exclude lists for both the Platform Services Process and the Platform Receiver symmetrically if the platform uses password replication.

11.2.1 Installing Platform Services

To install Platform Services:

11.2.2 Upgrading Platform Services

To upgrade an existing installation of Platform Services:

11.2.3 Executing Commands for Unattended Installation

Since the release of Identity Manager 3.6, the Fan-Out Platform Services installer supports command-line non-interactive installations and configurations. Using this feature you can install Platform Services with a single command line, allowing the entire process to be scripted for a mass deployment. To use the unattended installation feature, you must specify the -non-interactive parameter with one or more of the following parameter options.

sh linux_x86_platformservices.bin -non-interactive 
    -corehost 10.0.0.1:3451 -admin admin.acme -password novell 
    -platname linux123 -local-prov -auth-local -pam-pass 
    -path /usr/local -runmode persistent

11.2.4 Customizing Installation

If you have a custom process for deploying installations, upgrades or updates, you may prefer to extract the installation content manually for integration into your process. The self-extracting .bin installers use platform-specific packages to deploy the distribution files. These packages can be recovered by executing the appropriate installer with the -extract parameter.

For example, if linux_x86 were the operating system architecture of your target platform, you would execute the following command:

  sh linux_x86_platformservices.bin -extract

This resulting extraction would produce the following temporary directory structure:

  linux_86
  linux_86/setup
  linux_86/setup/admin.fanplat
  linux_86/setup/install
  linux_86/license-C.txt
  linux_86/license-zh_cn.txt
  linux_86/license-de.txt
  linux_86/license-cs.txt
  linux_86/package
  linux_86/package/novell-DXMLfanplat-3.6.rpm
  linux_86/license-es.txt
  linux_86/license-fr.txt
  linux_86/license-it.txt
  linux_86/license.txt
  linux_86/license-jp.txt
  linux_86/license-zh_tw.txt
  linux_86/license-nl.txt
  linux_86/license-pl.txt
  linux_86/license-pt.txt
  linux_86/license-ru.txt
  linux_86/license-sv.txt

The installation script is located under the setup directory. The native package file, which is located inside the package directory, will vary in name depending on the operating system used by your target platform. To determine the name of your native package file, see Table 11-2.

Once you have extracted the contents from the .bin archive, you may choose to modify the configuration script, <os>/setup/install, and wish to rebundle the contents into a new .bin installer. To do so, first extract the header file:

  head -n 76 <os>_platformservices.bin > header

Then, edit the files as necessary inside the <os> directory. Finally, recreate the .bin:

  tar cf <os>_platformservices.tar <os>
  cat header <os>_platformservices.tar > <os>_platformservices.bin

11.3.1 Configuring PAM

If you have chosen to configure for authentication redirection on a platform that is running Linux or UNIX, you will need to manually configure PAM on that system. For technical instructions on how to configure PAM for authentication, see Section B.1, PAM Configuration Notes.

The Platform Services installer automatically copies sample configurations you can use as templates to the following location:

11.3.2 Configuring LAM on AIX

If you have chosen to configure for authentication redirection on a platform that is running AIX, and you want to use IBM’s proprietary Loadable Authentication Module (LAM), you will need to manually configure the Fan-Out Driver’s LAM module on that AIX system. For technical instructions on how to configure LAM for authentication, see Section B.3, LAM Configuration Notes.

The Platform Services installer automatically copies sample LAM-related configuration files you can use as templates to the following location:

  /usr/local/ASAM/bin/PlatformServices/methods.cfg.sample
  /usr/local/ASAM/bin/PlatformServices/user.sample
  /usr/local/ASAM/bin/PlatformServices/user.sample2

11.3.3 Running a Full Synchronization

Upon initial deployment of the Fan-Out Driver Platform Services, you may find it useful and necessary to perform an initial migration or synchronization of users and groups within the Identity Vault. You can perform a full synchronization by executing asamrcvrd fullsync. Location of this executable will vary depending on your target platform. See Table 11-3 for the appropriate full command line that includes your directory location.

11.3.4 Starting Platform Services

Starting Platform Services requires you to start one or more of the following components, depending on your configuration:

For more information about these components, see Section 11.1, About Platform Services for Linux and UNIX and Section 12.0, Configuring and Administering Platform Services.

11.3.5 Stopping Platform Services

Stopping Platform Services requires you to stop one or more of the following components, depending on your configuration:

For more information about these components, see Section 11.1, About Platform Services for Linux and UNIX and Section 12.0, Configuring and Administering Platform Services.

11.3.6 Testing Platform Services for PAM or LAM

If you are using PAM (or LAM on AIX) for password authentication, it may be helpful to verify that the Platform Services Process (asampsp) and the API Library (libascauth) are functioning properly, before you finalize PAM configuration. You can do this with a program called asctest, which is included with your Platform Services installation. Here’s where to find it:

/usr/local/ASAM/bin/PlatformServices/PlatformClient/asctest

This program allows you to test the various calls (listed in Table 11-10) that can be made to the API library in support of PAM. To use asctest, simply enter it from a command line with no parameters. When prompted select the desired method by entering its corresponding letter (a-o) and respond to any further prompts. The following table provides descriptions of the API methods.

11.4.1 Removing PAM

If you have configured your system to use the Fan-Out Driver PAM module for authentication, make sure you first remove the Fan-Out Driver Platform Services module, ascauth, from your PAM configuration before uninstalling the product. Leaving PAM with invalid library references can leave your system in an unpredictable state for new logon requests.

11.4.2 Removing LAM

If you have configured your system to use the Fan-Out Driver LAM module (/usr/lib/security/DCE) for authentication, make sure you first remove any LAM-related modifications you made to the following files:

  /etc/security/user
  usr/lib/security/methods.cfg

11.4.3 Running the Uninstall Script

To uninstall Platform Services, run the following script:

  /usr/local/ASAM/bin/PlatformServices/plat-uninstall

12.3.1 Local Authentication

With local authentication, passwords are stored locally (in /etc/shadow for example) and users that log onto the Linux or UNIX system will authenticate with this password. To synchronize passwords with the Identity Vault, ensure the following keyword statement is located inside your asamplat.conf file:

  UPDATEPASSWORD

The Platform Receiver (asamrcvr file) needs to be running to keep passwords synchronized with the Identity Vault. For more information, see Starting the Platform Receiver.

12.3.2 Authentication Redirection

With redirected authentication, passwords are not stored locally. Instead, when a user logs on to the Linux or UNIX system, the Fan-Out Driver’s PAM (or LAM) module will redirect the request to the Identity Vault, where the password is checked along with eDirectory Password and Login rules. Optionally, password policies can be enforced.

To configure your system to use the PAM module for authentication redirection, you will need to manually configure PAM for each application that is to be PAM-enabled. For details on manually configuring PAM, see Section B.1, PAM Configuration Notes.

If you are running AIX and chose to use LAM for authentication redirection, you will need to manually configure LAM as detailed in Section B.3, LAM Configuration Notes.

The Platform Services Process (asampsp file) also needs to be running to provide a connection pool and driver load balancing. For more information, see Starting the Platform Services Process.

12.3.3 Authentication Redirection with Local Failover

Authentication redirection with local failover is a hybrid of local authentication and authentication redirection. In such a scenario, authentication is redirected unless the connection between Platform Services and the Identity Vault is unavailable, in which case local authentication takes place. In this configuration, you will need the Platform Receiver running to synchronize passwords and the Platform Services Process running to provide authentication. For information about starting these two services, see Section 11.3.4, Starting Platform Services.

12.3.4 Name Service Switch Authentication

If you have chosen the virtual provisioning option (see Section 12.2, Provisioning), users will authenticate to the Linux or UNIX system using the Name Service Switch, which is supplied by Platform Services. Virtual users and their password information are kept in a local protected cache on the connected system. This provides the system with a local copy and therefore all the advantages of using local provisioning. If you wish to enforce eDirectory password and login rules, you will also need to manually configure PAM for authentication redirection.

13.1.1 Debugging the Linux/UNIX Platform Services Process and Platform Receiver

To obtain debugging output for the Platform Services Process or Platform Receiver on Linux/UNIX:

13.4.1 IP Connections

To verify IP Connections between platforms and the Core Driver, use the ping command. From a command prompt on the Linux, UNIX or Windows system, use a command prompt to enter ping ipaddr, where ipaddr is the IP address of the remote computer.

13.4.2 Firewalls

Firewalls can disrupt connectivity between the Core Driver and its connected systems. To verify that the TCP port is reachable, use a command prompt to enter telnet ipaddr 3451, where ipaddr is the IP address of the remote computer. The TCP port 3451 is used by the Core Driver for communication with the connected platforms.

13.4.3 DNS

Check DNS if you are using named hosts in your platform or Core Driver address configurations. DNS resolution is necessary to verify certificates for SSL communication.