2. Setting up a new Repository
This chapter describes how to setup a new GemStone repository.
For new users, we recommend that you create a GemStone repository initially on a single machine, to ensure that all the pieces work together. Chapter 1 of the System Administration Guide provides an introduction to GemStone, and this manual provides details on setting up configurations to meet specific application requirements.
Set up a new Repository
There are many ways to set up a GemStone repository, depending on your system requirements.
The repository setup instructions in this Chapter describes setting up a basic repository, suitable for a single user, or a small system with low security requirements.
Multi-user systems and system with stringent security requirements will need special configuration to allow multiple users to login and access the database while ensuring unauthorized users cannot access or modify data. Large or high-volume repositories require separation of the extents holding data, the transaction logs holding the records of changes, and the log files.
The options for setting up a GemStone repository that is optimized for larger, higher-volume, highly trackable and maintainable, and for more highly secure repositories are described in the System Administration Guide. Please consult GemTalk Technical Support for additional assistance.
The historic installgs utility, described under Repository configuration using legacy installgs, performs both configuration and also offers to setup a new repository. While this script is valuable for some securityconfigurations, it is not a recommended way to setup a repository.
Simple Data-conf repository setup using createNewGemStoneRepository
A Data-conf installation is a repository configuration in which all the repository-specific files are located in a single directory (one that is not within the GemStone distribution directory), and a specific configuration file, gemstone_data.conf, is used as the -E argument to GemStone processes.
While convenient for new users and small examples, this is not a recommended configuration for enterprise-level GemStone production environments. The System Administration Guide provides much more guidance on setting up a scalable, multi-user GemStone configuration.
The special configuration file gemstone_data_conf, makes setup of this environment easy. The Stone, NetLDI, and linked topaz startup commands use -E to specify this configuration file.
To set up a Data-conf repository, use the script createNewGemStoneRepository, passing in an argument of the path to your desired repository root directory. This directory must not exist or be empty, and the path must be writable.
For example, to create a new repository directory under the existing directory /gshost/, with the directory name testGS, do the following:
1. Create the repository using the script:
os$ $GEMSTONE/install/createNewGemStoneRepository /gshost/testGS
This will printout commands to start the Stone and NetLDI.
2. Start the stone, passing in the configuration file using the -E argument.
os$ startstone -E /gshost/testGS/gemstone_data.conf
This will start the stone with the default name gs64stone.
3. Start the NetLDI. This example starts the NetLDI in guest mode with captive account.
os$ startnetldi -g -a gsAdminUser
os$ startnetldi -E /gshost/testGS/gemstone_data.conf -g -a gsAdminUser
This will start the NetLDI with the default name gs64ldi. The -E argument to startnetldi is optional; it is only useful if you have other configuration file customizations that apply to Gem sessions.
Simple classic repository setup in data directory
The classic GemStone Installation uses the $GEMSTONE/data directory for all repository-specific files. This includes the extent file and the system configuration file system.conf, and in which the server log files and transaction logs are written.
While convenient for new users and small examples, this is not a recommended configuration for enterprise-level GemStone production environments. The System Administration Guide provides much more guidance on setting up a scalable, multi-user GemStone configuration.
The distribution installation is setup for this configuration; all that is needed is to copy an extent into the data directory.
1. Copy $GEMSTONE/bin/extent0.dbf to $GEMSTONE/data/.
os$ cp $GEMSTONE/bin/extent.dbf $GEMSTONE/data/
2. chmod the extent file to have user and group write.
os$ chmod ug+w $GEMSTONE/data/extent0.dbf
os$ startstone
This will start the stone with the default name gs64stone.
4. Start the NetLDI. This example starts the NetLDI in guest mode with captive account, using the default named gs64ldi.
os$ startnetldi -g -a gsAsminUser
Using a NetLDI by Port number
Without the nameOrPortNumber argument, the NetLDI will be started with the default name gs64ldi and a randomly selected port. If you have not defined gs64ldi (see Configure Services for a Named NetLDI), you may use a port number; this requires an additional argument.
os$ startnetldi -g -a gsAsminUser netldiNameOrPort
os$ startnetldi -g -a gsAsminUser 54321
Verifying your new repository by logging in
Verify your Stone and NetLDI by logging in with topaz, the command line environment. This verification is done on the same host as the stone, with the gemstone environment setup. You will need to set login parameters, and execute the topaz login command.
You should ensure that your envionment is setup as described here, that is, with the GEMSTONE environment and path set up.
os$ export GEMSTONE=InstallDir/GemStone64Bit3.7.2-platform
os$ export PATH=$GEMSTONE/bin:$PATH
os$> topaz
<startup headers>
topaz> set stone gs64stone user DataCurator password swordfish
topaz> login
Configure and set up users in new repository
Users log into GemStone using a GemStone user account (UserProfile), which is distinct from the UNIX user account. Logging into GemStone normally requires first authentication for your unix userId, and then login to GemStone with the GemStone userId and password.
Note that there are ways to configure a streamlined authentication, as described in the The chapter entitled “User Accounts and Security” in the System Administration Guide.
Change Passwords for Administrative Accounts
GemStone comes with built-in administrative accounts, referred to as System accounts or System userProfiles. These accounts are used to perform system administration and maintenance operations.
- The DataCurator account is used to perform system administration tasks.
- The SystemUser account is ordinarily 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
The GemStone/S 64 Bit extents come with the time zone of 'America/Los_Angeles' installed as the default.
If you are in another time zone, login to GemStone as SystemUser and execute TimeZone installOsTimeZone to install the time zone configured in the OS, or TimeZone installNamedZone: to install another time zone by the zoneinfo (Olson) name.
You may also edit the file installtimezone.txt in the $GEMSTONE/upgrade directory, and file it in as SystemUser.
GemStone User Accounts
All users who log into GemStone should have a GemStone user account. While possible, it is not recommended to do development as DataCurator.
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 using topaz, or tools included the GemBuilder for Smalltalk (GBS) product. See the GemBuilder for Smalltalk Users’s Guide for information on the GUI tools in GBS.
Before login, Unix users should:
- Set the environment variable GEMSTONE to the full pathname (starting with a slash) of the GemStone/S 64 Bit 3.7.2 directory.
- Update their path to include the $GEMSTONE/bin directory.
- Optionally, update the man path (MANPATH variable) to include the $GEMSTONE/doc directory. GemStone provides man pages for utility functions.
os$ export GEMSTONE=InstallDir/GemStone64Bit3.7.2-platform
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 user’s login shell initialization file.