1dsctl(8) System Manager's Manual dsctl(8)
2
3
4
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
17
18 Sub-commands
19 dsctl restart
20 Restart an instance of Directory Server, if it is running: else
21 start it.
22
23 dsctl start
24 Start an instance of Directory Server, if it is not currently
25 running
26
27 dsctl stop
28 Stop an instance of Directory Server, if it is currently running
29
30 dsctl status
31 Check running status of an instance of Directory Server
32
33 dsctl remove
34 Destroy an instance of Directory Server, and remove all data.
35
36 dsctl db2index
37 Initialise a reindex of the server database. The server must be
38 stopped for this to proceed.
39
40 dsctl db2bak
41 Initialise a BDB backup of the database. The server must be
42 stopped for this to proceed.
43
44 dsctl db2ldif
45 Initialise an LDIF dump of the database. The server must be
46 stopped for this to proceed.
47
48 dsctl dbverify
49 Perform a db verification. You should only do this at direction
50 of support
51
52 dsctl bak2db
53 Restore a BDB backup of the database. The server must be stopped
54 for this to proceed.
55
56 dsctl ldif2db
57 Restore an LDIF dump of the database. The server must be stopped
58 for this to proceed.
59
60 dsctl backups
61 List backup's found in the server's default backup directory
62
63 dsctl ldifs
64 List all the LDIF files located in the server's LDIF directory
65
66 dsctl tls
67 Manage TLS certificates
68
69 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
75 dsctl get-nsstate
76 Get the replication nsState in a human readable format
77
78 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
95
96 dsctl ldifgen
97 LDIF generator to make sample LDIF files for testing
98
99 dsctl dsrc
100 Manage the .dsrc file
101
102 dsctl cockpit
103 Enable the Cockpit interface/UI
104
106 usage: dsctl [instance] restart [-h]
107
108
109
110
112 usage: dsctl [instance] start [-h]
113
114
115
116
118 usage: dsctl [instance] stop [-h]
119
120
121
122
124 usage: dsctl [instance] status [-h]
125
126
127
128
130 usage: dsctl [instance] remove [-h] [--do-it]
131
132
133
134 --do-it
135 By default we do a dry run. This actually initiates the removal
136 of the instance.
137
138
140 usage: dsctl [instance] db2index [-h] backend
141
142
143 backend
144 The backend to reindex. IE userRoot
145
146
147
149 usage: dsctl [instance] db2bak [-h] [archive]
150
151
152 archive
153 The destination for the archive. This will be created during the
154 db2bak process.
155
156
157
159 usage: dsctl [instance] db2ldif [-h] [--replication] [--encrypted]
160 backend [ldif]
161
162
163 backend
164 The backend to output as an LDIF. IE userRoot
165
166
167 ldif The path to the ldif output location.
168
169
170 --replication
171 Export replication information, suitable for importing on a new
172 consumer or backups.
173
174
175 --encrypted
176 Export encrypted attributes
177
178
180 usage: dsctl [instance] dbverify [-h] backend
181
182
183 backend
184 The backend to verify. IE userRoot
185
186
187
189 usage: dsctl [instance] bak2db [-h] archive
190
191
192 archive
193 The archive to restore. This will erase all current server data‐
194 bases.
195
196
197
199 usage: dsctl [instance] ldif2db [-h] [--encrypted] backend ldif
200
201
202 backend
203 The backend to restore from an LDIF. IE userRoot
204
205
206 ldif The path to the ldif to import
207
208
209 --encrypted
210 Import encrypted attributes
211
212
214 usage: dsctl [instance] backups [-h] [--delete DELETE]
215
216
217
218 --delete DELETE
219 Delete backup directory
220
221
223 usage: dsctl [instance] ldifs [-h] [--delete DELETE]
224
225
226
227 --delete DELETE
228 Delete LDIF file
229
230
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
238
239 Sub-commands
240 dsctl tls list-ca
241 list server certificate authorities including intermediates
242
243 dsctl tls list-client-ca
244 list client certificate authorities including intermediates
245
246 dsctl tls show-server-cert
247 Show the active server certificate that clients will see and
248 verify
249
250 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
254 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
259 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
263 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
268 dsctl tls import-server-cert
269 Import a new Server-Cert after the csr has been signed from a
270 CA.
271
272 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
277 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
284
285
286
288 usage: dsctl [instance] tls list-client-ca [-h]
289
290
291
292
294 usage: dsctl [instance] tls show-server-cert [-h]
295
296
297
298
300 usage: dsctl [instance] tls show-cert [-h] nickname
301
302
303 nickname
304 The nickname (friendly name) of the certificate to display
305
306
307
309 usage: dsctl [instance] tls generate-server-cert-csr [-h] [--subject
310 SUBJECT]
311 [alt_names ...]
312
313
314 alt_names
315 Certificate requests subject alternative names. These are
316 auto-detected if not provided
317
318
319 --subject SUBJECT, -s SUBJECT
320 Certificate Subject field to use
321
322
324 usage: dsctl [instance] tls import-client-ca [-h] cert_path nickname
325
326
327 cert_path
328 The path to the x509 cert to import as a client trust root
329
330
331 nickname
332 The name of the certificate once imported
333
334
335
337 usage: dsctl [instance] tls import-ca [-h] cert_path nickname
338
339
340 cert_path
341 The path to the x509 cert to import as a server CA
342
343
344 nickname
345 The name of the certificate once imported
346
347
348
350 usage: dsctl [instance] tls import-server-cert [-h] cert_path
351
352
353 cert_path
354 The path to the x509 cert to import as Server-Cert
355
356
357
359 usage: dsctl [instance] tls import-server-key-cert [-h] cert_path
360 key_path
361
362
363 cert_path
364 The path to the x509 cert to import as Server-Cert
365
366
367 key_path
368 The path to the x509 key to import associated to Server-Cert
369
370
371
373 usage: dsctl [instance] tls remove-cert [-h] nickname
374
375
376 nickname
377 The name of the certificate to delete
378
379
380
381
383 usage: dsctl [instance] healthcheck [-h] [--list-checks] [--list-
384 errors]
385 [--dry-run] [--check CHECK [CHECK
386 ...]]
387
388
389
390 --list-checks
391 List of known checks
392
393
394 --list-errors
395 List of known error codes
396
397
398 --dry-run
399 Do not execute the actual check, only list what would be done
400
401
402 --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
407
409 usage: dsctl [instance] get-nsstate [-h] [--suffix SUFFIX] [--flip
410 FLIP]
411
412
413
414 --suffix SUFFIX
415 The DN of the replication suffix to read the state from
416
417
418 --flip FLIP
419 Flip between Little/Big Endian, this might be required for cer‐
420 tain architectures
421
422
424 usage: dsctl [instance] ldifgen [-h]
425 {users,groups,cos-def,cos-tem‐
426 plate,roles,mod-load,nested}
427 ...
428
429
430 Sub-commands
431 dsctl ldifgen users
432 Generate a LDIF containing user entries
433
434 dsctl ldifgen groups
435 Generate a LDIF containing groups and members
436
437 dsctl ldifgen cos-def
438 Generate a LDIF containing a COS definition (classic, pointer,
439 or indirect)
440
441 dsctl ldifgen cos-template
442 Generate a LDIF containing a COS template
443
444 dsctl ldifgen roles
445 Generate a LDIF containing a role entry (managed, filtered, or
446 indirect)
447
448 dsctl ldifgen mod-load
449 Generate a LDIF containing modify operations. This is intended
450 to be consumed by ldapmodify.
451
452 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
465
466
467 --number NUMBER
468 The number of users to create.
469
470
471 --suffix SUFFIX
472 The database suffix where the entries will be created.
473
474
475 --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
480
481 --generic
482 Create generic entries in the format of "uid=user####". These
483 entries are also compatible with ldclt.
484
485
486 --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
490
491 --rdn-cn
492 Use the attribute "cn" as the RDN attribute in the DN instead of
493 "uid"
494
495
496 --localize
497 Localize the LDIF data
498
499
500 --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
504
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
516
517 NAME The group name.
518
519
520 --number NUMBER
521 The number of groups to create.
522
523
524 --suffix SUFFIX
525 The database suffix where the groups will be created.
526
527
528 --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
532
533 --num-members NUM_MEMBERS
534 The number of members in the group. Default is 10000
535
536
537 --create-members
538 Create the member user entries.
539
540
541 --member-parent MEMBER_PARENT
542 The entry DN that the members should be created under. The
543 default is the suffix entry.
544
545
546 --member-attr MEMBER_ATTR
547 The membership attribute to use in the group. Default is
548 "uniquemember".
549
550
551 --ldif-file LDIF_FILE
552 The LDIF file name. Default is "/tmp/ldifgen.ldif"
553
554
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
565
566 NAME The COS definition name.
567
568
569 --type TYPE
570 The COS definition type: "classic", "pointer", or "indirect".
571
572
573 --parent PARENT
574 The parent entry that the COS definition should be created
575 under.
576
577
578 --create-parent
579 Create the parent entry
580
581
582 --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
586
587 --cos-template COS_TEMPLATE
588 The DN of the COS template entry, only used for "classic" and
589 "pointer" COS definitions.
590
591
592 --cos-attr [COS_ATTR ...]
593 A list of attributes which defines which attribute the COS gen‐
594 erates values for.
595
596
597 --ldif-file LDIF_FILE
598 The LDIF file name. Default is "/tmp/ldifgen.ldif"
599
600
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
611
612 NAME The COS template name.
613
614
615 --parent PARENT
616 The DN of the entry to store the COS template entry under.
617
618
619 --create-parent
620 Create the parent entry
621
622
623 --cos-priority COS_PRIORITY
624 Sets the priority of this conflicting/competing COS templates.
625
626
627 --cos-attr-val COS_ATTR_VAL
628 defines the attribute and value that the template provides.
629
630
631 --ldif-file LDIF_FILE
632 The LDIF file name. Default is "/tmp/ldifgen.ldif"
633
634
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
644
645 NAME The Role name.
646
647
648 --type TYPE
649 The Role type: "managed", "filtered", or "nested".
650
651
652 --parent PARENT
653 The DN of the entry to store the Role entry under
654
655
656 --create-parent
657 Create the parent entry
658
659
660 --filter FILTER
661 A search filter for gathering Role members. Required for a "fil‐
662 tered" role.
663
664
665 --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
669
670 --ldif-file LDIF_FILE
671 The LDIF file name. Default is "/tmp/ldifgen.ldif"
672
673
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
688
689
690 --create-users
691 Create the entries that will be modified or deleted. By default
692 the script assumes the user entries already exist.
693
694
695 --delete-users
696 Delete all the user entries at the end of the LDIF.
697
698
699 --num-users NUM_USERS
700 The number of user entries that will be modified or deleted
701
702
703 --parent PARENT
704 The DN of the parent entry where the user entries are located.
705
706
707 --create-parent
708 Create the parent entry
709
710
711 --add-users ADD_USERS
712 The number of additional entries to add during the load.
713
714
715 --del-users DEL_USERS
716 The number of entries to delete during the load.
717
718
719 --modrdn-users MODRDN_USERS
720 The number of entries to perform a modrdn operation on.
721
722
723 --mod-users MOD_USERS
724 The number of entries to modify.
725
726
727 --mod-attrs [MOD_ATTRS ...]
728 List of attributes the script will randomly choose from when
729 modifying an entry. The default is "description".
730
731
732 --randomize
733 Randomly perform the specified add, mod, delete, and modrdn
734 operations
735
736
737 --ldif-file LDIF_FILE
738 The LDIF file name. Default is "/tmp/ldifgen.ldif"
739
740
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
747
748
749 --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
753
754 --node-limit NODE_LIMIT
755 The total number of user entries to create under each node/sub‐
756 tree
757
758
759 --suffix SUFFIX
760 The suffix DN for the LDIF
761
762
763 --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
767
768
770 usage: dsctl [instance] dsrc [-h] {create,modify,delete,display} ...
771
772
773 Sub-commands
774 dsctl dsrc create
775 Generate the .dsrc file
776
777 dsctl dsrc modify
778 Modify the .dsrc file
779
780 dsctl dsrc delete
781 Delete instance configuration from the .dsrc file.
782
783 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
797
798
799 --uri URI
800 The URI (LDAP URL) for the Directory Server instance.
801
802
803 --basedn BASEDN
804 The default database suffix.
805
806
807 --binddn BINDDN
808 The default Bind DN used or authentication.
809
810
811 --saslmech SASLMECH
812 The SASL mechanism to use: PLAIN or EXTERNAL.
813
814
815 --tls-cacertdir TLS_CACERTDIR
816 The directory containing the Trusted Certificate Authority cer‐
817 tificate.
818
819
820 --tls-cert TLS_CERT
821 The absolute file name to the server certificate.
822
823
824 --tls-key TLS_KEY
825 The absolute file name to the server certificate key.
826
827
828 --tls-reqcert TLS_REQCERT
829 Request certificate strength: 'never', 'allow', 'hard'
830
831
832 --starttls
833 Use startTLS for connection to the server.
834
835
836 --pwdfile PWDFILE
837 The absolute path to a file containing the Bind DN's password.
838
839
840 --do-it
841 Create the file without any confirmation.
842
843
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
858
859
860 --uri [URI]
861 The URI (LDAP URL) for the Directory Server instance.
862
863
864 --basedn [BASEDN]
865 The default database suffix.
866
867
868 --binddn [BINDDN]
869 The default Bind DN used or authentication.
870
871
872 --saslmech [SASLMECH]
873 The SASL mechanism to use: PLAIN or EXTERNAL.
874
875
876 --tls-cacertdir [TLS_CACERTDIR]
877 The directory containing the Trusted Certificate Authority cer‐
878 tificate.
879
880
881 --tls-cert [TLS_CERT]
882 The absolute file name to the server certificate.
883
884
885 --tls-key [TLS_KEY]
886 The absolute file name to the server certificate key.
887
888
889 --tls-reqcert [TLS_REQCERT]
890 Request certificate strength: 'never', 'allow', 'hard'
891
892
893 --starttls
894 Use startTLS for connection to the server.
895
896
897 --cancel-starttls
898 Do not use startTLS for connection to the server.
899
900
901 --pwdfile [PWDFILE]
902 The absolute path to a file containing the Bind DN's password.
903
904
905 --do-it
906 Update the file without any confirmation.
907
908
910 usage: dsctl [instance] dsrc delete [-h] [--do-it]
911
912
913
914 --do-it
915 Delete this instance's configuration from the .dsrc file.
916
917
919 usage: dsctl [instance] dsrc display [-h]
920
921
922
923
924
926 usage: dsctl [instance] cockpit [-h]
927 {enable,open-firewall,disable,close-
928 firewall}
929 ...
930
931
932 Sub-commands
933 dsctl cockpit enable
934 Enable the Cockpit socket
935
936 dsctl cockpit open-firewall
937 Open the firewall for the "cockpit" service
938
939 dsctl cockpit disable
940 Disable the Cockpit socket
941
942 dsctl cockpit close-firewall
943 Remove the "cockpit" service from the firewall settings
944
946 usage: dsctl [instance] cockpit enable [-h]
947
948
949
950
952 usage: dsctl [instance] cockpit open-firewall [-h] [--zone ZONE]
953
954
955
956 --zone ZONE
957 The firewall zone
958
959
961 usage: dsctl [instance] cockpit disable [-h]
962
963
964
965
967 usage: dsctl [instance] cockpit close-firewall [-h]
968
969
970
971
972
973 -v, --verbose
974 Display verbose operation tracing during command execution
975
976
977 -j, --json
978 Return result in JSON object
979
980
981 -l, --list
982 List available Directory Server instances
983
984
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
993
994
995 Manual dsctl(8)