/ansible-role-win_controlm_agent_config

This Ansible module allows to change the Control-M Agent configuration on Windows-based systems.

Primary LanguagePowerShellApache License 2.0Apache-2.0

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.