UNIX: Objectivity/DB Configuration

Printer-friendly version

As the foundation of the Objectivity product set, Objectivity/DB provides:

  • Tools for database administration and data inspection.
  • Servers for managing concurrency and accessing remote files.
  • Runtime libraries containing the Objectivity/DB kernel, which is used by the tools and servers, and by the database applications you develop.

To configure Objectivity/DB, refer to the following:

Setting Permissions

All Objectivity/DB users need both read and execute permission to installDir.

Setting Environment Variables

Each application developer should:

  • Add installDir/bin to the PATH environment variable.
  • Add installDir/lib as the first component of the LD_LIBRARY_PATH environment variable (required for running Objectivity/DB tools).

Note: As a convenience, the installer creates a setup script (installDir/setup.sh) that contains commands for temporarily setting up environment variables in a shell.

About Objectivity Servers

The following servers are provided with Objectivity/DB:

  • The lock server, which manages concurrent access to persistent objects in one or more federated databases. The lock server must be running in order to use Objectivity/DB.
  • The Advanced Multithreaded Server (AMS), which allows remote database applications to access to local data files and journal files in a distributed Objectivity/DB system.
  • The query server, which executes the subtasks of a parallel query or a navigation query initiated from within an Objectivity/DB database application.

For more information about these servers, refer to Objectivity/DB Administration.

Setting Up the Lock Server

Objectivity/DB uses a system process called a lock server to manage concurrent access to persistent objects in one or more federated databases. The lock server must be running in order to use Objectivity/DB.

Important: For security purposes, consider running the lock server under a special-purpose user account in a group that can be granted just the minimum necessary permissions. See "Using a Lock Server" in Objectivity/DB Administration for more information.

Note: You can run the lock server on one or more hosts. If you want to run the lock server on a workstation that does not contain the Objectivity/DB installation, you can run the installer in Custom mode to install just the servers you want.

The installation and setup of the lock server varies by platform.

Linux Platforms

A default Full or Typical installation as root installs the lock server as a Linux init.d service that is enabled at runlevel 3 and runlevel 5. The lock server is started, and will restart when the workstation reboots. To modify these settings, refer to the documentation for your Linux platform.

The lock server service is named ools-13 and uses TCP/IP port 6780 by default.

Verify that the lock server is running. If it is not, check whether another process is already running on the port that the server expected to use. If so, you should try to reassign that other service to a different port. If you cannot do this, you may have to change the default port for the Objectivity server, see "Using a Lock Server" in Objectivity/DB Administration.

Note: If you change the port number for an Objectivity server, you must make this change on every host that is to run a process that uses the server.

Other UNIX Platforms

With a default Full or Typical installation as root, the lock server is installed, but is not started nor is it set up to start when the system reboots.

To set up the lock server:

  1. Set up a log directory for lock-server log files. Follow the steps in Setting Up a Log Directory for the Lock Server.
  2. Start the lock server to verify that it is installed properly. To start the lock server under the user account userName, enter a command such as:
    su - userName -c "installDir/bin/oolockserver"
  3. If the lock server does not start, check whether another service already uses the TCP/IP port that the lock server expected to use.

    The lock server will not start if another service already uses the TCP/IP port that the lock server expected to use. If you cannot reassign the other service to a different port, you may have to change the default port for the lock server. To do this, see "Using a Lock Server" in Objectivity/DB Administration.

  4. (Optional) Configure your workstation to start the lock server whenever the machine reboots. To do this, edit the workstation’s startup script (usually /etc/rc.local or /etc/init.d) and add a command such as the one in step 2.

See "Automatic and Manual Recovery" in Objectivity/DB Administration for information about entering a command to start the lock server upon reboot with automatic recovery enabled.

Setting Up a Log Directory for the Lock Server

A running lock server creates log files in a log directory. By default, the lock server expects to write log files in the default log directory, which is /usr/spool/objy.

Note: If you run the lock server and AMS on the same host, they will both use the same log directory.

The setup for a log directory varies by platform.

Linux Platforms

By default, a running lock server creates log files in /usr/spool/objy and no setup is required.

To use a different location, refer to Changing the Log Directory for the Lock Server.

Other UNIX Platforms

Perform the following steps to set up the default log directory:

  1. Log in as root.
  2. Create the /usr/spool/objy log directory.
  3. Set the log directory’s permissions to enable the lock server to create and update files in this directory, and to enable all users to read and write files there. Enter:
    chmod 777 objy  

To use a different location, refer to Changing the Log Directory for the Lock Server.

Changing the Log Directory for the Lock Server

To use a nondefault log directory:

  1. Create the directory with the appropriate permissions.
  2. Set the environment variable OO_SERVER_LOG_DIR to the directory pathname before you start the lock server.

If you are configuring your workstation to restart the lock server on reboot, this environment variable must be set before the lock server is restarted. You can edit a startup file (such as .login ) for the userName account and add a command to set the environment variable.

The lock server will consult the OO_SERVER_LOG_DIR environment variable before it looks for the default log directory.

For information, see "Using a Lock Server" in Objectivity/DB Administration.

Checking the Lock Server

To check whether the lock server is running, enter the following command:

installDir/bin/oocheckls

Setting Up Data-Server Software

You can distribute an Objectivity/DB system across multiple hosts on a network. This means that an Objectivity/DB application running on a client host can access Objectivity/DB files on other hosts set up as data server hosts; see "Objectivity/DB Basics" in the Objectivity/DB Administration for more information.

By default, Objectivity/DB applications contact NFS on the data-server host to access Objectivity/DB files. For improved performance, you can run the Objectivity Advanced Multithreaded Server (AMS) on hosts containing Objectivity/DB files. When AMS is running, it is contacted instead of NFS for remote data access.

Within a distributed Objectivity/DB system, you can use NFS on some hosts and AMS on others. Note, however, that you must run AMS on every host that is to store an autonomous partition or a replicated database; see Objectivity/DB High Availability Configuration.

Setting Up AMS

AMS allows remote database applications to access to local data files and journal files in a distributed Objectivity/DB system.

Important: For security purposes, consider running AMS under a special-purpose user account in a group that can be granted just the minimum necessary permissions. When an application uses AMS, any data files or journal files created by the application are owned by the user account under which AMS was started. It is strongly recommended that you do not run AMS under the root account. See "Advanced Multithreaded Server" in Objectivity/DB Administration for more information.

Note: You can run AMS on one or more hosts. If you want to run AMS on a workstation that does not contain the Objectivity/DB installation, you can run the installer in Custom mode to install just the servers you want.

The installation and setup of AMS varies by platform.

Linux Platforms

A default Full or Typical installation as root installs AMS as a Linux init.d service that is disabled. If you want to enable AMS, it is recommended that you enable the service at runlevel 3 and runlevel 5. Refer to the documentation for your Linux platform for instructions.

The AMS service is named ooams-3 and uses TCP/IP port 6779 by default.

Other UNIX Platforms

With a default Full or Typical installation as root, AMS is installed, but is not started nor is it set up to start when the system reboots. You must configure each UNIX data server that is to use AMS, and you must start AMS before running any database applications.

To set up AMS:

  1. If you are starting AMS on the same host as the lock server, skip this step. Otherwise, set up a log file directory for AMS.
  2. Start AMS to verify that it is installed properly. To start AMS under the user account userName, enter a command such as:
    su - userName -c "installDir/bin/oostartams"
    

    By default, AMS handles eight threads. You can specify a different number of threads by entering the oostartams command with the -numthreads option.

    AMS will not start if another service already uses the TCP/IP port that AMS expected to use. If you cannot reassign the other service to a different port, change the default port for AMS; see "Advanced Multithreaded Server" in Objectivity/DB Administration.

  3. (Optional) Configure your workstation to start AMS whenever the machine reboots. To do this, edit the workstation’s startup script (usually /etc/rc.local or /etc/init.d) and add a command such as the one in step 2.

Setting Up a Log Directory for AMS

A running AMS creates log files in a log directory. By default, AMS expects to write log files in the default log directory, which is /usr/spool/objy .

Note: If you run the lock server and AMS on the same host, they will both use the same log directory.

The setup for a log directory varies by platform.

Linux Platforms

By default, a running AMS creates log files in /usr/spool/objy and no setup is required.

To use a different location, refer to Changing the Log Directory for AMS.

Other UNIX Platforms

Perform the following steps to set up the default log directory.

Note: If you run AMS and the lock server on the same host, they will both use the same log directory.

  1. Log in as root.
  2. Create the /usr/spool/objy log directory.
  3. Set the log directory’s permissions to enable AMS to create and update files in this directory, and to enable all users to read and write files there. Enter:
    chmod 777 objy  

To use a different location, refer to Changing the Log Directory for AMS.

Changing the Log Directory for AMS

To use a nondefault log directory:

  1. Create the directory with the appropriate permissions.
  2. Set the environment variable OO_SERVER_LOG_DIR to the directory pathname before you start AMS.

If you are configuring your workstation to restart the lock server on reboot, this environment variable must be set before AMS is restarted. You can edit a startup file (such as .login ) for the userName account and add a command to set the environment variable.

AMS will consult the OO_SERVER_LOG_DIR environment variable before it looks for the default log directory.

For information on changing the log directory for AMS log files, see "Advanced Multithreaded Server" in Objectivity/DB Administration.

Checking AMS

To check whether AMS is running, enter the following command:

installDir/bin/oocheckams

Setting Up NFS

To set up a UNIX data-server host using NFS:

rpcinfo -p hostname	
  1. Find out whether the nfs and mountd daemons are running. Enter:
  2. If necessary, start the nfs and mountd daemons.
    (The mountd daemon may require an option on some architectures; see Non-Privileged Ports below.)
  3. Verify that NFS exports any directories that will contain Objectivity/DB data files or journal files. For example, list these directories in the /etc/exports file. (On some architectures, you may need to include an additional option; see Non-Privileged Ports.)

Non-Privileged Ports

Depending on the architecture of your UNIX data-server host, you might need to arrange for NFS to accept client requests originating from non-privileged ports.

Table 1 Additional NFS Setup 
Architecture of Data-Server Host Allow Client Requests from Non-Privileged Ports
hpuxia64 Run mountd.
linux86_64 Export Objectivity/DB directories using the insecure option.
linux86gcc3 Export Objectivity/DB directories using the insecure option.

Setting Up Client Hosts for Remote Data Access Through NFS

When you use NFS in a distributed Objectivity/DB system, you may need to adjust the data packet size on each client host that will access files through NFS. In particular, you should check whether the TCP/IP protocol stack on each client host requires a smaller data packet size than 8192 bytes, which is the default used by Objectivity/DB with NFS. Furthermore, in a congested network, a Remote Procedure Call (RPC) timeout error message may also indicate that the data packet size is too large.

To adjust the data packet size:

► Set the environment variable OO_NFS_MAX_DATA .

Note: You do not need to adjust the data packet size if you use AMS instead of NFS.

Setting Up the Query Server

Query servers execute the subtasks of a parallel query initiated from within an Objectivity/DB database application. You must start a query server before running any database applications that perform parallel queries. See "Using a Query Server" in Objectivity/DB Administration for more information.

Important: For security purposes, you should consider running the query server under a special-purpose user account in a group that can be granted just the minimum necessary permissions.

Note: You can run the query server on one or more hosts. If you want to run a query locally on a workstation that does not have an Objectivity/DB installation, you can run the installer in Custom mode to install just the servers you want.

The installation and setup of the query server varies by platform.

Linux Platforms

A default Full or Typical installation as root installs the query server as a Linux init.d service that is disabled. If you want to enable the query server, it is recommended that you enable the service at runlevel 3 and runlevel 5. Refer to the documentation for your Linux platform for instructions.

When enabled with these run levels, the query server will restart when the workstation reboots.

Other UNIX Platforms

With a default Full or Typical installation as root, the query server is installed, but is not started nor is it set up to start when the system reboots.

The query server service is named ooqs-1 and uses TCP/IP port 6782 by default.

To set up the query serve:

  1. Log in as root.
  2. Start the query server to verify that it is installed properly. To start the query server under the user account username, enter a command such as:
    su - username -c "installDir/bin/ooqueryserver -start"
    
  3. If the query server does not start, check whether a port conflict exists.

    The query server will not start if another service already uses the TCP/IP port that the lock server expected to use. If you cannot reassign the other services to a different port, you may have to change the default port for the lock server. To do this, see "Using a Query Server" in Objectivity/DB Administration.

  4. (Optional) Configure your workstation to start the query server whenever the machine reboots. To do this, edit the workstation’s startup script (usually /etc/rc.local or /etc/init.d) and add a command such as the one shown in step 2.

Checking the Query Server

Perform the following step to check that the query server is running:

► Enter the following command:

installDir/bin/ooqueryserver -check

Starting Objectivity/Assist

Objectivity/Assist (Assist) is a graphical tool for getting started quickly with Objectivity/DB. You can use Assist to perform tasks such as:

  • Creating and administering a federated database.
  • Listing a federated database’s physical components (files and servers) and logical components (databases, containers, and persistent objects).
  • Creating, browsing, and changing the data in a federated database, and the types in a federated database’s schema.
  • Generating C++ and Java class definitions (including accessor methods) from a federated database’s schema.

Assist also provides tutorials for getting started with Objectivity/DB basic concepts, as well as application development for selected programming-language interfaces. Assist is implemented as a rich client application on the Eclipse Rich Client Platform (RCP).

To start Assist:

  1. At a command prompt, enter:
    installDir/assist/ooassist
  2. At the prompt, specify a workspace directory for Assist project files (see below).

Environment Variables

To add Assist to your PATH:

  1. Add installDir/assist to your PATH environment variable.
  2. Start Assist from a command prompt as follows:
    ooassist

Configuring Your Own Eclipse Platform

If you already have a compatible release of the Eclipse Platform or Eclipse SDK, you can install the Assist plugin into that framework:

  1. Copy all the subdirectories in installDir/assist/plugins that begin with com.objy.assist except com.objy.assist.rcp_x.x.x into the eclipseInstallDir/plugins directory, where:

    installDir Objectivity/DB installation directory
    eclipseInstallDir Directory containing the Eclipse installation to be used
  2. Copy the installDir/assist/features/com.objy.assist_x.x.x directory into the eclipseInstallDir/features directory.
  3. Start Eclipse.
  4. From the Eclipse menus, choose Window > Open Perspective > Other, then choose Objectivity/Assist.

Getting Started With Assist’s Tutorials

Assist provides several tutorials for getting started with Objectivity/DB. To find a tutorial, click on its link in Assist’s Welcome page. Alternatively, you can:

  1. Start Assist, if you have not already done so.
  2. In the Assist menu bar, click Help > Help Contents.
  3. In the Help window, click Objectivity/Assist User Guide. If you are new to Objectivity/DB, start with the Objectivity/DB Basics Tutorial.

Setting Up ootoolmgr

Note: If Objectivity/Assist is available on your architecture, it is recommended that you use it instead of ootoolmgr and skip this section.

Objectivity/DB provides a graphical tool called ootoolmgr for browsing objects and types in a database. This tool runs as an X Window System (X) application. Before you can run ootoolmgr, you must install several X resource files that specify various aspects of tool appearance and behavior. The required files are supplied in subdirectories of installDir (the Objectivity/DB installation directory).

You can install the required resource files in one of two ways, depending on whether you have access to the standard directory for locating X resource files. This directory is /usr/lib/X11 on most workstations and /usr/openwin/lib on workstations running OpenWindows.

Warning: The X resource files supplied with Objectivity/DB contain resources that are critical to the proper functioning of ootoolmgr. Do not modify these files.

Installing With Access to /usr/lib/X11

If you have access to the standard X directory, you can install the Objectivity/DB resource files by setting up symbolic links to them.

Caution: You should consult your system administrator before attempting to modify the /usr/lib/X11 directory or its subdirectories.

To set up the appropriate symbolic links:

  1. Log in as root, if necessary.
  2. Determine whether one or both of the following directories already exists in the file system of each of the workstations where ootoolmgr will be run:
    • /usr/lib/X11/bitmaps
    • /usr/lib/X11/app-defaults

    Note: On workstations running OpenWindows, look in /usr/openwin/lib instead of /usr/lib/X11.

  3. Create the bitmaps and app-default directories, if necessary. Enter:
    cd /usr/lib/X11
    mkdir bitmaps
    mkdir app-defaults
    
  4. Link the Objectivity/DB resource files to the corresponding X subdirectories. Enter:
    cd /usr/lib/X11/bitmaps
    ln -s installDir/etc/bitmaps/OoToolMgr OoToolMgr
    cd /usr/lib/X11/app-defaults
    ln -s installDir/etc/app-defaults/OoToolMgr OoToolMgr

Installing Without Access to /usr/lib/X11

If you cannot alter the /usr/lib/X11 directory, you can install the Objectivity/DB resource files by setting environment variables. To do this:

  1. Set the following environment variables to enable X to find the Objectivity/DB resources. If you are using the C shell, add the following lines to your login files (.cshrc, .login, and so on) using a text editor:
    setenv XFILESEARCHPATH installDir/etc/app-defaults/%N
    setenv XBMLANGPATH installDir/etc/bitmaps/%N/%B
  2. Update your environment to enable the resource path variables. For example, if you are using the C shell, enter:
    source homeDir/.cshrc

Troubleshooting the Installation

On completion, the installer produces a log file that lists any warning messages and provides information about what was installed. This log is placed in the top-level installation directory:

installDir/Objectivity-x.x-installLog.log

This section provides workarounds for potential problems that might occur during installation.

Lock Server: Directory Permission or File System Errors

Error message produced when starting the lock server:

ools:Error Directory /usr/spool/objy not found
O.S. errno = 13 -- permission denied
Failed to connect to server...  

Cause: A nondefault log directory has not been set up and Objectivity/DB cannot find or access the default log directory /usr/spool/objy .

Solutions:

  • Check whether the default log directory exists. If it doesn’t exist, either create it or set up a nondefault log directory. Follow the steps in Setting Up a Log Directory for the Lock Server.
  • If the default directory does exist, either use chmod to set less restrictive access privileges for it or start the lock server as the root user.

Alternatively, if you are unable to change permissions or start the lock server as the root user, you can set up a nondefault log directory. Follow the steps in Setting Up a Log Directory for the Lock Server.

Error message produced when starting the lock server:

Warning: Unable to open dirName.   

Cause: The OO_SERVER_LOG_DIR environment variable has been set to a nondefault log directory dirName, but Objectivity/DB cannot find or access dirName.

Solutions:

  • Check whether dirName exists. If it doesn’t exist, either create it or else set the OO_SERVER_LOG_DIR environment variable to refer to a different existing directory. Follow the steps in Setting Up a Log Directory for the Lock Server.
  • If the dirName does exist, use chmod to set less restrictive access privileges for it or start the lock server as the root user.

Alternatively, if you are unable to change permissions or start the lock server as the root user, you can set up a nondefault log directory. Follow the steps in Setting Up a Log Directory for the Lock Server.

Error message produced when starting the lock server:

Not enough disk space.

Solution: Free up space on your disk.

Date: 
Monday, August 20, 2012
Product: 
Objectivity/DB
Version: 
11.0