7.3. Shell Scripts
This section covers the following scripts:
Section 7.3.5, “db2ldif (Exports Database Contents to LDIF)”
Section 7.3.8, “ldif2ldap (Performs Import Operation over LDAP)”
Section 7.3.10, “monitor (Retrieves Monitoring Information)”
Section 7.3.11, “repl-monitor (Monitors Replication Status)”
Section 7.3.12, “restart-slapd (Restarts the Directory Server)”
Section 7.3.13, “restoreconfig (Restores Administration Server Configuration)”
Section 7.3.14, “saveconfig (Saves Administration Server Configuration)”
Section 7.3.17, “suffix2instance (Maps a Suffix to a Backend Name)”
Section 7.3.18, “vlvindex (Creates Virtual List View Indexes)”
Some of the shell scripts can be executed while the server is running. For others, the server must be stopped. The description of each script below indicates whether the server must be stopped or if it can continue to run while executing the script.
When a shell script has a Perl equivalent, there is a cross-reference to the section describing the equivalent Perl script.
Restores the database from the most recent archived backup. To run this script, the server must be stopped.
bak2db
backupDirectory
[
-n backend
]
| Option | Description |
|---|---|
| backupDirectory | Gives the backup directory path. |
| -n backendInstance |
Optional. Specifies the backend name, such as userRoot, which is being restored. This option is only used for filesystem replica initialization or to restore a single database; it is not necessary to use the n option to restore the entire directory.
|
For information on the equivalent Perl script, see Section 7.4.1, “bak2db.pl (Restores a Database from Backup)”. For more information on restoring databases, see the "Populating Directory Databases" chapter in the Red Hat Directory Server Administration Guide. For more information on using filesystem replica initialization, see the "Managing Replication" chapter in the Red Hat Directory Server Administration Guide.
Troubleshoots replication-related problems. cl-dump is a shell script wrapper of cl-dump.pl to set the appropriate library path.
cl-dump [
-h host
] [
-p port
] [
-D bindDn
]
-w bindPassword
|
-P bindCert
[
-r replicaRoots
] [
-o outputFile
] [
-c
] [
-v
]
cl-dump
-i changelogFile
[
-o outputFile
] [
-c
]
Without the -i option, the script must be run when the Directory Server is running from a location from which the server's changelog directory is accessible.
| Option | Description |
|---|---|
| -c |
Dumps and interprets CSN only. This option can be used with or without the -i option.
|
| -D bindDn |
Specifies the Directory Server's bind DN. Defaults to cn=Directory Manager if the option is omitted.
|
| -h host | Specifies the Directory Server's host. This defaults to the server where the script is running. |
| -i changelogFile | Specifies the path to the changelog file. If there is a changelog file and if certain changes in that file are base-64 encoded, use this option to decode that changelog. |
| -o outputFile | Specifies the path, including the filename, for the final result. Defaults to STDOUT if omitted. |
| -p port |
Specifies the Directory Server's port. The default value is 389.
|
| -P bindCert | Specifies the path, including the filename, to the certificate database that contains the certificate used for binding. |
| -r replicaRoots | Specifies the replica-roots whose changelog to dump. When specifying multiple roots, use commas to separate roots. If the option is omitted, all the replica roots will be dumped. |
| -v | Prints the version of the script. |
| -w bindPassword | Specifies the password for the bind DN. |
For information on the equivalent Perl script, see Section 7.4.2, “cl-dump.pl (Dumps and Decodes the Changelog)”.
Verifies the backend database files. dbverify is a shell script wrapper of verify-db.pl to set the appropriate library path.
dbverify [
-a /path/to/database_directory
]
| Option | Description |
|---|---|
| -a path |
Gives the path to the database directory. If this option is not passed with the verify-db.pl command, then it uses the default database directory, /var/lib/dirsrv/slapd-.
|
For information on the equivalent Perl script, see Section 7.4.13, “verify-db.pl (Check for Corrupt Databases)”.
Creates a backup of the current database contents. This script can be executed while the server is still running.
db2bak [
backupDirectory
]
For information on the equivalent Perl script, see Section 7.4.3, “db2bak.pl (Creates a Backup of a Database)”.
Exports the contents of the database to LDIF. This script can be executed while the server is still running, except with the -r option. To export the replication state information, shutdown the server first, then run db2ldif with -r.
For information on the equivalent Perl script, see Section 7.4.5, “db2ldif.pl (Exports Database Contents to LDIF)”.
For the shell scripts, the script runs the ns-slapd command-line utility with the db2ldif keyword. Ellipses (...) indicate that multiple occurrences are allowed.
db2ldif [
-n backendInstance
|
-s includeSuffix
] [
-x excludeSuffix
] [
-r
] [
-C
] [
-u
] [
-U
] [
-m
] [
M
] [
-a outputFile
] [
-1
] [
-N
] [
-E
]
Either the -n or the -s option must be specified. By default, the output LDIF will be stored in one file. To specify the use of several files, use the option -M.
| Option | Description |
|---|---|
| -1 | Deletes, for reasons of backward compatibility, the first line of the LDIF file which gives the version of the LDIF standard. |
| -a outputFile | Gives the name of the output LDIF file. |
| -C | Uses only the main database file. |
| -E | Decrypts encrypted data during export. This option is used only if database encryption is enabled. |
| -m | Sets minimal base-64 encoding. |
| -M |
Use of several files for storing the output LDIF, with each instance stored in instance filename (where filename is the filename specified for -a option).
|
| -n backendInstance | Gives the instance to be exported. |
| -N |
Specifies that the entry IDs are not to be included in the LDIF output. The entry IDs are necessary only if the db2ldif output is to be used as input to db2index.
|
| -r | Exports a replica. |
| -s suffix_name |
Names the suffixes to be included or the subtrees to be included if -n has been used.
|
| -u | Requests that the unique ID is not exported. |
| -U | Requests that the output LDIF is not folded. |
| -x suffix_name | Names the suffixes to be excluded. |
Reindexes the database index files. Ellipses indicate that multiple occurrences are allowed.
For information on the equivalent Perl script, see Section 7.4.4, “db2index.pl (Creates and Generates Indexes)”.
db2index [[
-n backendInstance
] | [
-s includeSuffix
]] [
-t [attributeName{:indextypes(:mathingrules)}]
] [
-T vlvAttribute
]
Here are a few sample commands:
Reindex all the database index files:
db2index
Reindex cn and givenname in the database instance userRoot:
db2index -n userRoot -t cn -t givenname
Reindex cn in the database where the root suffix is dc=example,dc=com:
db2index -s "dc=example,dc=com" -t cn
| Option | Description |
|---|---|
| -n backendInstance | Gives the name of the instance to be reindexed. |
| -s includeSuffix |
Gives suffixes to be included or the subtrees to be included if -n has been used.
|
| -t attributeName{:indextypes(:mathingrules)} |
Names of the attributes to be reindexed. Optionally, this can include the index type (eq, pres, sub, approx) and a matching rule OID.
|
| -T vlvAttributeName |
Gives the names of the VLV attributes to be reindexed. The name is the VLV index object's common name in cn=config.
|
Runs the ns-slapd command-line utility with the ldif2db keyword. To run this script, the server must be stopped. Ellipses indicate that multiple occurrences are allowed.
For information on the equivalent Perl script, see Section 7.4.6, “ldif2db.pl (Import)”.
ldif2db supports LDIF version 1 specifications. An attribute can also be loaded using the :< URL specifier notation; for example:
jpegphoto:< file:///tmp/myphoto.jpg
Although the official notation requires three ///, the use of one / is accepted. For further information on the LDIF format, see the "Managing Directory Entries" chapter in the Red Hat Directory Server Administration Guide.
ldif2db [
-n backendInstance
|
{
-s includeSuffix
}
... ] [
-x excludeSuffix
] [
{
-i ldifFile
}
] [
-O
] [
-g string
] [
-G namespaceId
] [
-E
]
| Option | Description |
|---|---|
| -c | Merges chunk size. |
| -E | Encrypts data during import. This option is used only if database encryption is enabled. |
| -g string |
Generates a unique ID. Type
By default, a time-based unique ID is generated. When using the -g deterministic
namespace_id is a string of characters in the format Use this option to import the same LDIF file into two different Directory Servers and the contents of both directories should have the same set of unique IDs. If unique IDs already exist in the LDIF file being imported, then the existing IDs are imported to the server, regardless of the options specified. |
| -G namespaceId |
Generates a namespace ID as a name-based unique ID. This is the same as specifying the -g deterministic option.
|
| -i ldifFile | Gives the names of the input LDIF files. When multiple files are imported, they are imported in the order they are specified on the command line. |
| -n backendInstance | Gives the instance to be imported. Ensure that the specified instance corresponds to the suffix contained by the LDIF file; otherwise, the data contained by the database is deleted, and the import fails. |
| -O | Requests that only the core database is created, without attribute indexes. |
| -s includeSuffix |
Gives the suffixes to be included or to specify the subtrees to be included if -n has been used.
|
| -x excludeSuffix | Gives the suffixes to be excluded. |
Performs an import operation over LDAP to the Directory Server. To run this script, the server must be running.
ldif2ldap
-D rootdn
-w password
-f filename
| Option | Description |
|---|---|
| -D rootdn |
Gives a user DN with root permissions, such as Directory Manager.
|
| -f filename | Gives the name of the file to be imported. When importing multiple files, the files are imported in the order they are specified on the command line. |
| -w password | Gives the password associated with the user DN. |
Prints the encrypted form of a password using one of the server's encryption algorithms. If a user cannot log in, use this script to compare the user's password to the password stored in the directory.
pwdhash
-D config_directory
[
-H
] [[
-s scheme
] | [
-c comparepwd
]] [
password
]
| Option | Description |
|---|---|
| -D config_directory | Gives the full path to the configuration directory. |
| -c password | Gives the hashed password string to which to compare the user's password. |
| -s scheme | Gives the scheme to hash the given password. |
| -H | Shows the help. |
For more information on the different storage schemes, such as SSHA, SHA, CRYPT, and CLEAR, see the Directory Server Administration Guide.
Retrieves performance monitoring information using the ldapsearch command-line utility.
monitor
There are no options for this script.
For more information on the ldapsearch command-line utility, see Section 6.8, “ldif”.
Shows in-progress status of replication. repl-monitor is a shell script wrapper of repl-monitor.pl to set the appropriate library path.
For more information on the Perl script, see Section 7.4.12, “repl-monitor.pl (Monitors Replication Status)”.
repl-monitor
-h host
-p port
-f configFile
[
-u refreshUrl
] [
-t refreshInterval
] [
-r
] [
-v
]
| Option | Description |
|---|---|
| -h host | Specifies the initial replication supplier's host. The default value is the current hostname. |
| -f configFile | Specifies the absolute path to the configuration file, which defines the connection parameters used to connect to LDAP servers to get replication information. For more information about the configuration file, see Configuration File Format. |
| -p port |
Specifies the initial replication supplier's port. The default value is 389.
|
| -r | If specified, causes the routine to be entered without printing the HTML header information. This is suitable when making multiple calls to this routine — such as specifying multiple, different, unrelated supplier servers — and expecting a single HTML output. |
| -t refreshInterval |
Specifies the refresh interval in seconds. The default value is 300 seconds. This option must be used with the -u option.
|
| -u refreshUrl |
Specifies the refresh URL. The output HTML file may invoke a CGI program periodically. If this CGI program in turn calls this script, the effect is that the output HTML file would automatically refresh itself. This is useful for continuous monitoring. See also the -t option. The script has been integrated into Red Hat Administration Express, so that the replication status can be monitored through the gateway.
|
| -v | Prints the version of this script. |
The configuration file defines the following:
The connection parameters for connecting to the LDAP servers to get replication information; specifying this information is mandatory.
The server alias for more readable server names; specifying this information is optional.
The color thresholds for time lags; specifying this information is optional.
The format for the configuration file is shown below.
[connection] host:port:binddn:bindpwd:bindcert host:port:binddn:bindpwd:bindcert ... [alias] alias = host:port alias = host:port ... [color] lowmark = color lowmark = color
The connection section defines how this tool may connect to each LDAP server in the replication topology to get the replication-agreement information. The default binddn is cn=Directory Manager. Simple bind will be used unless bindcert is specified with the path of a certificate database.
A server may have a dedicated or shared entry in the connection section. The script will find out the most matched entry for a given server. For example, if all the LDAP servers except host1 share the same binddn and bindpassword, the connection section will need to contain just two entries:
[connection] *:*:binddn:bindpassword: host1:*:binddn1:bindpassword1:
In the optional alias section, use aliases such as Supplier1, Supplier2, and Hub1, to identify the servers in the replication topology. If used, the output shows these aliases, instead of http(s)://hostname:port.
The CSN time lags between suppliers and consumers can be displayed in different colors based on their range. The default color set is green for 0-5 minutes lag, yellow for 5-60 minutes lag, and pink for a lag of 60 minutes or more.
The connection parameters for all the servers in a replication topology must be specified within one configuration file. One configuration file, however, may contain information for multiple replication topologies.
Because of the connection parameters, the replication monitoring tool does not need to perform DES decryption of the credentials stored in the Directory Server. Each line in this file could either be a comment started with the # character or a connection entry of the format:
host:port:binddn:bindpwd:bindcert
host, port, and binddn can be replaced with relevant values or *, or omitted altogether. If host is null or *, the entry may apply to any host that does not have a dedicated entry in the file. If port is null or *, the port will default to the port stored in the current replication agreement. If binddn is null or *, it defaults to cn=Directory Manager.
bindcert can be replaced with the full path to the certificate database, null, or *. If bindcert is omitted or replaced with *, the connection will be a simple bind.
For example, the configuration file may appear as follows:
#Configuration File for Monitoring Replication Via Admin Express [connection] *:*:*:mypassword [alias] M1 = host1.example.com:10011 C1 = host4.example.com:10021 C2 = host2.example.com:10022 [color] 0 = #ccffcc 5 = #FFFFCC 60 = #FFCCCC
A shadow port can be set in the replication monitor configuration file. For example:
host:port=shadowport:binddn:bindpwd:bindcert
When the replication monitor finds a replication agreement that uses the specified port, it will use the shadow port to connect to retrieve statistics.
Restarts the Directory Server.
restart-slapd
There are no options for this script.
| Exit Code | Description |
|---|---|
| 0 | Server restarted successfully. |
| 1 | Server could not be started. |
| 2 | Server restarted successfully but was already stopped. |
| 3 | Server could not be stopped. |
Restores, by default, the most recently saved Administration Server configuration information to the NetscapeRoot partition under the /etc/dirsrv/slapd- directory.
instance_name/
To restore the Administration Server configuration, do the following:
Stop the Directory Server.
Run the restoreconfig script.
Restart the Directory Server.
Restart the Administration Server for the changes to be taken into account.
restoreconfig
There are no options for this script.
Saves Administration Server configuration information to /var/lib/dirsrv/slapd- directory.
instance_name/bak
This script will only run if the server is running.
saveconfig
There are no options for this script.
Starts the Directory Server. It might be a good idea to check whether the server has been effectively started using the ps command because it could sometimes be that the script returned while the startup process was still on-going, resulting in a confusing message.
start-slapd
There are no options for this script.
| Exit Code | Description |
|---|---|
| 0 | Server started successfully. |
| 1 | Server could not be started. |
| 2 | Server was already started. |
Stops the Directory Server. It might be a good idea to check whether the server has been effectively stopped using the ps command because it could sometimes be that the script returned while the shutdown process was still on-going, resulting in a confusing message.
stop-slapd
There are no options for this script.
| Exit Code | Description |
|---|---|
| 0 | Server stopped successfully. |
| 1 | Server could not be stopped. |
| 2 | Server was already stopped. |
To run the vlvindex script, the server must be stopped. The vlvindex script creates virtual list view (VLV) indexes, known in the Directory Server Console as browsing indexes. VLV indexes introduce flexibility in the way search results are viewed. VLV indexes can organize search results alphabetically or in reverse alphabetical order, making it easy to scroll through the list of results. VLV index configuration must already exist prior to running this script.
vlvindex [
-d debugLevel
] {[
-n backendInstance
] | [
-s suffix
]} [
-T vlvTag
]
Either the -n or the -s option must be specified.
| Option | Description |
|---|---|
| -d debugLevel | Specifies the debug level to use during index creation. Debug levels are defined in Section 2.3.1.42, “nsslapd-errorlog-level (Error Log Level)” |
| -n backendInstance | Gives the name of the database containing the entries to index. |
| -s suffix | Gives the name of the suffix containing the entries to index. |
| -T vlvTag | VLV index identifier to use to create VLV indexes. The Console can specify VLV index identifier for each database supporting the directory tree, as described in the Directory Server Administration Guide. Define additional VLV tags by creating them in LDIF and adding them to Directory Server's configuration, as described in the Red Hat Directory Server Administration Guide. Red Hat recommends using the DN of the entry for which to accelerate the search sorting. |