1. Installing GemStone/S 64 Bit Version 3.6.2

Platform

• Intel/AMD x86_64
• Apple M1 (arm64)

RAM and Swap space

• While small installations can run on systems with only a few GB of physical RAM, increasing RAM 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 500MB for GemStone/S 64 Bit, and additional space for other products.
• Additional disk space as required for your repository.
• The repository files should be located on a disk drive that does not contain swap space. Use of multiple disk drives is advisable for servers.

Operating system

• MacOS 11.1 (Big Sur) with Darwin 20.2.0 kernel, for x86_64
• MacOS 10.15.6 (Catalina) with Darwin 19.6.0 kernel, for x86_64
• MacOS 11.6 (Big Sur) with Darwin 20.6.0 kernel, for Apple M1

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 only if you are developing C or C++ code for user actions or for a C or C++ application; as described in the GemBuilder for C manual. This compiler is required only for development work, not for execution.

• Catalina: Apple clang version 11.0.3 (clang-1103.0.33.17)
• Big Sur: Apple clang version 12.0.0 (clang-1200.0.32.28)

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.

Configure the Operating System

The kernel must be configured to support shared memory and semaphores. See your operating system documentation for further information. These requirements apply both to server nodes and to client nodes.

8192 MB * .75 = 6144 MB

6144 MB * 220 = 6442450944 bytes

kern.sysv.shmmax=6442450944

kern.sysv.shmall=1572864 

<?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>

auth	required	pam_opendirectory.so

auth	required	pam_opendirectory.so

auth	required	pam_opendirectory.so

Set the Environment

Perform the following steps to properly configure the operating environment.

1. Set the environment variable GEMSTONE.

a. If more than one installation of any GemStone/S product resides on this machine, check for existing GemStone environment variables:

> env | grep GEM

All GemStone environment variables are displayed.

b. If any environment variables exist and are not appropriate for the new installation, you must specifically unset each one. For example:

> unset GEMSTONE GEMSTONE_SYS_CONF

c. Set the environment variable GEMSTONE to the full pathname (starting with a slash) of your new GemStone installation directory. For example:

> export GEMSTONE=InstallDir/GemStone64Bit3.6.2-i386.Darwin

or

> export GEMSTONE=InstallDir/GemStone64Bit3.6.2-arm64.Darwin

Set the GemStone Key File

To run GemStone, you must have a key file for the correct version of GemStone/S 64 Bit and for the appropriate platform. Note that the keyfiles for Darwin on Intel/AMD and Apple M1 are not interchangeable; you must have the GemStone keyfile for the correct platform. The keyfile must be located where GemStone can find it on startup:

• 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

Verify TCP/IP

To run GemStone, TCP/IP must be functioning, even if your machine is not connected to a network.

Verify that TCP/IP networking software is functioning (1 is the number 1):

> /sbin/ping -c 1 hostname

where hostname is the name of your machine. If ping responds with statistics, TCP/IP is functioning.

Define the NetLDI Service

The NetLDI service, by default gs64ldi, can be defined in your system services database to return the NetLDI listening port. A NetLDI is required for some local and all remote sessions to log into GemStone, and it can be resolved by name or directly by port number. If you are defining NetLDI services by name, the same NetLDI service name and port number must be defined on the remote machines as on the Stone’s node.

The following steps can be skipped if you will be using the NetLDI port rather than name. Using the port number requires that this same port be specified when the NetLDI is started up, and when sessions login. The details are described in the System Administration Guide.

If you are upgrading from a previous version, you may need to keep the NetLDI for that version running. In this case, select a distinct name and/or port for the NetLDI for GemStone/S 64 Bit 3.6.2.

1. Determine whether the gs64ldi service is already defined. How to do this will depend on how your system is set up. The GemStone distribution includes an executable that will allow you to do this:

unix> $GEMSTONE/install/getservbyname gs64ldi

s_name=gs64ldi s_port = 50377 s_proto = tcp

If gs64ldi is defined, skip the rest of this procedure and continue with the installation at Run the Installation Script.

If it is not defined, continue performing this procedure.

2. Add an entry similar to the following to the system services database:

gs64ldi 50377/tcp #GemStone/S 64 Bit 3.6.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 confirm to IANA standards (http://www.iana.org/assignments/port-numbers).

3. If several machines will be running GemStone, have the UNIX system administrator update the system services database for each machine. This includes Windows client machines as well as UNIX nodes. Note that the port number must be the same for every machine.

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 /usr/gemstone may be used in legacy installations. A different location can be specified using the environment variable GEMSTONE_GLOBAL_DIR; however, all Gemstone processes that will interact on this machine must have this environment variable set to the same directory.

If the directory does not exist, the installation script offers to create /opt/gemstone and the subdirectories locks and log, and 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.

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 file?

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

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

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 selecting the default.

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

Set up an Extent?

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, and edit the configuration file to reference this location. For more information, see the System Administration Guide.

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

Start a NetLDI?

You can start a NetLDI that runs as root by answering yes to this prompt and the confirmation that follows.

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 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 (Stone), but the script offers to start one as another user.

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

3. Log out as root

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

Change Passwords for Administrative Accounts

GemStone comes with a number of built-in System user accounts, which are needed to perform administrative operations (such as adding application user accounts).

• The DataCurator account is used to perform system administration tasks.
• The SystemUser account ordinarily is used only for performing GemStone system upgrades.
• The GcUser account is used by the garbage collection task, which runs automatically as a separate login.

The initial password for these administrative accounts is swordfish.

Access to each of these accounts should be restricted; you should always change the passwords for these accounts, to provide basic security for your application.

The chapter entitled “User Accounts and Security” in the System Administration Guide tells you how to change the passwords.

Add GemStone User Accounts

For each of the users in your system, you should establish GemStone accounts, which involves creating an individual UserProfile in GemStone.

The chapter entitled “User Accounts and Security” in the System Administration Guide provides information on how create accounts for GemStone users, and the options for authentication. This task can be done by executing Smalltalk code, or using GemBuilder for Smalltalk tools. See the GemBuilder for Smalltalk Users’s Guide for information on the GUI tools in GemBuilder.

Users must set environment

After GemStone/S 64 Bit 3.6.2 has been installed, you should notify each person who will be using GemStone about the installation, and explain how to setup their environment.

Each user must:

• Set the environment variable GEMSTONE to the full pathname (starting with a slash) of the GemStone/S 64 Bit 3.6.2 directory.
• update their path to include the $GEMSTONE/bin directory.
• Optionally, update the man path (MANPATH variable) to include the $GEMSTONE/doc directory. GemStone provides man pages for utility functions.

These last two steps can be done using scripts that are part of the GemStone distribution. The directory $GEMSTONE/bin contains the files gemsetup.sh and gemsetup.csh, which define the GemStone environment for users by modifying the PATH and MANPATH variables to include $GEMSTONE/bin and $GEMSTONE/doc, respectively.

For example:

 export GEMSTONE=installdir

 export PATH=$GEMSTONE/bin:$PATH

 export MANPATH=$MANPATH:$GEMSTONE/doc

If the user will use GemStone frequently, consider adding these steps to the login shell initialization file.

Install the default TimeZone

GemStone/S 64 Bit is shipped with a default time zone of US Pacific. If you are in another Time Zone, edit the file installtimezone.txt in the GemStone upgrade directory, then file it in as SystemUser.