3 Installing Eloquence on Windows

Configuring the eloqsd service

The eloqsd service is an important part of Eloquence. It is responsible for the following tasks

NOTE: The eloqsd service is not related to Eloquence database operation. If the only Eloquence component you intend to use is the database, you don't need to configure and run the eloqsd service.

NOTE: On Windows XP Home Edition, it is not possible to use the eloqsd service because XP Home lacks the Windows Group Policy Editor.

Eloquence implements its own file sharing capabilities through the eloqsd server. This makes it independent of the availability of specific network file systems (NFS, SMB) and overcomes inappropriate limitations.

In order to run the eloqsd service it is required to adapt your system configuration. This involves the following steps:

Registering the eloqsd server with the Windows operating system

The eloqsd is installed as a Windows service. The installation program installs the eloqsd.exe executable in the Windows system directory (C:\Windows\System32). In addition, it is automatically registered with the Windows Service Control Manager.

NOTE: Manual registration of the eloqsd service with the Windows Service Control Manager is usually not required since the installation program performs a default registration. Unless you are interested in the registration and unregistration details you can skip this section.

In order to manually register the eloqsd server with the Windows Service Control Manager you must execute eloqsd.exe with the -install argument:

  1. Log on as Administrator.

  2. Open a Command Prompt window.

  3. Execute the command: eloqsd -install. This makes the eloqsd server available to the Windows Service Control Manager. The service name is "eloqsd".

NOTE: To manually unregister, use the command: eloqsd -remove. Note, however, that this is normally not required since the installation program takes care of unregistering the eloqsd service during product update or uninstallation.

Configuring your System

This involves the following steps:

Configuring the eloqsd TCP service

For eloqsd, the installation program adds the following default TCP service to your local SERVICES file:

eloqsd          8100/tcp    # Eloquence A.06.xx eloqsd server
In rare cases it might be necessary to modify this standard configuration, for example if the port number does not match the one configured on other systems. Please refer to the previous section Modify the standard configuration of Eloquence service names for details.

Configuring the default eloqsd account

The eloqsd server requires you to specify an account name in the configuration file. This account is used to define the access rights which are used unless a specific account is defined for the user.

You may specify any existing account in the configuration file (for example the guest account) or you may create a new user account "eloqsd" which is used by the eloqsd server.

Grant the background login right to users

Each system account associated with an eloqsd user must have the right to log on as a batch job. This must be setup manually using the Windows Server 2003/XP/2000 security settings or the Windows NT User Manager (or User Manager for Domains).

NOTE: This requires that the Windows Group Policy Editor is available which is not the case on Windows XP Home Edition.

  1. Log on as Administrator.

  2. Windows Server 2003 or XP:

* Open the Windows Control Panel

* Select Performance and Maintenance

* Select Administrative Tools

* Select Security Settings

* Select Local Policies - User Rights Assignment

Windows 2000:

* Open the Windows Control Panel

* Select Administrative Tools

* Select Security Settings

* Select Local Policies - User Rights Assignment

Windows NT:

* Select Programs - Administrative Tools in the Windows Start Menu

* Start the User Manager (or the User Manager for Domains)

* Select User Rights from the Policies menu

* Check the Show Advanced User Rights option

  1. Select the user right named "Log on as a batch job".

  2. On Windows Server 2003/XP/2000, open the Settings dialog either from the menu or using the context menu (right mouse button). This opens the list of users/groups to which this user right is granted. On Windows NT, this list is part of the User Rights dialog and therefore already open.

  3. Use the Add... button to add the users or groups who should have access to the eloqsd server. To grant this right to all accounts you could simply select "everyone".

Increase the Windows desktop heap

This is an optional configuration step which is only required if during runtime you encounter the Windows error #1816 (ERROR_NOT_ENOUGH_QUOTA). Getting this error indicates that there are too many concurrent eloqsd sessions so that the so-called Windows desktop heap overflows.

To change the size of the Windows desktop heap (more precisely: the desktop heap for the non-interactive windowstation), a Windows system registry entry must be edited, according to the procedure described in the Microsoft knowledgebase document http://support.microsoft.com/?id=184802 .

NOTE: Editing the Windows registry must be done with extreme care, as doing the wrong changes to a registry value can prevent Windows from operating correctly.

  1. Log-on as Administrator (Windows "power user" privileges are sufficient).

  2. Locate the following value in the Windows registry:
    HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\
    Session Manager\SubSystems\Windows

  3. This is a string value consisting of multiple sections. Locate the section starting with SharedSection=, it should have 3 parameters which are comma-separated. Example
    SharedSection=1024,3072,512

  4. The 3rd parameter (512 in the example above) is the one which must be increased. If you find only 2 parameters you should add the 3rd parameter yourself.

You can set the 3rd parameter as high as the 2nd (3072 in the example above), but this is often too much. Increase it in steps of 256 until the Windows error #1816 does not occur anymore.

  1. Windows must be restarted afterwards to activate this change.

Configuring the eloqsd server

The eloqsd server is configured by editing the eloqsd.cfg, eloqsd.user and eloqsd.share configuration files. They are located in the etc subdirectory of your Eloquence installation, for example at C:\Program Files\Eloquence\etc. All configuration files provide complete inline documentation and are included at the end of this chapter for your reference.

Each configuration file is responsible for a specific part of the eloqsd configuration:

eloqsd.cfg
Defines the general configuration of the eloqsd server.
eloqsd.user
Eloqsd provides its own user configuration. This makes it possible to define eloqsd users without the need to have a system account for each individual user. Instead, eloqsd users are associated with system accounts.
eloqsd.share
This configuration file is used to define resources which can be accessed through the eloqsd server's file sharing mechanism.

Configuring the eloqsd server startup

After the eloqsd server has been registered with the Windows Service Control Manager it can be accessed using the Services applet:

Windows Server 2003 or XP:

Windows 2000:

Windows NT:

Locate the eloqsd entry in the list and select it with the mouse. On Windows Server 2003/XP/2000, open the Properties dialog either from the menu or using the context menu (right mouse button). On Windows NT, click the Startup... button to open the Startup Options dialog:

Alternatively, you can specify a different account using the This Account option, but concerning to the eloqsd server this will not make a big difference.

After you have setup the startup options, you can define additional arguments for the eloqsd server as an option. This is usually not required since all settings are normally provided in the eloqsd.cfg configuration file. However, this can be used to track down problems (e.g. starting the eloqsd server temporarily with different log options).

Possible arguments are: 

 -c name    = configuration file
 -d flags   = log flags
 -l name    = log file name
 -s name    = service name (tcp/ip transport)
OptionDescriptionEquiv.*
-c nameSpecifies the configuration file name 
-d flagsSpecifies the server log flags.LogFlags
-l nameSpecifies the server log file.LogFile
-s nameThe service name (as defined in SERVICES) or the port number where the server should listen for requests. The default value is eloqsd.Service

*Equivalent configuration file directive.

For example, if you wish to specify a different TCP service name (the default is "eloqsd"), you could enter the following into the Startup Parameters field: 

  -save -s 8567
which causes the eloqsd server to listen to the TCP port number 8567. The leading -save argument makes this command line persistent so that the same arguments are used each time the eloqsd server is started. If you do not specify the -save argument this command line will be used only once.

If you want to make sure that the command line is empty and that any persistent command line is deleted, just specify -save without any additional arguments.

NOTE: After having entered a command line, use the Start button from within the same dialog, otherwise your command line will not come into effect. In particular, if you use the OK button, the dialog will close without having started the service, i.e. your command line never being applied.

At this point, everything is configured and the eloqsd server can be started:

Select the eloqsd entry in the list, then choose Start either from the menu or using the context menu (right mouse button).

Select the eloqsd entry in the list, then click the Start button.

If you did not specify a log file, the eloqsd server will write log messages to the Windows Event Log. In case the eloqsd does not start the Event Log will probably contain an error message pointing out the cause of the problem. You should also periodically check the Event Log in order to get aware of possible configuration problems:

Windows Server 2003 or XP:

Windows 2000:

Windows NT:

Having started the eloqsd service for the first time after installation, the Application Log should already contain a few entries noting that the eloqsd was successfully installed and started.

Controlling the eloqsd server from the command line

The net start and net stop system commands can be used to start and stop the eloqsd server from the command line. This is equivalent to starting and stopping the server using the Windows Services applet as explained in the previous section.

Command syntax:

net start eloqsd
net stop eloqsd

The eloqsd HTTP status display

When ServiceHttp is defined in the eloqsd.cfg configuration file, you can use a web browser such as Mozilla, Netscape or Internet Explorer to view the configuration and state of the eloqsd process in your network.

To access the eloqsd server, you provide an URL like this:

http://server:port/
where server is the host name or IP address of the system running the eloqsd server and port is the port number used for ServiceHttp in the eloqsd.cfg file.

Eloquence Installation and Configuration - 29 OCT 2004