Commands Reference, Volume 1

ctsthl Command

Purpose

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

Syntax

ctsthl {-a | -d | -h | -l}
[-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 default trusted host list file /var/ct/cfg/ct_has.thl. 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 network name of the host (zathras.ibm.com, 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 name 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 or replaces a host entry to the trusted host list. The -n, -m, and -p flags must also 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 must also 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.
-f trusted_host_list_file: Instructs the command to display or modify the trusted host list stored in the named file. If this flag is not provided, the default trusted host list file /var/ct/cfg/ct_has.thl is used.
-n host_name: Specifies the name of the host to be used in this operation. The name should be a name 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, 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.

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: ctsidmck successfully found a mapped identity for network_ID.
3: The command detected a failure in the operation of the cluster security library mechanism pluggable module (MPM) corresponding to the security mechanism what was requested. The command was unable to search for a possible mapped identity for network_ID in this case. This failure may be accompanied by descriptive output indicating the nature of the MPM failure. Consult this output and perform any recommended actions.
4: The caller invoked the command incorrectly, omitting required options and arguments, or using mutually exclusive options. The command terminated without attempting to find a mapped identity for network_ID.
6: A memory allocation request failed during the operation of the command. The command was unable to search for a possible mapped identity for network_ID in this case.
21: The command was unable to locate any of the identity mapping definition files on the local system. The command was unable to search for a possible mapped identity for network_ID in this case. Verify that at least one identity mapping definition file exists on the system.
22: The command was unable to dynamically load the cluster security library mechanism pluggable module (MPM) corresponding to the security mechanism what was requested. The module may be missing, corrupted, or one of the shared libraries used by this module may be missing or corrupted. The command was unable to search for a possible mapped identity for network_ID in this case. This failure may be accompanied by descriptive output indicating the nature of the MPM failure. Consult this output and perform any recommended actions.
37: At least one of the identity mapping definition files on the system appears to be corrupted. The command was unable to search for a possible mapped identity for network_ID in this case. Verify that none of the identity mapping files are corrupted, truncated, or contain syntax errors.
38: ctsidmck could not locate a mapped identity for network_ID. No entry within any of the identity mapping definition files yielded a mapped identity for the specified security network identifier.

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.

Standard Error

Descriptive information for any detected failure condition is written to the 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 remove an entry for zathras.ibm.com from the default trusted host list, enter:
```
ctsthl -d -n zathras.ibm.com
```

Location

/usr/sbin/rsct/bin/ctsthl: Contains the ctsthl command

Files

/usr/sbin/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.

Related Information

Commands: ctskeygen

Daemons: ctcasd

Files: ct_has.thl