1. Installing GemStone/S 64 Bit Version 3.5.3

Next chapter

This chapter describes the procedure for installing GemStone/S 64 Bitâ„¢ version 3.5.3. We recommend that you set up GemStone initially on a single machine, to ensure that all the pieces work together. At the end of this chapter, we suggest refinements you might want to make. 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 as described in this chapter.

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.

Platform

  • System with an x86_64-compatible processor.

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.

Total swap space should be at least equal to the amount of RAM. Due to the way GemStone uses memory, systems with insufficient swap space allocated have a risk of memory errors even if there is available RAM.

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.

Operating system

  • Red Hat Linux ES 8.1
    kernel version 4.18.0-193.6.3.el8_2.x86_64 and glibc-2.28-101.el8.x86_64
  • Red Hat Linux ES 7.6
    kernel version 3.10.0-693.11.6.el7.x86_64 and glibc-2.17-292.el7.x86_64
  • Red Hat Linux ES 6.9
    kernel version 2.6.32-696.18.7.el6.x86_64 and glibc-2.12-1.209.el6_9.2.x86_64
  • Ubuntu 20.04 LTS
    kernel version 5.4.0-42-generic and glibc 2.31-0ubuntu9
  • Ubuntu 18.04 LTS
    kernel version 4.15.0-65-generic and glibc 2.27-3ubuntu1
  • Ubuntu 16.04 LTS
    kernel version 4.4.0-97-generic and glibc 2.23-0ubuntu9

Debugger

  • Red Hat Linux ES 8.1: gdb 8.2-11
  • Red Hat Linux ES 7.6: gdb 7.6.1-100
  • Red Hat Linux ES 6.9: gdb 7.2-92
  • Ubuntu 20.04 LTS: gdb 9.1
  • Ubuntu 18.04 LTS: gdb 8.2.50
  • Ubuntu 16.04 LTS: gdb 87.11.1

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 the debugger be installed.

C/C++ Compiler

  • Red Hat Linux ES 8.1: gcc/g++ 8.3.1
  • Red Hat Linux ES 7.6: gcc/g++ 4.8.5
  • Red Hat Linux ES 6.9: gcc/g++ 4.4.7
  • Ubuntu 20.04 LTS: gcc/g++ 9.3.0
  • Ubuntu 18.04 LTS: gcc/g++ 7.5.0
  • Ubuntu 16.04 LTS: gcc/g++ 5.4.0

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.

X Windows

An X Windows server allows you to use GemStone’s graphical VSD application on Linux. 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.

1. Shared memory

The upper limit for shared memory single segment size and total usage should be set to values larger than your desired Shared Page Cache size, and not more than 75% of your real memory size.

The single segment maximum size, shmmax, is set in bytes, and the total shared memory limit, shmall, is configured in pages, with a base page size of 4KB. Note that the results of ipcs may be reported in kbytes.

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

8192 MB * .75 = 6144 MB
6144 MB * 220 = 6442450944 bytes
6442450944 / 4K = 1572864

To set shared memory sizes, you would append the following text to the /etc/sysctl.conf file. The settings are read from this file during the boot process.

# Shared Memory setting for GemStone
kernel.shmall = 1572864
kernel.shmmax = 6442450944

For more details, consult your Linux operating system documentation.

2. Semaphores

You may need to increase the settings for semaphores. These settings are configured by setting kernel.sem to a 4-element array, with the equivalent to the old semmsl, semmns, semopm, and semmni. For example, append the following to the /etc/sysctl.conf file.

kernel.sem=1000 512000 64 2048

The first element sets the maximum number of semaphores per id (per semaphore set). This parameter 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 must provide two semaphore 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.

The second value sets the total number of semaphores in the system, which must be increased to along with the first.

3. File Descriptors

Each user session requires two file descriptors, and others are needed for extents, transaction logs, and other overhead. The default setting for fs.file-max setting is usually sufficient.

4. Locking the Shared Page Cache in memory

If you intend to lock the shared page cache into memory via the stone configuration option SHR_PAGE_CACHE_LOCKED, then the linux user starting the stone must either have the Linux capability CAP_IPC_LOCK, or have a RLIMIT_MEMLOCK resource limit set greater than the size of the SPC.

5. OOM Killer

If your system runs low on memory, the Linux OOM killer may select GemStone processes to terminate. To protect the shared page cache and other critical GemStone processes, each GemStone process’s oom_score_adj, which is used to select processes to terminate, is adjusted. If the userid that will be running the server processes has the CAP_SYS_RESOURCE privilege, critical GemStone processes have their oom_score_adj reduced, making them safer; if the user does not have CAP_SYS_RESOURCE, then non-critical processes such as Gems have their score increased, so they will be selected rather than more critical processes.

To set CAP_SYS_RESOURCE on kernels v2.6.32 and later, set the capability on the executables:

a. Install libcap2-bin

b. for i in pgsvrmain gem stoned shrpcmonitor; do sudo setcap cap_sys_resource=pe $GEMSTONE/sys/$i ; done

c. for i in startstone topaz; do sudo setcap cap_sys_resource=pe $GEMSTONE/bin/$i ; done

6. 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 files under the directory /etc/pam.d. Alternatively, they can be lines in the configuration file /etc/pam.conf, but this usage is deprecated on many distributions. On these distributions, the presence of the /etc/pam.d directory will cause /etc/pam.conf to be ignored.

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/pam.d/gemstone.gem with the following contents:

auth	required	pam_ldap.so

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

auth	required	pam_ldap.so

Red Hat, by default, installs a file /etc/pam.d/other which disables “other” authentication. On Ubuntu, it is enabled by default. You can allow the “other” authentication stack to be used for GemStone authentication by ensuring that the file /etc/pam.d/other has the following contents:

auth	required	pam_ldap.so

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

7. Transparent Huge Memory Pages

The default size for memory pages on Linux is 4KB. Linux supports 2MB and 1GB Huge Pages; this document, and GemStone code, refers to these page sizes and all larger-than-default memory pages using the generic term large pages. Using large pages will improve performance for large repositories with large shared page caches.

On Linux, you may explicitly allocate Huge Pages to an application, which allows you to ensure that GemStone will be using these pages; this is described in the next section, Huge Memory Pages.

The Linux kernel (in versions later than 2.6.38) also supports transparent huge pages, which are 2MB in size (/sys/kernel/mm/transparent_hugepage/hpage_pmd_size returns 2097152). Transparent huge pages are limited to anonymous memory regions. If they are enabled (they are by default), transparent huge pages are managed by the kernel without application level configuration.

Linux systems should ensure:

  • /sys/kernel/mm/transparent_hugepage/enabled
    should be set to "always" or "madvise".
  • /sys/kernel/mm/transparent_hugepage/defrag
    should be set to "always" or "madvise".
  • /sys/kernel/mm/transparent_hugepage/shmem_enabled
    should be set to "madvise", "within_size", or "always".

To confirm these settings are correct in your Linux environment, cat the file; the enabled parameter is within the square brackets. E.g.,

unix> cat /sys/kernel/mm/transparent_hugepage/enabled
always [madvise] never

To confirm that GemStone is using transparent huge pages, after GemStone has been started up, execute:

cat /proc/shrpcmonPid/smaps

and look for the /SYSV line, and the subsequent value for ShmemPmdMapped. Note that this command is expensive, and should not be run unnecessarily.

8. Huge Memory Pages

Linux supports explicit configuration for 2MB and 1GB large pages (on Linux, Huge Pages), as well as transparent large pages (as described in the previous section).

A Linux installation may be configured to support either 2MB and 1GB large pages, or both. Using large pages may improve performance for large repositories with large shared page caches; by explicitly configuring large pages, they are allocated on boot and the GemStone executable can be explicitly configured to use them.

To use explicitly configured large pages, you must determine the huge page size and the number of huge pages needed, configure Linux to allocate the required number of pages, and configure GemStone to use large pages.

To configure the use of large pages:

a. Determine pages sizes available on your Linux system, and decide on the size you intend to use. Smaller repositories may use 2MB pages, but repositories with multi-GB shared page cache sizes may benefit more from 1GB pages.

To determine the default huge page size, execute:

unix> grep -e '^Huge' /proc/meminfo

which reports, for example,

   HugePages_Total:    5000
   HugePages_Free:     2756
   HugePages_Rsvd:        0
   HugePages_Surp:        0
   Hugepagesize:       2048 kB

To determine if you have another page size available, execute:

unix> ls /sys/kernel/mm/hugepages/

If you have 2MB pages, it will return:

   hugepages-2048kB

If you have both 2MB and 1GB pages, it will report:

   hugepages-1048576kB  hugepages-2048kB

b. Determine the number of huge pages that will be needed, based on your GemStone configuration. This is calculated by the utility largememorypages. This utility needs several details to compute the number of required pages: the shared page cache size, the maximum number of GemStone processes, and the number of shared counters. These can be provided by arguments or read from an existing configuration file.

largememorypages [-e path ] [-z path] [-F cacheFrames | -M cacheKB]
  [ -P maxProcesses] [-C maxSharedCounters] [-p largeMemoryPageSize]

You may specify the required values using a valid configuration file. This is parsed as a Stone configuration file and the necessary values extracted.

-e path
specifies an executable config file (same as startstone -e).

-z path
specifies a system config file (same as startstone -z).

If a config file is not specified, then -M or -F and -P and -C are required. These arguments can be used in addition to the configuration file, in which case they override values set or computed in the configuration file:

-F cacheFrames
shared cache size expressed in 16 KB frames

-M cacheKB
shared cache size with a optional units suffix.

-P maxProcesses
setting for SHR_PAGE_CACHE_NUM_PROCS

-C maxSharedCounters
setting for SHR_PAGE_CACHE_NUM_SHARED_COUNTERS.

-p largeMemoryPageSize
setting for SHR_PAGE_CACHE_LARGE_MEMORY_PAGE_SIZE_MB. Optional; the default is 2MB, may also specify 1 GB (or equivalent using appropriate units).

The following example is for an (approximately) 20GB shared page cache, 200 processes, and 1900 shared counters, with 2 MB memory pages:

unix> largememorypages -p 2MB -M 20GB -C 1900 -P 200
Cache config is 1310784 pages = 20481 MB,  total is 21384 MB,  overhead 4% of configured size
Large page size requested is: 2 MB.
Large page overhead: 0.11 MB
For 1310784 pages, 200 processes and 1900 shared counters, 10 pusherThreads
  minimum sizing for cache shmmax 22422749184, shmall 5474304.
Number of 2 MB large pages required: 10692
<with further update commands>

c. Configure Linux to use large pages, according to the instructions for your Linux distribution. You must execute these as root.

(1) Edit /etc/sysctl.conf to add or update the following lines.

kernel.shmmax=requiredCacheSize
kernel.shmall=requiredCacheSizeIn4kPages

For the above example above, the actual values would be:

kernel.shmmax=22422749184
kernel.shmall=5474304

Note that the numeric values set in sysctl.conf may be larger than, but not smaller, than these values.

(2) Delete or comment out any lines that contain 'vm.nr_hugepages'

(3) Edit the file /etc/default/grub, to append the following to the GRUB_CMDLINE_LINUX_DEFAULT entry:

"hugepagesz=1G hugepages=0 hugepagesz=2M hugepages=10692 default_hugepagesz=2M"

(4) Run the command to update the kernel config.

On Ubuntu:

unix> /usr/sbin/update-grub

On Red Hat and Centos:

unix> /usr/sbin/grub2-mkconfig -o /boot/grub2/grub.cfg

On Red Hat and Centos UEFI systems:

unix> /usr/sbin/grub2-mkconfig -o /boot/efi/EFI/centos/grub.cfg

(5) Reboot the system:

unix> shutdown -r now

d. Give the shared page cache monitor permission to allocate large memory pages, by executing:

unix> setcap cap_ipc_lock=pe $GEMSTONE/sys/shrpcmonitor

If the above process fails, alternatively the SPC monitor process can be run with an effective user ID of root:

unix> chown root $GEMSTONE/sys/shrpcmonitor 
unix> chmod u+s $GEMSTONE/sys/shrpcmonitor 

e. Configure GemStone to request large pages by set the configuration option SHR_PAGE_CACHE_LARGE_MEMORY_PAGE_POLICY. This can be set to 1 or 2; with a setting of 1, the cache will be started anyway if the request for large pages is denied, while a setting of 2 indicates that startup should fail if large pages cannot be allocated.

If you are using 1GB pages, you will also need to update the setting for SHR_PAGE_CACHE_LARGE_MEMORY_PAGE_SIZE_MB. By default, this is set to 2; if you are using 1GB pages, set this to 1024.

9. 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.

10. 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.

11. Unset LD_BIND_NOW

On some Linux distributions, setting the environment variable LD_BIND_NOW may result in process startup failures due to loading incorrect shared libraries.

Install the GemStone Server

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, these are the portions of the system that are affected by the installation of GemStone:

/dev/raw
Optional raw partitions for repository extents and transaction logs.

/etc/services
Internet services database, for NetLDI name lookup.

/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 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.:

unix> cat /proc/swaps

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.5.3-x86_64.Linux.zip. Move this distribution file to the directory location in which GemStone will be installed, InstallDir.

5. Unzip the distribution file using unzip.

6. The InstallDir now contains a GemStone directory with a name similar to GemStone64Bit3.5.3-x86_64.Linux.

In addition to 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.

The GemStone server is now installed.

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.5.3-x86_64.Linux

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:

  • 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

Licensed Customer key file

You may use a keyfile from any v3.5.x version with v3.5.3; keyfiles from 3.4.x and earlier are not valid with v3.5.3. If you are upgrading from v3.4.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 custom keyfile, this starter keyfile will be used instead.

Installing a keyfile

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.5.3 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.

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:

> /bin/ping 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.5.3.

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.5.3

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

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.

1. Log in 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:

 unix> cd $GEMSTONE/install
 unix> ./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.

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.

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

Allow NetLDI to Run 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.
  • 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?

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?

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 (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.

Complete GemStone Configuration

The following should be done by an administrative user, not as root.

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.5.3 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.5.3 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:

unix> export GEMSTONE=installdir
unix> export PATH=$GEMSTONE/bin:$PATH
unix> 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.

Further Configuration and Administration

This chapter has guided you through installation of GemStone/S 64 Bit 3.5.3, 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.5.3; and Chapter 5 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.

Next chapter