This chapter describes the procedure for installing GemStone/S 64 Bitâ„¢ version 3.6.7. We recommend that you set up GemStone initially on a single machine, to ensure that all the pieces work together. Further setup to run a distributed system are described in the System Administration Guide. You will need to adjust the installation process to meet your specific needs.
If you are upgrading to this release from a previous version of GemStone/S 64 Bit, follow the instructions in the appropriate later chapter of this Installation Guide. These upgrade instructions will provide details on steps that need to be taken before and after the installation described here.
GemStone/S 64 Bit on MacOS is supported for development use only, not for use in production.
The following list summarizes the steps to install GemStone/S 64 Bit.
Before you install GemStone/S 64 Bit, ensure that the following system requirements are satisfied. Additional system resources may be necessary to support large applications.
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 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.
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.
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.
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.
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.
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.
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.
The following example contents of com.gemtalksystems.shared-memory.plist would apply to a system with 8GB 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>
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.
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.
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 OS default may not be appropriate for your system. For further information, refer to your operating system documentation.
Installing GemStone can be done as a regular user, but in order to set up shared security, some portions of the installation should be done when logged in as the root user. Other steps of the installation are done as the unix user who will be the GemStone administrative account.
In addition to the installation directory, /opt/gemstone is updated for new installations of GemStone. This is the default location for server lock files, host name id file, and log files for GemStone network servers (NetLDIs). See the System Administration Guide for details.
1. Log in as the GemStone administrator to the machine on which you are installing GemStone. This part of the installation should not be done as root, to ensure all the files are not owned by root.
2. Determine that adequate swap space is available.:
3. Select the drive on which you will install the GemStone software, and the installation directory on this drive, InstallDir. Make this directory the current working directory.
We recommend that you avoid choosing either an NFS-mounted partition or one containing UNIX swap space for the initial installation. Mounted partitions can result in executables running on the wrong machine and in file permission problems. Existence of swap space on the same drive can dramatically slow GemStone disk accesses.
4. GemStone/S 64 Bit is provided as a .dmg file with a name similar to:
GemStone64Bit3.6.7-i386.Darwin.dmg (on Intel/AMD), or GemStone64Bit3.6.7-arm64.Darwin.dmg (on Apple M1).
NOTE
While Intel/AMD executables can run on Apple M1, it would run in emulation mode; this has not been tested, and would have performance issues.
You should download the correct distribution for your system.
5. Double click on this file to open it, and drag the installation tree to InstallDir.
6. The InstallDir now contains a GemStone directory with a name similar to GemStone64Bit3.6.7-platform.Darwin.dmg.
In addition to subdirectories, this directory also contains the text file version.txt, which identifies this particular product and release of GemStone.
The GemStone server is now installed.
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:
os$ 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:
os$ 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:
os$ export GEMSTONE=InstallDir/GemStone64Bit3.6.7-i386.Darwin
os$ export GEMSTONE=InstallDir/GemStone64Bit3.6.7-arm64.Darwin
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 silicon 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:
You may use a keyfile from any v3.6.x version of the correct platform with v3.6.7; keyfiles from 3.5.x and earlier are not valid with v3.6.7. If you are upgrading from v3.5.x or earlier, or you have questions about your keyfile or license limits, email keyfiles@gemtalksystems.com, or contact GemTalk Technical Support.
The GemStone distribution includes a community key file, community.starter.key., with product and system limits per the Community and Web Edition License. See https://gemtalksystems.com/licensing for details on the license terms.
If you do not install a custom keyfile, this starter keyfile will be used instead.
To specify the location and name of the keyfile using the KEYFILE configuration parameter, edit the configuration file that will be used by the v3.6.7 stone to include the location and name of the keyfile.
You may also put the keyfile in the default location, $GEMSTONE/sys/gemstone.key. This requires modifying the write permissions of the $GEMSTONE/sys directory; ensure you change this back to not writable, after this update.
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):
os$ /sbin/ping -c 1 hostname
where hostname is the name of your machine. If ping responds with statistics, TCP/IP is functioning.
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.7.
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:
os$ $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.7
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.
The installation script verifies your environment, creates lock file directories, sets up the extent files, and can be used to configure certain types of security for multi-user systems. It is not required to run the installation script; however, if you are new to GemStone, or installing GemStone on a new server, running the install script is recommended.
For development systems without strict security requirements, it is recommended to run GemStone with the NetLDI in guest mode with captive account, which simplifies debugging. In this case, do not accept the default answers to the installation script questions regarding protecting the extent and running NetLDI as root.
You can run the installation script as a non-root user, however, some options are not available as a non-root user. To ensure that the installation is successful, you must install as root. See the System Administration Guide for details on setting up GemStone server file security.
2. Invoke the installation script from the install subdirectory:
os$ cd $GEMSTONE/install
os$ ./installgs
installgs is an interactive script that analyzes your system configuration and makes suggestions to guide you through installing GemStone on your machine. You can run the script multiple times; it will skip completed tasks.
NOTE
You can usually terminate execution of the installation script with Ctrl-C without risk to your files. When it is not safe to do so, the message Please do not interrupt appears on the screen.
During installation, you are asked several questions. The entire installation dialog is not reproduced here, but the main points are addressed. Some questions may not be asked, depending on answers to previous questions.
Whenever you are asked to answer “yes” or “no,” answer with y or n. When the script offers a default answer in square brackets (such as “[y]”), press Enter to accept the default.
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.
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.
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.
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.
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.
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.
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.
The following should be done by an administrative user, not as root.
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 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.
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.
After GemStone/S 64 Bit 3.6.7 has been installed, you should notify each person who will be using GemStone about the installation, and explain how to setup their environment.
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.
os$ export GEMSTONE=installdir
os$ export PATH=$GEMSTONE/bin:$PATH
os$ export MANPATH=$MANPATH:$GEMSTONE/doc
If the user will use GemStone frequently, consider adding these steps to the login shell initialization file.
This chapter has guided you through installation of GemStone/S 64 Bit 3.6.7, with the objective of getting a simple, default configuration up and running.
The next chapters explain the process of upgrading a previous version of GemStone/S 64 Bit to version 3.6.7; and Chapter 4 provides information on GemBuilder for Smalltalk.
For more information and details on customizing your GemStone object server, Gem client processes, and setting up distributed configurations, see the System Administration Guide.