10.3. Shell Scripts
10.3.1. bak2db (Restores a Database from Backup)
Note
bak2db
backupDirectory
Table 10.3. bak2db Options
Option | Description |
---|---|
backupDirectory | Gives the backup directory path. |
10.3.2. cl-dump (Dumps and Decodes the Changelog)
cl-dump
is a shell script wrapper of cl-dump.pl
to set the appropriate library path.
Note
cl-dump
-h host
-p port
-D bindDn
[
-w bindPassword
|
-P bindCert
] [
-l
]
-r replicaRoots
-o outputFile
[
-c
] [
-v
]
cl-dump
[
-i changelogFile
] [
-l
] [
-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.
Table 10.4. cl-dump Options
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. |
-l | Renames the temporary LDIF files in the /var/lib/dirsrv/slapd-instance_name/changelogdb/ directory to *.done instead of removing them. |
-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. |
10.3.3. db2bak (Creates a Backup of a Database)
Important
db2bak.pl
Perl script or using the Directory Server Console if the server is kept running. The changelog only writes its RUV entries to the database when the server is shut down; while the server is running, the changelog keeps its changes in memory. For the Perl script and the Console, these changelog RUVs are written to the database before the backup process runs. However, that step is not performed by the command-line script.
db2bak
should not be run on a running master server. Either use the Perl script or stop the server before performing the backup.
Note
db2bak
[
backupDirectory
]
10.3.4. db2ldif (Exports Database Contents to LDIF)
-r
option. To export the replication state information, shut down the server first, then run db2ldif
with -r
.
Note
db2ldif
uses the entryrdn
index to order the parent-child entries when it exports the database; this enables the exported LDIF file to be used for import, since the proper hierarchy of parent and child entries is preserved. If the entryrdn
index is unavailable for some reason, then db2ldif
uses the parentid
key for each entry to identify the parent and export it before the child entry. This second method allows the export operation to succeed, but the operation may take a long time to complete.
ns-slapd
command-line utility with the db2ldif keyword. Ellipses (...) indicate that multiple occurrences are allowed.
Note
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
.
Table 10.5. db2ldif Options
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 | Uses multiple 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 the information required to initialize a replica when the LDIF is imported. Using this option requires that the server be stopped first, then run the
db2ldif command.
The LDIF file which is created with
db2ldif can be imported using ldif2db . When it is imported, if the -r option was used, than the database is automatically initialized as a replica.
See Section 10.3.10, “ldif2db (Import)” for information on importing an LDIF file.
|
-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. |
10.3.5. db2index (Reindexes Database Index Files)
Note
db2index
uses the entryrdn
index to order the parent-child entries when it indexes the database to preserve the proper hierarchy of parent and child entries. If the entryrdn
index is unavailable for some reason, then db2index
uses the parentid
key for each entry to identify the parent. This second method allows the index operation to succeed, but the operation may take a long time to complete.
Note
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
andgivenname
in the database instanceuserRoot
:# db2index -n userRoot -t cn -t givenname
- Reindex
cn
in the database where the root suffix isdc=example,dc=com
:# db2index -s "dc=example,dc=com" -t cn
Table 10.6. db2index Options
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 . |
10.3.6. dbmon.sh (Database Monitoring and Entry Cache Usage)
dbmon.sh
script enables you to monitor the Directory Server database and entry cache usage. You can use the values the script displays to tune the database, entry and DN cache.
dbmon.sh
continuously returns database information until you terminate the script by pressing the Ctrl+C keyboard shortcut.
Note
Syntax
[
INCR=seconds
] [
SERVID=server_identifier
] [
BINDDN=bind_DN
] [
BINDPW=bind_password
] [
DBLIST=databases
] [
INDEXLIST=indexes
] [
VERBOSE=level
] dbmon.sh
Options
dbmon.sh
script does not take any command-line options. You can specify additional options by using environment variables. For example:
# SERVID=slapd-instance_name BINDPW=password dbmon.sh
Option | Parameter | Description |
---|---|---|
INCR | seconds | Returns output every period set in this option. Default: 1 second |
SERVID | server_identifier | Sets the server instance name. Using the instance name, Directory Server automatically uses secure connections to the server, if encryption is enabled on the instance. |
BINDDN | bind_DN | DN used to bind to the directory. The account specified must have read permissions for the cn=config entry and sub entries. Default: cn=Directory Manager |
BINDPW | bind_password | Password for the bind DN. Default: secret |
DBLIST | databases | Space-separated list of databases to check. Enter the list in quotes or escape spaces. Default: all databases |
INDEXLIST | indexes | Space-separated list of indexes to show for every database. Enter the list in quotes or escape spaces. To display all indexes, set the parameter to all . Default: none |
VERBOSE | level |
Sets the output level. Default:
0
Available values:
|
10.3.7. dbverify (Checks for Corrupt Databases)
Important
dbverify
when a modify operation is in progress. This command calls the BerkeleyDB utility db_verify
and does not perform any locking. This can lead to data corruption if the script is run at the same time as a modify. If that occurs, an entry will be recorded in the error log:
DB ERROR: db_verify: Page 3527: out-of-order key at entry 42 DB ERROR: db_verify: DB->verify: db/mstest2/uid.db: DB_VERIFY_BAD: Database verification failed Secondary index file uid.db in db/mstest2 is corrupted. Please run db2index(.pl) for reindexing.
db2index -t uid
to avoid rebuilding all of the indexes or export and reimport all of the databases using db2ldif
and ldif2db
.
dbverify
is a shell script wrapper of verify-db_pl
to set the appropriate library path.
Note
dbverify
[
-a /path/to/database_directory
]
Table 10.7. dbverify Options
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-instance/db . |
10.3.8. ds_removal
ds_removal
tool removes a single instance of Directory Server. The server instance usually must be running when this script is run so that the script can bind to the instance. It is also possible to force the script to run, which may be necessary if there was an interrupted installation process or the instance is corrupted or broken so that it cannot run.
cert8.db
and key3.db
, are not removed, so the remaining instance directory is renamed removed.slapd-
instance.
Note
Option | Parameter | Description |
---|---|---|
-f | Forces the removal of the instance. This can be useful if the instance is not running but must be removed anyway. | |
-s | instance_name | The name of the instance to remove. |
-w | manager_password | The Directory Manager password to use to bind to the instance. |
10.3.9. ds-replcheck (Check Replication Status Between Two Databases)
ds-replcheck
utility compares two Directory Server instances or LDIF-formatted files to identify if they are synchronized. For further details, see the Comparing Two Directory Server Instances section in the Red Hat Directory Server Administration Guide.
Syntax
ds-replcheck
[
-h
] [
-v
] [
-o file_name
] [
-D bind_DN
] [
-w bind_password
] [
-W
] [
-m LDAP_URL_of_master
] [
-r LDAP_URL_of_replica
] [
-b suffix
] [
-l lag_time
] [
-c
] [
-Z certificate_directory
] [
-i attribute_list
] [
-p page_size
] [
-M master_LDIF_file
] [
-R replica_LDIF_file
]
Options
Option | Parameter | Description |
---|---|---|
-h | Displays usage information. | |
-v | Enables the verbose mode. | |
-D | bind_DN | Sets the DN used to bind to the directory. |
-w | bind_password | Sets the password for the bind DN. |
-W | Asks for the password for the bind DN. | |
-m | LDAP_URL_of_master | Sets the URL to the master server. |
-r | LDAP_URL_of_replica | Sets the URL to the replica server. |
-b | suffix | Sets the LDAP suffix to compare. |
-l | lag_time | Sets the amount of time in seconds to ignore inconsistencies. Default: 300 seconds |
-c | Displays verbose conflict information. | |
-Z | certificate_directory | Sets the path to the certificate database directory for secure connections. |
-i | attribute_list | Specifies a comma-separated list of attributes to ignore. |
-p | page_size | Sets the number of entries per page that is displayed. |
-M | master_LDIF_file | Sets the path to the master LDIF file when comparing two files. |
-R | replica_LDIF_file | Sets the path to the replica LDIF file when comparing two files. |
10.3.10. ldif2db (Import)
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.
Note
ldif2db
supports LDIF version 1 specifications. An attribute can also be loaded using the :< URL specifier notation; for example:
jpegphoto:< file:///tmp/myphoto.jpgAlthough 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.
Note
ldif2db
[
-Z instance_name
] [[
-n backendInstance
] | [
[
-s includeSuffix
]
...]] [
-x excludeSuffix
] [
-i ldifFile
] [
-O
] [
-g string
] [
-G namespaceId
] [
-E
] [
-q
] [
-h
]
Table 10.8. ldif2db Options
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
none for no unique ID to be generated and deterministic for the generated unique ID to be name-based.
By default, a time-based unique ID is generated. When using the
deterministic generation to have a name-based unique ID, it is also possible to specify the namespace for the server to use, as follows:
-g deterministic namespace_idnamespace_id is a string of characters in the format 00-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx .
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. |
-h | Displays the usage information. |
-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. |
-q | Enables the quiet mode and suppresses the output. |
-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. |
-Z instance_name | Sets the name of the instance. |
10.3.11. ldif2ldap (Performs Import Operation over LDAP)
Note
ldif2ldap
[
-D rootdn
] [
-w password
] [
-f filename
]
Table 10.9. ldif2ldap Options
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. |
10.3.12. monitor (Retrieves Monitoring Information)
ldapsearch
command-line utility.
Note
monitor
There are no options for this script.
10.3.13. repl-monitor (Monitors Replication Status)
repl-monitor
is a shell script wrapper of repl-monitor.pl
to set the appropriate library path.
Note
repl-monitor
[
-h host
] [
-s
] [
-p port
] [
-f configFile
] [
-u refreshUrl
] [
-t refreshInterval
] [
-r
] [
-v
]
Table 10.10. repl-monitor Options
Option | Description |
---|---|
-h host | Specifies the initial replication supplier's host. The default value is the current host name. |
-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. |
-s | Prints the report in plain text instead of in HTML format. |
-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 a web browser. |
-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.
[connection] host:port:binddn:bindpwd:bindcert host:port:binddn:bindpwd:bindcert ... [alias] alias = host:port alias = host:port ... [color] lowmark = color lowmark = color
cn=Directory Manager
. Simple bind will be used unless bindcert is specified with the path of a certificate database.
host1
share the same binddn and bindpassword, the connection section will need to contain just two entries:
[connection] *:*:binddn:bindpassword: host1:*:binddn1:bindpassword1:
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.
#
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 tocn=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.
#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
host:port=shadowport:binddn:bindpwd:bindcert
10.3.14. pwdhash (Encrypts Passwords)
pwdhash
utility encrypts a specified plain text password. If a user or the Directory Manager cannot log in, use pwdhash
to compare the encrypted passwords. You can also use the generated hash to manually reset the Directory Manager's password.
pwdhash
utility uses the following storage scheme to encrypt the password:
- If you pass the
-s storage_scheme
parameter topwdhash
, the specified scheme will be used. - If you pass the
-D config_directory
parameter topwdhash
, the scheme set in thensslapd-rootpwstoragescheme
attribute will be used. - If you neither specify the path to a valid Directory Server configuration directory nor pass a scheme to
pwdhash
, the utility uses the Directory Server default storage scheme.
pwdhash
[
-D config_directory
] [
-s storage_scheme
] [
-c password_to_compare
] [
-H
]
password
Table 10.11. pwdhash Options
Option | Description |
---|---|
-D config_directory | Sets the full path to the configuration directory. |
-c password_to_compare | Sets the encrypted password string to which to compare specified plain text password. |
-s storage_scheme | Sets the storage scheme to hash the given password. |
-H | Displays the usage information. |
10.3.15. restart-dirsrv (Restarts the Directory Server)
restart-dirsrv
[instance_name]
Option | Description |
---|---|
instance_name | A name of a specific Directory Server instance to restart. If the instance name is not given, then all local Directory Server instances are restarted. |
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. |
10.3.16. restart-ds-admin (Restarts the Administration Server)
Note
restart-ds-admin
There are no options for this script.
10.3.17. restart-slapd (Restarts the Directory Server)
restart-dirsrv
and automatically supplies the instance name to the restart-dirsrv
script.
Note
restart-slapd
There are no options for this script.
Table 10.12. restart-slapd Exit Status Codes
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. |
10.3.18. restoreconfig (Restores Administration Server Configuration)
NetscapeRoot
partition under the /etc/dirsrv/slapd-instance/
directory.
- Stop the Directory Server.
- Run the
restoreconfig
script. - Restart the Directory Server.
- Restart the Administration Server for the changes to be taken into account.
Note
restoreconfig
There are no options for this script.
10.3.19. saveconfig (Saves Administration Server Configuration)
/var/lib/dirsrv/slapd-instance/bak
directory.
Note
saveconfig
There are no options for this script.
10.3.20. start-dirsrv (Starts the Directory Server)
ps
command because it could sometimes be that the script returned a message while the startup process was still on-going, resulting in a confusing message.
start-dirsrv
[instance_name]
Option | Description |
---|---|
instance_name | A name of a specific Directory Server instance to start. If the instance name is not given, then all local Directory Server instances are started. |
Exit Code | Description |
---|---|
0 | Server started successfully. |
1 | Server could not be started. |
2 | Server was already running. |
10.3.21. start-ds-admin (Starts the Administration Server)
Note
start-ds-admin
There are no options for this script.
10.3.22. start-slapd (Starts the Directory Server)
ps
command because it could sometimes be that the script returned a message while the startup process was still on-going, resulting in a confusing message.
start-dirsrv
and automatically supplies the instance name to the start-dirsrv
script.
Note
start-slapd
There are no options for this script.
Table 10.13. start-slapd Exit Status Codes
Exit Code | Description |
---|---|
0 | Server started successfully. |
1 | Server could not be started. |
2 | Server was already started. |
10.3.23. status-dirsrv (Obtains the Status of the Directory Server)
status-dirsrv
[instance_name]
Option | Description |
---|---|
instance_name | A name of a specific Directory Server instance to return the status of. If no instance name is given, then the status of all local Directory Server instances is returned. |
Exit Code | Description |
---|---|
0 | If you specified an instance name, the specified instance is running. If you did not specify an instance name, all Directory Server instances are running. |
1-254 | The number of instances which are not running. If you specified an instance name and this instance exists but is not running, status-dirsrv returns 1 . |
255 | The specified instance does not exist. (Only if you specified an instance name.) |
10.3.24. stop-dirsrv (Stops the Directory Server)
ps
command because it could sometimes be that the script returned a success message while the shutdown process was still on-going, resulting in a confusing message.
stop-dirsrv
[instance_name]
Option | Description |
---|---|
instance_name | A name of a specific Directory Server instance to stop. If the instance name is not given, then all local Directory Server instances are stopped. |
Exit Code | Description |
---|---|
0 | Server stopped successfully. |
1 | Server could not be stopped. |
2 | Server was already stopped. |
10.3.25. stop-ds-admin (Stops the Administration Server)
Note
stop-ds-admin
There are no options for this script.
10.3.26. stop-slapd (Stops the Directory Server)
ps
command because it could sometimes be that the script returned a message while the shutdown process was still on-going, resulting in a confusing message.
stop-dirsrv
and automatically supplies the instance name to the stop-dirsrv
script.
Note
stop-slapd
There are no options for this script.
Table 10.14. stop-slapd Exit Status Codes
Exit Code | Description |
---|---|
0 | Server stopped successfully. |
1 | Server could not be stopped. |
2 | Server was already stopped. |
10.3.27. suffix2instance (Maps a Suffix to a Backend Name)
Note
suffix2instance
[
-s suffix
]
Table 10.15. suffix2instance Options
Option | Description |
---|---|
-s | Suffix to be mapped to the back end. |
10.3.28. upgradednformat
Note
setup-ds-admin.pl -u
when a Directory Server instance is upgraded. It is not likely that this script will need to be run manually.
Note
upgradednformat
[
-N
]
-n backendInstance
[
-a /path/to/database/directory
]
Either the -N
or both -n
and -a
must be specified.
Table 10.16. upgradednformat Options
Option | Description |
---|---|
-a /path/to/database/directory | Gives the full path to the database directory. |
-N | Checks whether any DNs in the database need to be updated. |
-n backendInstance | Gives the name of the database containing the entries to index. |
10.3.29. vlvindex (Creates Virtual List View Indexes)
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.
Note
vlvindex
[
-d debugLevel
] [
-n backendInstance
] | [
-s suffix
] [
-T vlvTag
]
Either the -n
or the -s
option must be specified.
Table 10.17. vlvindex Options
Option | Description |
---|---|
-d debugLevel | Specifies the debug level to use during index creation. Debug levels are defined in Section 3.1.1.76, “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 Red Hat 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. |