ctmsec

The ctmsec utility can be invoked in interactive or batch mode.

For more information about Control-M security concepts, see Control-M SSL Configuration.

The ctmsec utility is used to:

• Add, delete, or modify specific users and groups in the Control-M Security database

• Assign authorizations to a user or group to perform actions on a Folder or Control-M entities

Security Considerations

Control‑M/Server includes security features that protect Control‑M against unauthorized usage or modification. These features enhance the standard UNIX and Windows security, and provides an additional application-level security layer. Using Control‑M security, you can specify actions that each Control‑M/EM user or Control‑M/Server user is authorized to perform. These authorizations are used to perform security checks each time one of the following actions is attempted:

• Accessing a Folder to add, delete, or modify a job definition

• Ordering, selecting and submitting a job

• Commands affecting jobs in Active Jobs database such as Hold, Confirm, or Rerun

• Maintenance of Control-M entities such as calendars or prerequisite conditions

Security verifications for the above actions are implemented according to the specifications in a database of authorizations. This database can be modified by the security officer or systems manager to meet the needs of the enterprise.

For more information, see Security Maintenance Utility (Interactive Mode)

Control‑M provides the following levels of application security for users not explicitly defined in the Control‑M Security database:

• Restricted: A user not defined in the Control-M Security database is regarded as having no authorizations and cannot perform any function requiring security authorization.

• Unrestricted: A user not defined in the Control-M Security database is regarded as having all Control-M application authorizations.

The security level is determined by the value of the Control‑M system parameter Full Security. If SSL is installed, Secure Sockets Layer encryption and compression provide security for Control‑M/Server communication with Control-M/EM and Control‑M/Agents. For more information, see Control-M SSL Configuration.

Regardless of which level is implemented, a user, for whom one or more authorizations have been assigned in the Security database, can only perform those actions. The user of each job processing definition must be defined as a user on the Agent computer, otherwise, Control‑M/Agent will not execute the job.

When working with the Control‑M/Server Security facility, wildcard characters are available for all options. Wildcard characters * and $ are translated during runtime security checking.

Valid wildcard characters:
    *  represents any number of characters (including none).
    $  represents a single character.
Wildcard character authorizations do not override full name authorizations.

Security Maintenance Utility (Interactive Mode)

The ctmsec Control‑M Security Maintenance utility defines users in the Control‑M Security database and assigns authorizations required for working with Control‑M using the Control-M Configuration Manager. ctmsec runs on the Control-M/Server computer.

Changes made by this utility are implemented only after you exit the utility.

Users can be defined as part of a group. Authorizations can be specified for a specific user, for a group, or for both. See Security Maintenance Utility (Batch Mode).

When assigning a user to a group, the following rules apply:

• If there are no authorizations defined for the user, the user inherits the authorizations for the group.

• If there are authorizations defined for a user, these authorizations take precedence.

• When defining an authorization for a user, such as Folder, use of the (D)efault setting enables the specific authorization, such as Read, defined for the group.

• If all of a user’s authorizations for a specific Control-M element, such as Folder, are defined with a (D)efault setting, the user authorizations for that element can be deleted more efficiently.

• Authorizations not specifically defined for a group, or for a user not belonging to a group, revert to the Full Security parameter setting. See ctmsys

Certain functions of the ctmsec utility can be activated directly from a command line. For more information, see Security Maintenance Utility (Batch Mode). In addition, certain functions of the ctmsec utility can be activated using the Control-M Configuration Manager. For more information, see Control-M SSL Configuration.

The security of Sub Folders and jobs within Sub Folders is determined according the security that is set for SMART folders.

User Maintenance

The User Maintenance option of the ctmsec utility is used to add, delete, or modify specific users in the Control‑M Security database.

Each Control‑M/EM user who performs actions affecting the Control‑M/Server database or jobs in the Active Jobs database must be defined in the Control‑M Security database when full security is on. In addition, all other users who invoke Control‑M Security utilities must be defined in the Security database and assigned appropriate privileges.

If the user in the commands listed below is a Control-M/Agent user, then the <user> format is <username@HOST_ID>.

Configuring Users in the Control-M Security Database Using ctmsec Utility

This procedure describes how to add, delete, or modify specific users in the Control‑M Security database.

Begin

1. 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.

2. Type the ctmsec command and then select the User Maintenance Menu option.

3. Select one or more of the following options:

   • List all existing users.

   • Add a new user by doing the following:

     1. Type Y to add the new user

     2. Add a description and a value for the group.

   • Delete an existing user by specifying the user name to delete which is deleted from the Security database.

   • Modify an existing user by doing the following:

     1. Type the name of the user.

     2. Select the information that you want to modify.

   • Copy an existing user by doing the following:

     1. In the FROM user field, type the exact name of the user to be copied.

     2. In the TO user field, type a new user name for the Control-M/EM user (maximum 30 characters, case-sensitive).

     3. Enter Y to add the new user.

Group Maintenance

Each user who has a user account on the Control-M/Server computer and who is defined in the Control‑M Security database, can be defined as part of a group. Belonging to a group is optional. All users belonging to a group inherit the authorizations defined for the group.

Select Option 2 from the Security Maintenance Main Menu to display the Group Maintenance menu.

Group Maintenance Menu
-----------------------
1)   List   Groups
2)   Add    Group
3)   Delete Group
4)   Modify Group Information
q)   Quit
Enter option:

Configuring Groups in the Control-M Security Database

This procedure describes how to view, add, delete or modify existing groups in the Control‑M Security database.

Begin

1. 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.

2. Type the ctmsec command and then select the GroupMaintenance Menu option.

3. Select one or more of the following options:

   • List existing groups

   • Add a new group by typing a group name and description.

     Group Name—maximum 32 characters—must be unique and cannot be an existing user or group name.

   • Delete an existing group by typing group name to delete.

   • Modify the description field by typing the group name and description.

   Description—maximum length 50 characters—is optional and for documentation purposes only.

Folder Authorization

This option is used to assign authorizations to a user or group to perform actions on a Folder.

Select Option 3 from the Security Maintenance Main Menu to display the Folder Authorization menu.

For more information about the types of authorization that can be granted using this option, see Folder Authorization options in Security Maintenance Utility (Batch Mode).

Configuring Folder Authorizations in Control-M Security Database

This procedure describes how to view, create, modify or delete folder authorizations in the Control‑M Security database.

Begin

1. 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.

2. Type the ctmsec command and then select the Folder Authorization option.

3. In the User/Group field, type the user or group that you want to configure.

4. Select one or more of the following options:

   • View a list of folder authorizations

   • Create or modify folder authorizations by doing the following:

     1. Type the name of the folder.

        Maximum 20 characters, case-sensitive. The folder does not have to exist at the time you specify authorizations for it.

        A folder definition menu appears.

        The Y setting enables authorization for the action, such as Read, N disables the authorization, and (D)efault uses the authorization defined for the user’s group. If the user was previously authorized for this folder, the current user authorizations are displayed; otherwise, all authorizations are set to N.

     2. Type s to save your changes.

   • Delete folder authorization by typing the folder name you want to delete.

Active Jobs Authorization Option

This option is used to assign authorizations to a user or group for actions on jobs in the Active Jobs database. The authorizations assigned are with regard to specific job owners—the user appearing in the Owner parameter for each job.

When creating or modifying a job, working in full security mode and ordering SMART folders where Y has been specified for Order, BMC recommends to specify Y also for Hold. The SMART folder remains in Hold status if the user has only ORDER/FORCE permissions. In addition, if you did not specify an asterisk (*) for the Host Group prompt, you need to create another Active Jobs database authorizations for the specified user for the SMART folder and Sub Folder entities, in which in the Host Group prompt, you must specify the local hostname of the Control-M/Server. Do this by running ctm_menu and then from the Control-M Main Menu select option 5 - Parameter Customization, then option 1 - Basic Communication and Operational Parameters and then 1 - Local IP Host Interface Name.

For more information about the types of authorization that can be granted using this option, see Active Jobs Authorization in Security Maintenance Utility (Batch Mode).

Configuring Active Jobs Authorizations

This procedure describes how to view, create, modify of delete Active Jobs authorizations.

Begin

1. 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.

2. Type the ctmsec command and then select the Active Jobs FileAuthorization option.

3. In the User/Group field, type the user or group that you want to configure.

4. Select one or more of the following options:

   • View Run As Names for whom the user has Active Jobs authorizations.

   • Create or modify Active Jobs authorizations by doing the following:

     1. Type the Run As and Host Group fields.

        The host group of the Agents where the job can be scheduled to run (maximum 30 characters, case-sensitive). A value must be specified for the Host Group prompt. To indicate all host groups, specify an asterisk (*). The Y setting enables authorization for the action (for example, Read), N disables the authorization, and (D)default uses the authorization defined for the user’s group. If the user was previous authorized for this owner and host, the user’s current authorizations are displayed; otherwise, all authorizations are set toN.

     2. Type s to save your changes.

   • Delete Active jobs authorizations by typing the Run As name and then the Host group of the Run As Name.

Entities Authorization

This option assigns authorizations to a user or group to perform actions relating to Control‑M entities.

For more information about the types of authorization that can be granted using this option, see Entities Authorization Option in Security Maintenance Utility (Batch Mode).

Configuring Entities Authorizations

This procedure describes how to maintain Entities authorizations.

Begin

1. 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.

2. Type the ctmsec command and then select the Entities Authorization option.

3. In the User/Group field, type the user or group that you want to configure.

4. Select one or more of the following options:

   • View entity categories

   • Create or modifying entity authorizations by doing the following:

     1. Type option you want to create or modify authorizations.

        The Y setting enables the specific authorization (for example, Read), N disables the authorization, and (D)efault uses the authorization defined for the group with which the user is associated. If the user was previous authorized for this category, the user’s current authorizations are displayed; otherwise, all authorizations are set toN.

     2. Type s to save your changes and return to the previous menu. Modifications are not saved until you perform this action.

   • Delete entity authorizations by typing the relevant category.

Security Maintenance Utility (Batch Mode)

Certain ctmsec Security Maintenance utility functions can be activated in batch mode. These functions include listing, updating, and deleting entries in the Control‑M Security database. These functions are described in Security Maintenance Utility (Interactive Mode) .

User Authorization

The user authorization options of the ctmsec command are used to list, update, delete, and copy users in the Control‑M Security database.

• Use the following command to list user authorizations:
  ctmsec -USER_LIST <user>

• Use the following command to update user authorizations:
  ctmsec -USER_UPDATE <user> <description> <group>

• Use the following command to delete user authorizations:
  ctmsec -USER_DELETE <user>

• Use the following command to copy user authorizations from one user to another:
  ctmsec -USER_COPY <from_user> <to_user>

  If the user in the commands listed above is a Control-M/Agent user, then the <user> format is <username@host_id>.

Group Authorization

Group authorization options of the ctmsec command are used to list, modify, and delete groups in the Control‑M Security database.

• Use the following command to list group authorizations:
  ctmsec -GROUP_LIST <group>

• Use the following command to update group authorizations:
  ctmsec -GROUP_UPDATE <group> <description>

• Use the following command to delete group authorizations:
  ctmsec -GROUP_DELETE <group>

Folder Authorization Option

The Folder authorization options of the ctmsec command are used to assign authorizations to users and groups to perform actions on Folders.

• Use the following command to list Folder authorizations:
  ctmsec -SCHED_LIST {<user>|<group>}

• Use the following command to update Folder authorizations:
  ctmsec -SCHED_UPDATE {<user>|<group>} <folder> [-DELETE {Y|N|D}] [ -READ {Y|N|D}]
  

  [ -ORDER {Y|N|D}] [ -UPDATE {Y|N|D}]

• Use the following command to delete Folder authorizations:
  ctmsec -SCHED_DELETE {<user>|<group>} <folder>

  If the user in the commands listed above is a Control-M/Agent user, then the <user> format is <username@host_id>.

Active Jobs Database Authorization

The Active Jobs database authorization options of the ctmsec command are used to assign authorizations to users and groups to perform actions on jobs in the Active Jobs database.

• Use the following command to list Active Jobs database authorizations:
  ctmsec -ACT_LIST {<user>|<group>}

• Use the following command to update Active Jobs database authorizations:

  ctmsec -ACT_UPDATE {<user>|<group>} <owner> <host>

  [-HOLD {Y|N|D}]

  [-FORCE {Y|N|D}]

  [-ORDER {Y|N|D}]

  [-CONFIRM {Y|N|D}]

  [-DELETE {Y|N|D}]

  [-WHY {Y|N|D}]

  [-RERUN {Y|N|D}]

  [-OUTPUT {Y|N|D}]

  [-LOG {Y|N|D}]

  [-STATISTICS {Y|N|D}]

  [-ZOOM_AND_SAVE {Y|N|D}]

  [-KILL_JOB {Y|N|D}]

• Use the following command to delete Active Jobs database authorizations:
  ctmsec -ACT_DELETE {<user>|<group>} <owner> <host>

  If the user in the commands listed above is a Control-M/Agent user, then the <user> format is <username@host_id>.

Entities Authorization Options

The entity authorization options of the ctmsec command are used to assign authorizations to users and groups to perform actions relating to Control‑M entities.

• Use the following command to list entity authorizations:
  ctmsec -ENTITY_LIST {<user>|<group>}

• Use the following command to update entity authorizations:
  ctmsec -ENTITY_UPDATE {<user>|<group>}
  

  {LOG|QR|Control|CALENDAR|CONDITION}
  

  [-ADD {Y|N|D}][-DELETE {Y|N|D}][-CHANGE {Y|N|D}]

• Use the following command to delete entity authorizations:
  ctmsec -ENTITY_DELETE {<user>|<group>}
  

  {LOG|QR|Control|CALENDAR|CONDITION}

  If the user in the commands listed above is a Control-M/Agent user, then the <user> format is <username@host_id>.

Exporting Security Definition Folders

The EXPORT option of the ctmsec command is used to export Control‑M Security Definition folders. The file that is generated by the ctmsec command is an execufolder file containing API functions that will redefine all the security entries when the script is run. The generated file can be modified and imported to any Control‑M installation.

The file created by the EXPORT option of the ctmsec utility can be modified before security definitions are imported back to the same or different Control-M/Server installation. This is different from the file that is created using the Backup Security Definition Folders option of the Security Authorization Menu, which cannot be modified.

Begin

• Use the following command to export Control‑M Security Definition folders:

  ctmsec -EXPORT <fileName>

  <fileName>: the full path name of the file to be exported.

  ctmsec -EXPORT /home/Control-M/securedata

Importing Security Definition Folders

The file created using the ‑EXPORT option of the ctmsec utility contains multiple ctmsec commands that describe the various security definitions in your Control‑M installation. If necessary, these ctmsec commands can be modified before the security definitions are imported back to the same or a different Control‑M installation.

Importing updates the security definitions in your Control‑M installation. Use the restore security procedure to replace security definitions.

Begin

• Execute the script file that was created using the ctmsec utility.

  /home/Control-M/securedata

  This procedure will work only with a file that was created using the ‑EXPORT option of the ctmsec utility. If your input is a file created using the Backup Security Definition Folders option of the Security Authorization menu, then you must import using the Restore option in that same menu.