Virtual Directory Server 6.1 - Virtual Directory Server User Guide

88851: How to overcome a page size limit set on target LDAP system 89110: Error with BINDS in Active Directories 107560: Unix ODBC Configuration 107701: Install on 64-bit Linux 108986: Upgrade Guide 109131: Memory Limits

INTEGRATION WITH OTHER PRODUCTS FROM DELL SOFTWARE

SAML Support with Cloud Access Manager Securing the Environment and Auditing Modifications with ChangeAuditor

Generic Attribute Editor

You can use the Generic Attribute Editor to edit arbitrary entries in your configuration. It is a special editor for attribute-value pairs that are commonly used in LDAP Directory entries and LDIF files. The editor supports the editing of multi-value attributes.

Fig-21: Generic Attribute Editor in View Mode

When you view an entry, you will see the generic attribute editor in view mode. To start editing, click the Edit button. The editor will then change its appearance to make it easy for you to make changes. Once you are finished, you can confirm your changes by clicking the OK button, or to abort them by pressing the Cancel button.

Fig-22: Generic Attribute Editor in Edit Mode

When editing an entry, you will see a table consisting of two columns: Attribute and Values. The right column entitled Attribute contains the attribute name (or Attribute Type in LDAP nomenclature).

Adding new Attributes or Values

One of the Generic Attribute Editor's main features is to facilitate the adding of new attributes or values. In edit mode, a blank cell will be displayed below the last value of every attribute, and below the last attribute in the table. The empty cells in the Values column can be used to add additional values to an attribute. The empty cell at the end of the Attribute column can be used to add new attributes.

When you have finished editing an entry, press the OK button and your changes will be saved. In some cases, when you are adding new entries, it is necessary to add the objectclass attribute and to set it to at least one value. If you forget to do this, you will be asked for a value for the objectclass attribute as soon when you finalize your edits by pressing the OK button.

Removing Attributes or Values

To delete a value, click with the secondary (usually right) mouse button on the cell containing the value and select the option to delete from the pop-up context menu that appears. You are able to delete values one by one.

You are able to delete whole attributes from the table in a similar manner, by right clicking on the cell containing the attribute type and then selecting the delete option from the context menu. Note, however, that when deleting an attribute all associated values are naturally deleted as well.

Inserting Attributes or Values

Within the context menu, that appears when you right click on any attribute or value, there are also the options to Insert Before and Insert After. You can use these options to add a new row either before or after the current one that you are editing. You will then be able to add a new value or attribute by editing the new blank row that will have been created.

CONFIGURATIONS

Creating Configurations

Configurations are created or modified using the Menu buttons or shortcuts provided within the GUI. To create a new configuration, you can click on the New Config button in the shortcut menu, or you can click on File, New and then select the appropriate type of configuration (e.g. Local or Remote). To open an existing configuration for editing, click on the Open Config button in the shortcut menu, or click on File, Open and then select the appropriate type of configuration (e.g. Local or Remote). When multiple configurations have been loaded, a tabbed menu appears along the top of the panels, allowing you to switch between the different configurations. Each configuration will load in the navigation panel on the left of the GUI as a 'configuration tree' with a collection of nodes. The nodes on the tree represent the different sections that comprise the complete configuration for any instance of VDS. You can navigate to the different sections by clicking on the appropriate node in the configuration tree, which will load the configuration panel in the frame on the right of the GUI.

There are six nodes in the configuration tree. Many of the default settings for a new instance of the VDS will be sufficient to create a fully functioning configuration, however you may want to revisit some of the optional settings to provide further services. The first three nodes in the configuration tree represent core and optional features. An initial configuration does not require any settings in these nodes to be modified. The next three nodes will require modification in order to create a functional configuration of VDS.

The first three nodes of the configuration could be grouped together to cover general configuration requirements, all of which are covered in this chapter. These are:

Global Parameters: This includes global settings that will affect the entire instance of the VDS and which will affect the overall performance of the service. Changes to this node should be made with a clear understanding of the repercussions to the service.
Health Checking: While the settings for this component are considered to be optional, this is an important component when making use of the load-balancing and failover services provided by VDS. Health checking is responsible for checking the availability of the servers defined within the configuration.
Administration: As an optional node of the configuration tree, the Administration Port currently provides facilities for graceful shutdown and basic statistics indicating the health and performance of an instance of VDS. Additionally, the Administration port can be used to change logging levels for various components while an instance is running. This node is under active development and more features are likely to appear in this part of the configuration in future versions of the product.

The following three nodes in the configuration tree could be grouped together to describe the functional configuration requirements, in that each of these sections will require settings for the instance of VDS to function. Each of these sections will be described in their own chapters as their settings are required in order to provide a working configuration.

Input: Within the Input node, you are able to configure the settings which allow external applications to interact with an instance of VDS. From this node you can configure the port and protocol settings that external applications will make use of to connect to VDS. The following chapter, ( INPUT ), will provide a detailed explanation on how this done.
Processing: This section of the configuration is used to define various functionalities that this instance of VDS will implement. Within this node of the configuration tree, you are able to define the different elements (plugins, stages and hooks) that will allow your client applications to interact with your data repositories. This is a complex section and is discussed in detail in the PROCESSING chapter.
Output: This final node on the configuration tree deals with the definition of the different data repositories that the instance being created will make use of. A full explanation on this node is given in the OUTPUT chapter.

Each configuration is stored directly within the filesystem and the GUI interacts directly with the file-based configuration. Configuration changes can be made directly to the individual files themselves for greater control over the final setup. Although we recommend that you make use of the GUI to create or edit a configuration, the next section will discuss briefly how the configurations are stored in the filesystem to provide more clarity on what is actually taking place in the GUI.

Configuration storage in the Filesystem

Since version 4.0, VDS configurations are mapped into folders or directories that contain all the necessary files (configuration and scripts) to make the configuration work.

VDS will take care of the creation of the directory structure whenever a new configuration is created, or an existing configuration is saved with a different name or copied from another server.

A configuration directory has the following elements:

Main configuration file (main.ldif). This is the file that is passed to the VDS binary whenever the configuration is loaded.
Custom scripts directory (local). This directory is used to store the source files of all custom functionalities used by the Processing section of the configuration. If for some reason the configuration uses a source file that is not in this directory, the source file will NOT be moved if the GUI is used to move the configuration to a different server.
Log directory (logs). This directory is used to store the logging output files generated by the configuration. All logging scripts should be configured to generate their output to this directory.

Configuration selector

Every operation affecting a configuration (creation, saving, saving with a different name and opening) is handled using the "Configuration Selector" panel.

Fig-23: Configuration Selector

In the image, it should be clear that there are three sections to the configuration selector:

The source selector. As several different configuration directories can be defined for each instance (configurations or samples), this "drop-down" selector allows you to quickly choose from the available existing configuration directories.
The file tree. The filesystem information for the selected configuration directory is shown here. There are three different filesystem elements in the list: files (indicated with an icon that resembles a piece of paper), normal directories (indicated with an icon that resembles a folder) and complete configuration directories (indicated with an icon of a grey cylinder). The file tree is used to select among the different elements within the selected source.
The command section. This section includes the configuration name and the command buttons. The line will show the currently selected item in the file tree, and can also be used to specify a name when creating a new configuration. The two buttons below the line are used to issue a Configuration Selector command, such as creating a new configuration or opening a selected one.

Configuration versions

When opening a configuration that was created with an older version of VDS the GUI will try to update it automatically to the current version, so that it is effectively upgraded when saved. If the version of the configuration to be upgraded is recent the process should work without problem, but if it was created with an older version of the product, the functionality may change afterwards (and additional manual updates may be required for it to work).

When working remotely it is also possible to have a version mismatch between the local GUI (with which the configuration is edited) and the remote administration server (that runs the instance). This case can create unexpected results, so it is recommended that the product versions are always aligned.

Opening a Configuration in DSGUI from the Command Line

DSGUI supports a few command-line options that may make it easier to work with in some environments. With regard to configurations, DSGUI can be opened with one or more specified configurations loaded. This is achieved using the openConf command line switch, used in the following way:

    bin/dsgui -openConf myconfig@localhost -openConf production@server1.mydomain.com

This example will open DSGUI with two configurations loaded and ready to work with. The first configuration is hosted locally on the same system as the DSGUI application, while the second configuration will open a RAS connection to a remote system (server1.mydomain.com) and will open a configuration named 'production' hosted at this location. In order to open a configuration from the command-line, you need to know the configuration name beforehand. If you specify a configuration name that does not exist, you will be presented with an error message once DSGUI has opened. In order to open a remote configuration, you must ensure that RAS is enabled on the remote system before you attempt to connect to it. Please see How to configure the RAS for more information.

Global Parameters

The Global Parameters configuration panel allows you to set several parameters that affect the operation of the VDS instance for which the configuration will apply. These parameters define how the VDS application will interact with the system that it runs on, and its general operational behavior. These settings can be changed to tweak the overall performance of the application, and for debugging purposes.

WARNING: Before changing these parameters, make sure you understand their meaning exactly. Misconfiguration of global parameters can have wide-ranging and potentially adverse effects on the manner in which VDS operates.

Fig-24: Global Parameters Panel - Global properties

The Global Parameters Panel is separated into four distinct sections.

Debug Level for DataSources

This 'slider' option allows you to specify the level of verbosity that the VDS will generate as logging output when it handles the initial setup of your configuration. The log output specifically relates to the initialization process of the DataSources (creation of connection pools, creation of health checking infrastructure, etc.) and with the process of routing PDUs on to back-end servers.

The level of detail returned in the logs can be controlled by moving the slider from left to right to increase verbosity, or from right to left to decrease verbosity. Please also see the section on Debug Logs for live instances.

Debugging options are usually turned off in production environments, as the amount of printing that a process must go through can impact on the overall performance of the application.

Poll Timeout: VDS uses the epoll(4) I/O event notification facility, provided on UNIX systems, to check many file descriptors at once for input and output. The value that you specify here will be passed directly to the timeout parameter of the epoll_wait system call. See the manual page for epoll by typing man epoll on your UNIX system. In general, if you set this number lower, VDS may do more iterations of epoll_wait, which under certain circumstances, will improve the responsiveness of VDS to a single synchronous client, however as a trade-off more system CPU time will be used. Note that since this option makes use of a UNIX facility, changing this option will have no effect on an instance installed on Windows.
Max. Simultaneous Connections: Regardless of the maximum open file descriptors limit that is set by the operating system, this is the maximum number of connections that VDS will accept. So the maximum number of simultaneous connections will be limited by the lowest of these two parameters.
Max. PDU Length (Kb): Specifies the maximum size of a PDU that will be accepted by the proxy. The lowest possible value is 4Kb, and the default value is 1024Kb.
Number of CPUs: The number of CPUs available on the system where the configuration will run. This value is used to calculate the appropriate thread limits for the values specified below.
Writer Threads: The number of writer threads, responsible for all write operations (such as writing a PDU to an outgoing stream). The default value should be sufficient in most use cases, however if this value needs to be adjusted, it should be a power of two. This value should only be adjusted on multi-processor systems, and should ideally be equivalent to the number of processors available divided by 4. i.e. for 8 processors, you might change this value to 2. Setting this value outside of the recommended values will prompt a warning, but will nevertheless store the value that you have set.
Reader Threads: The number of reader threads, responsible for handling all read operations (such as reading an incoming PDU to memory). The default value for this field should be sufficient for most use cases, however if this value needs to be adjusted, it should be a power of two. The general rule is that this value should not exceed a number higher than half the number of processors available on the system. i.e. for 8 processors, the value should not exceed 4. Setting this value outside of the recommended values will prompt a warning, but will nevertheless store the value that you have set. This option will not appear within DSGUI on a Windows system, due to a performance requirement that results in a slightly different approach to threading.
Consumer Threads: The number of consumer threads (by reader thread). Consumer threads are used to handle processing on the data held for any PDU and will read the entire PDU for processing, releasing the file descriptor for use by another consumer thread. This setting is per reader thread, thus the actual number of consumer threads will be equivalent to this value multiplied by the number of reader threads that are running. The default number of consumer threads should be sufficient in most use cases, but where an adjustment is required, on Linux and Unix systems it should not be set to below 2 and should generally not be greater than 8 times the number of processors within the system. On Windows systems this value may be set up to 10 times the number of processors. Setting this value outside of the recommended values will prompt a warning, but will nevertheless store the value that you have set.
Define Default FE Timeout: This checkbox will enable a default timeout value for frontend connections. This will allow the proxy to drop an idle connection on the client facing side after a specified period. To the right of this checkbox the value in seconds can be defined after which an idle frontend connection will be dropped (if the Define Default FE Timeout option is checked).
Tcp No-Delay: This selector will enable or disable Tcp No-Delay functionality for the selected configuration. The Tcp No-Delay option may improve network latency. Network packets are sent immediately after the application submits them. This may decrease the latency for each packet, but often does so at the expense of efficiency. When this option is disabled, the default state, Nagle's algorithm is employed to reduce the number of actual packets being sent over the network, reducing network load and potential congestion issues.
Activate Watchdog: This selector will enable or disable the watchdog functionality for the selected configuration. The watchdog option only works in Unix environments (Solaris, Linux, AIX, etc.), and it tells the engine to start a second process called the "watchdog" that will monitor the status of the running instance and restart it automatically if it is detected to no longer be active. In Windows environments this functionality is automatically implemented.

Running Parameters

Fig-25: Running Parameters

The Running Parameters override runtime options for VDS by specifying the various switches required to launch the process. In general, you will run an instance of VDS using the default values that are specified in VDS's Preferences. You can change these settings for all instances of VDS by editing the fields under the Running node within the application Preferences ( Running Preferences ). Or you can change the settings for a single instance of VDS by editing the fields within this part of the panel.

Lock Windows Service Details: This setting will only apply to instances running on a Microsoft Windows platform. Each time an instance is started on Windows, it is registered as a service and the runtime parameters are stored as a registry key entry. When the instance is stopped, the service is removed. If you wish to lock the service (so that it is not removed), in order to manage starting the instance at boot time, you can check this box. However, it is important to be aware that if this box is checked, any changes to the run-time parameters will not be effective until the service is removed and re-registered.
Load from Preferences: As these settings are modifiable and the settings specified here may not conform to the default values that you have set to run all instances of VDS, this button has been provided to conveniently copy the values stored in your default preferences to all of the fields in this part of the panel.
GUI Params: Parameters to pass to the VDS binary when launching the application. This is a non-writable field, the parameters are given by the fields: Default Options, Extra Options, Enable afr debug and afr size.
Standard Output/Error Redirection: A file selector to specify the name of the file and the place (usually the path to the log sub-directory of the configuration directory) where the VDS binary will send its STDOUT / STDERR output. These logs are displayed in The Message Output Area , when an instance is started within DSGUI.
Rotate Logs: Rotation options for STDOUT, STDERR and logs generated by plugins: No Rotate, Daily or Monthly.
Default Options: Parameters required by the VDS binary when launching the application. The allowed parameters are: -SI, -C, -I and -ek. Their values can be edited, but it's not recommended. Make sure you understand what you are doing, the application could not work.
Extra Options: Optional parameters to pass to the VDS binary when launching the application. For a full list of available parameters please refer to Dell One Identity Virtual Directory Server Administrator's Reference Manual
Core Dump Generation: In the event of a crash this option will generate a dump file with live internal information that can be analyzed later.
afr size: Size in MB of Application Flight Recorder buffer per thread. Allowed values are from 1 to 10, default is 3.
Delete Logs on start: Defines if the configuration will delete both STDOUT and STDERR outputs every time it is restarted or will just append information to existing files.

SASL

Fig-26: SASL Parameters

The following options are available to control SASL behaviour within VDS.

Use Default SASL Values: Enabling this checkbox will cause the proxy engine to use the default SASL values expected for your operating system and the corresponding SASL library. In the case of a Windows system, it points to the library delivered with the product (../../lib/wingss.dll). In the case of a Linux system the default value is libgssapi_krb5.so; MIT Kerberos library should be installed and available within the system path for dynamic libraries.
SASL Library: The SASL library that should be used to provide Kerberos support via GSSAPI. It should only be changed if you are using an alternative SASL library or the one that you are using is not available within the system path for some reason (see default values before). While it is possible to use an alternate Kerberos implementation with VDS, we highly recommend that you use the default supported libraries.
SASL Prefix: By default this setting should be empty. It should only be changed if an alternate SASL Library has been used and the particular GSSAPI implementation uses prefixes within its function names.

Supervisors

Fig-27: Supervisor Parameters

This panel allows you to configure as many supervisor scripts for your configuration as you need. Supervisors are a fairly advanced topic that you will probably not require unless you are implementing your own back-end management algorithm or custom health-checking system.

Supervisors are the feature that will allow you to activate daemons within the engine. A daemon in this context is a script that is automatically invoked when you start a configuration, thus allowing you to create any functionality that does not need a PDU to trigger it. There are a few rules that you should be aware of if you want to implement your own supervisor:

The supervisor process uses one of the consumer threads and never releases it. So you must make sure that you have a working thread for each defined supervisor, as well as the ones that you need for your "normal" processing.
Exiting from a supervisor function (either with a return or with an exit call) will make the whole configuration that you are running to exit, so as a general rule your supervisor function must be an infinite loop that never finishes.
Implementing your own health-checking and monitoring system
Implementing long slow background processes that should not affect the overall running of the system

You can define as many supervisor functions as you want by adding rows to the table that you see when you select the Supervisor tab. The meaning of the different fields is:

File: Path to file name holding the supervisor function that will be invoked at startup. Note that it would usually be best to provide the full path to the file, and that it is generally a good idea to store configuration specific scripts within the 'local' folder inside the configuration directory.
Function: Name of the function that will be invoked as a daemon on start-up of your configuration.
Parameters: As with any other script, supervisor scripts can also be provisioned with an external parameter. This field configures the value of that parameter.
Number: In some situations, you would need to start several identical instances of the same supervisor script (each one using a different working thread). This parameter specifies the number of times that this supervisor script should be invoked. In most situations it will keep the default value of 1.

The Edit button can be used to open an editor to edit the supervisor script that you have attached here.

Please select your product:

To serve you better, please complete the Purpose of your Chat:

Recommended Solutions for Your Problem