1dsctl(8) System Manager's Manual dsctl(8)
2
6 dsctl
7
9 dsctl [-h] [-v] [-j] [-l] [instance] {restart,start,stop,sta‐
10 tus,remove,db2index,db2bak,db2ldif,dbverify,bak2db,ldif2db,back‐
11 ups,ldifs,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] backend
141 backend
144 The backend to reindex. IE userRoot
145
149 usage: dsctl [instance] db2bak [-h] [archive]
150 archive
153 The destination for the archive. This will be created during the
154 db2bak process.
155
159 usage: dsctl [instance] db2ldif [-h] [--replication] [--encrypted]
160 backend [ldif]
161 backend
164 The backend to output as an LDIF. IE userRoot
165 ldif The path to the ldif output location.
168 --replication
171 Export replication information, suitable for importing on a new
172 consumer or backups.
173 --encrypted
176 Export encrypted attributes
177
180 usage: dsctl [instance] dbverify [-h] backend
181 backend
184 The backend to verify. IE userRoot
185
189 usage: dsctl [instance] bak2db [-h] archive
190 archive
193 The archive to restore. This will erase all current server data‐
194 bases.
195
199 usage: dsctl [instance] ldif2db [-h] [--encrypted] backend ldif
200 backend
203 The backend to restore from an LDIF. IE userRoot
204 ldif The path to the ldif to import
207 --encrypted
210 Import encrypted attributes
211
214 usage: dsctl [instance] backups [-h] [--delete DELETE]
215 --delete DELETE
219 Delete backup directory
220
223 usage: dsctl [instance] ldifs [-h] [--delete DELETE]
224 --delete DELETE
228 Delete LDIF file
229
232 usage: dsctl [instance] tls [-h]
233 {list-ca,list-client-ca,show-server-
234 cert,show-cert,generate-server-cert-csr,import-client-ca,import-
235 ca,import-server-cert,import-server-key-cert,remove-cert}
236 ...
237 Sub-commands
240 dsctl tls list-ca
241 list server certificate authorities including intermediates
242 dsctl tls list-client-ca
244 list client certificate authorities including intermediates
245 dsctl tls show-server-cert
247 Show the active server certificate that clients will see and
248 verify
249 dsctl tls show-cert
251 Show a certificate's details referenced by it's nickname. This
252 is analogous to certutil -L -d <path> -n <nickname>
253 dsctl tls generate-server-cert-csr
255 Generate a Server-Cert certificate signing request - the csr is
256 then submitted to a CA for verification, and when signed you
257 import with import-ca and import-server-cert
258 dsctl tls import-client-ca
260 Import a CA trusted to issue user (client) certificates. This is
261 part of how client certificate authentication functions.
262 dsctl tls import-ca
264 Import a CA or intermediate CA for signing this servers certifi‐
265 cates (aka Server-Cert). You should import all the CA's in the
266 chain as required.
267 dsctl tls import-server-cert
269 Import a new Server-Cert after the csr has been signed from a
270 CA.
271 dsctl tls import-server-key-cert
273 Import a new key and Server-Cert after having been signed from a
274 CA. This is used if you have an external csr tool or a service
275 like lets encrypt that generates PEM keys externally.
276 dsctl tls remove-cert
278 Delete a certificate from this database. This will remove it
279 from acting as a CA, a client CA or the Server-Cert role.
280
282 usage: dsctl [instance] tls list-ca [-h]
283
288 usage: dsctl [instance] tls list-client-ca [-h]
289
294 usage: dsctl [instance] tls show-server-cert [-h]
295
300 usage: dsctl [instance] tls show-cert [-h] nickname
301 nickname
304 The nickname (friendly name) of the certificate to display
305
309 usage: dsctl [instance] tls generate-server-cert-csr [-h] [--subject
310 SUBJECT]
311 [alt_names ...]
312 alt_names
315 Certificate requests subject alternative names. These are
316 auto-detected if not provided
317 --subject SUBJECT, -s SUBJECT
320 Certificate Subject field to use
321
324 usage: dsctl [instance] tls import-client-ca [-h] cert_path nickname
325 cert_path
328 The path to the x509 cert to import as a client trust root
329 nickname
332 The name of the certificate once imported
333
337 usage: dsctl [instance] tls import-ca [-h] cert_path nickname
338 cert_path
341 The path to the x509 cert to import as a server CA
342 nickname
345 The name of the certificate once imported
346
350 usage: dsctl [instance] tls import-server-cert [-h] cert_path
351 cert_path
354 The path to the x509 cert to import as Server-Cert
355
359 usage: dsctl [instance] tls import-server-key-cert [-h] cert_path
360 key_path
361 cert_path
364 The path to the x509 cert to import as Server-Cert
365 key_path
368 The path to the x509 key to import associated to Server-Cert
369
373 usage: dsctl [instance] tls remove-cert [-h] nickname
374 nickname
377 The name of the certificate to delete
378
383 usage: dsctl [instance] healthcheck [-h] [--list-checks] [--list-
384 errors]
385 [--dry-run] [--check CHECK [CHECK
386 ...]]
387 --list-checks
391 List of known checks
392 --list-errors
395 List of known error codes
396 --dry-run
399 Do not execute the actual check, only list what would be done
400 --check CHECK [CHECK ...]
403 Areas to check. These can be obtained by --list-checks. Every
404 element on the left of the colon (:) may be replaced by an
405 asterisk if multiple options on the right are available.
406
409 usage: dsctl [instance] get-nsstate [-h] [--suffix SUFFIX] [--flip
410 FLIP]
411 --suffix SUFFIX
415 The DN of the replication suffix to read the state from
416 --flip FLIP
419 Flip between Little/Big Endian, this might be required for cer‐
420 tain architectures
421
424 usage: dsctl [instance] ldifgen [-h]
425 {users,groups,cos-def,cos-tem‐
426 plate,roles,mod-load,nested}
427 ...
428 Sub-commands
431 dsctl ldifgen users
432 Generate a LDIF containing user entries
433 dsctl ldifgen groups
435 Generate a LDIF containing groups and members
436 dsctl ldifgen cos-def
438 Generate a LDIF containing a COS definition (classic, pointer,
439 or indirect)
440 dsctl ldifgen cos-template
442 Generate a LDIF containing a COS template
443 dsctl ldifgen roles
445 Generate a LDIF containing a role entry (managed, filtered, or
446 indirect)
447 dsctl ldifgen mod-load
449 Generate a LDIF containing modify operations. This is intended
450 to be consumed by ldapmodify.
451 dsctl ldifgen nested
453 Generate a heavily nested database LDIF in a cascading/fractal
454 tree design
455
457 usage: dsctl [instance] ldifgen users [-h] [--number NUMBER] [--suffix
458 SUFFIX]
459 [--parent PARENT] [--generic]
460 [--start-idx START_IDX] [--rdn-
461 cn]
462 [--localize] [--ldif-file
463 LDIF_FILE]
464 --number NUMBER
468 The number of users to create.
469 --suffix SUFFIX
472 The database suffix where the entries will be created.
473 --parent PARENT
476 The parent entry that the user entries should be created under.
477 If not specified, the entries are stored under random Organiza‐
478 tional Units.
479 --generic
482 Create generic entries in the format of "uid=user####". These
483 entries are also compatible with ldclt.
484 --start-idx START_IDX
487 For generic LDIF's you can choose the starting index for the
488 user entries. The default is "0".
489 --rdn-cn
492 Use the attribute "cn" as the RDN attribute in the DN instead of
493 "uid"
494 --localize
497 Localize the LDIF data
498 --ldif-file LDIF_FILE
501 The LDIF file name. Default location is the server's LDIF direc‐
502 tory using the name 'users.ldif'
503
506 usage: dsctl [instance] ldifgen groups [-h] [--number NUMBER]
507 [--suffix SUFFIX] [--parent PAR‐
508 ENT]
509 [--num-members NUM_MEMBERS]
510 [--create-members]
511 [--member-parent MEMBER_PARENT]
512 [--member-attr MEMBER_ATTR]
513 [--ldif-file LDIF_FILE]
514 NAME
515 NAME The group name.
518 --number NUMBER
521 The number of groups to create.
522 --suffix SUFFIX
525 The database suffix where the groups will be created.
526 --parent PARENT
529 The parent entry that the group entries should be created under.
530 If not specified the groups are stored under the suffix.
531 --num-members NUM_MEMBERS
534 The number of members in the group. Default is 10000
535 --create-members
538 Create the member user entries.
539 --member-parent MEMBER_PARENT
542 The entry DN that the members should be created under. The
543 default is the suffix entry.
544 --member-attr MEMBER_ATTR
547 The membership attribute to use in the group. Default is
548 "uniquemember".
549 --ldif-file LDIF_FILE
552 The LDIF file name. Default is "/tmp/ldifgen.ldif"
553
556 usage: dsctl [instance] ldifgen cos-def [-h] [--type TYPE] [--parent
557 PARENT]
558 [--create-parent]
559 [--cos-specifier COS_SPECIFIER]
560 [--cos-template COS_TEMPLATE]
561 [--cos-attr [COS_ATTR ...]]
562 [--ldif-file LDIF_FILE]
563 NAME
564 NAME The COS definition name.
567 --type TYPE
570 The COS definition type: "classic", "pointer", or "indirect".
571 --parent PARENT
574 The parent entry that the COS definition should be created
575 under.
576 --create-parent
579 Create the parent entry
580 --cos-specifier COS_SPECIFIER
583 Used in a classic COS definition, this attribute located in the
584 user entry is used to select which COS template to use.
585 --cos-template COS_TEMPLATE
588 The DN of the COS template entry, only used for "classic" and
589 "pointer" COS definitions.
590 --cos-attr [COS_ATTR ...]
593 A list of attributes which defines which attribute the COS gen‐
594 erates values for.
595 --ldif-file LDIF_FILE
598 The LDIF file name. Default is "/tmp/ldifgen.ldif"
599
602 usage: dsctl [instance] ldifgen cos-template [-h] [--parent PARENT]
603 [--create-parent]
604 [--cos-priority COS_PRIOR‐
605 ITY]
606 [--cos-attr-val
607 COS_ATTR_VAL]
608 [--ldif-file LDIF_FILE]
609 NAME
610 NAME The COS template name.
613 --parent PARENT
616 The DN of the entry to store the COS template entry under.
617 --create-parent
620 Create the parent entry
621 --cos-priority COS_PRIORITY
624 Sets the priority of this conflicting/competing COS templates.
625 --cos-attr-val COS_ATTR_VAL
628 defines the attribute and value that the template provides.
629 --ldif-file LDIF_FILE
632 The LDIF file name. Default is "/tmp/ldifgen.ldif"
633
636 usage: dsctl [instance] ldifgen roles [-h] [--type TYPE] [--parent PAR‐
637 ENT]
638 [--create-parent] [--filter FIL‐
639 TER]
640 [--role-dn [ROLE_DN ...]]
641 [--ldif-file LDIF_FILE]
642 NAME
643 NAME The Role name.
646 --type TYPE
649 The Role type: "managed", "filtered", or "nested".
650 --parent PARENT
653 The DN of the entry to store the Role entry under
654 --create-parent
657 Create the parent entry
658 --filter FILTER
661 A search filter for gathering Role members. Required for a "fil‐
662 tered" role.
663 --role-dn [ROLE_DN ...]
666 A DN of a role entry that should be included in this role. Used
667 for "nested" roles only.
668 --ldif-file LDIF_FILE
671 The LDIF file name. Default is "/tmp/ldifgen.ldif"
672
675 usage: dsctl [instance] ldifgen mod-load [-h] [--create-users]
676 [--delete-users]
677 [--num-users NUM_USERS]
678 [--parent PARENT] [--create-
679 parent]
680 [--add-users ADD_USERS]
681 [--del-users DEL_USERS]
682 [--modrdn-users MODRDN_USERS]
683 [--mod-users MOD_USERS]
684 [--mod-attrs [MOD_ATTRS ...]]
685 [--randomize] [--ldif-file
686 LDIF_FILE]
687 --create-users
691 Create the entries that will be modified or deleted. By default
692 the script assumes the user entries already exist.
693 --delete-users
696 Delete all the user entries at the end of the LDIF.
697 --num-users NUM_USERS
700 The number of user entries that will be modified or deleted
701 --parent PARENT
704 The DN of the parent entry where the user entries are located.
705 --create-parent
708 Create the parent entry
709 --add-users ADD_USERS
712 The number of additional entries to add during the load.
713 --del-users DEL_USERS
716 The number of entries to delete during the load.
717 --modrdn-users MODRDN_USERS
720 The number of entries to perform a modrdn operation on.
721 --mod-users MOD_USERS
724 The number of entries to modify.
725 --mod-attrs [MOD_ATTRS ...]
728 List of attributes the script will randomly choose from when
729 modifying an entry. The default is "description".
730 --randomize
733 Randomly perform the specified add, mod, delete, and modrdn
734 operations
735 --ldif-file LDIF_FILE
738 The LDIF file name. Default is "/tmp/ldifgen.ldif"
739
742 usage: dsctl [instance] ldifgen nested [-h] [--num-users NUM_USERS]
743 [--node-limit NODE_LIMIT]
744 [--suffix SUFFIX]
745 [--ldif-file LDIF_FILE]
746 --num-users NUM_USERS
750 The total number of user entries to create in the entire LDIF
751 (does not include the container entries).
752 --node-limit NODE_LIMIT
755 The total number of user entries to create under each node/sub‐
756 tree
757 --suffix SUFFIX
760 The suffix DN for the LDIF
761 --ldif-file LDIF_FILE
764 The LDIF file name. Default location is the server's LDIF direc‐
765 tory using the name 'users.ldif'
766
770 usage: dsctl [instance] dsrc [-h] {create,modify,delete,display} ...
771 Sub-commands
774 dsctl dsrc create
775 Generate the .dsrc file
776 dsctl dsrc modify
778 Modify the .dsrc file
779 dsctl dsrc delete
781 Delete instance configuration from the .dsrc file.
782 dsctl dsrc display
784 Display the contents of the .dsrc file.
785
787 usage: dsctl [instance] dsrc create [-h] [--uri URI] [--basedn BASEDN]
788 [--binddn BINDDN] [--saslmech
789 SASLMECH]
790 [--tls-cacertdir TLS_CACERTDIR]
791 [--tls-cert TLS_CERT] [--tls-key
792 TLS_KEY]
793 [--tls-reqcert TLS_REQCERT]
794 [--starttls]
795 [--pwdfile PWDFILE] [--do-it]
796 --uri URI
800 The URI (LDAP URL) for the Directory Server instance.
801 --basedn BASEDN
804 The default database suffix.
805 --binddn BINDDN
808 The default Bind DN used or authentication.
809 --saslmech SASLMECH
812 The SASL mechanism to use: PLAIN or EXTERNAL.
813 --tls-cacertdir TLS_CACERTDIR
816 The directory containing the Trusted Certificate Authority cer‐
817 tificate.
818 --tls-cert TLS_CERT
821 The absolute file name to the server certificate.
822 --tls-key TLS_KEY
825 The absolute file name to the server certificate key.
826 --tls-reqcert TLS_REQCERT
829 Request certificate strength: 'never', 'allow', 'hard'
830 --starttls
833 Use startTLS for connection to the server.
834 --pwdfile PWDFILE
837 The absolute path to a file containing the Bind DN's password.
838 --do-it
841 Create the file without any confirmation.
842
845 usage: dsctl [instance] dsrc modify [-h] [--uri [URI]] [--basedn
846 [BASEDN]]
847 [--binddn [BINDDN]]
848 [--saslmech [SASLMECH]]
849 [--tls-cacertdir [TLS_CACERTDIR]]
850 [--tls-cert [TLS_CERT]]
851 [--tls-key [TLS_KEY]]
852 [--tls-reqcert [TLS_REQCERT]]
853 [--starttls]
854 [--cancel-starttls] [--pwdfile
855 [PWDFILE]]
856 [--do-it]
857 --uri [URI]
861 The URI (LDAP URL) for the Directory Server instance.
862 --basedn [BASEDN]
865 The default database suffix.
866 --binddn [BINDDN]
869 The default Bind DN used or authentication.
870 --saslmech [SASLMECH]
873 The SASL mechanism to use: PLAIN or EXTERNAL.
874 --tls-cacertdir [TLS_CACERTDIR]
877 The directory containing the Trusted Certificate Authority cer‐
878 tificate.
879 --tls-cert [TLS_CERT]
882 The absolute file name to the server certificate.
883 --tls-key [TLS_KEY]
886 The absolute file name to the server certificate key.
887 --tls-reqcert [TLS_REQCERT]
890 Request certificate strength: 'never', 'allow', 'hard'
891 --starttls
894 Use startTLS for connection to the server.
895 --cancel-starttls
898 Do not use startTLS for connection to the server.
899 --pwdfile [PWDFILE]
902 The absolute path to a file containing the Bind DN's password.
903 --do-it
906 Update the file without any confirmation.
907
910 usage: dsctl [instance] dsrc delete [-h] [--do-it]
911 --do-it
915 Delete this instance's configuration from the .dsrc file.
916
919 usage: dsctl [instance] dsrc display [-h]
920
926 usage: dsctl [instance] cockpit [-h]
927 {enable,open-firewall,disable,close-
928 firewall}
929 ...
930 Sub-commands
933 dsctl cockpit enable
934 Enable the Cockpit socket
935 dsctl cockpit open-firewall
937 Open the firewall for the "cockpit" service
938 dsctl cockpit disable
940 Disable the Cockpit socket
941 dsctl cockpit close-firewall
943 Remove the "cockpit" service from the firewall settings
944
946 usage: dsctl [instance] cockpit enable [-h]
947
952 usage: dsctl [instance] cockpit open-firewall [-h] [--zone ZONE]
953 --zone ZONE
957 The firewall zone
958
961 usage: dsctl [instance] cockpit disable [-h]
962
967 usage: dsctl [instance] cockpit close-firewall [-h]
968 -v, --verbose
974 Display verbose operation tracing during command execution
975 -j, --json
978 Return result in JSON object
979 -l, --list
982 List available Directory Server instances
983
986 lib389 was written by Red Hat Inc., and William Brown
987 <389-devel@lists.fedoraproject.org>.
988
990 The latest version of lib389 may be downloaded from
991 ⟨http://www.port389.org/docs/389ds/FAQ/upstream-test-framework.html⟩
992 Manual dsctl(8)