2.4 Configuring Listeners

A listener is the network interface where the LDAP Proxy listens for incoming requests. Using proxy you can configure any number of listeners to listen on to multiple interfaces.

Each listener is made up of interface information that is a combination of an IP address and a port number or a domain name and port number. You must also provide service protocol information indicating either LDAPS or LDAP, which means that it is either a secure or clear-text interface. By default, LDAP Proxy listens on all interfaces.

The <list-listener> node in the configuration file lists all the listeners configured for the proxy. The additional listeners must be defined in this node.

For instance, if you want to define listener1 to use the LDAP protocol. You also want to define the IP address as 192.168.1.1 and the port as 389. Any request coming through this interface must be processed through a Connection Route policy identified as <ref-policy-connection-route>conn-route-policy</ref-policy-connection-route>. To do this, you can define your configuration as follows:

<list-listener>
 <listener id-listener="listener1">
  <service protocol="ldap">
   <addr-ipv4>192.168.1.1</addr-ipv4>
   <port>389</port>
  </service>
  <ref-policy-connection-route>conn-route-policy</ref-policy-connection-route>
 </listener>
<list-listener>

2.4.1 Configuration Parameters for Listeners

Use the following elements and attributes to define the listener configuration:

<listener>: Specifies that the element configured is a listener. This element has the following attributes:

  • id-listener: The identity of the listener. The value of this attribute is used to refer to the listener. It must be a unique alphanumeric value, such as listener1.

The <listener> element must have the following child elements:

  • <service>: Specifies how the listener listens for incoming requests. It must have the following attributes:

    • protocol: The protocol that the listener uses to listen for incoming requests. The attribute value can be ldap or ldaps. For more information, see Configuring Protocols.

      NOTE:If you specify the protocol as ldaps, you must specify the certificate information. Use the <certificate-file-name> element to specify the name of the file that contains the certificate information.

    The <service> element can have the following child elements:

    • <addr-ipv4>/<addr-ipv6>: The IP address of the system on which LDAP Proxy is installed.

    • <port>: The port on which the listener listens for incoming requests.

    • <addr-dns>: The domain name of the system on which LDAP Proxy is installed. In Example 1, the value is server1.example.com.

    • <tls-opts>: A configuration option to specify the Transport Layer Security (TLS) parameters when protocol is defined as LDAPS under the <service> tag for the listener configuration. For more information, see Configuring Secured Communication Using TLS Parameters.

  • <ref-policy-client-network>: Any request coming through this listener must be processed by using the Client Network policy. The term ref in this element indicates that this element is actually a pointer to a policy called policy-client-network. For more information about the Client Network policy, refer to Accepting or Denying a Client Connection (Client Network Policy).

  • <ref-policy-connection-route>: Any request coming through this listener must be processed by using the Connection Route policy. The term ref in this element indicates that this element is actually a pointer to a policy of type policy-connection-route. For more information about the Connection Route policy, refer to Routing an Incoming Request to a Back-End Server Group (Connection Route Policy).

    The value shown in Example 1 is anonymous-policy. It means a policy identified as the anonymous-policy must be applied to all requests coming through the port specified in the relevant listener configuration.

  • <certificate-file-name>: The name of the file that contains the certificate information. If the proxy is going to listen on a secure port, you must specify certificate information.

    NOTE:Ensure that you place the specified certificate file in the /etc/opt/novell/ldapproxy/conf/ssl/private directory. The certificate should be in the pem format.

    For more information about how to export certificate file information, refer to Configuring Certificate Information.

2.4.2 Configuring Listener on a Secure Port

LDAP Proxy can be configured to use the TLS protocol to provide data privacy and integrity between the Proxy server and the LDAP client and back-end server. This configuration ensures data confidentiality and integrity protection.

To configure a listener on a secure port, perform the following steps:

  1. Configure the LDAP Proxy listener with a X.509 certificate.

    The certificate should reside in a PKCS#12 file along with the private key and all the CA certificates in the chain. Also, ensure that the LDAP Proxy server's IP address or DNS name is present in the Common Name (CN) field of the certificate's subject name or in the Subject Alternative Name list. You can obtain a PKCS#12 certificate file for the LDAP Proxy listener from any of the following Certificate Authority (CA):

    • eDirectory

      Create a LDAP Proxy server certificate in eDirectory and export it using Certificate Management in Identity Console. For more information, see Understanding the Certificate Server in the eDirectory Administration Guide.

    • Active Directory Microsoft Management Console (MMC) Certificate snap-in

      Refer to the Active Directory documentation for more information.

    • Third-party CA

      Refer to the third-party documentation for more information.

  2. Export the library path by using the following command:

    . /opt/novell/ldapproxy/bin/nlppath

  3. Import the certificates and keys present in the PKCS#12 files by using the nlpcert utility:

    nlpcert -i server_cert.pfx -o private-cert.pem

    In this example, server_cert.pfx is the downloaded PKCS#12 certificate file and private-cert.pem is the converted pem certificate file.

  4. Copy the private-cert.pem to /etc/opt/novell/ldapproxy/conf/ssl/private directory.

  5. Specify the private-cert.pem in the <certificate-file-name> tag of nlpconf.xml.

    Ensure that you define the protocol as ldaps under the <service protocol> tag as shown below:

    <listener id-listener="listener1">
              <service protocol="ldaps">
                    <addr-ipv4>0.0.0.0</addr-ipv4>
                          <port>636</port>
              </service>
              <certificate-file-name>private-cert.pem</certificate-file-name>
              <ref-policy-connection-route>conn-route-policy</ref-policy-connection-route>
    </listener>
  6. Save the nlpconf.xml file.

2.4.3 Configuring Listener on a Non-Secure Port

To configure a listener on a non-secure port, complete the following steps:

  1. Open the nlpconf.xml file from the /etc/opt/novell/ldapproxy/conf directory.

  2. Verify that the listener configuration is defined as shown below:

    <listener id-listener="listener1">
      <service protocol="ldap">
               <addr-ipv4>0.0.0.0</addr-ipv4>
               <port>389</port>
      </service>
      <ref-policy-connection-route>conn-route-policy</ref-policy-connection-route>
    </listener>

    NOTE:Ensure that you define the protocol as ldap under the <service protocol> tag.

  3. Save the nlpconf.xml file.

2.4.4 Configuring Additional Listeners

You can configure additional listeners using both nlpconf.xml file or NLPManager utility.

Manually Configuring Additional Listeners

  1. Open the nlpconf.xml file from the /etc/opt/novell/ldapproxy/conf directory in any XML editor.

  2. To add a listener to the existing configuration, create an instance of the following within the <list-listener> node:

    <listener id-listener="listener1">
     <service protocol="ldap">
      <addr-ipv6>[2015::37]</addr-ipv6>
      <port>4489</port>
     </service>
     <ref-policy-request-route>anonymous-policy</ref-policy-request-route>
    </listener>
  3. Define the following in the newly created instance:

    • The name to identify the listener you are configuring.

    • Provide either the IP address or the domain name of the system on which you have installed LDAP Proxy.

    • The protocol as either LDAP or LDAPS.

    • The port number of the interface.

    • The name of the certificate file, if you specify the protocol as LDAPS.

    • The Client Network policies and Connection Route policies that must be applied to the incoming requests. Multiple Connection Route policies can be configured on the listener, based on the identity.

    For information about the elements and attributes that are used to define these parameters, refer to Configuration Parameters for Listeners.

  4. To add more listeners, repeat Step 2 to Step 3.

  5. Save the nlpconf.xml file.

Configuring Additional Listeners Using NLPManager

You can configure additional listeners for the LDAP Proxy configuration by using the Listeners tab.

  1. Run the ./NLPManager command to start NLPManager.

  2. To open the nlpconf.xml file, In the Provisioning menu, click Open Configuration:

    The Open dialog box appears.

  3. Browse to the nlpconf.xml file in the /etc/opt/novell/ldapproxy/conf directory and click Open.

    The conf directory is available on the machine where you installed LDAP Proxy.

    If NLPManager and LDAP Proxy are installed on different machines, you must either save the nlpconf.xml file on the machine where you installed NLPManager or map a network drive to the machine where you installed the proxy.

    The proxy configuration is displayed in the Project Explorer pane.

  4. Click the Listeners option in the Project Explorer pane.

    The Listeners tab is displayed. To change the listener configuration, change this setting.

  5. To add a listener, click the icon.

    The Add New Listener window is displayed.

  6. Specify a name to identify the listener you are configuring and click OK.

    The name must be a unique alphanumeric value.

    The listener configuration fields are displayed in the Editor pane.

  7. Specify the following:

    • Address Type: The address type of the interface where the listener must listen for requests.

      To provide the IP address of the system where you installed the LDAP Proxy, select IPv4 or IPv6.

      To provide the domain name of the system where you installed the LDAP Proxy, select DNS.

    • Address: The value of the IP address or domain name, depending on the address type you have specified.

    • Protocol: Specify either ldap or ldaps.

    • Port: The port number of the listener interface.

    • Certificate File Name: The name of the certificate file, if the protocol specified is ldaps.

      Ensure that you have placed the certificate file in the /etc/opt/novell/ldapproxy/conf/ssl/trustedcert directory.

  8. To add more listeners, repeat Step 6 and Step 7.

  9. To delete a listener, select the listener from the list and click the icon.

  10. Click Provisioning > Save to save the changes.

2.4.5 Examples

Example 1

<list-listener>
 <listener id-listener="listener1">
  <service protocol="ldaps">
   <addr-ipv4>192.168.1.1</addr-ipv4>
   <port>636</port>
  </service>
  <certificate-file-name>private-cert.pem</certificate-file-name> 
  <ref-policy-connection-route>admin-policy</ref-policy-connection-route>
 </listener>
 <listener id-listener="listener2">
  <service protocol="ldap">
   <addr-dns>server1.example.com</addr-dns>
   <port>389</port>
  </service>
  <ref-policy-connection-route>anonymous-policy</ref-policy-connection-route>
 </listener>
<list-listener>

In Example 1, two listeners are defined as listener1 and listener2. Listener1 is defined to use the ldaps protocol to listen for incoming request on the system. The interface is defined by IP address 192.168.1.1 and port 636. This node also specifies that a Connection Route policy identified as admin-policy is to be applied to all requests coming through the specified port, and also specifies the filename of the certificate to be used by the protocol. Listener2 is defined to use the ldap protocol, and the interface is defined by domain name server1.example.com and port 389. It also routes requests to a Connection Route policy defined as anonymous-policy.

Example 2

<list-listener>
 <listener id-listener="listener3">
  <service protocol="ldaps">
   <addr-dns>server1.example.com</addr-dns>
   <port>636</port>
  </service>
  <certificate-file-name>private-cert1.pem</certificate-file-name> 
  <ref-policy-connection-route>admin-policy</ref-policy-connection-route>
 </listener>
 <listener id-listener="listener4">
  <service protocol="ldap">
   <addr-dns>server1.example.com</addr-dns>
   <port>1389</port>
  </service>
  <ref-policy-connection-route>admin-policy</ref-policy-connection-route>
 </listener>
<list-listener>

In Example 2, two listeners are defined as listener3 and listener4. Listener3 is defined to use the ldaps protocol to listen for incoming request on the system. The interface is defined by domain name server1.example.com and port 636. This node also specifies that a Connection Route policy identified as admin-policy is to be applied to all requests coming through the specified port, and also specifies the filename of the certificate to be used by the protocol. Listener4 is defined to use the ldap protocol, and the interface is defined by domain name server1.example.com and port 1389. It also routes requests to a Connection Route policy defined as admin-policy.