|
| Sun ONE Directory Server 5.2 Reference Manual |
Chapter 2 Command-Line Scripts
This chapter provides information on the scripts you can use to back up and restore your database. These scripts are a shortcut to executing the ns-slapd interface commands, documented in Appendix B "ns-slapd and slapd.exe Command-Line Utilities."
This chapter is divided into the following sections:
Command-Line Scripts Quick Reference
All scripts and commands, with the exception of admin_ip.pl and schema_push.pl, can be accessed in the following way:
Solaris Packages
Using the /usr/sbin/directoryserver name command
Other platforms
As the /ServerRoot/slapd-serverID/name script or .bat file
The admin_ip.pl script is located in the /ServerRoot/shared/bin folder. The schema_push.pl script is located in /ServerRoot/slapd-serverID/ and must be run from this location on all platforms.
Refer to the tables below for the name and purpose of each script.
When scripts request either a directory name or a file name, always provide the absolute path. The scripts assume that you want to use the dse.ldif file located in:
/ServerRoot/slapd-serverID/config
Caution
To execute the Perl Scripts, you must change to the directory in which the command-line utilities are stored. Although it is possible to set command-path and library-path variables to execute these scripts, this is not the recommended procedure. You run the risk of disrupting the correct execution of other scripts and utilities and of compromising the security of the system, particularly when you have more than one server version installed.
The same procedure applies to the ldapsearch, ldapmodify, ldapdelete, ldapcompare and ldif command-line utilities. For more information on these command-line utilities, see the Directory Server Resource Kit Tools Reference.
Note also that when you are running the Perl scripts on Windows machines, the path environment variable must contain the Perl executable (perl.exe) file. You must therefore run the scripts from the following directory on Windows:
\ServerRoot\bin\slapd\admin\bin
The following table lists command-line script names, which are also option names for the /usr/sbin/directoryserver command (Solaris packages.)
The following table gives the names of Perl scripts and the equivalent command for Solaris packages.
Shell and Batch Scripts
Some of the shell and batch scripts can be executed while the server is running. Others require that the server is stopped. The description of each script below indicates whether the server must be stopped, or if it can continue to run while you execute the script. When a Shell or Batch script has a Perl equivalent, a cross-reference to the section describing the equivalent Perl script is provided.
bak2db (Restore Database From Backup)
Restores the database from the most recent archived backup. To run this script the server must be stopped.
Syntax
Platform
Syntax
Solaris Packages
directoryserver bak2db backup_directory
Other platforms
bak2db backup_directory
For information on the equivalent Perl script, see "bak2db.pl (Restore Database From Backup)". For more information on restoring databases, see Chapter 3, "Populating Directory Contents" in the Sun ONE Directory Server Administration Guide.
db2bak (Create Backup of Database)
Creates a backup of the current database contents. This script can be executed while the server is running.
Syntax
Platform
Syntax
Solaris Packages
directoryserver db2bak [backup_directory]
Other platforms
db2bak [backup_directory]
For information on the equivalent Perl script, refer to "db2bak.pl (Create Backup of Database)".
db2ldif (Export Database Contents to LDIF)
Exports the contents of the database to LDIF. This script can be executed while the server is still running.
For information on the equivalent Perl script, refer to "db2ldif.pl (Export Database Contents to LDIF)".
For the shell and batch scripts, the script runs the slapd (Windows) or ns-slapd (UNIX) command-line utility with the ldif2db keyword.
Syntax
Options
getpwenc (Print Encrypted Password)
Prints the encrypted form of a password using one of the server's encryption algorithms. If a user cannot log in, you can use this script to compare the user's password to the password stored in the directory.
Syntax
Platform
Syntax
Solaris Packages
/serverRoot/slapd-serverID/getpwenc storagescheme clearpassword
Other platforms
getpwenc storagescheme clearpassword
Options
There are no options for this script.
For more information on the different storage schemes such as SSHA, SHA, CRYPT, and CLEAR, see Chapter 7, "User Account Management" in the Sun ONE Directory Server Administration Guide.
ldif2db (Import)
Runs the slapd (Windows) or ns-slapd (UNIX) command-line utility with the ldif2db keyword. To run this script the server must be stopped.
For information on the equivalent Perl script, see "ldif2db.pl (Import)".
Note
- ldif2db supports LDIF version 1 specifications. You can load an attribute using the :< URL specifier notation. For example:
jpegphoto:< file:///tmp/myphoto.jpg
Although the official notation requires three ///, the use of one / is tolerated. For more information on the LDIF format, see Appendix E "LDAP Data Interchange Format".
- The default behavior of a read-write replica that has been initialized either online or offline from a backup or an LDIF file, is NOT to accept client update requests. The replica will remain in read-only mode and refer any updated operations to other suppliers in the topology until the administrator does one of the following:
- changes the duration of the read-only mode default period using the ds5referralDelayAfterInit attribute
- manually resets the server to read-write mode using the ds5BeginReplicaAcceptUpdates attribute (once the replica has completely converged with the other suppliers in the topology)
The second option is advised because it does not present non-convergence risks. For more information, refer to Chapter 8, "Managing Replication" in the Sun ONE Directory Server Administration Guide.
Syntax
Options
Note You must specify either the -n or the -s option (or both).
ldif2ldap (Perform Import Operation Over LDAP)
Performs an import operation over LDAP to the Directory Server. To run this script the server must be running.
Syntax
Platform
Syntax
Solaris Packages
directoryserver ldif2ldap -D rootDN -w password -f filename
Other platforms
ldif2ldap -D rootDN -w password -f filename
Options
monitor (Retrieve Monitoring Information)
Retrieves performance monitoring information using the ldapsearch command-line utility.
Syntax
Platform
Syntax
Solaris Packages
directoryserver monitor
Other platforms
monitor
Options
There are no options for this script.
For more information on the ldapsearch command-line utility, see Chapter 1 "Command-Line Utilities."
restart-slapd (Restart Directory Server)
Restarts Directory Server.
Syntax
Platform
Syntax
Solaris Packages
directoryserver restart
Other platforms
restart-slapd
Options
There are no options for this script.
Exit Status
0: Server restarted successfully.
1: Server could not be started.
2: Server restarted successfully but was already stopped.
3: Server could not be stopped.
restoreconfig (Restore Administration Server Configuration)
By default, restores the most recently saved Administration Server configuration information to the NetscapeRoot suffix under the following directory:
/ServerRoot/slapd-serverID/config
To restore the Administration Server configuration:
- Stop Directory Server
- Run the restoreconfig script
- Restart Directory Server
- Restart the Administration Server for the changes to be taken into account.
Syntax
Platform
Syntax
Solaris Packages
directoryserver restoreconfig
Other platforms
restoreconfig
Options
There are no options for this script.
saveconfig (Save Administration Server Configuration)
Saves the Administration Server configuration information to the following directory
/ServerRoot/slapd-serverID/confbak
:This script will run only if the server is running.
Syntax
Platform
Syntax
Solaris Packages
directoryserver saveconfig
Other platforms
saveconfig
Options
There are no options for this script.
start-slapd (Start Directory Server)
Starts Directory Server.
Syntax
Platform
Syntax
Solaris Packages
directoryserver start
Other platforms
start-slapd
Options
There are no options for this script.
Exit Status
0: Server started successfully.
1: Server could not be started.
2: Server was already started.
stop-slapd (Stop Directory Server)
Stops Directory Server.
Syntax
Platform
Syntax
Solaris Packages
directoryserver stop
Other platforms
stop-slapd
Options
There are no options for this script.
Exit Status
0: Server stopped successfully.
1: Server could not be stopped.
2: Server was already stopped.
suffix2instance (Map Suffix to Backend Name)
Maps a suffix to a backend name.
Syntax
Platform
Syntax
Solaris Packages
directoryserver suffix2instance {-s suffix}
Other platforms
suffix2instance {-s suffix}
Options
Option
Meaning
-s
The suffix to be mapped to the backend.
vlvindex (Create Virtual List View (VLV) Indexes)
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 you view search results. Using VLV indexes, you can organize search results alphabetically or in reverse alphabetical order, and you can scroll through the list of results. VLV index configuration must already exist prior to running this script.
Syntax
Platform
Syntax
Solaris Packages
directoryserver vlvindex options
Other platforms
vlvindex options
options
[-d debug_level] [-n backend_instance] [-s suffix]
[-T VLVTag]Options
Option
Meaning
-d
Specifies the debug level to use during index creation. Debug levels are defined in "nsslapd-errorlog-level (Error Log Level)".
-n
Name of the database containing the entries to index.
-s
Name of the suffix containing the entries to index.
-T
VLV index identifier to use to create VLV indexes. You can use the console to specify VLV index identifier for each database supporting your directory tree, as described in the Sun ONE Directory Server Administration Guide. You can define additional VLV tags by creating them in LDIF, and adding them to Directory Server's configuration, as described in the Sun ONE Directory Server Administration Guide. In any case, we recommend you use the dn of the entry for which you want to accelerate the search sorting.
Note You must specify either the -n or the -s option.
Perl Scripts
admin_ip.pl (Change IP Address)
When your system's IP address changes, you must update the local Administration Server configuration file and the configuration directory. If you do not enter the new IP address in these locations, you will not be able to start the Administration Server.
A Perl script is provided to help you update these two configurations. The script changes the IP address for an instance of Administration Server in both the local.conf file and the configuration directory. The script is called admin_ip.pl and is located in the serverRoot/shared/bin folder.
Usage
To run admin_ip.pl, follow the instructions for UNIX or Windows systems as appropriate:
On UNIX Systems
In the serverRoot/shared/bin folder, type the following:
admin_ip.pl Directory_Manager_DN Directory_Manager_password old_IP new_IP [port]
The old IP address is saved in a file called local.conf.old.
On Windows
From the command line go to the serverRoot/shared/bin folder and type the following:
../../install/perl admin_ip.pl Directory_Manager_DN Directory_Manager_password old_IP new_IP [port]
The old IP address is saved in a file called local.conf.old.
bak2db.pl (Restore Database From Backup)
The perl script bak2db.pl creates an entry in the directory that launches this dynamic task. An entry is generated based upon the values you provide for each option.
Syntax
Platform
Syntax
Solaris Packages
directoryserver bak2db-task options
Other platforms
bak2db.pl options
options
[-v] -D rootDN {-w password | -w - | -j filename }
-a backup_directory [-t databasetype]Options
db2bak.pl (Create Backup of Database)
The perl script db2bak.pl creates an entry in the directory that launches this dynamic task. An entry is generated based upon the values you provide for each option.
Syntax
Platform
Syntax
Solaris Packages
directoryserver db2bak-task options
Other platforms
db2bak.pl options
options
[-v] -D rootDN {-w password | -w - | -j filename }
-a backup_directory [-t databasetype]Options
db2index.pl (Create and Generate Indexes)
Creates and generates the new set of indexes to be maintained following the modification of indexing entries in the cn=config configuration file. Note that indexes are generated only for those attributes that are present in the database configuration as index attributes.
Syntax
Options
Note This perl script db2index.pl creates an entry in the directory that launches this dynamic task. An entry is generated based upon the values you provide for each option.
db2ldif.pl (Export Database Contents to LDIF)
Exports the contents of the database to LDIF. This Perl script creates an entry in the directory that launches this dynamic task. The entry is generated based upon the values you provide for each option. The * indicates that multiple occurrences are allowed.
Syntax
Options
ldif2db.pl (Import)
To run this Perl script, the server must be running. This script creates an entry in the directory that launches this dynamic task. The entry is generated based upon the values you provide for each option.
Syntax
Options
migrateInstance5 (Migrate to Directory Server 5.x)
The migrateInstance5 Perl script (note that this is a Perl script despite the fact that it does not have the .pl extension) migrates a 4.x Directory Server to Directory Server 5.x. It can also be used to upgrade from Directory Server 5.0 or 5.1 to Directory Server 5.2.
When you run this script, it migrates the configuration files or configuration entries, database instances and schema with minimum manual intervention. The migrateInstance5 script calls on the migrateTo5 script, which then executes the migration.
For complete information on the configuration parameters and attributes that are migrated, see Chapter 6 "Migration From Earlier Versions."
Before performing the migration, check that the user-defined variables contain the following associated values, where ServerRoot is the path to where Sun ONE Directory Server 5.2 is installed:
$PERL5LIB
ServerRoot/bin/slapd/admin/bin
PATH
ServerRoot/bin/slapd/admin/bin
Syntax
migrateInstance5 -D rootDN {-w password | -w - | -j filename }
-n backend_instance -p port -o 4.xInstancePath -n 5.xInstancePath [-t] [-L]Options
ns-accountstatus.pl (Establish Account Status)
Provides account status information to establish whether an entry or group of entries is inactivated or not.
Syntax
Platform
Syntax
Solaris Packages
directoryserver account-status options
Other platforms
ns-accountstatus.pl options
options
[-D rootDN] {-w password | -w - | -j filename }
[-h host] [-p port] -I DNOptions
ns-activate.pl (Activate an Entry or Group of Entries)
Activates an entry or group of entries.
Syntax
Platform
Syntax
Solaris Packages
directoryserver account-activate options
Other platforms
ns-activate.pl options
options
[-D rootDN] {-w password | -w - | -j filename }
[-h host] [-p port] -I DNOptions
ns-inactivate.pl (Inactivate an Entry or Group of Entries)
Inactivates, and thus locks, an entry or group of entries.
Syntax
Platform
Syntax
Solaris Packages
directoryserver account-inactivate options
Other platforms
ns-inactivate.pl options
options
[-D rootDN] {-w password | -w - | -j filename }
[-h host] [-p port] -I DNOptions
schema_push.pl
When schema modifications are made manually (by editing the .ldif files directly), this script should be run to update the modification time used by replication. This ensures that the modified schema are replicated to the consumers. Once the script has been run, you must restart the server to trigger the schema replication.
Syntax
/ServerRoot/slapd-serverID/schema_push.pl