The Agent Configuration File lists alias names for agents and provides the name and location of agent configuration files. It can also defines startup arguments and output files for agents that are managed by the Controller Daemon. The sqdagents.cfg file begins with global parameters followed by sections for each agent controlled by the daemon.
Global section - not identified by a section header and must be specified first.
acl=<path_to/acl.cfg>
authorized_keys=<path_to/nacl_auth_keys>
identity=<path_to/id_nacl>
message_level=<0-8>
message_file=../logs/daemon.log
service=<port_num>
Keyword | Description |
---|---|
acl=<path_to/acl.cfg> |
Location, fully qualified path to the working directory) and name of the acl configuration file to be used by the Controller Daemon. While the actual name of this file is user defined, we strongly recommend using the file name acl.cfg. |
authorized_keys=<path_to/nacl_auth_keys> (Non-z/OS only) |
Location of the authorized_keys file to be used by the Controller Daemon. On z/OS platforms, specified at runtime by DD statement. |
identity=<path_to/id_nacl> - (Non-z/OS only) |
Local file system path and file name or AKV url for the NaCl private key to be used by the Controller Daemon. On z/OS platforms both Public and Private Key files are specified at runtime by DD statements. |
message_level=<0-8> |
Level of verbosity for the Controller Daemon messages. This is a numeric value from 0 to 8. Default is 4. |
message_file=../logs/daemon.log |
Location of the file that will accumulate the Controller Daemon messages. If no file is specified, either in the config file or from the command line, then messages are send to the syslog. |
service=<port_num> |
Number of the port or service to be used by the Controller Daemon to listen for incoming service requests. Service can be defined using the SQDPARM DD on z/OS, on the command line starting sqdaemon, in the config file described in this section or, on some platforms, as the environment variableSQDAEmon_SERVICE, in that order of priority. Absent any specification, the default is 2626. If for any reason a second Controller Daemon is run on the same platform they must each have a unique port specified. |
Agent sections - not identified by a section header, each agent is identified with its "alias name" between square brackets, heading a block of properties for that agent.
[<capture_agent_alias>] | [<publisher_agent_alias>]
[<engine_agent_alias> ] | [<program_alias> ] | [<process_alias>]
type=capture | publisher |[ engine | program ]
cab=<full or relative path>/<capture/publisher_name.cab>
program=<name>
args=<parameter list>
working_directory=<full path to working directory>
stdout_file=<full or relative path>/<agent_alias>.<ext>
stderr_file=<full or relative path>/<agent_alias>.<ext>
report=<synonym of stderr_file>
comment=<user comment>
auto_start=[ Y | N ]
Keyword | Description |
---|---|
[<capture_agent_alias>] | [<publisher_agent_alias>] |
Must be unique in the configuration file of the daemon on the same machine as the Capture / Publisher process. This alias name will be referenced in the Engine connect string. Must be associated with the cab=<*.cab> file name specified in the sqdconf create command for the capture or publisher Agent setup in the previous section. |
[<engine_agent_alias>] |
Only present in the configuration file of the daemon on the same machine where the Engine process executes. Also known as the Engine name, the <engine_agent_alias> provided here does not need to match the one specified as the subscription name in the Capture/Publisher .cab file, however there is no reason to make them different. Will also be used by sqdmon agent management and display commands. |
[<program_alias> ] | [<process_alias>] | Only present in the configuration file of the daemon on the same machine where the program or process associated with the alias will execute. Any string of characters may be used. |
type=Capture | Publisher | Engine | Program |
Type of the agent. This can be Engine, Program, capture or publisher. It is not necessary to specify the type for Engines, programs, scripts or batch files. |
program=<name> |
The name of the program (or nix shell script / or windows batch file) to invoke in order to start an agent. This can be a full path or a simple program name. In the latter case, the program must be accessible via the PATH of the sqdaemon - context. The value must be "SQDATA" for Engines but may also be any other executable program, shell script (nix) or batch file (Windows). |
args=<parameter list> |
Parameters passed on the command line to the the program=<name> associated with the agent on startup. In the case of an Connect CDC SQData Engine, the first must be the "parsed" Engine script name ie <engine.prc>. This is valid for program= entries only. |
working_directory=<full path to working directory> |
Specify the working directory used to execute the agent. |
cab=<full or relative path/<capture/publisher_alias.cab> |
Location and name of the configuration (.cab) file for capture and publisher agent entries. |
stdout_file=<full or relative path>/<agent_alias>.<ext> - NON-zOS SQDAEMON's ONLY | Location and name of the output file name used by the agent_alias for stdout. The file extension is optional but .rpt is recommended. If not specified, the default value is agent_name.stdout. Using the same file name for stdout_file and stderr_file is recommended and will result in a concatenation of the two results, for example <engine_name.rpt>. |
stderr_file=<full or relative path>/<agent_alias>.<ext> - NON-zOS SQDAEMON's ONLY |
Location and name of the output file name used by the agent_alias for stderr. The file extension is optional but .rpt is recommended. If not specified, the default value is agent_name.stderr. Using the same file name for stdout and stderr is recommended and will result in a concatenation of the two results, for example <engine_name.rpt> |
report=<synonym of stderr_file> |
If both are specified, report takes precedence. |
comment=<user comment> |
User specified comment associated with the agent, used for display purposes. |
auto_start=[ Y | N ] |
A boolean value (yes/no/1/0), indicating if the associated agent should be automatically started when sqdaemon is started. This also has an impact in the return code reported by sqdmon when an agent stops with an error. If an agent is marked as auto_start and it stops unexpectedly, this will be reported as an Error in the sqdaemon log, otherwise it is reported as a Warning. This is valid for engine entries only. |
Notes:
- Directories and paths specified must exist before being referenced. Relative names may be included and are relative to the working directory of the sqdaemon "-d" parameter or as specified in the file itself.
- While message_file is not a required parameter we generally recommend its use or all messages, including authentication and connection errors, will go to the system log. On z/OS however the system log may be preferable since other management tools used to monitor the system, use the log as their source of information.
- All references to .cab files names must be fully qualified.
- Azure Key Vault (AKV) based secrets in Connect CDC SQData are supported only on Linux platforms.
- AKV requires an Azure Active Directory (AAD) token to be presented to retrieve secrets. SQData retrieves AAD tokens from Azure differently when running on on-prem Linux machines and when running on Azure Linux VM.
- When running on-prem, to retrieve AAD, tenant_id, client_id and client_secret have to be specified in the sqdata_cloud.conf file located in the working directory.
- When running on Azure VM, AAD will retrieved from managed identity. Two types of managed identities are supported:
- If client_id is specified in sqdata_cloud.conf file, then AAD token is retrieved from user managed identity.
- If tenant_id, client_id and client_secret are not specified, then AAD token is retrieved from system managed identity.
A sample sqdagent.cfg file for the Capture Controller Daemon running on z/OS created using JCL similar sample member CRDAEMON included in the distribution. The JCL should be edited to conform to the operating environment and the zFS directories previously allocated. Once created, the sqdagent.cfg file can be directly edited or the JCL can be edited and the files recreated. Changes are not known to the daemon until the configuration file is reloaded (see SQDMON Utility) or the daemon process is stopped and started.
//*--------------------------------------------------------------------
//* Create and populate the sqdagents.cfg file
//*--------------------------------------------------------------------
//CRAGENTS EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN DD DUMMY
//SYSUT2 DD PATH='//home/sqdata/daemon/cfg/sqdagents.cfg',
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=SIRWXU,
// PATHDISP=(KEEP,DELETE),
// FILEDATA=TEXT
//*
//SYSUT1 DD *
acl=acl.cfg
message_file=../logs/acl.log
[DB2CDC]
type=capture
cab=/home/sqdata/db2cdc/db2cdc.cab
/*