1. Installing GemStone/S 64 Bit Version 3.7.2

Platform

• Intel/AMD x86_64
• Apple silicon (ARM)

RAM and Swap space

• While small installations can run on systems with only a few GB of physical RAM, increasing RAM, and so allowing a larger Shared Page Cache, is important for GemStone performance.
• Adequate free disk space on the machine’s boot partition beyond other system needs.

Disk space

• Space for the installed distribution files—you need approximately 800MB for GemStone/S 64 Bit, and additional space for other products.
• Additional space as required for your repository.

Operating system

• MacOS 14.5 (Sonoma) with Darwin 23.5.0 kernel on Apple silicon (ARM)
• MacOS 14.5 (Sonoma) with Darwin 23.3.0 kernel on x86_64
• MacOS 11.7.10 (Big Sur) with Darwin 20.6.0 kernel on Apple silicon (ARM)
• MacOS 11.7.10 (Big Sur) with Darwin 20.6.0 kernel on x86_64

Debugger

A C debugger allows C-level stack traces when a GemStone error occurs, or when using the pstack command. While not required for GemStone execution, it is strongly recommended that a debugger be installed, so diagnostic error stacks will be available.

• lldb 12.3.0

lldb is installed as part of the Xcode command line tools package.

You must be logged in as root, or as a user with administrative privileges, in order to use a debugger or to generate stack traces from GemStone processes.

C/C++ Compiler

GemStone requires a C/C++ compiler if you are parsing C header files for creation of FFI interface classes, as described in the Programming Guide, or developing C or C++ code for user actions or a C or C++ application; as described in the GemBuilder for C manual.

If you have committed your FFI generated code, or compiled your user actions or application, the C/C++ compiler is not needed for application execution.

The compiler is required for application execution only when using GsTsExternalSession to access remote Stones running a different version of the GemStone server.

• Sonoma: Apple clang version 15.0.0 (clang-1500.3.9.4)
• Big Sur: Apple clang version 13.0.0 (clang-1300.0.29.30)

X Windows

An X Windows server allows you to use GemStone’s graphical VSD application on Mac. Alternatively, GemStone statistical data may be viewed on Windows, by transferring the data files, or by mounting the file system on Windows. X Windows is not required for GemStone execution.

Set Environment Variables

To use GemStone, you will need to define the GEMSTONE environment variable, and in most cases, set the OS search path.

1. The environment variable GEMSTONE should be set to the full pathname (starting with a slash) of your new GemStone installation directory. For example:

os$ export GEMSTONE=InstallDir/GemStone64Bit3.7.2-platform

2. Set your OS search path to include the $GEMSTONE/bin directory.

os$ export PATH=$GEMSTONE/bin:$PATH

3. If this machine has run previous versions of GemStone, or will run multiple versions, it is important to review all GemStone-related environment variables for ones that are incorrect for the new version, such as GEMSTONE_NRS_ALL, GEMSTONE_EXE_CONF, and GEMSTONE_SYS_CONF.

Check for existing GemStone environment variables:

os$ env | grep GEM

If any environment variables exist that are not appropriate for the new installation, you must specifically unset each one.

Set the GemStone Keyfile

The GemStone/S distribution includes a community keyfile, which will be used if a keyfile is not specified.

You may use a licenced customer keyfile (that is, a GemTalk-provided keyfile for your license) of the correct platform from any v3.7.x version with v3.7.2; keyfiles from 3.6.x and earlier are not valid with v3.7.2.

A keyfile must be located where GemStone can find it on startup, in order:

• A file specified by the KEYFILE configuration parameter in the configuration file used by the stone. This is not set by default, but may be defined to read a keyfile with any name in any location.
• $GEMSTONE/sys/gemstone.key
• $GEMSTONE/sys/community.starter.key

Configure Services for a Named NetLDI

The NetLDI permits remote processes to interact with the repository. A NetLDI is required for some local and all remote sessions to log into GemStone. Logins can specify a NetLDI by name or by port number.

Defining a NetLDI service name is only necessary if you will use named NetLDIs. If you start a NetLDI using a port number, then no configuration of the system services database is needed. The login parameters can use the NetLDI’s port rather than a name.

If you are using named NetLDIs, and your configuration includes multiple machines, (including clients on Windows or other platforms), you must update the services database on each node with an entry mapping the NetLDI name to the same port number.

To configure a named NetLDI:

1. Determine how the services file is setup on your system. If your system is using /etc/services, the installgs script can setup a named NetLDI for you.Otherwise, consult your system administrators.

2. Determine whether a service for the NetLDI name, such as gs64ldi, is already defined. The GemStone distribution includes an executable that will allow you to check for a definition:

os$ $GEMSTONE/install/getservbyname gs64ldi

s_name=gs64ldi s_port = 50377 s_proto = tcp

3. If your desired NetLDI name is not defined, add an entry similar to the following to the system services database:

gs64ldi 50377/tcp #GemStone/S 64 Bit 3.7.2

Choose a port number that is not being used by another service. The port number should be in the range 49152 <= port <= 65535, to conform to IANA standards (http://www.iana.org/assignments/port-numbers).

If several machines will be running GemStone, the system services database must be updated for each machine, including Windows clients as well as UNIX nodes. The port number must be the same for every machine.

Repository configuration using configuregs

If you are installing GemStone on a machine that has not previously had a version of GemStone installed, running configuregs (or the equivalent manual process) is required to perform the setup of the /opt/gemstone/locks and log directories. These directories must exist and be accessible in order to run GemStone.

If the /opt/gemstone/locks and log directories already exist, running configuregs is optional.

The configuregs script must be executed with root permissions; either logged in as root, or using sudo. the $GEMSTONE environment variable must be defined.

os$ sudo -E $GEMSTONE/install/configuregs

This has the following options:

• Enter the user that will own GEMSTONE (required, must exist and not be root)

The files in the installation will be chowned to be owned by this user. Enter gsAdminUser.

• Enter the group that will own GEMSTONE (required, must exist):

The files in the installation will be chgrouped to this group. Depending on your NetLDI configuration, all users that will use GemStone should be in this group.

• Enter a key file to use with GEMSTONE (optional):

Enter the path to a keyfile, if you have a keyfile you wish to install. If you leave this empty (the default), by pressing enter, the Stone may be started using the community key file, or you may install your own key file later. If you supply the path to a keyfile, this is renamed and copied, to $GEMSTONE/sys/gemstone.key.

• Should the netldi and port number be added to /etc/services ?: ['n']

configuregs can add the NetLDI name and port number to /etc/services. Unless you are familiar with this step and know your port lookup goes through /etc/services, use the default n.

• Protect GemStone processes from the Linux Out of Memory killer?: ['y']

configuregs can add Out-of-Memory killer protection to key GemStone process. If you answer the default y, configuregs will add the cap_sys_resource capability to certain executables.

• Update /etc/systemd/logind.conf to prevent killing GemStone at logout?: ['y']

On some Linux distributions, the default for RemoveIPC is yes, which can result in the GemStone repository dying with an error when the user that started GemStone logs out. To be safe, we recommend explicitly setting RemoveIPC=no in /etc/systemd/logind.conf. Answering yes to this question will add the line to this file, unless it is already present.

os$ sudo -E $GEMSTONE/install/doconfiguregs /var/tmp/gsanswers.txt

Repository configuration using legacy installgs

The legacy installgs script verifies your environment, creates lock and log file directories, sets up the extent files, and can be used to configure certain types of security for multi-user systems.

For new users and for test and development systems without strict security requirements, it is recommended to use the configuregs script (here), and not running installgs.

Running installgs is needed if you want to configure the NetLDI to run in root mode with the s bit set.

The installgs script must be executed with root permissions; either logged in as root, or using sudo. the $GEMSTONE environment variable must be defined.

os$ cd $GEMSTONE/install

os$ sudo ./installgs

This has the following options:

• Set up directories for server lock files and NetLDI logs?

The default location for server lock files and NetLDI log files is /opt/gemstone. If the directory does not exist, the installation script asks a number of questions allowing you to create /opt/gemstone and the subdirectories locks and log, and to set access (770) to these directories.

• Set the owner and group for all the files in the 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.

• Protect the repository extent file?

The default gives only the owner read and write access (600) through ordinary UNIX commands. Other users can read and write the repository extent through a GemStone session. If you choose not to protect the repository, the executables 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?

The NetLDI 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.

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.

If you are running a development system without strict security requirements, we recommend not using the default.

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

• Set up an Extent?

installgs offers to set up a new GemStone repository in $GEMSTONE/data. This is only appropriate if you wish to create a new repository. It performs the equivalent of the setup described in Simple classic repository setup in data directory.

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

• Start a NetLDI?

installgs offers to start a NetLDI that is running in root with s-bit set; this should only be used if you have answered yes to “Allow NetLDI to Run as Root?”.

Default: Do not start a NetLDI at this time.

After running installgs, log out as user root. Further work is done as the GemStone administrative user.  

1. Kernel parameters

To specify shared memory and other kernel parameters, you must create a plist file with the name com.gemtalksystems.shared-memory.plist, and put this file in /Library/LaunchDaemons/. See below for an example.

Shared Memory

The maximum shared memory segment should be set to a value larger than your desired Shared Page Cache size, and not more than 75% of your real memory size. In addition, for most systems you will need to increase the system-wide limit on shared memory segments.

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

8192 MB * .75 = 6144 MB

6144 MB * 220 = 6442450944 bytes

The following settings would be defined:

kern.sysv.shmmax=6442450944

kern.sysv.shmall=1572864 

Note that kern.sysv.shmmax is configured in bytes, but kern.sysv.shmall is configured in pages with a base page size of 4096.

Number of Processes

The default limits on the number of processes are adequate for up to about 250 GemStone users, for configurations establishing security via captive account. To allow more processes for the GemStone administrative userid, increase the settings for kern.maxprocperuid and kern.maxproc.

Setting kernel parameters

The following example contents of com.gemtalksystems.shared-memory.plist would apply to a system with 8MB of RAM, as described above.

You may download this file from https://docs.gemtalksystems.com/current/com.gemtalksystems.shared-memory.plist

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<plist version="1.0">

<dict>

  <key>Label</key>

  <string>shmemsetup</string>

  <key>UserName</key>

  <string>root</string>

  <key>GroupName</key>

  <string>wheel</string>

  <key>ProgramArguments</key>

  <array>

    <string>/usr/sbin/sysctl</string>

    <string>kern.sysv.shmmax=6442450944</string>

    <string>kern.sysv.shmall=1572864</string>

  </array>

  <key>KeepAlive</key>

  <false/>

  <key>RunAtLoad</key>

  <true/>

</dict>

</plist>

After defining the file or making changes to the settings, you will need to reboot so the changes take effect.

NOTE: On some version of macOS, you may need to run plist manually after reboot in order for the settings to take effect.

2. 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 files under the directory /etc/pam.conf/.

The specific GemStone service file 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, create a file named /etc/pamd.conf/gemstone.gem with the following contents:

auth		required			pam_opendirectory.so

For NetLDI authentication, again using LDAP, create a file named /etc/pamd.conf/gemstone.netldi with the following contents:

auth		required			pam_opendirectory.so

You can allow the “other” authentication stack to be used for GemStone authentication by editing the file /etc/pamd.conf/other so it includes the following:

auth		required			pam_opendirectory.so

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

3. 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; a system time earlier than the last checkpoint time may be taken as an indication of corrupted data and prevent GemStone from starting. The time comparisons use GMT.