1.1 Configuration Overview
The Server Configuration File
Example Configuration Settings
Gemservers for Large Configurations
Recommendations About Disk Usage
Why Use Multiple Drives?
When to Use Raw Partitions
Developing a Failover Strategy
1.2 How To Establish Your Configuration
Gathering Application Information
Planning Operating System Resources
Estimating Server Memory Needs
Estimating Server Swap Space Needs
Estimating Server File Descriptor Needs
Reviewing Kernel Tunable Parameters
Checking the System Clock
/opt/gemstone/locks and /opt/gemstone/log
Host Identifier
GemStone shared libraries
To Set the Page Cache Options and the Number of Sessions
Shared Page Cache
Estimating the Size of the Shared Page Cache
Verifying OS support for sufficient Shared Memory
Stone’s Private Page Cache
Diagnostics
To Configure the Repository Extents
Estimating Extent Size
Choosing the Extent Location
Extent disk configuration
Setting a Maximum Size for an Extent
Pregrowing Extents to a Fixed Size
Pregrowing Extents to the Maximum Size
Allocating Data to Multiple Extents
Sequential Allocation
Weighted Allocation
Effect of Clustering on Allocation Mode
Weighted Allocation for Extents Created at Run Time
To Configure the Transaction Logs
Choosing a Logging Mode
Estimating the Log Size
Choosing the Log Location and Size Limit
To Configure Server Response to Gem Fatal Errors
To Set File Permissions for the Server
Using the Setuid Bit
Alternative: Use Group Write Permission
File Permissions for Files and Directories
How To Set Up a Raw Partition
Sample Raw Partition Setup
Changing Between Files and Raw Partitions
Moving an Extent to a Raw Partition
Moving an Extent to the File System
Moving Transaction Logging to a Raw Partition
Moving Transaction Logging to the File System
1.3 How To Access the Server Configuration at Run Time
To Access Current Settings at Run Time
To Change Settings at Run Time
1.4 How To Tune Server Performance
Tuning the Shared Page Cache
Adjusting the Cache Size
Matching Spin Lock Limit to Number of Processors
Clustering Objects That Are Accessed Together
Reducing Swapping
Controlling Checkpoint Frequency
Suspending Checkpoints
Tuning Page Server Behavior
To Add AIO Page Server threads
Free Frame Page Server
Process Free Frame Caches
1.5 How To Run a Second Repository
2.1 Overview
Linked and RPC Applications
The Session Configuration File
2.2 How To Configure Gem Session Processes
Estimating Session Memory Needs
Estimating Client Swap Space Needs
Estimating Session File Descriptor Needs
To Set Ownership and Permissions for Session Processes
Extents
To Set Access for Linked Applications
To Set Access for All Other Applications
To Set Access to Other Files
To Set Configuration for Remote Shared Page Caches
2.3 Set the Gem Configuration Options
Configure Temporary Object Space
Configure SSL for remote Gem sessions
2.4 How To Access the Configuration at Run Time
2.5 Tuning Gem Performance
Private Page Cache
Native Code
2.6 How To Install a Custom Gem
3.1 Overview
Distributed configuration with Local Gem
Distributed configuration with Remote Gem
GemStone NetLDIs
NetLDI Ports and Names
Stone and Shared Page Cache Monitor
GemStone Page Servers
GemStone Network Objects
Shared Page Cache in Distributed Systems
Disrupted Communications
3.2 NetLDI configuration and Network Security
Running as Root with Authentication
Setting host Username and Password
Authentication Levels
Default
Secure Mode
Running in Guest Mode with Captive Account
3.3 How To Use Network Resource Strings
To Set a Default NRS
3.4 Configuring GemStone on Remote Nodes
Local Gems only
Remote Gems
Configuration Examples
Determine if you will run RPC or Linked application
Set the environment
Configure NetLDI and authentication mechanism
RPC Application on a Remote Node with Local Gem
Linked Application on a Remote Node
RPC Application on a Remote Node with Remote Gem
RPC Application, Gem, and Stone on Three Nodes
Distributed System with a Mid-Level Cache
Connection Methods
Reporting Methods
3.5 Troubleshooting Remote Logins
How the Login Process starts Session Processes
RPC Application with Gem on Server Node
Linked Application on Remote Node
If You Still Have Trouble
Try Linked Topaz on the Server
Try Topaz RPC on the Server
Check NetLDI Log Files
4.1 Starting the GemStone Server
To Start GemStone
To Troubleshoot Stone Startup Failures
Missing or Invalid Key File
Shared Page Cache Cannot Be Attached
Extent Missing or Access Denied
Extent Open by Another Process
Extent Already Exists
Other Extent Failures
Transaction Log Missing
Other Startup Failures
4.2 Starting a NetLDI
To Troubleshoot NetLDI Startup Failures
4.3 Listing Running Servers
4.4 Starting a GemStone Session
To Define a GemStone Session Environment
To Start a Linked Session
To Start an RPC Session
To Troubleshoot Session Login Failures
4.5 Identifying and Stopping Logged-in Sessions
Stopping Logged-in Sessions
4.6 Shutting Down the Object Server and NetLDI
4.7 Recovering from an Unexpected Shutdown
Normal Shutdown Message
Disk Failure or File System Corruption
Shared Page Cache Error
Fatal Error Detected by a Gem
Some Other Shutdown Message
No Shutdown Message
4.8 Bulk-Loading Objects
4.9 Managing Large Repositories
Loading the object table at startup
Making efficient use of remote caches
Disk Space and Commit Record Backlogs
Handling signals indicating a commit record backlog
5.1 GemStone Process Logs
Finding log files
Stone Log
Log name and location
Log file deletion policy
Shared Page Cache Monitor Log
Admin Gem Log
Reclaim Gem Log
Free Frame Page Server Log
AIO Page Server Log
Page Manager Log
Symbol Gem Log
NetLDI Log
Gem Logs and logs related to Gem Sessions
Linked Gems
RPC Gems on Stone’s host
Remote RPC or Linked Gems
Controlling log file names and locations via NRS
“D” Pattern
Logsender and logreceiver Logs
Other Log Files
Summary of GemStone Process Log Behaviors
Managing log files
Retaining or deleting all log files
Customizing individual process deletion behavior
Localizing timestamps in log files
Programmatically adding messages to logs
5.2 Repository Page and Object Audit
Page Audit
Object Audit and Repair
Performing the Object Audit
Error Recovery
Collect and reclaim garbage and retry
Restore from backup
Manual repair of invalid object references
Repository repair
5.3 Profiling Repository Contents
5.4 Monitoring Performance
Statmonitor and VSD
Programmatic Access to Cache Statistics
Statistics by name
All statistics for a process
Setting the name for the Gem in the cache
Session Statistics
Global Session Statistics
Host Statistics
Host Statistics for processes
Host Statistics for OS
6.1 GemStone Users
UserProfiles
AllUsers
Special System Users
SystemUser
DataCurator
GcUser
SymbolUser
Nameless
6.2 Creating and Removing Users
UserProfile Data
User ID
Password
Default Object Security Policy
Privileges
Code Modification Privilege
Groups
AllGroups
Symbol Lists
Creating Users
Simple User Creation
Simple User Creation with GsObjectSecurityPolicy Creation
User Creation With Privileges, Groups, and ObjectSecurityPolicy
Removing Users
DeletedUserProfile and AllDeletedUsers
Remove User, with ObjectSecurityPolicies Going to the Current User
Remove User, with ObjectSecurityPolicies going to another User
6.3 Administering Users
List Existing Users
Modifying the UserId
Modifying Password
Users Changing Their Own Password
Changing Another User’s Password
Modifying defaultObjectSecurityPolicy
Determining Who Is Authorized to Read or Write in an Object Security Policy
Changing the Authorization of an Object Security Policy
Remove a Group from an Object Security Policy’s Authorization List
Change a User’s Default Object Security Policy
Modifying Groups
Examining Group Memberships
Adding a User to a Group
Removing a User from a Group
Listing Members of a Group
Removing a Group
Modifying Privileges
Examining a User’s Privileges
Adding a Privilege
Revoking a Privilege
Reassigning All Privileges
Modifying SymbolLists
Adding a SymbolDictionary to Your Own Symbol List
Adding a SymbolDictionary to Someone Else’s Symbol List
Removing a SymbolDictionary from Your Own Symbol List
Removing a SymbolDictionary from Someone Else’s Symbol List
Disable and Enable User Logins
Disable an Account Explicitly
Re-enable an Account
Find Out Which Accounts Have Been Disabled
Check If an Account Is Disabled
Find Out Why an Account Was Disabled
Disable and Enable Commits by User
Disable Commits
Re-enable Commits for a User
Check If a User Can Commit
6.4 Password Authentication
GemStone Authentication
UNIX Authentication
LDAP Authentication
UserId or Alias
Fully Qualified DN
Search for DN
LDAP authentication without anonymous binds
Validating passwords
Explicit mode
Search mode with anonymous bind
Search mode with authenticated bind
Determining an Account’s Authentication Scheme
6.5 Configuring GemStone Login Security
Limiting Choice of Passwords
Disallowing Particular Passwords
Disallowing Reuse of Passwords
Disallow All Previously Used Passwords
Disallow a Specific Number of Previous Passwords
Clearing a User’s Disallowed Old Passwords
Password Aging – Require Periodic Password Changes
Repository-Wide Password Aging
Password Age Limits for Individual Users
Repository-Wide Password Expiration Warning
Finding Accounts with Password About to Expire
Finding Out When a Password Was Changed
Account Aging – Disable Inactive Accounts
Repository-Wide Stale Account Aging
Per-User Stale Account Aging
Finding Out When an Account Last Logged In
Enabling Account Aging and lastLoginTime
Limit Logins Until Password Is Changed
Limit Concurrent Sessions by a Particular UserId
Limit Login Failures
Record Login Failures
Disabling Further Login Attempts
6.6 Tracking User Logins
Login logging
Login Hook
7.1 The Repository and Extents
Repository Growth
How To Check Free Space
7.2 Adding and Removing Extents
To Add an Extent While the Stone is Running
Possible Effects on Other Sessions
Repository>>createExtent:
Repository>>createExtent:withMaxSize:
To Remove an Extent
7.3 Reallocating Existing Objects Among Extents
To Reallocate Objects Among a Different Number of Extents
To Reallocate Objects Among the Same Number of Extents
7.4 Shrinking the Repository
7.5 Checking Page Fragmentation
7.6 Recovering from Disk-Full Conditions
Repository Full
8.1 Overview
Logging Modes
Restoring Transactions to a Backup
How the Logs Are Used
8.2 How To Manage Full Logging
To Archive Logs
To Add a Log at Run Time
To Force a New Transaction Log
To Initiate a Checkpoint
To Change to Partial Logging
8.3 How To Manage Partial Logging
To Change to Full Logging
8.4 How To Recover from Tranlog-Full Conditions
Transaction Log Space Full
9.1 Overview
Warm and Hot Standbys
Version Compatibility
9.2 Types of Backups
Full vs. Partial Transaction logging
Verify Backup Process
9.3 How To Make an Extent Snapshot Backup
Extent Snapshot Backup when the Repository is shutdown
Extent Snapshot Backup when the Repository is running
An Example Script
9.4 How To Make a Smalltalk Full Backup
The fullBackupTo: Methods
Backup fails to run or encounters an error
Monitoring and Performance
Shared Page Cache Size
Multi-threading
Cache Statistics
Backups and Garbage Collection
Compressed Backups
Verifying a Backup is Readable
Checking Backup Start and Completion
9.5 How to Restore from Backup
Restore Status
Restoring from an Extent Snapshot Backup
Restoring from a Full Backup
Controlling Reclaim Activity When Restore Completes
9.6 How to Restore Transaction Logs
9.7 Special Cases and Errors in Restore
Precautions When Restoring a Subset of Transaction Logs
Fork-in-Time Scenario
Restoring Logs up to a Specific Log
Restoring Logs to a Point in Time
Errors While Restoring Transaction Logs
Missing Transaction Log File
Truncated or Corrupt Transaction Log File
Recovering from File System Problems
10.1 Overview
10.2 Warm Standby
Setup and run the warm standby
Activate the warm standby in case of failure in the primary
10.3 Hot Standby
Precautions regarding tranlog sequences
Hot standby processes
logsender
logreceiver
Continuous Restore Mode
Transaction Record Transmittal
Multiple standby repositories
To setup and run the hot standby
Activate the hot standby in case of failure in the primary
Planned failovers
Connecting using SSL Mode
Self signed certificates
10.4 Tuning a Warm or Hot Standby
Tuning Reclaim
11.1 Memory Organization
11.2 Configuring Temporary Memory Usage
Configuration Options
Methods for Computing Temporary Object Space
Sample Configurations
Default Configuration
Larger old, Smaller pom
Smaller old Area, Larger pom
Debugging out-of-memory errors
Recording Out of Memory Information to CSV file
Signal on low memory condition
12.1 Basic Concepts
Different Types of Garbage
The Process of Garbage Collection
Live objects
Transitive closure
Dead objects
Shadow objects
Commit records
Commit record backlog
Shadow or Dead?
What Happens to Garbage?
Admin and Reclaim Gems
Admin and Reclaim Gem configuration parameters
GemStone’s Garbage Collection Mechanisms
Marking
Reclaiming
GcLock
Symbol Garbage Collection
12.2 MarkForCollection
Impact on Other Sessions
Scheduling markForCollection
12.3 Epoch Garbage Collection
Running Epoch Garbage Collection
Tuning Epoch
Epoch Configuration Parameters
Determining the Epoch Length
12.4 Reclaim
Reclaim Configuration Parameters
Reclaim Commit Frequency
Controlling the impact of reclaim
Speeding up reclaim
Avoiding disk space issues
12.5 Running Admin and Reclaim Gems
Configuring Admin Gem
Configuring Reclaim Gem
Starting GcGems
Stopping GcGems
Adjusting the number of Reclaim sessions
12.6 Further Tuning Garbage Collection
Multi-Threaded Scan
Tuning Multi-Threaded Scan
Memory Impact
Identifying Sessions Holding Up Voting
Tuning Write Set Union Sweep
Identifying Sessions Holding Up Page Reclaim
Finding large objects that are using excessive space
Identify Large Objects in the Repository
Finding References to an Object that prevent garbage collection
Full reference path
All References
A.1 How GemStone Uses Configuration Files
System Configuration File
Executable Configuration File
Creating or Using a System Configuration File
Creating an Executable Configuration File
Naming Executable Configuration Files
Application Gems
System Gems
Stone
Linked Topaz
Linked GemBuilder for Smalltalk (GBS)
Linkable GemBuilder for C Applications
Naming Conventions for Configuration Options
A.2 Configuration File Syntax
Errors in Configuration Files
Syntax Errors
Option Value Errors
Alternate ways to specify configuration parameter values
A.3 Configuration Options
CONFIG_WARNINGS_FATAL
DBF_ALLOCATION_MODE
DBF_EXTENT_NAMES
DBF_EXTENT_SIZES
DBF_PRE_GROW
DBF_SCRATCH_DIR
DUMP_OPTIONS
GEM_ABORT_MAX_CRS
GEM_FREE_FRAME_CACHE_SIZE
GEM_FREE_FRAME_LIMIT
GEM_FREE_PAGEIDS_CACHE
GEM_GCI_LOG_ENABLED
GEM_HALT_ON_ERROR
GEM_KEEP_MIN_SOFTREFS
GEM_MAX_SMALLTALK_STACK_DEPTH
GEM_NATIVE_CODE_ENABLED
GEM_PGSVR_COMPRESS_PAGE_TRANSFERS
GEM_PGSVR_FREE_FRAME_CACHE_SIZE
GEM_PGSVR_FREE_FRAME_LIMIT
GEM_PGSVR_UPDATE_CACHE_ON_READ
GEM_PGSVR_USE_SSL
GEM_PRIVATE_PAGE_CACHE_KB
GEM_READ_AUTH_ERR_STUBS
GEM_REPOSITORY_IN_MEMORY
GEM_RPCGCI_TIMEOUT
GEM_RPC_KEEPALIVE_INTERVAL
GEM_RPC_USE_SSL
GEM_STATMONITOR_ARGS
GEM_STATMONITOR_MID_CACHE_ARGS
GEM_SOFTREF_CLEANUP_PERCENT_MEM
GEM_TEMPOBJ_AGGRESSIVE_STUBBING
GEM_TEMPOBJ_CACHE_SIZE
GEM_TEMPOBJ_CONSECUTIVE_MARKSWEEP_LIMIT
GEM_TEMPOBJ_MESPACE_SIZE
GEM_TEMPOBJ_OOMSTATS_CSV
GEM_TEMPOBJ_OOPMAP_SIZE
GEM_TEMPOBJ_POMGEN_PRUNE_ON_VOTE
GEM_TEMPOBJ_POMGEN_SCAVENGE_INTERVAL
GEM_TEMPOBJ_POMGEN_SIZE
GEM_TEMPOBJ_SCOPES_SIZE
GEM_TEMPOBJ_START_ADDR
INCLUDE
KEYFILE
LOG_WARNINGS
SHR_NUM_FREE_FRAME_SERVERS
SHR_PAGE_CACHE_LARGE_MEMORY_PAGE_POLICY
SHR_PAGE_CACHE_LOCKED
SHR_PAGE_CACHE_NUM_PROCS
SHR_PAGE_CACHE_NUM_SHARED_COUNTERS
SHR_PAGE_CACHE_PERMISSIONS
SHR_PAGE_CACHE_SIZE_KB
SHR_SPIN_LOCK_COUNT
SHR_TARGET_FREE_FRAME_COUNT
SHR_WELL_KNOWN_PORT_NUMBER
STN_ADMIN_GC_SESSION_ENABLED
STN_ALLOCATE_HIGH_OOPS
STN_ALLOW_NFS_EXTENTS
STN_CACHE_WARMER
STN_CACHE_WARMER_SESSIONS
STN_CHECKPOINT_INTERVAL
STN_COMMIT_QUEUE_THRESHOLD
STN_COMMIT_RECORD_QUEUE_SIZE
STN_COMMIT_TOKEN_TIMEOUT
STN_COMMITS_ASYNC
STN_CR_BACKLOG_THRESHOLD
STN_DISABLE_LOGIN_FAILURE_LIMIT
STN_DISABLE_LOGIN_FAILURE_TIME_LIMIT
STN_DISKFULL_TERMINATION_INTERVAL
STN_EPOCH_GC_ENABLED
STN_EXTENT_IO_FLAGS
STN_FREE_FRAME_CACHE_SIZE
STN_FREE_SPACE_THRESHOLD
STN_GEM_ABORT_TIMEOUT
STN_GEM_LOSTOT_TIMEOUT
STN_GEM_TIMEOUT
STN_HALT_ON_FATAL_ERR
STN_LISTENING_ADDRESSES
STN_LOGIN_LOG_DIR
STN_LOGIN_LOG_ENABLED
STN_LOGIN_LOG_HALT_ON_ERROR
STN_LOGIN_LOG_MAX_SIZE
STN_LOG_IO_FLAGS
STN_LOG_LOGIN_FAILURE_LIMIT
STN_LOG_LOGIN_FAILURE_TIME_LIMIT
STN_LOOP_NO_WORK_THRESHOLD
STN_MAX_AIO_RATE
STN_MAX_AIO_REQUESTS
STN_MAX_GC_RECLAIM_SESSIONS
STN_MAX_LOGIN_LOCK_SPIN_COUNT
STN_MAX_REMOTE_CACHES
STN_MAX_SESSIONS
STN_MAX_VOTING_SESSIONS
STN_NUM_AIO_WRITE_THREADS
STN_NUM_GC_RECLAIM_SESSIONS
STN_NUM_LOCAL_AIO_SERVERS
STN_OBJ_LOCK_TIMEOUT
STN_PAGE_MGR_COMPRESSION_ENABLED
STN_PAGE_MGR_MAX_WAIT_TIME
STN_PAGE_MGR_PRINT_TIMEOUT_THRESHOLD
STN_PAGE_MGR_REMOVE_MAX_PAGES
STN_PAGE_MGR_REMOVE_MIN_PAGES
STN_PGSVR_PORT_RANGE
STN_PRIVATE_PAGE_CACHE_KB
STN_REMOTE_CACHE_PGSVR_TIMEOUT
STN_REMOTE_CACHE_STARTUP_TIMEOUT
STN_REMOTE_CACHE_TIMEOUT
STN_SHR_TARGET_PERCENT_DIRTY
STN_SIGNAL_ABORT_AGGRESSIVE
STN_SIGNAL_ABORT_CR_BACKLOG
STN_SMC_SPIN_LOCK_COUNT
STN_STATMONITOR_ARGS
STN_STONE_CACHE_STARTUP_TIMEOUT
STN_SYMBOL_GC_ENABLED
STN_SYMBOL_GEM_TEMPOBJ_CACHE_SIZE
STN_TRAN_FULL_LOGGING
STN_TRAN_LOG_DEBUG_LEVEL
STN_TRAN_LOG_DIRECTORIES
STN_TRAN_LOG_LIMIT
STN_TRAN_LOG_PREFIX
STN_TRAN_LOG_SIZES
STN_TRAN_Q_TO_RUN_Q_THRESHOLD
STN_WELL_KNOWN_PORT_NUMBER
A.4 Runtime-only Configuration Options
GemConvertArrayBuilder
GemDropCommittedExportedObjs
GemExceptionSignalCapturesStack
LogOriginTime
SessionInBackup
StnCurrentTranLogDirId
StnCurrentTranLogNames
StnLogFileName
StnLogGemErrors
StnLoginsSuspended
StnMaxReposSize
StnMaxSessions
StnStandbyRole
StnSunsetDate
StnTranLogOriginTime
copydbf
gslist
Remote queries
Date and Time format
Exit status
gslist on Windows
pageaudit
pstack
removedbf
startcachewarmer
startlogreceiver
startlogsender
startnetldi
startstone
statmonitor
stoplogreceiver
stoplogsender
stopnetldi
stopstone
topaz
vsd
waitstone
Overview
Defaults
Notation
Syntax
Non-Numeric Constants
Numeric Constants
Repository and GsObjectSecurityPolicies
Global Variables and Collections
Current TimeZone
Zoneinfo
Utilities
tzselect
zdump
zic
Public Environment Variables
System Variables Used by GemStone
Reserved Environment Variables
A.1 Overview
A.2 Tranlog Analysis Scripts
Script Prerequisites
Output
Tranlog Assumptions
Filter Criteria
printlogs
Examples
searchlogs
A.3 Tranlog Structure
Tranlog Entries
Tranlog Entry Types
Login
AbortLogout
BeginData Data BeginStoreData StoreData
Commit
Abort
BreakSerialization
Very Large Objects
Full vs. Normal Mode
A.4 Example of Tranlog Analysis
Tracking Changes to an Employee
Changed vs. new objects
Details of Changes to an Employee
A.5 Further Analysis
Class Operations
Deleted Objects
Managing Volume