1DSCTL(8) Generated Python Manual DSCTL(8)
2
6 dsctl
7
9 dsctl [-h] [-v] [-j] [-l] [instance] {restart,start,stop,status,re‐
10 move,db2index,db2bak,db2ldif,dbverify,bak2db,ldif2db,backups,ld‐
11 ifs,tls,healthcheck,get-nsstate,ldifgen,dsrc,cockpit,dblib} ...
12
15 dsctl restart
16 Restart an instance of Directory Server, if it is running: else
17 start it.
18 dsctl start
20 Start an instance of Directory Server, if it is not currently
21 running
22 dsctl stop
24 Stop an instance of Directory Server, if it is currently running
25 dsctl status
27 Check running status of an instance of Directory Server
28 dsctl remove
30 Destroy an instance of Directory Server, and remove all data.
31 dsctl db2index
33 Initialise a reindex of the server database. The server must be
34 stopped for this to proceed.
35 dsctl db2bak
37 Initialise a BDB backup of the database. The server must be
38 stopped for this to proceed.
39 dsctl db2ldif
41 Initialise an LDIF dump of the database. The server must be
42 stopped for this to proceed.
43 dsctl dbverify
45 Perform a db verification. You should only do this at direction
46 of support
47 dsctl bak2db
49 Restore a BDB backup of the database. The server must be stopped
50 for this to proceed.
51 dsctl ldif2db
53 Restore an LDIF dump of the database. The server must be stopped
54 for this to proceed.
55 dsctl backups
57 List backup's found in the server's default backup directory
58 dsctl ldifs
60 List all the LDIF files located in the server's LDIF directory
61 dsctl tls
63 Manage TLS certificates
64 dsctl healthcheck
66 Run a healthcheck report on a local Directory Server instance.
67 This is a safe and read-only operation. Do not attempt to run
68 this on a remote Directory Server as this tool needs access to
69 local resources, otherwise the report may be inaccurate.
70 dsctl get-nsstate
72 Get the replication nsState in a human readable format
73 Replica DN: The DN of the replication configuration
75 entry Replica Suffix: The replicated suffix Replica ID:
76 The Replica identifier Gen Time The time the CSN
77 generator was created Gen Time String: The time string of
78 generator Gen as CSN: The generation CSN Local Offset:
79 The offset due to the local clock being set back Local Offset
80 String: The offset in a nice human format Remote Offset:
81 The offset due to clock difference with remote systems Remote
82 Offset String: The offset in a nice human format Time Skew:
83 The time skew between this server and its replicas Time Skew
84 String: The time skew in a nice human format Seq Num:
85 The number of multiple csns within a second System Time:
86 The local system time Diff in Seconds: The time difference
87 in seconds from the CSN generator creation to now Diff in
88 days/secs: The time difference broken up into days and sec‐
89 onds Endian: Little/Big Endian
90 dsctl ldifgen
92 LDIF generator to make sample LDIF files for testing
93 dsctl dsrc
95 Manage the .dsrc file
96 dsctl cockpit
98 Enable the Cockpit interface/UI
99 dsctl dblib
101 database library (i.e bdb/lmdb) migration
102
105 usage: dsctl [instance] restart [-h]
106
109 usage: dsctl [instance] start [-h]
110
113 usage: dsctl [instance] stop [-h]
114
117 usage: dsctl [instance] status [-h]
118
121 usage: dsctl [instance] remove [-h] [--do-it]
122
125 --do-it
126 By default we do a dry run. This actually initiates the removal
127 of the instance.
128
131 usage: dsctl [instance] db2index [-h] [--attr [ATTR ...]] [backend]
132 backend
135 The backend to reindex. IE userRoot
136
139 --attr [ATTR ...]
140 The attribute's to reindex. IE --attr aci cn givenname
141
144 usage: dsctl [instance] db2bak [-h] [archive]
145 archive
148 The destination for the archive. This will be created during the
149 db2bak process.
150
153 usage: dsctl [instance] db2ldif [-h] [--replication] [--encrypted]
154 backend [ldif]
155 backend
158 The backend to output as an LDIF. IE userRoot
159 ldif The path to the ldif output location.
162
165 --replication
166 Export replication information, suitable for importing on a new
167 consumer or backups.
168 --encrypted
171 Export encrypted attributes
172
175 usage: dsctl [instance] dbverify [-h] backend
176 backend
179 The backend to verify. IE userRoot
180
183 usage: dsctl [instance] bak2db [-h] archive
184 archive
187 The archive to restore. This will erase all current server data‐
188 bases.
189
192 usage: dsctl [instance] ldif2db [-h] [--encrypted] backend ldif
193 backend
196 The backend to restore from an LDIF. IE userRoot
197 ldif The path to the ldif to import
200
203 --encrypted
204 Import encrypted attributes
205
208 usage: dsctl [instance] backups [-h] [--delete DELETE]
209
212 --delete DELETE
213 Delete backup directory
214
217 usage: dsctl [instance] ldifs [-h] [--delete DELETE]
218
221 --delete DELETE
222 Delete LDIF file
223
226 usage: dsctl [instance] tls [-h]
227 {list-ca,list-client-ca,show-server-cert,show-cert,gen‐
228 erate-server-cert-csr,import-client-ca,import-ca,import-server-cert,im‐
229 port-server-key-cert,remove-cert}
230 ...
231
234 dsctl tls list-ca
235 list server certificate authorities including intermediates
236 dsctl tls list-client-ca
238 list client certificate authorities including intermediates
239 dsctl tls show-server-cert
241 Show the active server certificate that clients will see and
242 verify
243 dsctl tls show-cert
245 Show a certificate's details referenced by it's nickname. This
246 is analogous to certutil -L -d <path> -n <nickname>
247 dsctl tls generate-server-cert-csr
249 Generate a Server-Cert certificate signing request - the csr is
250 then submitted to a CA for verification, and when signed you im‐
251 port with import-ca and import-server-cert
252 dsctl tls import-client-ca
254 Import a CA trusted to issue user (client) certificates. This is
255 part of how client certificate authentication functions.
256 dsctl tls import-ca
258 Import a CA or intermediate CA for signing this servers certifi‐
259 cates (aka Server-Cert). You should import all the CA's in the
260 chain as required. PEM bundles are accepted
261 dsctl tls import-server-cert
263 Import a new Server-Cert after the csr has been signed from a
264 CA.
265 dsctl tls import-server-key-cert
267 Import a new key and Server-Cert after having been signed from a
268 CA. This is used if you have an external csr tool or a service
269 like lets encrypt that generates PEM keys externally.
270 dsctl tls remove-cert
272 Delete a certificate from this database. This will remove it
273 from acting as a CA, a client CA or the Server-Cert role.
274
277 usage: dsctl [instance] tls list-ca [-h]
278
281 usage: dsctl [instance] tls list-client-ca [-h]
282
285 usage: dsctl [instance] tls show-server-cert [-h]
286
289 usage: dsctl [instance] tls show-cert [-h] nickname
290 nickname
293 The nickname (friendly name) of the certificate to display
294
297 usage: dsctl [instance] tls generate-server-cert-csr [-h] [--subject
298 SUBJECT]
299 [alt_names ...]
300 alt_names
303 Certificate requests subject alternative names. These are
304 auto-detected if not provided
305
308 --subject SUBJECT, -s SUBJECT
309 Certificate Subject field to use
310
313 usage: dsctl [instance] tls import-client-ca [-h] cert_path nickname
314 cert_path
317 The path to the x509 cert to import as a client trust root
318 nickname
321 The name of the certificate once imported
322
325 usage: dsctl [instance] tls import-ca [-h] cert_path nickname [nickname
326 ...]
327 cert_path
330 The path to the x509 cert to import as a server CA
331 nickname
334 The name of the certificate once imported
335
338 usage: dsctl [instance] tls import-server-cert [-h] cert_path
339 cert_path
342 The path to the x509 cert to import as Server-Cert
343
346 usage: dsctl [instance] tls import-server-key-cert [-h] cert_path
347 key_path
348 cert_path
351 The path to the x509 cert to import as Server-Cert
352 key_path
355 The path to the x509 key to import associated to Server-Cert
356
359 usage: dsctl [instance] tls remove-cert [-h] nickname
360 nickname
363 The name of the certificate to delete
364
367 usage: dsctl [instance] healthcheck [-h] [--list-checks] [--list-er‐
368 rors]
369 [--dry-run] [--check CHECK [CHECK
370 ...]]
371
374 --list-checks
375 List of known checks
376 --list-errors
379 List of known error codes
380 --dry-run
383 Do not execute the actual check, only list what would be done
384 --check CHECK [CHECK ...]
387 Areas to check. These can be obtained by --list-checks. Every
388 element on the left of the colon (:) may be replaced by an as‐
389 terisk if multiple options on the right are available.
390
393 usage: dsctl [instance] get-nsstate [-h] [--suffix SUFFIX] [--flip
394 FLIP]
395
398 --suffix SUFFIX
399 The DN of the replication suffix to read the state from
400 --flip FLIP
403 Flip between Little/Big Endian, this might be required for cer‐
404 tain architectures
405
408 usage: dsctl [instance] ldifgen [-h]
409 {users,groups,cos-def,cos-tem‐
410 plate,roles,mod-load,nested}
411 ...
412
415 dsctl ldifgen users
416 Generate a LDIF containing user entries
417 dsctl ldifgen groups
419 Generate a LDIF containing groups and members
420 dsctl ldifgen cos-def
422 Generate a LDIF containing a COS definition (classic, pointer,
423 or indirect)
424 dsctl ldifgen cos-template
426 Generate a LDIF containing a COS template
427 dsctl ldifgen roles
429 Generate a LDIF containing a role entry (managed, filtered, or
430 indirect)
431 dsctl ldifgen mod-load
433 Generate a LDIF containing modify operations. This is intended
434 to be consumed by ldapmodify.
435 dsctl ldifgen nested
437 Generate a heavily nested database LDIF in a cascading/fractal
438 tree design
439
442 usage: dsctl [instance] ldifgen users [-h] [--number NUMBER] [--suffix
443 SUFFIX]
444 [--parent PARENT] [--generic]
445 [--start-idx START_IDX]
446 [--rdn-cn]
447 [--localize] [--ldif-file
448 LDIF_FILE]
449
452 --number NUMBER
453 The number of users to create.
454 --suffix SUFFIX
457 The database suffix where the entries will be created.
458 --parent PARENT
461 The parent entry that the user entries should be created under.
462 If not specified, the entries are stored under random Organiza‐
463 tional Units.
464 --generic
467 Create generic entries in the format of "uid=user####". These
468 entries are also compatible with ldclt.
469 --start-idx START_IDX
472 For generic LDIF's you can choose the starting index for the
473 user entries. The default is "0".
474 --rdn-cn
477 Use the attribute "cn" as the RDN attribute in the DN instead of
478 "uid"
479 --localize
482 Localize the LDIF data
483 --ldif-file LDIF_FILE
486 The LDIF file name. Default location is the server's LDIF direc‐
487 tory using the name 'users.ldif'
488
491 usage: dsctl [instance] ldifgen groups [-h] [--number NUMBER]
492 [--suffix SUFFIX] [--parent PAR‐
493 ENT]
494 [--num-members NUM_MEMBERS]
495 [--create-members]
496 [--member-parent MEMBER_PARENT]
497 [--member-attr MEMBER_ATTR]
498 [--ldif-file LDIF_FILE]
499 NAME
500 NAME The group name.
503
506 --number NUMBER
507 The number of groups to create.
508 --suffix SUFFIX
511 The database suffix where the groups will be created.
512 --parent PARENT
515 The parent entry that the group entries should be created under.
516 If not specified the groups are stored under the suffix.
517 --num-members NUM_MEMBERS
520 The number of members in the group. Default is 10000
521 --create-members
524 Create the member user entries.
525 --member-parent MEMBER_PARENT
528 The entry DN that the members should be created under. The de‐
529 fault is the suffix entry.
530 --member-attr MEMBER_ATTR
533 The membership attribute to use in the group. Default is
534 "uniquemember".
535 --ldif-file LDIF_FILE
538 The LDIF file name. Default is "/tmp/ldifgen.ldif"
539
542 usage: dsctl [instance] ldifgen cos-def [-h] [--type TYPE] [--parent
543 PARENT]
544 [--create-parent]
545 [--cos-specifier COS_SPECIFIER]
546 [--cos-template COS_TEMPLATE]
547 [--cos-attr [COS_ATTR ...]]
548 [--ldif-file LDIF_FILE]
549 NAME
550 NAME The COS definition name.
553
556 --type TYPE
557 The COS definition type: "classic", "pointer", or "indirect".
558 --parent PARENT
561 The parent entry that the COS definition should be created un‐
562 der.
563 --create-parent
566 Create the parent entry
567 --cos-specifier COS_SPECIFIER
570 Used in a classic COS definition, this attribute located in the
571 user entry is used to select which COS template to use.
572 --cos-template COS_TEMPLATE
575 The DN of the COS template entry, only used for "classic" and
576 "pointer" COS definitions.
577 --cos-attr [COS_ATTR ...]
580 A list of attributes which defines which attribute the COS gen‐
581 erates values for.
582 --ldif-file LDIF_FILE
585 The LDIF file name. Default is "/tmp/ldifgen.ldif"
586
589 usage: dsctl [instance] ldifgen cos-template [-h] [--parent PARENT]
590 [--create-parent]
591 [--cos-priority COS_PRIOR‐
592 ITY]
593 [--cos-attr-val
594 COS_ATTR_VAL]
595 [--ldif-file LDIF_FILE]
596 NAME
597 NAME The COS template name.
600
603 --parent PARENT
604 The DN of the entry to store the COS template entry under.
605 --create-parent
608 Create the parent entry
609 --cos-priority COS_PRIORITY
612 Sets the priority of this conflicting/competing COS templates.
613 --cos-attr-val COS_ATTR_VAL
616 defines the attribute and value that the template provides.
617 --ldif-file LDIF_FILE
620 The LDIF file name. Default is "/tmp/ldifgen.ldif"
621
624 usage: dsctl [instance] ldifgen roles [-h] [--type TYPE] [--parent PAR‐
625 ENT]
626 [--create-parent] [--filter FIL‐
627 TER]
628 [--role-dn [ROLE_DN ...]]
629 [--ldif-file LDIF_FILE]
630 NAME
631 NAME The Role name.
634
637 --type TYPE
638 The Role type: "managed", "filtered", or "nested".
639 --parent PARENT
642 The DN of the entry to store the Role entry under
643 --create-parent
646 Create the parent entry
647 --filter FILTER
650 A search filter for gathering Role members. Required for a "fil‐
651 tered" role.
652 --role-dn [ROLE_DN ...]
655 A DN of a role entry that should be included in this role. Used
656 for "nested" roles only.
657 --ldif-file LDIF_FILE
660 The LDIF file name. Default is "/tmp/ldifgen.ldif"
661
664 usage: dsctl [instance] ldifgen mod-load [-h] [--create-users]
665 [--delete-users]
666 [--num-users NUM_USERS]
667 [--parent PARENT] [--cre‐
668 ate-parent]
669 [--add-users ADD_USERS]
670 [--del-users DEL_USERS]
671 [--modrdn-users MODRDN_USERS]
672 [--mod-users MOD_USERS]
673 [--mod-attrs [MOD_ATTRS ...]]
674 [--randomize] [--ldif-file
675 LDIF_FILE]
676
679 --create-users
680 Create the entries that will be modified or deleted. By default
681 the script assumes the user entries already exist.
682 --delete-users
685 Delete all the user entries at the end of the LDIF.
686 --num-users NUM_USERS
689 The number of user entries that will be modified or deleted
690 --parent PARENT
693 The DN of the parent entry where the user entries are located.
694 --create-parent
697 Create the parent entry
698 --add-users ADD_USERS
701 The number of additional entries to add during the load.
702 --del-users DEL_USERS
705 The number of entries to delete during the load.
706 --modrdn-users MODRDN_USERS
709 The number of entries to perform a modrdn operation on.
710 --mod-users MOD_USERS
713 The number of entries to modify.
714 --mod-attrs [MOD_ATTRS ...]
717 List of attributes the script will randomly choose from when
718 modifying an entry. The default is "description".
719 --randomize
722 Randomly perform the specified add, mod, delete, and modrdn op‐
723 erations
724 --ldif-file LDIF_FILE
727 The LDIF file name. Default is "/tmp/ldifgen.ldif"
728
731 usage: dsctl [instance] ldifgen nested [-h] [--num-users NUM_USERS]
732 [--node-limit NODE_LIMIT]
733 [--suffix SUFFIX]
734 [--ldif-file LDIF_FILE]
735
738 --num-users NUM_USERS
739 The total number of user entries to create in the entire LDIF
740 (does not include the container entries).
741 --node-limit NODE_LIMIT
744 The total number of user entries to create under each node/sub‐
745 tree
746 --suffix SUFFIX
749 The suffix DN for the LDIF
750 --ldif-file LDIF_FILE
753 The LDIF file name. Default location is the server's LDIF direc‐
754 tory using the name 'users.ldif'
755
758 usage: dsctl [instance] dsrc [-h] {create,modify,delete,display} ...
759
762 dsctl dsrc create
763 Generate the .dsrc file
764 dsctl dsrc modify
766 Modify the .dsrc file
767 dsctl dsrc delete
769 Delete instance configuration from the .dsrc file.
770 dsctl dsrc display
772 Display the contents of the .dsrc file.
773
776 usage: dsctl [instance] dsrc create [-h] [--uri URI] [--basedn BASEDN]
777 [--binddn BINDDN] [--saslmech
778 SASLMECH]
779 [--tls-cacertdir TLS_CACERTDIR]
780 [--tls-cert TLS_CERT] [--tls-key
781 TLS_KEY]
782 [--tls-reqcert TLS_REQCERT]
783 [--starttls]
784 [--pwdfile PWDFILE] [--do-it]
785
788 --uri URI
789 The URI (LDAP URL) for the Directory Server instance.
790 --basedn BASEDN
793 The default database suffix.
794 --binddn BINDDN
797 The default Bind DN used or authentication.
798 --saslmech SASLMECH
801 The SASL mechanism to use: PLAIN or EXTERNAL.
802 --tls-cacertdir TLS_CACERTDIR
805 The directory containing the Trusted Certificate Authority cer‐
806 tificate.
807 --tls-cert TLS_CERT
810 The absolute file name to the server certificate.
811 --tls-key TLS_KEY
814 The absolute file name to the server certificate key.
815 --tls-reqcert TLS_REQCERT
818 Request certificate strength: 'never', 'allow', 'hard'
819 --starttls
822 Use startTLS for connection to the server.
823 --pwdfile PWDFILE
826 The absolute path to a file containing the Bind DN's password.
827 --do-it
830 Create the file without any confirmation.
831
834 usage: dsctl [instance] dsrc modify [-h] [--uri [URI]] [--basedn
835 [BASEDN]]
836 [--binddn [BINDDN]]
837 [--saslmech [SASLMECH]]
838 [--tls-cacertdir [TLS_CACERTDIR]]
839 [--tls-cert [TLS_CERT]]
840 [--tls-key [TLS_KEY]]
841 [--tls-reqcert [TLS_REQCERT]]
842 [--starttls]
843 [--cancel-starttls] [--pwdfile
844 [PWDFILE]]
845 [--do-it]
846
849 --uri [URI]
850 The URI (LDAP URL) for the Directory Server instance.
851 --basedn [BASEDN]
854 The default database suffix.
855 --binddn [BINDDN]
858 The default Bind DN used or authentication.
859 --saslmech [SASLMECH]
862 The SASL mechanism to use: PLAIN or EXTERNAL.
863 --tls-cacertdir [TLS_CACERTDIR]
866 The directory containing the Trusted Certificate Authority cer‐
867 tificate.
868 --tls-cert [TLS_CERT]
871 The absolute file name to the server certificate.
872 --tls-key [TLS_KEY]
875 The absolute file name to the server certificate key.
876 --tls-reqcert [TLS_REQCERT]
879 Request certificate strength: 'never', 'allow', 'hard'
880 --starttls
883 Use startTLS for connection to the server.
884 --cancel-starttls
887 Do not use startTLS for connection to the server.
888 --pwdfile [PWDFILE]
891 The absolute path to a file containing the Bind DN's password.
892 --do-it
895 Update the file without any confirmation.
896
899 usage: dsctl [instance] dsrc delete [-h] [--do-it]
900
903 --do-it
904 Delete this instance's configuration from the .dsrc file.
905
908 usage: dsctl [instance] dsrc display [-h]
909
912 usage: dsctl [instance] cockpit [-h]
913 {enable,open-firewall,dis‐
914 able,close-firewall}
915 ...
916
919 dsctl cockpit enable
920 Enable the Cockpit socket
921 dsctl cockpit open-firewall
923 Open the firewall for the "cockpit" service
924 dsctl cockpit disable
926 Disable the Cockpit socket
927 dsctl cockpit close-firewall
929 Remove the "cockpit" service from the firewall settings
930
933 usage: dsctl [instance] cockpit enable [-h]
934
937 usage: dsctl [instance] cockpit open-firewall [-h] [--zone ZONE]
938
941 --zone ZONE
942 The firewall zone
943
946 usage: dsctl [instance] cockpit disable [-h]
947
950 usage: dsctl [instance] cockpit close-firewall [-h]
951
954 usage: dsctl [instance] dblib [-h] {bdb2mdb,mdb2bdb,cleanup} ...
955
958 dsctl dblib bdb2mdb
959 Migrate bdb databases to lmdb
960 dsctl dblib mdb2bdb
962 Migrate lmdb databases to bdb
963 dsctl dblib cleanup
965 Remove migration ldif file and old database
966
969 usage: dsctl [instance] dblib bdb2mdb [-h] [--tmpdir TMPDIR]
970
973 --tmpdir TMPDIR
974 ldif migration files directory path.
975
978 usage: dsctl [instance] dblib mdb2bdb [-h] [--tmpdir TMPDIR]
979
982 --tmpdir TMPDIR
983 ldif migration files directory path.
984
987 usage: dsctl [instance] dblib cleanup [-h]
988
991 -v, --verbose
992 Display verbose operation tracing during command execution
993 -j, --json
996 Return result in JSON object
997 -l, --list
1000 List available Directory Server instances
1001
1004 Red Hat, Inc., and William Brown <389-devel@lists.fedoraproject.org>
1005
1008 The latest version of lib389 may be downloaded from
1009 ⟨http://www.port389.org/docs/389ds/FAQ/upstream-test-framework.html⟩
1010lib389 1.4.0.1 2023-01-23 DSCTL(8)