Change Directory Server Instance Attributes (QgldChgDirSvrInstA) API

The Change Directory Server Instance Attributes (QgldChgDirSvrInstA) API changes the directory server instance configuration. It can be used to change the following server properties:

• General server properties
• Suffixes served by this server
• Encrypted connection configuration. The Secure Sockets Layer (SSL) is used for encrypted communication.
• Performance settings
• Referral server information
• Server auditing information
• IP address information
• Server administration information

Authorities and Locks

*ALLOBJ and *IOSYSCFG special authority is required to use this API with formats CSVR0100, CSVR0200, CSVR0600, CSVR0800, or CSVR0900. *AUDIT special authority is required to use this API with format CSVR0700. *SECADM special authority is required to change the AES passphrase and the AES salt values with format CSVR0100.

Required Parameter Group

Input data

INPUT; CHAR(*)

A variable that contains the input data. See Format of Input Data for a description of the data associated with a specific format name.

Length of input data

INPUT; BINARY(4)

The length of the input data area.

Format name

INPUT; CHAR(8)

The format name identifying the type of information to be changed. The possible format names follow:

CSVR0100	Basic server configuration
CSVR0200	Add or remove suffixes from this server
CSVR0600	Add or change referral server information
CSVR0700	Server auditing information
CSVR0800	IP address information
CSVR0900	Server administration information

See Format of Input 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 changed. If a NULL pointer or blanks is specified, the default instance name, QUSRDIR is used.

Format of Input Data

For details about the format of the input data, see the following sections. For details about the fields in each format, see Field Descriptions.

CSVR0100 Format

This format is used to change basic server configuration information.

CSVR0200 Format

This format is used to add or remove suffixes from the server. The input data consists of a header and a series of change entries. The header identifies the number of suffixes to be added or removed. Each change entry identifies a suffix and the action to be performed (add or remove the suffix).

Note: Removing a suffix from a server will result in the loss of all directory entries with that suffix.

CSVR0600 Format

This format is used to change referral server configuration information. The input data consists of a header and a series of change entries. The header identifies the master server information and the number of referral servers. This replaces the referral server information, if any, that is currently configured.

CSVR0700 Format

This format is used to change the server auditing configuration information.

CSVR0800 Format

This format is used to change the IP address configuration information. The input data consists of a header and a series of change entries. The header identifies the number of IP addresses in the list. This replaces the IP address information that is currently configured. At least one IP address value must be specified for the server.

CSVR0900 Format

This format is used to change the server administration information.

Field Descriptions

Action. The action to be performed for a given entry. The following values may be specified:

Administrator DN. A distinguished name that has access to all objects in the directory. When either the administrator DN or the administrator password field is changed, both must be specified. This field is specified in UTF-16 (CCSID 13488). To leave the value unchanged, specify a length and offset to this field of zero.

Administrator password. The password used when connecting to the directory server using the administrator DN. When either the administrator DN or the administrator password field is changed, both must be specified. This field is specified in UTF-16 (CCSID 13488). To leave the value unchanged, specify a length and offset to this field of zero.

AES encryption salt. The value for the AES encryption salt for passwords. This must be 12 characters in length. If this field is specified, the AES passphrase field must also be specified. This field is specified in UTF-16 (CCSID 13488). Valid characters include the following characters:

! " # $ % & ' ( ) * + , - . / ? > = < ; : @ [ \ ] ^ _ ` { } | ~

ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789

To leave the value unchanged, specify a length and offset to this field of zero. If not specified, the default is 0, leave the value unchanged.

To have the API generate a salt value, specify "*GENERATE" as the value with a length of 9.

AES passphrase. The value for the AES passphrase for passwords. A minimum of 12 characters and maximum of 1016 characters is allowed. If this field is specified, the AES encryption salt field must also be specified. This field is specified in UTF-16 (CCSID 13488). Valid characters include the following characters:

! " # $ % & ' ( ) * + , - . / ? > = < ; : @ [ \ ] ^ _ ` { } | ~

ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789

To leave the value unchanged, specify a length and offset to this field of zero. If not specified, the default is 0, leave the value unchanged.

Autostart. Indicates if the instance starts automatically. If not specified, the default is -1, the value remains the same.

Change entry. A structure identifying a change to be made. The structure identifies the suffix and the operation to be performed (add, or delete).

Change log database path. The path to a library to contain the change log database objects. This is an integrated file system path name, for example, /QSYS.LIB/QDIRSRV.LIB. If an existing library is to be used, the library must exist in a system ASP or a basic user ASP (ASP value of 1 to 32). The library cannot exist in an independent ASP (ASP value greater than 32). This field is specified in UTF-16 (CCSID 13488). To leave the value unchanged, specify a length and offset to this field of zero. If not specified, the default is to leave the value unchanged.

Change log indicator. The indicator of whether to have a change log for entries that are added, changed or deleted. The following values may be specified:

Create change log database. Whether the change log database object is to be created or if it must previously exist. This is only used if the change log indicator field is set to Yes, have a change log. If the change log indicator field is set to No, this field must be 0. If not specified, the default is to not create a change log database.

Create database. Whether the database object is to be created or if it must previously exist. This is only used if the database path field is specified. If not specified, the database will not be created.

Current cipher protocols. The cipher protocols that the server will allow when using encrypted connections. The following values may be specified:

Or the sum of one or more of the following values:

Database path. The path to an existing library containing the directory database objects. This is an integrated file system path name, for example, /QSYS.LIB/DIRSRV.LIB. By changing this field, you make the current directory contents inaccessible. By changing the field back to its original value, you restore the original directory contents. The library must exist in a system ASP or a basic user ASP (ASP value of 1 to 32). The library cannot exist in an independent ASP (ASP value greater than 32). This field is specified in UTF-16 (CCSID 13488). To leave the value unchanged, specify a length and offset to this field of zero.

Displacement to IP address. The displacement, in bytes, from the start of the current entry to the IP address field.

Displacement to next entry. The displacement, in bytes, from the start of the current entry to the next entry in the input data.

Displacement to referral server URL. The displacement, in bytes, from the start of the current entry to the referral server URL field.

Displacement to suffix. The displacement, in bytes, from the start of the current entry to the suffix field.

Encrypted port number. The port number to use for encrypted connections. The standard port number for encrypted connections (SSL) is 636. Valid port numbers are in the range 1 to 65535. The following special value may be specified:

Event notification registration indicator. Indicator of whether to allow client to register for event notification. The following special values may be specified:

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. If not specified, the value of this field does not change. The following special values may be specified:

IP address. The IPv4 or IPv6 address of the client for which the directory server will accept connections. The IP address must already exist to be specified. A value of hexadecimal zeroes and leading zeroes is not allowed. An IPv4 address is expressed in standard dotted-decimal form www.xxx.yyy.zzz; for example, 130.99.128.1. An IPv6 address always has at least one occurrence of a colon (':') in the format. Some possible IPv6 address formats would be: ::x (for example, ::1) or ::w.xxx.y.zzz (for example, ::9.130.4.169). For further IPv6 examples and explanation, refer to the Usage Notes section in the Convert IPv4 and IPv6 Addresses Between Text and Binary Form (inet_pton) API. This field is specified in UTF-16 (CCSID 13488).

The following special value may be specified:

Kerberos administrator ID. The name of the Kerberos administrator. This field is specified in UTF-16 (CCSID 13488). The following special value may be specified:

To leave the value unchanged, specify a length and offset to this field of zero.

Kerberos administrator realm. The realm where the kerberos administrator is registered. This field is specified in UTF-16 (CCSID 13488). The following special value may be specified:

To leave the value unchanged, specify a length and offset to this field of zero.

Kerberos authentication indicator. The following special values may be specified:

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. The QDIRSRV user profile is given authorization to read this file. This field is specified in UTF-16 (CCSID 13488). The following special value may be specified:

To leave the value unchanged, specify a length and offset or displacement to this field of zero.

Kerberos to DN mapping indicator.

Length of administrator DN. The length, in UTF-16 (CCSID 13488) characters, of the administrator DN field.

Length of administrator password. The length, in UTF-16 (CCSID 13488) characters, of the administrator password field.

Length of AES encryption salt. The length, in UTF-16 (CCSID 13488) characters, of the AES encryption salt. Specify a length of 0 to leave the AES encryption salt unchanged. If not specified, the default is 0, do not change the AES encryption salt.

Length of AES passphrase. The length, in UTF-16 (CCSID 13488) characters, of the AES passphrase. Specify a length of 0 to leave the AES passphrase unchanged. If not specified, the default is 0, do not change the AES passphrase.

Length of change log database path. The length, in UTF-16 (CCSID 13488) characters, of the change log database path field. If not specified, the default is 0, do not change the change log database. If not specified, the change log database path is not changed.

Length of database path. The length, in UTF-16 (CCSID 13488) characters, of the database path field.

Length of IP address. The length, in UTF-16 (CCSID 13488) characters, of the IP address field.

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 referral server URL. The length, in UTF-16 (CCSID 13488) characters, of the referral server URL 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. Specify a length of 0 to leave the server instance description unchanged. If not specified, the default is 0, do not change the server instance description.

Length of suffix. The length, in UTF-16 (CCSID 13488) characters, of the suffix field.

Length of update DN. The length, in UTF-16 (CCSID 13488) characters, of the update DN field.

Length of update password. The length, in UTF-16 (CCSID 13488) characters, of the update password field.

Level indicator. The level indicator of the data supplied for a format. See the format descriptions for possible uses and values of this 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. Allowing a user profile to become an LDAP administrator can be done by setting the 'Level of authority integration' to '1' and then authorizing specific user profiles to the 'Directory Server Administrator' function of the operating system through System i™ Navigator's Application Administration support. The Change Function Usage Information (QSYCHFUI) API, with a function ID of QIBM_DIRSRV_ADMIN, can also be used to change the list of users that are allowed to be an LDAP administator. The user profile can be mapped to a DN as a projected user (for example, for user profile 'FRED', and the projected suffix of 'systemA', the projected user's DN would be os400-profile=FRED,cn=accounts,os400-sys=systemA ).

The following special values may be specified:

Log client messages. Whether the directory server will log client messages in the server joblog. The following values may be specified:

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 specified:

To leave the value unchanged, specify a length and offset to this field of zero.

Maximum age of change log entries. The maximum 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 used if 'Change log indicator' is set to 1. The following special values may be specified:

Maximum event registrations for connection. The following special values may be specified:

Maximum event registrations for server. The following special values may be specified:

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 used if 'Change log indicator' is set to 1. The following special values may be specified:

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. The following special values may be specified:

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. The following special value may be specified:

Nonencrypted port number. The port number to be used for nonencrypted connections. The standard port number is 389. Valid port numbers are in the range 1 to 65535. The following special value may be specified:

Number of change entries. The number of change entries present in the input data.

Number of database connections. The number of database connections used by the server. Valid numbers are in the range 4 to 32. The following special value may be specified:

Offset to administrator DN. The offset, in bytes, from the start of the input data area to the administrator DN field.

Offset to administrator password. The offset, in bytes, from the start of the input data area to the administrator password field.

Offset to AES encryption salt. The offset, in bytes, from the start of the input data area to the AES encryption salt. To leave the AES encryption salt unchanged, specify a value of 0 for this field. If not specified, the default is 0, do not change the AES encryption salt.

Offset to AES passphrase. The offset, in bytes, from the start of the input data area to the AES passphrase. To leave the AES passphrase unchanged, specify a value of 0 for this field. If not specified, the default is 0, do not change the AES passphrase.

Offset to change entries. The offset, in bytes, from the start of the input data area to the the first change entry.

Offset to change log database path. The offset, in bytes, from the start of the input data area to the change log database path field. To leave the change log database path unchanged, specify a value of 0 for this field. If not specified, the default is 0, do not change the change log database path.

Offset to database path. The offset, in bytes, from the start of the input data area to the database path field. To leave the database path unchanged, specify a value of 0 for this 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 input data area 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 server administration URL. The offset, in bytes, from the start of the input data to the server administration URL field.

Offset to server instance description. The offset, in bytes, from the start of the input data area to the server instance description. To leave the server instance description unchanged, specify a value of 0 for this field. If not specified, the default is 0, do not change the server instance description.

Offset to update DN. The offset, in bytes, from the start of the input data area to the update DN field.

Offset to update password. The offset, in bytes, from the start of the input data area to the update password field.

Password format. The format of the encrypted password. The following values may be specified:

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 will allow updates to be made to the directory contents. The following values may be specified:

Read only projected suffix. Whether the directory server will allow updates to be made to the projected suffix. The following values may be specified:

Read only schema. Whether the directory server will allow updates to be made to the directory schema. The following values may be specified:

Referral server URL. The uniform resource locator (URL) of the referral server. This field is specified in UTF-16 (CCSID 13488).

Reserved. A reserved field. This field must be set to zero.

Reset schema. Reset the schema to what is initially shipped with the IBM i directory server. If not specified, the value of the field does not change.The following may be specified:

Schema checking level. The level of schema checking performed by the server. The following values may be specified:

Search size limit. The maximum number of entries that the server will return for a given search request. The following special values may be specified:

Search time limit. The maximum time, in seconds, that the server will spend performing a given search request. The following special values may be specified:

Security. Whether the server should use encrypted connections. The following values may be specified:

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 specified:

Server instance description. The server instance description for the server instance. This field is specified in UTF-16 (CCSID 13488). To leave the value unchanged, specify a length and offset or displacement to this field of zero. If not specified, the default is 0, do not change the server instance description.

Server is replica. Whether the server is a master server or a replica server. When this field is changed to make the server a replica, the update DN, update password, and referral fields must be specified. The following values may be specified:

Server administration URL. The server administration URL. This field is specified in UTF-16 (CCSID 13488). To leave the value unchanged, specify a length and offset to this field of zero.

SSL authentication method. The method used during SSL authentication. The following values may be specified:

Suffix. The name of the directory suffix to be added or removed from the server. This field is specified in UTF-16 (CCSID 13488).

Suffix change entries. The list of suffixes to be added or deleted.

System ASP number for change log database. Specifies the number of the system or basic user auxiliary storage pool (ASP) where storage for the directory change log database library is allocated. This is only used if the Create change log database field is set to Yes. If the Create change log database field is set to No, this field must be 0. If not specified, the default is 0.

1

The storage space for the change log database library is allocated from the system auxiliary storage pool ASP 1.

number

Specify a value ranging from 1 through 32 that is the number of the system or basic user ASP.

System ASP number for database. Specifies the number of the system or basic user auxiliary storage pool (ASP) where storage for the directory database library is allocated. This is only used if the Create database field is set to Yes. If the Create database field is set to No, this field must be 0. If not specified, the default is 0.

1

The storage space for the database library is allocated from the system auxiliary storage pool ASP 1.

number

Specify a value ranging from 1 through 32 that is the number of the system or basic user ASP.

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. The following special values may be specified:

Update DN. The distinguished name that the master server must use when propagating directory updates to this replica server. This field may be specified only when the server is a replica. When either the update DN or the update password field is changed, both must be specified. This field is specified in UTF-16 (CCSID 13488). The following special value may be specified:

To leave the value unchanged, specify a length and offset to this field of zero.

Update password. The password used when connecting to this server using the update DN. This field may be specified only when the server is a replica. When either the update DN or the update password field is changed, both must be specified. This field is specified in UTF-16 (CCSID 13488). To leave the value unchanged, specify a length and offset to this field of zero. The following special value may be specified:

Error Messages

[ Back to top | UNIX-Type APIs | APIs by category ]