Migrating PaperCut to a New Server - when using external database

This article describes how to migrate the PaperCut primary server to a new system, when using an external database (like Microsoft SQL Server or PostgreSQL) hosted on a different machine to PaperCut.

Important: If you are using the internal database, or are also moving the external database to a new machine then you should follow the standard migration process.

Install PaperCut on the new machine

  1. Perform a backup of the PaperCut directory on the old server.
  2. Perform a backup the external database, using the tools available for that database.
  3. Take down PaperCut services on the old server. e.g. Disable the PaperCut Application Server service or manually uninstall PaperCut from the old server. This is important as only one PaperCut primary server must exist on a network and only one instance of PaperCut should connect to the database at any one time.
  4. Download the latest available version available from the PaperCut NG download page. For information on what has changed in recent releases, see the release history page. NOTE: Make sure you are eligible to upgrade to this release by checking our upgrade policy. Past releases can be downloaded here
  5. Run the PaperCut NG setup on the new machine.
  6. Once the setup is complete, you will be requested to run the config wizard. After the installation has ran, complete the configuration wizard and import your users. Although importing the users again is not strictly required - as this data will be overridden later - it does confirm that your new server has the correct network connectivity and also saves your admin password as entered in the wizard.
    TIP: If you have a very large list of users, try importing a small group of users, hence cutting down the import time.
  7. Stop the PaperCut Application Server by running the script [app-path]/server/bin/<platform>/stop-server
  8. Copy the [app-path]/server/server.properties file from the old server to the new server. This file contains your database connection settings, and admin password, etc. If your database connection settings have changed, update the file appropriately.
  9. Copy the [app-path]/server/application.license file from the old server to the new server. This file contains your license information. NOTE: On Mac/Linux ensure proper permissions on the new server: chown papercut:admin server.properties
  10. Start the application server again. PaperCut should connect to the database and start correctly. NOTE: If a database upgrade is required, this may take a while, but you can view the status of the upgrade at http://server:9191/admin. DO NOT STOP/RESTART THE APPLICATION WHEN AN UPGRADE IS IN PROGRESS.
  11. One started check that all data has been migrated across correctly and the system works as expected. It is recommended that perform some testing as described in our post upgrade test plan.
  12. If you had any custom SSL certificates installed: You will have to migrate them manually by copying your custom keystore my-ssl-keystore (or similarly named) from the old [app-path]/server/custom directory to the new one. Also copy the following parameters from the old [app-path]/server/server.properties to the new one: server.ssl.keystore, server.ssl.keystore-password, server.ssl.key-password.
  13. Consider turning off the old server or if running Windows, making the PaperCut services a manual start-up.

Updating user client, release station, site server, and secondary server connection details

If the server’s name and/or IP address is changing then it will be necessary to update these connection details for user clients, site servers, secondary servers, and release stations that connect directly to it.

User clients

If user clients are being run from the share on the PaperCut server, you just need to ensure that the clients are run from the share on the new server.

If clients have been installed locally on workstations, then the connection details need to be edited in the “config.properties” file in the user client install directory.

Site Servers

If you have any site servers, then the server.master.address= setting in the “site-server.properties” file on each of those site servers needs to be updated to point to the new primary server’s network address.

On each site server, start by opening a text editor such as Notepad.

Then open the file:


Locate the line starting with server.master.address= and change the name or IP address to that of the new primary server.

Restart each site server so their new configuration is detected. Alternately, an administrator may choose to manually restart the Site Server service following the same process used to restart an application server.

Secondary Servers

If you have secondary print servers, then the “print-provider.conf” file on these servers need to be updated to point to the new machine’s network address.

Release Stations

For all release stations, the “connection.properties” file located in the release station installation directory must be updated to reflect the machine’s new network address.

Web Print (Simple)

If running a simple Web Print installation on Windows, Web Print will need to be reconfigured on the new server. If the server is not a domain member, you will have to recreate the “webprint” user and reconfigure its access to the Web Print Hot Folder, as well as the PaperCut Web Print service. Review the Web Print Simple Mode setup instructions for further details.

Web Print (Sandbox)

If running Web Print in sandbox mode, check the “webprint” user’s printer and Web Print Hot Folder shares as added on each of the Web Print Servers, as the relevant network paths may have changed. Review the Web Print Sandbox Mode setup instructions for further details.

Secondary Servers (Internet)

If you have secondary Internet servers, then the “connection.properties” file on these servers need to be updated to point to the new machine’s network address.

Other devices

If running PaperCut MF, you may need to reconfigure your MFDs to connect to point to the new machine’s network address.

Migrating a PaperCut Site Server

Migrating a Site Server is a lot simpler than migrating a PaperCut primary Application Server. You don’t need to backup and restore a database, nor do you need to copy across any configuration or license files. It’s best to just install a new site server and associate it with the Application Server, before switching off your pre-existing Site Server. Once setup, the new Site Server will simply copy down all the information it needs from the primary Application Server.

However, if your Site Server has been configured to use an external database of its own, then the original Site Server should be shutdown before the new one is configured to connect to both the external database and the Application Server; this will prevent two separate Site Servers attempting to access the same external database simultaneously. Additionally, it’s very important to note that if the Site Server’s name and/or IP address is changing, then any devices at your site that were configured to directly connect to it will need to be reconfigured with these new connection details.

This will typically be any of the site’s Release Stations and Secondary Servers, which can be reconfigured using the same methods as described above in this article for connecting those components to a new primary Application Server. Similarly, if you’re running PaperCut MF, you may need to reconfigure the site’s MFDs to point to the new Site Server’s network address.

Renaming Printers

If the server’s hostname has changed (or if the installed printer names have changed) then you may like to rename the existing printer entries in PaperCut so that the printing history and settings are maintained. See the article How to Rename a Printer for more details.

Advanced Tips:

  • Set up your printers on the new server and test before installing PaperCut.
  • Consider turning your old server into a PaperCut Secondary Server reporting usage across to your new primary server. This may give you more time to map over workstations that may not be managed via a logon script, etc. You can then decommission the server at a later date.
  • Consider informing your users that jobs currently in a secure hold/release queue will not be transitioned across to the new installation and they should release their jobs prior to the planned outage.

See also:

Categories: How-to Articles, Installing, Uninstalling and Migrating

Keywords: migrate, upgrade, move, moving to a new server, changing servers, transfer