Tarma Preloader Utilities

David Adams - 2019-09-11 11:02 (updated 2021-02-17 20:16)

TPUtil.exe screen shot

The Tarma Preloader Utilities are a set of programs that convert an executable program to a compressed, self-extracting new program with optional predefined command line arguments, and an optional embedded Administrator password for deployment in locked-down environments.

This allows non-Administrator users to execute the program with Administrator privileges, without the real Administrator having to be present or having to disclose his/her password to start the program.

Note: As of release 7.1.4046, you can also embed non-executable files in the self-extracting program. They will be opened or run with the appropriate Windows shell association on the target system (if available). You can use this to embed, for example, MSI installation packages for deployment with a specific set of credentials.

Obtaining TPUtils
General workflow
TPUtil.exe usage
TPMake.exe usage
TPSet.exe usage
Runtime operation
Examples

Obtaining TPUtils

TPUtils is distributed as an installation package with password protection. To obtain the password for installation, you must buy a license for each developer who uses the package. Distribution of the resulting self-extracting archives is royalty free.

Download TPUtils (version 9.98.0.7663; requires a license and a password to install)
Buy online (TPUtils costs GBP 35 per developer; you will automatically receive the password to install TPUtils)

After downloading, run TPUtils.exe to install the utilities on your system. The Tarma Preloader utilities consist of the following files:

Preloader.exe is a small executable that forms the head of the self-extracting archive. You do not use this program directly.
TPMake.exe is a console program that builds the self-extracting archive. It is documented below.
TPSet.exe is a console program that sets or removes the embedded Adminsitrator password. It is documented below.
TPUtil.exe is a GUI wrapper around the TPMake.exe and TPSet.exe tools. It is documented below.

System requirements: Runs on Windows 2000, XP, Vista, 7, 8, 10, their Server editions 2003, 2008, 2012, 2016, 2019, and later, both 32-bit and 64-bit versions. It does not run on Windows 9x systems or Windows NT4.

General workflow

The general workflow is as follows.

GUI mode

Start TPUtil.exe from its shortcut Tarma Preloader Utilities on the Start > All Programs menu.
Select the path to the original program or document file. You can pack .exe files, .msi files, or any other type of file that has an associated application on the target system.
Optional: Enter command line options to embed, a user name, and a password.
Click the Pack To... button and select the output path.
When the packing process is completed, a new Windows Explorer window will open with the packed executable preselected. This is the executable that you should redistribute.

Command-line mode

Open a command prompt window (Start > Run > cmd.exe, press Enter; or Start > All Programs > Accessories > Command Prompt).
Run TPMake.exe to build the compressed, self-extracting archive.
Optional: Run TPSet.exe to embed the Administrator password for the intended target systems.
Distribute the resulting self-extracting archive.

TPUtil.exe usage

This executable is a simple GUI wrapper that internally calls the TPMake.exe and TPSet.exe tools. It can be used instead of the command line tools if you prefer a graphical user interface.

The TPUtil.exe window contains the following fields and options.

File to embed: Enter the full path to the original file, either an executable program (.exe) or any other file that can be executed/opened by Windows, such as an MSI installation package. You can use the small ... button to the right of this field to browse for the file. This path acts as the input_path for TPMake.exe.
Arguments to embed: Enter the command line arguments that must be embedded in the self-extracting archive, or leave empty for no embedded arguments. This field is equivalent to the /a option of TPMake.exe.
User name to embed: Enter the user name or the domain\username combination to embed in the self-extracting archive. This field is equivalent to the /n option of TPSet.exe.
Password to embed: Enter the password corresponding to the embedded user name, or leave empty to omit the password. If you leave the password field empty, then the user name field is ignored. This field is equivalent to the /p option of TPSet.exe.
Show password: Check this box to display the password in the Password to embed field; clear the box to hide the password. (The password is always encrypted when embedded in the self-extracting archive.)
Preloader options: Use Debug version: Check this box to embed the Debug version of the preloader in the self-extracting archive. The Debug version displays various message boxes with diagnostic information when the self-extracting archive is executed. It is meant for testing and diagnostics only; do not distribute the Debug version. This field is equivalent to the /d option of TPMake.exe.
Preloader options: Do not compress embedded file: Check this box to store the embedded file without compression. For large files, this will save some build time at the expense of a larger package. The runtime performance for non-compressed files is virtually the same as for compressed files, so this option only makes sense if you want to save time during the build process. This field is equivalent to the /n option of TPMake.exe.
Pack To...: Click this button to select the output path for the self-extracting archive. After you have selected the path, the self-extracting archive will be built. When the build is complete, a new Windows Explorer window opens with the output file preselected.
Close: Click this button to close the TPUtil.exe window.
About: Click this button for TPUtil.exe version information.
Help: Click this button to open the current web page.

TPMake.exe usage

TPMake /?
TPMake [/a:"arguments"] [/d] [/n] [/o:[path\]output_name.exe] [path\]input_name.exe

The first form displays a syntax summary and exits. The second form creates a self-extracting archive with optional embedded command line arguments. The following options are supported:

/a:"arguments": Embed the argument list arguments in the self-extracting archive. At runtime, the command line for the embedded executable consists of arguments, followed by a space, followed by any additional arguments that are passed on the command line of the self-extracting archive. You must "quote" the set of arguments to avoid misinterpretation of any '/' or '-' characters inside the arguments list. The maximum allowed length of arguments is 63 characters.
/d: Embed the Debug version of the preloader in the self-extracting archive. The Debug version displays various message boxes with diagnostic information when the self-extracting archive is executed. It is meant for testing and diagnostics only; do not distribute the Debug version.
/n: Do not compress the embedded file. For large files, this will save some build time at the expense of a larger package. The runtime performance for non-compressed files is virtually the same as for compressed files, so this option only makes sense if you want to save time during the build process.
/o:[path\]output_name.exe: Write the resulting self-extracting archive to [path\]output_name.exe. This must specify at least a file name (with a .exe extension), and may contain a full path specification. If this option is not specified, the self-extracting archive is written to [path\]input_name#.exe (i.e., the path and name of the input file, with a hash character '#' appended to the name).

TPMake.exe builds the self-extracting archive as follows:

The Preloader.exe stub is copied to the output path (either [path\]output_name.exe or [path\]input_name#.exe).
The VERSIONINFO from [path\]input_name.exe is copied to the VERSIONINFO of the output file, so the resulting self-extracting archive will carry the same internal product name and version, and other details, as the original executable.
[Optional] If the /a command line option is specified, the given arguments are embedded in the preloader.
The file [path\]input_name.exe is compressed and appended to the preloader stub to form the complete output file.

The resulting self-extracting file is ready to run. For details of its operation, see the section Runtime operation below.

TPSet.exe usage

TPSet /?
TPSet [/n:name] [/p:password] [path\]output_name.exe

The first form displays a syntax summary and exits. The second form modifies the self-extracting archive [path\]output_name.exe. The following options are supported:

/n:name: Embeds an encrypted version of name inside the self-extracting archive. If present, and if a password is also present (see /p option), then this name is used at runtime to run the embedded executable under the named account.

Note: As of release 5.9.3900, the name parameter may contain a domain name as well as a user name. This will attempt to use the domain-relative user account instead of the local user account. To specify a domain name, use the following format:

/n:domain\user
/p:password: Embeds an encrypted version of password inside the self-extracting archive. If present, this password is used at runtime to run the embedded executable under the name account (if the /n option is also used) or the local Administrator account (if the /n option was not used). If you do not specify the /p option, then any existing name and password are removed from the self-extracting archive.

TPSet.exe can be used to prepare an existing self-extracting archive for a new environment for which the Administrator password is known (for example, in a organizational setting where many systems share the same Administrator password).

Runtime operation

At runtime, the self-extracting archive created and modified by TPMake.exe and TPSet.exe can be run as:

output_name.exe [additional command line arguments...]

The preloader stub at the start of the self-extracting archive receives control and then performs the following actions:

The embedded executable is extracted and copied to the Temp folder of the current user, using its original file name. In other words, the executable is stored as %TEMP%\input_name.exe
A new set of command line arguments is prepared that consists of the arguments that were embedded through the TPMake /a option, followed by a space and the arguments, if any, that were passed by the command line that started the current instance of the self-extracting archive. The resulting command to be executed becomes "%TEMP%\input_name.exe" embedded_options additional_options
If a non-empty password was embedded in the self-extracting archive by the TPSet /p option, then:

If an account name was also embedded (with the /n option), then that name is used; else the name of the local Administrator account is retrieved from the system (this will be Administrator on most English Windows systems, but might be something else on non-English systems or if the system administrator intentionally renamed the Administrator account).
Using the embedded or the administrative account name and the decrypted version of the embedded password, the program attempts to log on with those credentials and then starts the embedded executable under that account.

If no password is present, the embedded executable is started normally. This may lead to a Windows UAC elevation prompt if the executable contains an application manifest that requests elevation.
The preloader waits until the embedded program terminates, then deletes the temporary copy %TEMP%\input_name.exe and terminates itself. It returns the exit code from the embedded program.

If an error occurs at any point, the preloader stub terminates prematurely and returns a suitable exit code of its own. The following exit codes are defined:

Value	Description
0	Success
250	Access denied: A password was embedded but could not be used to log on as Administrator.
251	WaitForProcess() failed while waiting for the embedded process to terminate.
252	CreateProcess() failed while trying to start the embedded process
253	(not used)
254	Invalid loader stub
255	General function failure
any other	Exit code from the embedded process

Tip: Under normal circumstances, the preloader does not display any error messages. You can enable the display of preloader error messages by pressing and holding either Shift key when you start the self-extracting archive. The preloader will then display an initial confirmation, after which you can release the Shift key. This option is meant for testing and diagnosis, not for normal usage.

Examples

Here is a usage example:

TPMake /o:Editor.exe "C:\Program Files\PSPad\PSPad.exe"
TPSet /p:magic_words Editor.exe
Editor.exe sample.cpp

In this sample, we create a self-extracting archive called Editor.exe that contains the PSPad.exe program internally. We then set the embedded Administrator password to magic_words, and finally run the self-extracting archive with the command line option sample.cpp

If all goes well, this will extract and start the embedded PSPad.exe program, run it under the local Administrator account, and load the sample.cpp file for editing.

Another usage example:

TPMake /o:Editor.exe "C:\Program Files\PSPad\PSPad.exe"
TPSet /n:RealAdmin /p:magic_words Editor.exe
Editor.exe sample.cpp

This sample is similar to the previous, but embeds the account name RealAdmin inside the self-extracting archive. At runtime, the preloader will try to run the embedded PSPad.exe program under account RealAdmin with password magic_words.

To embed a domain-relative user account name, use TPSet as in the following example:

TPMake /o:Editor.exe "C:\Program Files\PSPad\PSPad.exe"
TPSet /n:OurDomain\MyUserName /p:magic_words Editor.exe
Editor.exe sample.cpp

This will use the user name MyUserName from the domain OurDomain when running the embedded executable.

David Adams's profile and contact details >>