Easysoft ODBC-ODBC Bridge User's Guide - Configuration

Configuring the Easysoft ODBC-ODBC Bridge

This section explains the configuration options available for the Easysoft ODBC-ODBC Bridge (OOB) Server. The configuration for Unix subsection also covers how the OOB Server for Unix can be run as a standalone server process without {x}inetd.

Chapter Guide

The Web Administrator

There are a number of configurable parameters for the OOB Server, irrespective of platform. There are platform-specific ways to change these settings, but the OOB Server also provides a simple HTTP server, known as the Web Administrator, that provides a web-browser based interface to use for updating these parameters.

The Web Administrator is available in the OOB Server for Windows and in the OOB Server for Unix when run as a standalone server process without {x}inetd (see Configuring the Server as Standalone for details).

This section describes the Web Administrator and shows you how to change the server configurable parameters.

In order to run the Web Administrator you will need:

In order to make changes in the Web Administrator you will need:

(Note that it's also possible to configure the Web Administrator so that an HTTPAdmin user name and password need to be supplied before any Web Administrator page can be accessed. For more information, see HTTPAuthAll.)


NB

To obtain the HTTPAdmin user name that was entered for your OOB Server when it was installed (HTTP authentication will have been disabled if this field was left blank) display the HTTPAdmin setting on the Configuration screen (see HTTPAdmin). This setting is hidden by default, but may be reset. The HTTPAdmin user name and password are required in order to make changes through the Web Administrator. If this value is not a valid user on the server system, then you must change it. The value is case sensitive.

HTTPAdmin is a registry setting on Windows. If you forget the HTTPAdmin user name or it is invalid, you cannot change it in the Web Administrator and will need to edit the registry. For information about the registry key where Web Administrator settings are stored, see OOB Configuration Parameters in the Registry.


Start the Web Administrator by opening the URL http://oobhost:8890/ from a web browser (substituting your machine name in place of oobhost and the required port address if you have specified a port other than the Easysoft default of 8890).


NB

To obtain the port number for the Web Administrator you need to refer to the HTTPPort setting on the Configuration screen (see HTTPPort).


If HTTPAdmin is set to anything other than "disabled" then some pages in the Web Administrator are protected with HTTP authentication.

If you click on a link to a protected page you will be prompted for the HTTPAdmin user name and password by your browser for the ESOOBServer realm:

Figure 43: The Enter Network Password dialog box

The web page returned is generated by the server process and displays runtime statistics for the latest run of the server:

Figure 44: The Statistics screen of the Web Administrator

The following additional screens can be accessed from the Statistics screen:

 Client Hosts displays details of client machines which have connected to the OOB Server.

The Statistics and Data Sources screens display information, whilst the Configuration and Security screens allow you to modify the server's runtime parameters.

The Configuration Screen

Figure 45: The Configuration screen of the Web Administrator

This section explains the parameters that are configurable via the Web Administrator Configuration screen. These parameters apply either to the OOB Server itself, or as a default value for all DSNs accessed via the server.

These settings, and some additional settings, can also be edited via the registry in Windows (see OOB Configuration Parameters in the Registry) or in a file in Unix (see Changing Server Configurable Parameters under Unix).

Note that enabling the HideSensitive attribute will result in some sensitive settings not being displayed (see HideSensitive).

You can modify the server settings by clicking Change and then typing the HTTP Admin user name and password when prompted. This is the user name that you entered during the installation process and the password for that user on the system where the OOB Server is running.


NB

You are only asked for this if the HTTP authentication has been enabled by the HTTP Admin user name being previously entered as something other than "disabled".


Keys are not case-dependent, so for example Port, PORT and pOrT are treated as the same key. Values are case-dependent if the operating-system is, so it is best to match case where possible.

The Configuration screen contains the following fields (click Submit to make your changes):

Parameter Description
Port The port where the OOB server is listening for incoming OOB client connections. The OOB server will need restarting for the changes to take effect.
IPAddress The IP address the OOB Server listens on. This is only relevant if you have multiple NICs and only want the OOB server to listen on one. The default is for the server to bind to port 8888 on INADDR_ANY which means it is listening on all local interfaces.
HTTPPort The port on which the OOB Server will listen for HTTP requests. The default is port 8890 but it may be any port not in use on your machine. On Unix, if the Flags configurable option HTTP_SERVER attribute is set (see HTTP_Server) then the OOB Server will listen on the specified port for HTTP requests as well as acting in its normal role serving the OOB Client. On Windows, the Web Administrator is a separate service that is started automatically by the Windows Service Manager. The Web Administrator listens on the specified port for HTTP requests. You may use the URL http://machine_name:HTTPPort where machine_name is the name (or IP address) of the machine running the OOB Server and HTTPPort is the port number to communicate with the OOB Server from your browser. It can show statistics, DSNs and the current values of configurable parameters. On Windows, the Web Administrator needs to be restarted in Service Manager for the new port to take effect.
Timeout The inactivity timeout in seconds (the default is 7200 - 2 hours). Currently, this option is only applicable to the Windows OOB Server. The OOB Server starts a new thread (or process) for each client that connects. If there has been no communication in Timeout seconds the thread or process exits. This causes the client to be disconnected. To disable timeouts, set this field to 0. Disable this field if using persistent connections from PHP/mod_perl etc.
RetryCount The number of additional attempts (after the first attempt fails) the server will make to get a resource. The resources influenced by this are thread/process creation and license slots for new connections.
RetryPause The time in seconds between each retry attempt (see RetryCount).
HTTPAdmin The username of the person allowed to make changes to the OOB server via the Web Administrator. This must be a valid username in the operating system the server is running on. If set to the string "disabled" (omit the quotes) then HTTP authentication is not required (this does not mean the OOB Server stops authenticating incoming ODBC connections). The "eye" symbol
displayed against the HTTPAdmin parameter denotes that the value of the field is only visible to the user via the Change Configuration screen, which may require the entry of a user name and password.
KeyFIle The path to the file containing the private key for the certificate specified with CertFile. You need to restart the OOB server before this setting takes effect.
CertFile The path to the file containing the certificate used to secure the connection between OOB client and server. For example, /home/myuser.cert.pem. You need to restart the OOB server before this setting takes effect.
HTTPNetWorkAccess The network or IP address for clients allowed to use the Web Administrator. For example 194.131.236.4 only allows one machine but if the netmask was 255.255.255.0 then setting 194.131.236 would allow anyone on that network. The default is all browser clients have access to the Web Administrator although they may be required to enter a username/password if HTTPAdmin is set to anything other than "disabled".
MaxBookMarkSize The size of the largest bookmark the OOB can handle (it defaults to 32 bytes). ODBC 2.0 uses fixed length bookmarks of 4 bytes. In ODBC 3.0 bookmarks are all variable in size. If you find an ODBC driver that needs more than 32 bytes for a bookmark please contact support@easysoft.com, otherwise the default should be fine.
Path The installation path of the Easysoft ODBC-ODBC Bridge. This is a read-only parameter for information only.
Logging A bitmask specifying the events to be logged by the OOB Server. Logging slows the Easysoft ODBC-ODBC Bridge down considerably and should only be set as directed by Easysoft support. The number may be specified as decimal (e.g. in the format 2047)or hexadecimal (e.g. in the format 0x7ff).
LogDir The directory where log and audit files are created (see Logging and AuditODBCAccess). It defaults to drive:\Program Files\Easysoft\Easysoft ODBC-ODBC Bridge\Logs\ in Windows and /tmp in UNIX. This is also the directory where the OOB Server might write an esoob.exception file if an unhandled exception is caught.
MaxThreadCount The maximum number of concurrent connections from a single client. If MaxThreadCount is set to 0, there is no limit. The default is 0. You can use this parameter to prevent people from swamping your machine with ODBC connections.
MaxClientConnect The maximum number of concurrent connections from a single client (where a client is defined as the IP address of the machine where the client is running). If MaxClientConnect is set to 0, there is no limit. The default is 0. You can use this parameter to prevent people from swamping your machine with ODBC connections.
NetRCVLOWAT The size of the receive low-water mark in bytes. Possible values are: 0, do not set it at all, leave at system default. -1, set to internal OOB default (the default setting) n (n > 0), set to this value
NetRCVBUF The size of the receive queue buffer for the socket in bytes. Possible values are: 0, do not set it at all, leave at system default. -1, set to internal OOB default (the default setting, which is 16K) n (n > 0), set to this value
NetSNDBUF The size of the send queue buffer in bytes. Possible values are: 0, do not set it at all, leave at system default. -1, set to internal OOB default (the default, which is 16K) n (n > 0), set to this value
NetConnectRetryCount (Deprecated) The number of times the OOB client will attempt a connection to an OOB Server. Each time a connection attempt fails the OOB client waits (0.1 * connect attempt) seconds before trying again. Possible values are: 1, set to internal OOB default (the default, which is 5) n (n >= 0), set to this value If you're using multiple server definitions in a single DSN you may find lowering this setting from the default of 5 an advantage as it reduces the time from the client failing to connect to the first server and starting a connection attempt to the second and subsequent servers.
ListenBacklog Defines the maximum length the queue of pending connections may grow to. It is a value passed to the BSD sockets call listen(). If a connection request arrives with the queue full the client will probably get an error of ECONNREFUSED and the OOB Server will be totally unaware of the connection attempt. If this happens the OOB client will use ConnectAttempts to make multiple connection attempts. Possible values are: 1 <= n <= 100 (the default is 20) You should not usually need to change this value as the default is sufficient for all but the very busiest of OOB Servers and having to set a high value is an indication that the server machine is underpowered. In addition, on Windows operating systems, the backlog queue is in non-pageable system memory. For some versions of the Windows operating system (NT workstation) changing this value has no effect since it is hard-wired at 5. For more information about the ConnectAttempts setting, see Connection Attempts. For more information about the listen backlog queue, see the OOB FAQ.
Affinity If the OOB Server is running on a multiple CPU Windows Server machine you will see a check box for each CPU (labelled CPU_0 to CPU_N). The OOB Server holds the Affinity value as a mask of processors in your machine which the OOB Server can run on. Initially, the affinity value is 0 which means the OOB Server will make no changes at all and the Web Administrator will show all CPUs as available. However, if you make any changes to the CPU check boxes the OOB Server will call SetProcessAffinityMask which will define which processors the threads in the OOB Server are allowed to run on. In this way you can bind the OOB Server to particular CPUs in your machine.
Flags A bitmask of operational flags, split into check boxes, one for each bit in Flags.

The following table lists and describes each Flags setting. If you're changing the Flags setting by editing oobserver.ini on Unix rather than by using the Web Administrator, use the hexadecimal value instead of the flag name. To set multiple flags, add the hexadecimal values for the flags you want

Name Hex
Value
Description
Authentication_Disabled 0x1 If set then authentication is disabled in the OOB Server. The default is off. Although setting this parameter should be considered as a security risk, on some high hit servers in a controlled environment where you do not need to authenticate the connections this can save a considerable amount of time during connections (e.g. Windows NT can use between 0.25 and 0.75 seconds of the connection time for authentication)
HTTP_Server 0x2 If set then the Web Administrator is made available as soon as the Unix OOB Server is started. The default is on. This option is not applicable to the Windows OOB server. On Windows, the Web Administrator is a service that is started automatically by the Windows Service Manager.
MultiProcess 0x4 If set then the OOB Server starts a new process for each incoming connection, rather than a new thread. The default is off, so the OOB Server starts a new thread for each connection. Enable MultiProcess if an ODBC driver which is not thread-safe is being used or if your ODBC driver leaks memory. Currently on non-Windows platforms the server always starts new processes as it is NOT multi-threaded and so this flag cannot be changed.
MetaDataBlockFetch_Disabled (Deprecated) 0x8 If set prevents the OOB client from automatically starting block-fetch-mode for read-only metadata result-sets. The default is off.
HideSensitive 0x10 If set causes the Web Administrator to hide sensitive parameters on the Configuration screen. Currently the parameters removed when HideSensitive is set are HTTPAdmin (see HTTPAdmin) and Authentication_Disabled (see Authentication_Disabled). All parameters are always shown in full on the password protected Change Configurable screen. The default is on.
ReverseLookup 0x20 If set causes the OOB Server to call gethostbyaddr() on the connecting client's IP address to obtain the client's machine name. On machines where DNS is not set up properly this can cause problems and in any case adds time to the connection. ReverseLookup currently only affects the statistics, number of different clients page where "unknown" will be displayed instead of the machine name for connecting client's machine names if ReverseLookup is off. The default is off.
AuditODBCAccess 0x40 If set the OOB Server audits all ODBC connections to a log file (named esoob_access.log in the LogDir directory) which may be viewed through the Web Administrator. The default is off.
FreeStmtsOnDisconnect 0x80 If set then the OOB Server frees all existing statements in the driver before calling SQLDisconnect. By default this flag is off as this function should be executed by the ODBC driver, rather than the application, as detailed in the ODBC specification. Setting this flag fixes a potential crash in Navision's ODBC driver if SQLDisconnect is called from Perl when there are existing statements.
ShowProcessTime 0x100 If set the OOB Server retrieves the user and kernel CPU times for the main OOB Server process and displays them on the Statistics screen. The values are only updated once every five seconds. The default is on.
AutoUpdateConfiguration (Deprecated) 0x200 If set the OOB Server automatically updates its internal copy of the configuration settings from the registry when five seconds elapse without an incoming connection. Disabling this feature reduces the number of accesses to the registry, but means that the server has to be restarted to pick up configuration changes. The default is off.
HTTPAuthAll 0x400 If set then all pages in the Web Administrator are protected by HTTP authentication and you will be prompted for the HTTPAdmin username and password before any pages are returned to you (the realm is "ESOOBServer"). Note that setting HTTPAuthAll has no effect if HTTPAdmin is to "disabled".
ConnectionPooling 0x800 If set then the OOB Server automatically sets the SQL_ATTR_CONNECTION_POOLING attribute to SQL_CP_ONE_PER_DRIVER to enable connection pooling in the driver manager for the ODBC driver. Note that ConnectionPooling is meaningless when the OOB Server is running in MultiProcess mode (see MultiProcess).
LogFailingSQL 0x1000 If set then when any call to SQLPrepare/SQLExecDirect fails the SQL is logged to the file oob_sql.log in the LogDir. As some DBMS only parse the SQL at SQLExecute time sometimes you do not find out the SQL is incorrect until SQLExecute is called. To catch these SQL errors too the OOB Server saves the first 1K of any SQL passing SQLPrepare successfully so it may be logged if SQLExecute fails. For this reason turning this flag on will have some impact on the speed of the server and memory use. This is extremely useful when developing applications or web services and can be used to monitor errors. The default is off.
AllowDBBrowse 0x2000 If set the data sources listed on the Data Sources screen may be browsed to get lists of tables, columns in tables and rows of table data. The default is off.
AutoDenyNonOOBClients 0x4000 If set then any clients connecting to the OOB Server port and sending initial data down the socket which is not the EasyRPC protocol will be added to the internal denied ACL. Clients automatically added in this way are not visible on the security page and are removed from the ACL when the OOB Server is restarted or when the ACLs are changed on the security page. The default is off.
AllowDSNBrowse 0x8000 If AllowDSNBrowse is not enabled then OOB Clients cannot obtain a list of SYSTEM DSNs from the OOB Server. This affects the ODBC API function SQLBrowseConnect() and the population of the TargetDSN dropdown in the OOB Client Setup dialogue. The default is on.
NoStatusArrayResize 0x10000 This is a workaround for an issue in the SQL Server ODBC driver, which can write off the end of the parameter status array (SQL_ATTR_PARAM_STATUS_PTR) when the SQL_ATTR_PARAMSET_SIZE is reduced. For details about when this issue can happen, see the OOB FAQ "Why do I get an Access Violation in MS SQL Server ODBC Driver?". The default is off.
WriteStatsOnExit 0x20000 If set, the contents of the Statistics screen are written to file when the OOB Server service (on Windows) or the Standalone process (Unix) exits. For more information, see Termination statistics. The default is off.
.

Figure 46: The Change Configuration screen of the Web Administrator


64-bit Windows

The OOB Server parameters in the Configuration screen apply to both the 32-bit and 64-bit OOB Server, apart from Port. The Port setting defines the port on which the 32-bit OOB Server listens for incoming client connections. If you change the Port value, the 32-bit OOB Server will listen on the new Port; the 64-bit Server will continue to listen on the default port, 8888. (When the 32-bit and 64-bit OOB Servers are listening on different ports, it is possible for both Servers to run at the same time.)

If you do not want the 64-bit OOB Server to listen on the default port, you need to change the value of this Registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Easysoft ODBC-ODBC Bridge\Configuration\System\Settings\Port64


Support for multiple network interface cards

By default, the OOB Server will start to listen on port 8888 on all network interfaces, but if the server has network interface cards (NICs) on multiple networks the OOB Server can be associated with a particular NIC by specifying an IP address.

This will be necessary if the server is running on multiple networks and access to the OOB Server is only required from one network.

The IPAddress configurable parameter on the Web Administrator Configuration page is usually an empty field, signifying that the OOB Server is listening on all local interfaces.

Change this field to the IP address of a particular NIC to restrict access to a particular network.

Specific support for multiple processors (Process Affinity)

On multiple processor Windows machines, you can allocate particular processors on which to run the OOB Server. This is known as process affinity.

If your server has multiple CPUs then the Web Administrator Configuration screen will show each configured processor as CPU_n (where n is a number between zero and the number of configured processors minus one).

Initially, the OOB Server starts with its process affinity set to the default (available to run on all processors). However, unchecking the CPU_n check boxes on the change configuration page changes the OOB Server affinity so that it is restricted to a subset of the configured processors.

Note that the OOB Server only sets process affinity when starting up, so any changes made will only affect the server after it has been restarted.

Connection Pooling

Automatic connection pooling in the OOB Server process may be enabled from the Web Administrator Configuration page (see ConnectionPooling).

If connection pooling is enabled then the OOB Server sets the SQL_ATTR_CONNECTION_POOLING attribute to SQL_CP_ONE_PER_DRIVER to enable connection pooling in the driver manager for the ODBC driver.

If connection pooling is enabled then connections through the ODBC driver to the database are held open by the driver manager for use the next time the application uses the same DSN.

This is only of any real benefit if the OOB Server is running in multi-threaded mode (the default), as the pooled connections are per process.

Enabling connection pooling in the OOB Server can vastly reduce connection times, especially through ODBC drivers connecting to remote databases.

Exporting Server Configurations

OOB Server configuration is stored in the registry (in Windows) or in a plain text file (on Unix systems).

It is simple to safeguard this configuration or copy it to another OOB Server on Unix, but normally more difficult on Windows.

In Windows, at the bottom of the Configuration screen in the Web Administrator there is an Export button.

Clicking Export writes the entire OOB Server configuration out to the file LogDir\oob.reg where LogDir is an OOB Server configurable parameter defined on the Configuration screen.

This file is in RegEdit 4 format, so it can be copied to other servers where double-clicking on it will install that OOB Server configuration into the registry.

The Security Screen

The Web Administrator Security screen displays and allows the user to change the set of hosts that are allowed to connect to the OOB Server.

If they have not already been entered, you are then prompted for the HTTPAdmin user name and password before the Security screen is displayed:

Figure 47: The Security screen of the Web Administrator

In addition to the user names and passwords of your system and of the database management system, the Easysoft ODBC-ODBC Bridge provides another layer of security by using access control lists.

To add an IP address to a list, type the address into either the Allowed Access or Denied Access boxes and click Add.

Unix administrators will recognize this mechanism from the hosts.allow and hosts.deny files.


NB

Though the approach is similar, the rules for determining whether or not a host should be allowed to connect are different from those for hosts.allow and hosts.deny.

Please read the rest of this section for more information.


Easysoft ODBC-ODBC Bridge Security takes the form of two lists of IP addresses.

When a host attempts to connect to the OOB Server, access is only granted if:

The lists can be edited via the Web Administrator (Windows and Unix when run standalone), their relevant flat files (Unix), or the registry (Windows),

List entries must consist of full dotted quad notation IP addresses. For example, 194.131.236.4. Entries may be followed by an optional "/" and a network mask. For example, 192.168.5.0/255.255.255.0 specifies the private class C address 192.168.5. You can use the address/mask notation to specify any network address. If you omit the network mask it defaults to 255.255.255.255 i.e. an exact match for the specified IP address.

To delete a list entry, click the entry you want to delete.

If you have just installed the OOB Server and selected the "initially secure" option then the "Denied Access" column will contain 0.0.0.0/0.0.0.0 (which denies everyone access to the OOB Server).

Access Control Per DSN

The Easysoft ODBC-ODBC Bridge provides these methods of controlling access to data sources:

The DSN Access Control section of the Security screen provides the additional facility to build access control lists to give you even more control over specific data sources.

With DSN access control lists you can define exactly which machines and users access which DSNs.

Figure 48: The Web Administrator Access Control table

The DSN Allowed Access list and Denied Access list define the hosts and users which may access a particular DSN.

The server consults the Deny Access list first, and access is denied if a client address/user name matches an entry in this list.

If there is no match for the client/user name in the Denied Access list then the Server consults the Allowed Access list, and if the Allowed Access list is empty the client/user is allowed access.

If there are any entries in the Allowed Access list then the client/user is only allowed access if it matches an entry in this list.

The entries in either list must consist of either IP addresses or user names. IP addresses must be full dotted quad notation. For example, 194.131.236.4. Entries may be followed by an optional "/" and a network mask. For example, 192.168.5.0/255.255.255.0 specifies the private class C address 192.168.5. You can use the address/mask notation to specify any network address. If you omit the network mask it defaults to 255.255.255.255 i.e. an exact match for the specified IP address.

Any user name added to either list must match the LogonUser attribute used by the OOB Client to log the OOB Server thread/process into that account before allowing access to a DSN.


NB

As a special case (to avoid having to name every user when adding an IP address to the DSN allow list) the deny list is checked for the current user, and allows access to the DSN if no matching entry is found.


Securing the Web Administrator from clients outside your network

The HTTPNetworkAccess configurable parameter can be used to restrict access to the Web Administrator by setting it to the network or IP address of clients that are to be allowed access.

The IP address may be followed by an optional "/" and a network mask. For example, 194.131.236.4 only allows one machine to access the Web Administrator. 194.131.236/255.255.255.0 allows anyone on that network.

Browser clients not permitted access will receive an "HTTP 403 Forbidden" error. By default, all browser clients have access to the Web Administrator, although they may be required to enter a user name/password if HTTPAdmin is set to anything other than "disabled".

Preventing data sources being browsed in the administrator

The Easysoft ODBC-ODBC Bridge is not only capable of displaying a list of system data sources, but can also allow those data sources to be browsed (see Viewing data sources, tables, columns and data).

This is a powerful, but potentially dangerous feature, as anyone with a browser and access to the Web Administrator might be able to see data in your database.

Although you can protect all of the Web Administrator pages with HTTP authentication, the AllowDBBrowse parameter allows the user to define a more precise configuration.

By default AllowDBBrowse is not set, which means that data sources shown on the Data Sources page are listed but not browsable. If AllowDBBrowse is turned on then the data sources become hyper links allowing you to browse down through the DSNs, tables, columns and data.

Configuring the OOB Server under Windows

The OOB Server under Windows is installed as a service, configured to be started automatically by the Windows Service Manager when the machine boots.

A Services entry is also added to the Windows Easysoft ODBC-ODBC Bridge menu.


NB

The OOB Server writes status, diagnostic, and security information to the Windows application event log. To examine this information, use Event Viewer to view the application event log. For more information, see Event Logging On Windows.


The OOB Server runs with administrative privileges, allowing it to become the user specified in the client DSN.

When a user connects, the OOB Server becomes the user specified in the LogonUser attribute so that it acts with the specified user's permissions.

You can configure the service like any other service. For instance, you can set it up not to start automatically on system boot.

You can also explicitly stop the service, as follows:

Choose:

1.  Open Administrative Tools in Control Panel.

2.  Open Services.

The Service Manager displays a list of services, along with their status and their startup configuration.

To Start or Stop the Service in Windows

1.  In the Services dialog box, ensure that the Easysoft ODBC-ODBC Bridge Server entry is selected.

2.  If the service does not have Started recorded in the Status column, you can click Start to run the service.

¯ OR ¯

If the service has Started recorded in the Status column, you can click Stop to stop the service. Click Yes if the Service Manager asks you to confirm your action.


64-bit Windows

By default, only the 32-bit OOB Server is started automatically. (With the default configuration settings, both 32-bit and 64-bit OOB servers listening for incoming client connections on port 8888, it is not possible for both servers to run at the same time.) If you want to use the 64-bit OOB Server, you need to:

Stop the 32-bit OOB Server service (Easysoft ODBC-ODBC Bridge Server).

Start the 64-bit OOB Server service (Easysoft ODBC-ODBC Bridge Server x64).

To configure the 64-bit OOB Server service to start automatically when Windows starts:

1. In the Windows Services dialog box, double-click Easysoft ODBC-ODBC Bridge Server.

2. In the Easysoft ODBC-ODBC Bridge Server Properties dialog box, click Stop. In the Startup type list, choose Manual.

The 32-bit OOB Server service is no longer running and will not start when Windows starts.

3. In the Windows Services dialog box, double-click Easysoft ODBC-ODBC Bridge Server x64.

4. In the Easysoft ODBC-ODBC Bridge Server Properties x64 dialog box, click Start. In the Startup type list, choose Automatic.

The 64-bit OOB Server service is now running and will start when Windows starts.


To Configure Automatic/Manual/Disabled status

When installed, the Easysoft ODBC-ODBC Bridge Server is configured to run automatically when Windows starts. Windows offers two other options for services.

The Manual startup mode dictates that the service should start only when a user explicitly runs the service.

If you need to stop the service, for example if you need to restructure your data sources or you have a security policy stating that services should not be available outside allotted times. Windows provides the Disabled state for this.

1.  In the Services dialog box, double-click the Easysoft ODBC-ODBC Bridge Server entry.

2.  In the Service configuration dialog box, in the Startup Type section, choose the relevant option:

¯ OR ¯

¯ OR ¯

3.  Click OK to close the dialog box.

To Set Up Recovery Actions For The OOB Server

If you are running the OOB Server as a service in multi-threaded mode (the default) and an exception is caught by the OOB Server it will shut itself down. The reason for this is that the exception could have occurred anywhere (most commonly, the ODBC driver you are using) and there is no way for the OOB Server to correct the problem and no way for it to protect the other threads in the service.

On later versions of Windows it is possible to set the service manager to monitor services and restart them for you after a specified time:

1.  In the Services dialog box, double-click the Easysoft ODBC-ODBC Bridge Server entry.

2.  In the Service configuration dialog box, click the Recovery tab.

3.  Click the recovery action you want in First failure, Second failure, and Subsequent failures.

User Accounts and the Server

Windows distinguishes two types of service with respect to their privileges:

The OOB Server is designed to be run in the System Account. As soon as a client connects, authentication takes place using the LogonUser and LogonAuth attributes. The server calls the LogonUser() and ImpersonateLoggedOnUser() Windows APIs, so that all subsequent actions are attempted with only the privileges of LogonUser.

This is the default configuration of the OOB Server. The other option is to set up the server to always run with a specific user's permissions. This is not recommended, but if you do want to do this, the procedure is as follows.


Caution!

Running the OOB Server under a named account for added security is counterproductive because you open up security holes by doing this. Firstly, anyone with the OOB client can now connect to your data and secondly, to administer the OOB Server via HTTP you will have to disable HTTP authentication. Disabling HTTP authentication means anyone can change the OOB Server settings.

Easysoft recommend you run the OOB Server in the System Account.


1.  Go into the OOB Web Administrator and disable authentication.

2.  In the OOB Web Administrator, disable HTTP authentication by setting HTTPAdmin to "disabled" (omit the quotes).

3.  Be sure that the user account you wish to use is set up and that you know its password. It may be an existing end-user's account, or one created specifically for the OOB Server.


Caution!

For the OOB Server to function correctly when running as a specific user, that user needs two important access rights:Log On as a Service, which is needed for the service to start, and Act as Part of Operating System, which is needed so that the service can authenticate connecting users for the OOB Server and for the Web Administrator.


4.  In the Services dialog box, double-click the Easysoft ODBC-ODBC Bridge Server entry to open the Service configuration dialog box.

5.  In the Log On tab, in the Log On As section, select This Account.

6.  In the This Account text box, type the user name or click ... to browse for a user name.

7.  In the Password box, type the user account password.

8.  Type the same password in the Confirm Password box.

9.  Click OK to close the dialog box and commit your changes.

You may have noticed the Allow Service to Interact With Desktop checkbox. This has no effect on the OOB Server.

OOB Configuration Parameters in the Registry

OOB and Web Administrator configuration settings are stored in the registry. The settings are saved under this registry key:

\HKEY_LOCAL_MACHINE\SOFTWARE\Easysoft ODBC-ODBC Bridge\Configuration\System\Settings.

The Configuration Screen describes the available configuration settings.


64-bit Windows

OOB and Web Administrator configuration settings are saved under this registry key:

\HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Easysoft ODBC-ODBC Bridge\Configuration\System\Settings


Configuring the OOB Server under Unix

On Unix systems, the OOB Server is by default installed as a service under inetd, but it may be configured in its standalone mode.

When the OOB Server is installed as an inetd-controlled service, entries are added to the inetd.conf and services files. Examples of these entries might be

esoobserver stream tcp nowait root /bin/sh /bin/sh /usr/local/easysoft/oob/server/server

esoobserver 8888/tcp # Easysoft OOB Server

These are just examples and may differ if you picked a different port, service name or installation path.

The mechanics of inetd and the server

inetd handles incoming network connections and starts the relevant program to service each incoming request.

When inetd starts (or is sent a SIGHUP), it reads /etc/inetd.conf for a list of what services to supply and to configure its handler for each service.

It then starts listening on the ports defined in /etc/services for each service configured in inetd.conf.

When a new connection is made, inetd starts the relevant program and hands over control.

The following example applies to the default installation: when a client connects to port 8888, inetd uses the information read from /etc/inetd.conf to decide which program to run and with what arguments.


NB

Note that /bin/sh is repeated. The first time it appears (in the sixth position on the line) it is the name of the executable to run. The second time it appears it is the value to be passed as the zeroeth argument to /bin/sh. Normally this is the same as the name of the executable.


In the default installation, the arguments on the line cause /bin/sh to run the OOB Server startup script <InstallDir>/easysoft/oob/server/server.

The script then sets any necessary environment variables required by the dynamic linker and runs esoobserver.

The script passes an argument of inetd to the server executable, which notifies the server that it is running under inetd rather than at the command line.

The OOB Server inherits the socket from inetd and begins communicating with the OOB Client. inetd returns to listening on port 8888 for any new connections.


NB

The Web Administrator feature of the OOB Server does not run when the OOB Server is configured under inetd, because esoobserver itself is not run until an OOB Client connects.


Choosing another Port or Service Name

If you have a port conflict or a service name conflict, or for some other reason you want to change the port or service name of the OOB Server, then you will need to edit the configuration files manually.

The /etc/services file maps service names to ports. The /etc/inetd.conf file lists the services that inetd will handle requests for.

After making the necessary amendments you will have to send SIGHUP to the inetd process to make it re-read the files. This can be achieved with the command:

kill -HUP pid

where pid is the process ID of inetd. You need to be root to edit the configuration files and send inetd a SIGHUP.

Configuring the Server as Standalone

By default, on Unix the OOB Server is installed as a service with entries in the /etc/services and /etc/inetd.conf files (inetd is informed of the configuration file changes).

However, the OOB Server will also run standalone. When run as standalone, the OOB Server is faster at accepting connections than the inetd started server. So if you are making a lot of small connections to the OOB Server, starting it standalone (without inetd) is preferable. Also, the Web Administrator is only available when the OOB Server is running standalone.

Note that the OOB Server no longer uses inetd to listen on the socket when running as standalone, so you cannot run tcp wrappers. You can use the facilities within the Easysoft ODBC-ODBC Bridge to set up access control.

To start the OOB Server in standalone mode:

1.  Comment out the esoobserver entry in the /etc/services file.

2.  Force inetd to re-read the files using:

 kill -HUP inetd

3.  Start the server with:

 path/esoobserver standalone

This notifies the server that it must listen on the port itself and fork its own child process when a connection is made (the OOB Server reads the port and httpport settings in path/oobserver.ini for its configuration).


NB

You should start the OOB Server as the root user otherwise it will be unable to change to the LogonUser specified in the OOB Client data source. However, if you do not start the OOB Server as root then no logon authentication will be performed and all clients will run on the server as the user who started the OOB Server.


You could add a line to one of your rc scripts to have the OOB Server start up as standalone every time the machine boots.

The file you need to edit depends on your operating system so consult your system administrator for further information.

When the OOB Server is started standalone, by default it will fork a process to handle HTTP requests on port 8890 (you can change this in esoobserver.ini).

You can then use your browser to go to the Web Administrator (see The Web Administrator).

The HTTPAdmin configuration parameter controls whether you're prompted for a password before making changes in the Web Administrator. The default value for HTTPAdmin is "disabled" which means that you're not prompted before accessing Web Administrator pages that let you change configuration settings. If you do want to control access to these Web Administrator pages, edit the HTTPAdmin value. Specify a user name that exists on the server the OOB server is running on. If you do want to do this, the OOB Server must be running as root on some machines to validate the user name and password. For more information, see HTTPAdmin.

Changing Server Configurable Parameters under Unix

If you're running the standalone OOB Server you can use the Web Administrator to examine and change OOB configuration settings. If your OOB server runs under inetd or you prefer a configuration file to a web-based interface, you'll need to edit the following file to configure the OOB:

<InstallPath>/easysoft/oob/server/esoobserver.ini.

If <InstallPath> is anything other than /usr/local/ then there will be a symbolic link /usr/local/easysoft to the real easysoft directory.

esoobserver.ini entries have the following format:

{Settings}

attribute = value

The Configuration Screen describes the available configuration settings.

Note that the bitmask values are given either in decimal or in hexadecimal and the access control lists are separated simply by spaces.

Set Flags by entering the sum of the corresponding bitmask values of your required options.


Oracle is a registered trademark of Oracle Corporation and/or its affiliates.