ctmsetown

The ctmsetown command line utility manages the authentication credentials of Run as Users for both local and Agentless jobs. In addition, the ctmsetown utility also enables the authentication details of users to be imported or exported from different Control-M environments.

When a job is submitted, Control-M/Server attempts to find the owner and hostname authentication details.

If the owner and hostname are found, Control-M/Server uses these credentials.
If the specified hostname is not found, Control-M/Server tries to find the owner on host <All>.
If the run_as is found on host <All>, Control-M/Server uses these credentials.
If the run_as is not found on the specified hostname or on host <All>, Control-M/Server uses empty credentials.

Using ctmsetown through Control-M/Agent, the functionality of the ctmsetown utility (when invoked from Control-M/Agent), is limited to updating passwords of existing owners. Using the utility, job owner passwords can be updated through Control-M/Agent for:

Jobs running on Agentless hosts
Jobs running on Control-M/Agent for Windows that is configured to work in 'logon as user' mode"
Jobs running on Control-M/Agent for UNIX that is running in non-root mode

Running the ctmsetown Utility

This procedure describes how to run the ctmsetown utility, which manages the authentication credentials of Run as Users for both local and Agentless jobs.

Begin

Do one of the following:
- UNIX: Log in to a Control-M/Server account
- Windows: Open a command prompt window where Control-M/Server is installed.
- NOTE: You can also run this command where Control-M/Agent is installed.
Type one of the following commands:
- ctmsetown -action add -run_as <user name> -host <host name>
  [-password <password> | -keyname <key name> [-passphrase <key passphrase>]]
- ctmsetown -action update -run_as <user name> -host <host name> [-password <password> | -keyname <key name > [-passphrase <key passphrase>]]
- ctmsetown -action delete -run_as <user name> -host <host name>
- ctmsetown -action list [-run_as <user name>] [-host <host name>]
- ctmsetown -action export -filename <export file name>
- ctmsetown -action import -filename <import file name> -data append|truncate
- ctmsetown help
Specify the following command to invoke the ctmsetown utility from Control-M/Agent:

ctmsetown -action update -owner <user name> -host <host name> -password <new password> -oldpassword <old password>

ctmsetown Utility Action Parameters

The following table describes the actions in the ctmsetown utility:

Action	Description
add	Specifies the security details of a new owner entry (user).
update	Modifies the security details of an existing owner entry (user).
delete	Removes the security details of an owner entry. The owner name and host name must match an existing entry in the folder.
list	Lists the details of the user. Wildcards can be used to specify -owner and -host parameters, as follows: * represents any number of characters ? represents any single character
export	Exports the security details of the existing users to a text file. ctmsetown -action export -filename $HOME/ctm_server/data/user_report.txt Exporting the text file from Windows to UNIX or from UNIX to Windows, requires EOL transformation.
import	Imports the details of the users stored in the specified import file.
help	Displays the usage of the ctmsetown utility.

ctmsetown Utility Parameters

The following table describes the ctmsetown utility parameters:

Parameter	Description
-run as	Specifies the name of the user under whose name the job will run.
-host	Specifies the name of the computer where the owner of the job is defined. Specify <All> to include all hosts. ctmsetown -action delete -run_as s -host "<All>"
-password	Specifies the password of the owner. The password cannot exceed 120 characters.
-old password	Specifies the existing password that the user is changing. This parameter is mandatory only when the ctmsetown utility is executed from the Agent.
-key name	Defines the logical name of the key. The key itself is kept in a separate folder with its passphrase. For more information about generating and maintaining the key, see ctmkeygen. The same key can be used for multiple users.
-pass phrase	Specifies the phrase used to encrypt the key itself. Used only if -keyname is defined.
-file name	Specifies the name of the file that contains the security details of the users. The filename cannot exceed 1024 characters. This parameter is used only when either -action export or -action import is specified.
-data	Describes what action to take with the data from the imported text file. Valid actions: append: details of the users from the imported text file are added to the existing users truncate: details of the users from the imported text file replace the details of the existing users

ctmsetown Utility Examples

The following are examples of the ctmsetown utility commands that are run from Control-M/Server, apart from the last example which is run from Control-M/Agent.

To create an entry with the security details of a user whose name is username1, the name of the host computer is saturn and the user password is pass01, specify the following command:

ctmsetown -action add -run_as username1 -host saturn -password pass01

The following message is displayed:
Copy
```
Entry created successfully.
```
Create a user entry as in the first example, however, use the keyname k1 and passphrase BMC user. Specify the following command:

ctmsetown -action add -run_as username1 -host saturn -keyname k1 -passphrase "BMC user"

The following message is displayed:
Copy
```
Entry created successfully.
```
Assume that the security details of the run_as, described in the first example, already exists. To change the password from pass01 to newpass, specify the following command:

ctmsetown -action update -run_as username1 -host saturn -password newpass

The following message is displayed:
Copy
```
Entry updated successfully.
```
To delete the user entry created in the first example, specify the following command:

ctmsetown -action delete -run_as username1 -host saturn

The following message is displayed:
Copy
```
Entry deleted successfully.
```

To list the security details of user entries, specify the following command:

ctmsetown -action list

The following message is displayed:

Copy

Run_as               Host                Password/Key Flag        Key value
-----                ----                -----------------        ---------
jupiter              saturn              Key                      Key1
jupiter              venus               Password                 Not Applicable
2 entries were found.

To create an export text file containing a list of security details of user entries, specify the following command:

ctmsetown -action export -filename /home/ctm900oe/sec.exp

The following is displayed:
Copy
```
Exporting data, please wait...
Export ended successfully.
Check report file ~<controlm_run_as>/ctm_server/proclog/export_report_53d1.txt’ for details.
```
To import the /home/ctm900oe/sec.exp text file created in the sixth example, containing a list of security user entries, and to replace the current security user information, specify the following command:

ctmsetown -action import -filename /home/ctm900oe/sec.exp -data truncate

The following is displayed:
Copy
```
Importing data, please wait...
Import ended successfully.
Check report file ~<controlm_run_as>/ctm_server/proclog/import_report_53d9.txt’ for details.
```
Example to show ctmsetown run from an Agent computer to update the password of a user.

Assume that the old password of user Agentuser1 is agntpass01. To change the password to newpass, specify the following command:

ctmsetown -action update -run_as Agentuser1 -host saturn -password newpass

The following message is displayed:
Copy
```
Entry updated successfully.
```