2. Changes in Administration
This chapter describes changes and new features that apply to the administration of a GemStone Repository, including:
2.1 UserProfile and groups changes
Enable and disable
Previously, disabling of UserProfile was bound to the GemStone authentication scheme, and had some logically inconsistent behavior. It was not supported to manually disable accounts using non-GemStone authentication. These processes have been reviewed and the code updated.
Now: any UserProfile can be explicitly disabled using disable or disableWithReason:. UserProfiles that use GemStone authentication can be re-enabled using:
reenableWithPassword:
password:
UserProfiles not using GemStone authentication that were explicitly disabled can be re-enabled using:
reenable
GemStone authentication, but not external authentication, supports automatic disable for login checks, such as exceeding STN_DISABLE_LOGIN_FAILURE_LIMIT. Accounts disabled in this way are also reenabled using reenableWithPassword: or password:.
When using external (non-GemStone) authentication, password security login checks are handled by the authentication mechanism, and no disable is done in GemStone. If logins are disabled by the system that performs the authentication, you must re-enable the account as defined by that system, outside of GemStone.
For example, if using LDAP authentication and the LDAP account is disabled for too many failed logins, the GemStone UserProfile is not "disabled", although logins will fail. After correcting the problem with the LDAP account, you do not need to re-enable the GemStone UserProfile.
enableGemStoneAuthentication requires password argument
The method UserProfile>>enableGemStoneAuthenticationWithPassword has been removed, replaced by UserProfile>>enableGemStoneAuthenticationWithPassword:
Since enabling GemStone authentication requires a password, the earlier version was not sufficient.
Bypass GsCurrentSession initialize in topaz
On login, the method GsCurrentSession >> initialize is invoked, which in turn does session method initialization and invokes that UserProfile’s loginHook:, if present. In much older releases before loginHook was introduced, the GsCurrentSession >> initialize method could be modified. Errors or problems in these functions, however, can prevent logins from completing.
To allow logins under these error conditions, the topaz option SET SESSIONINIT has been added, further controlled by the new configuration parameter STN_ALLOW_NO_SESSION_INIT. For details, see SESSIONINIT to allow login when session initialization fails.
UserIds outside the ASCII range
It has been possible to create userIds (user names) containing characters in the range 128..255. However, the topaz command line input is always UTF-8, and the internal storage of userIds is traditional string, and as a result logins on the topaz command line were not possible. Now, you may enter such userIds at the topaz command line. (#46370)
It is not legal to use characters with codePoints over 255 in userIds or passwords; this has been disallowed to avoid unusable UserProfiles.
UserProfile empty passwords disallowed
Previously, an empty string was a legal password, although not necessarily usable for login. This has been disallowed; the minimum password size is now 1. A password size of zero indicates single-sign on.
UserProfile Instance variable slot for spare1 now reused
The UserProfile slot used by instance variable spare1 is now kerberosPrincipal.
UserProfileGroup replaces string-based groups
Historically, a Group has been represented by an instance of String with the name of the group, and these group strings were added to a UserProfiles’s groups variable, as well as to the Global AllGroups.
To support group-based single sign-on, in v3.4 this implementation has been changed, and a group is now an instance of the new class UserProfileGroup. AllGroups now maps group names to instances of UserProfileGroup, and each UserProfile’s group field contains a set of UserProfileGroups.
During upgrade, existing groups are automatically converted.
Creating and Deleting Groups using UserProfileGroup
To create a group and add it to all groups, you no longer add a String directly to AllGroups. The new process is to create the group using UserProfileGroup class methods. For example,
UserProfileGroup newGroupWithName: ’finance’
To lookup a group based on its string name, also use UserProfileGroup class methods. For example,
UserProfileGroup groupWithName: ’finance’ ifAbsent:
[UserProfileGroup newGroupWithName: ’finance’]
Removing a group likewise uses UserProfileGroup class methods deleteGroup:*.
The AllGroups global should not be accessed directly when querying or updating groups. Use the class methods in UserProfileGroup instead.
Connecting UserProfiles and Groups
Existing UserProfile methods such as addGroup: and removeGroup: that manage group membership continue to accept group string arguments; these methods perform a lookup to UserProfileGroups as needed.
New methods have been added to add groups to and remove them from a UserProfile:
UserProfile >> addToUserProfileGroup:
UserProfile >> removeFromUserProfileGroup:
In addition to the traditional API in which groups were added to users, protocol has been added to allow users to be added to groups, which may be more intuitive.
UserProfileGroup >> addUser:
UserProfileGroup >> removeUser:
Membership
To find the users in a group, use:
UserProfileGroup >> userIds
Return a set of all UserId strings for each member of the group
UserProfileGroup >> users
Return a set of UserProfiles that includes each member of the group
To find the groups for a user use:
UserProfile >> groupNames
Return a set of all group strings for each group that the given user belongs to.
UserProfile >> groups
Return a set of UserProfileGroups that includes each group that the given user belongs to.
Note: in previous versions, this method returned a set of Strings rather than a set of UserProfileGroups.
Group audit
Methods have been added to support an audit of group membership.
UserProfileGroup >> auditGroup
Verify that all users in the receiver do have the receiver in their groups array.
UserProfileGroup class >> auditGroups
Audit each group in AllGroups.
UserProfile >> auditGroups
Verify that each group associated with this UserProfile does include this user in its members, and that each group is in AllGroups.
UserProfileSet >> auditGroups
Audit groups for each user in AllUsers (the singleton instance of UserProfileSet), and audit UserProfileGroup.
2.2 Single sign-on with Kerberos
GemStone now supports Single Sign-On (SSO), using Kerberos. When Kerberos has been setup on your system, you can configure GemStone authentication to use Kerberos, so no separate authentication is required for GemStone login. This may also be referred to as passwordless login.
Note that while most users can use SSO authentication, SystemUser will always require GemStone authentication. Since SSO users cannot log in if Kerberos is not running, this avoids the risk of complete inaccessibility.
Both linked and RPC logins and remote logins, including logins from GBS and using GsExternalSession, can use SSO to authenticate, provided the user can authenticate via Kerberos on the client’s node.
Kerberos
Using SSO with Kerberos requires that Kerberos be installed and configured on your system. For specifics, consult your System Administrators. The general requirements are outlined here.
GemStone uses Kerberos v5 Release 1.15.2 with AES encryption.
Realm
Kerberos uses the term "realm" for a domain within an installation/organization. Realms are generally the DNS domain in upper case; for example, at GemTalk the realm would be GEMTALKSYSTEMS.COM.
User Principals
The term "principal" is used for any unique identity, including UNIX user ids, hosts, and services.
User principals are identified as name@REALM, e.g.
lalmarod@GEMTALKSYSTEMS.COM
When a user authenticates using Kerberos (e.g by UNIX login or by using kinit), the user enters their password, and Kerberos provides a ticket -- more specifically, a ticket granting ticket (TGT). This is cached on the user’s host, and is used to create specific tickets for requested services at the time they are requested. The TGT is usually put under /tmp, and is valid for a limited period, by default usually 10 hours.
GemStone Service Principals
In addition to the user principals, you will need to have service principals for GemStone. The service principal is of the form Service/fully.qualified.domain.name@REALM. The name of the service principal for authentication in GemStone is GEMSTONE64. So, for example, a service principal might be
GEMSTONE64/santiam.gemtalksystem.com@GEMTALKSYSTEMS.COM
Keytab
A keytab is a file containing pairs of Kerberos principals and encrypted keys. GemStone requires a keytab that stores keys for the GEMSTONE64 kerberos service, which must be there for each host. This keytab does not store user principals.
This keytab file will be used for authorization; any user who has authenticated via Kerberos and has access to the keytab file will be able to do a single sign-on login.
KerberosPrincipal and AllKerberosPrincipals
The new class KerberosPrincipal defines the association between the name of a Kerberos principal and GemStone login information. A KerberosPrincipal has the following information:
There are a number of ways that a repository can be configured to allow one or more UserProfiles to login using one or more KerberosPrincipals.
- There may be a one-to-one relationship between a UserProfile and a KerberosPrincipal, with each referencing the other. In this case loginUserProfileGroups and loginAsAnyoneEnabled are usually nil.
- One or more UserProfile/s may reference a KerberosPrincipal with loginUserProfileGroups configured as a set of UserProfileGroups. The KerberosPrincipal has a nil loginUserProfile and loginAsAnyoneEnabled set to false. Any user that is a member of any of these groups can use this KerberosPrincipal to log in.
- One or more UserProfile/s may reference a KerberosPrincipal that has a nil loginUserProfile, and with loginAsAnyoneEnabled set to true. This allows any user to configure SingleSignOn using that KerberosPrincipal.
KerberosPrincipals are created using class protocol in KerberosPrincipal, and are automatically added to the global collection AllKerberosPrincipals. You can look up a KerberosPrincipal by name. The AllKerberosPrincipals global should not be accessed directly.
The login log includes the Kerberos principal, and descriptionOfSession: results includes Kerberos principal.
UserProfile new methods
Methods that set or query for the authentication scheme can now use #SingleSignOn in addition to #GemStone, #UNIX, or #LDAP.
To setup singleSignOn authentication, use
enableSingleSignOnAuthenticationWithPrincipal: aKerberosPrincipal
To query if this authentication is enabled use:
authenticationSchemeIsSingleSignOn
To query and set the KerberosPrincipal for a particular user use:
kerberosPrincipalkerberosPrincipal: aKerberosPrincipal
Setting up Kerberos Authentication in GemStone
Within GemStone, the following steps are required:
Create or locate the UserProfile
The UserProfile who will use SSO will have their authentication changed, and will no longer use the GemStone password. This user will only be able to login as long as Kerberos is running. For this reason, the SystemUser account cannot be set to SSO.
Create an instance of KerberosPrincipal
A UserProfile who will use SSO is associated with an instance of the new class KerberosPrincipal.
Enable SSO for that UserProfile
Single sign-on/Kerberos is another way to do GemStone authentication, enabled via enableSingleSignOnAuthenticationWithPrincipal: .
You may disable SSO by enabling a different type of authentication.
Commit the changes to the UserProfile
As an example of the previous steps, the following code configures the user named ’john’ to use SSO:
| prin user |
user := AllUsers userWithId: 'john'.
prin := KerberosPrincipal
newPrincipalWithName: 'jsmith@GEMTALKSYSTEMS.COM'
loginUserProfile: user.
user enableSingleSignOnAuthenticationWithPrincipal: prin.
System commitTransaction.
Configure the gem’s environment to set the keytab file location
The Gem configuration parameter GEM_KERBEROS_KEYTAB_FILE must be set in order to specify the location of the keytab file.
For example, enter this in the configuration file used by john:
GEM_KERBEROS_KEYTAB_FILE =/export/localnew/common/kerberos/gemtalk.keytab;
Using Groups to authenticate with Kerberos
A KerberosPrincipal often will correspond to a specific GemStone UserProfile. However, you may use groups to configure your system so multiple GemStone UserProfiles can login using the same KerberosPrincipal.
To do this, create a KerberosPrincipal with a nil loginUserProfile. Create a new group and make the users part of the group, and add the group to the KerberosPrincipal. You can then use this KerberosPrincipal to enable single sign-on for all the users in the group
For example, the following code uses jsmith’s principal to login as both ’john’ and ’mary’.
| prin user1 user2 group |
user1 := AllUsers userWithId: 'john'.
user2 := AllUsers userWithId: 'mary'.
group := UserProfileGroup
newGroupWithName: 'KerberosAdminLogin'.
user1 addGroup: group groupName.
user2 addGroup: group groupName.
prin := KerberosPrincipal newPrincipalWithName:
'jsmith@GEMTALKSYSTEMS.COM' loginUserProfile: nil.
prin addGroup: group.
group users do: [:aUserProfile | aUserProfile
enableSingleSignOnAuthenticationWithPrincipal: prin].
System commitTransaction.
You can configure all users on your system (except SystemUser) to share the KerberosPrincipal by using
aKerberosPrincipal loginAsAnyoneEnabled: true
This is equivalent to creating a group that includes all users except SystemUser and using this for the KerberosPrincipal’s group.
Then, any user (again, except SystemUser) can set their authentication to #SingleSignOn using the principal aKerberosPrincipal.
The AllKerberosPrincipals global should not be accessed directly when querying or updating KerberosPrinciples. Use the class methods in KerberosPrincipals instead.
Remote login on Windows
Single sign-on can be used to login clients on Windows. On Windows, Kerberos is built-in as part of SSPI.
Single sign-on can only be used on Windows clients that are part of a Windows domain; clients on machines that are only members of Windows workgroups cannot use Kerberos authentication. The domain controller must either be samba or a MS Windows server.
Consult your system administrators or GemTalk Technical Support for clarification or assistance.
GemBuilder for Smalltalk
Single sign-on can be used for logins from GBS clients on Windows and Unix.
However, given the various ways KerberosPrincipals can be configured, the GBS User Tools do not support configuring single sign-on interactively. You must setup KerberosPrincipals and assign to users using GemStone code, as described above.
Login log includes Kerberos principal
When STN_LOGIN_LOG_ENABLED is set, the login log entry that is written now includes another field within each line. The new field, at the end of each line, lists the name of the KerberosPrincipal used for single sign-on login enclosed in single quotes, or '' (two single quotes) if single sign-on login was not used.
descriptionOfSession:
The result of System descriptionOfSession: now includes an additional element (22): The KerberosPrincipal object used for single sign-on login to the session, or nil if single sign-on login was not used.
Using Kerberos for NetLDI authentication
The NetLDI can be configured to use Kerberos for authentication for the hostUserId/hostPassword. A new argument as been added to startnetldi to allow a Kerberos keytab to be specified:
This option can only be applied when NetLDI requires authentication, since in guest mode, no authentication is done. It is disallowed to specify both -g and -k.
To configure Kerberos authentication for NetLDI:
- startnetldi must be executed with the -k option argument of the Kerberos keytab file path.
- The GemStone login parameters must have an empty hostPassword field, and the username must match the one in the Kerberos ticket.
- There must be a currently valid ticket (TGT) associated with a principal for the UNIX user id that the NetLDI is authenticating as.
2.3 Secure Backups
The new secure backups feature provides two new capabilities:
- Digital signing, ensuring the identity of the originator. All backups created using the secure backup API are digitally signed.
- Encrypted backups, requiring a private key to restore. Encryption is optional, using AES-CTR with key sizes of 128, 192, or 256.
Secure backups, as with standard backups, can also be written to one or multiple files and may be uncompressed, compressed using gzip, or compressed using lz4.
Secure backups are created using a new Repository method that contains a number of arguments to specify the filenames, encryption type, and other details of the backup.
secureFullBackupTo:MBytes:compressKind:bufSize:encryptKind:
publicKeyCerts:signatureHashKind:signingKey:signingKeyPassphrase:
Restoring a secure backup uses new Repository methods
restoreFromSecureBackup[s]:*.
You cannot use the secure restore to restore a regular backup, nor vice versa.
Secure backups require RSA keypairs, both for signing and encryption (if used); DSA is not supported. You will need separate keypairs for signing and encryption. The signing key may or may not require a passphrase, although a passphrase is recommended for security. The example keys included in the distribution require passphrases.
To create a secure encrypted backup, you can use one or up to eight public keys. Restoring this backup requires a private key that corresponds to any one of these public keys. This allows you to create a backup that can be restored by multiple entities, without these entities having to share a single private key.
Before using the secure backup API to make or restore secure backups, you must set the keyfile directories (keyring), using the new Gem configuration option GEM_KEYRING_DIRS. This can be set either in the configuration file used by the Gem process, or set at runtime. The directories specified in GEM_KEYRING_DIRS are used to confirm there is a matching public keyfile for keys used by the secure backup operations, and that private keys match the public keys.
Example keys and passphrases
The directory $GEMSTONE/examples/openssl includes two subdirectories with example keys for creating, signing, and restoring secure backups:
These keys are used in the examples starting here.
Added Methods
Making the Backup
Repository >> secureFullBackupTo: fileNames MBytes: mByteLimit
compressKind: compKind bufSize: count encryptKind: encKind
publicKeyCerts: anArrayOrString signatureHashKind: hashKind
signingKey: signingKeyFn signingKeyPassphrase: aPassphrase
Writes a secure full backup file containing the most recently committed version of the receiver as of the time the method is executed.
Secure backups support compression, encryption and digital signatures. Compression and encryption are optional. Digital signatures are mandatory.
fileNames must either be a string which is the backup file name or an array of strings containing a list of backup file names.
Secure backups have a file extension of .sdbf, which will be appended to all backup file names if necessary.
compKind argument:
The following compression kinds are supported. LZ4 is recommended since it is faster than zlib.
0 - no compression
1 - zlib (aka gzip) compression.
2 - lz4 compression.
encKind argument:
An encKind of zero indicates the backup is not encrypted. An encKind greater than zero indicates the backup is encrypted using AES-CTR mode using the key size shown below:
0 - no encryption
1 - AES-CTR-128
2 - AES-CTR-192
3 - AES-CTR-256
hashKind argument:
hashKind specifies what message digest (hash) algorithm will be used to hash the signature before it is encrypted and stored in the backup file. The following message digests are supported:
1 - SHA256
2 - SHA384
3 - SHA512
All certificates and keys must be in one of the directories specified in the key ring, which is the list of directories specified in the GEM_KEYRING_DIRS configuration option. Certificate and key file names must be specified without the path. GemStone will automatically search the key ring for the matching file.
If encKind is greater than zero, the publicKeyCerts argument anArrayOrString must either be a String or an Array of Strings where each element is the filename of an X509 certificate in PEM format that contains an RSA public key without a passphrase. The RSA public key(s) may be any valid length (1024, 2048, 3072, bits etc). A key length of at least 2048 bits is recommended. anArrayOrString must be nil if encKind is zero. A maximum of eight (8) public key certificates may be specified.
When encryption is enabled, each backup file is encrypted with a randomly generated session key, which is then encrypted with the provided public key(s) and stored in the backup file. One of the corresponding private keys must be available in order to restore the backup, but are not required when the backup is created.
signingKeyFn is the name of a private key file in PEM format used to sign the backup. The file must be in the key ring. aPassphrase is a string which is the passphrase for the private key. If the private key does not use a passphrase, then aPassphrase must be nil. A certificate containing the public key which matches the private key specified in privateKeyFn is stored in the backup and must also be present in the key ring. GemStone automatically searches the keyring for the matching certificate.
The bufSize argument controls the size of the buffer used to write records to the file. The count argument specifies the number of 128KB backup records are contained in the buffer. The values allowed are 1 (128KB) through 8192 (1GB).
Restoring the Backup
Repository >> restoreFromSecureBackup: aFileName
privateDecryptionKey: aKey passphrase: aPassphrase
Repository >> restoreFromSecureBackup: aFileName
scavengePagesWithPercentFree: aPercent privateDecryptionKey: aKey passphrase: aPassphrase
Repository >> restoreFromSecureBackups: anArrayOfFilenames
privateDecryptionKey: aKey passphrase: aPassphrase
Repository >> restoreFromSecureBackups: anArrayOfFilenames
scavengePagesWithPercentFree: aPercent privateDecryptionKey: aKey passphrase: aPassphrase
Disables logins and starts a full restore of the repository based on the contents of the specified secure backup file(s). Behaves the same as the restoreFromBackup: method except for extra security and integrity checks as described below.
Secure backup files must have a file extension of .sdbf. All file names in arrayOfFileNames will have the .sdbf suffix appended if it is not present.
All certificates and keys must be in one of the directories specified in the key ring, which is the list of directories specified in the GEM_KEYRING_DIRS configuration option. Certificate and key file names must be specified without the path. GemStone will automatically search the key ring for the matching file.
Secure backups are always digitally signed with a private signing key, and optionally were encrypted using one or more public keys. Before the backup is restored, the integrity of each backup file is checked by reading the file and computing the signature. If the computed signature does not match the signature stored in the file, then an error is raised indicating the backup file has been either been corrupted or tampered with. If the signature is correct, the restore proceeds.
A certificate containing the public key which matches the private key used to sign the backup must be present in the key ring. GemStone automatically searches all files in the key ring for a certificate which contains a matching public key. The restore will fail and an error will be raised if the key ring does not contain the appropriate certificate.
If the backup was encrypted, aKey is a String representing the file name containing a private key in PEM format. The private key must match one of the public keys specified when creating the backup. The file must be present in the key ring as described above. If the backup is not encrypted then aKey must be nil.
aPassphrase is the passphrase to access the private key. If the backup is not encrypted or aKey is not protected by a passphrase (not recommended) then aPassphrase must be nil.
This method performs the restore using multiple slave sessions. The number of slave sessions is automatically determined from the number of extents in the repository, with a minimum of 2 sessions and a maximum of 16. The performance can be modified during the run by updating the Multithreaded Scan Tuning methods.
Configuration option
A new configuration file option allows you to specify the location of keys and certificates used for secure backup/restore.
copydbf information about secure backups
copydbf can be used with secure backups similarly as with ordinary backup files; however, byte-order changes and copying over the network to another page server are not allowed with secure backups.
The reports produced by copydbf -i/-I include basic security attributes for secure backup files.
In addition, new copydbf arguments can be used to extract certain elements of security information from the backup.
copydbf -i now includes security information when run against a secure backup:
host> copydbf -i tsb.multifile.backup.bak_4.sdbf
Source file: tsb.multifile.backup.bak_4.sdbf
File type: secure backup fileId: 3
in a backup set with 4 files
ByteOrder: Intel (LSB first) compatibilityLevel: 850
The file was created at: 09/08/17 13:28:36 PDT
Second or subsquent file of a multi-file full backup.
Oldest tranlog needed for restore not available.
Backup was created by GemStone Version: 3.4.0.
Secure Backup Attributes:
Compression: Zlib
Encryption: AES_128_CTR
Signature Hash: SHA-256
Encryption Keys: 1
New options have been added to extract information, and verify a secure backup file. These options allow you to extract public certificate information from the backup to a disk file. While this is provided for convenience, this information does not contribute to the security of backup administration.
The added copydbf options are:
-K directories
list of colon-separated directories which contain keys and certificates, which is used with the -V option to verify the digital signature.
-V verify the digital signature of a secure backup. This requires including either the -K command line option, or setting the GEMSTONE_KEYRING_TABS environment variable.
-W filename
Create a new file or files with the given name containing the encryption certificate(s) from a secure backup to file(s). Cannot be used with other write options on a single command line.
-X filename
Create a new file with the given name containing the signing certificate from a secure backup to file. Cannot be used with other write options on a single command line.
-Y filename
Create a new file with the given name containing the digital signature from a secure backup to file. Cannot be used with other write options on a single command line.
Examples of Secure Backup
Create a signed, unencrypted backup
The following code creates a single file secure backup, uncompressed and not encrypted, using the example key and passphrase in the GemStone distribution.
topaz 1> run
System gemConfigurationAt: #GemKeyRingDirs
put: {'$GEMSTONE/examples/openssl/certs' .
'$GEMSTONE/examples/openssl/private' }.
SystemRepository
secureFullBackupTo: '$GEMSTONE/data/backup'
MBytes: 0
compressKind: 0
bufSize: 8
encryptKind: 0
publicKeyCerts: nil
signatureHashKind: 1
signingKey: 'backup_sign_2_clientkey.pem'
signingKeyPassphrase: (GsSecureSocket
getPasswordFromFile:
'$GEMSTONE/examples/openssl/private/backup_sign_2_client_passwd.txt' ).
%
copydbf of a signed, unencrypted backup
unixprompt> copydbf -i backup.sdbf
Source file: backup.sdbf
File type: secure backup fileId: 0
in a backup set with 1 files
ByteOrder: Intel (LSB first) compatibilityLevel: 850
The file was created at: 09/08/2017 14:16:39 PDT
Full backup started from checkpoint at: 09/08/2017 14:16:38 PDT.
Oldest tranlog needed for restore is fileId 1 ( tranlog1.dbf ).
Backup was created by GemStone Version: 3.4.0.
Secure Backup Attributes:
Compression: NONE
Encryption: NONE
Signature Hash: SHA-256
Encryption Keys: 0
Restore an unencrypted secure backup
topaz 1> run
System gemConfigurationAt: #GemKeyRingDirs
put: {'$GEMSTONE/examples/openssl/certs' .
'$GEMSTONE/examples/openssl/private' }.
SystemRepository
restoreFromSecureBackup: 'backup.sdbf'
privateDecryptionKey: nil
passphrase: nil.
%
Create an encrypted backup
To encrypt a backup, you can specify between 1 and 8 public certificates. To restore an encrypted backup, any one of the private keys associated with the public keys can be used. The private key is not required to create the encrypted backup, only to restore it.
For example, if an organization wishes to distribute a backup to multiple customers via an encrypted backup, the public key for each customer can be specified when the backup is created. Each customer may use their individual private key to restore the backup.
topaz 1> run
System gemConfigurationAt: #GemKeyRingDirs
put: {'$GEMSTONE/examples/openssl/certs' .
'$GEMSTONE/examples/openssl/private' }.
SystemRepository
secureFullBackupTo: '$GEMSTONE/data/backup'
MBytes: 0
compressKind: 2
bufSize: 8
encryptKind: 2
publicKeyCerts: { 'backup_encrypt_1_clientcert.pem' .
'backup_encrypt_2_clientcert.pem'}
signatureHashKind: 1
signingKey: 'backup_sign_1_clientkey.pem'
signingKeyPassphrase:
(GsSecureSocket getPasswordFromFile:
'$GEMSTONE/examples/openssl/private/backup_sign_1_client_passwd.txt' )
Copydbf of an encrypted backup
unixprompt> copydbf -i backup.sdbf
Source file: back1.bak.sdbf
File type: secure backup fileId: 0
in a backup set with 1 files
ByteOrder: Intel (LSB first) compatibilityLevel: 850
The file was created at: 09/08/2017 14:35:10 PDT
Full backup started from checkpoint at: 09/08/2017 14:35:09 PDT.
Oldest tranlog needed for restore is fileId 1 ( tranlog1.dbf ).
Backup was created by GemStone Version: 3.4.0.
Secure Backup Attributes:
Compression: LZ4
Encryption: AES_192_CTR
Signature Hash: SHA-256
Encryption Keys: 2
Restore an encrypted backup
topaz 1> run
System gemConfigurationAt: #GemKeyRingDirs
put: {'$GEMSTONE/examples/openssl/certs' .
'$GEMSTONE/examples/openssl/private' }.
SystemRepository
restoreFromSecureBackup: 'backup.sdbf'
privateDecryptionKey: 'backup_encrypt_1_clientkey.pem'
passphrase: (GsSecureSocket getPasswordFromFile:
'$GEMSTONE/examples/openssl/private/backup_encrypt_1_client_passwd.txt' )
%
Script to support verifying digital signature
A script has been added that uses publicly available openSSL, by default the executable in $GEMSTONE/bin/openssl, to verify the digital signature of a secure backup.
$GEMSTONE/bin/verify_backup_with_openssl.sh
Example
Verify the signature using OpenSSL:
% $GEMSTONE/bin/verify_backup_with_openssl.sh backup.sdbf
$GEMSTONE/examples/openssl/certs/backup_sign_2_clientcert.pem
[Info]: Using certificate file /lark1/GS/examples/openssl/certs/backup_sign_2_clientcert.pem
[Info]: Digest kind is SHA-256
[Info]: Invoking openssl to perform the digital signature verification:
Verified OK
% copydbf -V backup1.sdbf -K $GEMSTONE/examples/openssl/certs/
Source file: backup1.sdbf
File type: secure backup fileId: 0
in a backup set with 1 files
ByteOrder: Intel (LSB first) compatibilityLevel: 850
The file was created at: 09/07/2017 23:26:16 PDT
[Info]: Digital signature successfully verified.
2.4 Changes related to Repository Scan operations
Repository scan operations are those that need to scan the entire repository, including backup creation, garbage collection, audit, and operations that analyze the objects in a repository.
Concurrent Repository Scan Operations
Historically, only one repository scan operation could be run at one time within a given GemStone repository, to avoid the risk of conflicting updates. Repository scan operations include garbage collection (MFC, FDC, and Epoch), backups, object audit, and listing operations such as list instances and list references. The single gcLock limited reclaim operations, so only pages that have been scanned (below the gcHighWaterMark) were allowed to be processed for reclaim.
While two garbage collection operations cannot be safely run simultaneously, with v3.4, it is now possible to run one garbage collection operation and up to three other repository scans at the same time within a single GemStone repository, provided the repository’s I/O and CPU can support the load.
Note that if there is more than one scan performed simultaneously, shadow page reclaim is disabled for the duration. Only dead objects will be reclaimed.
Object Profiling of objects in temporary object memory
GsObjectInventory can now create a report on the contents of temporary object memory, with the added method:
GsObjectInventory class >> profileMemory
Finding Reference Paths
A new subsystem has been added to provide optimized, multi-threaded repository scans for reference paths. This subsystem replaces the internal code invoked by the Repository >> findReferencePath... methods.
To perform the scan, you create an instance of the added class GsSingleRefPathFinder for the object or objects, run the scan, and collect/view the results.
GsSingleRefPathFinder provides a number of instance variables to parameterize the search:
- maxThreads
- lockWaitTime
- pageBufferSize
- percentCpuLimit
- maxLimitSetDescendantObjs
- maxLimitSetDescendantLevels
- printToLog
Defaults are provided, or you may send messages as needed, for example to perform a less aggressive scan.
To perform a simple scan and print the result string:
(GsSingleRefPathFinder newForSearchObjects: { anObject })
scanAndReport
To perform a scan with a specific limit set on descendents:
inst := GsSingleRefPathFinder newForSearchObjects: { anObject }.
inst maxLimitSetDescendantLevels: 4.
inst runScan.
inst buildResultObjects collect:
[:refPath | refPath resultString].
The method buildResultObject returns a collection of instances of the new class GsSingleRefPathResult. This class is a subclass of Array, with each element representing an element in the reference path, and instance variables for the searchOop and status.
Note that using a smaller maxLimitSetDescendantLevels may not be performant; if the search objects are found within the limit set, the repository scan is not needed.
Deprecated methods
The following methods on Repository are deprecated; they invoke the new classes to perform the scan:
Repository >> findReferencePathToObject:
Repository >> findReferencePathToObjects:findAllRefs: printToLog:
Repository >> findReferencePathToObjs:limitObjArray: findAllRefs:printToLog:
Note that these methods now return an instance or instances of GsSingleRefPathResult, and arguments other than the search object/s are not used.
Backup and restore support lz4 compression
GemStone now supports lz4 for most operations that allow compression.
To support lz4 compression of programmatic backups, new API methods have been added, and restore methods now recognize and can decompress both formats.
It is expected that .gz and .lz4 extensions reliably indicate the compression used.
For backups, lz4 is generally much faster than gzip (usually by 2.5X but up to 10X) but does not compress data quite as well.
The following methods have been added to create lz4-compressed backups:
fullBackupLz4CompressedTo:
fullBackupLz4CompressedTo:MBytes:
To differentiate creating backups that are compressed using gzip from compression using lz4, new methods have been created that include "Gz" in the name:
fullBackupGzCompressedTo:
fullBackupGzCompressedTo:MBytes:
A method has also been added to programmatically specify the type of compression:
fullBackupTo:MBytes:compressKind:bufSize:
fullBackupCompressedTo: deprecated
The existing methods invoke the Gz versions, and are deprecated in v3.4:
fullBackupCompressedTo:
fullBackupCompressedTo:MBytes:
2.5 Bitmap based operations with new class GsBitmap
GsBitmap
The class GsBitmap has been added, encapsulating behavior of GemStone’s hidden sets.
GsBitmap represents an in memory bitmap, i.e. a transient bitmap that cannot be made persistent. A bitmap is a sparse data structure that logically implements a bit array. Each bit in the bitmap represents the oopNumber of a committed non-special object.
GsBitmaps return an error on an attempt to add a temporary object or a special, or if you attempt to commit a reference to them. As with hidden sets, you should use caution in working with GsBitmaps, since the objects are referenced as OOPs, and if not otherwise referenced, are not protected from garbage collection nor the OOP from reuse.
While GsBitmap can be considered as a collection and implements Collection protocol, it does not inherit from Collection. You may send asGsBitmap to create a GsBitmap from a collection, provided the collection only contains objects that are allowed in a GsBitmap; use asArray to collect the objects corresponding to the OOPs in the GsBitmap.
An instance of GsBitmap uses C Heap memory to store the bit array. The C Heap memory associated with an instance of GsBitmap is automatically freed when the instance is garbage collected.
Bitmap Files
In addition to standard collection protocol, GsBitmaps can be written to and read from disk, using the following methods:
GsBitmap >> writeToFile:
GsBitmap >> writeToFileInPageOrder:
GsBitmap >> readFromFile:
GsBitmap >> readFromFile:withLimit:startingAt:
You may also query for information on a given bitmap file, using GsBitmap >> fileInfo:. This method returns an array containing:
- number of oops in the file
- whether the file was written in page order
- number of valid oops
- number of oops that are not allocated, or in the process of being garbage collected
File format
GsBitmap files are written in a new file format, which is not compatible with files written using hidden set protocol. You may not read files using the GsBitmap interface that were generated using the hidden set interface, and vice versa.
findDisconnectedObjectsAndWriteToFile:* and loadGcCandidatesFromFile:* also now use the GsBitmap format, rather than the previous specialized format. You may use GsBitmap methods to load the disconnected object files generated by findDisconnectedObjectsAndWriteToFile* methods.
Garbage Collection consequences
The objects referenced in a GsBitmap are not protected from garbage collection.
The reference within the GsBitmap is to the OOP. For a GsBitmap that exists in a session for time periods that include commits or aborts, if the object is otherwise unreferenced, there is a risk that it may be garbage collected and the OOP may be reused. Subsequently, the GsBitmap may not contain objects that were expected to be there, or may contain objects that were not expected to be there.
GsBitmap and Hidden Sets
System’s hidden set API has been superceded by GsBitmap. The Hidden set public API is not deprecated, but it is marked as Legacy and may be deprecated in the future.
GsBitmap uses hidden set specifiers that are symbols, rather than integers. The method GsBitmap class >> hiddenSetSpecifiers lists the symbolic names for the various hidden sets.
NOTE: While the position of the symbolicName in the list of hiddenSetSpecifiers is internally used as an index, these indexes do NOT match the integers used as specifiers for System HiddenSets. Nor do the symbolic names match the strings returned by System HiddenSetSpecifiers.
Public access to most System hiddenSets is provided by creating a GsBitmap that references a particular hiddenSet, using GsBitmap class >> newForHiddenSet:.
Many of the System hiddenSets are read only, and generate an error for update operations. This includes updates by SystemUser. See the comments in the GsBitmap class >> hiddenSetSpecifier method; hidden sets after the one labeled "last mutable hiddenSet" generate an error if an attempt is made to modify them.
NotifySet and GCI sets
There are system hidden sets that may need to be updated by users (other than SystemUser) for particular GemStone application requirements. These hidden sets have a separate, limited public API in System class.
The #NotifySet (System hidden set 25) has an interface defined in class System with methods in the Notification category; clearNotifySet, addToNotifySet:, etc.
#ExportedDirtyObjs and #TrackedDirtyObjs (System hidden sets 22 and 23) have an interface defined in class System, category Gci Set Support. These method allow these sets to be initialized and to get and clear the contents.
#PureExportSet and #GciTrackedObjs (System hidden sets 39 and 40) also have an interface in class System, category GciSets. These methods allow you to add and remove objects from these hidden sets.
Methods returning GsBitmaps
The following methods have been added as alteratives to existing methods but return an instance of GsBitmap. There are some differences from the earlier equivalents; refer to image method comments for details.
Repository >> allInstances:
Repository >> fastAllInstances:
Analogous to Repository >> (fast)listInstances:
Repository >> allObjectsInObjectSecurityPolicies:
Repository >> fastAllObjectsInObjectSecurityPolicies:
Analogous to Repository >> (fast)
listObjectsInObjectSecurityPolicies:
Repository >> allObjectsLargerThan:
Repository >> fastAllObjectsLargerThan:
Analogous to System class >>
(fast)findObjectsLargerThan:limit:
Repository >> allReferences:
Repository >> fastAllReferences:
Analogous to Repository >> (fast)listReferences:
Repository >> allReferencesToInstancesOfClasses:
Repository >> fastAllReferencesToInstancesOfClasses:
Analogous to Repository >> (fast)
listReferencesToInstancesOfClasses:toDirectory:
Changes to existing methods
The output files generated by findDisconnectedObjectsAndWriteToFile* methods are now in GsBitmap file format, which is different than the format used in earlier versions.
The method loadGcCandidatesFromFile:intoHiddenSet: requires the argument be a GsBitmap hiddenSetSpecifier, such as #CustomerSet1.
Deprecated Methods
The following methods, whose functions can be more easily performed using GsBitmap, have been deprecated:
Repository >> auditPageOrderOopFileWithId:
Repository >> closePageOrderOopFileWithId:
Repository >> openPageOrderOopFile:
Repository >> numberOfObjectsInPageOrderOopFileWithId:
Repository >> readObjectsFromFileWithId:startingAt:upTo:into:
Note that some of these are primitives and do not send the deprecated: message.
2.6 Other changes affecting administrative operations
fileSizeReport formatting change
The method Repository >> fileSizeReport returns a string describing the extents in the repository. This display has removed newlines to produce a more compressed result, and the dividing lines have been adjusted for readability.
Added method Repository >> extentsReport
This method produces a report with the same information as fileSizeReport, but formatted in a more condensed way with two lines per extent.
Temporary Symbol creation allowed during restore from logs
During restore, the symbol gem is not running so it is not possible to create persistent symbols. This creates problems for executing code that contains temporary variables that do not already exist as a symbol.
In v3.4, while in restore mode, you may now perform operations that create symbols, and these symbols exist only in temporary memory. If the session has created temporary symbols and does an abort, the session will be terminated with error 4070.
This only applies in restore mode: symbol creation is still not allowed in normal mode when the symbol gem is not running.
Logging to GCI server rather than client
A number of maintenance methods log output to the application console. While most of these logged to the server console, a few methods wrote to the client console, which was irretrievably lost in some configurations.
The following methods that previously logged to the client console via GsFile >> gciLogClient: now invoke gciLogServer:.
Repository >> reclaimAll
Repository >> _setGcConfigAt:put:
Repository >> _setupContinuousRestore:
System class >> clusterAllSymbols
The login log includes the Kerberos principal
When STN_LOGIN_LOG_ENABLED is set, the login log entry that is written now includes another field within each line. The new field, at the end of each line, lists the name of the KerberosPrincipal used for single sign-on login enclosed in single quotes, or '' (two single quotes) if single sign-on login was not used.
2.7 Cache Warming Changes
With large caches, running cache warming on startup is important to avoid unpredictable initial performance as object table and data pages are loaded into an empty cache. In v3.4, there is an improved system for specifying cache warming on startup, and a way to load the specific working set of useful data pages.
Running cache warming automatically on startstone
Historically there have been two options for cache warming: configuration parameters that specified cache warming to automatically run on startup, and a script that was normally run immediately after startup, but required manual execution.
In v3.4, configuration parameters have been added to allow the startcachewarmer script to be automatically invoked on stone startup or on remote cache startup. These new parameters let you specify the particular arguments to be used to invoke the startcachewarmer script.
The previously existing cache warming configuration parameters (STN_CACHE_WARMER and STN_CACHE_WARMER_SESSIONS) are not deprecated in this release, but will be deprecated in a future release, ensuring that all cache warming uses the same code paths.
The added configuration parameters allow automatic cache warming on:
- Stone’s cache, using STN_CACHE_WARMER_ARGS
- All remote shared page caches, using GEM_CACHE_WARMER_ARGS
- All mid-level caches that are started, using GEM_CACHE_WARMER_MID_CACHE_ARGS
To configure automatic cache warming, the relevant subset of startcachewarmer arguments are used as the setting for the configuration parameter. For example,
STN_CACHE_WARMER_ARGS = "-d";
Legal startcachewarmer arguments for this usage include -d -D -l -n -w, and for remote cache warmers only, -L.
Cache warming based on previously loaded data pages
Cache warming options include loading the object table only into the shared page cache, or loading both the object table and data pages. By loading data pages, you can (potentially) load the entire repository into the SPC, and provide the best performance for initial queries.
However, if your cache is not large enough to hold all the data pages, the cache warmer loaded as many pages as would fit into the cache, in page id order. There was previously no way to ensure that frequently accessed pages were loaded, rather than unnecessary or archival data.
In v3.4 an argument has been added to allow you to configure your system to record the pageIds of data pages in your shared page cache to a compressed disk file, and have these data pages loaded on stone startup. Using this feature, after a stone shutdown and restart, the shared page cache can contain the same set of data pages as were loaded before shutdown, which are likely to be frequently used data.
There are two parts to this feature:
- startcachewarmer now always looks for the well-known file of working set pageIds, and loads this if the file exists. If the working set file does not exist, the usual default, -d or -D argument manages the behavior, as in previous releases.
- Using the startcachewarmer -w interval argument instructs the shared page cache monitor to write the working set file every interval minutes. With a value of 0, it writes the file only on clean stone shutdown (including a kill that performs a clean shutdown).
The well-known working set file is
/opt/gemstone/locks/<stoneName><hostid>workingSet.lz4
The stone log now includes descriptive messages on what was loaded by cache warming; the gem log file for the cache warmer has also been renamed and is now written to the same directory as other stone log files.
For example, by configuring cache warming in the stone configuration file with the following:
STN_CACHE_WARMER_ARGS = "-w 0 -d";
With this setting, the first time the stone is started, all data pages are loaded into the cache in page order; on subsequent stone restarts, the working set file exists and is loaded instead.
startstone can wait for cache warming to complete
While logins are allowed during cache warming, it may be preferable to wait for cache warming to complete before making the repository available.
You may now specify for startstone to wait until cache warming is complete, before returning, using the new configuration parameter STN_CACHE_WARMER_WAIT_MODE.
0 - startstone never waits for cache warming to complete.
1 - startstone waits for cache warming to complete, only after a clean shutdown or a startup without tranlogs (-N); if recovery or tranlog replay was needed, startstone returns after recovery but before cache warming completes. This is the default.
2.8 Configuration Parameter changes
Parsing Change
With configuration option values that are strings, it is now allowed to use either single quotes, double quotes, or no quotes.
Quotes are required for option values containing embedded spaces.
Changes in parameters
The following option has been renamed:
STN_TRAN_Q_TO_RUN_Q_THRESHOLD has been renamed, and the semantics changed. It is now STN_TRANQ_TO_RUNQ_THRESHOLD.
The following options have been superceded:
STN_CACHE_WARMER
STN_CACHE_WARMER_SESSIONS
The added options STN_CACHE_WARMER_ARGS, GEM_CACHE_WARMER_ARGS, and GEM_CACHE_WARMER_MID_CACHE_ARGS provide automatic cache warming on startup, invoking the cache warming scripts, and are the preferred way to configure automatic cache warming.
The older way to invoke automatic cache warming on startup, using STN_CACHE_WARMER and STN_CACHE_WARMER_SESSIONS, are still available and fully supported; however, these options may be deprecated in a future release.
STN_MAX_AIO_REQUESTS default/minimum changed
The calculation for default and minimum for STN_MAX_AIO_REQUESTS has been changed to accommodate smaller systems. Previously, the default was 128; now, the default is the lesser of SHR_PAGE_CACHE_NUM_PROCS and 128, and minimums less than 100 are allowed.
Added configuration Parameters
GEM_CACHE_WARMER_ARGS
This parameter configures cache warming on a remote cache started by a remote gem. When this is non-empty, cache warming will run automatically when the remote cache is started.
Arguments to enable cache warming are a string that may containing white space, or the arguments used to start a cache warmer. When a remote gem creates a remote shared page cache, if the value of this configuration parameter is empty, no cache warmer is started; if the value contains spaces only, a default cache warmer is started. Otherwise the value should contain valid arguments that will be used to invoke the cache warmer.
startcachewarmer arguments may be obtained using startcachewarmer -h. The only arguments that should be used are: -d -D -l -L -n -w.
This option is only used by remote gems that create a remote shared page cache. It is ignored by all other gems.
GEM_CACHE_WARMER_MID_CACHE_ARGS
This parameter configures cache warming on a mid-level cache. When this is non-empty, cache warming will run automatically when a mid-level cache is started.
Arguments to enable cache warming are a string that may containing white space, or the arguments used to start a cache warmer. When a gem creates a mid-level shared page cache, if the value of this configuration parameter is empty, no cache warmer is started; if the value contains spaces only, a default cache warmer is started. Otherwise the value should contain valid arguments that will be used to invoke the cache warmer.
startcachewarmer arguments may be obtained using startcachewarmer -h. The only arguments that should be used are: -d -D -l -L -n -w.
This option is only used by remote gems that create a mid-level shared page cache. It is ignored by all other gems.
GEM_COMPRESS_TRANLOG_RECORDS
WIth this configuration parameter set to true, sessions will compress tranlog data records using lz4 compression before sending them to the Stone. The resulting tranlog files are significantly smaller.
GEM_KERBEROS_KEYTAB_FILE
Path to the Kerberos key table file. The keytab file only is required when single sign-on logins to GemStone are in use. The file contains pairs of Kerberos principals and encrypted keys. In this case, the Kerberos service is the service for a GemStone repository.
Refer to the GemStone System Administration Guide to learn about creating and maintaining this file.
GEM_KEYRING_DIRS
A list of directories which contain keys and certificates used for secure backup and restore.
SHR_PAGE_CACHE_LARGE_MEMORY_PAGE_SIZE_MB
Specifies the large memory page size in megabytes used when creating the shared page cache. This option is only supported on Linux, and is ignored on other platforms. A value of 0 means use the default large page size for the host. Normally the default large page size on Linux is 2 MB, but that default may be changed by the system administrator.
Valid large page sizes on Linux are 2 MB and 1024 MB. Not all systems support one or both large memory page sizes.
This setting is ignored if SHR_PAGE_CACHE_LARGE_MEMORY_PAGE_POLICY is set to 0.
STN_ALLOW_NO_SESSION_INIT
If false, GciLogin ignores the flag GCI_CLIENT_DOES_SESSION_INIT.
If true, GciLogin implements the flag GCI_CLIENT_DOES_SESSION_INIT.
Runtime equivalent: #StnAllowNoSessionInit (may only be set by SystemUser)
Default: FALSE
STN_CACHE_WARMER_ARGS
This parameter configures cache warming on the Stone’s cache on Stone startup. When this is non-empty, cache warming will run automatically when Stone starts.
Arguments to enable cache warming are a string that may containing white space, or the arguments used to start a cache warmer. On Stone startup, if the value of this configuration parameter is empty, no cache warmer is started; if the value contains spaces only, a default cache warmer is started. Otherwise the list should contain valid arguments that will be used to invoke the cache warmer.
The list of valid arguments may be obtained using startcachewarmer -h. The only arguments that should be used are: -d -D -l -n -w.
If this configuration option is specified with a non empty string, it overrides any settings for STN_CACHE_WARMER and STN_CACHE_WARMER_SESSIONS
STN_CACHE_WARMER_WAIT_MODE
Determines if and when startstone waits until cache warming has finished. The following values are allowed:
0 - disabled. startstone does not wait until cache warming has finished.
1 - startstone waits until cache warming has finished but only if stone is starting after a clean shutdown, or without tranlogs (i.e., startstone with -N option). Otherwise startstone does not wait for cache warming to finish. This is the default setting.
2 - startstone always waits until cache warming has finished.
Has no effect and is ignored if cache warming is not enabled.
STN_COMMIT_RECORD_BM_CACHING
When true, enables caching at the commit point of page allocation information needed when disposing a commit record. This option can reduce I/Os during commit record dispose when the commit record backlog is high, or when there is a lot of page preemption occurring in the shared cache.
When enabled, the maximum commit rate is slightly lower and commit latency is slightly higher because more work is done in the commit critical region in stone.
STN_GEM_PGSVR_CONNECT_TIMEOUT
The time in seconds that a remote gem will wait for a connection to a pgsvr on stone's machine to complete.
Runtime equivalent: #StnGemPgsvrConnectTimeout (may only be set by SystemUser)
STN_GEM_PRIVATE_PGSVR_ENABLED
If TRUE, a remote gem will start a private pgsvr process if the attempt to connect to a multithreaded pgsvr on stone's machine fails.
Runtime equivalent: #StnGemPrivatePgsvrEnabled (may only be set by SystemUser)
STN_GROUP_COMMITS
Specifies the maximum number of commits to group into a tranlog write. The default, 1, means commits are not grouped. Grouping is performed only if another session is waiting to commit while stone is processing a session's commit.
STN_TRANQ_TO_RUNQ_THRESHOLD
The number of sessions in the commit queue (waiting for the commit token) that are allowed to simultaneously process unions (read old commit records) while waiting for the commit token.
For example, if this parameter is set to 2, then sessions commitQueue[1], and commitQueue[2] (if they exist) will process unions. The first session in the commit queue , commitQueue[0], will never process unions since it will receive the token when the current commit completes.
Cache Statistic: (Stone) StnTranQToRunQThreshold
Runtime equivalent: #StnTranqToRunqThreshold (may only be set by SystemUser)
2.9 Utility and script changes
gemnetdebug change
The default for GS_DEBUG_VMGC_VERBOSE_OUTOFMEM is now 1, so more information will be printed by default on out of memory.
In this case, if no .csv file is configured, the .csv formatted data is now also written to the stdout (topaz console or gem log).
copydbf changes
copydbf supports lz4 compression
The -Z (uppercase) option has been added to allow lz4 compression for the resulting output file.
The new -z (lower case) option compresses using gzip, and is the same as the previously existing -C option.
Tranlog restore can read either lz4 or gzip, and copydbf can read both gzip and lz4 compressed files
Added secure backup options
The output for copydbf -i/-I for secure backup files includes some encryption information. In addition, the new options -K, -V, -W, -X, and -Y are supported only with secure backups. For more information on using these options for secure backups, see copydbf information about secure backups.
startnetldi
Process authentication using Kerberos
The NetLDI now supports Kerberos for client authentication, as described under Using Kerberos for NetLDI authentication.
To enable this, the -k keytab option has been added. When this is set, the NetLDI can use Kerberos to authenticate the host user id.
Version mismatch handling
The RPC connection to a NetLDI now uses SSL in v3.4. As a result, the NetLDI cannot definitely report a version mismatch since the connection itself does not complete. Attempting to connect to the 3.4 NetLDI with an RPC client using v3.3x or older shared libraries results in a message in the netldi log:
accept failed, SSL mismatch: we expect SSL, peer does not
expect SSL; client may be using old version of libgci library
startcachewarmer
Cache warming a working set
Cache warming now supports warming using a set of data pages that were previously in the cache and written to the working set file on disk. SeeCache warming based on previously loaded data pages for details.
If the working set file exists, with the name and location:
/opt/gemstone/locks/stoneNameHostid.workingSet.lz4
then the startcachewarmer will load valid pages from this file. Invalid pages will be ignored. The -d or -D options apply when that file does not exist.
Using the new option -w writeInterval, the startcachewarmer instructs the shared page cache monitor to write pages to the well-known file at the given interval, as described here.
waitstone
Headers simplified
Previously, the waitstone utility printed a complete header file with all build and version details. This has been simplified; now a single line is printed. For example:
unixprompt> waitstone gs64stone
waitstone[Info]: GemStone version '3.4.0'
arguments: gs64stone
Network service !#server!gs64stone is ready.
Wait for cache warming to complete
A fourth positional argument, waitForWarming, has been added.
If an integer larger than 0 is specified as the fourth argument to waitstone, waitstone will block until cache warming completes; this is useful when cache warming is automatically run on startup. Note that the specific value of the waitForWarming is not important.
Use of this option requires that you specify both of the preceding arguments rather than relying on the defaults.
stoplogreceiver
The undocumented and unsupported stoplogreciver -p argument, which specified the local port only, has been removed. The existing -P argument, which uses either the listening port or the local port depending on how the logreceiver was started, is the correct argument to use.
Legal to use netldid and stoned directly
startnetldi and startstone are utilities that invoke the netldid and stoned executables, block until startup is complete, and return control to the command line.
There are cases in which it is more useful to invoke a non-blocking utility. To support this, is it now allowed to invoke the netldid or stoned executables directly.
Note that these are in $GEMSTONE/sys, and thus may not normally be on the path.
2.10 Topaz Changes
Printing change
There are changes in how topaz displays characters to stdout. These changes only apply to stdout; characters that are written to files such as logged by output push are written as UTF-8, as before.
- Non-printing control characters are now returned as caret notation to avoid problems with x terminals. For example, the character with codePoint 11 is displayed as ^K.
- Characters over 255 are provided encoded. For example the character with codePoint 353, ลก, is displayed as \u0161.
Note that this is a change in behavior; previous versions sent UTF-8 to the terminal for Characters over 255, but this was not reliable for xterm/shells in all environments.
Option added for linked topaz that suppresses gemnetid in .topazini
The -L command line argument has been added to topaz.
Using this option instead of -l (lowercase ell) similarly invokes linked topaz, but any setting of gemnetid within a .topazini script or a script passed in using -I (uppercase eye) is ignored.
Since setting gemnetid causes linked topaz to login an RPC session, and input via .topazini is not echoed, this avoids the confusion when an intended linked topaz login inadvertently becomes RPC.
Setting gemnetid explicitly by entering the topaz set gemnetid command, including in files input via the input command, is not affected by the -L option, and will set the linked topaz environment to login RPC.
set cachename changes
The topaz set cachename command sets the name of the process, as displayed in VSD.
Previously, this was only applied to linked sessions; now, both linked and RPC sessions may use set cachename.
Previously, the cache name had the numeric session id appended to the end of the name; now, the name is used as specified.
The cache name is still limited to 31 characters. Now, it displays a warning when the name is truncated; previously it was silently truncated.
-u sets cachename
The topaz -u command line argument previously did not do anything, but was useful for identifying the process in the OS.
Now, the name provided by -u is used to set the cachename, equivalent to using the topaz set cachename command.
Custom arguments following POSIX end of options marker
The topaz and gem command lines now accept custom arguments, specified using by using -- following the regular options. Any text following ’ -- ’ on the command line are passed to the application without interpretation.
-- stringOfArgs
These argument can be accessed, for example, by invoking a System method:
unixprompt> topaz -l -- foo bar
<topaz startup and login headers>
topaz 1> run
System commandLineArguments printString
%
anArray( 'topaz', '-l', '--', 'foo', 'bar')
Added LIST options
Added option linenumbers
List allows you to print the source of a method. The new linenumbers option allows you to get a listing of the method source that includes line numbers. For example,
topaz 1> set class Set
topaz 1> list linenumbers method: asSet
1 asSet
2
3 "Returns a Set with the contents of the receiver."
4
5 ^ self
Added options primitives, cprimitives
List selectors of all methods which are primitives. These commands accept an optional string token, which restricts the list to selectors that contain the token.
primitives or prim lists instance methods, cprimitives or cprim lists class methods.
Added argument for selectors and cselectors
list selectors and cselectors allow you to find instance or class method selectors within the currently set class. Now, you may also include a token after the selectors keyword, which will be used to filter the results. For example:
topaz 1> set class Time
topaz 1> list cselectors mill
fromMilliseconds:
millisecondClockValue
millisecondsElapsedTime:
Added SUBHIERARCHY command
The subhierarchy command has been added, which prints a hierarchy report for all subclasses of the current class without an argument, or of the argument class.
Added RUNBLOCK command
The topaz command runblock was added to support internal debugging.
runblock takes two arguments on the command line, and the following lines up to the next % must be the source for a block with between 0 and 10 block variables.
The first argument is used for self in the block, and can be anything that can be specified on the command line.
The second argument must be an Array of size N, N <= 10, where N is the number of argument variables. This second argument can be specified using ** or @OOP, or named in UserGlobals.
SESSIONINIT to allow login when session initialization fails
The topaz set command has a new argument sessioninit.
This command allows you to bypass the GsCurrentSession initialize execution that is normally done on every login. This is important for cases such as upgrades that require method recompile, or errors in methods invoked during initialize.
To control the ability to bypass loginHook:, set sessioninit is only allowed when the new configuration parameter STN_ALLOW_NO_SESSION_INIT has been set. This can be set during runtime only by SystemUser, using the runtime parameter #StnAllowNoSessionInit. For example:
System stoneConfigurationAt: #StnAllowNoSessionInit put: true
When this is set, additional status messages are printed to topaz during login.
When STN_ALLOW_NO_SESSION_INIT is set to true, GsCurrentSession initialize and the loginHook: block are executed, but errors do not prevent login; this allows debugging the loginHook: initialization code.
To turn off execution entirely, in topaz, execute:
set sessioninit off
This disables execution of GsCurrentSession initialize for subsequent logins.
2.11 Cache Statistics Changes
statmonitor changes
New option to specify the hours for restart
The -k listOfTimes option has been added.
This sets statmonitor to restart each day at specified times. Either the -r or -R flag must also be specified, and neither -h nor -t flags may be specified. The list of times must start and end with a single quote and times must be separated by a comma. Hours must be specified in 24 hour format.
The times do not need to be in order, but should not contain duplicates. The restart will be performed at the next sampling interval after the time, so may be delayed with long sample intervals.
For example, to restart statmonitor at 1:30 am, 9:30 am and 1:30 pm:
statmonitor -r -k '01:30,9:30,13:30' gs64stone
The following statistics have been removed:
LogRecordsIoCount (replaced by TranlogIoCount)
Changes in existing statistics
NewGenSizeBytes, OldGenSizeBytes, PermGenSizeBytes, and CodeCacheSizeBytes are now 64 bit.
The following statistics have been added:
ActiveCHeapLogBuffers (Stone)
Number of C Heap tranlog buffers in stone for which tranlog writes are in progress.
CommitQueueHeadNoMsg (Stone)
The number of times a session in commit queue was not ready for token and not ready for service.
CommitQueueHeadNotReadyCount (Stone)
The number of times the session at head of commit queue was not ready to receive the commit token.
CommitQueueNotSerializing (Stone)
The number of times a session in commit queue was not in serialization.
CommitQueueSymbolWait (Stone)
The number of times a session in commit queue was waiting for SymbolGem to commit.
CommitRecordsDisposedNotCached (Stone)
The number of commit records not in stone’s CR cache at the time they were disposed.
FreeLogBuffers (Stone)
Number of free tranlog buffers in shared memory.
MemMappedSize (Gem)
The size in bytes of memory mapped regions used by multithreaded operations
NumWorkingSetWrites (SPC Monitor)
Number of writes to the cache warmer working set file performed since the system was started.
RcTransQueueSize (Stone)
Shows the number of sessions waiting for an rc commit to complete so that their rc retry can be serviced.
StnAioCompletedHeapBuffers (Stone)
Number of tranlog buffers written from C heap memory.
StnAioCompletedSharedBuffers (Stone)
Number of tranlog buffers written from shared memory.
StnAiosWaitedForWriteThread (Stone)
Number of times a tranlog write was delayed because all tranlog write threads were busy.
TranlogBuffersWritten (Gem, Stone)
The number of tranlog buffers written to the tranlogs.
TranlogIoCount (Stone)
The number of pwritev calls made by stone to write to the transaction logs since stone was last started.
AIX System stats
On AIX, added System Pages statistics
The following stats are now available, in a new category "System Pages". They are only collected if -A or -W is specified.
These SystemPages stats are collected using vmgetinfo(), vs. AIX_System stats which are collected using the perfstat API.
AvailableMemory
Number of bytes of memory available without paging. From the memavailable member of the vminfo64 struct returned by the vmgetinfo() AIX function.
ClientSegPages
Count of pages in use for the client segment. From the numclseguse member of the vminfo64 struct returned by the vmgetinfo() AIX function.
ClientSegPagesPinned
Count of pages pinned for the client segment. From the numclsegpin member of the vminfo64 struct returned by the vmgetinfo() AIX function.
LoanedPages
Number of pages loaded to the hypervisor for CMO. From the nloaned member of the vminfo64 struct returned by the vmgetinfo() AIX function.
MemGuardRemovedFail
Number of pages mguard failed to remove. From the memgrd_fail_pgs member of the vminfo64 struct returned by the vmgetinfo() AIX function.
MemGuardRemovedOk
Number of pages mguard successfully removed. From the memgrd_succ_pgs member of the vminfo64 struct returned by the vmgetinfo() AIX function.
NonRemovablePages
Number of nonremovable pages for DR. From the normlmbmem member of the vminfo64 struct returned by the vmgetinfo() AIX function.
NonSystemPages
Number of pages on SCBs not marked V_SYSTEM. From the nonsys_pgs member of the vminfo64 struct returned by the vmgetinfo() AIX function.
PageAheadMax
Maximum number of page ahead pages. From the maxpgahead member of the vminfo64 struct returned by the vmgetinfo() AIX function.
PageAheadMin
Minimum number of page ahead pages. From the minpgahead member of the vminfo64 struct returned by the vmgetinfo() AIX function.
PageOutsFileBuferRemote
Count of file buffer remote page outs. From the numremote member of the vminfo64 struct returned by the vmgetinfo() AIX function.
PageOutsFileBuffer
Count of file buffer page outs. From the numpout member of the vminfo64 struct returned by the vmgetinfo() AIX function.
PageSpaceFreeBlocks
Number of free paging space blocks. From the psfreeblks member of the vminfo64 struct returned by the vmgetinfo() AIX function.
PagesRepagedComp
Number of computational pages repaged. From the nrepaged member of the vminfo64 struct returned by the vmgetinfo() AIX function.
PagesRepagedFile
Number of file buffer pages repaged. From the nrepaged member of the vminfo64 struct returned by the vmgetinfo() AIX function.
PagesReplacedComp
Number of computational pages replaced. From the nreplaced member of the vminfo64 struct returned by the vmgetinfo() AIX function.
PagesReplacedFile
Number of file buffer pages replaced. From the nreplaced member of the vminfo64 struct returned by the vmgetinfo() AIX function.
PersistSegPages
Count of pages in use for the persistent segment. From the numpseguse member of the vminfo64 struct returned by the vmgetinfo() AIX function.
PersistSegPagesPinned
Count of pages pinned for the persistent segment. From the numpsegpin member of the vminfo64 struct returned by the vmgetinfo() AIX function.
PinnablePages
Number of pages available for pinning. From the pfavail member of the vminfo64 struct returned by the vmgetinfo() AIX function.
PinnablePagesAppLevel
Number of pages available for pinning by applications. From the pfpinavail member of the vminfo64 struct returned by the vmgetinfo() AIX function.
RemoteAllocations
Number of remote allocations. From the numralloc member of the vminfo64 struct returned by the vmgetinfo() AIX function.
RepagedCompFrames
Count of repaged computational frames. From the rpgcnt member of the vminfo64 struct returned by the vmgetinfo() AIX function.
RepagedFileFrames
Count of repaged files frames. From the rpgcnt member of the vminfo64 struct returned by the vmgetinfo() AIX function.
SegmentIdHw
Max index + 1 of sids ever used. From the hisid member of the vminfo64 struct returned by the vmgetinfo() AIX function.
SigDangerThreshold
Threshold of free memory pages below which the operating system may send SIGDANGER to processes. From the npswarn member of the vminfo64 struct returned by the vmgetinfo() AIX function.
SigKillThreshold
Threshold of free memory pages below which the operating system may send SIGKILL to processes. From the npskill member of the vminfo64 struct returned by the vmgetinfo() AIX function.
SoftPagesClientSeg
Number of soft pages in use for the working segment. From the soft_clseguse member of the vminfo64 struct returned by the vmgetinfo() AIX function.
SoftPagesPersistSeg
Number of soft pages in use for the working segment. From the soft_pseguse member of the vminfo64 struct returned by the vmgetinfo() AIX function.
SoftPagesWorkingSeg
Number of soft pages in use for the working segment. From the soft_wseguse member of the vminfo64 struct returned by the vmgetinfo() AIX function.
SpecialDataSegIds
Number of special dataseg id's. From the numspecsegs member of the vminfo64 struct returned by the vmgetinfo() AIX function.
SpecialDataSegIdsFree
Number of free special dataseg id's. From the numspecfree member of the vminfo64 struct returned by the vmgetinfo() AIX function.
SpecialDataSegIdsHighWater
Highwater count of special dataseg id's. From the specsegshi member of the vminfo64 struct returned by the vmgetinfo() AIX function.
SystemPages
Number of pages on SCBs marked V_SYSTEM. From the system_pgs member of the vminfo64 struct returned by the vmgetinfo() AIX function.
SystemReservedBlocks
Number of system reserved blocks. From the pfrsvdblks member of the vminfo64 struct returned by the vmgetinfo() AIX function.
TrueFreePages
True number of free 4K memory pages. From the true_numfrb member of the vminfo64 struct returned by the vmgetinfo() AIX function.
TrueMemPages
True total number of logical and physical 4K memory pages. From the true_memsizepgs member of the vminfo64 struct returned by the vmgetinfo() AIX function.
UnmanagedPages
Number of pages not on SCBs. From the unmngd_pgs member of the vminfo64 struct returned by the vmgetinfo() AIX function.
WorkingSegPages
Count of pages in use for the working segment. From the numwseguse member of the vminfo64 struct returned by the vmgetinfo() AIX function.
WorkingSegPagesPinned
Count of pages pinned for the working segment. From the numwsegpin member of the vminfo64 struct returned by the vmgetinfo() AIX function.
The following are additional AIX_System stats:
Backtracks
Count of backtracks. From the backtrks member of the vminfo64 struct returned by the vmgetinfo() AIX function.
ExecFilledPages
Count of exec filled pages. From the exfills member of the vminfo64 struct returned by the vmgetinfo() AIX function.
ExtendXptWaits
Count of extend XPT waits. From the extendwts member of the vminfo64 struct returned by the vmgetinfo() AIX function.
FreeFrameWaits
Count of free frame waits. From the freewts member of the vminfo64 struct returned by the vmgetinfo() AIX function.
FreeListSize
Number of pages in the free list. From the numfrb member of the vminfo64 struct returned by the vmgetinfo() AIX function.
LargePagesFree
Number of free large memory pages. From the lgpg_numfrb member of the vminfo64 struct returned by the vmgetinfo() AIX function.
LargePageSize
Size in bytes of a large memory page on this host. From the lgpg_size member of the vminfo64 struct returned by the vmgetinfo() AIX function.
LargePagesTotal
Total number of large memory pages. From the lgpg_cnt member of the vminfo64 struct returned by the vmgetinfo() AIX function.
LargePagesUsed
Number of large memory pages in use. From the lgpg_inuse member of the vminfo64 struct returned by the vmgetinfo() AIX function.
LargePageUsedHighWater
High water number of large memory pages used. From the lgpg_hi member of the vminfo64 struct returned by the vmgetinfo() AIX function.
LockMisses
Count of lock misses. From the lockexct member of the vminfo64 struct returned by the vmgetinfo() AIX function.
MaxClient
The maximum number of pages that may be used for client pages. From the maxclient member of the vminfo64 struct returned by the vmgetinfo() AIX function.
MaxFree
The threshold of free pages above which the page-stealing algorithm will stop stealing pages to replenish the free list. From the maxfree member of the vminfo64 struct returned by the vmgetinfo() AIX function.
MaxPerm
The threshold of free pages below which the page-stealing algorithm may steal computational pages as well as file buffer pages. If the free page list is larger than this value, then the page-stealing algorithm will only steal file buffer pages. From the maxperm member of the vminfo64 struct returned by the vmgetinfo() AIX function.
MinFree
The threshold of free pages below which the page-stealing algorithm will begin to steal pages to replenish the free list. From the minfree member of the vminfo64 struct returned by the vmgetinfo() AIX function.
MinPerm
The threshold of free pages below which the page-stealing algorithm may steal computational and file buffer pages regardless of the repaging rate. From the minperm member of the vminfo64 struct returned by the vmgetinfo() AIX function.
NumClient
Number of client frames. From the numclient member of the vminfo64 struct returned by the vmgetinfo() AIX function.
NumPerm
Number of pages used to cache files. From the numperm member of the vminfo64 struct returned by the vmgetinfo() AIX function.
PageReclaims
The total number of page reclaims; both from the free list and from disk. Page reclaims are caused by a reference to a page that has been stolen from a process by the page daemon.
PendingIoWaits
Count of pending I/O waits. From the pendiowts member of the vminfo64 struct returned by the vmgetinfo() AIX function.
RealMemoryPages
The real memory size in 4K pages. From the memsizepgs member of the vminfo64 struct returned by the vmgetinfo() AIX function.
VirtualPagesAccessed
The number of virtual pages accessed. From the numvpages member of the vminfo64 struct returned by the vmgetinfo() AIX function.
ZeroFilledPages
The total number of pages have been block-cleared to contain all zeros.