Defaults File for epadmin

< Previous		Next >

Defaults File Introduction

A defaults file can be used to specify default values for the following global parameters:

keystore
keystorepassword
truststore
truststorepassword

If these parameters are specified in the defaults file, they can be omitted from epadmin invocations that would otherwise require them.

The default location for the defaults file is $HOME/.epadmin/defaults. This location can be overridden per command execution using the defaultsfile global parameter. In addition, the defaults file can be ignored per command execution using the ignoredefaultsfile global parameter. Finally, for the keystore and truststore parameters, if they are specified both in the defaults file and on the command line, the command line value takes precedence. The associated password precedence is summarized in the following table.

Key or Trust Store Value is Specified...	Password Precedence
On command line	Password must be specified on command line. Value in defaults file is ignored.
In defaults file	If there is a password in the defaults file, it is always used and a specified command line password is ignored. If there is no password in the defaults file, a command line password value is required.

Defaults File Structure

The defaults file consists of the following sections:

[Security]: Optional section used to specify the keystore to use when decrypting any encrypted passwords specified in the defaults file. There can only be one Security section in a defaults file and it is required, if there are encrypted passwords in the defaults file.
[Service]: Optional section specifying one or more service names, with multiple service names separated by a space. The service names can be fully-qualified, partially-qualified, or a cluster name. There can be multiple Service sections in a defaults file.
[Address]: Optional section specifying one or more network addresses in the form hostname:adminport. Multiple network addresses must be separated by a space. There can be multiple Address sections in a defaults file.

Section names are case insensitive.

The beginning of a section is marked by a line that begins with a left square bracket and ends with a right square bracket (after any leading and trailing white space is removed). The end of a section is marked by the start of a new section or an end of file.

# Security section
#
[Security]

# Service section
#
[Service A.X B.X]

# Address section
#
[Address myhost.example.com:12345 myotherhost.example.com:12345]

Within the defaults file:

Blank lines are ignored.
Lines starting with the # character are comment lines (with leading white space removed) and are ignored.

Within a section:

Property values are specified using name=value pairs.
Each property must be on a separate line.
Property values that are relative file paths are relative to $HOME/.epadmin.
Property values that are passwords can be encrypted using the encrypt secret command .

The supported property values are shown in the following table:

Property Name	Supported Sections	Description
`keystore`	`Security`	Path to an epadmin secret key store file. When this property is in the `Security` section, the key store pointed to is used to decrypt encrypted passwords in this defaults file.
`keystorepasswordfile`	`Security`	Path to a plain text password file for the epadmin secret key. Use file permissions to protect the contents of this file. If this property does not exist, and a password must be decrypted, a password prompt is displayed.
`keystore`	`Address` and `Service`	Path to a client authentication key store file.
`keystorepassword`	`Address` and `Service`	Key store password for the client authentication key file. This value can be encrypted.
`truststore`	`Address` and `Service`	Path to a client authentication trust store file.
`truststorepassword`	`Address` and `Service`	Trust store password. This value can be encrypted.

See Clarifying keystore Parameters below for more on the difference between the two uses of keystore.

When an epadmin command is executed, it uses the most specific service or address match in the defaults file. If there are multiple equivalent matches, the first one found is used. Service sections are used when the servicename parameter is specified to run a command. Address sections are used when hostname and adminport are specified to run a command. For example, consider this defaults file:

#  Cluster X 
#
[Service X]
    keystore = /path/to/keystore1.pem

#  Node A.X
#
[Service A.X]
    keystore = /path/to/some/other/keystore2.pem

With those defaults, an epadmin command that specifes servicename=A.X uses /path/to/some/other/keystore2.pem.

Defaults File Example

Here is a full example of a defaults file.

[Security]
  #
  # Keystore to use when decrypting encrypted entries in this file.
  #
  keystore = /path/to/keystore.ks

  #
  # Plain text keystore password.  Protect the contents of this file
  # with appropriate file permissions.  Or, omit this property from
  # the defaults file, in which case, epadmin prompts for the 
  # keystore's password if not specified.
  #
  keystorepasswordfile = /path/to/password/file
  
#
# Fully-qualified service name.
# 
# Multiple entries separated by spaces.
#
[Service A.Y.X B.Y.X C.Y.X]
  keystore = /path/to/client/auth/keystore.pem
  keystorepassword = notsecret
  truststore = /path/to/client/auth/truststore.pem
  truststorepassword = #!!MoupLc8mgVhE5wNVpgCNiQgs96opSn7kkGB1qpKW70bL

# Partially-qualified service name
[Service .Y.X]
  # ...

# Cluster name
[Service X]
  # ...

# Host/port pair
[Address myhost.tibco.com:12345]
  # ...

Clarifying keystore Parameters

There are two sets of --keystore and --keystorepassword parameters:

A pair of global parameters related to client authentication for nodes.
A pair of target parameters related to epadmin encryption.

Features of keystore Global Parameters

The global parameters --keystore and --keystorepassword have these features:

keystore points to a PKCS#12 or PEM key file containing certificate and keys necessary for any epadmin command to connect to a node that requires client authentication.
The key file pointed to must have the .p12 or .pem extension.
Global keystore and keystorepassword parameters can be stored in one or more [Service] sections of an epadmin defaults file:
- The [Service] section of a defaults file defines parameters for an exact node, or set of nodes, or a cluster.
- In the [Service] section, keystore and keystorepassword point to the TLS keys that allow client communication with the TLS-enabled nodes defined in that [Service] section.
- You can have more than one [Service] section, each with different sets of key files.

Features of keystore Target Parameters

The target parameters --keystore and --keystorepassword have these features:

The epadmin install node command and all epadmin secret commands take --keystore and --keystorepassword target parameters.
The key file pointed to must be created with epadmin create secret.
This key file is used to encrypt and decrypt passwords and other strings in configuration files as described in Encrypting Sensitive Configuration Data.
This file does not have a required extension (although this Guide suggests using .ks).
Target keystore and keystorepasswordfile parameters can be stored in the [Security] section of an epadmin defaults file. There, they are ONLY used to decrypt encrypted strings in the same defaults file.
Notice that the defaults file parameter is keystorepasswordfile, not keystorepassword. This points to a local plain text file that you protect with operating system access control, such as chmod 600 keyfile.ks.