eimadmin

Purpose

Perform actions on the following objects:

Domains
Registries
Identifiers
Associations
Access authorities
Policies

The actions you can perform include the following:

Add an object
Purge an object
List objects (for example, list directories, list registries, and so forth)
Modify attributes associated with objects
Erase attributes

Format

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

Table 1 summarizes the objects and actions and the flags required and optional for each.

Figure 1. Tips

Each eimadmin command must include one action and one object type. Depending on the object and action you are performing on it, EIM might require additional parameters.
Some options are for multi-value attributes, which you can specify more than once. Other options are for single-value attributes, which you can specify once. (If you repeat an option that is for a single-value attribute, eimadmin processes only the first value it encounters in the command.) Other than this, the order in which you specify parameters is not important.
You can code the parameters of the eimadmin command in several ways:
- You can concatenate an action and an object, but must omit the embedded hyphen:
```
-aD
```
- You can include both hyphens but must separate the two options with a space:
```
-a -D
```
- In other words, the following is not valid because it includes both hyphens and there is no space before -D:
```
-a-D
```

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. See Using an input file for more information. See Table 1 for the mapping of file labels with command line options.

Figure 2. Rule

The required connection flags, generally independent of the specified object type and action, are shown in Table 1.

Table 1. Required and optional flags. Required and optional flags
Object	Action	Required	Optional	Comments
`D`	`a`	`b,d, h, w`	`n, B`	Add a domain. b and w can be omitted if bind information and password are obtained from the RACF profile.
	`p`	`d, h, b, w`	`s`	Remove a domain. If the domain is not empty, include '-s RMDEPS'.
	`l`	`d, h, b, w`		List domain(s). Specify -d'*' to list all domains.
	`m`	`d, h, b, w`	`n, B`	Modify or add a domain attribute.
	`e`	`d, h, b, w`	`n, B`	Remove or clear a domain attribute.
`R`	`a`	`r,y`	`g, k, n, x, z, B`	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.
	p	`r`	`s`	Remove a registry.
	`l`	`r`	`y`	List registries. Return all registry entries in the domain that match the specified '-r' value search filter, which might contain the wild card '*'.
	`m`	`r`	`k, n, x, z, B`	Modify or add a registry attribute, including a registry alias.
	`e`	`r`	`k, n, x, z, B`	Remove or clear a registry attribute, including a registry alias.
`I`	`a`	`i`	`j, n, o`	Add an identifier.
	`p`	`i`		Remove an identifier.
	`l`	`i`		List an identifier by unique identifier name. Return all identifier entries in the domain that match the specified '-i' value search filter, which might contain the wild card '*'.
		`U`		Echo the identifier UUID followed by the unique identifier name. The -U value search filter cannot include the wild card '*'.
		`j`		List an identifier by non-unique identifier name. Return all identifier entries in the domain that have a non-unique identifier matching the specified '-j' value search filter, which might contain the wild card '*'.
	`m`	`i`	`j, n, o`	Modify or add an identifier attribute.
	`e`	`i`	`j, n, o`	Remove or clear an identifier attribute.
`A`	`a`	`i, r, u` or `E, t`	`n, o`	Add an association. You can repeat the '-t' option to add multiple associations types. Flags '-n' and '-o' are relevant only to TARGET associations.
	`p`	`i, r, u` or `E, t`		Remove an association. You can repeat the '-t' option to remove multiple associations types.
	`l`	`i`	`t`	List association(s). 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.
	`m`	`r, u` or `E, t`	`n, o`	Modify or add an association attribute. Flags '-n' and '-o' are relevant only to TARGET associations.
	`e`	`r, u` or `E, t`	`n, o`	Remove or clear an association attribute. Flags '-n' and '-o' are relevant only to TARGET associations.
`Y`	`a`	`t DOMAIN, T, u` or `E`	`n, o`	Add a default domain policy association. For association type -t DOMAIN only.
		`t REGISTRY, r, T, u` or `E`	`n, o`	Add a default domain policy association. For association type -t REGISTRY only.
		`r`, one or more of `J,F, G`		Add a filter policy. No association type is specified.
		`t FILTER, r` one or more of `J, F, G`, `T, u` or `E`	`n, o,`	Add a filter policy and a filter policy association. For association type -t, FILTER only.
	`p`	`t DOMAIN, T, u` or `E`		Remove a default domain policy association. For association type -t DOMAIN only.
		`t REGISTRY, r,T, u` or `E`		Remove a default registry policy association. For association type -t REGISTRY only.
		`r`, one or more of `J, F, G`		Remove a filter policy and it's filter policy associations. No association type is specified.
		`-t FILTER`, `r`, one or more of `J, F, G, T, u` or `E`		Remove a filter policy association. For association type -t FILTER only.
	`l`	`t POLICY`	`r, T`	List all types of policies for a domain, all policies with the source registry, and/or all policies with the target registry. For association type -t POLICY.
		`t DOMAIN`	`T, u` or `E`	List default registry policies. For association type -t DOMAIN only.
		`t REGISTRY`	`r, T, u` or `E`	List default registry policies. For association type -t REGISTRY only.
		`t FILTER`	`T, u` or `E`, `J, F, G, r`	List only filter policies with associations. For association type -t FILTER only.
			`R, J, F, G`	List all filters policies. Associations are not displayed. No association type is specified.
	`m`	`T, u` or `E`	`n, o`	Modify or add an attribute belonging to the target user of a policy.
	`e`	`T, u` or `E`	`n, o`	Remove or clear an attribute belonging to the target user of a policy.
`C`	`a`	`c, q, f`	`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.
	`p`	`c, q, f`	`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.
	`l`	`c`	`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.
	`l`	`q, f`		List access by user.

Parameters

Actions

-a|-p|-l|-m|-e

This is the action you want to perform:

-a: Add an object. (Create an object definition and its attributes.)
-p: Purge an object. (Remove an object definition and its attributes.)
-l: List an object. (Retrieve an object definition and its attributes.)
-m: Modify an attribute. (Alter an attribute of an existing object, either by changing a single-value attribute or adding a multi-value attribute.)
-e: Erase an attribute. (Clear a single-value attribute or remove a multi-value attribute.)

Object types

-D|-R|-I|-A|-C |-Y

This parameter specifies the object types on which to perform the action:

-D: A domain. This is a collection of identifiers, user registries, and associations between identifiers and user IDs, and policies, stored within an LDAP directory. (For more information about EIM domains, see topic 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. It is a logical collection of user identities and policies. (For more information, see topic EIM domain.)
-I: An identifier. This is the name of a person or entity participating in an EIM domain. (For more information, see topic EIM domain.)
-A: An association. This is a relationship between an identifier in the EIM domain with a user ID. (For more information, see topic EIM domain.)
-C: An access authority. This is an EIM-defined LDAP access control group. (For more information, see topic EIM access control.)
-Y: A policy. This is a relationship between a registry or domain and a user identity in a target registry.

Processing controls, attributes, and connection values

Processing controls

Processing controls include the following:

-s switch

The switch specifies a value that affects the way the eimadmin utility functions operate. You can specify the following value:

RMDEPS: Remove dependents when removing a domain or system registry. This facilitates removing a domain by first removing all identifiers and registries defined for the domain. It facilitates the removing a system registry by first removing all applications registries defined for the registry.
Attention: The eimadmin utility does not warn you that dependents exist before removing them, so use this switch carefully.

-U identifierUUID: The identifierUUID is the universally unique identifier form of the EIM identifier. This flag is only valid with eimadmin -lI.

-v verboseLevel

The verboseLevel is an integer from 1 to 10, that controls the amount of trace detail that the eimadmin utility 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", which indicates EIM API call parameters and return values
"6", which indicates option values and input file labels
"9", which indicates utility routine entry and exit statements

Objects and attributes

Rule: Options are single-valued unless indicated otherwise.

The section that follows explains required and optional attributes and their parameters.

Figure 3. Tips

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 multi-word value without quotation marks in effect truncates the command line options; values after the first word are truncated.
The following special characters are not allowed in registryName, registryParent, or identifier:
```
, = + < > # ; \ *
```

Figure 4. Rule

Except where indicated, the parameters are single-value options. If you specify an option more than once, the utility processes only the first occurrence.

-B attribute

The attribute flag is used to add, modify, remove, or clear and attribute for the domain. It may also enable or disable a function in the EIM domain.

The attribute flag specified with the domain object may have the following value:

POLICY: Enable or disable default domain and registry policies. By default, default policies are disabled in the domain.

The attribute flag specified with the registy object may have one of the following values:

LOOKUP: Enable or disable lookup operations
POLICY: Enable or disable default registry policies

By default, registries are enabled for lookup operations, but default registry policies are disabled. Specifying -e deactivates the function. Specifying -m activates the function.

-c accessType

The accessType specifies the scope of access authority that a user has over the EIM domain. It 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.

-E certificate

The name of a file or dataset containing an X.509 certificate. The name stored in the certificate will be used to create an association with an identifier. The certificate may be DER or base 64 encoded. The base 64 encoded certificate may be in EBCIDIC or ASCII.

When working with an source, target, or administrative associations, the subject's distinguished name, the issuer's distinguished name, and the public key info are extracted from the certificate and used to create the registry user name for the association.

-f accessUserType

The accessUserType specifies the type for the access user name. It must be one of the following:

DN: The accessUser is a distinguished name. (See -q accessUser for a description)
KERBEROS: The accessUser is a Kerberos identity. (See -q accessUser for a description)

-F issuerFilter

All or part of the issuer portion of a certificate filter policy name. When used without the -E certificate flag, the issuer filter must be a sequence of relative distinguished names that make up a complete certificate filter policy issuer name. For example:

O=A Certificate Authority,L=Internet

When used with the -E certficate flag, the issuer filter is a substring that indicates what part of the issuer's distinguished name from the certificate should be used for the certificate filter policy's issuer name. For example if the certificate has the issuer's distinguished name of the following:

OU=Certified User,O=A Certificate Authority,L=Internet

and the issuerFilter value is O=, then the issuer portion of the certificate filter policy name is:

O=A Certificate Authority,L=Internet

If the -F flag is omitted when working with certificate filter policies, the certificate filter policy's name will not contain an issuer filter.

-G certificateFilterTemplate

The name of a file or dataset containing an X.509 certificate. The name stored in the certificate will be used to create a certificate filter policy. The certificate may be DER or base 64 encoded. The base 64 encoded certificate may be in EBCIDIC or ASCII.

When working with a certificate filter policy, only the subject's distinguished name and issuer's distinguished name are extracted from the certificate. They are used as a template for the name of the certificate filter policy. The -J subjectFilter and -F issuerFilter flags are used to indicate what portion of the distinguished names to use.

-g registryParent: The 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

The identifier is a unique identifier name.

Figure 5. Example

John Day

-j otherIdentifier

The otherIdentifier specifies a non-unique identifier name.

Figure 6. Example

John

Note: You can specify this option multiple times to assign multiple non-unique identifiers.

-J subjectFilter

All or part of the subject portion of a certificate filter policy name. When used without the -E certificate flag, the subject filter must be a sequence of relative distinguished names that make up a complete certificate filter policy subject name. For example:

O=My Company,C=US

When used with the -E certificate flag, the subject filter is a substring that indicates what part of the subject's distinguished name from the certificate should be used for the certificate filter policy's subject name. For example if the certificate has the following subject distinguished name:

CN=John Smith,O=My Company,C=US

and the subjectFilter value is C=, then the subject portion of the certificate filter policy name is:

C=US

If the -J flag is omitted when working with certificate filter policies, the certificate filter policy name will not contain a subject filter.

-k URI: The URI specifies the Universal Resource Identifier (URI) for the registry (if one exists).

-n description: The 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: The 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: The accessUser specifies the user distinguished name (DN) or the Kerberos identity with EIM access, depending on the accessUserType specified.

-r registryName: The registryName specifies the name of a registry. When you add a new registry, eimadmin considers the registry a system registry unless you also specify the -g option. If you specify the -g option, eimadmin considers the registry an application registry.

-t associationType

The associationType specifies the relationship between an identifier and a registry or a policy type. It 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.
DOMAIN: Indicates a default domain policy.
REGISTRY: Indicates a default registry policy.
FILTER: Indicates a certificate filter policy.
POLICY: Indicates any kind of policy.

Note: You can specify this option multiple times to define multiple relationships.

-T targetRegistryName

The targetRegistryName specifies the name of a registry. This value is used when creating or deleting a default registry policy.

-u registryUser: The registryUser specifies the user ID of the user defined in the registry.

-x registryAlias: The registryAlias specifies another name for a registry.
See Working with registry aliases for information about working with aliases.
You can specify this option multiple times to assign multiple aliases.

-y registryType

The registryType specifies the type of registry. Predefined types that eimadmin recognizes include the following:

RACF
OS400
KERBEROS (for case ignore)
KERBEROSX (for case exact)
AIX
NDS
LDAP
PD (Policy Director)
WIN2K
X509
LINUX
DOMINOS
DOMINOL

You can also create your own types by concatenating a unique OID with one of the following two normalization methods:

-caseIgnore
-caseExact

(See EIM registry definition for more information.)

-z registryAliasType

The 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 utility recognizes only the first specification of registryAliasType. However, the eimadmin utility does recognize multiple registry aliases and associates all of them with the single registryAliasType.

Connection values

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 not specified, the information is retrieved from a RACF profile. See Storing LDAP binding information in a profile for more information.

Rule: If any of the connect information is specified, the full set of values required for the connect type must be specified. Omitting one or more values (but not all) results in an error. Table 2 shows the required and optional values for each connect and host type when specified with the eimadmin command:

Table 2. Required connection values. Required connection values
Connection type	Host type `secure(ldaps://) / non-secure(ldap://)`	Required values	Optional values
SIMPLE or CRAM-MD5	secure	-d, -h, -b, -w, -K, -P	-N
SIMPLE or CRAM-MD5	non-secure	-d, -h, -b, -w
EXTERNAL	secure	-d, -h, -K, -P, -S	-N
EXTERNAL	non-secure	unsupported	unsupported
GSSAPI	secure	-d, -h, -K, -P, -S	-N
GSSAPI	non-secure	-d, -h, -S
Figure 7. Tips Exceptions: 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. The utility prompts for the simple bind password if required and -w is not specified on the command line, and prompts for the SSL key database file password if required and -P is not specified on the command line.

-S connectType

The connectType is the method of authentication to the LDAP server. It 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, the connect type 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 z/OS Integrated Security Services Network Authentication Service Administration.

-d domainDN

The domainDN is the full distinguished name (DN) of the EIM domain. It begins with 'ibm-eimDomainName='. It further consists of:

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, for example, "o=ibm,c=us".

Figure 8. Example

ibm-eimDomainName=MyDomain,o=ibm,c=us

-h ldapHost

The ldapHost is the URL and port for the LDAP server controlling the EIM data. The format is:

Figure 9. Examples

ldap://some.ldap.host:389

ldaps://secure.ldap.host:636

-b bindDN

The bindDN is the distinguished name to use for the simple bind to LDAP. The format is:

Figure 10. Examples

cn=Johns Admin

cn=Johns Admin,o=ibm,c=us

-w bindPassword

The bindPassword is the password associated with the bind DN (for the LDAP bind).

-K keyFile

The keyFile is 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 which contains authentication certificates. This value is required for SSL communications with a secure LDAP host (prefixed ldaps://).

Figure 11. Example

/u/eimuser/ldap.kdb

-P keyFilePassword

The keyFilePassword is 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://.

Figure 12. Example

secret
or
file:///u/eimuser/ldapclient.sth

Note: The eimadmin utility prompts for a key file password if you specify the name of a key database file for -K but not the -P option on the command line.

-N certificateLabel

The certificateLabel identifies 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.

Figure 13. Example

eimcert

Authorization

The LDAP administrator has the authority to use the eimadmin utility and access to all the functions it provides. EIM administrators can use the utility as long as:

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
See EIM access control for details about the specific tasks each administrator can perform.

Messages

Eimadmin 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 for the start, stop, and a progress message for every 50 records.

Note: Eimadmin 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 that data.

For eimadmin error messages, see Messages, specifically ITY4xxx messages.

Error codes

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

Table 3. Eimadmin utility exit codes
Exit code	Meaning
0	No errors encountered.
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.