Setting up the Server Keychain
The keystore and each certificate entry are protected by passwords stored in the server keychain file. The location of the keychain file is specified in the value of the <url> element under the <keychain> element of the server's configuration file.
For example, with this
server configuration, when the server starts up, the keychain file would be searched for in the user's (process owner's) home directory. In the configuration example, a keychain file called
server1keychain.tkc is searched for when server1 is started.
The keychain file should have the following entries:
An entry for the local server's keystore entry.
An entry for every server that the local server will connect to.
Entries are created using the keychain script found in the Terracotta kit's tools/security/bin directory.
Creating an Entry for the Local Server
Create an entry for the local server's keystore password:
tools/security/bin/keychain.sh -O <keychain-file> <certificate-URI>
where <keychain-file> is the file named in the server configuration's <keychain>/<url> element (including correct path), and <certificate-URI> is the URI value in the server configuration's <ssl>/<certificate> element.
Note: The <certificate-URI> must match the server configuration's <ssl>/<certificate> element exactly, including the path to the keystore.
By default, the keychain file stores passwords using an obfuscation scheme, requiring the use of
-O (hyphen capital letter O) with the keychain script for
any operation on the file. To switch a more secure encryption-based scheme, see
Using Encrypted Keychains.
If the keychain file does not exist, add the -c option to create it:
tools/security/bin/keychain.sh -O -c <keychain-file> <certificate-URI>
You will be prompted to enter a password to associate with the URI. You must enter the same password used to secure the server's certificate in the keystore.
For example, to create an entry for server1 from the configuration example above, enter:
tools/security/bin/keychain.sh -O server1keychain.tkc
jks:server1alias@/the/path/keystore-file.jks
Terracotta Management Console - Keychain Client
Enter the password you want to associate with this URL: server1pass
Confirm the password to associate with this URL: server1pass
Password for jks:server1alias@/the/path/keystore-file.jks successfully stored
Creating Entries for Remote Servers
Entries for remote servers have the format tc://<user>@<host>:<group-port> . Note that the value of <user> is specified in each server configuration's <security>/<auth>/<user> and is not related to the user running as the process owner. If a value for <security>/<auth>/<user> is not specified, the username "terracotta" is used by default.
For example, to create an entry for server2 in server1's keychain, use:
tools/security/bin/keychain.sh -O server1keychain.tkc
tc://server2username@172.16.254.2:9530
If the keychain file does not exist, add the -c option:
tools/security/bin/keychain.sh -O -c server1keychain.tkc
tc://server2username@172.16.254.2:9530
You will be prompted to enter a password to associate with the entry server2username@172.16.254.2:9530.
An entry for server1 must also be added to server2's keychain:
tools/security/bin/keychain.sh -O server2keychain.tkc
tc://server1@172.16.254.1:9530