1. Installing GemStone/S 64 Bit Version 3.7 using RPM

Next chapter

This chapter describes the procedure for installing GemStone/S 64 Bitâ„¢ version 3.7, using the RPM (Red Hat Package Manager) installation process.

For new users, 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.

When upgrading, note that if your existing application relies on files in $GEMSTONE/data/, including the system.conf file, or use $GEMSTONE/ualib for User Action libraries, you must make changes in your configuration for the RPM environment. In an RPM installation, GemStone repositories should not write to the $GEMSTONE directory tree. You will need to define a new directory, move any files to this location, and replace references in configuration files and application code.

Installation using RPM is a recent capability for GemStone software. The specific installation details and recommendations in this document may not be final. Contact GemTalk Technical Support if you have issues or questions.

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. Additional system resources may be necessary to support large applications.

Platform

  • Intel x86_64 CPU with architecture Sandy Bridge or newer (excluding Atom CPUs)
  • AMD x86_64 CPUs with architecture Bulldozer version 1 or newer

GemStone/S 64 Bit v3.7 will not run on x86_64 CPUs older than listed. GemStone/S 64 Bit v3.7 was built using compilation features that are not available on older CPUs; v3.7 cannot run on these CPUs, regardless of the Linux OS version.

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 for GemStone/S 64 Bit, and additional space for other products.
  • Additional disk space as required for your repository.
  • ext4, XFS, and ZFS are supported; XFS or ZFS filesystem should be used in preference to ext4. Extent files cannot be accessed via CIFS, and NFS requires special configuration.
  • 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-compatible Linux ES 9.2 on x86_64
    kernel version 5.14.0-284.11.1.el9_2.x86_64 and glibc-2.34-60.el9.x86_64
  • Red Hat-compatible Linux ES 8.7 on x86_64
    kernel version 4.18.0-425.3.1.el8.x86_64 and glibc-2.28-211.el8.x86_64
  • Red Hat-compatible Linux ES 7.9 on x86_64
    kernel version 3.10.0-1160.71.1.el7.x86_64 and glibc-2.17-326.el7_9.x86_64

GemStone performs testing on a mixture of Red Hat, CentOS, Rocky and Alma servers; these are all considered fully certified platforms. Any reference to Red Hat applies to any Red Hat-compatible distribution.

Note that you must also have a supported CPU; GemStone/S 64 Bit v3.7 will not run on CPUs older than listed under Platform.

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.

  • Red Hat-compatible Linux ES 9.2: gdb 10.2
  • Red Hat-compatible Linux ES 8.7: gdb 9.1
  • Red Hat-compatible Linux ES 7.9: gdb 9.1

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.

  • Red Hat-compatible Linux ES 9.2: gcc/g++ 11.3.1
  • Red Hat-compatible Linux ES 8.7: gcc/g++ 8.5
  • Red Hat-compatible Linux ES 7.9: gcc/g++ 4.8.5

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

Modern Linux installations default to settings that support most GemStone configurations; there is no longer a need to set kernel.shmall, kernel.shmmax, kernel.sem, or fs.file-max. The default limits on modern Linux kernels are sufficiently large even for very large GemStone configurations.

1. Locking the Shared Page Cache in memory

It is recommended that you have sufficient memory to avoid the need to swap to disk. If there is the risk of swapping, you can avoid problems with GemStone performance (at the expense of other processes running on this machine) by locking the shared page cache into memory. Locking the cache into memory is configured by the parameter SHR_PAGE_CACHE_LOCKED.

If you are using huge pages (Consult your System Administrators for more information on how authentication is handled on your system.), the cache is inherently locked, so there is no further action needed.

Locking the cache into memory requires that the user starting GemStone has permission to lock the amount of memory required by the cache. There are several ways to do this.

  • Edit /etc/security/limits.conf to give the administrative user permission to lock larger memory segments:
   gsAdminUser soft memlock sizeInKB
   gsAdminUser hard memlock sizeInKB

Note that after editing this file, you do not need to reboot, but you will need a new shell.

  • While not recommended for security reasons, you may give the Shared Page Cache Monitor executable the Linux capability CAP_IPC_LOCK.
os$os$ setcap cap_ipc_lock=pe $GEMSTONE/sys/shrpcmonitor 

Note that setting this capability will prevent statmonitor and gdb from attaching to shrpcmonitor; statmonitor will not be able to record certain process statistics, and pstack cannot get C stack traces. See statmonitor additional permission.

2. 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, the process’s oom_score_adj, which is used to select processes to terminate, is reduced, making them less likely to be selected and killed.

Reducing the oom_score_adj requires configuring the process to have that capability. To set the capability on the required executables:

os$ setcap cap_sys_resource=pe $GEMSTONE/sys/stoned 
os$ setcap cap_sys_resource=pe $GEMSTONE/sys/pgsvrmain 

Only the Stone and pgsvrmain executables need the capability; other critical processes spawned by the Stone, such as the Shared Page Cache Monitor, inherit the Stone’s protection and adjust their oom_score_adj, and therefore also are protected. The capability is dropped as soon as the oom_score_adj has been updated.

Likewise, the pgsvrmain, which is responsible for spawning critical processes for distributed configurations with remote caches, protects processes such as the remote cache.

To examine the oom_score_adj for a process, check the file:

os$ cat /proc/pid/oom_score_adj 
3. Transparent Huge Memory Pages

The default size for memory pages on Linux/x86 is 4KB. Linux/x86 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.

The Linux kernel allows you to explicitly reserve 2MB or 1GB large pages for a specific application (such as GemStone), and also allows you to take advantage of 2MB transparent large pages, which are managed automatically without application level configuration.

Specifically allocated large memory pages are described in the next section, Consult your System Administrators for more information on how authentication is handled on your system..

Transparent huge pages are limited to anonymous memory regions. If they are enabled (they are enabled by default), transparent huge pages are managed by the kernel without application level configuration.

In general we recommend settings of "madvise" or "advise", which allow GemStone to use transparent huge pages. Settings of "always" will allow GemStone to use transparent huge pages, but may affect overall performance either positively or negatively.

Linux systems should ensure:

  • /sys/kernel/mm/transparent_hugepage/enabled
    should be set to "madvise".
  • /sys/kernel/mm/transparent_hugepage/defrag
    should be set to "madvise".
  • /sys/kernel/mm/transparent_hugepage/shmem_enabled (on all except some older OS versions)
    should be set to "advise".

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

os$ 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:

os$ cat /proc/pid/smaps

and look for the /SYSV line, and check that the subsequent value for ShmemPmdMapped is nonzero.

4. Huge Memory Pages

Linux supports explicit configuration for 2MB and 1GB large pages that are specifically reserved for an application, as well as transparent large pages (as described in the previous section).

A Linux installation may be configured to use 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 page size and the number of pages needed, configure Linux to allocate the required number of pages, and configure GemStone to use these pages.

To configure the use of large pages:

a. Determine the Linux Page Size

From the page sizes that are available on your Linux system, you must 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:

os$ 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:

os$ 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 required number of Linux Pages

Calculate 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. When using a configuration file, the file must have large memory pages (SHR_PAGE_CACHE_LARGE_MEMORY_PAGE_POLICY) enabled, and page size (SHR_PAGE_CACHE_LARGE_MEMORY_PAGE_SIZE_MB) set, if the calculated default page size is not correct.

The largememorypages computation by default is for the Stone’s cache. When configuring large pages for remote cache, the values are somewhat smaller. Use the -r option to compute large page requirements for a remote cache.

You may specify the required values using an existing configuration file, or by passing in the relevant values as argument. A configuration file is parsed as a Stone configuration file and the necessary values extracted; the configuration file must have large memory pages enabled.

If a configuration file is not specified, then -M or -F, and -p, -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:

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

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

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

-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. Options are 2MB and 1GB (or equivalent using appropriate units).

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

os$ largememorypages -p 1GB -M 20GB -C 1900 -P 200
Cache kind is: Primary SPC (stone shared page cache)
Cache config is 1373248 pages = 21457 MB,  total is 22528
MB,  overhead 4% of configured size
  HashTableSize 2097152 TotalPces 3483008 freeListPces 1385856
Large page size requested is: 1024 MB.
Large page overhead: 0.09 MB
[Info]: Increasing number of pages from 1310720 to 1373248
to reduce large memory page overhead.
For 1373248 pages, 200 processes and 1900 shared counters, 0 pusherThreads
  minimum sizing for cache shmmax 23622320128, shmall 5767168.
Number of 1024 MB large pages required: 22
<with further update commands>

c. Allow large memory pages to be allocated and accessed by GemStone processes

To ensure processes have permission to use large memory pages, you need to do one of the following. You must execute these commands as root.

  • Define a huge pages group.

Select or create a group that includes the Linux user that will be starting up the shared page cache, and all users who will be accessing the shared page cache

Then create a file /etc/sysctl.d/64-gemstone-local.conf, to set this group’s numeric id; add the line:

vm.hugetlb_shm_group = numericGidOfGroup

To determine the group id based on the group name, execute

os$ getent group nameOfGroup

This will take effect on reboot; you can apply immediately by executing:

os$ sysctl --system

To verify the current value, cat /proc/sys/vm/hugetlb_shm_group, which will show the group id. To enable large pages transiently without rebooting, you can set the gid of the group directly in /proc/sys/vm/hugetlb_shm_group. This will be reset on reboot if not configured as by /etc/sysctl.d/64-gemstone-local.conf.

  • While not recommended for security reasons, you may instead give the Shared Page Cache Monitor the cap_ipc_lock capability:
os$ setcap cap_ipc_lock=pe $GEMSTONE/sys/shrpcmonitor

Setting this capability will prevent statmonitor and gdb from attaching to that process; statmonitor will not be able to record certain process statistics, and pstack cannot get C stack traces. See statmonitor additional permission.

d. Configure large pages on Linux

Linux must be configured according to the instructions for your Linux distribution. You must execute these commands as root.

(1) To enable hugepages, the file /etc/default/grub needs to contain an entry for GRUB_CMDLINE_LINUX_DEFAULT that defines the number of 2MB and 1 GB huge pages.

Edit the file /etc/default/grub, to append a line defining the number of each size of pages to the GRUB_CMDLINE_LINUX_DEFAULT entry, for example to configure with 1GB pages to support the 20GB cache in the above example:

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

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

On Ubuntu:

os$ /usr/sbin/update-grub

On Red Hat and CentOS:

os$ /usr/sbin/grub2-mkconfig -o /boot/grub2/grub.cfg

On Red Hat and CentOS UEFI systems:

os$ /usr/sbin/grub2-mkconfig -o /boot/efi/EFI/centos/grub.cfg

(3) Reboot the system:

os$ shutdown -r now

e. Configure GemStone to use large pages

To configure GemStone to request large pages, 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.

Setting SHR_PAGE_CACHE_LARGE_MEMORY_PAGE_SIZE_MB to 2 (for 2 MB) or 1024 (for 1GB) is recommended; otherwise, the default is based on the current configuration of 1 GB, 2 MB, and/or the Linux default huge page size.

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

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

7. 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 OS default may not be appropriate for your system. For further information, refer to your operating system documentation.

8. /etc/systemd/logind.conf must disable RemoveIPC

To avoid Stone shutdown when the session that started the Stone logs out, ensure that

/etc/systemd/logind.conf

includes the line

RemoveIPC=no

With the default value of yes, when the session that started the Stone logs out, the Stone's shared semaphore array is deleted, causing fatal errors.

9. statmonitor additional permission

If you are running with the NetLDI owned as root with the s bit set, then statmonitor running as an ordinary user, including as the administrative user, will not be able to collect certain memory statistics for Gems started by other users.

  • You can enable statmonitor to still collect these statistics by giving it cap_sys_ptrace.
os$ setcap cap_sys_ptrace=pe $GEMSTONE/bin/statmonitor
  • Alternatively, statmonitor can be run as root with s bit set:
os$ cd $GEMSTONE/sys
os$ chown root $GEMSTONE/bin/statmonitor
os$ chmod u+s $GEMSTONE/bin/statmonitor

If you have set the Linux capacity cap_ipc_lock for shrpcmonitor, for huge pages or locking (this is permitted but not recommended), statmonitor will not be able to collect memory statistics for the shared page cache monitor, and the above workarounds may ba applied. The cap_sys_resource capability, for OOM protection, is dropped after the process has adjusted its oom_score_adj, and is not an issue.

10. 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 using RPM installs under /usr/lib64, as root user. This installation differs from the historic installation of GemStone from zipped distributions.

The defaults that GemStone provides for configuration and utilities, and many examples provided in documentation, assume a writable $GEMSTONE/data directory, which contains the system-wide configuration file and process log files. The default installation also places the repository extent files and transaction logs in this location. While convenient for new users and small examples, this has never been a recommended configuration for enterprise-level GemStone production environments.

These default assumptions are not valid for an RPM installation, since this installs GemStone in a location that is expected to be shared and write-only, and the Stone’s primary configuration file must be writable.

Instead, after installing the product tree, you will need to define directories to contain your extents, configuration files, and other important GemStone files.

Install the GemStone Product

1. Log in as root.

2. Perform the installation.

os$ rpm -i GemStone64-3.7.0-1.x86_64.rpm

The RPM will install the GemStone product tree to the following locations:

/usr/lib64/gemstone/3.7.0

3. The GemStone server product is now installed in /usr/lib64/gemstone/3.7.0.

In addition to subdirectories, this directory also contains the text files version.txt, which identifies this particular product and release of GemStone, and externals.sha.txt, which lists shas for external projects included in this version.

Note that with an RPM installation, do not run the installgs executable. The options in that script are not appropriate for an RPM installation.

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

Keyfiles for GemStone version 3.6.x and earlier are not valid with v3.7. Licenced customers can email keyfiles@gemtalksystems.com or contact GemTalk Technical Support to request a keyfile for version 3.7 for their platform or platforms.

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.7 stone to include the location and name of the keyfile.

You may also put the keyfile in the default location, /usr/lib64/gemstone/3.7.0/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.

The keyfile should have read-only permissions.

Configure the 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.

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, or for new users, we recommend running in guest mode with captive account. This requires no further configuration of your GemStone installation.

If you will be running the NetLDI with authentication, and if multiple UNIX userIds will be logging into GemStone, then set the s bit for the $GEMSTONE/sys/netldid executable. This allows an administrative UNIX userId to start a NetLDI process that will run as root.

os$ chmod u+s $GEMSTONE/sys/netldid

Named NetLDI Service

The NetLDI can be specified by port number, or you may configure a named NetLDI service. Named NetLDIs must be defined in your system services database to resolve to a port number, on all nodes that will be using GemStone.

Using a port avoids this configuration, however you must select a port that will consistently be available.

Configuring a named NetLDI service

1. Determine whether a service for the NetLDI name, such as gs64ldi, 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

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

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 the Environment

Perform the following steps to properly configure the operating environment.

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

os$ export GEMSTONE=/usr/lib64/gemstone/3.7.0

If GemStone was previously installed, or more than one installation GemStone exists on this machine, check for existing GemStone environment variables:

os$ env | grep GEM

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

Create a GemStone repository

If you are upgrading from a previous version, you may return to the appropriate chapter of this installation guide for upgrade instructions.

The following steps apply if you are setting up a new GemStone repository.

Setup Extents and Configuration

Create a new directory or directories, or determine an existing directory or directories, for your repository extent files, transaction logs, and system log files.

In a simple configuration, this may be a single directory. For non-trivial applications, multiple directories are recommended. The following instructions provide the simplest possible setup. The System Administration Guide provides much more guidance on setting up a scalable, multi-user GemStone configuration.

Simple Installation

1. Create a directory to hold your extent files, stoneDataDirectory.

2. Copy $GEMSTONE/bin/extent0.dbf and $GEMSTONE/bin/gemstone_data.conf to stoneDataDirectory:

os$ cp $GEMSTONE/bin/extent.dbf stoneDataDirectory
os$ cp $GEMSTONE/bin/gemstone_data.conf stoneDataDirectory

3. chmod both files to have user and group write.

os$ chmod ug+w stoneDataDirectory/*

4. Start the stone, using -E to pass in the configuration file, stoneDataDirectory/gemstone_data.conf.

os$ startstone -E stoneDataDirectory/gemstone_data.conf

This will start the stone with the default name gs64stone.

5. Start the NetLDI. This example starts the NetLDI in guest mode with captive account.

os$ startnetldi -stoneDataDirectory/gemstone_data.conf -g -a adminUserName 

This will start the NetLDI with the default name gs64ldi. The -E argument to startnetldi is optional; it allows RPC Gems started by the NetLDI to use the same configuration file, but while Gems may use a configuration file, it is not required.

Your GemStone repository is now running and ready for users to log in.

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.

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.

Add GemStone User Accounts

While it is possible for users to login as DataCurator, DataCurator has broad permissions and is not recommended. In a multi-user system, each users should have a 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.

Each user should:

  • Set the environment variable GEMSTONE to the full pathname (starting with a slash) of the GemStone/S 64 Bit 3.7 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:

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.

Further Configuration and Administration

This chapter has guided you through installation of GemStone/S 64 Bit 3.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.7.

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