dirxmodify
Synopsis
dirxmodify
-f LDIF_file [-a]
[-A attribute_type1:attribute_value1+attribute_type2:attribute_value2
[+attribute_type3:attribute_value3+…]]
[-B type:_value_+type1:_value1_[_type2_:_value2_…]]
[-c]
[-C certDB_file]
[-d]
[-D bind_DN]
[-w password | -W password_file]
[-e error_file]
[-E]
[-g]
[-G]
[-h host]
[-p port_number]
[-i attribute_type] […]
[-I number]
[-l]
[-M pattern] […]
[-n]
[-O file_name]
[-o entry_offset]
[-P number]
[-S number]
[-q filter]
[-R]
[-r separator-old_string-separator-new_string]
[-s separator-old_type-separator-new_type]
[-t byte_offset]
[-U separator-old_string-separator-new_string]
[-u]
[-v]
[-x]
[-z string]
[-Z] |
-V
Purpose
Loads an LDIF content or change file into an existing directory database using an LDAPv3 server.
Options
-f LDIF_file
-
Specifies the LDIF file to be loaded via LDAPv3 protocol. Specify the full pathname or relative pathname of the LDIF file.
-a
-
This option is required for LDIF content files. Only new entries are added. Any error reported stops processing. Non-fatal errors are ignored if the -c option has been specified. This option is prohibited for LDIF change files.
If an LDIF file containing schema information is loaded this option is prohibited.
-A attribute_type1:attribute_value1+attribute_type2:attribute_value2
[+attribute_type3:attribute_value3+…]
-
Specifies attribute types and values that are added to each object in the specified LDIF content file that contains attribute_type1 with attribute_value1. The number of attribute types and values is unlimited. Separate multiple attribute value assertions with a plus sign (+). A SPACE character can only be specified as part of an attribute value. Specifying binary or Base-64 encoded attribute values is not supported. You can specify this option only once.
This option is prohibited for LDIF change files.
-B[none] * type:_value_+type1:_value1_ [+type2:_value2_+…]
-
Specifies that all occurrencies of the attribute type type and attribute value value in the specified LDIF content file are replaced by the attribute type(s) and attibute value(s) specified in type1*:*vaue1**...*type_n:*value_n. You can use the wildcard character (*) for the old attribute value value to specify any exisiting attribute value. The number of new attribute type and value assertions type1*:*vaue1**...*type_n:*value_n is unlimited. Separate multiple attribute value assertions with a plus sign (+). You can specify this option only once.
This option is prohibited for LDIF change files.
-c
-
Directs dirxmodify to continue processing and ignore LDAP errors detected during the load operation.
-C certDB_file
-
Specifies the full pathname of the cert8.db file that contains the certificate database used by the Mozilla ldapssl library. A certificate database typically consists of PKCS#12 containers with the client’s user certificates and their corresponding private keys, server certificates of valid servers and CA-certificates of accepted Root CAs. (See section SSL/TLS Certificate Database of chapter DirX Directory Files for details.)
The default value is install_path*/client/conf/cert8.db*.
-d
-
Directs dirxmodify to display the options specified or their default values and exits. To process the LDIF file you must re-issue the dirxmodify command without the -d option.
-D bind_DN
-
Specifies the distinguished name in LDAP format that dirxmodify is to use when binding to the LDAP server that manages the database. If this option is not used, dirxmodify binds as an anonymous user.
-w password
-
Specifies the password that dirxmodify is to use when binding to the LDAP server.
-W password_file
-
Specifies the path to a file containing the password that dirxmodify is to use when binding to the LDAP server (see the -w option). The password must be the only content of this file. When creating the file, the password must be specified in plain ASCII format. After the first successful reading by the application, the password is symmetrically encrypted and the file is rewritten to provide protected local storage.
-e error_file
-
Directs dirxmodify to write erroneous LDIF entries detected during the load operation to the specified file.
-E
-
Directs dirxmodify to use server-based authenticated, encrypted LDAP communication over SSL/TLS.
-g
-
Directs dirxmodify to ignore all attribute assertions with empty values.
-G
-
Directs dirxmodify to handle attribute assertions with empty values like an error.
-h host
-
Specifies the host name or TCP/IP address of the LDAP server to which dirxmodify is to bind. The default value is localhost.
-p port_number
-
Specifies the LDAP port number of the LDAP server to which dirxmodify is to bind. The default value is 389.
-i attribute_type […]
-
Directs dirxmodify to ignore attributes of the specified attribute type(s) during the load operation. You can specify a maximum of 16 attribute types. You cannot specify the distinguished name (DN) attribute type. This option can only be used for LDIF content files together with the option -a.
-I number
-
(Capital letter "i".) Sets the reporting interval to number records.
-l
-
(Lower letter "L".) Converts ISO-8859-1 (Latin-1) characters to UTF-8 characters for all attribute values. Conversion is not performed on Base-64-encoded values. You cannot use this option with the -u option.
-M pattern […]
-
Directs dirxmodify to ignore all records of the LDIF file containing the string pattern. If pattern contains the SPACE character it must be enclosed by quotation marks (""). pattern must not contain the characters carriage return or line feed. pattern can be any string that may occur in the LDIF record.
-n
-
Runs dirxmodify in "simulation" mode: the command processes the LDIF file but does not perform the LDAP operations. This option is useful for collecting statistics or checking LDIF files.
-O file_name
-
Directs dirxmodify to write possibly modified records to a LDIF content or LDIF change file with the name specified in file_name instead of performing the modifications to the DirX Directory database. The following options are evaluated when processing the LDIF file records:
-
-A (adds attribute types and values)
-
-B (replaces attribute types and values)
-
-i (ignores attributes, only when rewriting LDIF content files)
-
-l (converts Latin-1 characters to UTF-8)
-
-M (ignores records conatining a specific string)
-
-o (specifies the file position where to start processing records)
-
-P (specifies the maximum number of values in the first operation propagated to the DSA when splitting records)
-
-S (specifies the maximum number of values in the operations propagated to the DSA when splitting records)
-
-r (replaces specific strings)
-
-s (replaces attribute types)
-
-t (specifies the file position where to start processing records)
-
-U (modifies a specific string inside a distinguished name)
-
-u (checks Base-64 values for UTF-8 conformance)
-
-z (process only records whose distinguished name contain the specified string)
-
-o entry_offset
-
Specifies the LDIF entry number within the LDIF file at which dirxmodify is to start the load operation. The default value is 0. When this option is used with the -t option, entry_offset is relative to -t byte_offset.
-P number
-
Specifies the maximum number of values in the first add operation propagated to the DSA when splitting records. The default value is 100. A value of 0 disables auto-splitting mode.
This option is prohibited for LDIF change files.
-S number
-
Specifies the maximum number of values in follow-up modify operations propagated to the DSA when splitting records. The default value is 5000. A value of 0 disables auto-splitting mode.
This option is prohibited for LDIF change files.
-q filter
-
Performs a simple LDAP filter query on the LDIF file. Specify the filter using the syntax (*attribute___type=assertion). You can use the wildcard character () in the filter. You cannot use "not", "or" and "and" filters. When you use this option, you must also use the -n option.
-R
-
Directs dirxmodify to extract all distinguished names from the LDIF content file and performs delete operations for all entries with these distinguished names in the DIT. This option overrules the -a option.
This option is prohibited for LDIF change files.
-r separator-old_string-separator-new_string
-
Replaces all occurrences of old_string with new_string in attribute values. separator is a character that marks the start of each string; for example, a slash (/), a colon (:), and so on. For example, -r /old/new replaces the string "old" by the string "new". You can specify this option only once.
-s separator-old_type-separator-new_type
-
Replaces all occurrences of old_type with new_type in attribute types. separator is a character that marks the start of each string; for example, a slash (/), a colon (:), and so on. For example, -s :phone:telephone replaces the attribute type "phone" by the attribute type "telephone". You can specify this option only once.
-t byte_offset
-
Specifies the offset in bytes into the LDIF file at which processing is to start. The default value is 0.
-U separator-old_string-seperator-new_string
-
Replaces all occurrences of old_string with new_string in the distinguished name. separator is a character that marks the start of each string; for example, a slash (/), a colon (:), and so on. For example, -U /ou=Kieselbach/ou=Kisseldorf replaces the old ou=Kieselbach by the new ou=Kisseldorf inside the distinguished name. This option is only performed to the distinguished name, it is not performed to attributes with distinguished name syntax. You can specify this option only once.
-u
-
Checks all non Base-64 values for UTF-8 conformance. You cannot use this option with the -l option.
-v
-
Enables verbose mode. Displays progress and performance information during the load operation.
-x
-
Displays additional LDIF statistics about attributes, entries, and nodes after it completes the load operation.
-z string
-
Directs dirxmodify to process only those entries whose distinguished names contain the specified string.
-Z
-
Directs dirxmodify to add a specific LDAP control to all requests. This LDAP control directs the directory server to save the values of the operational attributes creatorsName, modifiersName, creationTimestamp and modificationTimestamp present in the LDIF file. If this option is not specified or the LDIF record does not contain the operational attribute the directory server generates values for this attribute.
-V
-
Displays the DirX Directory product version, in the format:
product_version build_id date time
For example:
DirX Directory V9.0 9.4.428 2023:03:23 20:10 64-Bit
Description
The dirxmodify command processes the contents of an LDIF content or change file and performs the modifications to the directory database over LDAPv3 protocol. This command is a stand-alone tool: it does not require a running DirX Directory installation in order to run (it requires only that the Mozilla LDAP libraries V6.0 or newer are installed) if you do not propagate the modifications to the server, for example if you have specified the -x, the -n, or the -O option. You can run the command locally or from a remote machine.
It is recommended to perform a backup of your database before you load the LDIF files.
The schema must correspond to the entries that are contained in the LDIF files. The LDIF files must either contain schema modifications at the beginning of the files or the administrator must modify the schema before loading the LDIF files. DirX Directory Manager for example provides easy and convenient to use features for schema management and schema synchronization.
By default, dirxmodify stops the load operation whenever it encounters errors. Use the -c option to allow dirxmodify to continue with the load operation when it encounters non-fatal errors.
If an error occurs that causes dirxmodify to exit, you must re-issue the dirxmodify command (the command has no automatic error recovery function). To continue after the error location, use the
-o or -t option.
By default, dirxmodify performs an anonymous bind to the LDAP server that is managing the DirX Directory database. Use the -D option and the -w or -W option to direct dirxmodify to perform a simple authenticated bind to the LDAP server using the distinguished name and password specified by the options. You must ensure that the specified user has the necessary permissions to perform the directory modifications.
By default, dirxmodify binds to the LDAP server defined by "localhost" that is listening on port 389. Use the -h and/or -p options to specify a different LDAP server host name or TCP/IP address and/or another LDAP port number.
By default, dirxmodify does not save the LDIF entries that it rejects during the load operation. Use the -e option to override this default. When you specify this option, dirxmodify saves each erroneous LDIF entry (in LDIF format) with a description of the error to the file you specify to the option. Consequently, you can use this file as input to dirxmodify after correcting the indicated errors.
Use the -l (lowercase "L") option to convert ISO-8859-1 (Latin-1) characters to UTF-8 characters. When using this option, you must ensure that Latin-1 characters in the file are not already represented by their 2-byte UTF-8 characters, because the hex codes will be converted twice and incorrect entries may be added to the database.
Use the -M option to exclude all records of an LDIF file containing specific strings from processing.
Use the -n option to check whether dirxmodify can successfully process the LDIF file. The command performs all of the operations but does not make any LDAP requests to perform the operations on the DirX Directory database. Consequently, any LDIF entries that contain errors normally detected by LDAP operations—for example, entries with object classes or attribute types that are not defined in the schema, or with superior DSEs that do not exist in the DIT—will not be detected. You can use the -n option with the -x option to generate statistical information for analysis.
Use the -I number (capital letter "i") option to set the reportimg interval to a specific number of records.
Use the -q option in conjunction with the -n option to perform a simple LDAP query on the LDIF file.
Use the -R option to delete the entries from the database instead of adding or modifying them.
Use the -r option to replace strings in attribute values during the load operation (attribute types are not affected). The command makes the string replacements to the read-in LDIF file before it propagates the modifications to the DirX Directory database. It does not modify the LDIF file itself. Similarly, you can use the -s option to replace attribute type names during the load operation (attribute values are not affected). Note that dirxmodify does not check the syntax of the new attribute type for consistency with the old type. The separator character that you use with the -r and -s options must not appear in the old or new values. You cannot use wildcards in old or new values.
Similarly to the -r and -s option, you can use the -U option to modify substrings in distinguished names. Non-naming attributes and values are not affected. Note that dirxmodify does not check the syntax, the schema consistency, or the consistency with the old type of the new naming attribute type or value. The separator character that you use with the -U must not appear in the old or new values. You cannot use wildcards in old or new values.
Use the -A option to add the specified attribute values to each object in the LDIF content file that contains attribute_type1 with attribute_value1. The command adds the attributes to the attribute list of all create operations before it propagates the modifications to the DirX Directory database. It does not modify the LDIF file itself. Adding an already existing attribute value results in an error. This option is prohibited for LDIF change files.
Use the -B option to replace all occurrencies of an specified attribute (type*:*value) in the LDIF content file with the specified new attribute type and value assertions (type1*:*vaue1**...*type_n:*value_n). The command adds only the new attribute types and values to the attribute list of all create operations before it propagates the modifications to the DirX Directory database. It does not modify the LDIF file itself and does not create the old attribute in the DirX Directory database. This option is prohibited for LDIF change files.
Use the -i option to ignore up to 16 attributes during the load operation.
Use the -G option to handle attribute assertions with empty values as an error. This avoids adding attribute types without values.
By default, dirxmodify reads an LDIF file starting at byte offset zero (the first LDIF entry). Use the -o option to specify an LDIF entry number at which dirxmodify is to begin reading the file. Use the -t option to specify the offset in bytes into the LDIF file at which dirxmodify is to begin reading the file. The -t option is useful if you have used CTRL/C to stop dirxmodify, and you want to resume processing at the location in the file at which you stopped dirxmodify. If you also both the -t and the -o options, the LDIF entry offset is relative to the byte offset (dirxmodify calculates the entry offset specified in the -o option starting from the byte offset specified in the -t option).
Use the -P and -S options to direct dirxmodify to automatically split huge records that cannot be processed otherwise. This is useful for example when processing group attributes containing a huge number of members. When splitting a record the LDAP server propagates an add operation to the server followed by several modify operations. If one of the operations fails the database is rolled back to the status before sending the first operation. Auto-splitting of records can only be performed for LDIF content files and only for adding new objects or adding new attribute values to existing attributes.
Use the -O option to process the LDIF file records and write the possibly modified records into a new LDIF file instead of propagating the operations to the server. The maximum size of an LDIF file that dirxmodify can process for this option is 2 GB. If the LDIF file is greater than 2 GB the behaviour of dirxmodify is undefined.
Use the -E option to enable authenticated, encrypted LDAP communication over SSL/TLS. Specify the name of the certificate database in the -C option, and the LDAP secured port number of the LDAP server in the -p option. Usually the LDAP secured port number is 636. Running dirxmodify in SSL mode may reduce performance.
By default, dirxmodify reports only errors that occur during the load operation. Use the -v option to direct dirxmodify to write statistical information about the load operation to standard output.
Before you process a large LDIF file, we recommend that you run dirxmodify with the -n option and the -e option to scan the LDIF file for errors and write any erroneous LDIF entries to an error file for examination and correction. Using this method allows you to detect systematic errors in an LDIF file and prevents you from having a partially loaded database that contains possibly unwanted data.
Examples
-
The following sample command loads an LDIF file starting at the 500th LDIF entry.
dirxmodify –o 500 -f mycompany.ldif
-
The following sample command returns the number of common names present in an LDIF file:
dirxmodify -n -q (cn=*) -f mycompany.ldif
-
The following sample command adds all entries in the LDIF content file mycompany.ldif. In the event that errors occur they are ignored and processing continues. The attributes telephone number (tn) and description (dsc) are ignored during the load operation.
dirxmodify -D cn=admin,o=My-Company –w dirx –a –c –i tn –i dsc -f mycompany.ldif -
The following sample command loads the LDIF file mycompany.ldif and ignores all records containing the strings dn: cn=ldapRoot, o=pqr and objectClass: x500subSchema.
dirxmodify –M "dn: cn=ldapRoot, o=pqr" –M "objectClass: x500subSchema" -f mycompany.ldif -
The following sample command adds the objectclass values OrgPerson, person, and top to all entries in the LDIF content file mycompany.ldif. It adds the attribute value assertion \{objectclass=OrgPerson;person;top} to all create operations before propagating them to the server.
dirxmodify -D cn=admin,o=My-Company –w dirx –A objectclass:OrgPerson+objectclass:person+objectclass:top -f mycompany.ldif