eimadmin Command

Purpose

Manages Enterprise Identity Mapping (EIM) domains.

Syntax

eimadmin -a | -p | -l | -m | -e -D | -R | -I | -A | -C [-s switch] [-v verboseLevel] [-c accessType] [-f accessUserType] [-g registryParent] [-i identifier] [-j otherIdentifier] [-k URI] [-n description] [-o information] [-q accessUser] [-r registryName] [-t associationType] [-u registryUser] [-x registryAlias] [-y registryType] [-z registryAliasType] [-d domainDN] [-h ldapHost] [-b bindDN] [-w bindPassword] [-K keyFile [ -P keyFilePassword] [-N certificateLabel]] [-S connectType]

Description

The eimadmin command is an AIX® System Services Shell tool. An administrator can use it to define an EIM domain and prime the domain with registries, identifiers, and associations between identifiers and registry users. An administrator can also use eimadmin to give users (and other administrators) access to an EIM domain, or list or remove the EIM entities.

Administrators can use the eimadmin command in two ways:
  • By including information with command-line options on an eimadmin command
  • By including information in an input file that an eimadmin command references

You can create the file manually or by exporting records from a database. The administrator directs utility processing by specifying a combination of command-line options.

The eimadmin command can perform the following actions:
  • Add an object (-a)
  • Purge an object (-d)
  • List objects (-l)
  • Modify attributes associated with objects (-m)
  • Erase attributes (-e)
on the following objects:
  • Domains (-D)
  • Registries (-R)
  • Identifiers (-I)
  • Associations (-A)
  • Access authorities (-C)
Note:
  1. Each eimadmin command must include one action and one object type. Depending on the object and the action you are performing on it, EIM might require additional parameters.
  2. Some options are for multivalue attributes, which you can specify more than once. Other options are for single-value attributes, which you can specify only once. (If you repeat an option that is for a single-value attribute, eimadmin processes only the first value it encounters in the command.) Apart from these stipulations, the order in which you specify parameters is not important.
  3. You can code the parameters of the eimadmin command in several ways:
    • Concatenate an action and an object, omitting the embedded hyphen: -aD
    • Include both hyphens, and separate the two options with a space: -a -D
    In other words, the following example is not valid because it includes both hyphens and there is no space before -D: -a-D

Flags

The eimadmin command takes the following action flags.

Item Description
-a Adds an object. (Creates an object definition and its attributes.)
-e Erases an attribute. (Clears a single-value attribute or removes a multivalue attribute.)
-l Lists an object. (Retrieves an object definition and its attributes.)
-m Modifies an attribute. (Alters an attribute of an existing object, either by changing a single-value attribute or adding a multivalue attribute.)
-p Purges an object. (Removes an object definition and its attributes.)

The eimadmin command takes the following object flags.

Item Description
-A An association. This is a relationship between an identifier in the EIM domain and a user ID.
-C An access authority. This is an EIM-defined LDAP access control group.
-D A domain. This is a collection of identifiers, user registries, and associations between identifiers and user IDs, stored within an LDAP directory.
-I An identifier. This is the name of a person or entity participating in an EIM domain.
-R A registry. This is the name of a user registry. Associations are defined between identifiers and user IDs in the user registry.

The eimadmin command takes the following processing control flags.

Item Description
-s switch The switch specifies a value that affects the way the eimadmin command functions operate. You can specify the following value:
RMDEPS
Removes dependents when removing a domain or system registry. This makes it easier to remove a domain by first removing all identifiers and registries defined for the domain. It also makes it easier to remove a system registry by first removing all application registries defined for the registry.
Attention: Attention: The eimadmin command does not warn you that dependents exist before removing them, so use this switch carefully.
-v verboseLevel The verboseLevel parameter is an integer from 1 to 10 that controls the amount of trace detail that the eimadmin command displays. (It is for diagnosing problems in the eimadmin utility.) The default value of 0 indicates no trace information. You can specify an integer value from 1 to 10, from the least to greatest amount of trace information. The utility checks the value and displays trace information defined for the level and all lower levels. The following levels trigger specific information:
  • 3–indicates EIM API call parameters and return values
  • 6–indicates option values and input file labels
  • 9–indicates utility routine entry and exit statements
The eimadmin command takes the required and optional attribute flags listed in the following table. The flag options are single-valued unless otherwise indicated. If you specify an option more than once, the utility processes only the first occurrence.
Note:
  1. You can specify these attributes as command options or as fields in input files. If you are specifying command options, you must enclose values with imbedded blanks within quotation marks (") or ('). Quotation marks are optional for single-word values. Specifying a multiword value without quotation marks in effect truncates the command line options; values after the first word are truncated.
  2. The following special characters are not allowed in registryName, registryParent, or identifier: 
    , = + < > # ; \ *
Item Description
-c accessType Specifies the scope of access authority the user has over the EIM domain. accessType must be one of the following values:
ADMIN
Specifies administrative access.
REGISTRY
Specifies registry access. If you specify REGISTRY, you must also specify a registry value (-r). The registry value can be a specific registry name or it can be an asterisk (*) to indicate access to all registries.
IDENTIFIER
Specifies identifier access.
MAPPING
Specifies mapping operations access.
-f accessUserType Specifies the type for the access user name. accessUserType must be one of the following types:
DN
The accessUser is a distinguished name.
KERBEROS
The accessUser is a Kerberos identity.
-g registryParent Specifies the name of a system registry. An application registry is a subset of a system registry. If you are adding an application registry, you must use the -r option and the -g option. The -r value is the application registry you are defining. The -g option is the preexisting system registry.
-i identifier Specifies a unique identifier name. For example: John Day.
-j otherIdentifier Specifies a nonunique identifier name. For example: John.
Note: You can specify this option multiple times to assign multiple nonunique identifiers.
-k URI Specifies the Universal Resource Identifier (URI) for the registry (if one exists).
-n description Specifies any text (that you provide) to associate with the domain, registry, identifier, or association.
Note: You can define a user description only for target associations.
-o information Specifies additional information to associate with an identifier or association.
Note: You can define user information only for target associations. You can specify this option multiple times to assign multiple pieces of information.
-q accessUser Specifies the user distinguished name (DN) or the Kerberos identity with EIM access, depending on the accessUserType specified.
-r registryName Specifies the name of a registry. When you add a new registry, eimadmin treats the registry as a system registry unless you also specify the -g option. If you specify the -g option, eimadmin treats the registry as an application registry.
-t associationType Specifies the relationship between an identifier and a registry. associationType must be one of the following:
ADMIN
Indicates associating a user ID with an identifier for administrative purposes.
SOURCE
Indicates that the user ID is the source (or from) of a lookup operation.
TARGET
Indicates that the user ID is the target (or to) of a lookup operation.
Note: You can specify this option multiple times to define multiple relationships.
-u registryUser Specifies the user ID of the user defined in the registry.
-x registryAlias Specifies another name for a registry. You must specify this option multiple times to assign multiple aliases.
-y registryType Specifies the type of registry. Predefined types that eimadmin recognizes include the following:
  • RACF®
  • OS/400®
  • KERBEROS (for case ignore)
  • KERBEROSX (for case exact)
  • AIX
  • NDS
  • LDAP
  • PD (Policy Director)
  • WIN2K
You can also create your own types by concatenating a unique OID with one of the following two normalization methods:
  • caseIgnore
  • caseExact
-z registryAliasType Specifies the type for a registry alias. You can invent your own value or use one of the following suggested values:
  • DNSHostName
  • KerberosRealm
  • IssuerDN
  • RootDN
  • TCPIPAddress
  • LdapDnsHostName
Note: For a set of command line options or single input data record, the eimadmin command recognizes only the first specification of registryAliasType. However, the eimadmin command does recognize multiple registry aliases and associates all of them with the single registryAliasType.

The eimadmin command takes the following connection type flags.

Item Description
-b bindDN Specifies the distinguished name to use for the simple bind to LDAP.
-d domainDN Specifies the full distinguished name (DN) of the EIM domain. domainDN begins with 'ibm-eimDomainName=' and consists of the following elements:
domainName
The name of the EIM domain you are creating. For example, MyDomain.
parent distinguished name
The distinguished name for the entry immediately above the given entry in the directory information tree hierarchy, such as o=ibm,c=us. For example: 
 ibm-eimDomainName=MyDomain,o=ibm,c=us
-h ldapHost Specifies the URL and port for the LDAP server controlling the EIM data. The format is: 
ldap://some.ldap.host:389  
ldaps://secure.ldap.host:636
-K keyFile Specifies the name of the SSL key database file, including the full path name. If the file cannot be found, it is assumed to be the name of a RACF key ring that contains authentication certificates. This value is required for SSL communications with a secure LDAP host (prefixed ldaps://). For example: 
/u/eimuser/ldap.kdb
-N certificateLabel Specifies which certificate to use from the key database file or RACF key ring. If this option is not specified, the certificate marked as the default in the file or ring is used.
-P keyFilePassword Specifies the password required to access the encrypted information in the key database file. Alternatively, you can specify an SSL password stash file for this option by prefixing the stash file name with file://. For example: 
secret  or file:///u/eimuser/ldapclient.sth
Note: The eimadmin command prompts for a key file password if you specify the name of a key database file for the -K option but not the -P option on the command line.
-S connectType Specifies the method of authentication to the LDAP server. connectType must be one of the following values:
  • SIMPLE (bind DN and password)
  • CRAM-MD5 (bind DN and protected password)
  • EXTERNAL (digital certificate)
  • GSSAPI (Kerberos)
If not specified, connectType defaults to SIMPLE. For connect type GSSAPI, the default Kerberos credential is used. This credential must be established using a service such as kinit prior to running eimadmin. For KINIT and related information, refer to the AIX Authentication Service Administration.
-w bindPassword Specifies the password associated with the bind DN.

The connection information needed by the utility includes the EIM domain (-d) and its controlling server (-h), the identity (-b,-w; or -K,-P,-N) with which to authenticate (bind) to the server, and the authentication method (-S).

For object types other than domain (-D), specifying the domain, server and bind identity is optional. If these are not specified, the information is retrieved from a RACF profile.
Note: If any of the connect information is specified, the full set of values required for the connect type must also be specified. Omitting one or more values (but not all) results in an error. The following table shows the required and optional values for each connect and host type when specified with the eimadmin command.
Connection Type/Host Type Required Values Optional Values
SIMPLE or CRAM-MD5/secure (ldaps://) -d, -h, -b, -w, -K, -P -N
SIMPLE or CRAM-MD5/nonsecure (ldap://) -d, -h, -b, -w  
EXTERNAL/secure (ldaps://) -d, -h, -K, -P, -S -N
EXTERNAL/nonsecure (ldap://) unsupported unsupported
GSSAPI/secure (ldaps://) -d, -h, -K, -P, -S -N
GSSAPI/nonsecure (ldap://) -d, -h, -S  
Note:
  1. There are two exceptions to the preceding table:
    • The domain option (-d) is not required for domain functions if the value is specified through an input file.
    • An SSL key database file password or stash file (-P) is not required when -K specifies a RACF key ring.
  2. The eimadmin command prompts for the simple bind password if it is required and -w is not specified on the command line, and prompts for the SSL key database file password if it is required and -P is not specified on the command line.
The following table summarizes required and optional flags for each object type and action pair. You can specify the value for most options in an input file instead of specifying it on the command line.
Object Type (Action) Flags Comments
D (a)
  • Required: d, h
  • Optional: n
 Add a domain.
D (p)
  • Required: d, h
  • Optional: s
 Remove a domain. If the domain is not empty, include -s RMDEPS.
D (l)
  • Required: d, h
  • Optional:
List domains. Specify -d* to list all domains.
D (m)
  • Required: d, h
  • Optional: n
 Modify or add a domain attribute.
D (e)
  • Required: d, h
  • Optional: n
 Remove or clear a domain attribute.
R (a)
  • Required: r, y
  • Optional: g, k, n, x, z
 Add a registry. The value specified for -r is assumed to be a new system registry unless -g is also specified, in which case the -r value indicates a new application registry.
R (p)
  • Required: r
  • Optional: s
 Remove a registry.
R (l)
  • Required: r
  • Optional: y
 List registries. Return all registry entries in the domain that match the specified -r value search filter, which might contain the wild card *.
R (m)
  • Required: r
  • Optional: k, n, x, z
 Modify or add a registry attribute, including a registry alias.
R (e)
  • Required: r
  • Optional: k, n, x, z
 Remove or clear a registry attribute, including a registry alias.
I (a)
  • Required: i
  • Optional: j, n, o
 Add an identifier.
I (p)
  • Required: i
  • Optional:
Remove an identifier.
I (l)
  • Required: i
  • Optional:
 List an identifier by unique identifier name. Return all identifier entries in the domain that matches the specified -i value search filter, which might contain the wild card *.
I (l)
  • Required: j
  • Optional:
List an identifier by nonunique identifier name. Return all identifier entries in the domain that have a nonunique identifier matching the specified -j value search filter, which might contain the wild card *.
I (m)
  • Required: i
  • Optional: j, n, o
 Modify or add an identifier attribute.
I (e)
  • Required: i
  • Optional: j, n, o
 Remove or clear an identifier attribute.
A (a)
  • Required: i, r, u, t
  • Optional: n, o
 Add an association. You can repeat the -t option to add multiple associations types. The -n and -o flags are relevant only to TARGET associations.
A (p)
  • Required: i, r, u, t
  • Optional:
 Remove an association. You can repeat the -t option to remove multiple associations types.
A (l)
  • Required: i
  • Optional: t
 List associations. Return all associations in the domain for specified -i unique identifier. Specify a -t value to limit the entries returned to the given association type.
A (m)
  • Required: r, u
  • Optional: n, o
 Modify or add an association attribute. The -n and -o flags are relevant only to TARGET associations.
A (e)
  • Required: r, u
  • Optional: n, o
 Remove or clear an association attribute. The -n and -o flags are relevant only to TARGET associations.
C (a)
  • Required: c, q, f
  • Optional: r
 Add access. For access type REGISTRY, provide a specific -r registry value, or a wild card * indicating access to all registries in the domain.
C (p)
  • Required: c, q, f
  • Optional: r
 Remove access. For access type REGISTRY, provide a specific -r registry value, or a wild card * indicating access to all registries in the domain.
C (l)
  • Required: c
  • Optional: r
 List access by type. For access type REGISTRY, provide a specific -r registry value, or a wild card * indicating access to all registries in the domain.
C (l)
  • Required: q, f
  • Optional:
 List access by user.

Exit Status

The eimadmin command returns one of the following exit codes upon completion:

Item Description
0 Successful.
4 One or more errors encountered but, if you specified an input file, all records were processed.
8 A severe error occurred that caused processing to stop before reaching the end of an input file, if specified.

Examples

  1. To list a single domain, type: 
    eimadmin -lD -h ldap://my.server -b "cn=EIM admin,o=MyCompany,c=US" -d "ibm-eimDomainName=My Employees,o=My Company,c=US"
    This returns something similar to the following output: 
    domain name: My Employees 
domain DN: ibm-eimDomainName=My Employees,o=My Company,c=US 
description: employees in my company
  2. To list a single registry, type: 
    eimadmin -lR -r MyRegistry
    This returns something similar to the following output: 
    registry: MyRegistry 
registry kind: APPLICATION 
registry parent: MySystemRegistry 
registry type: RACF 
description: my racf registry 
URI: ldap://some.big.host:389/profileType=User,cn=RACFA,o=My Company,c=US 
registry alias: TCPGROUP 
registry alias type: DNSHostName
  3. To list identifiers, type: 
    eimadmin -lI -i "J.C.Smith"
    This returns something similar to the following output: 
    unique identifier: J.C.Smith 
other identifier: J.C.Smith 
other identifier: Joseph 
other identifier: Joe 
description: 004321 
information: D01 
information: 1990-04-11
  4. To list target associations, type: 
    eimadmin -lA -i "J.C.Smith" -t target
    This returns something similar to the following output: 
    unique identifier: J.C.Smith 
registry: MyRegistry 
registry type: RACF 
association: target 
registry user: SMITH 
description: TSO 
information: 1989-08-01 
information: ADMIN1
  5. To list accesses, type: 
    eimadmin -lC -c admin
    This returns something similar to the following output: 
    access user: cn=JoeUser,o=My Company,c=us 
access user: cn=admin1,o=My Company,c=us 
access user: cn=admin2,o=My Company,c=us

Location

/usr/bin/eimadmin

Security

The LDAP administrator has the authority to use the eimadmin command and access to all the functions it provides. EIM administrators can use the command as long as the following conditions are true:
  • They have a bind distinguished name and password defined at the LDAP server containing the EIM domain
  • Their bind distinguished name has one of the EIM authorities:
    • EIM administrator
    • EIM registries administrator
    • EIM registry X administrator
    • EIM identifiers administrator

Standard Error

The eimadmin command issues a message to prompt for a password or to indicate an error. Do not expect to receive a message for successful completion unless you use an input file. When processing records in an input file, eimadmin issues an informational message as the process starts and stops, in addition to a progress message every 50 records.

Note: The eimadmin command returns one or more data lines for list (-l) requests unless it finds no matching EIM entries, or the bind identity is not authorized to access that data.