ctsthl Command

Purpose

Displays and modifies the contents of a cluster security services trusted host list file.

Syntax

ctsthl {-a | -d | -h | -l | -s } [ -f trusted_host_list_file ] [ -n host_name ] [ -m method ] [ -p identifier_value ]

Description

This command displays and modifies the contents of a cluster security services trusted host list file. Unless the -f flag is provided, the command performs its operations on the trusted host list file configured in the ctcasd.cfg file. ctsthl allows the command user to add, modify, or remove entries in the trusted host list for specific hosts. When a host is added or modified, the command user must provide the following information:

The identity of the host (zathras.ibm.com or 129.34.128.54, for example)
The host identifier value to be used for this host, in a character string format representing the identifier's hexadecimal value (b87c55e0, for example)
The method that was used to generate the host identifier (see the description of the ctskeygen -i command)

The command validates the generation method name, converts the character string representation to binary form, and creates a new entry within the trusted host list file for this host. Generally, the host identifier value is quite large. For instance, the character representation of a RSA 1024-bit generated identifier is over 256 characters in size. This can cause a problem on systems such as AIX®, which limit the command line length to a smaller size. To avoid this problem, use the ctsthl -a command from a shell script, or in conjunction with the xargs command.

When the contents of the trusted host list file are displayed, ctsthl provides the following information for each entry:

The network identity of the host
The host identifier value for that host, represented as a character string
The method used to generate the host identifier

Flags

-a: Adds to or replaces a host entry in the trusted host list. The -n, -m, and -p flags also must be provided. If the host specified already exists in the trusted host list file, the entry for that host is modified to match the information provided to this command.
-d: Removes a host's entry from the trusted host list file. The -n flag also must be provided to indicate the host being removed.
-h: Writes the command's usage statement to standard output.
-l: Instructs the command to list the contents of the trusted host list file. If this flag is combined with the -a or -d flags the contents are displayed after these flags are processed. If this flag is combined with the -s flag, any new entries made by the command are displayed, as well as any public key mismatches detected for host names and IP addresses supported by the local system.
-f trusted_host_list_file: Specifies the fully-qualified path name of the trusted host list file. If this flag is not provided, the trusted host list file configured in the ctcasd.cfg file is used.
-n host_name: Specifies the identity of the host to be used in this operation. The identity should be a host name or IP address specification by which the host is known to the cluster's network.
-m method: Instructs the command to use the specified key generation method in creating the host identifier keys. You can use the ctskeygen -i command to display valid values for method.
-p identifier_value: Specifies the host identifier value to be stored for the host. This is a character string that represents the hexadecimal value of the host identifier to be stored for this identifier. For example, if the host identifier value is 0xB87C55E0, this flag would be specified as -p b87c55e0. Generally, In AIX, host identifier keys will be much longer than this example, making it too large for the command line limit on some systems such as AIX. If the resulting command line is too large, use xargs to extend it, or issue the command from a shell script.
-s: Explores the local system for all known IP addresses and host names associated with AF_INET-configured and active adapters that the daemon can detect. For any host name or IP address on the local system that is not found in the local system's trusted host list file, an entry is added to associate that value with the local system's public key value.

Parameters

network_ID: Specifies the security network identifier to be mapped. This should be an identity that can be assumed by a client application of a trusted service.

Security

Permissions on the ctsthl command permit only root to run the command.

Exit Status

0: The command completed successfully.
4: The caller invoked this command incorrectly, omitting required flags and parameters, or using mutually exclusive flags. This command terminated without processing the request.
6: A memory allocation request failed during the operation of this command. The command was unable to complete the requested action.
10: The command was unable to locate any configured and active network (AF_INET) interfaces for the local system while processing the -s flag. The local system's identities may not be properly recorded to the trusted host list. Verify that at least one AF_INET or AF_INET6 interface is defined and active on the local system and reissue the command.
12: The command user does not have sufficient permission to view or modify the contents of the trusted host list file.
21: The trusted host list file could not be located, or could not be extended to contain a new public key value.
30: ctsthl was unable to obtain exclusive use of the trusted host list file. Another instance of this command may be running and attempting to modify the keys, or the ctcasd daemon may be examining these files. Retry the command at a later time.
31: The public key value specified by the -p flag does not end on a full byte boundary. Make sure the value contains an even number of digits.
37: The key file appears to be corrupted. Try to view the public key value using the -d flag to verify if the file is corrupted. Follow the problem resolution advice listed in the error message for further recovery action.

Restrictions

Cluster security services supports its own host identifier format and trusted host list file format only.
Trusted host lists are modifiable using this command only.
Cluster security services does not provide an automated utility for creating, managing, and maintaining trusted host lists throughout the cluster. This is a procedure left to either the system administrator or the cluster management software.

Standard Output

When the -h flag is specified, this command's usage statement is written to standard output. When the -l flag is specified, the contents of the trusted host list file are written to standard output.

Standard Error

Descriptive information for any detected failure condition is written to standard error.

Examples

To view the contents of the trusted host contained in the file /mythl, enter:
```
ctsthl -l -f /mythl
```
To add an entry to the default trusted host list file for the system zathras.ibm.com, enter:
```
ctsthl -a -n zathras.ibm.com -m rsa1024 -p 120400a9...
```
Note that this example does not complete the entire identifier value.
To add an entry to the default trusted host list file for the system 129.23.128.76, enter:
```
ctsthl -a -n 129.23.128.76 -m rsa1024 -p 120400a9...
```
Note that this example does not complete the entire identifier value.
To remove an entry for zathras.ibm.com from the default trusted host list, enter:
```
ctsthl -d -n zathras.ibm.com
```

Location

/opt/rsct/bin/ctsthl: Contains the ctsthl command

Files

/opt/rsct/cfg/ctsec_map.global: The default identity mapping definition file. This file contains definitions required by the RSCT cluster trusted services in order for these systems to execute properly immediately after software installation. This file is ignored if the cluster-wide identity mapping definition file /var/ct/cfg/ctsec_map.global exists on the system. Therefore, any definitions within this file should also be included in the cluster-wide identity mapping definition file, if that file exists.
/var/ct/cfg/ctsec_map.local: Local override to the cluster-wide identity mapping definitions. Definitions within this file are not expected to be shared between nodes within the cluster.
/var/ct/cfg/ctsec_map.global: Cluster-wide identity mapping definitions. This file is expected to contain identity mapping definitions that are common throughout the cluster. If this file exists on the system, the default identity mapping definition file is ignored. Therefore, if this file exists, it should also contain any entries that would also be found in the default identity mapping definition file.