Plugin Documentation and Help
For default plugins bundled with VDS, documentation is available formatted as individual PDF files, stored within doc/plugins off the root of your installation. For your convenience, the files are named in the following way:
<grouping>-<plugin_name>.pdf
For example:
Directory_Integration-JoinEntries.pdf
For all extensions, documentation is also provided in HTML format, and can usually be accessed directly by clicking on the Help button within the configuration panel for the plugin. If, for some reason, you are unable to access the file in your browser by clicking on the Help button, you will find the file located within:
extensions/plugins.vds/<extension_name>/files/help_<extension_name>.html
For example:
extensions/plugins.vds/accesslog/files/help_access_log_plugin.html
Managing Extensions
Fig-63: The DSGUI Extension Manager
DSGUI includes a plugin or extension management interface, which can be accessed from the Menu Toolbar under the Extras menu as Manage DSGUI Extensions. Clicking on this menu item will open a dialog that lists the currently available dynamic plugins within a table. Within this dialog you are able to enable or disable different versions of each of the dynamic plugins that DSGUI has loaded. You are also able to Add New plugins, or Uninstall existing plugins.
The DSGUI Extension Manager dialog window contains two panels. In the first panel, plugins are listed within a table. The second panel provides detailed information about the plugin. The plugin table shows three columns: 'Enabled', 'Name' and 'Version'. The Enabled column shows whether or not a plugin will be available within the plugin list when you choose to Add a Plugin within an Automatic Processing Stage. The Name column provides the name of the plugin. Finally, the Version column is used to display the version number of the plugin.
When any row in the table is selected, detailed information including a full description for the plugin is displayed in the panel on the right.
It is possible to enable and disable plugins by simply checking or unchecking the 'Enabled' checkbox within the plugin table. Disabling a plugin will remove it from the plugin list when you choose to Add a Plugin within an Automatic Processing Stage. It is important to note that if a configuration already makes use of a plugin within a processing stage, the plugin will remain active and can be configured for that particular configuration, even if the plugin has been disabled within the extension manager. However, removing a plugin from the extension manager, will remove that plugin for an existing configuration as well.
The Menu toolbar, at the top of the dialog, provides a File menu and an Extension Menu:
-
File
-
Add Extension: Allows you to import a new extension / plugin in the form of a 'jar' file.
-
Select All: Selects all of the plugins within the plugin table (this is useful to mass-enable or mass-disable plugins).
-
Select None: Unselects all items in the plugin table.
-
Refresh Extensions: Updates the plugin table with a newly acquired list of available plugins by querying the plugins stored within the extensions folder.
-
Close Window: Closes the Extension Manager window.
-
-
Extension
-
Enable Extensions: Marks all selected plugins as 'Enabled'.
-
Disable Extensions: Marks all selected plugins as 'Disabled'
-
Remove Extensions: Removes the selected plugins from the extensions folder so that they are permanently unavailable to DSGUI.
-
DSGUI also provides some command-line options that may be useful when you need to perform batch operations to add and remove many extensions at once. The following command line options are available:
-
listExt: Returns a list of all installed extensions, including their version number, whether or not they are enabled and which protocols they apply to. Note that this option will briefly open and close the GUI, so that it is not left running after it has returned this information.
-
addExt: Provides the option to install an extension within the GUI from the command line. You will need to provide the path to the JAR file for the extension. The extension will not be enabled by default, although this can be easily achieved within the extension manager inside the GUI once the extension is installed. This option can be invoked for as many extension files that you need to add in a single operation. Once the extensions have been added, DSGUI will open and remain running.
-
remExt: Provides the option to remove an extension from the GUI from the command line. You will need to provide the extension ID (e.g. plugins.vds/deltree) for the extension that you wish to remove. You can obtain the extension ID for any plugin using the listExt option. This option can be invoked for as many extensions that you need to remove in a single operation. Once the extensions have been removed, DSGUI will open and remain running.
The following examples show the command line options in operation:
bin/dsgui -listExt
plugins.vds/victimattribute:1.1:true:Victim Attribute:VictimAttribute:LDAP
plugins.vds/routeonip:1.1:true:Route On Client IP Address:IPRoute:LDAP:HTTP:Radius
plugins.vds/memberof:1.0:true:User Entry Membership Control Plugin:MemberOf:LDAP
plugins.vds/routeonbind:1.1:true:Route On Bind:RouteOnBind:LDAP
plugins.vds/loghttp:1.2:true:Http Log:HttpLog:HTTP
plugins.vds/routeonfilter:1.1:true:Route On Filter:RouteOnFilter:LDAP
plugins.vds/rootdse:1.1:true:Root DSE:RootDse:LDAP
plugins.vds/mapdnvalues:1.1:true:Map DN values:MapDNValues:LDAP
plugins.vds/changelog:1.1:true:Change Log:ChangeLog:LDAP
plugins.vds/hidepage:1.0:true:Hide Page:Hide Page:LDAP
plugins.vds/inmemoryattr:1.2:true:In Memory Attribute:InMemoryAttr:LDAP
plugins.vds/enforceschema:1.0:true:Enforce Schema Plugin:EnforceSchema:LDAP
plugins.vds/showpage:1.0:true:Show Page:Show Page:LDAP
bin/dsgui -addExt JoinEntries.jar -addExt MapSuffixes.jar -addExt DataView.jar
bin/dsgui -remExt plugins.vds/loghttp -remExt plugins.vds/routeonip
Extensions and RAS
It is important to understand that when you install, enable or disable a dynamic plugin in the Extension Manager, you are only affecting your local copy of DSGUI. If you are working on a remote configuration and wish to make use of a dynamic plugin, you need to ensure that this plugin is also available on the remote system. Since extensions are largely designed to provide a GUI interface to a plugin script, it is still possible to use dynamic plugins for a remote system that does not have DSGUI installed (and therefore is incapable of installing Extensions).
To do this, you will need to identify the script file that the extension is using, and ensure that you copy this file to the same location on the remote system. As long as this file is in place, any configuration generated using a dynamic extension will work perfectly well on a remote system. In general, this can usually be achieved by simply copying the /extensions folder at the root of your local installation, to the root of your remote installation. The extensions are stored as separate folders within this directory, so it is possible to only copy a particular extension across to a remote system, if this is all you require. Finally, it is also possible to determine the path to the script that a particular extension is using by looking at the details for a plugin within the extension manager. By simply copying this script to the identical location on a remote system, any configuration generated using the extension will be able to run on the remote system.
If DSGUI is available on the remote system and you have shell or command line access to this system, it should be relatively simple to use the command line options within DSGUI to ensure that you have the correct extensions installed on the remote system.
Samples
VDS includes a number of samples that can be loaded into an environment in order to help you understand how the different plugins work and how they can be used. These samples include example configurations, as well as sample data that can be loaded into LDAP servers. The samples that are provided with VDS are largely for demonstration purposes and should help you to understand the different functionalities that VDS offers.
It is very important to note that while trying out the sample configurations, you should only run one sample configuration on a system at a time. When you have finished testing a sample configuration, you should stop it or shut it down before running the next sample. If you do not do this, the next sample that you run will be unable to bind to the various ports required in the configuration and will fail to run as expected.
In order to make use of the samples included with VDS, you will need to install and set up one or more LDAP servers into which you will need to load the sample data. Once this has been done, you will be able to load the example configuration files using the VDS GUI (DSGUI) in order to gain an understanding of how the different standard functionalities (or plugins) are configured and how they work.
Please note that setting up and configuring an LDAP server is not necessarily a simple task. The sample data, although provided in LDIF format (which will help facilitate loading the data into an LDAP server) may require some work to import into an existing LDAP setup. The sample data was exported from a SUN LDAP server and may require some work to import into other Unix-based LDAP servers and will almost certainly require a lot of work to import into an Active Directory setup. The data has been successfully imported into the SUN LDAP, OpenDS and IBM LDAP servers without too much trouble in the past, but the operation is not always simple. If you are importing the sample data, we highly recommend that you consult an LDAP specialist for help with this before continuing.
This section is NOT designed to provide detailed help for each functionality. Documentation for the sample that is provided for each plugin is provided, where a sample is available, within the plugin's independent help file or manual, along with a detailed description of the plugin and how it is configured. If you load a sample configuration and you want to see associated documentation and find help for the configuration of the plugin/s used within the sample, expand the Automatic processing stage where the plugin is contained, click on the plugin and then click on the Help button in the configuration panel for the plugin.
While most plugins are provided with a corresponding sample configuration, there are some plugins where a configuration will very much depend on your environment and no sample configuration will exist for these plugins.
Sample Data
In order to use the samples, two sets of data must be loaded into your Directory Servers. This data is stored inside the samples/data directory of your VDS installation. The data is provided in LDIF format, in order to facilitate an easy load into any standard LDAP server. The LDIF files provided for demonstration purposes are named OneCorp.ldif and TwoCorp.ldif.
A few plugins are specific to handling problems in Active Directory environments. As a result, we have included some sample data that can be imported into any Active Directory instance. This data is available in the LDIF file AD-sample-users.ldif. If you choose to make use of this data to try out the samples that require it, you will need to edit the LDIF file to alter the DN suffixes to match your domain requirements.
Each file contains a set of data representing the internal information of a fictional corporation, and was created following standard schema attributes and objectclasses, in order to make it easy to load on virtually every directory server platform available without any changes to the schema definitions.
In order to maximize the benefit of using the sample data, and to gain a complete understanding of how VDS works, we recommend that the data is loaded into two separate directory server instances. However, the samples will also work perfectly well if they are stored in the same instance, although you may not be able to see the full capability of the VDS plugins. Before importing the LDIF file, make sure that the following root DNs are available in the directories where each set of data will be stored:
-
OneCorp.ldif: Data representing "One" corporation. This should be loaded into the dc=onecorp,dc=com branch.
-
TwoCorp.ldif: Data representing "Two" corporation. This should be loaded into the dc=twocorp,dc=com branch.
-
AD-sample-users.lidf: Data for Active Directory specific samples. This should be edited so that the DN suffixes match your domain, and should then be loaded into an Active Directory instance, where it will create a branch 'OU=Tests2,DC=MYCOMPANY,DC=LOCAL'. Note that you may need to change 'DC=MYCOMPANY,DC=LOCAL' to match your environment.
If you are creating new directory instances for the purpose of testing the sample we suggest that you choose "cn=dirmanager" as the DN of the directory manager and "dirmanager" as the password.
Server hostnames in all configurations are as follows:
-
ldapserver1: The hostname used in configurations to represent the server where the OneCorp.ldif data is loaded
-
ldapserver2: The hostname used in configurations to represent the server where the TwoCorp.ldif data is loaded
-
ADserver: The hostname used in configurations to represent the server where the AD-sample-users.ldif data is loaded
-
SUNserver: The hostname used in configurations to represent a Sun DSEE server (for samples using the Simple2VLV and Showpage plugins)
It may be useful to add these entries to your hosts file if you are trying out the samples. For all LDAP server configuration entries, the port number is set to '389'. You may need to edit these to match the ports actually used by your server instances.
After loading the data, and if your environment does not match the one described above, you will find it useful to write down the information of the instance(s) where the data is stored (host name and port number), as you will need to provide this information when setting up the "Output" section of the example configurations in order to make them work.
Once the data has been loaded, you may wish to check that your LDAP instances are running and accessible and that you are able to access the data. You can do this using any standard LDAP Browser application. You will also be able to do this using the built-in LDAP Browser provided with VDS by opening DSGUI and selecting the LDAP Browser button from the toolbar, or selecting Extras from the File menu and then selecting LDAP Browser from the list of options presented.
Working with Samples
All example configurations are stored in the samples directory and can be accessed from DSGUI by opening a local configuration and changing the root of the configurations to the "samples" directory.
Each sample configuration is meant to show how one of the plugins works. All of them consist of a single listener accepting requests on port 3890 (where test LDAP queries should be sent), a processing stage with a single functionality (except the logging samples where the logging functionality is added to one of the already defined samples) and an "Output" definition where the destination directory servers are configured.
In order to make the samples work, the only change required for each configuration is the redefinition of the "Output" section so that requests can be routed to the directory servers that you have used to load the sample data (as explained in the previous section).
By default, the configurations will have defined two DataSources called sgOneCorp and sgTwoCorp within the Output section of the configuration tree. Each DataSource will need to be configured to point to the place where the OneCorp.ldif and TwoCorp.ldif files were loaded respectively. You should edit the DataSource information within this part of the configuration so that it contains the server information (host name and port) that we suggested that you write down in the previous section.
Each plugin, for which a sample has been configured, will come with its own documentation explaining what the sample does, how it works and how to test it. Since plugins can be chained together within the staged processing model used within the product, some sample configurations will make use of more than one plugin, typically to show common usage scenarios.
Complex Scenario
VDS includes a sample configuration designed to show how multiple plugins can be used in conjunction to create a more complex solution handling a variety of functionalities at once.
Plugins
The following plugins are used in this sample configuration:
-
Operation Dumper: Used to log operations moving through the virtual directory
-
Max / Min Limits: Used to control the maximum and minimum values that can be entered for attributes
-
Attach Trees: Used to mount a branch from a backend directory onto the DIT structure of the virtual directory
-
Join Entries: Used to merge data from entries that share a common attribute within separate branches of the virtual directory
-
Suffix Mapping: Used to transform a suffix or DN used in one directory to appear as if it belongs to another
-
Merge Trees: Used to create a virtual branch consisting of entries from one or more different branches within one or more backend directories
Location
The sample configuration will be accessible within DSGUI in the Open Config dialog, by clicking on the drop-down selector at the top of the dialog window, and changing the value from 'confs' to 'samples'. The sample configuration is named:
sample.complex
If you wish to view the actual LDIF file that makes up this configuration it is located in the samples folder at the root of your installation.
samples/sample.complex
Objective
Most of the samples included with the bundled plugins, use a single plugins within their respective example configurations. This sample, however, will attempt to show how multiple plugins can be used in more complex configurations.
This scenario uses six of the bundled plugins, each of which performs the functionality presented in their independent samples. Documentation for each plugin, including how the plugin is configured within the sample, can be found by clicking on the Help button in the configuration panel for the respective plugin. The six plugins are joined in a single configuration to show how they can interact among themselves, and also to show how VDS has created a modular processing system that allows you to manipulate and control data as it moves between client applications and server repositories.
Configuration
All of the plugins in this example configuration use the configuration settings that are used in their independent sample configurations. More detail on how they are configured can be found by clicking on the Help button in the configuration panel for the respective plugin The only difference in this configuration is that the plugins are now all grouped together in a single configuration. Each plugin is attached to its own stage, which is labelled in such a way as to indicate the functionality that we are trying to achieve using the plugin.
Test
All of the tests explained in the samples for the different plugins that are used in this configuration can be used to test this sample, and all of them should work in the Virtual Directory created by this configuration.