Chapter 7. Configuring Data Sources

Chapter 7. Configuring Data Sources

7.1. About Data Sources
7.2. Configuring Sources in Penrose Studio
7.3. Creating and Editing Sources Manually

Data sources are applications or servers which can be accessed by Penrose Server; the source entry defines the data set and the reverse mappings going from the source data to the virtual directory entry attribute. This chapter describes how to create and edit sources.

7.1. About Data Sources

Data sources are applications or servers which can be accessed by Penrose Server. A connection gives a connection to a server machine; a source is an application on that host machine. A single connection could theoretically have several databases, LDAP servers, and NIS servers. A source is a single instance of Directory Server or a single Active Directory server.

To define the source, the entry includes information to access the source, such as a search base and filter to access an LDAP server. It also lists relevant object classes and attributes for the entries contained in the source.

The source entry also contains fields. These fields are reverse mappings. Basically, Penrose Virtual Directory creates a directory by creating a pair of cross-references. The first mapping (described in Chapter 8, Configuring the Virtual Directory) links the virtual directory entry attribute to a source attribute. The field in the source entry is a reverse mapping, going from the source attribute to a virtual directory attribute.

The information referenced in a field depends on the type of data source:

  • In a JDBC data source, the source is a database table, and the fields are the table columns.

  • For an LDAP data source, the source is a directory subtree, and the fields are its attributes.

  • For an NIS data source, the source is an NIS map, and the fields are the columns in that map.

The data within sources can be normalized on the source before being processed by Penrose Virtual Directory mappings. Penrose Virtual Directory can also normalize data, but this is done through Penrose Virtual Directory, which uses Java, rather than the native tools on the source itself, so normalizing on Penrose Virtual Directory can be much slower than normalizing data on the source. What kind of normalization can be performed depends on the source schema.

7.2. Configuring Sources in Penrose Studio

  1. Open the server entry in Penrose Studio, and expand the Partitions folder.

  2. Right-click the Sources folder, and select New ... Source... from the menu. There are three options — LDAP, JDBC, and NIS — for each supported source type.

  3. Name the source and, if necessary, give a brief description.

    The Class is available for applying a custom Java class to the entry, but, if it is not given, the default class is used. The default is fine for almost all applications.

  4. Choose the connection to use for the source. You can also add a new connection to use a different host or to use a different adapter to connect to a host.

  5. Fill in the data source information. For example, for an LDAP source, supply parameters for LDAP operations (base DN, search filter, and search scope). The parameters for LDAP, JDBC, and NIS sources are described in Table 7.2, “Parameters for LDAP, JDBC, and NIS Sources”.

  6. Select the attributes allowed with the object class which will be displayed when the data source is browsed.

  7. Select the checkbox by the attributes which will be used for naming or identifying the entries.

  8. Click Finish to save the new data source.

7.3. Creating and Editing Sources Manually

Data sources are configured in the file sources.xml, and, as with other partition configuration files, the sources.xml file is in /opt/vd-server-2.0/conf for the default partition and in /opt/vd-server-2.0/partitions/partition_name/DIR-INF directory for additional partitions. This file is illustrated in Example 7.1, “Annotated sources.xml File”. 

 <sources>  main file tag 

   <source name="..."> begins the connection entry  

     <partition-name>...</partition-name> the partition to which the source belongs 
 
     <connection-name>...</connection-name> the connection to use with the source 
 
     <field name="..." primaryKey="..."/> the names of attributes which will be viewed 
 

     <parameter> the configuration settings, in attribute-value pairs 
        <param-name>...</param-name>
        <param-value>...</param-value>
     </parameter>
 
   </source>
 
 </sources>
Example 7.1. Annotated sources.xml File

To create a new source, add a new source entry to the sources.xml file. To edit a source, add, remove, or edit parameters within the entry. Example 7.2, “Example sources.xml File” shows three different source entries for LDAP, JDBC, and NIS sources.

IMPORTANT

Always restart Penrose Server after editing the configuration file. For example: 

service vd-server restart
<sources>

   <source name="LDAP1">
     <partition-name>ExamplePartition2</partition-name>
     <connection-name>example</connection-name>
     <field name="uid" primaryKey="uid" />
     <field name="givenName" />
     <field name="surName" />
     <field name="cn" />
     <field name="mail" />
     <parameter>
               <param-name>baseDn</param-name>
               <param-value>dc=example,dc=com</param-value>
     </parameter>
     <parameter>
               <param-name>scope</param-name>
               <param-value>SUBTREE</param-value>
     </parameter>
     <parameter>
               <param-name>filter</param-name>
               <param-value>(objectClass=*)</param-value>
     </parameter>
     <parameter>
               <param-name>objectClasses</param-name>
               <param-value>inetorgperson,person</param-value>
     </parameter>
   </source>

   <source name="MySQL">
     <partition-name>ExamplePartition2</partition-name>
     <connection-name>example</connection-name>
     <field name="username" />
     <field name="firstname" />
     <field name="lastname" />
     <field name="fullname" />
     <field name="email" />
     <parameter>
               <param-name>catalog</param-name>
               <param-value>employees</param-value>
     </parameter>
     <parameter>
               <param-name>schema</param-name>
               <param-value>system</param-value>
     </parameter>
     <parameter>
               <param-name>table</param-name>
               <param-value>employees</param-value>
     </parameter>
     <parameter>
               <param-name>filter</param-name>
               <param-value>u.lastname = ''</param-value>
     </parameter>
   </source>

   <source name="NISUsers">
     <connection-name>NIS</connection-name>
     <field name="uid" primaryKey="true"/>
     <field name="uidNumber"/>
     <field name="gidNumber"/>
     <field name="homeDirectory"/>
     <field name="userPassword"/>
     <field name="loginShell"/>
     <field name="gecos"/>
     <field name="description"/>
     <parameter>
                <param-name>objectClasses</param-name>
                <param-value>posixAccount</param-value>
     </parameter>
     <parameter>
                <param-name>base</param-name>
                <param-value>passwd</param-value>
     </parameter>
  </source>
Example 7.2. Example sources.xml File

Two important parameters are set in the sources.xml file: fields and parameters.

Argument Description JDBC LDAP
NIS sources do not take any additional arguments with their fields.
primaryKey The naming attribute for the entry.
originalName The original DN or name of the entry in the source.
type The type of entry.
originalType The orignal type of entry in the source.
castType Method for changing the value type.
length The field length in the database table.
precision A parameter to define the precision of number-related data.
caseSensitive Whether the information is case-sensitive.
autoIncrement Automatically increments values in table rows.
Table 7.1. Field Arguments for LDAP and JDBC

Source Parameters Description Example
LDAP Sources
baseDn As with an LDAP command like ldapsearch, the entry name of the entry or subtree to use as a search base. dc=example,dc=com
scope The scope of the operation, how far below the search base to search for entries. The possible values are OBJECT (only the base DN), ONELEVEL (the base DN and all of its immediate children), and SUBTREE (every entry below the base DN). SUBTREE
filter The LDAP filter to use to search for and identify matching entries. (objectClass=*)
objectClasses A comma-separated list of object classes which are assigned to the newly-added entries. person,organizationalPerson,inetOrgPerson
JDBC Sources
catalog The name of the database's catalog. example
schema The name of the schema used by the database. system
table The name of the specified database table. users
filter A search filter to use, based on the database field name. The source is identified by prefixing its alias to the filter. u.lastName = 'Smith'
NIS Sources
objectClasses A comma-separated list of object classes which are assigned to the newly-added entries. posixAccount
base A search base for NIS attributes. passwd.adjunct.byname
Table 7.2. Parameters for LDAP, JDBC, and NIS Sources