on the toolbar of the LauncherTree.1. Substitution of named parameters and passwords on launcher execution.
1.1 Example of named parameters and passwords
1.2 Format of named parameters and passwords
1.3 When to use substitution of named parameters and passwords
2. Managing named parameters and passwords
2.1 Which places are scanned for parameters
2.2 When Proxy32 scans launchers for named parameters and passwords
2.3 Global list of named parameters and passwords in memory
2.4 File "proxy-parms.txt"
2.5 Parameter attributes (encryption, persistence, confirmation)
2.6 Dialogs and menu commands to manage named parameters and passwords
2.6.1 Edit
2.6.2 Search
2.6.3 Merge (global and local version)
2.6.4 Tidy
2.6.5 Menu commands to load and save global parameter list
2.6.6 Parameter input dialog
2.6.7 Parameter edit dialog
2.6.8 Proxy TreeNode Edit dialog
2.6.9 Proxy SCRIPT/I-SCRIPT Editor
2.7 Scanning for parameters when AUTOLOGIN mode is used
3. Fixed parameters (configuration info)
4. Positional parameters for SCRIPT and I-SCRIPT files
4.1 format
4.2 where they can be used
4.3 where to supply the value for positional parameter
4.4 how to use named parameter as positional
Lets assume that user double-clicks on the SHELL-TERMINAL launcher that contains following text:
proxycygterm.exe -s '/usr/bin/telnet <PROXYPARM=TELNET server IP address> <PROXYPARM=TELNET server port>'The text between angle brackets (including the angle brackets themselves) will be replaced by the actual value of server IP address and port when such launcher will be executed. The parameter name is contained between equal sign and the right angle bracket and can contain any character string (except angle bracket > itself or strings <PROXYPARM= and <PROXYPASSWORD=). The actual IP address and port will be requested from user on execution of the launcher or Proxy32 will be using predefined value that was supplied by user before and is already stored in Proxy32 memory.
Proxy32 will scan for (and try to replace by substitute values) following tokens in the configuration text fields of the launchers:
<PROXYPARM=parameter name>or
<PROXYPASSWORD=password name>where
parameter nameor
password nameis any character string that does not contain character >.
Angle brackets are part of the token.
Specifically, substrings of launcher configuration text fileds (and in rows of SCRIPT/I-SCRIPT text files) that are matching regular expression is <PROXYPARM=(.+?)> or <PROXYPASSWORD=(.+?)> will be replaced by the string values associated with parameter name or password name accordingly.
Text configuration information that is stored inside of user-created Launchers is mostly static and non-confidential. For the confidential information (that should not be kept in the launchers or in the text of the commands/scripts/plugins) or highly dynamic information (that is changing on every execution of the launcher), or highly reusable information (that causes need to edit multiple launchers when it changes), there is a special solution called substitution of named parameters and passwords:
When Launcher configuration information should contain confidential piece of information (like password) it is recommended to keep it as Proxy32.exe password. This way passwords will be kept in the separate protected storage instead of being visible in the clear text in the COMMANDs/SCRIPTs/PLUGINs.
When Launcher configuration information should contain piece of information that will be changing (user-supplied) on every execution of the Launcher (like name of directory or file to be used as a part of the UNIX ls command) it is recommended to keep it as Proxy32.exe parameter. This way user does not have to edit Launcher before every execution, only supply new value of the parameter in parameter input dialog on execution of the Launcher.
When some piece of information (like Host/Gateway IP address, user name or password) is shared by configuration of many user-created Launchers, instead of repeating the same piece of info verbatim in the configuration of every Launcher it is recommended to keep it as Proxy32.exe parameter or Proxy32.exe password. Then if this piece of info needs to be changed, user needs to edit value of one Proxy32.exe parameter/password instead of editing configuration of dozens of Launchers that may use this piece of information.
In summary, if you have confidential, dynamic or highly re-usable piece of information in the configuration of the Launchers, save this piece of the information as Proxy32.exe password or Proxy32.exe parameter.
Proxy32.exe parameter/password appears in the text of configuration of user-created Launchers and in the text of user-created SCRIPT/I-SCRIPT text files as named tag/placeholder (<PROXYPARM=My UNIX User name>, <PROXYPASSWORD=My UNIX Password>). User can enter the TEXT value associated with every named tag (PROXYPARM and PROXYPASSWORD) via GUI Proxy32.exe Parameter editor. Pairs of strings (Name, Value) for every PROXYPARM or PROXYPASSWORD are stored in the Proxy32.exe parameters memory and, if requested, saved to the parameters file proxy-parms.txt. When user requests execution of the Launcher, all named tags (PROXYPARMs and PROXYPASSWORDs) in the configuration of this Launcher are replaced by their values before Launcher is executed. If named tag has no TEXT value yet assigned, user will receive parameter/password input dialog to supply TEXT values needed to complete substitution before execution of the Launcher.
Proxy32 will scan for named parameters and passwords in following places:
command string in COMMAND launcher
shell command line string in SHELL-TERMINAL launcher
plugin command line string in PLUGIN and I-PLUGIN launcher
application command line string in LAUNCH launcher
URL string in VIEWER launcher
in positional parameters of SCRIPT and I-SCRIPT launcher
in every line in SCRIPT file
in command line part of every line in I-SCRIPT file
There are two possible reasons why Proxy32 would be looking for the named parameters in the configuration text of the launcher:
User has requested the execution of the launcher and proxy32 will have to substitute the values for all named tags (or parameters) in order for the launcher to be executable. Proxy32 presents user with the dialogue to enter parameter values. In that dialogue user can supply the values for all parameters and then press the okay button to confirm substitution and execution of the launcher;
User explicitly asks Proxy32 to scan one particular launcher or the whole subtree of the launchers or the whole tree of the launchers. While doing so Proxy32 will collect all the named parameters and passwords that are contained in the subtree and let the user supply the values and attributes for all those parameters with the help of the special dialogue that is intended to edit parameters.
There is no separate button or menu option that will allow you to create named parameter or password explicitly. Instead, parameter is created at the moment when Proxy32 scans configuration text for the existing launcher, finds parameter and asks user to supply substitution value for this parameter. If user has supplied substitution value for the parameter, this value can be used to execute launcher but it also can be saved for the future (to keep saved value for the next execution of the same or another launcher).
Proxy32 keeps the list of the named parameters and passwords that have already been used during launcher execution. This list is kept in memory ready to use. It is called global parameters list.
When proxy32 finds named parameter or password in the text of the launcher, it will first check if it is already present in the global parameters list in memory. If so, then this parameter already has value previously supplied by the user. Depending of the parameter attributes proxy32 will use previously supplied value without additional confirmation or will present this old value to the user and ask user to confirm or replace this value before execution of the launcher. If found parameter is not present in the global parameters list in memory, then Proxy32 will ask user to supply substitution value for this parameter before executing the launcher. In both cases, if user was supplying, modifying or confirming the value, the parameter is added to global parameter list in memory or this parameter is updated in global parameter list in memory.
If parameter value is changing not very often, it makes sense to save its value when proxy32 will exit. If user configured particular parameter/password as Save on Exit, it will be saved into file proxy-parms.txt in the proxy32 startup directory on proxy32 exit. When proxy32 starts, it will load file proxy-parms.txt from the proxy32 startup directory to create initial global list of named parameters and passwords in memory.
By default, when writing values into disk file, password substitution values are protected by hasing them with built-in constant value. That means that loading this file into instance of proxy32 owned by other user will unhash password substitution values. To prevent another user from loading stolen file proxy-parms.txt, enable "Master password" in proxy32 options dialog. When Master password is enabled, password substitution values in file proxy-parms.txt are protected by hasing them with hash of user's Master password. Master password is not saved anywhere, only hash of Master password is stored in Proxy32 memory while proxy32 is running. So it is harder to compromise Master password.
After user has supplied and confirmed values for the parameters, those values will be saved in the Proxy32 memory (in so-called global parameter list) as the pair of the text strings (name, value) and also several attributes associated with this pair of strings. The name of the parameter cannot be changed, once it is created. Substitution value of the parameter and some of the parameter attributes can be changed after parameter was created.
There are three Boolean attributes for every parameter:
Encryption: Any named parameter (pair of strings (name, substitution-value)) can be either simple parameter or password (depending on whether PROXYPARM or PROXYPASSWORD keyword is used in parameter token). The type of the parameter cannot be changed, once it is created. If this is the PROXYPASSWORD parameter the substitution-value will be labeled as password and if it was PROXYPARM then the substitution-value will be labeled as simple parameter (not password). If substitution-value is labeled as password, then the value will be displayed as the dots/stars in all the dialogues where it can be edited. In addition, the value will be encrypted (hashed) when it is saved to the disk (Save on Exit check mark in parameter editing dialogues). There are two ways to encrypt the password while saving it to disk. With the simple encryption (default mode) password text is hashed with the constant string, so that it will not be readable in the file on the disk. But when using such encryption method anyone can decrypt passwords back by loading password file into Proxy32. There is a safer way to encrypt the passwords when they are being recorded to disk. This method has to be explicitly enabled in Proxy32 Options Dialog. In this method saved passwords are hashed with the user's "Master password" that user will give as a key to protect all other passwords. Master password will never be saved to disk and it is requested from the user only when Proxy32 has to open or save file with all the other passwords. Any other user will not be able to load password file into Proxy32 if he/she doesn't know master password that was used to protect this password file.
Persistence: (Save on Exit check mark in parameter editing dialogues). Whether parameter should be saved to disk when Proxy32 exits. If this attribute is set then this pair of strings (Name, Substitution-value) together with all the attributes will be saved to the text file named proxy-parms.txt when Proxy32 exits. When proxy32 starts it will load all those parameters together with their attributes from the same text file called proxy-parms.txt, so that those parameters will be in memory again (in so-called global parameter list).
Confirmation: (Do not ask again check mark in parameter editing dialogues). Whether Proxy32 should ask user to modify or confirm the value of the parameter every time when it has to be substituted on the launcher execution. If launcher contains many parameters and all those parameters are not labelled as parameters that require confirmation on every use then when executing such a launcher parameter input dialogue will not be given to the user. In such a case all parameters will be substituted with the values that were already saved in the global parameter list. If at least one of the parameters that is contained in the configuration of the launcher is labeled as parameter that requires confirmation on every use then when executing such a launcher user will be receiving parameter input dialogue in which user can confirm or modify values of the substituted parameters before the launcher is actually executed.
In the MenuBar of LauncherTree Window there is a popup menu called Parms. In this menu there is a command called Edit Parms/Passwords memory. This command does following:
Parameter edit dialog and lets user edit parameters in this local listOK then edited local list will update global parameter listCancel then edited local list is discardedThis command is used to edit global parameters list.
In the MenuBar of LauncherTree Window there is a popup menu called Parms.
In this menu there is a command called Search/Filter Parms/Passwords memory.
This command does following:
name-matching parameters and passwords from the global parameter list into local list for editingParameter edit dialog and lets user edit parameters in this local listOK then edited local list will update global parameter listCancel then edited local list is discardedThis command is used to edit particular parameters/passwords in global parameters list.
This command is used frequently, so it has dedicated button on the toolbar of the LauncherTree.
In the MenuBar of LauncherTree Window there is a popup menu called Parms. In this menu there is a command called Edit Parms/Passwords scanned from all TreeNodes and Merge them into Parms/Passwords memory. This command does following:
SCRIPT/I-SCRIPT files on the LauncherTree for named parameters and passwords (PROXYPARM and PROXYPASSWORD)Parameter edit dialog and lets user edit parameters in this local listOK then edited local list will update global parameter listCancel then edited local list is discardedThe same operation can be performed on selected launcher or on SUBTREE of Launchers if user right-clicks on selected launcher or SUBTREE and chooses Edit Parms/Passwords scanned from TreeNode and Merge them into Parms/Passwords memory from the right click popup menu.
This command is used to add scanned (from LauncherTree or SUBTREE) parameters/passwords into global parameters list.
In the MenuBar of LauncherTree Window there is a popup menu called Parms.
In this menu there is a command called Tidy Parms/Passwords memory to match Parms/Passwords scanned from all TreeNodes.
This command does following:
SCRIPT/I-SCRIPT files on the LauncherTree for named parameters and passwords (PROXYPARM and PROXYPASSWORD)Parameter edit dialog and lets user edit parameters in this local listOK then edited local list will replace global parameter list (essentially, removing from memory parameters and passwords that are not in use on current LauncherTree)Cancel then edited local list is discardedThis command is used to replace existing global parameters list in memory by the list of scanned (from LauncherTree) parameters/passwords.
In the MenuBar of LauncherTree Window there is a popup menu called Parms.
In this menu there is a group of following commands to load/save global parameter list to file:
Load named parameters and passwords from the text file into global parameter list. If parameter name is not yet in the global parameter list then add it to global parameter list. If parameter name is in the global parameter list, then update parmeter value and attributes from the file. Password values are decrypted on loading.
Load named parameters and passwords from the text file into global parameter list. If parameter name is not yet in the global parameter list then add it to global parameter list. If parameter name is in the global parameter list, then parmeter value and attributes will not be updated from the file. Password values are decrypted on loading.
Load named parameters and passwords from the text file into global parameter list. If parameter name is not yet in the global parameter list then parameter will not be added to global parameter list. If parameter name is in the global parameter list, then update parameter value and attributes from the file. Password values are decrypted on loading.
Save named parameters and passwords from global parameter list into the text file. Password values are encrypted on saving.
Save named parameters and passwords from global parameter list into the text file. Password values are not encrypted on saving.
Load named parameters and passwords from the text file into global parameter list. If parameter name is not yet in the global parameter list then add it to global parameter list. If parameter name is in the global parameter list, then update parmeter value and attributes from the file. Password values are not decrypted on loading.
Normally, global parameter list is saved to/loaded from particular text file (proxy-parms.txt in the Proxy32 startup directory) on Proxy32 exit/startup. Above command allows to manually load/save global parmeter list in any text file in any directory.
Fig.1. Parameter input dialog
When user has requested execution of the launcher proxy32 checks if this launcher contains substitution parameters. If there is no substitution parameters in the configuration of the launcher, parameter input dialog is not shown.
If there are substitution parameters in the configuration of the launcher Proxy32 checks whether they are all present in global parameter list (have some substitution values already supplied before) and if they all marked as Do not ask again (no need to modify or confirm the substitution values on every substitution). If so, input dialog is not shown and parameters are substituted into the launcher with the values that are stored in the global parameter list. Otherwise, before launcher execution user will receive Parameters input dialog where user can supply new (or modify existing) substitution values for the named parameters and passwords before they will be substituted into the launcher for its execution.
Dialog contains six large buttons on the top.
When user presses OK button, edited parameter values and attributes are saved into the global parameter list (for future use) and then substituted into the launcher for the execution.
When user presses Cancel button, edited parameter values and attributes are discarded and launcher will not be executed.
When user presses Save to file button, list of parmeters from dialog window is saved to the text file. It can be loaded into the dialog by pressing button Update from file. Password substitution values are encrypted on saving and decrypted on loading. Pair of buttons Save to file (no encryption)/Update from file (no decryption) performs the same functions except that password substitution values are saved/loaded in the clear text.
After those top six buttons, dialog contains one row for each named parameter or password that is found in the configuration of the launcher that was requested to be executed.
Each row starts from name of the parameter or password (name is the string that was used in the text of the launcher in PROXYPARM or PROXYPASSWORD tag between equal sign and the closing angle bracket, for example <PROXYPARM=User Name >). Name is not editable.
After parameter name there is a text input field that allows to enter substitution value for the parameter. If parameter is a password, then text that user types into text input field will be shown with dots/stars, so that password value cannot be seen while it is being typed. After text input field each row contains two checkmarks that allows user to set attributes for each parameter.
Save on Exit check mark defines persistence mode: whether parameter should be saved to disk when Proxy32 exits. If this attribute is set then this pair of strings (Parameter Name, Parameter-Substitution-Value) together with all the attributes will be saved to the text file named proxy-parms.txt when Proxy32 exits. When Proxy32 starts it will load all those parameters together with their attributes from the same text file called proxy-parms.txt, so that those parameters will be in memory again (in so-called global parameter list).
Do not ask again check mark defines confirmation mode: whether Proxy32 should ask user to modify or confirm the value of the parameter every time when it has to be substituted on the launcher execution. If launcher contains many parameters and all those parameters are not labelled as parameters that require confirmation on every use then when executing such a launcher parameter input dialogue will not be given to the user. In such a case all parameters will be substituted with the values that were already saved in the global parameter list. If at least one of the parameters that is contained in the configuration of the launcher is labeled as parameter that requires confirmation on every use then when executing such a launcher user will be receiving parameter input dialogue in which user can confirm or modify values of the substituted parameters before the launcher is actually executed.
At the end of each per-parameter row there is a File button. This buttons calls file open dialog to select any file in the disk. When file is selected, its path and anme is inserted into the input text field that contains parameter substitution value. This button is useful when parameter is used to substitute file name and path into the configuration text of the launcher.
Fig.2. Parameter edit dialog
When user has requested to edit susbstitution parameters (see Edit/Search/Merge/Tidy menu commands above), editing is done via Parameters edit dialog.
Dialog contains 4 buttons and 4 checkmarks on the top.
When user presses OK button, edited parameter values and attributes are saved into the global parameter list (for future use).
When user presses Cancel button, edited parameter values and attributes are discarded.
When user presses Save to file button, list of parmeters from dialog window is saved to the text file. It can be loaded into the dialog by pressing button Load from file. Password substitution values are encrypted on saving and decrypted on loading if check mark encrypt/decrypt passwords on save/load is selected. If this check mark is not selected password substitution values are saved/loaded in the clear text.
When loading new parameter list from file into dialog, dialog already contains old parameters list. On the loading from file user can choose: - to clear old list in the dialog before loading new list from file (check mark Clear old list on load), - to add from file parameters that are not in the old list in the dialog (check mark Add new on load), - to update from file parameters that are already present in the old list in the dialog (check mark Update existing on load),
After those 4 buttons and 4 checkmarks, dialog contains table that has one row for each named parameter or password that is contained in the edited list. Depending on the situation, dialog may contain list of named parameters and passwords: - loaded from file, (Load from file) - scanned from LauncherTree (or from subset of LauncherTree) and then updated (values/attributes) from the global parmeter list (Merge/Tidy) - full global parameter list (Edit) - matching subset of the global parmeter list (Search)
First column Parameter/Password Name is the name of the parameter or password (name is the string that was used in the text of the launcher in PROXYPARM or PROXYPASSWORD tag between equal sign and the closing angle bracket, for example <PROXYPARM=User Name>). Name is not editable.
Second column Value is a text input table cell that allows to enter substitution value for the parameter. Double-click inside of the table cell to start editing in it. If parameter is a password, then text that user types into text input cell will be shown with dots/stars, so that password value cannot be seen while it is being typed.
After text input field each row contains two checkmarks that allows user to set attributes for each parameter.
Third column Save on Exit is boolean value (Y/N) that defines persistence mode: whether parameter should be saved to disk when Proxy32 exits. To flip between Y and N double-click on the table cell. If this attribute is set then this pair of strings (Parameter Name, Parameter-Substitution-Value) together with all the attributes will be saved to the text file named proxy-parms.txt when Proxy32 exits. When Proxy32 starts it will load all those parameters together with their attributes from the same text file called proxy-parms.txt, so that those parameters will be in memory again (in so-called global parameter list).
Fourth column Do not ask again is boolean value (Y/N) that defines confirmation mode: whether Proxy32 should ask user to modify or confirm the value of the parameter every time when it has to be substituted on the launcher execution. To flip between Y and N double-click on the table cell. If launcher contains many parameters and all those parameters are not labelled as parameters that require confirmation on every use then when executing such a launcher parameter input dialogue will not be given to the user. In such a case all parameters will be substituted with the values that were already saved in the global parameter list. If at least one of the parameters that is contained in the configuration of the launcher is labeled as parameter that requires confirmation on every use then when executing such a launcher user will be receiving parameter input dialogue in which user can confirm or modify values of the substituted parameters before the launcher is actually executed.
When user double-clicks on TELNET-TERMINAL, COM-PORT-TERMINAL or SHELL-TERMINAL launcher, Proxy32 will check if I-SCRIPT or PLUGIN launcher is located immediately under terminal launcher that is being double-clicked. If so, such I-SCRIPT or PLUGIN launcher is considered to be AUTOLOGIN script and will be executed automatically after the terminal window (created or connected during execution of preceding terminal launcher) is connected successfully. The same logic applies when one uses terminal launcher to re-connect existing terminal window (instead of creating new terminal window).
Terminal launcher and associated with it AUTOLOGIN launcher are executed in one step one after another without delay. If there would be delay, AUTOLOGIN script would miss the messages that server sends to terminal immediately after terminal is connected.
Therefore, Proxy32 scans both launchers for named parameters and passwords before the pair is executed. This way user will receive only one parameter input dialog before executing the launcher pair (terminal launcher and associated AUTOLOGIN launcher) instead of receiving separate parameter input dialogs before execution of each launcher in the pair. Getting parameter input dialog after connecting terminal and before the execution of AUTOLOGIN script would prevent AUTOLOGIN script from receiving the messages that server sends to terminal immediately after terminal is connected. Therefore, for the purposes of parameter substitution, such pair of launchers is behaving as one combined launcher.