LDAP Directory Synchronizer
Online Documentation

HOME NEXT PREVIOUS

Setting up LDSU_CONFIG.DAT

The LDSU Configuration file (by default, named ldsu_config.dat) is the configuration file for each LDSU synch instance. LDSU can run in four modes: Import, Transaction, Export, Changes. Each mode has a different set of configuration parameters. In addition, Export and Changes modes have two types of operations explained below.

This section first contains a list of the syntax rules for ldsu_config.dat files following by a list of the parameters for each of the LDSU modes with brief explanations for each parameter.

There is also a table containing all LDSU_CONFIG.DAT parameters in alphabetical order with more detailed explanations.


LDSU_CONFIG.DAT Syntax Rules


LDSU_CONFIG.DAT IMPORT Parameters

The following table lists the parameters used in IMPORT mode. This mode compares an input file against an LDAP directory and updates the LDAP directory as needed using Add, Modify, and Delete transactions.

ParameterDefaultShort Explanation
synch_type REQUIRED LDSU Mode. Must be IMPORT.
synch_label LDSU Label for log files. Suggested value: subdirectory name.
layout_file ldsu_layout.dat in parent directory File containing LDAP Directory RDN and Attributes Definitions
bind_server REQUIRED Host name of LDAP Directory Server
bind_port 389 TCP port number for LDAP Directory Server
bind_name   DN to bind to the LDAP Directory with if not using an Anonymous bind.
bind_password   Password to bind to the LDAP Directory with if not using an Anonymous bind.
input_rdf REQUIRED Name of input rdf file. Suggested value: import.rdf or LDIF
input_file REQUIRED Name of directory input file. Suggested value: import.txt
input_lines_per_record 1 #lines in input_file per entry
input_field_separator "<TAB>","" Primary and Secondary input_file field separator optionally used by input_rdf
input_num_header_lines 0 Number of lines in the input_file to skip at the head of the file.
input_metafile   Temporary file. Only specify if this needs to be on a different disk.
output_metafile   Temporary file. Only specify if this needs to be on a different disk.
log_file ldsu_log.log Name of transaction log file. Suggested value: import.log
verbose N Set to Y to get extra diagnostic output.
max_transactions   LDSU transaction limit between running max_trans_file and re-binding.
max_trans_file   Procedure to run every max_transactions.
max_fail_transactions   #failed LDAP add, modify, or delete transactions allowed before LDSU exits.
max_add_transactions   Cause LDSU to exit if this many LDAP add transactions would occur.
max_delete_transactions   Cause LDSU to exit if this many LDAP delete transactions would occur.
dn_sequence RDN order from ldsu_layout.dat Set to comma separated list of RDN's to override layout file sequence.
create_root   Set to RDN in dn_sequence where LDSU can create parent entries up to.
search_context RECOMMENDED DN search base for extracting existing LDAP records
synch_object REQUIRED Comma separated list of objectclass attribute values for Add entries.
synch_id_field   LDAP attribute to hold synch_id_value
synch_id_value LDSU Value to place in synch_id_field attribute for every Add entry
gid_field REQUIRED LDAP attribute to hold Group ID (gid_value)
gid_value REQUIRED Value to place in gid_field attribute for every Add entry
unique_search_context   DN search base for performing unique searches. Usually same as search_context.
unique_fields   List of attributes (or sets of attributes) that must be unique.
make_unique_field   Attribute which is made unique if not unique
make_unique_field_len   Length of make_unique_field. Default is length in layout file.
make_unique_truncate   Set to NUMBER or leave blank
make_unique_separator   Separator between original field value and suffix string to make unique.
make_unique_program   User-defined procedure to run to produce unique values
make_unique_params   Fields to pass to make_unique_program as parameters.
gen_profs_alias_fields   Fields used to generate a unique ID
gen_snads_alias_fields   Fields used to generate a unique ID
recognize_case_changes Y Set to N to treat case changes in the input file as not being changed.
add_only_fields   Comma separated list of attributes which are only added and never modified.
mark_for_delete_field   Attribute to modify instead of deleting a record if no longer in the input_file.
mark_for_delete_value   Value to place in the mark_for_delete_field when marking a record for delete
big_search_field   Attribute to search on when LDAP directory extract needs to be segmented.
big_search_type   Type of data in big_search_field: A, AN, N, IA5, PRINT (with optional $)
read_only_test N Set to Y to NOT update LDAP directory (run in test mode).


LDSU_CONFIG.DAT TRANSACTION Parameters

The following table lists the parameters used in TRANSACTION mode. This mode applies transactions contained in the ADD, MODIFY, and/or DELETE input files against an LDAP directory. One, two, or all three of the input files may be specified.

ParameterDefaultShort Explanation
synch_type REQUIRED LDSU Mode. Must be TRANSACTION.
synch_label LDSU Label for log files. Suggested value: subdirectory name.
layout_file ldsu_layout.dat in parent directory File containing LDAP Directory RDN and Attributes Definitions
bind_server REQUIRED Host name of LDAP Directory Server
bind_port 389 TCP port number for LDAP Directory Server
bind_name   DN to bind to the LDAP Directory with if not using an Anonymous bind.
bind_password   Password to bind to the LDAP Directory with if not using an Anonymous bind.
input_rdf REQUIRED if next 3 rdf files not specified Name of rdf file for all input files. Suggested value: import.rdf or LDIF
input_add_rdf REQUIRED if input_add_file and not input_rdf specified Name of rdf file for input_add_file. Suggested value: import_add.rdf
input_mod_rdf REQUIRED if input_mod_file and not input_rdf specified Name of rdf file for input_mod_file. Suggested value: import_mod.rdf
input_del_rdf REQUIRED if input_del_file and not input_rdf specified Name of rdf file for input_del_file. Suggested value: import_del.rdf
input_file   Name of directory input file if input_rdf=LDIF. Suggested value: import.txt
input_add_file   Name of directory input add file. Suggested value: import_add.txt
input_mod_file   Name of directory input modify file. Suggested value: import_mod.txt
input_del_file   Name of directory input delete file. Suggested value: import_del.txt
input_lines_per_record 1 Used if input_rdf specified. #lines per entry in all input files
input_add_lines_per_record 1 Used if input_add_rdf specified. #lines per entry in input_add_file
input_mod_lines_per_record 1 Used if input_mod_rdf specified. #lines per entry in input_mod_file
input_del_lines_per_record 1 Used if input_del_rdf specified. #lines per entry in input_del_file
input_field_separator "<TAB>","" Primary and Secondary input file field separator optionally used by input rdf files.
input_num_header_lines 0 Number of lines in an input file to skip at the head of the file.
input_metafile   Temporary file. Only specify if this needs to be on a different disk.
log_file ldsu_log.log Name of transaction log file. Suggested value: import.log
mod_or_add_flag N Set to Y to treat input_mod_file as a "Modify or Add" Input File
mod_hidden_flag N Set to Y to force input_mod_file records to be modified even if they cannot be read
verbose N Set to Y to get extra diagnostic output.
max_transactions   LDSU transaction limit between running max_trans_file and re-binding.
max_trans_file   Procedure to run every max_transactions.
max_fail_transactions   #failed LDAP add, modify, or delete transactions allowed before LDSU exits.
dn_sequence RDN order from ldsu_layout.dat Set to comma separated list of RDN's to override layout file sequence. Not used for MOD and DEL files if key_fields specified
create_root   Set to RDN in dn_sequence where LDSU can create parent entries up to.
search_context RECOMMENDED if key_fields defined Used for search base if key_fields specified for MOD and DEL files
key_fields   Optional comma separated list of attributes used to identify records in MOD and DEL files instead of dn_sequence
synch_object REQUIRED if input_add_file specified. Comma separated list of objectclass attribute values for Add entries.
synch_id_field   LDAP attribute to hold synch_id_value
synch_id_value LDSU Value to place in synch_id_field attribute for every Add entry
gid_field   LDAP attribute to hold Group ID (gid_value)
gid_value   Value to place in gid_field attribute for every Add entry
unique_search_context   DN search base for performing unique searches.
unique_fields   List of attributes (or sets of attributes) that must be unique.
make_unique_field   Attribute which is made unique if not unique
make_unique_field_len   Length of make_unique_field. Default is length in layout file.
make_unique_truncate   Set to NUMBER or leave blank
make_unique_separator   Separator between original field value and suffix string to make unique.
make_unique_program   User-defined procedure to run to produce unique values
make_unique_params   Fields to pass to make_unique_program as parameters.
gen_profs_alias_fields   Fields used to generate a unique ID
gen_snads_alias_fields   Fields used to generate a unique ID
recognize_case_changes Y Set to N to treat case changes in the input mod file as not being changed.
read_only_test N Set to Y to NOT update LDAP directory (run in test mode).


LDSU_CONFIG.DAT EXPORT Parameters

The following table lists the parameters used in basic EXPORT mode. This mode extracts records from an LDAP directory, based on a search base and search filters, and writes the records to a formatted output file.

ParameterDefaultShort Explanation
synch_type REQUIRED LDSU Mode. Must be EXPORT.
synch_label LDSU Label for log files. Suggested value: subdirectory name.
layout_file ldsu_layout.dat in parent directory File containing LDAP Directory RDN and Attributes Definitions
bind_server REQUIRED Host name of LDAP Directory Server
bind_port 389 TCP port number for LDAP Directory Server
bind_name   DN to bind to the LDAP Directory with if not using an Anonymous bind.
bind_password   Password to bind to the LDAP Directory with if not using an Anonymous bind.
output_rdf REQUIRED Name of output rdf file. Suggested value: export.rdf or LDIF
output_file REQUIRED Name of directory output file. Suggested value: export.txt
output_lines_per_record 1 #lines in output_file per entry
output_header_file   Name of optional file containing lines to prefix output records in output_file
output_field_separator "<TAB>" Output_file field separator optionally used by output_rdf
output_metafile   Temporary file. Only specify if this needs to be on a different disk.
verbose N Set to Y to get extra diagnostic output.
search_context RECOMMENDED DN search base for extracting LDAP records
synch_id_field   LDAP attribute which holds synch_id_value. Used as an export filter
synch_id_value LDSU Value to use with synch_id_field attribute export filter
gid_field REQUIRED LDAP attribute which holds Group ID (gid_value). Used as an export filter
gid_value REQUIRED Value of one or more Group ID's to extract. Or * for all or if using gid_exclude
gid_exclude   If gid_value is *, value of one or more Group ID's NOT to extract.
get_field   LDAP attribute to hold get_value. Used as an export filter.
get_value * Value to use with get_field attribute export filter.
custom_filter   Use to specify an additional filter in LDAP filter syntax
big_search_field   Attribute to search on when LDAP directory extract needs to be segmented.
big_search_type   Type of data in big_search_field: A, AN, N, IA5, PRINT (with optional $)


LDSU_CONFIG.DAT EXPORT1 Parameters

The following table lists the parameters used in EXPORT1 mode. This mode extracts records from an LDAP directory, which are identified in an input file, and writes the records to a formatted output file.

ParameterDefaultShort Explanation
synch_type REQUIRED LDSU Mode. Must be EXPORT.
synch_label LDSU Label for log files. Suggested value: subdirectory name.
layout_file ldsu_layout.dat in parent directory File containing LDAP Directory RDN and Attributes Definitions
bind_server REQUIRED Host name of LDAP Directory Server
bind_port 389 TCP port number for LDAP Directory Server
bind_name   DN to bind to the LDAP Directory with if not using an Anonymous bind.
bind_password   Password to bind to the LDAP Directory with if not using an Anonymous bind.
output_rdf REQUIRED Name of output rdf file. Suggested value: export_output.rdf or LDIF
output_file REQUIRED Name of directory output file. Suggested value: export_output.txt
output_lines_per_record 1 #lines in output_file per entry
output_header_file   Name of optional file containing lines to prefix output records in output_file
output_field_separator "<TAB>" Output_file field separator optionally used by output_rdf
output_metafile   Temporary file. Only specify if this needs to be on a different disk.
input_rdf REQUIRED Name of input rdf file. Suggested value: export_input.rdf
input_file REQUIRED Name of directory input file identifying records to export. Suggested value: export_input.txt
input_lines_per_record 1 #lines in input_file per entry
input_field_separator "<TAB>","" Primary and Secondary input_file field separator optionally used by input_rdf
input_num_header_lines 0 Number of lines in the input_file to skip at the head of the file.
verbose N Set to Y to get extra diagnostic output.
search_context RECOMMENDED DN search base for extracting LDAP directory records
gid_field REQUIRED LDAP attribute which holds Group ID (gid_value)
gid_value REQUIRED Group ID value
dn_sequence RDN order from ldsu_layout.dat Set to comma separated list of RDN's to override layout file sequence. Not used if key_fields specified
key_fields   Optional comma separated list of attributes used to identify records instead of dn_sequence


LDSU_CONFIG.DAT CHANGES Parameters

The following table lists the parameters used in basic CHANGES mode. This mode compares an extract of records from an LDAP directory, based on a search base and search filters, with a previous extract and writes the changes to formatted ADD, DELETE, and (optional) MODIFY output files.

ParameterDefaultShort Explanation
synch_type REQUIRED LDSU Mode. Must be CHANGES.
synch_label LDSU Label for log files. Suggested value: subdirectory name.
layout_file ldsu_layout.dat in parent directory File containing LDAP Directory RDN and Attributes Definitions
bind_server REQUIRED Host name of LDAP Directory Server
bind_port 389 TCP port number for LDAP Directory Server
bind_name   DN to bind to the LDAP Directory with if not using an Anonymous bind.
bind_password   Password to bind to the LDAP Directory with if not using an Anonymous bind.
output_rdf REQUIRED if next 3 rdf files not specified Name of rdf file for all output files. Suggested value: export.rdf or LDIF
output_add_rdf REQUIRED if output_rdf not specified Name of rdf file for output_add_file. Suggested value: export_add.rdf
output_mod_rdf REQUIRED if output_rdf not specified Name of rdf file for output_mod_file. Suggested value: export_mod.rdf
output_del_rdf REQUIRED if output_rdf not specified Name of rdf file for output_del_file. Suggested value: export_del.rdf
output_file REQUIRED if next 3 files not specified Name of export file to contain all changes. Suggested value: export.txt
output_add_file REQUIRED if output_file not specified Name of add changes export file. Suggested value: export_add.txt
output_mod_file OPTIONAL Name of modify changes export file. Changed records written to delete and add file if not specified. Suggested value: export_mod.txt
output_del_file REQUIRED if output_file not specified Name of delete changes export file. Suggested value: export_del.txt
output_lines_per_record 1 Used if output_rdf specified. #lines per entry in all output files
output_add_lines_per_record 1 Used if output_add_rdf specified. #lines per entry in all output_add_file
output_mod_lines_per_record 1 Used if output_mod_rdf specified. #lines per entry in all output_mod_file
output_del_lines_per_record 1 Used if output_del_rdf specified. #lines per entry in all output_del_file
output_header_file   Name of optional file containing lines to prefix output records in output files
output_field_separator "<TAB>" Output_file field separator optionally used by output rdf file(s)
output_metafile REQUIRED Current extract of records to compare. Copy this file to input_metafile for next run if changes applied successfully. Suggested value: export.new
input_metafile REQUIRED Previous extract of records to compare. Copied from output_metafile for previous run. Suggested value: export.old
log_file ldsu_log.log Log of what changed in the LDAP directory to cause add, modify, and delete records to be exported. Suggested value: export.log
verbose N Set to Y to get extra diagnostic output.
search_context RECOMMENDED DN search base for extracting LDAP directory records
synch_id_field   LDAP attribute which holds synch_id_value. Used as an export filter
synch_id_value LDSU Value to use with synch_id_field attribute export filter
gid_field REQUIRED LDAP attribute which holds Group ID (gid_value). Used as an export filter
gid_value REQUIRED Value of one or more Group ID's to extract. Or * for all or if using gid_exclude
gid_exclude   If gid_value is *, value of one or more Group ID's NOT to extract.
get_field   LDAP attribute to hold get_value. Used as an export filter.
get_value * Value to use with get_field attribute export filter.
custom_filter   Use to specify an additional filter in LDAP filter syntax
big_search_field   Attribute to search on when LDAP directory extract needs to be segmented.
big_search_type   Type of data in big_search_field: A, AN, N, IA5, PRINT (with optional $)
recognize_case_changes Y Set to N to cause case changes not to write a change to the output mod file


LDSU_CONFIG.DAT CHANGES1 Parameters

The following table lists the parameters used in CHANGES1 mode. This mode compares an extract of records from an LDAP directory, based on a search base and search filters, with an input file containing a full export from a foreign directory and writes the changes to formatted ADD, DELETE, and (optional) MODIFY output files to be applied against the foreign directory.

ParameterDefaultShort Explanation
synch_type REQUIRED LDSU Mode. Must be CHANGES.
synch_label LDSU Label for log files. Suggested value: subdirectory name.
layout_file ldsu_layout.dat in parent directory File containing LDAP Directory RDN and Attributes Definitions
bind_server REQUIRED Host name of LDAP Directory Server
bind_port 389 TCP port number for LDAP Directory Server
bind_name   DN to bind to the LDAP Directory with if not using an Anonymous bind.
bind_password   Password to bind to the LDAP Directory with if not using an Anonymous bind.
output_rdf REQUIRED if next 3 rdf files not specified Name of rdf file for all output files. Suggested value: export.rdf or LDIF
output_add_rdf REQUIRED if output_rdf not specified Name of rdf file for output_add_file. Suggested value: export_add.rdf
output_mod_rdf REQUIRED if output_rdf not specified Name of rdf file for output_mod_file. Suggested value: export_mod.rdf
output_del_rdf REQUIRED if output_rdf not specified Name of rdf file for output_del_file. Suggested value: export_del.rdf
output_file REQUIRED if next 3 files not specified Name of export file to contain all changes. Suggested value: export.txt
output_add_file REQUIRED if output_file not specified Name of add changes export file. Suggested value: export_add.txt
output_mod_file OPTIONAL Name of modify changes export file. Changed records written to delete and add file if not specified. Suggested value: export_mod.txt
output_del_file REQUIRED if output_file not specified Name of delete changes export file. Suggested value: export_del.txt
output_lines_per_record 1 Used if output_rdf specified. #lines per entry in all output files
output_add_lines_per_record 1 Used if output_add_rdf specified. #lines per entry in all output_add_file
output_mod_lines_per_record 1 Used if output_mod_rdf specified. #lines per entry in all output_mod_file
output_del_lines_per_record 1 Used if output_del_rdf specified. #lines per entry in all output_del_file
output_header_file   Name of optional file containing lines to prefix output records in output files
output_field_separator "<TAB>" Output_file field separator optionally used by output rdf file(s)
output_metafile   Temporary file. Only specify if this needs to be on a different disk.
input_rdf REQUIRED Name of input rdf file. Suggested value: export_input.rdf
input_file REQUIRED Name of input file to compare with LDAP directory to generate changes. Suggested value: export_input.txt
input_lines_per_record 1 #lines in input_file per entry
input_field_separator "<TAB>","" Primary and Secondary input_file field separator optionally used by input_rdf
input_num_header_lines 0 Number of lines in the input_file to skip at the head of the file.
input_metafile   Temporary file. Only specify if this needs to be on a different disk.
log_file ldsu_log.log Log of what changed in the LDAP directory to cause add, modify, and delete records to be exported. Suggested value: export.log
verbose N Set to Y to get extra diagnostic output.
dn_sequence RDN order from ldsu_layout.dat For input_file. Set to comma separated list of RDN's to override layout file sequence. Not used if key_fields specified
key_fields   For input_file. Optional comma separated list of attributes used to identify records instead of dn_sequence
search_context RECOMMENDED DN search base for extracting LDAP directory records
synch_id_field   LDAP attribute which holds synch_id_value. Used as an export filter
synch_id_value LDSU Value to use with synch_id_field attribute export filter
gid_field REQUIRED LDAP attribute which holds Group ID (gid_value). Used as an export filter
gid_value REQUIRED Value of one or more Group ID's to extract. Or * for all or if using gid_exclude
gid_exclude   If gid_value is *, value of one or more Group ID's NOT to extract.
get_field   LDAP attribute to hold get_value. Used as an export filter.
get_value * Value to use with get_field attribute export filter.
custom_filter   Use to specify an additional filter in LDAP filter syntax
big_search_field   Attribute to search on when LDAP directory extract needs to be segmented.
big_search_type   Type of data in big_search_field: A, AN, N, IA5, PRINT (with optional $)
recognize_case_changes Y Set to N to cause case changes not to write a change to the output mod file


All LDSU_CONFIG.DAT Parameters

The following list contains a detailed explanation of all ldsu_config.dat parameters used for all modes in alphabetical order.

add_only_fields
Optional parameter in Import Mode. Lists the field(s) to be entered in the LDAP directory only during the initial ADD of the record. This allows LDSU to provide an initial value for a field but it no longer "owns" (or updates) the field value on subsequent imports. Therefore, if the value of the field is changed by another Agent, LDSU would not set it back to its initial value during the next IMPORT. If more than one add_only_field, separate field names with a comma. An example use for this would be the userPassword field in X.500 which can be set to some default value when the record is created, but will never again be updated by LDSU, rather it is "owned" by the user through a web client or other agent..
big_search_field
Optional parameter for Import, Export, and Changes Mode. For large extracts of an LDAP Directory, LDSU (and the LDAP directory) may require a large amount of resources if too many records need to be extracted at once which slows down the extract (or worse). Use of big_search_field and big_search_type allow the extract to be divided up into multiple segments. To use this option, set big_search_field to an LDAP attribute that must have a value in EVERY entry to be extracted and set big_search_type to the type of data contained in the big_search_field (see big_search_type). The goal is to reduce the maximum number of records extracted in any one search.
big_search_type
Optional parameter for Import, Export, and Changes Mode. Required if using big_search_field. The value for big_search_type is a string which describes the range of data in the big_search_field. Valid values are:
AAlphabetic (A-Z)
ANAlphaNumneric (A-Z, 0-9)
NNumeric (0-9)
IA5IA5 Syntax (e.g. rfc822Mailbox)
PRINTPrintable String Syntax

If big_search_type is A, the single extract of big_search_field=* is replaced by 26 extracts of big_search_field=a*, big_search_field=b*, etc. (Note: LDAP filters are case insensitive). The big_search_type can also end with an optional dollar sign ($) which can be used if the distribution of values for the big_search_field is more evenly distributed by the last character instead of the first character. For example, if big_search_field is a numeric badge number where more than half start with a 1, but the last character is evenly distributed between 0-9, then big_search_type should be set to "N$" instead of "N". This will create 10 extracts of big_search_field=*0, big_search_field=*1, etc.

bind_name
Optional for all modes. Set to the Distinguished Name (DN) of the entry that is binding to the directory (using simple authentication). If this parameter is not specified, then an unauthenticated (or anonymous) bind is performed. Many directories may allow anonymous read access (for Export or Changes mode), but this parameter is usually required for write access (for Import and Transaction mode). In addition, some attributes may not be accessible even in read mode when doing an anonymous bind.
bind_password
Optional for all modes. Set to the Password string associated with the bind_name DN for an authenticated bind. The password value will not be output in any logs and will only appear in plain text in the ldsu_config.dat file.
bind_port
Optional for all modes. This parameter specifies the TCP port of the bind_server for the LDAP directory. The standard LDAP port of 389 is the default but can be overridden by specifying a alternate port number.
bind_server
Required for all modes. This parameter specifies the name or IP address of the of TCP/IP host where the LDAP server for the LDAP directory resides.
create_root
Optional for Import and Transaction modes. By default, when creating entries in an LDAP directory, all parent entries must already exist. For instance if creating the entry "cn=megan, ou=daddy, o=home, c=us", the parent entry "ou=daddy, o=home, c=us" must already exist or the add will fail. By specifying an RDN level for create_root, LDSU will create any parent entries (up to the create_root level) before creating the target entry. In this example, setting create_root=ou would create the ou=daddy entry if it did not exist. The "o=home, c=us" would have to be there, however. When creating a parent entry, LDSU creates the entry with only one attribute, objectclass, set. The value for the objectclass is taken from the "rdn parent object class" field in ldsu_layout.dat for the RDN. When using multiple levels of a single RDN type (e.g. ou=town, ou=county, ou=state, ou=region), specify ou, ou_2, ou_3, ou_4 for the root level. This parameter is designed for deep naming contexts. For flat naming contexts or where parent entries need additional attributes, parent entries should be created by the directory before running LDSU.
custom_filter
Optional for Export and Changes modes. If use of gid_field, synch_id_field, get_field, and big_search do not provide an adequate way to specify the search filter needed to extract data out of an LDAP directory, use the custom_filter parameter to specify any additional filter in LDAP Filter format (RFC 1960). This filter is "anded" with the gid_field and any other defined filters. Examples of LDAP Filters are:
  • surname equals smith: surname=smith
  • surname equals smith or jones: |(surname=smith)(surname=jones)
  • surname equals smith and givenname equals john: &(surname=smith)(givenname=john)
  • surname does not equal smith: "!(surname=smith)"
Double quotes must be used for the value if the filter contains an exclamation point (!) character (which means NOT EQUAL).
dn_sequence
Used in Import, Transaction, Export1, and Changes1 Mode if the key_fields parameter is not specified. The Distinquished Name (DN) is the object which identifies a record in an LDAP directory. It consists of one or more parts called Relative Distinguished Names (RDNs). Unless using another unique key field to identify a record, each input file record must produce the DN for that record. In order to produce the DN, the sequence of RDN's which produce the DN must be known. By default, LDSU uses the RDN's (in order) from the ldsu_layout.dat file. To override this, specify the RDN's (separated by a comma) for the dn_sequence parameter. If an RDN repeats itself in the sequence, use the _N suffix starting with the second RDN. Also, different DN's are supported by not populating some RDN's in the RDF file. If an RDN is missing it won't be part of the DN. Note, however, that all entries (except any parent entries - see create_root) must have the same objectclass (synch_object). The dn_sequence parameter also needs to be supplied if using multi-part RDN's. Examples of specifying a dn_sequence:
  • cn, ou, L, ou_2, ou_3, ou_4, o, c
  • cn + serial, ou, o, c
  • cn, cn_2, ou, o
gen_profs_alias_fields
Used in Import and Transaction Mode. This optional parameter allows for the generation of a unique field. The values of this parameter contain the names of 4 attributes separated by a comma. They are, in order, the UID, LOC, GIVN, and SURN. The UID is the field which is made unique for LOC in unique_search_context. Its value is generated from values in the GIVN and SURN fields. The values for the LOC, GIVN, and SURN attributes should be assigned in the input RDF file. The value for UID is generated using the following algorithm:
  1. Determine max length of UID from ldsu_layout.dat and set to N
  2. Set UID to up to first N-1 characters of SURN + first character of GIVN
  3. If UID is unique for LOC in unique_search_context, then done
  4. Set UID to up to first N-2 characters of SURN + first 2 characters of GIVN
  5. If UID is unique for LOC in unique_search_context, then done
  6. Set UID to first character of GIVN + first character of SURN + random #
  7. If UID is unique for LOC in unique_search_context, then done
  8. Repeat Step 6 until unqiue value found
Example values for this parameter would be emailPRUSERNAME, emailPRLOCATION, givenName, surname.
gen_snads_alias_fields
Used in Import and Transaction Mode. Contains the same functionality of gen_profs_alias_fields. Either one or both may be used to produce a unique_field.
get_field
Optional for Export and Changes modes. To create another simple filter get_field and get_value may used to narrow the entries being exported from the LDAP directory. The get_field parameter contains the name of the attribute to include in the filter. If specified, this filter would be "anded" with any other filters that are specified (see gid_field, synch_id_field, custom_filter, big_search).
get_value
Optional for Export and Changes modes. Required if get_field defined. The get_value parameter contains the value to search on. The value may be a single asterisk (*) to denote presence or contain asterisks as wilcards to denote a substring filter type (e.g. m*e*g*a*n) For more advanced filters (e.g. approximate, greater than or equal, less than or equal, or not present) use the custom_filter parameter.
gid_exclude
Optional for Export and Changes modes if gid_value is set to a single asterisk (*). If used, this field contains the Group ID(s) NOT to extract from the LDAP Directory. Separate multiple values by a comma.
gid_field
Required for all modes except Transaction Mode. This parameter specifies the "Group ID" attribute in the LDAP directory for LDSU. In Import Mode (or Transaction Mode if specified), every entry added will have gid_field set to gid_value to mark the field as part of that Import Group. After the initial load in Import Mode, the Group ID (gid_field=gid_value) is used as a filter to determine which existing entries in the LDAP directory to compare against the new import input file. In Transaction Mode, the Group ID is optional but recommended because LDSU will make sure the specified Group ID matches an existing record before it will modify or delete an entry in the LDAP Directory. In Export and Changes Mode, the Group ID is used as a filter to specify which Group(s) to extract out of the LDAP directory. Note: If exporting from an existing LDAP directory that LDSU didn't populate and doesn't have Group ID's, use surname or some other attribute that is contained in all entries to be exported as the gid_field and asterisk(*) as the gid_value.
gid_value
Required for all modes if gid_field specified. This parameter specifies the "Group ID" value for the gid_field which is written to all entries when added to the LDAP directory. In Import and Transaction Mode, it is recommended that the value be set to something that identifies the source (or "owner") of the data. In Export and Changes Mode, one or more gid_value(s) to extract may be specified (separated by a comma) or a single asterisk may be specified to denote all groups. In addition, if a single asterisk is specifed, Group ID's may be excluded by specifying one or more value(s) for the gid_exclude field. Except for a single asterisk in Export or Changes Mode, this value may not contain any asterisks since this is the wild card character. (Unless the value of the field contains an asterisk. This is not recommended but may be implemented by preceding the asterisk with a backslash(\). )
input_add_file
Used in Transaction Mode. Optional input file containing ADD records to be applied against the LDAP directory. Suggested name, if used, is import_add.txt.
input_add_lines_per_record
Used in Transaction mode if import_add_rdf is specified. Specify the number of lines in the input_add_file per record in the LDAP directory. Default value is 1.
input_add_rdf
Used in Transaction Mode to describe the input_add_file unless input_rdf is used to describe all input files. This specifies the name of the rdf file. The suggested value for this field, if used, is input_add.rdf. If LDIF formatted input, set input_rdf=LDIF and leave this blank.
input_del_file
Used in Transaction Mode. Optional input file containing DELETE records to be applied against the LDAP directory. Suggested name, if used, is import_del.txt.
input_del_lines_per_record
Used in Transaction mode if import_del_rdf is specified. Specify the number of lines in the input file per record in the LDAP directory. Default value is 1.
input_del_rdf
Used in Transaction Mode to describe the input_del_file unless input_rdf is used to describe all input files. This specifies the name of the rdf file. The suggested value for this field, if used, is input_del.rdf. If LDIF formatted input, set input_rdf=LDIF and leave this blank.
input_field_separator
Used in all modes if an input file is specified. This parameter defines a one or two strings to use as the primary and secondary input field separators when using the N-N or N-N-N syntax in input rdf files. By default, the primary field separator is a single tab character and the secondary field separator is not defined. To define different separator string(s), define the value(s) enclosed in double quotes. Separate the two values by a comma if needed. (e.g. input_field_separator = ",","%" would define the primary separator as a comma and the secondary separator as a percent sign. Ignored if input_rdf=LDIF.
input_file
Required in Import Mode or if using Export1 or Changes1 mode. Also required in Transaction Mode if input_rdf=LDIF. Contains the name of the file containing input records as described by the input_rdf file. The suggested value for this field is import.txt for Import mode and export_input.txt for Export1 or Changes1 mode.
input_lines_per_record
Used in all modes when import_rdf is specified. Specify the number of lines in the input file per record in the LDAP directory. Default value is 1. Ignored if input_rdf=LDIF.
input_metafile
Required parameter for basic Changes Mode. Optional parameter for Import, Transaction, and Changes1 Mode. When creating records from an input file, they are placed in a temporary file (metafile) for comparison with records in the LDAP directory (if needed) before written to the LDAP directory (if import or transaction). In basic Changes Mode, this file is a copy of the output_metafile from the previous run and must be specified (suggested name is export.old). In other modes, this parameter defaults to a temporary filename in the default directory and is deleted when LDSU exits. For these modes, only specify a parameter containing a full file specification if you want the metafile to reside in a different directory due to space or efficiency reasons.
input_mod_file
Used in Transaction Mode. Optional input file containing MODIFY records to be applied against the LDAP directory. Suggested name, if used, is import_mod.txt.
input_mod_lines_per_record
Used in Transaction mode if import_mod_rdf is specified. Specify the number of lines in the input file per record in the LDAP directory. Default value is 1.
input_mod_rdf
Used in Transaction Mode to describe the input_mod_file unless input_rdf is used to describe all input files. This specifies the name of the rdf file. The suggested value for this field, if used, is input_mod.rdf. If LDIF formatted input, set input_rdf=LDIF and leave this blank.
input_num_header_lines
Used in all modes whenever an input file is used. Contains the number of lines in any input file to skip before processing data. The default is 0 - no header lines. Note: this parameter has no relationship to the input*lines_per_record parameters.
input_rdf
Required in Import mode and if using Export1 or Changes1 mode to describe the input_file. Needed in Transaction Mode if input_add_rdf, input_del_rdf, and input_mod_rdf are not specified. The suggested value for this field is import.rdf for Import and Transaction mode and export_input.rdf for Export or Changes mode. If using an LDIF formatted input file in Import ,Transaction, or Changes1 mode, set input_rdf=LDIF.
key_fields
Optional parameter for Transaction Mode (if no input_add_file specified) and Export1 and Changes1 Mode. If the input file cannot produce the DN (see dn_sequence) of the record to be modified or exported, the key_fields parameter can be specified to uniquely identify a record in the search_context. For example if an LDAP record is updated from two sources:
  1. an Import instance which creates records with a DN using the Common Name as an RDN and has a unique badge# for each entry;
  2. a Transaction Modify instance which has a unique badge number but not the exact Common Name the import has.
In the Transaction ldsu_config.dat file, specify the badge number attribute as a key_field, and LDSU will access the field using the badge number in search filter instead of using the DN. A combination of fields can also be supplied. If, for example, the badge number is only unique for a given department, then specify both the department and badge number fields as key fields. Separate multiple fields with a comma when specifying the key_fields parameter.
layout_file
Used for all modes. Name of the LDSU layout file which describes the RDN's and Attributes for the LDAP directory used for the Import or Export. The default value is ldsu_layout.dat in the parent directory above the default directory (usually the LDSU root directory). See the Setting up Directory Layout File section.
log_file
Used for Import, Transaction, and Changes Mode. Name of a file to record transaction logs of changes made to the LDAP Directory (for Import and Transaction modes) or a log of what differences in the LDAP Directory caused changes (for Changes Mode). Default value is ldsu_log.log, but the recommended name is import.log for Import and Transaction mode and export.log for Changes mode. If using LDSU scripts, this file is also copied to the LDSU logs subdirectory.
make_unique_field
Optional parameter for Import and Transaction Mode. If desired, specify an attribute that must be unique in unique_search_context, and if it is not unique it is made unique in one of two ways. If make_unique_program and make_unique_params are defined, then perform a call to a user specified procedure to keep getting values until a unique value is returned. If make_unique_program is not specified, then a random number is added to the field value until it is unique. The make_unique_field_len, make_unqiue_truncate, and make_unique_separator are used to define this process. In Import Mode, the make_unique_field is treated as an add_only_field in that it cannot be modified after being added. In Transaction Mode, the make_unique_field can be modified if it did not previously have a value.
make_unique_field_len
Optional parameter for Import and Transaction Mode if make_unique_field is specified. Contains the maximum length of the make_unique_field value. If not defined, the default is the length of the make_unique_field in ldsu_layout.dat.
make_unique_params
Optional parameter for Import and Transaction Mode if make_unique_field and make_unique_program are specified. If the make_unique_field is not unique from data in the input file, then the make_unique_program is called with the values from the the make_unique_params fields as parameters. Specify one more or attributes separated by commas.
make_unique_program
Optional parameter for Import and Transaction Mode if make_unique_field is specified. To use a user-defined procedure to create a unique name, specify the name of a procedure that ldsu will run if the make_unique_field is not unique. The parameters to the make_unique_program will be the attempt number (as a string starting with 0) followed by any field values listed in the make_unique_params procedure. See the Pre and Post Processors section for examples on using make_unqiue_program.
make_unique_separator
Optional parameter for Import and Transaction Mode if make_unique_field is specified and make_unique_program is not specified. If the make_unique_field is not unique, LDSU will append this string before the randon number suffix. Specify a string in double quotes. Default value is a null string.
make_unique_truncate
Optional parameter for Import and Transaction Mode if make_unique_field is specified and make_unique_program is not specified. If the make_unique_field is not unique and adding a random number will exceed the make_unique_length, then set this parameter to NUMBER to truncate the random number. If blank, the default, the base field value is truncated to keep the length at make_unique_length.
mark_for_delete_field
Optional parameter for Import Mode. Specifying this parameter (along with mark_for_delete_value), will cause LDSU to modify records in the LDAP directory instead of permanently deleting them. LDSU sets this field to the value specified in mark_for_delete_value if mark_for_delete_field is empty. If a record is "marked-for-delete" and it reappears in the input file on a subsequent import, the record is modified to remove the mark_for_delete_field attribute (along with any other usual modifications that may be needed). Use of this field is useful if manual intervention is needed to check on records that are to be deleted for example.
mark_for_delete_value
Optional parameter for Import Mode. Required if mark_for_delete_field specified. Sets the value for mark_for_delete_field if a record is to be marked-for-delete.
max_add_transactions
Optional parameter for Import Mode. After generating the input_metafile from the input_file and output_metafile from the LDAP directory extract, LDSU will stop processing without making ANY changes if this many add transactions would occur. Specify a valid positive integer to enable this option. This creates a safety valve against too many new records being added.
max_delete_transactions
Optional parameter for Import Mode. After generating the input_metafile from the input_file and output_metafile from the LDAP directory extract, LDSU will stop processing without making ANY changes if this many delete transactions would occur. Specify a valid positive integer to enable this option. This creates a safety valve against too many records being deleted.
max_fail_transactions
Optional parameter for Import and Transaction Mode. Specify a valid positive integer. If LDSU performs this many failed transactions (Add, Modify, or Delete), the LDSU will exit without any further processing. Default is to have no limit of failed transactions.
max_trans_file
Optional parameter for Import and Transaction Mode. Name of a procedure to run every max_transactions. See max_transactions for more detail.
max_transactions
Optional parameter for Import and Transaction Mode. If a valid positive integer is specified, then after every time LDSU performs the number of transactions specified, if will unbind from ldap directory, execute the max_trans_file procedure (if defined), and re-bind to the LDAP directory. This option is not normally used but available if any LDAP directory needs some sort of cleanup procedure run every N transactions for example.
mod_hidden_flag
Used in Transaction Mode. Valid values are Y or N. Default is N. When processing the input_mod_file, if this flag is Y then an attempt to modify the record is made even if the existing record cannot be read (e.g. is hidden). If the flag is N, then the modify returns KEYNOTFND if the existing record cannot be read and no modify is performed. The purpose of this flag is allow a force modification of hidden records. If the flag is Y, the key_fields must not be defined, since the DN_SEQUENCE must be used from the input record.
mod_or_add_flag
Used in Transaction Mode. Valid values are Y or N. Default is N. When processing the input_mod_file, if this flag is Y then an attempt is made to modify the entry in the LDAP directory, but if that fails, an attempt to add the entry to the LDAP directory is made as well. If the flag is N only attempt to modify records in the LDAP directory. The purpose of this flag is to support foreign directories that cannot distinguish between records which are New or Modified. If the flag is Y, the key_fields must not be defined, since the DN_SEQUENCE must be used for the Add record.
output_add_file
Used in Changes Mode. Required name of the file to hold changes add records exported from the LDAP directory. Specify the name of the file. Suggested name is export_add.txt.
output_add_lines_per_record
Used in Changes Mode if using output_add_rdf. Specify the number of lines in the output file per changed record exported from the LDAP directory. Default value is 1.
output_add_rdf
Used in Changes Mode and required if not using output_rdf. This specifies the name of the rdf file defining the output_add_file format. The suggested value for this field, if used, is output_add.rdf. If LDIF formatted output desired, set output_rdf=LDIF and leave this blank.
output_del_file
Used in Changes Mode. Required name of the file to hold changes delete records exported from the LDAP directory. Specify the name of the file. Suggested name is export_del.txt.
output_del_lines_per_record
Used in Changes Mode if using output_del_rdf. Specify the number of lines in the output file per changed record exported from the LDAP directory. Default value is 1.
output_del_rdf
Used in Changes Mode and required if not using output_rdf. This specifies the name of the rdf file defining the output_del_file format. The suggested value for this field, if used, is output_del.rdf. If LDIF formatted output desired, set output_rdf=LDIF and leave this blank.
output_field_separator
Used in Export and Changes Mode. This parameter defines a string to use as an output field separator when using the N-*-# syntax in output rdf files. By default, the value is a single tab character. To define a different separator string, define the value enclosed in double quotes. (e.g. output_field_separator = "," would define this parameter as a comma). Ignored if output_rdf=LDIF.
output_file
Required for Export Mode. Optional for Changes Mode if all delete, modify, and add records can go to one file. (e.g. if output_rdf=LDIF). Name of the file containing records exported from the LDAP directory as described by the output_rdf file. The suggested value for this field is export.txt for basic Export and Changes Mode and export_output.txt for Export1 and Changes1 Mode.
output_header_file
Used in Export and Changes Mode. Optional parameter which gives the name of a file whose lines should prefix and records written to the output_file for Export Mode or output_add_file, output_del_file, and output_mod_file for Changes Mode.
output_lines_per_record
Used in Export Mode and in Changes Mode if using output_rdf. Specify the number of lines in the output file per record exported from the LDAP directory. Default value is 1. Ignored if output_rdf=LDIF.
output_metafile
Required parameter for basic Changes Mode. Optional parameter for Import, Export, and Changes1 Mode. When extracting records from the LDAP directory, they are placed in a temporary file (metafile). In basic Changes Mode, this file is saved to be used as the input_metafile in the next run and must be specified (suggested name is export.new). In other modes, this parameter defaults to a temporary filename in the default directory and is deleted when LDSU exits. For these modes, only specify a parameter containing a full file specification if you want the metafile to reside in a different directory due to space or efficiency reasons.
output_mod_file
Used in Changes Mode. Optional name of the file to hold changes modify records exported from the LDAP directory. If not specified, all modify records will be written to the Delete (with Old Values) and the Add (with New Values) output files. Allowing this file to not be specified accommodates foreign directories which can only do Adds and Deletes and cannot do Modifies. Suggested name, if used, is export_mod.txt.
output_mod_lines_per_record
Used in Changes Mode if using output_mod_rdf. Specify the number of lines in the output file per changed record exported from the LDAP directory. Default value is 1.
output_mod_rdf
Used in Changes Mode if not using output_rdf and you want a changes Modify file to be produced (output_mod_file). This specifies the name of the rdf file. The suggested value for this field, if used, is output_mod.rdf. If LDIF formatted output desired, set output_rdf=LDIF and leave this blank.
output_rdf
Used in Export and Changes Mode. This specifies the name of the RDF file for the output file. In Export Mode, this parameter is required. In Changes Mode, this parameter is required if not using output_add_rdf, output_del_rdf, and (optionally) output_mod_rdf. The suggested value for this field is export.rdf for basic Export or Changes Mode, and export_output.rdf for Export1 or Changes1 mode, If LDIF formatted output desired, set output_rdf=LDIF.
read_only_test
Used in Import and Transaction Mode. Set to Y to run in a "Read Only" Mode that will test all the configuration and data files but not actually do any updates (Adds, Modifies, or Deletes) to the LDAP Directory. Set to N or leave blank for normal Read/Write operations. With read_only_test=Y, LDSU will do all read operations - Search, Uniqueness Checking, etc. LDSU will not be able to test for some conditions (e.g. valid DN's, unique DN's, and directory constraint violations) which are not checked until a Write (ADD, MODIFY, DELETE) operation occurs against the LDAP directory.
recognize_case_changes
Used in all modes, but mainly used in Import and Changes Mode when comparing field values to see if there is a modify. If this parameter is set to Y then a change in case will cause a modify to occur. If this parameter is N or blank, then a case changes will not cause a modify. Setting to Y is recommended since setting to N will also cause the first RDN value in the Distinguished Name (DN) to capitalized when added to the LDAP directory or when exported out of the directory.
search_context
Used in all modes when extracting entries from the LDAP Directory. Use of the field is not required but recommended. This field determines the search base when fetching entries from the LDAP Directory. The value for this field is the seach base in LDAP DN format (e.g. o=digital, c=us).
synch_id_field
Optional parameter used in all modes and used with synch_id_value. Using the parameter gives a way for LDSU to establish ownership for directory entries it adds/modifies/deletes in the LDAP directory. If specified, this parameter specifies the LDAP Directory attribute (in ldsu_layout.dat) to hold the synch_id_value. Every entry added will have synch_id_field set to synch_id_value. LDSU will only access entries where synch_id_field=synch_id_value. Because the Group ID (gid_field) provides the same basic function and an extra attribute to hold the synch id is required, using synch_id is often not necessary/desirable.
synch_id_value
Used in all modes. Value to place in the synch_id_field if specified. Default value is LDSU.
synch_label
Used in all modes. Set to a descriptive name that is used in the log files. A good convention is to use the name of ldsu subdirectory for this value.
synch_object
Required in Import Mode or Transaction Mode if using an Add Input file. This field contains the object classes that are stored with the object (in the objectclass attribute) on an Add operation to the LDAP Directory. Note: This attribute cannot be modified by LDSU. LDSU treats the objectclass as an add_only_field. If multiple object classes are needed, separate the values with a comma (e.g. person,organizationalPerson). Refer to the LDAP directory for more information on objectclass values for various objects.
synch_type
Required in all modes and must be the first parameter. Valid values are Import, Transaction, Export, or Changes. This parameter determines the mode and the remaining list of parameters that are needed.
unique_fields
Used in Import and Transaction Mode. When Adding or Modifying a record, LDSU makes sure any fields listed are unique for the unique_search_context. Multiple fields may be listed (separated by commas). Also sets of fields that have to be unique together can be specified by enclosing each group of fields in double quotes. Examples for using unique_fields:
  • rfc822Mailbox - Only rfc822Mailbox must be unique
  • mail,rdn - Both mail and rdn must be unique
  • "userloc,username" - The userloc,username pair must be unique
  • emailuse1, "emailuse2, emailuse3, emailuse4" - emailuse1 must be unique as well as the combination of emailuse2, emailuse3, and emailuse4.
No limit to the number unique fields or sets exists, though this may slow down the time it takes to add or modify entries. If the LDAP directory supports it, any attribute used for unique searching should be "indexed". Refer to the LDAP directory for more information on indexing.
unique_search_context
Used in Import and Transaction Mode. This field determines the search base to use when checking for unique fields in the LDAP directory. The field is used if using unique_fields, make_unique_field, gen_profs_alias_fields, or gen_snads_alias_fields. The value for this field is the seach base in LDAP DN format (e.g. o=digital, c=us). Typically this field will be the same value as the search_context, but can be independent.
verbose
Used in all modes. Set to Y to get extra output to stdout (in ldsu.log if using the ldsu scripts). This information is often useful in helping to figure out what LDSU is doing, so Y is recommended. Set to N or leave blank to not get extra output.




HOME NEXT PREVIOUS

Digital Copyright © Digital Equipment Corporation 1998