---

dsadm

Manages a Directory Server instance

Synopsis

install-path/bin/dsadm
subcommand [global-options] [subcommand-options]
 [subcommand-operands]

Description

The dsadm command is the local administration command for Directory Server instances. Use the dsadm command with any of the subcommands described in this man page.

While using the dsadm command, you may be required to stop the server depending upon the subcommands that are used with dsadm. The dsadm command must be run from the local machine where the server instance is located. This command must be run by the username that is the operating system owner of the server instance, or by root.

Subcommands

The following subcommands are supported:

dsadm add-cert [-Ci] [-W CERT_PW_FILE] INSTANCE_PATH CERT_ALIAS CERT_FILE

Adds a certificate to the certificate database.

dsadm add-selfsign-cert [-i] [-W CERT_PW_FILE] [-S DN] [--phone PHONE] [--email EMAIL] ... [--dns DOMAIN] ... [--validity DURATION] [--keysize SIZE] [--sigalg SIGALG] INSTANCE_PATH CERT_ALIAS

OR

dsadm add-selfsign-cert [-i] [-W CERT_PW_FILE] [--name NAME [--org ORG] [--org-unit ORG-UNIT] [--city CITY] [--state STATE] [--country COUNTRY]] [--phone PHONE] [--email EMAIL] ... [--dns DOMAIN] ... [--validity DURATION] [--keysize SIZE] [--sigalg SIGALG] INSTANCE_PATH CERT_ALIAS

Creates a self-signed certificate and adds it to the certificate database.

dsadm analyze-indexes [-bRi] [-o FILE] INSTANCE_PATH SUFFIX_DN

Analyzes indexes and displays statistics on their values.

dsadm autostart [--off [--v6]] [-i] INSTANCE_PATH

Enables or disables Directory Server instance startup at system boot. This command is only available if you installed native packages. This command must be run as root.

dsadm backup [-f FLAG] ... INSTANCE_PATH ARCHIVE_DIR

Creates a backup archive of the Directory Server instance.

dsadm create [-Bi] [-u USER_NAME -g GROUP_NAME] [-h HOST_NAME] [-p PORT] [-P SSL_PORT] [-D DN] [-w PW_FILE] INSTANCE_PATH

Creates a Directory Server instance.

dsadm delete INSTANCE_PATH

Deletes a Directory Server instance.

dsadm disable-service [-T TYPE] [--v6] INSTANCE_PATH

Disables a Directory Server instance from being managed as a service. This command is available on Windows and Solaris 10 distributions only. The command must be run as root.

dsadm enable-service [-T TYPE] INSTANCE_PATH

Enables a Directory Server instance to be managed as a service. This command is available on Windows and Solaris 10 distributions only. The command must be run as root.

dsadm export [-biQ] [-s DN] ... [-x DN] ... [-f FLAG] ... [-y [-W CERT_PW_FILE]] INSTANCE_PATH SUFFIX_DN [SUFFIX_DN ...] LDIF_FILE

OR

dsadm export [-biQ] [-s DN] ... [-x DN] ... [-f FLAG] ... [-y [-W CERT_PW_FILE]] INSTANCE_PATH SUFFIX_DN [ SUFFIX_DN ...] GZ_LDIF_FILE

Exports suffix data to LDIF format as a compressed or uncompressed exported file.

dsadm export-cert [-i] [-W CERT_PW_FILE] [-o OUTPUT_FILE] [-O OUTPUT_PW_FILE] INSTANCE_PATH CERT_ALIAS

Exports an encrypted copy of the certificate and its public and private keys from the certificate database.

dsadm get-flags INSTANCE_PATH [FLAG ...]

Displays the flag values for the Directory Server instance.

dsadm import [-biK] [-x DN] ... [-f FLAG=VAL] ... [-y [-W CERT_PW_FILE]] INSTANCE_PATH LDIF_FILE [LDIF_FILE ...] SUFFIX_DN

OR

dsadm import [-biK] [-x DN] ... [-f FLAG=VAL] ... [-y [-W CERT_PW_FILE]] INSTANCE_PATH GZ_LDIF_FILE [GZ_LDIF_FILE...] SUFFIX_DN

Populates an existing suffix with LDIF data from a compressed or uncompressed LDIF file.

dsadm import-cert [-i] [-W CERT_PW_FILE] [-I INPUT_PW_FILE] INSTANCE_PATH CERT_FILE

Adds a new certificate and its keys to the certificate database.

dsadm import-selfsign-cert [-i] [-W CERT_PW_FILE] [-I INPUT_PW_FILE] INSTANCE_PATH CERT_FILE

Adds a new self-signed certificate and its keys to the certificate database.

dsadm info INSTANCE_PATH

Displays Directory Server instance status and some configuration information.

dsadm list-certs [-Ci] [-W CERT_PW_FILE] INSTANCE_PATH

Lists all certificates in the certificate database.

dsadm list-instance-dirs INSTANCE_PATH

Lists all directories that comprise a Directory Server instance.

dsadm list-running-instances [--all]

Displays running instances on a host. By default, the only instances that are launched by the same installation as dsadm are listed.

dsadm reindex [-bl] -t ATTR_INDEX [-t ATTR_INDEX ...] INSTANCE_PATH SUFFIX_DN

Regenerates existing indexes.

dsadm remove-cert [-i] [-W CERT_PW_FILE] INSTANCE_PATH CERT_ALIAS

Removes a certificate from the certificate database. The instance must be stopped before running this command.

dsadm renew-cert [-i] [-W CERT_PW_FILE] INSTANCE_PATH CERT_ALIAS CERT_FILE

Replaces a certificate, but keeps the existing private key. The instance must be stopped before running this command.

dsadm renew-selfsign-cert [-i] [-W CERT_PW_FILE] [--validity DURATION] INSTANCE_PATH CERT_ALIAS

Renews a self-signed certificate in the certificate database. The instance must be stopped before running this command.

dsadm repack [-b backend][ -T FILE_TYPE ...] INSTANCE_PATH SUFFIX_DN [SUFFIX_DN...]

Repacks or compacts an existing suffix. The -b option enables you to specify the name of the backend instead of the suffix name. At least one suffix DN or one backend name must be specified. Can specify which type of file needs to be repacked. Possible values are entries|indexes|changelog. The instance must be stopped before running this command.

dsadm request-cert [-i] [-W CERT_PW_FILE] {-S DN | --name NAME [--org ORG] [--org-unit ORG-UNIT] [--city CITY] [--state STATE] [--country COUNTRY]} [--phone PHONE] [--email EMAIL] ... [--dns DOMAIN] ... [--keysize KEYSIZE] [--sigalg SIGALG] [-F FORMAT] [-o OUTPUT_FILE] INSTANCE_PATH

Generates a certificate request.

dsadm restart [-i] [--schema-push] [-W CERT_PW_FILE] INSTANCE_PATH

Restarts a Directory Server instance.

dsadm restore [-i] [-f FLAG] INSTANCE_PATH ARCHIVE_DIR

Restores Directory Server instance from a backup archive.

dsadm rewrite[-b] [-f FLAG=VAL] ... INSTANCE_PATH SUFFIX_DN

Rewrites all entries according to the current database format, and depending upon the flag.

dsadm set-flags [-i] [-W CERT_PW_FILE] INSTANCE_PATH FLAG=VAL [FLAG=VAL ...]

Sets flags for a Directory Server instance.

dsadm show-access-log [-A DURATION] INSTANCE_PATH

OR

dsadm show-access-log [-L LAST_LINES] INSTANCE_PATH

Displays the contents of the access log.

dsadm show-cert [-i] [-W CERT_PW_FILE] [-o OUTPUT_FILE] [-F FORMAT] INSTANCE_PATH [CERT_ALIAS]

Displays a certificate.

dsadm show-error-log [-A DURATION] INSTANCE_PATH

OR

dsadm show-error-log [-L LAST_LINES] INSTANCE_PATH

Displays the contents of the error log.

dsadm start [-Ei] [--schema-push] [-W CERT_PW_FILE] INSTANCE_PATH

Starts a Directory Server instance.

dsadm stop [--force] INSTANCE_PATH

Stops a Directory Server instance.

dsadm stop-running-instances [-i] [--force]

Stops Directory Server instances. The instances launched by the same installation as dsadm will be stopped.

dsadm upgrade [-i] INSTANCE_PATH

Upgrades Directory Server instance from versions 6.x, 7.0, and 11g R1 to version 11.1.1.7.0.

Global Options

The following options are global, and are applicable to all commands and subcommands. The global options must follow their respective commands or subcommands to execute successfully.

--?

--help

Displays help information for a command or subcommand.

-V

--version

Displays the current version of dsadm. The version is provided in the format year.monthday.time DISTRIB. So version number 2009.1004.0035 was built on October 4th, 2009 at 00h35. DISTRIB indicates the distribution type. NAT refers to the native packages version. ZIP refers to the ZIP version. If the components used by dsadm are not aligned, the version of each individual component is displayed.

-v

--verbose

Displays instructions for accessing verbose help.

Subcommands Options

The following options are applicable to the subcommands where they are specified.

-A DURATION

--max-age DURATION

Specifies the maximum age of lines to be returned from the access log or the error log. For example, to search for all entries younger than 24 hours, use -A 24h.

--all

Displays running instances from any installation path.

-B

--below

Creates the Directory Server instance in an existing directory, specified by the INSTANCE_PATH. The existing directory must be empty. On UNIX machines, the user who runs this command must be root, or must be the owner of the existing directory. If the user is root, the instance will be owned by the owner of the existing directory.

-b

--backend

Enables to specify backend name instead of SUFFIX_DN.

--C

--ca

Specifies a Certificate Authority certificate is to be used, or that the command should display information about CA certificates.

--city CITY

Adds L=CITY to the subject DN. Default is none.

--country COUNTRY

Adds C=COUNTRY to the subject DN. Default is none.

-D DN

--rootDN DN

Defines the Directory Manager DN. The default is cn=Directory Manager.

--dns DOMAIN

Specifies DOMAIN as DNS subject alternate name extension

-E

--safe

Starts Directory Server with the configuration used at the last successful startup.

--email EMAIL

Specifies EMAIL as email subject alternate name extension

--force

When used with stop-running-instances, the command forcibly shuts down all the running server instances that are created using the same dsadm installation. When used with stop, the command forcibly shuts down the instance even if the instance is not initiated by the current installation.

-F FORMAT

--format FORMAT

Specifies output format. For dsadm request-cert, the default is der, and the other possible output format is ascii. .For dsadm show-cert, the default is readable, and other possible output formats are ascii and der.

-f FLAG

--flags FLAG or FLAG=VAL

Customized values for options.

Possible flags for the dsadm backup subcommand are as follows.

verify-db

Check integrity of the backed up database.

no-recovery

Skip recovery of the backed up database.

Possible flags for the dsadm export subcommand are as follows.

compression-level

Compression level to use when a GZ_LDIF_FILE is given as operand. Default level is 3, level range is from 1 to 9.

minimal-encode

Perform minimal base64 encoding.

multiple-output-file

Generate multiple LDIF output files.

not-export-unique-id

Do not export the unique ID generated on import.

not-folded-output

Do not fold long lines.

no-num-version

Delete the initial line specifying the LDIF version, version: 1, for backward compatibility.

not-print-entry-ids

Do not include entry IDs in the LDIF output.

use-main-db-file

Only export from the main database file.

Possible flags for the dsadm import subcommand are as follows.

chunk-size

Merge chunk size.

incremental-output-file

Import LDIF generated during incremental import.

purge-csn

Purge the Change Sequence Number (CSN). The purge-csn flag is set to off by default. Setting the purge-csn to on prevents old CSN data from being imported by the dsadm import operation. This reduces the size of entries by removing traces of previous updates.

Possible flags for the dsadm restore subcommand are as follows.

move-archive

Performs restore by moving files in place of copying them.

Possible flags for the dsadm rewrite subcommand are as follows.

purge-csn

Purge the Change Sequence Number (CSN). The purge-can flag is set to off by default. Setting the purge-csn to on prevents old CSN data from being kept by the operation. This reduces the size of entries by removing traces of previous updates.

convert-pwp-opattr-to-DS6

Converts DS5 mode password policy operational attributes to run in D6-mode.

The convert-pwp-opattr-to-DS6 flag is set to off by default. When a server is DS6-migration-mode enabled, setting convert-pwp-opattr-to-DS6 to on, permits DS5 mode password policy operational attributes to be migrated using their ID (Internet Draft) and to run in DS6-mode. DS6-migration-mode is the only mode in which you can migrate operational attributes safely. When the migration has been successfully performed, run the server in DS6-mode when you are ready.

Note that the dsadm rewrite -f convert-pwp-opattr-to-DS6=on subcommand must be run on all servers in the topology that are in DS6-migration-mode in order to migrate their DS5 mode password policy operational attributes.

-g GROUP_NAME

--groupname GROUP_NAME

Sets the server instance owner's group ID. The default is the user's current UNIX group. This option is not available on Windows.

-h HOST_NAME

--hostname HOST_NAME

Specifies the hostname. The default is the name of the current host system.

-I INPUT_PW_FILE

--input-pwd-file INPUT_PW_FILE

Reads the input file password in the INPUT_PW_FILE file. The default is a prompt for password.

-i

--no-inter

Does not prompt for confirmation before performing the operation.

-K

--incremental

Specifies that the content of the imported LDIF file is appended to the existing LDAP entries. If this option is not specified, the contents of the imported file replace the existing entries.

--keysize SIZE

Specifies the length of private key.

-L LAST_LINES

--last-lines LAST_LINES

Specifies the number of lines to be returned from the access log or the error log. LAST_LINES must be an integer. For example, to return the last 50 lines, use -L 50. If no value is specified, the default number of lines returned is 20.

--l

--vlv

Specifies VLV (browsing) index.

--name NAME

Adds CN=NAME to the subject DN.

-o FILE

--cache-file FILE

Reads raw index data from FILE and writes them if necessary. The default location is: INSTANCE_PATH/logs/db_stat_DBNAME.

--O OUTPUT_PW_FILE

--output-pwd-file OUTPUT_PW_FILE

Reads the output password from the OUTPUT_FILE file. The default is a prompt for password.

--o OUTPUT_FILE

--output OUTPUT_FILE

Stores the command results in the OUTPUT_FILE file. The default is stdout, standard output.

--off

Disables server instance startup at system boot.

--org ORG

Adds O=ORG to the subject DN. The default is none.

--org-unit ORG-UNIT

Adds OU=ORG-UNIT to the subject DN. The default is none.

--P SSL_PORT

--ssl-port SSL_PORT

Specifies the secure SSL port for LDAP traffic. The default is 636 if dsadm is run by the root user, or 1636 if dsadm is run by a non-root user.

--p PORT

--port PORT

Specifies the port for LDAP traffic. The default is 389 if dsadm is run by the root user, or 1389 if dsadm is run by a non-root user.

--phone PHONE

Sets the contact phone number to PHONE.

--Q --no-repl

Specifies that additional data needed for replication is not included in the export.

-R

--rebuild-data

Overwrites current raw index data if it already exists.

--S DN

--subject DN

Specifies the subject DN. The default depends on the subcommand used, and is either CN=hostname or CN=CERT_ALIAS.

--s DN

--include DN

Exports data from suffix DN.

--schema-push

Ensures manually modified schema is replicated to consumers.

--sigalg SIGALG

Specifies certificate signature algorithm. The default algorithm is SHA1. The other valid values are MD5 and SHA256.

--state STATE

Adds ST=STATE to the subject DN. Default is none.

--T TYPE

--type TYPE

Service type. Can be SMF when using Solaris 10, or WIN_SERVICE when using Windows.

--t ATTR_INDEX

--attr ATTR_INDEX

Specifies attribute index ATTR_INDEX

--u USER_NAME

--username USER_NAME

Sets the server instance owner user ID. The default is the current UNIX user name. This option is not available on Windows.

--v6

Specifies that the version Directory Server instance is 6.x.

--validity DURATION

Sets validity of the certificate to DURATION months.

--W CERT_PW_FILE

--cert-pwd-file CERT_PW_FILE

Reads certificate database password from CERT_PW_FILE. The default is to prompt for password.

--w PW_FILE

--pwd-file PW_FILE

Sets the password file for the Directory Manager (-D). The default is to prompt for password.

--x DN

--exclude DN

Excludes the specified DN from the command.

--y

--decrypt-attr

Decrypts encrypted attributes.

Operands

The following operands are supported:

ARCHIVE_DIR

Specifies the path to the backup of the Directory Server instance.

CERT_ALIAS

Certificate alias name. A user-specified name that identifies a certificate.

CERT_FILE

Specifies the file that contains the certificate.

FLAG

Specifies a flag that represents a property operand when using the command dsadm get-flags. Possible flag: cert-pwd-prompt.

FLAG=VAL

Specifies a property flag operand and its value when using the command dsadm set-flags.

cert-pwd-prompt flag. Possible values are: off on. Default: off. By default the dsadm command generates a certificate database password when creating a server instance. This password is stored, allowing dsadm to access the certificate database when necessary, for example, when the server starts listening for SSL connections. When the cert-pwd-prompt flag is changed to on, the dsadm command prompts for the certificate database password when needed.

dsadm-startup-timeout flag. Integer set to specify the number of seconds dsadm is waiting for the server to start or stop.

dsadm-shutdown-timeout flag. Integer set to specify the number of seconds dsadm is waiting for the server to start or stop.

GZIP_LDIF_FILE

Path and filename for file in gzip compressed LDIF format.

INSTANCE_PATH

Path of the Directory Server instance.

LDIF_FILE

Filename of LDIF file.

SUFFIX_DN

Suffix DN (Distinguished name).

Exit Status

The following exit status values are returned:

0

Successful completion.

non-zero

An error occurred.

Examples

The following examples show how the dsadm command is used.

Example 1   Creating a Directory Server Instance

$ dsadm create -p 6389 -P 6636 /local/dsInst

This command creates the server instance files in the directory /local/dsInst. The server instance is owned by the UNIX user who creates the command.

In this example, the LDAP port is specified as 6389, and the secure port is specified as 6636. If you do not specify port numbers, the default port numbers 389 and 636 (for root user) or 1389 and 1636 (for not-root user) are used. If you do not specify port numbers and the default port numbers are already being used, the dsadm create command aborts. The dsadm create command also aborts if you specify the port numbers that are already in use.

Example 2   Starting a Directory Server Instance

The server instance path is /local/dsInst.

$ dsadm start /local/dsInst

Example 3   Getting Information About a Directory Server instance

This command shows information such as the owner, ports, and current state of the server instance. The instance path is /local/dsInst.

$ dsadm info /local/dsInst

Example 4   Importing an LDIF File

Import an LDIF file, specifying that no user confirmation is required, and giving the suffix DN.

$ dsadm import -i /local/dsInst /local/dsInst/ldif/example.ldif \
dc=example,dc=com

Example 5   Exporting an LDIF File

Export a suffix to an LDIF file.

$ dsadm export -x ou=People,dc=example,dc=com /local/dsInst \ 
dc=example,dc=com /local/dsInst/ldif/export.ldif

This command shows all data in the suffix dc=example,dc=com, excluding data in the subsuffix ou=People,dc=example,dc=com

Example 6   Backing Up a Directory Server Instance

This command backs up the suffix data. The instance path is /local/dsInst and the archive directory is /local/dsbackup/20060722 .

$ dsadm backup /local/dsInst /local/dsbackup/20060722

Example 7   Regenerating Attribute Indexes

To regenerate the existing cn and uid indexes:

$ dsadm reindex -t cn -t uid /local/dsInst dc=example,dc=com

Example 8   Renewing a Certificate

Use the following command to renew an existing server certificate with a new server certificate from your Certificate Authority.

$ dsadm renew-cert /local/dsInst cert_alias /local/certfiles/new-cert

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWdsee7
Stability Level	Evolving

See Also

dsconf(1M)