1DSCTL(8) System Manager's 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
14 dsctl restart
15 Restart an instance of Directory Server, if it is running: else
16 start it.
17 dsctl start
19 Start an instance of Directory Server, if it is not currently
20 running
21 dsctl stop
23 Stop an instance of Directory Server, if it is currently running
24 dsctl status
26 Check running status of an instance of Directory Server
27 dsctl remove
29 Destroy an instance of Directory Server, and remove all data.
30 dsctl db2index
32 Initialise a reindex of the server database. The server must be
33 stopped for this to proceed.
34 dsctl db2bak
36 Initialise a BDB backup of the database. The server must be
37 stopped for this to proceed.
38 dsctl db2ldif
40 Initialise an LDIF dump of the database. The server must be
41 stopped for this to proceed.
42 dsctl dbverify
44 Perform a db verification. You should only do this at direction
45 of support
46 dsctl bak2db
48 Restore a BDB backup of the database. The server must be stopped
49 for this to proceed.
50 dsctl ldif2db
52 Restore an LDIF dump of the database. The server must be stopped
53 for this to proceed.
54 dsctl backups
56 List backup's found in the server's default backup directory
57 dsctl ldifs
59 List all the LDIF files located in the server's LDIF directory
60 dsctl tls
62 Manage TLS certificates
63 dsctl healthcheck
65 Run a healthcheck report on a local Directory Server instance.
66 This is a safe and read-only operation. Do not attempt to run
67 this on a remote Directory Server as this tool needs access to
68 local resources, otherwise the report may be inaccurate.
69 dsctl get-nsstate
71 Get the replication nsState in a human readable format
72 Replica DN: The DN of the replication configuration
74 entry Replica Suffix: The replicated suffix Replica ID:
75 The Replica identifier Gen Time The time the CSN
76 generator was created Gen Time String: The time string of
77 generator Gen as CSN: The generation CSN Local Offset:
78 The offset due to the local clock being set back Local Offset
79 String: The offset in a nice human format Remote Offset:
80 The offset due to clock difference with remote systems Remote
81 Offset String: The offset in a nice human format Time Skew:
82 The time skew between this server and its replicas Time Skew
83 String: The time skew in a nice human format Seq Num:
84 The number of multiple csns within a second System Time:
85 The local system time Diff in Seconds: The time difference
86 in seconds from the CSN generator creation to now Diff in
87 days/secs: The time difference broken up into days and sec‐
88 onds Endian: Little/Big Endian
89 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
104 usage: dsctl [instance] restart [-h]
105
108 usage: dsctl [instance] start [-h]
109
112 usage: dsctl [instance] stop [-h]
113
116 usage: dsctl [instance] status [-h]
117
120 usage: dsctl [instance] remove [-h] [--do-it]
121
124 --do-it
125 By default we do a dry run. This actually initiates the removal
126 of the instance.
127
130 usage: dsctl [instance] db2index [-h] [--attr [ATTR ...]] [backend]
131 backend
134 The backend to reindex. IE userRoot
135
138 --attr [ATTR ...]
139 The attribute's to reindex. IE --attr aci cn givenname
140
143 usage: dsctl [instance] db2bak [-h] [archive]
144 archive
147 The destination for the archive. This will be created during the
148 db2bak process.
149
152 usage: dsctl [instance] db2ldif [-h] [--replication] [--encrypted]
153 backend [ldif]
154 backend
157 The backend to output as an LDIF. IE userRoot
158 ldif The path to the ldif output location.
161
164 --replication
165 Export replication information, suitable for importing on a new
166 consumer or backups.
167 --encrypted
170 Export encrypted attributes
171
174 usage: dsctl [instance] dbverify [-h] backend
175 backend
178 The backend to verify. IE userRoot
179
182 usage: dsctl [instance] bak2db [-h] archive
183 archive
186 The archive to restore. This will erase all current server data‐
187 bases.
188
191 usage: dsctl [instance] ldif2db [-h] [--encrypted] backend ldif
192 backend
195 The backend to restore from an LDIF. IE userRoot
196 ldif The path to the ldif to import
199
202 --encrypted
203 Import encrypted attributes
204
207 usage: dsctl [instance] backups [-h] [--delete DELETE]
208
211 --delete DELETE
212 Delete backup directory
213
216 usage: dsctl [instance] ldifs [-h] [--delete DELETE]
217
220 --delete DELETE
221 Delete LDIF file
222
225 usage: dsctl [instance] tls [-h]
226 {list-ca,list-client-ca,show-server-
227 cert,show-cert,generate-server-cert-csr,import-client-ca,import-ca,im‐
228 port-server-cert,import-server-key-cert,remove-cert}
229 ...
230
233 dsctl tls list-ca
234 list server certificate authorities including intermediates
235 dsctl tls list-client-ca
237 list client certificate authorities including intermediates
238 dsctl tls show-server-cert
240 Show the active server certificate that clients will see and
241 verify
242 dsctl tls show-cert
244 Show a certificate's details referenced by it's nickname. This
245 is analogous to certutil -L -d <path> -n <nickname>
246 dsctl tls generate-server-cert-csr
248 Generate a Server-Cert certificate signing request - the csr is
249 then submitted to a CA for verification, and when signed you im‐
250 port with import-ca and import-server-cert
251 dsctl tls import-client-ca
253 Import a CA trusted to issue user (client) certificates. This is
254 part of how client certificate authentication functions.
255 dsctl tls import-ca
257 Import a CA or intermediate CA for signing this servers certifi‐
258 cates (aka Server-Cert). You should import all the CA's in the
259 chain as required.
260 dsctl tls import-server-cert
262 Import a new Server-Cert after the csr has been signed from a
263 CA.
264 dsctl tls import-server-key-cert
266 Import a new key and Server-Cert after having been signed from a
267 CA. This is used if you have an external csr tool or a service
268 like lets encrypt that generates PEM keys externally.
269 dsctl tls remove-cert
271 Delete a certificate from this database. This will remove it
272 from acting as a CA, a client CA or the Server-Cert role.
273
275 usage: dsctl [instance] tls list-ca [-h]
276
279 usage: dsctl [instance] tls list-client-ca [-h]
280
283 usage: dsctl [instance] tls show-server-cert [-h]
284
287 usage: dsctl [instance] tls show-cert [-h] nickname
288 nickname
291 The nickname (friendly name) of the certificate to display
292
295 usage: dsctl [instance] tls generate-server-cert-csr [-h] [--subject
296 SUBJECT]
297 [alt_names ...]
298 alt_names
301 Certificate requests subject alternative names. These are
302 auto-detected if not provided
303
306 --subject SUBJECT, -s SUBJECT
307 Certificate Subject field to use
308
311 usage: dsctl [instance] tls import-client-ca [-h] cert_path nickname
312 cert_path
315 The path to the x509 cert to import as a client trust root
316 nickname
319 The name of the certificate once imported
320
323 usage: dsctl [instance] tls import-ca [-h] cert_path nickname
324 cert_path
327 The path to the x509 cert to import as a server CA
328 nickname
331 The name of the certificate once imported
332
335 usage: dsctl [instance] tls import-server-cert [-h] cert_path
336 cert_path
339 The path to the x509 cert to import as Server-Cert
340
343 usage: dsctl [instance] tls import-server-key-cert [-h] cert_path
344 key_path
345 cert_path
348 The path to the x509 cert to import as Server-Cert
349 key_path
352 The path to the x509 key to import associated to Server-Cert
353
356 usage: dsctl [instance] tls remove-cert [-h] nickname
357 nickname
360 The name of the certificate to delete
361
364 usage: dsctl [instance] healthcheck [-h] [--list-checks] [--list-er‐
365 rors]
366 [--dry-run] [--check CHECK [CHECK
367 ...]]
368
371 --list-checks
372 List of known checks
373 --list-errors
376 List of known error codes
377 --dry-run
380 Do not execute the actual check, only list what would be done
381 --check CHECK [CHECK ...]
384 Areas to check. These can be obtained by --list-checks. Every
385 element on the left of the colon (:) may be replaced by an as‐
386 terisk if multiple options on the right are available.
387
390 usage: dsctl [instance] get-nsstate [-h] [--suffix SUFFIX] [--flip
391 FLIP]
392
395 --suffix SUFFIX
396 The DN of the replication suffix to read the state from
397 --flip FLIP
400 Flip between Little/Big Endian, this might be required for cer‐
401 tain architectures
402
405 usage: dsctl [instance] ldifgen [-h]
406 {users,groups,cos-def,cos-tem‐
407 plate,roles,mod-load,nested}
408 ...
409
412 dsctl ldifgen users
413 Generate a LDIF containing user entries
414 dsctl ldifgen groups
416 Generate a LDIF containing groups and members
417 dsctl ldifgen cos-def
419 Generate a LDIF containing a COS definition (classic, pointer,
420 or indirect)
421 dsctl ldifgen cos-template
423 Generate a LDIF containing a COS template
424 dsctl ldifgen roles
426 Generate a LDIF containing a role entry (managed, filtered, or
427 indirect)
428 dsctl ldifgen mod-load
430 Generate a LDIF containing modify operations. This is intended
431 to be consumed by ldapmodify.
432 dsctl ldifgen nested
434 Generate a heavily nested database LDIF in a cascading/fractal
435 tree design
436
438 usage: dsctl [instance] ldifgen users [-h] [--number NUMBER] [--suffix
439 SUFFIX]
440 [--parent PARENT] [--generic]
441 [--start-idx START_IDX] [--rdn-
442 cn]
443 [--localize] [--ldif-file
444 LDIF_FILE]
445
448 --number NUMBER
449 The number of users to create.
450 --suffix SUFFIX
453 The database suffix where the entries will be created.
454 --parent PARENT
457 The parent entry that the user entries should be created under.
458 If not specified, the entries are stored under random Organiza‐
459 tional Units.
460 --generic
463 Create generic entries in the format of "uid=user####". These
464 entries are also compatible with ldclt.
465 --start-idx START_IDX
468 For generic LDIF's you can choose the starting index for the
469 user entries. The default is "0".
470 --rdn-cn
473 Use the attribute "cn" as the RDN attribute in the DN instead of
474 "uid"
475 --localize
478 Localize the LDIF data
479 --ldif-file LDIF_FILE
482 The LDIF file name. Default location is the server's LDIF direc‐
483 tory using the name 'users.ldif'
484
487 usage: dsctl [instance] ldifgen groups [-h] [--number NUMBER]
488 [--suffix SUFFIX] [--parent PAR‐
489 ENT]
490 [--num-members NUM_MEMBERS]
491 [--create-members]
492 [--member-parent MEMBER_PARENT]
493 [--member-attr MEMBER_ATTR]
494 [--ldif-file LDIF_FILE]
495 NAME
496 NAME The group name.
499
502 --number NUMBER
503 The number of groups to create.
504 --suffix SUFFIX
507 The database suffix where the groups will be created.
508 --parent PARENT
511 The parent entry that the group entries should be created under.
512 If not specified the groups are stored under the suffix.
513 --num-members NUM_MEMBERS
516 The number of members in the group. Default is 10000
517 --create-members
520 Create the member user entries.
521 --member-parent MEMBER_PARENT
524 The entry DN that the members should be created under. The de‐
525 fault is the suffix entry.
526 --member-attr MEMBER_ATTR
529 The membership attribute to use in the group. Default is
530 "uniquemember".
531 --ldif-file LDIF_FILE
534 The LDIF file name. Default is "/tmp/ldifgen.ldif"
535
538 usage: dsctl [instance] ldifgen cos-def [-h] [--type TYPE] [--parent
539 PARENT]
540 [--create-parent]
541 [--cos-specifier COS_SPECIFIER]
542 [--cos-template COS_TEMPLATE]
543 [--cos-attr [COS_ATTR ...]]
544 [--ldif-file LDIF_FILE]
545 NAME
546 NAME The COS definition name.
549
552 --type TYPE
553 The COS definition type: "classic", "pointer", or "indirect".
554 --parent PARENT
557 The parent entry that the COS definition should be created un‐
558 der.
559 --create-parent
562 Create the parent entry
563 --cos-specifier COS_SPECIFIER
566 Used in a classic COS definition, this attribute located in the
567 user entry is used to select which COS template to use.
568 --cos-template COS_TEMPLATE
571 The DN of the COS template entry, only used for "classic" and
572 "pointer" COS definitions.
573 --cos-attr [COS_ATTR ...]
576 A list of attributes which defines which attribute the COS gen‐
577 erates values for.
578 --ldif-file LDIF_FILE
581 The LDIF file name. Default is "/tmp/ldifgen.ldif"
582
585 usage: dsctl [instance] ldifgen cos-template [-h] [--parent PARENT]
586 [--create-parent]
587 [--cos-priority COS_PRIOR‐
588 ITY]
589 [--cos-attr-val
590 COS_ATTR_VAL]
591 [--ldif-file LDIF_FILE]
592 NAME
593 NAME The COS template name.
596
599 --parent PARENT
600 The DN of the entry to store the COS template entry under.
601 --create-parent
604 Create the parent entry
605 --cos-priority COS_PRIORITY
608 Sets the priority of this conflicting/competing COS templates.
609 --cos-attr-val COS_ATTR_VAL
612 defines the attribute and value that the template provides.
613 --ldif-file LDIF_FILE
616 The LDIF file name. Default is "/tmp/ldifgen.ldif"
617
620 usage: dsctl [instance] ldifgen roles [-h] [--type TYPE] [--parent PAR‐
621 ENT]
622 [--create-parent] [--filter FIL‐
623 TER]
624 [--role-dn [ROLE_DN ...]]
625 [--ldif-file LDIF_FILE]
626 NAME
627 NAME The Role name.
630
633 --type TYPE
634 The Role type: "managed", "filtered", or "nested".
635 --parent PARENT
638 The DN of the entry to store the Role entry under
639 --create-parent
642 Create the parent entry
643 --filter FILTER
646 A search filter for gathering Role members. Required for a "fil‐
647 tered" role.
648 --role-dn [ROLE_DN ...]
651 A DN of a role entry that should be included in this role. Used
652 for "nested" roles only.
653 --ldif-file LDIF_FILE
656 The LDIF file name. Default is "/tmp/ldifgen.ldif"
657
660 usage: dsctl [instance] ldifgen mod-load [-h] [--create-users]
661 [--delete-users]
662 [--num-users NUM_USERS]
663 [--parent PARENT] [--create-
664 parent]
665 [--add-users ADD_USERS]
666 [--del-users DEL_USERS]
667 [--modrdn-users MODRDN_USERS]
668 [--mod-users MOD_USERS]
669 [--mod-attrs [MOD_ATTRS ...]]
670 [--randomize] [--ldif-file
671 LDIF_FILE]
672
675 --create-users
676 Create the entries that will be modified or deleted. By default
677 the script assumes the user entries already exist.
678 --delete-users
681 Delete all the user entries at the end of the LDIF.
682 --num-users NUM_USERS
685 The number of user entries that will be modified or deleted
686 --parent PARENT
689 The DN of the parent entry where the user entries are located.
690 --create-parent
693 Create the parent entry
694 --add-users ADD_USERS
697 The number of additional entries to add during the load.
698 --del-users DEL_USERS
701 The number of entries to delete during the load.
702 --modrdn-users MODRDN_USERS
705 The number of entries to perform a modrdn operation on.
706 --mod-users MOD_USERS
709 The number of entries to modify.
710 --mod-attrs [MOD_ATTRS ...]
713 List of attributes the script will randomly choose from when
714 modifying an entry. The default is "description".
715 --randomize
718 Randomly perform the specified add, mod, delete, and modrdn op‐
719 erations
720 --ldif-file LDIF_FILE
723 The LDIF file name. Default is "/tmp/ldifgen.ldif"
724
727 usage: dsctl [instance] ldifgen nested [-h] [--num-users NUM_USERS]
728 [--node-limit NODE_LIMIT]
729 [--suffix SUFFIX]
730 [--ldif-file LDIF_FILE]
731
734 --num-users NUM_USERS
735 The total number of user entries to create in the entire LDIF
736 (does not include the container entries).
737 --node-limit NODE_LIMIT
740 The total number of user entries to create under each node/sub‐
741 tree
742 --suffix SUFFIX
745 The suffix DN for the LDIF
746 --ldif-file LDIF_FILE
749 The LDIF file name. Default location is the server's LDIF direc‐
750 tory using the name 'users.ldif'
751
754 usage: dsctl [instance] dsrc [-h] {create,modify,delete,display} ...
755
758 dsctl dsrc create
759 Generate the .dsrc file
760 dsctl dsrc modify
762 Modify the .dsrc file
763 dsctl dsrc delete
765 Delete instance configuration from the .dsrc file.
766 dsctl dsrc display
768 Display the contents of the .dsrc file.
769
771 usage: dsctl [instance] dsrc create [-h] [--uri URI] [--basedn BASEDN]
772 [--binddn BINDDN] [--saslmech
773 SASLMECH]
774 [--tls-cacertdir TLS_CACERTDIR]
775 [--tls-cert TLS_CERT] [--tls-key
776 TLS_KEY]
777 [--tls-reqcert TLS_REQCERT]
778 [--starttls]
779 [--pwdfile PWDFILE] [--do-it]
780
783 --uri URI
784 The URI (LDAP URL) for the Directory Server instance.
785 --basedn BASEDN
788 The default database suffix.
789 --binddn BINDDN
792 The default Bind DN used or authentication.
793 --saslmech SASLMECH
796 The SASL mechanism to use: PLAIN or EXTERNAL.
797 --tls-cacertdir TLS_CACERTDIR
800 The directory containing the Trusted Certificate Authority cer‐
801 tificate.
802 --tls-cert TLS_CERT
805 The absolute file name to the server certificate.
806 --tls-key TLS_KEY
809 The absolute file name to the server certificate key.
810 --tls-reqcert TLS_REQCERT
813 Request certificate strength: 'never', 'allow', 'hard'
814 --starttls
817 Use startTLS for connection to the server.
818 --pwdfile PWDFILE
821 The absolute path to a file containing the Bind DN's password.
822 --do-it
825 Create the file without any confirmation.
826
829 usage: dsctl [instance] dsrc modify [-h] [--uri [URI]] [--basedn
830 [BASEDN]]
831 [--binddn [BINDDN]]
832 [--saslmech [SASLMECH]]
833 [--tls-cacertdir [TLS_CACERTDIR]]
834 [--tls-cert [TLS_CERT]]
835 [--tls-key [TLS_KEY]]
836 [--tls-reqcert [TLS_REQCERT]]
837 [--starttls]
838 [--cancel-starttls] [--pwdfile
839 [PWDFILE]]
840 [--do-it]
841
844 --uri [URI]
845 The URI (LDAP URL) for the Directory Server instance.
846 --basedn [BASEDN]
849 The default database suffix.
850 --binddn [BINDDN]
853 The default Bind DN used or authentication.
854 --saslmech [SASLMECH]
857 The SASL mechanism to use: PLAIN or EXTERNAL.
858 --tls-cacertdir [TLS_CACERTDIR]
861 The directory containing the Trusted Certificate Authority cer‐
862 tificate.
863 --tls-cert [TLS_CERT]
866 The absolute file name to the server certificate.
867 --tls-key [TLS_KEY]
870 The absolute file name to the server certificate key.
871 --tls-reqcert [TLS_REQCERT]
874 Request certificate strength: 'never', 'allow', 'hard'
875 --starttls
878 Use startTLS for connection to the server.
879 --cancel-starttls
882 Do not use startTLS for connection to the server.
883 --pwdfile [PWDFILE]
886 The absolute path to a file containing the Bind DN's password.
887 --do-it
890 Update the file without any confirmation.
891
894 usage: dsctl [instance] dsrc delete [-h] [--do-it]
895
898 --do-it
899 Delete this instance's configuration from the .dsrc file.
900
903 usage: dsctl [instance] dsrc display [-h]
904
907 usage: dsctl [instance] cockpit [-h]
908 {enable,open-firewall,disable,close-
909 firewall}
910 ...
911
914 dsctl cockpit enable
915 Enable the Cockpit socket
916 dsctl cockpit open-firewall
918 Open the firewall for the "cockpit" service
919 dsctl cockpit disable
921 Disable the Cockpit socket
922 dsctl cockpit close-firewall
924 Remove the "cockpit" service from the firewall settings
925
927 usage: dsctl [instance] cockpit enable [-h]
928
931 usage: dsctl [instance] cockpit open-firewall [-h] [--zone ZONE]
932
935 --zone ZONE
936 The firewall zone
937
940 usage: dsctl [instance] cockpit disable [-h]
941
944 usage: dsctl [instance] cockpit close-firewall [-h]
945
948 usage: dsctl [instance] dblib [-h] {bdb2mdb,mdb2bdb,cleanup} ...
949
952 dsctl dblib bdb2mdb
953 Migrate bdb databases to lmdb
954 dsctl dblib mdb2bdb
956 Migrate lmdb databases to bdb
957 dsctl dblib cleanup
959 Remove migration ldif file and old database
960
962 usage: dsctl [instance] dblib bdb2mdb [-h] [--tmpdir TMPDIR]
963
966 --tmpdir TMPDIR
967 ldif migration files directory path.
968
971 usage: dsctl [instance] dblib mdb2bdb [-h] [--tmpdir TMPDIR]
972
975 --tmpdir TMPDIR
976 ldif migration files directory path.
977
980 usage: dsctl [instance] dblib cleanup [-h]
981
984 -v, --verbose
985 Display verbose operation tracing during command execution
986 -j, --json
989 Return result in JSON object
990 -l, --list
993 List available Directory Server instances
994
997 Red Hat Inc., and William Brown <389-devel@lists.fedoraproject.org>
998
1001 The latest version of lib389 may be downloaded from
1002 ⟨http://www.port389.org/docs/389ds/FAQ/upstream-test-framework.html⟩
1003 Manual DSCTL(8)