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} ...
12
14 instance
15 The name of the instance to act upon
16 Sub-commands
19 dsctl restart
20 Restart an instance of Directory Server, if it is running: else
21 start it.
22 dsctl start
24 Start an instance of Directory Server, if it is not currently
25 running
26 dsctl stop
28 Stop an instance of Directory Server, if it is currently running
29 dsctl status
31 Check running status of an instance of Directory Server
32 dsctl remove
34 Destroy an instance of Directory Server, and remove all data.
35 dsctl db2index
37 Initialise a reindex of the server database. The server must be
38 stopped for this to proceed.
39 dsctl db2bak
41 Initialise a BDB backup of the database. The server must be
42 stopped for this to proceed.
43 dsctl db2ldif
45 Initialise an LDIF dump of the database. The server must be
46 stopped for this to proceed.
47 dsctl dbverify
49 Perform a db verification. You should only do this at direction
50 of support
51 dsctl bak2db
53 Restore a BDB backup of the database. The server must be stopped
54 for this to proceed.
55 dsctl ldif2db
57 Restore an LDIF dump of the database. The server must be stopped
58 for this to proceed.
59 dsctl backups
61 List backup's found in the server's default backup directory
62 dsctl ldifs
64 List all the LDIF files located in the server's LDIF directory
65 dsctl tls
67 Manage TLS certificates
68 dsctl healthcheck
70 Run a healthcheck report on a local Directory Server instance.
71 This is a safe and read-only operation. Do not attempt to run
72 this on a remote Directory Server as this tool needs access to
73 local resources, otherwise the report may be inaccurate.
74 dsctl get-nsstate
76 Get the replication nsState in a human readable format
77 Replica DN: The DN of the replication configuration
79 entry Replica Suffix: The replicated suffix Replica ID:
80 The Replica identifier Gen Time The time the CSN
81 generator was created Gen Time String: The time string of
82 generator Gen as CSN: The generation CSN Local Offset:
83 The offset due to the local clock being set back Local Offset
84 String: The offset in a nice human format Remote Offset:
85 The offset due to clock difference with remote systems Remote
86 Offset String: The offset in a nice human format Time Skew:
87 The time skew between this server and its replicas Time Skew
88 String: The time skew in a nice human format Seq Num:
89 The number of multiple csns within a second System Time:
90 The local system time Diff in Seconds: The time difference
91 in seconds from the CSN generator creation to now Diff in
92 days/secs: The time difference broken up into days and sec‐
93 onds Endian: Little/Big Endian
94 dsctl ldifgen
97 LDIF generator to make sample LDIF files for testing
98 dsctl dsrc
100 Manage the .dsrc file
101 dsctl cockpit
103 Enable the Cockpit interface/UI
104
106 usage: dsctl [instance] restart [-h]
107
112 usage: dsctl [instance] start [-h]
113
118 usage: dsctl [instance] stop [-h]
119
124 usage: dsctl [instance] status [-h]
125
130 usage: dsctl [instance] remove [-h] [--do-it]
131 --do-it
135 By default we do a dry run. This actually initiates the removal
136 of the instance.
137
140 usage: dsctl [instance] db2index [-h] [--attr [ATTR ...]] [backend]
141 backend
144 The backend to reindex. IE userRoot
145 --attr [ATTR ...]
148 The attribute's to reindex. IE --attr aci cn givenname
149
152 usage: dsctl [instance] db2bak [-h] [archive]
153 archive
156 The destination for the archive. This will be created during the
157 db2bak process.
158
162 usage: dsctl [instance] db2ldif [-h] [--replication] [--encrypted]
163 backend [ldif]
164 backend
167 The backend to output as an LDIF. IE userRoot
168 ldif The path to the ldif output location.
171 --replication
174 Export replication information, suitable for importing on a new
175 consumer or backups.
176 --encrypted
179 Export encrypted attributes
180
183 usage: dsctl [instance] dbverify [-h] backend
184 backend
187 The backend to verify. IE userRoot
188
192 usage: dsctl [instance] bak2db [-h] archive
193 archive
196 The archive to restore. This will erase all current server data‐
197 bases.
198
202 usage: dsctl [instance] ldif2db [-h] [--encrypted] backend ldif
203 backend
206 The backend to restore from an LDIF. IE userRoot
207 ldif The path to the ldif to import
210 --encrypted
213 Import encrypted attributes
214
217 usage: dsctl [instance] backups [-h] [--delete DELETE]
218 --delete DELETE
222 Delete backup directory
223
226 usage: dsctl [instance] ldifs [-h] [--delete DELETE]
227 --delete DELETE
231 Delete LDIF file
232
235 usage: dsctl [instance] tls [-h]
236 {list-ca,list-client-ca,show-server-
237 cert,show-cert,generate-server-cert-csr,import-client-ca,import-ca,im‐
238 port-server-cert,import-server-key-cert,remove-cert}
239 ...
240 Sub-commands
243 dsctl tls list-ca
244 list server certificate authorities including intermediates
245 dsctl tls list-client-ca
247 list client certificate authorities including intermediates
248 dsctl tls show-server-cert
250 Show the active server certificate that clients will see and
251 verify
252 dsctl tls show-cert
254 Show a certificate's details referenced by it's nickname. This
255 is analogous to certutil -L -d <path> -n <nickname>
256 dsctl tls generate-server-cert-csr
258 Generate a Server-Cert certificate signing request - the csr is
259 then submitted to a CA for verification, and when signed you im‐
260 port with import-ca and import-server-cert
261 dsctl tls import-client-ca
263 Import a CA trusted to issue user (client) certificates. This is
264 part of how client certificate authentication functions.
265 dsctl tls import-ca
267 Import a CA or intermediate CA for signing this servers certifi‐
268 cates (aka Server-Cert). You should import all the CA's in the
269 chain as required.
270 dsctl tls import-server-cert
272 Import a new Server-Cert after the csr has been signed from a
273 CA.
274 dsctl tls import-server-key-cert
276 Import a new key and Server-Cert after having been signed from a
277 CA. This is used if you have an external csr tool or a service
278 like lets encrypt that generates PEM keys externally.
279 dsctl tls remove-cert
281 Delete a certificate from this database. This will remove it
282 from acting as a CA, a client CA or the Server-Cert role.
283
285 usage: dsctl [instance] tls list-ca [-h]
286
291 usage: dsctl [instance] tls list-client-ca [-h]
292
297 usage: dsctl [instance] tls show-server-cert [-h]
298
303 usage: dsctl [instance] tls show-cert [-h] nickname
304 nickname
307 The nickname (friendly name) of the certificate to display
308
312 usage: dsctl [instance] tls generate-server-cert-csr [-h] [--subject
313 SUBJECT]
314 [alt_names ...]
315 alt_names
318 Certificate requests subject alternative names. These are
319 auto-detected if not provided
320 --subject SUBJECT, -s SUBJECT
323 Certificate Subject field to use
324
327 usage: dsctl [instance] tls import-client-ca [-h] cert_path nickname
328 cert_path
331 The path to the x509 cert to import as a client trust root
332 nickname
335 The name of the certificate once imported
336
340 usage: dsctl [instance] tls import-ca [-h] cert_path nickname
341 cert_path
344 The path to the x509 cert to import as a server CA
345 nickname
348 The name of the certificate once imported
349
353 usage: dsctl [instance] tls import-server-cert [-h] cert_path
354 cert_path
357 The path to the x509 cert to import as Server-Cert
358
362 usage: dsctl [instance] tls import-server-key-cert [-h] cert_path
363 key_path
364 cert_path
367 The path to the x509 cert to import as Server-Cert
368 key_path
371 The path to the x509 key to import associated to Server-Cert
372
376 usage: dsctl [instance] tls remove-cert [-h] nickname
377 nickname
380 The name of the certificate to delete
381
386 usage: dsctl [instance] healthcheck [-h] [--list-checks] [--list-er‐
387 rors]
388 [--dry-run] [--check CHECK [CHECK
389 ...]]
390 --list-checks
394 List of known checks
395 --list-errors
398 List of known error codes
399 --dry-run
402 Do not execute the actual check, only list what would be done
403 --check CHECK [CHECK ...]
406 Areas to check. These can be obtained by --list-checks. Every
407 element on the left of the colon (:) may be replaced by an as‐
408 terisk if multiple options on the right are available.
409
412 usage: dsctl [instance] get-nsstate [-h] [--suffix SUFFIX] [--flip
413 FLIP]
414 --suffix SUFFIX
418 The DN of the replication suffix to read the state from
419 --flip FLIP
422 Flip between Little/Big Endian, this might be required for cer‐
423 tain architectures
424
427 usage: dsctl [instance] ldifgen [-h]
428 {users,groups,cos-def,cos-tem‐
429 plate,roles,mod-load,nested}
430 ...
431 Sub-commands
434 dsctl ldifgen users
435 Generate a LDIF containing user entries
436 dsctl ldifgen groups
438 Generate a LDIF containing groups and members
439 dsctl ldifgen cos-def
441 Generate a LDIF containing a COS definition (classic, pointer,
442 or indirect)
443 dsctl ldifgen cos-template
445 Generate a LDIF containing a COS template
446 dsctl ldifgen roles
448 Generate a LDIF containing a role entry (managed, filtered, or
449 indirect)
450 dsctl ldifgen mod-load
452 Generate a LDIF containing modify operations. This is intended
453 to be consumed by ldapmodify.
454 dsctl ldifgen nested
456 Generate a heavily nested database LDIF in a cascading/fractal
457 tree design
458
460 usage: dsctl [instance] ldifgen users [-h] [--number NUMBER] [--suffix
461 SUFFIX]
462 [--parent PARENT] [--generic]
463 [--start-idx START_IDX] [--rdn-
464 cn]
465 [--localize] [--ldif-file
466 LDIF_FILE]
467 --number NUMBER
471 The number of users to create.
472 --suffix SUFFIX
475 The database suffix where the entries will be created.
476 --parent PARENT
479 The parent entry that the user entries should be created under.
480 If not specified, the entries are stored under random Organiza‐
481 tional Units.
482 --generic
485 Create generic entries in the format of "uid=user####". These
486 entries are also compatible with ldclt.
487 --start-idx START_IDX
490 For generic LDIF's you can choose the starting index for the
491 user entries. The default is "0".
492 --rdn-cn
495 Use the attribute "cn" as the RDN attribute in the DN instead of
496 "uid"
497 --localize
500 Localize the LDIF data
501 --ldif-file LDIF_FILE
504 The LDIF file name. Default location is the server's LDIF direc‐
505 tory using the name 'users.ldif'
506
509 usage: dsctl [instance] ldifgen groups [-h] [--number NUMBER]
510 [--suffix SUFFIX] [--parent PAR‐
511 ENT]
512 [--num-members NUM_MEMBERS]
513 [--create-members]
514 [--member-parent MEMBER_PARENT]
515 [--member-attr MEMBER_ATTR]
516 [--ldif-file LDIF_FILE]
517 NAME
518 NAME The group name.
521 --number NUMBER
524 The number of groups to create.
525 --suffix SUFFIX
528 The database suffix where the groups will be created.
529 --parent PARENT
532 The parent entry that the group entries should be created under.
533 If not specified the groups are stored under the suffix.
534 --num-members NUM_MEMBERS
537 The number of members in the group. Default is 10000
538 --create-members
541 Create the member user entries.
542 --member-parent MEMBER_PARENT
545 The entry DN that the members should be created under. The de‐
546 fault is the suffix entry.
547 --member-attr MEMBER_ATTR
550 The membership attribute to use in the group. Default is
551 "uniquemember".
552 --ldif-file LDIF_FILE
555 The LDIF file name. Default is "/tmp/ldifgen.ldif"
556
559 usage: dsctl [instance] ldifgen cos-def [-h] [--type TYPE] [--parent
560 PARENT]
561 [--create-parent]
562 [--cos-specifier COS_SPECIFIER]
563 [--cos-template COS_TEMPLATE]
564 [--cos-attr [COS_ATTR ...]]
565 [--ldif-file LDIF_FILE]
566 NAME
567 NAME The COS definition name.
570 --type TYPE
573 The COS definition type: "classic", "pointer", or "indirect".
574 --parent PARENT
577 The parent entry that the COS definition should be created un‐
578 der.
579 --create-parent
582 Create the parent entry
583 --cos-specifier COS_SPECIFIER
586 Used in a classic COS definition, this attribute located in the
587 user entry is used to select which COS template to use.
588 --cos-template COS_TEMPLATE
591 The DN of the COS template entry, only used for "classic" and
592 "pointer" COS definitions.
593 --cos-attr [COS_ATTR ...]
596 A list of attributes which defines which attribute the COS gen‐
597 erates values for.
598 --ldif-file LDIF_FILE
601 The LDIF file name. Default is "/tmp/ldifgen.ldif"
602
605 usage: dsctl [instance] ldifgen cos-template [-h] [--parent PARENT]
606 [--create-parent]
607 [--cos-priority COS_PRIOR‐
608 ITY]
609 [--cos-attr-val
610 COS_ATTR_VAL]
611 [--ldif-file LDIF_FILE]
612 NAME
613 NAME The COS template name.
616 --parent PARENT
619 The DN of the entry to store the COS template entry under.
620 --create-parent
623 Create the parent entry
624 --cos-priority COS_PRIORITY
627 Sets the priority of this conflicting/competing COS templates.
628 --cos-attr-val COS_ATTR_VAL
631 defines the attribute and value that the template provides.
632 --ldif-file LDIF_FILE
635 The LDIF file name. Default is "/tmp/ldifgen.ldif"
636
639 usage: dsctl [instance] ldifgen roles [-h] [--type TYPE] [--parent PAR‐
640 ENT]
641 [--create-parent] [--filter FIL‐
642 TER]
643 [--role-dn [ROLE_DN ...]]
644 [--ldif-file LDIF_FILE]
645 NAME
646 NAME The Role name.
649 --type TYPE
652 The Role type: "managed", "filtered", or "nested".
653 --parent PARENT
656 The DN of the entry to store the Role entry under
657 --create-parent
660 Create the parent entry
661 --filter FILTER
664 A search filter for gathering Role members. Required for a "fil‐
665 tered" role.
666 --role-dn [ROLE_DN ...]
669 A DN of a role entry that should be included in this role. Used
670 for "nested" roles only.
671 --ldif-file LDIF_FILE
674 The LDIF file name. Default is "/tmp/ldifgen.ldif"
675
678 usage: dsctl [instance] ldifgen mod-load [-h] [--create-users]
679 [--delete-users]
680 [--num-users NUM_USERS]
681 [--parent PARENT] [--create-
682 parent]
683 [--add-users ADD_USERS]
684 [--del-users DEL_USERS]
685 [--modrdn-users MODRDN_USERS]
686 [--mod-users MOD_USERS]
687 [--mod-attrs [MOD_ATTRS ...]]
688 [--randomize] [--ldif-file
689 LDIF_FILE]
690 --create-users
694 Create the entries that will be modified or deleted. By default
695 the script assumes the user entries already exist.
696 --delete-users
699 Delete all the user entries at the end of the LDIF.
700 --num-users NUM_USERS
703 The number of user entries that will be modified or deleted
704 --parent PARENT
707 The DN of the parent entry where the user entries are located.
708 --create-parent
711 Create the parent entry
712 --add-users ADD_USERS
715 The number of additional entries to add during the load.
716 --del-users DEL_USERS
719 The number of entries to delete during the load.
720 --modrdn-users MODRDN_USERS
723 The number of entries to perform a modrdn operation on.
724 --mod-users MOD_USERS
727 The number of entries to modify.
728 --mod-attrs [MOD_ATTRS ...]
731 List of attributes the script will randomly choose from when
732 modifying an entry. The default is "description".
733 --randomize
736 Randomly perform the specified add, mod, delete, and modrdn op‐
737 erations
738 --ldif-file LDIF_FILE
741 The LDIF file name. Default is "/tmp/ldifgen.ldif"
742
745 usage: dsctl [instance] ldifgen nested [-h] [--num-users NUM_USERS]
746 [--node-limit NODE_LIMIT]
747 [--suffix SUFFIX]
748 [--ldif-file LDIF_FILE]
749 --num-users NUM_USERS
753 The total number of user entries to create in the entire LDIF
754 (does not include the container entries).
755 --node-limit NODE_LIMIT
758 The total number of user entries to create under each node/sub‐
759 tree
760 --suffix SUFFIX
763 The suffix DN for the LDIF
764 --ldif-file LDIF_FILE
767 The LDIF file name. Default location is the server's LDIF direc‐
768 tory using the name 'users.ldif'
769
773 usage: dsctl [instance] dsrc [-h] {create,modify,delete,display} ...
774 Sub-commands
777 dsctl dsrc create
778 Generate the .dsrc file
779 dsctl dsrc modify
781 Modify the .dsrc file
782 dsctl dsrc delete
784 Delete instance configuration from the .dsrc file.
785 dsctl dsrc display
787 Display the contents of the .dsrc file.
788
790 usage: dsctl [instance] dsrc create [-h] [--uri URI] [--basedn BASEDN]
791 [--binddn BINDDN] [--saslmech
792 SASLMECH]
793 [--tls-cacertdir TLS_CACERTDIR]
794 [--tls-cert TLS_CERT] [--tls-key
795 TLS_KEY]
796 [--tls-reqcert TLS_REQCERT]
797 [--starttls]
798 [--pwdfile PWDFILE] [--do-it]
799 --uri URI
803 The URI (LDAP URL) for the Directory Server instance.
804 --basedn BASEDN
807 The default database suffix.
808 --binddn BINDDN
811 The default Bind DN used or authentication.
812 --saslmech SASLMECH
815 The SASL mechanism to use: PLAIN or EXTERNAL.
816 --tls-cacertdir TLS_CACERTDIR
819 The directory containing the Trusted Certificate Authority cer‐
820 tificate.
821 --tls-cert TLS_CERT
824 The absolute file name to the server certificate.
825 --tls-key TLS_KEY
828 The absolute file name to the server certificate key.
829 --tls-reqcert TLS_REQCERT
832 Request certificate strength: 'never', 'allow', 'hard'
833 --starttls
836 Use startTLS for connection to the server.
837 --pwdfile PWDFILE
840 The absolute path to a file containing the Bind DN's password.
841 --do-it
844 Create the file without any confirmation.
845
848 usage: dsctl [instance] dsrc modify [-h] [--uri [URI]] [--basedn
849 [BASEDN]]
850 [--binddn [BINDDN]]
851 [--saslmech [SASLMECH]]
852 [--tls-cacertdir [TLS_CACERTDIR]]
853 [--tls-cert [TLS_CERT]]
854 [--tls-key [TLS_KEY]]
855 [--tls-reqcert [TLS_REQCERT]]
856 [--starttls]
857 [--cancel-starttls] [--pwdfile
858 [PWDFILE]]
859 [--do-it]
860 --uri [URI]
864 The URI (LDAP URL) for the Directory Server instance.
865 --basedn [BASEDN]
868 The default database suffix.
869 --binddn [BINDDN]
872 The default Bind DN used or authentication.
873 --saslmech [SASLMECH]
876 The SASL mechanism to use: PLAIN or EXTERNAL.
877 --tls-cacertdir [TLS_CACERTDIR]
880 The directory containing the Trusted Certificate Authority cer‐
881 tificate.
882 --tls-cert [TLS_CERT]
885 The absolute file name to the server certificate.
886 --tls-key [TLS_KEY]
889 The absolute file name to the server certificate key.
890 --tls-reqcert [TLS_REQCERT]
893 Request certificate strength: 'never', 'allow', 'hard'
894 --starttls
897 Use startTLS for connection to the server.
898 --cancel-starttls
901 Do not use startTLS for connection to the server.
902 --pwdfile [PWDFILE]
905 The absolute path to a file containing the Bind DN's password.
906 --do-it
909 Update the file without any confirmation.
910
913 usage: dsctl [instance] dsrc delete [-h] [--do-it]
914 --do-it
918 Delete this instance's configuration from the .dsrc file.
919
922 usage: dsctl [instance] dsrc display [-h]
923
929 usage: dsctl [instance] cockpit [-h]
930 {enable,open-firewall,disable,close-
931 firewall}
932 ...
933 Sub-commands
936 dsctl cockpit enable
937 Enable the Cockpit socket
938 dsctl cockpit open-firewall
940 Open the firewall for the "cockpit" service
941 dsctl cockpit disable
943 Disable the Cockpit socket
944 dsctl cockpit close-firewall
946 Remove the "cockpit" service from the firewall settings
947
949 usage: dsctl [instance] cockpit enable [-h]
950
955 usage: dsctl [instance] cockpit open-firewall [-h] [--zone ZONE]
956 --zone ZONE
960 The firewall zone
961
964 usage: dsctl [instance] cockpit disable [-h]
965
970 usage: dsctl [instance] cockpit close-firewall [-h]
971 -v, --verbose
977 Display verbose operation tracing during command execution
978 -j, --json
981 Return result in JSON object
982 -l, --list
985 List available Directory Server instances
986
989 lib389 was written by Red Hat Inc., and William Brown <389-de‐
990 vel@lists.fedoraproject.org>.
991
993 The latest version of lib389 may be downloaded from
994 ⟨http://www.port389.org/docs/389ds/FAQ/upstream-test-framework.html⟩
995 Manual dsctl(8)