Find your dream job at PaperCut

Choose your language

Choose your login

Contact us

Help Center menu

PRODUCT MANUALS

PaperCut NG & PaperCut MF Manual

PRODUCTS FEATURED

Application Server failover

Making sure your PaperCut NG/MF Application Server is always available is critical to maintaining the uptime of printing within your organization. The list of options to achieve the coveted 99.9% uptime is endless. PaperCut NG/MF fits perfectly with almost all of the industry-standard technologies that help provide high availability.

If you are the type of organization that is already using a network load balancer to make other applications readily available, then these steps will walk you through how you can include your PaperCut NG/MF Application Server as part of this infrastructure to help maintain maximum uptime.

At a high level, this solution utilizes your Network Load Balancer (NLB) to provide the Application Server with high availability. It involves setting up multiple copies of your PaperCut NG/MF Application Server so that there can be a seacmless transition between them should an outage occur to the active server.

When the network load balancer is configured, the various PaperCut NG/MF components such as the User Client or an embedded application on an MFD point to the load balancer. Traffic is then forwarded to the fully operational and active Application Server.

This section describes how to configure Application Server failover with PaperCut NG/MF. There’s a lot to go over, so get yourself some coffee and strap in!

The active/passive methodology

Our solution uses an active/passive methodology rather than a primary/secondary structure. This means that any server that you configure behind the NLB can act as the active server—so make sure all Application Servers are sized appropriately and have equal resources.

In the event of a server failure, the load balancer will seamlessly switch to the next available passive server. When that happens, you’ll need to resolve the problem on the failed server and manually restart it before it can re-enter the rotation as a passive server.

System requirements

  • PaperCut NG/MF version 20 or higher

  • A Network Load Balancer

  • 2+ servers (virtual or physical)

  • A highly available external database (RDBMS)

    • Microsoft SQL Server

    • PostgreSQL

    • MySQL

    • Oracle

  • A persistent network drive accessible by all servers

  • All print queues and PaperCut Mobility Print installations are hosted on PaperCut NG/MF Secondary or Site Servers. These components cannot be hosted on the Application Server when using this solution.

Configure the Application Servers

Configure the first Application Server

  1. Install PaperCut NG/MF and then stop the Application Server service.

  2. Upsize to an external database. Each Application Server must use the same database instance.

  3. Start the Application Server service and confirm that PaperCut NG/MF is fully functioning.

  4. Stop all of the PaperCut services (PaperCut Application Server service, PaperCut Print Provider service, etc.).

  5. Go to [app-path]/server.

  6. Open the server.properties file in a text editor with elevated permissions.

  7. Make the following changes to the file:

    1. Remove the # symbol to uncomment the following lines:

      • high-availability-guard.enabled = Y

      • high-availability-guard.fail-over-internal-secs = 30

      • high-availability-guard.startup-timeout-secs = 300

        Take a look at our configuration keys if you need more details.

    2. Change the high-availability-guard.enabled config option to Y.

    3. Save the file.

  8. Make the data folder common across the Application Servers.

    1. Rename the existing [app-path]/server/data folder to data.bak.

    2. Create a shared folder on a fast, high-performance external drive. For example, on Network Attached Storage.

    3. Copy the contents of data.bak to the new shared folder.

    4. Mount the shared folder onto the Application Server.

      Example for Windows
      1. Mount the new shared folder. Make sure to save the credentials.

      2. Create a symbolic directory link between the data folder path and the new shared folder.

        Example:
        mklink /D "C:/Program Files/PaperCut [NG or MF]/server/data" "\\Server Name\Shared Folder Name"

      Example for Linux and macOS
      Mount the new shared folder directly as the data folder.Example:
      mount -t cifs //ServerName/SharedFolderName -o username=papercut,password=secret,dir_mode=0777,file_mode=0777 /PaperCutInstallationPath/server/data
  9. Start all of the PaperCut services (PaperCut Application Server service, PaperCut Print Provider service, etc.).

  10. Open the Admin web interface and navigate to Options > Advanced > Server Address.

  11. Set the IP address of the NLB to be the advertised IP address for PaperCut NG/MF. This makes the recipient of any packet that PaperCut NG/MF sends a response to the Network Load Balancer rather than the active Application Server that handled the packet.

  1. Set up the SSL certificate.

Configure additional Application Servers

For each additional Application Server that will operate behind the network load balancer, complete the following

  1. Install PaperCut and then stop all of the PaperCut services (PaperCut Application Server service, PaperCut Print Provider service, etc.).

  2. Copy the server.properties and the application.license file from the server you have already set up, and overwrite this file on the current server.

  3. Make the data folder common across the Application Servers.

    1. Rename the existing [app-path]/server/data folder to data.bak.

    2. Mount the shared folder onto the Application Server.

      Example for Windows
      1. Mount the new shared folder. Make sure to save the credentials.

      2. Create a symbolic directory link between the data folder path and the new shared folder.

        Example:
        mklink /D "C:/Program Files/PaperCut [NG or MF]/server/data" "\\Server Name\Shared Folder Name"

      Example for Linux and macOS
      Mount the new shared folder directly as the data folder. Example:
      mount -t cifs //ServerName/SharedFolderName -o username=papercut,password=secret,dir_mode=0777,file_mode=0777 /PaperCutInstallationPath/server/data
  4. Make sure the PaperCut Application Server service is running under a user account that has Read/Write access to the shared network folder you set up earlier.

  5. Start all of the PaperCut services (PaperCut Application Server service, PaperCut Print Provider service, etc.).

  6. Confirm when attempting to access the Admin web interface on your new server that the below message is displayed:

Configure the Network Load Balancer

The Network Load Balancer must be able to do HTTP GET requests to carry out server checks.

  1. Set up a Network Load Balancer so that all incoming connections route to the active Application Server.

    1. Log in to PaperCut NG/MF as an admin and go to Options > Advanced.

    2. In the System Health Monitoring section, copy the HTTP header.

    3. Add it to the end of this URL and change the colon to an equals sign.

      /api/health/application-server/status?disk-threshold-mb=1&

      Example:

      /api/health/application-server/status?disk-threshold-mb=1&Authorization=MAJhuB55LDEm4quGi2XzaogOwqhbUYLm

    4. In the load balancer settings, paste the above URL as the monitoring URL.

    5. If the load balancer allows a monitoring interval, we recommend setting it to 30 seconds. A lower number will unnecessarily increase the load on the Application Server.

  2. Configure the operating system environment to accept forwarded traffic. For most network load balancers on the market, this would be referred to as Direct Server Return (DSR).

  3. Configure all external components (secondary servers, user clients, MFDs, etc.) to point to the virtual service IP address or hostname that has been set up on the Network Load Balancer.

Testing

Perform these tests to ensure high availability is set up correctly. When your testing is complete, remember to return all the servers to their default ready state.

TestHow

Test if the active server is handling traffic.

Attempt to load the PaperCut NG/MF admin web interface using the IP or hostname of the server that you want to test—not the IP/hostname of the NLB. If the server is in an active state, you will see the PaperCut NG/MF login page.

Test if the passive server is ready to pick up the load.

Attempt to load the Admin web interface using the IP or hostname of the server that you want to test—not the IP/hostname of the NLB. If the server is in the passive state, you will see a page that looks like this:

Test if a device is connected via the NLB.

Change the IP/hostname that the device is configured for to be the IP of the NLB and restart the device. If the device connects, the NLB is correctly handling the traffic.

Test if secondary components (user client, secondary server, etc.) are connected to the NLB.

Change the configured IP and restart (same process as above).

Perform a failover.Trigger a failure on the active Application Server and confirm that traffic is routed to and operation continues automatically on another server in the pool. We recommend performing this multiple times for each server in the pool.

Set up system notifications for application failures

You can subscribe to application log updates so that if there’s a failover event, you’re automatically notified.

  1. In the Application Server Options > Notifications tab, under System Notifications, select Error level events and enter the email address of each recipient.

  2. Check the SMTP Server Options are set up so that the server can send out email notifications. If an Application Server fails, you’ll see this message in the Application Log:

  3. We also recommend setting up monitoring and notifications on the Network Load Balancer, so you are aware of any of the servers in the pool become unavailable.

Configuration keys

Configuration KeysDescription
high-availability-guard.enabled

Enable or disable the high availability feature.

The default is disabled.

high-availability-guard.fail-over-interval-secs

The passive server communicates with the active server using the database.

If the passive server does not receive any communication from the active server for a certain period, the active server is deemed inactive.

This config value is the time in seconds that the active server can be inactive before the passive server takes over.

The default value is 30 seconds.

high-availability-guard.startup-timeout-secs

A server will assume the role of an active server on startup if it determines that there are no other servers active. If this active server fails to start correctly, a timeout is in place to trigger a failover if the server isn’t running before the timeout completes.

This config value is the time in seconds that the active server has to reach the fully running state before the failover is triggered.

The default value is 300 seconds.

Additional configurations

Upgrade Application Servers

Follow the normal upgrade path with some small adjustments:

  1. Stop the PaperCut Application Server service on all servers.

  2. Upgrade all servers.

  3. Start the PaperCut Application Server services one at a time.

Cloned VMs

This only applies if you cloned a VM when you created the additional Application Servers. If the same server.uuid file is used on different servers, it can lead to database corruption.

  1. Go to the folder [app-path]/PaperCut MF/server/

  2. Delete the server.uuid file.

  3. Restart the Application Server service on the cloned VM. A new server.uuid file is recreated containing a unique UUID for that VM.

If you are using PaperCut Print Deploy, then you also need to move the folder that contains all the information about the print queues onto shared storage. You’ll also need to copy several files from the first server you created to any additional Application Servers.

  1. On each Application Server perform the following:

    1. Stop the PaperCut Print Deploy Server service.

    2. Open the [app-path]/providers/print-deploy/[os]/data/config/client.conf.toml file in a text editor with elevated permissions.

    3. Add the following configuration parameters to the file:

      Configuration keysDescription
      HighAvailabilityCheckEnabledSet this to true to enable the PaperCut Print Deploy server to follow the high availability status of the PaperCut NG/MF application server on the same host.

      The default is false.
      HighAvailabilityAppServerProbeIntervalInSecsSpecify how often the PaperCut Print Deploy server should query the PaperCut NG/MF Application Server health API URL. The PaperCut Print Deploy server determines the status of the PaperCut NG/MF Application server using the HTTP code of the response.

      The default value is 15 seconds.
    4. Open the [app-path]/providers/print-deploy/[os]/pc-print-deploy.conf file in a text editor with elevated permissions.

    5. Make sure both StartupRandomDelaySecs attributes are set to 0 in both ScheduledTasks and StartupTasks sections. This change is required to make sure auto updates are applied to the both high-availability nodes simultaneously.

      "ScheduledTasks": [
         {
         "Args": [
            "https://update.print-deploy.cloud.papercut.com/client-version/v3/check-update/pc-print-deploy-server-dev/win"
         ],
         "Path": "pc-updater.exe",
         "Schedule": "@daily",
         "StartupRandomDelaySecs": 0,
         "TimeoutSecs": 3600
      }]
      
      "StartupTasks": [
      {
         "Args": [
            "https://update.print-deploy.cloud.papercut.com/client-version/v3/check-update/pc-print-deploy-server-dev/win"
         ],
         "Async": true,
         "Path": "pc-updater.exe",
         "StartupDelaySecs": 0,
         "StartupRandomDelaySecs": 0,
         "TimeoutSecs": 3600
      }]
      
    6. Navigate to the PaperCut Print Deploy data folder: [app-path]/providers/print-deploy/[os]/data

    7. Rename the repository folder to repository.bak

    8. Follow the steps below to make the repository folder common across the Application Servers.

      • Make available the shared storage you want to use for PaperCut Print Deploy to the Application Server. Make sure to save the credentials.
      • Create a symbolic directory link between the repository folder path and the new shared folder.
      Example for Windows

      mklink /D "C:/Program Files/PaperCut [NG or MF]/providers/print-deploy/win/data/repository" "\\Server Name\PaperCutPrintDeployData"

      Example for Linux and macOS

      mount -t cifs //ServerName/SharedFolderName -o username=papercut,password=secret,dir_mode=0777,file_mode=0777 /PaperCutInstallationPath/providers/print-deploy/[linux or mac]/data/repository

  2. From the first Application Server you installed:

    1. Copy and overwrite the following files and folder contents to the same location on all additional Application Servers

      • Folders and all of the contents:

        [app-path]/providers/print-deploy/[os]/data/config

        [app-path]/providers/print-deploy/[os]/data/translations

      • Individual files:

        [app-path]/providers/print-deploy/[os]/data/tls.cer

        [app-path]/providers/print-deploy/[os]/data/tls.pem

    2. Copy the contents of the repository.bak folder to the new repository folder.

  3. On each Application Server perform the following:

    1. Configure the PaperCut Print Deploy Server service to run under a user account with Read/Write access to the shared storage location.

    2. Restart the PaperCut Print Deploy Server service.

Web Print

  1. Copy the web-print-hot-folder used in the configuration for Web Print servers.

  2. Paste it into the same mounted drive you used for the data folder.

  3. Create a similar link to the folder for each server using mklink or the equivalent.

Custom branding

For custom branding to persist across all potential servers, copy the [app-path]/PaperCut [NG or MF]/server/custom folder to each of the Application Servers.

Custom reports

For custom reports to work across all potential servers, the [app-path]/PaperCut [NG or MF]/server/reports folder on each Application Server needs to be moved to shared storage.

  1. On each Application Server perform the following:

    1. Stop the PaperCut Application Server service.

    2. Navigate to the PaperCut NG/MF folder: [app-path]/PaperCut [NG or MF]/server

    3. Rename the reports folder to reports.bak.

    4. Follow the steps below to make the reports folder common across the Application Servers.

      • Make available the shared storage you want to use. Make sure to save the credentials.

      • Create a symbolic directory link between the reports folder path and the new shared folder.

        Example for Windows

        mklink /D "C:/Program Files/PaperCut [MF or NG]/server/reports" "\\Server Name\Shared Folder Name"

        Example for Linux and macOS

        mount -t cifs //ServerName/SharedFolderName -o username=papercut,password=secret,dir_mode=0777,file_mode=0777 /PaperCutInstallationPath/server/reports

  2. From the first Application Server you installed, copy the contents of the reports.bak folder to the new reports folder.

  3. On each Application Server perform the following:

    1. Configure the PaperCut Application Server service to run under a user account with Read/Write access to the shared storage location.

    2. Restart the PaperCut Application Server service.

Custom reports can be created and maintained in the same way they have always been, regardless of which Application server is active.

User Clients

If there’s a failover incident, the user clients need to seamlessly switch over to the new active server. For that to happen, user clients must point to the network load balancer’s IP address. The user client’s configuration is propagated when it’s installed from the server.

In both Application Servers, update the User Client config to point to the network load balancer’s IP address.

  1. Open

    <papercut installation="">\client\win\config.properties</papercut>

    <papercut installation="">.</papercut>

  2. Update the server-ip property to the IP address of the virtual service on the network load balancer.

Comments