win_controlm_agent_config - Manipulate the configuration of a Control-M Agent on a Windows host

Synopsis

• This Ansible module allows to change the Control-M Agent configuration on Windows-based systems.
• Control-M Agent configurations use both CTMWINCFG or CTMAGCFG command for setting configuration.
• This module provides an implementation for working with Agent configuration in a deterministic way. Commands are not used. This module makes changes in registry locations.

Parameters

Parameter	Choices/Defaults	Comments
agent_to_server_port integer	Default: 7005	Defines the port number in the Control-M Agent computer where data is received from the Control-M Server computer. The value assigned to this parameter must correspond to the value assigned to the Server-to-Agent Port Number field in the configuration file on the corresponding Control-M Agent computer.
server_to_agent_port integer	Default: 7006	Defines the port number between 1024 and 65535 that receives data from the Control-M Agent computer. This value must match the Agent-to-Server Port Number in Control-M Server. The value is the COMTIMOUT communication job-tracking timeout in seconds.
primary_controlm_server_host string		Defines the hostname of the computer where the current Control-M Server submits jobs to the Control-M Agent.
authorized_controlm_server_hosts string		Defines a list of backup servers which can replace the primary server if it fails. The Control-M Agent only accept requests from servers on this list. You cannot submit jobs to the same Control-M Agent if there is more than one active Control-M Server. Another Control-M Agent instance must be installed with unique ports to support this configuration or job status updates corrupt.
diagnostic_level integer	Default: 0	Defines the debug level. Range 0-4 where 0 indicates no diagnostic activity, and 4 indicates the highest level of diagnostic functionality.
communication_trace boolean	Choices: no ← yes	Flag indicating whether communication packets that Control-M Agent sends to and receives from Control-M Server are written to a file. If set to yes, separate files are created for each session (job, ping, and so forth). This parameter can only be changed after completing the installation.
days_to_retain_log_files integer	Default: 1	Number of days to retain agent proclog files. After this period, agent proclog files are deleted by the New Day procedure. Range 1-99.
daily_log_file_enabled boolean	Choices: no yes ←	Indicates if the ctmag_<year><month><day>.log file is generated Yes or not No.
tracker_event_port integer	Default: 7035	Number of the port for sending messages to the Tracker process when jobs end.
logical_agent_name string		Logical name of the agent. The value specified should match the name the agent is defined by in Control-M Server. Where multiple agent names are defined in Control-M Server, and all use the same server-to-agent port, server messages are sent to that agent. The logical name is used when the agent initiates the communication to Control-M Server with the output from agent utilities and in messages sent by the agent to the server. The default value is the Agent host name.
persistent_connection boolean	Choices: no ← yes	Indicates the persistent connection setting. Set the persistent_connection parameter to connect to a specific agent with either a persistent or transient connection. When persistent_connection is set to Yes, the NS process creates a persistent connection with the agent and manages the session with this agent. If the connection is broken with an agent or NS is unable to connect with an agent, the agent is marked as Unavailable. When the connection with the agent is resumed, the NS recreates a persistent connection with the agent and marks the agent as Available.
allow_comm_init boolean	Choices: no yes ←	Determines if the agent can open a connection to the server when working in persistent connection mode. When allow_comm_init is set to Y, the Control-M Agent to initiate the communication with the Control-M Server.
foreign_language_support string	Choices: LATIN-1 ← CJK	Indicates whether the system is configured for CJK languages or Latin1 languages.
ssl boolean	Choices: no ← yes	Determines whether SSL is used to encrypt the communication between Control-M Server and the Control-M Agent.
server_agent_protocol_version integer	Default: 12	Server-Agent communication protocol version. Valid values range to 12 or lower.
autoedit_inline boolean	Choices: no yes ←	Flag that indicates whether all variables will be set as environment variables in the script.
listen_to_network_interface string	Default: *ANY	The network interface the agent is listening on. It can be set to a specific hostname or IP address so that the agent port is not opened in the other interfaces. If this parameter is set to *ANY, the agent is listening on all available interfaces.
ctms_address_mode string	Choices: IP	If this parameter is set to IP, the IP address instead of the host name is saved in ctms_hostmane. Use this parameter when Control-M runs on a computer with more than one network card.
timeout_for_agent_utilities integer	Default: 600	Maximum time (in seconds) the agent waits after sending a request to Control-M Server. This timeout interval should be longer than the TCP/IP Timeout.
tcpip_timeout integer	Default: 60	The communication job-tracking timeout in seconds. When the value of ‘TCP/IP timeout’ is changed, using the configuration utility or CCM, the timeout part of the server_to_agent_port and agent_to_server_port parameters are changed. Range 0-999999.
tracker_polling_interval integer	Default: 60	Job Tracking Timeout. Tracker event timeout in seconds. Range 1-86400.
limit_log_file_size integer	Default: 10	Maximum size (MB) of diagnostic log files for a process or a thread. When the defined size is reached, the log file is closed and a new one is created. Restart the agent for the parameter to take effect. Range 1-1000.
limit_log_version integer	Default: 10	Number of generations of diagnostic log information to keep for a process or a thread. When the number is reached, the older log file is deleted. Range 0-99.
measure_usage_day integer	Default: 7	Determines the number of days to retain the files in the dailylog directory. These files contain the information about jobs that is used to calculate the metrics for the usage measurement report.
logon_as_user boolean	Choices: no ← yes	Flag that specifies which user account is used for the services to log on to. If this parameter is set to Yes, jobs are submitted with the permissions and environment variables of the specified user. If this parameter is set to No, jobs are submitted with the permissions and environment variables of the local system account.
logon_domain string	Default: ""	The domain is determined by the value of this parameter if logon_domain is not specified in <username> in the Run_As parameter of the job definition. If the domain is not specified in the Run_As parameter or this parameter, the user profile is searched in the trusted domains. BMC recommends that you do not specify a value for Logon Domain.
job_children_inside_job_object boolean	Choices: no yes ←	Flag that specifies if procedures invoked by a job can be run outside the Job Object. If so, this prevents a situation in which the original job remains in executing mode until the invoked procedure completes. If this parameter is set to Yes, all procedures invoked by the job are run outside the job object. If this parameter is set to No, all procedures invoked by the job are run inside the job object.
add_job_statistics_to_sysout boolean	Choices: no yes ←	Flag that indicates how to manage job object processing statistics. If this parameter is set to Yes, statistics are added to the end of the OUTPUT file. If this parameter is set to No, statistics are not added to the OUTPUT file.
job_output_name string	Choices: MEMNAME ← JOBNAME	Determines the prefix for the OUTPUT file name. If this parameter is set to MEMNAME, the OUTPUT file prefix is the MEMNAME of the job. If this parameter is set to JOBNAME, the OUTPUT file prefix is the JOBNAME of the job.
wrap_parameters_with_double_quotes integer	Default: 4	Indication of how parameter values (%%PARMn....%%PARMx) are managed by Control-M Agent for Microsoft Windows. If this parameter is set to 1, this parameter is no longer relevant. If this parameter is set to 2, parameter values are always passed to the operating system without quotes. If quotes were specified in the job definition, they are removed before the parameter is passed onward by the agent. This option is compatible with the way that these parameters were managed in version 6.0.0x, or 6.1.01 with Fix Pack 1, 2, 3, or 4 installed. In this case, if a parameter value contains a blank, the operating system may consider each string as a separate parameter. If this parameter is set to 3, this parameter is no longer relevant. If this parameter is set to 4, parameters are passed to the operating system in exactly the same way that they were specified in the job definition. No quotes are added or removed in this case. This option is compatible with the way that parameters were managed by version 2.24.0x.
run_user_logon_script boolean	Choices: no ← yes	Indicates wether a user-defined logon script should be run by the Control-M Agent before running the standard user logon script. If this parameter is set to Yes, the user-defined logon script is run, if it exists. If this parameter is set to No, the user-defined logon script is not run.
cjk_encoding string	Choices: UTF-8 ← JAPANESE EUC JAPANESE SHIFT-JIS KOREAN EUC SIMPLIFIED CHINESE GBK SIMPLIFIED CHINESE GB TRADITIONAL CHINESE EUC TRADITIONAL CHINESE BIG5	Determines the CJK encoding used by Control-M Agent to run jobs.
default_printer string	Default: ""	Default printer for job OUTPUT files.
echo_job_commands_into_sysout boolean	Choices: no yes ←	Specifies whether to print commands in the OUTPUT of a job. If this parameter is set to Yes, implements ECHO_ON, which prints commands in the job OUTPUT. If this parameter is set to No, implements ECHO_OFF, which does not print commands in the job OUTPUT.
smtp_server_relay_name string		The name of the SMTP server.
smtp_port integer	Default: 25	The port number on which the SMTP server communicates. Range 0-65535.
smtp_sender_mail string	Default: control@m	The e-mail address of the sender. Text up to 99 characters.
smtp_sender_friendly_name string		The name or alias that appears on the e-mail sent.
smtp_reply_to_mail string		The e-mail address to which to send replies. If this field is left empty, the sender e-mail address is used.

Examples

---
- name: test the win_controlm_agent_config module
  hosts: all
  gather_facts: false

  roles:
    - win_controlm_agent_config

  tasks:
    - name: Change port numbers
      win_controlm_agent_config:
        agent_to_server_port: 8000
        server_to_agent_port: 8001
        tracker_event_port: 8002

    - name: Change Control-M Server hosts
      win_controlm_agent_config:
        primary_controlm_server_host: "server1"
        authorized_controlm_server_hosts: "server1|server2|server3.cloud"

    - name: Change job children inside job object
      win_controlm_agent_config:
        job_children_inside_job_object: no

    - name: Change the job ouput name
      win_controlm_agent_config:
        job_output_name: JOBNAME

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Returned	Description
config dictionary	On success	The retrieved configuration.
agent_to_server_port         integer	success	The port number in the Control-M Agent computer where data is received from the Control-M Server computer. Sample: 7006
allow_comm_init         boolean	success	Indicates whether the agent can open a connection to the server when working in persistent connection mode.
authorized_controlm_server_hosts         string	success	A list of backup servers which can replace the primary server if it fails.
autoedit_inline         boolean	success	Indicates whether all variables will be set as environment variables in the script.
cjk_encoding         string	success	The CJK encoding used by Control-M Agent to run jobs. Sample: UTF-8
communication_trace         boolean	success	Indicates whether communication packets that Control-M Agent sends to and receives from Control-M Server are written to a file.
ctms_address_mode         string	success	Indicates if the IP address is used instead of the host name.
daily_log_file_enabled         boolean	success	Indicates if the ctmag_<year><month><day>.log file is generated.
days_to_retain_log_files         integer	success	Number of days to retain agent proclog files. Sample: 1
default_printer         string	success	The default printer for job OUTPUT files.
diagnostic_level         integer	success	The debug level. Sample: 0
echo_job_commands_into_sysout         boolean	success	Indicates whether to print commands in the OUTPUT of a job.
foreign_language_support         string	success	Indicates whether the system is configured for CJK languages or Latin1 languages. Sample: LATIN-1
job_children_inside_job_object         boolean	success	Indicates whether procedures invoked by a job can be run outside the Job Object.
limit_log_file_size         integer	success	The maximum size (MB) of diagnostic log files for a process or a thread. Sample: 10
limit_log_version         integer	success	The number of generations of diagnostic log information to keep for a process or a thread. Sample: 10
listen_to_network_interface         string	success	The network interface the agent is listening on. Sample: *ANY
logical_agent_name         string	success	The logical name of the agent.
logon_as_user         boolean	success	Indicates whether the user account is used for the services to log on to.
logon_domain         string	success	The logon domain of the user account.
measure_usage_day         integer	success	The number of days to retain the files in the dailylog directory. Sample: 7
persistent_connection         boolean	success	Indicates whether NS process creates a persistent connection with the agent and manages the session with this agent.
primary_controlm_server_host         string	success	The hostname of the computer where the current Control-M Server submits jobs to the Control-M Agent.
server_agent_protocol_version         integer	success	The server-Agent communication protocol version. Sample: 12
run_user_logon_script         boolean	success	Indicates wether a user-defined logon script should be run by the Control-M Agent before running the standard user logon script.
server_to_agent_port         integer	success	The port number that receives data from the Control-M Agent computer. Sample: 7005
smtp_port         integer	success	The port number on which the SMTP server communicates. Sample: 25
smtp_reply_to_mail         string	success	The e-mail address to which to send replies.
smtp_sender_friendly_name         string	success	The name or alias that appears on the e-mail sent.
smtp_sender_mail         string	success	The e-mail address of the sender. Sample: control@m
smtp_server_relay_name         string	success	The name of the SMTP server.
ssl         boolean	success	ndicates whether SSL is used to encrypt the communication between Control-M Server and the Control-M Agent.
job_output_name         string	success	The prefix for the OUTPUT file name. Sample: JOBNAME
tcpip_timeout         integer	success	The communication job-tracking timeout in seconds. Sample: 60
timeout_for_agent_utilities         integer	success	The maximum time (in seconds) the agent waits after sending a request to Control-M Server. Sample: 600
tracker_event_port         integer	success	The number of the port for sending messages to the Tracker process when jobs end. Sample: 7035
tracker_polling_interval         integer	success	The tracker event timeout in seconds. Sample: 60
wrap_parameters_with_double_quotes         integer	success	Indicates how parameter values (%%PARMn....%%PARMx) are managed by Control-M Agent for Microsoft Windows. Sample: 4
default_agent_name         string	success	The agent name. Sample: Default
cm_name         string	success	The Control/M application version. Sample: WIN
cm_type         string	success	The Control/M plateforme type. Sample: WIN2K
agent_version         string	success	The agent version. Sample: 9.0.19.200
fd_number         string	success	The unique identifier of the agent. Sample: DRKAI.9.0.20.000
fix_number         string	success	The unique identifier of the fix pack. Sample: DRKAI.9.0.20.000
agent_directory         string	success	The installation folder of the agent. Sample: C:\Program Files\Control-M Agent\Default\

Authors

• Stéphane Bilqué (@sbilque) Informatique CDC

License

This project is licensed under the Apache 2.0 License.

See LICENSE to see the full text.