Managing the amount of memory used by PaperCut NG/MF

By default, the PaperCut Application Server will use 25% of the host system’s overall memory while running. This configuration allows other installed services to comfortably run on the same system, but is inefficient if you’re running PaperCut NG/MF on a dedicated machine or VM.

How much memory to allocate

Increasing the amount of memory allocated to the application server can improve performance. Conversely, not leaving enough memory for the base OS and other memory usage can cause instability and crashes.

Before adjusting memory allocation, ensure your system is appropriately sized (see the Server Sizing Guide), as an under-resourced system may observe poor performance and instability at the same time.

Overall, the memory allocated to the PaperCut Application Server should:

• be at least 25% of the system memory amount required by the Server Sizing Guide.
  • If a server was sized via the guide to require 12GB of memory, at least 3GB of memory should be allocated to the PaperCut Application Server.
• leave at least 1GB of the system memory free while the Application Server is running.
  • If a server reports 5GB of free memory while the PaperCut Application Server is stopped, at most 4GB of memory should be allocated to the PaperCut Application Server.

When to increase memory allocation

If the Application Server runs out of allocated memory, your memory allocation is too low.
This can be observed in persistent high CPU usage of the pc-app process, or via OutOfMemoryError or GC overhead limit exceeded errors in the UI or logs.

When to decrease allocated memory

If your system runs out of overall memory, your memory allocation is too high.
This can be observed in the system RAM usage being maxed out, or via a malloc , JVM hung or Failed to allocate initial Java heap error in the PaperCut NG/MF service.log or server-out.log files.

Adjusting memory allocation (Windows/Linux)

1. Locate the text file service.conf in the following directory:
   [app-path]/server/custom/
2. Open the file in a text editor and add or modify the additional config lines below.

To adjust the percentage of system memory used by the Application Server, add/modify the following lines:

wrapper.java.additional.6=-XX:MaxRAMPercentage=50
wrapper.java.additional.7=-XX:InitialRAMPercentage=50

This example will configure the Application Server to use 50% of the host system’s overall memory.
For stability, always use the same value for both lines. Reasonable values are between 25 and 75.

Alternatively, to configure the Application Server to use a precise amount of memory, add/modify the following lines:

wrapper.java.additional.6=-Xmx8G
wrapper.java.additional.7=-Xms8G

This example will make the Application Server use exactly 8GB of memory.
For stability, always use the same value for both lines. Reasonable values are between 2G and [free memory at idle - 1]G.

Finally, restart the Application Server.

After the service is restarted, the Application Server log in [app-path]\server\logs\server.log, will show the new memory configuration.

Adjusting memory allocation (macOS)

1. Locate the text file launch-app-server.conf in the following directory:
   [app-path]/server/custom/
2. Open the file in a text editor and add or modify the additional config lines below.

To adjust the percentage of system memory used by the Application Server, add/modify the following line:

export PC_CUSTOM_SERVER_ARG="-XX:InitialRAMPercentage=50 -XX:MaxRAMPercentage=50"

This example will configure the Application Server to use 50% of the host system’s overall memory.
For stability, always use the same value for both arguments. Reasonable values are between 25 and 75.

Alternatively, to configure the Application Server to use a precise amount of memory, add/modify the following line:

export PC_CUSTOM_SERVER_ARG="-Xms8G -Xmx8G"

This example will make the Application Server use exactly 8GB of memory.
For stability, always use the same value for both arguments. Reasonable values are between 2G and [free memory at idle - 1]G.

Finally, restart the Application Server.

After the service is restarted, the Application Server log in [app-path]\server\logs\server.log, will show the new memory configuration.

Enabling Transparent Huge Pages (Linux)

If the Application Server is allocated a large amount of memory (e.g. 32GB), performance may be improved slightly by enabling Linux’s Transparent HugePages (THP) function.

Feel free to consult your distribution’s documentation on THP, but in most cases it can be enabled for applications that request it by running:

echo "madvise" > /sys/kernel/mm/transparent_hugepage/enabled

A restart of the OS/server is then required for this to take effect.

Enabling Large Pages (Windows)

A feature similar to “Transparent Huge Pages” called Large Pages is available for Windows. To use it, the Application Server must have the “Lock pages in memory” group policy permission.

Setting this varies based on system configuration, but it can usually be achieved with the following:

1. Run gpedit.msc
2. Navigate to Computer Configuration -> Windows Settings → Security Settings → Local Policies -> User Rights Assignment
3. Double click Lock pages in memory
4. Click Add User or Group and add the user SYSTEM (or whichever account is configured to run the pc-app process), then press OK
5. Restart the OS/server.

Legacy memory allocation configuration

Older sites may have configured allocations using the method below:

wrapper.java.additional.6=-XX:MaxRAMFraction=3

This method is now deprecated, and you might see an error in the log files: Option MaxRAMFraction was deprecated in version 10.0 and will likely be removed in a future release.

We recommend updating your configuration to the percentage based configuration above.