DSCTL(8) Generated Python Manual DSCTL(8)

dsctl

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} ...

Restart an instance of Directory Server, if it is running: else start it.
Start an instance of Directory Server, if it is not currently running
Stop an instance of Directory Server, if it is currently running
Check running status of an instance of Directory Server
Destroy an instance of Directory Server, and remove all data.
Initialise a reindex of the server database. The server must be stopped for this to proceed.
Initialise a BDB backup of the database. The server must be stopped for this to proceed.
Initialise an LDIF dump of the database. The server must be stopped for this to proceed.
Perform a db verification. You should only do this at direction of support
Restore a BDB backup of the database. The server must be stopped for this to proceed.
Restore an LDIF dump of the database. The server must be stopped for this to proceed.
List backup's found in the server's default backup directory
List all the LDIF files located in the server's LDIF directory
Manage TLS certificates
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.
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

LDIF generator to make sample LDIF files for testing
Manage the .dsrc file
Enable the Cockpit interface/UI
database library (i.e bdb/lmdb) migration

COMMAND 'dsctl restart'

usage: dsctl [instance] restart [-h]

COMMAND 'dsctl start'

usage: dsctl [instance] start [-h]

COMMAND 'dsctl stop'

usage: dsctl [instance] stop [-h]

COMMAND 'dsctl status'

usage: dsctl [instance] status [-h]

COMMAND 'dsctl remove'

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

OPTIONS 'dsctl remove'

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

COMMAND 'dsctl db2index'

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

The backend to reindex. IE userRoot

OPTIONS 'dsctl db2index'

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

COMMAND 'dsctl db2bak'

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

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

COMMAND 'dsctl db2ldif'

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

The backend to output as an LDIF. IE userRoot

The path to the ldif output location.

OPTIONS 'dsctl db2ldif'

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

Export encrypted attributes

COMMAND 'dsctl dbverify'

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

The backend to verify. IE userRoot

COMMAND 'dsctl bak2db'

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

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

COMMAND 'dsctl ldif2db'

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

The backend to restore from an LDIF. IE userRoot

The path to the ldif to import

OPTIONS 'dsctl ldif2db'

Import encrypted attributes

COMMAND 'dsctl backups'

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

OPTIONS 'dsctl backups'

Delete backup directory

COMMAND 'dsctl ldifs'

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

OPTIONS 'dsctl ldifs'

Delete LDIF file

COMMAND 'dsctl tls'

usage: dsctl [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}
...

POSITIONAL ARGUMENTS 'dsctl tls'

list server certificate authorities including intermediates
list client certificate authorities including intermediates
Show the active server certificate that clients will see and verify
Show a certificate's details referenced by it's nickname. This is analogous to certutil -L -d <path> -n <nickname>
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
Import a CA trusted to issue user (client) certificates. This is part of how client certificate authentication functions.
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
Import a new Server-Cert after the csr has been signed from a CA.
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.
Delete a certificate from this database. This will remove it from acting as a CA, a client CA or the Server-Cert role.
Export a certificate to PEM or DER/Binary format. PEM format is the default

COMMAND 'dsctl tls list-ca'

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

COMMAND 'dsctl tls list-client-ca'

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

COMMAND 'dsctl tls show-server-cert'

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

COMMAND 'dsctl tls show-cert'

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

The nickname (friendly name) of the certificate to display

COMMAND 'dsctl tls generate-server-cert-csr'

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

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

OPTIONS 'dsctl tls generate-server-cert-csr'

Certificate Subject field to use

COMMAND 'dsctl tls import-client-ca'

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

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

The name of the certificate once imported

COMMAND 'dsctl tls import-ca'

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

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

The name of the certificate once imported

COMMAND 'dsctl tls import-server-cert'

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

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

COMMAND 'dsctl tls import-server-key-cert'

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

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

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

COMMAND 'dsctl tls remove-cert'

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

The name of the certificate to delete

COMMAND 'dsctl tls export-cert'

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

The name of the certificate to export

OPTIONS 'dsctl tls export-cert'

Export certificate in DER/binary format

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

COMMAND 'dsctl healthcheck'

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

OPTIONS 'dsctl healthcheck'

List of known checks

List of known error codes

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

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.

COMMAND 'dsctl get-nsstate'

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

OPTIONS 'dsctl get-nsstate'

The DN of the replication suffix to read the state from

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

COMMAND 'dsctl ldifgen'

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

POSITIONAL ARGUMENTS 'dsctl ldifgen'

Generate a LDIF containing user entries
Generate a LDIF containing groups and members
Generate a LDIF containing a COS definition (classic, pointer, or indirect)
Generate a LDIF containing a COS template
Generate a LDIF containing a role entry (managed, filtered, or indirect)
Generate a LDIF containing modify operations. This is intended to be consumed by ldapmodify.
Generate a heavily nested database LDIF in a cascading/fractal tree design

COMMAND 'dsctl ldifgen users'

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

OPTIONS 'dsctl ldifgen users'

The number of users to create.

The database suffix where the entries will be created.

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

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

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

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

Localize the LDIF data

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

COMMAND 'dsctl ldifgen groups'

usage: dsctl [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.

OPTIONS 'dsctl ldifgen groups'

The number of groups to create.

The database suffix where the groups will be created.

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

The number of members in the group. Default is 10000

Create the member user entries.

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

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

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

COMMAND 'dsctl ldifgen cos-def'

usage: dsctl [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.

OPTIONS 'dsctl ldifgen cos-def'

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

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

Create the parent entry

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

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

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

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

COMMAND 'dsctl ldifgen cos-template'

usage: dsctl [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.

OPTIONS 'dsctl ldifgen cos-template'

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

Create the parent entry

Sets the priority of this conflicting/competing COS templates.

defines the attribute and value that the template provides.

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

COMMAND 'dsctl ldifgen roles'

usage: dsctl [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.

OPTIONS 'dsctl ldifgen roles'

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

The DN of the entry to store the Role entry under

Create the parent entry

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

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

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

COMMAND 'dsctl ldifgen mod-load'

usage: dsctl [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]

OPTIONS 'dsctl ldifgen mod-load'

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

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

The number of user entries that will be modified or deleted

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

Create the parent entry

The number of additional entries to add during the load.

The number of entries to delete during the load.

The number of entries to perform a modrdn operation on.

The number of entries to modify.

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

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

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

COMMAND 'dsctl ldifgen nested'

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

OPTIONS 'dsctl ldifgen nested'

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

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

The suffix DN for the LDIF

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

COMMAND 'dsctl dsrc'

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

POSITIONAL ARGUMENTS 'dsctl dsrc'

Generate the .dsrc file
Modify the .dsrc file
Delete instance configuration from the .dsrc file.
Display the contents of the .dsrc file.
Display the contents of the .dsrc file.

COMMAND 'dsctl dsrc create'

usage: dsctl [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]

OPTIONS 'dsctl dsrc create'

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

The default database suffix.

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

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

The default Bind DN used or authentication.

The SASL mechanism to use: PLAIN or EXTERNAL.

The directory containing the Trusted Certificate Authority certificate.

The absolute file name to the server certificate.

The absolute file name to the server certificate key.

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

Use startTLS for connection to the server.

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

Create the file without any confirmation.

COMMAND 'dsctl dsrc modify'

usage: dsctl [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]

OPTIONS 'dsctl dsrc modify'

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

The default database suffix.

Sets the RDN used for the 'people' container

Sets the RDN used for the 'groups' container

The default Bind DN used or authentication.

The SASL mechanism to use: PLAIN or EXTERNAL.

The directory containing the Trusted Certificate Authority certificate.

The absolute file name to the server certificate.

The absolute file name to the server certificate key.

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

Use startTLS for connection to the server.

Do not use startTLS for connection to the server.

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

Update the file without any confirmation.

COMMAND 'dsctl dsrc delete'

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

OPTIONS 'dsctl dsrc delete'

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

COMMAND 'dsctl dsrc display'

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

COMMAND 'dsctl dsrc repl-mon'

usage: dsctl [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 ...]]

OPTIONS 'dsctl dsrc repl-mon'

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

delete a replica connection by its NAME

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

delete a host/port alias by its ALIAS_NAME

COMMAND 'dsctl cockpit'

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

POSITIONAL ARGUMENTS 'dsctl cockpit'

Enable the Cockpit socket
Open the firewall for the "cockpit" service
Disable the Cockpit socket
Remove the "cockpit" service from the firewall settings

COMMAND 'dsctl cockpit enable'

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

COMMAND 'dsctl cockpit open-firewall'

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

OPTIONS 'dsctl cockpit open-firewall'

The firewall zone

COMMAND 'dsctl cockpit disable'

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

COMMAND 'dsctl cockpit close-firewall'

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

COMMAND 'dsctl dblib'

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

POSITIONAL ARGUMENTS 'dsctl dblib'

Migrate bdb databases to lmdb
Migrate lmdb databases to bdb
Remove migration ldif file and old database

COMMAND 'dsctl dblib bdb2mdb'

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

OPTIONS 'dsctl dblib bdb2mdb'

ldif migration files directory path.

COMMAND 'dsctl dblib mdb2bdb'

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

OPTIONS 'dsctl dblib mdb2bdb'

ldif migration files directory path.

COMMAND 'dsctl dblib cleanup'

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

Display verbose operation tracing during command execution

Return result in JSON object

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

2024-04-15 lib389 2.4.5