1. Installing GemStone/S 64 Bit Version 3.3.1
This chapter describes the procedure for installing GemStone/S 64 Bit version 3.3.1 on a single machine. We recommend that you set up GemStone this way initially to ensure that all the pieces work together. At the end of this chapter, we suggest refinements you might want to make, such as running GemStone in a network configuration.
NOTE
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.
Adjust the installation to meet your specific needs. The topic What Next? provides references to procedures and related information in the System Administration Guide.
GemStone/S 64 Bit on Mac OS X/Darwin is supported for development use only, not for use in production.
Review the Installation Procedure
The following list summarizes the steps to install GemStone/S 64 Bit.
Check the System Requirements
Before you install GemStone/S 64 Bit, ensure that the following system requirements are satisfied. Systems meeting these requirements are suitable for installing GemStone/S 64 Bit and beginning development, but additional system resources may be necessary to support large applications.
RAM and Swap space
Disk space
- Space for the installed distribution files—you need approximately 450 MB 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.
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. This compiler is required only for development work, not for execution.
Debugger
A C debugger can be useful to allow problem analysis by GemStone consulting or Technical Support. It also may allow you to debug your C user actions. It is not required for GemStone execution. 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.
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.
1. 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 system you will need to increase the system-wide limit on shared memory segments.
Note that kern.sysv.shmmax is configured in bytes, but kern.sysv.shmall is configured in pages with a base page size of 4096.
For example, if you have 8192 MB of real memory:
8192 MB * .75 = 6144 MB
6144 MB * 220 = 6442450944 bytes
To set shared memory, you would include the following text in the /etc/sysctl.conf file, creating this file if it does not exist. The setting of the shared memory size is read from this file during the boot process.
# Shared Memory setting for GemStone
kern.sysv.shmmax=6442450944
kern.sysv.shmall=1572864
2. 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 in /etc/sysctl.conf.
3. PAM
If you are using UNIX authentication for GemStone logins, or if you run NetDLI 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 authenticaton. 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.
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.
Prepare for Installation
Perform the following steps to prepare the machine to receive the GemStone/S 64 Bit software. Although most steps require root login, we recommend that you perform the initial step as the GemStone administrator.
These are the portions of the system that are affected by the installation of GemStone:
/dev/rdisk*
Optional raw partitions for repository extents and transaction logs.
/etc/services
Internet services database, for NetLDI name lookup.
/InstallDir/GemStone64Bit3.3.1-i386.Darwin
Location of the object server software.
/opt/gemstone
Default location for server lock files, host name id file, and log files for GemStone network servers (NetLDIs). See the System Administration Guide for more information.
1. See the System Administration Guide for more information.As the GemStone administrator, log in to a machine that has adequate resources to run GemStone and that owns the disk on which you are going to install the GemStone files.
NOTE
Do not copy the files as root. The ownerships that were in effect when the distribution media was created are preserved, and this might result in file permission errors for users at your site.
2. Determine that adequate swap space is available.:
3. Check the free disk space and determine the disk drive and partition on which you will install the GemStone software.
To list all disk partitions, along with the amount of free space in each partition:
% df -k
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. Select an installation directory, InstallDir, and make this directory the current working directory.
5. GemStone/S 64 Bit is provided as a zipped archive file with a name similar to GemStone64Bit3.3.1-i386.Darwin.zip.
6. Move this distribution file to the directory location in which GemStone will be installed, InstallDir.
7. Unzip the distribution file using unzip. For example:
% unzip GemStone64Bit3.3.1-i386.Darwin.zip
8. The InstallDir now contains a GemStone directory with a name similar to GemStone64Bit3.3.1-i386.Darwin.
In addition to several subdirectories, this directory also contains two text files: PACKING, which lists all of the GemStone files, and version.txt, which identifies this particular product and release of GemStone.
NOTE
Although you can complete the installation as a non-root user, we do not recommend this. During installation, GemStone system security is established through file permissions and process attributes. To ensure that the installation is successful, you must install as root. If you later decide to change the security of your GemStone system, see Chapter 1 of the System Administration Guide, which explains the concept of GemStone server file permissions and how to change them.
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, depending on your shell:
% unsetenv GEMSTONE GEMSTONE_SYS_CONF
$ 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, depending on your shell:
% setenv GEMSTONE InstallDir/GemStone64Bit3.3.1-i386.Darwin
$ GEMSTONE=InstallDir/GemStone64Bit3.3.1-i386.Darwin
$ export GEMSTONE
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. The keyfile must be located where GemStone can find it on startup:
- $GEMSTONE/sys/gemstone.key
- $GEMSTONE/sys/community.starter.key
- The KEYFILE configuration parameter in theconfiguration file used by the stone, such as $GEMSTONE/data/system.conf
Licensed Customer key file
You may use a keyfile from version 3.3 with your version 3.3.1 installation. If you are upgrading from 3.2.x or earlier, or you have questions about your keyfile or license limits, email keyfiles@gemtalksystems.com, or contact GemTalk Technical Support.
Community key file
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 customer keyfile, this starter keyfile will be used instead.
Installing a keyfile
If you specify the location and name of the keyfile using the KEYFILE configuration parameter, edit the configuration file that will be used by the v3.3.1 stone to include the location and name of the keyfile.
To set the keyfile in the default location:
1. Change the permissions on the directory $GEMSTONE/sys so that you can create the file:
% chmod 755 $GEMSTONE/sys
2. Copy the keyfile into this directory, using the name gemstone.key.
cp mykeyfile.key $GEMSTONE/sys/gemstone.key
3. Change the file and directory permissions so that they are not writable:
% chmod 555 $GEMSTONE/sys/gemstone.key
% chmod 555 $GEMSTONE/sys
Verify TCP/IP
To run GemStone, TCP/IP must be functioning, even if your machine is not connected to a network.
1. 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, should be defined in your system services database. A NetLDI is required for certain kinds of local and remote sessions to log into GemStone, and if it cannot be resolved by name, you must refer to it by port number. For clients on remote machines, the same NetLDI service name and port number must be defined on the remote machines as well as the main host.
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 port for the NetLDI for GemStone/S 64 Bit 3.3.1.
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:
% $GEMSTONE/install/getservbyname gs64ldis_name=gs64ldi s_port = 50377 s_proto = tcp
If you are using a local copy of the system services database, /etc/services, then check in this file for a definition for gs64ldi.
If you are using NIS or LDAP, consult your UNIX system administrator for assistance.
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.3.1
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.
Run the Installation Script
Invoke the installation script from the install subdirectory:
% cd $GEMSTONE/install
% ./installgs
installgs is an interactive script that analyzes your system configuration and makes suggestions to guide you through installing GemStone on your machine.
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. If this happens, wait for the message now it is OK to interrupt before you interrupt the script. You can run the script again from the beginning as many times as necessary.
Decisions to Make During Installation
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.
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.
Change System Passwords and Add Users
After installing GemStone/S 64 Bit, you must change the passwords for the administrative users: DataCurator, SystemUser, and GcUser. (The initial password for each is swordfish.) 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. Access to each of these accounts should be restricted.
You must then establish GemStone accounts for each of your system’s users.
The chapter entitled User Accounts and Security in the System Administration Guide tells you how to change the passwords and set up accounts for other GemStone users, and how to create new GemStone user accounts. These functions can also be done using GemBuilder for Smalltalk tools; see the GemBuilder for Smalltalk Users’s Guide for more information.
Users must execute gemsetup
The directory $GEMSTONE/bin contains two files, gemsetup.sh and gemsetup.csh, to help set a user’s environment. These files define the GemStone environment for users by modifying the PATH and MANPATH variables to include $GEMSTONE/bin and $GEMSTONE/doc, respectively.
After GemStone/S 64 Bit 3.3.1 has been installed, you should notify each GemStone user of the installation and explain how to use the gemsetup files.
Each user must perform this procedure before running GemStone.
1. Set the environment variable GEMSTONE to the full pathname (starting with a slash) of the GemStone/S 64 Bit 3.3.1 directory. For example, depending on your shell:
% setenv GEMSTONE InstallDir/GemStone64Bit3.3.1-i386.Darwin
$ GEMSTONE=InstallDir/GemStone64Bit3.3.1-i386.Darwin
$ export GEMSTONE
2. Invoke the script gemsetup. For example, depending on your shell:
% source $GEMSTONE/bin/gemsetup.csh
$ . $GEMSTONE/bin/gemsetup.sh
3. If you will use GemStone frequently, consider adding to your login shell’s initialization file (.cshrc or .profile) the environment variable GEMSTONE and the command gemsetup. This way, the GemStone environment is automatically configured every time you log in or create a login shell.
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.
What Next?
This chapter has guided you through installation of GemStone/S 64 Bit 3.3.1 in an initial configuration that is sufficient to create a basic repository and begin setting up user accounts. The objective has been to get a simple, default configuration up and running.
You might consider performing the following tasks:
- To modify the initial object server configuration to one that is more efficient for your particular needs, refer to Chapter 1 of the System Administration Guide. This chapter describes in detail the many options for configuring your system.
- To modify the configuration of Gem session processes and to ensure that users have the necessary permissions to access the shared page cache and the extents, refer to Chapter 2 of the System Administration Guide.
- Chapter 3 of the System Administration Guide has additional information about setting up distributed configurations.
- To start and stop the GemStone object server, refer to instructions in Chapter 4 of the System Administration Guide.