1. Installing GemStone/S 64 Bit Version 3.3

1. Shared memory maximum

The default for maximum shared memory segment is not adequate to run GemStone/S 64 Bit. We recommend a value larger than your desired Shared Page Cache size, and not more than 75% of your real memory.

For example, if you have 8192 MB of real memory:

8192 MB * .75 = 6144 MB

6144 MB * 220 = 6442450944 bytes

The parameter in Solaris 10 and above is project.max-shm-memory, which controls project total memory use, not segment size. To configure this, use a command similar to the following, which sets the shared memory maximum to 6GB.

Solaris 10:

prctl -n project.max-shm-memory -v 6gb -r -i project "user.root"

Solaris 11:

projmod -sK 'process.max-shm-memory=(privileged,6G,deny)' default

In earlier versions of Solaris, shmsys:shminfo_shmmax set the maximum shared memory segment size, rather than limiting total memory use. To set this parameter using legacy-style Solaris configuration, in /etc/system include the following:

set shmsys:shminfo_shmmax=6442450944

2. Semaphores

The maximum number of semaphores per id (per semaphore set) limits the number of GemStone sessions that can log in to a particular Stone and connect to its shared page cache.

On the Stone’s node, this parameter must provide two semaphores for each user who will log in to that Stone from any node plus an overhead of four. In distributed systems, nodes that have only user sessions (Gems), but no Stones, must provide two semaphores for each user session on that node plus an overhead of one.

The number of semaphores actually requested for a particular shared page cache depends on the GemStone configuration file read by the process that starts the cache and is (SHR_PAGE_CACHE_NUM_PROCS * 2 ) + 1.

In Solaris 10 and above, the project parameter is process.max-sem-nsems. The default is 512 which is adequate for smaller-sized systems. For larger systems, use a command similar to the following, which set the value to 2048:

Solaris 10:

prctl -n project.max-sem-nsems -v 2048 -r -i project "user.root"

Solaris 11:

projmod -sK 'process.max-sem-nsems=(privileged,2048,deny)' default

In earlier versions of Solaris, this parameter was named semsys:seminfo_semmsl (Note that semmsl ends with a lowercase L, not a digit.). To set this, use a command similar to the following, which sets the value to 500:

set semsys:seminfo_semmsl=500

If you are adjusting settings using /etc/system, save the file, and reboot the system using boot -r.

The maximum number of semaphore identifiers in the system limits the number of GemStone shared page caches on the node; each shared page cache uses one identifier. This parameter must be large enough to allow for one shared page cache for each Stone running on the node, plus one for each cache running on a remote node.

The project parameter in Solaris 10 and above is project.max-sem-ids. The default is 128. This should be adequate for most installations.

In earlier versions of Solaris, the parameter is semsys:seminfo_semmni.

3. PAM

If you are using UNIX authentication for GemStone logins, or if you run NetLDI as root with setuid (i.e. not in guest mode), you must have PAM (Pluggable Authentication Module) configured on the server. You may include a specific GemStone authorization service name, or allow the default “other” authentication definitions to be used.

PAM authentication definitions are in /etc/pam.conf. The specific GemStone service names are gemstone.gem for user authentication, and gemstone.netldi for a NetLDI running with authentication. The libraries that are specified in the stack depend on how you are configuring PAM to perform the authentication. The examples below are for PAM configured to invoke LDAP for authentication.

For example, to allow GemStone UNIX authentication, which uses PAM, to authenticate via LDAP:

gemstone.gem 	auth requisite	pam_authtok_get.so.1

gemstone.gem 	auth required	pam_ldap.so.1

For NetLDI authentication, again using LDAP:

gemstone.netldi 	auth requisite	pam_authtok_get.so.1

gemstone.netldi 	auth required	pam_ldap.so.1

If the following “other” stack is available in /etc/pam.conf, GemStone can use this to authenticate via LDAP:

other 	auth requisite	pam_authtok_get.so.1

other 	auth required	pam_ldap.so.1

Consult your System Administrators for more information on how authentication is handled on your system.

4. Configuring GemStone’ Shared Page Cache

The configuration option SHR_PAGE_CACHE_SIZE_KB defines the size (in KBytes) of extent page space in the shared page cache. The maximum acceptable value for this configuration option is limited by system memory, kernel configurations, cache space allocated by SHR_PAGE_CACHE_NUM_PROCS and space allocated for other GemStone caches.

For more general information about these and other configuration options, see Appendix A of the System Administration Guide.

5. System clock

The system clock must be set to the correct time. When GemStone opens the repository at startup, it compares the current system time with the recorded checkpoint times as part of a consistency check. A system time earlier than the time at which the last checkpoint was written may be taken as an indication of corrupted data and prevent GemStone from starting. The time comparisons use GMT.

6. TCP keepalive option

GemStone processes ordinarily use the TCP keepalive option to determine how long they will wait after communications activity ceases unexpectedly. This setting can be useful for reaping stale RPC Gems, but the operating system default may not be appropriate for this purpose. For further information, refer to your operating system documentation.

Do you want the installation script to set up directories for server lock files and NetLDI logs?

The default location for server lock files and NetLDI log files is /opt/gemstone, although for compatibility with earlier products /usr/gemstone is used only if it exists. If the environment variable GEMSTONE_GLOBAL_DIR is defined to point to a valid directory, this overrides the default server lock files and log file location; however, all Gemstone processes that will interact on this machine must have this environment variable set to the same directory.

If these directories do not exist, the installation script offers to create /opt/gemstone and the subdirectories locks and log. Then, the script offers to set access (770) to these directories.

If you answer no to creating the directories, you must create them (or provide a symbolic link) before starting the server.

Do you want the installation script to set the owner and group for all the files in the GemStone distribution?

If you answer yes, the script will prompt you for the owner and group you want to use. Refer to Chapter 1 of the System Administration Guide for more information about setting owner and group permissions.

If you answer no, the permissions will remain the same as when the files were extracted from the distribution media.

Do you want the installation script to protect the repository file?

The default, which we recommend, gives only the owner read and write access (600) through ordinary UNIX commands. Other users can read and write the repository through a GemStone session. If you choose not to protect the repository, the setuid bit is cleared from all executables, which causes them to run under ownership of the user who invokes them.

Default: Set the repository permission to 600, and leave the setuid bit applied.

Allow NetLDI to Run as Root?

Do you want the installation script to allow non-root users to start a NetLDI that runs as root?

The NetLDI is a network server that permits remote processes to interact with the repository. There are two ways to set up a NetLDI so that it can provide services to all GemStone users: it can run as root, or it can run in guest mode with a captive account.

• To run NetLDIs as root, accept the default “yes” response. Ownership of the NetLDI executable is changed to root, and the setuid bit is set. Any GemStone user will be able to start a NetLDI process that is accessible to all GemStone users because it will always run as root. For certain services, users will need to authenticate themselves by supplying a password. Alternatively, answer “no” but log in as root before starting the NetLDI.

If the NetLDI uses a port number less than 1024, it must run as root.

• To run NetLDIs in guest mode with a captive account, answer “no” to the prompt, because those modes are not permitted if the NetLDI runs as root. “Guest mode” means that GemStone users do not have to supply a UNIX password to use NetLDI services. The “captive account” is an account that owns all processes the NetLDI starts; typically, it is the GemStone administrative account that owns the files. You must start the NetLDI while logged in as that account.

Default: Change ownership of the netldi executable to root, and set its setuid bit.

Set up an Extent?

Do you want the installation script to set up an extent now?

GemStone is distributed with a read-only copy of the initial repository in
$GEMSTONE/bin/extent0.dbf. Before you can start GemStone, this file must be copied to a suitable location and made writable. The script offers to copy the file to its default location of $GEMSTONE/data.

If you are a new GemStone user, we recommend that you answer y. If you are an existing GemStone user, you might prefer to answer n, then copy the extent to a different location yourself. (If you choose a location other than the default, you must edit your configuration file before starting GemStone. For information, see the System Administration Guide.)

Default: Place a writable copy of extent0.dbf in $GEMSTONE/data.

Start a NetLDI?

Do you want the installation script to start a NetLDI?

If you prefer, you can start these processes manually at any time.

Almost every host needs a NetLDI. You must start a NetLDI when the Stone repository monitor or Gem session processes will run on this machine.

You can start a NetLDI that runs as root by answering yes to this prompt and the confirmation that follows. However, if you want to start the NetLDI in guest mode with a captive account, you must do that after completing the installation. For more information about guest mode with captive account, see Chapter 3 of the System Administration Guide.

Default: Do not start a NetLDI at this time.

Start an Object Server?

As root, you cannot start an object server, but the script offers to start one as another user. You will start the server later in the installation, so answer no.

Default: Do not start an object server at this time.

Log out as root

Log out as user root. The rest of the installation is done as the GemStone administrative user.