The ldifsearch Command-Line Tool

Search one or more LDIF files to identify entries matching a given set of criteria.

Usage

ldifsearch {arguments} [filter] [attributes...]

Input Arguments

• -l {path} / --ldifFile {path} — the path to an LDIF file containing the entries to search. This must be provided at least once, but if multiple files are given, they will be searched in the order provided. The file may optionally be compressed or encrypted.
  The specified path must refer to a file that exists.
  
  
• --ldifEncryptionPassphraseFile {path} — The path to the file containing the passphrase used to encrypt the contents of the input LDIF files. If this argument is provided, the file must exist and must contain exactly one line that contains only the encryption passphrase. If the input LDIF file is encrypted but this argument is not provided, then the tool will interactively prompt for the passphrase.
  The specified path must refer to a file that exists.
  
  
• --stripTrailingSpaces — Strip off any illegal trailing spaces identified in LDIF entries rather than rejecting those entries.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --schemaPath {path} — The path to an LDIF file (or a directory containing multiple LDIF files) with the schema definitions to use during processing. This argument may be used multiple times to specify multiple schema paths. If this argument is ot provided, the LDAP SDK's default standard schema will be used.
  The specified path must refer to a file that exists.
  
  
• --checkSchema — Indicates whether to validate each entry read from an LDIF file to ensure that it conforms to the defined schema. If this argument is provided, an error will be reported for every entry that does not conform to the schema.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --isCompressed — Indicates whether the input LDIF files are compressed. This argument is no longer necessary, as the tool will automatically detect whether each file is compressed.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  

Output Arguments

• -o {path} / --outputFile {path} — The path to an output file to which matching entries will be written. If this is not provided, then matching entries will be written to standard output.
  The specified path must refer to a file which may or may not exist, but whose parent directory must exist.
  
  
• --separateOutputFilePerSearch — Use a separate output LDIF file for each search filter. This argument is only applicable if either the --filterFile or --ldapURLFile argument is provided to specify multiple sets of search criteria. If this argument is given, then each output file will use the path specified by the --outputFile argument, followed by a period and a number indicating which search criteria is being used (e.g., '.1'; for the first set of search criteria, '.2' for the second, and so on).
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --compressOutput — GZIP-compress the data as it is written to each output file.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --encryptOutput — Encrypt the data as it is written to each output file. If the '--outputEncryptionPassphraseFile' argument is provided, then the passphrase contained in that file will be used to encrypt the output. Otherwise, the tool will interactively prompt for the passphrase.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --outputEncryptionPassphraseFile {path} — The path to a file containing the passphrase to use to encrypt the contents of the output files. If this argument is provided, then the file must exist, and it must contain exactly one line comprised entirely of the encryption passphrase.
  The specified path must refer to a file that exists.
  
  
• -O / --overwriteExistingOutputFile — Overwrite any output file that already exists, rather than appending to it. This argument must be provided if the output file already exists and either of the '--compressOutput' or '--encryptOutput' arguments is provided.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --outputFormat {ldif|json|csv|multi-valued-csv|tab-delimited|multi-valued-tab-delimited|dns-only|values-only} — Specifies the format that should be used for the output generated by this tool. Allowed values are 'LDIF' (LDAP Data Interchange Format, which is the standard string representation for LDAP data), 'JSON' (JavaScript Object Notation, which is a popular format used by web services), 'CSV' (comma-separated values, which is a commonly used format for text processing, with only a single value per attribute), 'multi-valued-csv' (comma-separated values with a vertical bar between values of multivalued attributes), 'tab-delimited' (another commonly used general text format, with only a single value per attribute), 'multi-valued-tab-delimited' (tab-delimited text with a vertical bar between values of multivalued attributes), 'dns-only' (in which only the DN of each matching entry will be written on a line by itself with no information about the entry's attributes), and 'values-only' (in which each value returned will be written on a line by itself with no attribute names, entry DNs, or delimiters between entries). If the single-valued or multivalued CSV or tab-delimited formats are used then there must be a specific set of attributes requested, and the order in which values are returned will match the order in which they are requested. Further, the CSV and tab-delimited formats cannot be used in conjunction with the '--ldapURLFile' argument. If no output format is specified, a default of 'LDIF' will be used.
  A provided value should be one of the following: 'values-only', 'multi-valued-csv', 'tab-delimited', 'ldif', 'csv', 'multi-valued-tab-delimited', 'json', 'dns-only'.
  
  
• --wrapColumn {value} — The column at which long lines should be wrapped. By default, long lines will be wrapped based on the terminal width (or 80 columns if the terminal width cannot be determined).
  The specified value must not be less than 5 or greater than 2,147,483,647.
  
  
• -T / --doNotWrap — Do not wrap long lines as they are written.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  

Search Criteria Arguments

• -b {dn} / --baseDN {dn} — The base DN to use when searching for matching entries. This argument must not be provided if the --ldapURLFile argument is given, as the base DN from each URL will be used. If no LDAP URL file is given and this argument is not provided, then the null DN will be used as the search base.
  A provided value must be able to be parsed as an LDAP distinguished name as described in RFC 4514.
  
  
• -s {base|one|sub|subordinates} / --scope {base|one|sub|subordinates} — The scope to use when searching for matching entries. This argument must not be provided if the --ldapURLFile argument is given, as the scope from each URL will be used. If no LDAP URL file is given and this argument is not provided, then a default scope of 'sub' will be used.
  The provided value should be one of 'base', 'one', 'sub', or 'subordinate'.
  
  
• -f {path} / --filterFile {path} — The path to a file containing one or more search filters (each on a separate line) to use to identify matching entries. If neither this argument nor the --ldapURLFile argument is provided, then the filter must be provided as the first trailing argument.
  The specified path must refer to a file that exists.
  
  
• --ldapURLFile {path} — The path to a file containing one or more LDAP URLs (each on a separate line) with the criteria to use to identify matching entries. Note that only the base DN, scope, filter, and requested attributes will be used from the LDAP URLs; the server address and port (if any) will be ignored. If neither this argument nor the --filterFile argument is provided, then the filter must be provided as the first trailing argument.
  The specified path must refer to a file that exists.
  
  
• -z {value} / --sizeLimit {value} — The maximum number of entries to return for each search. If this is not provided, then no size limit will be enforced.
  The specified value must not be less than 0 or greater than 2,147,483,647.
  
  
• -t {value} / --timeLimitSeconds {value} — The maximum length of time in seconds to spend processing. If this is not provided, then no time limit will be enforced.
  The specified value must not be less than 0 or greater than 2,147,483,647.
  
  

Additional Arguments

• --interactive — Launch the tool in interactive mode.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -H / --help — Display usage information for this program.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --help-debug — Display usage information for debug logging.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --enable-debug-logging — Enables debug logging for the tool.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --debug-log-level {level} — The debug log level to use for the tool. Allowed values include 'off', 'severe', 'warning', 'info', 'fine', 'finer', and 'finest'. If this is not specified, a default level of 'severe' will be used.
  
  
• --debug-log-category {category} — The message categories to include in the debug log output. Allowed values include 'asn1', 'connect', 'exception', 'ldap', 'connectionpool', 'ldif', 'monitor', 'codingerror', and 'other'. This argument may be provided multiple times to indicate that multiple categories should be included. If this is not specified, then all categories will be included.
  
  
• --include-debug-stack-traces — Indicates that debug log messages should include a stack trace with the code location from which each debug message originated.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --use-multi-line-debug-messages — Indicates that debug log messages (which will be JSON objects) should be written as multi-line strings rather than single-line strings.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --debug-log-file {path} — The path to the debug log file to be written. If this is not specified, a default path of 'ldifsearch.debug' will be used.
  The specified path must refer to a file which may or may not exist, but whose parent directory must exist.
  
  
• -V / --version — Display version information for this program.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --propertiesFilePath {path} — The path to a properties file used to specify default values for arguments not supplied on the command line.
  The specified path must refer to a file that exists.
  
  
• --generatePropertiesFile {path} — Write an empty properties file that may be used to specify default values for arguments.
  The specified path must refer to a file which may or may not exist, but whose parent directory must exist.
  
  
• --noPropertiesFile — Do not obtain any argument values from a properties file.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --suppressPropertiesFileComment — Suppress output listing the arguments obtained from a properties file.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  

Dependent Argument Sets

• If the --separateOutputFilePerSearch argument is provided, then the --outputFile argument must also be provided.
• If the --compressOutput argument is provided, then the --outputFile argument must also be provided.
• If the --encryptOutput argument is provided, then the --outputFile argument must also be provided.
• If the --overwriteExistingOutputFile argument is provided, then the --outputFile argument must also be provided.
• If the --outputEncryptionPassphraseFile argument is provided, then the --encryptOutput argument must also be provided.

Exclusive Argument Sets

• The following arguments cannot be used together: --wrapColumn, --doNotWrap
• The following arguments cannot be used together: --baseDN, --ldapURLFile
• The following arguments cannot be used together: --scope, --ldapURLFile
• The following arguments cannot be used together: --filterFile, --ldapURLFile
• The following arguments cannot be used together: --outputFormat, --separateOutputFilePerSearch
• The following arguments cannot be used together: --propertiesFilePath, --noPropertiesFile

Examples

• Search for entries with a uid value of 'jdoe' in the data.ldif file. The matching entries will be written to standard output.

    ldifsearch --ldifFile data.ldif "(uid=jdoe)"

• Search for all entries with the 'person' object class below 'dc=example,dc=com' in the data.ldif file. Write the matching entries to the 'people.ldif' file, but only include the 'givenName', 'sn', and 'cn' attributes.

    ldifsearch --ldifFile data.ldif --outputFile people.ldif \
         --baseDN dc=example,dc=com --scope sub "(objectClass=person)" \
         givenName sn cn