Application Server failover

Overview

Making sure your PaperCut NG/MF Application ServerAn Application Server is the primary server program responsible for providing the PaperCut user interface, storing data, and providing services to users. PaperCut uses the Application Server to manage user and account information, manage printers, calculate print costs, provide a web browser interface to administrators and end users, and much more. 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 Application Server high availability. It involves setting up multiple copies of your PaperCut NG/MF Application Server so that there can be a seamless transition between them should an outage occur to the active server.

When the network load balancer is configured, the various PaperCut components such as the User ClientThe User Client tool is an add-on that resides on a user's desktop. It allows users to view their current account balance via a popup window, provides users with the opportunity to confirm what they are about to print, allows users to select shared accounts via a popup, if administrators have granted access to this feature, and displays system messages, such as the "low credit" warning message or print policy popups. 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. 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.

Requirements

• PaperCut version 20 or higher

• A Network Load Balancer

• 2+ servers (virtual or physical)

• A highly available external database (RDBMSA Relational database management system (RDBMS) is a program that lets you create, update, and administer a relational database. Most commercial RDBMS's use the Structured Query Language (SQL) to access the database, although SQL was invented after the development of the relational model and is not necessary for its use.)

  • 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 Secondary or Site Servers. These components cannot be hosted on the Application Server when using this solution.

Configure the Application Server(s)

Configure the initial Application Server

1. Install PaperCut 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 ProviderA Print Provider is a monitoring service installed on a secondary print server to allow PaperCut to control and track printers. This monitoring component intercepts the local printing and reports the use back to the primary Application Server. 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 configuration keys if you need 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.

      NOTE

      The PaperCut Application Server service should run under a user account that has read/write access to the new shared network folder.

   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 [MF or NG]/server/data" "\\Server Name\Shared Folder Name"

         TIP

         Creating a directory link is important as it tells the OS to route requests for the data folder to the shared data folder on the mounted drive.

      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.).

   NOTE

   At this stage, we have installed and configured PaperCut NG/MF on the first server. Before continuing with the configuration, we recommend carrying out an end-to-end test of the system you have set up to ensure the Application Server is functioning as expected.

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.

    This makes the recipient of any packet that PaperCut sends respond to the Network Load Balancer rather than the active Application Server that handled the packet.

    

12. Set up the SSL certificate.

    IMPORTANT

    Since multiple hosts will use this certificate, use either a Wildcard certificate or a certificate that supports “Subject Alternative Names”.

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 [MF or NG]/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 : to an =

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

      Example:

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

      TIP

      The Network Load Balancer can use the URL to determine if the server is currently running or not. The active Application Server will reply with a JSON and a HTTP 200 OK response while the passive server will respond with a HTTP 503 (no JSON).

   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).

   NOTE

   This is an important step, as, by default, your Application Server will not accept the traffic from the Network Load Balancer. By configuring Direct Server Return (DSR), this makes sure that packets that arrive will not be rejected or delayed as they pass through the system.

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.

Test

Test that high availability is set up correctly.

Set up system notification for application failures

You can subscribe to App log updates so that if there’s a failover event, you are 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 App Log:

   

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

Configuration keys

Additional configurations

Upgrade Application Servers

Follow the normal upgrade path with some small adjustments: https://www.papercut.com/kb/Main/Upgrading

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.

Print Deploy

If you are using PaperCut Print Deploy, then you will also need to move the folder, which contains all the information about the print queues, on to shared storage. Several files will also need to be copied 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. Navigate to the Print Deploy data folder: [app-path]/providers/print-deploy/[win, linux or mac]/data

   3. Rename the repository folder to repository.bak

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

      • Make available the shared storage you wish to use for Print Deploy to the Application Server. Make sure to save the credentials.

        NOTE

        This shared storage must be a unique location and not be the same as the Application Server(s) shared storage configured previously.

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

        Example for Windows

        mklink /D "C:/Program Files/PaperCut [MF or NG]/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/[win, linux or mac]/data/config

        [app-path]/providers/print-deploy/[win, linux or mac]/data/translations

      • Individual files:

        [app-path]/providers/print-deploy/[win, linux or mac]/data/tls.cer

        [app-path]/providers/print-deploy/[win, linux or mac]/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 PrintWeb Print enables printing from user-owned devices without the need to install printer drivers and manage server authentication. 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 wish 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

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