Agent Unix

Structure of the INI File ucxjxxx.ori.ini

Parameter Name Description
[ GLOBAL ]
name =

Name of the agent (or proxy agent)

The agent name is limited to 32 of the following characters: A-Z, 0-9, _, ., $, @, - and #.

Hyphens ("-") are only allowed in agent names. They must not be used in the names of any other objects.

The host name is used instead if this parameter remains undefined. Lowercase letters are converted to uppercase letters.

Default: UNIX01

system =

AE system name

The name can consist of a maximum of 8 characters. Allowed are the upper-case letters A to Z, numbers and "_".

System names must not contain the character "_" if you use a z/OS agent in combination with the SMF technique. By default, the job Includes convert "_" to "#". Should you intend to use "_" despite of this fact, you can bypass this situation by specifying the system name in the Event Monitor with "#".

Default: AUTOMIC

language =

The Language(s) in which the log messages are displayed.Always a pair of languages separated by comma enclosed in brackets.

if a message text is not available in the primary language the secondary language will be taken.

Values

  • E: english
  • D: german
  • F: french

Default: (E,D)

logging =

Full file name pattern for log file names

$$ is replaced by the purpose of a Process (CP or WP or JWP or DBSERVICE). No replacements in other components

* is replaced by the 3 digit number of a Worker Process.

## is replaced by the log file sequence number after the existing log files' corresponding numbers have been raised by one during startup of the component.

z/OS components only:

If you comment this parameter, this log file is stored in JES. Also refer to the parameter logpurgeclass= which is described below.

The following parameters can be added if the log is written to a dataset (after the dataset name and separated by semicolons):

"recfm" = (all 27 z/OS plus * and A record formats are valid)

"lrecl" = (0, each positive number up to 32760 and X for each reclen)

"blksize" = (0, each positive number up to 32760)

"space" = ([CYL,TRK],(prim,sec,directory))

AE and Java components only:

Logging to standard output can be enabled by setting the value to CON:

For relative path indications the system uses the installation directory when creating files.

For BS2000/OSD Operation System the name may be specified with or without User ID. If without User ID the log file is written to the user ID under which the component has been started

Default: ../temp/ucxjxxx_l##.txt

logCount =

number of log files being kept on disk

Default: 10

helplib =

name of the message text library

may have different names dependent on platform rules.

Default: ucx.msl

killSignal =

The signal that is sent to the job if it is canceled through the UserInterface.

Values

  • SIGTERM: The job is terminated (15).
  • SIGABRT: The job is canceled (6)
  • SIGKILL: The job ends immediately (9).

Default: SIGKILL

login_Check =

Password check.

Note that the agent must have root rights as otherwise, login_check=yes does not work. Use login_check=no and ANONYMOUS_JOB=yes in this case. See also UC_HOSTCHAR_DEFAULT.

Values

  • yes: login credentials are checked
  • no: login credentials are not checked

Default: no

open_File_Max =

Sets the users 'open file descriptor' limit

A value of 0 forces the agent to set the users soft limit to the existing users hard limit. A value not equal to 0 forces the agent to set the soft limit and the hard limit to that value. If the value exceeds the users existing hard limit, the agent even sets that value, if it is operated with root privileges. If the value exceeds the users existing hard limit and the agent is not operated with root privileges, the agent cannot exceed the hard limit and sets the users soft limit to the users hard limit.

Default: 32768

readUserAlways =

when to read users from section [USERID].

You allow or reject User IDs by using the parameter userid_type= in the [USERID] section. You can use the parameter ReadUserAlways= in order to specify whether this section should always be read before a job starts or only once when the agent starts. Reading this section only once improves the performance of your system and is therefore the default value.

Values

  • yes: The agent always reads the [USERID] section before a job starts.
  • no: The agent reads this section only once when the agent starts.

Default: no

reportMode =

A mask in three octal digits that you can use to assign additional rights to the job report file.

The default value is the minimum value. The value 6 is used even if you specify an owner authorization level below this value.

Default: 600

uc_User_Type =

The option that can be used to allow or reject particular AE users.

Values

  • INCL: Access must be granted to every single user in the [UC_USER] section.
  • EXCL: No access is granted to the AE users who are specified in the [UC_USER] section. All other AE users can start jobs

Default: EXCL

userid_Type =

This is an additional parameter that allows to allow or reject particular users.

Values

  • INCL: Access must be granted for every single user specified in (USERID).
  • EXCL: Access is denied to the users that are specified in (USERID). All other users can start jobs.

Default: EXCL

vanishedRetry =

If the agent runs jobs in START_TYPE=batch mode the job's process id cannot be retrieved from the system at job start. Therefore, in batch mode the $? in the start command outputs the job's pid to the agent. However, in seldom cases depending on OS' welcome message settings the pid cannot be retrieved reliably this way and the agent has to wait until it is reported by the start messenger. This parameter can be used to specify how often the agent retries to check for the status within the job check interval before it reports the status "ENDED_VANISHED".

Values

  • 0..9999: number of retries

Default: 1

fileProcessingMaxDepth =

The maximum level of sub-directories for FILE Events.

You use this setting in order to determine the extent to which the directory structure is included in your search for FILE Event files. The search directory serves as the basis for the maximum sub-directory level.

By limiting the directory level, you can improve the performance of FILE Events especially when their folder structure is deeply nested and includes numerous files.

This parameter is relevant for FILE Events and the script element GET_FILESYSTEM

Values

  • 0: There is no limitation.
  • 1: The files are only searched in the search directory. Sub-directories are not included in this search.
  • 2: With this setting being used, the search for files includes the search directory and one directory level below.
  • 3: The search includes the directory plus two sub-directory levels.
  • 4...n: The search includes the directory plus n-1 levels

Default: 0

fileProcessingTimeout =

The time limit in second for the file search.

The file search aborts when the specified time limit is reached. No time limit applies when you either define the setting "0" or "-1".

This parameter is relevant for FILE Events and the script element GET_FILESYSTEM.

Default: 0

ft_Owner =

The owner of file transfer files.

This parameter does not affect file rights or the group.

The new file transfer protocol (source and target agent are of version 9 or later) ignores this parameter. In this case, the owner is always the user who is defined in the Login object.

Values

  • user: The user who is defined in the Login object is the file owner (User ID) of the transferred file(s). The owner of existing files that might be overwritten is kept.
  • directory: The transferred file(s) obtein the owner of the target folder. The same rule applies for existing files that are overwritten.

Default: user

ft_Temp_File =

Creates temporary files in file transfers.

The OSS file system requires the parameter file_temp_file_oss to be used

on z/OS the temp file name contains the dataset name of the file to be transferred.

on z/OS The file immediately obtains its final name if the temporary file name would exceed maximum of 44 characters.

Values

  • yes: The file obtains a temporary name that is composed of the letter "T" and an alphabetic string that stems from the RunID. The new file transfer protocol additionally appends a file ID in order to obtain a unique file name because basically, only a RunID is provided.The file is renamed after it has successfully been transferred.
  • no: The agent assigns the final file name when the file transfer starts.

Default: yes

jobFileMode =

A mask in three octal digits that you can use to assign additional rights to the job file.

The default value is the minimum value. The value 7 is used even if you specify an owner authorization level below this value.

Default: 700

ServiceProgramStartCommand =

Command which is used by the Unix Agent to start the external file event service.

If required this command can be adopted to make use of another login tool than su. For instance sudo.

It is recommended to keep the default value. However if the default value has to be modified it is suggested to test the command in the shell before it is used in the Agent.

It is not recommended to install the service application ucxj???s with the SetUID-Bit. Otherwise all file operations of the service will be executed as the effective UserID of the file owner.

Default: su %USER% -c '%IOSCOMMAND%'

listenerUID =

Listener process UserID. This parameter is only effective if the component has been started as elevated user, e.g. root.

Default: 65534

listenerGID =

Listener process GroupID. This parameter is only effective if the component has been started as elevated user, e.g. root.

Default: 65534

allow_nologin_shell =

Inidcate whether system accounts (users with nologin/true/false shell) can execute jobs.

Default: N

[ TRACE ]
file =

The path and the file name of the trace file.

Any file name for a text file with several place holders for current system information:

$$ is replaced by server process type (WP or CP) in the context of a server process.

* is replaced by the three-digit process number in the context of a server process.

## is replaced by 00 after the available trace files' corresponding numbers have been raised by one during startup of a trace.

xxx is replaced by the three-digit abbreviation of the respective unix version (unix agent only).

z/OS components only:

The following parameters can be added (after the dataset name and separated by semicolons) if the log is written to a dataset:

"recfm" = (all 27 record formats of z/OS plus * and A are valid)

"lrecl" = (0, each positive number up to 32760 and X for each reclen)

"blksize" = (0, each positive number up to 32760)

"space" = ([CYL,TRK],(prim,sec,directory))

AE and Java components only:

Tracing to standard output can be enabled by setting the value to CON:

Currently the External Monitoring Interface (EMI) does not produce any trace regardless of the settings here.

For BS2000/OSD the name might be specified with or without user ID. If without the trace file is written to the user ID under which the component has been started.

Default: ../temp/ucxjxxx_t##.txt

trccount =

Number of stored trace files

Default: 10

tcp/ip =

traceflag

Default: 0

event =

traceflag

Default: 0

ex_init =

traceflag

Default: 0

ft_debug =

traceflag

Default: 0

job_debug =

traceflag

Default: 0

mail =

traceflag

Default: 0

memory =

traceflag

Default: 0

signal =

traceflag

Default: 0

[ TCP/IP ]
connection =

Connection Parameter: Address of the endpoint used to connect to the AE system.

Allowed formats:

DNS Name:Port number

TCP/IP Address:Port number

Default: jcphost:8443

bindAddr =

IP address the component uses to connect.

Use this parameter if the connection should be established via a particular IP address (for example, the computer has more than one network interface card).

Alternately, you can also specify the IP address or host name in PORT= (Format: PORT=IP address:port or DNS name:port). Specifications made in BINDADDR= are then ignored.

In a distributed server environment, this value must be adapted with a valid IP address that is available to that specific host.

Default:

bindLocal =

Consideration of local host 127.0.0.1 (IPv4) or ::1 (IPv6).

Use this parameter together with BINDADDR=.

Values

  • 0: No listen socket is created.
  • 1: An additional listen socket is created on the local host.

Default: 0

chiffre =

Encryption for transfer.

Values

  • 0: Non-encrypted transfer.
  • 1: Transfers are encrypted.

Default: 1

connect =

The time interval in seconds for the reestablishment of connections after a loss of connection.

For the Automation Engine: reconnect between Server Processes

For Agents: reconnect to the Engine. Reconnecting starts after an initial successful network connection to the AE system. The agent stops if it cannot reach the AE system on the first start.

For the zOS Event Monitor: reconnect to the Agent

For the Proxy: reconnect to Automation Engine or Server Proxy

For Agents: This parameter is only effective until the first successful logon to the AE system. Afterwards, you can use the parameter RECONNECT_TIME in the host characteristics.

For z/OS Event Monitor: The Console command "MODIFY ..., EX=<addr>,:<port> serves to facilitate a new connection immediately. In this case, the attempt to re-connect to the specified agent is made immediately. A reconnection is established, even if the Event Monitor already has a connection to another agent. A new connection is then established. The old connection is ended if the new connection has successfully been established.

Default: 60

maxMsgSize =

Maximum length of messages (in bytes) that a CP (Server communication process) or an Agent accepts in Bytes.

Default: 500000

maxRepCnt =

The maximum number of report blocks that should be transferred to the Automation Engine at the same time.

Default: 8

port =

Port number of the agent.

Other agents and the Job Messenger establish a connection with the agent by using this port number.

Default: 2300

sendBufferSize =

The size of the TCP/IP input buffer for the messages that should be sent (in bytes).

The default value that depends on the system environment is used when you do not define this setting or when you define the value 0.

Default: 1024k

recvBufferSize =

The size of the TCP/IP input buffer for the message that should be received (in bytes).

The default value that depends on the system environment is used when you do not define this setting or when you define the value 0.

Default: 1024k

tcp_KeepAlive =

This sends keep-alive packets in order to keep the agent connections.

This parameter is only checked when the agent runs under Linux.

Values

  • Y: Keep-alive packets are sent.
  • N: Keep-alive packets are not sent.

Default: Y

tcp_KeepAlive_Time =

The time interval in seconds in which keep-alive packets are sent in order to keep connections.

The default value that depends on the system environment is used when you do not define this setting or when you define the value 0.

Default: 6600

[ AUTHORIZATION ]
initialPackage =

The name and the path of the file that includes the authentication package (company-key file).

This parameter must be specified if you use the authentication methods "Server" or "Server and Agent". Authentication will not succeed if the company-key file is missing.

When the agent starts, it reads the company-key file. The file is deleted after successful authentication.

Default:

trustedCertFolder =

The path to the folder where additional trusted certificates are stored (optional). Certificates must be PEM encoded.

Default:

agentSecurityFolder =

The path to the folder where the agent can store security related files needed for authentication. E.g., private key, signed certificate, root certificate.

If the folder does not exist, it will be created when the agent starts for the first time. The folder should not be deleted, renamed or moved.

Default: ./security

keyPassword =

The password used to encrypt the agent's private key.

The password can be obfuscated using the UCYBCRYP utility.

A random password will be generated at runtime if this is left empty.

Default:

SSLCertDir =

The location of the trusted CA certificates, with each certificate in a separate file.

Newer distributions usually have this format to faster lookup certificates by a hash value, for example /etc/ssl/certs/.

This location can also be set by using the SSL_CERT_DIR environment variable.

Default:

SSLCertFile =

The location of the trusted CA certificates, included in one file in pem format.

Older distributions might have all certificates in one file, for example /etc/pki/tls/certs/ca-bundle.crt.

This location can also be set by using the SSL_CERT_FILE environment variable.

Default:

ft_source =

Agent can be use as a source for file transfers; default = yes

Values

  • yes: The agent can be used as a source of a file transfer
  • no: The agent can not be used as a ft source

Default:

ft_target =

Agent can be use as a target for file transfers; default = yes

Values

  • yes: The agent can be used as a target of a file transfer
  • no: The agent can not be used as a ft target

Default:

Execute =

Agent can execute jobs; default = yes

Values

  • yes: The agent can execute jobs
  • no: The agent refuses to execute jobs

Default:

CAU_enabled =

Agent can be updated by CAU; default = yes

Values

  • yes: The agent can be updated by using CAU
  • no: The agent refuses to be updated by using CAU

Default:

[ FILETRANSFER ]
ft_Check_Free_Disk_Space =

This parameter checks the available hard disk space before a file transfer is processed.

Checking the available space of network drives may occasionally lead to an incorrect result.

Values

  • yes: The system checks whether there is sufficient hard disk space for the files that should be transferred. The files will only be transferred when there is enough space. Otherwise, the file transfer will abort with an error message.
  • no: No check is made.

Default: no

ft_Linkfiles =

By using this parameter you control, if the agent should transfer linked files of the source or ignore them.

Executing a Wildcard File Transfer with "no" as value, may result in the transfer being set to ENDED_EMPTY, in case there are only links in the source directory.

Values

  • yes: Links will be dereferenced and files the links are pointing to, will be transferred.
  • no: Links will be ignored.

Default: no

ft_ConnectingTimeout =

This parameter can be used to specify the seconds attempting to establish a new connection to the file transfer partner.

Default: 10

[ HOSTS ] Assignment of an agent's name to its address (DNS name or TCP/IP address) if it cannot directly be accessed through the address that is stored in the server.

Specify several assignments line by line, there is no upper limit for the number of assignments.

In file transfers, the sending agent obtains the destination agent's internal address from the Automation Engine.

The sending agent replaces this internal address by the external address that is defined here.

This setting is only required if you run file transfers with agents that cannot directly establish a TCP/IP connection between each other by using the address that they have received from the Server.

This can happen if the agents that are involved in the file transfer are located on different networks or if a firewall is used.

[ MISC ]
authentication =

Authentication method for the login data in the Login objects of the jobs and file transfers.

PAM authentication is only supported for agents that run on AIX, Linux and Sun Solaris

Values

  • local: OS calls
  • PAM: Pluggable Authentication Modules (see also: parameter Libname=)

Default: local

FileBufferSize =

Size of the input buffer for files that are transferred with a File Transfer Object .

Bytes are used by default. Alternately, you can also append the letter "K" or kilobytes or "M" for megabytes to the number. You can use uppercase or lowercase letters for this purpose. The OS setting is used if 0 is specified.

Examples (the following definitions are identical):

Specification in bytes: 1048576

Specification in Kbytes: 1024K or 1024k

Specification in Mbytes : 1M or 1m

Default: 0

FileEndDelimiter =

file transfer: line breaks in text files

Values

  • yes: The agent always adds an LF to the end of text files in file transfers in which it is the receiving agent.e It is irrelevant whether the files already end with an LF.
  • no: The files are transferred without any changes.

Default: no

fileRemoveCheck =

Authorization check before the source file is deleted.

Values

  • yes: The user's authorization to delete the source file is verified.
  • no: The authorization is not verified and the file is deleted. The UNIX user under which the agent runs is used (usually this is root).

Default: yes

MsgToStdout =

Logging output in the terminal that is used to start the agent.

Values

  • yes: The agent's logging data is output in the console. An additional log file is written.
  • no: Logging data is only written to the log file.

Default: no

processInfo =

Collection of process information

This parameter is not available for AIX.

Values

  • yes: The agent retrieves the process information of all AE processes and sends it to the Automation Engine for the periodic job check. By doing so, the consumed CPU time is refreshed in the UserInterface. Note that this can negatively affect CPU and performance if many active processes are involved.
  • no: No process information is collected. The consumed CPU time is retrieved when the job has ended and then sent to the Automation Engine.

Default: yes

TraceFileSize =

The maximum size of a trace file.

The agent creates a new file if this value has been reached. Bytes are used by default. Alternately, you can also append the letter "K" or kilobytes or "M" for megabytes to the number. You can use uppercase or lowercase letters for this purpose.

Default: 32M

FolderOwner =

Specified user name or id who becomes the owner of the newly created agent's folder,

default is the user who executes the agent,

if you use a ID instead of name, then this ID will be then used for user and group ownership

Default:

FolderOwner_backup =

Owner of backup directory

Default:

FolderOwner_temp =

Owner of Agent's temp directory

Default:

FolderOwner_out =

Owner of Agent's output directory

Default:

FolderOwner_cache =

Owner of Agent's resources cache directory

Default:

FolderPermissionMask =

specified permission masks is used as default for for newly created Agent's folders

existing folder permissions are not modified

the mask can be used as octal number eg. 777 or as string representation eg. rwxr-xr-x

Default: rwxrwxrwx

FolderPermissionMask_backup =

Permission mask of backup directory, can be used to overwrite the default settings

Default:

FolderPermissionMask_temp =

Permission mask of Agent's temp directory, can be used to overwrite the default settings

Default:

FolderPermissionMask_out =

Permission mask of Agent's output directory, can be used to overwrite the default settings

Default:

FolderPermissionMask_cache =

Permission mask of Agent's resources cache directory, can be used to overwrite the default settings

Default:

[ PAM ]
libName =

Path and filename of the PAM library.

Specify the library name if the PAM authentication methodshould be used (see also parameter authentication=). By default, the file libpam.so is searched in the agent's directory

This parameter is only relevant for AIX, Linux and Sun Solaris agents

Default: libpam.so

pam_Open_Session =

open pam session on job level.

If turned on and PAM authentication is used, a PAM user session is opened for each job also applying the session credentials by PAM (e.g. limits defined in /etc/security/limits.conf). This setting applies to jobs, but not File Transfers or FILE Events.

Values

  • yes: turned on
  • no: turned off

Default: no

[ STARTCMD ]
start_Type =

Method that is applied to start jobs.

Values

  • fork: The job starts with fork function.
  • batch: The job starts with a batch command.

Default: fork

shell =

Bourne-Shell=su - &user -c '(nohup &jobFile 1>&jobReport 2>&1 & echo $!)'

C-Shell=su - &user -c '(nohup &jobFile 1>&jobReport & echo $!)'

Korn-Shell=su - &user -c '(nohup &jobFile 1>&jobReport 2>&1 & echo $!)'

Other-Shell=su - &user -c '(nohup &jobFile 1>&jobReport 2>&1 & echo $!)'

Default:

[ USERID ] The definition of the authorized/unauthorized users

Format: user=START|NO_START

User has to be defined in the notation of the Operating System,

Windows: User/Domain

Unix : user

BS2000 : Userid TSOS

SAP : client number/user name

Examples:

Windows: ni/home=START

BS2000 : TSOS=NO_START

SAP : 001/NI=START

This section only affects Job objects. File Transfer or FILE Event Objects are not affected.

[ UC_USER ] This section only affects Job objects. File Transfer or FILE Event Objects are not affected.
[ VARIABLES ] This section contains the agent variables that include agent settings and information.
UC_EX_JOB_MD =

Path and file name of the Job Messenger

Default: ucxj???m

UC_EX_IP_ADDR =

IP address used to contact Agent's listen port.

Default:

UC_EX_IP_PORT =

Port used to contact Agent's listen port.

Default:

UC_EX_JOB_MD_IP_ADDR =

IP address used by the Job Messenger to contact Agent's listen port. This setting is necessary when UC_EX_IP_ADDR should be used by other agents for File Transfers, but the Job Messenger should use a different value (i.e. localhost). This setting overwrites UC_EX_IP_ADDR for the Job Messenger.

Default: localhost

UC_EX_JOB_MD_IP_PORT =

Port used by the Job Messenger to contact Agent's listen port. This setting is used by the agent automatically when UC_EX_JOB_MD_IP_ADDR is set with the value of PORT. This setting overwrites UC_EX_IP_PORT for the Job Messenger.

Default:

UC_EX_HOST_ROLE =

Role of the Agent, which is the name that can be used as a filter in Agent groups.

Default:

UC_EX_HOSTCHAR =

Suffix part of the UC_HOSTCHAR_<SUFFIX> variable which contains specific agent settings.

Default: DEFAULT

UC_EX_PATH_BACKUP =

Path to the backup directory for file backup/restore feature

Default: ../backup/

UC_EX_PATH_CACHE =

Directory is used to store client-wide resources.

Default: ../resources/

UC_EX_PATH_BIN =

Path to Agent binaries

Default: .

UC_EX_PATH_JOBREPORT =

Path to which the Agent writes job reports

Default: ../temp

UC_EX_PATH_TEMP =

Path to which the Agent writes log and trace files

Default: ../temp

UC_HOST_CODE =

Name of the code table object in client zero used for transporting jobs and job reports to the target system and vice versa

Default: UC_CODE

UC_HOST_JCL_VAR =

The reference to Includes that are used when the job is generated. (JCL Variant)

These are generally the Includes HEADER.*, TRAILER.* and RESTART.* of the system client 0000. User-defined Includes can also be used.

Default: UNIX

[ JCPLIST ] This section is self-maintained and contains port-to-host mappings of either all available Java communication processes or TLS-Gateways depending on the Agent's server connection setup.

When an Agent starts using the value defined in the connection= parameter, it receives a list of all JCPs available from the Automation Engine. On connection attempts from that point forward the agent will connect to a random JCP from the JCPLIST.

You can also use the JCP_ENDPOINT parameter in the UC_SYSTEM_SETTINGS variable to define where to reach the JCPs. In this case, the Agent receives all entries from the JCP_ENDPOINT definition and stores the information in this section.

If the JCP_ENDPOINT points to the location of only one load balancer, the JCP sends this location to the connecting Agent. However, if the JCP_ENDPOINT points to more than one load balancer, the JCP sends the location of all the load balancers available to the connecting Agent.

Allowed formats:

JCP1=host-name:port

JCP2=host-name:port

...

or

JCP1=https://host-name:port/

JCP2=https://host-name:port/