Retrieve Directory Server Instance Attributes (QgldRtvDirSvrInstA) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Error code | I/O | Char(*) |
| 5 | Instance name | Input | Char(8) |
Default Public Authority: *USE
Library Name/Service Program: QSYS/QGLDUAPI
Threadsafe: No
The Retrieve Directory Server Instance Attributes (QgldRtvDirSvrInstA) API retrieves information about the directory server instance configuration. It can be used to retrieve information about:
- General server properties
- Encrypted communications configuration. The Secure Sockets Layer (SSL) is used for encrypted communications.
- Performance settings
- Auditing settings
Authorities and Locks
To retrieve format RSVR0700, Server auditing information, the caller of this API must have either *ALLOBJ or *AUDIT special authorities.
For all other formats, no IBM® i special authority is required.
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The variable to receive output data. See Format of Output Data for a description of the format of the output data associated with a specific format name.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable area.
- Format name
- INPUT; CHAR(8)
The format name identifying the type of information to be retrieved. The possible format names follow:
RSVR0100 Basic server configuration RSVR0700 Server auditing information RSVR0900 Server administration information See Format of Output Data for a description of these formats.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
- Instance name
- Input; CHAR(8)
Contains the name of the Directory Server instance to be created. If a NULL pointer or blanks are specified, the default instance name, QUSRDIR is used.
Format of Output Data
For details about the format of the output data, see the following sections. For details about the fields in each format, see Field Descriptions.
RSVR0100 Format
This format is used to retrieve basic server configuration information.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Version |
| 12 | C | BINARY(4) | Read only |
| 16 | 10 | BINARY(4) | Server is replica |
| 20 | 14 | BINARY(4) | Security |
| 24 | 18 | BINARY(4) | Unencrypted port number |
| 28 | 1C | BINARY(4) | Encrypted port number |
| 32 | 20 | BINARY(4) | Current cipher protocols |
| 36 | 24 | BINARY(4) | Installed cipher protocols |
| 40 | 28 | BINARY(4) | Search time limit |
| 44 | 2C | BINARY(4) | Search size limit |
| 48 | 30 | BINARY(4) | Reserved |
| 52 | 34 | BINARY(4) | Reserved |
| 56 | 38 | BINARY(4) | Referral port |
| 60 | 3C | BINARY(4) | Password format |
| 64 | 40 | BINARY(4) | Offset to referral server |
| 68 | 44 | BINARY(4) | Length of referral server |
| 72 | 48 | BINARY(4) | Offset to administrator distinguished name (DN) |
| 76 | 4C | BINARY(4) | Length of administrator DN |
| 80 | 50 | BINARY(4) | Offset to update DN |
| 84 | 54 | BINARY(4) | Length of update DN |
| 88 | 58 | BINARY(4) | Reserved |
| 92 | 5C | BINARY(4) | Reserved |
| 96 | 60 | BINARY(4) | Offset to database path |
| 100 | 64 | BINARY(4) | Length of database path |
| 104 | 68 | BINARY(4) | Reserved |
| 108 | 6C | BINARY(4) | SSL authentication method |
| 112 | 70 | BINARY(4) | Number of database connections |
| 116 | 74 | BINARY(4) | Schema checking level |
| 120 | 78 | BINARY(4) | Offset to master server URL |
| 124 | 7C | BINARY(4) | Length of master server URL |
| 128 | 80 | BINARY(4) | Change log indicator |
| 132 | 84 | BINARY(4) | Maximum number of change log entries |
| 136 | 88 | BINARY(4) | Reserved |
| 140 | 8C | BINARY(4) | Kerberos authentication indicator |
| 144 | 90 | BINARY(4) | Offset to Kerberos key tab file |
| 148 | 94 | BINARY(4) | Length of Kerberos key tab file |
| 152 | 98 | BINARY(4) | Kerberos to DN mapping indicator |
| 156 | 9C | BINARY(4) | Offset to Kerberos administrator ID |
| 160 | A0 | BINARY(4) | Length of Kerberos administrator ID |
| 164 | A4 | BINARY(4) | Offset to Kerberos administrator realm |
| 168 | A8 | BINARY(4) | Length of Kerberos administrator realm |
| 172 | AC | BINARY(4) | Event notification registration indicator |
| 176 | B0 | BINARY(4) | Maximum event registrations for connection |
| 180 | B4 | BINARY(4) | Maximum event registrations for server |
| 184 | B8 | BINARY(4) | Maximum operations per transaction |
| 188 | BC | BINARY(4) | Maximum pending transactions |
| 192 | C0 | BINARY(4) | Transaction time limit |
| 196 | C4 | BINARY(4) | ACL model |
| 200 | C8 | BINARY(4) | Level of authority integration |
| 204 | CC | BINARY(4) | Offset to projected suffix |
| 208 | D0 | BINARY(4) | Length of projected suffix |
| 212 | D4 | BINARY(4) | Read only schema |
| 216 | D8 | BINARY(4) | Read only projected suffix |
| 220 | DC | BINARY(4) | Log client messages |
| 224 | E0 | BINARY(4) | Maximum age of change log entries |
| 228 | E4 | BINARY(4) | Autostart |
| 232 | E8 | BINARY(4) | AES passphrase is set |
| 236 | EC | BINARY(4) | Offset to change log database path |
| 240 | F0 | BINARY(4) | Length ofchange log database path |
| 244 | F4 | BINARY(4) | Offset to AES encryption salt |
| 248 | F8 | BINARY(4) | Length of AES encryption salt |
| 252 | FC | BINARY(4) | Offset to server instance description |
| 256 | 100 | BINARY(4) | Length of server instance description |
| 260 | 104 | BINARY(4) | Offset to configuration library |
| 264 | 108 | BINARY(4) | Length of configuration library |
| 268 | 10C | BINARY(4) | Offset to directory server version |
| 272 | 110 | BINARY(4) | Length of directory server version |
| CHAR(*) | Referral server | ||
| CHAR(*) | Administrator DN | ||
| CHAR(*) | Update DN | ||
| CHAR(*) | Database path | ||
| CHAR(*) | Master server URL | ||
| CHAR(*) | Kerberos key tab file | ||
| CHAR(*) | Kerberos administrator ID | ||
| CHAR(*) | Kerberos administrator realm | ||
| CHAR(*) | Projected suffix | ||
| CHAR(*) | Change log database path | ||
| CHAR(*) | AES encryption salt | ||
| CHAR(*) | Server instance description | ||
| CHAR(*) | Configuration library | ||
| CHAR(*) | Directory server version | ||
RSVR0700 Format
This format is used to retrieve server auditing configuration information.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Security audit option for objects |
| C | C | BINARY(4) | Group Assertion Auditing |
RSVR0900 Format
This format is used to retrieve server administration information.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Offset to server administration URL |
| 12 | C | BINARY(4) | Length of server administration URL |
| CHAR(*) | Server administration URL | ||
Field Descriptions
ACL model. The ACL model that is being used. The following special values may be returned:
| 0 | The ACL model being used supports access-class level permissions. This is the ACL model the directory server used prior to V5R1M0. |
| 1 | The ACL model being used supports both access-class level permissions and attribute-level ACL permissions. |
Administrator DN. A distinguished name (DN) that has access to all objects in the directory. This field is specified in UTF-16 (CCSID 13488).
AES encryption salt. The value for the AES encryption salt for passwords. This field is specified in UTF-16 (CCSID 13488).
AES passphrase is set. Whether the AES passphrase for passwords is set. The passphrase itself cannot be retrieved.
| 0 | No, AES passphrase is not set |
| 1 | Yes, AES passphrase is set |
Autostart. Indicates if the instance starts automatically.
| 0 | No, does not automatically start |
| 1 | Yes, automatically starts |
Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.
Bytes returned. The number of bytes of data returned.
Change log database path. The integrated file system path name of the library containing the directory database. This field is specified in UTF-16 (CCSID 13488).
Change log indicator. The indicator of whether a change log exists for entries that have been added, changed and deleted. The following values may be returned:
| 0 | No, a change log does not exist |
| 1 | Yes, a change log exists |
Configuration library. The name of the configuration library used by this directory server instance. This field is specified in UTF-16 (CCSID 13488).
Current cipher protocols. The cipher protocols that the server allows when using encrypted connections. The value is the sum of zero or more of the following values:
| 0x0100 | Triple Data Encryption Standard (DES) Secure Hash Algorithm (SHA) (U.S.) |
| 0x0200 | DES SHA (U.S) |
| 0x0400 | Rivest Cipher 4 (RC4) SHA (U.S.) |
| 0x0800 | RC4 Message Digest (MD) 5 (U.S.) |
| 0x1000 | RC2 MD5 (export) |
| 0x2000 | RC4 MD5 (export) |
| 0x4000 | Advanced Encryption Standard (AES) SHA 128 bit (U.S.) |
| 0x8000 | Advanced Encryption Standard (AES) SHA 256 bit (U.S.) |
Database path. The integrated file system path name of the library containing the directory database. This field is specified in UTF-16 (CCSID 13488).
Directory server version. The version of the directory server. This field is specified in UTF-16 (CCSID 13488).
Encrypted port number. The port number to use for encrypted connections. The standard port number for encrypted connections is 636.
Event notification registration indicator. Indicator of whether to allow client to register for event notification. The following special values may be returned:
| 0 | Do not allow clients to register for event notification. |
| 1 | Allow clients to register for event notification. |
Group assertion auditing. When the QAUDCTL system value is set to *OBJAUD, then object auditing can be done in the directory. See the Security reference topic collection for information about Directory Server auditing. The following special values may be returned:
| 0 | Specifies that the server should audit only that the operation included a group membership assertion control. |
| 1 | Specifies that the server should audit the list of groups specified in a group membership control. |
Installed cipher protocols. The cipher protocols installed on the system. Refer to the current cipher protocols field for a description of the values.
Kerberos administrator ID. The name of the Kerberos administrator. This field is specified in UTF-16 (CCSID 13488). The following special value may be returned:
| *NONE | No value is specified. |
Kerberos administrator realm. The realm in which the kerberos administrator is registered. This field is specified in UTF-16 (CCSID 13488). The following special value may be returned:
| *NONE | No value is specified. |
Kerberos authentication indicator. The following special values may be returned:
| 0 | Do not support Kerberos authentications. |
| 1 | Support Kerberos authentications. |
Kerberos key tab file. The integrated file system path name for the key tab file that contains the server's secret key used for authentication. This field is specified in UTF-16 (CCSID 13488). The following special value may be returned:
| *NONE | No value is specified. |
Kerberos to DN mapping indicator.
| 0 | Map the Kerberos ID to pseudo DN. A pseudo DN can be used to uniquely identify an LDAP user object of the form 'ibm-kerberosName=principal@realm' or 'ibm-kn=principal@realm'. |
| 1 | Use associated DN in directory. The LDAP server will attempt to find an entry in the directory that contains the kerberos principle and realm as one of its attributes. Once found, this DN will then be used to determine the client's authorizations to the directory. |
Length of administrator DN. The length, in UTF-16 (CCSID 13488) characters, of the administrator DN field.
Length of AES encryption salt. The length, in UTF-16 (CCSID 13488) characters, of the AES encryption salt.
Length of change log database path. The length, in UTF-16 (CCSID 13488) characters, of the change log database path field.
Length of configuration library. The length, in UTF-16 (CCSID 13488) characters, of the configuration library name.
Length of database path. The length, in UTF-16 (CCSID 13488) characters, of the database path field.
Length of directory server version. The length, in UTF-16 (CCSID 13488) characters, of the directory server version.
Length of Kerberos administrator ID. The length, in UTF-16 (CCSID 13488) characters, of the Kerberos Administrator ID field.
Length of Kerberos administrator realm. The length, in UTF-16 (CCSID 13488) characters, of the Kerberos administrator realm field.
Length of Kerberos key tab file. The length, in UTF-16 (CCSID 13488) characters, of the Kerberos key tab file field.
Length of master server URL. The length, in UTF-16 (CCSID 13488) characters, of the master server URL field.
Length of projected suffix. The length, in UTF-16 (CCSID 13488) characters, of the projected suffix field
Length of server administration URL. The length, in UTF-16 (CCSID 13488) characters, of the server administration URL field.
Length of server instance description. The length, in UTF-16 (CCSID 13488) characters, of the server instance description field.
Length of referral server. The length, in UTF-16 (CCSID 13488) characters, of the referral server field.
Length of update DN. The length, in UTF-16 (CCSID 13488) characters, of the update DN field.
Level of authority integration. The level of IBM i authority integration to use to determine if a distinguished name (DN) can become an LDAP administrator. The following special values may be specified:
| 0 | Do not apply 'Directory Server Administrator' (QIBM_DIRSRV_ADMIN) function identifier to bound distinguished names to determine LDAP administrators. |
| 1 | Allow bound distinguished names that refer directly to user profiles to become LDAP administrators if the user profile is identified in the 'Directory Server Administrator' (QIBM_DIRSRV_ADMIN) function identifier. |
Log client messages. Whether the directory server will log client messages in the server joblog. The following values may be returned:
| 0 | The directory server will not log client messages in the server joblog. |
| 1 | The directory server will log client messages in the server joblog. |
Master server URL. The uniform resource locator (URL) of the master server. This field is specified in UTF-16 (CCSID 13488). The following special value may be returned:
| *NONE | No value is specified. |
Maximum event registrations for connection. The following special values may be returned:
| 0 | Do not limit the number of event registrations for connection. |
Maximum event registrations for server. The following special values may be returned:
| 0 | Do not limit the number of event registrations for server. |
Maximum age of change log entries. The age, in seconds, of change log entries that can be stored. If the maximum is reached, the change log entries will be deleted starting with the oldest entry. This value only valid if 'Change log indicator' is set to 1. The following special values may be returned:
| 0 | The age of change log entries is not limited. |
Maximum number of change log entries. The maximum number of change log entries that can be stored. If the maximum is reached, the change log entries will be deleted starting with the oldest entry. This value only valid if 'Change log indicator' is set to 1. The following special values may be returned:
| 0 | The number of change log entries is not limited. |
Maximum operations per transaction. The maximum number of operations that are allowed for each transaction. Transaction support allows a group of directory changes to be handled as a single transaction.
Maximum pending transactions. The maximum number of pending transactions allowed. Transaction support allows a group of directory changes to be handled as a single transaction.
Number of database connections. The number of database connections used by the server.
Offset to AES encryption salt. The offset, in bytes, from the start of the receiver variable to the AES encryption salt field.
Offset to change log database path. The offset, in bytes, from the start of the receiver variable to the change log database path field.
Offset to configuration library. The offset, in bytes, from the start of the receiver variable to the configuration library name field.
Offset to database path. The offset, in bytes, from the start of the receiver variable to the database path field.
Offset to directory server version. The offset, in bytes, from the start of the receiver variable to the directory server version field.
Offset to Kerberos administrator ID. The offset, in bytes, from the start of the input data area to the Kerberos administrator ID field.
Offset to Kerberos administrator realm. The offset, in bytes, from the start of the input data area to the Kerberos administrator realm field.
Offset to Kerberos key tab file. The offset, in bytes, from the start of the input data area to the Kerberos key tab file field.
Offset to master server URL. The offset, in bytes, from the start of the receiver variable to the master server URL field.
Offset to projected suffix. The offset, in bytes, from the start of the input data area to the projected suffix field.
Offset to referral server. The offset, in bytes, from the start of the receiver variable to the referral server field.
Offset to server administration URL. The offset, in bytes, from the start of the receiver variable to the server administration URL field.
Offset to server instance description. The offset, in bytes, from the start of the receiver variable to the server instance description field.
Offset to update DN. The offset, in bytes, from the start of the receiver variable to the update DN field.
Password format. The format of the encrypted password. The following values may be returned:
| 1 | Unencrypted. The clear text password is stored in a validation list and can be returned by searches or used for DIGEST-MD5 SASL authentication. |
| 2 | SHA. (Default) |
| 3 | MD5. |
| 4 | Crypt (The password is one-way hashed using a modified DES algorithm. The 'crypt' algorithm originally was used by many UNIX® operating systems for password protection.) |
| 5 | AES128. |
| 6 | AES192. |
| 7 | AES256. |
Projected suffix. The suffix under which all projected objects for this server reside including user and group profiles. This field is specified in UTF-16 (CCSID 13488).
Read only. Whether the directory server allows changes to be made to the directory contents. The following values may be returned:
| 0 | The directory server is not read only. Updates are allowed to the directory. |
| 1 | The directory server is read only. Updates are not allowed to the directory. |
Read only projected suffix. Whether the directory server will allow updates to be made to the projected suffix. The following values may be returned:
| 0 | The directory server projected suffix is not read only. Updates are allowed to the projected suffix. |
| 1 | The directory server projected suffix is read only. Updates are not allowed to the projected suffix. |
Read only schema. Whether the directory server will allow updates to be made to the directory schema. The following values may be returned:
| 0 | The directory server schema is not read only. Updates are allowed to the schema. |
| 1 | The directory server schema is read only. Updates are not allowed to the schema. |
Referral port. An optional port number to be returned to a client when a request is made for a directory object that does not reside on this server. The referral port and referral server together are used to form a referral URL. The following special value may be returned:
| 0 | The LDAP port is not specified, the client should use the default LDAP port. |
Referral server. The IP name of a server to return to a client when a request is made for a directory object that does not reside on this server. This field is specified in UTF-16 (CCSID 13488). The referral port and referral server are used together to form a referral URL. The following special value may be returned:
| *NONE | No value is specified. |
Reserved. A reserved field. This field must be set to zero.
Schema checking level. The level of schema checking performed by the server. The following values may be returned:
| 0 | None. |
| 1 | LDAP version 2. |
| 2 | LDAP version 3 strict. |
| 3 | LDAP version 3 lenient. |
Search size limit. The maximum number of entries that the server will return for a given search request. The following special value may be returned:
| 0 | Do not limit the number of entries returned. |
Search time limit. The maximum time, in seconds, that the server will spend performing a given search request. The following special value may be returned:
| 0 | Do not limit the search time. |
Security. Whether the server is to use encrypted connections. The following values may be returned:
| 0 | Allow unencrypted connections only. |
| 1 | Allow encrypted connections only. |
| 2 | Allow both encrypted and unencrypted connections. |
Note: SSL is used for encrypted connections to the server.
Security audit option for objects. When the QAUDCTL system value is set to *OBJAUD, then object auditing can be done in the directory. See the Security reference topic collection for information about Directory Server auditing. The following special values may be returned:
| 0 | Do not do object auditing of the directory objects. |
| 1 | Audit changes to directory objects. |
| 2 | Audit all access to directory objects. This includes search, compare and change. |
Server is replica. Whether the server is a master server or a replica server. The following values may be returned:
| 0 | The server is a master server for the directory suffixes present on the server. |
| 1 | The server is a replica server for the directory suffixes present on the server. |
Server administration URL. The server administration URL. This field is specified in UTF-16 (CCSID 13488).
Server instance description. The description of the server instance. This field is specified in UTF-16 (CCSID 13488).
SSL authentication method. The method used during SSL authentication. The following values may be returned:
| 1 | Server authentication. |
| 3 | Server and client authentication. |
Transaction time limit. The maximum time, in seconds, that the server will spend performing a transaction request. Transaction support allows a group of directory changes to be handled as a single transaction.
Unencrypted port number. The port number to be used for unencrypted connections. The standard port number is 389.
Update DN. The distinguished name that the master server must use when propagating directory updates to this replica server. This field is specified in UTF-16 (CCSID 13488). The following value may be returned:
| *NONE | No value is specified. |
Version. Returns the version of the LDAP server.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPFA314 E | Memory allocation error. |
| GLD016E E | *ALLOBJ or *AUDIT special authority required. |
| GLD0215 E | Server has not been configured. |
API introduced: V6R1