Configuring MyVD

MyVD is configured using a properties file. The properties file defines what port the server will listen on, which inserts will run on the global and local namespaces.

Basic Configuration Concepts

The MyVD configuration file is broken into three parts:

  • Listener
  • Global Namespace
  • Local namespaces

The listener portion defines what port the server will listen on and if there is a secure port. The global namespace defines what inserts will run for all requests and the local namespaces defines what inserts will run for indivdual namespaces.

Configuring the Listener

The listener can be configured to listen on a secure port, a non secure port or both. To configure a non secure port simply supply a port number.

#Listen on port 389
server.listener.port=389

To open a secure port you need to know the port, have a keystore to provide a key for encryption and the password for that keystore.

#Listen on 636 using SSL
server.secure.listener.port=636
server.secure.keystore=/var/keystores/myvd.ks
server.secure.keypass=secret

Configuring Namespaces

Namespaces are configured by first specifying a list of inserts and then configuring each interceptor. To illustrate how to configure MyVD we will configure the virtual directory described in the MyVD overview. This virtual directory uses a relational database to store users while utilizing ActiveDirectory for authentication and a custom webservice for updating user information. Bellow is a diagram describing the virtual directory.

MyVD Sample Setup

Configuring the Global Namespace

The global namespace is setup by first listing the inserts that are used in the global chain and then each insert is configured. 

#First specify the inserts in the global namespace's chain
server.globalChain=insert1,insert2,insert3

#Configure insert1
server.globalChain.insert1.className=com.package.class1
server.globalChain.insert1.config.option1=value1
server.globalChain.insert1.config.option2=value2

#Configure insert2
server.globalChain.insert2.className=com.package.class2
server.globalChain.insert2.config.option1=value1
server.globalChain.insert2.config.option2=value2

#Configure insert3
server.globalChain.insert3.className=com.package.class3
server.globalChain.insert3.config.option1=value1
server.globalChain.insert3.config.option2=value2

In the above diagram there a single "global" insert: the RoutingPlugin. This insert is used to instruct the router how to route certain requests and is described in the "Insert Reference" section. Based on the above diagram the global namespace configuration would be as follows.

#first configure the global chain
server.globalChain=router

#routing plugin to forward all writes to the master and reads to the database
server.globalChain.router.className=net.sourceforge.myvd.inserts.routing.MasterReplicaRouter
server.globalChain.router.config.specifyToInclude=false
server.globalChain.router.config.readOnly=DB
server.globalChain.router.config.master=Master

Configuring the Local Namespaces

MyVD is configured to have multiple "namespaces" which determine the flow of data through the system. Namespaces are seperated by LDAP DNs. Like the global namespace, local namespaces contain chains of inserts. Unlike the global namespaces, local namespaces are seperated by an LDAP DN and a weight to determine which namespace takes priority when there is a conflict. To configure local namespaces:

#First, list all the namespaces
server.namespaces=ns1,ns2

#configure the ns1 namespace
server.ns1.chain=insert1,insert2
server.ns1.nameSpace=ou=People,dc=domain,dc=com
server.ns1.weight=100

#Configure insert1
server.ns1.insert1.className=com.package.class1
server.ns1.insert1.config.option1=value1
server.ns1.insert1.config.option2=value2

#Configure insert2
server.ns1.insert2.className=com.package.class2
server.ns1.insert2.config.option1=value1
server.ns1.insert2.config.option2=value2

#configure the ns2 namespace
server.ns2.chain=insert2
server.ns2.nameSpace=ou=Groups,dc=domain,dc=com
server.ns2.weight=100

#Configure insert2
server.ns1.insert2.className=com.package.class2
server.ns1.insert2.config.option1=value1
server.ns1.insert2.config.option2=value2

In the above virtual directory there are two namespaces : Master & DB. The Master namespace has a custom built insert for updating identity data via a webservice. The DB namespace is configured with the kerberos insert and a database insert. 

server.namespaces=Master,DB

server.Master.chain=webservice
server.Master.nameSpace=ou=People,dc=domain,dc=com
server.Master.weight=100
server.Master.webservice.className=com.mycompany.webservice.Insert
server.Master.webservice.config.url=http://someserver.somehost.com/myservice

server.DB.chain=kerberos,db
server.DB.nameSpace=ou=People,dc=domain,dc=com
server.DB.weight=100
server.DB.kerberos.className=net.sourceforge.myvd.inserts.kerberos.KerberosInterceptor
server.DB.db.className=net.sourceforge.myvd.inserts.jdbc.JdbcInterceptor
server.DB.db.config.driver=com.db.driver.Driver
server.DB.db.config.url=jdbc:db://server/db
server.DB.db.config.user=user
server.DB.db.config.pass=secret
server.DB.db.config.rdn=uid
server.DB.db.config.mapping=uid=id,cn=name
server.DB.db.config.objectClass=inetOrgPerson
server.DB.db.config.sql=SELECT id,name FROM users

The first line defines the which namespaces will exist. Then each namespace and it's chain are defined. There are two things to note about this configuration:

  • The custom web service insert is configured in the same fashion as the pre-built inserts. This is because all functionality is derived from inserts.
  • Both namespaces have the same weight, but there are no conflicts. This is because the routing insert in the global plugin explictly sets the namespace to be used.

Complete Config

Below is the complete server's configuration.

#Listen on port 389
server.listener.port=389

#Listen on 636 using SSL
server.secure.listener.port=636
server.secure.keystore=/var/keystores/myvd.ks
server.secure.keypass=secret

#first configure the global chain
server.globalChain=router

#routing plugin to forward all writes to the master and reads to the database
server.globalChain.router.className=net.sourceforge.myvd.inserts.routing.MasterReplicaRouter
server.globalChain.router.config.specifyToInclude=false
server.globalChain.router.config.readOnly=DB
server.globalChain.router.config.master=Master

server.namespaces=Master,DB

server.Master.chain=webservice
server.Master.nameSpace=ou=People,dc=domain,dc=com
server.Master.weight=100
server.Master.webservice.className=com.mycompany.webservice.Insert
server.Master.webservice.config.url=http://someserver.somehost.com/myservice

server.DB.chain=kerberos,db
server.DB.nameSpace=ou=People,dc=domain,dc=com
server.DB.weight=100
server.DB.kerberos.className=net.sourceforge.myvd.inserts.kerberos.KerberosInterceptor
server.DB.db.className=net.sourceforge.myvd.inserts.jdbc.JdbcInterceptor
server.DB.db.config.driver=com.db.driver.Driver
server.DB.db.config.url=jdbc:db://server/db
server.DB.db.config.user=user
server.DB.db.config.pass=secret
server.DB.db.config.rdn=uid
server.DB.db.config.mapping=uid=id,cn=name
server.DB.db.config.objectClass=inetOrgPerson
server.DB.db.config.sql=SELECT id,name FROM users

Next Steps

At this point you have been shown how to configure MyVD. From here you can look at the available inserts or how to build your own.