Administration of Directory Server has always been a complex topic. We have a variety of helper perl scripts that are installed with the instance. These administer specific parts of the server, but the server greater cannot be managed with them alone. We often have pushed people to the Java Console, or application of ldifs to the server.
These are at opposite extremes, the Java Console having it’s own issues, but easy to use, where as the application of ldifs is at the opposite end of being highly complex.
As a result, we need a new way to administer Directory Server. It should contain extensive help, be a complete one stop, and command line focused.
A deployment and instance of Directory Server should be able to be setup, administered, and eventually decommisioned without ever applying an ldif. This should accomodate advanced usage, and basic usage.
There are three tools we provide
Lib389, our testing framework, already has all the parts needed to make an administrative toolkit. dsconf and dsadm are just wrappers on this. Consider
# Not a complete script, misses the opening of a connection from lib389.backend import Backends bes = Backends() be_uroot = bes.get('userRoot') be_uroot.set('nsslapd-cachememsize', 10485760)
This is how we can set the database cachesize, using pure python. To wrap this to a command line is a very simple extension.
<command> <resource> <action> [<options>]
dsconf ldaps://localhost backend create dc=example,dc=com userRoot
For extra arguments these are provided with the same command flags as the openldap cli tools. IE
dsconf -D 'cn=Directory Manager' ldaps://localhost backend list
Many arguments can be preconfigured in a ~/.dsrc file, for example:
[localhost] uri = ldaps://localhost basedn = dc=example,dc=com binddn = cn=Directory Manager
This allows you to use “aliases” of the configuration, rather than always typing URIs.
dsconf localhost backend list
If you are not using a ~/.dsrc file, then you can set the localinstance name as well:
dsconf slapd-localhost backend create dc=example,dc=com userRoot
A major component of this, is that dsadm will not use or rely on any of the existing perl scripts. As a result we will include and use the new SetupDs from lib389.
The new installer itself uses a simplified inf format compared to the current answer file.
A complete example can be generated with:
dscreate create-template > /tmp/instance.inf
Or, to have it write the file for you with the correct permissions you can do:
dscreate create-template /tmp/instance.inf
The example being generated over commited, means we keep the internal code helptext up to date, and it will throw exceptions if it’s not there. We are forced to keep it correct and up to date as a result.
The instance can then be installed with:
dscreate install /tmp/instance.inf
dscreate also has an interactive installer. Just run dscreate install to enter the interactive mode, but you can not set all the options in interactive mode - just the core settings needed to create the instance.
The command line interface can be unit tested, and the current components are already tested in the pytest suite. This works because our output to the user is via the python logging module, and I have a loghandler that intercepts the output, and can assert it contains expected outputs. This brings gives us guarantees about our command lines tools and their correctness that we have never had before.
You can run these tests with the following:
sudo py.test-3 lib389/tests/cli/ lib389/tests/instance/
As we add more commands and functions, we must add these to be tested also.
Run the install script in an interactive mode that asks for a limited number of installation options
I0> dscreate interactive
Or, use the INF file installation method…
Displaying an example inf
I0> dscreate create-template ...snip...
Or have the script write the INF file to disk
I0> dscreate create-template /tmp/instance.inf
Dryrun installing an instance (will verify your environment)
I0> dscreate fromfile -n /tmp/instance.inf
Actually install an instance
I0> dscreate fromfile /tmp/instance.inf READY: Preparing installation for localhost READY: Beginning installation for localhost FINISH: Completed installation for localhost FINISH: Command succeeded
Doing a verbose install. All commands support a verbose flag that may help you understand issues or processes.
I0> dscreate -v fromfile /tmp/instance.inf DEBUG: The 389 Directory Server Creation Tool DEBUG: Inspired by works of: ITS, The University of Adelaide DEBUG: Called with: Namespace(ack=False, containerised=False, dryrun=False, file='/tmp/instance.inf', func=<function instance_create at 0x7f2f2668fea0>, verbose=True) INFO: Running setup with verbose INFO: Using inf from /tmp/instance.inf INFO: Configuration ['general', 'slapd'] DEBUG: general:strict_host_checking not in inf, or incorrect type, using default ... DEBUG: Pid of 30104 for localhost and running DEBUG: Pid of 30104 is not running for localhost WARNING: WARNING: Starting instance with ASAN options. This is probably not what you want. Please contact support. INFO: INFO: ASAN options will be copied from your environment INFO: FINISH: Completed installation for localhost INFO: FINISH: Command succeeded
Configure our .dsrc to make our instance easier to administer:
[localhost] uri = ldaps://localhost basedn = dc=example,dc=com binddn = cn=Directory Manager tls_cacertdir = /etc/dirsrv/slapd-localhost/
Now that we have an instance, show the backends. Remember, backends store suffixes of data like users and groups:
I0> dsconf localhost backend list Enter password for cn=Directory Manager on ldaps://localhost : No objects to display Command successful.
Create a backend. First checking help for what we might need.
I0> dsconf localhost backend create --help usage: dsconf instance backend create [-h] [--nsslapd-suffix [NSSLAPD_SUFFIX]] [--cn [CN]] optional arguments: -h, --help show this help message and exit --nsslapd-suffix [NSSLAPD_SUFFIX] Value of nsslapd-suffix --cn [CN] Value of cn I0> dsconf localhost backend create Enter password for cn=Directory Manager on ldaps://localhost : Enter value for nsslapd-suffix : dc=example,dc=com Enter value for cn : userRoot Sucessfully created userRoot Command successful.
List the backends again to see it’s there.
I0> dsconf localhost backend list Enter password for cn=Directory Manager on ldaps://localhost : userRoot Command successful.
We can populate our new backend with sample data. Because this is part of the database, it’s in dsidm. This populates the suffix from your .dsrc “basedn” parameter.
I0> dsidm localhost initialise Enter password for cn=Directory Manager on ldaps://localhost : Command successful.
You can see there are demo users and groups:
I0> dsidm localhost user list Enter password for cn=Directory Manager on ldaps://localhost : demo_user Command successful. I0> dsidm localhost group list Enter password for cn=Directory Manager on ldaps://localhost : demo_group Command successful.
We can even add our demo_user to the demo_group:
I0> dsidm localhost group add_member demo_group uid=demo_user,ou=people,dc=example,dc=com Enter password for cn=Directory Manager on ldaps://localhost : Command successful.
We can create users
I0> dsidm localhost user create Enter password for cn=Directory Manager on ldaps://localhost : Enter value for uid : william Enter value for cn : William Enter value for displayName : William Brown Enter value for uidNumber : 1000 Enter value for gidNumber : 1000 Enter value for homeDirectory : /home/william Sucessfully created william Command successful.
Lock their accounts
I0> dsidm localhost user lock Enter password for cn=Directory Manager on ldaps://localhost : Enter uid to check : william locked william Command successful.
Check that they can’t login
I0> dsidm localhost user status william Enter password for cn=Directory Manager on ldaps://localhost : uid: william locked: True Command successful.
Unlock their account
I0> dsidm localhost user unlock william Enter password for cn=Directory Manager on ldaps://localhost : unlocked william Command successful.
There is much more that we can do today too, but this is just a taste. Please contact firstname.lastname@example.org for more details or questions.