Using pdfMachine in a Remote Desktop Environment

Read the specific notes when using pdfMachine in a Citrix / Remote Desktop / Terminal Server:


pdfMachine is licensed per user. The same Windows user can use the license on up to 5 devices when logging in as that user. Read the license agreement for specific details.

In a terminal server environment the server and the clients are detected as a single device. This allows a user to use a single license in a terminal server farm across many clients.

Note: Versions prior to 14.61 are licensed per machine, i.e. each machine involved (servers and Citrix / RDP clients), no matter how thin the client, need a separate license.

Installation on Citrix / Remote desktop / Terminal Server

The following notes should be read before installing in a terminal server environment:

(1) Do use the pdfMachine.exe download file to install. Instructions are here.
(2) Don't use the control panel add/remove programs to install.  
(3) Don't use the command:  "change user /install"

If you do either of (2) or (3) above terminal server creates "shadow registry" entries which will overwrite valid pdfMachine registry entries. If this is done, you need to uninstall pdfMachine then manually remove any shadow registry entries from the registry. They are usually located under the registry key:
HKEY_LOCAL_MACHINE\SOFTWARE\ Microsoft\Windows NT\CurrentVersion\Terminal Server\Install\Software\ pdfMachine
Once this is done, reboot, then install pdfMachine by running the pdfMachine.exe program under an admin account.

The process bgsmsnd.exe must be running at user logon time.  Each user will have a copy running.  If you publish applications via terminal server then make sure that you add a line to the logon script that executes bgsmsnd.exe, which is located in the printer driver directory, typically: C:\Windows\System32\spool\ drivers\w32x86\3\bgsmsnd.exe or C:\Windows\System32\spool\ drivers\x64\3\bgsmsnd.exe

User Options:
The first time a user logs on after pdfMachine is installed, registry entries for all pdfMachine options are created in:

HKEY_CURRENT_USER\Software\ pdfMachine 

These are created using sensible defaults and values saved in the "bgsconf.ini" file.  Bgsconf.ini is located in the printer driver directory (e.g. C:\Windows\System32\spool\ drivers\w32x86\3\bgsconf.ini or C:\Windows\System32\spool\ drivers\x64\3\bgsconf.ini) If you manually edit the bgsconf.ini file you can pre-set options that users will end up with.  However, once users have logged on the first time after an install subsequent changes to the contents of the bgsconf.ini file will have no effect.

Note for Windows 7 users:

Make sure you are using version 13.098 or later.
In the advanced options for the pdfMachine printer set the following option : "Print Directly to the printer"

Using pdfMachine on the client side

When using Citrix / Windows Terminal Server / Remote sessions, you can initiate a pdfMachine print and have the client side send email / save / view. To do this :

Version 15.26 and later

The pdfMachine printer will appear as a redirected printer. If you print to the redirected printer you can then send email / save / view on the client side.

Versions earlier than 15.26

NOTE: This setup is only necessary if you don't want the default behaviour where the server side sends email / saves / views.

This requires some manual setup.

Server machine setup:
Setup pdfMachine to print to a pdf file and update a text file in directory(s) on the server.
1. Install pdfMachine
2. On the "Next Action tab", set the "Next Action" to "execute command line" and the "Command Line" to:

cscript.exe c:\touchx.js "%s"

NOTE : See the following FAQ about batch files in "Next Action".

3. Create a script  file (e.g. C:\touchx.js) which updates a file (e.g. c:\tmp\x.txt) in a server directory that clients can access. e.g.

fn = WScript.arguments(0);
	fso = new ActiveXObject("Scripting.FileSystemObject");
	fso.CopyFile(fn, "c:\tmp\x.pdf", true);
	f = fso.CreateTextFile("c:\tmp\x.txt", true);

4. Now when a print is done on the server machine, no user interface is presented, the pdf file c:\tmp\x.pdf is generated, and then the file c:\tmp\x.txt is updated.

Client side setup:
Setup pdfMachine to check the server file periodically. The client side must have a drive mapped which allows access to the directory that the server puts the files into (e.g. x.pdf and x.txt above).

1. Install pdfMachine

2. On the general tab, set "Save Filename action" to "Use the default dir and default save filename" and set the "default directory" and "default filename" to the client side mapping of the path required to access the pdf file (e.g. x.pdf above) on the server.

3. Create a new registry string value called "checkfile" under the key "HKEY_CURRENT_USER\Software\pdfMachine\Broadgun pdfMachine". The last part of the path is the printer name which in this example is the default printer name Broadgun pdfMachine. Set the string registry value to the client side filepath mapping required to access the file on the server. (e.g. \\server\c\x.txt)

4. Either reboot the client PC or stop and restart bgsmsnd.exe (bgsmsnd.exe is usually in c:\windows\system32\spool\drivers\32x86\3)

Now when the server file c:\tmp\x.txt is updated, the client bgsmsnd.exe notices (the checkfile registry val does this) and will load the pdf file on the client.

NOTE: You can choose to have the file automatically emailed by the client by setting the client option "Next Action" to "Launch default email client". If you want encryption with this option, enable it on the server, not the client.

Using Published Applications

If you are using are using the "published application" feature of Citrix or terminal server there are a few things you have to do to get pdfMachine to work.

bgsmsnd.exe is a pdfMachine background process that must be running under the same account as the application that is doing the printing. It is started at install and logon time. It is usually located in the printer driver directory :



You need to configure a start-up script or something that launches bgsmsnd.exe before the published app starts.


You will need to then configure your Citrix or terminal server session to kill bgsmsnd.exe upon exit, otherwise it will hang around. You can do this by running bgsmsnd.exe again with the command line option -exit. e.g. bgsmsnd.exe -exit

In the event of a loss of connection or the user kills the app, bgsmsnd.exe will still be running. On citrix, this can be handled by setting a registry entry, as described:

Note the registry key:

You can also set the maximum amount of time that a disconnected user session is kept active:

Security Settings

When you are logged into a Terminal Server and you connect to a shared printer that is running on another machine the error "You do not have sufficient access to your machine to connect to the selected printer" may be displayed. This is because the "Prevent users from installing printer drivers" option is enabled by default in the local security settings.

On the server running Terminal Services:

(1) Click Start, point to Programs, click Administrative Tools, and then double-click Local Security Policy.
(2) Double-click Local Policies.
(3) Double-click Security Options.
(4) In the right pane, double-click Prevent users from installing printer drivers.
(5) Click Disabled, and then click OK.
(6) Close the Local Security Settings window.

It may then be necessary to reboot the server or to force an immediate policy refresh for the change to take effect.