dsctl - Man Page

dsctl [-h] [-v] [-j] [-l] [instance] {restart,start,stop,status,remove,db2index,db2bak,db2ldif,dbverify,bak2db,ldif2db,backups,ldifs,tls,healthcheck,get-nsstate,ldifgen,dsrc,cockpit,dblib} ...

dsctl restart

Restart an instance of Directory Server, if it is running: else start it.

dsctl start

Start an instance of Directory Server, if it is not currently running

dsctl stop

Stop an instance of Directory Server, if it is currently running

dsctl status

Check running status of an instance of Directory Server

dsctl remove

Destroy an instance of Directory Server, and remove all data.

dsctl db2index

Initialise a reindex of the server database. The server must be stopped for this to proceed.

dsctl db2bak

Initialise a BDB backup of the database. The server must be stopped for this to proceed.

dsctl db2ldif

Initialise an LDIF dump of the database. The server must be stopped for this to proceed.

dsctl dbverify

Perform a db verification. You should only do this at direction of support

dsctl bak2db

Restore a BDB backup of the database. The server must be stopped for this to proceed.

dsctl ldif2db

Restore an LDIF dump of the database. The server must be stopped for this to proceed.

dsctl backups

List backup's found in the server's default backup directory

dsctl ldifs

List all the LDIF files located in the server's LDIF directory

dsctl tls

Manage TLS certificates

dsctl healthcheck

Run a healthcheck report on a local Directory Server instance. This is a safe and read-only operation.  Do not attempt to run this on a remote Directory Server as this tool needs access to local resources, otherwise the report may be inaccurate.

dsctl get-nsstate

Get the replication nsState in a human readable format

Replica DN:           The DN of the replication configuration entry Replica Suffix:       The replicated suffix Replica ID:           The Replica identifier Gen Time              The time the CSN generator was created Gen Time String:      The time string of generator Gen as CSN:           The generation CSN Local Offset:         The offset due to the local clock being set back Local Offset String:  The offset in a nice human format Remote Offset:        The offset due to clock difference with remote systems Remote Offset String: The offset in a nice human format Time Skew:            The time skew between this server and its replicas Time Skew String:     The time skew in a nice human format Seq Num:              The number of multiple csns within a second System Time:          The local system time Diff in Seconds:      The time difference in seconds from the CSN generator creation to now Diff in days/secs:    The time difference broken up into days and seconds Endian:               Little/Big Endian

dsctl ldifgen

LDIF generator to make sample LDIF files for testing

dsctl dsrc

Manage the .dsrc file

dsctl cockpit

Enable the Cockpit interface/UI

dsctl dblib

database library (i.e bdb/lmdb) migration

usage: dsctl [-v] [-j] [instance] restart [-h]

usage: dsctl [-v] [-j] [instance] start [-h]

usage: dsctl [-v] [-j] [instance] stop [-h]

usage: dsctl [-v] [-j] [instance] status [-h]

usage: dsctl [-v] [-j] [instance] remove [-h] [--do-it]

--do-it

By default we do a dry run. This actually initiates the removal of the instance.

usage: dsctl [-v] [-j] [instance] db2index [-h] [--attr [ATTR ...]] [backend]

backend

The backend to reindex. IE userRoot

--attr [ATTR ...]

The attribute's to reindex. IE --attr aci cn givenname

usage: dsctl [-v] [-j] [instance] db2bak [-h] [archive]

archive

The destination for the archive. This will be created during the db2bak process.

usage: dsctl [-v] [-j] [instance] db2ldif [-h] [--replication] [--encrypted]
                               backend [ldif]

backend

The backend to output as an LDIF. IE userRoot

ldif

The path to the ldif output location.

--replication

Export replication information, suitable for importing on a new consumer or backups.

--encrypted

Export encrypted attributes

usage: dsctl [-v] [-j] [instance] dbverify [-h] backend

backend

The backend to verify. IE userRoot

usage: dsctl [-v] [-j] [instance] bak2db [-h] archive

archive

The archive to restore. This will erase all current server databases.

usage: dsctl [-v] [-j] [instance] ldif2db [-h] [--encrypted] backend ldif

backend

The backend to restore from an LDIF. IE userRoot

ldif

The path to the ldif to import

--encrypted

Import encrypted attributes

usage: dsctl [-v] [-j] [instance] backups [-h] [--delete DELETE]

--delete DELETE

Delete backup directory

usage: dsctl [-v] [-j] [instance] ldifs [-h] [--delete DELETE]

--delete DELETE

Delete LDIF file

usage: dsctl [-v] [-j] [instance] tls [-h]
                           {list-ca,list-client-ca,show-server-cert,show-cert,generate-server-cert-csr,import-client-ca,import-ca,import-server-cert,import-server-key-cert,remove-cert,export-cert} ...

dsctl tls list-ca

list server certificate authorities including intermediates

dsctl tls list-client-ca

list client certificate authorities including intermediates

dsctl tls show-server-cert

Show the active server certificate that clients will see and verify

dsctl tls show-cert

Show a certificate's details referenced by it's nickname. This is analogous to certutil -L -d <path> -n <nickname>

dsctl tls generate-server-cert-csr

Generate a Server-Cert certificate signing request - the csr is then submitted to a CA for verification, and when signed you import with import-ca and import-server-cert

dsctl tls import-client-ca

Import a CA trusted to issue user (client) certificates. This is part of how client certificate authentication functions.

dsctl tls import-ca

Import a CA or intermediate CA for signing this servers certificates (aka Server-Cert). You should import all the CA's in the chain as required.  PEM bundles are accepted

dsctl tls import-server-cert

Import a new Server-Cert after the csr has been signed from a CA.

dsctl tls import-server-key-cert

Import a new key and Server-Cert after having been signed from a CA. This is used if you have an external csr tool or a service like lets encrypt that generates PEM keys externally.

dsctl tls remove-cert

Delete a certificate from this database. This will remove it from acting as a CA, a client CA or the Server-Cert role.

dsctl tls export-cert

Export a certificate to PEM or DER/Binary format.  PEM format is the default

usage: dsctl [-v] [-j] [instance] tls list-ca [-h]

usage: dsctl [-v] [-j] [instance] tls list-client-ca [-h]

usage: dsctl [-v] [-j] [instance] tls show-server-cert [-h]

usage: dsctl [-v] [-j] [instance] tls show-cert [-h] nickname

nickname

The nickname (friendly name) of the certificate to display

usage: dsctl [-v] [-j] [instance] tls generate-server-cert-csr
      [-h] [--subject SUBJECT] [alt_names ...]

alt_names

Certificate requests subject alternative names. These are auto-detected if not provided

--subject SUBJECT, -s SUBJECT

Certificate Subject field to use

usage: dsctl [-v] [-j] [instance] tls import-client-ca [-h] cert_path nickname

cert_path

The path to the x509 cert to import as a client trust root

nickname

The name of the certificate once imported

usage: dsctl [-v] [-j] [instance] tls import-ca [-h]
                                               cert_path
                                               nickname [nickname ...]

cert_path

The path to the x509 cert to import as a server CA

nickname

The name of the certificate once imported

usage: dsctl [-v] [-j] [instance] tls import-server-cert [-h] cert_path

cert_path

The path to the x509 cert to import as Server-Cert

usage: dsctl [-v] [-j] [instance] tls import-server-key-cert
      [-h] cert_path key_path

cert_path

The path to the x509 cert to import as Server-Cert

key_path

The path to the x509 key to import associated to Server-Cert

usage: dsctl [-v] [-j] [instance] tls remove-cert [-h] nickname

nickname

The name of the certificate to delete

usage: dsctl [-v] [-j] [instance] tls export-cert [-h] [--binary-format]
                                                 [--output-file OUTPUT_FILE]
                                                 nickname

nickname

The name of the certificate to export

--binary-format

Export certificate in DER/binary format

--output-file OUTPUT_FILE

The name for the exported certificate. Default name is the certificate nickname with an extension of ".pem" or ".crt"

usage: dsctl [instance] healthcheck [-h] [--list-checks] [--list-errors]
                                   [--dry-run] [--check CHECK [CHECK ...]]

--list-checks

List of known checks

--list-errors

List of known error codes

--dry-run

Do not execute the actual check, only list what would be done

--check CHECK [CHECK ...]

Areas to check. These can be obtained by --list-checks. Every element on the left of the colon (:) may be replaced by an asterisk if multiple options on the right are available.

usage: dsctl [instance] get-nsstate [-h] [--suffix SUFFIX] [--flip FLIP]

--suffix SUFFIX

The DN of the replication suffix to read the state from

--flip FLIP

Flip between Little/Big Endian, this might be required for certain architectures

usage: dsctl [-v] [-j] [instance] ldifgen [-h]
                               {users,groups,cos-def,cos-template,roles,mod-load,nested} ...

dsctl ldifgen users

Generate a LDIF containing user entries

dsctl ldifgen groups

Generate a LDIF containing groups and members

dsctl ldifgen cos-def

Generate a LDIF containing a COS definition (classic, pointer, or indirect)

dsctl ldifgen cos-template

Generate a LDIF containing a COS template

dsctl ldifgen roles

Generate a LDIF containing a role entry (managed, filtered, or indirect)

dsctl ldifgen mod-load

Generate a LDIF containing modify operations.  This is intended to be consumed by ldapmodify.

dsctl ldifgen nested

Generate a heavily nested database LDIF in a cascading/fractal tree design

usage: dsctl [-v] [-j] [instance] ldifgen users [-h] [--number NUMBER]
                                               [--suffix SUFFIX]
                                               [--parent PARENT] [--generic]
                                               [--start-idx START_IDX]
                                               [--rdn-cn] [--localize]
                                               [--ldif-file LDIF_FILE]

--number NUMBER

The number of users to create.

--suffix SUFFIX

The database suffix where the entries will be created.

--parent PARENT

The parent entry that the user entries should be created under. If not specified, the entries are stored under random Organizational Units.

--generic

Create generic entries in the format of "uid=user####". These entries are also compatible with ldclt.

--start-idx START_IDX

For generic LDIF's you can choose the starting index for the user entries. The default is "0".

--rdn-cn

Use the attribute "cn" as the RDN attribute in the DN instead of "uid"

--localize

Localize the LDIF data

--ldif-file LDIF_FILE

The LDIF file name. Default location is the server's LDIF directory using the name 'ldifgen.ldif'

usage: dsctl [-v] [-j] [instance] ldifgen groups [-h] [--number NUMBER]
                                                [--suffix SUFFIX]
                                                [--parent PARENT]
                                                [--num-members NUM_MEMBERS]
                                                [--create-members]
                                                [--member-parent MEMBER_PARENT]
                                                [--member-attr MEMBER_ATTR]
                                                [--ldif-file LDIF_FILE]
                                                NAME

NAME

The group name.

--number NUMBER

The number of groups to create.

--suffix SUFFIX

The database suffix where the groups will be created.

--parent PARENT

The parent entry that the group entries should be created under. If not specified the groups are stored under the suffix.

--num-members NUM_MEMBERS

The number of members in the group. Default is 10000

--create-members

Create the member user entries.

--member-parent MEMBER_PARENT

The entry DN that the members should be created under. The default is the suffix entry.

--member-attr MEMBER_ATTR

The membership attribute to use in the group. Default is "uniquemember".

--ldif-file LDIF_FILE

The LDIF file name. Default location is the server's LDIF directory using the name 'ldifgen.ldif'

usage: dsctl [-v] [-j] [instance] ldifgen cos-def [-h] [--type TYPE]
                                                 [--parent PARENT]
                                                 [--create-parent]
                                                 [--cos-specifier COS_SPECIFIER]
                                                 [--cos-template COS_TEMPLATE]
                                                 [--cos-attr [COS_ATTR ...]]
                                                 [--ldif-file LDIF_FILE]
                                                 NAME

NAME

The COS definition name.

--type TYPE

The COS definition type: "classic", "pointer", or "indirect".

--parent PARENT

The parent entry that the COS definition should be created under.

--create-parent

Create the parent entry

--cos-specifier COS_SPECIFIER

Used in a classic COS definition, this attribute located in the user entry is used to select which COS template to use.

--cos-template COS_TEMPLATE

The DN of the COS template entry, only used for "classic" and "pointer" COS definitions.

--cos-attr [COS_ATTR ...]

A list of attributes which defines which attribute the COS generates values for.

--ldif-file LDIF_FILE

The LDIF file name. Default location is the server's LDIF directory using the name 'ldifgen.ldif'

usage: dsctl [-v] [-j] [instance] ldifgen cos-template [-h] [--parent PARENT]
                                                      [--create-parent]
                                                      [--cos-priority COS_PRIORITY]
                                                      [--cos-attr-val COS_ATTR_VAL]
                                                      [--ldif-file LDIF_FILE]
                                                      NAME

NAME

The COS template name.

--parent PARENT

The DN of the entry to store the COS template entry under.

--create-parent

Create the parent entry

--cos-priority COS_PRIORITY

Sets the priority of this conflicting/competing COS templates.

--cos-attr-val COS_ATTR_VAL

defines the attribute and value that the template provides.

--ldif-file LDIF_FILE

The LDIF file name. Default location is the server's LDIF directory using the name 'ldifgen.ldif'

usage: dsctl [-v] [-j] [instance] ldifgen roles [-h] [--type TYPE]
                                               [--parent PARENT]
                                               [--create-parent]
                                               [--filter FILTER]
                                               [--role-dn [ROLE_DN ...]]
                                               [--ldif-file LDIF_FILE]
                                               NAME

NAME

The Role name.

--type TYPE

The Role type: "managed", "filtered", or "nested".

--parent PARENT

The DN of the entry to store the Role entry under

--create-parent

Create the parent entry

--filter FILTER

A search filter for gathering Role members. Required for a "filtered" role.

--role-dn [ROLE_DN ...]

A DN of a role entry that should be included in this role. Used for "nested" roles only.

--ldif-file LDIF_FILE

The LDIF file name. Default location is the server's LDIF directory using the name 'ldifgen.ldif'

usage: dsctl [-v] [-j] [instance] ldifgen mod-load [-h] [--create-users]
                                                  [--delete-users]
                                                  [--num-users NUM_USERS]
                                                  [--parent PARENT]
                                                  [--create-parent]
                                                  [--add-users ADD_USERS]
                                                  [--del-users DEL_USERS]
                                                  [--modrdn-users MODRDN_USERS]
                                                  [--mod-users MOD_USERS]
                                                  [--mod-attrs [MOD_ATTRS ...]]
                                                  [--randomize]
                                                  [--ldif-file LDIF_FILE]

--create-users

Create the entries that will be modified or deleted. By default the script assumes the user entries already exist.

--delete-users

Delete all the user entries at the end of the LDIF.

--num-users NUM_USERS

The number of user entries that will be modified or deleted

--parent PARENT

The DN of the parent entry where the user entries are located.

--create-parent

Create the parent entry

--add-users ADD_USERS

The number of additional entries to add during the load.

--del-users DEL_USERS

The number of entries to delete during the load.

--modrdn-users MODRDN_USERS

The number of entries to perform a modrdn operation on.

--mod-users MOD_USERS

The number of entries to modify.

--mod-attrs [MOD_ATTRS ...]

List of attributes the script will randomly choose from when modifying an entry. The default is "description".

--randomize

Randomly perform the specified add, mod, delete, and modrdn operations

--ldif-file LDIF_FILE

The LDIF file name. Default location is the server's LDIF directory using the name 'ldifgen.ldif'

usage: dsctl [-v] [-j] [instance] ldifgen nested [-h] [--num-users NUM_USERS]
                                                [--node-limit NODE_LIMIT]
                                                [--suffix SUFFIX]
                                                [--ldif-file LDIF_FILE]

--num-users NUM_USERS

The total number of user entries to create in the entire LDIF (does not include the container entries).

--node-limit NODE_LIMIT

The total number of user entries to create under each node/subtree

--suffix SUFFIX

The suffix DN for the LDIF

--ldif-file LDIF_FILE

The LDIF file name. Default location is the server's LDIF directory using the name 'ldifgen.ldif'

usage: dsctl [-v] [-j] [instance] dsrc [-h] {create,modify,delete,display,repl-mon} ...

dsctl dsrc create

Generate the .dsrc file

dsctl dsrc modify

Modify the .dsrc file

dsctl dsrc delete

Delete instance configuration from the .dsrc file.

dsctl dsrc display

Display the contents of the .dsrc file.

dsctl dsrc repl-mon

Display the contents of the .dsrc file.

usage: dsctl [-v] [-j] [instance] dsrc create [-h] [--uri URI]
                                             [--basedn BASEDN]
                                             [--people-rdn PEOPLE_RDN]
                                             [--groups-rdn GROUPS_RDN]
                                             [--binddn BINDDN]
                                             [--saslmech SASLMECH]
                                             [--tls-cacertdir TLS_CACERTDIR]
                                             [--tls-cert TLS_CERT]
                                             [--tls-key TLS_KEY]
                                             [--tls-reqcert TLS_REQCERT]
                                             [--starttls] [--pwdfile PWDFILE]
                                             [--do-it]

--uri URI

The URI (LDAP URL) for the Directory Server instance.

--basedn BASEDN

The default database suffix.

--people-rdn PEOPLE_RDN

Set the RDN for the 'people' subtree. Default is "ou=people"

--groups-rdn GROUPS_RDN

Set the RDN for the 'groups' subtree. Default is "ou=groups"

--binddn BINDDN

The default Bind DN used or authentication.

--saslmech SASLMECH

The SASL mechanism to use: PLAIN or EXTERNAL.

--tls-cacertdir TLS_CACERTDIR

The directory containing the Trusted Certificate Authority certificate.

--tls-cert TLS_CERT

The absolute file name to the server certificate.

--tls-key TLS_KEY

The absolute file name to the server certificate key.

--tls-reqcert TLS_REQCERT

Request certificate strength: 'never', 'allow', 'hard'

--starttls

Use startTLS for connection to the server.

--pwdfile PWDFILE

The absolute path to a file containing the Bind DN's password.

--do-it

Create the file without any confirmation.

usage: dsctl [-v] [-j] [instance] dsrc modify [-h] [--uri [URI]]
                                             [--basedn [BASEDN]]
                                             [--people-rdn [PEOPLE_RDN]]
                                             [--groups-rdn [GROUPS_RDN]]
                                             [--binddn [BINDDN]]
                                             [--saslmech [SASLMECH]]
                                             [--tls-cacertdir [TLS_CACERTDIR]]
                                             [--tls-cert [TLS_CERT]]
                                             [--tls-key [TLS_KEY]]
                                             [--tls-reqcert [TLS_REQCERT]]
                                             [--starttls] [--cancel-starttls]
                                             [--pwdfile [PWDFILE]] [--do-it]

--uri [URI]

The URI (LDAP URL) for the Directory Server instance.

--basedn [BASEDN]

The default database suffix.

--people-rdn [PEOPLE_RDN]

Sets the RDN used for the 'people' container

--groups-rdn [GROUPS_RDN]

Sets the RDN used for the 'groups' container

--binddn [BINDDN]

The default Bind DN used or authentication.

--saslmech [SASLMECH]

The SASL mechanism to use: PLAIN or EXTERNAL.

--tls-cacertdir [TLS_CACERTDIR]

The directory containing the Trusted Certificate Authority certificate.

--tls-cert [TLS_CERT]

The absolute file name to the server certificate.

--tls-key [TLS_KEY]

The absolute file name to the server certificate key.

--tls-reqcert [TLS_REQCERT]

Request certificate strength: 'never', 'allow', 'hard'

--starttls

Use startTLS for connection to the server.

--cancel-starttls

Do not use startTLS for connection to the server.

--pwdfile [PWDFILE]

The absolute path to a file containing the Bind DN's password.

--do-it

Update the file without any confirmation.

usage: dsctl [-v] [-j] [instance] dsrc delete [-h] [--do-it]

--do-it

Delete this instance's configuration from the .dsrc file.

usage: dsctl [-v] [-j] [instance] dsrc display [-h]

usage: dsctl [-v] [-j] [instance] dsrc repl-mon [-h]
                                               [--add-conn ADD_CONN [ADD_CONN ...]]
                                               [--del-conn DEL_CONN [DEL_CONN ...]]
                                               [--add-alias ADD_ALIAS [ADD_ALIAS ...]]
                                               [--del-alias DEL_ALIAS [DEL_ALIAS ...]]

--add-conn ADD_CONN [ADD_CONN ...]

Add a replica connection: 'NAME:HOST:PORT:BINDDN:CREDENTIAL'

--del-conn DEL_CONN [DEL_CONN ...]

delete a replica connection by its NAME

--add-alias ADD_ALIAS [ADD_ALIAS ...]

Add a host/port alias: 'ALIAS_NAME:HOST:PORT'

--del-alias DEL_ALIAS [DEL_ALIAS ...]

delete a host/port alias by its ALIAS_NAME

usage: dsctl [-v] [-j] [instance] cockpit [-h]
                               {enable,open-firewall,disable,close-firewall} ...

dsctl cockpit enable

Enable the Cockpit socket

dsctl cockpit open-firewall

Open the firewall for the "cockpit" service

dsctl cockpit disable

Disable the Cockpit socket

dsctl cockpit close-firewall

Remove the "cockpit" service from the firewall settings

usage: dsctl [-v] [-j] [instance] cockpit enable [-h]

usage: dsctl [-v] [-j] [instance] cockpit open-firewall [-h] [--zone ZONE]

--zone ZONE

The firewall zone

usage: dsctl [-v] [-j] [instance] cockpit disable [-h]

usage: dsctl [-v] [-j] [instance] cockpit close-firewall [-h]

usage: dsctl [-v] [-j] [instance] dblib [-h] {bdb2mdb,mdb2bdb,cleanup} ...

dsctl dblib bdb2mdb

Migrate bdb databases to lmdb

dsctl dblib mdb2bdb

Migrate lmdb databases to bdb

dsctl dblib cleanup

Remove migration ldif file and old database

usage: dsctl [-v] [-j] [instance] dblib bdb2mdb [-h] [--tmpdir TMPDIR]

--tmpdir TMPDIR

ldif migration files directory path.

usage: dsctl [-v] [-j] [instance] dblib mdb2bdb [-h] [--tmpdir TMPDIR]

--tmpdir TMPDIR

ldif migration files directory path.

usage: dsctl [-v] [-j] [instance] dblib cleanup [-h]

-v,  --verbose

Display verbose operation tracing during command execution

-j,  --json

Return result in JSON object

-l,  --list

List available Directory Server instances

Red Hat, Inc., and William Brown <389-devel@lists.fedoraproject.org>

The latest version of lib389 may be downloaded from http://www.port389.org/docs/389ds/FAQ/upstream-test-framework.html