TPC - Terminal Plugin Controller - FAQ

What is TPC?
TPC is our upgraded solution to replace PMTerminal. We can change the plugins without affecting
the current structure. For example, we can keep the process and prompts text files and replace only
the engine.

TPC functions as both a platform for creating state machine plugins, and as an engine for running
these plugins (interpreter). It supports communication protocols SSH and Telnet. In addition,
provides the ability to interact with common scripting languages, such as Python, PowerShell, and
cScript.

The CPM calls the TPC.exe and provides the following input:

• Action (can be one of the following - logon, verify, change, prereconcile, reconcile)
• User parameters file (containing policy parameters and file categories)

For example:

• It then waits for the process to end and in case of a failure, writes the error message in the
TPLog.

The TPC completes the following:

• Parse input from CPM

• Validate input from CPM
• Serialize plugin implementation files (Process + Prompts)
• Build an automated state machine that will interact with remote target machine
• Establish a connection to remote target machine
• Execute automated state machine protocol with target machine to achieve the relevant
scenario completion.

Where scenario can be one of the following:

o Logon
o Verify
o Change password
o PreReconcile
o Reconcile

All scenarios are supported via logon account as well.

Why do we utilize it? Why is it required?
https://cyberark.my.site.com/s/article/What-are-the-differences-between-PMTerminal-and-TPC

How do we upgrade TPC?

**Please ensure your TPC is always on the latest version to take advantage of the newest features
and bug fixes through the version.

The steps are listed below:

1) Download latest TPC plugin from CyberArk Marketplace. Link below:

https://cyberark-customers.force.com/mplace/s/#a3550000000El8nAAC-a3950000000jju7AAA

2) Transfer zipped file to the CPM (create a temporary folder and unzip it in that folder)

3) Backup the bin folder (Default location <drive>:\Program Files (x86)\CyberArk\Password

Manager\bin)
4) Copy all unzipped content of the unzipped new TPC version to the bin folder. Allow it to overwrite
old files.

5) Open PowerShell as administrator and navigate to the bin folder

6) Run the following command, this will unblock any file on the bin folder.

Get-ChildItem -Recurse | Unblock-File

7) Please restart the CyberArk Password Manager service (if possible)

(include location of .exe files and process prompts explanation)

Process and Prompts

Prompts file documentation

https://docs.cyberark.com/PAS/13.2/en/Content/SDK/TPC-
promps.htm?tocpath=Developer%7CCreate%20extensions%7CCreate%20CPM%20plugins%7CTermi
nal%20Plugin%20Controller%7C_____1

Process file documentation

https://docs.cyberark.com/PAS/13.2/en/Content/SDK/TPC-
process.htm?tocpath=Developer%7CCreate%20extensions%7CCreate%20CPM%20plugins%7CTermi
nal%20Plugin%20Controller%7C_____2
Basic Troubleshooting
- How to enable debug logs (process/prompt file names within the platform)

Debug Information: https://docs.cyberark.com/PAS/13.2/en/Content/SDK/TPC-

process.htm#Debuginformation

How to Enable Extended Debug and TPCLogonPrompts:

https://cyberark.my.site.com/s/article/00004850

Where can I find the logs for TPC?

TPC logs are stored in the following location(s):

* CPM log files (default location is <CPM installation folder>\Logs):

- pm.log

- pm_error.log

- PMTrace.log

- PMConsole.log

- \ThirdParty\*.log (this is where debug logs are stored)

Common Scenarios and Known Problems
Error:

Invalid username or secret

Action:

• Check the account details

• Run reconcile action to reset the password

Error:

Invalid transition in plugin flow. Refer to log for more information

Action:

• View logs to identify the invalid transition.

• Flow the flow of the plugin and make sure only one session is opened at each given time.
• Make sure only one SendToRemote command is sent between the sending the username and
the password

Error:

Invalid syntax for Invoke command. Valid usage: '(Invoke) "<DLLPath>" "<Action>"'.

Action:

• View logs to identify the invalid state

• Update the Invoke command

Error:

Failed to execute 'spawn' command. Refer to logs for more information

Action:

• View logs to identify the state and information on the failure

Error:

Unable to locate the file '{file path}'

Action:

• Plugin file is too large (CPM Parameters, process, prompt).

• Review and amend the config files

Error:

Unable to locate the file '{path}'

Action:

• Command line validation: Unable to locate CPM parameters file

• Confirm location is correct

Error:

No states were found in the process file. Make sure the plugin contains at least 1 state.

Action:

Review the plugin's process file and make sure the states section is valid

Error:

Spawn command exception: Address parameter is missing in spawn command.

Action:

• View logs to identify the invalid state

• Update the spawn command

Error:
Allowed characters list can't be empty, line '{line}'.

Action:

• Review the "CPM parameter validations" section of the process file

• Make sure all validations with "AllowCharacters" include a list of chars

Error:

Invalid character '{0}' in parameter: {1}.

Action:

• Update the relevant parameter. Make sure it doesn't contain any characters which are
invalid in Windows file names.

Error:

Failed to evaluate '{commandValue}'.

Action:

• Find the relevant command in the process file

• Fix the syntax of the command

Error:

'{prompt key}' prompt value is empty. Prompt value cannot be empty.

Action:

• Find the relevant prompt in the plugin's prompts file

• Set a value to the prompt or remove it

Error:

Not able to detect the exe file name from the spawn command '{command value}'

Action:
 • Locate the command in the process file
• Update the spawn command

Error:

Failure state does not have a command

Action:

• View the logs to identify the Failure state

• Modify the state to include a command

Error:

The expression '{expression}' evaluation failed. Error: {error}

Action:

• Find the relevant expiration in the prompts file

• Fix the syntax of the expiration

Error:

The script '{script}' evaluation failed. Error: {error}

Action:

• Find the relevant script command in the process file

• Fix the syntax of the command

Error:

No failure states were found in the process file. Make sure the plugin contains at least 1 failure
state.

Action:

• Add the missing tags to the user.ini file.

Error:

The CPM Parameters file is missing the PolicyID tag

Action:

• Add the missing tag to the user.ini file.

Error:

Unable to locate the <File Name> file

Action:

• Ensure that all required ini files are in the same folder as the TPC. The required ini files are:
• Process
• Prompts
• User

Error:

Invalid command line argument. Valid action values are logon, verifypass, changegpass,
prereconcilepass, and reconcilepass

Action:

• Run the plugin with one of the supported actions.

Error:

Invalid syntax for fail keyword, value <Line>. Syntax: FAIL (Message,Return code)

Action:

• Fix the relevant line in the Process file. A Fail state must be written in the following way:
• <State Name>=FAIL(<Message>,<Return Code>)

Error:

Prompt definition does not exist. Prompt name: <Prompt Name>. Define the prompt in the prompts
file
Action:

• Add the missing prompt in the prompts file or remove the use of the prompt.

Error:

State definition does not exist. State name: <State Name>. Define the state in the process file's
[States] section

Action:

• Define the state in the process file under the [States] section or remove the use of the state.

Error:

Invalid transition definition: <Transition>. Syntax: State, Condition, State

Action:

• Fix the relevant line in the Process file. A transition must be written in the following way:

<Source State>, <Condition>, <Destination State>

Error:

Invalid command line argument. Syntax: CyberArk.TPC.exe <CPM parameters file> <Action>

Action:

• Correct the command used to invoke TPC.

Error:

Parameter '<Parameter name>' is mandatory but does not exist or has an empty value.

Action:

Add the parameter to the account or the platform.

Error:

Process and Prompts file names cannot be empty. Make sure the 'ProcessFileName' and
'PromptsFileName' parameters contain valid values

Action:

• Ensure that valid values are entered in the ProcessFileName and PromptsFileName
parameters in the platform under Automatic Password Management > Additional Policy
Settings.

Error:

No failure states were found in the process file. Make sure the plugin contains at least one failure
state

Action:

Ensure that the process file contains at least one failure state.

Error:

Did not find any matching prompt for '<Prompt>'

Action:

• The plugin process failed to find a match prompt that was returned from the device.
• Refer to the logs for information on the state on which this occurred.
• Update the plugin to support this type of prompt by adding a new prompt or updating an
existing prompt.

Error:

Invalid syntax for script command, value '<Command>'. Syntax: set <ParameterName>
"<Value>";

Action:

• Fix the relevant line in the Process file. A set command must be written in the following
way:
• set <ParameterName> "<Value>";
Error:

Cannot proceed to next state since none of the conditions were met. Refer to log for more
information

Action:

• The plugin process failed to find a match for the next state.
o Refer to the logs for information on the state and prompton which this occurred.
o Update the plugin to support a FAIL state for this type of prompt.

Error:

Failed to initialize safe-folder-object properties from the CPM parameters file

Action:

• Fix the relevant tag(s) to the user.ini file.

Error:

General error occurred. Refer to log for more information

Action:

• Refer to the logs for more information. If this error continues, contact your CyberArk
representative.

Error:

Invalid syntax for CPM Parameters validation rule 'rule'. Valid values: Yes, No or TCL Expression.
See documentation for TCL Expression examples.

Original message:

Invalid syntax for CPM Parameters Validation rule '<Command>'. Valid values: Yes, No or
(expression)[string equal -nocase "<parameter name>" "<expected value>"]"
Action:

• Fix the relevant line in the Process file. A validation command must be written in the
following way:
o Yes
o No
o (expression)[string equal -nocase "<parameter name>" "<expected value>"]"

Error:

Secret used for user {0} is invalid.

Action:

• The password or key is invalid.

Error:

Expected section <Section Name> is missing from <File Name> file

Action:

• Add the missing section to the relevant file.

Error:

Script variable <Variable Name> was not set. Modify the plugin process file and set the variable

Action:

• Set the missing variable in the Process file.

Error:

Unable to connect to remote machine. Refer to log for more information

Action:

• Check connectivity to the target device.

 • Check the relevant parameters (address, port).
• Refer to the logs for more information.

10 of the Most common TPC issues

Issue: Proper network communications have not be allowed between the CPM and target system
Description: A network device such as a firewall or proxy is blocking the communications between
the CPM and the target system resulting in failure of TPC to run the plugin
Resolution: Enable approciate network communications (https://docs.cyberark.com/Product-
Doc/OnlineHelp/PAS/Latest/en/Content/PAS%20SysReq/Standard%20Ports%20-%20CPM.htm)

Issue: Older version of TPC is being used on CPM

Description: Older versions of TPC may contains bugs or may be missing necessary features for the
desired plugin to operate successfully
Resolution: Update to the latest version of TPC from the Marketplace

Issue: Older version of Credentials Management .NET SDK is being used with a newer version of TPC
Description: TPC relies on functionality built into the Credentials Management .NET SDK. If it is an
older version of Credentials Management .NET SDK is in use, it may be missing methods necessary
for the newer version of TPC
Resolution: Update to the latest version of Credentials Management .NET SDK from the Marketplace

Issue: Unsupported version of .NET framework is installed

Description: As of version 12.0, .NET framework 4.8 is required and TPC will not function with an
older version
Resolution: Update to the supported version of .NET framework

Issue: TPC is executing too quickly and the sends are not reaching the target system
Description: If TPC sends key strokes too quickly on slower network connections or target systems,
some characters may be missed the command lost all together which results in failure of the state
Resolution: Use SendHumanMin and SendHumanMax values to adjust the send speed (See
KB: https://cyberark-customers.force.com/s/article/TPC-SendHuman-commands or https://cyberark-
customers.force.com/s/article/CPM-TPC-SendHumanMin-SendHumanMax-usage)

Issue: TPC fails when server default language is not English

Description: TPC does not know how to parse non-English content
Resolution: Set OS of the CPM server to have English as the default language (See
KB: https://cyberark-customers.force.com/s/article/CPM-TPC-fails-when-server-default-language-is-
not-English)

Issue: TPC exe and dlls are blocked due to being downloaded from the internet
Description: When executable files are downloaded from the internet through a browser, they are
often marked with a "Zone.Identifier" alternate data stream. This prevents them from being loaded
on the operation system until they are "unblocked"
Resolution: Unblock the files by either right-click and going to Properties and selecting "Unblock",
or by using PowerShell and the Unblock-File cmdlet (See KB: https://cyberark-
customers.force.com/s/article/DNA-does-not-work-when-downloaded-from-the-internet)
Issue: TPC fails to spawn executables if one of the properties passed to the spawn command
contains EXE
Description: There is a bug in TPC where it incorrectly evaluates the spawn command if EXE is
contain in one of the passed properties. IE in the username or address
Resolution: Workaround is to use values that do not have exe in them. IE if the problem value is
address, it might be possible to use IP instead (See Bugs 00015883 and 00019041)

Issue: Incompatible Cipher suites or HMAC.

Description: TPC uses the RENCI ssh.net SSH client by default. This client supports certain Cipher
suites and HMACs. If the customer has hardened their target system, they may not have allowed a
compatible configuraton.
Resolution: Enable a compatible set of Cipher suites or HMAC
(See SSH.net reference: https://github.com/sshnet/SSH.NET), or enable UsePlink to use plink at the
SSH client and utilize it's compatible Cipher suites and HMAC (https://docs.cyberark.com/Product-
Doc/OnlineHelp/PAS/Latest/en/Content/SDK/TPC-process.htm#Spawn). We have since developed a
3rd option which allows the customer to utilize Rebex which opens up more supported algorithms.
(https://docs.cyberark.com/PAS/13.2/en/Content/Plugins/Configure-SSH-
features.htm#ConfigureSSHlibrary).

Issue: Signing Certificate expired

Description: In versions 11.3 through 12.2.4 the signing certificate was incorrectly evaluated which
caused failure once the certificate was expired
Resolution: Replace TPC and related files with newly signed versions. (See KB: https://cyberark-
customers.force.com/s/article/CPM-engine-certificate-expiration-notification)

References and Documentation

Terminal Plugin Controller Documentation

https://docs.cyberark.com/PAS/13.2/en/Content/PASIMP/Plug-in-Terminal-Plugin-
Controller.htm?tocpath=Developer%7CCreate%20extensions%7CCreate%20CPM%20plugins%7CTerminal
%20Plugin%20Controller%7C_____0

How can I test logging in using the same SSH client as TPC outside of the TPC process?
https://cyberark-customers.force.com/s/article/CPM-How-can-I-test-logging-in-using-the-same-SSH-
client-as-TPC-outside-of-the-TPC-process

TPC – SendHumanMin \ SendHumanMax usage

https://cyberark-customers.force.com/s/article/CPM-TPC-SendHumanMin-SendHumanMax-usage

CACPM344E - Error: Invalid prompt or did not receive any prompt. State: "StartSessionSSH". code:
7001
https://cyberark-customers.force.com/s/article/CPM-CACPM344E-Error-Invalid-prompt-or-did-not-
receive-any-prompt-State-StartSessionSSH-code-7001-plug-in-cannot-work-with-old-cached-key-The-
server-s-host-key-does-not-match-the-one-PuTTY-has-cached-in-the-registry
Can't change/verify password on UNIX Server - First login - Unable to connect to machine
https://cyberark-customers.force.com/s/article/00002461

Unix Password Management - su: Bad Password

https://cyberark-customers.force.com/s/article/CPM-Unix-Password-Management-su-Bad-Password

TPC Top 10
https://ca-il-confluence.il.cyber-ark.com/display/GS/TPC+Top+10