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} ...
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
100 usage: dsctl [instance] restart [-h]
101
106 usage: dsctl [instance] start [-h]
107
112 usage: dsctl [instance] stop [-h]
113
118 usage: dsctl [instance] status [-h]
119
124 usage: dsctl [instance] remove [-h] [--do-it]
125 --do-it
129 By default we do a dry run. This actually initiates the removal
130 of the instance.
131
134 usage: dsctl [instance] db2index [-h] backend
135 backend
138 The backend to reindex. IE userRoot
139
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
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 --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
183 usage: dsctl [instance] bak2db [-h] archive
184 archive
187 The archive to restore. This will erase all current server data‐
188 bases.
189
193 usage: dsctl [instance] ldif2db [-h] [--encrypted] backend ldif
194 backend
197 The backend to restore from an LDIF. IE userRoot
198 ldif The path to the ldif to import
201 --encrypted
204 Import encrypted attributes
205
208 usage: dsctl [instance] backups [-h] [--delete DELETE]
209 --delete DELETE
213 Delete backup directory
214
217 usage: dsctl [instance] ldifs [-h] [--delete DELETE]
218 --delete DELETE
222 Delete LDIF file
223
226 usage: dsctl [instance] tls [-h]
227 {list-ca,list-client-ca,show-server-
228 cert,show-cert,generate-server-cert-csr,import-client-ca,import-
229 ca,import-server-cert,import-server-key-cert,remove-cert}
230 ...
231 Sub-commands
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
251 import 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.
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
276 usage: dsctl [instance] tls list-ca [-h]
277
282 usage: dsctl [instance] tls list-client-ca [-h]
283
288 usage: dsctl [instance] tls show-server-cert [-h]
289
294 usage: dsctl [instance] tls show-cert [-h] nickname
295 nickname
298 The nickname (friendly name) of the certificate to display
299
303 usage: dsctl [instance] tls generate-server-cert-csr [-h] [--subject
304 SUBJECT]
305 [alt_names
306 [alt_names ...]]
307 alt_names
310 Certificate requests subject alternative names. These are
311 auto-detected if not provided
312 --subject SUBJECT, -s SUBJECT
315 Certificate Subject field to use
316
319 usage: dsctl [instance] tls import-client-ca [-h] cert_path nickname
320 cert_path
323 The path to the x509 cert to import as a client trust root
324 nickname
327 The name of the certificate once imported
328
332 usage: dsctl [instance] tls import-ca [-h] cert_path nickname
333 cert_path
336 The path to the x509 cert to import as a server CA
337 nickname
340 The name of the certificate once imported
341
345 usage: dsctl [instance] tls import-server-cert [-h] cert_path
346 cert_path
349 The path to the x509 cert to import as Server-Cert
350
354 usage: dsctl [instance] tls import-server-key-cert [-h] cert_path
355 key_path
356 cert_path
359 The path to the x509 cert to import as Server-Cert
360 key_path
363 The path to the x509 key to import associated to Server-Cert
364
368 usage: dsctl [instance] tls remove-cert [-h] nickname
369 nickname
372 The name of the certificate to delete
373
378 usage: dsctl [instance] healthcheck [-h]
379
384 usage: dsctl [instance] get-nsstate [-h] [--suffix SUFFIX] [--flip
385 FLIP]
386 --suffix SUFFIX
390 The DN of the replication suffix to read the state from
391 --flip FLIP
394 Flip between Little/Big Endian, this might be required for cer‐
395 tain architectures
396
399 usage: dsctl [instance] ldifgen [-h]
400 {users,groups,cos-def,cos-tem‐
401 plate,roles,mod-load,nested}
402 ...
403 Sub-commands
406 dsctl ldifgen users
407 Generate a LDIF containing user entries
408 dsctl ldifgen groups
410 Generate a LDIF containing groups and members
411 dsctl ldifgen cos-def
413 Generate a LDIF containing a COS definition (classic, pointer,
414 or indirect)
415 dsctl ldifgen cos-template
417 Generate a LDIF containing a COS template
418 dsctl ldifgen roles
420 Generate a LDIF containing a role entry (managed, filtered, or
421 indirect)
422 dsctl ldifgen mod-load
424 Generate a LDIF containing modify operations. This is intended
425 to be consumed by ldapmodify.
426 dsctl ldifgen nested
428 Generate a heavily nested database LDIF in a cascading/fractal
429 tree design
430
432 usage: dsctl [instance] ldifgen users [-h] [--number NUMBER] [--suffix
433 SUFFIX]
434 [--parent PARENT] [--generic]
435 [--start-idx START_IDX] [--rdn-
436 cn]
437 [--localize] [--ldif-file
438 LDIF_FILE]
439 --number NUMBER
443 The number of users to create.
444 --suffix SUFFIX
447 The database suffix where the entries will be created.
448 --parent PARENT
451 The parent entry that the user entries should be created under.
452 If not specified, the entries are stored under random Organiza‐
453 tional Units.
454 --generic
457 Create generic entries in the format of "uid=user####". These
458 entries are also compatible with ldclt.
459 --start-idx START_IDX
462 For generic LDIF's you can choose the starting index for the
463 user entries. The default is "0".
464 --rdn-cn
467 Use the attribute "cn" as the RDN attribute in the DN instead of
468 "uid"
469 --localize
472 Localize the LDIF data
473 --ldif-file LDIF_FILE
476 The LDIF file name. Default location is the server's LDIF direc‐
477 tory using the name 'users.ldif'
478
481 usage: dsctl [instance] ldifgen groups [-h] [--number NUMBER]
482 [--suffix SUFFIX] [--parent PAR‐
483 ENT]
484 [--num-members NUM_MEMBERS]
485 [--create-members]
486 [--member-parent MEMBER_PARENT]
487 [--member-attr MEMBER_ATTR]
488 [--ldif-file LDIF_FILE]
489 NAME
490 NAME The group name.
493 --number NUMBER
496 The number of groups to create.
497 --suffix SUFFIX
500 The database suffix where the groups will be created.
501 --parent PARENT
504 The parent entry that the group entries should be created under.
505 If not specified the groups are stored under the suffix.
506 --num-members NUM_MEMBERS
509 The number of members in the group. Default is 10000
510 --create-members
513 Create the member user entries.
514 --member-parent MEMBER_PARENT
517 The entry DN that the members should be created under. The
518 default is the suffix entry.
519 --member-attr MEMBER_ATTR
522 The membership attribute to use in the group. Default is
523 "uniquemember".
524 --ldif-file LDIF_FILE
527 The LDIF file name. Default is "/tmp/ldifgen.ldif"
528
531 usage: dsctl [instance] ldifgen cos-def [-h] [--type TYPE] [--parent
532 PARENT]
533 [--create-parent]
534 [--cos-specifier COS_SPECIFIER]
535 [--cos-template COS_TEMPLATE]
536 [--cos-attr [COS_ATTR [COS_ATTR
537 ...]]]
538 [--ldif-file LDIF_FILE]
539 NAME
540 NAME The COS definition name.
543 --type TYPE
546 The COS definition type: "classic", "pointer", or "indirect".
547 --parent PARENT
550 The parent entry that the COS definition should be created
551 under.
552 --create-parent
555 Create the parent entry
556 --cos-specifier COS_SPECIFIER
559 Used in a classic COS definition, this attribute located in the
560 user entry is used to select which COS template to use.
561 --cos-template COS_TEMPLATE
564 The DN of the COS template entry, only used for "classic" and
565 "pointer" COS definitions.
566 --cos-attr [COS_ATTR [COS_ATTR ...]]
569 A list of attributes which defines which attribute the COS gen‐
570 erates values for.
571 --ldif-file LDIF_FILE
574 The LDIF file name. Default is "/tmp/ldifgen.ldif"
575
578 usage: dsctl [instance] ldifgen cos-template [-h] [--parent PARENT]
579 [--create-parent]
580 [--cos-priority COS_PRIOR‐
581 ITY]
582 [--cos-attr-val
583 COS_ATTR_VAL]
584 [--ldif-file LDIF_FILE]
585 NAME
586 NAME The COS template name.
589 --parent PARENT
592 The DN of the entry to store the COS template entry under.
593 --create-parent
596 Create the parent entry
597 --cos-priority COS_PRIORITY
600 Sets the priority of this conflicting/competing COS templates.
601 --cos-attr-val COS_ATTR_VAL
604 defines the attribute and value that the template provides.
605 --ldif-file LDIF_FILE
608 The LDIF file name. Default is "/tmp/ldifgen.ldif"
609
612 usage: dsctl [instance] ldifgen roles [-h] [--type TYPE] [--parent PAR‐
613 ENT]
614 [--create-parent] [--filter FIL‐
615 TER]
616 [--role-dn [ROLE_DN [ROLE_DN
617 ...]]]
618 [--ldif-file LDIF_FILE]
619 NAME
620 NAME The Role name.
623 --type TYPE
626 The Role type: "managed", "filtered", or "nested".
627 --parent PARENT
630 The DN of the entry to store the Role entry under
631 --create-parent
634 Create the parent entry
635 --filter FILTER
638 A search filter for gathering Role members. Required for a "fil‐
639 tered" role.
640 --role-dn [ROLE_DN [ROLE_DN ...]]
643 A DN of a role entry that should be included in this role. Used
644 for "nested" roles only.
645 --ldif-file LDIF_FILE
648 The LDIF file name. Default is "/tmp/ldifgen.ldif"
649
652 usage: dsctl [instance] ldifgen mod-load [-h] [--create-users]
653 [--delete-users]
654 [--num-users NUM_USERS]
655 [--parent PARENT] [--create-
656 parent]
657 [--add-users ADD_USERS]
658 [--del-users DEL_USERS]
659 [--modrdn-users MODRDN_USERS]
660 [--mod-users MOD_USERS]
661 [--mod-attrs [MOD_ATTRS
662 [MOD_ATTRS ...]]]
663 [--randomize] [--ldif-file
664 LDIF_FILE]
665 --create-users
669 Create the entries that will be modified or deleted. By default
670 the script assumes the user entries already exist.
671 --delete-users
674 Delete all the user entries at the end of the LDIF.
675 --num-users NUM_USERS
678 The number of user entries that will be modified or deleted
679 --parent PARENT
682 The DN of the parent entry where the user entries are located.
683 --create-parent
686 Create the parent entry
687 --add-users ADD_USERS
690 The number of additional entries to add during the load.
691 --del-users DEL_USERS
694 The number of entries to delete during the load.
695 --modrdn-users MODRDN_USERS
698 The number of entries to perform a modrdn operation on.
699 --mod-users MOD_USERS
702 The number of entries to modify.
703 --mod-attrs [MOD_ATTRS [MOD_ATTRS ...]]
706 List of attributes the script will randomly choose from when
707 modifying an entry. The default is "description".
708 --randomize
711 Randomly perform the specified add, mod, delete, and modrdn
712 operations
713 --ldif-file LDIF_FILE
716 The LDIF file name. Default is "/tmp/ldifgen.ldif"
717
720 usage: dsctl [instance] ldifgen nested [-h] [--num-users NUM_USERS]
721 [--node-limit NODE_LIMIT]
722 [--suffix SUFFIX]
723 [--ldif-file LDIF_FILE]
724 --num-users NUM_USERS
728 The total number of user entries to create in the entire LDIF
729 (does not include the container entries).
730 --node-limit NODE_LIMIT
733 The total number of user entries to create under each node/sub‐
734 tree
735 --suffix SUFFIX
738 The suffix DN for the LDIF
739 --ldif-file LDIF_FILE
742 The LDIF file name. Default location is the server's LDIF direc‐
743 tory using the name 'users.ldif'
744 -v, --verbose
748 Display verbose operation tracing during command execution
749 -j, --json
752 Return result in JSON object
753 -l, --list
756 List available Directory Server instances
757
760 lib389 was written by Red Hat Inc. <389-devel@lists.fedoraproject.org>.
761
763 The latest version of lib389 may be downloaded from
764 ⟨http://www.port389.org/docs/389ds/FAQ/upstream-test-framework.html⟩
765 Manual dsctl(8)