Skip to content

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

License

Notifications You must be signed in to change notification settings

informatique-cdc/ansible-role-win_controlm_agent_config

Repository files navigation

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.