nlpconfig: A CLI utility to work with LDAP Proxy configuration

0 Likes
over 4 years ago

NetIQ LDAP Proxy uses an XML configuration file nlpconf.xml. Sometimes it can get difficult editing the XML file repeatedly to try out policy combinations, complex condition flows, etc. This utility tries to make it slightly simpler by providing a shell friendly command line interface to view the configuration in a human-readable format on the console and to edit any possible node in the configuration with switches.

SYNTAX



nlpconfig [OPERATION] [NODE] [OPTIONS]

OPERATION  can be:

    • --bfs  Build from the scratch, used to create a new configuration file.

 

    • --add  Add nodes/add options to nodes

 

    • --edit Edit nodes/edit options in nodes

 

    • --list Print the contents of the node on the console.

 

    • --help Display help message.



NODE can be

    • --listeners

 

    • --backends

 

    • --load-balancers

 

    • --policy

 

    • --proxy-paths

 

    • --stat-log

 

    • --audit-config

 

    • --xdas



OPTIONS will be many and varied depending on the OPERATION and NODE set. The NODE names should be self-explanatory. The add and edit operations, when combined with a specific node will have a specific set of options.

Example Usage



Creating a configuration from scratch, with a backend server in it. The only node you can add without a reference is a backend server. So --bfs can be used only with adding a backend.

nlpconfig --bfs --backends --id=backend1 --address=192.168.56.103 \
--port=389 --type=ipv4 --protocol=ldap


Adding another backend using --add

nlpconfig --add --backends --id=backend2 --address=192.168.56.104 \
--port=389 --type=ipv4 --protocol=ldap


Adding a load-balancer to hold the defined backends.

nlpconfig --add --loadbalancers --id=loadbalancer1 --type=connection \
--backend-servers=backend1,backend2


Adding a connection route policy with a do-use-route action referring to the created load balancer.

nlpconfig --add --policy --id=connpolicy --type=connection-route \
--actions=do-use-route --actions-default=do-nothing \
--ref-load-balancer=loadbalancer1


Adding a listener on a secure LDAPS port which will use the connection-route policy defined.

nlpconfig --add --listener --id=listener1 --address=0.0.0.0 \
--port=636 --type=ipv4 --protocol=ldaps --certificate=ec_cert.pem \
--conn-route=connpolicy



Now we have a working basic NetIQ LDAP Proxy configuration in place. Inspecting it with --list will be as follows:

Inspecting the listener:

nlpconfig --list --listener


The output will be:

Listener: listener1
Address : 0.0.0.0
Type : ipv4
Port : 636
Protocol : ldaps
TLS Options:
Certificate: ec_cert.pem
Connection Route Policy ID: connpolicy


Inspecting the policy:

nlpconfig --list --policy


Output:

Policy type: connection-route
id: connpolicy
Rule :
Action:
Refer Load Balancer: loadbalancer1
Default Action :
Do nothing


Inspecting the loadbalancer

nlpconfig --list --load-balancers


Output:

Load balancers: 
Load Balancer id : loadbalancer1
Load Balancer type : Connection
Backend Server ID: backend1
Backend Server ID: backend2


Inspecting the loadbalancer using --expand-id

nlpconfig --list --load-balancers --expand-id


Output:

Load balancers: 
Load Balancer id : loadbalancer1
Load Balancer type : Connection
Backend: backend1
Address : 192.168.56.103
Type : ipv4
Port : 389
Protocol : ldap
Backend: backend2
Address : 192.168.56.104
Type : ipv4
Port : 389
Protocol : ldap


Using --expand-id to expand all IDs starting from the listener.

nlpconfig --list --listener --expand-id


Output:

Listener: listener1
Address : 0.0.0.0
Type : ipv4
Port : 636
Protocol : ldaps
TLS Options:
Certificate: ec_cert.pem
Connection Route Policy:
Policy type: connection-route
id: connpolicy
Rule :
Action:
Refer Load Balancer:
Load Balancer id : loadbalancer1
Load Balancer type : Connection
Backend: backend1
Address : 192.168.56.103
Type : ipv4
Port : 389
Protocol : ldap
Backend: backend2
Address : 192.168.56.104
Type : ipv4
Port : 389
Protocol : ldap
Default Action :
Do nothing


Adding a simple network restriction condition to the Connection-route policy.

nlpconfig --edit --policy --id=connpolicy \
--conditions='(network-addr equal 192.168.56.0/24)'


Inspecting the policy after the condition is added:

nlpconfig --list --policy


Output:

Policy type: connection-route
id: connpolicy
Rule :
Condition:
(network-addr equal 192.168.56.0/24)
Action:
Refer Load Balancer: loadbalancer1
Default Action :
Do nothing



Notes



The manpage - nlpconfig(1), bundled has all the details on what options are supported by different operations and node combinations. Here are some points to have in mind, to understand and predict how nlpconfig will work:

nlpconfig uses GNU-style long options consistently. All options will be of the form: --option or --option=value. Please note there are two hyphens at the start of an option.

nlpconfig always makes an in-place edit of the nlpconf.xml. There are no-backups.

nlpconfig operates on a nlpconf.xml in the current directory. This behavior is a safe default so that you don't end up clobbering your working nlpconf.xml currently used by your NetIQ LDAP Proxy server. This can be changed using the --in-file option, use it with care.

Add/Edit always requires an --id=<id> option, except for nodes - backends, stat-log, audit-config and xdas. You can optionally pass an --id=<id> option to --list  if you want to list a specific policy/listener for example.

nlpconfig writes a certificate-file-name tag only inside a tls-options tag. So a nlpconf.xml edited/created with nlpconfig is meant for use only with NetIQ LDAP Proxy 1.5.2 .

All edit/add options flow-through the proxy-configuration XML tree. At each level, the node tries to consume the options it supports and pass on the rest. After reaching the end of the tree, if there are still options left then nlpconfig generates a warning message with the list of options and values that were not consumed. So a successful edit/add should generate no output on the console.

As an example to explain this option consumption design better, consider the following edit.

nlpconfig --edit --backends --health-check=5 \
--id=backend1 --capability=3 --cipher='HIGH:!aNULL:!eNULL' \
--port=636 --protocol=ldaps



Here, the options are consumed as follows:


    • --health-check by the list-backend-server node

 

    • --capability by the backend-server node

 

    • --protocol, --port by the service node

 

    • --cipher by the tls-opts node




During add/edit, nlpconfig does reference checking for any ID referred to. This would mean for example, you can't add a loadbalancer without adding backends first. This explains the sequence in which operations are done in the example section above.

Conditions are handled as s-expressions by nlpconfig. So a if-srch-base condition would be of the form (srch-base equal "o=netiq"). The syntax for combining conditions using logical operators will be similar to LDAP search filters (which are also s-expressions). Example: (|(srch-base equal "o=netiq")(srch-base equal "o=micorofocus")).

There are two versions of the cool tool RPM attached. The one with a release tag of el6 is for Redhat 6 systems and the other is for SLES12 . They contain the binary nlpconfig and a manpage - nlpconfig(1) with all the options detailed in it. Let me know if you find this tool useful and also if you spot bugs.

Labels:

How To-Best Practice
Collateral
Comment List
Anonymous
Related Discussions
Recommended