Run as User Configuration

The following API commands enable you to configure the Run as User accounts:

config server:runasuser::add

The config server:runasuser::add command enables you to add a new user to the list of users that are available for running jobs on an Agent. Whenever you define a job, you can choose a Run as User from the list of predefined users.

Before adding a new Run as User, you might want to use the config server:runasuser::test command to test the connection to the user and verify the authentication details that you defined in your configuration file.

CLI Syntax

Copy 
ctm config server:runasuser::add <server> <agent> <user> [password] [-f <configuration file>]

The following table describes the config server:runasuser::add command parameters.

Parameter

Description

server

Defines the Control-M/Server name.

agent

Defines the Agent hostname or alias.

Admins with full config authorization can use All for all Agents.

You can instead specify the Agent in a configuration file. If you specify the Agent in both the command line and the configuration file, the command line takes precedence.

user

Defines the username.

  • If the username contains special characters, in a REST API command use URL encoding for any special characters in the username. For example, for a Windows domain account domainA\userB, specify domainA%5CuserB

  • You can instead specify the user in a configuration file. If you specify the user in both the command line and the configuration file, the command line takes precedence.

password

A valid password for the specified user.

You can instead specify the password in a configuration file. If you specify the password in both the command line and the configuration file, the command line takes precedence.

configuration file

Defines the pathname to a JSON file that contains Run as User details, especially authentication details.

The configuration file can contain the Agent and username definitions. These details are optional if you are using the CLI, and they are mandatory if you are using a REST API command.

For authentication, you can define either of the following authentication methods in the configuration file:

  • Password Authentication: A password for the user, either plain text or a predefined secret.

  • Key Authentication: A key and passphrase for an SSH connection to an Agentless Host. The passphrase can be either plain text or a predefined secret.

For examples of configuration file contents and syntax, see Contents of Configuration File.

If annotation is enabled for the Configuration Management category in the Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

Contents of Configuration File

  • The following example configuration file contains a password in plain text, and also defines the Agent and user:

    Copy 
    {
       "user": "dbauser",
       "agent": "sqa",
       "password": "pass1"
    }

  • The following example configuration file contains the name of a predefined secret from the Control-M vault instead of a password:

    Copy 
    {
       "password": "Secret:topSecretPassword"
    }

  • The following example configuration file contains key authentication details for an SSH connection. In this example, the passphrase is specified as a predefined secret from the Control-M vault:

    Copy 
    {
       "user": "user1",
       "agent": "All",
       "key": 
       {
          "keyname": "keyName",
          "passphrase": "Secret:topSecretPassphrase"
       }
    }

REST API Syntax

In the following cURL example, note that the path to the configuration file is prefixed with an @ (at) character.

Copy 
server=IN01
curl -H "x-api-key: $token"
-H "Content-Type: application/json" --data "@runasUserDefinition.json"
-X POST "$endpoint/config/server/$server/runasuser"

config server:runasuser::get

The config server:runasuser::get command enables you to get the details of a specific Run as User. You can use this command to verify that a certain user exists in the list of defined users. Each Run as User is uniquely identified by its combination of Agent and username.

CLI Syntax

Copy 
ctm config server:runasuser::get <server> <agent> <user>

The following table describes the config server:runasuser::get command parameters.

Parameter

Description

server

Defines the Control-M/Server name.

agent

Defines the Agent hostname or alias.

Admins with full config authorization can use All for all Agents.

user

Defines the username.

If the username contains special characters, in a REST API command use URL encoding for any special characters in the username. For example, for a Windows domain account domainA\userB, specify domainA%5CuserB.

REST API Syntax

cURL:

Copy 
server=IN01
agent=realAgent
user=user1
curl -H "x-api-key: $token"
$endpoint/config/server/$server/runasuser/$agent/$user

config server:runasuser::update

The config server:runasuser::update command enables you to update the authentication parameters of an existing Run as User. Each Run as User is uniquely identified by its combination of Agent and username.

Before updating the Run as User, you might want to use the config server:runasuser::test command to test the connection to the user and verify the validity of the user's authentication details.

CLI Syntax

Copy 
ctm config server:runasuser::update <server> <agent> <user> [password] [-f <configuration file>]

The following table describes the config server:runasuser::update command parameters.

Parameter

Description

server

Defines the Control-M/Server name.

agent

Defines the Agent hostname or alias.

Admins with full config authorization can use All for all Agents.

You can instead specify the Agent in a configuration file. If you specify the Agent in both the command line and the configuration file, the command line takes precedence.

user

Defines the username.

  • If the username contains special characters, in a REST API command use URL encoding for any special characters in the username. For example, for a Windows domain account domainA\userB, specify domainA%5CuserB.

  • You can instead specify the user in a configuration file. If you specify the user in both the command line and the configuration file, the command line takes precedence.

password

A new valid password for the specified user.

You can instead specify the password in a configuration file. If you specify the password in both the command line and the configuration file, the command line takes precedence.

configuration file

Defines the pathname to a JSON file that contains details that you want to update for the Run as User, especially authentication details.

The configuration file can optionally contain the Agent and username definitions.

For authentication, you can define either of the following authentication methods in the configuration file:

  • Password Authentication: A password for the user, either plain text or a predefined secret.

  • Key Authentication: A key and passphrase for an SSH connection to an Agentless Host. The passphrase can be either plain text or a predefined secret.

For examples of configuration file contents and syntax, see Contents of Configuration File under the config server:runasuser::add command.

If annotation is enabled for the Configuration Management category in the Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The REST API command specifies the Agent and user, and the configuration file contains only the authentication details (either a password or a key and passphrase). In the following cURL example, note that the path to the configuration file is prefixed with an @ character.

Copy 
server=IN01
agent=realAgent
user=user1
curl -H "x-api-key: $token"
-H "Content-Type: application/json" --data "@runasUserDefinition.json"
-X POST "$endpoint/config/server/$server/runasuser/$agent/$user"

config server:runasuser::delete

The config server:runasuser::delete command enables you to deletes a Run as User from the list of users that are available for running jobs on an Agent. Each Run as User is uniquely identified by its combination of Agent and username.

CLI Syntax

Copy 
ctm config server:runasuser::delete <server> <agent> <user>

The following table describes the config server:runasuser::delete command parameters.

Parameter

Description

server

Defines the Control-M/Server name.

agent

Defines the Agent hostname or alias.

Admins with full config authorization can use All for all Agents.

user

Defines the username.

If the username contains special characters, in a REST API command use URL encoding for any special characters in the username. For example, for a Windows domain account domainA\userB, specify domainA%5CuserB.

If annotation is enabled for the Configuration Management category in the Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

cURL:

Copy 
server=IN01
agent=realAgent
user=user1
curl -H "x-api-key: $token"
-X DELETE $endpoint/config/server/$server/runasuser/$agent/$user

config server:runasuser::test

The config server:runasuser::test command enables you to test the connection for a Run as User that you specify. You can use this command in the following ways:

  • Specify the Agent and username in the command line, but do not specify authentication credentials. This is especially useful for verifying the validity of the credentials of a defined Run as User before you use the config server:runasuser::update command to update the user's authentication parameters.

  • Specify also the password in the command line or specify authentication details in a configuration file. This is especially useful for verifying the validity and connectivity of a user before you use the config server:runasuser::add command to add the user to the list of Run as Users.

CLI Syntax

Copy 
ctm config server:runasuser::test <server> <agent> <user> [password] [-f <configuration file>]

The following table describes the config server:runasuser::test command parameters.

Parameter

Description

server

Defines the Control-M/Server name.

agent

Defines the Agent hostname or alias.

  • The All value is not supported when testing a Run as User.

    If this Run as User is associated with all Agents, you can test it against any individual Agent. In this case, the password is required.

  • You can instead specify the Agent in a configuration file. If you specify the Agent in both the command line and the configuration file, the command line takes precedence.

user

Defines the username.

  • If the username contains special characters, in a REST API command use URL encoding for any special characters in the username. For example, for a Windows domain account domainA\userB, specify domainA%5CuserB.

  • You can instead specify the user in a configuration file. If you specify the user in both the command line and the configuration file, the command line takes precedence.

password

A password to test for the specified user.

You can instead specify the password in a configuration file. If you specify the password in both the command line and the configuration file, the command line takes precedence.

configuration file

Defines the pathname to a JSON file that contains details of the Run as User.

For examples of configuration file contents and syntax, see Contents of Configuration File under the config server:runasuser::add command.

REST API Syntax

cURL:

  • Example for testing an existing user:

    Copy 
    server=IN01
    agent=realAgent
    user=user1
    curl -H "x-api-key: $token"
    -H "Content-Type: application/json" --data "{}"
    -X POST $endpoint/config/server/$server/runasuser/$agent/$user/test

    For this test, a configuration file is not necessary, because authentication details are not required.

  • Example for testing a user that has not yet been added:

    Copy 
    server=IN01
    agent=realAgent
    user=user1
    curl -H "x-api-key: $token"
    -H "Content-Type: application/json" --data "@runasUserDefinition.json"
    -X POST "$endpoint/config/server/$server/runasuser/$agent/$user/test"

    For this test, the REST API command specifies the Agent and user, and the configuration file contains only the authentication details (either a password or a key and passphrase). The path to the configuration file is prefixed with an @ (at) character.

config server:runasusers::get

The config server:runasusers::get command enables you to get details about all Run as Users that match a specified search criteria. The response matches the user level of authorization.

CLI Syntax

Copy 
ctm config server:runasusers::get <server> [-s <query string>]

The following table describes the config server:runasusers::get command parameters.

Parameter

Description

server

Defines the Control-M/Server name.

query string

A string to search for, with the following format:
"field1=criteria1&field2=criteria2"

You can include the following fields in the query string:

  • agent

  • user

agent=agent1*& user=user1*

REST API Syntax

cURL:

Copy 
server=IN01
curl -H "x-api-key: $token" "$endpoint/config/server/$server/runasusers?agent=agent1&user=user1"