Choose your language

Choose your login

Support

Print scripting, device scripting, and other advanced scripting features

This page applies to:

PaperCut NG/MF version 22.1.1 introduced changes for how to enable and control print scripting, device scripting, and swipe card number conversions. The changes reduced the impact of vulnerabilities that might occur from executing potentially unsafe code.

These features are enabled and configured via security config keys in the security.properties file.

Each script you write can be enabled per printer or device. You can also easily copy scripts to other printers and devices.

Security properties keys - default values

Security.properties keyDefault value
security.print-and-device.script.enabled=N
security.print-script.allow-unsafe-code=N
security.device-script.allow-unsafe-code=N

Location of the keys

The keys are stored in the security.properties file, which is in [app-server]/server for all operating systems.

Enabling Print Scripting and Device Scripting

  1. In any operating system, open the [app-path]/server/security.properties file.

    Windows

    a. In the Start menu, right-click Notepad and select Run as administrator.

    b. From the File menu select Open.

    c. Browse to and open the security.properties file.

    macOS/Linux

    We recommend using sudo or su to open the file in your favorite editor as root.

  2. Find the security.print-and-device.script.enabled=Nconfig key and set it to Y.

  3. Save the security.properties file.

  4. Restart the PaperCut Application Server .

    The Advanced Scripting page is enabled for both print scripts and device scripts. In the admin interface, you’ll find the pages at:

    • Printers > [printer name] > Scripting
    • Devices > [device name] > Scripting
  5. If your scripts contain extended Java classes, perform these additional steps .

Disabling Print Scripting and Device Scripting

To disable print and device scripts:

  1. In any operating system, open the [app-path]/server/security.properties file.

    Windows

    a. In the Start menu, right-click Notepad and select Run as administrator.

    b. From the File menu select Open.

    c. Browse to and open the security.properties file.

    macOS/Linux

    We recommend using sudo or su to open the file in your favorite editor as root.

  2. Set security.print-and-device.script.enabled= to N.

  3. Set security.print-and-device.script.enabled= to N.

  4. Restart the PaperCut Application Server .

Enabling card converter scripts

Card converter scripts are JavaScript code that administrators can enable to perform advanced manipulations of the card number read from a user’s card. PaperCut NG/MF supports multiple built-in methods to convert card numbers to change the format of the card. You can use JavaScript alongside other built-in methods to manipulate card numbers.

To enable JavaScript card conversions:

  1. Create a text file in a folder on the server of your choice, for example, [install-path]/server/custom/card.js.

  2. Edit this file to define a single JavaScript function called convert. It should accept and return a single string. Here’s an example:

    function convert(cardNumber) {

    return cardNumber.substring(3,10).toLowerCase();

    }

  3. Save the file.

  4. Open the [app-path]/server/security.properties file, which is in [app-server]\server for all operating systems.

    Windows

    a. In the Start menu, right-click Notepad and select Run as administrator.

    b. From the File menu select Open.

    c. Browse to and open the security.properties file.

    macOS/Linux

    We recommend using sudo or su to open the file in your favorite editor as root.

  5. Find the security.card-no-converter-script.path-allow-list config key.

  6. At the end of the key, type the full path, or multiple full paths separated by semicolons, to the folder(s) that the JavaScript file(s) you created earlier are saved in.

    • Do not use relative paths.
    • Do not include the name of the executable.

    For Windows paths using backslashes, enter each backslash as a double backslash (\\). Spaces are OK. Always add slashes to the end of the path.

    Examples:

    • Linux: /custom/;/custom/subfolder/;
    • Windows: C:\\folder\\;c:\\apps\\;C:\\\Program Files\My Scripts\\
  7. Save the security.properties file.

  8. In the admin interface, go to Options > Config Editor.

  9. Search for ext-device.card-no-converter.

  10. Type the word javascript: followed by the full path to the JavaScript file you created earlier into the form, for example, javascript:custom/card.js.

  11. If your JavaScript contains extended Java classes, follow the steps in Using extended Java classes in scripts .

  12. Restart the PaperCut Application Server .

Disabling card converter scripts

  1. Open the [app-path]/server/security.properties file, which is in [app-server]\server for all operating systems.

    Windows

    a. In the Start menu, right-click Notepad and select Run as administrator.

    b. From the File menu select Open.

    c. Browse to and open the security.properties file.

    macOS/Linux

    We recommend using sudo or su to open the file in your favorite editor as root.

  2. Find the security.card-no-converter-script.path-allow-list config key.

  3. Delete any paths entered in the config key.

  4. Save the security.properties file.

  5. Go to Options > Config Editor.

  6. Search for ext-device.card-no-converter.

  7. Delete any paths preceded by JavaScript:.

  8. Restart the PaperCut Application Server .

FAQs

What exactly is ‘unsafe code’?
Unsafe code is an extension of print and device scripts that when enabled can allow executables to run on the server. Device Scripting and Print Scripting are powerful and useful features, but their flexibility and power also introduce some security risks. Disabling unsafe code means that the scripting engine keeps scripts isolated from the server operating system, and limits scripts from exceeding the scope of their intended use. **Note:** Prior to PaperCut NG/MF version 22.1.1, ‘unsafe code’ was referred to as ‘sandboxing’.
What happens if I disable scripting by mistake and I have a script enabled on a printer?

If you have a script enabled on a printer, and then you set `security.print-and-device.script.enabled` to N, the Application Server will process the job as though the script doesn’t exist.

Depending on the contents of the script, it could fail in different ways. For example, if a print script triggers a popup with a warning to the user, the popup will no longer appear and the job will be processed as though the script doesn’t exist.

I’m using javascript for card number conversions - will this stop working if I switch off print and device scripting?
No. If you’re using the advanced device key ext-device.card-no-converter to call a script to convert card numbers, this will continue to work successfully, even if you have set security.print-script.allow-unsafe-code to N. See Enabling card converter scripts above.

Comments