PaperCut Hive and Pocket Compatibility Tool

The PaperCut Hive and Pocket Compatibility Tool (also known as the pc-compatibility-tool) is a standalone utility designed to verify network requirements and troubleshoot connectivity issues.

Since PaperCut Hive and Pocket rely on a cloud-native architecture, the network environment must meet specific requirements for reliable operation. This tool helps Administrators validate these requirements before installation or diagnose specific issues in an existing deployment.

When to use the PaperCut Hive and Pocket Compatibility Tool

There are three primary scenarios where using this tool is recommended:

1. Pre-installation checks

Goal: Validate the network before deploying software.

Usage: Run the tool on a representative computer at the organization’s site. It checks if the firewall allows traffic to the PaperCut Cloud and if local ports (9263 and 9264) are open for Edge Mesh communication.

Benefit: Confirms the environment is ready for deployment, which reduces setup time and improves setup success.

2. Troubleshooting client (edge node) connectivity

Goal: Diagnose why a client (edge node) is offline or unable to communicate.

Usage: If a client appears “Offline” in the admin console and the associated device is powered up and online, run the network diagnostics. This can identify if a security update, firewall rule, or web filter (for example, Zscaler) is blocking access to PaperCut’s cloud services.

Benefit: Isolates whether the issue is local to the device or related to the network.

3. Verifying printer communication

Goal: Troubleshoot printer status or toner level reporting issues.

Usage: Run the protocol connectivity diagnostic to verify the client can communicate with the printer via SNMP, RAW Port 9100, and/or IPP.

Benefit: Often reveals if the printer is not ready to print as their correct protocols are not open, for example, RAW Port 9100 is required for printing.

How to use the PaperCut Hive and Pocket Compatibility Tool

The tool is a standalone executable and does not require a PaperCut installation to run.

Prerequisites

• Ensure you have access to the internet, the organization’s LAN or WAN, and the printers you want to test.
• Use a computer running Windows 10 (or higher) or macOS 12 (or higher).
• The tool runs in a Command Prompt on Windows or a Bash shell terminal on macOS.
• Decide which mode you would like to use the tool in:
  • Interactive Mode (Wizard): prompts for information step-by-step.
  • Command line mode: an advanced mode that allows you to run specific diagnostics individually without using the wizard.

How to download and run the PaperCut Hive and Pocket Compatibility Tool

1. Download and extract the .zip file.
2. Open a terminal (macOS) or Command Prompt/PowerShell (Windows).
3. Navigate to the extracted directory and run the appropriate command:
   1. macOS — Interactive Mode: ./pc-compatibility-tool.command -i
   2. macOS — Command line reference: ./pc-compatibility-tool.command [enter command here]
   3. Windows — Interactive Mode: .\pc-compatibility-tool.bat -i
   4. Windows — Command line reference: .\pc-compatibility-tool.bat [enter command here]

How to use the tool in Interactive Mode (Wizard)

For a guided experience, run the tool in Interactive Mode. This launches a text-based wizard that prompts for information step-by-step.

Checks performed by Interactive Mode

When run in Interactive Mode, the tool performs six sequential checks. Press Enter to accept defaults or skip specific sections.

1. Basic System: Checks OS compatibility, version, and disk space.
2. Network Security: Scans for interfering proxies or “man-in-the-middle” inspections.
3. Cloud Connectivity: Tests connection to PaperCut Cloud regions.
4. Edge Node Ports: Checks if Ports 9263, 9264, and 9266 are open on a target IP. These are required for job replication in the Edge Mesh.
5. Printer Connectivity: Pings a target printer’s IP to verify reachability.
6. Protocol Connectivity: Verifies printing protocols (SNMP, RAW Port 9100, and IPP) are active.

Running the tool in command line reference mode (advanced)

You can run specific diagnostics individually without using the wizard. This is useful for scripting or quick checks.

Basic system information

To check the hostname, OS version, and disk space, run:

./pc-compatibility-tool.command basic

Network diagnostics

To verify DNS, and access to Google Cloud, PaperCut APIs, and IoT services, run:

./pc-compatibility-tool.command network cloud

Port checker

To check connectivity to another machine (for example, verifying Port 9264), run:

./pc-compatibility-tool.command network ports <target_ip>

Printer diagnostics

To validate communication with a printer using standard protocols, run:

./pc-compatibility-tool.command printer ping --ip <printer_ip>

Interpreting and troubleshooting Compatibility Tool results

After the Compatibility Tool has run, you will receive results. Here’s how to interpret and troubleshoot them.

Compatibility Tool results: