Installing and Configuring Windows Agents

This section describes how to install, configure, and run an agent on Windows.

Windows Server 2012 .NET Requirement

The Windows Agent installation requires .NET 4.7.2 or higher. For more information, refer to the TA Compatibility Matrix.

Installing an Agent on Windows

To install an agent:

1. Download and extract the Tidal Automation Agent for Windows software.

2. Double-click the Agent_windows_TIDAL Agent.msi file. The Security Warning dialog is displayed.

3. Click Run. The Status panel is displayed. The Welcome to the TA Agent Setup panel is displayed.

   Note: If any other agents are running on the machine, a dialog notifies you that the agent(s) must be stopped before the installation can continue.

4. Click Next. The Destination Folder panel is displayed.

5. Choose the directory where the TA files will reside:

   • Click Change and choose the appropriate file.

     OR

   • Accept the default location at C:\Program Files (x86)\TIDAL.

6. Click Next. The Agent Port Number panel is displayed.

7. Enter the port number that the agent will listen on. The default port is 5912.

8. Click Next. The Ready to Install the Program panel is displayed.

9. Click Install.

   Note: Do not click Cancel once the installation copies files in the Setup Status screen. Cancelling the installation at this point corrupts the installation program.

   You will not be able to install the component without the help of the Tidal Support Center. If you do not want to install the component, you must complete the installation and then uninstall it.

   The Setup Completed panel is displayed.

10. Click Finish.

Verifying the Installation

To verify the installation:

1. Click All Programs > Tidal Automation > TA Service Manager on the Windows Start menu to display the TA Service Manager.

2. Click AGENT_1 on the Services list.

   If the TA Service Manager displays the message AGENT_1: Running at the bottom, then the agent runs and the installation succeeds.

   Note: To edit the service parameters, click ellipsis to access the Service Configuration dialog.

Silent Mode Installation

To install the Tidal Agent for Windows:

1. Locate the Installer in the directory

2. Execute the below commands in the command prompt.

   msiexec /i "Installer Directory" INSTALLDIR="path" PORT=number /l*v "Logpath" /quiet

   Note: The default path of the INSTALLDIR is "C:\Program Files (x86)\TIDAL" and the port value is PORT = 5912. If required, the user can change the default value of the port.

   Example: msiexec /i "C:\TES\silent 1\TWA Agent.msi" INSTALLDIR="C:\Program Files (x86)\TIDAL\" PORT=5912 /l*v C:\Test\msilog.txt /quiet

3. Press Enter. The silent installation is triggered.

4. Navigate to <log file path> to ensure the Windows Tidal Agent has been installed successfully.

Configuring Agents on Windows

You can add and edit agent instances with the Agent Instance Manager.

Adding Agent Instances

To add an instance:

1. Click Programs > Tidal Automation > Agent > Instance Manager on the Windows Start menu, then right-click on the Instance Manager and choose “Run as Administrator” to display the Instance Manager.

2. Click Add.

3. Enter this information:

   • Service Name – The name of the agent service. The name in this field is automatically generated and cannot be edited.

   • Display Name – The name of the agent to add. The name in this text field is automatically generated as a possible candidate for your agent's name. You can keep the name or change the name.

   • Port – Choose the agent's port number to listen for Master connections. By default, the TIDAL_AGENT_1 port is 5912.

     Note: When you add additional agents, the port increments by one by default.

   • Run on a cluster group – Enabled if this agent instance is on a node that is configured for a cluster with an existing agent service. This option is unavailable if the node is not part of a cluster. See Configuring the Windows Agent for a Cluster.

4. Click Save.

   Note: To connect to the agent you just added, see Defining an Agent Connection.

Editing Agent Instances

You can modify the port number and the name of the instance displayed, but the service name cannot be changed.

Note: The Edit button is unavailable as long as the agent is running.

To edit an instance:

1. Stop the agent.

2. Click All Programs > Tidal Automation > TA Service Manager on the Windows Start menu to display the TA Service Manager.

2. Choose TIDAL_AGENT_<#> from the Services list.

3. Click Stop.

   • Click Programs > Tidal Automation > Agent > Instance Manager on the Windows Start menu, right-click on the Instance Manager and choose “Run as Administrator” to display the Instance Manager.

   • Click the instance.

   • Click Edit. The Edit dialog is displayed.

   • Make the necessary edits, then click Save. The Information dialog is displayed.

4. Click OK.

5. Restart the agent.

   • Click All Programs > Tidal Automation > TA Service Manager on the Windows Start menu to display the TA Service Manager.

   • From the Services list, choose TIDAL_AGENT_<#>.

   • Click Start.

Deleting Agent Instances

Deleting agent instances does not delete the agent. Even if you delete all instances, you must still uninstall the agent program to remove the agent.

Note: The Delete button is unavailable as long as the agent is running.

To delete an instance:

1. Stop the agent.

2. Click All Programs > Tidal Automation > TA Service Manager on the Windows Start menu to display the TA Service Manager.

3. Choose TIDAL_AGENT_<#> from the Services list.

4. Click Stop.

5. Click Programs > Tidal Automation > Agent > Instance Manager on the Windows Start menu, then right-click on the Instance Manager and choose “Run as Administrator” to display the Instance Manager.

6. Choose the instance.

7. Click Delete. A confirmation message is displayed.

8. Click Yes.

Note: It is recommended that you do not delete the last agent instance called agent_instance_1. It is better to uninstall the agent program to remove the previous agent instance. For instructions on uninstalling the agent, refer to Uninstalling Unix Agents Using theCommand Line.

Note: To delete an agent through the client, see Defining an Agent Connection.

Configuring an Agent for Windows

Note: This section is optional.

After installing or adding agents, you can configure some Windows settings through the Services window, as documented below, or through the TA Services Manager, as discussed in Verifying the Installation.

To configure an agent for Windows:

1. Click Settings > Control Panel on the Windows Start menu.

2. Double-click Administrative Tools.

3. Double-click Services.

4. Double-click the agent you just installed.

5. Click Stop on the General tab of the AGENT Properties dialog to stop the service.

6. Click the Account on the Log On tab.

7. Enter the requested information in the User Name/Domain Name and Password fields, then click OK.

8. Right-click the agent and choose Start.

   OR

   Cclick Start on the General tab to restart the agent.

9. Close the Services and Administrative Tools dialoges.

10. Navigate to the client and follow the Configuring an Agent for Windows procedure to re-connect the agent.

Configuring Agent Parameters

Specific parameters of the Windows agent can be configured for users' convenience. You modify the parameters of a Windows agent by adding the parameter statements to the Service Manager Agent startup parameters (add them to the Service Manager Path field) or optionally (for most parameters) in the tagent.ini file. If the default location was used during the agent installation, the agent files are in C:\Program Files (x86)\TIDAL\Agent\Bin.

Any parameters specified in the Service Manager Path field will precede anything specified in tagent.ini. Some parameters needed during start must be specified in the Service Manager Path field (cpuload, msgthreads, rjaport).

The tagent.ini file in the bin directory works the same as in Unix agents, except the agent(s) definition and ports are not specified there. There is a [config] section and an [<Agent Name>] section. The parameters specified in the [config] section are global, and the parameters specified in the [<Agent Name>] section only apply to that agent. They will override specifications in the [config] section for the specific agent.

The tagent.ini file:

[config] debug=y logdays=3 logsize=1024000 encryptonly=y sslvldcrt=y

vldhstcrt=y this a synonym for sslvldcrt, as host validation also applies to SSH (only works in tagent.ini)

[TIDAL_AGENT_1]

debug=high logdays=5 logsize=2048000 encryptonly=n vldhstcrt=n

If specified in tagent.ini, you do not need to specify them in the Service Manager Path field. Restart the agent after modifying any of the agent’s parameters.

These agent parameters can be modified:

• Debug

  y|high

  Where y (yes) turns on low-level debugging and high turns on maximum debug level.

• Logdays

  N

  Where n is the number of days to preserve logs. Older logs will be deleted.

• Sftpumask

  <xxxx>

  Where xxxx is a permissions mask (4 digit octal) for files created on a Unix-type system by SFTP PUT actions. Default is '0022'.

• Logfilesize

  <xxxxxxxxx>

  Where xxxxxxxxx is the maximum log file size (512 MB). Default value is 1 (in MB).

• Number of Message Threads

  A new startup parameter, MSGTHREADS=x, has been added. It can optionally be specified on the startup line. The default number of threads that will handle messages is five, which seems optimal for 1-2 CPU machines. If you have more CPUs, you may want to increase your thread count.

• EncryptOnly Option

  The EncryptOnly startup parameter option has been added. EncryptOnly=Y will cause an Agent not to remain connected to any Master that has turned off message encryption.

  The default is EncryptOnly=N. It must be set to Y (Yes) for the more restrictive rules to take effect.

• Secure FTP Host Validation

  Tidal Automation Agents v3.0 validates the host defined in the FTPS SSL certificate. This is a change in behavior from the current Windows agent. The Host Validation feature can be turned off by specifying an SSLVLDCRT parameter on the agent command line. The default is SSLVLDCRT=Y (yes). You can turn this off by selecting SSLVLDCRT=N. Use Service Manager to edit the Agent startup parameters (add them to the Service Manager PATH field). Use vldhstcrt as an optional synonym that is available only in tagent.ini.

• AGTRESOURCE

  AGTRESOURCE=CPU;VMEM enables monitoring CPU and VMEM monitoring with default time (15 seconds) AGTRESOURCE=CPU,10000 enables monitoring only CPU with default time

  The AGTRESOURCE specifications above indicate that (1) CPU utilization and Virtual Memory utilization should be monitored, (2) only CPU utilization should be monitored and change the time interval to 10 seconds (10000 milliseconds), and (3) CPU utilization should be monitored at a time interval of 10 seconds (10000 milliseconds) and that Virtual Memory utilization should be monitored every 15 seconds (15000 milliseconds).

  The default time to send the resource value(s) to the Master will be 15 seconds, and the minimum allowed time will be 5 seconds.

  Note: The Linux sysstat package must be installed to use this parameter.

• MultiFTPStd

  Y|N

  Where Y is the default, Standard FTP, with no error if no files are operated on by MGET, MPUT or MDELETE. N is non-standard FTP completion where the job will complete abnormally if no files are operated on.

• FTPTimeout

  nnnnnn

  Where nnnnnn is timeout time in milliseconds. 0 will cause no timeout (infinity).The Windows default timeout is 2 minutes (120000 milliseconds). This is a signed integer value.

Starting and Stopping Agents on Windows

To start or stop an agent:

1. Click All Programs > Tidal Automation > TA Service Manager on the Windows Start menu to display the TA Service Manager.

2. Choose the name of the agent from the Services list.

3. Click Start to start the agent.

   OR

   Click Stop to stop the agent.

Checking Agent Status

To check the status of an agent:

1. Click All Programs > Tidal Automation > TA Service Manager on the Windows Start menu to display the TA Service Manager.

2. Choose the name of the agent from the Services list.

The status of the agent is displayed at the bottom of the manager.

Configuring Jobs to Run in the Foreground

Since job processes do generally not require user interaction, they usually run in the background on the agent machine. You can configure your agent’s system to run job processes in the foreground if needed. Running processes in the foreground allows user interaction with the process as it runs and enables more processes to run by providing another desktop. This can be configured to run in two different ways.

Note: Changing settings in the Windows registry can have severe consequences for your computer system. Consult with your Windows system administrator before making any changes to the registry.

If you want to be able to interact with the process, you can configure the job to run in a command prompt window.

To configure jobs to run in the foreground:

1. Navigate to TA Service Manager > Service Configuration.

2. Click Run as LocalSystem and Allow Service to Interact with Desktop check boxes, respectively.

3. Open regedit for 64-bit systems and navigate to Registry HKEY_LOCAL_MACHINE\SOFTWARE\Tidal Software. Navigate to Registry HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\TIDAL Software\Agent for 32-bit systems.

4. Right-click Tidal Software and add a new key.

5. Add a new key with the agent name.

   Example: TIDAL_AGENT_1.

6. Create a new string called JobLaunchMode with a value of 7 under TIDAL_AGENT_1.

7. Click the Value Data field and type one of these numeric values to configure the appearance of the command prompt window:

   0 = Hides the command quick window and activates another window.

   1 = Activates the command quick window and displays it minimized.

   2 = Activates the command quick window and shows it in its current size and position.

   3 = Activates the command prompt window and displays it at maximum size

   4 = Activates the command prompt window and displays it at a minimized size.

   5 = Displays the command prompt window in its current size and position, but the window is not activated.

   6 = Displays the command prompt window at its most recent size and position, but the window is not activated.

   7 = Activates and displays a window at its original size and position. Recommended when displaying the command prompt window for the first time.

8. Set Job to Use Windows Password on the Job on the Run tab.

9. Check the for UNIX checkbox on the Job under Options tab.

10. Set the Windows/FTP/Datamover password for the Runtime Users in Runtime Users field.

11. Log onto the Agent server as the Runtime User.

    If needed, you can repeat this procedure for the other agent instances listed in this key. To revert to the original configuration, delete the added registry key.

    If you want the job process to run in the foreground without interacting with the job, you can run it from the default desktop.

Configuring Jobs to Run from the Default Desktop

To run a job from the default desktop:

1. Navigate to TA Service Manager > Service Configuration.

2. Click Run as LocalSystem and Allow Service to Interact with Desktop check boxes, respectively.

3. Open regedit for 64-bit systems and navigate to Registry HKEY_LOCAL_MACHINE\SOFTWARE\Tidal Software. Navigate to Registry HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\TIDAL Software\Agent for 32-bit systems.

4. Right-click Tidal Software and add new key.

5. Add a new key with the agent name.

   Example: TIDAL_AGENT_1.

6. Create a new string called JobUseDefDesktop with a value of 7 under TIDAL_AGENT_1 .

7. Click the Value Data field and type one of these numeric values to configure the appearance of the command prompt window:

   0 = Hides the command prompt window and activates another window.

   1 = Activates the command prompt window and displays it minimized.

   2 = Activates the command prompt window and displays it in its current size and position.

   3 = Activates the command prompt window and displays it at maximum size.

   4 = Activates the command prompt window and displays it at a minimized size.

   5 = Displays the command prompt window in its current size and position, but the window is not activated.

   6 = Displays the command prompt window at its most recent size and position, but the window is not activated.

   7 = Activates and displays a window at its original size and position. It is recommended when displaying the command prompt window for the first time.

8. Set Job to Use Windows Password on the Job on the Run tab.

9. Check the For UNIX checkbox, source user profile on the Job under Options tab.

10. Set the Windows/FTP/Datamover password for the Runtime Users on Runtime Users.

11. Log onto the Agent server as the Runtime User.

Configuring a Windows Agent to be a Remote Job Adapter Proxy

Designating the Port for HTTPS

To designate the HTTPS port:

1. Click All Programs > Tidal Automation > TA Service Manager pn the Windows Start menu to display the TA Service Manager.

2. Click ellipsis to display the Service Configuration dialog.

3. Click the Path field and edit the command line of the Agent by entering the parameter:

   RJAPort=PPPPP

   Where PPPPP (e.g. 50001) is the port number you want to use for the HTTPS connection from the Adapter.

   Example: "C:\Program Files\TIDAL\Agent\Bin\TidalAgent.exe" AGENT=TIDAL_AGENT_1 PORT=5912 PATH="C:\Program Files\TIDAL\Agent" RJAPort=PPPPP

4. Click OK.

5. Allow the Service Manager to restart the agent when you save the change.

   Note: The proxy support will not be available in this Agent if the RJAPort is not specified in the command line. The Agent will not be usable by the Adapter until the RJAPort parameter is specified.

   Note: After adding the RJAPort parameter, you must add another dependency to the Agent service definition called HTTP SSL. You can do this by entering Service Manager, clicking the ellipses (...) for the specific agent, selecting the 'Dependencies' tab, and then selecting 'HTTP SSL' as a new dependency. The Agent will not start automatically at system start-up without adding this dependency. (May not be available in Windows 2008 and beyond)

Assigning Certificate to the Port for HTTPS

If your machine already has a valid server certificate, you should only have to perform Steps 7 and 8 below.

To create a self-signed host certificate and configure it to a port:

1. Open a DOS prompt (Command Shell).

2. Click Run on the Windows Start menu. The Run dialog is displayed.

3. Enter cmd.

4. Click OK.

5. Enter this to create and install a self-signed certificate in the certificate store:

   makecert -r -pe -n "CN=localhost" -eku 1.3.6.1.5.5.7.3.1 -ss my -sr localMachine -sky exchange

   Note: makecert is available in the SDK if you have Visual Studio 2005 installed (Microsoft Visual Studio 8\SDK\v2.0\Bin). There are other ways to get a certificate.

6. Start Microsoft Management Console (mmc) and copy the certificate "local" located in Personal > Certificates into Trusted Root Certification Authorities > Certificates.

7. Run at the DOS prompt (Command shell):

   Note: The port used to connect from the Master to the proxy agent via HTTPS (the RJAPORT) requires that it be configured to use SSL.

   For pre-2008 systems:

   httpcfg.exe set ssl -i 0.0.0.0:PPPPP -c "Root" -h XXXXX

   where 0.0.0.0:PPPPP is the IP and port.

   This for https://localhost:PPPPP, where XXXX is the Thumbprint value of the local certificate. To obtain the thrumbprint of a certificate, open the certificate and click the Details tab. Copy the thumbprint and delete all blanks (spaces) between numbers in 'Thumbprint'

   Note: It is critical that the name after '-c' in the httpcfg set matches the store that the certificate is in, Root is recommended (see below).

   Store Names:

   • AddressBook – The X.509 certificate store for other users.

   • AuthRoot – The X.509 certificate store for third-party certificate authorities (CAs).

   • CertificateAuthority – The X.509 certificate store for intermediate certificate authorities (CAs).

   • Disallowed – The X.509 certificate store for revoked certificates.

   • My – The X.509 certificate store for personal certificates.

   • Root – The X.509 certificate store for trusted root certificate authorities (CAs).

   • TrustedPeople – The X.509 certificate store for directly trusted people and resources.

   • TrustedPublisher – The X.509 certificate store for directly trusted publishers.

   For post-2008 systems:

   netsh http add sslcert ipport=0.0.0.0:PPPPP certhash=XXXX appid={YYYYYY}

   where ipport=0.0.0.0:PPPPP (e.g. 0.0.0.0:50001) is IP and port, this for https://localhost:PPPPP.

   certhash= XXXX is the Thumbprint value of the local certificate. To obtain the thrumbprint of a certificate, open the certificate and click the Details tab. Copy the thumbprint and delete all blanks (spaces) between numbers in 'Thumbprint'.

   appid={YYYYYY} is a GUID identifying the owning application.

8. Click OK.

Preventing Unauthorized Use of Windows Agent

To prevent unauthorized user access to Windows agents, each agent includes a Users.cfg file that controls which users can run jobs on that agent.

You must create the Users.cfg file in the agent’s local directory. This directory is in the install path of the agent and has the name of the agent as it was specified when the agent was defined, similar to the default location:

C:\Program Files\TIDAL\Agent\TIDAL_AGENT_1

Add the list of users to be excluded or allowed to run jobs on an agent in the Users.cfg file. If an unauthorized user tries to run a job on an agent that the user is excluded from, the job ends with an “Error Occurred” status.

To define which users can run jobs on an agent:

1. Login as the owner of the agent.

2. Create a file called Users.cfg in the root directory of the agent install location.

   Example: C:\Program Files\TIDAL\Agent\<name-of-agent>.

   Note: The file name, Users.cfg, is case sensitive, so only the first letter should be capitalized and the rest of the name should be lowercase.

   Note: This file should have limited access using native system access control definitions.

3. Add one of these parameters to the Users.cfg file:

   • EXCLUDE – Only the specified users cannot run jobs on the agent. This is default parameter, if no other parameter is specified.

   • INCLUDE – Only the specified users can run jobs on the agent.

     This example excludes only three users while allowing all other users to run jobs on the agent.

     Example: EXCLUDE
     TESUser1
     TESUser2
     TESUser3

   • EXCLUDE

     TESUser1 TESUser2 TESUser3

4. To ensure the changes take effect, do either:

   • Stop and restart the agent.

   • Disconnect and reconnect the client connection to the agent.

   Note: While this procedure prevents unauthorized users from running system commands on an agent for which they are excluded, FTP jobs can still be run from the agent because a user does not login to an agent for FTP access.

Configuring a Cluster to Run the Windows Agent

The Agent for Windows can run in a Windows cluster environment. A cluster environment is defined as multiple machines working together as one system. The cluster environment provides a level of redundancy so that if one of the machines in the cluster fails, another machine is available to replace the failed component.

The instructions describe how to configure a two-node cluster environment to run the Windows agent TA offers.

Prerequisites

Before installing the Agent for Windows on the nodes of a cluster, complete and verify these on each node:

• Verify that the systems on each node are identical

• Verify that the agent machines in each node meet the hardware and software requirements specified in the TA Compatibility Matrix.

• Verify that the user installing the Windows agent has the specified user rights including access to the registry on each machine.

• Verify that the cluster group has these resource types:

  Network name

  IP address

  Physical disk

Configuring the Windows Agent for a Cluster

During configuration, you should complete a step on a machine and then go around to the other machines in the cluster and do the same step. When that step has been performed on each machine in the cluster, return to the first machine and do the next step, and then again do that step on the other machines in the cluster, and return to the first machine and do the next step, etc.

An agent instance must exist on every node in the cluster before it can be configured to run as a cluster. This means that if you add a third agent instance to a machine before you configure that instance, go to all of the other machines in the cluster and add a third instance.

To configure the agents:

1. Verify that the cluster works correctly.

   Check that the cluster software is installed and configured correctly by forcing a failure on a server. Be sure that a failover to another server occurs as intended, and that control can be returned to the failed server. Your Windows Cluster Administrator should help you with this.

2. Install the Agent for Windows on the first cluster node.

   Be sure to install the agent to a non-clustered physical disk on the local machine using the default directory path during installation.

   Note: Install the agent on the same disk drive letter on each cluster node. For example, if you install the agent on the C drive of one node, the agent must be installed on the C drive of the other nodes also.

3. Stop the agent if it is running.

   Note: If an agent instance is configured as part of a cluster, you cannot stop the agent. You must stop the agent service.

4. An agent instance must exist on every node in the cluster before it can be configured to run as a cluster. If you are adding an agent instance, add the agent instance to a machine. Go to each of the other nodes in the cluster and add that same instance.

   Once each node on the cluster has the same agent instance, you can edit the agent instance to configure it for the cluster.

   Choose Programs > Tidal Automation > Agent > Instance Manager from the Windows Start menu to display the Agent Instance Manager.

5. Choose the first agent instance and click Edit to display the Agent Instance Manager’s configuration screen.

   If this agent instance is on a node configured for a cluster with an existing agent service, the Run on a cluster group option is available. This option is unavailable if the node is not part of a cluster. You cannot proceed any further without verifying with your Windows Cluster Administrator that the node is correctly configured as a cluster member.

6. Choose the Run on a cluster group option to expand the screen to display the cluster configuration fields.

7. Choose which cluster group this agent instance belongs to in the Cluster Group field.

8. Choose the disk on which the agent instance resides on the Physical Disk field. All the disks that were created on all of the cluster groups are listed. Be sure to choose a disk that exists on the cluster group you selected.

9. Click the Work Directory field and enter the pathname to the work directory created for the cluster group.

   Note: This Work Directory must be on a shared disk that moves with the active node on a fail-over.

10. Choose which node this agent instance is on in the Cluster Nodes field. When the fields are completed, click Save.

11. Go to each node and repeat this procedure for each agent instance.

12. When each agent instance on each node is configured correctly, start each clustered agent instance from its active node using the TA Service Control Manager. Starting the agent instance in the Service Control Manager automatically starts the agent resource in the Windows Cluster Administrator.

Uninstalling Agents on Windows

To uninstall the agent, you must use the Add/Remove Programs utility in the Windows Control Panel.

To uninstall an agent:

1. Close the TA client to begin the uninstallation process.

2. Click the Windows Start menu and choose Settings>Control Panel, then double-click Add or Remove Programs.

3. Scroll down the list of programs installed on the machine to the TA program.

4. Click the TA program to highlight it.

5. Click Remove to start the uninstallation process.

6. Click OK when prompted to confirm that you want to uninstall the program.

7. Click Finish to end the uninstallation process.

8. Reboot the machine to save the changes to the registry.

   Note: An empty folder may be left in the Start menu after uninstalling TA components. If this occurs, go to the Programs directory and delete the empty folder manually. The installation log file must also be manually deleted.