Macintosh: 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:

Important: Do not use the Macintosh Time Machine software to back up your Objectivity data. Rather, use the Objectivity backup and restore tools as described in Objectivity/DB Administration.

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 DYLD_LIBRARY_PATH (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 Objectivity 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 and is automatically started with a default Full or Typical installation.
  • The Advanced Multithreaded Server (AMS), which allows remote database applications to access 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.

By default, the installer creates a default directory named /var/spool/objy for server log files. In addition, an XML configuration file is installed in /Library/LaunchDaemons/ for each server.

Configuring Objectivity Servers

At boot time, the Macintosh daemon manager, launchd, looks for server configuration files in predefined locations and loads those servers according to their configuration. The configuration files for Objectivity servers are installed in one of those predefined locations:

Locker Server /Library/LaunchDaemons/com.objectivity.ools.plist
AMS /Library/LaunchDaemons/com.objectivity.ooams.plist
Query Server /Library/LaunchDaemons/com.objectivity.oopqe.plist

The lock server's configuration file has an entry that restarts the lock server when the system reboots:

<key>RunAtLoad</key>
<true/>

For AMS and the query server, RunAtLoad is set to false. You can change the startup configuration of Objectivity servers using the launchctl program, which interfaces with launchd. To modify a server’s configuration file:

  1. From a Terminal window, issue a command to unload the server’s configuration file and stop the server.

    For example, the following unloads the lock server configuration file and stops the running lock server:

    sudo launchctl unload /Library/LaunchDaemons/com.objectivity.ools.plist

  2. Edit the server’s configuration file with text editor to make any changes you want.
  3. Issue a command to load the configuration file and restart the server.

    For example:

    sudo launchctl load /Library/LaunchDaemons/com.objectivity.ools.plist

Note: See Configuring Servers after a Non-Root Installation for information about setting up services when the configuration files were not installed.

Configuring 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. A default Full or Typical installation as root installs the lock server as service that will restart when the workstation reboots. The installer also starts the lock server.

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.

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.

Note: You can run the lock server on one or more hosts. If you want to run a 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.

Checking the Lock Server

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

installDir/bin/oocheckls

Using a Special-Purpose Account for the Lock Server

For security purposes, you should consider running the lock server under a special-purpose user account in a group that can be granted just the minimum necessary permissions. These permissions are described in "Using a Lock Server" in Objectivity/DB Administration.

After creating the special-purpose account, you need to edit the lock server’s configuration file to start the lock server under that account. Refer to Configuring Objectivity Servers for general instructions on how to unload, edit, then reload a server’s configuration file.

To specify a special-purpose account for running the lock server:

 Edit /Library/LaunchDaemons/com.objectivity.ools.plist to change the UserName string value from root to your special user account name.

For example, the following shows part of a lock server configuration file that starts the lock server under the user name specialUser:

...
<!-- Key to uniquely identify the lock server -->
<key>Label</key>
<string>com.objectivity.ools</string>
<key>ProgramArguments</key>
<array>
  <!-- Lock server executable -->
  <string>/Applications/Objectivity/version/bin/ools</string>
</array>
<!-- User account used to run the server -->
<key>UserName</key>
<string>specialUser</string>
...

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 writes log files in the default log directory, /var/spool/objy. Alternatively, you can arrange for the lock server to write these files into a nondefault log directory.

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

Perform the following steps to set up the nondefault log directory logDir:

  1. Verify that the desired log directory exists, and, if necessary, create it. Enter:
    sudo mkdir logDir
  2. 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:
    sudo chmod 777 logDir
  3. Modify the lock server’s configuration file to set the OO_SERVER_LOG_DIR environment variable to point to the nondefault log directory.

See Configuring Objectivity Servers for general instructions on how to unload, edit, then reload a server’s configuration file. The following shows part of a lock server configuration file that specifies a nondefault log file directory:

...
<key>EnvironmentVariables</key>
<dict>
  ...
  <!-- Specify the server's log directory -->
  <key>OO_SERVER_LOG_DIR</key>
  <string>/Users/john/objy</string>
</dict>
...

Note: The lock server 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 lock-server log files, see "Using a Lock Server" in Objectivity/DB Administration.

Additional Configuration Options

Additional lock server options can be manually added to the lock server configuration file. For example, the following portion of a modified lock server configuration file includes an option to set the size of the transaction identification table to 4000, and provides options for the lock server’s recovery monitor.

Note: See Configuring Objectivity Servers for general instructions on how to unload, edit, then reload a server’s configuration file.

...
<dict>
  <!-- Key to uniquely identify the lock server -->
  <key>Label</key>
  <string>com.objectivity.ools</string>
  <key>ProgramArguments</key>
  <array>
    <!-- Lock server executable -->
    <string>/Applications/Objectivity/version/bin/ools</string>
    <string>-monitor</string>
    <string>-timeout 60</string>
    <string>-interval 90</string>
    <string>-testport 8888</string>
    <string>/Users/john/helloWorld/Helloworld.boot</string>
    </array>
...

Note: Configuration files call servers directly, such as  with ools. They do not call the wrappers, such as oolockserver.

For more information about lock server options, see oolockserver in Objectivity/DB Administration.

Configuring Data-Server Software

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

When Objectivity/DB applications contact a remote data-server host to access the Objectivity/DB files, they use AMS if it is running on that host. Otherwise, NFS is used.

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).

Configuring AMS

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

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 data server that is to use AMS, and you must start AMS before running any database applications.

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

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.

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.

Perform the steps given below on each Macintosh host that is to provide file access to remote database applications through AMS.

Starting AMS at Reboot

To set up AMS to start at system reboot:

  1. Refer to Configuring Objectivity Servers for information about unloading and reloading configuration files.
  2. Modify AMS's configuration file to set RunAtLoad to true.
<key>RunAtLoad</key>
     <true/>

Using a Special-Purpose Account for AMS

For security purposes, you should consider running AMS under a special-purpose user account in a group that can be granted just the minimum necessary permissions. These permissions are described in "Advanced Multithreaded Server" in Objectivity/DB Administration. 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.

Note: It is strongly recommended that you do not run AMS under the root account.

After creating the special-purpose account, you need to edit the AMS configuration file to start AMS under that account. Refer to Configuring Objectivity Servers for general instructions on how to unload, edit, then reload a server’s configuration file.

To specify a special-purpose account for running AMS:

► Edit /Library/LaunchDaemons/com.objectivity.ooams.plist to change the UserName string value from root to your special user account name.

For example, the following shows part of a modified AMS configuration file that starts AMS under the user name specialUser:

...
<!-- Key to uniquely identify the AMS server -->
<key>Label</key>
<string>com.objectivity.ooams</string>
<key>ProgramArguments</key>
<array>
  <!-- AMS server executable -->
  <string>/Applications/Objectivity/version/bin/ooams</string>
  <!-- Internal identifier, do not change  -->
  <string>xyzzy</string>
  <!-- Number of threads (default is 8) -->
  <string>8</string>
</array>
<!-- User account used to run the server -->
<key>UserName</key>
<string>specialUser</string>
...

Setting Up a Log Directory for AMS

A running AMS creates log files in a log directory. By default, AMS writes log files in the default log directory, /var/spool/objy. Alternatively, you can arrange for AMS to write these files into a nondefault log directory.

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

Perform the following steps to set up the nondefault log directory logDir:

  1. Verify that the desired log directory exists, and, if necessary, create it. Enter:
    sudo mkdir logDir
  2. 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:
    sudo chmod 777 logDir
    
  3. Modify the AMS configuration file to set the OO_SERVER_LOG_DIR environment variable to point to the nondefault log directory

See Configuring Objectivity Servers for general instructions on how to unload, edit, then reload a server’s configuration file.

The following shows part of an AMS configuration file that specifies a nondefault log file directory:

...
  <key>EnvironmentVariables</key>
  <dict>
    ...
    <!-- Specify the server's log directory -->
    <key>OO_SERVER_LOG_DIR</key>
    <string>/Users/john/objy</string>
  </dict>
   ...

Note: 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.

Specifying the Number of Threads

By default, AMS handles eight threads. You can specify a different number of threads by modifying the AMS configuration file. Refer to Configuring Objectivity Servers for general instructions on how to unload, edit, then reload a server’s configuration file.

To specify a different number of threads for AMS:

► Edit /Library/LaunchDaemons/com.objectivity.ooams.plist to change the number of threads string to a different number.

For example, the following shows a modified AMS configuration file that specifies 32 threads:

...
<!-- Key to uniquely identify the AMS server -->
<key>Label</key>
<string>com.objectivity.ooams</string>
<key>ProgramArguments</key>
<array>
  <!-- AMS server executable -->
  <string>/Applications/Objectivity/version/bin/ooams</string>
  <!-- Internal identifier, do not change  -->
  <string>xyzzy</string>
  <!-- Number of threads (default is 8) -->
  <string>32</string>
</array>
...

Configuring NFS

Perform the following steps on each Macintosh data-server host that is to provide file access to remote Objectivity/DB applications through NFS:

  1. Find out whether the nfs and mountd daemons are running. Enter:
    rpcinfo -p hostname
    
  2. If necessary, start the nfs and mountd daemons.
  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.

Non-Privileged Ports

You need to arrange for NFS to accept client requests originating from non-privileged ports.

To do so, configure nfsd to run with the -N flag.

Setting Up Client Hosts for Remote Data Access Through NFS

When you use NFS to provide data access 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.

Configuring the Query Server

An application can initiate a parallel query or a navigation query, which uses one or more query servers to distribute query processing across an Objectivity/DB system. 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.

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

Note: If you want to run the query 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.

Starting the Query Server at Reboot

To set up the query server to start at system reboot:

  1. Refer to Configuring Objectivity Servers for information about unloading and reloading configuration files.
  2. Modify the query server's configuration file to set RunAtLoad to true.
<key>RunAtLoad</key>
<true/>

Non-Privileged Ports

Using a Special-Purpose Account for the Query Server

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. These permissions are described in "Using a Query Server" in Objectivity/DB Administration.

After creating the special-purpose account, you need to edit the query server’s configuration file to start the query server under that account. See Configuring Objectivity Servers for general instructions on how to unload, edit, then reload a server’s configuration file.

To specify a special-purpose account for running the query server:

► Edit /Library/LaunchDaemons/com.objectivity.oopqe.plist to change the UserName string value from root to your special user account name.

For example, the following shows part of a query server configuration file that starts the server under the user name specialUser:

...
<!-- Key to uniquely identify the query server -->
<key>Label</key>
<string>com.objectivity.oopqe</string>
<key>ProgramArguments</key>
<array>
  <!-- Query server executable -->
  <string>/Applications/Objectivity/version/bin/ooqs</string>
</array>
<!-- User account used to run the server -->
<key>UserName</key>
<string>specialUser</string>
...

Additional Configuration Options

Additional query server options can be manually added to the query server configuration file. For example, the following portion of a modified query server configuration file includes an option to set the number of threads to 10 and the cache size to 900.

...
<dict>
  <!-- Key to uniquely identify the query server -->
  <key>Label</key>
  <string>com.objectivity.oopqe</string>
  <key>ProgramArguments</key>
  <array>
  <!-- Query server executable -->
  <string>/Applications/Objectivity/version/bin/ooqs</string>
   <string>-numthreads 10</string>
  <string>-cachesize 900</string>
  </array>
...

For more information about query server options, see ooqueryserver in Objectivity/DB Administration.

Checking and Stopping Servers

You can verify that the servers are running using Objectivity command-line tools:

  • oocheckls indicates whether a lock server is running on a particular computer.
  • oocheckams indicates whether AMS is running on a particular computer.
  • ooqueryserver -check indicates whether the query server is running on a particular computer. You can also check whether the query server is running using the Macintosh Activity Monitor found in the Utilities folder inside the Applications folder. If the query server is up and running, the Activity Monitor lists the ooqs process.

You can let each Objectivity server continue running, or you can stop a server. However, you must restart a stopped server before you can run any database application that requires it.

You can stop Objectivity servers using Objectivity command-line tools.

  • ookillls terminates a lock server.
  • oostopams terminates AMS.
  • ooqueryserver -stop terminates the query server.

Note that you must restart a stopped server before you can run any database application that requires it.

Any stopped Objectivity server will restart automatically at boot time (for any Objectivity installation hierarchy created with root permissions). You can modify a server’s startup configuration file to prevent this; see Configuring Objectivity Servers.

Configuring Servers after a Non-Root Installation

If you installed Objectivity/DB under a user other than root, the lock server will not be configured to start automatically at boot time.

To set up the servers to start automatically at boot time:

  1. Copy the appropriate configuration file from your installation hierarchy into /Library/LaunchDaemons:
    sudo cp installDir/etc/servers/com.objectivity.ools.plist /Library/LaunchDaemons
    
  2. As root, edit the configuration file to make the following changes:
    • In the <array> section, modify the path to the executable so that it’s correct for your hierarchy. For example:

      /Applications/Objectivity/version/bin/ools
       
    • In the EnvironmentVariables <dict> section, modify the path to Objectivity libraries so that it’s correct for your hierarchy. For example:

      /Applications/Objectivity/version/lib
       
    • In the EnvironmentVariables <dict> section, modify the path for the OO_SERVER_LOG_DIR environment variable, which specifies the location for server log files. For example:

      /var/spool/objy
  3. Issue a command to load the configuration file. For example:
    sudo launchctl load com.objectivity.ools.plist
    

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).

Unless you explicitly requested otherwise, the installer creates a symbolic link for Objectivity/Assist:

Objectivity Assist.app -> installDir/assist/ooassist.app  

To start Assist:

  1. In the Finder, open the Applications folder and double click on the Objectivity Assist icon.
  2. At the prompt, specify a workspace directory for Assist project files (see below).

Alternatively, you can start Assist from a Terminal window:

  1. At a command prompt, enter:
    sudo open "/Applications/Objectivity Assist.app"
  2. At the prompt, specify a workspace directory for Assist project files (see below).

Assist Workspace Directory

Any directory on your computer can serve as your Assist workspace directory. For example, to keep your Assist files with your Objectivity/DB installation, you can specify installDir/assist/workspace. If necessary, a workspace directory with the name you specify is created.

Note: Every user or group that is to run Assist must have read and write permissions on the hidden directory .metadata within the Assist workspace directory.

Configuring Your Own Eclipse Platform

If your computer already has 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.

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 /var/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 /var/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 dirNameexists. 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 the disk that contains the lock server’s log directory.

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