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:
|
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:
|
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:
CopyEntry 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:
CopyEntry 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:
CopyEntry 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:
CopyEntry deleted successfully.
-
To list the security details of user entries, specify the following command:
ctmsetown -action list
The following message is displayed:
CopyRun_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:
CopyExporting 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:
CopyImporting 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:
CopyEntry updated successfully.