PaperCut NG 15.0 Print Management User Manual
Below you will find brief information for PaperCut NG 15.0. This user manual outlines how to install, configure, and operate the PaperCut NG print management solution. It covers key concepts like system architecture, user and printer management, shared accounts, reporting, and advanced deployment scenarios, ensuring efficient print usage and cost recovery in various environments.
Advertisement
Advertisement
Version 15.0
User Manual
PaperCut NG 15.0 User Manual
PaperCut NG 15.0 User Manual
Table of Contents
iv
PaperCut NG 15.0 User Manual
v
PaperCut NG 15.0 User Manual
vi
PaperCut NG 15.0 User Manual
7.10.3. What technical considerations do I need to review before implementing Popup
vii
PaperCut NG 15.0 User Manual
viii
PaperCut NG 15.0 User Manual
13.2.6. Override/Change Account Selection during Admin Web Release ............................ 228
ix
PaperCut NG 15.0 User Manual
x
PaperCut NG 15.0 User Manual
xi
PaperCut NG 15.0 User Manual
xii
PaperCut NG 15.0 User Manual
28.3.5. Mac OS X systems using domain authentication via Open Directory ....................... 492
28.3.6. Mac OS X systems using domain authentication via Windows Active Directory ......... 492
28.3.7. Mac OS X laptops (or single user systems) printing to Windows print queues ........... 493
28.3.8. Linux Workstations in a lab environment with printers hosted on a Windows server .... 493
28.3.9. Linux Workstations in a lab environment with printers hosted on Linux CUPS server .. 494
xiii
PaperCut NG 15.0 User Manual
29.3.3. Scenario Three: Multi-user Macs using LDAP or Active Directory authentication ........ 507
A.5.3. Changing the time after which jobs are deleted when awaiting popup response .......... 563
xiv
PaperCut NG 15.0 User Manual
xv
List of Figures
xvi
PaperCut NG 15.0 User Manual
5.31. Tile sample: Organization C0
2
use ........................................................................................ 84
xvii
PaperCut NG 15.0 User Manual
7.31. Searching job log for signature b608c7a39f08643768051217f2f5315a
................................ 149
xviii
PaperCut NG 15.0 User Manual
xix
PaperCut NG 15.0 User Manual
xx
PaperCut NG 15.0 User Manual
xxi
PaperCut NG 15.0 User Manual
xxii
List of Tables
20.2. Job Info Script Reference ( inputs.job
) ............................................................................ 327
20.3. User Info Script Reference ( inputs.user
) ......................................................................... 328
20.4. Client Info Script Reference ( inputs.client
) .................................................................... 328
20.5. Printer Info Script Reference ( inputs.printer
) ................................................................. 329
20.6. Utilities Script Reference ( inputs.utils
) .......................................................................... 330
20.7. Job Actions Script Reference ( actions.job
) ...................................................................... 332
20.8. Client Actions Script Reference ( actions.client
) .............................................................. 335
20.9. Log Actions Script Reference ( actions.log
) ...................................................................... 338
20.10. Utility Actions Script Reference ( actions.utils
) .............................................................. 339
20.11. User Actions Script Reference ( actions.user
) ................................................................. 339
20.12. Printer Actions Script Reference ( actions.printer
) ......................................................... 340
xxiii
PaperCut NG 15.0 User Manual
xxiv
Preface
1. About This Guide
The PaperCut NG User Guide covers the setup, management and configuration of PaperCut NG.
addition, people new to print control may also find the accompanying implementation guide available from the
PaperCut Software website useful in managing the deployment process.
The latest version of this manual in HTML and a printable PDF format are available from the PaperCut Software
International Pty Ltd website at http://www.papercut.com/.
2. Expectations & Prerequisites
PaperCut NG is a network based server application. Experience with basic network concepts such as server administration and network connectivity is expected. Prior to installing or evaluating PaperCut NG you should be familiar with:
• The concept of sharing printers and print servers
• Understanding of client-server relationships
• Understanding of basic security concepts such as permissions, groups and users.
3. Terminology used in this document
To make reading this manual easier, the names of all of the screens, tabs and actions from PaperCut NG are marked up in a different font. The User Details screen for instance.
A sub-screen or tab is indicated with an arrow. User Details
→
Adjustments means: select Adjustments & Charges tab from the User Details screen.
User Interface Buttons are indicated like this: Press OK to continue.
System output and keyboard input is indicated with a different font as well.
Field labels are indicated like this Username.
Important
Important notes are marked like this.
Tip
Tips provide useful advice to make your life easier.
xxv
Preface
Caution
Indicate situations where you have to be careful what you are doing.
Warning
Where extreme care has to be taken.
4. Notice
While every effort has been taken to ensure the accuracy and usefulness of this guide, we cannot be held responsible for the occasional inaccuracy or typographical error. If you do find an error, please let the PaperCut
Software Development Team know.
Information in this document is subject to change without notice. The names of companies, products, people, characters, and data mentioned herein are fictitious and are in no way intended to represent any real individual, company, product, or event, unless otherwise noted. No part of this document may be reproduced or transmitted in any form without the express written permission of PaperCut Software International Pty Ltd.
PaperCut is a trademark of PaperCut Software International Pty Ltd.
(c) Copyright 1999-2015 PaperCut Software International Pty Ltd. All rights reserved.
xxvi
Chapter 1. Introduction
1.1. What is PaperCut NG?
PaperCut NG is a comprehensive print management system designed to seamlessly monitor and control your resources with easy to use administrative and user tools that can be securely accessed from anywhere on the network though a web browser.
Print management requirements vary from organization to organization, and often change dramatically within an organization over time. PaperCut NG is designed for flexibility and scalability and can be configured to meet your print management needs now and in the future. It is used in a wide variety of environments ranging from universities with large printer fleets supporting over 100,000 users to smaller organizations that track printing for a fewer than 50 users on 3 or 4 printers. You can implement a basic system within a few minutes, or if you need more than simple monitoring and reporting, you can configure powerful features that include differential pricing, blocking filters and programmatic control via APIs and scripting. No matter where you start, you can easily adjust parameters to implement changes as gradually or quickly as you wish.
Possible implementations can include:
• Silent activity monitoring
• Visible activity monitoring and expense tracking by work area, projects and departments
• Quota/allowance enforcement
• Charge per-print system
• Combinations of all of the above to accommodate various user / group profiles
In addition PaperCut NG provides system administrators with a kit of tools to manage printers including:
• Detailed logging and reporting
• Notifications for printer errors and low toner
• Job blocking filters and re-direction
1.1.1. Benefits
Some of the key benefits of PaperCut NG are:
• Transfers accountability to users or departments by individually tracking activity.
• Creates environmental awareness by drawing users' attention to the impact of their specific usage.
• Reduces overall printing cost through job filtering, enforcing flexible quotas, or direct cost recovery.
• Discourages overuse of IT resources by establishing a managed print environment.
• Improves efficiency by allowing administrators to create rules that can steer printing to designated printers for load balancing, to implement 'Find Me' printing, or to redirect print jobs based on criteria defined using advanced scripting tools.
• Improves network reliability by implementing rules to prevent printer queue jams, queue hogging, and inappropriate printing types.
• Protect intellectual property and conform to audit objectives by enabling features such as print auditing and digital signatures.
1
Introduction
1.1.2. Key Features
Some of the key features of PaperCut NG are:
• Track all printing activity by user, client account, printer and document metadata.
• Enforce per user quotas, or group account budgets
• Differential print cost/charging allowing costs to be assigned on a per printer basis with advanced options to charge different amounts based on document type (e.g. color, grayscale or duplex), page size, user or group.
• Hardware neutral solution supports all major printer types and operating systems. No hardware vendor lock-in!
• Both cross-platform and multi-platform support. Run a mix of Windows and/or Linux print servers and support clients ranging from Windows, Mac, Linux, Unix and Novell OES.
• User Web Tools allow end-users to track usage, transfer funds, request refunds and upload documents from unauthenticated (wireless) laptops.
• Provides end-users with advanced options to allocate print jobs to shared accounts, cost centers, faculties or departments.
• Single sign-on user authentication with native Active Directory integration or synchronization with LDAP user accounts. (no separate passwords to manage!)
• Flexible hold/release queue support with Release Station software allowing administrators to implement management approved or secure user release printing environments.
• Service Oriented Architecture utilizing the latest software design methods including, test driven development,
XML Web Services and layered architecture. This ensures scalability and stability by design.
• Advanced reporting and charts available in standard formats including PDF, Excel, and HTML. All reports accessible from anywhere on the network via a standard web browser.
• Ability to run on top of leading 3rd party Relational Database Management Systems (RDBMS) including
Microsoft SQL Server, Oracle, MySQL and PostgreSQL Database.
• Enterprise level security and encryption based on SSL.
• Open architecture with a powerful scripting language, source code access and API documentation.
1.1.3. System Requirements
PaperCut NG supports the following server platforms:
• Microsoft Windows Server 2012 R2 (any edition)
• Microsoft Windows Server 2012 (any edition)
• Microsoft Windows Server 2008 R2 (any edition)
• Microsoft Windows Server 2008 (any edition)
• Microsoft Windows 8 (Pro/Enterprise editions)
• Microsoft Windows 7 (any edition except Home editions)
• Microsoft Windows Server 2003 (any edition)
• Microsoft Windows Vista (any edition except Home editions)
• Mac OS X 10.8 - 10.10 (i.e. Lion, Mountain Lion, Mavericks, Yosemite)
• Novell Open Enterprise Server 11 (OES11)
• Most modern Linux operating systems including:
• Red Hat Enterprise Linux (6.0+)
• Novell SuSE Linux (11.0+)
• Ubuntu (10.04+)
• Debian (6.0+)
2
Introduction
• Others supporting GNU glibc 2.11 or higher.
Print queues may be hosted on:
• Any Windows version listed above
• CUPS based print queues on Mac OS X 10.8 and above and Linux
• Novell OES
Servers and clients must use user ID/username based authentication (e.g. Active Directory, Windows NT, LDAP, or local system accounts).
Sites with more than 500 users should consider a server class system with more than 512MB of RAM and 500 MB of free disk space. When using print archiving then at least 100Gb of free disk space is recommended.
servers do not need to run the same operating system or database as the Application Server.
PaperCut NG supports approximately 90% of printers on the market. Where possible we recommend printers that support one of the two major printer language standards - Postscript or PCL. Up-to-date information on printer compatibility is covered on the PaperCut Software website knowledge base at: PaperCut Knowledge Base Printer
Information [http://www.papercut.com/kb/Main/SupportedPrinters]
On workstation clients:
• All supported Microsoft Windows platforms: Windows 8, 7, Vista, XP
• Mac OS X 10.8 or higher recommended
• Most modern Linux and Unix Operating Systems (Java 5.0+ required for optional client tool)
1.2. How does PaperCut NG work?
Before explaining how PaperCut NG works at a technical and end-user level, the reader should be familiar with the following key concepts.
1.2.1. Key Concepts
1.2.1.1. Print Server
A print server is a system responsible for hosting print queues and sharing printer resources to desktop clients/workstations. Users on the workstations submit print jobs to a print server rather then directly to the printer itself. A print server may be a dedicated server but on many networks this server may also perform other tasks such as file serving.
1.2.1.2. Print Queue
A print queue is first-in-first-out queue listing all jobs pending on a given printer.
1.2.1.3. User ID/Username
In a multi-user environment, users log on to a network or computer using a username and password. These are often managed by services such as Active Directory or LDAP. The username is known as the user's identity.
PaperCut NG uses this identity to track printing.
1.2.1.4. Shared Account
A shared account is a PaperCut NG term used to represent an account (pool of funds or allocation group) accessible to multiple users. Accounts usually represent "work areas" and the term can be used interchangeably with terms such as Departments, Faculties, Projects, Clients, Client/Matter, or Cost Centers.
3
Introduction
1.2.1.5. Client/Server Model
Client software is a small program that runs on each workstation and communicates with a server. The printing process on most networks works on a client/server model with clients (workstations) submitting jobs to a server.
PaperCut NG also uses the client/server model in the optional client software to communicate with end-users.
1.2.1.6. Application Server
An application server is a server program responsible for centrally processing “business logic” and providing services to end-users. PaperCut NG uses the application server model to provide a “business logic” unit for calculating user costs and providing a web browser interface to end-users.
1.2.1.7. Information Provider
A provider is a software component or program responsible for providing information to an Application Server.
PaperCut NG uses providers to submit print queue/job information to its application server. This information provider is called the Print Provider. Other important providers included with PaperCut NG include user directory and authentication providers.
1.2.1.8. Web Application Interface
A web application is a software program that interacts with end-users via a web browser. Examples range from
Google, Microsoft SharePoint, Hotmail, Internet banking and router management consoles. PaperCut NG provides a web-based interface for system administration and management. Web applications offer administration flexibility by allowing access from any location on the network and avoid the need for installation of separate software.
1.2.1.9. Scripting Language
A scripting language is a programming language that allows control of one or more software applications. In
PaperCut NG scripting can be used to perform various administrative functions such as modifying parameters for users, shared accounts or printers. It can also be used for programmatic control during the print process to provide functionality such as print job re-direction, user notifications / warnings and confirmation for large or expensive print jobs.
1.2.1.10. Web Print Server
Web print server is the PaperCut terminology for a server that allows laptop (wireless) users to upload Microsoft
Office and PDF files to be printed on network printers from personal computers that are not authenticated to the network and do not have network printer drivers.
1.2.2. Understanding the print process flow
To help explain what PaperCut NG is and how it works we'll introduce the system by example. We'll start with a simple high school example:
The student's perspective (transparent quota control):
1.
Chris is a student at a local high school. He has logged onto the network using his username, chris.j.smith
, and is surfing the Internet. He selects Print from his web browser to print out a web page for his school assignment.
2.
The network administrator has allocated Chris a printing credit budget of $20.00 a month. He can see his current account balance of $10.00 in the PaperCut Client Tool window.
4
Introduction
Figure 1.1. The user client tool
3.
A confirmation screen listing the number of pages and the cost of the print job is displayed on the Workstation.
4.
Chris confirms the print job.
5.
5 pages come out of the printer.
6.
The network administrator has set a cost-per-page inside PaperCut on the printer at $0.10. Chris' 5 page document costs $0.50.
7.
Chris' account balance is now at $9.50. He may continue to print until he submits a print job that has a cost that is higher than the balance in his account.
The teacher's perspective (allocation to accounts):
1.
Matt is an English and Mathematics teacher at the same local high school.
2.
Matt needs to print out a 279 page document for his next class.
3.
The network administrator has configured PaperCut to charge users in the faculty group $.01 per page, and has granted Matt access to charge to his personal account or to the English or math department's shared accounts.
4.
Matt presses the Print button in the application.
5.
The PaperCut client tool displays a popup and presents Matt with information about the print jobs and requests an account selection. In this case accounts represent Departments but could also represent projects or other work areas.
6.
Matt selects the English department's shared account from the list.
5
Introduction
Figure 1.2. The User Client account selection popup
7.
The print job is printed and the English department account is charged $2.79 for the print job.
The technical perspective (behind the scenes):
1.
When the teacher, Matt, prints from his application, his workstation transfers the print job to the server and places it in the print queue.
Figure 1.3. The Windows print queue
2.
The PaperCut Print Provider intercepts the print job in the queue prior to printing, pauses it, and analyzes the information determining: a.
Who printed the document b.
The number of pages in the document c.
Other information such as duplex, grayscale mode, paper size, etc.
3.
The Print Provider submits the job's information to the Application Server to process the “business logic”.
4.
The Application Server determines that Matt needs to select the account to charge. It notifies the Client
Software on Matt's desktop.
5.
The Client Software displays the Popup requesting for the user to select an account.
6.
After Matt selects the account, the Application Server is notified of Matt selection. The “business logic” validates that Matt is authorized to charge to the selected account.
7.
The Application Server charges the appropriate account, logs the job and instructs the Print Provider to resume or unpause the print job in the print queue allowing it to proceed to the printer.
1.2.3. Architecture Overview
PaperCut NG was developed using the latest software development strategies, a strong influence being Service
Oriented Architecture (SOA). The Print Provider, Application Server and Client Software all communicate with one another using XML-based web services over HTTP.
6
Introduction
Figure 1.4. PaperCut NG Architecture - an advanced configuration
A more detailed explanation of the architecture and support for multiple servers, web print servers, server clustering, and payment gateways can be found in subsequent sections of this User Guide.
1.3. The Top-Ten Hidden Features!
Much of PaperCut NG flexibility and usefulness comes not from the features you can see, but from the advanced hidden features. PaperCut NG is packed full of handy tools, utilities and options and you will read about these throughout this guide. To provide a quick overview now, the most popular hidden features are:
1.3.1. One: Zero-install Client Deployment
PaperCut NG is implemented using 100% server-side logic and no client software is required. A simple lightweight client tool is however provided so end-users have access to advanced features such as shared accounts and the option of viewing their account balance in a popup window.
Deploying client software can be a time consuming and fiddly process. To streamline the process PaperCut NG allows its client to be run directly off a network share - no need to install locally, or mess around with deployment tools! Just set the executable as a startup program and it will run and auto-update itself thereafter.
See Section 5.2, “User Client” for more information.
1.3.2. Two: Remote Administration
PaperCut NG is a 100% web based application. Full system administration can be performed from anywhere on the network via a standard web browser - no special admin software is required! To access the administration section, point a browser at the server on port 9191:
7
Introduction http://[server_name]:9191/admin
Encrypted SSL/HTTPS access is also available on port 9192: https://[server_name]:9192/admin
Access is granted to the built-in admin
, or to any user that has been granted administrator level access.
1.3.3. Three: Mobile Printing & BYOD
Mobile Printing & BYOD enables printing from user-owned devices without the overhead of installing printer drivers and managing workstation authentication to the server.
For example in Web Print Microsost Office or Adobe PDF files are uploaded using the same User Web Tools available on network computers. Mobile Printing & BYOD is fully integrated into PaperCut's standard print charging/accounting/quota process. It does not matter if you're a staff user allocating to a faculty or department account, or a student charging to your free print quota, the user account allocation experience the same as that seen when printing from a networked desktop system.
PaperCut's Mobile Printing & BYOD has been widely deployed across education campuses and is an ideal solution for offering print services via student owned laptops, netbooks or hand held devices.
See Section 23.5, “Web Print (Driver-less printing via a web browser)” for more information.
1.3.4. Four: Shared Accounts
Many organizations would like to track their printing on more than a per-user level. With the Shared Accounts feature, users can allocate jobs to cost areas such as Faculties, Departments, Projects, Clients, Cost Centers, or
Pools. Shared accounts are selected via a customizable popup window. Two popup window types are available:
• Standard - A simple account selection window design ideal for most users.
• Advanced - An advanced account selection window designed for the power user including features such as search, preference list, recent selections, comment entry and invoicing options. This is ideal for businesses including Engineering, Law, Accounting and Architecture Firms.
Access to accounts is controlled via integrated network group membership or optionally PIN's.
See Chapter 8, Shared Accounts for more information.
1.3.5. Five: Secondary Servers and Site Servers
PaperCut NG is an enterprise level application designed to be managed and controlled from a central location.
Multi-server environments are common in large organizations and PaperCut NG handles them with ease. All servers are configured to report back to the central Application Server. This ensures that all management, logging and control is centralized. Secondary servers and workstations with local printers simply run a light weight monitoring component that communicates to the central server via XML Web Services calls.
the Application Server is unavailable due to a network outage.
Servers and workstations can run the site server and secondary server software on any supported operating system no matter what operating system is used on the Application Server because PaperCut NG supports mixed or heterogeneous networks as well!
See Chapter 10, Multi-Server and Multi-Site Deployments for more information.
1.3.6. Six: Scripting
Scripting can be applied on a per printer basis to provide programatic control during the print process. Possible
8
Introduction applications include:
• Route the job to the cheapest compatible printer and notify the user of the change (least-cost routing)
• Prompt users to print large color jobs on a compatible low cost grayscale printer
• Charge printing during class time to the department
• Inform user when printer is in error and suggest a compatible alternative
See Chapter 20, Advanced Scripting (Print Scripting) for more information.
1.3.7. Seven: Customizable Web Interface
Did you know that the end-user interface can be quickly customized to make it look like an official part of your organization's infrastructure? With some simple HTML, you can make the PaperCut NG end-user interface look just like your existing web site or intranet site.
See Section 18.3, “Customizing the User web pages” for more information.
1.3.8. Eight: XML Web Services and Command-line Control
It seems like everything these days is Web Services enabled. Not to be outdone, PaperCut NG exposes dozens of
API's via secured XML Web Services. This provides advanced administrators and developers with the ability to programmatically remotely control, integrate and manage the application. The possibilities are endless... some of our users now have their library fines hooked into the PaperCut NG system!
In addition to the Web Services API's, system administrators may hook into the inner workings of PaperCut NG using server commands and scripting.
With server commands you can use batch files or scripts to automate system functions such as:
• Schedule "online" backups to coordinate with your existing backup processes. No need to take the system down to take a data snapshot.
• Create users in PaperCut NG automatically and as part of your existing user creation scripts.
• Automatically import/sync list of accounts from a file, 3rd party system or existing directory structure. (Great for
Engineering and Architecture firms)
information.
1.3.9. Nine: 3rd Party Database Support
PaperCut NG ships with its own preconfigured and self-maintaining database. The system however is database independent and can be run on top of a number of leading database systems. Maybe you have an existing Microsoft
SQL Cluster and would like to take advantages of this infrastructure. No problem! PaperCut NG can be quickly configured to hook into your preferred database.
See Chapter 22, Deployment on an External Database (RDBMS) for more information.
1.3.10. Ten: The Development Team
Software is only as good as the development process. PaperCut NG is developed in an open and transparent fashion by a small development team. Suggestions and feedback are encouraged and source code access is provided to our customers. The team works closely with key system users to architect new features. A member of the development team is online for 8 hours a day and is always happy to chat. Come visit us on our Live Web Chat page!
See the PaperCut Software website http://www.papercut.com/ for more information.
9
Chapter 2. Installation
This chapter covers the initial installation and configuration of PaperCut NG in your network environment. Initial installation takes only a few minutes on a currently configured server. This guide will walk you through installation and configuration step-by-step. The process is summarized below:
1.
System requirements check
2.
Downloading and installing PaperCut NG
3.
Completing the configuration wizard
4.
Testing client software
5.
Testing printing and remote access
PaperCut NG is a cross-platform solution and the installation procedure will vary depending on the target operating system(s). Please jump to the appropriate section below:
•
Windows: Section 2.1, “Installation on Windows”
•
Mac: Section 2.2, “Installation on Apple Mac”
•
Novell: Section 2.3, “Installation on Novell OES Linux (iPrint)”
•
Linux: Section 2.4, “Installation on Linux (CUPS and/or Samba)”
2.1. Installation on Windows
Important
This guide assumes that you are using Windows Server 2008. The process is similar for other
Windows operating systems such as XP, Server 2003 or Windows 7.
If you're upgrading from a previous PaperCut NG version, please refer to the directions outlined in
Appendix F, Upgrading From a Previous Version.
2.1.1. Step 1 - System Requirements & Network Setup
Before installing PaperCut NG for either evaluation or production use, the system administrator should take a few minutes to verify system requirements.
• Is the operating system version supported and patches up-to-date? Take a few minutes to verify the system is
current and supported (see Section 1.1.3, “System Requirements”).
• In workgroup environments (i.e. where no domain is present), some additional configuration may be required.
For more details see Chapter 30, Running in a Workgroup Environment.
• Are printer(s) installed and hosted on this system? PaperCut NG needs to be installed on the system directly hosting the printer(s). The printer should be installed as a "Local Printer" with a connection method such as
TCP/IP Port, LPR, or JetDirect or directly connected to the system via USB or LPT Port.
• In a multi-user environment, printers are often shared with other network users. Other workstations should connect to these printers as "Network Printers". Ensure workstations are configured to print to the shared print queues.
For example a Windows workstation may connect to a printer via a path like:
\\[samba_server]\[printer]
.
• Ensure that printers are configured correctly and work before installing PaperCut NG.
10
Installation
Figure 2.1. Network printer configuration
Important
If you are running the PaperCut NG server on Windows XP (Professional) you must disable "Simple
file sharing". For more information please see Appendix B, Troubleshooting & Technical FAQ's.
If you are running a Windows workgroup network or using Windows XP/Vista Home workstations,
please see Chapter 30, Running in a Workgroup Environment.
2.1.2. Step 2 - Print Queue Configuration
When using release stations or account selection popups, PaperCut pauses jobs on the Windows print queue to hold jobs prior to printing. It is important, especially in charging environments, that the queue is secured to prevent users from resuming jobs themselves and bypassing PaperCut. There are two ways a Windows print queue can be secured:
1.
Configure the queue using the PaperCut TCP/IP Port.
2.
Restrict the print queue security permissions to prevent users from performing management functions.
2.1.2.1. Using the PaperCut TCP/IP Port
Queues configured to use the PaperCut TCP/IP Port will automatically ensure that manually resumed jobs will not be printed. You will already be using a PaperCut TCP/IP Port if you are using hardware page count validation. You can see which port is being used in the Ports tab under Printer Properties. If you are not currently using PaperCut
TCP/IP ports, please see Section 7.12.4.2, “Windows printer queue configuration”.
2.1.2.2. Restricting Windows Print Queue Security Permissions
This method works for most versions of Windows. However it may interfere with printing on Windows 8.1 and
Windows 2012 Server SP2. On these systems you should secure printing using PaperCut TCP/IP ports.
11
Installation
To restrict security permissions for a queue:
1.
Log onto the server hosting the printers as an Administrator.
2.
Open the printer configuration screen: Start
→
Printers
3.
Right-click a printer and select Printer Properties.
4.
Select the Security tab.
5.
Select the CREATOR OWNER user and uncheck the Manage Documents permission. See Figure 2.2,
“Configuring Windows print queue permissions”
6.
Press the OK button.
7.
Perform these steps for each of the monitored printers.
Figure 2.2. Configuring Windows print queue permissions
Tip
A tip from one of our customers Chris, is when using Windows 2008 Server is to use the Server
Manager, navigate to the Print Management Console and globally set the security permissions by right-clicking the Print Server(s)
→
Properties
→
Security and editing the permissions there. Please note that this will only apply to printers added after the global permissions are changed, not for pre-existing printers.
2.1.2.3. Windows Server 2008 R2 only
Windows Server 2008 R2 installations may experience an issue where print jobs are not removed from the print queue when completed. These jobs stay in the queue with a status of 'Sent to Printer'. To work around this you will need to configure the Printer Driver Isolation so that jobs are removed from the queue when completed.
1.
Log onto the server hosting the printers as an Administrator.
2.
Using the Server Manager, navigate to the Print Management Console: Server Manager
→
Roles
→
Print and
Document Services
→
Print Management
→
Print Servers
→
PrintServerName
→
Drivers
3.
Right-click a printer driver and select Set Driver Isolation
→
None.
12
Installation
4.
Perform these steps for each of the monitored printers drivers.
Windows 2008 R2 installations may require hotfix KB2906850 be installed. Please consult with your Microsoft experts regarding the suitability of this hotfix.
Tip
If you receive an "Access denied" error when changing both the CREATOR OWNER permissions and the Print Driver Isolation settings you may need to turn off the Render print jobs on client
computers found under the Sharing Tab for that printer.
Figure 2.3. Configuring Windows print queue client rendering
2.1.3. Step 3 - Download and Install
PaperCut NG is supplied as a standard Windows setup.exe
install program. The latest version may be downloaded from http://www.papercut.com/. This installer automatically detects whether your operating system is 32 or 64-bit and installs a version of the software optimized for your system. After the download is complete, run the setup wizard as an administrator level user. A system restart is usually not required but administrators are advised to perform installation on live production systems during periods of low activity - for example, not during backup operations or other administration activities.
13
Installation
Figure 2.4. Setup wizard
Select the "Standard installation (primary server)" option and install PaperCut NG onto a hard drive with adequate free disk space. The default options will suffice for most systems.
2.1.4. Step 4 - Configuration Wizard
After installation, the install will open a web browser window. The configuration stages are explained below:
2.1.4.1. Administrator Password
This is the master password for the main in-built admin account, and is independent of the operating system or domain passwords. The password will need to meet minimum strength requirements, and must be at least six characters. Ensure that knowledge of this password is kept secure. This screen also sets the system's physical location and language; ensure that these are correct before proceeding.
14
Installation
Figure 2.5. PaperCut NG Configuration wizard
Tip
Treat this password like your router/modem management passwords. It is independent of your domain accounts and needs to be kept secure.
2.1.4.2. Organization Type
This is the organization type which matches the organizational environment where PaperCut NG will be used.
Choosing the appropriate organization type will determine which system defaults are used on setup. For example, in a Professional (Client Billing) organization, where it is useful to charge-back printing to customers, an advanced client popup is provided with additional features useful for dealing with large numbers of client (shared) accounts.
These default settings chosen for an organization type can be changed after installation.
2.1.4.3. Default Print Cost
This is the default cost-per-page assigned to the printers. This setting can be changed on a per-printer basis after installation. Choosing a sensible cost now will help minimize future setup. For example in the USA, a value of $0.05
would be appropriate for many standard black & white printers.
15
Installation
2.1.4.4. Initial User Credit (for Education installations)
When the organization type has been set to Education, users can be assigned an initial starting credit. This ensures they have funds in their account as soon as the system is enabled. An option also exists to control what happens when users run out of credit/quota. If you are evaluating PaperCut NG it might be appropriate not to disable printing when a users funds run out. This way you can be assured that user printing is not disrupted during the evaluation.
These settings may be changed after setup.
2.1.4.5. User/Group Synchronization
PaperCut NG extracts user information out of the System or Domain. The options presented here will vary depending on the Operating System and its environment. During evaluation, most sites will opt to import all users from the system/domain into PaperCut NG. An option also exists to import a subset of users from a given group.
This option is pertinent when it is known that only a subset of users will only ever use the printers.
Figure 2.6. User sync configuration wizard page
Options on Microsoft Windows include Windows Standard, Active Directory, or LDAP. In a domain enviroment,
Active Directory is the default option as this offers access to Organization Units, Nested Groups and other AD features.
Use the Test Settings to test and confirm your settings before continuing.
2.1.4.6. Client Settings in Professional (Client Billing) installations
In a Professional (Client Billing) environment, the main focus is on allowing users to allocate print jobs to client
(shared) accounts. The process works by:
• Pausing all jobs that enter the print queues.
• Displaying a popup on the user's workstation asking them to allocate the print job to an account. This is done by selecting the account from a list.
• After the user has responded to the popup, the job is released to the printer.
The account selection popup option is enabled at the user level. Once the option is enabled, the user must run the client software. If the client software is not running, the popup cannot display, and the job will remain paused in the print queue. This option is hence considered high impact. You are presented with two strategies that allow you to choose the implementation approach that best suits your needs:
2.1.4.6.1. Minimal impact (Initial single user testing)
In this strategy the account popup is only initially enabled on a single user for testing. You need to nominate the testing account; this may be an existing system/domain account used for testing purposes or even your own user
16
Installation account. The username should be in the format used to log into the domain/system (usually the short form).
The minimal impact strategy will allow you to test the popup with the nominated test system/domain user account, after which the Advanced Account Selection Popup option can be enabled for other users as appropriate.
2.1.4.6.2. Immediate implementation (Enable for all users)
This strategy enables the account selection popup on all users, and is often preferred for smaller networks as it minimizes the required post-install configuration. Once the client has been deployed, the system will be operational.
If this option is selected, you should be prepared for installation of the client software to user desktops (see Step 7) immediately to prevent disruption of user printing services.
If in doubt, select the minimal impact strategy. This will ensure the impact is isolated to only the nominated test account.
2.1.4.7. Verify Setup Options
Prior to enabling the configuration options that you have selected, you will have the chance to verify setup options.
At this stage you are still able to return to any of the prior configuration screens to alter options before clicking
Finish.
2.1.4.8. Wizard Completion
After completing the configuration wizard you will be presented with a user synchronization status screen, showing the progress and results of the system completing its initial setup. Once you have closed that, click Login to access the interface and begin familiarising yourself with the options and features available. Take some time to explore, and refer back to the relevant sections of this manual as required.
2.1.5. Step 5 - Printer Configuration
The printers should be automatically detected, and listed under the Printers section. If the printers do not display, try printing a document as the first job will trigger registration.
2.1.6. Step 6 - Sharing Client Software
The PaperCut NG client software is located in the directory
[app-path]/client
. This software needs to be shared over the network so workstations can access/install the client application. The directory is automatically shared in read-only form as
PCClient as part of the install process. Confirm that you can access the client software via the network by browsing to
\\server\PCClient
.
2.1.7. Step 7 - Client Software Deployment (Optional)
The PaperCut client software may now be deployed if required. The client software is not required for basic print tracking and reporting. Some features the client software provides include:
• Displays notification messages, such as why a print job was denied.
• Displays print policy popups, such as to encourage duplex printing.
• Displays popups for shared account allocation/charging (department accounts, client billing).
• Allow the user to confirm the details and/or cost of their print job before printing.
• Shows the user their current balance (useful in schools where print quotas are used).
• Can be used for authentication when printing from public terminals or other unauthenticated systems.
For a professional (client billing) installation the client software is required so that users can allocate print jobs to
For other installation types the client software is optional. If you choose not to deploy the client software you may
17
Installation still choose to deploy it in the future.
software see Section 5.2.1, “User Client Deployment”.
2.1.8. Step 8 - Testing
Following a fresh installation, it is highly recommended to test core features of the system. For further details please
see Section 2.5, “Testing the Installation”.
2.1.9. What Next?
This concludes the Install Guide. You may like to take some time to explore the features of PaperCut NG before
Client”.
2.2. Installation on Apple Mac
Important
This guide assumes that you are installing on Mac OS X (either server or workstation) hosting and sharing printers. This guide will refer to this system as the 'server'. This represents the role of the system rather than the 'edition' of the operating system. PaperCut NG equally supports both the server and workstation versions of Mac OS. If you're upgrading from a previous PaperCut NG version please
refer to the directions outlined in Appendix F, Upgrading From a Previous Version.
The following section assumes the reader has knowledge of general Mac OS X server management.
Although the installation process is graphical, it would be an advantage to have knowledge of the command-line, creating users, editing configuration files and an understanding file permissions.
2.2.1. Step 1 - System Requirements
Before proceeding with the installation the system administrator should take a few moments to verify system requirements. Is the operating system version supported and are patches up-to-date? Take a few minutes to verify
the system is current and supported (see Section 1.1.3, “System Requirements”).
2.2.2. Step 2 - Print Queue Setup
Most small to medium Mac networks will have their workstations configured to print directly to the physical printers.
This method of printing is not supported by PaperCut NG and instead administrators will need to set up global server hosted print queues. Some administrators will be familiar with server queues, while others will need to invest some time into understanding Mac printing in more detail. The topic of Mac printing is complex and is hence
organization's printers are set up as required.
Administrators should ensure that the server based print queues are set up and working as expected before attempting to install PaperCut NG.
2.2.3. Step 3 - Download and install
PaperCut NG is supplied as a standard disk image containing the installer. Log on as an admin level account.
Download and double-click Mac installer. Double-click on the installer package named
PaperCut NG Standard
Installation.pkg
. Follow the directions on the screen. The installation process will take between two and five minutes depending on the speed of the system. A system restart is not required but administrators are advised to perform installation on live production systems during periods of low activity - for example, not during backup operations or other administration activities.
18
Installation
The default install location is
/Applications/PaperCut NG
Important
Make sure you're installing the correct package. The similarly named
PaperCut NG Secondary
Server Installation.pkg
only installs part of the application and is designed for more advanced networks.
Figure 2.7. The Mac installer
2.2.4. Step 4 - Configuration Wizard
After installation, the install will open a web browser window. The configuration stages are explained below:
2.2.4.1. Administrator Password
This is the master password for the main in-built admin account, and is independent of the operating system or domain passwords. The password will need to meet minimum strength requirements, and must be at least six characters. Ensure that knowledge of this password is kept secure. This screen also sets the system's physical location and language; ensure that these are correct before proceeding.
19
Installation
Figure 2.8. PaperCut NG Configuration wizard
Tip
Treat this password like your router/modem management passwords. It is independent of your domain accounts and needs to be kept secure.
2.2.4.2. Organization Type
This is the organization type which matches the organizational environment where PaperCut NG will be used.
Choosing the appropriate organization type will determine which system defaults are used on setup. For example, in a Professional (Client Billing) organization, where it is useful to charge-back printing to customers, an advanced client popup is provided with additional features useful for dealing with large numbers of client (shared) accounts.
These default settings chosen for an organization type can be changed after installation.
2.2.4.3. Default Print Cost
This is the default cost-per-page assigned to the printers. This setting can be changed on a per printer basis after installation. Choosing a sensible cost now will help minimize future setup. For example in the USA, a value of $0.05
would be appropriate for many standard black & white printers.
2.2.4.4. Initial User Credit (for Education sites)
20
Installation
When the organization type has been set to Education, users can be assigned an initial starting credit. This ensures they have funds in their account as soon as the system is enabled. An option also exists to control what happens when users run out of credit/quota. If you are evaluating PaperCut NG it might be appropriate not to disable printing when a users funds run out. This way you can be assured that user printing is not disrupted during the evaluation.
These settings may be changed after setup.
2.2.4.5. User/Group Synchronization
PaperCut NG extracts user information out of the System or Domain. The options presented here will vary depending on the Operating System and its environment. During evaluation, most sites will opt to import all users from the system/domain into PaperCut NG. An option also exists to import a subset of users from a given group.
This option is pertinent when it is known that only a subset of users will only ever use the printers.
Figure 2.9. User sync configuration wizard page
Options include Mac Standard (PAM, Local NetInfo, etc.), LDAP (Open Directory), or Samba. Select Mac
Standard if the user accounts are setup and defined on the local system. This option will work with most Mac networks.
The LDAP option is appropriate for large networks with existing Open Directory domains. This includes networks running Mac OS X Server with Open Directory, and Windows domains running Active Directory. PaperCut NG will do it's best to auto discover LDAP settings, but some knowledge of LDAP and/or Open Directory will be required.
More information on LDAP is available in Section 15.3.8, “Using LDAP for user synchronization”.
Use the Test Settings to test and confirm your settings before continuing.
2.2.4.6. Client Settings in Professional (Client Billing) installations
In a Professional (Client Billing) environment, the main focus is on allowing users to allocate print jobs to client
(shared) accounts. The process works by:
• Pausing all jobs that enter the print queues.
• Displaying a popup on the user's workstation asking them to allocate the print job to an account. This is done by selecting the account from a list.
• After the user has responded to the popup, the job is released to the printer.
The account selection popup option is enabled at the user level. Once the option is enabled, the user must run the client software. If the client software is not running, the popup cannot display, and the job will remain paused in the print queue. This option is hence considered high impact. You are presented with two strategies that allow you to choose the implementation approach that best suits your needs:
2.2.4.6.1. Minimal impact (Initial single user testing)
21
Installation
In this strategy the account popup is only initially enabled on a single user for testing. You need to nominate the testing account; this may be an existing system/domain account used for testing purposes or even your own user account. The username should be in the format used to log into the domain/system (usually the short form).
The minimal impact strategy will allow you to test the popup with the nominated test system/domain user account, after which the Advanced Account Selection Popup option can be enabled for other users as appropriate.
2.2.4.6.2. Immediate implementation (Enable for all users)
This strategy enables the account selection popup on all users, and is often preferred for smaller networks as it minimizes the required post-install configuration. Once the client has been deployed, the system will be operational.
If this option is selected, you should be prepared for installation of the client software to user desktops (see Step 7) immediately to prevent disruption of user printing services.
If in doubt, select the minimal impact strategy. This will ensure the impact is isolated to only the nominated test account.
2.2.4.7. Verify Setup Options
Prior to enabling the configuration options that you have selected, you will have the chance to verify setup options.
At this stage you are still able to return to any of the prior configuration screens to alter options before clicking
Finish.
2.2.4.8. Wizard Completion
After completing the configuration wizard you will be presented with a user synchronization status screen, showing the progress and results of the system completing its initial setup. Once you have closed that, click Login to access the interface and begin familiarising yourself with the options and features available. Take some time to explore, and refer back to the relevant sections of this manual as required.
2.2.5. Step 5 - Printer Configuration
To configure which printers are monitored by PaperCut you should run the
Control Printer
Monitoring.command
script as described in in the section Monitoring Printers on the Mac, and return to this
section when complete.
The monitored printers should be listed under the Printers section. If the printers do not display, try printing a document as the first job will trigger registration.
2.2.6. Step 6 - Sharing Client Software
The PaperCut NG client software is located in the directory
/Applications/PaperCut NG/client
. It may be useful to share this directory over the network so workstations can access/install the client application. If you're running Mac OS X Server, use Server Admin to add a read-only file share called
PCClient
. Sharing with
Protocols AFP for Mac clients, and SMB for Windows clients is recommended.
Users can have the client software start automatically using the OS X "Open at Login" feature. Manually start the
PaperCut NG client software, command Click on the dock icon, select "options" and the Open at Login" from the small pop up menu.
2.2.7. Step 7 - Testing
Following a fresh installation, it is highly recommended to test core features of the system. For further details please
see Section 2.5, “Testing the Installation”.
2.2.8. Step 8 - Deployment for a Professional (Client Billing) Installation
NOTE: This step is a requirement for a Professional (Client Billing) installation.
Now that the system is tested and working, it is time to deploy the client software and enable the account popup for their use. It is important to deploy the client software before enabling the popup, otherwise users' printing will be stopped/paused.
22
Installation
2.2.8.1. Deploy the client software
As discussed earlier in the chapter the client can be run directly from a network share (which is automatically configured on Windows). There is also the option to install the software locally on each workstation, however this is not usually recommended because it makes the process of updating the client software more complicated.
those instructions to deploy the client software, and then enable the popup as described below.
2.2.8.2. Enable the advanced client popup
Once the client software is deployed on user workstations, the Account Selection can be set. In a Professional
(Client Billing) configuration, all users that print jobs for clients are often given the Advanced account selection popup, however, other Account Selection options may be better suited for some users based on their job function.
The popup can be enabled on one user at a time or can be updated for all users in bulk. The user details page can be used to enable the popup for a single user. To enable the popup for all users in bulk:
1.
Log into the admin interface.
2.
Under the Users section, select the Bulk user actions... action from the menu at the top left of the Users tab.
3.
Select the target group. To enable for all users select the
[All Users] group.
4.
In the Change account selection setting section, enable the Change account selection option.
5.
Select the Show the advanced account selection popup option from the list.
6.
If you do not want to allow users to charge printing to their personal account, then disable the Allow user to
charge to their personal account option.
7.
Press the OK button, and confirm the operation. Once completed, the selected users will have the account popup enabled.
Once the popup has been enabled on all users some testing should be performed from users' desktops. To test, login to the user workstation, perform a print, and check that the account popup appears and the job is logged as expected.
2.2.9. What next?
This concludes the Install Guide. You may like to take some time to explore the features of PaperCut NG before
Client”.
2.3. Installation on Novell OES Linux (iPrint)
Important
The following section assumes the reader has knowledge of general Novell OES Linux system management including using the command-line, creating users, editing configuration files and understanding file permissions.
2.3.1. Step 1 - System Requirements & Printer Setup
Before proceeding with the installation the system administrator should take a few moments to verify system requirements. Is the operating system version supported and are patches up-to-date? Take a few minutes to verify
integrate with iPrint on Novell OES Linux. If your printers are currently hosted on iPrint on a Netware server or even under legacy NDPS, you will first need to migrate your queues over to a OES Linux based server. Ensure your printing is correctly working under iPrint on OES Linux before continuing to the next step.
23
Installation
Important: iPrint and the print queues must be configured and confirmed to work before progressing to step 2.
2.3.2. Step 2 - Create the host user account and firewall settings
PaperCut NG runs and installs under a non-privileged user account called "papercut". The papercut user's home directory location is the application install location.
/home/papercut is recommended, however Administrators may consider alternate install locations depending on personal preference. Alternatives may include:
•
/usr/local/papercut
•
/opt/papercut
The host user account is not an eDirectory account but a local system account. One way to create the "papercut" account on OES Linux is:
1.
Open YaST Control Panel and select User Management under Security and Users.
2.
Click Add to create a new user.
3.
On the User Data tab, enter a username of papercut and assign a secret password.
Figure 2.10. Creating the host user account - part 1
4.
On the Details tab, select
Empty Home with permissions
755 and change the
Home Directory path to define an alternate install location.
24
Installation
Figure 2.11. Creating the host user account - part 2
5.
Create the account by clicking the Accept button.
Important
This quick start guide assumes the install location is
/home/papercut
. If an alternate home location is defined, some of the paths listed in subsequent sections will require modification.
A default OES Linux installation imposes strict resource usage limits on user accounts ( ulimit
). The papercut account is a special account used for hosting an application and hence should be granted satisfactory resource limits such as the ability to open many files. Larger sites should consider adding the following line to
/etc/security/limits.conf
: papercut nofile 65535
Novell OES Linux has a strict default firewall policy. PaperCut NG uses ports 9191 (for HTTP) and ports 9192 (for
HTTPS/SSL) and these ports must be open. To open these ports:
1.
Open YaST Control Panel and select Firewall under Security and Users.
2.
Select Allowed Services, then click the Advanced... button.
3.
Add ports
9191 and
9192 to the TCP Ports list (separated by spaces).
4.
Click OK, Next, then Accept to apply the changes.
25
Installation
2.3.3. Step 3 - Download and installing
PaperCut NG is supplied as a self-extracting and self-installing archive. The installation is performed under the rights of the newly created papercut account and temporary root access will be required. Please have the root password handy. (Administrators who are after a detailed explanation of the install process should also consult the
background information in Chapter 27, PaperCut NG on Linux).
Log on as the newly created papercut user and download and execute the installer from the command prompt.
Here is an example using wget to fetch the installer: shell> su - papercut shell> wget [download url from PaperCut Software website] shell> sh ./pcng-setup-novell-oes-linux.sh
Follow the installation instructions and enter the root password when requested.
Important
Ensure you login as the user papercut so that the user's environment is sourced and the home directory (install location) is correctly defined.
Figure 2.12. The Novell OES Linux install process
The installation process will take between two and five minutes depending on the speed of the system. A system restart is not required but administrators are advised to perform installation on live production systems during periods of low activity - for example, not during backup operations or other administration activities.
2.3.4. Step 4 - Configuration Wizard
After installation, you will be prompted to open a web browser at http://[server-name]:9191/admin to complete configuration. The configuration stages are explained below:
2.3.4.1. Administrator Password
This is the master password for the main in-built admin account, and is independent of the operating system or domain passwords. The password will need to meet minimum strength requirements, and must be at least six
26
Installation characters. Ensure that knowledge of this password is kept secure. This screen also sets the system's physical location and language; ensure that these are correct before proceeding.
Figure 2.13. PaperCut NG Configuration wizard
Tip
Treat this password like your router/modem management passwords. It is independent of your domain accounts and needs to be kept secure.
2.3.4.2. Organization Type
This is the organization type which matches the organizational environment where PaperCut NG will be used.
Choosing the appropriate organization type will determine which system defaults are used on setup. For example, in a Professional (Client Billing) organization, where it is useful to charge-back printing to customers, an advanced client popup is provided with additional features useful for dealing with large numbers of client (shared) accounts.
These default settings chosen for an organization type can be changed after installation.
2.3.4.3. Default Print Cost
This is the default cost-per-page assigned to the printers. This setting can be changed on a per printer basis after installation. Choosing a sensible cost now will help minimize future setup. For example in the USA, a value of $0.05
would be appropriate for many standard black & white printers.
27
Installation
2.3.4.4. Initial User Credit (for Education installations)
When the organization type has been set to Education, users can be assigned an initial starting credit. This ensures they have funds in their account as soon as the system is enabled. An option also exists to control what happens when users run out of credit/quota. If you are evaluating PaperCut NG it might be appropriate not to disable printing when a users funds run out. This way you can be assured that user printing is not disrupted during the evaluation.
These settings may be changed after setup.
2.3.4.5. User/Group Synchronization
PaperCut NG extracts user information out of the System or Domain. The options presented here will vary depending on the Operating System and its environment. During evaluation, most sites will opt to import all users from the system/domain into PaperCut NG. An option also exists to import a subset of users from a given group.
This option is pertinent when it is known that only a subset of users will only ever use the printers.
Figure 2.14. eDirectory/LDAP configuration wizard page
PaperCut NG has native support for eDirectory LDAP schemas. This will be the default user import option for most sites. PaperCut NG will do it's best to auto-discover LDAP settings, but some knowledge of eDirectory and/or LDAP
2.3.4.6. Client Settings in Professional (Client Billing) installations
In a Professional (Client Billing) environment, the main focus is on allowing users to allocate print jobs to client
(shared) ccounts. The process works by:
• Pausing all jobs that enter the print queues.
• Displaying a popup on the user's workstation asking them to allocate the print job to an account. This is done by selecting the account from a list.
• After the user has responded to the popup, the job is released to the printer.
The account selection popup option is enabled at the user level. Once the option is enabled, the user must run the client software. If the client software is not running, the popup cannot display, and the job will remain paused in the
28
Installation print queue. This option is hence considered high impact. You are presented with two strategies that allow you to choose the implementation approach that best suits your needs:
2.3.4.6.1. Minimal impact (Initial single user testing)
In this strategy the account popup is only initially enabled on a single user for testing. You need to nominate the testing account. You may already have an appropriate test user account on your system/domain or alternatively selecting your own personal account is a good choice. The name should be in the format used to log into the domain/system (usually the short form).
The minimal impact strategy will give you time to test the popup with the nominated test user Then the Advanced
account selection popup option can be enabled for other users when appropriate.
2.3.4.6.2. Immediate implementation (Enable for all users)
This strategy enables the account selection popup on all users. This option is good for smaller networks as it minimizes the amount of post-install configuration - just deploy the client and your up! If this option is selected you should be in a position to install the client software on user desktops as soon as possible.
If in doubt, select the minimal impact strategy. This will ensure the impact is isolated to only the nominated test user.
2.3.4.7. Verify Setup Options
Prior to enabling the configuration options that you have selected, you will have the chance to verify setup options.
At this stage you are still able to return to any of the prior configuration screens to alter options before clicking
Finish.
2.3.4.8. Wizard Completion
After completing the configuration wizard you will be presented with a user synchronization status screen, showing the progress and results of the system completing its initial setup. Once you have closed that, click Login to access the interface and begin familiarising yourself with the options and features available. Take some time to explore, and refer back to the relevant sections of this manual as required.
2.3.5. Step 5 - Printer/iPrint Configuration
PaperCut NG works by directly integrating with the Novell iPrint Print Manager. iPrint must however be configured to use PaperCut NG as an accounting control source. In the current release, this configuration is done manually at the individual print queue level:
1.
Log into iManager, expand iPrint, and select Manage Printer Manager
2.
Select the Printer Manager associated with one of your print queues.
3.
Click the Manage health monitor link. A list of all your printers should appear.
4.
Select a Printer Agent from the list.
5.
Click Configuration Options.
29
Installation
6.
Enter papercut under the Accounting Autoload Command. Take care to write this all in lower case with no spaces.
7.
Click Apply.
8.
Click Back, then Back and repeat steps 4 through 7 for all printers that should be monitored/controlled by
PaperCut NG
9.
In line with best practice, backup the new printer configuration ( padbtxt.xml
) as follows: a.
In iManager open up the active Print Manager.
b.
Select Manager health monitor
→
Advanced iPrint Manager Information
→
iPrint Manager Internal
c.
Click the button Backup Database.
10. Finally restart the Printer Manager in iManager by pressing Shutdown then Startup. After this, all jobs on the queues should be tracked.
2.3.6. Step 6 - Sharing Client Software
The PaperCut NG client software is located in the local directory:
/home/papercut/client
This software needs to be shared over the network so workstations can access/install the client application. Novell iManager provides a number of file sharing options. One simple solution is to add a read-only NCP or Samba share called
PCClient pointing to
/home/papercut/client
. Established networks will benefit from ensuring the client files are available in their Distributed Files Services. The deployment of the client software (e.g. zero-install
deployment) is covered in Section 5.2, “User Client”.
30
Installation
2.3.7. Step 7 - Testing
Following a fresh installation, it is highly recommended to test core features of the system. For further details please
see Section 2.5, “Testing the Installation”.
2.3.8. Step 8 - Deployment for a Professional (Client Billing) Installation
NOTE: This step is a requirement for a Professional (Client Billing) installation.
Now that the system is tested and working, it is time to deploy the client software and enable the account popup for their use. It is important to deploy the client software before enabling the popup, otherwise users' printing will be stopped/paused.
2.3.8.1. Deploy the client software
As discussed earlier in the chapter the client can be run directly from a network share (which is automatically configured on Windows). There is also the option to install the software locally on each workstation, however this is not usually recommended because it makes the process of updating the client software more complicated.
those instructions to deploy the client software, and then enable the popup as described below.
2.3.8.2. Enable the advanced client popup
Once the client software is deployed on user workstations, the Account Selection can be set. In a Professional
(Client Billing) configuration, all users that print jobs for clients are often given the Advanced account selection popup, however, other Account Selection options may be better suited for some users based on their job function.
The popup can be enabled on one user at a time or can be updated for all users in bulk. The user details page can be used to enable the popup for a single user. To enable the popup for all users in bulk:
1.
Log into the admin interface.
2.
Under the Users section, select the Bulk user actions... action from the menu at the top left of the Users tab.
3.
Select the target group. To enable for all users select the
[All Users] group.
4.
In the Change account selection setting section, enable the Change account selection option.
5.
Select the Show the advanced account selection popup option from the list.
6.
If you do not want to allow users to charge printing to their personal account, then disable the Allow user to
charge to their personal account option.
7.
Press the OK button, and confirm the operation. Once completed, the selected users will have the account popup enabled.
Once the popup has been enabled on all users some testing should be performed from users' desktops. To test, login to the user workstation, perform a print, and check that the account popup appears and the job is logged as expected.
2.3.9. What next?
This concludes the Install Guide. You may like to take some time to explore the features of PaperCut NG before
Client”.
2.4. Installation on Linux (CUPS and/or Samba)
Important
The following section assumes the reader has knowledge of general Unix/Linux system management including using the command-line, creating users, editing configuration files and understanding file
31
Installation permissions.
2.4.1. Step 1 - System Requirements
Before proceeding with the installation the system administrator should take a few moments to verify system requirements. Is the operating system version supported and are patches up-to-date? Take a few minutes to verify
the system is current and supported (see Section 1.1.3, “System Requirements”).
Are printer(s) installed and hosted on this system and are they exposed to the network either via CUPS or Samba?
Administrators should ensure that the print queues are set up and working as expected before attempting to install
PaperCut NG.
In a multi-user environment, printers are often shared with other network users. Other workstations should connect to these printers as "Network Printers". Ensure workstations are configured to print to the shared print queues. For example a Windows workstation may connect to a samba exposed printer via
\\[samba_server]\[printer]
.
Other Linux or Mac workstations will use IPP via CUPS.
If the printers are currently not installed and configured, this task should be performed and verified before proceeding further.
2.4.2. Step 2 - Create the host user account and firewall settings
PaperCut NG runs and installs under a non-privileged user account called "papercut". The installation location for the application is the papercut user's home directory. Create a user account on this system called papercut
.
This is usually done by logging in as root and using a user management GUI tool or at the command prompt entering: shell> useradd -m -d /home/papercut papercut
The syntax for useradd and groupadd may differ slightly on different versions of Linux. They may also be called adduser and addgroup
.
The user's home directory (the
-d option) denotes the install location.
/home/papercut is the recommended location. Administrators may however also consider alternate install locations depending on personal preference.
Alternatives may include:
•
/usr/local/papercut
•
/opt/papercut
Important
This quick start guide assumes the install location is
/home/papercut
. If an alternate home location is defined, some of the paths listed in subsequent sections will require modification.
Some Linux distributions impose strict resource usage limits on user accounts ( ulimit
). The papercut account is a special account used for hosting an application and hence should be granted satisfactory resource limits such as the ability to open many files. The methods of setting user-level ulimit levels vary from distribution to distribution, however the common solution is to add the following line to
/etc/security/limits.conf
: papercut nofile 65535
Many Linux distributions have strict default firewall policies. PaperCut NG uses TCP ports 9191 (for HTTP) and
32
Installation ports 9192 (for HTTPS/SSL) and these ports must be open. Take some time now to ensure these ports are open.
Consult your distribution documentation for details on how to open firewall TCP ports.
2.4.3. Step 3 - Download and installing
Important: Please make sure you download the correct architecture for your distribution.
i686 is for 32-bit operating systems.
x64 is for 64-bit systems (also known as x86_64 or amd64
).
PaperCut NG is supplied as a self-extracting and self-installing archive. The installation is performed as the newly created papercut user and will install to that user's home directory. Temporary root access will be required for part of the install. Please have the root password or sudo password handy. For more detail about the install process
including installing to a different location, see Chapter 27, PaperCut NG on Linux.
Log on as the newly created papercut user and download and execute the installer. The file may be executed from any directory.
shell> su - papercut shell> wget [download url from PaperCut Software website] shell> sh ./pcng-setup-*-linux-*.sh
Follow the installation instructions and enter the root password when requested.
Important
Ensure you login as the user papercut so that the user's environment is sourced so the home directory (install location) is correctly defined.
Figure 2.15. The Linux install process
The installation process will take between two and five minutes depending on the speed of the system. A system restart is not required but administrators are advised to perform installation on live production systems during periods of low activity - for example, not during backup operations or other administration activities.
2.4.4. Step 4 - Configuration Wizard
After installation, you will be prompted to open a web browser at http://[server-name]:9191/admin to
33
Installation complete configuration. The configuration stages are explained below:
2.4.4.1. Administrator Password
This is the master password for the main in-built admin account, and is independent of the operating system or domain passwords. The password will need to meet minimum strength requirements, and must be at least six characters. Ensure that knowledge of this password is kept secure. This screen also sets the system's physical location and language; ensure that these are correct before proceeding.
Figure 2.16. PaperCut NG Configuration wizard
Tip
Treat this password like your router/modem management passwords. It is independent of your domain accounts and needs to be kept secure.
2.4.4.2. Organization Type
This is the organization type which matches the organizational environment where PaperCut NG will be used.
Choosing the appropriate organization type will determine which system defaults are used on setup. For example, in a Professional (Client Billing) organization, where it is useful to charge-back printing to customers, an advanced client popup is provided with additional features useful for dealing with large numbers of client (shared) accounts.
These default settings chosen for an organization type can be changed after installation.
34
Installation
2.4.4.3. Default Print Cost
This is the default cost-per-page assigned to the printers. This setting can be changed on a per printer basis after installation. Choosing a sensible cost now will help minimize future setup. For example in the USA, a value of $0.05
would be appropriate for many standard black & white printers.
2.4.4.4. Initial User Credit (for Education sites)
When the organization type has been set to Education, users can be assigned an initial starting credit. This ensures they have funds in their account as soon as the system is enabled. An option also exists to control what happens when users run out of credit/quota. If you are evaluating PaperCut NG it might be appropriate not to disable printing when a users funds run out. This way you can be assured that user printing is not disrupted during the evaluation.
These settings may be changed after setup.
2.4.4.5. User/Group Synchronization
PaperCut NG extracts user information out of the System or Domain. The options presented here will vary depending on the Operating System and its environment. During evaluation, most sites will opt to import all users from the system/domain into PaperCut NG. An option also exists to import a subset of users from a given group.
This option is pertinent when it is known that only a subset of users will only ever use the printers.
Figure 2.17. User sync configuration wizard page
Options on Linux include Unix Standard (PAM, NIS, etc.), LDAP, or Samba.
Select Unix Standard if the user accounts are setup and defined on the local system as standard Unix accounts or mapped into the system from a central directory service such as LDAP via nsswitch.conf and PAM. Most large established networks will use this option.
The LDAP option is appropriate for large networks with existing Open Directory domains. This includes networks running Open LDAP and Windows domains running Active Directory. PaperCut NG will do it's best to auto-discover
LDAP settings, but some knowledge of LDAP and/or Open Directory will be required. More information on LDAP is
available in Section 15.3.8, “Using LDAP for user synchronization”.
Select Samba if the central user directory is a Windows Domain. The Samba option is only available if Samba is installed on the system. The Samba option is appropriate on medium to small networks currently operating in a
Windows Domain environment.
The Samba option requires additional information such as the name of a domain server, and login credentials for an
Administrator level account. This information is requested on the subsequent wizard screen. Take care to ensure this information is complete and correct.
2.4.4.6. Client Settings in Professional (Client Billing) installations
35
Installation
In a Professional (Client Billing) environment, the main focus is on allowing users to allocate print jobs to client
(shared) accounts. The process works by:
• Pausing all jobs that enter the print queues.
• Displaying a popup on the user's workstation asking them to allocate the print job to an account. This is done by selecting the account from a list.
• After the user has responded to the popup, the job is released to the printer.
The account selection popup option is enabled at the user level. Once the option is enabled, the user must run the client software. If the client software is not running, the popup cannot display, and the job will remain paused in the print queue. This option is hence considered high impact. You are presented with two strategies that allow you to choose the implementation approach that best suits your needs:
2.4.4.6.1. Minimal impact (Initial single user testing)
In this strategy the account popup is only initially enabled on a single user for testing. You need to nominate the testing account. You may already have an appropriate test user account on your system/domain or alternatively selecting your own personal account is a good choice. The name should be in the format used to log into the domain/system (usually the short form).
The minimal impact strategy will give you time to test the popup with the nominated test user Then the Advanced
account selection popup option can be enabled for other users when appropriate.
2.4.4.6.2. Immediate implementation (Enable for all users)
This strategy enables the account selection popup on all users. This option is good for smaller networks as it minimizes the amount of post-install configuration - just deploy the client and your up! If this option is selected you should be in a position to install the client software on user desktops as soon as possible.
If in doubt, select the minimal impact strategy. This will ensure the impact is isolated to only the nominated test user.
2.4.4.7. Verify Setup Options
Prior to enabling the configuration options that you have selected, you will have the chance to verify setup options.
At this stage you are still able to return to any of the prior configuration screens to alter options before clicking
Finish.
2.4.4.8. Wizard Completion
After completing the configuration wizard you will be presented with a user synchronization status screen, showing the progress and results of the system completing its initial setup. Once you have closed that, click Login to access the interface and begin familiarising yourself with the options and features available. Take some time to explore, and refer back to the relevant sections of this manual as required.
2.4.5. Step 5 - Printer Configuration
Unlike Windows and Mac with single print system environments, Linux is a more complex environment with a choice of print system implementations. At this stage some manual printer configuration is required. Please see
environment before returning to this section and following on with the next step.
Printers hosted a machine other than the PaperCut NG server will require additional installation steps to be
Attached Printers for details.
2.4.6. Step 6 - Sharing Client Software
The PaperCut NG client software is located in the directory
[app-path]/client
. It may be useful to share this directory over the network so workstations can access/install the client application. Common sharing methods include:
36
Installation
• Samba - used to share files to Windows based workstations. Mac OS X Server tools such as the Workgroup
Manager or other 3rd party tools such as SharePoint may help with sharing the client directory via Samba.
Similar GUI tools exist on Linux.
Advanced system administrators may be comfortable sharing this directory by hand-editing the
/etc/smb.conf
file. The following configuration will share the directory in read-only form:
[pcclient] path = /home/papercut/client comment = PaperCut Client public = yes only guest = yes read only = yes
• NFS - a popular sharing method used for Linux/Unix based workstations.
2.4.7. Step 7 - Testing
Following a fresh installation, it is highly recommended to test core features of the system. For further details please
see Section 2.5, “Testing the Installation”.
2.4.8. Step 8 - Deployment for a Professional (Client Billing) Installation
NOTE: This step is a requirement for a Professional (Client Billing) installation.
Now that the system is tested and working, it is time to deploy the client software and enable the account popup for their use. It is important to deploy the client software before enabling the popup, otherwise users' printing will be stopped/paused.
2.4.8.1. Deploy the client software
As discussed earlier in the chapter the client can be run directly from a network share (which is automatically configured on Windows). There is also the option to install the software locally on each workstation, however this is not usually recommended because it makes the process of updating the client software more complicated.
those instructions to deploy the client software, and then enable the popup as described below.
2.4.8.2. Enable the advanced client popup
Once the client software is deployed on user workstations, the Account Selection can be set. In a Professional
(Client Billing) configuration, all users that print jobs for clients are often given the Advanced account selection popup, however, other Account Selection options may be better suited for some users based on their job function.
The popup can be enabled on one user at a time or can be updated for all users in bulk. The user details page can be used to enable the popup for a single user. To enable the popup for all users in bulk:
1.
Log into the admin interface.
2.
Under the Users section, select the Bulk user actions... action from the menu at the top left of the Users tab.
3.
Select the target group. To enable for all users select the
[All Users] group.
4.
In the Change account selection setting section, enable the Change account selection option.
5.
Select the Show the advanced account selection popup option from the list.
6.
If you do not want to allow users to charge printing to their personal account, then disable the Allow user to
charge to their personal account option.
7.
Press the OK button, and confirm the operation. Once completed, the selected users will have the account popup enabled.
Once the popup has been enabled on all users some testing should be performed from users' desktops. To test,
37
Installation login to the user workstation, perform a print, and check that the account popup appears and the job is logged as expected.
2.4.9. What next?
This concludes the Install Guide. You may like to take some time to explore the features of PaperCut NG before
Client”.
2.5. Testing the Installation
Once the installation is complete, it is now time to test the system.
2.5.1. Testing for an Education or Small/Medium Enterprise Installation:
1.
Print a test document such as a web page or basic document.
2.
Navigate to the printer section and select the Print Log tab.
3.
Navigate to the Printers
→
Print Log tab.
4.
Your print job should now be listed in the log.
5.
Your user account should also be charged an appropriate amount.
2.5.2. Testing for a Professional (Client Billing) Installation:
1.
Log into the admin interface after completing the configuration wizard.
2.
Under the Users section, locate and click on your test user account. The quick find feature may assist here.
3.
Ensure that the user has the Account Selection option set to Show the advanced account selection popup.
Figure 2.18. Ensure the advanced popup is enabled
Now we need to log onto a workstation, start the client and test printing. The following instructions assume testing is performed from a Windows desktop system. For other platforms please consult the client deployment process as
explained in Section 5.2, “User Client”.
1.
Log onto a workstation and open Windows Explorer (the file explorer). In the address bar enter:
38
Installation
\\[server-name]\PCClient
Where
[server-name] is the hostname of the system you installed PaperCut on. Explorer should connect to the share containing the client software.
2.
Browse into the win directory and double-click pc-client.exe
. The client should launch and an icon should appear in the task tray.
3.
Print a test document such as a web page or basic document.
4.
The client popup window should display. Select My Personal Account.
Figure 2.19. The account selection popup (displaying extra accounts)
5.
Back in the PaperCut NG server admin interface, navigate to the Printers
→
Print Log tab.
6.
Your print job should now be listed in the log.
7.
Your personal user account should also be charged an appropriate amount.
39
Chapter 3. Implementation by Example
PaperCut NG is a feature-packed application designed to meet the print management requirements of all types of organizations. It's unlikely that any single organization would use or need all the features in PaperCut NG. The key to a successful implementation is with identifying the features that are most needed, and utilizing them in the correct manner.
This chapter covers common implementation scenarios in a case study form. It discusses the requirements common to the scenario, and how these requirements are satisfied using key features. The aim of this chapter is to guide implementers towards identifying and utilizing the most appropriate features.
Locate the scenario that's the closest fit to your organization. It may also be beneficial to read other scenarios that might apply to your situation. For example, a large business may benefit from some of the ideas presented in the small business case and so on.
3.1. Scenario: The Small School
Fast River School has a student population of 200 and caters to students in Kindergarten through 6th grade. A teacher is responsible for each class. The school has a two computers in each class room and a small computer lab for older students. All computers are networked. A single server acts as a domain controller and a file and print server. The students in each year level log on to the computers using the username and password allocated to their class.
3.1.1. Requirements
1.
Each grade level has a monthly printing budget of $50.
2.
If the budget is exceeded, teachers may discuss additional funding with the school principal.
3.
Student use of color printers should be approved by teachers.
4.
The teacher for each grade level should have access to activity reports in order to track the class's printing volume.
5.
The school principal needs a summary report of class printing activity at the end of each semester.
3.1.2. Implementation
3.1.2.1. Initial Installation
PaperCut NG should be installed on the school's file and print server. The initial installation process is covered in
3.1.2.2. Requirement 1
The monthly budget can be automated by applying a $50.00 monthly quota to the
[All Users] group. The domain login accounts used for each year level are automatically placed in the
[All Users] group. See the following areas for more information:
•
Section 6.1, “Groups in PaperCut NG”
•
Section 6.2, “Setting up quota allocations”
3.1.2.3. Requirement 2
Teachers can be warned when their class's balance has reached a low balance limit. The notification can be via email. The notification option is located under: Options
→
Notifications
→
Low Balance Notifications. Enable the email option for email notifications.
3.1.2.4. Requirement 3
40
Implementation by Example
The system administrator can set up the printers so only selected users (i.e. teachers) can approve jobs issued to color printers. By selecting the Only managers can release option on a given printer, jobs are held in a queue.
Teachers can then approve the student print jobs by accessing the web based release software accessed via the
URL: http://server_name:9191/release
Where server_name is the name of the organization's print server.
3.1.2.5. Requirement 4
Teachers can view print activity and account balance by connecting a web browser to: http://server_name:9191/user
Where server_name is the name of the organization's print server. Access to the end-user pages is covered in
Section 4.6, “Interface Levels”.
3.1.2.6. Requirement 5
Summary reports can quickly be generated by any user with PaperCut NG's system administrator access. Granting
3.2. Scenario: The Large School
North Shore High has a student population of 2000 students. Their network consists of:
• Three student Windows PC labs and one Mac lab with other computers scattered around the school for student use.
• A mixture of Mac and Windows laptops used by staff.
• A Windows Active Directory environment hosted on a number of servers.
• Printers are hosted on two separate Windows servers.
• Some teaching staff have desktop printers attached locally to their workstations.
• Each lab has a black and white laser printer.
• Two high-end color copier/printers and large format printers are located in a print room situated away from the computer labs.
Students have their own login account and small home directories for storage.
3.2.1. Requirements
1.
The system must support the mixed Mac and Windows environment.
2.
The system should support multiple print servers and locally attached desktop printers.
3.
The school would like to experiment with hosting printers on a Linux system with the aim of using Linux for print serving tasks to help save on future Windows licensing costs.
4.
Students are to be granted a small $5 a month printing budget. Final year students have a $10 a month allowance.
5.
If students need additional printing, they must purchase it. The payment process should be simple and easy to manage.
6.
Jobs issued to printers situated in the print room should be held in a queue and only printed on the physical printers after the user has arrived at the room to collect the job.
7.
Staff members should have the option of charging printing to department accounts or to a small personal
41
Implementation by Example account, depending on the type of print job.
8.
Student printing should be archived for a period of 4 weeks. This will allow IT staff to determine the individual students responsible for printing inappropriate material when incidents are reported.
3.2.2. Implementation
3.2.2.1. Initial Installation
The mixture of operating systems and multiple-servers makes this a complex installation. Prior to deployment, it is advisable for the network manager and/or network administrator to plan the deployment and familiarize themselves with the PaperCut NG software.
3.2.2.2. Requirement 1
PaperCut NG is a cross platform solution designed for all major operating systems. Given the existence of an existing domain environment, the installation of Windows systems is typically straightforward. The Macs however
3.2.2.3. Requirement 2
Multi-server installations are commonplace on larger networks. One system needs to be nominated as the primary
PaperCut NG server. This system is responsible for running the "brains" of the system and storing all data. The other servers, secondary servers, report back to the central primary server via XML Web Services. The system
Servers”.
3.2.2.4. Requirement 3
Linux is becoming ever popular in the server space. First web hosting, and now common file and print services are being serviced with the Linux operating system. PaperCut NG is available for Windows, Mac and Linux systems. Not only that, its architecture allows all three systems to run side-by-side sharing a common central server. This school may experiment with hosting printers on Linux by running a Linux based secondary server alongside their main
information.
3.2.2.5. Requirement 4
Quotas or allowances are allocated to users on a per-group basis. By adding network domain groups to PaperCut
NG that represent the respective student groups, system administrators can automate the allocation process. See
Section 6.2, “Setting up quota allocations” for further information.
3.2.2.6. Requirement 5
The purchase of additional quota/credit is best managed by the TopUp/Pre-Paid Card system. The system reduces the data entry and management requirements associated with manual transactions. More information on
TopUp/Pre-Paid Cards is covered in Chapter 16, TopUp/Pre-Paid Cards.
3.2.2.7. Requirement 6
Print release in the print room is best achieved with the release station. By running a special full-screen application on a dedicated terminal in this room, students can release their jobs once they arrive at the room. The release
3.2.2.8. Requirement 7
teaching staff are presented with a popup window asking them to select an account to charge. Account access can be controlled via domain group membership or via PINs. More information on shared accounts is available at
42
Implementation by Example
3.2.2.9. Requirement 8
will allow approved staff to visually inspect the contents of all print jobs.
3.3. Scenario: The University
West Face University has a student population of 10,000 full-time students and off-campus and part-time students.
IT services centrally control the network, however individual faculties and departments also offer and manage some of the specialist IT infrastructure. All major operating systems are in used on both the workstations and servers.
3.3.1. Requirements
1.
Centrally managed printers are hosted in a clustered print server environment. The solution needs to support clustering.
2.
IT services wants to provide the option for department labs to also have their printers controlled via the central system.
3.
Client software needs to be optional. It would be preferable for students to have access to their account details via a web browser.
4.
The design of the web interface should be customizable.
5.
The system must be secure and support SSL-based encryption.
6.
The system should run on top of a database system and allow data access to facilitate custom reports using packages such as Crystal Reports.
7.
An open source system would be preferable.
3.3.2. Implementation
3.3.2.1. Initial Installation
University-wide deployments can be quite involved. Most large universities that have deployed PaperCut NG have worked closely with the PaperCut NG development team during implementation. A lot can be gained by arranging a teleconference or similar with the development team. We're always happy to help our larger customers deploy the ideal solution.
3.3.2.2. Requirement 1
PaperCut NG supports clustering at all application layers including the print server, the database server, and the application server on both Microsoft Windows and Linux. Setting up PaperCut NG in Microsoft Clustering Services is
Linux-HA (High-Availability Linux) and other tools to support customers who use Linux.
3.3.2.3. Requirement 2
Printers and labs hosted by individual faculties and departments outside the central IT services area can optionally be joined into the campus-wide system via PaperCut NG's secondary server support. Central IT staff can approve these secondary servers via IP address and grant selected staff administrator level access to the system's admin
Printers for more information on secondary servers.
3.3.2.4. Requirement 3
PaperCut NG's client software is optional in a basic charging/quota environment. Users can access their accounts and view their account balance, transaction and printing history, and use advanced tools such as TopUp/Pre-Paid
3.3.2.5. Requirement 4
43
Implementation by Example
The design and layout of the end-user web interface can quickly be changed using HTML and Cascading Style
3.3.2.6. Requirement 5
PaperCut NG provides secure connections for report access and administration via SSL-based encryption. Larger universities often have their own certificate signing procedure for SSL based servers. PaperCut NG can even accept these signed certificates. SSL-based encryption is set up by default and is accessed via a URL such as: https://[server_name]:9192/admin
Information on using a custom SSL certificate is covered in Section A.4, “SSL/HTTPS Key Generation”.
3.3.2.7. Requirement 6
Hosting the PaperCut NG system on top of an external database system such as Microsoft's SQL Server offers a number of advantages including easy data access, better performance and scalability, and the ability to take
Deployment on an External Database (RDBMS).
The data structure is simple and administrators with report writing skills will quickly be able to access the data for custom reporting via tools such as MS Access or Crystal Reports.
3.3.2.8. Requirement 7
PaperCut NG is a commercial system with commercial level support. However unlike many other commercial applications, PaperCut Software International Pty Ltd does offer source code access. A number of universities have used the source code access for:
• auditing - verifying that the software is secure.
• customization - knowing how the application works and how to implement add-ons.
Large universities should also look at the large school scenario. Features such as shared accounts and secure printing are also applicable to many university environments.
3.4. Scenario: The Small Business
Northwoods Inc. is a small twelve-person Engineering and Architect Drafting office serving the local area. Their network consists of a mix of Windows XP and Windows Vista workstations connected on a Workgroup based network. Wireless network access is also provided to employees with laptops. Most staff work on a project basis and there is a need to track use by project code and sub-project. Some staff work on a freelance basis and management would like to track and charge for color printer use on a monthly basis.
3.4.1. Requirements
1.
The system must be easy to set up and maintain as there is no full-time IT staff.
2.
The system must work in a Windows workgroup environment.
3.
Staff are to have unlimited access (i.e. no budgets).
4.
Staff need to allocate their printing to projects and cost centers so printing and drafting costs can be passed back onto the clients (chargeback).
5.
Managers need access to view real-time reports.
6.
Data should be able to be exported to Excel on a monthly basis for billing.
3.4.2. Implementation
44
Implementation by Example
3.4.2.1. Initial Installation
One system on the network needs to be allocated the task of hosting the printer and the PaperCut NG application.
Users will print via this system so it needs to be left on most for most of the time. An existing file server is ideal, however someone's desktop system will also suffice (must be left on at all times).
3.4.2.2. Requirement 1
PaperCut NG is well known for its ease-of-use. It is a self-maintaining system with a simple to use web-based interface. Apart from the initial set up, and the recommendation to incorporate the application's data into a backup procedure, no further technical administration and support is required.
3.4.2.3. Requirement 2
Workgroup environments are common on small networks. They differ from a domain environment in that they are not centrally authenticated via a server. Users may use a system that automatically logs in as "a user" or maybe
information on the ways in which PaperCut NG can be installed in a workgroup environment.
3.4.2.4. Requirement 3
All users can be set up as "unrestricted". In this mode, users can start of with a zero balance and count down as they print. Their balance indicates their printing value to date.
3.4.2.5. Requirement 4
Shared accounts can be created to represent the current projects with sub-accounts used to represent areas under these projects (sub-projects). The client popup software can be enabled on user accounts forcing users to allocate printing to the project/client. In addition, the advanced client popup will allow premiums to be charged for special printing such as reproduction of expensive mylar film.
Selected staff can run monthly or quarterly invoice reports at any time to quickly determine printing associated with a
3.4.2.6. Requirement 5
PaperCut NG records data in real-time. Full print logs and reports are available at any time and can be accessed using a standard web browser. The manager can log into the administration interface and access the reports at any time.
3.4.2.7. Requirement 6
All reports and activity lists can be exported to Microsoft Excel. To access the Excel data, click on the small Excel icon located next to the report name, or the icon at the bottom of the print log.
3.5. Scenario: The Medium to Large Business
SandComp is a large manufacturing company consisting of 3000 employees spread over 4 sites. All sites are connected via a fast Wide Area Network (WAN). Printers are hosted on local servers with the largest site hosting printers in a Microsoft Cluster environment.
3.5.1. Requirements
1.
Must support a Microsoft Cluster environment.
2.
Must centrally store print data on a server located at the main office.
3.
Must not cause disruption if the WAN link goes down between offices.
4.
The consulting division needs to be able to track printing by project (client/matter format) so costs can be passed back to their clients.
45
Implementation by Example
5.
The finance department needs secure print release on their shared printers stored in the utility room.
3.5.2. Implementation
3.5.2.1. Initial Installation
The implementation of PaperCut NG in this environment would best be managed using staggered or step-by-step approach. First, the software should be installed and tested on the central offices' clustered environment, then rolled out to the other offices, and finally the secure printing and client popups should be implemented. A staggered approach is likely to minimize disruption allowing network administrators to focus on the tasks at hand.
3.5.2.2. Requirement 1
Clustering and High Availability.
3.5.2.3. Requirement 2
The print servers at the remote locations can be installed as secondary servers reporting back to the primary server.
All data will be stored in one location. The services communicate using XML Web Services and only consume a few bytes per print job. Hence the system will work well over the WAN.
3.5.2.4. Requirement 3
PaperCut NG has a fail-open design. This means that if a failure occurs, such as the network fails between servers,
each site to ensure continuity of Find-me Print and copy services during a WAN outage.
3.5.2.5. Requirement 4
The consulting division can make use of the share accounts feature to track their printing by client. More information
advanced popup. The advanced popup offers advanced searching features allowing end-users to quickly located the appropriate account and enter job comments as required.
3.5.2.6. Requirement 5
Secured print release can be facilitated by setting up a terminal (a low-end PC will do) in the finance department's utility room. When a member of the finance department prints to a shared printer, their document will hold in the queue until that member goes to the utility room and releases the print job with his or her username and password.
This process ensures that documents stay secure and can't be "accidentally" collected by other people.
3.6. Scenario: The Public Library or Internet Cafe/Kiosk
The Sandy Beach Cafe is a typical Internet cafe offering Internet access, faxing, printing and other services. This business has 50 computers and two printers. A black & white laser printer called "Black and White Printer" and a high-end color inkjet system named as "Color Printer". They would like to implement a pay-per-print system that meets the following process and requirements:
3.6.1. Requirements
1.
The customer prints the job to the appropriate printer.
2.
At the front desk, the customer pays a staff member for the print job.
3.
The staff member releases the job for printing.
4.
The customer collects the print job.
3.6.2. Implementation
PaperCut NG's hold/release queues are ideally suited to the Internet cafe scenario. More information on the
46
Implementation by Example
provides both an application interface for release station managers (i.e. desk staff) as well as a convenient web browser-based interface. To summarize a typical implementation:
1.
The PaperCut NG server software is installed on the system hosting the printers. An existing server or desktop system will suffice.
2.
Workstations are configured to print to the printers shared on the system set up in step 1.
3.
Inside the PaperCut NG admin interface, the printers should have the manager only release option selected.
4.
Desk staff can view and control pending print jobs, their cost, and other details via the web based release interface accessible at the URL: http://server_name:9191/release
47
Chapter 4. Quick Tour
This section will guide you through the main areas of the application and cover some common management tasks.
4.1. Navigation
Before we jump in and start our tour of PaperCut NG it is important to take some time to understand the application's navigation tools. The subsequent sections detail the major user interface elements.
4.1.1. Tabs
Figure 4.1. Application navigation tabs
Application areas are grouped into tabs that logically separate parts of the system. Selecting a tab displays the controls and information related to that area. Users will be familiar with the concept of tabs from many other applications.
4.1.2. Actions
Figure 4.2. The Actions area. Click to perform the action.
Throughout the application, the Actions area lists a number of tasks or actions that can be performed. The Actions list is always located in the top left-hand corner of the application window. Actions are adaptive and the list of actions changes depending on the area of the application being viewed.
4.1.3. Buttons
Figure 4.3. Buttons to validate and save settings
Changes made to options, user settings or configurations are only validated and applied after submitting the change. Screens that you can save in the application will have the following buttons located at the bottom:
• Apply - Validate and save the changes and return to this location/object
48
Quick Tour
• OK - Validate and save the changes and return to the data list ready to select and edit another object.
• Cancel - Don't save and changes.
4.1.4. Crumb Trail
Figure 4.4. The crumb trail highlighting the location
The crumb trail serves two purposes. It maps out the navigation path followed by the user and provides a way to navigate up (back) the navigation path. For example, while editing a user's account, the crumb trail provides a hyperlink up one level back to the User List.
4.1.5. Status Messages
Figure 4.5. A red status message indicating a validation error
Important status messages are displayed in the top section of the application window. Messages relating to an error or requiring user intervention are displayed in red. Standard messages are displayed in green and cautions in yellow.
4.1.6. Fields
49
Quick Tour
Figure 4.6. A field highlighted indicating a validation error
Configuring printers, users or settings are often done via text fields. Changes made to fields are validated after pressing OK or Apply buttons. If the field fails validation, the offending data is marked with a red asterisk. Typical validation errors include invalid number or currency formats.
4.2. Sections
The PaperCut NG administration interface is grouped into task oriented sections. These are denoted by the tabs at the top of the screen. The sections are:
Figure 4.7. Application navigation tabs
4.2.1.
Dashboard
4.2.2.
• The What's next? gadget provides tips for new users.
• The System Status gadget provides a list of system statistics.
• The Pages Printed graph shows a running history of the daily pages printed over the past 30 days.
• The Environmental Impact gadget provides environmental impact statistics.
• The Printer Status gadget displays daily pages printed and device status per printer.
• The News gadget has links to the latest information about release and development activity at PaperCut.
• The Real-time Activity gadget is a scrolling summary of PaperCut events with expandable details.
• Related sections:
•
Users
• View a list of all users
• View and change a user's credit balance
• View a user's statistics and charts
• List a user's printing activity
50
4.2.3.
• Change user privileges and settings
• Related sections:
•
Section 4.3, “Basic User Operations”
•
Chapter 6, Advanced User Management
Groups
Quick Tour
4.2.4.
• Add/Remove domain or network groups required for user management
• Define rules controlling how new users are created
• Perform bulk user operations
• Control user quota allocations
• Related sections:
•
Section 6.1, “Groups in PaperCut NG”
•
Chapter 6, Advanced User Management
Accounts
4.2.5.
• View, edit and create shared accounts
• View and change the shared accounts credit balance
• List all charges against shared accounts
• Set account access security
• Related sections:
•
•
Printers
4.2.6.
• View and edit printer costs and settings
• Define printer filter rules and restrictions
• View all recent print jobs
• View printer statistics and charts
• Visually inspect the contents of print jobs (via print archiving)
• Related sections:
•
Section 4.4, “Basic Printer Operations”
•
Chapter 7, Advanced Printer Management
•
Section 23.5, “Web Print (Driver-less printing via a web browser)”
•
Chapter 24, Print Archiving (viewing and content capture)
Reports
• Access to standard reports for viewing, export and printing
51
Quick Tour
4.2.7.
• Run “one click” reports for quick overviews
• Run reports over Ad-hoc date ranges
• Related sections:
•
Section 4.8, “Charting, Statistics, Reports and Logs”
•
Cards
4.2.8.
• Managed TopUp/Pre-Paid Cards
• View card use and activity
• Download and install the card creation wizard
• Import new cards
• Related sections:
•
Chapter 16, TopUp/Pre-Paid Cards
Options
4.2.9.
• Access general system settings
• Control administrator access and security
• Perform network user and group synchronization tasks
• Perform backup snapshots
• Related sections:
•
•
Appendix A, Tools - database, server-command scripting, and APIs (Advanced)
Application Log
4.2.10.
• View system audit, security and application events
• Related sections:
•
About
• List version and build information
• Access update news
• Install and view license information
• Related sections:
•
Chapter 21, Licensing and Support
4.3. Basic User Operations
The user section is dedicated to user management. Common user oriented tasks include assigning additional credit
52
Quick Tour to users, viewing a user's activity, and controlling user privileges.
Users in PaperCut NG can be assigned either:
• Restricted access where access to resources is denied once their credit drops to zero (or to the overdraft limit).
• Unrestricted access meaning the user is never denied access.
To change a user's restriction privileges:
1.
Log in as the built-in admin user.
2.
Click on the Users section.
3.
Select the user from the list (or enter the user name in the quick find).
4.
Scroll down to the Account Details section.
5.
Click on the Restricted checkbox.
6.
Click on the Apply button to save the change. A save success message will appear.
To increase a user's account balance by $10.00:
1.
Select the user from the list (or enter the user name in the quick find).
2.
Select the Adjustments and Charges tab.
3.
Enter
$10.00
in the adjustment field.
4.
Enter a comment to associate with the transaction.
5.
Click the Apply button.
Figure 4.8. Adjusting a user's credit up $10.00
To view a user's transaction and print history:
1.
Select the user from the list (or enter the user name in the quick find).
2.
Select the Transaction History tab to view the user's transaction.
53
Quick Tour
3.
Select the Job Log tab to view the user's recent print activity.
4.4. Basic Printer Operations
All printers managed by PaperCut NG are configured under the Printers section. Printer configuration may include:
• Setting a cost-per-pages or defining more complex charging rules.
• Defining advanced filter and restriction rules. For example, configuring a printer to deny jobs of a selected size or automatically removing duplicate documents.
• Controlling the enabled/disabled status via time-latches.
To define a basic cost-per-page of $0.10:
1.
Log in as the build-in admin user.
2.
Select the Printers section.
3.
Click on the printer who's page cost is to be defined.
4.
Enter a page cost of
$0.10
under the configuration section.
5.
Press the Apply button to save the change.
To define an advanced cost model offering a 40% discount for duplex (double sided) printing:
1.
Under the Printers section, select the printer whose cost model is to be modified.
2.
Click on the Advanced Charging tab.
3.
Select a charge type of by category.
4.
Enter 40% in the duplex discount field and select Percent less from the dropdown list.
5.
Click the Apply button to save the change.
Figure 4.9. A 40% discount applied to double-sided printing
Filters provide administrators with access to a set of rules to control what type of documents are allowed access to the printer. Filter rules can be used for a variety of tasks such as:
• Enforcing good printing practices
• Preventing queue jamming and hogging
54
Quick Tour
• Ensure printers are used for the purpose they are designed for
Filter options include:
• Control by the jobs cost
• Control by a document's page count
• Denying jobs based on their color mode
• Filtering by document name
• Automatically denying and deleting duplicate documents
Example - To apply a filter preventing jobs over 100 pages:
1.
Under the Printers section, select the printer to which the filter should be applied.
2.
Click on the Filters tab.
3.
Scroll to the Page Count section.
4.
Click and select the deny jobs based on number of pages.
5.
Enter in
100 in the maximum filed.
Figure 4.10. Printer Filters and Restrictions
To disable a printer for the next hour using a time latch:
1.
Under the Printers section select the printer to lock or disable.
2.
On the Summary tab, scroll to the Configuration section.
55
Quick Tour
3.
Select Disable for next hour from the drop-down list.
4.
Click the Apply button to save the change.
Figure 4.11. A printer disabled for 1 hour
4.5. Client Software
The client software is optional and not required for basic logging, however it does provide users with access to advanced features. These features include:
• Real-time feedback to the user including their account balances and event messages such as "print job denied" reasons.
• Access to the account selection popup so users can allocate print jobs to shared accounts - for example, accounts representing departments, projects, clients, etc. This is particularly important in a business environment.
56
Quick Tour
Figure 4.12. The user client displaying the "Advanced Account Selection Popup"
4.5.1. Demonstrating the client software and account selection process
Create a Shared Account:
1.
Log into PaperCut NG as an administrator (e.g. admin account).
2.
Select the Accounts tab.
3.
Click the Create a new account action.
4.
Enter an appropriate name for the account. For example "test account".
5.
Click the Apply button to save the account.
6.
Select the security tab and ensure the
[All Users] group has access to the account. If not, add the group by selecting it from the drop-down and pressing Add.
7.
See Chapter 8, Shared Accounts for more details about creating and managing shared accounts.
Grant account selection access to your account:
1.
Select the Users tab.
2.
Locate and click on your personal user account.
3.
Under the Account Selection section, select the option Show the advanced account selection popup.
4.
Print the OK button to save and apply changes.
Launch the client software (Windows Platform):
1.
Log into a workstation using your user account as modified above (note: The server itself can also be used for this testing if desired)
2.
Open Windows Explorer (File Explorer).
3.
In the address bar, enter
\\server_name\pcclient where
"server_name" is the name of the server hosting the PaperCut NG software. This will bring up files located on the
PCClient share.
4.
Launch the pc-client.exe
program by double-clicking on the file. An icon should appear in the task tray.
5.
Print a test page (for example a web page). The advanced client popup should appear allowing you to select the "test account" set up in the preceding section.
software deployment is covered in Section 5.2, “User Client”.
4.6. Interface Levels
PaperCut NG provides two layers of system access, Admin and User.
4.6.1. Admin Access
Admin access provides access to the system for administration and management. This level is usually only granted to selected individuals in the organization, such as network administrators or management staff. To assign admin
rights to an individual or group of users see Section 4.7, “Assigning Administrator Level Access”.
4.6.2. User Access
End users are granted access to a set of basic web pages providing them with access to:
• View their account balance
• List recent account activity
• Use tools such as TopUp/Pre-Paid Cards and funds transfers to other users
57
Quick Tour
The User Client Tool (PaperCut NG User Client Software) complements the web pages by providing users with a quick view of their current account balance.
Important
Access to the user area, like the admin area, requires authentication - that is the user must enter their network username and password. Authentication is required because user information such as print history is confidential. Access to the user's funds transfer feature also needs to be protected. This is particularly important in schools. Students can rest assured that should they leave their workstation for a few minutes another student can't transfer their account balance to themselves!
To access the user pages via the User Client Tool:
1.
Start the client software if it is not already running. On the server this may be started via the Client Start menu item. See the client software section for details on how to start this on a remote workstation or desktop.
Figure 4.13. The user client tool
2.
Click the Details... link. The web browser will open.
3.
Enter your username and password and click Login.
4.
The user page pages will display.
To access the user pages directly via a web browser:
1.
Open a standard web browser.
2.
Enter the URL http://[servername]:9191/user where
[server_name] is the network name assigned to the system running PaperCut NG. The login screen will appear.
3.
Enter your username and password and click Login.
4.7. Assigning Administrator Level Access
PaperCut NG sets up one administrator account called “admin”. This is the master administrator account, with access to all features, whose password is assigned during the configuration wizard. In large organizations it is likely that administrator level access will need to be granted to more than one person. One solution is to give all persons the master password; however the recommended approach is to assign administrator rights to these individual's network user accounts. The advantages of this approach are:
• They can access the administration pages using their own username and password (they don't have to remember another password!).
• Different levels of administrator access can be assigned to different users. PaperCut NG includes an advanced
Access Control List (ACL) allowing different administrators access to different functions and areas of the application.
• Most activity is audited so changes can be sourced to an individual.
58
Quick Tour
For more information see Section 15.4, “Assigning Administrator Level Access”.
4.8. Charting, Statistics, Reports and Logs
One of the key features of PaperCut NG is the advanced charting, statistics, reporting and logging. This information can be used by administrators to:
• Determine which printers are most used
• Spot areas where printers may be inappropriate for the task.
• View user and printer trends over time.
4.8.1. Charts
Charts are ideal for obtaining a quick visual overview. All users and printers have a line chart displaying activity over the last 30-days.
Figure 4.14. User 30-day account balance history
The Charts Tab under the Printers section hosts a set comparison charts allowing administrators to compare printers side by side.
59
Quick Tour
Figure 4.15. Printer utilization chart
Under each individual printer the Statistics section provides information on all jobs printed on a given printer.
Figure 4.16. Print page history for a single printer
4.8.2. Reports
Reports provide a tabular data display, often in a printable format, of system information ranging from activity histories, summaries, transaction details, etc. Reports are typically run to print a summary of user activity, printer activity, or group or account activity. To streamline access to common reports, PaperCut NG provides a series of predefined one-click report links under the Reports section. Most reports can be generated over a variety of common date ranges or user defined date ranges.
Standard reports include:
• User Reports
60
Quick Tour
• Print summary statistics grouped by user
• Quick list of the most active print users
• Printer Reports
• Summary of print activity grouped by printer
• Quick lists of the most active/busiest printers
• Group Reports
• Summary of print activity grouped by network group (Note: The group needs to be defined under the Groups section.)
• Shared Account Reports
• Summary of print activity grouped by shared account charged
• Print Log Reports
• Detailed lists of all print jobs over a given period
• Quick list of the largest print jobs
Figure 4.17. Printer report in PDF
Standard reports are provided in a variety of output formats including, HTML, PDF and MS Excel. PDF reports are ideal for printing. HTML versions of the reports are provided for systems without a PDF viewer.
Tip
In addition to the standard reports, administrators can run other reports on ad-hoc data by using the
Export/Print option available under most of the data lists. This is covered further in the subsequent
report section (See Chapter 9, Reports).
4.8.3. Logging
The PaperCut NG activity logging can be classed into the following areas:
61
Quick Tour
4.8.3.1. Usage Logging
Usage logging records information about usage events such as printing. Information includes:
• The date of the use
• Who performed the use
• Details of the type of user including, cost and other attributes
Figure 4.18. Printer usage log
4.8.3.2. Transaction Logging
All modifications or deductions to an account (user or shared) are recorded in the transaction log. Information recorded includes:
• The date of the transaction
• Who performed the transaction
• Any comment or note associated with the transaction (if performed by a user)
Figure 4.19. User account transaction log
4.8.3.3. Application Activity Logging
The Application Log records system events messages such as:
• User logins
• Security errors such as incorrect password attempts
• Backup times and scheduled tasks
• Any system errors or warning
It is similar to the operating system's event log. It is recommended that system administrators view this log on a daily basis for the first week and weekly thereafter.
62
Chapter 5. Services for Users
5.1. Introduction
How a user experiences and interacts with PaperCut NG will vary depending on how it is implemented. When configured as a silent monitoring solution, users may not even know PaperCut NG is in use. In other environments, users will make extensive use of the various services that are available.
Services are provided to users through one of two interfaces: the User Client
The User Client is an optional piece of software that provides additional functionality. The client software may be used to serve a number of purposes including to:
• Display the user's account balance (for print charging or quota environments)
• Display account selection or print conformation popups.
• Show system messages such as "low balance" notifications.
• Display popup warnings as configured by the administrator (e.g. Print policy discourage printing of emails).
• Provide popup authentication services in anonymous desktop environments.
Figure 5.1. PaperCut user client on Mac OS X
The appearance of the user client tool may be customized to fit in with your organization. More information is
popup dialogs) are a function of server-side settings and are configured by the administrator.
the User Web Pages
The User Web Pages provide additional features that may be of use to users. Functionality includes summaries and logs of usage, using TopUp/Pre-Paid Cards, transferring funds and displaying usage costs. The User Web
Pages are accessed either via the Details... link on the User Client window, or via the browser URL http://[server_name]:9191/user
.
63
Services for Users
Figure 5.2. PaperCut user web pages
The appearance of the user web pages may be customized to fit in with your organization's existing intranet,
Figure 5.3. Example of customized user web pages
the iPad / iOS App (for iPad Printing)
64
Services for Users
The PaperCut iPad / iOS App for iPad/iOS Printing enables printing from your iPads enables printing to all your
More information about each of these areas is available in the following sections.
5.2. User Client
The PaperCut NG activity tracking and charging is implemented using 100% server-side technology. User Client software is not required as part of the activity monitoring process.
Note
The use of client software for activity monitoring could open up security problems as client software is readily accessible to end-users. By design PaperCut Software developers endeavor to implement all monitoring at the server level eliminating client-side loopholes. The client software supplied with
PaperCut NG is simply a presentation layer around server-side implementation.
Client software is provided to facilitate four tasks:
• Allow users to view their current account balance via a popup window.
• Provide users with a "last chance" before printing, confirming what they are about to print.
• Allow users to select shared accounts via a popup, if administrators have granted access to this feature.
• Display system messages such as the "low credit" warning message or print policy popups.
Figure 5.4. The user client balance window
Figure 5.5. The user client's confirmation popup
65
Services for Users
Figure 5.6. The user client's standard account selection popup
66
Services for Users
Figure 5.7. The user client's advanced account selection popup
The client software is available for most major platforms including:
• Microsoft Windows
• Mac OS X
• Linux and Unix
Figure 5.8. PaperCut Client on Mac OS X
The client software and deployment tools are installed automatically on the server under the
[app-path]\client directory. On a Windows based server this directory is automatically shared in read-only form providing network users with access to the client executables.
The following chapters contain further information about the user client:
•
Command line and config options are discussed in Section A.5, “User Client Options”.
•
Tip
The behavior of the user client, such as where on the screen it pops up or which option is selected by
default, can be customized. This is discussed in Section A.5, “User Client Options”.
To educate the users about the user client, administrators might find the sample information sheets
helpful.
5.2.1. User Client Deployment
5.2.1.1. Deployment on Windows
The PaperCut NG client software may be deployed to workstations using a variety of deployment methods. The deployment options are covered in detail in the
[app-path]\client\README.txt
file.
Options include:
1.
If you're after a manual "setup wizard" style installer, run the program client-local-install.exe
located in the network share
PCClient
. You can access this share by typing the following address into Windows
Explorer.
\\<MyServer>\PCClient\win
, where
MyServer is the name of the server where PaperCut NG is installed.
2.
Administrators looking for an automated install/deployment option should consider the "zero install" strategy.
This is the recommended strategy for most Windows network environments as it's 100% self-maintaining.
3.
Administrators can also consider deploying via MSI package, allowing the Client software to be remotely
67
Services for Users installed via Group Policy. This option is available for advanced sites which already leverage MSI packages for staged software deployment and continuing with this existing procedure is desirable.
The recommended approach with Windows networks is the "zero install" strategy. This involves configuring the workstations via group policy or otherwise, to run the client executable directly off the
PCClient share - a share set up during installation. This avoids the need to undertake a separate installation process on each workstation and ensures the client software is automatically updated in conjunction with server updates.
The client can simply be run directly from the
PCClient share setup on the server. Two executables provide this launch functionality: pc-client.exe
pc-client-local-cache.exe
pc-client.exe
will launch the client directly off the network share.
The "local-cache" version
( pc-client-local-cache.exe
), is a smarter version that first copies itself and associated files to the local drive and launches itself from there. The local-cache version has the advantage that any future startups will use the local copy and hence minimize network traffic. The cache is self-managing and kept up-to-date ensuring that any new versions of the client are automatically and transparently copied down to the client.
Using pc-client-local-cache.exe
is recommended on large networks. It does however require a globally writable cache directory. By default the cache is created in a directory on the system drive (normally
C:\Cache
). An alternate cache can be specified with the
--cache command-line switch. Administrators should ensure than standard users have write access to the system drive, or manually create the cache directory if required.
The zero-install deployment option is not appropriate for all situations. A local install is recommend on Windows
Laptop systems that are not permanently connected to the network or centrally managed by network administrators.
The client-local-install.exe
program can assist end users with a standard "setup wizard" install process.
Streamlining Installation on Windows” for more details.
The recommended way to launch the pc-client-local-cache.exe
on startup is to add a line to your Domain login script: cmd /c "start \\servername\PCClient\win\pc-client-local-cache.exe --silent"
See below for other automatic start options.
For more information on alternate deployment options see the
[app-path]\client\README.txt
file.
5.2.1.2. Deployment on Windows via Silent Installer MSI
The User Client software is available as a silent-install MSI (no clicks or wizards). This option is available for advanced sites which already leverage MSI packages for automated software deployment and upgrades using
Active Directory Group Policy options. Please note that using the pc-client-local-cache.exe version of the User Client is our recommended method for most deployments, as all updates are automatically pushed to client machines. The
MSI option discussed here must be manually updated.
The MSI package is a great option for organizations managing staged rollouts via Group Policy Filters. It is common in large organizations to progressively roll out new software as a series of small steps, for example the IT department may get the software first, followed by a roll out across the organization.
Important
Ensure these steps are conducted by an administrator experienced with Active Directory MSI software deployment.
68
Services for Users
5.2.1.2.1. Step 1 - Copy User Client files to deployment location
Copy the all client files and subdirectories from
\\servername\PCClient\win\ into a versioned folder on your domain, alongside your other MSI-deployed software, e.g.
\\DeployedSoftware\papercut-client-15.0\
Do not deploy the MSI directly from the PaperCut install directory because the contents of this directory will change when PaperCut is upgraded. This will result in problems in your MSI deployments.
Please take note that unlike some other MSI packages you may have seen, this file is not a self-contained archive it must be copied along with the rest of the PaperCut client files when preparing your deployment.
5.2.1.2.2. Step 2 - Configure the User Client
If you need to make adjustments to the client (such as modifying config.properties
or adding a custom logo), now's the time to do so. Changes made will be distributed to your domain as the MSI deploys.
5.2.1.2.3. Step 3 - Deploy the MSI
Deploy the pc-client-admin-deploy.msi
to your domain, as a Software Installation component to a Group
Policy Object. The procedure for MSI deployment via Group Policy is explained in Microsoft's Knowledge Base: http://support.microsoft.com/kb/816102.
Figure 5.9. Deploying an MSI package as part of a Group Policy
5.2.1.2.4. Step 4 - Configure for auto launch
Configure pc-client.exe to launch automatically at startup, as you would for any other program. One option is to add
69
Services for Users the User Client application to your GPO's
"Run these programs at user logon" setting, found under
Computer/User Configuration
→
Policies
→
Administrative Templates
→
System
→
Logon
Figure 5.10. Configuring a startup application in Group Policy Manager
Tip
If you need to deploy to a heterogeneous environment of 32 and 64-bit systems, the default install paths will be different for each architecture. A simple solution to this path problem is to simply launch the client from both
C:\Program Files and
C:\Program Files (x86) paths, as in the screenshot above. The non-matching path will silently fail.
An alternate option is to start the client from an existing user logon script. An example of the line to add to the logon script is: cmd /c "start "C:\Program Files\PaperCut NG Client\pc-client.exe --silent"
5.2.1.2.5. Prerequisites/Troubleshooting
Older machines may require an upgrade to the Windows Installer Service. If so, you will encounter this error message:
"This installation package cannot be installed by the Windows Installer Service.
You must install a Windows service pack that contains a newer version of the
Windows Installer Package"
To resolve this, download and install the Windows Installer 4.5
Redistributable, from: http://www.microsoft.com/en-us/download/details.aspx?id=8483
5.2.1.3. Upgrade an MSI Installation
70
Services for Users
The procedure for upgrading an already-deployed installation of the client (e.g. from 12.3 to 12.4) is slightly different to that of the initial deployment - updated MSI packages need to be added to your original GPO as an upgrade item.
For step-by-step instructions on the procedure, see http://technet.microsoft.com/en-us/library/cc783421%28v=ws.10%29.aspx
Microsoft's Upgrade Guide at:
Please don't simply replace an old MSI with a newer version. If after following the instructions in the Microsoft article above you're still unsure how to proceed, please seek assistance, or contact technical support.
Figure 5.11. Upgrading an MSI package as part of a GPO
5.2.1.4. Windows 8 Metro Requirements
Windows 8 a introduced a new user interface called Metro. It has a tile based start screen or runs one application at a time. This user interface is also known as the "Windows 8-style UI".
When the Windows 8 user interface is in Metro mode, Windows Desktop applications are not visible. This includes notifications such as the PaperCut Client popup. Therefore the Client popup could be missed.
PaperCut uses a Toast notification to notify user in Metro mode that a notification requires their attention in Metro mode.
Figure 5.12. Toast Notification (panel at top right) in Metro Mode
71
Services for Users
With the Toast notification, users working in metro mode will be notified of all PaperCut activities that require their attention in Desktop mode.
5.2.1.5. Deployment on Mac OS X
This section covers the installation of the PaperCut client on Apple Mac systems. Before installing the client
working as expected.
The PaperCut Mac client is a supplied as a native Mac
.app
package. The client is delivered in two flavors:
1.
The current client, which supports Mac OS X 10.7 (Mountain Lion) and above.
2.
The legacy client, which supports Mac OS X versions from 10.4 to 10.6. It is a universal application that runs on both PowerPC and Intel hardware. The legacy client will not be receiving future feature enhancements.
The three common installation methods are outlined below cover most situations. The instructions for the "single user install" follow the standard Mac application installation process and should be able to be conducted by any Mac end-user. The other installation methods are more technically focused and aimed at Mac network administrators.
5.2.1.5.1. Special Notes for Mac OS X 10.6 and earlier
Note
The current version of the PaperCut client will not work on Mac OS X 10.6 and earlier. For these systems the legacy client must be used. If the client fails to start, please ensure you are using the correct client for your system.
The legacy client is found in
[app-path]/client/legacy
. Use this path to locate the client when referenced in the following sections.
The legacy client software will work best if Java 5 (or higher) is installed. Java 5 is available for OS X 10.4 or above.
If Java is not already installed, the installer is available from the Apple website. This simplest way to install Java is to run /Applications/Utilities/Java Preferences from OS X Finder, and you will be prompted to complete the installation.
5.2.1.5.2. Single User Install
This method is suitable for a Mac computer used by a single user. For example, a personal Mac desktop or laptop.
The installation process simply involves clicking on the client-local-install program. This copies the
PCClient application into the over to the system's
Applications folder and starts the client in the "confirm network identity" mode. The simplest way to run the install process is to connect to a Windows server's pcclient share over the network, however alternate methods such as copying the folder contents via a USB key or drive are also possible.
To install the Mac client from a server's share:
1.
Start and Log into the Mac computer. Ensure it's connected to the network.
2.
Open the Finder.
3.
From the Go menu, select Connect to Server....
72
Services for Users
Figure 5.13. Connecting to a Windows server
4.
Enter the pcclient share's connection details like: smb://server_name/pcclient
.
Figure 5.14. The PCClient share's connection string
5.
Enter password information if requested.
6.
Double-click the client-local-install file. This will execute a small AppleScript program that will commence the install/copy process. (If installing on a legacy system (OS X 10.6 or lower) you must install the legacy client located in the legacy folder.)
7.
Test the application by double-click on the
PCClient application icon in the system's local
Applications folder.
If the user needs the client for printing - for example to use the shared account popup - it's advisable to configure the application to automatically open upon start-up:
1.
Open System Preference... from the Apple menu.
2.
Select Accounts.
3.
Select your login account.
4.
Click the Login Items tab.
5.
Click the
+ button and browse and locate the
PCClient application.
73
Services for Users
Figure 5.15. Add PCClient as a Login Item
6.
Test by restarting the computer. The client should start automatically after the reboot and login procedure is complete.
5.2.1.5.3. Multi-User Install
On a multi-user Mac system, setting up a Login Item for each user would be a tedious task. To streamline this process, the
PCClient application can be configured to start on login via the login hook. A login hook is an advanced Mac feature that works by running a script when a user logs in. The
PCClient package includes a command script resource that installs the login hook.
To install the client on a multi-user system:
1.
Start and Log into the Mac computer. Ensure it's connected to the network.
2.
Open the Finder.
3.
From the Go menu, select Connect to Server...
4.
Enter the pcclient share's connection details like: smb://server_name/pcclient
5.
Enter password information if requested.
6.
Drag the
PCClient
(or legacy/PCClient on OS X 10.6 or lower) package over to the local hard disk's
Applications folder. The copy process will commence.
7.
Control-click on the newly copied
PCClient application in the Applications directory. Select Open Package
Contents.
74
Services for Users
Figure 5.16. Control-click and open the package contents
8.
Navigate to
Contents/Resources/
.
9.
Double-click on the install-login-hook.command
script.
Figure 5.17. Double-click to install the login hook
10. Restart the system and verify the client starts on login.
Important
If you're already using a login hook for other script tasks, the setup process will be different. Instead in step 9, double-click on the set-permissions.command
file. Then insert the following line at the end of your current login script (all on one line):
/Applications/PCClient.app/Contents/Resources/login-hook-start
"$1"
The set-permissions.command
script ensures the software is set up with the correct permissions, ensuring it's accessible to all users.
The login hook, once installed, can be removed with the terminal command:
75
Services for Users sudo defaults delete com.apple.loginwindow LoginHook
5.2.1.5.4. Zero-Install Deployment
This deployment method is for advanced Mac network administrators and is suitable for medium to large Mac networks. Knowledge of the Mac's Unix underpinning and scripting is required.
A more flexible option over locally installing the
PCClient package on each Mac system, is to directly launch the client from the pcclient share. The advantage of this deployment method is that any updates applied on the server (and hence updates to the client directory) will automatically be propagated to all workstations.
The process of setting up zero-install deployment will vary form network to network depending on the directory environment in use and administrator preferences. The process can however be summarized as:
1.
Configure the Macs to mount the pcclient share as a volume on login or start-up.
2.
Configure a login hook to start the client off the share. The install-login-hook.command
resource script explained in the multi-user install above may help.
The typical way to mount the share is to use mount_smbfs in a boot script. See the Apple documentation on mount_smbfs at: http://developer.apple.com/documentation/Darwin/Reference/ManPages/man8/mount_smbfs.8.html
Further information on Mac printing is available at Chapter 29, Mac Printing in Detail.
5.2.1.6. Deployment on Linux and Unix
The PaperCut NG user client software may be deployed on Linux and other Unix based operating systems using the following installation procedure.
5.2.1.6.1. Step 1 - Install Java 5.0+
Linux and Unix workstations are supported via Java. Java version 5.0 or higher is required. Your Linux distribution may come with Java pre-installed or have the option to install. If no Java option exists, Sun Microsystems provides a self-install Java distribution for Linux and other major Unix platforms.
Ensure Java 5.0 is installed and the
JAVAHOME environment variable is defined on the
PATH
.
5.2.1.6.2. Step 2 - Copy (or Mount) the PaperCut NG user client files
Like the Windows version of the client software, the Linux/Unix Java version is installed in the
~/client directory on the server. All files in this directory need to be copied, or make available to the Linux/Unix workstation. Common methods include:
• Copying the files from the server using file transfer programs such as FTP or scp.
• If the server is Windows based, connecting using smbclient or the Gnome or KDE smb:// file browsing tools.
The client files are shared via a read-only share called
\\[server_name]\PCClient
.
• If the server is Linux based, consider exporting the
~papercut/client directory via NFS and mounting on the workstations. The client can then be ran directly from the mount.
If the workstation is used by multiple users, the client directory should be copied to a common location such as
/usr/local/papercut/client
.
5.2.1.6.3. Step 3 - File permissions
Open a command prompt and set execute permissions on the pc-client-linux.sh
file as follows:
76
Services for Users cd /usr/local/papercut/client chmod 755 ./pc-client-linux.sh
5.2.1.6.4. Step 4 - Testing
Log on as a user (a user listed in the PaperCut NG system) in your preferred Linux desktop GUI environment.
Locate and execute the file
/usr/local/papercut/client/pc-client-linux.sh
. The PaperCut NG client should open displaying the user's account balance.
It is usual to configure the client as a "Startup Program" or "AutoStart Program" launched during login. See your desktop documentation to see how to define a startup program.
A number of command-line options are available to change the client's behavior. More information can be found in
Table A.2, “User Client command-line options”.
5.3. User Web Pages
The User Web Pages are accessed either via the Details... link on the User Client window, or via the browser URL http://[server_name]:9191/user
.
The User Web Pages provide a range of services for users, including:
• Summary: A summary of usage and balance history.
• Shared Accounts: Lists the shared accounts that the user may use for printing.
• Rates: The current costs for printing usage.
• Use Card: Add balance by using a TopUp/Pre-Paid Card.
• Add Credit: Add balance from an external payment system (when using the payment gateway module).
• Transfers: Transfer funds to other users.
• Transaction History: A history of balance transactions.
• Recent Print Jobs: A list of the user's recent printing.
• Jobs Pending Release: Print jobs pending release (when using a release station).
The services available provide a range of functionality that empowers users to make the most of PaperCut NG without requiring intervention from administrators. The user web pages allows users to do what they need for themselves, and quickly get back to what they were doing.
Many services can be switched on or off as required. This is useful for situations where a particular service is not suitable for exposing to the users. For example, some organizations may like to disable the ability for users to transfer funds.
Each service is discussed in the following sections.
5.3.1. Summary
This page provides a summary of the information most important for a user, including their current balance, a summary of their printing usage, and a graph of their balance history.
77
Services for Users
Figure 5.18. A user's summary information
5.3.2. Environmental Impact
One of the primary aims of PaperCut NG is to reduce printing levels by changing a user's printing behavior.
Implementing monitoring, quotas and charging are a good way of drawing a user's attention to their habits. The topic of the environment, global warming, and waste management is currently an area of debate and interest to many.
Highlighting the environmental aspects of their activities is another good way of modifying a user's behavior.
The Environmental Impact section appears on the Summary page and provides the user with feedback on the environmental impact or footprint associated with their activities. Information presented includes an indication on how their printing equates to trees, CO
2 emissions and energy.
this option can be disabled via the Options section.
Figure 5.19. Draw a user's attention to their environmental impact
5.3.3. Shared Accounts
Shared accounts page lists the balances of the shared accounts that a user can access.
78
Services for Users
Figure 5.20. A list of available shared accounts
More information about shared accounts can be found in Chapter 8, Shared Accounts.
5.3.4. Rates
The rates page lets users know the printing costs associated with each printer. Displaying costs to users is a good way for them to see and understand the costs involved without having to spend time distributing the information to them.
Armed with this information, users can seek the most cost effective way to manage their printing. With discounts for grayscale and duplex printing clearly visible, ink and paper usage will be reduced by the users own accord.
Figure 5.21. Printing costs as seen by the user
5.3.5. Use Card
From here users can use a TopUp/Pre-Paid Card. When a valid card number is entered, the value of the card is
79
Services for Users
Figure 5.22. Using a TopUp/Pre-Paid Card
5.3.6. Add Credit
The Add Credit page is used to transfer funds into a user's account from an external source. This option is available when using the payment gateway module for integration with an external system.
5.3.7. Transfers
This page allows users to transfer credit to other users. Transferring balance can be useful in situations such as:
• A student transferring credit to a fellow student for printing something for them
• A teacher transferring credit to a student for extra printing
• Teachers trading printing credit between each other
Figure 5.23. Transferring funds to another user
5.3.8. Transaction History
The transaction history page displays a user's balance history in detail. Here a user can see how, when any why their balance was affected. If there is ever doubt about why a user's balance is at the current amount, or what they have been spending their credit on, the transaction history page has the answer.
Figure 5.24. A user's recent balance transactions
5.3.9. Recent Print Jobs
This page displays the user's printing history. It allows a user to see the cost of their print jobs, or to find a particular print job. The filter criteria allows for many different views of printing, and can be used to easily drill-down to find the
80
information required.
Services for Users
Figure 5.25. A user's recent printing
5.3.10. Jobs Pending Release
This page allows users to view and interact with jobs held in a hold/release queue. From here, jobs that have been held in a managed queue can be released (printed) by the user. This allows for them to confirm the cost and details of the job before printing, and/or confirm their identity before the job is released.
Figure 5.26. The user's view of jobs pending release
81
Services for Users
5.3.11. Web Print
Web Print is a printing solution ideal for laptops and other non-domain connected systems. This page allows users to upload documents for printing, rather than requiring the print queues to be installed on their system.
The user will be guided through a wizard where they can select a printer, choose options such as number of copies, and select a document to upload. The document will then be queued for printing and the user can track its status from this page.
Figure 5.27. Web Print jobs in progress
5.4. Environmental Dashboard / Windows 8.1 Live Tiles
One of the most powerful features in PaperCut is not actually a feature at all - it’s the culture change that it brings about in an organization. Most of this change is encouraged by increasing the visibility of the impact printing has on the company and the environment. The Environmental Dashboard and the Windows 8.1 Live Tile is an innovative way to raise awareness. It promotes paper saving in a positive and creative way. For example:
• See your environmental impact front and center
• Benchmark your usage against others in the organization
• Reward and promote good user behaviour:
• Award users for printing less
• Encourage the user of duplex and grayscale
• It makes printing impact tangible and understandable:
• Converting sheets into an "energy equivalent"
• Emphasising forest conservation
• Highlighting CO
2 emissions
82
Services for Users
Figure 5.28. Environmental Dashboard
Figure 5.29. Windows live tile sample
5.4.1. Windows 8.1 Live Tile
The increasing use of Windows 8 devices and Tile based interface has opened up a new avenue to communicate to users. The Environmental Dashboard page can be Pinned to the Windows Start Screen to create a dynamic Live
Tile. This Live Tile will communicate over 20 user-specific facts, awards and challenges all generated from real-time
PaperCut data.
5.4.1.1. Sending a positive message with the Live Tile
All too often, the IT department is implementing back-end systems or invisible projects. The PaperCut Windows Live tile is a highly visible and positive story, and is a great complement to other changes planned in your print management program.
Tip
Recently PaperCut was working with a large national retail organization and they were in the middle of a project to implement PaperCut’s secure print release. There was push-back from various department
83
Services for Users heads worried that any barriers to printing were going to reduce productivity. The environmental impact statistics helped turn this reluctance around. In the end, the savings were so compelling the project’s success was promoted not only internally but externally as a strong corporate and social responsibility story... Oh, and for once the IT guy was the hero!
Some suggestions:
• Encourage your users to bookmark their dashboard
• Draw Windows 8.1 users attention to the Live Tile and encourage them to Pin it to their start page. See
Section 5.4.2, “Windows 8.1 Live Tile Installation”.
• Link to the Environmental Dashboard on your intranet or monthly newsletter
• Share environmental impact information visually with management
• Challenge users to compare their live tile awards with their colleagues
5.4.1.2. Windows Live Tile Examples
Below is a small sample of the 20+ tiles available:
Figure 5.30. Tile sample: 5 stars
Figure 5.31. Tile sample: Organization C0
2 use
Figure 5.32. Tile sample: Organization tree consumption
Figure 5.33. Tile sample: Organization weekly printed sheets
84
Services for Users
Figure 5.34. Tile sample: Tip to use grayscale
Figure 5.35. Tile sample: User energy use
5.4.2. Windows 8.1 Live Tile Installation
To pin the environmental live tile on the Windows 8.1 Start Screen:
1.
On Windows 8.1, go to the Start Screen (Press the Windows key).
2.
Open Internet Explorer in the Start Screen. (NOTE: Internet Explorer must be configured as the default browser to complete the pinning process).
3.
Enter the URL below (where
[server-name] is the hostname of your application server.) http://[server-name]:9191/environmentaldashboard/
4.
Enter your network username/password. After successful login you will be taken to the Environmental
Dashboard showing your usage statistics.
5.
Press the favorites button.
6.
Press the pin button.
7.
Press the Pin to Start button.
8.
Press the Windows key to go back to the Start Screen. The Environmental Dashboard will now be pinned to the
Start Screen. Clicking on the live tile will open the Environmental Dashboard.
After a short period the live tiles will start displaying. Five distinct live tiles will rotate displaying your environmental usage statistics, ratings, tips, etc. A new set of five tiles will be retrieved every 30 minutes.
Tip
Although Windows usually starts displaying the live tiles after a short delay, sometimes it takes a few minutes for them to activate. If the live tiles are not displaying, changing the tile size can kick it into action. To do this, right-click the tile, select the "Resize" option from the bottom and select a different size. Then change the size again back to the "Wide" tile format.
85
Services for Users
Important
The Environmental Dashboard will show user level environmental information by default. If you do not wish user level information to be available, you can turn it off by unchecking the
Show environmental impact information checkbox found in the administration interface under
Options
→
General
→
User Features. When this option is off, only organization wide environmental stats are shown in the live tiles and dashboard.
5.4.2.1. Windows 8.1 Tile Deployment
Windows 8.1 is a new environment and there are very limited options to automatically deploy the live tile through the organization. We are hopeful that Microsoft will introduce improved tooling for this deployment as Windows 8.1
evolves.
Our current recommendation is to provide instructions to your users instructions on how to access the
Environmental Dashboard and install the live tiles on Windows 8.1. These instructions could be provided in an email
Tile Installation” and Section 5.4.3, “Using Environmental Dashboard on other browsers/platforms”.
5.4.3. Using Environmental Dashboard on other browsers/platforms
The Environmental Dashboard displays interesting environmental impact and printing statistics for the user and organization. The Dashboard is is useful to all users and can be accessed using any web browser running on any platform.
The simplest way for to access the Environmental Dashboard is to open their web browser to:
1.
Open a web browser to the following URL: http://[server-name]:9191/environmentaldashboard/
2.
Enter their network username/password. After successful login you will be taken to the Environmental
Dashboard showing your usage statistics.
Tip
An alternate way to access the dashboard is to open a browser to the following URL (replacing
[username] with their username): http://[server-name]:9191/environment/dashboard/[username]/
This URL could be linked from the organization's intranet site if the user's username is known.
5.5. Mobile User Web Pages
When the user web pages are accessed from a mobile browser (e.g. Mobile Safari from an iPhone) the user will be presented with a lightweight interface that has been optimized for smaller screen sizes.
86
Services for Users
Figure 5.36. Mobile user web tools - summary page
The user may choose to view the user web pages in desktop mode instead by clicking View in Desktop mode.
Figure 5.37. View in Desktop mode link
Features available in the mobile user web pages include:
• Checking user balance
Figure 5.38. Mobile user web tools - balance
• Viewing environmental impact statistics
Figure 5.39. Mobile user web tools - environmental impact statistics
• Redeeming a TopUp/Pre-Paid Card
87
Services for Users
Figure 5.40. Mobile user web tools - redeem TopUp/Pre-Paid Card
Figure 5.41. Mobile user web tools - entering a TopUp/Pre-Paid Card number
For more information about the full (desktop) user web pages see Section 5.3, “User Web Pages”.
5.6. Gadgets/Widgets and more...
Gadgets/Widgets are a lightweight application that sits on a user's desktop. Some versions of Windows (for example
Windows Vista and Windows 7) have in-built support for sidebar gadgets. The equivalent on the Mac is the Widget.
PaperCut NG offers three useful Gadgets as well as a series of AJAX/JSON style embeddable components that can be leveraged by intranet developers.
5.6.1. Paper-Less Alliance Widget
PaperCut has teamed up with Do Something, the non-profit organization behind many environmental initiatives including Save Paper (http://savepaper.com.au/category/save-paper/what-software-to-get). The Desktop Widget, developed in Adobe Air works off the data in PaperCut. It is designed to help organizations reduce paper in a fun positive way. Highlights include:
• Draw user's attention to their environmental impact upon login
• Allow users to compare/benchmark their usage with the company/organization average
• Highlight facts fun about the environment and paper use
• Support a non-profit organization leading the paper reduction initiative
To download the widget, visit: http://www.papercut.com/products/save-paper-widget/
88
Services for Users
Figure 5.42. The Paper-Less Alliance Desktop Widget
Note
Organizations deploying the widget are asked to make a small donation of less than $1.00 a user to the Paper-Less Alliance. All proceeds go to the non-profit supporting paper saving initiatives and awareness.
5.6.2. Windows Gadgets
Two small footprint Windows Gadgets are available:
• The Print Balance Gadget: Used to display user's personal balance on the desktop or sidebar. This is called
PCBalance.gadget
.
• The Environmental Impact Gadget: Used to provide the users with feedback on the environmental impact associated with their printing activities. Highlighting the environmental aspects is useful in modifying a user's behavior towards printing. For more information about how these values are calculated, see the section called
Section 15.8, “Environmental Impact”. This gadget is called
PCEnvironmentalImpact.gadget
.
89
Services for Users
Figure 5.43. The Environmental Impact Gadget
Figure 5.44. The Print Balance Gadget
To install a Gadget:
1.
Log in as administrator
2.
Browse to the share on the PaperCut NG server at
\\server\PCClient\win\Gadgets
3.
Copy all
*.gadget
folders to the local directory
C:\Program Files\Windows Sidebar\Gadgets
4.
Users should now see the PaperCut NG Gadgets as available Gadgets on the system.
5.6.3. Web Widgets
PaperCut NG also provides web widgets that can be easily embedded within pages on your intranet site. These widgets work in a similarly to Google Web Gadgets or the Google Maps APIs. All that is required is to paste a few lines of HTML/JavaScript on your pages. There are two built-in web widgets that offer balance and environmental impact (and look identical to the Vista widgets above). However if the built-in widgets do not suit your needs you can create your own that better suit your site.
There are only two requirements to running web widgets on your intranet site:
1.
You require edit access to the intranet pages to add the required HTML/JavaScript.
2.
The username of the logged in user is required so the web widget knows whose details to load. This will usually require that users login to the intranet. When using a Microsoft Active Directory domain and Microsoft IIS web server the user can be automatically detected if using NTLM or Kerberos authentication which provides a transparent login process via the Web Browser.
The simplest way to get started with web widgets is to look at some examples. There are detailed and well commented examples available on the PaperCut NG server in the directory
[app-path]/server/examples/webwidgets/examples.html
. These examples should be used as a starting point to implement web widgets on your site.
The basic steps to adding a web widget to a page are:
1.
Add a
<div> element to your page. The widget will be drawn within this tag. The div element must be given a
90
Services for Users unique
ID
.
2.
Include scripts into your page to load the widget and user data from the PaperCut NG.
3.
Edit the included script to set pcUsername to the logged in user.
4.
Edit the included script to set pcServerURL to base URL of the PaperCut NG server.
5.
Add some script to draw the built-in widgets to the page. You can use one of the built-in widgets, or create your own.
91
Chapter 6. Advanced User Management
This section covers some of the more advanced user management tasks. On large networks managing users on an individual basis is not practical. Management needs to be handled either via a level of automation, or manually at group level. Some common user management tasks that typically consume time on a large network include:
• Creating new user accounts
• Allocating user credit or quotas.
• Performing administration tasks such as allocating additional allowances or applying different privileges.
• Generating or allocating card/ID numbers for users
PaperCut NG offers a number of features to help automate these tasks.
6.1. Groups in PaperCut NG
Groups are collections of users. PaperCut NG uses the network domain or computer's groups, meaning administrators can take advantage of the existing network structure. Groups in PaperCut are used in the following ways:
1.
To control how quota/credit is allocated to users on a regular basis.
2.
To automate the addition of new (future) user accounts.
3.
To assist with making modifications to user accounts by group.
4.
For group based reporting.
PaperCut NG mirrors (caches) domain network group memberships for performance reasons. Hence changes in group membership made at the domain level may not be immediately reflected in PaperCut. The group membership can be refreshed at any time via the User/Group Sync option under the Options section. Groups are mirror/cached for two reasons:
• For fast reporting and search performance.
• To ensure PaperCut NG is a good network application and does not overload domain controllers with group membership requests.
Many large networks may contain hundred of groups and/or organizational units. In many cases only a small percentage of these groups are pertinent to PaperCut NG management. To ensure administrators are not overwhelmed with all groups, PaperCut NG only lists the groups selected as relevant by the administrator.
To add a group to PaperCut NG:
• Navigate to the Group section.
• Select the Add/Remove Group link at the bottom of the groups list.
• Select the group(s) required on the left-hand-side and click the Add arrow.
• Click the OK button to add the group(s).
92
Advanced User Management
Figure 6.1. Adding/removing groups
PaperCut NG includes one built-in group called the
[all users] group. This group is not related to any existing network group and simply is a "catch all" group that represents all users list in the PaperCut system. It is similar to the "Everyone" special group in Windows.
Note
PaperCut NG sources groups and group members from your selected directory/domain source. There are however some situations where maintaining groups within the network directory source is not possible. For example, may you only have read-access to the domain. If for technical reasons it's not possible to define the required groups in your network directory, groups may also be defined via a text file (e.g.
a tab-delimited file).
Simply place your group definition file at the location
[app-path]/server/data/conf/additional-groups.txt
.
See the template file additional-groups.txt.tmpl
in the same directory for an example and further information.
The additional-groups.txt
may also be used to manage an internal user's group memberships.
6.2. Setting up quota allocations
In many organizations PaperCut NG is used to control and restrict users to sensible use by allocating a quota or allowance (a budget). For example a user may be allocated $10.00 a week. This type of control is particularly popular in schools and universities. The process of quota allocation can be automated via the Groups section.
To allocate a $10.00 a week to members of the Students group:
1.
Navigate to the Groups section
2.
Add the
Student group via Add/Remove Groups if not already listed.
3.
Select the Student group
4.
Under the Quota Scheduling section, select a period of Weekly and enter
10.00
in the Schedule amount.
5.
Click the Apply button to save the change.
93
Advanced User Management
Figure 6.2. The Group Details screen
To configure quotas correctly it is important to understand how quota allocations work. Users receive quotas for all groups they belong to. For example, consider the situations where
Students and
Student Newspaper groups are defined in PaperCut NG, with $20/month and $10/month quotas respectively. If a student belongs to both groups they will receive a $30/month of quota. If they belong to only the
Students group they will receive only $20/month.
If you configure a quota on the special
[All Users] group then all users in the system will receive this quota in addition to quotas defined on other groups.
Credit will be assigned to group members at just past 12:00am (midnight) on the day of the schedule. Administrators can verify that this has taken place by inspecting log entries in the Application event log and/or users' transaction logs.
Task
Daily Allocations
Weekly Allocations
Monthly Allocations
Custom Allocations
Table 6.1. Quota schedule times
Time
Applied at
12:10am every day (7 days a week).
Applied at 12:20am on Sunday.
Applied at
12:30am on the first day of the month.
Applied at
12:10am on the given day (after the daily allocations).
One potential issue associated with quota allocation in some organizations (for example Schools or Universities) is that users can "bank up" their quota allowance over time leading to excessive use at periods of the year such as the end of semester. The Only allow accumulation up to option can be used to implement a "use it or lose it" policy!
6.2.1. Custom Quota Scheduling Periods
In some cases quotas may need to be scheduled for unusual times. A good example of this is unusual term or semester start dates. The
Custom quota scheduling period allows specifying any date for which to run quotas. To set a custom quota scheduling period:
• Select the group for which to allocate quotas
• Under the Quota Scheduling section, select a Period of Custom.
• Enter a date in the ISO international date format
YYYY-MM-DD
(e.g.
2007-03-15
). Multiple dates may be entered, separated by a comma (e.g.
2007-03-15,2007-08-20
).
* wildcards are supported.
94
Advanced User Management
• Click the Apply button to save the change.
Tip
The year may be omitted or replaced with a
* wildcard to specify that quota allocations should take place on the same date every year. The same is true for months.
For example, entering
*-03-15 or
03-15 will result in quotas being allocated on March 15th every year.
Entering
*-*-15 will result in quotas being allocated the 15th of every month of every year.
6.2.2. Advanced User Quota Management
Some organizations may require scheduling quota allocations for periods other than those available above. For example, an education organization may like to schedule quota allocation per term, semester (period) or academic year, which may not have set dates. This can be achieved by a manual update when necessary though Bulk user
6.2.3. Automated Quota Allocation Example
One way to automate quota allocation is through the use of Server Commands. Following is an example of how to use Server Commands to automate quota allocation in a Microsoft Windows environment:
North Shore High would like to automate their quota allocation on a per-term basis. There are four terms in a year, and terms do not necessarily start on the same date every year. Junior students are to receive $5 per term printing budget, and senior students are to receive $10 per term. The domain has the groups junior-students and senior-students to reflect the students' grade.
Command adjust-user-account-balance-by-group will meet the needs of this situation. Create a batch file with a name like assign-term-quotas.bat
with content similar to the following (depending on your environment): cd "C:\Program Files\PaperCut NG\server\bin\win" server-command adjust-user-account-balance-by-group "junior-students" \
+5.00 "$5 term budget for junior students" server-command adjust-user-account-balance-by-group "senior-students" \
+10.00 "$10 term budget for senior students"
Note: backslash indicates text should appear on the same line.
Running this script will allocate $5 to all members of the group junior-students
, and $10 to all members of the group senior-students
. The script can then be scheduled to run at the specified dates by the use of a tool such as Windows Task Scheduler ( Control Panel
→
Scheduled Tasks
→
Add Scheduled Task).
This example can be found with your PaperCut NG
[app-path]\server\examples\scripting\batch\assign-term-quotas.bat
.
installation under
6.3. New User Creation Rules
It is inevitable that new users will be added to your network in the future. To streamline account setup, PaperCut NG offers the option of having new users automatically assigned initial settings such as starting credit, privilege level, and other settings based on their group membership. Users are automatically added to PaperCut NG when either:
95
Advanced User Management
• The user sends his or her first print job
• Overnight during user/group synchronization
• When a manual user/group synchronization is performed
• When a user logs in (i.e. authenticates) to the user client, release station or user web pages
Taking the time to configure initial settings rules means one less job for administrators to perform! The group based control offers maximum flexibility and ensures that it's possible to have a different set of initial settings rules for different types of users. This flexibility is particularly important in an academic environment where students of different year levels need different settings.
For example an administrator may wish for new users belonging members of the
Senior Students group to be allocated $10 starting credit and restricted access, while all other students receive $5.00 starting credit.
New user creation rules are controlled under the Groups
→
Group Details
→
New User Settings section. When a new group is added it does not provide any new user settings. To enable user creation rules for a group the Use
this group to define new user settings option must be enabled.
Figure 6.3. Initial settings applied to new users
Important
Changes made to new user settings are in the Groups section only affect users NOT yet listed in the system. (i.e. future users). Any users already listed in the system are not affected. Initial user settings also do not apply when users change groups. To modify settings or credit on existing users, see Bulk
user actions in the following section.
Tip
Initial settings can become confusing when a user belongs to more than one group. PaperCut NG uses the following logic to allocate initial settings:
• The user obtains a starting credit that is the sum of all the matching groups (the special
[all-users] group is ignored).
• If any of the matching groups has unrestricted access, the user will inherit unrestricted status.
• If any of the matching groups has account selection popup settings, the user will inherited the ON settings.
• If the user does NOT belong to any group with new user settings defined, they will inherit the settings applied to the special
[all-users] group.
96
Advanced User Management
• The initial settings are applied from each group in alphabetical order. So for settings that cannot be merged (e.g. charge to single shared account) the last group alphabetically will take precedence.
Tip
To control when users are automatically created, see Section 15.3.6, “On Demand User Creation”.
6.4. Bulk User Operations
A bulk user operation refers to an operation that is applied to more than one user. This operation was referred to in previous PaperCut releases as "Group level functions". Bulk operations can be performed on a user group or a comma separated list of users. Bulk user operations are best described by example.
6.4.1. Example 1: Bulk operation on a user group
John is a network administrator at a local high school. A number of students from each year level have been placed on the school newspaper committee. The head teacher has requested that John allocated an extra $10.00 of printing credit to these students. The students are all in a network group called "NewspaperCommittee". John performs this operation as follows:
1.
Clicking the Bulk user actions link under the Users section.
2.
Selecting NewspaperCommittee as the group to perform the action on.
3.
Selecting the Adjust credit by option and entered $10.00 in the amount field.
4.
Entering a transaction comment of "extra allowance for newspaper committee role".
5.
Clicking the OK button to apply the change.
6.4.2. Example 2: Bulk operation on an ad-hoc list of users
Now, John wants to add $10.00 credit to a list of users he has saved in a Excel spread sheet. John will need to perform this operation as follows:
1.
Clicking the Bulk user actions link under the Users section.
2.
Change the Perform operation on users to in the list.
3.
Cut and paste the list of names from the spread sheet. This would generate a comma separated list of usernames.
4.
Selecting the Adjust credit by option and entered $10.00 in the amount field.
5.
Clicking the OK button to apply the change.
6.4.3. Additional information
Bulk user operations apply changes to all users matching the selected group and other criteria. Settings under the
Groups section or shared accounts are not affected.
Warning
Group level operations are one-way and cannot be undone. Always carefully consider the operation before proceeding. If you are unsure of the function or behavior, performing a backup prior to undertaking the operation is advised.
97
Advanced User Management
Other bulk user operations available under Bulk user actions include:
• Adjust or set the users' credit (perform a transaction).
• Change the users' restriction status
• Modify account selection popup options
• Reset the users' count statistics
• Apply user level overrides like print cost adjustments, and disabling printer filters for a user
• Disable printing for a specified period of time
• Generate new card/ID numbers for users who don't have one
6.5. Using Overdrafts
The overdraft setting applies to restricted users (and restricted Shared Accounts). An overdraft allows a user to continue to use services even though their account has dropped below zero. In essence, the overdraft value moves the "zero-point" allowing users to overdraw the account to the agreed limit. An overdraft can also be referred to as a credit limit.
Reasons for using an overdraft include:
• Provide users with flexibility between budget, quote or allocation periods. For example, an overdraft will allow a user to "draw on" a portion the next month's quota allocation.
• To Implement a credit system with credit limits rather than an up-front pay system.
• Grant trusted users a "loan" on a case-by-case basis.
An overdraft can be defined at two levels:
1.
Globally as a default affecting all users and shared accounts.
2.
On an individual user or account basis.
The default overdraft is zero. This can be changed by Options
→
General
→
Account Options
→
Default overdraft limit
Optionally, a separate overdraft can be applied to an individual user (or shared account) using the following procedure:
1.
Click on the Users section.
2.
Select the user.
3.
Ensure the account is set as Restricted.
4.
In the Overdraft field, select the option Individual overdraft.
5.
Enter a positive value in the adjacent overdraft balance field.
6.
Click Apply to save the changes.
Figure 6.4. Setting a user's overdraft to $20.00
98
Advanced User Management
6.6. Batch User Data Import and Update
The user data batch import and update feature allows the administrator to import users, user information and optionally update existing users details by reading data from a simple text file. It enables administrators to update the following user data:
• Credit balance
• Restriction status
• Full name
• Email address
• Department
• Office
• Primary Card/ID Number
• Card/ID PIN
• Notes
• Secondary Card/ID Number
• Other email addresses
• Username alias
Examples of where the batch user details import feature is useful include:
• To set the user email addresses that are stored in another system (like a student management system).
• When importing user and balance data from another external or legacy system.
• When moving user balances from previous PaperCut editions to PaperCut NG.
For more information on using the batch import to import data from previous PaperCut editions, please see
Appendix G, Upgrading from PaperCut Quota.
Tip
PaperCut NG is designed to import user information from the underlying system or network domain.
The batch user data import feature is not designed to replace this but rather complement it by allowing importing of user data from other systems our sources. For information about managing a set of users
To perform a batch import:
1.
Manually inspect your file in a text editor and ensure it's in the prescribed tab-delimited format as detailed at
Section 6.6.1, “Batch User Import File Format”.
2.
Navigate to the Users section.
3.
Click the Batch import ... action (on the left).
4.
5.
Choose whether you want the import to create new users if they do not already exist. If you clear this checkbox, lines that contain users that do not exist will be ignored and only existing users will be updated.
6.
Press the Import button.
7.
Upon completion you will be told how many users were updated and how many users were created.
99
Advanced User Management
Caution
Batch imports are a major operation modifying data en masse. Best practise suggests:
• Always run a backup before proceeding with the import.
• First experiment/test the import process with a small batch of users before moving onto the full batch.
6.6.1. Batch User Import File Format
The import file is in tab delimited format and contains the following fields in the given order.
No.
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
Field
Username
Credit Balance
Restricted Status
Full Name
Department
Office
Card/ID Number
Card/ID PIN
Notes
Secondary Card/ID Number
Other email addresses
Username alias
Description
The user's username
The user's credit balance
Optional?
Limitations
Mandatory Max. 50 characters
Optional - balance not set if blank
A number with no currency symbol or separators, using a full stop for the decimal separator.
Correct:
1.23
Incorrect:
$1.23
or
1,23 or
1,023.00
The user's restricted status.
(Y/N)
Optional - restricted status not set if blank
The user's full name Optional - full name not set if blank
Max. 255 characters
The user's email address Optional - email not set if blank
Max. 255 characters
The user's department or faculty
Optional - department not set if blank
Max. 200 characters
The user's office or location Optional - office not set if blank
Max. 200 characters
The user's identity/card number primary Optional - card/id number not set if blank
Max. 100 characters, case insensitive
The user's card PIN number
Notes about the user.
Optional - card/id PIN not set if blank. If the field is '-' then the PIN is set to zero.
Max. 20 digits
Optional - notes not set if blank
Max. 2000 characters
The user's secondary identity/card number
Optional - secondary card/id number not set if blank
Max. 100 characters, case insensitive
The user's other email addresses
Optional other email addresses not set if blank
Email addresses must be separated by commas
The user's alias. Only useful if username aliasing is enabled
Optional - alias not set if blank
Max. 100 characters, case insensitive
Table 6.2. User Import File Format
Other limitations: Although any actual limit to the size of an import file should be large enough for any purpose, we recommend keeping the file size below 10MB.
100
Advanced User Management
Tip
A simple way to create a tab delimited file is to create a spreadsheet in Microsoft Excel, and then save it in the
Text (Tab delimited) format.
6.6.1.1. Import File Format Examples
The following lines shows importing all the above fields. (The fields are separated by tabs).
matt 20.00 Y Matt Johnson [email protected] Science Dept Head office \
103251 912254 NoteA john 25.00 N John Jackson [email protected] Administration Other office \
963254 123254 NoteB
Note: backslash indicates text should appear on the same line.
The following lines shows importing user email addresses only. NOTE: That the tabs still exist for balance, restriction, full name fields, but each entry is blank.
matt john [email protected]
The following lines shows importing the credit balance and full name for the first user and the credit balance and email address for the second user. NOTE: That the tabs characters still exist for blank fields.
matt 10.00
john 15.00
Matt Johnson [email protected]
6.7. User card and ID numbers
PaperCut NG supports two closely related features: card and ID numbers:
1.
A card number is the number read from a swipe or proximity card assigned to a user. Swipe and proximity cards are often used for user authentication at hardware terminals, copiers and print release stations.
2.
An ID number is a unique number allocated to a user. It may represent a student or employee number or may simply be a random number. It may be keyed in at a copier, hardware terminal or release station as an alternative to username/password authentication. As ID numbers may be guessed or learnt by others we recommend a secret PIN be used in conjunction with an ID number when used for user authentication.
As both card numbers and ID numbers function as a unique number identifying a user, they both share the same field in the User record of the database - the card/ID number. This means that all administrative functions related to card numbers and ID numbers are the same - because they operate on the same database field.
Tip
Although we use the term "number", PaperCut permits any string containing both letters and numbers in the card/ID field. If used as an ID number to be typed at a numeric keypad, a purely numeric number is best. ID numbers generated by PaperCut are always purely numeric.
One more thing to know is that PaperCut NG actually supports two different card/ID numbers for each user. We call
101
Advanced User Management these the primary and the secondary card/ID number. There are many reasons why having two numbers can be useful. For example:
1.
One number can be for a card - and the other for an ID number in case the user misplaces his or her card.
2.
Different card readers can sometimes read different numbers from the same card - so having two numbers allows both types of readers to be supported.
3.
It is possible to issue new cards to users and phase out the old card with an overlap period in which they both work.
Use of either the primary or secondary card/ID number field is optional - the decision is up to your organization.
PaperCut offers a range of tools for managing card/ID numbers allowing for either centrally managed or user managed card/ID numbers:
1.
Automatic generation of numbers within PaperCut (See Section 6.7.1, “Automatic Card/ID Generation”)
2.
Batch update from an external file (See Section 6.7.2, “Batch User Card/Identity Update”)
3.
Import from AD or LDAP (See Section 15.3.5, “Card/Identity Numbers Sync”)
4.
Lookup via an external database (See Section 6.7.3.1, “Database lookup configuration”)
6.7.1. Automatic Card/ID Generation
PaperCut can generate random card/ID numbers for your users. This may be the ideal solution if you don't already have ID numbers assigned for other purposes. PaperCut provides a number of options allowing you to choose whether to centrally administer the card/ID numbers or to allow users to generate and manage their own numbers.
You may:
1.
2.
3.
Generate numbers as a Bulk User Operation. (See Section 6.4, “Bulk User Operations”.)
When generating numbers on behalf of users, you will need to inform users what their number is. PaperCut can help with this task as well. You can:
1.
Send an email to each user with their new number. This is set up in Options
→
Notifications
→
Card/ID
Number Notification. See Section 15.6.1.3, “Card/ID Number Notification” for more information.
2.
Allow users to view their number in the user web portal. To enable this feature, check the "Allow users to view their card/ID numbers" checkbox in Options
→
General
→
User Features. You will need to specify whether you wish users to view their primary or secondary card/ID number.
Tip
When generating card/ID numbers, you are asked to specify the length or number of digits you require in the generated numbers. Short numbers are easier to remember and faster to key in, but it is also easier to guess someone else's number. If your number is too short, PaperCut may not be able to generate sufficient numbers to cover all your users.
A good rule of thumb is to make the number 3 digits longer than the number of users in your organisation. If you have 10-20 users, a 4 digit number is probably sufficient. However, if you have
1000 users, you probably need a 7 or 8 digit number.
6.7.1.1. Allowing users to manage their own card/ID number and/or PIN
102
Advanced User Management
You can choose to allow users to manage their own card/ID number or PIN or both. These options are controlled in
Options
→
General and result in different functionality appearing in the Change Details menu item of the end-user web interface.
6.7.1.1.1. Editing card/ID PIN
When using card number and PIN authentication is may be useful too allow users to change their PIN in a similar way to users changing passwords.
To enable this feature:
1.
Navigate to Options
→
General.
2.
Enable the option Allow users to change their card/ID PIN
Users may then login into the end user web interface and under the Change Details menu item will see the option
Change Card/ID PIN.
6.7.1.1.2. User Generating the card/ID number
You may allow users to generate their own card/ID number from the Change Details page:
1.
Navigate to Options
→
General.
2.
Enable the option Allow users to change their card/ID number and then select which card number they can change. Users may edit the prinary number, or the secondary but not both.
3.
Ensure that Auto-generate random number (users cannot manually enter a number) is checked. This option gives users the ability to generate a new random number, but not to create a number of their own choosing.
If unchecked, users may choose any number they wish. Please note that this may be a potential security
risk as it may allow users to confirm the existence of a valid card number used by someone else. We recommend that sites enable two-factor authentication by also requiring users to have a secret PIN number.
Note: To change the number of digits used when users auto-generate their own card/ID number, change the
user.auto-generate-card-id.length value by using the Config Editor. In version 14.3 or later, you can also set this in the Admin interface under the Auto-generate random number option, by setting the 'Length' value.
Users may then login into the end user web interface and under the Change Details menu item will see the option
Change Card/ID.
6.7.2. Batch User Card/Identity Update
The batch user card/ID update feature allows the administrator to update user card/ID numbers and optionally import or update PINs by reading data from a simple text file. User card/ID numbers may also be imported using the
batch user import/update feature (see Section 6.6, “Batch User Data Import and Update”).
Example: To update/import the card/ID numbers or PINs of all the users in the import.txt file on a windows system.
C:\> cd C:\Program Files\PaperCut NG\server\bin\win server-command batch-import-user-card-id-numbers "C:\card numbers\import.txt"
Note that the import path should be quoted if it contains spaces.
Important
The card/ID number must uniquely identify a user, so care should be taken to ensure that no two users have the same card/ID number. This means that the card/ID numbers defined in the import file should be unique. If PaperCut NG encounters a non-unique card/ID number that user will not be updated.
103
Advanced User Management
A batch user card/ID update may be performed by calling the batch-import-user-card-id-numbers
import file format is detailed in Section 6.7.2.1, “Batch User Card/Identity Update File Format”.
Caution
Batch updates are a major operation modifying data en masse. Best practise suggests:
• Always run a backup before proceeding with the import.
• First experiment/test the update process with a small batch of users before moving onto the full batch.
6.7.2.1. Batch User Card/Identity Update File Format
The import file is in tab delimited format and contains the following fields in the given order.
No.
Field Description Optional?
Limitations
1.
2.
Username
Primary
Number
User
The user's username.
Mandatory Max. 50 characters
Card/ID A unique primary card/ID number for this user.
Optional (card/ID number not set if blank)
Max.
100 characters.
To specify that the number should be set to blank, enter a hyphen (
-
).
3.
User Card/ID PIN The user's card/ID PIN.
Optional (card/ID PIN not set if blank)
To specify that the PIN should be set to blank, enter a hyphen (
-
).
4.
Secondary User Card/ID
Number
A unique secondary card/ID number for this user.
Optional (card/ID number not set if blank)
Max.
100 characters.
To specify that the number should be set to blank, enter a hyphen (
-
).
Table 6.3. User Card/Identity Update File Format
Other limitations: Although any actual limit to the size of an update file should be large enough for any purpose, we recommend keeping the file size below 10MB.
Tip
A simple way to create a tab delimited file is to create a spreadsheet in Microsoft Excel, then save it in the
Text (Tab delimited) format.
6.7.3. Looking up card numbers in an external database
PaperCut NG can import user card/ID numbers from Active Directory and LDAP. This is the recommended approach because it allows the card/ID numbers to be associated with users in a centralized location. For more information
see Section 15.3.5, “Card/Identity Numbers Sync”.
In some circumstances the mapping between card numbers and users may be stored in another external database
(e.g. a database used for secure door access). In this case, it may be more convenient to look up the card numbers
104
Advanced User Management in this database in real-time.
Tip
This also allows users to be associated with more than two card/ID numbers. This is useful where users are allocated different types of authentication cards, or there are alternate card systems used throughout the organization.
To allocate multiple card numbers to a user, simply populate the mapping table with multiple entries per user where different card numbers map to the same username.
Once external user lookups are enabled, PaperCut NG will do the following when looking up a user by card number:
1.
Find a user with the matching card number in the PaperCut NG database.
2.
If not found, the card number will be looked up in the external database.
3.
If a match is found the information returned is used to find the matching user in the PaperCut NG database. If a user is found the lookup is successful.
6.7.3.1. Database lookup configuration
To enable external card number lookups:
1.
Navigate to Options
→
Advanced
→
External User Lookup.
2.
Enable the option Use external database for card number lookup.
3.
Select the database type. If using Oracle or MySQL you must install the database driver as described in the
Section 22.3, “Database specific configuration”, and the application server must be restarted.
4.
Enter the database connection URL. For examples see Section 22.2.4, “Step 4 - Change the PaperCut NG
connection details” of Section 22.2, “Upsizing to an External RDBMS”.
5.
Enter the database connection username and password.
6.
The option SQL to map card number in external database to: allows you to choose what the card number in your external database maps to. The options include:
• username, used if your external database contains a mapping between card numbers and usernames, and
• user's identity number, used if your external database contains a mapping between card numbers and user ids (and the user ids have been imported and stored on users in PaperCut).
Select the option that matches the mapping in your external database.
7.
Enter an SQL select query that looks up the card number in your external database and returns either a username or user id as selected above. The query must return a single row with the first field being the username or user id (as found in PaperCut NG). The SQL statement must contain
{cardnumber}
, which will be replaced with the card number to find.
An example select query that looks up a card number and returns a username is: select user_name from users_table where card_number = {cardnumber}
An example select query that looks up a card number and returns an indentity number is: select user_id from users_table where card_number = {cardnumber}
Note
The
{cardnumber} replacement does not require quotations (it is sent as a parameter). This
105
Advanced User Management also serves to prevent SQL injection attacks sent via card numbers.
6.7.3.2. Testing
To test the lookup is working as expected:
1.
Navigate to the Users tab.
2.
Pick a card number from your external database that maps to a user in PaperCut NG.
3.
Enter this card number in the Quick Find field and press Go.
4.
Verify that the matching user is displayed. If the expected user is not displayed check the App. Log tab for errors.
6.8. Disabling user printing with time latches
PaperCut NG allows printing to be disabled for particular users using time-based locks. These time latches allow a user's printing to be disabled for a predetermined amount of time. After this time has passed, the user's printing is re-enabled without the need for manual intervention. Some examples of where time latches may be useful include:
• Student discipline - Under some circumstances it might be useful to disallow printing for a student who has been misbehaving in class, abusing computer resources or for other disciplinary reasons. The user's printing can be disabled for the duration of a class, or indefinitely. Once the time period has passed, printing will automatically be enabled for this user.
• Classroom Management - Using the bulk user actions screen, printing can be disabled for a group of users. This can be useful to stop a classroom from printing for a period of time.
• User Management - If a employee or student is away for an extended period of time and may return, printing can be disabled so that their details and balance is unchanged but no-one can use their account for printing.
The disable printing option is located on each user on the user details screen.
Figure 6.5. User printing disabled using a time-latch
6.9. Office/Department History
PaperCut maintains a historical record of changes to users' office and department fields. PaperCut cross-references job logs against these histories so that it can report print usage by the office and department a user belonged to at the time they printed a job. Normally this happens in the background and there is no need to be aware that it is happening.
There are some cases where a user's office or department will have been updated incorrectly in the user directory,
106
Advanced User Management e.g. updated too late, or changed to the wrong name. These changes will reflect how user activity is reported by
PaperCut. To ensure that information is reported correctly, the changes that were made incorrectly can be retrospectively altered. The most common cases where alteration might be required are described below.
Note
A user's office and department history are synchronized from the user directory into PaperCut, and not the other way around. Therefore it is important that the details in the user directory are updated before making historical changes in PaperCut. PaperCut automatically synchronizes these details overnight, however a change can be made in the same day by running a manual synchronization via Options
→
User/Group Sync
→
Synchronize Now.
6.9.1. Scenario 1: Correcting a late change to a user's office or department
User peter moves from the Science department to the Medicine department on 14 May but the user directory is not updated with the change until 28 May. The PaperCut administrator Jane notices that Peter's activity between 14 and
28 May has been incorrectly allocated to his old department, Science. Luckily Jane can alter history, and she does so as follows:
1.
Navigates to Users
→
peter.
2.
Clicks View/edit history below the Department field.
Figure 6.6. View/edit department history link on User Details page
3.
The Department history screen is displayed, including the department change on the incorrect date of May 28.
Figure 6.7. Department history page with date to change highlighted
4.
Jane finds the row where the department was changed to
Medicine on the incorrect date (
On 28 May
2011...
in the screenshot below), corrects the date and clicks Apply.
5.
Peter's department change has now been retrospectively updated to 14 May. Reports now show Peter's activity being allocated to the
Medicine department after this date.
6.9.2. Scenario - Correcting an unintended office or department change
On April 9 Peter joins the Medicine department. At the time, his department's administrator entered the department name into the user directory as
Medical Department
, where the correct name should have been
Medicine
. The
PaperCut administrator Jane realizes this mistake on April 28 and updates the user directory.
PaperCut now displays Peter's activity between April 9 and April 28 as being allocated to the incorrect department
Medical Department
. To correct this, Jane performs the following actions:
107
Advanced User Management
1.
Navigates to Users
→
peter.
2.
Clicks View/edit history below the Department field.
Figure 6.8. View/edit department history link on User Details page
3.
The department history screen is displayed, and shows the incorrect department change on April 9.
4.
Jane clicks the delete link in the row of the incorrect department change
Medical Department
.
Figure 6.9. Link to delete a historical department (or office) change.
5.
The incorrect department change has now been deleted, leaving the new department
Medicine as active since April 28.
Figure 6.10. Department history page after having deleted a historical change
6.
Jane updates the change date of the
Medicine department to April 9 and clicks OK.
7.
Reports will now consider
Medicine as Peter's department since April 9, and the incorrect entry
Medical
Department has been deleted.
6.10. Username Aliasing
In some scenarios, a particular user wants to print a job but his/her username has been changed for various reasons and it is reflected in PaperCut now as a different username. Examples of why the username may have changed:
• Two networks/domains/servers have different naming conventions, e.g. for user John Smith, one network uses the convention "j.smith" while the other uses "jsmith".
• For some policy reasons, the format of usernames has changed and you want to allow forgetful users to log in with their previous username.
• Print jobs are coming from an ERP or mainframe system where usernames are different.
• In some organizations, users log in with employee numbers.
108
Advanced User Management
• Print jobs coming from some software packages may use the "application username" and not the user's network username used by PaperCut. This can occur in some SAP configurations.
• Unix has strict requirements for usernames, (IEEE Std 1003.1–2001), where the only valid characters are letters, digits, underscores, full stops, at-signs, dashes (but not start with a dash) and having $ at the end. So when printing on a Unix server, it can sanitize the username, such as converting an apostrophe into an underscore, and then recording in PaperCut as a different user when one really wants it to be the same user.
To work around this problem PaperCut allows users to have an alias for their username. The username alias is applied at the following levels:
• User login to the web interface, client popup authentication, or release station login.
• Print jobs arriving in the print queues under the alias.
Username aliasing can be enabled via Options
→
Advanced
Figure 6.11. Enabling Username Aliasing
Once username aliasing has been enabled, you will see a new text field on the User Details page.
Figure 6.12. Username alias field on the User Details page.
or "afh27" and can send jobs under the username "anne".
This information can be automatically imported from Active Directory or LDAP during an overnight sync. Once username aliasing is enabled, an option to enter an AD/LDAP field name appears under Options
→
User/Group
sync. Any valid Active Directory user field can be chosen to import this information. For example: employeeNumber,
109
employeeID, otherLoginWorkstations.
Advanced User Management
Figure 6.13. Active Directory sync option for username aliasing
Once this has been set, information from this Active Directory field will be imported every night as username aliases.
6.11. User Management Quick Reference
How do I add credit to a user?
Select the user from the groups list, and click on the adjust link next to the credit or select the Adjustment &
Charges tab.
How do I add a new user to the system?
PaperCut NG will automatically add users to the system the first time they print. If your new user initial settings rules are defined correctly under groups section, the user will automatically be created with the designated starting credit and settings.
If you have added a large batch of new users, you can force the addition of these users immediately via the
How should I make a change to more than one user?
110
Advanced User Management
If you need to make a change to more than one user, consider using the Bulk user actions link located under either the User or Groups section. This allows bulk modification of user settings based on their network group
membership. See Section 6.4, “Bulk User Operations”.
How do I grant administrator access to a trusted person to manage a group of users?
the option Limit access to users only in group.
How can I prevent new users from being added automatically?
See Section 15.3.6, “On Demand User Creation”.
Due to technical reasons I'm unable to create new groups in my domain. Can I create groups in PaperCut
NG?
Yes. Groups may also be defined via a text file (e.g. a tab-delimited file). Simply place your group definition file at the location
[app-path]/server/data/conf/additional-groups.txt
See the template file additional-groups.txt.tmpl
in the same directory for an example and further information.
I have two different networks with different username naming conventions (e.g. j.smith and jsmith). Is this supported?
Yes. You can enable Username aliasing under Options
→
Advanced
Another option to set up username aliasing is described in the file below:
[app-path]/server/data/conf/username-aliases.txt.tmpl
See the comments in this file for more information.
Can I manage my own set of users inside PaperCut NG (as well as / instead of importing users from a user directory)?
Yes. PaperCut NG is designed to keep user management simple and automated, but it is possible to manage users inside PaperCut NG as well as or instead of using users from a user directory. Users managed by PaperCut NG are
111
Chapter 7. Advanced Printer Management
This section covers some of the more advanced printer management tasks. Advanced printer management can be grouped into the following high-level concepts:
• Activity monitoring
• Encouraging appropriate use
• Managing the addition of new printers
This section addresses these management areas and covers tools available in PaperCut NG to assist administrators.
7.1. Adding and Removing/Deleting/Ignoring Printers
7.1.1. On Windows
PaperCut NG tracks all print queues local to the system by default. Local print queues are those that have been set up on the server running PaperCut NG with a local port, such as: a TCP/IP connection to a network printer, an LPR connection, or a printer attached locally via USB or LPT. Standard Windows print queues that are hosted on a different system, or “re-shared”, are not tracked (these queues may be tracked by setting up a secondary print
server, see Chapter 17, Configuring Secondary Print Servers and Locally Attached Printers).
New print queues added to the system should show up automatically in PaperCut NG, however in some rare situations the printer may only show up after the first print job has been sent.
Under some situations it may not be desirable to track all printers. Some examples of why an administrator may choose not to monitor a printer include:
• The printer is a “virtual printer” such as a PDF generator, FAX, or document management program.
• The administrator may wish to offer free printing on a selected printer and not be concerned with monitoring
(silent monitoring with a zero page cost will also achieve this).
• The printer may not be supported by PaperCut NG and may need to be ignored.
The Print Provider component is responsible for locating and tracking the printers. To instruct it to ignore a printer:
1.
On the computer system running the print provider component open the file
[app_dir]\providers\print\win\print-provider.conf
in a text editor such as Notepad.
2.
Locate the line
IgnorePrinters= and enter the full name of the printer on the right-hand-side of the equals line. For example:
IgnorePrinters=Office Printer
Note: This is the printer's locally assigned name and not the name of its network share.
If you have multiple printers to ignore, then separate the each printer name with a comma. For example:
IgnorePrinters=Office Printer,Copy Room Printer
Wildcard expressions can also be used. Use '*' to ignore any span of characters, and '?' to ignore a single character. For example, to ignore any printers which start with the phrase Copy Room:
112
Advanced Printer Management
IgnorePrinters=Copy Room*
3.
Restart (stop then start) the
PaperCut Print Provider component under Start
→
Control Panel
→
Administrative Tools
→
Services
4.
If the printer data is no longer required for reporting purposes, log into PaperCut NG's admin interface and select the Printers section, then click on the printer to be removed and select Delete printer from the Actions list.
5.
Test the changes by printing to the deleted printer and ensuring the printer does not re-register itself in the system. It if does, verify the name assigned under the
IgnorePrinters= setting is correct.
7.1.2. On Mac
The list of monitored printers is configured when installing PaperCut NG. To change the list of monitored printers, run the script at
/Applications/PaperCut NG/Control Printer Monitoring.command
. Please read the script's instructions carefully and ensure that the Print Setup Utility is closed/quit when running this script.
After running the script, print a test document (i.e. using a text editor or printing a web page from Safari). The act of printing for the first time will register the printer with the primary server. Log into PaperCut NG as admin and verify that the printers are now listed under the Printers section. Perform a test print on each printer and verify that the jobs are tracked correctly.
Note
At the technical level, Mac systems use the Common UNIX Printing System (CUPS). PaperCut NG tracks printing by integrating with CUPS. (For system administrators familiar with CUPS, PaperCut NG integrates by wrapping or proxying the CUPS backend).
The
Control Printer
Monitoring.command
script simply edits the file /etc/cups/printers.conf and prefixes the
DeviceURI with papercut:
, enabling monitoring on the selected printer.
System administrators experienced with the terminal may prefer to edit the printers.conf
file
directly with a text editor. See Section 7.1.3, “On Linux” for more details.
To delete a printer:
1.
Double click on the
Control Printer Monitoring.command
script.
2.
Choose to disable monitoring on the printer(s) to delete.
3.
If the printer data is no longer required for reporting purposes, log into PaperCut NG's admin interface and select the Printers section, then click on the printer to be removed and select Delete printer from the Actions list.
4.
Test the changes by printing to the deleted printer and ensuring the printer does not re-register itself in the system. It if does, verify that it is not being monitored using
Control Printer Monitoring.command
.
7.1.3. On Linux
PaperCut NG tracks printing by integrating with the Common UNIX Printing System (CUPS), the printing system on
Linux. For a printer to be tracked, CUPS needs to be told to route print jobs through PaperCut NG before printing.
To do this, the printers.conf
file must be edited. This can either be done manually, or assisted via the configure-cups script.
To use the script, run the script file at
[app-path]/providers/print/linux-*/configure-cups
. Please read the script's instructions carefully to enable monitoring on the desired printers.
To edit the file manually:
113
Advanced Printer Management
1.
Open your printers.conf
in a text editor such as vim
. On most Linux distributions printers.conf
is located at
/etc/cups/printers.conf
.
2.
Prepend papercut: to the
DeviceURI of the printers you wish to track. After the modification a
DeviceURI line might look like:
DeviceURI papercut:ipp://1.2.3.4/printers/My_Printer
3.
Restart CUPS in the way appropriate to your distribution. E.g.:
/etc/init.d/cupsys restart
4.
Perform a test print on each printer. This will cause the printers to be registered. This step is not required with the configure-cups script, because the script registers the printers automatically.
5.
The printers should now be registered. Log into PaperCut NG as admin and verify that the printers are now listed under the Printers section. Verify that the test prints sent previously were tracked correctly.
To delete a printer:
1.
Double click on the configure-cups script (or manually edit printers.conf
), and choose to disable monitoring on the printer(s) to delete.
2.
If the printer data is no longer required for reporting purposes, log into PaperCut NG's admin interface and select the Printers section, then click on the printer to be removed and select Delete printer from the Actions list.
3.
Test the changes by printing to the deleted printer and ensuring the printer does not re-register itself in the system. If it does, verify that it is not being monitored using configure-cups
.
7.2. The Template Printer
The Information Technology field is a rapidly moving environment. Change is driven by two main forces:
• Business and end-user requirements
• Technology advances
It is change that often consumes a network administrator's time. PaperCut NG endeavors to alleviate some of the more mundane tasks via automation. The New User Initial Settings section under Groups assists with the creation of new user accounts. The addition of new printers, although less common, is also inevitable. PaperCut NG helps administrators streamline new print setup using a concept of a template. A template is a pattern or initial condition used as a starting point. PaperCut NG has a special virtual printer called the
[template printer]
. This is not a real printer, but a special printer used as a template for printers added in the future.
The
[template printer] is best described by an example:
1.
Jane is a network administrator at a local business. She has implemented a print policy across all printers as follows: a.
The page cost for a standard page is $0.10.
b.
Double sided printing is encouraged with a 40% discount.
c.
A filter exists on all printers to prevent jobs of over 100 pages. This prevents users from holding up the queues with large single jobs.
2.
Jane has set up her policy on all existing printers and then adjusted settings on a printer-by-printer basis depending on the type and functions.
3.
She has also set up this policy on the
[template printer]
.
114
Advanced Printer Management
4.
Two months later Jane adds 4 new printers. No change in PaperCut NG needs to take place as the printers automatically set themselves up based on the settings in the
[template printer]
.
5.
When Jane has spare time later in the month she fine tunes printer configuration as required.
As the example shows, the template printer not only helps alleviate future configuration work, but also ensures a consistent policy is applied on printers by default. It brings PaperCut NG one step closer to the "zero-administration" goal.
It is recommended the administrators take a few minutes to configure the template printer on any network of more than 100 users.
Figure 7.1. The Template Printer
7.3. Copying Printer Settings
Another way to quickly configure printers and have a consistent charging policy is to copy printer settings (costs, filters, etc.) from one printer to another.
Warning
Copying settings to printers is a one-way operation and cannot be undone. Always carefully consider the operation before proceeding. If you are unsure of the function or behavior, performing a backup prior to undertaking the operation is advised.
To copy printer settings from one printer to another:
1.
Navigate to the Printers tab.
2.
Select the printer you wish to copy the printer settings from. The Printer Details screen appears.
3.
Click the Copy settings to other printers action link.
4.
Choose which settings to copy. There is a choice of the cost and the filter settings.
5.
Select the printers / printer groups to copy the settings to.
6.
Press Copy to perform the copy.
115
Advanced Printer Management
Figure 7.2. Copy settings from one printer to others
7.4. Renaming a printer
To uniquely identify a print queue PaperCut NG uses a combination of the hostname the print queue is hosted on and the printer's queue name. If either of these change, for example because if the print queue is renamed, or because the print queue was migrated to a new print server, then a new entry will be created for the Printer List.
Future print logs will be tracked against the new printer name, and the old printer name will still be available along with all its logs.
In some cases this is the desired behavior. In other cases it may be preferred to rename the "old" printer to its new name so that logs and settings are maintained.
To rename a printer, log into the administration interface and:
1.
Select the printer to rename via Printers
→
Printer List
2.
Click Rename this printer from the Actions menu.
3.
Enter the new server and print queue name.
Important
The print queue name may not be the same as the print queue's share name. On Windows the print queue name appears in Control Panel
→
Printers. On Mac the print queue name can be found on the printer's Printer Info sheet under Name & Location
→
Queue Name. Take care to enter the name exactly as it appears in the OS, as case sensitivity can be important.
4.
If there is already a printer with the chosen name, for example because the print queue has already been renamed in the OS and was automatically added to PaperCut NG, ensure the checkbox If a printer with the
new name already exists, delete and replace it is enabled.
5.
Press Apply.
6.
Perform a test print to ensure that printing is logged under the new name.
7.5. Disabling printers with time latches
116
Advanced Printer Management
Time latches allow a printer to be disabled for a predetermined amount of time. After the disable time has expired, the printer is re-enabled without the need for manual intervention. Some examples of where time latches may be useful include:
• Printer maintenance - A printer may be consistently jamming and require maintenance. The administrator can lock the printer for 24 hours until the maintenance is performed. Users receive a notification message if they try to use the locked printer.
• Classroom management in schools - A teacher may wish to disable printer use to force students to focus on their work for the duration of the class. The printer can be locked for the duration of the class. After the class has finished the printer is re-enabled automatically ready for the next class.
The disable option is located on each printer under the printer configuration area.
Figure 7.3. Printer disabled using a time-latch
7.6. Managing printing using differential charging
In a quota-based or charged environment, one of the most important tools at the administrator's disposal is the ability to charge different amounts for different types of documents or on different types of printers. Printers are designed for a particular task and a particular work rate. For example an inkjet color printer is ideal for photos or the occasional color page but should not be used print 1000-page black and white documents when the heavy duty laser printer is located just down the corridor.
PaperCut NG allows administrators to:
• Charge different cost-per-page amounts for each printer
• Charge different amounts based on the type of document including:
• Charge more for color printing vs. black and white or grayscale
• Charge more for single-sided printing vs. double-sided or duplex
• Charge more for larger or non-standard paper sizes
Administrators can use differential charging to encourage users to use the correct printer and printer settings for the task at hand. This ensures maximum utilization of the resources available.
Example: David is a network administrator at a local university. The printer comparison charts in PaperCut NG suggest that one of the printers on the 4th floor in the computer science wing is only used half as much as other printers. Upon investigation he finds that students prefer to use the closer printer located in the corridor outside the lab. David decides to relocate the printer at the end of semester. In the meantime he encourages its use by reducing the price thereby taking load off the other printers.
7.6.1. Charging types available
PaperCut NG offers a range of charging types to cover the needs of most organizations. Most people will find that either Simple or Standard Charging meet their needs best and we suggest you look at these first.
117
Advanced Printer Management
7.6.1.1. Simple Charging
Simple charging is appropriate to all types of printers. It allows administrators to define a simple cost-per-page setting only. For example if the cost per page was defined at $0.10, 50 pages would cost $5.00.
7.6.1.2. Standard Charging
Standard charging is the default and is ideal for printers that support advanced print attributes including:
• Duplex or double-sided printing
• Color or Black & White (grayscale) printing modes
• Multiple paper trays offering standard and large sizes
Standard charging allows administrators to define the exact charges per page for each printing category and paper size in a spreadsheet-like table. Each row in the table specifies the charges for a specified paper size. Rows for common paper sizes are added by default and you may add or delete rows as required.
• To add a row, select the desired paper size and press Add.
• To delete a row, press the trash can icon
The columns in the table represent the different printing modes for each paper size.
• Color: specify the cost per sheet for printing color single sided. This should be the most expensive option.
• Grayscale: specify the cost per sheet for printing grayscale (black and white) single sided. This should be lower than Color.
• Color duplex: specify the cost per side for printing color double sided.
• Grayscale duplex: specify the cost per side for printing grayscale double sided. This should be the lowest cost option.
Figure 7.4. Standard charging example
Press Apply after making any changes to save your changes to the database.
7.6.1.3. Charging by Category
Category based charging is an alternative to Standard charging for printers that support advanced print attributes.
The difference with Category charging over Standard charging is that a base charge and discounts are specified, rather than an exact charge per category. For example, Black and white (grayscale) documents can be granted a discount over full color. An option also exists to discount and encourage double-sided printing. Discounts can be applied either as fixed amounts or as a percentage of document cost.
118
Advanced Printer Management
A practical example, Mary has a color printer that supports letter and legal paper and duplex. She would like to define rules to:
• Charge $1.00 per page for letter (standard size) color printing.
• Charge $0.40 per page if the users select grayscale (black & white) - a $0.60 discount for grayscale
• Charge an extra $0.80 if they use large legal size paper
• Offer a 50% discount for duplex to encourage double sided printing.
To accomplish this complex set of charging rules, Mary should setup the Advanced charging options for the particular printer as defined in the screenshot below.
Figure 7.5. Advanced differential charging example
7.6.1.4. Charging by Paper Sizes
The charging by paper size mode is designed for printers with multiple trays and a variety of available paper sizes.
Administrators have full flexibility to define cost for each of the paper sizes support by the printer. For example, printing a letter size page would cost less than printing a legal size page. This mode includes options to enable discounts for grayscale and/or duplex jobs. Discounts can be applied either as fixed amounts or as a percentage of document cost.
7.6.1.5. Charging by Paper Area
This mode is designed for plan printers, plotters or printers that support a variety of paper sizes. For example, many engineering firms use these types of printers for plotting CAD design diagrams. Charging by area allows the cost of the print job to be a function of the paper area.
7.6.1.6. Charging by Paper Length
This mode is designed for plotters or printers that use a paper roll or fixed width media. Charging by length allows the cost of the job to be a function of the paper/plot length.
7.6.2. How duplex discounts are calculated
Several of the supported cost modes allow a discount to be applied to printing duplex documents. The discount is entered as either a percentage or a constant amount per page. It is important to understand that PaperCut NG counts a single side of printing as a one page. For example, if you have a 50 page Word document, PaperCut NG will count this as a 50 page document, whether it is printed single-sided or duplex.
When calculating the cost of a job, the duplex discount is only applied to pages when there is printing on both sides of a sheet paper. If a document contains an odd number of pages, the duplex discount is not applied to the last
119
Advanced Printer Management page. For example, if a 11 page document is printed as duplex, the duplex discount is applied to the first 10 pages, but not the last page.
Some printers allow multiple copies of a document to be printed as a single job. PaperCut NG will calculate the cost using the above rules. i.e. If a copy contains an odd number of pages, it will not apply the discount to the last page of each copy.
7.7. Print filters: conversions and restrictions
PaperCut NG offers two categories of print filters: conversions and restrictions. Conversions change something about the print job, e.g. from color to grayscale. Restrictions are used to ensure jobs meet certain criteria (denying those that don't). Each printer has its own set of filters.
Conversion filters include:
• Convert to grayscale (for all users, or for users in specified groups)
• Convert to duplex (for all users, or for users in specified groups)
Figure 7.6. Print conversion filters
Restriction filters include:
• Restrict printer access to one or more user groups
• Restrict color printing access to one or more user groups
• Define the maximum cost of a single print job
• Define the maximum number of pages allowed in a single print job
• Define the maximum number of copies allowed in a single print job
• Allow only simplex or duplex jobs
• Allow only color or grayscale jobs
• Filter documents based on the file extension or name
• Allow only selected paper sizes
• Define the maximum spool size of a print job (to prevent large jobs blocking the printer)
• Detect and delete duplicate print jobs
By default restrictions only apply to restricted users. Optionally, restrictions can be applied to all users by changing the Restriction Scope option.
120
Advanced Printer Management
Figure 7.7. Some of the available print restriction filters
For more advanced functionality there is print scripting. While the options available on the Filters & Restrictions tab are useful for rules that apply to all users or to some user groups, scripting can take into account multiple factors. Examples include:
• automatically convert all printed emails to grayscale (i.e. do a conversion based on the application type)
• automatically convert large documents to duplex
• suggest or require that users print in grayscale if their job contains a large number of color pages
Figure 7.8. Advanced conversion functionality with print scripting
For more detail see Chapter 20, Advanced Scripting (Print Scripting).
7.7.1. Examples
121
Advanced Printer Management
Filters and scripts are applied at the printer level (i.e. on a per-printer basis). The following examples cover how to apply a filter/script to a single printer. Once a filter or script has been applied to one printer it can be copied to other
printers (see Section 7.3, “Copying Printer Settings”).
7.7.1.1. Converting student print jobs to grayscale
Converting all jobs that were sent by a student to grayscale can be achieved from the Filters & Restrictions tab as follows:
1.
Ensure you have a
Students group in your domain (or equivalent) that contains all students.
2.
Ensure the
Students group has been added to PaperCut so that it appears on the Groups tab. For more
information about adding and removing groups see Section 6.1, “Groups in PaperCut NG”.
3.
Navigate to Printers
→
[select printer]
→
Filters & Restrictions
4.
Enable the option Convert color jobs to grayscale for: and select Users in the following groups: from the dropdown menu.
5.
Enable the Students group in the list of groups for selection.
6.
Press Apply.
7.
Test by printing a color job as a user in the
Students group.
Figure 7.9. Converting student printing to grayscale
7.7.1.2. Converting printed emails to grayscale
Printing of emails is a prime candidate for reduction of paper and printing costs. Printing of emails in color (when the colour is being used for blue links and email footers) is doubly so. Having PaperCut automatically convert emails to grayscale requires a printer script as multiple factors are taken into account. The logic would read: when a user prints and the print appears to be an email, convert the print to grayscale.
There is a built-in recipe script to achieve this:
1.
Navigate to Printers
→
[select printer]
→
Scripting
2.
Click Import Recipe.
3.
Find the recipe called Convert all email printing to grayscale and click the import button next to it. Note the message at the top of the script about the method it uses to detect when an email is printed.
4.
Click Apply.
5.
Test by printing an email in color.
122
Advanced Printer Management
7.7.1.3. More Examples
More examples are available in the application by clicking Import Recipe on the Scripting tab.
7.7.2. Print Conversion Filters in Detail
Conversion filters work by modifying print jobs on the fly. E.g. rather than denying color printing access and asking the user to print again (as can be done using a restriction filter), a conversion filter can convert the job to grayscale automatically.
Possible uses include:
• converting color jobs to grayscale to prevent accidental color printing
• converting jobs on high volume printers to duplex to save paper
• having student jobs automatically converted to duplex
Scripting (Print Scripting) for more details.
Important
Conversions is a new and experimental feature, and may not work on all devices. If you encounter
a new printer model it is always a good idea to perform a test to ensure it is working as expected.
7.7.2.1. Using the PaperCut printer port for conversion filters on Windows (Advanced)
Conversion filters work by modifying print jobs on the fly. On Windows (when using standard printer ports) this is performed by modifying a print job and submitting it as a new job. An alternative is to configure the printers to use a
PaperCut printer port. When using a PaperCut port, print jobs are modified in-place rather than copied. This has several advantages:
• Processing is faster as there is no need to take a copy of the job.
• When jobs are re-submitted the new job may look unusual (the owner is
SYSTEM
, the document name has a special code in it). Using the PaperCut port avoids this and any potential confusion from administrators about what those jobs are.
• There is no need to disable the advanced printing features option on the print queues. Without the PaperCut port this option can cause problems with watermarking and other advanced features. When the PaperCut port is used it can cater for this option being enabled.
• Processing is more robust. Without the re-submission there are less steps, so less things to go wrong!
• Re-submitting can alter job ordering and priority (a feature of Windows print queues). Using the PaperCut port avoids this.
Changing the printer port is not required on other platforms such as Mac, Linux or Novell as the same limitations do not apply.
7.7.2.2. Troubleshooting
7.7.2.2.1. Disabling EMF printing (Windows print servers only)
123
Advanced Printer Management
Important
Print conversion filters work best with open standard languages such as PostScript and PCL. Other manufacturer specific and GDI based languages may be supported, but most of all it's important that print jobs spool in the printer's native language, and not the "EMF" format. If your print server is running Windows and documents are printing using the EMF language (the default) then conversions will not take place.
Figure 7.10. Job Log showing an EMF job
To disable EMF printing on a Windows print server:
1.
On the print server, navigate to: Start
→
Control Panel
→
Printers
→
[right-click printer]
→
Properties
→
Advanced
2.
Turn off (disable) the option Enable advanced printing features.
3.
Test printing and check the printer language to ensure that it is now something other than EMF.
You can read more about this setting on the Microsoft website at: http://support.microsoft.com/?kbid=268093.
7.7.2.2.2. Updating Printer Drivers
When experiencing problems with print conversion filters and there are new driver versions available for your printer, updating may resolve issues with the driver that caused conversions to not work.
When updating printer drivers, it is important to update the printer drivers on both the client and the server.
7.7.2.2.3. Contacting Support
If the other troubleshooting steps do not assist with a print conversion filter related problem, feel free to contact the
PaperCut support team. Please include information about the make, model and driver for the printer you are using.
7.7.3. Print Restriction Filters in Detail
Print restrictions provide network administrators with advanced control over printer usage. Some common examples include:
7.7.3.1. Reduce printer jams
Many printers expect print jobs to be on a single size of paper, or maybe two sizes if the printer has multiple paper trays. A non-standard size will cause the printer to enter a manual load state causing the queue to halt. PaperCut
NG Filters & Restrictions section allows Administrators to select the allowed sizes. Non-standard sizes are automatically deleted before they're sent to the printer. It's an effective way of reducing one of the most common causes of queue jams.
7.7.3.2. Controlling documents on slow inkjets
Many inkjet printers have very low throughput rates. A large color document can hold up a queue preventing other users from getting their "fair share" of print time. By setting an upper page count via the printer's Filters &
Restrictions section, network administrators can prevent large print jobs. The page count forces users to split up large documents and allows other users access to the printer.
124
Advanced Printer Management
7.7.3.3. Automatically deleting duplicate jobs
PaperCut NG can also monitor the print queues and automatically delete duplicate print jobs. This option is useful on networks with novice users. New users often "double click" an application's printer icon causing two identical print jobs to be sent to the queue. This wastes paper and users' print quota. Network administrators can enable duplicate job detection via the Filters & Restrictions section. A popup message warns the user and the duplicate job is removed from the queue.
Important
This option can affect multiple prints from Microsoft Excel and some other applications. Users wishing to print multiple prints from Excel may need to reprint the document 30 seconds apart.
When printing to a Hold/Release queue, the filter does not apply until the jobs are released, not at the time of submitting the print job. Please consider wether this Filter and Hold/Release queues are the workflow you require for your organisation.
7.7.3.4. Force sensible use
Restrictions can be set to define a maximum cost per job. This will prevent users from accidentally spending all their credit/quota in one print job.
7.7.3.5. Automatically deny documents based on file extension or name
There are many reasons why users should not print certain files. For example, maybe a report from the accounting application consists of 400 pages. Users may not be aware of this and "accidentally" print the report expecting only a few pages. PaperCut NG can be configured to match this document via its name and automatically delete it from the queue. Use the Filters & Restrictions keyword filter to implement this functionality.
Additionally it's also possible to filter documents based on file extension by entering a keyword like
.htm
or
.
To filter a document name based on a regex (regular expression), enclose the keyword in forward slashes. Note that the regex matches the entire document name. For example:
• To disallow printing of any documents ending in
.htm
:
/.*\.htm/
• To disallow printing documents of the form account-12345.pdf
:
/account-\d*\.pdf/
Important
This is not a security option. It is easy to circumvent the filter by simply renaming the document. Some systems may not even report type information!
7.7.3.6. Control who can print in color (Advanced)
To control which group of users have access to color printing to a particular printer use one of the following methods:
125
Advanced Printer Management
Method 1
1.
On the print server, create a print queue.
2.
Share the print queue as normal.
3.
Add the printers to PaperCut NG and define appropriate costs.
4.
From the printer's Filters & Restrictions tab in PaperCut NG select the groups which should have accesss to color printing via Groups With Color Access restriction.
For example:
• To only allow group "staff" to print in color to this printer.
Figure 7.11. Select "staff" from the list of groups
Method 2
This method utilizes two print queues, each with different driver defaults. One queue is set to grayscale only and the other have full color access. Group access is used to control who has access to the color queue.
To implement:
1.
On the print server, set up two print queues that point to the same physical printer. Call one queue Grayscale
Only and the other Color. You will now have two printer icons (logical printers) each connected to the same physical printer.
2.
Share the printers as normal.
3.
Set Windows access permissions on each queue as required. Users that require color access should be able to print to the color printer. Other users should only be provided access to the "black and white" only printer.
4.
Add the printers to PaperCut NG and define appropriate costs.
5.
From the printer's Filters & Restrictions tab in PaperCut NG ensure that the Color Mode restriction is configured to Allow grayscale documents only on the grayscale printer.
This method although being more complex to manage, sometimes offer better user experience as users do not need to select driver color and black and white options for each print.
7.7.3.7. Advanced Setups
PaperCut NG provides printer management features that can be easily extended to more advanced network setups including:
• Environments with multiple print servers
• Monitoring of locally attached network printers.
• Central monitoring over Wide Area Networks (WAN) or VPN.
These topics are an advanced subject and covered in subsequent sections.
Tip
126
Advanced Printer Management
For more flexibility in filtering print jobs, one should consider the Advanced Scripting capability.
Advanced scripting allows filtering on more more attributes of a print job or combinations of attributes.
See Chapter 20, Advanced Scripting (Print Scripting) for more details.
7.8. Managing printer groups
Administrators use groups to manage large number of users. Groups are used for all manner of purposes such as reporting, access control and management. PaperCut NG also offers the ability to group printers offering administrators the same level of management advantages they get from user groups. Printer groups are most useful for organizations with a medium to large number of devices.
Printer groups allow administrators to tag or group printers by attributes. Group names are user definable and may represent any attribute appropriate for printer management. Examples include printer type, location, make, function, owner, age, etc. PaperCut NG's grouping is implemented using text based "tags" offering similar flexibility to that seen in many modern online systems such as Flickr - the popular photo management website.
Some examples of where printer groups may be useful include:
• Grouping by printer type allowing an organisation to compare volume on inkjets vs. laser printers.
• Grouping by floor, departments, or work areas providing comparison reports to identify areas that may need additional printers.
• Quickly locate printers by attributes or tags defined by administrators.
• Implement fine grained access control by ensuring administrators can only apply adjustments to devices under their ownership/responsibility.
• Facilitate group-level management of devices settings such as copying new rules, costs and policies between like devices.
To group printers that support color output the admin will follow the following procedure:
1.
Locate and click a color printer via the Printers tab.
2.
On the printer details screen scroll down to the Printer Groups/Tags section.
3.
Enter an appropriate group name (tag) such as
Type:Color
. Read best practises in Section 7.8.1, “Suggested best practises for naming printer groups”
Figure 7.12. Adding a new printer group "Type:Color"
4.
Click OK to save the change.
5.
Repeat step 1 and 2 selecting another color device.
6.
This time select Choose from recent groups and click
Type:Color
.
127
Advanced Printer Management
Figure 7.13. Adding an existing printer group
7.
Repeat step 6 for all color devices.
Tip
An alternate method to apply a set of printer groups to multiple printers is to use Copy settings from
printer to printer action.
7.8.1. Suggested best practises for naming printer groups
An important requirement of group management is to have clear and consistent naming conventions for your groups. This convention needs to be followed by all involved in group management leveraging the Choose from
recent groups link is a good way to ensure consistency. A group name may contain any character except for
","
.
Administrators are encouraged to use a key-colon-value format such as:
• Type:Laser
• Location:Floor1
• Department:Science
• Subnet:192.168.4.*
• Office:NewYork
Prefixing the value with a type makes it easier to compare and locate groups of interest.
Like user groups, it's important to keep printer groups up-to-date. Ensure someone is tasked with assigning printer groups when new devices are added to your network.
7.9. Cost Adjustments
Account Selection Popup”) or Manager Popup (see Section 8.4.3, “Manager Mode Popup”). They allow an
administrator to define a user selectable list of adjustments to apply to the current print job. These adjustments can be in the form a percentage adjustment, a per job fixed adjustment or a per page adjustment. Charge Rates are commonly used in the Engineering and Architectural Drafting fields. Examples include:
• Charging different rates for premium print material. For example 150% for use of Mylar drafting film.
• Offering a discount of selected situations. A 2nd copy of an architectural plan printed on draft quality paper may be charged at 50% normal rate.
• Charging a fixed cost for services like document binding. For example, binding might cost an additional $5.00.
• Increasing the per-page cost of a job for color paper (e.g. an additional $0.20 per page).
Cost adjustments are defined at both a global and printer level - allowing common adjustments to be applied globally to all printers, with the flexibility to also define printer specific adjustments. The adjustments are defined in the format:
128
Advanced Printer Management adjust1:100%, adjust2:150%, adjust3:3.0pj, adjust4:0.10pp, adjust5:1.0pc
(A comma separated list of rates in the format of "Name" and "Amount" separated by a colon). The first rate listed is the default rate and is automatically selected in the Advanced Client Popup. The format of the "Amount" depends on the type of adjustment. Each of the formats is defined below:
Type
Percentage
Description Format
Applies a percentage adjustment to the job cost. Rates above 100% will increase the cost, while those below
100% will discount the job.
(NOTE: When multiple adjustments are applied with the manager popup, the percentage adjustments are applied last)
0.00%
Adds/subtracts a fixed amount to each page in the job.
0.00pp
Examples
120% - increases cost by 20%
75%
- discounts the cost by 25%
0%
- sets the cost to zero
Per Page
Per Job
Per Copy
Adds/subtracts a fixed amount to the total job cost.
0.00pj
Adds/subtracts a fixed amount to each copy in the job.
0.00pc
0.10pp
- increases cost by $0.10 per page
-0.05pp
- reduces cost by $0.05 per page
3.00pj
- increases total cost by
$3.00
-1.00pj
- reduces total cost by $1.00
3.00pc
- increases total cost by
$3.00 per copy
-1.00pc
- reduces total cost by $1.00
per copy
Table 7.1. Cost Adjustment Types
If the option Always require manual selection is enabled then the default selected rate will read “Select...”, requiring that users manually select a charge rate every time they print.
Global cost adjustments are defined in Options
→
Client Software. These will be available for all printers. Any adjustments defined at the printer level will be in addition to the global adjustments. The printer level adjustments are defined in Printers
→
Summary
→
Advanced Configuration
→
Define cost adjustments. If an adjustment with the same name is defined at both the global and printer level, the printer adjustment takes preference.
Figure 7.14. Three cost adjustments defined at the printer level
129
Advanced Printer Management
Figure 7.15. Cost adjustments displayed in the Advanced Client Popup
Figure 7.16. Cost adjustments displayed in the Manager Mode Popup
7.10. Popup Authentication
PaperCut NG normally relies on the underlying operating system and the associated print queues to perform authentication. For example, in normal operation, a user logs into a workstation using a domain/network level authentication method such as a username and password. The print queues also use this authentication and
PaperCut NG can trust the supplied identity. However in some network environments, relying on network level authentication may either not be possible, or may not be reliable. Common examples include:
• All users log in with a common generic username and password meaning that it's not possible to distinguish between users.
• A print queue that does not enforce authentication.
For a detailed explanation of print authentication, please Chapter 28, Print Authentication.
7.10.1. How does popup authentication work?
Popup Authentication matches the source IP address of the print job with the user confirmed to be operating from the popup client IP address. The workflow is as follows:
130
Advanced Printer Management
• The user initiates a print job to a server-hosted, PaperCut NG-managed, queue (printer) via unauthenticated print protocol.
• The print job arrives in the print queue and because of the unauthenticated protocol, the username cannot be trusted.
• PaperCut NG uses the job's source IP address to determine the PaperCut NG popup client it should contact for authentication.
• The user is prompted to enter their username and password, which are then verified against PaperCut NG's configured directory source. If the credentials are correct, the user is considered authenticated at that client.
• The print job is attributed to the authenticated user.
• Depending on configuration, the server may remember the association between the IP address and the authenticated user for a period of time.
7.10.2. Where and when should Popup authentication be used?
Some real life examples include:
7.10.2.1. The Student Lab
Some student labs are set up so everyone logs in using a generic username and password. For example, username: student, password: student. This is common in Apple Mac labs, where enabling multi-user authentication is complex and can often prevent selected applications from running correctly.
7.10.2.2. LPR/LPD or CUPS
The Line Printer Daemon print protocol, often used in UNIX environments, is a non-authenticated system. The username associated with the print jobs is passed through to the print queue, however the name is not verified and can easily be forged. An extra level of authentication is required.
CUPS, the modern print system often used on Linux, Apple Mac and some Unix systems, is often implemented in a non-authenticated fashion. Although CUPS can support authentication, technical considerations such as the inability to interface with Active Directory domain authentication often prevent its use.
7.10.2.3. Mac Print Queues
Mac OS X server use the CUPS print system. Current Apple implementations prevent administrators from enabling
CUPS authentication. This is not usually a problem in an environment where logins can be controlled at individual workstation level. It does however pose a problem if users have local admin access - for example, individual owned laptops. PaperCut NG popup authentication provides a way to work around the non-authentication issue.
7.10.2.4. Macs and popup authentication
Popup authentication is often required on Mac networks supporting a mix of lab systems authenticated via a
7.10.2.5. iPad / iOS Printing and popup authentication
PaperCut comes with an iPad / iOS app that provides popup authentication and other functionality. For more
information see Section 23.3, “iOS Printing (iPad & iPhone)”.
7.10.3. What technical considerations do I need to review before implementing Popup
Authentication?
As a general rule, Popup Authentication should only be used in low-volume, low-complexity scenarios when
Protocol-Level Authentication has been ruled out. By its design, Protocol-Level Authentication is always the most secure and hence this is the reason why it is used in Windows and authenticated protocols such as HTTP, SSH or
Novell's iPrint protocol.
131
Advanced Printer Management
A good example of a situation where Protocol-Level Authentication is not ideal would be a public-access PC in a library set to auto-logon as the insecure, generic account "public". In this case the Protocol-Level Authentication is passing through the insecure user of "public". PaperCut NG's client software and IP address authentication can overlay these insecure user credentials and request authentication from the user at the time of print via a popup.
The following is a general guide to factors your System, Network and Security teams should consider when implementing Popup Authentication:
• IP address changes should be minimized. If you are using DHCP, consider the lease time as well as the re-use rate of IP address and DNS scavenging timeouts.
• Do not use any form of NAT between the clients and print server. NAT will obscure the IP address seen by the server.
• Consider the authentication session time (TTL - Time To Live) options offered to your users. This is detailed further in the Popup Authentication configuration page of the manual. TTL settings are a trade-off; the shorter the time, the smaller the window of mismatch, but the greater the inconvenience to the user. There is no one-size-fits-all answer, this must be taken on a site-by-site basis.
• Ensure that hostnames can be resolved to IP addresses, both from the client and server. In some situations, hostnames may be reported instead of IP addresses, and resolution results are key to correct behaviour.
• Any machine relying on Popup Authentication must have the PaperCut NG client running at all times for printing from that workstation to function.
• Awareness of IP address spoofing. Large sites will often actively monitor this and/or endeavour to prevent it, as
IP address spoofing is something that affects network application security in general.
• Always reconsider your choice of Popup Authentication. Protocol-Level Authentication may become viable with changes in technology, infrastructure or internal procedure.
• Popup Authentication is not a viable solution for simultaneous multi-user systems, such as Terminal Server or
Citrix, as multiple users will be reported from a single IP address.
7.10.3.1. A real-life an example of the practical difficulties associated with Popup Authentication
In 2012 one major university user of PaperCut NG in the USA were using Popup Authentication to support authentication on print jobs issued via the LPR protocol (for Unix desktop systems). This setup had been in place successfully for 5 years with no reported problems. The site's networking team (independent of the server team responsible for PaperCut NG's management) decided to make a few network infrastructure changes and enabled
NAT for some subnets. Thhis caused a subtle set of authentication issues that took a number of days to detect and diagnose. During this time some jobs were incorrectly attributed.
7.10.4. Configuration
The following sections cover how to enable popup authentication on either the user account level or the print queue level.
7.10.4.1. Popup authentication and generic user accounts
The following notes explain how to enable popup authentication when a user logs in under a generic user account for example, student
.
• Add the account to the domain called student
. You may already have such as account set up.
• Perform a User/Group Sync or print a job from this account so the username is listed in PaperCut NG
• Select the generic user and set the account to a zero balance and a restricted status. This will ensure that users can't charge against this account.
• Check the Unauthenticated option and click on the Apply button to save the changes.
132
Advanced Printer Management
Figure 7.17. Turning on popup authentication at the user level
•
Install client software on workstations. See Section 5.2, “User Client” for details.
• When a user logs in as the generic student
, they will be prompted for their domain level username and password.
Figure 7.18. PaperCut NG client requesting for authentication
7.10.4.2. Popup authentication on a print queue
The following notes explain how to enable popup authentication when a user attempts to print to a non-authenticated printer such as one hosted via an LPR/LPD queue or a CUPS print queue:
• Add the printer to the system as normal. Perform a few test prints to ensure the printer is functioning and tracking as expected.
• Log into PaperCut NG and check the Unauthenticated option under the relevant print to enable the popup authentication.
•
details.
• When a user attempts to print to this printer, they will be prompted for their username and password.
7.10.4.3. User Interaction
When running in popup authentication mode, the client makes available a number of additional options including:
• Logout
• Login as another user
The Logout option is available on Windows via either the right-click option on the task try icon, or when running on
Mac or Linux, via a right-click popup menu (Option Click) access via the icon on the balance window.
The Login as... option is made available if the client starts as an unauthenticated user. This option allows users to
133
Advanced Printer Management authenticate or quickly switch user identity.
7.10.4.4. Advanced Popup Configuration
The login box displayed to the user offers the choice of how long their authentication details should remain active.
An administrator can control the options presented to the user by modifying the following system configuration keys.
These configuration keys are edited under Options
→
Actions
→
Config editor (Advanced)
Config name
client.config.auth.ttl-values client.config.auth.ttl-default-minutes client.config.auth.popup-on-startup-if-unauthenticated
Description
A comma separated list of values to display in the popup authentication login box. Positive numbers represent the number of minutes to remember the authentication for.
The value of
0 indicates that the authentication is remembered for "this print job only".
The value of -1 indicates that the authentication is remembered until the user logs out or exits the client.
The value of
-2 indicates that the authentication is remembered indefinitely, even after restarting the client. For security reasons this change needs to be made in the Config editor, not the client's config.properties
and the client does not save the password. Instead a server generated cookie is placed in a file in the user's home directory.
The default is:
1,5,15,30,60,-1
The default time-to-live value automatically selected when the login authentication window displays.
Determine if the client should request authentication when the client starts if the operating system user is unauthenticated. Set to
Y
(yes = enabled) or
N
(no = off).
Table 7.2. User Client Popup Config Keys
Important
User client tools that are already running will pick up changes made via the config editor the next time they are restarted.
Please see Section 15.10, “Using the Config Editor” to find out how to change config keys.
7.11. Color Detection
The color detection setting determines the method used by PaperCut NG to analyze documents for the presence of color. Changing the detection method may require some additional printer configuration. Please read this section in its entirety.
The standard way used by PaperCut NG to handle color in documents is to see if the printer's driver has set the grayscale flag. When this flag has been set on a document sent to a color printer, the grayscale discount is applied. Otherwise, the document is charged at the printer's standard rate. This may be an inconvenience for users when a large document is printed with just a few color pages.
For example, a user prints a 21 page document to a color printer. The document is all grayscale except for a color header on the first page. When using standard color detection, the user is charged for 21 pages at the color printer's standard rate. As a workaround, the user could send the document as two print jobs (one with just the first page containing color, and another with the rest of the document), but this is an inconvenience. An enhanced alternative is to use page-level color detection. When this option is selected, the user would be charged for one page at the color printer's standard rate, and receive the grayscale discount for the other 20 pages.
PaperCut NG has three options for document color detection:
• Grayscale only (for grayscale printers)
• Standard color detection (also referred to as document-level detection)
134
Advanced Printer Management
• Page-level color detection
The color detection setting is available for each printer controlled by PaperCut NG. To access the setting, click on a printer from the Printers tab to bring up the Printer Details page.
Figure 7.19. The color detection setting for a printer
'This is a grayscale printer'
This option indicates that the printer is not capable of printing color documents, so color detection should be bypassed. This will ensure that the color page count for this printer is always zero.
'This is a color printer (use standard detection)'
When this option is active, documents are treated as being either grayscale (where a printer's driver has set the grayscale flag) or color. This mode is available in almost all color printers. Where users print documents containing both grayscale and color pages, this option encourages users to use color printers only for their color printing.
'This is a color printer (use page-level detection)'
Page-level color detection scans each page of a document for traces of color. The grayscale discount is applied to any grayscale pages and other pages are charged at the printer's standard rate.
PaperCut NG can perform page-level color detection with most modern color printers.
Important: To use page-level color detection:
1.
Apply the page-level detection option for the printer in PaperCut NG.
Linux and Mac systems will pick up the change immediately.
On Windows based servers the change will take up to 2 minutes to propagate to the
Print Provider
. This can be sped up by manually restarting (stop and starting) the
PaperCut Print Provider service via
Control Panel
→
Administrative Tools
→
Services.
2.
On Windows print servers set the Enable advanced printing features on the Advanced tab of the printer's
Windows Properties page according to the type of printer:
Disable the setting for PostScript, PCL, HPGL or XPS printers. (With these printers, Page level detection will work regardless of the advanced printing features setting, but you must disable the setting if you wish to use advanced PaperCut features such as Grayscale/Duplex Conversion Filters and Watermarking.)
Enable the setting for other printer types. On most printers, this setting will cause print files to be spooled using
Window's EMF format. PaperCut supports for page level color detection for EMF. See below for limitations.
3.
On non-Windows print servers page-level color detection is only available for PostScript, PCL, HPGL and XPS printers.
4.
Print a few test documents with both grayscale and color pages and ensure PaperCut NG is correctly charging the document. The Print Log under the Printers tab is a good place to monitor the detection in real-time.
7.11.1. Printer Color Mode Auto-Detection
From version 14.1 onwards, when a printer is first added, PaperCut NG will detect if it is grayscale or color and set its color detection mode accordingly. Color mode auto-detection is performed only once and can be overridden manually.
135
Advanced Printer Management
Color mode auto-detection works well but you may have a reason for not using it. You can turn it off by setting the configuration key printer.detect.grayscale.printers
to
N
. Please see Section 15.10, “Using the Config
Editor” to find out how to change config keys.
7.11.2. Limitations of Page-Level Color Detection
Page level detection works by inspecting the contents of the document looking for color use. The aim is to track down simple black and white only pages so it can offer the user the grayscale discount on these pages. There are a few situations that may cause a seemingly grayscale page to list as color - referred to as a 'false positive'. These situations are rare and are discussed below:
• The use of some image formats, even if they look grayscale, may detect as color. For example, JPEG is a lossy format and artifacts as a result of compression may cause speckles of color. PaperCut NG will handle most of these situations but grayscale JPEG images in PDF files can cause false positives.
• The use of 'color' white-space in Microsoft Word can cause a false positive with some print drivers. For example, the user selects a color font, enters a single space or new-line, and then changes back to black. PaperCut NG in most cases will correctly filter out the 'color space' but may experience problems with some drivers leading to a false positive.
• The Windows Enable advanced printing features setting will allow page level color detection to work for many color printers by spooling print files in EMF format. The accuracy of color detection is dependent on the particular printer driver in use. Our testing has seen very good accuracy with newer printers and drivers, but poorer results with some older drivers. If using an older printer, we recommend you run a representative set of print jobs to verify that the color page counts meet your requirement. Where possible, we recommend you select a PCL or
PostScript driver if available for your printer.
7.12. Validating page counts using hardware checks
PaperCut provides accurate tracking of printer usage by analyzing the printer spool file on the server. Before the job is sent to the printer, PaperCut determines the job attributes including the page count, color/grayscale, duplex, paper-size, etc. This up-front analysis allows PaperCut:
• To calculate the job cost and determine up-front whether the user has enough credit to print.
• To display the job details (e.g. the cost and page count) to the user in the print confirmation screens and release stations.
• To apply filters and policy rules to print jobs (e.g. to disallow non-duplex jobs, or to enforce print policy using the advanced printer scripting).
After the job is queued for printing, PaperCut logs this print job information and charges the usage to the user.
If the job is sent to the printer but it does not print completely (e.g. if the user cancels the job at the printer), then print job hardware checks allow PaperCut to determine the actual number of pages printed. These checks are performed at the hardware-level by communicating with the printer via SNMP (Simple Network Management
Protocol).
The combination of up-front spool file analysis and post-job hardware verification of the jobs provides the best of both worlds:
• Accurate up-front page count and cost calculations; and
• Verification of the printed pages after the job is completed.
7.12.1. Causes for differences in page counts
The printer may report a difference to the PaperCut server's spool file analysis for a variety of reasons:
• The user cancels the job at the printer's panel - e.g. LCD screen or cancel button.
• The printer goes into an error state (e.g. out of toner) after the job has partially printed. The administrator may then cancel the job at the printer.
136
Advanced Printer Management
• The print job may have become corrupted, causing the printer to print 100's of pages of junk (e.g. PostScript code) instead of the user's document!
• Configuration "strangeness" such as the devices double-counting large pages or counting the blank page at the end of a duplex job. Most of these corner-cases have been worked around, however, like all things in
Computing, some are bound to show up again!
7.12.2. Requirements
PaperCut's hardware checks use the SNMP protocol to query the page counters of the printer. This is a network protocol supported by most network printers. To support hardware checks the following is required:
• A network printer that supports the SNMP protocol.
• SNMP enabled in the printer (also ensure the "public" SNMP community is enabled).
• The network/firewall allows SNMP UDP packets from the print server to the printers. SNMP uses UDP port 161.
• Some additional configuration of the printer queues may be required. See installation instructions in
Section 7.12.4, “Configuring hardware checks”.
• Only PaperCut should send jobs to the printer. If a job from another print server is sent it's possible the resulting statistics will be unreliable
7.12.3. How hardware checks work
The Printer SNMP standard allows querying of printer status and page count information over SNMP. PaperCut makes use of this information to verify the number of pages printed for each print job. This works as follows:
1.
Before the print job is sent to the printer PaperCut confirms the printer is idle (i.e. not printing).
2.
A snapshot of the page counters is retrieved using SNMP.
3.
PaperCut waits for the job to complete by querying the printer status and page counts. If the printer is in error
(e.g. out of paper), then PaperCut will continue to wait until the printer error is resolved and the job completes printing.
4.
Once the job is completed and the printer is idle, another snapshot of the page counts is taken.
5.
The total pages printed is calculated using the differences between the initial and the post-job snapshot.
7.12.4. Configuring hardware checks
Printer hardware checks are not enabled by default in installations of PaperCut. Enabling the checks requires some configuration within PaperCut and also some additional configuration of the operating system's printer queues.
Hardware checks may be enabled/disabled at the individual printer queue level, or alternatively the settings can be
applied to multiple printers using the Section 7.3, “Copying Printer Settings”.
7.12.4.1. Enabling hardware checks
To enable the print job hardware checks:
1.
Navigate to the Printers tab.
2.
Select the printer to configure.
3.
Under the Advanced Configuration setting, enable the Enable print job hardware check option.
Figure 7.20. Enabling the hardware check
137
Advanced Printer Management
4.
Press OK or Apply to save the changes.
Important
On Windows print servers, you must also configure the printer to use a PaperCut TCP/IP Port.
For instructions see Section 7.12.4.2, “Windows printer queue configuration”.
Tip
On Windows print servers, this setting can take up to 2 minutes to take effect. This can be sped up by restarting the PaperCut Print Provider service.
When a difference in page counts is reported by the printer, the administrator can choose how this is applied to the print jobs. This option is configured using the When a difference in page counts is detected: settings as follows:
Figure 7.21. Hardware check adjustment options
'Show differences in the log status. Do not adjust'
The page count differences are recorded against the print job, but no adjustments are made to the page counts or job costs. This is the default option when hardware checks are enabled.
This mode can be useful when you want to use the hardware check information to validate refund request by users.
In this case the administrator can verify that a user's job did not complete printing and then refund the job.
The hardware check information is displayed in the print log status and also in the refund screens.
'Apply differences and adjust the print cost automatically'
In this mode, the hardware check information is also recorded on the print jobs as described above. However, any differences in page count and costs will be automatically applied to the job.
For example, if a user printed a 5 page document costing $0.50, and they cancelled the job after only 3 pages were printed, the job cost would be reduced to $0.30 and the user would be refunded $0.20.
In rare situations, it is possible for the hardware check to report an increased number of pages. For example, this might happen when a print job is corrupted and prints out 100's of pages of "junk" instead of what the user printed.
In this case the hardware check will report an increased number of pages resulting in an increased cost. By default
PaperCut will not apply the adjustments to the job if the cost would increase.
If you would prefer to apply the differences even if the cost is increased, then select the Always apply cost
adjustments option.
Tip
138
Advanced Printer Management
To enable the hardware page counts quickly on multiple printers, use the Copy settings to other
printers action available on the left of screen.
7.12.4.2. Windows printer queue configuration
To perform printer hardware checks, the Windows printer queues need to be configured to use the PaperCut
TCP/IP Port type. This port works just like the Standard TCP/IP Port that ships with Windows. The PaperCut
TCP/IP Port allows PaperCut NG to perform the page count checks before and after printing the job.
To configure an existing printer queue to use a PaperCut TCP/IP Port
• Open the Printers list
• Right-click on the printer and select Printer Properties or Properties
• Select the Ports tab.
• Press the Add Port button.
Figure 7.22. Printer properties dialog:
• Select the PaperCut TCP/IP Port option. (Note: if this port does not appear in the list of available port types,
• Press the New Port... button.
139
Advanced Printer Management
Figure 7.23. Printer ports dialog:
• Enter the printer IP address and port name.
• Press Add Port to save the new port.
Figure 7.24. Add port dialog:
• Press the Close button on each dialog window.
• This printer will now be configured to use the new port. The previous port may now be deleted if no longer in use by other printers.
To create a new printer queue to use a PaperCut TCP/IP Port:
• Open the Printers list
• Click the Add a Printer button.
• Choose to add a Local printer.
• When prompted for the printer port, select Create a new port.
• Select the PaperCut TCP/IP Port option, and click Next.
140
Advanced Printer Management
Figure 7.25. Choose printer port:
• Enter the printer IP address and port name.
• Press Add Port to save the new port.
• Complete the Add Printer wizard as normal choosing the drivers, etc.
7.12.4.3. Novell, Linux and Mac printer queue configuration
When using Novell, Linux or Mac there is no additional configuration of the operating system required for hardware checks to be enabled. This function is controlled via the PaperCut administration console and will come into affect automatically shortly after the hardware checks are enabled. On Linux or Mac, the hardware checking is supported for the CUPS backends of socket, ipp and lpd.
7.12.4.4. Changing the SNMP community string
By default, the hardware checks use the SNMP community string of "public". For a basic level of security, one can change the SNMP community string that is used. This must also be set in the configuration of the printer.
1.
Open the file
[app_dir]/providers/print/[platform]/print-provider.conf
in a text editor such as Notepad.
2.
Locate the line
SNMPCommunity= and enter the new community string on the right-hand-side of the equals line.
For example:
SNMPCommunity=secretcommunity
7.12.5. Reviewing hardware check results
Hardware check results are recorded in PaperCut on the print log records. When a hardware check is recorded the
Checked status appears in the Status column of the print logs as shown below.
141
Advanced Printer Management
To see the basic details of the hardware check, hover your mouse over the Checked status.
Figure 7.26. Hardware check status
When the hardware check detects a difference, click the Checked status link to see more detailed information.
To manually apply hardware checks to a print job (if this is not configured to apply automatically):
1.
Click on the Checked status.
2.
Review the hardware check information.
3.
Press the Apply Differences button. This will apply the page counts and any cost differences to the print log.
Figure 7.27. Hardware check log status
142
Advanced Printer Management
7.12.6. Known Limitations
Hardware-level page count checks are not enabled by default. Sites should carefully consider these limitations and known issues before implementing:
• The use of the PaperCut TCP/IP Ports in a Microsoft Clustered Windows Printing Environment should be
PaperCut). Clustering is a complex technology and further work is being undertaken to support the Hardware
Page Count Checks in a clustered environment. We don't recommend its use in a production environment at this time.
• Hardware-level checks will slow down printing a little (a few seconds between each job). The system needs to take a count snapshot before and after a job. The start/end of a job is detected by the printer entering an idle state and stabilization on some devices can take a few seconds (printing => idle). This process adds a small delay between each job.
• Copier functions that delay printing such as printing to a "Mailbox" will prevent PaperCut from detecting the print job as it is expected that the print job is printed imediately.
• Not all devices support SNMP and even some devices that do, do not support the ability to check page counts at the hardware level. Most major MPF/MFD devices support SNMP, however smaller printer brands may not. We suggest taking some time to test this option across your device type(s) once enabled.
• On Windows, a different Printer Port needs to be installed/configured to support this level of device integration.
Care has been taken to emulate the behavior of the Standard TCP/IP Port, however some drivers may complain if a non-default port is selected. Although this is rare, it may cause issues with some drivers. Always test the printer after changing the printer port. The development team is looking at ways to remove the dependency on a custom port, however at the current time this method has proven to be the most reliable.
• The use of non-PaperCut hold/release functionality on printers and copiers may cause inaccurate hardware validation as it will appear that the job never prints, or at least in a timely fashion. It is recommended to use
PaperCut based release stations where required: (see Chapter 13, Hold/Release Queues & Print Release
• If you have many printers it's very time consuming to use the Windows GUI to change the ports! Sorry about this, however we've not found a reliable way to script this process. Our recommended approach is to first test on a representative sample of your devices for a few days, then role the port change out across your fleet. We have found that some good music on the iPod and copious amounts of coffee will help ease the frustration :-)
7.12.7. Troubleshooting
7.12.7.1. The "Checked" status does not appear on any print logs
• Verify that the printer supports SNMP and that SNMP v1 or v2 is enabled in the printer's admin interface.
• Ensure that your networks and firewalls allow SNMP traffic (i.e. UDP port 161) between your print server and printers.
• If using a Windows print server, check that the printer is configured to use the PaperCut TCP/IP Port. See
Section 7.12.4.2, “Windows printer queue configuration”
•
• You can test that PaperCut can query SNMP data from the printer by running the following in a command prompt or terminal/shell:
Windows:
[app-path]\providers\print\[platform]\pc-print-monitor.exe -p -h [printer-ip]
Mac/Linux/Novell:
[app-path]/providers/print/[platform]/pc-print-monitor -p -h [printer-ip]
143
Advanced Printer Management
If SNMP data can be retrieved, some basic status information will be printed. If not, an error is displayed.
• If you are still unable to diagnose the problem, then please send the following log files in a support request:
Windows:
[app-path]\providers\print\[platform]\print-monitor.log*
[app-path]\providers\print\[platform]\print-provider.log*
Mac/Linux/Novell:
[app-path]/providers/print/[platform]/print-provider.log*
7.12.7.2. Why is the "Checked" status missing on some print logs?
• An intermittent networking problem between the print server and printer may have stopped the SNMP page counts from being retrieved. E.g. the network was briefly interrupted while PaperCut was waiting for the print job to finish printing.
• If the job is deleted from the print queue while in progress PaperCut will cancel any hardware checks and the
Checked status will not appear on the print log. To avoid this, it is recommended to fix any problems (e.g. out of paper, etc) at the printer and then allow the document to finish printing. This will allow PaperCut to retrieve the page counts from the printer after the job completes. Only delete the job from the queue if it stays stuck even after the printer error has been resolved.
7.12.7.3. Why is the PaperCut TCP/IP Port not available to be chosen in port selection on Windows?
• A possible reason why the PaperCut TCP/IP Port is not available may be because the port was unable to be installed due to a Security Policy disabling the installation of unsigned drivers. A solution for this is to change the
Security Policy for the unsigned driver installation behavior to either allow unsigned driver installations or to warn but allow their installation.
7.13. Watermarking/Job Annotation
Watermarking is a feature that allows a small portion of text to be written to the bottom (or top) of every page.
Watermarking is a powerful and flexible feature. Typical uses of watermarking include:
• adding a username to the bottom of every page to help identify the owner
• writing job metadata in the footer such as print time, printer or document name
• applying a digital signature to help track and verify documents
Watermark text is defined by the PaperCut administrator and can be applied to printers individually. Print scripting
Watermarks may contain substitution variables allowing the insertion of document metadata such as date/time, username, document name, etc.
A typical watermark is shown the picture immediately below. This watermark uses the
%user%
,
%date% and
%signature% substitution variables described in the Substitution Variables section.
144
Advanced Printer Management
Figure 7.28. An example watermark using variables
Note
PaperCut NG watermarks print jobs by modifying the print stream as jobs spool via the print server.
The watermark is injected into the job using advanced PDL methods such as macros and overlays.
This is the reason why PaperCut only supports standards based print languages like PCL and
PostScript - PaperCut must understand the job and its data to perform this on-the-fly modification.
Important
Watermarking is a new feature that uses advanced printer techniques that can be implemented differently by each device manufacturer. Please report any problems that you may experience to our support team for investigation.
7.13.1. Typical Uses
1.
Owner Identification. Add the username to each page so it is easy to find the owner (e.g. uncollected print jobs).
Suggested Watermark:
Printed by %user%
2.
Student Assignments. Add the username and time of printing to each page. This will help teachers match up student work and help students prove that assignments were delivered on time.
Suggested Watermark:
Printed by %user% at %date% on printer %printer%
3.
Tracking an Organization's Physical Documents. Add a sequentially allocated number to every document printed. This number is a document-level Bates number (http://en.wikipedia.org/wiki/Bates_numbering). It is recorded in the PaperCut NG database and is useful for organizing document trails.
Suggested Watermark:
Document No.: %bates% composed of %pages% pages
4.
Identification and Source Tracking. Add a unique and secure digital signature to each document. This can be used to verify the origin and generation details of a document. (Note: see Digital Signatures in Detail section below if security is required).
Suggested Watermark:
%signature%
5.
Protecting Value of Documents. The copy protection aspects of watermark signatures described above can be used to protect valuable documents where royalties apply.
Suggested Watermark:
Copyright ABC Corporation.
All rights reserved.
Document
Signature: %signature%
6.
Behavioral Change. The cost of each print job is added to the bottom of each page. This gives the user immediate feedback on the cost of their printing.
145
Advanced Printer Management
Suggested Watermark:
The cost of this print job is: %cost%
Tip
To configure watermarking based on the user (e.g. a user's group membership) or job attributes, consider the Advanced Scripting feature. Advanced Scripting allows the watermarking to be
enabled/disabled and the watermarking text to be adjusted to meet any need. See Chapter 20,
Advanced Scripting (Print Scripting) for more details.
7.13.2. Requirements
Watermarking is currently available for printers using PostScript and PCL drivers. You should ensure that the printer driver uses the PostScript or PCL language rather than GDI or other languages. This can be verified by observing the word
PostScript
,
PCL5 or
PCL6 in the Job Log as shown in the screenshot below.
Figure 7.29. Print Job Log showing the PostScript metadata
On Windows systems, if the language lists as EMF then you will need to turn off "Advanced Printing Features" as
described in Section 7.13.5, “Troubleshooting”.
7.13.3. Enabling Watermarking
Watermarking is enabled in a printer’s Printer Details
→
Advanced Configurationsettings via the options Apply
watermarks to all pages.
146
Advanced Printer Management
Figure 7.30. Enabling watermarking in the Admin Console
7.13.3.1. Options
Text is the text that will be printed on the watermark. It is possible to use macro substitution variables such as
%user% and
%date%
. Substitution variables are described in the Substitution Variables/Macros section below.
Gray level determines how dark or light the text will appear. Medium is the default. Light should be just viewable.
Font size determines the watermark text size.
Position can be bottom left of page, top left of page, or custom. Custom is intended for advanced situations where some tweaking is required due to differences in page printable area. Custom positions are specified as the distance from the left of the page and distance from the bottom of the page in millimeters.
7.13.3.2. Substitution Variables/Macros
Field
%user%
%user_primary_card_id%
%user_secondary_card_id%
%user_full_name%
%user_email%
%date%
%document%
%server%
%printer%
%client_ip%
%client_machine%
%job_id%
Description
The name (username) of the user that printed the document.
The user's primary ID code.
The user's secondary ID code.
The full name of the user that printed the document.
The email address of the user that printed the document.
The date/time that the document was printed. The date is formatted in according the locale of the server. An example of a
%date% is
12/12/2010 3:12:37
PM
.
The name of the document that printed.
The server name that is hosting the printer that printed the print job.
The name of the printer where the print job was printed.
The IP address of the workstation the job was sent from.
The name of the workstation that sent the print job.
The PaperCut NG job id of the job.
147
Advanced Printer Management
Field
%copies%
%cost%
%pages%
%bates%
%signature%
%digest%
%sig_md5%
%digest_md5%
%sig_sha1%
%digest_sha1%
Table 7.3. Substitution Variables/Macros
Description
The number of copies of the document that was printed.
The cost of the print job.
The total number of pages in the print job.
A sequentially incrementing number based on a Bates Numbering
(http://en.wikipedia.org/wiki/Bates_numbering) scheme.
All pages in the document are stamped with the same number. The number is recorded as a signature in the print log.
A unique secure digital signature (in text form) generated via an MD5 HMAC.
The signature is recorded in the print log. See Digital Signatures in Detail
(Advanced) below for technical details.
A unique digital signature (in text form) generated using an MD5 of various document attributes.
Same as
%signature%
.
Same as
%digest%
.
Same as %signature% but based on the SHA1 message digest algorithm.
Same as
%digest% but based on the SHA1 message digest algorithm.
7.13.3.3. Restrictions and Limitations
To ensure a document that has a unique single signature, only one digital signature macro should be used in a watermark. The digital signature macros are:
•
%bates%
•
%signature%
•
%sig_md5%
•
%sig_sha1%
7.13.4. Digital Signatures in Detail (Advanced)
7.13.4.1. Signature Algorithm
PaperCut NG document digital signatures are generated using a cryptographic technique called an HMAC
(http://en.wikipedia.org/wiki/HMAC). This works by taking various print job attributes such as print time, username, printer name and document name and combining them with a secret key. The result is then passed through a digest algorithm such as MD5. The resulting signature is unique to the document. The secret key portioning ensures that it is not possible to predict a signature. Two message digest algorithms are available: MD5 And SHA1. In our opinion
MD5 will be secure enough for print job signature applications, however for cryptographic completeness SHA1 is provided as an option. Using MD5 makes it easier to enter keys to find matching print jobs because the signatures are shorter.
Note
The algorithm used is:
•
Digest = Hash(date time || username || server name || printer name || document name || job id)
•
Signature = Hash(Digest || Key)
148
Advanced Printer Management where
• key is a random string generated on first use and stored in the config key
"print.signature.hmac-key" and hash is either MD5 or SHA1.
• date time is formatted in ISO 8601 basic format from year to second ("yyyyMMddTHHmmss").
The time is local time (not UTC). E.g. "20100130T141059"
7.13.4.2. Verifying a Signature
If a document is located, say due to an information leak, the signature can be used to track down the print event details such as the originating user, time of print, and other details. This is done as follows:
1.
Printers -> Job Log
2.
Expand the filter section
3.
Enter the signature in the signature signature field.
4.
Press Apply. The matching job should list.
For example, the following screenshot shows how to search for the print job with signature b608c7a39f08643768051217f2f5315a in the job log.
Figure 7.31. Searching job log for signature b608c7a39f08643768051217f2f5315a
7.13.5. Troubleshooting
Watermarking requires print jobs to be printed in PostScript or PCL format. If your document is printed in EMF you may be able to print in PostScript or PCL by following the procedure listed in the EMF section below. For all other
drivers please see Section 7.13.5.2, “Other Printer Languages”.
7.13.5.1. EMF
149
Advanced Printer Management
On Windows systems, if the printer language for a job lists as
EMF then you will need to turn off "Advanced Printing
Features". Disabling this option will cause print jobs to be rendered into their printer language on the client side.
Enabling it can result in rendering on the server side, which is usually unwanted.
Figure 7.32. Job Log showing an EMF job
You can do this by following these steps:
1.
On the print server, navigate to: Start
→
Control Panel
→
Printers
→
[right-click printer]
→
Properties
→
Advanced
2.
Turn off (disable) the option Enable advanced printing features.
3.
Test printing and check the printer language to ensure that it is now PostScript or PCL.
You can read more about this setting on the Microsoft website at: http://support.microsoft.com/?kbid=268093.
7.13.5.2. Other Printer Languages
If the printer language for a job is listed as a non-supported language such as ESC/P2(Epson) then watermarking will not work. The manufacturer may also support other languages such as PostScript as an option. Please check the printer manufacturer's website download page for details.
Figure 7.33. Job Log showing a ESC/P2(Epson) job
7.13.5.3. Updating Printer Drivers
When updating printer drivers, it is important to update the printer drivers on both the client and the server.
7.14. Behavior on Server Connection Failures
There are various scenarios where the users want to print their print jobs but the PaperCut Application Server is unable to receive the information about the printing, including when:
• The Application Server's machine is being rebooted,
• The network link is down between a Secondary Print Server on a remote machine and the Application Server,
• The administrator has decided to shutdown the Application Server for maintenance.
When this occurs PaperCut must decide on how to handle the print job without communicating with the Application
Server. The administrator can configure PaperCut to handle new jobs in 3 ways:
1.
Allow new print jobs to print but do not log (default),
2.
Allow new print jobs to print and log after reconnection,
3.
Do not allow new print jobs to print but hold and wait for reconnection.
Each of these options offer different compromises, and the best option will depend on the needs and priorities of a
150
Advanced Printer Management particular installation. For example, if it's important to never interrupt printing then options 1 or 2 can be selected. If it's important to strictly enforce quotas (i.e. allow the job to be cancelled if they do not have enough quota) and it is acceptable to delay printing until the connection is reestablished then option 3 can be chosen. These options are discussed in further detail below.
These configuration options are controlled under the Printers+[select printer]
→
Failure Mode.
Figure 7.34. Failure mode settings
7.14.1. Failure Mode Settings
7.14.1.1. Mode 1: Allow new jobs to print but do not log
This is the default mode and will allow jobs to print when the connection to the server is down (a "fail open" mode).
The jobs printed during this period will not be logged in the Application Server. This mode can be used when:
• It is important to not interrupt printing when outages occur,
• The setup needs to be simple and easy to understand,
• It is not important to log jobs printed during failures,
• Strict quota enforcement is not required, Users will not be charged for printing that occurred during the outage.
7.14.1.2. Mode 2: Allow new jobs to print and log after reconnection
This mode allows jobs to print when the connection to the primary server is down, but when the connection is re-established these jobs are re-sent to the Application Server and logged (a "fail open" mode with re-send/offline mode). This mode can be used when:
• It is important to not interrupt printing when outages occur,
• It is important to log/charge every job printed during failures,
• Strict quota enforcement is less important. Users may end up using more credit than they have available.
In this failure mode the administrator can configure how these resent jobs are recorded in the job log:
1.
Leave the job information unchanged (i.e. log the job against the user that printed it),
2.
Change the recorded user to another nominated user,
3.
Change the charging of the print job to a nominated shared account.
The default reconnection option is 1, where we log and charge the same way we would if the recording was done live. The administrator may consider this unfair to charge the user during this failure time (as there were no warning popups or ways of telling that the user's quota was reaching its limit). It may be more reasonable to use the
151
Advanced Printer Management reconnection options of 2 or 3. With option 2, the administrator can choose a new user such as "AppServerDown" to record the job as and in this way completely divorce the user from jobs printed during the failure.
If the administrator would still like to track who did the printing but just thinks it is unfair to charge their personal account, then reconnection option 3 can be chosen, and a new shared account such as "AppServerDown", or an account corresponding to the department owning the printer can be charged. Jobs are still recorded under the user's name.
When the connection to the Application Server opens up again, the print jobs will show up in the Application Server's job log within a few minutes. They will show up with a special status and icon in the job log (see figure below).
Figure 7.35. Status of print jobs logged after reconnection
7.14.1.3. Mode 3: Do not allow new print jobs to print but hold and wait for reconnection
In this mode all jobs will be held in the queue while the connection to the server is down (a "fail closed" mode). Once the connection to the server is reestablished the jobs will be sent to the server and printing will be processed as normal. This mode can be used when:
• Strict quota enforcement is required,
• Secure Print Release or Find-me printing is used and jobs must not be printed until released by a user.
7.14.2. Failure Mode Settings on Virtual Queues
recommended to hold the all jobs and wait for reconnection when the server connection is down. By default, this setting is enforced by PaperCut to ensure the correct operation of the virtual queue.
If jobs are released from the virtual queue when the server connection is down, the jobs would be released to the configured printer (i.e. the configured printer port). If the queue is configured with a NULL port, the jobs are deleted.
If configured for a non-existent printer (e.g. LPT1) then the jobs go into an error state. If configured for a real printer, the jobs will be sent to the printer (contrary to the secure release / Find-me printing that the user expects). It is for these reasons that the failure mode on virtual queues is set to hold all jobs.
Some organizations prefer to have the virtual queue pointing to a real/physical printer so that if a failure occurs the jobs will be printed. This is usually only acceptable if the organization is happy that users jobs be printed on a single queue (bypassing any secure print release function). To configure this, enable the Override virtual queue failure
152
Advanced Printer Management
mode option and select one of the alternative modes. This option is only visible on virtual queues.
7.15. Toner Levels (for supported printers)
Managing printer toner on a large fleet of printers can be a time-consuming task. The administrator must track toner usage and ensure that replacement toner cartridges are available when printer toner runs out. Often the administrator is only made aware that a printer is out of toner after receiving complaints from users. PaperCut NG can track the toner levels for supported printers and provide toner level information in reports or email notifications when the toner is low.
Armed with this information the administrator can purchase toner supplies in advance and replace toner cartridges before the printer runs out of toner. This saves the administrator time and ensures that printer downtime is minimized.
Figure 7.36. Toner level information on Printer Details screen
7.15.1. How toner level information is retrieved?
PaperCut NG retrieves toner information from supported printers using the SNMP network protocol. Most modern network printers allow the toner information be queried via SNMP. PaperCut NG can retrieve toner information for printers that meet the following requirements:
• The printer is networked (i.e. it is connected to your network and not directly to a computer with a USB or parallel port).
• The printer supports SNMP and it is enabled.
• The printer supports the SNMP standard for printers (RFC 1759) that allows toner information to be retrieved in a standardized way. Most network printers support this standard.
• The PaperCut NG server can establish SNMP connections to the printer. Ensure that your network (e.g. routers, firewalls, etc) allow SNMP connections between the PaperCut NG server and your printers.
PaperCut NG regularly updates the toner information to ensure the data is kept up-to-date.
A report with 'Toner Status', 'Lowest Toner Value' and 'Toner Last Updated on' fields can be generated from the
Admin Console. Select the Printers tab to open the Printer List. At the bottom of the list select Export / Print in Excel format.
Tip
The thresholds for low and very low toner level warnings visible on Dashboard are configurable. The threshold values can be configured using the following config keys toner.low-threshold and toner.very-low-threshold
. Please see Section 15.10, “Using the Config Editor” to find out how
to change config keys.
7.16. Printer Quick Reference
How do I view printing history?
153
Advanced Printer Management
Printing history can be quickly accessed via a number of areas. The most appropriate area depends on the information required.
• To view a user's printing history select the Job Log under the user's details page.
• To view recent print jobs printed on a printer, select Job Log under the appropriate printer's details page.
• To view all print jobs printed on the network with advanced search and filtering options, use the global Print Log under the Printers section.
How do I add a new printer?
On Windows systems, new printers will be added to the system automatically once the printer is added to a monitored server. On a Mac or Linux system, after PaperCut NG is enabled on the printer, it will list in the administration interface after first print. New printers are assigned initial settings based on the configuration assigned to the
[Template Printer]
.
How do I delete a printer?
Once the printer has been removed from the operating system's print list, the printer may be deleted from PaperCut
NG via the delete printer action under the printer's detail page. This action will remove the printer from the monitored list. Print history logs are still maintained allowing access to historical data. Always confirm your action before proceeding with the delete!
How do I disable a printer?
Printers can be disabled indefinitely or for a specified time via the Disable option under the printer's details section.
How do I tell PaperCut NG to ignore (not monitor) a printer?
By default on Windows systems all printers are tracked by PaperCut NG. The Print Provider can be instructed to ignore a printer by setting the
IgnorePrinters= attribute in the print-provider.conf
file. A restart may be required for this to take effect. Note: This setting only stops monitoring. The printer will continue to be listed under the printer list section until it is manually deleted via the Delete printer action.
For more information see Section 7.1, “Adding and Removing/Deleting/Ignoring Printers”.
What can I use the printer notes field for?
The Notes field under each printer is useful for tracking all manner of information. Typical uses include:
• Tracking configuration changes
• Recording maintenance and/or toner replacements
• Documenting problems
• Leaving notes/comments to assist other administrators.
7.17. Refunding Print Jobs
Paper jams, toner problems and print quality issues will always occur. Larger organizations will require a policy to address these situations and under what conditions a print job may be refunded. The assessment to give a refund or not is subjective and needs to be managed by responsible administrators. To streamline and partially automate the process PaperCut NG provides a browser based refund management process.
Highlights include:
• Users can request refunds via a simple form and track their status.
• Administrators can quickly approve/deny requests with one click.
• Administrators can be alerted via email when requests are pending.
• Issue partial and manual refunds.
154
Advanced Printer Management
7.17.1. Enabling End-User Refunds
Users request refunds via the end user web pages. This feature is enabled as follows:
1.
Log into PaperCut NG admin interface.
2.
Navigate to Options
→
General.
3.
Under User Features, enable the option Allow users to request refunds.
Figure 7.37. Enabling end-user print job refund requests
4.
Click Apply.
End-users may enter a reason why they are requesting a refund. Some organizations may prefer to disable this feature, e.g. where users may write inappropriate comments. To disable end-user comments/reasons, deselect the
Allow users to enter a reason for their request checkbox.
It is recommended that organizations follow a formal refund policy. This policy may be outlined via Refund
policy/instructions option. This text may also include basic HTML markup such as a link to an external policy page.
7.17.2. Managing Refunds
The refund process is best described in the form of an example.
7.17.2.1. How users request refunds
John's print job failed to fully print due to a printer jam, forcing him to reprint the remainder of the job on another printer. He would like to request a refund of approx. 50% of his job cost for the first failed job. John would place the request as follows:
1.
Log in to the user web interface at http://[server_name]:9191/user using his network username and password.
2.
Locate the first, failed print job on the Recent Print Jobs page.
3.
Click the [Request Refund] link.
Figure 7.38. A [Request Refund] link on the Recent Print Jobs
155
4.
Enter a reason.
Advanced Printer Management
Figure 7.39. Sending refund request
5.
Click Send.
7.17.2.2. The administrator approval process
Jenny is an IT administrator at John's school. She has just received an email indicating that refund requests are pending review. To approve John's request Jenny would:
1.
Log into PaperCut NG admin interface.
2.
Navigate to Printers
→
Refunds.
3.
Locate John's request and review.
4.
Click the Approve link.
Figure 7.40. Approving a refund request from the Refunds tab in the admin interface.
Jenny could have denied the refund request by clicking on [reject] link. Clicking the [other] option would have
156
Advanced Printer Management allowed Jenny to review John's previous requests for refunds, edit the requested amount and write a comment.
Figure 7.41. Overview of user's refund request
7.17.3. Admin Notifications
Administrators may receive regular emails about pending refund requests. Email notifications can be enabled via
Options
→
Notifications
→
System Notifications
→
Notify when there are pending refund requests. More
information is available in Section 15.6.2.4, “Pending refund request notifications”.
Emails may be delivered hourly or daily. By default daily messages are delivered at 7 a.m. This hour of day can be configured via the config key notify.pending-refund-requests.daily-hour-of-day
“Using the Config Editor” for information about changing config keys.
7.17.4. User Notifications
Users may receive an email notification when their refund request has been actioned by an administrator. To enable this feature:
• Enable the option at Options
→
General
→
User Features
→
Allow users to request refunds
→
Email user
when their request is processed.
•
• Either the user must have an email address defined, or the email suffix must be enabled.
157
Advanced Printer Management
Figure 7.42. Printer refund request user notification options
The Email subject and Email body options make up the subject and body of the email that is sent to the user. The
Approved message
and
Denied message
options are used for the replacement marker
%approved-or-denied-message% in the email body.
Other than the
%approved-or-denied-message% marker, the following markers can be used in any of the above four fields:
Field
%job.copies%
%job.cost%
%job.date%
%job.document%
%job.pages%
%job.paper-size%
%job.printer%
%refund.refund-amount%
%refund.request-amount%
Description
The number of copies in the print job.
The original cost of the print job.
The date the original print job was sent.
The document name of the print job.
The number of pages in the print job.
The paper size of the print job.
The printer the print job was sent to.
The amount that was refunded.
The refund amount requested by the user.
158
Advanced Printer Management
Field
%refund.request-date%
%refund.request-reason%
%refund.request-username%
%refund.response-date%
%refund.response-reason%
%refund.response-username%
%refund.status%
Table 7.4. Fields available printer refund request user notifications
Description
The date the user made the refund request.
The reason the user gave for the refund request.
The username of the user making the refund request.
The date the refund was actioned.
The reason the admin user gave for approving/denying the refund request.
The username of the administrator who actioned the refund request.
The status of the refund request as it appears in the Job Log.
7.18. Custom Printer Fields
To assist with device management, custom fields may be enabled on printers. Custom fields can be assigned user-defined names and can represent any data you would find useful for printer management in your organization.
Common examples include recording metadata such as, asset number, lease period, device status, date of acquisition, last maintenance date, department ownership, etc.
Up to six custom fields may be defined. The names are set by the administrator as per the site requirement. In turn, these custom fields may be used for many purposes such as recording data, filtering lists, and creating/exporting reports.
7.18.1. Defining Custom Printer Fields
To define a custom printer field(s):
1.
Log into the PaperCut NG admin interface.
2.
Navigate to Options
→
General.
3.
Under Printer Options, select Enable custom printer fields.
Figure 7.43. Defining custom printer fields
4.
Enter an appropriate name for
Name 1 and repeat for any other fields that you plan to use.
5.
Click Apply.
Once enabled, the custom fields will be visible in the Printer Details page.
159
Advanced Printer Management
Figure 7.44. Custom printer fields
The custom field may also be used in other areas of the application such as filtering the printer list, and applying ad-hoc reporting conditions.
7.19. Extracting Usernames in Enterprise Print Environments (e.g. SAP, Unix)
It is common in an enterprise print environment using packages such as SAP, JD Edwards, Oracle Financials or
Unix systems for print jobs (e.g. batch reports) to appear in print queues under a system account name rather than the instigating user’s account name. The result is that all jobs printed from these programs are recorded in the
PaperCut NG job log as owned by the program/system account.
In most environments, these programs or systems can be configured to write the username into the print spool file
(PDL). For example, the username may be added as a PJL header. If this is done then PaperCut can extract the username and use it in place of the username supplied to the print queue.
Tip
This feature is often combined with Username Aliases (enable Username aliasing under Options
→
Advanced) when dealing with differences between the usernames used in the PaperCut NG environment and the external system or program that submits these jobs. For example, john.wayne
in PaperCut NG may have jwayne as a SAP user ID. For more information see Section 6.10,
The extraction process, when configured, follows a number of rules that an administrator should be aware of:
1.
It is possible to define multiple patterns to extract the username. The matching process will return the first valid result found.
2.
Username extraction at the current time is not supported on Novell.
3.
The username should appear in the first megabyte of the spool file.
7.19.1. Configuring PaperCut to Extract Usernames from Spool Files
Username extraction from spool files is performed by the PaperCut Print Provider and as such any configuration text described in the following steps needs to be inserted into
[app_path]\providers\print\win\print-provider.conf
. After a change to the config is made, the Print
Provider service should be restart before testing.
7.19.1.1. Extracting Usernames using the Simple Method
The Simple Method uses prefix and suffix text as static bookends for the username that should be extracted. In the below example (which can be copied and pasted into your print-provider.conf), the user john.wayne will be extracted from the string
@PJL COMMENT SAP_USER="john.wayne"
. Simple Matching should be sufficient in the majority
160
Advanced Printer Management of customer environments.
#
# Extract username from spool files coming from our enterprise system.
# Look for a header that matches @PJL COMMENT SAP_USER="john.wayne"
#
UsernameOverridePrefix=@PJL COMMENT SAP_USER="
UsernameOverrideSuffix="
7.19.1.2. Extracting Usernames using the Advanced Method (Regular Expressions)
The Advanced method adds powerful regular expression pattern plus the ability to define up to five of these patterns, labelled
UsernameOverrideRegex1 to
UsernameOverrideRegex5
. Administrators using this method should be familiar with regular expressions. The username is extracted from the first bracketed match group (e.g.
$1).
In the example below two patterns are matched:
#
# Extract username from spool files coming from our enterprise system.
# Username may be defined in one of two formats:
# (john.wayne) XJXsetUserName
# /Author (john.wayne) def
#
UsernameOverrideRegex1=\((\S+?)\)\s*XJXsetUserName
UsernameOverrideRegex2=Author\s*\((\S+?)\)\s*def
The table below shows some further examples of username declarations seen in spool files and corresponding regular expressions that can extract the correct username.
Username in Spool File
@PJL SET USERNAME="john.wayne"
@PJL SET USERNAMEW="john.wayne"
@PJL XJAUSERNAME = "john.wayne"
@PJL COMMENT "Username: john.wayne"
@PJL COMMENT CANPJL SET USERNAME="john.wayne"
@PJL COMMENT "Username: john.wayne;App FileName: True Grit.doc"
@PJL OKIAUXJOBINFO DATA="UserName=john.wayne"
%%For: john.wayne
/USERNAME (john.wayne) def
/UserName (john.wayne) def
/Author (john.wayne) def
(john.wayne) /RRCustomProcs /ProcSet findresource begin logusername end
(john.wayne) XJXsetUserName
Table 7.5. Examples of usernames seen in spool files and regular expressions to extract them
Regular Expression to Extract Username
@PJL\s+SET\s+USERNAME\s*=\s*"(\S+?)"
@PJL\s+SET\s+USERNAMEW\s*=\s*"(\S+?)"
@PJL\s+XJAUSERNAME\s*=\s*"(\S+?)"
@PJL\s+COMMENT\s+"Username\s*:\s*(\S+?)"
@PJL\s+COMMENT\s+CANPJL\s+SET\s+USERNAME\s*=\s*"(\S+?)"
@PJL\s+COMMENT\s*"Username\s*:\s*(\S+?)\s*;
@PJL\s+OKIAUXJOBINFO\s+DATA\s*=\s*"UserName\s*=\s*(\S+?)\s*"
%%For:\s*\(?([\w\.-=]+?)\)?\b
/USERNAME\s*\((\S+?)\)\s*def
/UserName\s*\((\S+?)\)\s*def
/Author\s*\((\S+?)\)\s*def
\((\S+?)\)\s*/RRCustomProcs\s*/ProcSet\s+findresource\s+begin\s+logusername
\((\S+?)\)\s*XJXsetUserName
161
Chapter 8. Shared Accounts
PaperCut NG has two types of accounts - personal accounts and shared accounts. Each user has a personal account. This is the default account charged under normal operation. In some organizations and businesses it may be useful to provide users, or selected users with the option to charge printing to a shared account. Some uses of shared accounts include ...
In business:
• Allocate and budget printing by business areas (e.g. cost center)
• Track printing by project, phase, client or account
• Track printing by client/matter - popular in legal and accounting firms
In a school or university:
• Budget staff use via shared faculty or department accounts
• Provide share accounts for classes or subjects
• Track printing costs by subject areas
Shared account scenario
East Beach High School has implemented PaperCut NG to control their printing. Students are allocated a $5.00 a month budget. Pre-paid cards are sold at the library for students who need extra credit above this allowance.
Teachers and staff are given a small personal budget to cover casual printing with curriculum material to be allocated to share accounts. Shared accounts exist for each faculty. The network administrator has granted staff members access to the share account popup. Access to faculty accounts is controlled via Active Directory group membership.
Sarah is a Science and English teacher at the school. When she prints she is able to allocate the print job to either her personal account or either the Science or English shared account via a drop-down list. She can also view the
shared accounts balances from the User web pages.
162
Shared Accounts
Figure 8.1. Selecting a shared account with the User Client popup
Tip
To educate the users about shared accounts, administrators might find the sample information sheet
helpful.
8.1. Creating a Shared Account
Personal user accounts are automatically created when users are first imported into the system. Shared accounts are created manually on an as-need basis. Normally shared accounts are created manually via the administration interface, however organizations with many accounts and good IT skills can automate the account creation process by importing accounts. Import options include via a file (for example Excel, or an export from a 3rd party system) or
“Batch Shared Account Import and Update”.
To create a shared account:
1.
Log into PaperCut NG as an administrator (e.g. admin account).
2.
Select the Accounts tab.
3.
Click the Create a new account action.
4.
Enter an appropriate name for the account. Account names should be as descriptive as possible.
5.
Complete other details such as starting balance, restrictions status and notes as appropriate.
6.
Click the OK button to save the changes and return to the accounts list.
163
Shared Accounts
Figure 8.2. Creating a shared account
By default shared accounts default to an unrestricted status. This means that the account's balance is allowed to drop below zero. Many organizations use shared account to track printing expense. A common strategy is to start the account off at a zero balance and let it count down into the negative. By setting the account to restricted and allocating an initial starting balance, shared accounts can be used as a budget control system as printing to the account is denied once credit is exhausted.
Tip
PaperCut NG has support for advanced parent/child account structures. The subsequent account
naming conventions section covers many of the common practices. See Section 8.2, “Account Naming
Each account can also be assigned a PIN/Code that helps uniquely identify an account. Many users use the codes to represent cost-centers, clients, projects, etc. These codes are often also used in other systems (like the accounting system) to identify these accounts consistently across the organization. Once defined, these codes can be used in the client software to quickly search for accounts, and can also displayed in account-based reports.
The account PIN/code can be entered on both parent and sub-accounts. For example, it is common to use parent accounts to represent clients and sub-accounts to represent projects for those clients. In this scenario, the parent account code would represent a client code, and the sub-account code would represent the project code.
8.1.1. The Template Account
The
[Template Account] is designed to save time by applying the most common settings to all newly created accounts. The
[Template Account] can be found on the Shared Account List page of the Accounts tab.
164
Shared Accounts
Figure 8.3. The template account
Any settings applied to the template account will be applied to new accounts when they are created.
Figure 8.4. Template account settings
Some examples of where the template account might prove useful include:
• Applying common security settings. For example, if the
Staff group should have access to all accounts, adding the group to the template account will ensure group members can also charge to future accounts.
• Applying a starting balance. The starting balance might represent the standard department print quota or the amount of 'free printing' a customer has before they are billed for the excess.
8.2. Account Naming Guidelines
Administrators are encouraged to create accounts as logically related groups. Doing so makes for easier searching and charging, and better integration with existing accounting systems.
Different account models may be adopted by organizations depending on their requirements. Common models are:
• Faculty or Department - a simple flat list familiar to schools, colleges and Universities.
• Client / Matter model - familiar to legal and accounting firms
• Project / Phase model - familiar to engineering and technology firms
165
Shared Accounts
• Customer / Job model - familiar to other customer based firms and common in accounting software
The following sections describe how to configure PaperCut NG to best match the three advanced models.
8.2.1. Client / Matter Naming Model
The client / matter model is one with which legal and accounting firms are familiar. In this model:
• Top level accounts are created for each client
• Sub-accounts are created for each matter under the relevant client
Usually, charging directly to a client (without a matter) is not allowed in this model. Instead users should charge to the relevant matter. System administrators should set each top level account to be inactive (disabled), and all
sub-accounts only.
Figure 8.5. Client / Matter Naming Model example
As shown in the example, the shared account code is used as the client code for the top level client accounts, and the matter code for the matter sub-accounts. In the account list, the sub-account codes are displayed as
[parentCode]-[subCode]
. For the shared account code to be visible, the option Make shared account PIN /
166
Shared Accounts
By including both the client/matter code and name, users are able to search for a particular account by either client code, matter code, client name or matter name. The following examples demonstrate this:
1.
Searching by client name will display the client plus all matter codes for the client.
Figure 8.6. Searching accounts by client name in the client/matter code naming model
2.
Searching by client code will display the client plus all matter codes for the client.
167
Shared Accounts
Figure 8.7. Searching accounts by client code in the client/matter code naming model
3.
Searching by matter name will display the matching matters plus the client for each matching matter.
168
Shared Accounts
Figure 8.8. Searching accounts by matter name in the client/matter code naming model
4.
Searching by matter code will display the matching matters plus the client for each matching matter.
169
Shared Accounts
Figure 8.9. Searching accounts by matter code in the client/matter code naming model
8.2.2. Project / Phase Naming Model
Engineering and IT firms will be familiar with the project / phase model:
• Parent accounts are created for each project
• Sub-accounts are created for each project phase or stage
Usually, charging directly to a project is not allowed in this model - instead users should charge to the relevant project phase. System administrators should set each parent account to be inactive (disabled), and all the
sub-accounts to be active, as shown in Figure 8.10, “Project / Phase Naming Model example”.
170
Shared Accounts
Figure 8.10. Project / Phase Naming Model example
When projects have a job or project number, it is recommended that it be included as the shared account code. For the shared account code to be visible, the option Make shared account PIN / code visible must be enabled. For
more information see Section 8.11, “Advanced Shared Account Options”.
By including the project name, project number and phase name, users can search for a particular account using any of these fields. The following examples demonstrate this:
1.
Searching by project name or number will display the project plus all phases for that project.
Figure 8.11. Searching accounts by project name or number in the project/phase code naming model
171
Shared Accounts
2.
Searching by phase will display all matching project phases, plus the project name for each phase.
Figure 8.12. Searching accounts by phase in the project/phase code naming model
8.2.3. Customer / Job Naming Model
Organizations that deal with customers on a per-job basis will be familiar with the customer / job model, as will those who use common accounting software packages. In this model:
• Parent accounts are created for each customer
• Sub-accounts are created for each job
The basic principals of the customer / job naming model are the same as the project / phase naming model. See
Section 8.2.2, “Project / Phase Naming Model”, substituting project for customer and phase for job.
8.3. Client Security
By default all printing is automatically charged to the user's personal account. For a user to be able to select a shared account the user needs to be granted access to the account selection popup.
172
Shared Accounts
Figure 8.13. Selecting a shared account from the popup
Access to the account selection popup, as shown in the above figure, is controlled at the user level on the user's details page. The Show the account selection popup option needs to be selected for each user that requires access to shared accounts. System administrators might find the Bulk user actions section under the User List screen convenient for applying this change to many users.
Figure 8.14. The user's popup settings under User -> User Details
Note
It is also possible to automatically charge printing to a single shared account without the need for the
173
Shared Accounts popup. This can be useful in environments where a user only ever needs to charge to a single shared account, and it is not desirable to display the popup.
Important
Users need to restart their workstation (or manually restart the PaperCut client software) for this change to take effect.
Users with the Show the account selection popup option enabled need to be running the client software at all times. Print jobs will not print until the user has selected the account.
In addition to granting users access to the popup they also need to be granted access to a shared account. Shared accounts access can be controlled using two methods:
• Network group membership
• PINs (also known as security codes or passwords)
If an account is allocated a PIN (an alpha-numeric access code) users with knowledge of the PIN can select the account. A PIN based system would be a sensible selection in an organization when PINs are already in use for other systems such as photocopiers or door access codes.
Tip
PINs/codes can also be used when using parent and sub-accounts. To select a specific sub-account from the client software, both the parent and sub-account pins are required. They should be entered in the format of:
[parentPIN]-[subPIN]
(i.e. they are separated by a hypen).
An alternate method is to delegate access to the shared account via network group membership. One advantage of group based control is that users do not have to remember PINs. Most medium to large organizations will already have their network structured into suitable groups representing their position, title, department or work area. These existing groups may be used to control access. Access to shared accounts can also be granted on an individual user basis, however best practice suggests group-based management for medium to large networks.
Tip
In a Windows Active Directory environment, Organization Units are treated as special groups. Hence they also can be used to control access to a shared account.
Controlling access to shared accounts via group membership rather than individual user accounts is recommended. By using group based control, new users created on the network inherit the correct account access by virtue of their network group membership. This alleviates the need for additional user modification inside PaperCut NG.
To grant access to a shared account for all members in a given network group:
1.
Log into the system as an administrator (i.e. admin account).
2.
Select the Accounts tab.
3.
Select the appropriate shared account from the list.
4.
Click on the Security tab.
5.
Select the appropriate group from the drop-down list.
174
6.
Click the Add button.
Shared Accounts
Figure 8.15. Setting up shared account security
Tip
Security settings of multiple shared accounts can be changed simultaneously by clicking on the Bulk
account actions... link under the Accounts tab. More information is available in Section 6.4, “Bulk
8.3.1. Using account security with PIN/codes
PIN/codes provide a convenient way to select shared accounts. However this convenience may compromise security when short or guessable PINs are used. For this reason PaperCut NG allows the user/group security to be also applied to PIN/code access. This allows sites to use convenient and short codes with confidence that only authorized users are granted access.
To enforce user/group security for PIN/code access:
1.
Log into the system as an administrator (i.e. admin account).
2.
Go to the Options tab, to the Account Options section.
3.
Change the Access rules defined on shared account security tab apply to: setting to both PIN/code and
selection from list.
4.
Click the Apply button.
With this setting changed, users can only select an account using PIN/code when they:
1.
know the PIN/code; and
2.
are in the shared account's user/group security
8.4. The Account Selection Popup
The account selection popup is a feature of the User Client that allows allocating printing to shared accounts. There are two types of account selection popup:
175
Shared Accounts
•
Standard account selection popup
The standard account selection popup provides the basic features required to charge to shared accounts. It's ideal for sites with simple account structures.
•
Advanced account selection popup
The advanced account selection popup includes additional features that are suitable when shared accounts are used frequently, and especially when many shared accounts exist.
•
Manager mode popup
The manager mode popup is designed for "print managers" that allows charging printing to any user or shared account, and apply adjustments to the job costs (e.g. for charge for special paper, binding, etc). The manager mode popup is often used in print rooms where staff perform printing on behalf of other users.
•
Automatically charge to a single shared account
This is a special mode that allows automatically charging all printing to a selected shared account, without any user interaction or popup.
8.4.1. Standard Account Selection Popup
The standard account selection popup offers four account selection types:
1.
Charge to personal account.
2.
Charge/allocate to a shared account selected by a PIN.
3.
Charge/allocate to a shared account from list (taking into account security settings).
4.
Perform print as another user (username and password required).
176
Shared Accounts
Figure 8.16. The standard account selection popup
When a user selects a shared account, there is the option to:
1.
Charge the print to a shared account.
2.
Charge the print to personal account (and allocate to shared account for reporting).
The option to charge a to personal account allows printing to be tracked against shared accounts while allowing the use of user-based quotas. When this option is selected, the cost of the print job is deducted from the user's personal account, but the job is allocated against the shared account which allows for account based print reporting.
The Default shared account can be set to speed up the process of selecting a commonly chosen account. When entered the selected account will be pre-selected in account selection popups.
System administrators can control on a per-user basis what options are available in the user's popup.
Note
Changes to the options available in the account selection popup come into effect immediately. There is no need to restart the client software for these settings to take effect.
Figure 8.17. Client popup options defined on a per-user basis
The Charge to personal account with popup notification option displays a popup with no account selection features. This option is useful in environments where the system administrator desires to provide users with cost confirmation prior to printing.
Figure 8.18. The print job confirmation dialog (no account selection options)
177
Shared Accounts
Tip
8.4.2. Advanced Account Selection Popup
The advanced account selection popup allows charging to personal or shared accounts, and has the following additional features:
1.
A searchable account list
The account list can be searched by the account name or code, making it much easier to find an account when there are many in the list. The search can also be remembered for next time.
2.
Structured account list
The account list is hierarchical; that is, sub-accounts are shown indented from their parent accounts for clarity.
3.
A preferred list of accounts
The most commonly used accounts can be saved to a list. This is a useful feature when many accounts exist, but each user mostly just uses a few of them.
4.
A list of recently selected accounts
The accounts that have been recently selected are saved to a list for quick selection.
5.
Comments on print jobs
The advanced account selection popup allows assigning a comment to a print job for future reference.
6.
Cost Adjustments
Cost adjustments offer the ability to apply various adjustments to the cost of a print job. Adjustments can be a percentage rate, a per job adjustment or a per page adjustment. For example, a 200% adjustment could be defined for manually loading photo paper (charge twice the standard cost). Other common examples of adjustments include; Mylar Film, draft paper, draft printing mode, discounts for "special" customers/jobs, and extra for binding and manual handling. Cost adjustments are defined at either a global or printer level and are
documented in detail in Section 7.9, “Cost Adjustments”.
7.
Option to not show a print job on invoices
Sometimes there are print jobs that need to be allocated to an account but not appear on any invoice reports.
The advanced account selection popup has an option to allocate a 'non invoiceable' print job to an account.
178
Shared Accounts
Figure 8.19. The advanced account selection popup
As in the standard account selection popup, there are two charging options for shared accounts:
• Charge shared account
• Charge personal account (and allocate to shared account for reporting)
The Default shared account can be set to speed up the process of selecting a commonly chosen account. When entered the selected account will be pre-selected in account selection popups.
8.4.2.1. Enabling the Advanced Account Selection Popup For All Users
In a professional (client billing) installation the advanced account selection popup is often enabled for all users, so that every user is prompted for a shared account (client) to charge when printing.
account selection popup may be enabled. The popup can be enabled on one user at a time or can be enabled for all users in bulk. To enable the popup for all users in bulk:
1.
Log into the admin interface.
2.
Navigate to Usres
→
Actions
→
Bulk user actions...
3.
By default the action will be applied to all users (the special
[All Users] group). To apply the action to a subset of users (a user group), select that group from the dropdown list.
4.
In the section Change settings, enable the option Change account selection setting and select the option
Show the advanced account selection popup from the dropdown list.
5.
If you do not want to allow users to charge printing to their personal account (i.e. they must select a shared account) then disable the option Allow user to charge to their personal account.
179
Shared Accounts
6.
Press OK and confirm the operation. Once completed, the selected users will have the account popup enabled.
Once the popup has been enabled on all users some testing should be performed from users' desktops. To test, log into a user workstation, perform a print and confirm that the account popup appears and the job is logged as expected.
8.4.3. Manager Mode Popup
The manager mode popup is designed to be used by authorized users to perform printing on behalf of other users
(e.g. in a school's print room when jobs are emailed in with often complex instructions such as binding, color paper covers, etc.). The approved user can charge printing to users' personal accounts or any shared account. This popup provides the following features:
1.
Charge printing to any user
The manager enters the user's username or ID number. The printing will be logged under this user's account.
2.
Charging to any account
The print job may be charged from the user's personal printing account or any of the shared accounts in the system. The shared accounts may be selected from a list, or using the account code/PIN.
3.
Standard cost adjustments
Standard cost adjustments provide a list of adjustments that can be applied to the cost of a print job. The print manager can select one or more standard adjustments to apply to a given print job. Adjustments can be a percentage rate, a per job adjustment or a per page adjustment. For example, a 200% adjustment could be defined for manually loading photo paper (charge twice the standard cost). Other common examples of adjustments include; Mylar Film, draft paper, draft printing mode, discounts for "special" customers/jobs, and extra for binding and manual handling. These adjustments can be defined on the server at a global or printer
level and are documented in detail in Section 7.9, “Cost Adjustments”.
4.
Custom cost adjustments
If none of the standard adjustments are applicable, the print manager can easily apply a custom per page or per job adjustment. Examples could include special binding, delivery, etc.
5.
Comments on print jobs
Allows assigning a comment to a print job for future reference. e.g. to explain the reason for the cost adjustments.
180
Shared Accounts
Figure 8.20. The manager mode popup
8.4.4. Automatically charge to a shared account
This special account selection mode allows all printing to be automatically charged to a single shared account, without user interaction or the need to run the User Client software on the workstation. This mode is useful when a user will only ever charge printing to a single shared account and does not want the inconvenience of responding the account selection popup then they print.
An example of where this would be useful is in a school or business environment where shared accounts represent a department within the organisation. In this situation user printing should be automatically allocated to a single shared account without any user interaction. Although this can mostly be achieved with the standard account selection popup, it requires the user to respond to each popup when they print.
This option can be selected for an individual user, set on multiple users using the Bulk User Actions or set in the initial user settings in the Group section. Once the Automatically charge to a shared account option is selected, then enter the account name to charge. To select a sub-account the account name must be entered in the parent\sub-account format.
Figure 8.21. Account selection option to automatically charge to a shared account
181
Shared Accounts
8.5. Account Selection in Non-Domain Environments (Workgroups)
Many small networks may not be controlled via a central domain server. These networks are sometimes referred to as workgroups or peer-to-peer networks. On these networks users may not log on to their desktop, or computers may be shared by multiple users. The Allow user to perform printing as another user option may be useful in non-domain/logon environments. User accounts can be set-up in the system hosting the printers and users can select their account using usernames and passwords for each print job, irrespective of which user account is currently logged onto the workstation.
Figure 8.22. Configuration allowing only selection of other user accounts
Figure 8.23. Popup requesting the user to enter their username and password
Tip
PaperCut NG can also be configured to manage its own set of user accounts. See Section 31.1,
“Internal Users (users managed by PaperCut NG)” for more details.
8.6. Batch Shared Account Import and Update
The batch import and update feature allows the administrator to import accounts, and optionally update existing account details by reading data from a simple text file or directory structure. In addition to being able to create accounts, it enables administrators to update the following account data:
• Enabled / disabled status
• Account PIN / Code
• Credit balance
• Restriction status
• Users allowed to use the account
182
Shared Accounts
• Groups allowed to use the account
• Invoicing options
• Comment options
• Notes
Examples of where the batch import feature is useful include:
• When importing account and balance data from another external system (e.g. a project management or accounting system).
• To reset the account balances at the end of a billing period (year/term/semester).
• To bulk update the users and groups who are allowed to use/access the accounts (security).
Tip
To update shared accounts from a tab delimited file on a regular basis, see Section 8.7, “Shared
Account Synchronization” instead. You can also synchronize shared accounts against the directory
structure of a file system, for example when there is a separate folder for each department or customer.
To perform a batch import:
1.
Manually inspect your file in a text editor and ensure it's in the prescribed tab-delimited format as detailed at
Section 8.6.1, “Batch Account Import File Format”.
2.
Navigate to the Accounts section.
3.
Click the Batch Import / Update tab.
4.
5.
Choose whether you want to delete accounts that exist in PaperCut NG but not in the import file.
6.
Press the Test Settings button.
7.
The window shown will tell you how many lines were processed, and how many shared accounts will be imported, updated or deleted when Import is pressed.
8.
If you are happy with the results of the test, press the Import button.
Tip
Consider testing your import file format with a small sample first (e.g. maybe a copy of the file containing only the first five lines). This way any formating mistake will only propagate to a few accounts rather than all!
Some example shared account import files can be found at
[app-path]/server/examples/import/shared-accounts/ in both Excel and TSV (tab separated values) formats. The Excel format may be used to produce the TSV format by saving as
Text (Tab delimited)
.
Examples include a flat list of accounts using the example of departments in a school
( school-departments.tsv
) and another with subaccounts using the example of a client-matter layout for a business' clients ( client-matter.tsv
).
8.6.1. Batch Account Import File Format
The import file is in tab delimited format and contains the following fields in the given order.
183
6.
7.
2.
3.
4.
No.
1.
5.
8.
Shared Accounts
Field
Parent Account Name
Sub-account Name
Enabled
Account PIN/Code
Credit Balance
Restricted Status
Users
Groups
184
Description Optional?
The name of this account's parent.
When creating a top level account, leave the sub-account name blank
(and this will be the account's name).
Mandatory
When creating a sub-account (1 level deep only), enter its name here.
Optional - account will be top level if blank
Whether or not this account is enabled. (Y/N where Y = YES, and N
= No).
Optional - account will be enabled if blank
The account PIN/Code. For parent accounts, the code must be unique for all parent accounts. For sub-accounts, the code must unique amongst accounts with the same parent account.
Optional - PIN not set if blank
The account balance.
• When updating an existing user, a blank balance indicates that the existing balance will be maintained without modification.
Optional - Balance not updated if blank
The account's restricted status. (Y/N where Y = YES, and N = No).
Optional if blank, set to a configurable default
Modifies the users that are allowed to select this account from the list (no
CODE/PIN required). The access list may be modified as follows:
• To replace the previously defined access list, use a pipe (
|
) delimited list of usernames. e.g.
user1|user2|user3 sets the list to these three users (removing any previously defined).
• To add users to the existing access list, prefix the pipe delimited user list with a plus sign
(
+
). e.g.
+user1|user2|user3 adds these three users to the access list.
• To remove users from the existing user list, prefix the pipe delimited user list with a hyphen (
-
). e.g.
-user1|user2|user3 removes these three users from the access list.
• To remove all users from the access list, enter a hyphen (
-
).
Optional - users are not updated if blank
Modifies the groups that are allowed to select this account from the list (no
CODE/PIN required). To reference the special 'All Users' group, use the syntax
[All Users]
. The access list may be modified as follows:
• To replace the previously defined access list, use a pipe (
|
) delimited list of groups.
e.g.
group1|group2|group3 sets the list to these three groups
(removing any previously defined).
• To add groups to the existing access list, prefix the pipe delimited group list with a plus sign
(
+
).
e.g.
+group1|group2|group3 adds these three groups to the access list.
• To remove groups from the existing group list, prefix the pipe delimited group list with a hyphen
Optional - groups are not updated if blank
Shared Accounts
No.
9.
10.
Field
Invoice Option
Comment Option
Description
-
).
-group1|group2|group3 e.g.
removes these three groups from the access list.
• To remove all groups from the access list, enter a hyphen (
-
).
Optional?
The invoicing option defines how prints allocated to this account are invoiced. Available values are:
ALWAYS_INVOICE
- prints allocated to this account are always invoiced
NEVER_INVOICE - prints allocated to this account are never invoiced
USER_CHOICE_ON
- it is up to the user whether or not to invoice prints allocated to this account. The default is yes.
USER_CHOICE_OFF
- it is up to the user whether or not to invoice prints allocated to this account. The default is no.
Optional - set to USER_CHOICE_ON if blank to The comments option defines whether or not comments should be added to prints allocated to this account.
Available values are:
NO_COMMENT
- comments may not be added
COMMENT_REQUIRED
comments must be added
COMMENT_OPTIONAL
- it is up to the user whether or not to add a comment
Optional set
COMMENT_OPTIONAL if blank
Notes about the shared account
(placed in the Notes field).
Optional - notes not set if blank 11.
Notes
Table 8.1. Shared Account Import File Format
Other limitations: Although any actual limit to the size of an import file should be large enough for any purpose, we recommend keeping the file size below 10MB.
Tip
A simple way to create a tab delimited file is to create a spreadsheet in Microsoft Excel, and then save it in the
Text (Tab delimited) format.
8.6.1.1. Import File Format Examples
The following lines shows importing all the above fields. (The fields are separated by tabs).
Maths Y 12 5 N user1|user2 group1|group2 ALWAYS_INVOICE COMMENT_REQUIRED
Science Physics Y 1620 100 Y user3 NO_COMMENT A Note
Science Biology N 16 12.50 N group3 USER_CHOICE_OFF
The following lines show updating only the groups that can access the account. NOTE: The tabs still exist for the enabled status, pin, balance, restriction and users fields, but each entry is blank.
185
Shared Accounts
Maths
Science Physics
Science Biology group1|group2|group3 group1 group3
Tip
The shared account import process can be triggered via the command-line scripting tool
server-command. See Section A.1, “Server Commands (server-command)”.
8.7. Shared Account Synchronization
The shared account synchronization feature allows the administrator to define an external source for shared accounts. This is useful for situations where shared accounts are managed by an external system, and allows
PaperCut NG to mirror the accounts without any additional administration.
To enable shared account synchronization:
1.
Navigate to the Accounts section.
2.
Click the Account Sync tab.
3.
4.
Press Test Settings
5.
The window shown will tell you how shared accounts were processed, and how many shared accounts will be imported, updated or deleted when Synchronize Now is pressed.
6.
If you are happy with the results of the test, press the Synchronize Now button. This will trigger a shared account synchronization, and synchronization will continue to occur at the chosen interval.
8.7.1. Synchronization Options
Shared Accounts can be synchronized against two possible sources: a text file or a directory structure. This is configured in the first option on the Account Sync tab: Sync source.
• Text file - Synchronize shared accounts against a text file. The format of this text file is discussed in
Section 8.6.1, “Batch Account Import File Format”.
• File System Directory Scan - Synchronize shared accounts against a directory structure. Many organizations will have a 'Customers' folder or similar in their file system which will contain one folder per customer. For example, given
Customers/Client 1 and
Customers/Client 2
, synchronizing against the
Customers directory will import
Client 1 and
Client 2 as shared accounts.
Tip
The location of the text file or directory (the sync source) is relative to the system where PaperCut NG is installed, not the system being used to access the admin interface. The sync source should either be physically on that system, or accessible via a mapped / mounted drive. Additionally, the source should have permissions to be readable by the
Local System account on Windows, or the papercut account on Mac or Linux.
The other options include:
• File location / directory location - The location of the file or directory to sync against. The location is relative to the server.
• Perform sync - How often the account sync should take place. The available options are Hourly and Overnight.
186
Shared Accounts
If new accounts are being added regularly throughout the day, Hourly is probably the best choice. The
Overnight sync occurs nightly at approximately 12:55am.
• Treat subdirectories as sub-accounts - This option is only available with directory synchronizing against a directory. When checked, subdirectories will be treated as sub-accounts. For example, a directory structure of
Customers/Client 1/Project 1 will produce a top level account called
Client 1 and a sub-account of
Client 1 called
Project 1
.
• Delete accounts that do not exist in the selected source - This option will delete accounts that exist in PaperCut
NG but not in the sync source. Use this option to clean out 'old' accounts. This option is not 'remembered' for the automatic synchronization, so accounts can only be deleted by checking this box and pressing Synchronize
Now. Deleting is a destructive operation. Don't forget to perform a test first and a backup is also advised!
8.8. Bulk Shared Account Operations
A bulk shared account operation refers to an operation that is applied to more than one shared account. There are occasions where the same task needs to be performed on multiple accounts. With a large number of shared accounts, it may take too long to perform the task manually on each one; this is where bulk account operations are useful.
Bulk account actions... can be found in the Actions list while on the Accounts tab.
Some examples of where bulk account operations might come in useful include:
• Shared account balances need to be reset at the start of a new billing period.
• A new printing policy or account model is being introduced, and needs to be rolled out across all shared accounts.
• Shared accounts are to be temporarily disabled. For example over the holiday period when there should be no shared account based printing.
• A particular group needs to be given access to all the shared accounts.
Warning
The bulk account operations are one-way and cannot be undone. Always carefully consider the operation before proceeding. If you are unsure of the function or behavior, performing a backup prior to undertaking the operation is advised.
The following tasks can be performed through bulk account operations:
• Adjust of set the accounts' credit (perform a transaction)
• Change the accounts' restriction status
• Disable the accounts for a specified period of time
• Change the invoicing option
• Change the comments option
• Change the cost multiplier
• Change the security settings
• Change quota scheduling settings
8.9. Shared Account Quota Allocation
Sometimes organizations want to control printing to shared accounts. This can be done by allocating quotas on a periodic basis.
To allocate a $100.00 weekly quota to
Science account:
187
Shared Accounts
1.
Navigate to the Accounts tab.
2.
Select the account.
3.
Under the Quota Scheduling section, select a period of Weekly and enter 100.00 in the Schedule amount.
4.
Click Apply.
for more details about quota scheduling.
For details about scheduling times please refer to Table 6.1, “Quota schedule times”.
8.10. Shared Account Cost Multiplier
Sometimes organizations will want to charge different amounts to different shared accounts. This can be done by setting a cost adjustment multiplier on a shared account. For example, by setting the Multiply cost by to 50%, then printing to the shared account will cost 50% less. Setting the Multiply cost by to 125% will cost 25% more.
To provide a discount to the example "Administration" shared account please follow the steps listed below:
1.
Navigate to the Accounts tab.
2.
Select the "Administration" account.
3.
Under the Advanced Options section, select the option Multiple cost by and enter 50.
4.
If you want to apply same cost adjustment to all it's sub accounts of "Administration", then select the option
Apply to all sub accounts.
5.
Click Apply.
If you want to apply same settings to multiple accounts you can use Bulk account actions. For details please see
Section 8.8, “Bulk Shared Account Operations”.
8.11. Advanced Shared Account Options
It is possible to customize the functionality of shared accounts to suit a wide range of uses. There are several advanced options available throughout PaperCut NG to control this customization:
•
Make shared account PIN/code visible
When this option is active, the purpose of the shared account PIN is changed. Usually the PIN is equivalent to a password, and can be required before a user is able to charge to a shared account. When this setting is active, the PIN is treated as a 'code' instead; that is, a unique identifier for a given shared account. For example, an organization dealing with projects might allocate a shared account the project code
123
.
When this option is active it has several effects throughout PaperCut NG, including:
• The shared account list (on the Accounts tab) includes the shared account code.
• Reports dealing with shared accounts display the code.
• On the account selection popup dialogue of the user client tool, the code is visible when entering (i.e. it is no longer hidden by stars). This allows charging to a shared account by code, rather than scrolling through the dropdown list to find the correct account by name.
To activate this option:
• Go to the Options tab
• Check the option Make shared account PIN/code visible
• Press Apply
•
Apply to all documents in queue
This option appears at the bottom of both the standard and advanced account selection popups. When checked,
188
Shared Accounts the settings being applied to the current print job will be applied to all waiting jobs automatically. The text will let you know how many jobs this will affect (e.g. "Jobs: 5").
This setting is useful when printing a batch of documents for the same purpose. For example, when printing a letter, diagram and spreadsheet for a client, the client account can be selected on the account selection popup along with any other appropriate settings, and the settings will be applied to all three jobs. This saves the time taken to apply the settings for each job.
•
Changing the time after which jobs are deleted when awaiting popup response
If a user does not respond to the account selection popup after a defined time, their print job will be automatically
189
Chapter 9. Reports
A report is a representation of data, often in a printable tabular format. PaperCut NG provides a set of built-in reports. These include simple pre-built reports accessed via one-click, up to more advanced reports constructed using custom filters.
Tip
PaperCut NG is an open system. System administrators with database management experience may choose to run the system on an external database system. 3rd party reporting tools can then be used to construct custom reports. The PaperCut Software Development team can also consult on custom report development.
Tip
PaperCut NG reports are generated for a single Application Server. If your site has multiple Application
Servers and you want consolidated reports, see Chapter 12, Central Reports.
Reports can be produced by selecting the date range and then clicking on one of the report format icons. Common date ranges, such as Last 30 days, Yesterday and Previous Month can be selected via the drop down box. The
Ad-hoc option may be used to generate the reports with custom date ranges and filters (e.g. generate a User
printing - summaryreport limited to a particular department). A sample of each report can be seen by clicking on the Show sample link. A sample report gives an indication of what the final report will look like.
Figure 9.1. An example report displaying different date ranges
190
Reports
Figure 9.2. Selecting Ad-hoc date ranges and filters for reports
9.1. Report types
The one-click reports accessed under the Reports section can be grouped into the following areas.
9.1.1. User Reports
These are reports producing information about users. They range from a list of users, their names and current account balance, to detailed reports listing all print jobs printed by a user over a particular time-frame.
9.1.2. Printer Reports
Printer reports produce information on printers including configuration, usage summaries and statistics.
9.1.3. Print Log Reports
The print log is a detailed list of all printing performed on the network. The print log reports allow administrators to produce reports list all jobs over a given date range with simple one-click version for today's print jobs and largest print jobs.
Figure 9.3. Printer log PDF report
9.1.4. Group Reports
These reports group printer usage by network group allowing system administrators to determine which group of users performs the most prints. These reports are ideal for gaining a quick overview of printing costs performed by work area, department, floor, management level, etc.
9.1.5. Shared Accounts Reports
191
Reports
Administrators may use the shared account reports to track printing allocated to shared accounts via the popup.
9.1.6. Transaction Reports
These provide a summary of the transactions / balance adjustments.
9.1.7. Environmental Impact Reports
These reports summarize the environment impact of printing.
9.1.8. Ratio Reports
These reports compare relative printing usage.
9.1.9. Period Comparison Reports
These reports compare printing activity between two periods.
9.2. Report Formats
All reports are available in three different formats. Access to all formats depends on the software installed on your system. Alternate formats are accessed via the three icons located next to the report period drop down box.
Figure 9.4. Clickable report icons to run reports in different formats (PDF, HTML, CSV (Excel)).
There are three report formats available.
Format
PDF Reports
HTML Reports
CSV/Excel Reports
Table 9.1. Report Formats
Description
PDF is the most appropriate format for printing. To view these reports your computer must have a PDF viewer installed. Adobe Acrobat Reader is a free
PDF viewer available from adobe.com.
HTML Reports will work on all systems and don't require an external PDF viewer. These reports may not print or format as well as the PDF versions and are designed for either a quick review of data or for systems that don't have a
PDF viewer.
The CSV/Excel reports can be used to access the data in plain text format. The format is suitable for importing data into programs such as Microsoft Excel.
192
Reports
9.3. Combining Filters and Reports
All data list views in PaperCut NG have export/print option linked at the bottom of the list. The export/print links run a report over the data currently displayed in the list. The lists column order and filter options are taken into consideration when generating the report data. This functionality can be used to produce ad-hoc or custom reports.
This functionality is best described by example.
To run a report to see who and how much people have printed against a shared account over the month of
September:
1.
Navigate to the Accounts.
2.
Click on the appropriate shared account.
3.
Select the Job Log tab.
4.
Click the Show Filters link.
5.
Select the 1st of September in the from date and enter the 30th of September in the to date.
6.
Click Apply Filter button. The data displayed in this list should be all print jobs printed against this shared account for the month of September.
7.
Click on the Summary by user link to produce the PDF report.
Figure 9.5. Filters applied to the shared account print log
To run a report listing all transactions issued against a user's account over the month of September ordered by transaction amount:
1.
Navigate to the Users tab.
2.
Click on the appropriate user account. The user details page will display.
3.
Select the Transactions tab.
4.
Click the Show Filters link.
5.
Select the 1st of September in the from date and enter the 30th of September in the to date.
6.
Click Apply Filter button.
7.
Click on the Amount column to order the data by amount value.
8.
Click on the Export/Print button at the bottom of the list to produce the report.
9.4. Scheduling and Emailing Reports
193
Reports
The one-click reports in the PaperCut NG web interface are good for finding important data fast, however sometimes it is more convenient to have important data 'pushed' to interested parties. This can be achieved through the use of
scheduled reports.
PaperCut NG can schedule reports to run periodically and have them automatically sent out via email or saved to a folder. Scheduling reports can be used for a variety of purposes, for example:
• Sending a department manager a summary of the department staff's printing.
• Sending a teacher a summary of printing for each student in their class.
• Producing and using a CSV report saved to disk to import into an external system, such as an accounting package.
• Producing a regular report for billing or invoicing purposes.
9.4.1. Usage
The scheduled reports page can be found at Reports
→
Scheduled Reports.
Important
Before scheduled reports can be sent via email, PaperCut NG needs to know where to find a SMTP server (outgoing email server). For information about how to configure email notifications, see
Section 15.6.1.4, “Configuring Email Notifications”.
194
Reports
Figure 9.6. The Scheduled Reports page
To create a scheduled report, choose the desired report options and press Add. The process is best described by way of example:
9.4.1.1. Example 1: Faculty based reporting in education
Joe is head of the science faculty at a university. Faculty staff have the ability to charge printing back to the faculty.
Joe would like to see, on a regular basis, how much printing each user charges to the faculty.
To do this:
1.
Navigate to the Scheduled Reports page.
2.
Click Schedule a new report... if the panel is not already displayed.
3.
Choose the report Type of Shared account printing - user summary.
4.
Under Optional parameters
→
Account name, enter Joe's faculty shared account name, Science.
5.
Change the report title to "Science Faculty Account Printing".
6.
Leave the report Format as PDF.
195
Reports
7.
Make the report deliverable every week by setting Report to Weekly.
8.
Set the Delivery to By email.
9.
Enter Joe's email address under Recipients.
10. Press Add.
The report is now scheduled to run every week, and should now be shown in the table on the bottom of the page.
Joe will receive an email every Sunday showing the previous week's printing in his faculty. To find out exactly when
example] next to the report. To manually run the report (generate it and email to Joe now), press [run now]. The
The [run now] operation also provides a convenient way to resend the previous period's report if the original delivery failed or if the email was accidentally deleted.
9.4.1.2. Example 2: Division based reporting in business
Mary is head of the marketing division at a company. She would like to see which printers her staff use most, to make decisions about printer redistribution and purchasing. Also of interest are the sizes of paper being used, and how much color printing is being performed.
To do this:
1.
Navigate to the Scheduled Reports page.
2.
Click Schedule a new report... if the panel is not already displayed.
3.
Choose the report Type of Group printing - printer summary.
4.
Under Optional parameters
→
Group name, enter Mary's division group name, Marketing.
5.
Leave the report Format as PDF.
6.
Make the report deliverable every fortnight by setting Report to Fortnightly.
7.
Set the Delivery to By email.
8.
Enter Mary's email under Recipients.
9.
Press Add.
The report is now scheduled to run every fortnight, and should now be shown in the table below. Mary will receive an email every second Sunday showing the previous fortnight's printer usage by her division.
9.4.1.3. Example 3: Create reports to import into external system
John is the head of the accounting department in the organization and wants to charge his clients for invoiced printing allocated to their account. He wants that data in the external accounting system. He can schedule shared
account printing - summary report to be saved to disk so that he can access the same file periodically and import the data into his external system.
1.
Navigate to the Scheduled Reports page.
2.
Click Schedule a new report... if the panel is not already displayed.
3.
Choose the report Type of Shared account printing - summary .
4.
Under Optional parameters
→
Invoiced, select, yes.
5.
Change the report Format to CSV.
6.
Make the report deliverable every week by setting Report to Weekly.
7.
Set the Delivery to To file.
8.
Enter a file name client-summary.This will be the name under which file will be saved on the disk.
9.
Press Add.
196
Reports
Tip
Selecting the option Append datestamp to file name is optional. If the option is selected, then the report will be saved with a unique name, including the date every time, otherwise the report will be overwritten periodically.
The report is now scheduled to be written to disk every week, and should now be shown in the table below. John will see a new report being generated under the name of client-summary.csv, every week under
[app-path]/server/data/scheduled-reports
.
9.4.2. Details
Each report Period determines when the report will run. When the report includes date based usage information
(such as printing usage), the period also determines the date range of the data to include.
Period
Daily
Weekly
Fortnightly
Monthly
Quarterly
Yearly
Report Run Time Report Date Range
Early every morning, about 12:55am.
The previous day.
Every Sunday in the early morning, about 12:55am.
The previous week, from Sunday to Saturday
Every second Sunday in the early morning, about
12:55am. Fortnightly reports are run on even weeks, i.e. the second week of the year, the fourth week of the year, etc.
The previous fortnight, from two Sundays ago to
Saturday.
Early morning on the first day of every month, about
12:55am.
The previous month.
Early morning on the first day of every quarter, about 12:55am. Each quarter of an year is 3 months long. For example: First quarter of the year is from
1st of January to 30th of March.
The previous quarter.
Early morning on the first day of every year , about
12:55am
The previous year.
Table 9.2. Scheduled reports delivery times
Tip
Reports scheduled to write to a file are always written to a folder on the server located at
[app-path]/server/data/scheduled-reports
. This is a local folder on the server where
PaperCut NG is installed. It is not possible to change this target location to point to say a network share on another system. The reason for this is that PaperCut runs as a system service/daemon with limited rights and hence will not have access to other locations/servers. If the file needs to be accessible/consumed from another system, consider sharing the target folder, or using a scheduled task running as a privileged user (e.g. Windows Task or Cron job) to copy the file.
Tip
If a user has their email address set in PaperCut NG, their username can be entered in the Recipients instead. For example, instead of entering [email protected], entering just joe will work.
9.5. Advanced Reporting Options
The following configuration keys can be used to configure report behavior. Configuration keys can be edited at
197
Reports
Options
→
Actions
→
Config editor (advanced).
Config name
reports.max-rows reports.top-x-rows scheduled-reports.day-of-month reports.csv-display-comment-headers
Description
The maximum number of rows that a report will produce. Once the number of rows in a report reaches this value, the data in the report will be cut short (and the report will contain a message to indicate this has happened). This is a
'sanity limit', intended to avoid producing overly large reports by accident. The default value is
10000
.
The number of rows to display in 'top X' reports, such as the Largest print users report. The default value is
100
.
The day of the month when the monthly scheduled reports are run. By default, the monthly scheduled reports are set to run on the first day of the month. So, the default value is
1
. The other valid values are between 2 to 28.
Determines whether to display the comment headers in CSV reports (e.g. The report name and report parameters in the first few rows of the file). It may be appropriate to remove the headers if the CSV files are to be post processed or imported into a 3rd party system such as an accounts database. To display comment headers set the value to
Y
, to hide set the value to
N
.
Table 9.3. Advanced Reporting Config Keys
Please see Section 15.10, “Using the Config Editor” to find out how to change config keys.
198
Chapter 10. Multi-Server and Multi-Site
Deployments
10.1. Overview
The PaperCut solution is designed with distribution in mind. The solution is built using Service Oriented Architecture which allows its components to be installed on different machines of varying OS’. This allows PaperCut to be installed in a variety of configurations, adapting to your network design as no two sites are the same.
The simplest and most common installation is to install PaperCut onto a site’s Print Server (where the site has only one). For a school or a small organization the implementation doesn’t need to be any more complex than this. This is a Single Application Server, Single Print Server deployment and suits the large majority of our customer’s deployments.
Some more complex implementation examples exist below, as a way of showing what’s possible. It should be easy to extend or merge some of these concepts to suit your network and create your ideal PaperCut deployment.
PaperCut operates at a layer above your network print services. For this reason we recommend you design your solution to provide your printing services first, then integrate the PaperCut Application into your network second. i.e.
if you need to have a Print Server per site to stop large jobs traversing network links, do so. If you need to use clustering to provide high up time to printing services, make that choice too. PaperCut will then fit into these choices.
10.1.1. PaperCut Site Server
All of the solution designs in the next section can be complemented with the PaperCut Site Server.
The PaperCut site server gives the risk averse customer peace of mind that access to printing resources won’t be interrupted by unexpected network dropouts. Customers that deploy the PaperCut Site Server will ensure the critical services of the PaperCut Primary Server are supported locally during a disaster. Site Servers are simple to install and hide the complexity of database replication from Administrators.
Whilst initially designed for usage in multi site solutions, this isn’t the only usage of the Site Server. Think of the Site
Server like a proxy to the Application Server that can also perform a set of the Application Server tasks with the last known set of data during an outage.
10.1.2. Deployment Examples
10.1.2.1. Scenario A - Single Site, Multi Print Server
It is quite common for sites to have multiple print servers, even if they are a customer at a single physical location.
• iOS printing - Supporting printing from iOS devices may be deployed using a Mac Server to compliment a
Windows Print server.
• Admin / Curriculum - A number of schools separate printing in the Administration section of the school from general staff/student printing.
• Clustering - Each node of a clustered resource is installed as a Print Server.
Each of the print servers in this scenario will need to be installed and configured to communicate with the
The PaperCut Site Server could add benefit in this deployment scenario if your Application Server were deployed within the Private Cloud. The Site Server would offer a local level of redundancy in the event the connection to the cloud resources were to drop. One of the Print Servers could play this role in addition to being a PaperCut Print
Provider host.
199
Multi-Server and Multi-Site Deployments
Figure 10.1. Multi-Server and Multi-Site Deployments Multi Site/Multi Print Server deployment
10.1.2.2. Scenario B - Multi Site, Single Server
Not all multi site installations rely on a print server on each site. This may be because the sites are small and don’t warrant the resources, or because they are quite large and have resources centralised in a data centre or on the
200
Multi-Server and Multi-Site Deployments private cloud.
In either case, if all printing is centralised through a Single Application Server, Single Print Server installation, the installation is the same as if it were a single site with a single server.
The PaperCut Site Server could add benefit in this deployment if each of the sites wanted to ensure key business services of MFD usage and Print Release were supported during a network outage between a site and Application
Server.
Figure 10.2. Multi-Server and Multi-Site Deployments Single Server deployment
10.1.2.3. Scenario C - Multi Site, Multi Print Server
The deployment of print servers into remote sites allows for print jobs to be spooled within the local site, alleviating the need for these jobs to be sent to a centralised print server to only be sent back again to the remote site where the destination printer is located. This may be the choice of design for customers with
• Low bandwidth between sites
• Large print jobs generated on sites (architects, design firms, etc)
• Historical infrastructure that supports this
Print Servers. This allows the print jobs to remain locally spooled, with only light-weight transactional data and control information being transmitted between sites.
The PaperCut Site Server would add significant benefit in this design, possibly being installed onto one of the existing Print Servers. This would provide local support for Application Server functions should the link between
Primary and Secondary sites be unavailable.
201
Multi-Server and Multi-Site Deployments
Figure 10.3. Multi-Server and Multi-Site Deployments Multi Site/Multi Print Server deployment
10.1.2.4. Scenario D - Multi Site, Multi Print Server, Multi Application Server
It is also possible to install PaperCut into each site of a multiple site organization as if each site itself were a separate installation of PaperCut. PaperCut has the ability to link separate Application Servers together for reporting purposes. Each individual site then has the ability to function and be administered autonomously, relying only on the
links between the sites when there is a need to run a report from the centralised reporting service.
Each of the individual autonomous sites would use one of the previous installation options. The PaperCut Site
Server could then be considered for deployment to offer the same benefits listed above within these installations.
202
Multi-Server and Multi-Site Deployments
Figure 10.4. Multi-Server and Multi-Site Deployments Multi Site/Multi PaperCut Server deployment
10.1.2.5. Scenario Variations
All of these scenarios may be complemented with other approaches to address high availability, resilience and scalability, including:
• Clustered [ch-clustering.html] print server.
• Clustered [ch-clustering.html] Application Server.
•
Chapter 22, Deployment on an External Database (RDBMS).
• Clustered [ch-clustering.html] Database Server.
• Off-premises (Private cloud hosted server backed by infrastructure provider).
10.1.3. Comparison Table
The following table should assist with comparing deployment architectures. Different models offer different benefits and challenges. The key is to select the model that addresses your primary requirements, and to understand any constraints that may need to be managed in your environment.
Deployment type
1 site, multi server
Multi site, single server
Multi site, multi print servers
Multi site, multi Application Servers
Benefits
• Printing load distribution
• Central Application Server administration
• Removes single-point sensitivity at print server layer
Considerations
• Multiple print servers to manage
• Requires robust WAN
• Least complex setup
• Central administration
• Simple deployment
• Simple user management
• Simple queue and device management
• Job roaming across sites (Find-Me)
• Central administration
• Simple user management
• Reduced WAN traffic
• Reflects commonly used architectures
• Job roaming across sites (Find-Me)
• Requires robust WAN
• Requires more servers
• Decentralised queue management
• Multiple find-me queues
• More complex setup
• Doesn't require robust WAN
• Enables decentralised and parallel deployment and setup
• Decentralised administration
• Enables rolling updates
• Consolidated reporting is available
• Each site requires an independent implementation
• Overall setup for all sites will require more time
• No job roaming across sites (Find-Me)
Table 10.1. Deployment model comparisons
10.1.4. Further Resources
For further details of setup for each scenario, please refer to the following resources. and .
10.1.4.1. Scenario A - Single Site, Multi Print Server
•
Chapter 17, Configuring Secondary Print Servers and Locally Attached Printers.
203
Multi-Server and Multi-Site Deployments
•
Chapter 11, Resiliency with Site Servers.
10.1.4.2. Scenario B - Multi Site, Single Server
•
Appendix D, Capacity Planning.
•
Chapter 11, Resiliency with Site Servers.
10.1.4.3. Scenario C - Multi Site, Multi Print Server
•
Chapter 17, Configuring Secondary Print Servers and Locally Attached Printers
•
Appendix D, Capacity Planning.
•
Chapter 11, Resiliency with Site Servers.
10.1.4.4. Scenario D - Multi Site, Multi Print Server, Multi Application Server
•
See Chapter 12, Central Reports.
•
Chapter 22, Deployment on an External Database (RDBMS)
•
Chapter 11, Resiliency with Site Servers.
204
Chapter 11. Resiliency with Site Servers
Important
Note:
PaperCut Site Servers are currently licensed under the Early Access Program,
[http://www.papercut.com/kb/Main/BetaTestingProgram] for customers wishing to begin an incremental rollout of Site Servers and MFDs. There is no grace period for Site Servers when installed, so a license must be arranged prior to installation. Please contact your reseller or PaperCut Software to access this feature.
11.1. Introduction
For customers with distributed deployments, considerations such as redundancy and resilience to network outages are often a high priority.
A robust solution should defend critical points of failure, to ensure an organization can still continue to operate whilst a network is under duress. For PaperCut this means a robust deployment should ensure the availability of printing over failing and unreliable network links.
The installation of PaperCut Site Servers give customers peace of mind that access to printing resources won’t be interrupted by unexpected network dropouts.
The Site Server duplicates the key features of a PaperCut Primary Server to a local site during an outage. MFDs are configured to connect to a Site Server as if it were the Primary Server to remove their reliance on WAN links.
PaperCut Secondary Servers (Print Providers) are also aware of their local Site Server, providing a failover server if the Primary Server cannot be contacted.
This simple but effective design delivers high availability to MFDs and support for Secure Print Release including
Find Me Print.
The Site Server installs in minutes with minimal configuration steps and no ongoing administration. Installers and
Administrators need no specialist skills in database management or replication to provide business continuity. The
Site Server ensures it is kept up to date with the current state of the Primary Server, transparently performing the role of the Primary Server when needed. Once a connection to the Primary Server can be re-established, the merge of local Site Server logs and transactions back to the Primary Server is also seamlessly managed by the Site
Server.
The close relationship between the Site and Primary Servers allows the support of the same set of Operating
Systems and Databases for installations. It's perfectly valid to promote an existing PaperCut Secondary Server
(Print Provider) to a PaperCut Site Server to improve a site's resiliency.
205
Resiliency with Site Servers
Figure 11.1. Site Server example
11.2. Technical Overview
The goal of the Site Server is to support access to printing and copying, and is designed to be implemented with equal ease for existing PaperCut customers and new PaperCut Customers. The diagrams below highlights the change in design for existing customers implementing a Site Server, or for new customers that wish to incrementally build a solution and phase a Site Server in after a basic single server solution is functioning.
206
Figure 11.2. WITHOUT Site Server
Resiliency with Site Servers
Figure 11.3. WITH Site Server
In these images, we illustrate the changes in how elements of a PaperCut solution communicate when a Site Server is deployed.
• MFDs now communicate with the Site Server. This ensure an outage between Site Server and Application
Server is defended by the Site Server.
• Print Servers also communicate with the Site Server when the Application Server is unavailable.
During normal operation where the Site Server and the Application Server are connected, the two servers together deliver the full set of PaperCut functionality. In anticipation of an outage, the Site Server also caches an up to date set of Application Server data.
In the unlikely event of an outage, the Site Server immediately takes over to deliver business continuity. When the link is re-established, normal operation resumes and offline job logs and transactions are submitted to the
Application Server.
11.2.1. What you will need
The Site Server implements the core functions of the Application Server, and as such the majority of requirements are the same.
Operating System
Database
Database licensing
Server specs
All eligible choices for an Application Server.
[http://www.papercut.com/system-requirements/] Can be chosen independently from the Application Server.
All eligible choices for an Application Server.
[http://www.papercut.com/system-requirements/] Can be chosen independently from the Application Server.
PaperCut database replication is provided by PaperCut. No database enterprise licensing is required.
Follow the suggested sizing
[http://www.papercut.com/kb/Main/PaperCutServerSizingGuide] requirements of the Application Server.
207
Resiliency with Site Servers
SSL
Versioning
Licensing
Ports
Server to server communication is encrypted by default. We recommend using a certificate for your Application Server signed by a CA. Your CA of choice should provide instructions for your installation.
Your Application Server must be v15.0 or greater, and your Site Servers must be of the same version.
The Site Server component is a license feature of the PaperCut Application.
Licenses must be arrange prior to installation.
Site Server: The Site Server will listen on port 9191 for Print Provider connections and the inbound ports for your chosen Device Connections.
[http://www.papercut.com/kb/Main/FirewallPorts]
Application Server: The Application Server will listen on port 9192 for connections from the Site Server and 9191 for Print Provider connections.
Table 11.1. What you will need
11.2.2. Where to deploy
An effective way to consider where a PaperCut Site Server should be deployed is to install a site server in any
network segment where you have concerns about the link reliability between this segment and the Application
Server and an outage to this segment would impact your business.
• Remote sites
• City offices
• Separate campuses
• Individual buildings with poor links
• Local sites where servers are on the Private Cloud [http://www.papercut.com/kb/Main/PrivateCloud]
11.3. Offline Operations
The intent of the Site Server is to ensure the access to Print and Copy services is supported during a network outage; i.e. to ensure the business can still continue to function during a disaster. Some services remain unavailable during an outage, as detailed below.
11.3.1. Supported functions
Basic printing (Failure mode)
MFD login (ALL devices)
Hardware terminals (CPad, Alpha,
VCC…)
Secure Print
Find-Me Print
User Balances
Filters and conversions
Release Stations
Shared Accounts at the MFD
Payment Gateways, Kiosks
Mobile Print (Web, GCP, iOS,
Normal Operations
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Offline with NO Site Server
Yes
No
No
No
No
No
No
No
No
No
No
Offline WITH Site Server
Yes
Yes
Yes
Yes
Yes
No
No
Yes
Yes
Yes
Yes
208
Resiliency with Site Servers
Email…)
Desktop Client / Account Selection
Scripting
Table 11.2. Supported Functions
Normal Operations
Yes
Yes
Offline with NO Site Server
No
No
Offline WITH Site Server
No
No
To ensure continuity, Offline Policies allow an Administrator to define the application behaviour ahead of any outage that disrupts PaperCut normal operations.
11.3.2. Offline Policies
As the user client, scripting services and payment options are not available during an outage, Offline Policies fill the gaps allowing users to continue to work. Offline policies are available after installing your first Site Server. They are accessible via Sites
→
Offline Policies
11.3.2.1. Account Selection
Figure 11.4. Account Selection when pop-up is not possible
the desktop client popup ask for a Shared Account before prints are accepted need a policy to determine the account to charge when the desktop client is unavailable during an outage. The policy options are;
1.
[default] Automatically charge to a single shared account. The print job is charged to a specified shared account (the default is "Offline Account").
2.
Automatically charge to personal account. The print job is charged to the user’s personal account.
3.
Cancel the print job. If a Shared Account must be selected by the end user and this is not possible, the job is cancelled.
11.3.2.2. Restricted Credit
Figure 11.5. Policy for restricted accounts
The Offline Credit Policy determines how PaperCut should determine whether to assume credit is available or to deny the job when the Application Server is unavailable. As an example, organizations may choose to allow an overdraft should the ability for users to top up their accounts be impacted whilst the central Application Server cannot be contacted.
209
Resiliency with Site Servers
The following policies are defined for restricted users and accounts whilst a site is in offline mode:
1.
[default] Use last known balance. Only deny jobs when the user’s balance (as known by the Site Server) is used up.
2.
Use the last known balance and allow overdraw by. Only deny jobs when the User’s balance known by the
Site Server, plus a specified offline overdraft amount is used up.
3.
Allow job to proceed, regardless of balance. Treat the account as unrestricted and allow all jobs to proceed.
The account may go into negative when the Application Server is available again.
4.
Assume no credit. Deny any job charging to restricted accounts. Only unrestricted accounts will be able to be used when offline with this policy. For example, when offline, Staff are able to use resources, whereas
Students are not.
Important: The first three policies may result in accounts being deficit when the Application Server is online again.
11.3.2.3. Unauthenticated Users
Figure 11.6. Policy for unauthenticated users
The User Authentication Policy prescribes the behavior in offline mode where PaperCut cannot validate the owner of
users, the following policies are available:
1.
[default] Assign print job to this user. (The default user is "unknown"). The preconfigured user should be configured as unrestricted, so that jobs allocated to this user are not denied based on the Offline Credit Policy.
You may also configure this user to charge to a specified shared account (which should also be unrestricted).
2.
Do not track, but allow job to print. Jobs will pass through physical queues unimpeded to the destination printers. However jobs sent to virtual queues will not print.
3.
Cancel the print job. Any print jobs sent from the unauthenticated users will be cancelled immediately.
Important: This policy also applies for users that have not been encountered by PaperCut previously. i.e. new domain users that have not been previously synced into PaperCut.
11.3.2.4. User Password Authentication
Figure 11.7. Policy for authentication
210
Resiliency with Site Servers
PaperCut normally performs user authentication via an external directory source, such as Active Directory. In normal operations, this validation is performed by the Application Server. When offline, we may choose between these options:
1.
External authentication on: The Site Server attempts to authenticate the user via the external source as configured. This option requires the authentication source to be able to be contacted by the Site Server during the interruption that is preventing access to the Application Server.
2.
External authentication off: Authentication from an external source is not available. This means that offline username/password login to a device or release station is not available, other than for Internal users.
11.4. Installation
Site Servers are an architectural component of the PaperCut solution. Setup is a straightforward process. Like most architecture projects, the time is best spent planning.
11.4.1. 1. Planning
Planning is the most critical step of a successful site server deployment. Taking a few moments prior to installation to run through a checklist of items is a wise first step;
• Arrange a license to include the required number of Site Servers.
• Consider a signed certificate by a trusted CA for your Application Server
• Plan to install/update the Application Server to v15.0.
• Discuss and choose the appropriate Offline Policies for your site.
• Choose a Site Server location that ensures a reliable connection to the devices and print servers it needs to support.
• Plan for minor disruption for any existing embedded or hardware devices you will reconfigure to use the Site
Server.
• Review the critical functions the Site Server supports to understand offline behaviour.
11.4.2. 2. Apply your license
Your Application Server must be licensed for Site Servers before installing the Site Server software.
11.4.3. 3. [optional] Import a trusted signed certificate
Where practical, organizations should consider implementing a signed certificate for SSL communications. This
topic is covered in detail in Appendix A of our manual.
11.4.4. 4. Installation
Before installing a Site Server you should take some time to ensure the primary server (central application server) is set up and running correctly. If it is not running fine now adding an extra server will only "add an extra variable to the equation" and complicate troubleshooting. Take some time now to verify that the primary server is functioning correctly.
11.4.4.1. Windows
On a Windows server, install the Site Server software by selecting the Site server installation (advanced) option in the installation wizard. If the PaperCut Primary Server software was previously installed on the server it must be uninstalled prior to installing the Site Server software.
11.4.4.2. Linux
––site-server when executing the installer.
211
Resiliency with Site Servers
11.4.4.3. Mac
On a Mac server, install the Site Server by downloading the latest Mac DMG disk image and execute the contained installer called PaperCut MF Site Server Install (advanced).pkg
11.4.5. 5. Post installation setup
1.
Set a unique name of the Site Server you are configuring.
Figure 11.8. Site Server name
2.
Enter the name or IP of the Application Server this Site Server will connect to.
Figure 11.9. Application server IP/Hostname
3.
Enter the credentials of a user with administrator access to PaperCut on the Primary Server.
212
Resiliency with Site Servers
Figure 11.10. Built-in admin credentials
4.
The Site Server is now connected to Application Server and will begin the data synchronization process.
Figure 11.11. Site Server status
5.
The Site Server requires no additional configuration at the local machine. You can use the Login link under the
Application Server image to access the PaperCut admin interface on the Primary Server. In here, you will see a new Sites tab.
213
Resiliency with Site Servers
Figure 11.12. Site Server list
6.
Click the Sites
→
Offline Policies tab to set the Offline Policies for your installation.
Tip
If you have installed the Site Server onto an existing PaperCut Secondary Print Server, the Print
Provider will have been automatically configured to work with the new Site Server. Additional Print
Providers will need to be upgraded to the same version of the Application Server and configured in the print-provider.conf
file to connect to the Site Server address.
11.4.5.1. Release Station configuration
be released in both online and offline operation.
• The Standard Release Station is connected to the Site Server by editing the release station's connection.properties
file and changing the server-ip setting to the Site Server address.
• The Site Server version of the mobile release app is accessed by using the Site server address in the URL, e.g.
http://[site-server]:9191/mr
11.4.5.2. Testing your installation
The Sites tab of the admin interface shows at a glance the status of all Site Servers. Whilst the Site Server is connected, your PaperCut installation should be operating as per normal.
To verify that your Site Server is providing resilience - you may take the site offline. This can be achieved by simulating network failure (pulling the plug), or more simply by disabling the site in the Sites tab.
1.
Select the site in the Sites tab
2.
Choose Disable connection (force offline) in the Site Connection section.
3.
Click Apply
The site can be validated as being in offline mode via the Site Server URL ( http://[site server]:9191/admin
). Printing and copying should continue according to the offline policies defined in the installation section. Validating the application of the policies via copy and print transactions will ensure your settings have been applied correctly.
To complete the test, return the Site to online by selecting Enable connection in the Site record. Validate your transactions have been uploaded to the Application Server by searching either the User, Device, Printer or Job log.
Tip
Jobs performed offline are marked as such in the print log. You can see which jobs are offline by
214
Resiliency with Site Servers inspecting the job details in the job log. In addition, when creating job log reports, you may now filter by offline jobs, to report only the jobs performed offline in a specified period.
11.4.5.3. Important note about future upgrades
Version upgrades to the Application Server will result in the Site Servers supporting their local site in offline mode until they are also upgraded. Therefore you should also plan to upgrade the Site Servers as part of your upgrade procedure. [http://www.papercut.com/kb/Main/UpgradingNG]
11.5. Common questions about Site Servers
1.
Do I need to backup my PaperCut Site Server?
No. The Site Server does not maintain its own data and does not need backing up. If a Site Server fails, a new one can be quickly re-established by re-installing. By contrast, the Application Server does maintain important configuration and history data and should be backed up.
2.
Does the Site Server replicate the entire PaperCut database?
No. The Site Server does replicate key tables from the PaperCut database related to configuration. This includes User, Group, Printer, Device and Attribute tables. Importantly, the Site Server does not replicate the
Printer Log table from the App Server, as this data is not needed. For many customers, the Printer Log table is by far the largest table in the database.
3.
Is communication between the Site Server and App Server secure?
Yes. The Site Server performs all communication with the App Server over a secure HTTPS connection. A Site
Server cannot be connected to the App Server without the approval of a PaperCut administrator with sufficient admin rights.
4.
Do I need to run a Site Server on an external database?
No. The PaperCut Site Server also ships with an internal database in the same way the Application Server does. However if your preference is for an external database, we support these too.
5.
What database replication technology do you use?
PaperCut developed its own database replication strategy to remove the requirement for costly enterprise database licenses.
6.
Is failover automatic, and how quickly does it happen?
The failover from online to offline mode for the site server is an automatic process and happens without the need for intervention from an administrator. The failover time is also instantaneous for the MFDs and configurable for the print provider, so users can continue to function without interruption.
7.
How do I check the status of a Site Server?
The status of a Site Server can be validated through the PaperCut admin interface via the Sitestab as well as via the http://[site-server]:9191/admin
URL.
8.
Will features like conversion to greyscale or force duplex work in offline mode?
Yes. Filters and restrictions set at the queue level are supported when the Site Server is offline from the
Application Server. However, print scripts and any conversions controlled by script will not run when offline.
9.
Will username and password login methods be supported if the Application Server isn’t available?
Yes. Site Servers are able to be configured in a way that they can validate username and passwords when the
Application Server is unavailable, however this is not enabled by default. If a link between a remote site and the main site is unavailable, there is a high likelihood that the directory server is also not available to validate credentials.
10. Will cross server releasing of print jobs work during an outage?
215
Resiliency with Site Servers
Cross server releasing of print jobs (where the physical queue and virtual queue are on different print servers) will be supported during an outage when both source and target queues reside on print servers connected to the same Site Server.
11. Will Site Servers replace the need for clustering?
Customers implementing clustering of the Application Server to maintain high service levels should continue to do so. The Site Server offers additional protection, but many features of the Application Server, such as Web
Print, BYOD printing and external payment gateways are not currently available through a Site Server.
12. Will Site Servers improve scalability of my system?
In the initial release, we are not claiming scalability benefits for the Site Server. However it is true that the Site
Server is distributing workload - and as we gather more data and continue to build the solution, we may well see some scalability benefits.
13. How do I specify the Site Server network address for my Web Services device?
Where a Site Server has multiple IP addresses, devices that look for PaperCut may need to know which IP address is the correct address to connect to. On the Application Server, this is easily set under Options
→
Advanced
→
Server Address. On the Site Server, you may specify the address to use on the Sites
→
Site
Server Details. page in the Override Network Address field.
14. What happens to my existing held print jobs when the Application Server becomes unavailable?
Jobs which were printed to a local print server prior to an outage will reappear in your held jobs list a few minutes after the Application Server becomes unavailable.
216
Chapter 12. Central Reports
12.1. Overview
Organizations with multiple sites will typically follow one of two deployment strategies: centralized or decentralized.
This includes businesses with offices in multiple cities and education institutes with international campuses. Each model comes with its own pros and cons.
One advantage of the decentralized model is that a system administrator at one site can't inadvertently make changes that affect the other sites. Poor inter-site link reliability and simplified site administration are other motivators for adopting the decentralized model. The main disadvantage of decentralization is the difficulty of gaining a unified view of print data and reporting. Central Reports solves this problem.
This chapter covers how Central Reports provides you with a consolidated data and reporting view across multiple primary/application servers (decentralized model). If you are using a single application server (centralized model)
this is not required as the regular reports provide the data you need - see Chapter 9, Reports.
A typical scenario is an organization with multiple sites and one application server per site. With Central Reports organizations like this can access consolidated reports for the entire organization.
Figure 12.1. Central Reports across multiple application servers
Central Reports works by running the same SQL query on all remote PaperCut databases and consolidating the result. This is done by first concatenating the result data from all databases, then grouping, sorting and aggregating as appropriate. For this purpose, entities such as users, groups, printers and accounts are matched by name. For example, if print usage records matching username "Mary" are received from multiple sites, they are all considered as coming from the same user and are aggregated. In other words, users (and some other entities) are considered to be unique across all sites.
We've taken most reports that are suitable for aggregation across systems and made them available in Central
Reports. This includes the Executive Summary report and most usage reports. Not included are configuration reports, transaction reports and print log reports.
Central Reports may be scheduled for automatic generation and email distribution just like standard reports and we anticipate that most customers will want to use Central Reports in this way.
Tip
Central Reports is not a centralized management system. Your multiple PaperCut application servers must continue to be operated and managed independently. All configuration and balances remain local to each application server, including user and shared account configuration, admin rights and user balances.
217
Central Reports
12.2. Prerequisites for Central Reports
Your organization needs at least two production application servers to use Central Reports. You can configure
Central Reports on one or both of these application servers. You can also configure Central Reports on a separate
PaperCut installation used solely for the Central Reports feature.
In addition:
1.
Each PaperCut application server (including the reporting server) must be configured with an external database
access from the central server by a nominated URL, user and password.
Central Reports works by running SQL queries on the remote PaperCut databases directly. It is therefore possible as an alternative approach to use other mechanisms to replicate the remote databases to your reporting server and run reports from the local read-only replicas. In this manual, however, we will document only the usual approach of accessing remote databases directly.
2.
All databases must be of the same type. For example, if you use Microsoft SQL Server at one site, this database type must be used at all sites, including the site doing the reporting.
3.
You should ensure the same PaperCut version is installed at each location, including the central reporting location. More specifically, the databases at all sites must use the same database schema (which can change between PaperCut versions).
4.
By default, Central Reports will not generate reports if any remote databases are unavailable or return errors. It is often better to log these events as errors rather than generate potentially incomplete and misleading reports.
Central Reports has a Status page which gives you a quick snapshot of the readiness of the system and flags any errors.
If desired, you may instruct central reports to generate reports even if some remote databases are unavailable.
To configure, see Section 12.3.1, “Server Configuration”.
12.3. Setting up Central Reports
Before setting up Central Reports, please review the prerequisites in the previous section. If you have not yet set up your external databases at each site, including the reporting site, you must do this first by following the instructions
in Section 22.2, “Upsizing to an External RDBMS”.
1.
Select a server as your reporting server. This is the server at which you will configure and run Central Reports.
You may choose whichever server is most convenient for you. In fact, it is possible to configure several or all servers to be able to run Central Reports.
2.
On the server, open the server config file
[app-path]/server/server.properties
in a text editor (e.g.
Notepad).
3.
At the bottom of the file, add central-reports
configuration statements as documented in Section 12.3.1,
“Server Configuration” below and save the file
4.
Log into the PaperCut admin interface to configure admin rights and email notifications:
To grant Central Reports admin rights to users who need access: a.
Navigate to the Options
→
Admin Rights page.
b.
Select the group you wish to add Central Reports rights for and click Add Group. Or if adding a single user, enter the user and click Add User.
c.
By default the group or user you added will have access to all features. To change this, click on the edit link to the right of the group or user entry. You may then select the specific rights you wish to apply. In particular, ensure that Access Central Reports is checked and click Apply to save your changes.
Enabling an email (SMTP) server allows scheduled Central Reports to be sent. Additionally, enabling email error notifications is recommended so that administrators are notified of any issues that would prevent Central
Reports from running successfully). E.g. if a scheduled central report fails, this allows administrators to be notified by email rather than needing to log into the admin interface and check the App. Log tab. To enable email notifications, navigate to Options
→
Notifications and:
218
Central Reports a.
Under Email Options, enter an SMTP server and other details so that PaperCut can send emails.
b.
Recommended: under System Notifications, enable Notify on error level events.
5.
Log into the Central Reports interface using the URL https://[server-name]:9192/central-reports and check the Status page for any errors. If this page is not available, please check that you have added
Central Reports admin rights to your login.
6.
Select the Central Reports tab and run several reports to test. Verify that the reports run and that the results are as expected.
12.3.1. Server Configuration
Central Reports is enabled by configuration statements in
[app-path]/server/server.properties
. Changes to the Central Reports related settings in this file do not require a restart of the PaperCut application server
(although most other settings in this file do).
This file should include template examples for configuring Central Reports. If it does not then you can see the
[app-path]/server/server.properties.template
(which is kept up to date with every upgrade) and copy the Central Reports related settings into your server.properties
file.
As an example, if using Microsoft SQL Server as the external database, the following statements configure a
Melbourne application server to run consolidated reports across the Melbourne, Perth and Sydney sites: central-reports.enabled=Y central-reports.database.local.include=Y central-reports.database.local.label=Melbourne HQ central-reports.require-all-databases-online=Y central-reports.database.1.label=Perth Branch central-reports.database.1.url=jdbc:jtds:sqlserver://per1.example.com/papercut central-reports.database.1.username=admin central-reports.database.1.password=xJf56gy central-reports.database.2.label=Sydney Branch central-reports.database.2.url=jdbc:jtds:sqlserver://syd1.example.com/papercut central-reports.database.2.username=admin central-reports.database.2.password=dF95FCd
Note that in this example the server.properties
file is for the "Melbourne HQ" site, and it would contain
The database statements detailed below must be specified for each remote server. Where specified, n is a numeric
ID (e.g: 1, 2, 3) used to associate statements for the same site, as per the example above.
Key
central-reports.enabled
central-reports.database.local.include
central-reports.database.local.label
Description
Central Reports is enabled (but not configured) by default. The purpose of this setting is to allow you to disable Central Reports if required. This will result in users not being able to log into the Central Reports interface, and scheduled
Central Reports will not run. Values: Y or N. Default: Y.
Specify whether to include the local server in the aggregated Central Reports.
Values: Y or N. Default: Y.
You would specify N if your local server was set up for running reports only and is not to be used as a PaperCut application server.
Provide a meaningful name for the local site. Default: "Local Site".
central-reports.require-all-databases-online This option configures whether or not all databases must be online to create
219
Central Reports
Key
central-reports.database.n.label
central-reports.database.n.url
Description
reports. If set to N, reports are created even if some remote databases are not available, but the aggregated reports will not include data from those databases.
Values: Y or N. Default: Y.
A text label to identify the remote server n, in the Central Reports status page and reports.
Specify the JBDC URL providing remote access to your database. This URL is specified in the same way as for the external database you have already configured on this system.
A database username providing read access to the remote database.
A database password for the supplied username.
central-reports.database.n.username
central-reports.database.n.password
Table 12.1. Central Reports statements in server.properties
12.4. Running Central Reports
Access Central Reports at the URL https://[server-name]:9192/central-reports
. You will see two tabs:
1.
Status - check the remote server status and whether you are ready to run reports
2.
Reports - generate on-demand and scheduled reports
12.4.1. Status Tab
The Status Tab shows the status of each configured remote servers and displays any errors that may prevent
Central Reports from running.
Figure 12.2. Central Reports Status Tab
Reports may not be generated if any server has an error. Typical errors include:
220
Central Reports
1.
Failing to connect to the database (incorrect authentication, firewall blocking access, configuration error).
2.
Servers have mis-matched application versions or database types.
12.4.2. Central Reports Tab
The Central Reports tab shows the reports available under Central Reports and allows reports to be generated on demand or to be scheduled for email delivery. Central Reports provides a sub-set of the reports available in the
run reports and configure filters.
Select the Schedule / Email Reports tab to schedule Central Reports for periodic generation and automatically have them emailed to the appropriate people in your organization.
221
Chapter 13. Hold/Release Queues & Print
Release Stations
In a standard network printing environment, when a user prints from an application, the job is sent directly to the printer and starts printing immediately. In some environments it may be advantageous to place the job in a holding state prior to printing. Some common examples include:
• Secure Printing - In a secure printing environment jobs are only printed when the user arrives at the print area and confirms his or her identity. This ensures the user is there to collect the job and other users can't
"accidentally" collect the document.
• Approved Printing - In some organizations it may be appropriate to hold jobs until they are approved by selected individuals. A good example would be a teacher approving printing on an expensive color printer.
• Authentication - Hold/Release queues can be used as a form of authentication in an unauthenticated environment. Users must authenticate prior to releasing their jobs allowing PaperCut NG to confirm their identity.
PaperCut NG provides the framework and software interface to implement hold and release queues.
Users can interact with the Hold/Release Queues (e.g. release their jobs) in a number of ways. This normally takes the form of a Release Station - a dedicated computer terminal located next to the printers, however other interaction methods include access via a browser-based interface. Hold/Release Queues are used for a wide variety of purposes depending on the requirements of the organization. This section outlines a number of these scenarios, and also how to install and configure the release interface.
required to configure and manage a queue.
Tip
Hold/release queues may be used to implement a find me printing environment. See Chapter 14, Find
Me Printing and Printer Load Balancing for details.
13.1. Release Station Interfaces
PaperCut NG includes four different interfaces to manage hold/release queues. Three of these are variations of a web-based interface and one is a software version that is typically used for dedicated release stations. These interfaces are described below.
13.1.1. Standard Release Station
The standard release station is typically used on dedicated workstations located near-by the printers. It usually runs in a full-screen mode that cannot be exited. The release station can be run in a number of modes that changes its
For more information regarding deployment of the Standard Release Station see the
[app-path]\release\README.txt
file. For information regarding configuration of the Standard Release Station
see Section 13.3.3, “Standard Release Station Configuration”.
The release station scenarios below describe which mode to use for different situations.
222
Hold/Release Queues & Print Release Stations
Figure 13.1. The Standard Release Station
Tip
To educate users about printing using a release station, administrators might find the sample
13.1.2. Manager-mode web-based release station
The manager-mode web-based release station provides functionality equivalent to the standard release station running in "Manager mode". However, the web-based release station may be more convenient because it can be run from anywhere using a web browser. It allows release managers and PaperCut administrators to manage held jobs and release or cancel jobs printed by any user.
A filter can be applied to the jobs table. The default filter is the one that was last used by the user (except for the default admin user).
The web-based release station can be access by visiting the following URL, and logging in as a user with admin or release station manager permissions.
http://[servername]:9191/release where [servername] is the name of the PaperCut NG server. To make a user a hold/release queue manager see
Section 13.3.2, “Hold/Release Queue Managers”.
223
Hold/Release Queues & Print Release Stations
Figure 13.2. Manager-mode web-based release station
Tip
Want to know more about the Override action? See Section 13.2.6, “Override/Change Account
Selection during Admin Web Release”.
13.1.3. Web-based release station within the admin pages
When logged into the admin pages, an administrator can view all jobs held by release stations by:
• Navigating to the Printers section.
• Selecting the Jobs pending release tab.
This interface is identical to the full-screen web-based release station, but can be more convenient for users already logged into the administration pages.
Figure 13.3. Web-based release station within the admin pages
13.1.4. End-user web-based release station
When end-users are logged into the user web interface, they can view their print jobs that are currently held pending release. The administrator can decide whether this interface is visible to end users, and which type of jobs a user
may release. More information can be found at Section 13.3.4, “End-User Web Based Release Interface
224
Hold/Release Queues & Print Release Stations
Figure 13.4. End-user web-based interface listing held jobs
13.1.5. Mobile Print Release
This print release interface allows end-users to release their own jobs via their mobile device. This allows administrators to provide secure print release without the need for dedicated hardware. More information can be
found in the Mobile Print Release chapter.
Figure 13.5. Mobile Print Release listing held jobs
225
Hold/Release Queues & Print Release Stations
13.2. Hold/Release Usage Scenarios
This section describes various usage scenarios discussing why and how to use a hold/release queue. They provide a good starting point for your own implementations.
13.2.1. Saving paper and toner
A large source of wasted paper in organizations are documents that were never collected from the printer. Some of these uncollected documents are caused by accidental printing, and others were just forgotten. But the majority of these documents end up in the bin.
If the document is not printed until a user walks to the printer to collect it, then this source of waste can be mostly eliminated.
To implement a release station to save paper:
• Set up a low-end workstation near the printer(s).
• Run the Standard Release Station in the default mode (Release Any mode). More information can be found at
Section 13.3.3.1, “Release Station Modes”.
•
“Enabling hold/release support on a printer”.
• To allow users to release jobs via the end-user web based release station, also enable Release Any mode for
13.2.2. Secure Printing
When users print documents that contain sensitive information, it is important that no one else picks up the document from the printer. Even when the printers are close-by, people can be distracted and accidentally leave sensitive documents on the printer. Print release stations can be used to implement Secure Printing, which ensures that a document can only be released by the person who printed it and only when that person is standing near the printers.
Secure printing is implemented as follows:
• Setup a low-end workstation near the printer(s).
•
•
“Enabling hold/release support on a printer”.
•
Mobile Print Release can be used to implement secure printing without dedicated hardware.
Secure printing requires users to be authenticated on the network when printing (i.e. an Active Directory domain).
This allows the release station to enforce the secure printing so that users can only release documents they print.
13.2.3. Pay per print (e.g. Library or Internet Cafe)
Libraries and Internet cafes usually only allow printing once a user has paid for the cost of the printed document.
Previously, implementing pay-per-print often involved deploying expensive card-based payment solutions, however
PaperCut NG release stations allow this to implemented in a more cost effective way.
An example of how print release stations would be used in this scenario is:
1.
Users print documents from a workstation without any assistance from staff.
2.
The printed documents will be held in the queue until released by a staff member.
3.
The user goes to the staff desk and asks for the document to be released.
4.
The staff member opens a release station (the program or a web page), finds the user's job, notes the cost and
226
Hold/Release Queues & Print Release Stations collects the payment from the user.
5.
The staff member presses the "Print" button, allowing the job to be printed.
6.
The user then collects the printed document from the printer.
If the user never pays for a print then the print job will be automatically deleted without any staff interaction.
To implement a pay-per-print hold/release queue:
•
• In PaperCut NG, setup the staff to be a "hold/release queue manager". This will allow them to log in to the
"manager mode" release stations. See Section 13.3.2, “Hold/Release Queue Managers”.
•
• There are two release interfaces to choose from:
•
Standard Release Station in "Manager mode" - requires minimal setup.
•
Web-based release interface - requires only a web browser.
13.2.4. Expensive Printers (Approved Printing)
At times it is necessary to restrict access to an expensive printer (like a color laser printer), or other printer that should only be used with an administrator's permission. Instead of locking the printer away where no one has access to it; the printer can be configured so that only administrators or hold/release managers can release print jobs. In this situation:
1.
The user prints the document to the restricted printer.
2.
The document is held in the queue awaiting approval by an authorized person.
3.
The user talks to the administrator (or approved user) who would decide whether the user should be allowed to perform the print.
4.
The administrator logs into the web-based release interface from any machine on the network, and "Release" or
"Cancel" the job as appropriate.
To implement admin/manager only release interface:
• In PaperCut NG, enable the hold/release mode on the printer(s), and select the "Admin/Manager only release"
mode. See Section 13.3.1, “Enabling hold/release support on a printer” for more info.
• It is not necessary to set up a dedicated release station near the printer, because the web-based release interface can be used from any machine on the network.
• It is also a good idea to put a notice on the printer that tells users how to have their documents released.
13.2.5. Delegated Print Release
It is sometimes useful to allow a user to release jobs printed by other users. We call this Delegated Print Release.
An example scenario is when a teacher needs to be able to view and release both their own jobs and also jobs printed by their students. This could be acheived by making each teacher a hold/release queue manager, but that would allow them to view and release any job. By using Delegated print release, teachers will be able to view and release only the print jobs they are need to manage.
In this situation:
1.
A student prints a document.
2.
The document is held in the queue awaiting approval by a teacher.
3.
The student talks to their teacher who will decide whether the document should be allowed to print.
227
Hold/Release Queues & Print Release Stations
4.
The teacher logs into their end-user web-based release interface from any machine on the network and releases or cancels the job as appropriate.
To implement Delegated print release:
1.
2.
Select the teacher's account via Users section
3.
Select the option Allow this user to release jobs printed by others (Delegated print release) under
Advanced Options.
4.
Enter a list of student usernames delegating print release to the teacher. Alternatively enter an existing group name under Groups. For example, if all students belong to "students" group, you can simply enter "students".
5.
Click Apply . Now this teacher will be able to release delegated jobs via the end-user web-based release interface.
6.
To prevent students from viewing/releasing their own jobs, only allow group "teachers" to view held jobs. To do that:
1.
Select the option Allow users to view held jobs (hold/release queues) via end-user interface under
Options
→
General
→
User Features
2.
Select the option Only allow users in this group to view held jobs:
3.
Set the group name to "teachers".
13.2.6. Override/Change Account Selection during Admin Web Release
Many educational organizations want to charge for printing which may mean that some users can not print because of a low balance. This means that the print job will wait in the Secure Hold/Release queue until it is either canceled, times out or the user obtains sufficient credit to release the job.
Release interfaces to override the selected account (Shared Account or Personal Balance) and charge the print job to a specific Shared Account, moving the cost of the print job from the user's selected Shared Account or Personal
Balance to a Shared Account that the Hold/Release Queue Manager has access to.
Important
The Hold/Release Queue Manager's must have access to the desired Shared Account for feature to work. They do not require the Standard Account Selection popup to be used.
In this situation:
1.
A student prints a document.
2.
The document is held in the queue awaiting additional funds.
3.
The student talks to their teacher who will decide whether the document should be allowed to print.
4.
The teacher logs into their end-user web-based release interface from any machine on the network and selects the [override] action for the job.
5.
The teacher then selects a Shared Account to charge the job to, optionally enters a job comment and clicks
Print.
228
Hold/Release Queues & Print Release Stations
Figure 13.6. Web based Print Release showing Override option
Figure 13.7. Selecting a Shared Account when using the Override option
To implement Override Print Settings to charge to a Shared Account:
1.
2.
Select the teacher's account via Users section
3.
Select the Account section and click Create a new account....
4.
Give the Shared Account a name. Determine if this is to be a restricted Shared Account (e.g. can not have a negative balance, limiting the amount of use) or if it is unrestricted and allowed to accrue a negative balance.
5.
Click Apply then select the Security tab.
6.
Find the teacher's user account in the Users: option and click Add.
7.
Now this teacher will be able to Override jobs via the web-based release interface.
13.2.7. Unauthenticated printing
In some environments it is not possible (or very difficult) to have users authenticated when printing. This could be due to a technology constraint (like using Macs in mainly Windows environment) or could be for convenience (like having kiosk computers in the library that people can use without logging in).
229
Hold/Release Queues & Print Release Stations
In these scenarios, print jobs are printed under one name, but charging should be allocated to another. For example, a job is printed by an generic "library user", but there is a need to charge to the user's real account. In order to charge the correct user for printing, PaperCut NG needs to identify the user to charge, and this can be achieved by using a release station in "Release Any" mode.
This works as follows:
1.
The user prints from a workstation but is not authenticated, so jobs are allocated to a generic user.
2.
The print job is held in the queue awaiting release.
3.
The user walks to the release station and enters a username and password. Alternatively the user may log into the PaperCut NG web interface and select Jobs Pending Release.
4.
All jobs held are listed. Jobs can be identified by document name or workstation machine name.
5.
The user selects his or her jobs. Any jobs released are charged to that user's account.
Figure 13.8. All documents easily identifiable by document and machine name
To implement unauthenticated printing using a release station:
• Set up a low-end workstation near the printer(s).
•
• In PaperCut NG, enable the printer(s) for release station use, and select the "User release" mode. See
Section 13.3.1, “Enabling hold/release support on a printer”.
• To allow users to release jobs via the end-user web based release interface, also enable Release Any mode for
To implement unauthenticated printing using the browser interface:
•
• Ensure end-users have the ability to view held jobs and can release any job (charging to their account). More
information can be found at Section 13.3.4, “End-User Web Based Release Interface Configuration”.
230
Hold/Release Queues & Print Release Stations
13.3. Release Station Configuration
This section describes various aspects to configuring release stations.
Some additional installation notes can also be found in the release station README file located here:
[app-path]\release\README.txt
13.3.1. Enabling hold/release support on a printer
By default, print jobs will be sent directly to the printer and will not be held. To turn on hold/release support on a given printer:
1.
Log on to the administration section.
2.
Navigate to the Printers section.
3.
Select the printer.
4.
Select the option to Enable hold/release queue.
5.
Choose the appropriate release mode for your needs.
The two release modes available are:
• User Release - this is the standard mode that allows users to release and view only the jobs printed under their name/user account.
• Admin/Manager only release - in this mode, jobs can only be released by administrators or hold/release queue managers.
Tip
To configure multiple printers with hold/release queue support, the Copy settings to other printers function can be used. To use this, configure one printer as required, press the Copy settings to other
printers and select the printers to copy the settings to.
13.3.2. Hold/Release Queue Managers
A hold/release queue manager is a user that has additional privileges to manage release stations and jobs held in hold release queues. Managers can:
• Log on to the "manager mode" release stations (both the software and web-based release station).
• Log on to the "secure mode" release stations which switches them into manager mode so that users' print jobs can be released.
• Release jobs that can only be released by managers or administrators.
• Can close the Standard Release Station when running in full-screen mode.
• Use the Override Print Account selection in the web-based release station.
To make a user or group a hold/release queue manager:
1.
Log on to the administration pages.
2.
Navigate to the Options
→
Admin Rights.
3.
Add a user or group as an administrator.
231
Hold/Release Queues & Print Release Stations
4.
To restrict their access to only the release station interface and deselect all the other admin rights.
5.
Click on the Apply button to save the changes.
It is also possible to make a user a hold/release queue manager by following the steps below:
1.
Log on to the administration pages.
2.
Navigate to the Options section.
3.
Find the Release Station security section.
4.
Enter user's username in Hold/Release Queue Managers field. To enter multiple users, separate usernames with a comma (
,
).
13.3.3. Standard Release Station Configuration
The Standard Release Station is configured using a configuration file located in the directory where the release station executables are located. The default configuration file is:
[app-path]\release\config.properties
This configuration file allows you to configure the behavior and look of the release station in a number of ways. Each of the configuration items are described in the table below:
Config name
mode use-username-authentication use-card-authentication show-jobs-from-queues releases-on confirm-printing display-columns display-column-widths
Description
The mode changes the behavior of the release station depending on the need.
The available modes are described in Section 13.3.3.1, “Release Station
(Y/N) - Enable username authentication. Users will be required to enter their domain username to log into the release station. They may also be required to enter their password, depending on the 'mode' setting. Default: Y (Yes).
(Y/N/USERNAME) - Enable card-based authentication. This is designed for use with dedicated hardware card readers.
If Y: The card number is validated against the user's card-number field.
If USERNAME: The card value is interpreted as a username. The user will be prompted for a password if required.
Default: N (No).
Filters the list of jobs to only those print queues listed. This is a comma separated list of full printer names (i.e. server\printer). This is useful when there are multiple release stations, each managing the queues of a different set of printers.
This option applies to installations using Find Me Printing and sets the behavior
of jobs released from a virtual queue. For more information see Chapter 14,
Find Me Printing and Printer Load Balancing.
This setting defines the printer (or list of printers) that the jobs should be printed to when released. This is usually the printer(s) in close proximity to this release station.
When enabled (Y) and users release a job that is charged to their personal account, a confirmation dialog is displayed to confirm that the user wants to print and be charged for the job. When disabled (N) the confirmation dialog is never displayed.
Used to customize the columns displayed and the order they appear in the list of print jobs.
The default value is: date,user,printer,document,machine,pages,cost
Used to customize the width of columns displayed. The setting can only be used if the display-columns is defined. The number of values must match the
232
Hold/Release Queues & Print Release Stations
Config name
hide-printer-server-names show-print-all show-cancel-all max-idle-secs background-color font-color locale title instructions card-and-username-instructions username-label password-label logo-image scale-factor release-cancel-gui-style enable-card-self-association enable-on-screen-keyboard
Description
number of values in the display-columns setting. The default value is:
8,12,25,30,15,8,8
(Y/N) - Used to hide the printer server names from the list of print jobs. Default:
N (No)
(Y/N) - Indicates whether the Print All button should be displayed. Default: Y
(Yes)
(Y/N) - Indicates whether the Cancel All button should be displayed. Default: Y
(Yes)
The number of seconds without user input, before the user is logged out of the release station. The default is 30 seconds.
Allows for customizing the background color of the release station to match the organization's colors. The color format is the hexadecimal color code used in
HTML - #RRGGBB (where RR is the red component, GG is the green component and BB is the blue component).
Allows for customizing the font/foreground color used in the release station. The color format is the hexadecimal color code used in HTML.
Allows to override the default language used for the release station. The value is a valid ISO language code. E.g. en, zh_HK.
The title that appears at the top of the release station screen.
The instructions to display at the login page. A
<br> can be included to start a new line.
The instruction text that appears when using both card authentication and username authentication, appearing in-between the card entry and username entry fields. A
<br> can be included to start a new line.
Override the label text for the Username field.
Override the label text for the Password field.
Allows a custom logo image to be displayed. For best results the image should be between 50 and 80 pixels in height. PNG, JPG or GIF images are allowed.
Allows to adjust the size of text displayed in the release station. Higher value increases the text size. Larger text may be preferable on high resolution screens or touch screens. The default is 1.5.
Allows to set the GUI style of the release station actions. The valid styles are link and button
.
Setting it to button is useful when running release station on touch screens.
The default is link .
(Y/N) - Enable or disable card self-association. This allows users to associate their card with their account without needing any administrator assistance.
Default: N (No)
(Y/N) - Enable or disable the on-screen (software) keyboard. Use of the on-screen keyboard is recommended for touch-screen devices. Supported on
Microsoft Windows only, via the on-screen keyboard utility (osk.exe) or an alternate application. Default: N (No)
Specify an alternate on-screen keyboard application to the Microsoft Windows default. Supported on Microsoft Windows only. Default: (none) on-screen-keyboard-path
Table 13.1. Standard Release Station config settings
Tip
When running release stations from the
\\server\PCRelease share, each workstation can have its own configuration file. The "config.properties" is used for default settings for all release stations, but
233
Hold/Release Queues & Print Release Stations settings can be overridden by defining another configuration file for each release station. These files should be put in the same directory and be named using the following convention: config.[machine-name].properties
where [machine-name] is the name of the machine running the release station. Please note that since the machine specific configuration file overrides the default settings, if you wish to clear a setting then it must be unset or commented out in both configuration files.
Apple OSX servers may require the use of the fully qualified domain name of the machine running the release station rather than the short name.
A custom configuration file may also be specified as a startup command-line option using the following syntax: pc-release.exe --config "[config file path]"
13.3.3.1. Release Station Modes
The release station modes available are described below. The release station mode is changed in the configuration
file as described in Section 13.3.3, “Standard Release Station Configuration”.
Mode
ReleaseAny
Manager
Secure
NoPassword
Description
This is the default mode. It allows a user who logs onto the release station to release any held jobs. Any jobs released will be charged to the logged in user.
Manager mode allows only administrators or hold/release queue managers to log in to the release station. In release station mode, all jobs are listed and users are not automatically logged out due to inactivity.
Secure mode allows users to only see and release print jobs that they have printed. Release station managers can see and release all users' print jobs.
This works similar to the secure mode, however users don't need to enter the password to view jobs.
Table 13.2. Standard Release Station modes
In all modes except Manager mode, users are logged out automatically after a period of inactivity defined in the configuration file, the default being 30 seconds.
13.3.3.2. Card-based User Authentication
In some environments, users are issued with identity cards that can be used for authentication. The cards might be used to gain entry to buildings, or borrow from a library. The cards can also be used to authenticate users at the standard release station. Using a card is often much more convenient and less error-prone than entering a username and password.
To use card-based authentication an appropriate hardware card-reader is required. The card reader must be connected to the machine running the release station and act like a keyboard. i.e. when the user swipes/scans their card, the card reader outputs the digits just as if someone entered them using the keyboard. There are card readers that can do this for all commonly used card types (e.g. magnetic stripe, barcode, etc). An easy way to test a card reader is to open a text editor and place the cursor in a new text document. Then when a card is swiped the card number will appear in the text file.
The card numbers entered at the release station are validated against the Card/Id number field for the user. This can be found at the bottom of the user details screen in the admin interface. Before card authentication can be used,
234
Hold/Release Queues & Print Release Stations the users' card numbers must be associated with the user record in PaperCut NG. The numbers can be entered
Once card numbers are associated with users, the card-based authentication can be enabled in the release station by setting the use-card-authentication to
Y in the release station's config.properties
file. Once the release station is restarted it will be in card-authentication mode, and can be tested by swiping a card through the card-reader.
Alternatively, card numbers may be self-associated by users at the release station. Enable this functionality by setting enable-card-self-association to
Y
. Note that this also requires use-card-authentication to be enabled as well.
The config.properties
file has some other settings to change how the card-number is read from the reader.
For example, you can change the header and trailer characters used by some card readers to indicate the start and end of the card number. See the config file for details.
13.3.3.3. Friendly client machine aliases
In some environments (for example public libraries), it can be important for users to identify print jobs by the client machine they were printed from. By default, the release station will list the either the IP address or the machine's unique network name Neither of these are helpful to release station users. To avoid this problem the administrator can define a list of aliases, that map the unfriendly names to a more user-friendly name.
For example, print jobs might appear in the release station as
192.168.1.100
or winpc0076
, but would be more meaningful for the user to appear as
Public PC 1
.
These aliases are defined in the
[app-path]/release/client-machine-aliases.properties
file. The entries are in the format:
[machine]=[alias]
It is also valid to have multiple entries that map to the same alias. So to add aliases for the example above the following lines would be added to the client-machine-aliases.properties
file:
192.168.1.100=Public PC 1 winpc0076=Public PC 1
13.3.3.4. Job timeout
If a user does not release their held job after a defined time, their job will be automatically deleted. This is to prevent a buildup of old/abandoned jobs in the hold/release queue. The default timeout is
30 minutes, and can be changed as follows:
1.
Navigate to Options
→
General
→
Hold/Release Queues and find the option Delete held jobs if not
released after.
2.
Enter the number of minutes to wait for users to release their job before it is deleted.
3.
Press Apply
13.3.4. End-User Web Based Release Interface Configuration
Configuration options for the end-user web based release interface can be found in the administrative interface at
Options
→
General
→
User Features. These options control the availability of the Jobs Pending Release option available to end users. The available options are:
235
Hold/Release Queues & Print Release Stations
Figure 13.9. End-user web based release interface options
• Allow users to view held jobs - this option enables the Jobs Pending Release screen in the user web tools.
When this option is disabled, no related functionality is available from the user web tools interface.
• Users have permission to: - this option changes which type of jobs users can see and/or release. The available options are:
• view their own jobs only - users may see their own jobs that are held in the hold/release queue. Jobs printed by other users are not displayed. They may cancel their own jobs, but cannot release them. This is useful if users are required to be physically at the printer to release a job, where a standard release station is running.
• release their own jobs - users may release or cancel their own jobs. Jobs printed by other users are not displayed.
• release any jobs (charged to their account) - users may release or cancel any job that is being held, including jobs from other users. If a user releases a job that was sent by a different user, the releasing user is charged for the job. This option is equivalent to the
Release Any mode used in Release Station and is ideal for authenticating printing in a unauthenticated environment.
• Enable the 'Release All' and 'Cancel All' buttons - enabling this option allows users to release or cancel all held jobs by clicking one button. When this option is disabled, users must release or cancel jobs individually.
This option is purely for the convenience of the users. It can save a user a few clicks when they want to release all their jobs at once. However if the user is able to release jobs other than their own, a user might accidentally release (and be charged for) many other users' jobs.
13.4. Mobile Print Release Configuration
Mobile Print Release configuration is detailed in the Mobile Print Release Chapter.
236
Chapter 14. Find Me Printing and Printer
Load Balancing
This chapter covers two powerful features: printer load balancing and "find me" printing.
• Find Me Printing - solves the problem of finding the closest printer from a long list of available printers. It is a roaming print service that allows print jobs to find users based on their physical location. It's sometimes referred to as "Pull Printing", "Push Printing" or "Follow Me" printing.
• Printer Load Balancing - covers the act of automatically distributing print load between multiple physical printers.
These topics are addressed together in this chapter as they both involve the concept of print job redirection, where a job is taken from one queue and transferred to another.
The topics covered in this chapter are relatively advanced in nature and targeted towards the administrator who is already comfortable with PaperCut NG and print queue configuration. If implementing PaperCut NG for the first time it is recommended to plan a simple configuration in the first phase, then return to implement find me printing or load balancing in a later phase once users and administrators are comfortable with the basic features.
14.1. Find Me Printing
Find Me Printing is best described not by what it does but by the problem it solves. Consider a large organization with hundreds of printers. The task of selecting the "best" printer from the list at the time of print can be daunting.
Organizations tend to mitigate this concern using a number of methods:
• Naming Conventions - network administrators will adopt a printer naming convention that helps users locate the best printer. A common convention is to use the room name or floor number. This is usually complemented by a sign on the printer itself.
• Location Adaptive Login Scripts - in many respects a location adaptive login scripts is a most elegant solution.
The login script automatically adds the printers to the workstation based on the workstation's physical location
(denoted by the computer name). For example, any workstation containing "lvl2" in the name will have the two printers on Level-2 by default. Users will only need to consult the full list of printers in the rare occasion that they wish to print to a printer outside their physical level/room.
• Global Profile - administrators map the "best" printer based on location globally on the workstation (e.g. using rundll32 printui.dll,PrintUIEntry /ga /n\\server\printer on Windows). Any user that logs on to the workstation will have the most appropriate printer selected by default.
All these methods have their drawbacks and require careful planning on the part of administrators, and the need for end-users to understand conventions/processes. Find Me Printing solves the problem by "asking the job to find the user, rather than having the user find the printer". It works as follows:
1.
The user prints to a single site-wide global queue.
2.
The user then walks up to a Release Station logs in, locates their job and releases it.
3.
The job will then proceed to automatically print to the closest physical printer.
Find Me Printing is referred to by users as other terms such as Follow-me printing (because print jobs follow you to a printer), Pull Printing (because the job is pulled from the global queue) or Push Printing (because the release station pushes the job to the nearest printer).
Before implementing a Find Me Printing scenario, the administrator should be familiar with release stations (see
hardware and driver compatibility. Find Me Printing works by re-directing a job targeted at one queue to another and hence printer compatibility is important. For example, a job designed to print on an inkjet photo printer will not usually be suitable for printing on a laser printer. The topic of printer/driver compatibility is discussed in detail in the section proceeding the examples below.
237
Find Me Printing and Printer Load Balancing
14.1.1. Implementation by Example
Implementing Find Me Printing is best described by way of example. The following sections cover some common scenarios for implementing Find Me Printing.
14.1.1.1. Example 1: Single Virtual Queue (High School)
14.1.1.1.1. Scenario
East Beach High School has seven high volume laser printers of the same model at various locations throughout the campus. When sending a print job students must currently select the printer nearest to them before retrieving the document. Students often send jobs to the wrong queue and rather than going to pick it up they re-send the document to a closer queue and leave the original document uncollected.
The current print queues are named laser-1 through laser-7 with the number corresponding to a label on the printer. All printers are hosted on the print server called print-server
. All printers are the same make and model
(using the same driver).
In the library there are two printers, laser-6 and laser-7
, side by side.
The goal is to implement one central queue to receive all print jobs. A release station will be set up next to each printer. Each release station will allow users to have their job printed at the nearby printer.
14.1.1.1.2. Implementation
The first step is to create a new print queue on the print server. This queue will be a virtual queue with hold/release enabled. When students print to the virtual queue their job will be held, and the release station the user releases the job at will determine to which printer the job is sent (the job is pulled from the virtual queue to a printer near the user).
A new queue will be called find-me-queue is created by the administrator on print-server using the normal methods for the operating system in use. The queue is created using the same driver that laser-1 through laser-7 use. The queue points to the IP address of one of the printers - this is not strictly necessary as the "virtual queue" is just a collecting queue that forwards jobs to real queues, however some printer drivers "complain" if they do not point to a real printer.
The administrator ensures that the print queue has registered itself with PaperCut NG by checking the Printers tab
Removing/Deleting/Ignoring Printers”.
After creating of the new virtual queue the administrator performs the following:
1.
Navigates to Printers
→
find-me-queue
→
Summary in the PaperCut NG administration interface.
2.
Changes the Queue type option to This is a virtual queue (jobs will be forwarded to a different queue).
This reveals the Job Redirection Settings section.
3.
The option Jobs may be forwarded to these queues: determines which queues find-me-queue is capable of redirecting to. The queues print-server\laser-1 through print-server\laser-7 are selected.
4.
Enables the option Enable hold/release queue and sets Release mode to User release (the default). This ensures that jobs are held in the virtual queue and not automatically forwarded to one of the targets.
5.
Clicks OK.
The next step is to configure the release stations:
1.
administrator decides that students should only be able to see and release the jobs they have personally printed, so sets up the release station in Secure mode.
2.
Each release station should be configured to release jobs on the printer it is associated with by setting the releases-on option in the release station config file. E.g. for the release station set up near the printer laser-4
, the option should be set to:
238
Find Me Printing and Printer Load Balancing releases-on=print-server\\laser-4
In the library (where there are two printers side by side) the administrator configures a single release station to release to either printer by setting the option to: releases-on=print-server\\laser-6,print-server\\laser-7
In this case when a user releases a job at the library release station PaperCut NG will select either laser-6 or laser-7
based on a load balancing algorithm (see Section 14.5.1, “Example 1: Simple Load Balancing”).
Now when students print from a lab computer to the virtual find-me-queue queue their job will be held. The student can visit any release station and see their job. When the student releases their job at a release station the job will be pulled from the virtual queue into the queue or queues associated with the release station for printing.
the find-me-queue queue is set as the default queue on all workstations.
The administrator may now optionally un-share all but the virtual queue. This would enforce that users use the "find me" process rather than printing directly to one of the target printers.
239
Find Me Printing and Printer Load Balancing
Figure 14.1. Single Virtual Queue (High School)
14.1.1.2. Example 2: Multiple Virtual Queues (Different Printer Types)
14.1.1.2.1. Scenario
West Face University has a Graphic Design department who use two wide format plotters and seven color laser printers. The two plotters and two of the laser printers are located in the department print room, while the other laser printers are scattered around various locations. The plan is to add more printers next year.
The two wide format plotter queues are named wf-plotter-1 and wf-plotter-2
, and the color laser printers are named color-laser-1 through color-laser-7
. Laser 1 and 2 are located in the print room with the plotters.
The goals of the project are:
• Implement Find Me Printing so users don't need to remember the names associated with the ever growing list of printers.
• Implement release stations. This will ensure the student/staff member is there to collect their work minimizing the chance of one person accidently collecting another's work.
240
Find Me Printing and Printer Load Balancing
• Ensure the procedure is similar for all types of printers, meaning users only have to learn one process.
• Automatic load balancing in the print room to ensure all printers receive an equal load and throughput is maximized.
14.1.1.2.2. Implementation
This implementation differs from the previous implementation in that we have two distinct printer types. It is not technically possible to have one "find-me-queue" as jobs rendered by the application for the wide-format printer can't
The first step is to create a new print queue for each printer type on the print server. These queues will be virtual
queues with hold/release enabled. When a student prints to a virtual queue their job will be held at displayed at the release station. When a student releases their job, PaperCut NG knows which target queues are compatible (based on configuration) and selects one of the available target queues using an intelligent load balancing algorithm.
Two new queues called wf-plotter and color-laser respectively are created by the administrator on the print server graphics-print
.
wf-plotter is created using the same driver as the existing queues wf-plotter-1 and wf-plotter-2
, and likewise color-laser uses the same driver as its counterparts. Both new queues point to any physical device of the same type, e.g.
wf-plotter to wf-plotter-1
. This last point is not strictly necessary but some printer drivers complain if they do not point to a real printer.
The administrator ensures that both print queues have registered themselves with PaperCut NG by checking the
Following creation of the new queues the administrator performs the following:
1.
Navigates to Printers
→
wf-plotter
→
Summary in the PaperCut NG administration interface.
2.
Changes the Queue type option to This is a virtual queue (jobs will be forwarded to a different queue).
This reveals the Job Redirection Settings section.
3.
The option Jobs may be forwarded to these queues: determines which queues wf-plotter is capable of redirecting to. The queues graphics-print\wf-plotter-1 and graphics-print\wf-plotter-2 are selected.
4.
Enables the option Enable hold/release queue and sets Release mode to User release (the default). This ensures that jobs are held in the virtual queue and not automatically forwarded to one of the targets.
5.
Clicks OK.
6.
Repeats steps 2 through 5 for the color-laser queue, except the option Jobs may be forwarded to these
queues:
in step 4 is instead set to graphics-print\color-laser-1 through graphics-print\color-laser-7
.
The next step is to configure the release station:
1.
administrator decides that students should only be able to see and release the jobs they have personally printed, so sets up the release station in Secure mode.
2.
A single release station should be configured to release jobs to the printers it is associated with by setting the releases-on option in the release station config file. In the print room the administrator sets the option to the four printers: releases-on=graphics-print\\wf-plotter-1,graphics-print\\wf-plotter-2,\ graphics-print\\color-laser-1,graphics-print\\color-laser-2
3.
A separate release station is also set up next to each of the five remaining laser printers in the department. The releases-on is set to the single adjacent printer in each case.
241
Find Me Printing and Printer Load Balancing
Now when a student prints from a lab computer to either virtual queue ( wf-plotter or color-laser
) their job will be held. The student can visit the release station and see their job. When the student releases their job in the print room, the system will automatically implement load balancing and select an available compatible printer. This setup
is illustrated in Figure 14.2, “Multiple Virtual Queues (Graphics Department)”.
Important
Load balancing may not be appropriate on the plotters if manual loading of paper media is required, as it is not possible to know beforehand which target printer will be selected. In this case a separate release station may be required for each plotter.
Figure 14.2. Multiple Virtual Queues (Graphics Department)
14.1.1.3. Example 3: Multiple Location Specific Virtual Queues (Large Company)
14.1.1.3.1. Scenario
Acme Inc. is a large organization with hundreds of printers located throughout. They maintain a common printer fleet
242
Find Me Printing and Printer Load Balancing of grayscale devices and a smaller but matching fleet of color devices.
The existing grayscale devices use a naming scheme like site1-server\B02_F12_G04
, where
B02 represents
"building 2",
F12 represents "floor 12",
G04 meaning it is the fourth grayscale printer on that floor. Color devices use the same naming scheme except the
G is replaced with a
C
.
Each floor of each building has a print room with several grayscale devices and two color devices. The organization also has multiple offices located and separate physical sites. Each sites hosts their local print queues on their own local print server, however all sites exist in a single WAN and shared domain.
Through trial testing, the IT administrators have confirmed that the Postscript drivers supplied with the color devices also work with the lower cost grayscale-only version of the printers. This means that one common driver will work across the full fleet.
The main goals of the project are:
• Simplify the printing process for users, so that they do not need to decipher the naming scheme to work out their closest available printer.
• Implement a system/procedure common across all sites.
• Reduce wasted printing by ensuring the user is physically present in the print room to pick up their job when it prints.
• Ensuring high uptime by minimizing single points of failure.
14.1.1.3.2. Implementation
This implementation differences from the previous implementation in that there is a large number of printers and users spread across multiple physical sites. Although it would be possible to implement one global virtual "Find-Me
Queue", there are some benefits in implementing multiple virtual queues - one per site:
• Minimize network traffic - jobs should only spool on queues on the local server where possible.
• No single-point-of-failure - if an issues occurs on the single "find me queue", it would affect printing on all sites.
Implementing multiple virtual queues will offer considerable benefits. One queue per site, or maybe even one queue per floor/department on larger sites should be considered as the benefits will outweigh the small additional overhead in administration/setup.
The first step is to create the new print queues that will become the virtual queues. The administrator installs a separate queue for each site called "find-me-queue" on each of the site's servers. This queue is set up using the common Postscript driver that has been confirmed to work with all models in the printer fleet.
The administrator ensures that all print queues have registered themselves with PaperCut NG by checking the
After creation of the new queues the administrator performs the following on each new virtual queue. ( site1 example).
1.
Navigates to Printers
→
site1-server\find-me-queue
→
Summary in the PaperCut NG administration interface.
2.
Changes the Queue type option to This is a virtual queue (jobs will be forwarded to a different queue).
This reveals the Job Redirection Settings section.
3.
The option Jobs may be forwarded to these queues: determines which queues are compatible. Because this virtual queue is capable of forwarding to all printers in the organization the Select all printers is clicked.
4.
Enables the option Enable hold/release queue and sets Release mode to User release (the default). This ensures that jobs are held in the virtual queue and not automatically forwarded to one of the targets.
5.
Clicks OK.
6.
Repeats steps 2 through 5 for all other find-me-queue
's on each site server.
243
Find Me Printing and Printer Load Balancing
The next step is to configure a release station for each floor's print room:
1.
release station is configured in Secure mode so that staff can only see and release the jobs they have personally printed.
2.
The release station should be configured to release jobs to the printers it is associated with by setting the releases-on option in the release station config file. The administrator sets the option to the full name of the printer(s) in each print room: releases-on=site1-server\\B02_F1_G01,\ site1-server\\B02_F1_G02,site1-server\\B02_F1_C01
All workstations should be configured to use the local find-me-queue on each site by default.
Now when a staff member prints to either virtual queue their job will be held. The staff member can visit the release station and see their job. When the staff member releases their job it will be sent to any of the available and
Advanced: PaperCut NG can also support redirection between print queues in different servers. In this example, it may occur when a laptop user that roams between sites prints. Their laptop may be configured to print to the virtual queue on site1
, but they have release their job on a printer hosted on the server in site2
. Directing between
“Cross-Server Job Redirection” for further information.
244
Find Me Printing and Printer Load Balancing
Figure 14.3. Multiple Location Specific Virtual Queues (Large Company)
14.1.2. Find Me Printing and Web-Based Release
The Find Me printing examples covered above involve setting up a release station so that users can release jobs to the printers at their current location. The web based release interfaces are also supported (via the user web tools, admin interface or full screen web based release interface), although due to the lack of location information the user is asked to select the destination printer.
When a user releases a job held in a virtual queue using one of the web based release interfaces they are
Figure 14.4. Find Me Printing and Web Based Release Interfaces
When using web based release interfaces in conjunction with Find Me Printing it is recommended to populate the
Location field on printers for the convenience of users.
14.2. Global Print Driver
A global find-me print queue, combined with secure print release, provides convenience to end-users. On the flip side it poses a number of technical challenges for the system administrator. One challenge is print driver selection in a mixed brand environment.
A single global queue means one print driver, whose output must be compatible with N possible target printers.
Finding a suitable driver is often a difficult trial and error exercise. The available solutions are:
14.2.1.
14.2.1.1. The PaperCut Global Print Driver
If your organization has a mix of printer brands, the PaperCut Global Print Driver is the most straightforward solution.
245
Find Me Printing and Printer Load Balancing
• A brand independent maximum compatibility signed print driver.
• Designed to work on the widest possible range of printers out of the box.
• Supports all main print features (duplex, color, paper size and tray selection).
14.2.1.2. Predominant Brand/Vendor Driver
If your organization has one predominant printer brand, it may be appropriate to use this brand’s driver for the global
queue, and use PaperCut’s adaptive transforms to enable compatibility on other brands.
14.2.2. About the PaperCut Global Print Driver
The PaperCut Global Print Driver should not be confused with "universal drivers" offered by leading printer manufacturers. Manufacturer universal drivers are designed to work with multiple models across a single brand.
PaperCut’s Global Print Driver works across both multiple models and multiple brands.
14.2.2.1. Windows:
The PaperCut Global Print Driver is a brand neutral, maximum compatibility PostScript driver developed by
PaperCut for Microsoft Windows. As a signed driver, it can be deployed and installed like any standard Windows print driver. You can find the driver at:
[install-path]/providers/print/drivers/global/win/
14.2.2.2. Mac and Linux:
At this time PaperCut is not supplying a Global Print Driver for Mac and Linux, and instead recommends the use of the "Generic PostScript Driver" included within these platforms. PaperCut’s server software is designed to use the output of the generic driver and complement it with adaptive transforms, to give maximum compatibility with a wide range of popular printer brands.
14.2.2.3. How it works
The PaperCut Global Print Driver is a standards compliant PostScript driver developed to produce PostScript output that is as widely compatible as possible. If vendor specific extensions are required to achieve functionality, the
PaperCut server software works transparently in conjunction with the driver to apply these extensions to each job.
This is done in the background using in-built Print Description Language (PDL) transforms.
14.2.2.4. Benefits
• Easy to deploy
• Consistent user experience across brands
• Familiar Windows print dialog design
14.2.2.5. Tradeoffs
• Devices connected to the global queue must support PostScript (other languages are in development)
• Advanced vendor specific extensions (e.g. color profiles) are not available via the Global Queue
• The broad set of capabilities available to the Global Print Driver may not be available on the destination printer.
For example, an A3 or Tabloid job can be sent to a device that prints only A4 or Letter. Depending on the target printer, the job may be scaled to A4 or Letter, cropped to size, or rejected by the device entirely.
246
Find Me Printing and Printer Load Balancing
14.2.3. Installation & Setup
Setting up Find-Me printing with the PaperCut Global Print Driver on Windows is done as follows:
14.2.3.1.
Step 1: Set up each device queue using the manufacturer’s standard driver (important).
Step 2: Set up the Global Virtual Queue using the PaperCut Global Print Driver.
Step 3: Configure Secure Print Release and Find-Me Printing.
Important
Make sure the Enable Advanced Printing Features option is disabled in the virtual queue's properties dialog.
Important
The PaperCut Global Print Driver should not be used on the individual device queues. It should only be used on the global virtual queue(s). It is important that the manufacturer's own driver is installed on the device’s direct print queue. The reason for this is that PaperCut uses the manufacturer's driver to identify the device and determine the type of output required.
14.2.3.2. User Education
The Global Print Driver should satisfy the vast majority of end users’ standard printing requirements. Should a user require device-specific functionality such as color profile settings, they can achieve this by printing to the direct device queue, which should be set up with the vendor’s driver (see Step 1 above).
Best practise is to set up the Global Virtual Queue as the desktop default printer.
14.2.4. Using Vendor Driver and Adaptive PDL Transforms
An alternative to using the PaperCut Global Printer Driver is to use a Vendor/Manufacturer driver and adapt its output if required. This setup may be preferred if there is a single dominant vendor on the site and there are reasons to use the vendor’s own driver. In some cases, vendor specific output will not work on another brand, such as differing tray names. PaperCut adaptive PDL Transforms can be used to solve this problem.
This is an advanced subject. Unlike the PaperCut Global Print Driver, vendor specific transforms need to be
14.2.4.1. Supported transform environments
PDL transforms on remote target printers are only supported on Windows. In addition, transforms are only applied when the virtual queue and the target printer are set up on the same operating system type e.g. Windows to
Windows, Mac to Mac.
Source Print Server Destination Print Server Global Virtual Queue Location
247
Find Me Printing and Printer Load Balancing
Source Print Server
Windows
Linux
Mac
Table 14.1. Supported transform environments
Destination Print Server
Windows
Linux
Mac
Global Virtual Queue Location
Local and Remote
Local only
Local only
14.3. Requirements For Job Redirection (Load Balancing or Find Me Printing)
When redirecting a job from one queue to another, the job is rendered by the source queue's driver, and printed by the destination queue's printer. It is therefore vital that the destination printer is compatible with the source driver.
To be compatible, the source (or virtual) print queue and the destination print queue must at least use drivers that produce the same print language (e.g. PostScript to PostScript or PCL5 to PCL5). However due to the differences in the way each manufacturer uses a print language, and even differences between models from the same manufacturer, compatibility can be limited to printers of the same or similar models.
The ideal setup for job redirection is when all target printers are of the same model. If this is not the case, you will need to select a driver for the virtual queue that gives the best result across your fleet of destination printers.
A great way to achieve compatibility with a wide range of PostScript printers on Windows is to use PaperCut's
Global Print Driver on the virtual (source) print queue.
If instead you wish to use a manufacturer driver for the virtual (source) print queue, pick a simple lowest common
denominator driver and test it for compatibility with each one of your printers. On the Mac the "Generic Postscript
Driver" is a good choice. On Windows select a Color Postscript driver for a mid range popular model. Always carefully test driver compatibility before implementing Find Me Printing. Take care to address corner cases such advanced graphics options, grayscale mode, paper sizes, duplexing, tray selection, etc. If a common driver can not be found, you may need to implement multiple virtual queues as discussed in Example 2 above. The following sections provide a simple procedure that can be followed to to test printer compatibility.
Tip
It may be possible to solve compatibility problems with manufacturer drivers using adaptive PDL
transforms. See Section 14.2.4, “Using Vendor Driver and Adaptive PDL Transforms”.
14.3.1. Compatibility Testing
1.
Select your candidate driver to use for your global virtual queue. Use it to set up a print queue on the server, and share the queue.
2.
Select the new printer in PaperCut NG and change it a virtual queue.
3.
In the list of compatible queues, select the printers for which you'd like to test compatibility.
4.
Enable the Hold/Release option on the queue.
5.
Print a test document (e.g. print an email) to the virtual queue from a workstation. The job should hold in the virtual queue.
6.
On the Jobs Pending Release tab under the Printers section, release the held job. Select a target queue to test when prompted.
7.
Verify that the job printed correctly. Also check the App. Log sections for any error reports.
8.
Repeat the previous 3 steps for all printer types and using different document settings and applications.
Make sure you test a variety of print options targeted at all device types. Problems may manifest in various and
248
Find Me Printing and Printer Load Balancing maybe subtle ways:
• Error events logged in PaperCut NG's App Log.
• Error status on the printer (e.g. a red light and failed print status message).
Or more subtle issues like:
• Truncated documents because of different device margin sizes (printable area).
• Errors only when non-default options options are selected (e.g. finishing options).
• Issues only on very large documents (due to printer memory limitations).
• Errors/problems when certain paper sizes are selected.
If issues/problems/errors occur:
1.
Try disabling the Enable Advanced Printing Features option in Windows on the virtual queue on the server.
This is accessed by right-clicking on the printer, selecting Properties..., then the Advanced tab. This change can improve redirection results with some drivers and is required if using the PaperCut Global Print Driver.
2.
If you continue to experience compatibility issues, you may need to consider setting up multiple virtual queues
14.3.2. Find Me Printing Implementation Checklist
Setting up Find Me Printing involves several configuration steps that must be completed before the setup will work.
Following is a checklist that can be used to ensure that the main requirements have been carried out. It can also serve as a troubleshooting guide in case of unexpected results.
1.
A new print queue should be created to function as the virtual queue. This print queue should be created using the standard methods or tools provided by the host operating system.
2.
The driver in use by the virtual queue should be confirmed to be compatible with the target printers. The output produced by this driver is what will be sent to the printer, so it must be compatible.
3.
The following settings should be configured in the PaperCut NG administration interface for the virtual print queue: a.
Queue type should be set to This is a virtual queue (jobs will be forwarded to a different queue).
b.
Jobs may be forwarded to these queues should be configured to reflect the possible or compatible targets for redirection.
c.
Enable hold/release queue should be enabled.
4.
When using Find Me Printing release stations are recommended because they can automatically choose the best nearby printer (based on a match between the virtual queue's configured compatible queues, the release station's configured "releases on" queues and current printer load). If the web based release interface is used instead the user must choose the desired printer from the list of all compatible queues.
5.
The releases-on option in the release station configuration file should be configured to reflect where jobs released at this station can be sent. PaperCut NG will compare this list with the Jobs may be forwarded to
these queues setting of the virtual queue to find possible target queues. Take care to ensure the name is spelt exactly the same as listed in the printer list.
6.
The show-jobs-from-queues option in the release station configuration file may optionally be configured to limit the jobs shown in the release station to one or more queues. This can be useful for situations with multiple virtual queues and release stations running in Release Any mode.
7.
If there are multiple print servers and the ability to redirect jobs across print servers is required, ensure that the
requirements in Section 14.4.3, “Cross-Server Job Redirection” are met.
14.4. Advanced Configuration
249
Find Me Printing and Printer Load Balancing
14.4.1. Overriding cost and filter settings
The default (and recommended) setup is to have the filter and cost settings applied to the virtual queue, for example the global "find-me-queue" as explained in the examples. This ensures that you have a common cost and access policy across all printers associated with that queue - a model that your end-users can easily understand. There may however be some special cases where you may wish to instead apply cost and filter settings based on the target queue/printer selected:
• A printer may have less memory that others and jam/error on large jobs. Implementing a page or job size filter at the target queue level may help prevent problems.
• A printer may not support the full range of paper sizes and may jam if an incorrect paper size is selected.
The settings are overridden by the option Cost and filter settings are overridden by the target queue. Please use this option with care and careful consideration.
Important
If used incorrectly, the Cost and filter settings are overridden by the target queue option can be very confusing to end-users. For example, the cost that is displayed in the release station and/or client popup will be as calculated by the virtual queue settings. If, after the job is redirected, the cost changes, the user may become confused. As a general rule, don't override the cost, or if it must be overridden, communicate this situation to your users beforehand.
14.4.2. Mixed Color and Grayscale Printers
When the organization has a mix of grayscale and color printers it is important to configure Find Me Printing carefully. Often the simplest approach is to configure 2 virtual queues: one configured as a color queue and the other as a grayscale queue. This makes it simpler for users to understand where to print and what they'll be charged if they need color or grayscale printing. The queues should be configured as follows:
• Grayscale virtual queue - configured to default to grayscale printing, the color mode detection set to This is a
grayscale printer, and can release on all printers (including color printers).
• Color virtual queue - configured to default to color printing, and can only release to color printers.
Using a single virtual queue is also a valid option. There are no technical problems with this approach, however it may be a little more complicated for users to understand.
Important
If a physical printer is a grayscale printer then it is recommended that you set the color detection mode to This is a grayscale printer in PaperCut NG. This will ensure the job is logged as grayscale, and the user is charged correctly (i.e. not charged for color).
This also applies if there is a single virtual queue. If the job is released to a grayscale printer it will be logged and charged as a grayscale job.
14.4.3. Cross-Server Job Redirection
PaperCut NG supports redirecting print jobs across print servers, but due to technical limitations the print servers must be running the same operating system (e.g. Windows to Windows, Mac to Mac, etc.).
14.4.3.1. Cross-Server Job Redirection On Windows
To enable redirection of print jobs from one Windows print server to another some additional configuration is required. This section covers the steps necessary to set it up.
250
Find Me Printing and Printer Load Balancing
The
PaperCut Print Provider service is the Windows service responsible for interaction with print queues. For security reasons this service, as for most other Windows services, runs as the
SYSTEM account. This account does not have the privileges required to access another system and place a print job in one of its queues. Therefore to enable this functionality the privileges of the
PaperCut Print Provider service must be escalated.
The recommended way to escalate the privileges of the
PaperCut Print Provider service to the required level is as follows. First a service account is created with permission to create new print jobs:
1.
Create a new domain user called papercut_service
(or something suitably descriptive). This account will be granted permission to print on both/all print servers.
If there are multiple domains involved it may be easier to create local users on each print server which all have the same username and password.
2.
Ensure that the Password never expires option is enabled.
3.
Grant this user local administrator rights on the print server where it is installed. This gives the papercut_service the same privileges as the Windows
SYSTEM account.
4.
Ensure this user has the rights to print on all remote printers.
Next the
PaperCut Print Provider service on each print server is configured to run as the new service account (changed from default
SYSTEM to papercut_service
):
1.
Open the Windows Services list.
2.
Stop the service PaperCut Print Provider.
3.
Right-click the PaperCut Print Provider service and select Properties.
4.
Select the Log On tab.
5.
Select the option This account.
6.
Enter the username and password of the newly created service account.
7.
Press OK.
8.
Start the PaperCut Print Provider service.
Now PaperCut NG should have the ability to redirect jobs to the remote print queues it has been provided access to.
14.5. Printer Load Balancing
Printer load balancing means distributing the printing load between two or more printers. While this can be implemented quite effectively by relying on users to pick a printer that is free, thereby distributing the load, the term generally refers to automatically managed load balancing.
Load balancing can be implemented in PaperCut NG as part of Find Me Printing as discussed in the proceeding section, or separately without the need for release stations in a direct printing environment. This section discusses load balancing in general including how it works, as well as how to set it up in a direct printing environment (without release stations).
Load balancing can be implemented at several different layers (none of which are usually mutually exclusive), including:
•
• the operating system layer, known as printer pooling in Windows and Novell environments, and CUPS classes in Mac and Linux.
• within PaperCut NG itself, which will be the topic of this chapter.
PaperCut NG adds value to the load balancing available in clusters and operating systems by ensuring equal load
251
Find Me Printing and Printer Load Balancing between printers. For comparison the primary objective of Windows printer pools is to provide fault tolerance while load balancing is secondary and to a large extent non-existent. Printer pooling on Windows will often simply pick the first available printer in a predefined order. The result is that wear and tear of printers is not even; the first printer in the group will see the heaviest usage and the others may be mostly idle. System administrators often mitigate this by rotating printers periodically. With load balancing in PaperCut NG none of this is necessary: jobs are distributed evenly between queues based on intelligent algorithms taking into account several factors:
• An estimate of the current print load (i.e. pages remaining to print) by inspecting past print history. The estimate is done by using a Pages Per Minute (PPM) for an average printer, however PaperCut NG will improve on the
PPM value by "watching" the printer and learning over time.
• The printer that is likely to get the job done quickest is selected.
• If all printers are currently equal (e.g. all idle), then a random printer is selected. This ensures that over time, load is distributed evenly.
• Printers currently in an error condition are avoided if possible.
• (Optionally) Printers a user has recently printed to.
Find Me Printing also makes use of printer load balancing while giving users the option of where to send their print
job. For more information about Find Me Printing see Section 14.1, “Find Me Printing”.
Implementing load balancing in PaperCut NG is best described by way of example. The following section covers a common scenario for implementing printer load balancing.
14.5.1. Example 1: Simple Load Balancing
14.5.1.1. Scenario
The science department at East Beach High School has a computer lab with a high volume of printing. Students send their print jobs to the nearby print lab, which hosts two high volume laser printers of the same model.
The current print queues are named sci_laser_1 and sci_laser_2
, and are hosted on the print server called science-lab
. Both queues use the same printer driver and settings.
In this scenario there is some natural form of load balancing, as students may select a queue at random or perhaps know which queue is available. Ideally this load balancing would be automatic, and students would not need to concern themselves with which queue to select.
14.5.1.2. Implementation
The first step is to create a new print queue on the print server. This queue will be a virtual queue. Students will print to this virtual queue, and PaperCut NG will handle the load balancing to the target ("real") queues.
A new queue simply called sci_laser is created by the administrator on the science_lab print server using the normal methods for the operating system in use. The queue is created using the same driver that sci_laser_1 and sci_laser_2 use. The queue points to the same physical printer that sci_laser_1 points to. This last point is not strictly necessary but some printer drivers complain if they do not point to a real printer.
The administrator ensures that the print queue has registered itself with PaperCut NG by checking the Printers tab
Removing/Deleting/Ignoring Printers”.
Following creation of the new queue the administrator performs the following:
1.
Navigates to Printers
→
sci_laser
→
Summary in the PaperCut NG administration interface.
2.
Changes the Queue type option to This is a virtual queue (jobs will be forwarded to a different queue).
This reveals the Job Redirection Settings section.
3.
The option Jobs may be forwarded to these queues: determines which queues sci_laser is capable of redirecting to. The queues science-lab/sci_laser_1 and science-lab/sci_laser_2 are selected.
4.
Clicks OK.
252
Find Me Printing and Printer Load Balancing
Now when students print from a lab computer to the virtual sci_laser queue PaperCut NG will intelligently redirect the job to either sci_laser_1 or sci_laser_2
, as illustrated by Figure 14.5, “Simple Load Balancing”.
The administrator may now optionally un-share the sci_laser_1 and sci_laser_2 queues. Doing so ensures that all printing will be via sci_laser and hence load balanced.
Figure 14.5. Simple Load Balancing
14.5.2. Bypassing Load Balancing For Recent Print Jobs
Students printing multiple documents may not want their print jobs distributed between multiple printers - especially when they're at opposite ends of the lab! PaperCut provides the capability to bypass Load Balancing for multiple recent print jobs.
By default, this feature is enabled and is set to a window of 20 seconds - that is - a print job will not be considered for Load Balancing if a user has printed up to 20 seconds ago, and will instead be sent to the previous job's destination.
To configure this setting, navigate to Options
→
Config Editor (Advanced) and modify the config setting print.load-balancer.default.reuse-printer-window-seconds
.
Setting this value to
0 will disable this feature.
14.6. Find Me Printing and Printer Load Balancing FAQ
Q:
Why do redirected jobs have document names starting like
R:123456:
?
A:
This is a security feature. PaperCut NG marks redirected jobs with a special token in the document name to both distinguish between regular jobs and prevent circumvention by users.
Q:
When jobs are redirected are they logged in PaperCut NG against the virtual queue or the target queues?
A:
Jobs are logged against target queues. Virtual queues do not represent real printers and hence have no printing associated with them. This is why the Job Log and Statistics pages are disabled when viewing a virtual queue.
253
Chapter 15. System Management
15.1. Overview
This section discusses various options and features to assist the administrator manage and configure the application. PaperCut NG is designed to work with minimal initial configuration and is self-maintaining once set up.
This section outlines some of the options available to the administrator, including:
• Monitoring the system activity and status of devices and users.
• Configuring the synchronization of users and groups
• Managing backups
• Configuring user notifications
• Exporting/import the data
• Defining security options
• Disabling features in the user web interface
• Display options (like whether to display the currency sign).
15.2. The Dashboard
The Dashboard tab is the first page displayed in the PaperCut NG administration interface. It provides an overview of system activity from the past and in real-time for devices and users. It does this by using a collection of gadgets which are described below.
254
System Management
Figure 15.1. The Dashboard Page
•
What's Next gadget
At the top of the page is the What's Next gadget. It gives a list of hints which are particularly useful for first-time administrators of PaperCut NG. They give descriptions of useful tasks to do in PaperCut NG with links to other administrator interface or help pages. This gadget can be closed for more experienced administrators who no longer need it.
255
System Management
•
System Status gadget
The System Status gadget provides a list of system level statistics. They provide an overview of system information including any warnings or errors that may need attention.
•
Pages Printed gadget
The Pages Printed gadget provides a graph showing the trends in printing volume over the last 30 days. The graph displays after three days of data has been accumulated. When upgrading from a version of PaperCut NG prior to a version supporting the Dashboard feature, the data from the previous version is not displayed.
•
Environmental Impact gadget
The Environmental Impact gadget provides overall environmental impact statistics in terms of trees, carbon and
energy. For more information on Environmental Impact, see Section 15.8, “Environmental Impact”.
•
Printer Status gadget
The Printer Status gadget provides a status overview of the printers managed by PaperCut. The information displayed includes the daily number of pages printed and device alerts such as low toner levels or printer jams.
“System Notifications and Emailing” for additional information.
•
News gadget
The News gadget ensures you're kept up to date with relevant release and development activity regarding
PaperCut.
•
Real-time Activity gadget
The Real-time Activity gadget shows a list of current events in real-time. It shows activities such as print jobs arriving, users logging in, exceeding print quotas, print job status, a variety of errors and much more. This tool is designed to help administrators monitor activity and diagnose problems. The events are updated as the occur and errors are highlighted in red. The events are described in a one line summary, but may be expanded by clicking on the link to the right of the message. The gadget can be expanded by clicking on the Expand item at the bottom of the gadget to display more events. Refreshing the browser page will reverse the expansion. The
Pause item at the bottom of the gadget can be used if the number of events being reported makes viewing difficult.
Tip
The Real-time Activity gadget will alert you if the PaperCut Account Selection has been configured to use the client software, and the client software is not running on the workstation. For example, if
a user has popup confirmation enabled, (see Section 8.4, “The Account Selection Popup”) and the
client software is not running, the job will stay paused and eventually time out. In this situation, as soon as the user prints a document the administrator will be warned in the Real-time Activity gadget that the client software is not running for that user.
15.3. User and Group Synchronization
One of the most important parts of managing PaperCut is to configure the User and Group synchronization options.
PaperCut synchronizes user and group information from a source such as Windows Active Directory (Windows domains). This simplifies the administration of the system by avoiding the need to manage a separate database of users and groups. If a user is added to the domain or is removed from a group then PaperCut will automatically synchronize this information without any intervention from the administrator. For example:
• Jason configures PaperCut to assign an initial credit of $10 to users that are members of the "Students" windows security group.
• At the start of the new school year Jason has just added 100 new students to the Windows Active Directory.
• Jason also adds all the users to the "Students" Windows security group.
• When PaperCut next synchronizes with Active Directory, the 100 new users are added to PaperCut and
256
System Management automatically assigned the $10 initial credit. This is done automatically without any additional work by Jason.
Synchronization settings are configured via the Options
→
User/Group Sync tab.
15.3.1. Sync Source
The settings in the Sync Source section defines where PaperCut imports users and groups from.
Figure 15.2. User/group sync source options
The drop-down list under Primary sync source selects the type of directory server to be used. Options include
Windows Active Directory, LDAP (Apple OpenDirectory, Novell eDirectory, OpenLDAP, etc.), Windows Standard
(local users and groups for workgroup environments), Samba and Unix Standard (local users and groups / NIS /
POSIX).
The Import a subset of users option allows users to be imported from a list of selected groups in the domain, rather than importing all the users in the domain. This can be useful if the domain contains old users or users who will not be printing.
Tip
If you are using Active Directory and have a long list of groups, you can set the config key user-source.ad.group-ou-filter to only display groups under a certain organizational unit. For example, if you set it to "myorganization.local/Import OU/Sub Import OU" then it will only display groups under "Sub Import OU".
If the PaperCut server is a member of an Active Directory domain it is recommended to use this option. The advantages over the "Windows Standard" include:
• Allows using Active Directory organizational units.
• Supports nested groups for simplified user management.
• Allows importing of users from other trusted Active Directory domains.
15.3.2. Sync Options
Tip
By default, PaperCut NG automatically syncs user and group information with your directory each night. However additional full user/group syncs may be performed by scheduling a script to run the appropriate server-command command. More information on using the server-command can be
found in Appendix A, Tools - database, server-command scripting, and APIs (Advanced).
257
System Management
The options listed in the Sync Options section control how the synchronization will take place.
• Update users' full-name, email, department and office when synchronizing - if a user's details in PaperCut do not match those in the synchronization source, they will be updated.
• Import new users and update details overnight - when selected, synchronization will be automated to occur each night at approximately 12:55am. This option will never delete users from PaperCut.
• Delete users that do not exist in the selected source - deletes users from PaperCut if they no longer exist in the selected synchronization source.
This option only applies to manual synchronization (clicking Synchronize Now) and will not delete users when automatically synchronizing overnight. Enabling the option will also only apply once (i.e. the option must be clicked before a manual sync each time when users are to be deleted).
15.3.3. Secondary Sync Source (Advanced)
Enabling a secondary sync source allows PaperCut to merge the results from two independent sources. Examples for where this may be useful include:
• A school with an Active Directory domain for the majority of users and a separate LDAP server that is used and managed by one department.
• An organization with a "new" LDAP server and an old "legacy" LDAP server with separate but unique users that have not been migrated to the new server.
• A university with an Active Directory for the Windows student workstations and an Open Directory for the staff
Mac workstations.
When enabled, PaperCut will query both sources to find users and groups. Usernames are treated as globally unique, so the same username existing in both sources will be treated as the same user (in this case, the details for the user will be merged, with the primary sync source taking priority). If there is an error connecting to or synchronizing against either source then no actions will take place.
15.3.4. Manual Synchronization
By default, PaperCut NG automatically re-syncs the user and group information each night, however the sync process can also be initiated manually. To initiate a manual sync:
1.
Navigate to the Options
→
User/Group sync tab.
2.
Press the Synchronize Now button.
3.
The sync process will start and a status window will open showing the status of the sync process.
258
System Management
Figure 15.3. Progress of a user/group synchronization process
15.3.5. Card/Identity Numbers Sync
Card and ID numbers are used as an alternative to usernames/passwords for authentication at software release stations, or at hardware terminals attached to photocopiers. The card/ID number can also be searched in the user
quick-find in the User List page. See Section 6.7, “User card and ID numbers” for more information.
In PaperCut NG one or two unique card/ID numbers can be associated with each user. These are known as the
Primary and Secondary card/ID number. You may choose to automatically import or generate these card/ID numbers for each user.
Very commonly, card/ID numbers are already assigned by other systems, in which case it is required to import these numbers into PaperCut from Active Directory or LDAP. Unlike other fields like full-name and email address there is no standard field used exclusively for card numbers. For this reason PaperCut allows specifying the field to import the card/ID number from.
To enable importing the primary card/ID number, first enable the Update users' full-name, email, department and
office when synchronizing and then under Primary number select Sync from AD/LDAP field. Then enter the field name to import the card/ID number from and press Apply. For more information on the field names to use, see the sections on Active Directory and LDAP below.
For your convenience, PaperCut also allows you to generate a random card/ID number for either the primary or secondary card/ID number. To auto-generate, select the option Auto-generate random ID (if blank) and specify the length or number of digits. Short numbers are easier to remember and faster to key in, but it is also easier to guess someone else's number. If your number is too short, PaperCut may not be able to generate sufficient numbers to cover all your users.
Important
The card/ID number must uniquely identify a user, so you should ensure that no two users have the same card/ID number. The card/ID numbers you have defined in your user source should be unique. If
PaperCut NG finds a non-unique card/ID number it will not update the user's details, and will display a warning in the synchronization results.
259
System Management
When generating card/ID numbers, you are asked to specify the length or number of digits you require in the generated numbers.
Figure 15.4. Card/ID number Sync Options
15.3.5.1. Importing the Card/ID number from Active Directory
Active Directory has a number of user fields that can be used to store the user's card/ID number. Some of these fields are editable in the user's properties in the Active Directory Users and Computer tool, but others can only be updated with other tools. By default, PaperCut NG will import the primary card/ID number from the user's pager number field (i.e. the pager field). This field was chosen because it is rarely used and is also editable in the
Windows user interface. If this field is not suitable, you can choose any valid Active Directory user field.
The list of standard Active Directory user fields can be found on the Microsoft web site here: http://msdn2.microsoft.com/en-us/library/ms683980.aspx. The field name entered in PaperCut NG must be in the
LDAP display name format. For example, if you want to use the
Employee-Number field, then the field name entered into PaperCut NG should be employeeNumber as shown on the
Employee-Number attribute page here: http://msdn2.microsoft.com/en-us/library/ms675662.aspx
A secondary card number field can be specified by selecting Sync from AD/LDAP field under Secondary number.
Important
If the field name is entered incorrectly, the synchronization will fail. It is therefore important to test your configuration changes. To test the changes, press the Test Settings button. If the card number is retrieved correctly, then they will be listed as the 4th user field in the test output.
15.3.5.2. Importing the Card/Identity number from LDAP
260
System Management
LDAP provides a very flexible way to store a variety of user related information. The fields available depend on
LDAP server being used and how that is configured. Many LDAP servers also allow administrators to create custom fields to store additional custom user information. It is recommended you consult your LDAP server's documentation or talk to your LDAP administrator to understand which LDAP field your stores the user card/ID number.
By default, PaperCut NG uses the employeeNumber field to retrieve the primary card number. This is a standard
LDAP field, but if this is not suitable, you can choose any valid LDAP user field.
A secondary card number field can be specified by selecting Sync from AD/LDAP field under Secondary number.
If using a secondary sync source, then select Sync from AD/LDAP field under Secondary number to specify the field. If defined, then the same regular expression that is applied to the first card number will be applied to the second card as well.
Important
It is important to test the card numbers are being retrieved correctly. To test the changes, press the
Test Settings button. If the card number is retrieved correctly, then they will be listed as the 4th user field in the test output.
15.3.5.3. Using a regular expression to extract the card/id number from an LDAP/AD field
The vast majority of sites store the full card number in a single field in AD/LDAP. In this situation there is no need to use a regular expression (regex) to extract the card number. A regular expression is only required under some unusual specific circumstances, including:
1.
The field contains more then just the card number. For example, if the field contained a card number and student number separated by a comma (e.g. 12345678,0003456).
2.
The multi-valued LDAP/AD field contains multiple values and only one representing the card number. e.g. Some third party authentication management systems store external IDs (like card numbers) in a single multi-valued
LDAP field. NOTE: For multi-value fields, PaperCut will import all the field values separated by TABs by default.
The regex may be used to extract the required portion of the field.
To use a regular expression to extract the card/id number, enable the Apply regular expression to extract card
number option on the User/Group Sync page. Then enter the regular expression used to extract the card number.
The regular expression must contain a capture group (represented by parentheses), that represents the part of the field that the card number is extracted from.
The simplest way to create a regular expression is to start from one of the examples that follow.
Regular Expression
([\d]+)
([\d]{5})
=([\d]+)
([\d]+)::abc
Description
Extracts the first sequence of digits.
e.g.
if the field contains
12345678,005678 then
12345678 is extracted.
Extracts the first sequence of 5 digits. e.g. if the field contains
12345678 then
12345 is extracted.
Extracts the sequence of digits after the = character. e.g. if the field contains
12345678=56789" then
56789 is extracted.
Extracts the sequence of digits preceding the text
::abc
. This is a common notation when storing identities in a multi-valued field in LDAP. The ::abc notation is used to indicate the different identity types. In this example, if the field contains
1234::xyz 5678:qrs 9876::abc then
9876 is extracted.
Table 15.1. Example regular expressions to extract card numbers
Regular expressions are an advanced topic and can be tricky to get just right. For more information on regular expressions and a test tool see http://www.fileformat.info/tool/regex.htm. If you need assistance, please contact
261
System Management support.
15.3.6. On Demand User Creation
The On Demand User Creation setting defines if and when PaperCut NG will create new users. The settings
via the user client tool or log into the user web tools. This makes administration much easier, as there is no need for additional administration when new users come along; they can use PaperCut straight away.
In some situations it may be preferable to change the way new users are treated. For example when just one department is being tracked, but there are other departments using the same printers, it may be preferable to allow the other departments' users to print, but not to track them using PaperCut NG.
There are three options available for the setting When the user does not exist:
1.
create the user on demand (default) - users are created when they interact with PaperCut NG for the first time.
E.g. when they print for the first time.
2.
do not create the user and allow usage - users interacting with PaperCut NG who do not already exist will not be created, but their usage will be allowed. The usage will not be logged.
3.
do not create the user and deny usage - users interacting with PaperCut NG who do not already exist will not be created, and their usage will be denied. The usage will not be logged.
Figure 15.5. On demand user creation options
To change the behavior, select the desired option and press Apply.
15.3.7. Using Active Directory for user synchronization
PaperCut NG's Active Directory integration is performed at a native level and supports advanced features such as nested groups and OU's. Some additional options provided with the Active Directory interface include:
• Import disabled users - If set, all users, including disabled accounts will be imported from the domain. In an education environment it is recommended to leave this option on as often student accounts are disabled for disciplinary actions, and removing the account from PaperCut NG is not appropriate.
• Enable multi-domain support - This is an advanced option and is appropriate for larger sites running multiple trusted domains. For example, in an education environment it is common to have separate domains for students and staff/teachers with a one-way trust relationship. This option can bring in groups, OU's and users from both domains.
The list of domains is semicolon separated (
;
). This list should contain the name of the domains in DNS dot notation, and should include the name of the current domain if importing from this domain is desired.
Trust domain relationships are a complex area and administrators are advised to use the Test button to verify that the settings result in the desired behavior. The total number of user accounts is a good measure.
• Import other email addresses - Advanced option to allow importing a user's other (secondary) email addresses from a custom field. The field is configured using user-source.ad.other-emails-field
.
15.3.8. Using LDAP for user synchronization
LDAP (Lightweight Directory Access Protocol) directories usually store information about user and groups in an organization. One of the most common uses of LDAP is to provide single sign-on on a network that comprises
262
System Management multiple platforms and applications. When a network consists of only Windows computers, then an Active Directory domain can be used. But when there is a mix of Windows, Apple and Linux machines then LDAP can provided the single source of user, group and authentication information. (It is worth noting that both Active Directory and Novell eDirectory implement the LDAP protocol).
PaperCut NG can use an LDAP directory for user authentication and as a source of user and group information.
LDAP can either be enabled at installation time, or by changing the user source option in Options
→
User/Group
sync. When enabling LDAP, a number of configuration settings must be specified to allow the application to connect to the LDAP server. Please ask your LDAP administrator what values to use for the various options:
• LDAP Server Type - Determines which LDAP fields are used to get user and group information.
• LDAP Host address - The hostname or IP address of the LDAP server.
• Use SSL - Indicates if an encrypted SSL connection should be used to connect to the LDAP server. The LDAP server requires SSL support to be enabled and should accept connections on the standard LDAPS port 636.
• Base DN - This is the Base DN of the LDAP server. This is the equivalent of the "suffix" config setting of the
OpenLDAP server. For example, if the domain hosted by the LDAP server is "domain.com" then the Base DN might be
DC=domain,DC=com
. The format of the Base DN can differ significantly depending on configuration.
Some older Novell eDirectory installations may require a blank Base DN to operate. Some examples:
DC=myschool,DC=edu,DC=au
DC=myorganization,DC=com
OU=OrgUnit,DC=domain,DC=com
DC=local
• Admin DN - The DN of the user who has permission to connect to and query the LDAP server. This is typically an administrative user, although it can be a user that only has read-only access to the LDAP server. An example of the DN of the Administrator user on a Windows AD domain "domain.com", would be
CN=Administrator,CN=Users,DC=domain,DC=com
. The exact format of the DN depends on the LDAP server. Some examples:
• Windows Active Directory:
CN=Administrator,CN=Users,DC=domain,DC=com
• Windows Active Directory (in organizational unit):
CN=administrator,OU=OrgUnit,DC=domain,DC=com
• Mac Open Directory: uid=diradmin,CN=users,DC=domain,DC=com
• Unix Open LDAP: uid=root,DC=domain,DC=com
, or uid=ldapadmin,DC=domain,DC=com
• Novell eDirectory:
CN=root,DC=domain,DC=com
, or
CN=ldapadmin,OU=users,DC=domain,DC=com
.
The Admin DN and password is optional if your LDAP server allows anonymous binds for querying.
• Admin password - The password for the above user.
Tip
Some LDAP servers are configured to allow 'anonymous' LDAP query access. In these situations, the
Admin DN and Admin password may be left blank.
PaperCut NG supports the following server types:
• Novell eDirectory
• Microsoft Active Directory
• Unix / Open Directory
However, it is easy to support other server types by adjusting the LDAP fields PaperCut NG searches. This is
discussed in Appendix C, Advanced LDAP Configuration.
263
System Management
Tip
Advanced features such as Nested Groups and OU are supported by the Windows Active Directory
sync option. See Section 15.3.7, “Using Active Directory for user synchronization”
15.4. Assigning Administrator Level Access
PaperCut NG sets up one administrator account called “admin”. This is the master administrator account, with access to all features, whose password is assigned during the configuration wizard. In large organizations it is likely that administrator level access will need to be granted to more than one person. One solution is to give all persons the master password; however the recommended approach is to assign administrator rights to these individual's network user accounts. The advantages of this approach are:
• They can access the administration pages using their own username and password (they don't have to remember another password!).
• Different levels of administrator access can be assigned to the user. PaperCut NG includes an advanced Access
Control List (ACL) allowing different administrators access to different functions and areas of the application.
• Most activity is audited so changes can be sourced to an individual.
Administrator access may be assigned at the group or user level. Assigning admin access to a group is convenient for giving the same permissions to multiple users. Assigning admin access to a user is useful when specific permissions are required. See the following sections for more detail.
Tip
Administrative users should login via http://servername:9191/admin rather than http://servername:9191/
, http://servername:9191/app or http://servername:9191/user so that they are directed to the correct interface.
Important
PaperCut NG allows different levels of administrator access to be defined via access control list. The access list is presented as a series of checkboxes enabling or disabling access to selected features or application areas.
For security reasons it is advisable to:
• Grant the user's own accounts administrator level rights rather than have them use the general built-in admin account.
• Grant the administrator the minimum level rights need for them to perform their job.
• ACL configuration can be complex. Always test that the ACL rights assigned work as expected by asking the administrator to log in and verify that they can access the required program functions.
15.4.1. Assigning Administrator Access to a Group
Assigning administrator access to a group is useful when many users all require access to the same functionality.
For example, the
Management group might be assigned access to reporting functionality only.
Groups in PaperCut NG are mirrored from the domain / directory server. Before a group can be used, it must be
synchronizes users' group membership with the domain / directory server overnight. If a user has been added to a
264
System Management group in the domain / directory and requires group level admin access on the same day, a manual synchronization
should be run. See Section 15.3, “User and Group Synchronization” for more information.
Example: assigning the
Management group access to reporting features:
1.
Log in to the system as the built in admin user.
2.
Ensure that the
Management
group has been imported into PaperCut NG (see Section 6.1, “Groups in
PaperCut NG” for more information).
3.
Navigate to the Options
→
Admin Rights page.
4.
In the field titled Assign administrator access to this group:, select the
Management group from the list, and click Add Group.
Figure 15.6. The list of users and groups granted admin access
5.
By default
Management will have access to all features. To change this, click on the edit link to the right of
Management
's entry or the name of the group itself.
6.
Deselect all access rights for
Management except Access reports section. When finished, click Apply to save the changes.
7.
Test by logging into the administrator interface as a user in the
Management group, and checking that access is allowed just to the Reports section.
Tip
The scheduled reports feature can automatically deliver selected reports via email to interested
parties. See Section 9.4, “Scheduling and Emailing Reports” for more information.
265
System Management
Figure 15.7. The list of users and groups granted admin access
15.4.2. Assigning Administrator Access to a User
Assigning access to an individual user is suitable when the access rights are specific to that user. For example, the junior system administrator mary might be assigned access to all functionality except the ability to grant administrator rights to other users.
Assigning the user with login name mary all admin rights except the ability to grant admin rights to other users:
1.
Log in to the system as the built in admin user.
2.
Navigate to the Options
→
Admin Rights page.
3.
Enter mary into the field titled Assign administrator access to this user: and click Add User.
4.
By default mary will have access to all features. To change this, click on the edit link to the right of mary
's entry or the name of the user itself.
5.
Deselect the access right Access admin rights settings for mary
.
6.
Click on the Apply button to save the change.
7.
Verify that Mary can now log into the administrator interface, but is unable to access the Admin Rights section.
266
System Management
Figure 15.8. The list of users and groups granted admin access
15.5. System Backups
As with any application, it is important to ensure that backups are performed regularly. PaperCut NG includes a built-in database export that saves the state of the database to a file. This functionality is designed to complement
(not replace) a good system-wide backup process. The export is stored in the industry standard XML format and compressed using the standard ZIP format to reduce disk-space on the server and your backup medium. The use of these open standards ensures that your data is always available and accessible.
print servers and site servers do not require a database backup.
PaperCut NG makes the process of managing export backups simple by automatically performing a weekly export.
Export backup files are placed in the following directory:
[app-path]\server\data\backups
The weekly exports are performed at 20 minutes past midnight on Sunday morning (or as otherwise defined by the schedule.weekly
config key. Please see Section 15.10, “Using the Config Editor” to find out how to change
config keys.)
Tip
In accordance with backup best practice, the above directory should be regularly backed-up to offline media (e.g. tape, CD or remote server). This will allow the data to be restored in the case the server hard-drive is corrupted. An example backup script called copy-backups-to-remote-server.bat
found at
[app-path]/server/examples/scripting/batch/ may help administrators automate the process of maintaining an off-disk copy.
On larger networks, it may be desirable to perform export backups more frequently than the in-built once a week period. The server-command tool may be used to execute the export task at other times.
Simply write a script (e.g.
batch file) to execute server-command perform-online-backup
. Schedule the script to run at the desired intervals. More information on server-command
is available in Section A.1, “Server Commands (server-command)”.
15.5.1. Performing an Online Backup
In addition to the automated weekly exports, it is also possible to manually initiate a database export. This might be useful to back up the system database before performing an upgrade. To perform a manual export:
1.
Navigate to the Options
→
Backups page.
2.
Press the Export Now button.
3.
A window will open showing the export progress and the location where the export file is saved.
15.5.2. Restoring an Export Backup
267
System Management
There are a number of situations when it might be necessary to restore a database, including:
• Hardware or system failure requires you to rebuild the server and reinstall PaperCut NG.
• A new print server was purchased and PaperCut NG is being moved to a new server.
•
To import data into an external RDBMS (See Chapter 22, Deployment on an External Database (RDBMS)).
To restore from an export file:
1.
Locate a previous export file.
2.
database cannot be in-use when performing the restore, so the application server needs to be stopped first.
3.
Open a command prompt. On Windows 7 and Server 2008 systems, this may need to be specifically elevated to run with administrator privileges, even if you are already logged in with an administrator account. Change to the server binaries directory.
On a Windows system the directory location is
[app-path]\server\bin\win\
.
4.
Re-initialize the database back to an empty state by typing the following: db-tools init-db -f
5.
Run the import process by executing the following: db-tools import-db -f "C:\path\to\backup\backup-file-name.zip"
(Or,
./db-tools
on some systems. See Section A.2, “Database Tool (db-tools)” for more information on using
db-tools
) NOTE: On Mac/Linux ensure proper permissions for access to the file, e.g.
chown papercut:admin \path\to\backup\backup-file-name.zip
6.
The import will ask whether the existing database data should be deleted before proceeding.
7.
15.5.3. Performing Offline Backups
Performing an online backup (as discussed above) is a simple and convenient process, but it is sometimes necessary to perform a backup when the application server is not running. For example:
• To integrate into your existing backup procedures, it might be necessary to write a script or batch file to perform a backup at a known point in time.
• When it is necessary to guarantee that the backup captures all the data. Performing an online export while the system is in use can modify data after the export is complete.
To perform an offline backup:
1.
is captured, the application server must be stopped to perform an offline backup.
2.
Open a command prompt.
On a Windows system change to the following directory:
[app-path]\server\bin\win\
3.
Run the database export process by executing:
268
System Management db-tools export-db
(This will create an export file in the system backups directory and the filename named with a timestamp).
The export command has additional options that allows you to specify a different directory or filename. See
Section A.2.1, “export-db Command” for more details.
15.5.4. Export File Retention
Export files in
[app-path]\server\data\backups will be retained for 30 days and then deleted. This number of days can be changed on the Options
→
Backups
page under "Keep exports for ... days". This period will automatically be extended should exports not be performed on a regular basis, i.e. when automatic exports have been temporarily disabled for a time or when skipping scheduled exports due to a system outage. Older export files will not be deleted unless a number of new exports have been performed. At the very least the latest export file will always be retained regardless of its age.
15.5.5. Backup Print Archive files
By default the Print Archive is stored in
[app-path]\server\data\archive and is not included in the database exports detailed above. It is recommended that you consider backing up part or all of the Print Archive with your existing backup processes. As PaperCut is resilient to partial restoration of the Print
Archive you may want to backup only a month or two worth of archives. There is a
README.txt
in the archive directory that explains more about partial backups and the directory structure layout.
15.6. System Notifications and Emailing
This section describes system notifications and how they can be configured to assist your users and administrators.
PaperCut NG includes built-in notifications to alert users and administrators of a important pieces of information.
Examples of these notifications include:
• Alerting a user when their account balance drops below a given balance.
• Displaying a message explaining why a print job was denied (e.g. not enough credit; the printer is disabled; the print job contains too many pages).
• Alerting administrators or key IT support staff to problems such as printer jams, or application errors.
The message that is delivered to the user can be customized to suit your organization. For example, if the user is denied printing for some reason, you may wish to direct the user to the intranet page that discusses printing policies and guidelines.
Important
Notifications are important to your users because they let them know why their print jobs were denied.
If notifications are not enabled, users print jobs might be deleted without them knowing and they will not understand what happened. They might then contact the Administrator or Help Desk for assistance. If they received a notification, then this situation is avoided.
System notifications can be delivered to the user in a number of ways, and the administrator can decide the preferred option. The delivery options available include:
• Winpopup (or "net send") - this is useful in a Windows network but workstations running other operating systems
269
System Management may not receive these messages.
• User Client - messages are sent to users running the PaperCut NG User Client tool. This option is guaranteed to work in all environments where the user runs the user client.
• Email - messages are delivered by email, to the email address defined in the system. This is a good alternative for "low balance warning" messages but is not recommended for real-time messages like when printing is denied.
15.6.1. Configuring Notifications
PaperCut NG provides flexible options for configuring the various notifications. The administrator can choose to:
• Enable/disable each of the notification types.
• Change the notification message to suit your organization.
• Choose the delivery method for each notification type.
Notification text can be modified to suit your organization's requirements. The notification text is a template that can include some special fields that are replaced by the system when the message is sent. They can be used to provide more detailed information to the user. These fields are surrounded by percent characters (
%
).
The default notification text in the application shows a variety of examples using these fields. For a list of the fields available in each type of notification, see the following sections covering each notification type in more detail.
15.6.1.1. Printing Notifications
To change printing notification options, navigate to Printers
→
Notification Options.
Field
%user%
%full_name%
%date%
%balance%
%cost%
%printer%
%printer-server%
%printer-queue%
%document%
%pages%
%copies%
%paper-size%
%id_num%
Table 15.2. Fields available in printing notifications
Description
The username of the user receiving the message.
The full name of the user receiving the message.
The date/time that the message was sent.
The user's current balance.
The cost of the print job.
The full printer name (including the server name) the job was printed to. e.g.
server-name\printer-name
The server name of the printer the job was printed to.
The queue name of the printer the job was printed to (i.e. without the server name).
The name of the document printed.
The total number of pages in the print job.
The number of copies of the document printed.
The size of the paper used to print the document.
The primary Card/Identity Number of the user receiving the message.
15.6.1.1.1. Notify the user before their print times out and is deleted from a hold/release queue
270
System Management
Figure 15.9. Options for a notification sent before a held job gets deleted
This notification option contains the following additional replacements.
Field Description
%minutes% Minutes from now until the job is timed out and deleted. Minimum of
2 minutes.
Table 15.3. Fields only available in notification sent before deleting the held job
For more information about hold/release queue timeout see Section 13.3.3.4, “Job timeout”.
15.6.1.2. Low Balance Notification
To change low balance notification options, navigate to Options
→
Notifications, and scroll down to the "Low
Balance Notification" section.
Figure 15.10. Options for a single system notification
Using the notification options (shown above), the notification can be enabled, the notification text can be changed, and the delivery type can be modified.
Field
%balance%
Table 15.4. Fields available in low balance notifications
Description
The user's current balance.
Important
This low balance notification is only sent to users who are restricted.
15.6.1.3. Card/ID Number Notification
To change card/ID number notification options, navigate to Options
→
Notifications, and scroll down to the
"Card/ID Number Notification" section.
271
System Management
Figure 15.11. Card/Id number Notification Option
Enable the option by selecting Notify users when their card/ID number is auto-generated. This notification option emails the user with their updated ID number. The notification subject and message can be changed to suit your environment.
Field
%id_number%
Table 15.5. Fields available Card/ID Number Notification
Description
The user's Card/ID number
Important
This notification sends an email to user's primary email address.
15.6.1.4. Configuring Email Notifications
Before sending notifications via email, the system needs to know the SMTP server to deliver emails to. The SMTP server can be internal or external to your organization however it must allow forwarding of emails to your users. The
SMTP server will typically be the same server that users set in their email application to send emails.
To set the SMTP server:
1.
Navigate to Options
→
Notifications.
2.
Find the Email Options section.
3.
Enter the SMTP server in the field provided.
4.
It is also recommended that the subject and from address are changed to be applicable for your environment.
5.
Press the Apply button.
The following advanced SMTP configuration settings are also available in the configuration editor (see
Section 15.10, “Using the Config Editor”).
Name
notify.smtp.enable-tls notify.smtp.port
notify.smtp.username
notify.smtp.password
notify.smtp.debug
Description
Set to
Y to enable STARTTLS, or
N to disable it. STARTTLS is for connecting to an SMTP server port using a plain (non-encrypted) connection, then elevating to an encrypted connection on the same port.
The port to connect to on the SMTP server. Common ports include 25 or 587 for
SMTP, and 465 for SMTPS.
Username for SMTP authentication. Commonly an email address.
Password for SMTP authentication.
Produces extra SMTP related logging for troubleshooting.
Table 15.6. Advanced email notification (SMTP) settings
272
System Management
Important
Anti-virus software running on the PaperCut server can block/disallow SMTP connections because it attempts to block spam sent by viruses and trojans. Ensure that any anti-virus software is configured to allow PaperCut to make SMTP connections (e.g. add an exception or disable the SMTP blocking).
When anti-virus is blocking email delivery PaperCut NG will log errors like:
Mail server connection failed. Software caused connection abort.
. These errors are displayed in the application log or on-screen when performing email notification tests.
If there are other SMTP connection problems, you should check that your firewall allows SMTP connections, and that your SMTP server is configured to accept connections from the PaperCut server.
15.6.1.4.1. Email Notification Configuration Examples
Name
SMTP server
notify.smtp.enable-tls notify.smtp.port
notify.smtp.username
Value
Your internal SMTP server hostname.
N
25
Blank.
notify.smtp.password
Blank.
Table 15.7. SMTP configuration example: internal SMTP server (no authentication)
Name
SMTP server
notify.smtp.enable-tls notify.smtp.port
notify.smtp.username
Value
Your internal SMTP server hostname.
N
25
A valid username for your internal SMTP server.
notify.smtp.password
The password for notify.smtp.username
.
Table 15.8. SMTP configuration example: internal SMTP server with authentication
Name
SMTP server
notify.smtp.enable-tls notify.smtp.port
notify.smtp.username
notify.smtp.password
Table 15.9. SMTP configuration example: Gmail
Value
smtp.gmail.com
(or your Google Apps SMTP host)
Y
587
A valid Gmail (or Google Apps) email address.
The password for notify.smtp.username
.
Name
SMTP server
notify.smtp.enable-tls notify.smtp.port
notify.smtp.username
notify.smtp.password
Value
smtp.gmail.com
(or your Google Apps SMTP host)
N
465
A valid Gmail (or Google Apps) email address.
The password for notify.smtp.username
.
273
System Management
Name
Table 15.10. SMTP configuration example: Gmail (alternate config)
Value
Name
SMTP server
notify.smtp.enable-tls notify.smtp.port
notify.smtp.username
notify.smtp.password
Table 15.11. SMTP configuration example: Exchange
Value
Your internal Exchange server hostname
Y
587
Variation of e.g. domain\username, username@domain, username
The password for notify.smtp.username
.
15.6.1.5. Configuring Email Addresses
To send notification messages to users via email, an email address needs to be defined for the user. User email addresses can be entered in the User Details screen. However, if all email addresses match the pattern
[username]@yourdomain.com
, then the email addresses can be defined globally using the global email suffix.
An example of how this works is as follows:
1.
An email notification needs to be sent to user brian
.
2.
No email address has been defined in Brian's user details, but a global email suffix of
@myschool.com
is defined in the Email Options section.
3.
To generate Brian's email address, the username ( brian
) and suffix (
@myschool.com
) are combined to form the email address [email protected]
.
To define the global email suffix:
1.
Navigate to Options
→
Notifications.
2.
Find the Email Options section.
3.
Enable the Use email suffix to build user email addresses option.
4.
Enter the Email Address Suffix.
5.
Press the Apply button.
To confirm that the email suffix is working as expected:
1.
Navigate to the Users section.
2.
Select a user from the list.
3.
The Use global email suffix option should be enabled, and the email field should contain the address constructed from the username and suffix.
15.6.2. System Notifications (for Administrators)
Hardware and software errors will happen on all networks from time to time. The key to minimizing disruption is to act on errors fast. PaperCut NG's error notifications feature will help keep response times down by proactively notifying key staff of error events. Take for example a paper jam. It might take several hours before an annoyed user reports the problem as most users may simply opt to use another printer. Automated email notifications take the
"human factor" out of the loop.
PaperCut NG's can also notify the administrator when printer toner levels are low (for supported printers). This allows for toner to be purchased and replaced pro-actively to minimise downtime of the printer fleet.
274
System Management
To enable and configure error notification options, navigate to Options
→
Notifications, and scroll down to the
"System Notifications" section. The following notification types are available:
• Printer errors: Notify when a printer enters an error state for a selected period of time.
• Low Toner warnings: Notify when a printer runs low on toner (for supported printers).
• Application errors: Notify if a software or application error is detected. This option will allow administrators to proactively act on errors raised in the App. Log section.
• License errors: Notify on important license events such as exceeding the licensed user limit.
All error notifications can be enabled using the checkbox, and a list of recipient email addresses can be specified.
Multiple email addresses can be entered by separating them with a comma, e.g.
[email protected],[email protected]
.
Tip
Consider SMS alerts: Error notifications are often important and require urgent attention. Many organizations use an email-to-SMS gateway service to ensure technical staff can receive urgent messages from anywhere in the building via the text message service on their cell/mobile phones.
15.6.2.1. Printer error notifications
Printer error notifications can be used to give advance warning when printers go into an error state.
PaperCut NG detects a printer error if either the print queue or the job at the top of the print queue are in an error state. This is equivalent to clicking on the print queue from the operating system and checking its status.
Some errors that might be seen on print queues or jobs include: paper jam
, out of paper
, out of toner
, out of memory
, device is offline
, device door is open
, or a generic error. The actual errors reported depend on the printer driver and which ones it supports.
The message can include information such as the name and location of the printer, the reason for the error, and how many jobs are pending in the queue (an indication of the impact).
Figure 15.12. Printer error notification settings
The setting
Time a printer has been in error before sending notification can be used to decide how soon a notification should be sent after a printer goes into error. For example if there is a paper jam the user might be able to fix it themselves, and raising an immediate notification is unnecessary. The suggested default is 10 minutes as problems lasting longer than this are probably more serious and will need technical intervention.
The following special fields can be used in printer error event notifications:
Field
%time%
Description
The time the printer error was first reported.
275
System Management
Field
%printer%
%printer-server%
%printer-queue%
%location%
%error%
%num_jobs%
Description
The name of the errored printer.
The server name of the errored printer.
The queue name of the errored printer (i.e. without the server name).
The location of the errored printer.
The error message detail. E.g.
Paper jam
.
The number of print jobs currently in the queue. This information can be used as a guide to judge the severity of the error. For example, if a printer goes into error while there are 30 jobs in the queue, there are probably quite a few people waiting.
Table 15.12. Fields available in printer error notifications
15.6.2.2. Printer low toner notifications
Printer low toner notifications are used give advance warning when printers are running low on toner. This allows administrators to ensure that printers never run out of toner and improves printer uptime.
The printer toner notifications are available for supported network printers. The toner information is retrieved from the printer using SNMP over the network. To use low toner notifications, ensure that SNMP is enabled on your printer and that your network/firewalls/switches allows the PaperCut NG server to send SNMP requests to the
printers. For more information see Section 7.15, “Toner Levels (for supported printers)”.
The notification message lists each printer with it's location that is low in toner, and includes toner levels for all the printer's toner cartidges. The notification message is sent each weekday at 10:30am by default.
Tip
If you would prefer to only be notified when new printers run low in toner, set the notify.toner-level.only-send-if-new to
Y
in the Config Editor (see Section 15.10, “Using the Config Editor”).
Figure 15.13. Low toner notification settings
15.6.2.3. Error level event notifications
Error level event notifications help to draw the attention of the administrator to any errors that might occur. This could involve events such as problems contacting a directory server, software crashes, or processing problems.
276
System Management
Figure 15.14. Error level event notification settings
The following special fields can be used in error level event notifications:
Field
%error%
Table 15.13. Fields available in error level event notifications
Description
The error message detail.
15.6.2.4. Pending refund request notifications
Pending refund requests notifications help to draw attention of the administrator to pending refund requests. By default, daily notification messages are sent at 7 a.m.
Figure 15.15. Pending refund request notification settings
The following special fields can be used in pending refund request notifications:
Field
%num_requests%
Table 15.14. Fields available in pending refund request notifications
Description
The number of pending refund requests.
15.6.3. Testing Notification Methods
Once the system notifications are configured, it is useful to test that messages can be delivered. PaperCut NG provides a function to send test messages to users. This allows you to verify that notifications are working without having to try to produce notifications artificially. To send a test notification:
1.
Navigate to the Options
→
Notifications.
2.
Scroll to the bottom of the page to the Test Notifications section.
3.
Enter the username of the user to send the message to.
277
System Management
4.
Select the delivery method to use.
5.
Enter the notification message to send.
6.
Press the Send Test Notification button
7.
Verify that the notification was received.
15.7. System Security Options
The default installation of PaperCut NG is configured to be secure by default. After initial installation only the admin user defined during the setup process is permitted to administer the system. To allow additional users to administer
PaperCut NG follow the instructions defined in Section 4.7, “Assigning Administrator Level Access”.
15.7.1. Application Server Connections
By default PaperCut NG runs an internal web server on port 9191. All communication with the server uses HTTP to this port and includes connections by:
• administrators to connect to the administration interface
• users to connect to the end-user interface
• the user client to communicate with the server to get the user balance and receive notifications; and
•
It is therefore important that all of the above clients can access this port on the server from across the entire network. If your organization uses firewalls between departments or campuses then it will be necessary to allow inbound HTTP connections on port 9191 to the PaperCut NG application server.
The application server port can be changed from 9191 to any other value.
Important
If the application server port is changed, the port number also must be changed in the applications that connect to the server. i.e, the print provider and the user client.
To change the application server port:
1.
On the server, navigate to the
[app-path]\server\ directory.
2.
Open the file server.properties
.
3.
Change the server.port
to setting to the desired port.
4.
Change the server port in all providers installed on your network. The server port is set in the print-provider.conf
file in the provider directory.
5.
Change the server port in the user client config file:
[app-path]\client\config.properties
.
Important
If the client is installed locally on workstations, then the config file will need to be changed on each workstation.
On Linux/Unix systems, the server runs under the privilege of a non-root account. Some systems may prevent non-root users from binding to ports lower than 1024. An alternate option is to use kernel level TCP port redirection (e.g.
iptables
).
6.
Restart the application server. (See Section A.6, “Stopping and Starting the Application Server”).
278
System Management
15.7.2. Provider Connection Security
data to the server to process. One example of a provider is the print provider which monitors printing and sends the printer activity to the central server.
PaperCut NG supports an unlimited number of information providers and they can be located on anywhere on the network. By default PaperCut NG allows these providers to connect from any machine on the network. This can be restricted to a reduced set of machines by specifying a list of IP addresses or subnets that are allowed to submit information to the application server.
To define the list of addresses that providers can connect from:
1.
Navigate to Options
→
Advanced.
2.
Scroll down to the Security section.
3.
Enter the list of IP addresses or subnet masks to allow. The list of addresses is comma separated. The format of the subnet is
X.X.X.X/Y.Y.Y.Y
(where X represents the address and Y the subnet mask).
4.
Press Apply.
5.
It is then recommended to test all providers to ensure that they can still submit information to the application server. To test the print provider, perform a test print job to the server that the provider is running on.
15.7.3. Release Station Connection Security
affect print release at an embedded device or from a web browser.
1.
Navigate to Options and select Config Editor (Advanced).
2.
Search for the config key: auth.release-station.allowed-addresses
3.
Enter the list of IP addresses or subnet masks to allow. The list of addresses is comma separated. The format of the subnet is
X.X.X.X/Y.Y.Y.Y
(where X represents the address and Y the subnet mask).
4.
Click
Update
.
5.
It is then recommended to test all standard release stations to ensure that they can still successfully start-up and connect to the Application Server.
15.7.4. Web Session Inactivity Timeout
For security reasons all the web sessions log out (timeout) after periods of inactivity. Clicking a link or refreshing a page will reset the inactivity timer. Closing the browser window/tab will also end the session (i.e. the session cookies are not persistent). The default timeout periods for different login types are described in the table below:
Login Type
Admin web interface
Web based release station
Web Cashier
User web interface
Table 15.15. Default Web Session Inactivity Timeout Values
Default value
1440 minutes (24 hours)
1440 minutes (24 hours)
1440 minutes (24 hours)
60 minutes (1 hour)
These timeout values (a period given in minutes) are configurable via the config keys below. A value of
0 indicates that the session will never time out. The special value DEFAULT indicates that the PaperCut defaults (in the above
279
System Management table) are used (the PaperCut defaults may change in future versions).
Config name
web-login.admin.session-timeout-mins web-login.web-cashier.session-timeout-mins web-login.release.session-timeout-mins web-login.user.session-timeout-mins
Table 15.16. Timeout Web Session Config Keys
Description
Inactivity timeout for the admin web interface.
Inactivity timeout for Web Cashier.
Inactivity timeout for the web based release station.
Inactivity timeout for the user web interface.
Please see Section 15.10, “Using the Config Editor” for information about changing config keys.
Changing the inactivity timeout values will take effect the next time users log in. Note that some pages periodically refresh the page (or data on the page), such as the dashboard and the web based release station. A session will not time out if a browser is left on these pages, as it will be considered active.
15.8. Environmental Impact
One of the primary aims of PaperCut NG is to reduce printing levels by changing a user's printing behavior.
Implementing monitoring, quotas and charging are a good way of drawing a user's attention to their habits. The topic of the environment, global warming, and waste management is currently an area of debate and interest to many.
Highlighting the environmental aspects of their activities is another good way of modifying a user's behavior.
Figure 15.16. Draw a user's attention to their environmental impact
details pages in the admin interface.
The meaning of the reported values and how they are calculated are detailed below:
Field
Trees
Carbon
Energy
Description
This value corresponds to percentage of a tree that has gone into making the paper. The value assumes the user is printing on standard A4 or Letter sheets and 80,500 sheets make up a tree a
This value is set by the config key: environment.sheets-per-tree
This value corresponds to greenhouse gases released in the production of the paper (CO
2 equivalent). The value assumes that the user is printing on standard
A4 or Letter sheets and one sheet equals 4.5g CO
2 b
.
The default value takes in account CO
2 produced as a byproduct of the paper production only. It does not take into account the power consumed by the printer or power associated with the ink / toner use and production. Finding referenced figures on these values is difficult, and one could argue that the printer power consumption is not a function of the user's usage as the printer would be there consuming power even if they choose not to use the device.
This value is set by the config key: environment.co2-grams-per-sheet
This value represents the manufacturing energy used to produce the paper. The energy value is represented by relating it to the equivalent energy consumed by a standard light bulb. This provides users with a real world understanding of the value. This value assumes the user is printing a standard A4 or Letter sheet and that the manufacturing cost per sheet is 17Wh c
. This is an appropriate amount for virgin office paper. 12Wh is more appropriate for 100% recycled paper d
.
280
System Management
Field Description
This value is set by the config key: environment.watt-hours-per-sheet
Table 15.17. Environmental Impact Reporting
a
A single tree can produce about 80,500 sheets of paper according to How Much Information? 2003 filed by University of California at Berkeley, http://www2.sims.berkeley.edu/research/projects/how-much-info-2003/print.htm, retrieved June 2007.
b
Office paper produces 0.27 metric tons of carbon equivalent (MTCE) per ton of paper, according to the USA EPA report Greenhouse Gas
Emissions From Management of Selected Materials in Municipal Solid
Waste, 1998, p26, http://www.epa.gov/climatechange/wycd/waste/downloads/fullreport.pdf, retrieved June 2007. This amount is equal to 1.0 metric tons of CO
2 carbon equivalents per metric ton of paper. The Environmental Energy Technologies Division of the U.S. Department of Energy indicate that there are about 220,000 paper sheets in a ton: http://eetd.lbl.gov/paper/ideas/html/copyfactsM.htm, retrieved June 2007.
c
According to the Environmental Energy Technologies Division of the U.S. Department of Energy, the manufacturing cost of virgin office paper is
17 Watt hours: http://eetd.lbl.gov/paper/ideas/html/issues.htm, retrieved June 2007.
d
According to the Environmental Energy Technologies Division of the U.S. Department of Energy, the manufacturing cost of 100% recycled office paper is 12 Watt hours: http://eetd.lbl.gov/paper/ideas/html/issues.htm, retrieved June 2007.
Tip
Config keys can be set from Options
→
Config editor (advanced).
15.9. Privacy Options
As a print tracking system, most organizations and users will expect PaperCut to record all printing activity. For organizations concerned that users might require more privacy than the default level of tracking affords, features can be enabled or disabled to suit. E.g. if it is considered that the content of documents should not be viewed by
PaperCut administrators, the Print Archiving feature can be disabled. Many features can be enabled and disabled at
Options
→
General.
Additional privacy-specific options are available at Options
→
General
→
Privacy Options.
Privacy Options
Omit document names from the print log
If this option is enabled, the document name of print jobs will not be logged. Document names may include identifying information about a user or the nature of their print job.
Anonymize jobs (don't link jobs with users)
When processing a job (print, copy, scan or fax), PaperCut needs to know the originating user to handle the job correctly, e.g. to provide the user with the correct account selection settings. When this option is enabled, once
PaperCut has finished processing a job it will "forget" the original user and clear any information from the database that links the two.
This anonymization is achieved by re-assigning the job to a different, specified user once the job has completed. The default and recommended approach is to assign jobs to a user called anonymous
. If this user does not exist at the time the feature is enabled then a new internal (non-domain) user with the configured name will be created (this user will have no password, so cannot be used to log in).
Viewing the Job Log for this anonymous user will show all jobs in the system. The transactions (charging) for jobs will still be applied to the original user, however, so that features such as print quotas will continue to work as expected. Please note that transaction times and job log times could be cross-referenced to potentially determine a link, as they will be close together in time. If this is a concern then the options at Options
→
Backups
→
Automatic Backups can be used to delete transaction logs older than a given age.
Enabling this option will mean that any functionality requiring a link between a user and a job (once the job has completed) will no longer be available. This includes user-based reporting and job refunds. It is recommended that this option is only enabled if strictly required.
15.10. Using the Config Editor
Most of the settings in PaperCut NG are easily accessible via the main admin interface (e.g. the Options tab). Some
281
System Management advanced settings are however only accessible via the Config Editor. The Config Editor stores keys or information used by PaperCut NG to configure various options and functions. This is very similar to the Windows System
Registry database.
Administrator can edit config keys using the following procedure:
1.
Login to the system as an administrator (e.g. the built-in admin account).
2.
Navigate to the Options section.
3.
Click on the "Config editor (advanced)" link in the Actions list on the left.
4.
In the quick find, enter the config key name and press GO.
5.
Locate the required key and enter a new value.
6.
Press the Update button to the right to apply the change.
Example of some keys that are often changed by administrators include:
• client.config.show-link - Indicates whether the link at the top of the user client should be displayed or not.
• client.config.show-details-link - Indicates whether the "Details" link that points to the user web interface is displayed or not.
• display.login-instruction - Used to display login instructions on the user/password screen.
Important
Take care when using the Config Editor. If you use the Config Editor incorrectly, you may cause serious problems which can only be fixed by reinstallation of the application.
282
Chapter 16. TopUp/Pre-Paid Cards
Many organizations run PaperCut NG in either a silent logging mode or as a way of enforcing sensible quotas. On the other hand, other organizations choose to run PaperCut NG in “charging mode” requiring users to make payments in advance. Recording and entering payments can be a time consuming process for staff or system managers. PaperCut NG offers a web interface for user account management to assist with the process, however there is still the need for someone to manually assign credit. The TopUp/Pre-Paid Card system included with
PaperCut streamlines the payment process and moves much of the manual handling over to the end-user.
Cards are also known as:
• Vouchers
• Re-Charge Cards
• Pre-Paid Cards
16.1. Cards by Example
The card system is best described by walking through the payment process:
16.1.1. The User's Perspective
Amy is a student at a local high school. The school uses PaperCut NG for their charging. Amy is allocated $5.00 a week for printing. This week she has used all her allocation but still has one assignment to print on Friday. She purchases a $5.00 Card from the school canteen. The card contains a 16-digit identification number. She logs onto the schools intranet site, enters the PaperCut section, and enters the card's ID number. Her account is automatically credited $5.00.
16.1.2. The Administrator's Perspective
Andrew is a system administrator at the same high school. At the start of the term he used the PaperCut NG card wizard to generate 500 TopUp/Pre-Paid Card of $5.00 value. These were generated in 2 batches. The first batch was prefixed with C1 and the second batch L1. The C1 batch was sold at the school canteen and the L1 batch sold at the school library. The cards are kept secured at these locations.
The card wizard generated a number definition file for each batch. Andrew imported these numbers into PaperCut.
Andrew took the time to customize the look of the cards to include the school logo and simple instructions on how to redeem the card.
During the year Andrew is able to track the cards sold and uses the batch prefixes to track where students like to purchase cards. Andrew also keeps an eye on the event log and has disciplined students attempting to guess card numbers.
16.2. The Card System
PaperCut Software International Pty Ltd has worked with a number of organizations to design the TopUp/Pre-Paid
Card system. A number of payment technologies were evaluated over the period of two years. These technologies included vending machines, smart cards, micro-payment systems, and manual processing. The card system proved to be the most successful and cost effective solution. The card concept is now the de facto standard in other industries such as pre-paid mobile phones.
The PaperCut NG card system is 100% software based. There is no need for special hardware such as smart card readers or special vending machines.
The card system is included as standard with PaperCut NG. The system includes:
• A card wizard application for assisting with the process of creating new cards.
• A web page for end-users to enter card numbers.
283
TopUp/Pre-Paid Cards
• A security framework for tracking card redemption and implementing fraud prevention.
16.3. Creating New Cards
16.3.1. Overview and Definitions
Cards are generated using the Card Wizard. The card wizard is a Microsoft Windows application that integrates with
Microsoft Word. The card wizard install can be downloaded from inside the PaperCut NG administration login under the Card section. The download link is located in the Actions area.
Important
The Card Wizard integrates with Microsoft Word. Please ensure that Microsoft Word is installed before using the Card Wizard.
Term
Card Wizard
Card Number
Definition
A tool to help administrators produce a set of cards. The wizard generates cards ready for printing and a number definition file suitable for importing into the
PaperCut NG system.
All cards are designated a random unique number. PaperCut uses this number to identify the card and its value. Users enter this number to allocate the credit to their account. An example number:
P0409-1945-4833-5750-4452
Batch ID
Valid Till Date (Expiration Date)
Mail Merge
Number Definition File
A batch ID is a user defined ID or number assigned to all cards in a batch. The batch ID will prefix all card numbers and are used to identify the source of a card. A unique number should be assigned to each batch.
Define the date on which a card can no longer be used. It's analogous to a “use by” date on a gift certificate. Expiration dates ensures cards only remain in circulation for a limited period of time. A six to 12 month period is recommended. In a school environment it may be useful to define an expiration date as the last day of the semester.
Mail merge is an advanced feature of Microsoft Word. The mail merge feature takes a design template and a data source, and merges the two together to construct a composite document. In the card wizard's case, the number list is the data source and the design template is the template Microsoft Word document.
The number definition file contains information on all cards in a batch including a list of card numbers, their expiration date, and value. The card wizard creates this file during the generation process and the system administrator will import this file into the Card administration section.
The card web entry page is a designated page inside the user login section.
Card Number Entry Page
Table 16.1. Card Terminology
16.3.2. Using the Card Wizard
This section will walk you through the process of creating a batch of TopUp/Pre-Paid Cards. The example covers creating a batch of 100 cards of value $10.00 each.
The Cards feature is accessed via the Cards tab. By default there is no Cards tab in the Professional (Client Billing) installation. You can enable the Cards tab by navigating to the Options section and selecting Enable use of
TopUp/PrePaid Cards. Click Apply.
16.3.2.1. Step 1 - Install the card wizard
284
TopUp/Pre-Paid Cards
Log onto a desktop system with Microsoft Word installed (normally not the server!). Open a web browser at: http://[server_name]:9191/admin
Log into PaperCut NG as admin and navigate to the Cards section. Download the card wizard from the Download
card wizard action. Run the install program and complete the installation process.
16.3.2.2. Step 2 - Welcome
Open the Card Wizard from the start menu, and press Next>.
16.3.2.3. Step 3 - Batch ID & Format
Enter a unique batch ID to define this batch and click Next>. We recommend adapting a consistent convention. For example, choose numbers representing the date, or a sequential numbering scheme.
The wizard offers a choice of two popular card number formats. The Numeric format is the most secure and generates long numbers. The Alphanumeric format produces a shorter format consisting of letters and numbers.
The Alphanumeric format is a little less secure due to the reduced number of possible permutations, however it does offer a shorter, more convenient entry format.
Figure 16.1. Entering a batch ID
16.3.2.4. Step 4 - Card Attributes
Ensure that the number of cards is set up to 100 and the value of each card is $10.00. By default the valid till date is set 6 months in the future. We recommend defining an appropriate date that corresponds to a fixed event such as the end of the year, budget year, term or semester.
285
TopUp/Pre-Paid Cards
Figure 16.2. Defining a valid till date
16.3.2.5. Step 5 - Design
To produce a set of standard cards, custom design is not required. Simply click the Next> button to move to the next step. Modifying the custom design requires knowledge of Microsoft Word's mail merge functionality. See the
Section 16.3.3, “TopUp/Pre-Paid Card Tips” for further details.
Figure 16.3. Options to edit the card design
286
TopUp/Pre-Paid Cards
16.3.2.6. Step 6 - Generate Numbers
Press Next> to generate the card numbers. The card wizard will prompt you for a location to save the number
definition file. Save the file on the local hard driver or a secure network drive.
16.3.2.7. Step 7 - Create Cards
The card wizard will now generate a merged Microsoft Word document. Before generating the Word document, the card wizard will ask you if Macros have been enabled in Microsoft Word. If the answer is no, or you are unsure, please say No and the card wizard will guide you through the process of enabling Macros. The card wizard uses
Word Macros to automate much of the card generation process.
If using Word 2007, after opening the document a Security warning is displayed on the Message Bar. You will need to enable macros by selecting "Enable this content" after clicking on "Options" on the Message Bar.
287
TopUp/Pre-Paid Cards
Figure 16.4. Enable Macros in MS Word 2007
16.3.2.8. Step 8 - Printing Cards
A new Microsoft Word document will open, listing all 100 cards. The cards are standard business card size suitable for printing on heavy paper and cutting with a paper cutter. For a professional look, consider forwarding a PDF
version to your local printing shop. See Section 16.3.3, “TopUp/Pre-Paid Card Tips” for more ideas.
288
TopUp/Pre-Paid Cards
Figure 16.5. Cards ready for printing
16.3.2.9. Step 9 - Importing
The final step is to activate the cards by importing the number definition file in the PaperCut NG admin section.
1.
Navigate to the Card section.
2.
Select the Import New Cards action.
3.
Click the Browse button and locate the number definition file as saved in step 5 above.
4.
Click the Upload button.
289
TopUp/Pre-Paid Cards
Figure 16.6. Imported card numbers
16.3.2.10. Step 10 - Testing
It is good practice to test the card process by using one of the cards on a test account (standard user level).
Remember to destroy the spent card used for the test!
16.3.3. TopUp/Pre-Paid Card Tips
16.3.3.1. Security
The PaperCut NG card system is designed with security in mind. All fraudulent card redemption attempts are detected, trapped and logged. The number allocation system is highly secure and guessing a number is “statistically impossible”. With 1,000 cards in circulation, the chance of guessing a number is 1-in-10,000,000,000,000, or in non-mathematical terms, it would take over 300,000 years to guess a number if a person enters one number every second!
Like many IT security systems, the weakest link in the system is the human interface. Cards are a form of virtual currency. Care should be taken to protect the cards from unauthorized access and disclosure.
• Ensure the generated Microsoft Word document is deleted or saved in a secure place after the cards are printed.
• Always delete the number definition file after importing the batch into PaperCut.
• Never leave the cards in an unsecured or visible location. Consider sealing cards in envelopes.
• Check the PaperCut NG application event log on a weekly basis for security messages. PaperCut will log and trap unauthorized card use.
• Use the card log to track card redemption and allocation.
• Cancel/Expire lost or stolen cards by batch number as soon as the problem is reported.
290
TopUp/Pre-Paid Cards
Important
The cards are like a form of cash and should be treated with the same care. Make sure the cards are carefully secured.
16.3.3.2. Cards Design
The Edit Template... button in Step 4 of the card wizard opens the standard card template for editing. The card wizard is able to use any standard mail merge design. It's even possible to convert the template layout to letters rather than cards. Microsoft's mail merge support is designed for Word “power users”. Consider taking the step-by-step mail merge tutorial provided with Microsoft Word help if you do not have experience with Word's mail merge functionality.
Consider keeping your customizations initially simple and work up towards more complex configuration.
To change the logo graphic:
1.
Click the Edit Template... button in step 5.
2.
Say Yes to Enable Macros.
3.
Select the standard PaperCut logo on the first card and press the Delete button on the keyboard.
4.
Select Insert
→
Picture
→
From File...
5.
Locate the desired logo and click Insert.
Figure 16.7. Inserting a new logo into a card
291
TopUp/Pre-Paid Cards
6.
If using pre-2007 MS Word click on the Propogate Labels button on the mail merge tool bar. The new logo should propagate across all cards on the page.
Figure 16.8. Propagate labels button in previous versions of MS Word
In MS Word 2007, click on the Update Labels button on the Mailings tool bar.
Figure 16.9. Update labels button in MS Word 2007
7.
Repeat the steps above to change other working and layout as required. Always change the first card then press the Propagate Lables or Update lables button to apply the changes to all cards. IMPORTANT: Do not accidently delete the special
<<Next Record>> field as this cause the merge to move to the next card number before printing the next card. Removing this will result in all cards displaying the same card number.
8.
Click File
→
Save and close Microsoft Word.
9.
Test the template by running a batch in the card wizard.
Tip
Design Recommendations:
• Consider changing the logo and adding your organization name
• Change the URL reference to point to your intranet site or event your network/card policy page.
• Provide basic instructions on how to redeem the card or the location of an information page.
16.4. Using a Card
The following information should be distributed to end-users - for example, via the "Print Policy" page on your organization's intranet site.
To redeem a TopUp/Pre-Paid Card:
1.
Purchase a card from the appropriate person or place. The network administrator creates cards specific for your organization. In schools, cards are often sold at the library, general office or school cafeteria.
2.
Open a web browser and navigate to the PaperCut NG user login page. After logging in, your account status should display.
3.
Click on the Redeem Card link on the left-hand navigation bar.
4.
Enter the Card Number in the Card Number box and press Redeem Card. Take care to enter the number exactly as listed including any dashes (
-
).
292
TopUp/Pre-Paid Cards
5.
If the card's number is valid, the credit as listed on the card will be transferred to your account and this will list in your transaction history.
Figure 16.10. Using a card
Tip
To educate the users about redeeming their TopUp/Pre-Paid Card, administrators might find the
sample information sheet helpful.
293
Chapter 17. Configuring Secondary Print
Servers and Locally Attached Printers
This section covers the setup of a secondary print server in "Quick Start" format. For a detailed explanation of the underlying technology and what's happening behind the scenes see the subsequent sections.
A secondary print server is a system that directly hosts a printer. In many situations it may be a dedicated server, however a secondary server may also be a desktop system hosting a directly attached USB printer. If this printer is to be controlled and tracked by PaperCut NG, a small monitoring component needs to be installed. The monitoring component intercepts the local printing and reports this use back to the primary Application Server. A secondary server may either be:
1.
A server style system hosting many printers.
2.
A desktop style system hosting printer(s) also shared to other network users.
3.
A desktop style system with the printer used only for local users (not shared).
The monitoring service is also referred to as a Print Provider as its task is to provide information back to the main
Application Server.
The process of setting up a secondary print server, depends on the operating system. Read the section appropriate to the required operating system.
Tip
For resilience against network outages, you may consider installing Site Servers at each of your
secondary print server locations. Refer to Chapter 10, Multi-Server and Multi-Site Deployments for a
broader discussion of multi-site and WAN scenarios.
17.1. Configuring a Windows Secondary Print Server
This section describes the process of setting up a secondary Windows print server.
17.1.1. Step 1 - Ensure primary server is set up correctly
Before installing a secondary server you should take some time to ensure the primary server (central application server) is set up and running correctly. If it is not running fine now adding an extra server will only "add an extra variable to the equation" and complicate troubleshooting. Take some time now to verify that the primary server is functioning correctly. For example, verify that:
• Printers on this server are being tracked.
• Users are allowed to login to user pages from their workstations.
• Administrators can access the system.
17.1.2. Step 2 - Ensure firewall software is set to allow access to port 9191
Secondary server needs to communicate (initiate a TCP connection) on port 9191. Administrators should ensure that any firewall software on the primary Application Server is not set to block any incoming local network traffic on this port.
17.1.3. Step 3 - Install the print provider
Install the print provider software onto the secondary server. On a Windows server, this is done by selecting the
"Secondary Print Server" option in the installation wizard. If the PaperCut Primary Server software was previously
294
Configuring Secondary Print Servers and Locally
Attached Printers installed on the server it must be uninstalled prior to installing the Secondary Server software.
17.1.4. Step 4 - Configuration
The Print Provider on the secondary server needs to know where the primary server is installed.
1.
Open a text editor such as Notepad.
2.
Open the file:
[app-path]\providers\print\win\print-provider.conf
3.
Locate the line starting with
ApplicationServer= and change localhost to the name or IP address of the primary server.
4.
Restart the server so the new configuration is detected. To avoid a restart, an administrator may also choose to manually restart the PaperCut Print Provider service.
17.1.5. Step 5 - Test
The secondary server should now be configured. Log into the system as "admin" and verify that the printers are now listed under the Printers section. Perform a multi-page test print on each printer and verify that print jobs are tracked correctly.
17.1.6. Automated Install
The installation of the secondary server component on Windows systems can be automated. This may be handy when the Print Provider component needs to be installed on a number of desktop systems running locally attached
17.2. Configuring a Macintosh Secondary Print Server
This section describes the process of setting up a secondary Mac print server. The primary Application Server may either be a Windows, Mac or a Linux basis system. PaperCut NG has full support for "mixed" or heterogeneous printing environments.
17.2.1. Step 1 - Ensure primary server is set up correctly
Before installing a secondary server you should take some time to ensure the primary server (central application server) is set up and running correctly. If it is not running fine now adding an extra server will only "add an extra variable to the equation" and complicate troubleshooting. Take some time now to verify that the primary server is functioning correctly. For example, verify that:
• Printers on this server are being tracked.
• Users are allowed top login to user pages from their workstations.
• Administrators can access the system.
17.2.2. Step 2 - Ensure firewall software is set to allow access to port 9191
Secondary server needs to communicate (initiate a TCP connection) on port 9191. Administrators should ensure that any firewall software on the primary Application Server is not set to block any incoming local network traffic on this port.
17.2.3. Step 3 - Create the host user account
PaperCut NG runs under a non-privileged user account called "papercut". This invisible system account is created automatically upon first install. Advanced system administrators may however have a preference to create this account manually. If you fall into this category, create the papercut account now prior to installation.
17.2.4. Step 4 - Install the print provider
295
Configuring Secondary Print Servers and Locally
Attached Printers
Install the print provider software onto the secondary server. Download the latest Mac DMG disk image and execute the contained installer called
PaperCut NG Secondary Server Installation.pkg
.
17.2.5. Step 5 - Configuration
The Print Provider on the secondary server needs to know where the primary server is installed. The installer may open the appropriate configuration file after the install completes.
1.
Open a text editor such as TextEdit.
2.
Open the file:
[app-path]/providers/print/ mac/print-provider.conf
3.
Locate the line starting with
ApplicationServer= and change localhost to the name or IP address of the primary server.
4.
Save the file and exit the text editor.
Double-click on the command script
/Applications/PaperCut
Monitoring.command
, and enable monitoring on the appropriate printers.
17.2.6. Step 6 - Test
NG/Control Printer
The secondary server should now be configured. Log into the system as "admin" and verify that the printers are now listed under the Printers section. Perform a multi-page test print on each printer and verify that print jobs are tracked correctly.
17.3. Configuring a Linux or Novell iPrint Secondary Print Server
This section describes the process of setting up a secondary print server on a Linux system. The primary Application
Server may either be a Windows, Mac, Novell or a Linux based system. PaperCut NG has full support for "mixed" or heterogeneous printing environments.
17.3.1. Step 1 - Ensure primary server is set up correctly
Before installing a secondary server you should take some time to ensure the primary server (central Application
Server) is set up and running correctly. If it is not running fine now, adding an extra server will only "add an extra variable to the equation" and complicate troubleshooting. Take some time now to verify that the primary server is functioning correctly. For example, verify that:
• Printers on this server are being tracked.
• Users are allowed user login to user pages from their workstations.
• Administrators can access the system.
17.3.2. Step 2 - Ensure firewall software is set to allow access to port 9191
Secondary server needs to communicate (initiate a TCP connection) on port 9191. Administrators should ensure that any firewall software on the primary Application Server is not set to block any incoming local network traffic on this port. A good way to test, is to open a browser on the planned secondary server and confirm you can access the administration web interface on port 9191.
17.3.3. Step 3 - Account setup
On the secondary server, create a user account called papercut
. The papercut user's home directory should be set to the desired install location. This is normally
/home/papercut
. The method of creating this account is the
17.3.4. Step 4 - Install the Print Provider
296
Configuring Secondary Print Servers and Locally
Attached Printers
Important
The instructions below assume i686 architecture. If your system OS is 64-bit, replace i686 with x64 in all file paths.
Install the Print Provider software onto the secondary server by copying all files and directories from the primary
Application Server's directory:
[app_path]/providers/print/linux-i686/* (32bit)
[app_path]/providers/print/linux-x64/* (64bit)
To the equivalent location on the secondary server:
/home/papercut/providers/print/linux-i686/ (32bit)
/home/papercut/providers/print/linux-x64/ (64bit) on the secondary server. Perform the copy operation as the papercut user so that files are owned by the papercut user. You may use any method to copy the files, including over the network or via a USB key. If the primary server is also Linux, the simplest way would be use Secure Copy ( scp
) as follows: shell> su - papercut shell> mkdir -p providers/print shell> cd providers/print shell> scp -r primary.server.name:/home/papercut/providers/print/* .
After the copy operation is performed, execute the setperms and roottasks scripts as root:
32bit shell> su - root shell> sh ~papercut/providers/print/linux-i686/setperms shell> sh ~papercut/providers/print/linux-i686/roottasks
64bit shell> su - root shell> sh ~papercut/providers/print/linux-x64/setperms shell> sh ~papercut/providers/print/linux-x64/roottasks
17.3.5. Step 5 - Configuration
The Print Provider on the secondary server needs to know where the primary server is installed (e.g. Its IP address).
1.
Open the file:
/home/papercut/providers/print/linux-i686/print-provider.conf (32bit)
/home/papercut/providers/print/linux-x64/print-provider.conf
(64bit) in a text editor.
2.
Locate the line starting with
ApplicationServer= and change localhost to the name or IP address of the
297
Configuring Secondary Print Servers and Locally
Attached Printers primary server.
The binaries copied in step 4 now need to be integrated into the CUPS, Samba or Novell iPrint print queues. This
17.3.6. Step 6 - Test
The secondary server should now be configured. Perform some test printing on all of this secondary server's printers. Log into the system as "admin" and verify that the printers are now listed under the Printers section.
Perform a multi-page test print on each printer and verify that print jobs are tracked correctly.
17.4. Print Monitoring Architecture
This section covers PaperCut NG print monitoring architecture from a technical perspective. Knowledge of advanced networking is expected.
PaperCut NG is designed using the latest software design principles. An important design principle used is Service
Oriented Architecture (SOA). PaperCut NG divides key operational areas into components. These components communicate using an XML Web Services standard. Two of the main services are:
Service/Component
The Application Server
Print Provider Service
Description
The central logic service responsible calculating user costs and providing the web and admin interface.
A service responsible for monitoring and analyzing print jobs and reporting this information using XML Web Services to the application server.
Table 17.1. PaperCut NG services/components
In a single server setup, an administrator does not need to be concerned with the two components as they automatically act as one (it's only noticeable in that two processes are running on the server). On a multi-server/system environment a deeper understanding of the architecture is required.
17.5. Multiple Print Servers
Many large networks, or even smaller networks with a legacy design, may be composed of more than one print server. Reasons for separating printers across servers/systems include:
• Legacy design - “That's the way the previous admin set it up.”
• Networks with 100 printers or more may need multiple servers to spread the printing load.
• Networks spanning multiple physical sites or subnets may have separate servers minimize cross-site network traffic.
• Servers may exist to support different operating systems
• A local desktop printer attached to a system is also a remote print server.
One of the servers on the network needs to be nominated as the primary server. This system runs the Application
Server software responsible for providing the user interface, storing the data, and managing the application logic.
The system nominated for this task is usually a print server (but could be any server). It needs to be a system with spare capacity to run the PaperCut NG application server software. This system should have good performance, have at least 500 Mb of free hard-disk space, and be included in an off-disk backup routine.
Other print servers are known as secondary servers. These servers run the Print Provider component and communicate back to the central server. The following diagram illustrates this setup.
298
Configuring Secondary Print Servers and Locally
Attached Printers
Figure 17.1. Secondary server reporting back to primary server (application server)
When a client prints to a secondary server, the Print Provider intercepts the print job and forwards the information to the central server for processing. Communication is via XML Web Services over HTTP on the PaperCut Application
Server's nominated port (normally port 9191). The web services protocol is specifically designed to facilitate easy firewalling, scalability, and will work over a wide range of network speeds.
PaperCut NG Service Oriented Architecture offers many advantages for network administrators including:
• Secondary servers run the minimum amount of software
• Communication between servers uses minimal bandwidth. Physically separated servers connected via WAN links, VPNs or other slow links are supported with minimal or no impact on printing performance.
• All data, logging and configuration information is stored on one single central server facilitating central backup from one location.
• Management may be conducted centrally from one location.
PaperCut NG's SOA design allows advanced setups including:
• Decentralized deployment
• Separation of concern (servers dedicated to separate tasks such as database server, application server and print server)
• Options to remove points of failure via clustering or fail-over
299
Configuring Secondary Print Servers and Locally
Attached Printers
Figure 17.2. PaperCut NG Architecture - an advanced configuration
17.6. Automating Secondary Server Deployment on Windows
The secondary server installation process can also be automated via command line switches issued to the installer program. This may be useful when there is a need to install the Print Provider on a number of desktop systems hosting local attached printers.
To automate the installation:
1.
Copy the windows installer program, pcng-setup.exe
, into a directory accessible to the target systems (i.e. A network share or mapped drive).
2.
Copy the print-provider.conf
file from main server.
This file is located at
[app-path]/providers/print/win
. Place the file in the same directory as the install program (as performed in step 1.)
3.
Edit the print-provider.conf
file and define the correct server name or IP address of the main application server in the line starting with
ApplicationServer=
.
4.
Use a batch file or equivalent to start the install program as follows: pcng-setup.exe /TYPE=secondary_print /SILENT
Note: The installer requires administrator level - needed to install a system service.
Note:
• The executable name of the installer program may vary depending on the version.
• Replacing the
/SILENT option with
/VERYSILENT will suppress all visual output during the installation process.
• The copy of the print-provider.conf
file is used during the install process to ensure the installation is aware of the location of the main application server.
•
300
Configuring Secondary Print Servers and Locally
Attached Printers
301
Chapter 18. Advanced Customization
PaperCut NG is an important part of network infrastructure at many thousands of organizations. Having the ability to seamlessly integrate PaperCut into an existing network is important. There are a number of ways to ensure end-users see the system as part of the network rather than an add-on. These include:
• Implementing Single Sign On (SSO) to integrate PaperCut into your organization's Intranet portal.
• Changing the URL or link on the User Client window
• Customizing the look and feel of the user web pages
• Using the PaperCut NG back-end data in other procedures such as custom reports
This section covers some of the customization options available within PaperCut NG. For Single Sign On please see
18.1. Customizing the User Client Tool window
The pc-client.exe
program displays a small window highlighting the current logged in user's current account balance. This window contains two links. One called Details that takes the user to the User Pages login. The other defaults to the PaperCut Software website. The link to the PaperCut Software website can be replaced. Some suggestions include linking to your organization's website or intranet site, or linking to a page containing your organization's network usage policy. The logo used on the window can also be customized.
To change the link on the User Client window:
1.
Login to the system as an administrator (e.g. the built-in admin account).
2.
Navigate to the Options section.
3.
Scroll down to the Client software section.
4.
Select the option Change link on client software.
5.
Enter a Destination URL pointing to your new destination. The link should be a complete URL including the http:// component. e.g.
http://www.myorganization.com/printpolicy.htm
.
6.
Under Link text enter the text that should be displayed. e.g.
Print Policy
.
7.
Press the Apply button to the right to apply the changes.
8.
The next time the client tool is started on one of the workstations, the new link will be displayed.
Figure 18.1. Customizing the user client link
302
Advanced Customization
Figure 18.2. Customized user client link
There are other configuration keys that allow an administrator to customize the user client for their organization. The table below outlines all of the client customization config keys available. The value of these config keys can be
config keys.
Config name
client.config.show-link client.config.show-details-link client.config.show-document-cost client.config.default-advanced-tab
Description
Indicates whether the link at the top of the user client should be displayed. To display set the value to
Y
, to hide set the value to
N
.
Indicates whether the "Details" link that points to the user web interface is displayed. To display the link set the value to
Y
, to hide set the value to
N
.
Determines whether to show the document cost to the user in print popup notifications. To show the cost set the value to
Y
, to hide set the value to
N
.
The default tab to display when a user is configured with advanced account selection.
Values:
DEFAULT (All Accounts)
,
ALL (All Accounts)
,
PREFERRED
(Preferred List),
RECENT
(Recent Selections)
Table 18.1. User Client Customization Config Keys
The logo used on the User Client balance window and the account selection dialog can also be customized by placing a file called client-logo.png
in the directory
[app-path]/client/[platform]
- the same directory as the executable. The image must satisfy the following requirements:
• Comply to the PNG (Portable network graphic) format.
• A size of 64px by 64px.
• Display correctly on different background colors (make use of transparencies or alpha channels).
On the Apple Mac platform the process is a little more involved. The image needs to be placed inside the App package at:
PCClient.app/Content/Resources
. To access this directory, Option-click on the PCClient icon and select Show package contents....
The user client can also be configured by passing command-line parameters to the program. This is described in
Section A.5, “User Client Options”.
18.2. Limiting the list of interface languages/translations
PaperCut NG has been translated into a number of languages. Some of these translations are complete and done at an official level while others are partial and done by PaperCut NG users working in cooperation. Many of these languages may not be appropriate for your environment and it may make sense to limit the list - the user selects the language in the drop-down list on the web login screen. The list of available languages can be set by changing config key language.available
to a comma-separated list of ISO language codes. The list should be a subset of: ca,cs,da,de,es,es_ES,fi,fr,hr,hu,it,iw,ja,ko,lt,lv,nl,no,pl,pt,pt_PT,ru,sl,sr,sv,tr,zh_CN,zh_HK,zh_TW
For example setting language.available
to en,de would limit the list to English and German only.
Please see Section 15.10, “Using the Config Editor” to find out how to change config keys.
18.3. Customizing the User web pages
303
Advanced Customization
18.3.1. Look & Feel
The user pages display information about the user's account and provide access to features such as
TopUp/Pre-Paid Cards. The visual design of these pages can be tailored to make them fit into the look and feel of an existing internet or intranet site. This gives the pages an official look ensuring your users see the system as an important part of your organization's network.
Figure 18.3. A customized end-user web designed for St Mary's Anglican Girls School
304
Advanced Customization
Figure 18.4. A customized end-user web designed for Williamstown High School
PaperCut Software International Pty Ltd offers a service where their developers will undertake design work based on an existing website. If you would like assistance with the customization, please email the PaperCut Software
International Pty Ltd support team.
Organizations whose staff have good to advanced HTML experience may choose to customize the pages in-house.
The design of the user pages is controlled via HTML "include" files for the header and footer areas of the page, with page styling controlled via Cascading Style Sheets (CSS). Placing the following files in the PaperCut NG directory structure at
[app-path]/server/custom/web overrides page layout and style.
Filename
user2.css
header2.inc
footer2.inc
login-logo.png
Description
If this file exists, the contents of user2.css
is included as an overriding stylesheet. Styles in this file can be used to define fonts, colors and sizes.
If the header include file exists, the HTML in the header area of the pages is replaced with the contents of the file. This file should be saved in
UTF-8 encoding for international characters to be displayed correctly.
If the footer include file exists, the HTML in the footer area of the page is replaced with the contents of the file. This file should be saved in
UTF-8 encoding for international characters to be displayed correctly.
If this file exists, the logo on the web-based login page is replaced with the supplied image. The file should be an image of size 250px by 64px in PNG format.
Table 18.2. Files used to customize the user web pages
305
Advanced Customization
Tip
Any custom content placed in
[app-path]/server/custom/web/
, such as additional images, can be accessed via a URL beginning with
/custom/
. For example if a file named header.jpeg
is placed in
[app-path]/server/custom/web/ it can be accessed via the URL
/custom/header.jpeg
.
Tip
To save a file in UTF-8 encoding on Windows using Notepad, change the Encoding option to UTF-8 on the Save As... dialog.
Note
Why the "
2
" in user2.css
etc.? In previous versions of PaperCut these files did not contain a number. The numbers are there to maintain backwards compatibility for existing user web interface customizations, so that as the default look of the interface is updated in new versions, your customized look is maintained. Please remove the "
2
" for older installations.
18.3.2. Login Instructions
Some organizations may benefit from providing additional login instructions to users. This can be useful for explaining which username or password to use (in the case there are multiple logins or passwords at the site).
Figure 18.5. Login Page with custom instructions
The following config keys allow you to customize the login page:
306
Advanced Customization
Config name
display.login-instructions auth.web-login.autocomplete
Description
A HTML friendly message to be displayed on the login screen, above the username and password fields.
Specify Y to enable browser auto-completion of the login fields as a convenience to users. By default, the browser is requested to not use auto-completion.
Table 18.3. Config Keys for Customizing the Login Page
18.3.3. Additional Links in the Navigation Menu
The navigation menu in the user web interface contains links for the PaperCut services that are enabled and available to the user. In some cases it may be desirable to add additional external links to this menu. Examples include:
• Linking to a print policy page on the organization's intranet.
• Linking to a page with key contact details.
• A link to return to the "main" intranet page/portal.
Custom links will appear above the Log Out item.
To add a custom link:
1.
Log into the admin interface and navigate to Options
→
General
→
User Features.
2.
Enable the option Add custom links to the user web navigation menu.
3.
Click the Add custom link button that appears.
4.
Fill out the Label/Text and URL fields in the dialog that appears after clicking the button. Label/Text is the text that will appear in the navigation menu, and URL is the destination of the URL when clicked.
Figure 18.6. Adding a new custom navigation link to the user web interface
5.
The link will now appear in the user web interface.
Figure 18.7. Example custom navigation link in the user web interface
307
Advanced Customization
Existing custom links are displayed in the admin interface under the Add custom links to the user web navigation
menu option. Links may be deleted by clicking the [delete] link next to the relevant link.
Figure 18.8. Deleting a custom navigation link
The URL in custom navigation links may also contain special replacement fields. E.g. the
%user% in http://example.edu/print-policy?u=%user% is replaced with the logged in username to create a URL like http://example.edu/print-policy?u=tom
.
The available special replacement fields are as follows:
Field Description
%user%
%user_full_name%
%user_id%
%user_email%
The username of the logged in user.
The full name of the logged in user.
The id/card number of the logged in user.
The email address of the logged in user.
%user_office%
%user_department%
The office of the logged in user.
The department of the logged in user.
%return_url% A URL that can be used to send the user back to the user web interface. The user will be sent back to the Summary page as if they had just logged in, assuming their session has not timed out.
Table 18.4. Fields available for replacement in custom navigation links in the user web interface
18.3.4. Custom Printer Maps for Web Print
A graphical map or other custom content may be used instead of the default printer selection list in the Web Print
18.4. Customizing the Administration Web Interface
As the PaperCut NG administration interface is designed for use by administrators there generally isn't the need to customize it to the extent of the user web interface (for information about customizing the user web interface see
header of the administration interface however. The available customizations are:
• Replace the existing administration logo
• Add an image of your choice to the right of the main administration logo
• Add a custom message to the dashboard
Logos can be added to customize the look of the admin interface. These can be customized by placing the following files in the PaperCut NG directory structure at
[app-path]/server/custom/web/
.
308
Advanced Customization
Figure 18.9. Customized logo (admin-logo.png) in the administration interface
Figure 18.10. Customized logo (admin-main-logo.png) in the administration interface
You can add your own content to the dashboard by placing an HTML file in
[app-path]/server/custom/web/ called dashboard-notice.inc
. This could be used to display a short message for the attention of other administrators. Other examples might include:
• Guidelines for administering printers
• Policies for handing refunds
• Contact details for key people
• Or even your own widget that loads content from elsewhere
309
Advanced Customization
Figure 18.11. Customized content in the administration interface dashboard
Tip
The title of the custom dashboard widget can be changed by setting the config key dashboard.gadget.custom.title
. For information about setting config keys please see
Section 15.10, “Using the Config Editor”.
Filename
admin-logo.png
admin-main-logo.png
Description
If this image exists it will be displayed to the right of the existing application logo. The image must be in PNG format and for best results should be sized
250px by 42px.
If this image exists it will replace the standard application logo in the top left corner. Changing the standard logo will display a "Powered by PaperCut" image beside it. The image must be in PNG format and for best results should be sized
280px by 42px.
HTML contained within this file will be displayed on the administration dashboard page.
dashboard-notice.inc
Table 18.5. Files used to customize the administration web pages
18.5. Customizing Report Headers
The standard PaperCut NG report header logo can be replaced with an alternate image. This can be used to include an organization logo and address for example, which may be useful when attaching reports to customer invoices, or just to make reports look more professional.
Figure 18.12. Example custom report header usage
To use a custom report
310 header logo, place an image at
Advanced Customization
[app-path]/server/custom/web/report-header.png
. The image should be 250px by 80px in PNG format.
18.6. Data Access and Custom Reports
The default PaperCut NG installation stores data in an internal database. For the interested person, the database is
Apache Derby - an open source database written by IBM and based on their DB2 Cloudscape Database. The internal database is optimized for embedded use, is very robust, ACID compliant and scales well. The internal database however is not designed for multi-application access. To access the data from an exteral source such as a reporting program, you'll need to consider running PaperCut NG on an external database (RDMS) designed for multi-user and multi-applicaiton user access. Common database solutions include Microsoft SQL Server, Oracle,
The PaperCut NG data structure is relatively simple and people with Crystal Reports, MS Access or SQL experience should have no problems extracting data or written custom reports. Report developers should keep in mind:
• Only access the data in a read-only mode. Modifying data directly underneath the application may cause unpredictable behavior.
• Always test any custom reports after an upgrade as the underlying data format may have changed. PaperCut
Software developers try to minimize data structure changes but they are expected to occur in major upgrades.
A database schema diagram can be found in the PaperCut NG knowledge base located at Database Schema
Diagrams [http://www.papercut.com/kb/Main/DatabaseSchema].
18.6.1. Plain Text Print Log
In addition to storing print log information in the database, a real-time, plain text log is also written into the directory:
[app-path]/server/logs/print-logs
Field 6
Field 7
Field 8
Field 9
Field 10
Field 11
Field 12
Field 13
Field 14
The log file is in a tab delimited format and a new log is created for each day. Files are named with the format printlog_yyyy_mm_dd.log
and files are archived for 30-days. The tab delimited file can easily be imported into programs such as Microsoft Excel, Microsoft Access or other database.
Field
Field 1
Field 2
Field 3
Field 4
Field 5
Description
Date in format yyyy-MM-dd\th:mm:ss a/p
Server Name
Printer Name
User who printed the document
Account charged (usually the user's personal account but could be a shared account)
Client/Workstation Name
Document name
Total number of pages
Total number of color pages
Number of copies (this has already been used to calculate the total pages).
Cost
Duplex status
Grayscale status (Color mode)
Paper Size (e.g. Letter, A4)
311
Advanced Customization
Field
Field 15
Field 16
Field 17
Field 18
Field 19
Field 21
Table 18.6. Text print log file format
Description
Paper Height in Millimetres (divide by 24.5 for inches)
Paper Width in Millimetres (divide by 24.5 for inches)
Print job size in KB
Printer Language
Cost Adjustments (comma separated)
Job Type (PRINT)
18.7. Automation and Scripting
PaperCut NG provides a detailed set of server commands and Web Services API's. These services may be used to automate common operations and management tasks. Some examples of where an administrator may choose to use scripting/automation include:
• Automate tasks such as backups and domain user/group synchronization.
• Integrate account creation and management into existing scripts or processes.
• Manage account balances and transactions outside the application.
The automation and scripting tools are written for software and script developers. It is expected that readers intending on using these tools are comfortable with developing system management and server monitoring programs.
The server-command and Web Services API's are included as standard with PaperCut NG. More information on
Section A.1, “Server Commands (server-command)” and Section A.3, “The XML Web Services API”.
18.8. Custom User Directory Information Providers
PaperCut NG is a modern application designed with a modern architecture. It supports plug-ins and extensions at a number of different levels. One such layer is the User Directory source. Organizations with very complex domains, such as those seen in large universities, can be accommodated either with the standard options, or if the standard options are not sufficient, via a custom plug-in.
For example, a University may have multiple domains, one running Active Directory and the other LDAP/NIS. A custom plug-in could support this by first querying Domain A, and if the user is not found, the query Domain B via
LDAP. The PaperCut NG development team is happy to provide API documentation and sample source code to assist organizations with custom requirements.
current installation, look in: For some working examples available in your
[app-path]/server/bin/linux-[x64|i686]/sambauserdir
,
[app-path]/server/bin/linux-[x64|i686]/authsamba
[app-path]/server/bin/linux-[x64|i686]/src/
.
18.9. Enabling ports 80 (HTTP) and 443 (HTTPS)
and
By default, PaperCut listens to ports 9191 and 9192 for HTTP and HTTPS communication respectively. These ports have been selected as they're generally unused by other applications. Because PaperCut is a web application it may be desirable to have the interface available on the standard HTTP and HTTPS ports (80 and 443 respectively).
One reason for doing so may be to simplify URLs communicated verbally (as the user will not have to supply a port number).
The configuration procedure is different for each operating system. See below for instructions. Important: Before you
312
Advanced Customization begin, first ensure no other applications (such as IIS, or Apache) are currently installed and using ports 80 or 443 on the server hosting PaperCut.
Important
The following directions detail how to enable port 80 in addition to port 9191. Enabling an additional port is recommended over simply changing the existing port. Port 9191 is also used for server-to-server and client-to-server communication so it's important that this port continue to be made available.
Important
Also make sure you you enable the 80 and 443 firewall ports if users access PaperCut across firewall devices
18.9.1. Windows
1.
Stop the PaperCut NG Application Sever, under Control Panel
→
Administrative Tools
→
Services.
2.
Open the file:
[app-path]\server\server.properties
3.
Enable port 80 (and 443) by changing the appropriate settings from a
N to a
Y
. They should look like: server.enable-http-on-port-80=Y server.enable-https-on-port-443=Y
4.
Restart the PaperCut NG Application Server stopped in Step 1.
5.
Test and ensure the web interface is working. e.g.
http://[myserver]/admin
18.9.2. Linux
On Linux systems, only privileged programs that run as root may use ports under 1024. In line with security best practice PaperCut runs as a non-privileged user. To enable port 80 and 443, use iptables
(or ipchains on old systems) to port-forward 80 to 9191. The following commands provide an example. You may need to consult your distribution's documentation to see how to persist the iptables rules between system restarts:
/sbin/iptables -t nat -I PREROUTING --src 0/0 --dst <server_ip> \
-p tcp --dport 80 -j REDIRECT --to-ports 9191
/sbin/iptables -t nat -I PREROUTING --src 0/0 --dst <server_ip> \
-p tcp --dport 443 -j REDIRECT --to-ports 9192
(These commands would typically be place these in an rc init script or the iptables startup config script as provided by your distribution.)
18.9.3. Mac
The approach on Mac systems is similar to Linux. Modify the Mac firewall ( ipfw
) with the following command: sudo /sbin/ipfw add 102 fwd 127.0.0.1,9191 tcp from any to any 80 in
See ipfw man page for all the scary details!
313
Advanced Customization
18.10. Customizing Mobile Print Release
creating custom images. This can be used to change the colors of the header, footer and the header image. It is also possible to change the icon shown on the iOS home page. Placing the following files in the PaperCut NG directory structure at
[app-path]/server/custom/web to override the page layout and style.
File name
mobile-release.css
mobile-release-icon-114x114.png
mobile-release-icon-72x72.png
Description
If this file exists, the content of this file is included as an overriding stylesheet.
Styles in this file can be used to define the colors of the header and footer.
You can customize the header image by placing your header image file under the custom directory and by defining the following rule in the CSS file.
#top-bar-logo { url('/custom/mobile-release-logo.png'); } background-image:
The header logo should be an image 130px wide and 25px high.
If this file exists, the home page icon on iPad can be replaced. The file should be a PNG that is 114px wide and 114px high.
If this file exists, the home page icon on iPhone can be replaced. The file should be a PNG that is 72px wide and 72px high.
Table 18.7. Files used to customize Mobile Print Release
Figure 18.13. Customized design of Mobile Print Release for WilTown School
314
Chapter 19. Web Browser Single Sign-on
(SSO)
Single sign-on lets users access PaperCut's web interface without re-entering credentials. For example, a user logged into Windows may be given direct access to PaperCut's web interface without the need to re-enter their username and password at the PaperCut login screen. Sites with an intranet portal often find SSO particularly attractive, as it allows diverse IT systems to be seamlessly integrated into the portal without the need for separate logins.
Single sign-on also goes hand in hand with technologies such as two-factor authentication used in high security environments. With two-factor authentication, sign-on may involve presentation of an ID card or reading a fingerprint. In some cases, user passwords are managed by the security system and not known to the user, making it impossible to login using a traditional login screen. PaperCut's SSO support allows PaperCut to leverage the two-factor security already in place.
Web single sign-on is an advanced topic. The standard web login that comes built-in with PaperCut is most appropriate for many sites.
PaperCut supports two different web SSO methods:
1.
Integrated Windows Authentication [http://en.wikipedia.org/wiki/Integrated_Windows_Authentication]
For
Windows domain environments where both the PaperCut Application Server and the user PC's share the same
Windows domain and intranet zone. With Integrated Windows Authentication, PaperCut uses existing Windows technologies to securely identify Windows domain users as PaperCut users.
2.
WebAuth [http://webauth.stanford.edu/] A web authentication system developed and freely licensed by Stanford
University. It is implemented as an Apache module and works by intercepting requests to the PaperCut
Application Server. WebAuth is operating system neutral, but requires specialist expertise to set up.
PaperCut's WebAuth integration is actually quite generic and is also used for Shibboleth SSO integration at several customer sites.
19.1. Planning for Web SSO Implementation
There are a number of considerations and preparation steps you must take prior implementing SSO in PaperCut
19.1.1. Preparing for SSO
1.
An effective security system offers multiple layers of defence against unwanted intrusion. For example an organization's firewall may provide the first layer of defence, but if an intruder penetrates that, the Windows login presents a second barrier. Once logged into Windows, PaperCut's login screen represents a third layer of defence.
SSO trades off the convenience of direct access with removing one layer of security. For example, with SSO a user may click on a hyperlink in an email or instant message and be taken directly into PaperCut. Before implementing SSO, you must weigh up the risks and benefits for your organization.
2.
PaperCut offers granularity of control over which parts of PaperCut will use SSO. For example, you may decide to use SSO for just the user web pages and mobile client, not the admin interface. You will need to decide your policy up front before configuring SSO.
3.
You must choose whether you wish PaperCut NG SSO to log users directly in, or to first present a confirmation page. The confirmation page displays the user name and can also offer a Switch User link to allow users to use an alternate login. With direct login, one less click is needed, but there is no opportunity to confirm the correct login or switch to an alternate user.
You will also need to decide whether you wish to redirect the user to your intranet portal after logout. A logout
URL is required when direct access is configured.
315
Web Browser Single Sign-on (SSO)
4.
PaperCut users, and the built-in
admin are internal to PaperCut and will not work with SSO. If you do need to retain some internal users, you will need to show the confirmation page with the Switch User link to make the
PaperCut login page accessible.
5.
/release, /webcashier and /central-reports.
6.
Select which SSO technology is right for you. Whilst many PaperCut NG sites will choose Integrated Windows
Authentication, it does have strict pre-requisites. For example, if you have a significant number of non-Windows users, Windows based SSO may not be the best choice for you. More information about each SSO technology is provided below.
19.1.2. Planning for Integrated Windows Authentication
Integrated Windows Authentication (IWA) is designed for Microsoft Windows environments where both the PaperCut
Application Server and client PCs reside on the same Windows domain and Intranet Zone. In summary the requirements are:
1.
The PaperCut Application Server must run on the Windows operating system.
2.
PaperCut web users are using PC's running Windows
3.
All computers are on the same domain
4.
Your site uses Active Directory for managing users, including PaperCut users. Windows Authentication will only work with users that are managed by Windows.
5.
The Application Server URL is on the same Intranet Zone as user's PC's. By default this means that the URL does not contain periods. User Internet options may also be configured to explicitly add the PaperCut
Application Server to the Intranet Zone.
6.
Your organization's recommended web browser supports IWA. Browsers that support IWA include Internet
Explorer, Chrome and Firefox.
(Note that Firefox requires additional configuration
[http://markmonica.com/2007/11/20/firefox-and-integrated-windows-authentication/] to enable IWA support.)
Integrated Windows Authentication is part of Windows, so if your site meets the above criteria, no additional setup is needed prior to configuring SSO.
19.1.3. Planning for WebAuth
WebAuth uses a reverse proxy server to manage HTTP traffic between users and PaperCut. If you are considering
WebAuth, you will need the resources and skills to implement and configure an Apache web server and perform the installation instructions [http://webauth.stanford.edu/install.html] provided by WebAuth.
WebAuth takes care of authorizing the user and inserts a special HTTP header in all authorized requests sent to
PaperCut. You will need to specify the name of this header and also a list of whitelisted source IP addresses when integrating WebAuth with PaperCut
Although WebAuth SSO is considerably more complex to implement than IWA, it does have the advantage of supporting a non-Windows environment.
19.2. Configuring Web SSO
Configuring SSO in PaperCut is easy, but you must work through the preparation steps above, or you may find that you are unable to login to PaperCut!
Tip
After enabling SSO on the admin interface, it will no longer be easy to use the built in admin user as the login page is no longer shown. Before configuring SSO, you must ensure your domain or corporate login has admin rights and you will need to use this login.
316
Web Browser Single Sign-on (SSO)
As a protection, the built-in admin user does not have the rights to enable SSO.
If you make a mistake, and lock yourself out after enabling SSO, you can bypass SSO by adding
/nosso to the Application Server URL. For example: http://[myserver]/admin/nosso
Go to: Options
→
Advanced and find the "Single Sign-on (SSO)" section.
Figure 19.1. Single Sign-on Configuration
1.
Check Enable Single sign-on to enable SSO. Additional configuration items will appear.
2.
Select the SSO method, either Integrated Windows Authentication or WebAuth.
3.
If you have selected WebAuth, enter the WebAuth header name and a list of whitelisted IP addresses.
4.
Specify the SSO behavior you want for user web interface and mobile client, admin interface and other interfaces: a.
Standard (username and password) - don't use SSO and show the PaperCut NG login screen.
b.
SSO with confirmation page - Use SSO and present a confirmation page at login.
c.
SSO with direct access - Use SSO and login the user directly with no confirmation page.
5.
Specify whether you wish to show a Switch User link on the confirmation page.
6.
Specify a URL to go to on logout. A typical example would be the URL for your intranet portal.
19.2.1. Advanced Configuration
learn how to set config keys.
1.
Some installations wish to enable SSO for web users, but not for mobile users of the mobile client and mobile release apps.
To disable SSO for mobile users, set the advanced config key: auth.web-login.sso-enable.mobile-user to
N
.
2.
By default, Windows SSO will not authenticate users belonging to the "Guest" group. You may change this behavior by setting the advanced config key auth.web-login.sso-allow-guest to
Y
.
317
Web Browser Single Sign-on (SSO)
19.2.2. Post Installation Testing
After enabling SSO, we recommend you perform these tests to ensure that users can successfully access the
PaperCut interface.
1.
Verify that you can still login to the admin interface.
2.
Verify that a user without admin rights can still access their user web pages.
3.
If in use, verify that a user with the appropriate admin rights can still access other interfaces such as release or webcashier.
4.
Try logging in from other PC's in the domain.
5.
Try logging in from different browsers supported in your organization.
6.
If using IWA, try logging in from a non-windows client or a PC outside the domain. Verify you can still login after providing your Windows credentials.
318
Chapter 20. Advanced Scripting (Print
Scripting)
20.1. Introduction
PaperCut's advanced scripting interface is a powerful and flexible feature that can be used to define and fine tune your printing policy. While there are many features that can be enabled by ticking checkboxes and changing options in the admin interface, scripting your own behavior introduces a whole new level of customization.
The functionality made possible by scripting is varied and is constantly being extended based on customer demand.
Some common uses include:
• Displaying a popup message if a user forgets to select duplex on large jobs.
• Showing a dialog that displays environmental impact statistics about a user's print job such as the amount of carbon dioxide equivalent greenhouse gases produced.
• Prompting the user to confirm large jobs before printing.
• Automatically routing large jobs to more efficient high volume printers.
All of the above is possible by writing a small script directly into a code editor in the admin interface. In fact, the above functionality is a pre-built recipe ready to use.
Other usage examples include:
• Requesting job data/security classification.
• Giving discounts during off-peak times.
• Charging printing to departments during class-time.
• Displaying warning messages under selected conditions.
• and many, many more.
At a high level, advanced scripting provides the ability to:
• Adapt logic based on print job attributes such as cost, pages, document name, time, etc.
• Modify job attributes and behavior such as routing the job to another printer, influencing job cost and account charged, and appending metadata such as comments.
• Interact with end users via client messages and pop-ups/dialog boxes.
319
Advanced Scripting (Print Scripting)
Figure 20.1. Print Policy Pop-up (as implemented in the Print Policy Recipe)
20.1.1. Prerequisites
Writing print scripts brings many possibilities but also introduces the possibility that writing a buggy print script results in unexpected behavior. Previous experience with scripting or programming is strongly recommended.
PaperCut NG does provide a number of tools to assist with script development, however, including:
• A mini JavaScript editor with basic error checking and syntax highlighting.
• Quick access to a code cookbook containing dozens of best-practice recipes.
• Pre-canned "code snippets" demonstrating the use of key functions.
• Simple debugging tools such as logging and runtime error reporting.
320
Advanced Scripting (Print Scripting)
Figure 20.2. The print script editor showing a sample script
All of PaperCut NG's advanced scripts are written using the world's most popular scripting language, JavaScript
(also known as ECMA-262 ECMAScript... apparently ;).
Note
Why JavaScript?
JavaScript was selected as PaperCut NG's scripting language after careful consultation with the existing user base. JavaScript was the language common to system administrators across all platforms (Windows, Mac and Linux). Its popularity in HTML programming also meant most administrators already had extensive exposure to the language.
Internally PaperCut uses the Rhino scripting engine maintained by Mozilla.org, makers of the popular
Firefox browser. It is highly performant and allows PaperCut NG to leverage advanced scripting without compromising system scalability. This is done using advanced techniques such as just-in-time compilation.
20.1.2. How to Use Print Scripts
Print scripts are segments of code that are run whenever a new print job arrives in the queue. The script is defined using the concept of a "hook". A hook is a JavaScript function (e.g.
function printJobHook(inputs, actions) { }
) that is called for each new job. Your print script defines this method, its behavior and its actions.
Print scripts are defined via Printers
→
[select printer]
→
Scripting.
All scripts are defined on a per printer basis allowing each printer to have its own logic (although it is possible to
into the editor and once completed can be saved using the Apply button. Errors raised by the script are displayed on this page.
321
Advanced Scripting (Print Scripting)
Tip
One good way of experimenting with print scripting is to apply your script initially on a test printer (or fake print queue such as a print queue pointing to an unused LPT port). This will allow you to test and experiment, and when the logic is right, copy/deploy across to other live printers.
Error messages are classed into two groups:
• Syntax errors - these are detected and displayed when a script is applied. The script will not save until all syntax errors are addressed.
Figure 20.3. Example syntax error in a print script
• Runtime errors - these are errors that only occur when a script is executed for a print job. Runtime errors are also listed on the Scripting tab in red. You may need to refresh the page to see runtime errors. Runtime errors are also logged and can be found on the App Log tab.
Figure 20.4. Example runtime error in a print script
Where possible the error message will indicate the line number on which the error was found and the relevant line will be highlighted.
The best way to start out writing print scripts is to first experiment with some of the recipes. Try importing a recipe on a test/non-production printer using the Import Recipe button. Recipes demonstrate best practice and should be considered as a starting point for development of your own scripts.
322
Advanced Scripting (Print Scripting)
Figure 20.5. Importing a print script recipe
Code snippets are small code fragments that demonstrate how to use make best use of the scripting API (inputs, functions and methods). Consider using snippets as a base for adding functionality to your script. Snippets are inserted at the current cursor location and accessed via the Insert Snippet at Cursor button.
Figure 20.6. Importing a print script snippet
323
Advanced Scripting (Print Scripting)
20.1.3. Advanced Print Scripting - Global Include Script
Large organizations with advanced print scripting requirements may need to share common code between different print scripts. Advanced scripting techniques can be used to build these common libraries.
Writing a common script allows reuse of JavaScript code and functions without needing to copy script code to all printers. Write the common script code in a file named print-script-common.js
and save it in the
[install-path]/server/custom directory. This script is included and executed automatically and functions created in this file are accessible from all print scripts.
Errors in the common print script are detected and displayed in the Scripting tab. The error message contains the name of the common script file, the error, and the line number where the error occurred. You may need to refresh the page to see these errors. These errors are also visible in the App. Log tab.
20.1.4. Tips for Print Scripts
1.
Use snippets and/or recipes where possible. They are tested and demonstrate best practice.
2.
Start out small and aim high. Don't try building your script all in one go. Write a bit, test, then move on. Large scripts written in one go are hard to debug.
3.
Always test your scripts! Just because a script compiles does not mean it is bug free. Take time to test your script and exercise all logic paths. For example, if your script applies an action to jobs with more than 100 pages, test it by printing jobs that are both more and less than 100 pages.
4.
Check all your scripts from time to time for runtime errors and/or enable error level event notifications to receive
an email when errors occur (see Section 15.6.2.3, “Error level event notifications”).
5.
Script API Reference”). Knowing what is possible will open up ideas.
6.
Use actions.log.debug() or actions.client.sendMessage() to assist with "print line" style debugging.
7.
If your scripts interact with end-users, perform some usability testing to ensure they understand your messages and intentions.
8.
Consider using HTML markup to pretty up your dialog messages (see the snippet titled Show a dialog with
HTML formatting).
20.2. Print Script API Reference
Print scripts are segments of code that are run whenever a new print job arrives. The script is defined using the concept of a "hook". A hook is a JavaScript function that is defined by you, the script writer. It is also commonly referred to as an entry point or method
. A number of print hooks (entry points) are available and each differ by the point in the print workflow when they are called. For example, a hook early in the workflow has the ability to influence behavior later in the flow, while scripts late will correspondingly have access to additional information that would not be available earlier. In most cases the generic main hook will satisfy most requirements.
Note
This API reference describing the all the properties and functions available to print scripts. Many of these inputs and functions reference JavaScript objects (e.g. String, Boolean, Date etc.). A good
JavaScript reference will assist with making use of and formatting these objects. A good reference can be found at the Mozilla Developer Center here: https://developer.mozilla.org/en/JavaScript/Reference.
20.2.1. Script Hooks (Entry Points)
The available print hooks are:
324
Advanced Scripting (Print Scripting)
Hook
printJobHook(inputs, actions) printJobAfterAccountSelectionHook(inputs, actions)
Other Hooks
Description
This is the main multi-purpose hook and will be suitable for most situations.
Point of Call: Immediately before account selection popup displays.
Suitability: Most situations as all print job inputs and most actions are available.
Limitations:
• Can't influence popup authentication behavior
• End-user account selection information is not available
This hook should only be used to perform actions that use the result of the account selection popup inputs.job.selectedSharedAccountName
).
(i.e.
accesses
Point of Call: Immediately after account selection popup displays (or would display if enabled).
Suitability: Only use when the result of the account selection is required.
Limitations:
• Can't influence account selection popup behavior or selected results
(because it's already been completed)
• Can't influence popup authentication behavior
If you have the need for another hook (e.g. pre-authentication), please explain your requirements to the support team. Your input can influence the development of future scripting features.
Table 20.1. Print Workflow Hooks
All print job hooks have access to job, printer and user information and can perform a variety of actions that affect the job processing. The scripts have access to these through the two function arguments:
• inputs
- Read-only access to the print job, user and printer information.
• actions
- Access to perform actions that can influence the job processing, e.g. to cancel a job or send a message to the client software.
inputs are read-only and any modification to variables will not affect the print job. All actions (also known as side-effects) must be performed via the available actions
. All available inputs and actions are listed below.
20.2.2. Script Inputs
20.2.2.1. Job Info (
inputs.job
)
Property/Method
inputs.job.date
inputs.job.username
inputs.job.printerServerName
inputs.job.printerName
inputs.job.fullPrinterName
inputs.job.documentName
inputs.job.isAnalysisComplete
Description
(date) The date/time the job was printed.
(string) The username of the user that printed the job.
(string) The name of the server the print queue is hosted on.
(string) The printer name.
(string) The full name of the printer including the server name, in the format server\printer
.
(string) The document name.
(boolean) Indicates that the print job has been completely analyzed. Before the job analysis is completed, only basic job information is available (e.g. date, username, printer, document name, client machine, etc). The detailed job information like page counts, paper size, costs, etc are only available after analysis is completed.
If scripts require access to the detailed information, they should only access these once the job analysis is completed. This is achieved by placing the
325
Property/Method
inputs.job.isWebPrintJob
inputs.job.jobSourceName
inputs.job.clientIP
inputs.job.clientMachineOrIP
inputs.job.selectedSharedAccountName
inputs.job.totalPages
inputs.job.totalSheets
inputs.job.totalColorPages
inputs.job.totalGrayscalePages
inputs.job.isGrayscale
inputs.job.isColor
inputs.job.isDuplex
inputs.job.cost
inputs.job.copies
inputs.job.spoolSizeKB
Advanced Scripting (Print Scripting)
Description
following snippet at the start of the print hook function: if (!inputs.job.isAnalysisComplete) { return;
}
This snippet will exit the script if analysis is not complete. Once analysis is completed the script will be called again and continue past this point.
(boolean) Determines if the job has been submitted by web print.
(string) The machine name of the client workstation where the job was printed, or the type of job if originating from Google Cloud Print
(GOOGLE_CLOUD_PRINT), Web Print (WEB_PRINT) or Email to Print
(EMAIL_PRINTING). May be blank if the client machine name is not known.
(string) The IP address of the client workstation where the job was printed. This may not be populated if the client IP address is not known.
(string) The machine name or IP address of the client workstation where the job was printed. If we know both the machine name and the IP address the machine name will be returned.
(string) The full name of the selected shared account. If no shared account is selected the an empty string is returned ("").
(Only available after the account selection is completed. i.e. from within the printJobAfterAccountSelectionHook hook.)
(number) The total number of pages in the print job.
(Only available when job analysis is complete. i.e.
isAnalysisComplete is true
.)
(number) The total number of sheets of paper produced by the job.
(Only available when job analysis is complete. i.e.
isAnalysisComplete is true
.)
(number) The total number of color pages in the print job.
(Only available when job analysis is complete. i.e.
isAnalysisComplete is true
.)
(number) The total number of grayscale pages in the print job.
(Only available when job analysis is complete. i.e.
isAnalysisComplete is true
.)
(boolean) Determines if the job is grayscale (i.e. contains no color).
(Only available when job analysis is complete. i.e.
isAnalysisComplete is true
.)
(boolean) Determines if the job is color (i.e. contains at least one color page).
(Only available when job analysis is complete. i.e.
isAnalysisComplete is true
.)
(boolean) Determines job is duplex.
(Only available when job analysis is complete. i.e.
isAnalysisComplete is true
.)
(number) The cost of the job.
(Only available when job analysis is complete. i.e.
isAnalysisComplete is true .)
(number) The number of copies. The totalPages attribute already takes the copies into account.
(Only available when job analysis is complete. i.e.
isAnalysisComplete is true
.)
(number) The size of the spool size in kilobytes (KB).
326
Property/Method
inputs.job.paperSizeName
inputs.job.printerLanguage
inputs.job.paperSizeHeightMM
inputs.job.paperSizeWidthMM
inputs.job.environmentBulbHours
inputs.job.environmentTrees
inputs.job.environmentGramsCO2
Advanced Scripting (Print Scripting) inputs.job.calculateCostForPrinter(printerName)
Description
(Only available when job analysis is complete. i.e.
isAnalysisComplete is true
.)
(string) The paper size name (e.g. Letter, Tabloid, A4, A3).
(Only available when job analysis is complete. i.e.
isAnalysisComplete is true
.)
(string) The printer language of the print job (e.g. PostScript, PCL5, etc).
(Only available when job analysis is complete. i.e.
isAnalysisComplete is true
.)
(number) The height of the paper size in millimetres (mm).
(Only available when job analysis is complete. i.e.
isAnalysisComplete is true
.)
(number) The width of the paper size in millimetres (mm).
(Only available when job analysis is complete. i.e.
isAnalysisComplete is true
.)
(number) The amount of energy used by this job in terms of the number of hours of use of a 60W light bulb.
(Only available when job analysis is complete. i.e.
isAnalysisComplete is true
.)
(number) The amount of paper used by this print job in terms of number of trees.
(Only available when job analysis is complete. i.e.
isAnalysisComplete is true
.)
(number) The amount of carbon dioxide (C02) produced by this print job.
(Only available when job analysis is complete. i.e.
isAnalysisComplete is true
.)
Calculates the cost of printing this job on another printer. This can be used to determine the "Least cost route" for this job. This returns the cost of the job.
Parameters:
• printerName
(string) - The name of the printer to calculate the cost of the job for. This can be entered as server\\printer or without the server name. If the server name is ommitted it is assumed the printer is on the same print server as the current job.
NOTE: The inputs.job.calculateCostForPrinter input requires the double
\ character.
Table 20.2. Job Info Script Reference ( inputs.job
)
20.2.2.2. User Info (
inputs.user
)
Property/Method
inputs.user.username
inputs.user.fullName
inputs.user.email
inputs.user.office
inputs.user.department
inputs.user.restricted
inputs.user.balance
Description
(string) The username of the user that printed the job.
(string) The full name of the user that printed the job (if known).
(string) The email address of the user that printed the job (if known).
(string) The office of the user that printed the job (if known).
(string) The deparment of the user that printed the job (if known).
(boolean) Determines if the user is restricted. i.e. printing is denied when they have no credit.
(number) The user's current account balance.
327
Property/Method
inputs.user.balance(accountName) inputs.user.isInGroup(groupName) inputs.user.getProperty(propName)
Advanced Scripting (Print Scripting) inputs.user.getNumberProperty(propName)
Description
(number) The user's current account balance.
Parameters:
• accountName
(string) - This is only valid when Multiple Personal Accounts
is enabled. This is an optional parameter to specify the personal account name. If not specified, it will retrieve the user's total account balance.
Determines if the user belongs to the given group name (as defined on the
Groups tab). Returns true if the user belongs to this group.
Parameters:
• groupName (string) - The name of the group to check. NOTE: The group name is case-sensitive.
Return a value as a string associated with a persistent custom-defined property saved on the user, or null if there is no such value.
Parameters:
• propName
(string) - The name/key of a user property to look-up.
For more information using storage properties see Section 20.2.4, “User
Defined Persistent Properties (Storage)”.
A convenience method to return a value as a number associated with a persistent custom-defined property saved on the user, or null if there is no such value.
Parameters:
• propName
(string) - The name/key of a user property to look-up.
For more information using storage properties see Section 20.2.4, “User
Defined Persistent Properties (Storage)”.
Table 20.3. User Info Script Reference ( inputs.user
)
20.2.2.3. Client Info (
inputs.client
)
Property/Method
inputs.client.isRunning
Description
(boolean) Determines if the user who printed the job is running the user client software. This can be used to adapt the script to handle when a client isn't running. e.g. Only display a popup question when the client is running.
The client is considered "running" if there was activity from that client within the last 5 minutes.
Table 20.4. Client Info Script Reference ( inputs.client
)
20.2.2.4. Printer Info (
inputs.printer
)
Property/Method
inputs.printer.serverName
inputs.printer.printerName
inputs.printer.fullPrinterName
inputs.printer.isVirtualQueue
inputs.printer.isDisabled
inputs.printer.isStatusError
Description
(string) The name of the server where the printer is hosted.
(string) The name of the printer.
(string) The full name of the printer in format server/printer
.
(boolean) Determines if this printer is a virtual queue.
(boolean) Determines if this printer is currently disabled.
(boolean) Determines if this printer is currently in an error state (e.g. paper jam, offline, etc.)
328
Property/Method
inputs.printer.statusInErrorSince
inputs.printer.statusInErrorSeconds
inputs.printer.groups
inputs.printer.isInGroup(groupName)
Advanced Scripting (Print Scripting) inputs.printer.getProperty(propName) inputs.printer.getNumberProperty(propName)
Description
(date) The time when the printer went into this error state.
(number) The number of seconds since the printer has been in error.
(Array) An array of all the printer groups that this printer is a member of.
(boolean) Determines if the printer belongs to a particular printer group. Returns true if the printer belongs to this group.
Parameters:
• groupName
(string) - The name of the printer group to check.
Return a value as a string associated with a persistent custom-defined property saved on the printer, or null if there is no such value.
Parameters:
• propName
(string) - The name/key of a printer property to look-up.
For more information using storage properties see Section 20.2.4, “User
Defined Persistent Properties (Storage)”.
A convenience method to return a value as a number associated with a persistent custom-defined property saved on the printer, or null if there is no such value.
Parameters:
• propName
(string - The name/key of a printer property to look-up.
For more information using storage properties see Section 20.2.4, “User
Defined Persistent Properties (Storage)”.
Table 20.5. Printer Info Script Reference ( inputs.printer
)
20.2.2.5. Utilities (
inputs.utils
)
Method
inputs.utils.formatBalance(amount) inputs.utils.formatCost(amount) inputs.utils.formatNumber(amount, decimals) inputs.utils.getProperty(propName)
Description
Formats the balance amount based on the server currency settings. Returns a string.
Parameters:
• amount
(number) - the amount to format.
Formats the cost amount (e.g. a job cost) based on the server currency settings.
Returns a string.
Parameters:
• amount
(number) - the amount to format.
Formats a number with the given number of decimal places. Returns a string.
Parameters:
• amount
(number) - the amount to format.
• decimals (number) - The number of decimal places to format.
Return a value as a string associated with a persistent custom-defined global property, or null if there is no such value.
Parameters:
• propName
(string) - The name/key of a global property to look-up.
For more information using storage properties see Section 20.2.4, “User
Defined Persistent Properties (Storage)”.
329
Advanced Scripting (Print Scripting)
Method
inputs.utils.getNumberProperty(propName)
Description
A conveneince method to return a value as a number associated with a persistent custom-defined global property, or null if there is no such value.
Parameters:
• propName
(string) - The name/key of a global property to look-up.
For more information using storage properties see Section 20.2.4, “User
Defined Persistent Properties (Storage)”.
Table 20.6. Utilities Script Reference ( inputs.utils
)
20.2.3. Script Actions
20.2.3.1. Job Actions (
actions.job
)
Method
actions.job.addComment(comment) actions.job.setCost(cost) actions.job.cancel() actions.job.cancelAndLog([comment]) actions.job.chargeToPersonalAccount() actions.job.chargeToSharedAccount(accountName)
330
Description
Appends a comment to the job. This will be logged to the database and is available in the job logs and reports. If the job already has a comment (e.g. set by the user with the advanced client) then this will append to the existing comment.
Parameters:
• comment
(string) - The comment to add to the print job.
Sets the cost of the print job. NOTE: If there are other cost adjustments configured (e.g. user cost overrides), these may further modify the job cost later in the job processing.
Parameters:
• cost
(number) - The cost of the job. Must be greater than or equal to 0.
Cancels the current print job so that it will not be printed. It will not log the cancelled job. To log the job use actions.job.cancelAndLog
. The script should typically exit using return after cancelling the job.
Cancels the current print job and logs it under job logs. It can also add a comment to the job which is then available in the job logs and reports. The script should typically exit using return after cancelling the job.
Parameters:
• comment
(string) - An optional parameter to add a comment to the print job.
Disables any client popups and account selection, and charges the job to the user's personal account.
NOTE: If you're using this in conjunction with e.g. inputs.job.jobSourceName to suppress popups when processing e.g. Google Cloud Print jobs, you'll need to remove the initial loop in the script that checks for inputs.job.isAnalysisComplete
being true. The reason being is that if this action happens after the analysis completes, that may be too late to suppress the client popup.
Disables any client popups and account selection, and charges the job to the specified shared account.
Parameters:
• accountName
(string) - The name of the shared account. If the shared account is a sub-account then the account name must be provided in the format parentName\\subName .
NOTE 1: The actions.job.chargeToSharedAccount action requires the double
\ character.
NOTE 2: If you're using this in conjunction with e.g. inputs.job.jobSourceName
to suppress popups when processing e.g. Google Cloud Print jobs, you'll need to remove the initial loop in the script that checks for inputs.job.isAnalysisComplete being true. The reason being is that if this action happens after the analysis completes, that may be too late to suppress the client popup.
actions.job.bypassReleaseQueue() actions.job.holdInReleaseQueue([mode]) actions.job.bypassFilters() actions.job.convertToGrayscale() actions.job.convertToDuplex()
Advanced Scripting (Print Scripting)
Method
actions.job.redirect(printerName[, options])
Description
Schedules the job to be redirected to the given printer queue. The job is redirected after it has completed processing (e.g. after print popups are acknowledged, filters are run, and the job is released from the hold/release queue).
NOTE 1: Jobs should only be redirected between compatible printers (e.g.
those that support the same printer language and features). For more
information see Section 14.3, “Requirements For Job Redirection (Load
Balancing or Find Me Printing)”.
NOTE 2: By default, once a job is redirected it will be printed on the destination queue. You may not run another script or use print popups at the destination queue. If you wish the job to be held at the destination queue, you must specify the option: allowHoldAtTarget:true.
Parameters:
• printerName
(string) - The name of the printer to redirect to. This can be entered as server\printer or without the server name. If the server name is omitted it is assumed the printer is on the same print server as the current job.
• options
(object/dictionary) - An optional parameter defining the additional options to the redirect command. Options include:
• allowHoldAtTarget
(boolean) - Determines whether the job will hold in the destination printer's hold/release queue if present. Although the job appears in the destination's hold/release queue, it is not physically redirected until printed. Default: false
.
• recalculateCost (boolean) - Determines whether to recalculate the cost based on the settings of the destination printer. Default: false
.
Example 1: Redirect to a printer named "server\Fast Printer".
actions.job.redirect("server\\Fast Printer");
Example 2: Redirect to a virtual queue named "server\Utility Room". The job will hold at the release station.
actions.job.redirect("server\\Utility Room",
{allowHoldAtTarget: true});
Example 3: Redirect to a virtual queue named "server\Utility Room", recalculating the cost based on the cost settings of the destination printer.
actions.job.redirect("server\\Utility Room",
{allowHoldAtTarget: true, recalculateCost: true});
NOTE 3: The actions.job.redirect() action requires the double
\ character.
Allows this job to pass through the queue without being held in a hold/release queue.
Holds this job in a hold/release queue that it was printed to. If the mode argument is omitted the job will be held in "User-release" mode.
Parameters:
• mode (string) - An optional parameter defining the release station mode. If set to user-release
, the user can release the job.
If set to manager-release
, only an admin or print release manager can release the job. Default: user-release
Allows this job to pass through the queue without being denied by the configured print filters/restrictions.
Convert this job to grayscale (if it is not already grayscale). The job's cost will be recalculated after conversion to grayscale.
For more information and troubleshooting with job conversions please see
Section 7.7.2, “Print Conversion Filters in Detail”.
Convert this job to duplex (if it is not already duplex). The job's cost will be recalculated after conversion to duplex.
For more information and troubleshooting please see Section 7.7.2, “Print
Conversion Filters in Detail”.
331
Advanced Scripting (Print Scripting)
Method
actions.job.changeNumberOfCopies(newCopies) actions.job.changeDocumentName(documentName)
Description
Change the number of copies in this job. E.g. change to print 4 copies instead of
1 copy. This should only be used to increase the copy count from 1, not to reduce the count or change in other ways. The job's cost will be recalculated after the number of copies has been changed. This feature may not be available for all print drivers.
For more information and troubleshooting please see Section 7.7.2, “Print
Conversion Filters in Detail”.
Parameters:
• newCopies
(number) - The new number of copies to print.
Note: changing the number of copies is experimental and may not work on all
devices. If you experience problems and the steps in Section 7.7.2.2,
“Troubleshooting” do not assist, please contact support for assistance.
Changes the name of the document that will be logged in the database.
Parameters:
• documentName
(string) - The new name of the document.
actions.job.changeUser(username) actions.job.disableArchiving() actions.job.setWatermark(text)
Changes the user associated with the job (i.e. the user will be logged as the user that printed the job).
Parameters:
• username
(string) - The username of the user.
actions.job.changePersonalAccountChargePriority(accountNames) Allows overriding which of a users' personal accounts to charge and in which order/priority. This can be useful when a printer can only be used when credit is available in a particular subset of user personal accounts (e.g. department allocated quotas). Only those accounts listed will be charged for the job. If credit isn't available in the listed accounts the jobs is denied.
NOTE: This is only valid when Multiple Personal Accounts is enabled. See
Chapter 32, Multiple Personal Accounts.
Parameters:
• accountNames
(array of strings) - the list of personal account names (as configured in Options
→
Advanced.) in the order they should be charged.
e.g.
["Default", "Cash"]
. When searching for the account names the case differences are ignored. If any of the accounts supplied to do not exist then an entry is written to the server log. If no valid accounts are found then the personal account charge priority is unchanged.
Example: To allow the jobs to be only charge to the accounts "Science
Department" and "Cash" (in that order) actions.job.changePersonalAccountChargePriority(
["Science Department", "Cash"]);
Disable print job archiving if it's been enabled for this job.
Sets the watermark text for this job. Watermarking allows text to be added on each printed page, e.g. the date and name of the user who printed the job.
NOTE: Using an empty string will disable the watermark, overriding a queue-level setting. Example: actions.job.setWatermark("");
Parameters:
• text
(string) - the watermark text to add to each page of the job. The text may include replacement variables such as "%user%" (replaced with the username of the user who printed the job). An empty string will disable watermarking for this job.
For more information about watermarking and the replacement variables that can be used in text
see Section 7.13, “Watermarking/Job Annotation”.
Table 20.7. Job Actions Script Reference ( actions.job
)
20.2.3.2. Client Actions (
actions.client
)
332
Advanced Scripting (Print Scripting)
The client actions allow a script to send messages to the user client and prompt the user for a variety of questions.
These require that the user is running the client software.
Method
actions.client.sendMessage(message)
Description
Sends a message to the user. This message is typically displayed as a task tray popup on Windows. Unlike the prompt actions, the user does not need to acknowledge the message to allow the job to print.
Parameters:
• message
(string) - the message to display to the user.
actions.client.promptOK(message[, options]) actions.client.promptOKCancel(message[, options]) actions.client.promptPrintCancel(message[, options]) actions.client.promptYesNo(message[, options])
Prompts the user with the message dialog that displays an OK button. Returns a string:
•
"OK"
- if the user presses the OK button.
•
"TIMEOUT"
- If the user does not respond within the timeout period.
Parameters:
• message
(string) - the message to display to the user. For information on
formatting messages see Section 20.2.3.2.2, “Client Prompt Message
• options
(object/dictionary) - Options to change the behavior of the prompt.
For the standard prompt options see Section 20.2.3.2.1, “Client Prompt
Prompts the user with the message dialog that displays an OK and Cancel button. Returns a string:
•
"OK"
- if the user presses the OK button.
• "CANCEL" - if the user presses the OK button.
•
"TIMEOUT"
- If the user does not respond within the timeout period.
Parameters:
• message (string) - the message to display to the user. For information on
formatting messages see Section 20.2.3.2.2, “Client Prompt Message
• options
(object/dictionary) - Options to change the behavior of the prompt.
For the standard prompt options see Section 20.2.3.2.1, “Client Prompt
Prompts the user with the message dialog that displays a Print and Cancel button. Returns a string:
•
"OK"
- if the user presses the OK button.
•
"CANCEL"
- if the user presses the OK button.
•
"TIMEOUT"
- If the user does not respond within the timeout period.
Parameters:
• message
(string) - the message to display to the user. For information on
formatting messages see Section 20.2.3.2.2, “Client Prompt Message
• options
(object/dictionary) - Options to change the behavior of the prompt.
For the standard prompt options see Section 20.2.3.2.1, “Client Prompt
Prompts the user with the message dialog that displays a Yes and No button.
Returns a string:
• "YES" - if the user presses the Yes button.
•
"NO"
- if the user presses the No button.
•
"TIMEOUT"
- If the user does not respond within the timeout period.
Parameters:
• message
(string) - the message to display to the user. For information on
formatting messages see Section 20.2.3.2.2, “Client Prompt Message
• options (object/dictionary) - Options to change the behavior of the prompt.
333
Advanced Scripting (Print Scripting)
Method Description
For the standard prompt options see Section 20.2.3.2.1, “Client Prompt
actions.client.promptYesNoCancel(message[, options]) actions.client.promptForText(message[, options])
Prompts the user with the message dialog that displays a Yes, No and Cancel button. Returns a string:
•
"YES"
- if the user presses the Yes button.
•
"NO"
- if the user presses the No button.
•
"CANCEL"
- If the user presses the Cancel button.
•
"TIMEOUT"
- If the user does not respond within the timeout period.
Parameters:
• message
(string) - the message to display to the user. For information on
formatting messages see Section 20.2.3.2.2, “Client Prompt Message
• options
(object/dictionary) - Options to change the behavior of the prompt.
For the standard prompt options see Section 20.2.3.2.1, “Client Prompt
Prompts the user with the message dialog that prompts the user to enter text, and shows an OK and Cancel button. Returns a string:
• [user entered text] - if the users enters text and presses OK.
•
"CANCEL"
- If the user presses the Cancel button.
•
"TIMEOUT"
- If the user does not respond within the timeout period.
Parameters:
• message
(string) - the message to display to the user. For information on
formatting messages see Section 20.2.3.2.2, “Client Prompt Message
• options
(object/dictionary) - Options to change the behavior of the prompt.
For the standard prompt options see Section 20.2.3.2.1, “Client Prompt
Standard Options”. Additional options include:
• defaultText
(string) - The text that will pre-populate the text entry field.
• fieldLabel
(string) - The label displayed on the left side of the text field. By default no field label is displayed, and the text-box fills the full width of the dialog.
actions.client.promptForPassword(message[, options])
Prompts the user with the message dialog that prompts the user to enter a password, and shows an OK and Cancel button. User input will be masked.
Note that this function simply masks user input - it does not perform any actual password authentication. Returns a string:
•
[user entered text]
- if the users enters text and presses OK.
•
"CANCEL"
- If the user presses the Cancel button.
•
"TIMEOUT"
- If the user does not respond within the timeout period.
Parameters:
• message
(string) - the message to display to the user. For information on
formatting messages see Section 20.2.3.2.2, “Client Prompt Message
• options
(object/dictionary) - Options to change the behavior of the prompt.
For the standard prompt options see Section 20.2.3.2.1, “Client Prompt
Standard Options”. Additional options include:
• defaultText (string) - The text that will pre-populate the text entry field.
• fieldLabel
(string) - The label displayed on the left side of the text field. By default no field label is displayed, and the text-box fills the full width of the dialog.
actions.client.promptForChoice(message, choices[, options])
Prompts the user with the message dialog that prompts the user to select from one or more choices from a drop-down list, and shows an OK and Cancel button. Returns a string:
•
[user selected choice]
- The selected choice item.
•
"CANCEL"
- If the user presses the Cancel button.
•
"TIMEOUT"
- If the user does not respond within the timeout period.
334
Advanced Scripting (Print Scripting)
Method
actions.client.promptForForm(htmlForm[, options])
Description
Parameters:
• message
(string) - the message to display to the user. For information on
formatting messages see Section 20.2.3.2.2, “Client Prompt Message
• choices
(array of strings) - the list of choices to display in the drop-down list. e.g.
["Unclassified", "Restricted", "Top secret"]
• options
(object/dictionary) - Options to change the behavior of the prompt.
For the standard prompt options see Section 20.2.3.2.1, “Client Prompt
Standard Options”. Additional options include:
• defaultChoice
(string) - The default choice which is pre-selected for the user. This must match one of the provided choices.
• fieldLabel
(string) - The label displayed on the left side of the drop-down box. By default no field label is displayed, and the drop-down fills the full width of the dialog.
Prompts the user with a dialog containing a multiple input field form. The dialog also shows OK and Cancel buttons. The input fields and layout are defined using HTML with form elements. The htmlForm parameter must contain valid
HTML including at least one or more form elements such as <input>. When the user presses the OK button, the form data is returned in a JavaScript object where the values may be retrieved using the field name.
e.g.
response['fieldName']
:
•
[JavaScript object containing form data]
- when the users enters text and presses OK. To retrieve the value of the field named fieldName use response['fieldName'].
•
"CANCEL"
- If the user presses the Cancel button.
•
"TIMEOUT"
- If the user does not respond within the timeout period.
Parameters:
• htmlForm
(string) - the HTML form/message to display to the user. The
HTML needs to include one or more HTML input elements - including text fields (normal, password or multi-line), radio boxes, check boxes and choice lists. Each form element must have a unique name that is used to identify the field when the user's input is returned to the server. For information on
formatting messages see Section 20.2.3.2.2, “Client Prompt Message
• options (object/dictionary) - Options to change the behavior of the prompt.
For the standard prompt options see Section 20.2.3.2.1, “Client Prompt
Use of promptForForm is demonstrated in a code snippet and in a recipe.
Table 20.8. Client Actions Script Reference ( actions.client
)
20.2.3.2.1. Client Prompt Standard Options
All the client prompt options have an options parameter to customize the prompt behavior. Some prompt types have additional options, but all prompt types have the following options:
• dialogTitle
(string) - The title of the dialog.
• dialogDesc
(string) - The brief one-line description to complement the dialog title.
• hideJobDetails
(boolean) - Used to hide the job details from the user. e.g. document name, printer name, pages, cost, etc. Default: false
- the job details are displayed.
• timeoutSecs
(number) - The number of seconds to wait for a response from the user. Once this time elapses, the prompt method returns
"TIMEOUT"
. The default timeout is 5 minutes (300 seconds).
• questionID
(string) - Uniquely identifies a question for a given print job and script. Once a user has responded to a prompt with a given questionID
, the result will be remembered and the user will not be prompted again for this job. This is important as the print script may be called repeatedly if jobs are held awaiting prompts, popups or are held in a release queue. If the questionID is not provided, the question ID is automatically generated based on the prompt parameters (e.g. message, buttons, choices, etc).
The questionID is rarely required, only in the following cases:
335
Advanced Scripting (Print Scripting)
• If the same prompt/question is required multiple times for a single script, and the user must answer each time. Assigning a different questionID to each prompt will ensure that the user is re-prompted.
• If the message of a prompt changes with each call. e.g. if the message included the current time it would change each time the prompt was called. Another example is if the message includes the user's balance, this might change if they are printing multiple print jobs. Both of these would cause the multiple prompts to appear. Assigning a questionID will avoid this re-prompting.
• When performing validation of user-entered text from a text prompt in a while loop. A unique questionID should be assigned with each loop iteration, otherwise the user will not be reprompted and an infinite loop will occur (PaperCut NG will detect this and cancel the script execution).
• fastResponse
(boolean) - When set to true
PaperCut will enable fast response mode to retrieve the response to the client prompt more quickly. This is only useful when displaying a sequence of prompts, and will cause the next prompt to display more quickly.
IMPORTANT: This setting is only useful when displaying a sequence of prompts. Care should be taken when enabling this option as it may cause increased load on the server.
You might also want to consider displaying a multi-input form instead of separate prompts. See actions.client.promptForForm() for details.
20.2.3.2.2. Client Prompt Message Formatting
The client prompts allow the administrator to display a message to the user and ask for user input. The dialog messages provide a subset of the most useful HTML formatting options. You can use them to make your message stand out and grab the user's attention.
Plain text formatting:
To use plain text formatting simply provide a standard JavaScript string as the message parameter. To start a new line, use the new line character
\n
. e.g.
actions.client.promptOK("First line\n\nSecond line");
HTML formatting:
The dialogs messages HTML formatting that provides a large subset of the most useful HTML formatting options. So you can get creative and make your message stand out and grab the user's attention.
To enable HTML formatting, surround the message text in
<html> and
</html> tags. Below is a very simple example that shows the word bold in bold.
actions.client.promptOK("<html>This is <b>bold</b></html>");
The client dialogs support many of the commonly used HTML features/elements including:
• Bold text -
<b>
• Colored text -
<span style='color: red'>
• Images -
<img src='http://host.com/image.jpg'>
• Line breaks -
<br>
• Font sizes -
<span style='font: 14px'>
• Bullet lists -
<ul> / <li>
• Numbered lists -
<ol> / <li>
• Horizontal rule -
<hr>
336
Advanced Scripting (Print Scripting)
• Text Field Input -
<input name="comment">
(only valid in actions.client.promptForForm
)
The dialog below shows most of the formatting options outlined above. The code for this dialog is available in the
"Show a dialog with HTML formatting" snippet.
Figure 20.7. Print Script Client Prompt with HTML formatting
Tip
To reference an image stored in the directory
[app-path]/server/custom/web/my-image.jpg
use the HTML:
<img src='http://%PC_SERVER%/custom/my-image.jpg'>
The special substitution variable
%PC_SERVER% is expanded to the name and port of your active
PaperCut server.
20.2.3.3. Log Actions (
actions.log
)
Method
actions.log.info(message)
Description
Logs an informational message to the App. Log.
Parameters:
• message
(string) - the message to log.
337
Advanced Scripting (Print Scripting)
Method
actions.log.warning(message) actions.log.error(message) actions.log.debug(message)
Description
Logs an warning message to the App. Log.
Parameters:
• message
(string) - the message to log.
Logs an error message to the App. Log.
Parameters:
• message
(string) - the message to log.
Logs a message to the server's text-based log file
( [app-path]/server/logs/server.log
). This can be helpful to diagnose problems with print scripts.
Parameters:
• message
(string) - the message to log.
Table 20.9. Log Actions Script Reference ( actions.log
)
20.2.3.4. Utility Actions (
actions.utils
)
Method
actions.utils.sendEmail(recipient, subject, body) actions.utils.sendEmail(recipients, subject, body)
Description
Sends an email to an email address or username.
Parameters:
• recipient
(string) - either the email address or username of the email recipient.
• subject
(string) - subject text of the email.
• body
(string) - body text of the email.
Sends an email to one or many email addresses or usernames.
Parameters:
• recipients
(array of strings) - either the email addresses or usernames of the email recipients.
• subject
(string) - subject text of the email.
• body
(string) - body text of the email.
Example: to send an email to many email addresses or usernames actions.utils.sendEmail(
["Administrator", "[email protected]"],
"Oh no!", "we're out of print credit!"); actions.utils.onCompletionSaveProperty(propName, options]) value[,
Saves a global value as a string associated with a persistent custom-defined property. This operation is performed once the print script completes and the print-job is printed.
Parameters:
• propName
(string) - the name/key of the property to set.
• value
(string) - the property value. Note: Numbers will be converted to a string.
• options
(object/dictionary) - options to modify behavior of the command.
• saveWhenCancelled
(boolean) - If set to true
, the operation is performed even if the print job is cancelled (eg. insufficient credit). By default, this is set to false
.
For more information using storage properties see Section 20.2.4, “User
Defined Persistent Properties (Storage)”.
actions.utils.onCompletionIncrementNumberProperty(propName, value[, options])
338
A convenience method to increment a global number value associated with a persistent custom-defined property. This operation is performed once the print
Advanced Scripting (Print Scripting)
Method Description
script completes and the print-job is printed.
Parameters:
• propName
(string) - the name/key of the property to set.
• value (number) - the amount to increment by. A negative number will decrement.
• options (object/dictionary) - options to modify behavior of the command.
• saveWhenCancelled
(boolean) - If set to true
, the operation is performed even if the print job is cancelled (eg. insufficient credit). By default, this is set to false
.
For more information using storage properties see Section 20.2.4, “User
Defined Persistent Properties (Storage)”.
Table 20.10. Utility Actions Script Reference ( actions.utils
)
20.2.3.5. User Actions (
actions.user
)
Method
actions.user.onCompletionSaveProperty(propName, options])
Description
value[,
Saves a value on the user as a string associated with a persistent custom-defined property. This operation is performed once the print script completes and the print-job is printed.
Parameters:
• propName
(string) - the name/key of the property to set.
• value
(string) - the property value. Note: Numbers will be converted to a string.
• options
(object/dictionary) - options to modify behavior of the command.
• saveWhenCancelled
(boolean) - If set to true
, the operation is performed even if the print job is cancelled (eg. insufficient credit). By default, this is set to false
.
actions.user.onCompletionIncrementNumberProperty(propName, value[, options])
For more information using storage properties see Section 20.2.4, “User
Defined Persistent Properties (Storage)”.
A convenience method to increment a number value on the user associated with a persistent custom-defined property. This operation is performed once the print script completes and the print-job is printed.
Parameters:
• propName
(string) - the name/key of the property to set.
• value
(number) - the amount to increment by. A negative number will decrement.
• options
(object/dictionary) - options to modify behavior of the command.
• saveWhenCancelled
(boolean) - If set to true
, the operation is performed even if the print job is cancelled (eg. insufficient credit). By default, this is set to false
.
For more information using storage properties see Section 20.2.4, “User
Defined Persistent Properties (Storage)”.
Table 20.11. User Actions Script Reference ( actions.user
)
20.2.3.6. Printer Actions (
actions.printer
)
Method Description
actions.printer.onCompletionSaveProperty(propName, value[, options])
Saves a value on the printer as a string associated with a persistent custom-defined property. This operation is performed once the print script completes and the print-job is printed.
Parameters:
• propName (string) - the name/key of the property to set.
• value
(string) - the property value. Note: Numbers will be converted to a string.
339
Advanced Scripting (Print Scripting)
Method Description
• options
(object/dictionary) - options to modify behavior of the command.
• saveWhenCancelled
(boolean) - If set to true
, the operation is performed even if the print job is cancelled (eg. insufficient credit). By default, this is set to false
.
For more information using storage properties see Section 20.2.4, “User
Defined Persistent Properties (Storage)”.
actions.printer.onCompletionIncrementNumberProperty(propName,
A convenience method to increment a number value on the printer associated value[, options]) with a persistent custom-defined property. This operation is performed once the print script completes and the print-job is printed.
Parameters:
• propName
(string) - the name/key of the property to set.
• value
(number) - the amount to increment by. A negative number will decrement.
• options
(object/dictionary) - options to modify behavior of the command.
• saveWhenCancelled
(boolean) - If set to true
, the operation is performed even if the print job is cancelled (eg. insufficient credit). By default, this is set to false
.
For more information using storage properties see Section 20.2.4, “User
Defined Persistent Properties (Storage)”.
Table 20.12. Printer Actions Script Reference ( actions.printer
)
20.2.4. User Defined Persistent Properties (Storage)
Print scripts have the ability to store or save information between executions. They allow script authors to implement advanced logic which takes advantage of not just the current print event information, but any information that has been stored by previous script events. Properties also can be used to share data between different scripts. Some ideas that can be implemented with print script properties could include:
• Rate limits – knowledge of previous jobs in the given period need to be stored/known.
• Detecting duplicate events/situations over time.
• Detecting repeatable user behavior. e.g. how many times a user uses duplex in a row.
• Shared settings between scripts . e.g. Global defined configuration variables/settings.
Properties are key-value pair storage which are associated with a user or printer, or optionally can be global. Keys are Strings that uniquely define the property. Values are stored as Strings and hence values can be any data that can be converted to and from a string. The maximum length of a key is 70 characters, and the value is 1,000 characters.
20.2.4.1. Working with properties
Properties are fetched via the getProperty call on the associated source. For example, to fetch a property stored on the user associated with the print job, use inputs.user.getProperty("my-key")
. Printer properties are fetched via inputs.printer.getProperty()
, and global via inputs.utils.getProperty()
. There exists a set of convenience methods called getNumberProperty() if dealing exclusively with a number.
By default, properties are only saved (to the database) after the print script completes and the job is printed (i.e. not cancelled or denied). If saving/incrementing properties on job cancellation is required (e.g. the user has insufficient credit, or actions.job.cancel
is called, use the saveWhenCancelled optional argument. For example, to set a property on the user, use: actions.user.onCompletionSaveProperty("my-key", "my-value")
The same command with "save on cancellation" behavior enabled is:
340
Advanced Scripting (Print Scripting) actions.user.onCompletionSaveProperty("my-key", "my-value", {'saveWhenCancelled' : true})
Tip
Global properties are stored as PaperCut config settings and hence can be edited by any priviledge system administrator. You can find your properties via Options
→
Actions
→
Config editor
(Advanced). All script properties are prefixed with script.user-defined.
and are searchable by name. Hence global properties are a great way to define editable configuration values that are shared between scripts.
20.2.4.2. Implementing Counters (Advanced)
There are two ways to implement a counter (e.g. a page number count). One approach is to simply get the current value, increment, then save. On high volume networks there exists the possibility of another event overwriting the value.
Print scripts provide a convenience method which avoids this called onCompletionIncrementNumberProperty()
. See the recipe "Prevent overuse of lab printers (rate limiting)" for an example.
20.2.5. Print Script Requirements (Advanced)
These notes are intended for advanced developers "pushing the limits" of print script functionality. All print scripts must conform to the following technical requirements:
1.
Timeouts: All scripts execution logic should complete within 5 seconds of CPU time. Failure to comply - say due to an infinite loop - will result in the script terminating and raising a runtime error. Five seconds should be adequate as even the most advanced example recipes complete within a few milliseconds.
2.
Reentrant and Idempotent: All scripts should be reentrent - designed to be called multiple times for the same job, each time producing the same result/behavior. For example your script will be called multiple times at various stages of analysis and it's expected to provide the same output given the same input. Side-effects based off logic other than the inputs are not recommended. For example, logic based off the result of
Math.random() would violate this principle.
3.
New APIs: If you have a need for new APIs, please email the developers. We have a number planned such as the ability to influence account selection popup behavior, options to store/persist attributes on users and printers, exec external processes, and more layout options for dialogs. Please share your ideas!
341
Chapter 21. Licensing and Support
This section describes how to install the PaperCut NG license you receive after purchase, and also provides information about gaining support and assistance.
21.1. Installing a License
PaperCut NG licenses are issued as a digitally signed file. Installing the license file into the application enables the software for use within your organization.
To install the license file supplied by your vendor:
1.
Save the license file to your hard disk. Your desktop is a handy location. Files are typically named
PaperCut
NG-[orgname].license
.
Tip
There is no need to unzip the file. The file can be loaded into the system as supplied.
2.
Log into the PaperCut NG administration interface.
3.
Navigate to the About page.
4.
Scroll down to the Register section and click the Browse... button.
5.
Locate the license file saved in step 1 and click Open.
6.
Click the Install license button.
7.
Verify license information is correctly listed in the About page.
Note
The file supplied is simply a digitally signed and zipped text file containing your license information. It's converted to ZIP format to minimize size. If you're interested in viewing the contents of the file, rename the file to .zip and simply open it in any ZIP extraction utility.
If you have a question about your license or need assistance please email the PaperCut Software International Pty
Ltd technical support team and they will be more than happy to assist you.
21.2. Technical Support & Further Information
The PaperCut Software development team is always happy to assist customers with further technical questions.
Please feel free to contact us via email or phone. The development team may also be contacted via the live web chat feature available on the PaperCut Software International Pty Ltd website at http://www.papercut.com/.
You may also find lots of other useful information in the Knowledge Base located at: http://www.papercut.com/kb/
The Knowledge Base is updated regularly and is a good place to start if your question is not addressed in this user manual.
342
Chapter 22. Deployment on an External
Database (RDBMS)
22.1. Overview
This section describes the process of running PaperCut NG on an external relational database, and describes why an organization would choose to do this. By default PaperCut NG uses an internal database product known as
Apache Derby. This database engine was donated to Apache by IBM and was previously known as IBM
Cloudscape.
22.1.1. Why use an external RDBMS?
The internal PaperCut NG database is stable, scalable, self-maintaining and provides very good performance. For this reason most organizations do not need to run PaperCut NG on an external database system. However there are some good reasons to run PaperCut NG on an external RDBMS, including:
• Your organization has existing database infrastructure and would like to consolidate all applications on the same database platform.
• Your organization has an existing database maintenance and backup procedure and would like PaperCut NG to take advantage of this.
• People would like to use 3rd party reporting and analysis tools (like Crystal Reports or Microsoft Access) to view and analyze the PaperCut NG database.
• Your organization is very large and requires the performance benefits of a dedicated RDBMS. This also allows the database to reside on a separate server to PaperCut NG, which improves the system scalability.
22.1.2. Supported Databases
PaperCut Software International Pty Ltd supports the following external databases out-of-the-box:
• Microsoft SQL Server 2000/2005/2008/2012/2014 (either 32 or 64 bit)
• Microsoft SQL Express 2005/2008/2012 (free from Microsoft)
• PostgreSQL 7.1+ (a free open source database)
• MySQL 5.0+ (a free open source database)
• Oracle 9.2+ (including the free Oracle Express Edition).
These databases were chosen to cater for the majority of our customers. For more information on supported databases, see the External Database Support Policy [http://www.papercut.com/kb/Main/ExternalDatabases].
22.2. Upsizing to an External RDBMS
Upsizing to an external RDBMS is a simple process that should take approximately 15-30 minutes. The high-level steps to upsize are:
1.
Backup the existing data.
2.
Create and initialize the new database.
3.
Load the backed-up data into the new database.
4.
Restart the application.
These steps are discussed in detail below.
This chapter also includes some sections that describe database specific configuration. See Section 22.3,
343
Deployment on an External Database (RDBMS)
“Database specific configuration” for more details.
Important
Each application server requires exclusive access to an external database. i.e. A single database cannot be shared between more than one application server. If you are running multiple application servers (e.g. a test and production instance), then each must have a separate database.
22.2.1. Step 1 - Stop PaperCut NG
To upsize to an external database the application server must be stopped. This allows the data to be backed up, guaranteeing that all data is saved and ready to load into the new database.
22.2.2. Step 2 - Perform a backup of the existing data
Perform a backup of the database. This data will be loaded into the application in a following step. A detailed
discussion about backups can be found in Section 15.5, “System Backups”. To backup the database:
1.
On the server, open a command prompt. (If you are seeing 'Access Denied' errors, please run command prompt as Administrator).
2.
If running on Linux or Mac, use su or equivalent to become the identity of papercut. e.g.
Mac: sudo su - papercut
Linux: su - papercut
3.
Change ( cd
) to the server binaries directory. e.g.
Windows: cd "C:\Program Files\PaperCut NG\server\bin\win"
Mac: cd "/Applications/PaperCut NG/server/bin/mac"
Linux: cd ~papercut/server/bin/linux-*
4.
Run the following command: db-tools export-db
5.
The output of the above command shows the name of the backup file created. Take note of this because it will be required in a future step.
22.2.3. Step 3 - Create a new database in the external RDBMS
This step depends on the external database you are using, and it is assumed that the administrator knows how to create a new database. No matter what database is used the following steps must be performed:
1.
Create a new empty database for dedicated use by PaperCut NG. When creating the database make sure to select the correct character encoding for your language. IMPORTANT: The database should be created with an character encoding suitable for your language. For SQL Server, the character encoding is set in the Collation field on the new database screen. For other databases like PostgreSQL or MySQL it is recommended to select a unicode character set (like UNICODE or UTF8) that allows all possible characters to be stored.
2.
Create a new database user (and password) for the PaperCut NG to use to connect to the database.
3.
Assign the appropriate permissions to the new user to give them full access to the new database (e.g.
permission to create/drop tables, and select/insert/update/delete in all tables).
344
Deployment on an External Database (RDBMS)
Important
To use SQL Server you must ensure that SQL Server has the TCP protocol, and the server authentication option is set to "SQL Server and Windows Authentication".
Important
The database user created for PaperCut NG should only have minimal set of permissions required for the PaperCut application. The user should have full permissions to create/drop tables and have full access to any created tables. However, the user should not have permissions to access other databases installed on the database server.
22.2.4. Step 4 - Change the PaperCut NG connection details
The next step is to configure PaperCut NG to connect to the new external database. To do this:
1.
On the server, open the server config file:
[app-path]/server/server.properties
in a text editor (e.g. Notepad).
2.
Comment out the line: database.type=Internal by adding a
#
(hash) character to the beginning of the line.
3.
Find the database connection details for the database type you require (e.g. SQL Server or PostgreSQL), and uncomment the lines by removing the
#
(hash) characters.
4.
Set the username and password used to connect to the database database.username=[your-db-user] database.password=[your-db-password]
5.
Set the database URL, which describes the location and connection details of the external database. See below for details of the format of the database URLs for different database types.
22.2.4.1. SQL Server Database Connection URL Format
The SQL Server URL format is: jdbc:jtds:sqlserver://[server]/[database]
The
[server] parameter is the name of the server running the SQL Server database, and must be resolvable from the PaperCut NG server. If the SQL Server instance is running on the same machine then localhost can be used.
The
[database] parameter is the name of the SQL Server database you created in Step 3 above.
The default port is 1433, you may specify a different port in the URL if required.
345
Deployment on an External Database (RDBMS) jdbc:jtds:sqlserver://[server][:port]/[database]
When using SQL Server instances, the instance name is specified in the connection URL as follows: jdbc:jtds:sqlserver://[server]/[database];instance=[instancename]
22.2.4.2. SQL Server Express Database Connection URL Format
The SQL Server Express format is: jdbc:jtds:sqlserver://[server]:[port]/[database]
The
[server] parameter is the name of the server running the SQL Server database, and must be resolvable from the PaperCut NG server. If the SQL Server instance is running on the same machine then localhost can be used.
The
[port] parameter is the port the SQL Server Express edition is configured to listen on. For more information
on configuring SQL Express, please see Section 22.3.1, “Configuring Microsoft SQL Express”.
The
[database] parameter is the name of the SQL Server database you created in Step 3 above.
22.2.4.3. PostgreSQL Database Connection URL Format
The Postgres URL format is: jdbc:postgresql://[server]/[database]
The
[server] parameter is the name of the server running the PostgreSQL database, and must be resolvable from the PaperCut NG server. If the PostgreSQL instance is running on the same machine then localhost can be used.
The
[database] parameter is the name of the PostgreSQL database you created in Step 3 above.
22.2.4.4. MySQL Database Connection URL Format
The MySQL URL format is: jdbc:mysql://[server]/[database]
The
[server] parameter is the name of the server running the MySQL database, and must be resolvable from the
PaperCut NG server. If the MySQL instance is running on the same machine then localhost can be used.
The
[database] parameter is the name of the MySQL database you created in Step 3 above.
Important
See Section 22.3.2, “Configuring MySQL” for specific instructions to configure MySQL.
22.2.4.5. Oracle Database Connection URL Format
346
Deployment on an External Database (RDBMS)
The Oracle URL format is: jdbc:oracle:thin:@[server]:[port]/[ServiceName]
The
[server] parameter is the name of the server running the Oracle database, and must be resolvable from the
PaperCut server. If the Oracle instance is running on the same machine then localhost can be used.
The
[port] specifies the port number that the Oracle services are listening on. By default this is 1521.
The
[ServiceName] specifies the Oracle service name or identifier used to identify the database. For Oracle
Express edition this is
XE
.
E.g. for an Oracle Express Edition installation on the same server as PaperCut, running on the default port and SID, use: jdbc:oracle:thin:@localhost:1521/SE
Important
See Section 22.3.3, “Configuring Oracle (and Oracle Express Edition)” for specific instructions to
configure Oracle.
22.2.5. Step 5 - Initialize the new database
The next step is to initialize the new database, creating the required database tables and initial data. To initialize the database:
1.
On the server, open a command prompt. (If you are seeing 'Access Denied' errors, please run command prompt as Administrator).
2.
If running on Linux or Mac, use su or equivalent to become the identity of papercut. e.g.
Mac: sudo su - papercut
Linux: su - papercut
3.
Change ( cd
) to the server binaries directory. e.g.
Windows:
Mac: cd "C:\Program Files\PaperCut NG\server\bin\win" cd "/Applications/PaperCut NG/server/bin/mac"
Linux (32bit): cd ~papercut/server/bin/linux-i686
Linux (64bit): cd ~papercut/server/bin/linux-x64
4.
Run the following command: db-tools init-db
A message will be displayed to indicate that the connection details are correct the database was initialized correctly.
22.2.6. Step 6 - Load the data into the new database
This step loads the data (that was exported in Step 2) into the database. To import the data:
1.
On the server, open a command prompt. (If you are seeing 'Access Denied' errors, please run command
347
Deployment on an External Database (RDBMS) prompt as Administrator).
2.
If running on Linux or Mac, use su or equivalent to become the identity of papercut. e.g.
Mac: sudo su - papercut
Linux: su - papercut
3.
Change ( cd
) to the server binaries directory. e.g.
Windows:
Mac: cd "C:\Program Files\PaperCut NG\server\bin\win" cd "/Applications/PaperCut NG/server/bin/mac"
Linux (32bit): cd ~papercut/server/bin/linux-i686
Linux (64bit): cd ~papercut/server/bin/linux-x64
4.
Run the following command: db-tools import-db "backup file name"
5.
This command will show progress importing the data.
If no errors occurred then the application is ready to restart.
22.2.7. Step 7 - Restart PaperCut NG
The data has now been moved to the new database and the server can be restarted.
Wait 30 seconds for the server to start, then log in to the admin console. If you can log in successfully, then the upsizing process worked successfully.
22.3. Database specific configuration
This section includes database specific configuration for use with PaperCut NG.
22.3.1. Configuring Microsoft SQL Express
Microsoft SQL Express provides enterprise class database performance for free. However it does have some limitations when compared to the full version of SQL Server. But these limitations are not likely to adversely affect most PaperCut NG users. These limitations include:
• 4GB limit on database sizes (10GB for SQL Server Express 2008 and 2012)
• Limited to only use 1 CPU
• Limited to only use 1GB of RAM
This section described how to configure Microsoft SQL Express edition for use with PaperCut NG. It is assumed that
SQL Server Express is already installed with the default configuration.
Once this configuration is complete, the database can be used with PaperCut NG by following the instructions in
Section 22.2, “Upsizing to an External RDBMS”.
22.3.1.1. Enable TCP/IP connections
PaperCut NG uses TCP/IP to connect to the SQL Server database, but SQL Server Express does not enable TCP support by default. To enable TCP/IP:
1.
On the machine with SQL Express installed, open the SQL Server Configuration Manager.
2.
Expand the SQL Server Network Configuration node on the left.
348
Deployment on an External Database (RDBMS)
3.
Select the Protocols for SQLEXPRESS node on the left.
4.
Right-click the TCP/IP item on the right and select Properties.
5.
On the General tab, change Enabled to Yes.
6.
On the IP Addresses tab, under the IPAll node clear the TCP Dynamic Ports field. Also enter the port to listen on in the TCP Port field. For example, 1450. Remember this port, because it needs to be used in the PaperCut
NG connection string.
7.
On the OK button to save the changes.
8.
Restart the Microsoft SQL Server Express service using either the standard service control panel or the SQL
Express tools.
22.3.1.2. Enable SQL Server authentication
PaperCut NG requires SQL Server authentication to be enabled on the instance of SQL Express. To do this:
1.
On the machine with SQL Express installed, open the SQL Server Management Studio Express tool.
2.
Right-click the instance of SQL Express to configure, and select Properties.
3.
Select the Security section on the left.
4.
Change the Server Authentication to SQL Server and Windows Authentication mode.
5.
Restart the Microsoft SQL Server Express service using either the standard service control panel or the SQL
Express tools.
22.3.1.3. Create Database User
PaperCut NG requires a user to connect to the database. To create this user:
1.
On the machine with SQL Express installed, open the SQL Server Management Studio Express tool.
2.
Right-click the Security->Logins node, and select New Login ....
3.
Enter the username (e.g. papercut).
4.
Change the Server Authentication to SQL Server and Windows Authentication mode.
5.
Enter the user's password.
6.
Disable password expiration.
7.
On the OK button to create the user.
8.
After creating the PaperCut NG database assign this user db_owner permissions on the database, so that it can create the required database tables.
9.
To initialize the database, follow the instruction in Section 22.2, “Upsizing to an External RDBMS”.
22.3.2. Configuring MySQL
MySQL is a free/open-source database solution that provides robust, proven and scalable storage at a great price.
PaperCut NG supports MySQL 5.0 and higher.
Important
PaperCut NG requires the use of the MySQL InnoDB table type, which provides full support for transactions. Please ensure your MySQL database server is configured to support InnoDB (usually this is enabled by default).
22.3.2.1. Database Driver
PaperCut NG does not ship with a database driver for MySQL because the MySQL licensing does not allow
349
Deployment on an External Database (RDBMS) redistribution of the driver. These drivers can be downloaded for free from the MySQL website as described below.
To download the required version of the driver:
1.
Visit the MySQL web site download page for the
MySQL Connector/J
product here: http://dev.mysql.com/downloads/connector/j/.
2.
Select the appropriate driver version (the latest version is best).
3.
Download the driver package and unzip the contents to a temporary directory.
4.
Find the driver JAR file, which is typically named mysql-connector-java-X.Y.Z-bin.jar
.
5.
Copy the JAR file into the
[app-path]\server\lib-ext directory. This will allow PaperCut NG to find and load the driver.
“Upsizing to an External RDBMS”.
22.3.3. Configuring Oracle (and Oracle Express Edition)
Oracle is a high-end database solution that provides a very robust and scalable data storage solution. And with the release of Oracle Express Edition, it is available at no cost, but it does have some limitations that should not impact
PaperCut NG installations.
PaperCut NG supports Oracle versions 9.2 and higher. Oracle 8 (and earlier) are not supported because they did not support the
TIMESTAMP datatype required by PaperCut NG.
22.3.3.1. Database Driver
PaperCut NG does not ship with a driver for Oracle because Oracle does not allow us to redistribute the driver and the recommended driver depends on the version of Oracle used. These drivers can be obtained from the Oracle website as described below.
To download the required version of the driver:
1.
Visit the Oracle web site here: http://www.oracle.com/technetwork/database/features/jdbc/index-091264.html
2.
Select the appropriate Oracle version.
3.
The required file to download will differ depending on the Oracle version. Download the ojdbc6.jar
for your version.
4.
Copy the downloaded file into the
[app-path]\server\lib-ext directory.
5.
Restart the service PaperCut Application Server This will allow PaperCut to find and load the driver.
“Upsizing to an External RDBMS”.
22.3.4. Best Practices on Microsoft SQL Server
Microsoft SQL Server provides enterprise class database performance. With this type of database, it is recommended that the administrator puts in place a database re-index every month. This database optimization will help with general performance, and more specifically, large queries performed on the SQL database. These queries include Reporting, as well as Bulk Actions performed on multiple data points. It's highly recommended that this optimization be set up as a scheduled task after hours to ensure you see no performance issues due to database indexing problems.
The optimization we recommend you run is:
• exec sp_msForEachTable @COMMAND1= 'DBCC DBREINDEX ( "?")';
• exec sp_updatestats;
PaperCut support has seen databases with large databases with millions of print jobs complete this command in
350
Deployment on an External Database (RDBMS) less than three minutes. The result was seen where reporting took 10-15 minutes before optimization, and now takes a matter of seconds.
351
Chapter 23. Mobile & BYOD Printing
23.1. Introduction
BYOD (Bring Your Own) Mobile devices are now accepted as playing an essential role in many organisations and are here to stay. However, providing printing support across the varied devices available is challenging as there are many competing technologies with no standardization. Current mobile printing solutions are problematic because:
• There are lots of choices
• They may not compatible with your printing infrastructure or are difficult to integrate
• They keep changing
There is no current "standout" mobile printing solution that is the best for all platforms. Rather, each platform has its own native or preferred option. PaperCut harnesses each of the native printing solutions to create a unified solution for your organization. PaperCut's approach is to:
• Integrate with the native printing solutions on each platform,
• Ensure that all of PaperCut's core print management features are available,
• Provide a natural print experience across all devices,
• Allow organizations to re-use their existing print infrastructure (no need for special printers),
• Ensure that all users can be accommodated by providing simple options such as Email to Print and Web Print.
This chapter will help you understand the various tools that PaperCut provides for mobile users and how they can be mapped to your organization's needs, no matter how many users you are supporting. In addition it provides some guidance on how to approach deployment and troubleshooting.
The Process:
• STEP 1 - Understand the tools
• STEP 2 - Understand your users
• STEP 3 - Develop your strategy and deployment plan
23.1.1. STEP 1 - Understanding the tools
Before planning your deployment, you need to have a good understanding of the tools and technologies. A number of these technologies may already be in place in your organization, while others are made possible with PaperCut.
The key technologies can be grouped as follows:
• Native mobile print technologies
•
•
•
Windows Print Queues (for Windows RT)
• PaperCut-provided technologies
•
•
PaperCut integrates with existing systems to complement native print technologies with print management functionality. Additionally, PaperCut technologies such as Email to Print provide alternatives on platforms where a native approach is not available or practical.
352
Mobile & BYOD Printing
Technology
Benefit
iOS provides users with a native and mature print experience on iPhones and iPads. Users have the power to select various printing options such as copies and grayscale, and can print from many applications without the need of additional software. Users may interface with PaperCut features via the Mobile
Client app.
GCP is Google's preferred mobile and Chromebook (Chrome OS) printing experience. It is the native printing experience for Android, Chromebooks, and
Google applications on iOS. GCP is also an option for laptop users (when using the Chrome browser or a custom driver/service). All of PaperCut's print management features integrate with GCP.
A lowest common denominator, and simplest solution that will work on any device that's able to send email attachments. PDF or Microsoft Office document attachments are converted to print jobs.
A simple web based experience suitable for any BYOD laptop or Netbook users.
End-users simply upload their document via a standard browser form. No special or client print driver setup required.
Table 23.1. Technology Benefits
The remaining parts of this chapter cover each of these technologies in detail. Ultimately hands-on experience is the best way to understand the approaches and technologies. Your deployment plan, discussed below, will likely have a testing period to help you understand and assess the technologies before committing to them. This is discussed more in the following steps.
23.1.2. STEP 2 - Understand your users
Every organization will have a different mobile & BYOD strategy. Small organizations may simply implement one technology, while larger organizations with dedicated IT departments may have a multi-faceted approach. Your strategy will be driven by your particular environment and user needs. The range of end-user drivers is diverse some examples:
• Many education organizations are now allowing students to bring their own laptops, or are considering supplying
Chromebooks or iPads.
• In business it's no longer 'one person - one device'. It's now desktop, laptop, tablet and mobile. Some have standard operating environments, while others support a broader spectrum or even a BYOD policy.
• ... and then there are the unexpected needs, such as Joe Exec turning up with his new Christmas present (a tablet) expecting to print.
After reviewing the user needs for your organization you'll know your device profile. Each device platform has preferred and supported approaches to printing. Use your device profile and the priorities of your user base to help determine the best technologies. The table below will help:
Android iPhone/iPad
Chromebooks (Chrome OS)
Netbooks
BYOD Laptops
Windows RT & Windows 8 tablets
Google Mobile Apps (many devices)
Other (e.g. Smart Phone)
N/A
iOS Printing
N/A
Preferred
N/A
N/A
N/A
Use standard Windows
Printing with Mobile Client
N/A
Web Print
N/A
N/A
Supported
Preferred
Preferred
Supported
N/A
N/A
Table 23.2. Technology Options
Google Cloud Print
Preferred
Email to Print
Supported
Preferred in Google iOS Apps Supported
Preferred Supported
Supported Supported
Supported
Supported
Supported
Supported
Preferred
N/A
Supported
Supported
23.1.3. STEP 3 - Develop your strategy and deployment plan
353
Mobile & BYOD Printing
As with most IT projects keeping the solution simple as possible but satisfying the majority of users is the preferred approach.
Smaller teams will need to balance the needs of their users against the complexity of implementing multiple technologies.
Larger organizations with dedicated IT teams have the benefit of scale. Offering choice to support the widest range of devices may be the project goal.
Each organization will differ in terms of rollout strategy. Here's a few checkpoints to work through to make sure everything is in place:
• Setup - Can this be done without impacting current users? Are there network or hardware requirements such as purchasing a Mac, or managing user accounts in Google to use GCP?
• Test - Before advertising any new feature, can you test it with a small group of users? Maybe you have a small group that's been requesting the feature. They will be eager to test it, and will hopefully come back with fresh feedback.
• Communicate - Before you roll out functionality, think about how you can most effectively communicate this to your users. Maybe a step-by-step guide via email is a good place to start.
• Rollout - Execute your plan. Larger organizations implementing a multi-platform/technology plan will conduct the rollout in phases.
• Manage - Don't forget to keep management in the loop with the different stages of the project. PaperCut has in-built reports on mobile print usage. This may be a useful tool.
• Evaluate - Continue to monitor usage and user requirements. If you introduce new device types in the future, it might be time to consider introducing different methods to print.
At a technical level, it's also important to understand IT infrastructure requirements and the impact your choices have on your data and security policies. The table below hightights some of these considerations.
Technology
iOS Printing
Data Flow
Internal
Print Options Basic Requirements Other Limitations
Basic options, provided by iOS. Usually:
• Page Size
• Color iOS devices. Mac print server with PaperCut, or 3rd party
Windows app.
Multiple subnet configuration can be challenging without
3rd party utilities.
Google Cloud Print Internal / external All options, provided by
Google Cloud Print. Usually at least:
• Page Size
• Duplex
• Color
Users must have a Google
Account.
Depending on configuration, users may not be able to print from all applications.
Exporting to PDF and printing from a browser is a common workaround.
Email to Print
Web Print
Table 23.3. Technology Options
Internal (maybe external depending on mail server configuration)
OS print queue defaults only
(currently theree are no options selected by the user)
It is possible to create multiple OS print queues with different defaults e.g.
a
'duplex queue'.
POP3 or IMAP email server.
Optional sandbox machine /
VM running Microsoft Office apps.
PDF only or PDF and
Microsoft Office documents if a sandbox is configured.
Internal
Possible to make external by exposing the PaperCut user web interface to the internet.
Number of copies only, other settings use OS print queue defaults
It is possible to create multiple OS print queues with different defaults e.g.
a
'duplex queue'.
Optional sandbox machine /
VM running Microsoft Office apps.
PDF only or PDF, Microsoft
Office and XPS documents if a sandbox is configured.
354
Mobile & BYOD Printing
Detailed information on each technology can be found in subsequent sections.
23.1.4. Common questions that come up during planning
Q:
Do I have to turn on all of these mobile solutions at once?
A:
No. It's best to pick the ones which are suitable for your environment, and perform a controlled rollout of the new feature.
Q:
Email to Print works with all platforms. Why would I not just implement this?
A:
This is a viable option and one that many organizations will adopt. Our recommendation is to look at native print options first where possible. The benefit for native print options is that they offer a richer and more familiar end-user experience.
Q:
What does it cost to add BYOD features to my PaperCut installation?
A:
All BYOD features are included in the standard PaperCut license. There are no additional licensing costs.
Q:
I want to allow printing, but I don't allow mobile devices to connect to our network. Is there an option?
A:
Google Cloud Print and Email to Print work without requiring users to connect to your network.
Q:
I want to use Google Cloud Print, but don't want users sending documents via Google's servers. Is there a version that I can run on my own server?
A:
Although Google Cloud Print uses open protocols (and upcoming standards), Google is the only server provider we're aware of at the time of writing. By contrast, Email to Print involves documents routing via your email server, and iOS Printing (if you are supporting mainly Apple devices) is network-internal.
23.2. Google Cloud Print
Early Access Program
Google Cloud Print integration is currently offered under an Early Access Program.
The Google Cloud Print integration has been extensively tested pre-release and there is a high level of confidence in its quality. However, there are many combinations of printers, printer drivers and servers that cannot all be tested. In addition, the Google Cloud Print interfaces continue to rapidly change and evolve.
We seek the assistance of our customers and partners to help ensure that any problems or feature gaps encountered are reported and addressed. We ask that customers:
1.
Be aware that some issues may exist with Google Cloud Print
2.
Work with PaperCut Software to quickly address issues if they occur
During the early access period you should check the following PaperCut knowledge base article discussing any known issues: http://www.papercut.com/kb/Main/KnownIssuesGCP
[http://www.papercut.com/kb/Main/KnownIssuesGCP]
23.2.1. Overview
355
Mobile & BYOD Printing
Google Cloud Print [http://www.google.com/cloudprint/learn/] (GCP) is a cloud based printing service from Google that lets people print anywhere from any device. Users are increasingly bringing their own mobile devices (BYOD) to the workplace and need a printing solution. Google Cloud Print provides a way to print from any mobile phone or tablet, running Android or iOS. Whilst almost any device, including mobile and desktop computers can print to
Google Cloud Print, for some devices, such as the Google Chromebook, Google Cloud Print is the only printing solution available.
On its own, Google Cloud Print provides untracked printing only to Google Cloud Print enabled printers. Coupled with PaperCut, Google Cloud Print becomes a powerful mobile and BYOD printing solution for organizations of any size:
1.
PaperCut tracks and controls Google Cloud Print jobs just like any other PaperCut print job.
2.
Google Cloud Print deployment is managed centrally, using the PaperCut admin console to publish and deploy
Google Cloud Print on selected printers.
3.
Balancing) work alongside Google Cloud Print.
4.
Use Google Cloud Print with your existing printers. With PaperCut you do not need to have “Google Cloud Print
Aware” printers.
Figure 23.1. Supported Environments
Users may print to Google Cloud Print in many ways:
1.
From a Chrome browser (mobile or desktop) or Chromebook device
2.
From an iOS or Android device with a Google Cloud Print enabling app installed
3.
From Google applications, such as Drive, Gmail on all platforms
4.
From a Windows or Mac desktop using the Cloud Printer app
A current list of compatible printing applications is available at http://www.google.com/cloudprint/learn/apps.html.
23.2.1.1. How it works
356
Mobile & BYOD Printing
Figure 23.2. Google Cloud Print and PaperCut
The diagram shows PaperCut as the bridge between an organization's printers and the Google Cloud Print service.
1.
PaperCut publishes selected printers to Google Cloud Print, making them available to Google Cloud Print user applications.
2.
A mobile or desktop user prints a document or email using Google Cloud Print and selects a published printer.
3.
PaperCut is notified and downloads the print job from the cloud.
4.
PaperCut authenticates the user sending the job, then renders and spools the job to the specified printer.
5.
PaperCut tracks and manages the print job in the same way as any normal print job.
6.
PaperCut informs Google that the job is complete.
PaperCut takes care of publishing printers with Google, downloading jobs from the Google cloud, and managing the print work-flow. This makes it very easy to integrate Google Cloud Print into your existing print service.
Printers must be published to Google Cloud Print to make them available for users to print. Once Google Cloud Print is enabled, a single button click is all that is needed to publish a printer. PaperCut will manage any Google Cloud
Print print jobs on behalf of the printer and jobs will be processed by the normal PaperCut work-flow.
Tip
Some internet printers are marketed as “Cloud Print Ready” and may be connected directly to Google
Cloud Print. However if you directly connect a printer to Google Cloud Print, you will not be able to track and control print jobs from Google.
We recommend you use PaperCut to connect your printers with Google Cloud Print. “Cloud Print
Ready” printers are not required.
23.2.1.2. Requirements
The following requirements must be met for a successful Google Cloud Print integration:
1.
Google Cloud Print is supported by PaperCut Print Providers running on Windows, Linux or Mac OS. Printers
357
Mobile & BYOD Printing managed by a Novell print server can not yet be published to Google Cloud Print.
2.
The Print Provider software must be running a version of PaperCut that supports Google Cloud Print. Google
Cloud Print support was first introduced with PaperCut release 13.5. Printers managed by an older version of the Print Provider may not be published to Google Cloud Print.
3.
Some printers and printer drivers may not respect all printer settings such as color or grayscale, single sided or duplex as specified by the user in the Google Cloud Print user client. If you observe issues in this area, please try upgrading to the latest drivers, as Google is working with the printer manufacturers to resolve any such issues.
4.
5.
The PaperCut Application Server must be able to connect to the internet to communicate with Google Cloud
Print servers. Ports or exceptions may need to be made in firewalls or proxy servers. The full details are: TCP
(HTTPS) port 443 connections to https://www.googleapis.com/*
, https://accounts.google.com/* and https://www.google.com/cloudprint/*
, as well as a TCP port 5222 (XMPP with STARTTLS) persistent connection to talk.google.com
.
23.2.2. User Authentication and Printer Sharing with Google Cloud Print
Google Cloud Print uses Google's OAuth based system for identifying users and printers. These must be reconciled with the users and printers managed by PaperCut so that Google Cloud Print jobs can be tracked as normal
PaperCut jobs and allocated to the correct PaperCut user.
This integration between Google Cloud Print and PaperCut domains is managed as follows:
1.
A Google account is set up for Google Cloud Print administration. PaperCut uses this account to publish printers and communicate with Google Cloud Print over the internet.
2.
User's Google accounts are added to the PaperCut user database as secondary email addresses. This can be done either manually or via an automated email verification process.
3.
Printers are published using PaperCut then shared with users using Google's sharing tools.
Each of these topics are covered in detail in the sections below:
23.2.2.1. Administrator Authentication
You need a Google administrator account
When Google Cloud Print is enabled in the PaperCut administrator interface, you are asked to authenticate with
Google credentials. All printers will be published by PaperCut using these credentials. The use of one set of credentials to register all printers is in line with Google's best practice recommendations.
You can use any Google account for this purpose, but we recommend that you set up a dedicated account for
Google Cloud Print administration. A personal account is not recommended as it may be deleted if an employee changes role or leaves your organization.
When you first enable Google Cloud Print, you will be asked to login to your Google administrator account and authorize PaperCut to have access to the Google services needed to manage Cloud Print. After accepting this request, PaperCut will permanently store an access token, avoiding the need to authenticate each time.
23.2.2.2. User Authentication
Each Google Cloud Print user must have a Google account associated with their PaperCut account.
Each Google Cloud Print user requires a Google account. This account may be self-registered, or provided to the user under a Google Apps managed environment.
PaperCut must map each user's Google account used for cloud printing to a PaperCut user. For example, Google may know a user as “[email protected]” whereas the same user in PaperCut may be “adamsj” with an email
358
Mobile & BYOD Printing
As with this scenario, PaperCut allows multiple email addresses to be associated with a user. Each user may have one primary email address and multiple secondary email addresses. All addresses must be unique across the system.
PaperCut provides two ways to populate the secondary emails on behalf of each user. You should select which method is best for your organization:
1.
Manual configuration. An administrator may add and remove secondary email addresses on behalf of a user in the Users tab of the PaperCut Admin interface.
2.
Self registration through automatic email verification.
When a print job arrives from Google, PaperCut finds the user with a primary or secondary email address matching the address of the sender. The matching user is then associated with the incoming print job.
If no matching user is found, you may choose to have PaperCut cancel the job, or hold the job and perform automatic email verification. Cancelling the job is the appropriate response if you are choosing to manually configure the secondary email addresses.
Automatic email verification works as follows:
1.
When a job arrives from an unknown user, the job is held and an email is sent to the originating Google email address asking for the user to click a link to validate their account.
2.
The link takes the user to the login screen for the PaperCut web interface.
3.
The user logs into their PaperCut account and the Google address is automatically associated with this account.
4.
The job proceeds to print as the verified PaperCut user.
23.2.2.3. Publishing and Sharing Printers
Each printer must be published and “Shared” with end users.
Printers are published to Google Cloud Print in order to make them available for Cloud printing. By default, printers managed by PaperCut are not published to Google Cloud Print. Publishing is performed by a single button click in the Printer Details page. A printer may be published by clicking on Publish to Google Cloud Print button at any time after enabling Google Cloud Print.
Figure 23.3. Publishing Printer
Printers are published by PaperCut using your chosen Google administrator account. By default only that account will have access to the printers for printing. To make printers available to your Google Cloud Print users, you must
share your printers.
Printer sharing is a Google feature and is administered in Google's Cloud Print web interface
(https://www.google.com/cloudprint#printers), not in PaperCut.
You may share printers with individual users by specifying a list of Google email addresses. You may also share printers with a Google Group [https://support.google.com/groups]. For example, you could set up a Google Group for Students and another group for Teachers and share printers to those groups. Users may self-register with the appropriate Google Groups, but you may need to moderate these registrations. Google provides mechanisms for people to request membership to a Google Group and for a moderator to accept or reject those requests.
Tip
359
Mobile & BYOD Printing
When a printer is shared with a user, the user must accept the sharing “invitation” before they are able to use the printer for printing. This action is performed within Google's web interface and at the time of writing is not available on some mobile devices. We recommend you test the sharing of printers at your site and provide users with any guidance needed to ensure they are able to successfully accept printers shared with them. It may be necessary to request people use a desktop browser to accept the sharing invitation.
23.2.3. Setting up Google Cloud Print
Setting up Google Cloud Print in PaperCut is straightforward. First you must create an administrator Google account
(see Section 23.2.2.1, “Administrator Authentication”). Then:
1.
Enable Google Cloud Print in Options
→
Mobile & BYOD
→
Google Cloud Print.
2.
Publish printers to Google Cloud Print and share with your users.
3.
Test your major user printer scenarios on a range of devices and printers.
These steps are covered in detail below:
23.2.3.1. Enabling and Configuring Google Cloud Print
Google Cloud Print is enabled in Options
→
Mobile & BYOD
→
Google Cloud Print. On checking "Enable" a wizard dialog appears to lead you through the process.
Figure 23.4. Google Cloud Print Setup Wizard
The first step in the process is to authorize PaperCut to use your administrator Google account. (See
use your Google account to obtain an authorization code. The authorization code is needed for PaperCut to use your administrator account to manage your printers with Google Cloud Print on your behalf.
360
Mobile & BYOD Printing
Figure 23.5. Google Request for Permissions Window
Note
You must grant permission for your PaperCut Application Server to use your administrator Google account to work with Google Cloud Print on your behalf.
You are not granting permission for any third party, including PaperCut Software, to access your account. Your authorization only applies to your PaperCut Application Server instance.
Once your Google Cloud Print administrator account is authorized, you may publish a printer to Google Cloud Print
Printers to Google Cloud Print via PaperCut” for more information.
There are several choices to make on how PaperCut process Google Cloud Print jobs with respect to user authentication and client popup reminders.
1.
Configure what PaperCut should do when a job arrives from an unknown email address.
361
Mobile & BYOD Printing
PaperCut searches the user database for the originating email address of each job. If the email address is not found, you may choose to have PaperCut cancel the job or hold the job and email the user with instructions for
verifying their Google email address. (See Section 23.2.2.2, “User Authentication”.)
You may wish to cancel the job if you have decided to manually configure the user Google email addresses in the Users page.
2.
23.2.3.2. Publishing Printers to Google Cloud Print via PaperCut
Before a printer can be used with Google Cloud Print it must be published to Google and shared with users.
Publishing a printer to Google Cloud Print will make the printer known to Google and enable access from Google's
Google Cloud Print user interfaces.
1.
Printers are published to Google Cloud Print on the printer details page for a selected printer in the Printers tab.
Click the Publish to Google Cloud Print button to publish a printer. The printer will remain published indefinitely.
If you do not see a Google Cloud Print section on the printer details page, check that Google Cloud Print is enabled under Options
→
Mobile & BYOD
→
Google Cloud Print.
2.
Once published, you must share your printer with users, using your Google administrator account to login to the
Google Cloud Print printer management page: https://www.google.com/cloudprint#printers
Figure 23.6. Printer published to Google Cloud Print
Printer can be unpublished by clicking on Delete from Google Cloud Print.
Sharing a printer will send a sharing invitation to each invited user. Each user must respond by accepting the invitation by logging in with their own Google account to the Google Cloud Print printer management page: https://www.google.com/cloudprint#printers
The printer sharing process is provided by Google as their solution for printer security and access control. We don't document the process in detail as Google's interfaces for sharing printers are likely to change. For example, at the time of writing, the sharing interfaces require a desktop or Chromebook browser.
You should test sending and accepting printer sharing invitations at your site, using your targeted mobile devices, and document any required steps for your users.
Tip
You can list only those printers published or not published to Google Cloud Print using a filter:
362
Mobile & BYOD Printing
1.
Go to the Printers tab to see a list of printers.
2.
Click [edit] to edit the filter.
3.
From “Published to Google Cloud Print” select Yes or No and click Apply Filter.
23.2.3.3. Testing Google Cloud Print
You should test the operation of Google Cloud Print before rolling out the system to your users. Your test plan should factor in the following items:
1.
Sharing and accepting printer sharing invitations. Share your printers and test using your targeted mobile devices and applications.
2.
Printing to a range of printers, page sizes, duplex and color settings.
3.
Automatic email verification (if used). Send a print job from an unknown Google account and check that a verification email is sent. Follow the steps in the email to associate the account with a PaperCut user and print the job.
4.
Tracking and control of Google Cloud Print jobs. Verify that print jobs from Google Cloud Print are associated with the correct user and are being tracked in the print log.
plan.
23.2.4. Troubleshooting Google Cloud Print Problems
23.2.4.1. Troubleshooting Printer Publishing Problems
Some printers may not be able to successfully publish to Google Cloud Print. There are several possible causes:
1.
The PaperCut Secondary Print Server is running on Novell
For various technical reasons, PaperCut does not currently support Google Cloud Print on Novell print servers.
2.
The Secondary Print Server is a Windows desktop machine
When running the Print Provider on a Windows desktop, PaperCut disables by default the server events needed for Google Cloud Print operation. This is done for performance reasons for sites running many desktop
Print Providers.
You may enable server events on a desktop Print Provider machine by adding the following line to the print-provider.conf file and restarting the Print Provider service:
ServerEventsEnableOnDesktops=on
There may be performance implications if this change is made on a large number of desktops.
3.
The Secondary Print Server is running an older version of PaperCut
The Print Provider must be running a version of PaperCut that supports Google Cloud Print. Google Cloud Print support was first introduced in PaperCut release 13.5.
4.
A connection from the Application Server to the Internet is unavailable
The Application Server must be connected to the Internet to publish printers and process Google Cloud Print jobs.
5.
Google access has been revoked
This may occur if the Google administrator account used to publish printers has been deleted or PaperCut's access to this account has been revoked. To recover from this scenario, you will need to disable and re-enable
Google Cloud Print in Options
→
Mobile & BYOD
→
Google Cloud Print and re-publish and share your printers.
363
Mobile & BYOD Printing
23.2.4.2. Troubleshooting Printing Problems
Print jobs printed to Google Cloud Print may not appear or print correctly. If this occurs, please check the App Log for any error or warning messages that may lead you to the cause. The user should also check Google's print job page https://www.google.com/cloudprint#jobs for job status information. If the job was submitted, but has not printed, some causes are listed below:
1.
The job is from an unknown user
PaperCut must map the Google email originating the job with a PaperCut user. If no user can be matched, the
may manually add the Google email as a user's secondary email address in the User Details page. Or you can enable automatic email verification.
2.
The job requires a popup response and no response received
If a job requires popup response, for example to select an account to charge, and no response is received,
PaperCut will wait up to 10 minutes before cancelling the job. Users must respond using the Mobile Client - see
received this email, check that the reminder setting is on, and that the email is not being diverted to the user's spam/junk folder.
3.
The print driver is not capable of rendering the job
When printing using CUPS (Linux and Mac print providers), the print driver is responsible for rendering the PDF document from Google Cloud Print. Some drivers, such as a generic Postscript driver, may not be able to render a PDF document. If you are using a generic Postscript driver as pass-through, you may need to setup a separate queue for Google Cloud Print using the proper printer driver for your printer.
4.
The print driver does not perform as expected
Some print drivers may not fully comply with the print ticket from Google Cloud Print. This can result in the printed output not respecting the requested paper size, color or duplex setting. Google is working with printer manufacturers to resolve such problems. The first course of action should be to update the printer driver to the latest version to see if the problem has been resolved. Otherwise, you may report the issue to our support team.
If the PaperCut page counts or color page counts are incorrect, please contact our support team.
5.
The PaperCut Application Server has lost connection with the Internet
The Application Server must be connected to the Internet to publish printers and process Google Cloud Print jobs.
6.
The Printer or Secondary Print Server is down
A printer may still appear available in Google Cloud Print even if the printer is currently down or the Print
Provider managing the printer is unavailable. The job will print when the Print Provider is brought back up.
23.3. iOS Printing (iPad & iPhone)
PaperCut's iPad / iPhone Printing support enables printing to all your PaperCut managed printers across your enterprise (and iOS devices - iPad, iPhone, iPod Touch). As well as enabling printing, the PaperCut iPad / iPhone
App also provides the rich functionality desktop users are used to, such as authentication, balance display and
selecting / charging to shared accounts when printing.
The PaperCut iPad / iPhone App is able to be deployed / installed in a pre-configured form for your network via a simple URL.
PaperCut's iPad / iPhone Printing support works by providing two key parts:
1.
The PaperCut Printer Advertiser - advertises the Apple CUPS printers managed by PaperCut using
Bonjour/mDNS (so the iPads / iPhones users can find the PaperCut controlled queues).
2.
The PaperCut iOS App, providing support for print authentication, balance display, account selection and other
364
Mobile & BYOD Printing features.
At the time of writing there is no built-in option provided by Apple to print from an iOS device to server shared print queues. PaperCut uses existing technologies built into Mac OS (Bonjour/mDNS) to advertise PaperCut managed server shared print queues so you an track and control iPad / iPhone printing. Some printers include built-in support for AirPrint®
1
(for printing direct from iOS devices to the printer), however the nature of print control/accounting requires that print jobs are intercepted by a central server. Additionally, most larger organizations want to leverage their existing print infrastructure, policies and print rules rather than change them. PaperCut's solution for iPad / iPhone Printing will now allow you to leverage your existing network and PaperCut setup.
23.3.1. Requirements
1.
Mac OS X 10.8 or greater system to share the print queues (desktop version is fine, server tools not required)
2.
Apple iOS 5 or greater devices to print from
3.
Wireless network
The PaperCut Printer Advertiser is a part of the PaperCut primary and secondary server installation and advertises the PaperCut print queues to iOS devices.
For Windows, Linux or Novell sites (or sites with a Mac OS 10.6 or older print server they would prefer not to upgrade), a separate (secondary) Mac OS 10.8 print server can be configured to share print queues. This can be as simple as purchasing a Mac Mini system and making it accessible from the wireless network.
Alternatively, you can use third party applications like Presto [http://www.papercut.com/kb/Main/PrestoIOSPrinting] or Efi's PrintMe Mobile [http://www.papercut.com/kb/Main/EfiPrintMeMobile] which can share printers on a Windows server to mobile devices across your network. PaperCut Software has worked with these vendors to ensure compatibility and an improving solution over time. The Presto application also provides a solution for advertising printers over multiple subnets.
23.3.2. Sharing Printers to iOS Devices
1.
Set up a Mac OS 10.8+ system to act as your iPad / iPhone print server. This can be your existing Mac print
“Configuring a Macintosh Secondary Print Server” for details).
2.
Install the print queues and drivers for the printers you wish to share to your iOS devices. These print queues should point directly to the printer, not another print server.
3.
Test printing from a local application (e.g. Safari) to ensure that the drivers and printers are functioning correctly.
4.
Install PaperCut. If you are setting up a secondary Mac print server (i.e. the primary PaperCut server is on
setting up a Mac primary server, follow the steps at Section 2.2, “Installation on Apple Mac”.
Ensure that your Mac server is connected to the same subnet as the wireless network that the iOS devices will connect to. Without further configuration, the publishing protocol Bonjour will broadcast to the local subnet only and devices on other subnets will not see your printers.
You may overcome the single subnet limitation by connecting your Mac server to multiple subnets. If you are using a cabled network, your Mac will need a separate Ethernet interface for each network connection.
However, if you are using a wireless network, you may add multiple IP addresses, one for each subnet, to the same network interface. To add multiple addresses to a wireless interface: a.
Open Network Preferences (System Preferences
→
Network) and select your wireless interface.
b.
Click the gear icon underneath the interface list and select Duplicate Service. Enter a name for your new network and click Duplicate.
c.
Select the duplicated network connection and click Advanced.... Select the TCP/IP tab and choose
Configure IPv4 Manually. Enter an IPv4 address for the subnet you wish to connect to.
1
"AirPrint" is a registered trademark of Apple Inc.
365
Mobile & BYOD Printing
Your chosen IP address must be unique. Make sure you choose an IP address outside the DHCP address allocation range so that you can be sure that you will not experience address conflicts. Alternatively you can configure DHCP to permanently reserve the chosen address for your Mac Server. (DHCP configuration is normally performed on your network router.)
5.
Share all the printers that you would like to publish to iOS devices: System Preferences
→
Print & Scan
→
[select printer]
→
Share this printer on the network (to do this, Printer Sharing must first be enabled in the
Sharing pane).
Figure 23.7. Sharing a printer on Mac OS
6.
Run
/Applications/PaperCut NG/Control Printer Monitoring.command
and choose to disable
to test iOS Printing functionality without PaperCut's monitoring involved (to limit what is being tested).
7.
Print a document from your iOS device e.g. open Safari, load a web page, touch the "arrow" menu and select
Q:). The job should print correctly.
8.
Test printing across a number of printers and apps such as Mail, Safari, Photos and iBooks / PDFs. Not all printers are capable of supporting all formats. Take the time to test and ensure the printers that you are making available produce acceptable results.
9.
Re-enable PaperCut tracking using
/Applications/PaperCut
Monitoring.command
(see Section 7.1.2, “On Mac” for details).
NG/Control Printer
23.3.3. The PaperCut iPad / iPhone App (Mobile Client)
366
Mobile & BYOD Printing
printers. The App authenticates each print job - effectively linking up users with their print jobs. It can also provide
balance display, print job confirmation, shared account selection and message notification.
23.3.3.1. Deployment
Deploying the App to iOS devices is simply a matter of having the user access a URL of the form http://[primary-server]:9191/ios/install
, where
[primary-server] is the preferred hostname or IP address of your primary PaperCut server.
Figure 23.8. Accessing the installation URL manually, using Safari
Tip
For easier distribution of the installation URL, try adding a link on an intranet page, sending it in an email or printing the URL on posters. It may help to add a short DNS name for your print server or even set up a simple redirect URL (e.g.
http://myorg/ios/install
-> http://print-server.myorg.edu:9191/ios/install
).
After accessing the installation URL on an iPad / iPhone (iOS device) an Install Profile dialog should appear.
Follow the promps to install the App. Afterwards, a Printing App (actually a Web Clip) should be available on the home screen.
367
Mobile & BYOD Printing
Figure 23.9. The "Install Profile" dialog, displayed after accessing the installation URL
368
Mobile & BYOD Printing
Figure 23.10. The PaperCut App for iPad on the home screen
For alternative and advanced deployment options, see Section 23.3.5.3, “Advanced App Deployment”.
23.3.3.2. Usage
The PaperCut App for iPad / iPhone (Mobile Client) is used to:
• Authenticate the user and their print jobs.
• Display the user's balance.
• Perform print job confirmation.
•
Perform shared account selection.
•
Display Print Scripting messages.
• Perform other functionality such as message notification.
Figure 23.11. The PaperCut App for iPad (before printing)
369
Mobile & BYOD Printing
Figure 23.12. The PaperCut App for iPhone(before printing)
The following examples illustrate typical usage of the App for a student (immediate print) and a staff member
(account selection).
23.3.3.2.1. Scenario: Student Printing
1.
The student prints from their selected app.
370
Mobile & BYOD Printing
Figure 23.13. Printing from iOS
2.
The student closes the app and opens the Printing (PaperCut) app.
371
Mobile & BYOD Printing
Figure 23.14. Printing (PaperCut) app on the home screen
3.
The student enters their username and password. On a personal device this step only needs to be performed once. Future logins are performed automatically through the use of an authentication cookie.
372
Mobile & BYOD Printing
Figure 23.15. Authenticating to the PaperCut iPad App
4.
The student's print job is authentication and proceeds to print. The student can see their job's progress in the app.
373
Mobile & BYOD Printing
Figure 23.16. The PaperCut App for iPad (after printing)
374
Mobile & BYOD Printing
Figure 23.17. The PaperCut App for iPhone (after printing)
23.3.3.2.2. Scenario: Staff Printing (Account Selection)
1.
The staff member prints from their selected app.
Figure 23.18. Printing from iOS
2.
The staff member closes the app and opens the Printing (PaperCut) app.
375
Mobile & BYOD Printing
Figure 23.19. Printing (PaperCut) app on the home screen
3.
The staff member enters their username and password. On a personal device this step only needs to be performed once. Future logins are performed automatically through the use of an authentication cookie.
376
Mobile & BYOD Printing
Figure 23.20. Authenticating to the PaperCut App
4.
The print job is authenticated and is ready for account selection. The account selection dialog appears.
377
Mobile & BYOD Printing
Figure 23.21. The account selection dialog in the PaperCut App
5.
The staff member selects their chosen shared account and touches Print. The job prints, and the staff member can see their job's progress in the app.
378
Mobile & BYOD Printing
Figure 23.22. The PaperCut App for iPad (after printing)
379
Mobile & BYOD Printing
Figure 23.23. The PaperCut App for iPhone (after printing)
23.3.4. Troubleshooting & FAQ
Q:
Jobs won't print.
A:
1.
Are you printing double sided? Try turning double sided off. There seems to be issues with double sided printing on some iOS devices, as of iOS 5.0.1.
2.
Try printing with PaperCut tracking disabled (using
/Applications/PaperCut NG/Control
Printer Monitoring.command
) to help diagnose the problem (see Section 7.1.2, “On Mac” for
details).
Q:
Can I have multiple Mac print servers running PaperCut's iPad / iPhone App (e.g. to provide different printers to different subnets)?
A:
Q:
My printers don't show up on the iOS devices when selecting a printer.
A:
Yes! Alternatively, to provide the same printers to multiple subnets, consider using Bonjour/mDNS "reflectors"
(left as an exercise for the reader ;-)
1.
Ensure that the printers are shared on the Mac server.
2.
Ensure that PaperCut is installed on the Mac server (primary or secondary server install).
3.
It can take a few minutes before the printers show up on the iOS devices. Has it been that long since sharing the printers?
4.
Ensure that the Mac server is on the same subnet as the iOS devices. Bonjour/mDNS, the protocol used to publish/advertise the print queues, will only broadcast to the local subnet without further configuration
(a "reflector", the configuration of which is beyond the scope of the documentation).
You may be able overcome this limitation by connecting a wireless interface on your Mac server to
5.
Try rebooting the Mac server. This will refresh the list of available printers and restart the Bonjour services that publish them.
Q:
My jobs do not show in the iPad / iPhone App.
A:
PaperCut uses the IP address of your iOS device to determine which jobs to display. If you are accessing
PaperCut via a proxy server, the remote IP address may not be immediately accessible and jobs will not appear.
Some proxy servers will retain the remote IP address in an X-Forwarded-For header. PaperCut can use this header to obtain the remote IP address, but for security reasons you must first add your proxy servers to
PaperCut's list of trusted proxy servers.
In PaperCut's admin interface:
1.
Go to Settings
→
Advanced
→
Security
2.
Add the IP addresses of your proxy servers to the Trusted Proxy Servers list and click Apply.
Q:
Other users' jobs are showing up in the PaperCut iPad / iPhone App.
A:
380
Mobile & BYOD Printing
1.
The IP addresses of the iOS devices need to be unique. Ensure that the devices are not behind a NAT relative to the Mac Print Server sharing the print queues.
2.
If just one other user's jobs are showing up, ensure that the DHCP lease times aren't too short.
Q:
Why isn't PaperCut iPad / iPhone Printing App supporting Windows print servers?
A:
Q:
I changed a printer's Location field and it's not being reflected on the devices.
A:
PaperCut supports Windows print servers by integrating with best-of-breed solutions like Presto
[http://www.papercut.com/kb/Main/PrestoIOSPrinting] and Efi's PrintMe Mobile
[http://www.papercut.com/kb/Main/EfiPrintMeMobile]. For sites that would prefer a 100% Apple solution, you can add a secondary Mac print server (e.g. a Mac Mini) to provide iOS printing support.
Changes to the printer's location and name will not immediately be reflected and you may need to restart the system or services to promptly broadcast these changes.
Q:
Under what username do jobs from iOS devices arrive in the print queue?
A: guest
. The CUPS web interface will display this username as Withheld.
Q:
Jobs are printing as
[generic account]
, e.g. " guest
".
A:
Ensure that
[generic account] is marked as Unauthenticated in PaperCut.
Q:
How do I uninstall / reinstall the PaperCut App on my iPad / iPhone?
A:
1.
Delete the Printing app (Web Clip) (hold your finger down over the app until the icons "go wobbly", then touch the cross icon next to the app).
2.
Delete the Printing profile via Settings
→
General
→
Profile
→
Printing
→
Remove It is important that the app / Web Clip is deleted before deleting the profile (if not, problems have been reported such as multiple blank icons returning once the profile is reinstalled, as of iOS 5.0.1).
3.
To reinstall, follow the installation procedure again.
Q:
How do I prevent a printer being shared?
A:
See Section 23.3.5.2, “Limiting Printer Deployment”.
Q:
How do I disable or re-enable iOS printing support on a Mac Print server?
A:
There are two commands that can be be run from the OS X termninal or the OS X Finder:
•
[app-path]/providers/iosprint/mac/disable-iosprint.command
. Stops (and disables) the iOS print service and creates a marker file that is used during susbquent upgrades to respect the iOS print status.
•
[app-path]/providers/iosprint/mac/start-iosprint.command
. Enables (and starts) the iOS print service and removes the marker file.
Q:
Can the PaperCut App for iPad / iPhone Printing display print scripting pop-ups?
A:
Not yet. Scripting pop-ups for the PaperCut App are planned for a future release.
381
Mobile & BYOD Printing
23.3.5. Advanced iPad / iPhone Printing Setup
23.3.5.1. iPad / iPhone Printing Technical Description
PaperCut for iPad / iPhone Printing works by providing four distinct parts:
1.
PaperCut enables Mac OS's built-in Bonjour/mDNS publishing to advertise/publish PaperCut managed/tracked shared print queues, so that they appear in the Print menu on iOS devices (on the same network).
2.
CUPS on Mac OS accepts print jobs (as PDF) and renders them into the queue's target printer language
(generally PostScript).
3.
PaperCut identifies the print jobs, generally arriving as user guest
, as being unauthenticated. The device IP address is used to identify the device sending the print job.
4.
The PaperCut App on the iOS device is used to authenticate the user from their device IP address, linking their print jobs with their username.
5.
The App receives directions from the PaperCut server, such as to display print job details or account selection.
23.3.5.2. Limiting Printer Deployment
When PaperCut has been installed on a Mac OS 10.8+ print server, all PaperCut NG managed and shared printers
for details). If you would like to share printers to OS X (desktop) systems but not to iOS devices, you can turn off broadcasting/advertising by adding "
No iOS
" anywhere in the printer's location field, then restarting the system e.g.:
1.
Navigate to System Preferences
→
Print & Scan
→
[select printer]
→
Options & Supplies...
→
Location
2.
Add the text "
No iOS
" to the Location field e.g. "
Lab G4.01 (No iOS)
".
3.
Restart the system for this change to take effect.
23.3.5.3. Advanced App Deployment
Large deployments such as universities, school districts or corporations with organization-wide iPad / iPhone deployments may want to consider more advanced app deployment techniques. Other than the standard URL
deployment options, all of which are compatible with PaperCut:
• If you are using the iPhone Configuration Utility [http://www.apple.com/support/iphone/enterprise/] to distribute
Configuration Profiles to your iOS devices, you can a Web Clip to them. Use a URL of the form http://[primary-server]:9191/ios
. If you are using an SSL certificate with PaperCut that is trusted by your iOS devices, you can use an HTTPS URL of the form https://[primary-server]:9192/ios
. You can find an icon at http://[primary-server]:9191/images/icons2/72x72/web-client.png
.
• If you are using a Mobile Device Management [http://www.apple.com/ipad/business/integration/mdm/] (MDM) server to send configuration to your iOS devices, you can add distribution of the PaperCut App as a Web Clip.
Use a URL of the form http://[primary-server]:9191/ios
. If you are using an SSL certificate with
PaperCut that is trusted by your iOS devices, you can use an HTTPS URL of the form https://[primary-server]:9192/ios
.
You can find http://[primary-server]:9191/images/icons2/72x72/web-client.png
.
an icon at
• You can access the PaperCut App for iOS devices from Safari using a URL of the form http://[primary-server]:9191/ios
. From here, you can either continue to use the app in Safari, or choose Add to Home Screen from the "arrow" menu. Launching the App from the home screen is recommended for the best experience.
23.4. Email to Print
Email to Print allows users to print by emailing their documents to a special address. No client software or drivers are required, providing a simple way for your organisation to print from any device that can send an email.
Email to Print is part of a collection of solutions to manage mobile and BYOD printing. For more information see
382
Mobile & BYOD Printing
Chapter 23, Mobile & BYOD Printing.
23.4.1. How Does it Work?
• Each printer has a unique email address e.g.
• Users compose an email, attach printable document(s), and email to the printer's address.
• PaperCut receives the email and prints the documents on behalf of the user.
Figure 23.24. Email to Print workflow
23.4.2. Solution Summary
• Easy to use, easy to set up.
• Works with nearly any device (anything that can send an email with an attachment).
•
• All print options are locked to the OS print queue defaults.
Tip
It is possible to set up multiple OS print queues for the one printer with different default settings e.g.
one for single-sided, one for double-sided.
Tip
Email to Print can be used in conjunction with Find Me Printing. Rather than one email address per
383
Mobile & BYOD Printing printer, there can be a single address for multiple printers. Users could then release their jobs at the printer of their choice.
Tip
Email to Print can be used in conjunction with PaperCut Internal Users. This allows users without a
(users managed by PaperCut NG)” for details.
Email to Print can also be used to create a guest printing solution for visitors and guests with BYOD
devices. See Section 31.2, “Anonymous Guest Printing” for details.
23.4.3. Before You Start: Aliases
When processing Email to Print jobs, PaperCut will connect to a single mailbox on a mail server. The mailbox will receive the emails of all printers, where each printer has its own email alias. This is achieved in one of three possible ways:
1.
Email forwarding - If options 1 and 2 are not possible with your email server, another option is to configure one mailbox per printer.
Each mailbox could then forward all mail to the "main" mailbox e.g.
is a mailbox that forwards to [email protected]
.
2.
Dynamic aliases
Many email servers support the dynamic alias "
+ syntax" e.g.
gets delivered to the printing mailbox. This is the simplest option to set up and maintain. However, removing or renaming a dynamic alias doesn't stop emails for the now defunct printer name. Also, the email addresses are arguably not as nice to look at!
3.
Server-side aliases - The email address for each printer is an email alias of the mailbox e.g.
is an alias of [email protected]
. This is the recommended approach when using Google Apps (gmail) and Outlook.com.
Pick a strategy that suits your environment and you are ready to start.
23.4.4. Prepare the PaperCut Server
1.
Configure your SMTP server details in PaperCut at Options
→
Notifications.
This is required so PaperCut can respond to user emails e.g. to let them know their job has been received.
Tip
When configuring your SMTP settings, use a real, attended From address. Users may reply to this address to ask questions. They will have a better experience if they receive a reply.
2.
Configure a user facing server address at Options
→
Advanced
→
Server Address
→
Server address
presented to users.
Email to Print sends emails to users that include links to the PaperCut server, so it needs to know the server's network address. If you would like to support Email to Print from the internet, this address will need to resolve both internally and externally to your network i.e. a fully qualified public DNS name.
For more details see Section 33.1.1, “Server address presented to users”.
23.4.5. Setting up a Mailbox
1.
Set up a new mailbox on your email server. Email to Print supports mailboxes with either POP3 or IMAP protocols.
384
Mobile & BYOD Printing
This mailbox will receive all emails for Email to Print. Each email will be deleted from the email server after it has been processed, so the storage requirements should not be large.
Tip
If you are using Gmail to host your mailbox, there are default actions for emails deleted. These actions are based on the protocol being used. POP3 keeps a copy of the email in the Inbox, while
IMAP archives it. If you prefer a different behavior, you can log into the Gmail account and change the following settings:
Settings
→
Forwarding and POP/IMAP
→
POP Download
→
When messages are accessed
with POP -
Delete
,
Mark or
Archive
[your org's] copy
Settings
→
Forwarding and POP/IMAP
→
IMAP Access
→
When a message is marked as
deleted and expunged from the last visible IMAP folder -
Archive
,
Move to the Bin or
Delete forever
Important
Do not use your personal email address for testing, unless you want to print every PDF ever sent to you! One of our developers did this. It wasn't pretty.
2.
Navigate to Options
→
Mobile & BYOD
→
Email to Print and check Enable Email to Print.
3.
Configure the section Receiving Email Account / Mailbox according to your mail server and newly created mailbox. Note that with some email servers, the Username may not be in the email address format.
The remaining settings are discussed later in this chapter. The default values will suffice for testing.
385
Mobile & BYOD Printing
Figure 23.25. Email to Print configuration
23.4.6. Testing Email to Print
1.
Navigate to Printers
→
Printer List and choose a printer for Email to Print testing.
2.
In the Email to Print section, give the printer a unique and simple email alias.
3.
Depending on your chosen alias type, configure the email server to point the new email alias to the Email to
Print mailbox (see Section 23.4.3, “Before You Start: Aliases”).
4.
Pick a test user account from the Users, tab and ensure it has an associated email address you can send an email from (the Primary email or Other emails fields). If you don't have a test email account, you can temporarily assign your own email address to the test user.
5.
From the test user's email address, compose a new email, attach a PDF, and send it to the printer's email address (the alias, not the mailbox).
6.
link in this email. Your job should now print!
7.
Check your job printed successfully, and inspect the print log at Printers
→
Job Log.
“Adding support for Microsoft Office Documents”.
Continue with Section 23.4.7, “Customization” below to tweak settings to your site's needs.
386
Mobile & BYOD Printing
23.4.7. Customization
The following customization settings can be found at Options
→
Mobile & BYOD
→
Email to Print.
Sender Verification
This option controls how PaperCut will respond when it receives an Email to Print job from a user.
The default setting, Verify sender. Users must click a verification link., will send an email with a link the user
of this setting is to verify the sender of the email actually owns the email address, as it is often trivial to fake/forge/spoof the sender address. In the Email body for this setting, the special replacement marker
%verify-link% is required.
If verification of the sender address is not important, the setting Do not verify sender. Respond to job with
confirmation. may be used. When this setting is used, jobs are processed immediately, and the user receives an email to let them know their job was received. In the Email body for this setting, the special replacement marker
%client-url% may be used as a link to the Mobile Client, which will show the job's status.
Anonymous/Guest Submission
This item enables the sending of Email to Print jobs from anonymous guest users. These jobs are sent to a special guest printer alias. Jobs will be logged to the specified user (default is guest-user
.)
See Section 31.2.1, “Anonymous Setup” for more information.
Error Responses
These options allow the customizing of response emails sent to users when things go wrong.
Nothing to print (no valid attachments) - Used when an email is received but no valid attachments were found. The user might have forgotten to attach their document, or perhaps attached an unsupported document type.
Other - Used when any other problem occurs e.g. if the document was corrupt and couldn't be printed, or something went wrong with the print driver attempting to print.
that apply to both Email to Print and Google Cloud Print.
23.4.8. Interaction with other features
23.4.8.1. Pop-ups (account selection, confirmation, print scripts)
When users have pop-ups configured, jobs will hold until the pop-up is addressed e.g. for shared account selection the user must choose an account to allocate the job to, before it will be printed. When using Email to Print, pop-ups
the Mobile Client. If most or all of your users have pop-ups configured, you may like to tweak the templates to indicate they must follow the included link to progress their job.
For more information about the Mobile Client see Section 23.8, “Mobile Client”.
23.4.8.2. Hold/Release Queues
Hold/release queues allow jobs to be held in a queue and later released by a user. This can be used, for example, to require that users are physically at the device to collect their job ("secure print release").
Hold/release queues can be used with Email to Print in the same way as other job types. For more information on
hold/release queues see Chapter 13, Hold/Release Queues & Print Release Stations.
23.4.8.3. Find Me Printing
Find Me Printing removes the need for a user to choose a printer when printing their job. Instead they print to a
"virtual", sometimes called "global", queue. They then release their job at the device of their choosing. PaperCut handles routing of the job to the right printer.
Find Me Printing can be used with Email to Print in the same way as other job types. For more information see
387
Mobile & BYOD Printing
Chapter 14, Find Me Printing and Printer Load Balancing.
23.4.8.4. Internal Users
Internal Users are users that only exist in the PaperCut database, not in the organization's domain. They can be used to set up users for printing quickly (or have users set up their own account) without having to go through the normal process of creating full domain accounts.
Internal Users may be combined with Email to Print, allowing users to register their own account (and email address) to set themselves up for printing. The recommended approach is as follows:
1.
adds a link to the login screen for users to create a new username, password and email.
2.
jobs from unknown email addresses to be held until the email "becomes known". When the user sends their first job via Email to Print, they will receive a response email asking to verify their email address by logging in. This default template should be changed to say "If you do not have a username, please create one via the Register link on the login screen" or something similar.
After the user has verified their email address, their job will continue to print. Future jobs will print as per normal.
23.4.8.5. Adding support for Microsoft Office Documents
Email to Print will print PDF attachments by default. You can add support for Microsoft Office document attachments by configuring a Web Print Sandbox running Microsoft Office. The Web Print Sandbox functions as a document conversion service. Incoming Microsoft Office attachments are sent to the sandbox, and the associated Microsoft
Office program automatically converts the source document to a PDF file. The PDF is then sent to the printer.
Microsoft Office.
23.4.9. Rollout
The following is a list of considerations when moving from a test Email to Print environment that is working as desired, to a wider or organization-wide rollout.
• Create and publish printer aliases for all printers available via Email to Print. This could involve:
• Adding the printer's email to a sign on the printer
• Publishing a web page with email addresses for all printers
• Adding printer email addresses to a shared address book
• Modify the procedure for creating new printers in PaperCut to optionally include an Email to Print alias.
23.4.10. Advanced Configuration
The following Email to Print settings are for advanced users or special cases, and should not normally need to
information on advanced configurations.
Config Name
email-printing.debug
email-printing.service-freq-secs email-printing.imap-read-folder
Description
This can be set to
Y to enable detailed logging of Email to Print emails received, emails sent, and how PaperCut is connecting to the email server.
By default, PaperCut will check (poll) for new emails every 20 seconds. This config item can change the polling frequency. Less than 20 seconds is not recommended so not to burden the email server. If this value is too large, users will find that sometimes jobs will take a long time to print. How long "too long" might be will vary between sites.
By default, PaperCut will look at the 'Inbox' folder of the mailbox. This is usually the right setting for most mailboxes. When using IMAP as the protocol, emails can be from any folder on the mail server; so if you would like to read emails
388
Mobile & BYOD Printing
Config Name Description
from a specific folder (e.g. setting a rule to forward emails with attachments to a pre-defined 'PrintQueue' folder) you can set the folder name here.
Table 23.4. Email to Print Advanced Configuration
23.4.11. Setting Printer Defaults
Email to Print printing is performed by the Print Provider running on the print server of the target printer.
Email to Print will use the default printer settings on CUPS print servers.
Windows default printer settings are not available to the Print Provider service when it is running under the SYSTEM account. These are the settings in Start
→
Devices and Printers
→
your printer
→
Printing Preferences
Windows services, including the Print Provider service, run under the SYSTEM account by default. If you want Email to Print to use the Windows printer defaults (Printing Preferences) then you will need to run the Print Provider service under a user account that has access to the Windows printer setttings.
You can do this for
PaperCut Print Provider in Start
→
Control Panel
→
Administrative Tools
→
Services
by going to Properties
→
Log On and setting the account to a user account that has access to the Windows printer setttings.
23.4.12. FAQ
Q:
Can multiple documents be printed at once?
A:
Yes, all attachments are printed (when the attachment type is supported).
Q:
Can a job be printed on more than one printer at a time?
A:
Yes, the job will be printed to each printer in the To or CC field of the email.
Q:
Will you add support for HTML formatting in the reply emails?
A:
Probably. Please email support to let us know you're interested!
Q:
I encrypt/sign my emails, do you support PGP and similar features?
A:
At this time we support plain emails. If you need support of other features, please email support to let us know you're interested!
Q:
I'd like to support Email to Print without assigning email addresses to users (and without requiring users to associate their own address with their account) i.e. to allow printing without user-level control. Will you add support for this?
A:
Probably. One possible solution would be to allocate all jobs from unknown emails to a special user account
(e.g.
guest
). Please email support to let us know you're interested!
Q:
My email server supports SPF (Sender Policy Framework) header checking. Can you add functionality to send a confirmation response when it checks out, and a verification response when it doesn't?
A:
Maybe. Please email support to let us know you're interested!
23.4.13. Troubleshooting
389
Mobile & BYOD Printing
Q:
My users are having my Email to Print response emails flagged as spam. How can I prevent this?
A:
1.
Ensure you have configured a public DNS name for your PaperCut server and have configured it at
Options
→
Advanced
→
Server Address
→
Server address presented to users, so your response emails do not contain (internal) IP addresses.
2.
Ensure you are using a valid SMTP 'From' address (Options
→
Notifications
→
Email Options
→
From
address). For best user experience we recommend using an attended email address.
Q:
The links in my PaperCut response emails contain IPs. How can I use a DNS name?
A:
Configure the public DNS name for your PaperCut server at Options
→
Advanced
→
Server Address
→
Server address presented to users.
Q:
The Email to Print status in the admin interface says there is an error. What should I do?
A:
1.
Check the App. Log tab for any obvious errors.
2.
Check your Email to Print mail server configuration. Ensure the server name, username, password etc.
are all correct.
3.
If there is no obvious cause, contact support for assistance.
Q:
Email to Print jobs are not coming out of the printer, but the status in the admin interface says OK. What should I do?
A:
1.
Check the App. Log tab for any obvious errors.
2.
Check the Realtime Activity section on the Dashboard tab. This contains a lot of information about the state of print jobs. Try sending a new Email to Print job while watching this status area. Look for messages about the job being held in a hold/release queue, etc.
3.
Is the job:
• canceled, because the email address was unknown?
• canceled due to filters or not enough credit?
• awaiting the user to verify their email?
• awaiting the user to click a job verification link? (is the email in the user's spam folder?)
• awaiting account selection, job confirmation, or a print script pop-up? (try opening the Mobile Client)
• held in a hold/release queue?
4.
If it's still a mystery, contact support for assistance.
23.5. Web Print (Driver-less printing via a web browser)
Web Print is a driver-less printing service that allows users to print by uploading documents from a web browser. No client software or driver installation is required. Web Print provides a simple way to enable printing for laptop, wireless and anonymous users without the overhead of installing printer drivers and managing server authentication.
The recent growth in popularity of laptops and other small devices such as Netbooks and smart phones is changing the landscape of network printing. Where it was previously normal to only allow printing from in-house systems, there is now a growing need to support casual printing from user-owned devices. Providing users with information about how to configure these devices can be inconvenient and complicated, due to issues such as drivers and authentication, and in some situations may not be possible at all.
Due to this complexity, many organizations opt to simply disallow printing from user-owned systems. A common workaround in these environments is for users to send themselves a document (e.g. via email, on a USB drive) and
390
Mobile & BYOD Printing print from an in-house system. Web Print works in a similar way: it allows a user to upload their file to an in-house system (known as a Web Print server) and have this system perform the printing on their behalf.
With Web Print, users are authenticated when they log into the PaperCut NG end-user web interface. Any documents they upload can then be tracked against their user name. Users have access to the standard selection of features normally available for in-house printing, including access to shared accounts.
Figure 23.26. Web Print architecture overview
23.5.1. Key Features
Some of the key features of PaperCut's Web Print solution include:
• Simple wizard style interface, accessed from any web browser.
• Users authenticate with their regular (network / domain) logins.
• 100% web based. No drivers, client software, or browser plugins required.
• File uploads with progress indicator (in the style of GMail attachment uploads).
• Supports popular document formats including PDF, DOC/DOCX (and other Microsoft Office Word formats),
XLS/XLSX (and other Microsoft Office Excel Formats), PPT/PPTX (and other Microsoft Office PowerPoint formats), and Microsoft XPS (XML Paper Specification).
• Users select printers from an auto-generated list or a clickable printer map, which can be designed or imported using open standards and free software.
23.5.2. Introduction to Web Print
Web Print works in two ways.
• It can print PDF files directly.
• It can accept popular file formats and convert them to print jobs using common applications. This is done by orchestrating applications such as Adobe Reader
TM
, Microsoft Office
TM and the Microsoft XPS Viewer as background server-side tasks. Using this approach ensures that maximum print compatibility and quality is maintained.
Important
Adobe Reader, Microsoft Office and XPS Viewer are not supplied with PaperCut. It is your
391
Mobile & BYOD Printing responsibility to purchase and conform to the licensing requirements of any third party software.
23.5.2.1. Supported Applications and File Formats
The following table lists the applications that Web Print may use to render uploaded documents into print jobs.
Before a file format can be accepted as an upload, its supporting application must be installed.
Note that when running Web Print on Windows in default mode, Microsoft Office applications are not available due
between Default Mode and Sandbox Mode.
Application File Format(s)
Adobe Reader 9, Adobe Reader X (10), Adobe Reader XI (11)
Microsoft Office Excel 2007, 2010
Microsoft Office PowerPoint 2007, 2010
Microsoft Office Word 2007, 2010
XLS, XLSX, etc.
PPT, PPTX, etc.
DOC, DOCX, etc.
Microsoft XPS Standalone Viewer (Essentials Pack) - For more information
please see Section 23.5.7, “XPS Viewer Installation Instructions”
XPS
Table 23.5. Web Print Supported Applications and File Formats
23.5.2.2. Security Considerations
Before setting up Web Print it is worth considering any security implications. Because Web Print allows any user with access to the PaperCut NG user web interface the ability to upload a document for printing, it naturally increases surface area for attack.
More specifically, security vulnerabilities that might usually be considered local, because they are triggered by opening a document in a Microsoft Office application or Adobe Reader can become a remote vulnerability. This is because these same applications are used to render print jobs on the server after the user has uploaded their document.
Much of the security risk can be mitigated through security best practice, such as regularly applying security updates to the orchestrated applications. Organizations that are very security conscious may wish to consider the sandbox approach. Sandboxing the Web Print server provides an extra layer of protection/isolation.
23.5.3. Setting Up Web Print
Web Print may be configured in one of two possible modes: Default Mode or Sandbox Mode.
Default Mode involves running the Web Print software on the same system as the PaperCut NG primary server. On
Windows, it runs as a Service. This is the fastest and easiest way to get Web Print working. However, only printing
Sandbox Mode uses a sandboxed or virtualized system, isolated and dedicated to the task of processing Web Print jobs or converting documents for Email to Print. Sandbox Mode takes a little more time to configure but offers
Primary Server Type
Microsoft Windows
Apple Mac
Linux running CUPS
Default Mode
Yes (PDF only)
Yes (PDF only)
Yes (PDF only)
392
Sandbox Mode
Yes. All formats supported
Yes. All formats supported
Yes. All formats supported
Mobile & BYOD Printing
Primary Server Type Default Mode
Novell OES Linux
Table 23.6. Web Print Setup Options (by platform)
No. Default Mode not supported
Sandbox Mode
Yes. All formats supported
23.5.3.1. Default Mode Setup
Default Mode involves running the Web Print software on the same system as the PaperCut NG primary server. It is the fastest and easiest way to get Web Print working. It is suitable for testing Web Print functionality or where only
PDF support is required.
In Default Mode the Web Print software runs as a service (background process or daemon) that is responsible for watching a directory for documents submitted by users e.g. PDFs. When a new document is detected, the background process opens the document and prints it.
23.5.3.1.1. Web Print Default Mode Setup for Windows Servers (PDF Only)
This section describes how to configure Web Print on the same Windows system as the PaperCut primary server.
This is the fastest and easiest way to get Web Print up and running on a Windows system. Due to the inability of
Microsoft Office or XPS Viewer applications to run as a system service, these file formats are only available on
information.
Web Print Default Mode supports the printing of PDF documents by default on Windows systems. No additional configuration should be required.
Important
Check in Windows Services, that the Web Print service is configured to start automatically. Also, start the service now, if needed.
To confirm that everything is configured correctly, check the Web Print Status section under Options
→
Mobile &
BYOD
→
Web Print. The status should be listed as
OK
. The Web Print option will also need to be enabled on at least one printer. If there are any status issues, or if basic Web Print testing produces some errors, please consider these limitations/requirements:
• The printers targeted for use via Web Print must be queues that are managed by the Primary PaperCut Server.
This includes print servers with the PaperCut Secondary Server installed.
• If you wish to print to remote printers, then the PaperCut NG Web Print server needs to run under a user account that has permission to access these printers.
Create a new user account called webprint
(or equivalent). If it is not possible to create a domain user or the system is not a member of a domain, then create a local user account instead. The password for this account
should be set to never expire. At a minimum, this account needs access to all the printers you wish to print to.
• The printers (as configured on the server) must have working compatible drivers.
• Administrators may find the following log file useful
[app-path]/providers/web-print/[platform]/logs/web-print.log
in diagnosing issues:
• As a final step you will need to enable Web Print for each printer via the Printers
→
[PrinterName]
→
Advanced Config
→
Enable Web Print checkbox.
23.5.3.1.2. Web Print Default Mode Setup for Mac and Linux Servers (PDF Only)
The Web Print Default Mode supports PDF documents by default on Mac and Linux systems (running CUPS). No additional configuration should be required. To confirm that everything is configured correctly, check the Web Print
Status section under Options
→
Mobile & BYOD
→
Web Print. The status should be listed as
OK
. The Web Print
393
Mobile & BYOD Printing option will also need to be enabled on at least one printer. If there are any status issues, or if basic Web Print testing produces some errors, please consider these limitations/requirements:
• The printers targeted for use via Web Print must be queues that are managed by the Primary PaperCut Server.
This includes print servers with the PaperCut Secondary Server installed.
• The printers (as configured on the server) must have working compatible drivers.
• Linux: The Primary Server must be running CUPS version 1.2 or higher.
• Administrators may find the following log file useful
[app-path]/providers/web-print/[platform]/logs/web-print.log
in diagnosing issues:
Default Mode for Novell OES Linux and iPrint is not available. Novell OES users should implement the Sandbox
Mode (in the following section).
23.5.3.2. Sandbox Mode Setup
A Web Print Sandbox (in Sandbox Mode) runs the Web Print software in a dedicated Windows system, often a virtual machine. Documents are opened and rendered by standard GUI applications such as Adobe Reader and
Microsoft Office applications.
Use Sandbox Mode when you need to:
1.
Support printing of Microsoft Office documents from Web Print
2.
Support printing of Microsoft Office documents from Email to Print
3.
Render documents in a secure, sandbox environment away from your main server.
Sandbox Mode takes a little more time to configure but offers several advantages, such as support for Microsoft
Office formats and improved security. Security is gained by opening and printing documents on an isolated system, separate from the PaperCut primary server; with the only connection between the two being a simple file share / mapped drive.
Tip
PaperCut is shipped with a high quality rendering engine for PDF documents. However, if you require documents to be rendered by Adobe Reader, this is also supported. Simply install Adobe Reader in your Web Print Sandbox.
Prerequisites:
• A dedicated, standalone, cleanly installed system or virtual machine.
• Windows operating system (suggested: Windows Vista or later).
• Adobe Reader 9 or later (optional)
• Microsoft Office 2007, 2010 or 2013 (to support Office formats)
• Microsoft Standalone XPS Viewer / XPS Essentials Pack (to support Microsoft XPS) - download here
[http://www.microsoft.com/downloads/details.aspx?FamilyID=b8dcffdd-e3a5-44cc-8021-7649fd37ffee]
To set up Web Print in Sandbox Mode:
1.
Make sure Default Mode is disabled. See Important box below:
Important
First, before setting up Web Print in Sandbox Mode, ensure Web Print in Default Mode is disabled as follows:
394
Mobile & BYOD Printing
• On Windows, stop and disable the
PaperCut Web Print Server
System Service (set its
Startup type to Disabled).
• On Mac and Linux, use a text editor to edit the file
[app-path]/providers/web-print/[platform]/web-print.conf
and change setting enabled to enabled=off
.
Remove the Web Print status files (named web-print-server.activity
and web-print-server.status
) located in the hot-folder
/Applications/PaperCut
NG/server/data/web-print-hot-folder
.
Restart the server (or services) to ensure the change is applied.
2.
Set up a new virtual machine using VMware Server [http://www.vmware.com/], Microsoft Virtual Server
[http://www.microsoft.com/windowsserversystem/virtualserver/] or VirtualBox [http://www.virtualbox.org/], or set up a standalone system e.g. a dedicated desktop PC. This system will house the Web Print server software and any required printing applications, and will be termed the Web Print server.
This system does not need access to all network resources, but will need access to the hot folder share. This is
Important
Ensure that the system clocks on the primary server and the web print sandbox are synchronized to a common clock. Time differences between these systems may cause problems with the web print system.
3.
Create a new user account called webprint
(or equivalent). The password for this account should be set to
never expire. At a minimum, this account needs access to the printers, the ability to run local programs, and the
ability to access the hot folder share (created in step 7).
4.
Skip this step if using the Sandbox for Email to Print only. Log in as the webprint user. Add print queues for the printers that should be made available to users via Web Print. The print queues should be added in the same way they would to a workstation. They should point to the print queues hosted on the print server, i.e. a
Network Printer mapped to
\\server\printer-share
. It is important that the jobs pass via the queue on the
server - do not add a Local Printer. You should also add the printers using the print server's machine name and not an IP address.
5.
Formats”. The applications installed will determine which file formats are available to users for printing.
As the webprint user, open a file in each of the installed applications and print to several different printers, ensuring that all works as expected. IMPORTANT: Make sure you permanently acknowledge any license agreement screen, initial-run wizard, or customer experience program dialog during this process.
Tip
• When installing Microsoft Office applications, choose all optional components for installation.
This will prevent printing issues occurring due to missing components.
• Adobe Reader X introduced a Protected Mode setting which prevents printing from the command interface used by Web Print. Using Adobe Reader therefore requires the Protected
Mode feature to be disabled. Web Print will automatically disable Protected Mode for your webprint user. (You may also disable Protected Mode manually by disabling the Enable
Protected Mode at startup setting in Adobe Reader under Edit
→
Preferences
→
Security
(Enhanced))
6.
Configure the Web Print server to automatically log in as the webprint user on startup. The service will then run when Windows is started, and be logged in as this user.
395
Mobile & BYOD Printing
• Automatic logon for Windows Vista/7
[http://windowshelp.microsoft.com/Windows/en-US/help/e224c60c-0708-48ba-ae97-fcdaddb3dd9d1033.mspx]
Tip
Windows Vista/7 machines on a domain may require direct editing of the registry as described here: Microsoft Technet Configuring Accounts to Autologon
[http://technet.microsoft.com/en-us/library/gg241187(v=ws.10).aspx].
You may want to consider a Group Policy Object (GPO) to make the registry changes.
• Automatic logon for Windows XP [http://support.microsoft.com/kb/315231]
7.
The primary server and the software on the sandboxed Web Print server communicate via a standard network file share. On the PaperCut primary server, share the folder web-print-hot-folder located at
[app-path]\server\data\web-print-hot-folder\
. The hot folder facilitates communication between the primary server and the Web Print server.
Tip
By default, Web Print will use this folder, not a sub-folder. You do not need to create a sub-folder in this folder.
Samba sharing on Linux
On the Linux PaperCut primary server, name the share
PCWebPrint
, and adjust both the Sharing and
Security (NTFS/file) permissions of the
PCWebPrint share to allow the webprint user read and write access.
The following Samba configuration settings may be useful.
[PCWebPrint] comment = PaperCut Web Print Hot Folder path = /home/papercut/server/data/web-print-hot-folder/ public = no writeable = yes read only = no valid users = webprint
You will also need to add the webprint username to Samba via smbpasswd -a [username] and you should consider disabling the
[home] shares in your smb.conf
.
Important
Ensure that your umask and Samba settings allow for the papercut linux user to be able to read and write to all files in the web-print-hot-folder
. When using Novell and Linux it is possible that the Web Print Sandbox will create files owned by a different user than the PaperCut
Application Server runs as, preventing the files from being accessed.
Samba sharing on Mac
On the Mac PaperCut primary server, adjust both the Sharing and Security (NTFS/file) permissions of the
PCWebPrint share to allow the webprint user read and write access.
• Create a user in Users & Groups, which will be used to read and write to the shared folder. Name the user webprint and assign it to the admin group.
• In Sharing -> File Sharing, share the folder
[app-path]\server\data\web-print-hot-folder\
396
Mobile & BYOD Printing and add Read & Write permissions for the webprint user.
• Click on Options... on the same menu and check the webprint user under Windows File Sharing.
• Set read access to everyone on the web print hot folder and any files under it by creating a new ACL. Open the Terminal app and type under
[app-path]\server\data folder: sudo chmod +ai "everyone allow read,file_inherit" web-print-hot-folder
8.
Log in to the Web Print server as the webprint user. Map the
W: drive to the hot folder share you have defined. Ensure that the option Reconnect at logon is selected when mapping the drive. If your webprint user's credentials on the PaperCut primary server are different from the Web Print Sandbox's user, click on
Connect using different credentials and enter them.
9.
Test that the file share can be accessed and written to from the Web Print server (e.g. by creating a new text file on
W:
). It is also recommended to test in the other direction as well, and confirm that files created on the primary server in the folder web-print-hot-folder can be opened/seen by the Web Print server.
10. Run the main PaperCut NG installer on the Web Print server, and select the Web Print server installation
(sandbox mode) install option.
11. Configure the webprint user to run
[app-path]\providers\web-print\win\pc-web-print.exe
at login i.e by adding a shortcut to the user's
Startup folder.
12. Reboot the system. Ensure the system automatically logs in as the webprint user when it starts up, and that the PaperCut Web Print dialog is displayed shortly afterwards.
Figure 23.27. The PaperCut Web Print dialog
13. Log into the PaperCut NG admin interface and navigate to Options
→
Mobile & BYOD
→
Web Print.
In the section titled Web Print Server, ensure that the Status is OK. If the status indicates an error, see
Section 23.5.6, “Troubleshooting Web Print Problems” for assistance.
If your sandbox is for Email to Print only, you should see the full set of supported document types in the Email to Print setup section. If there is a problem, you should temporarily enable Web Print so you can take advantage of the additional status information provided in the Web Print setup.
397
Mobile & BYOD Printing
Figure 23.28. Web Print Server status OK
Feature Tour” to submit a test print job and test functionality.
15. As a final step you will need to enable Web Print for each printer via the Printers
→
[PrinterName]
→
Advanced Config
→
Enable Web Print checkbox.
23.5.4. Web Print Testing and Feature Tour
1.
Log into the PaperCut NG user interface and click the Web Print link in the navigation menu.
Figure 23.29. Web Print link in the user interface
398
Mobile & BYOD Printing
2.
The front page contains a list of active and recently submitted Web Print jobs for the logged in user. At first, the list will be empty. Later, the list will show the status of submitted jobs.
Figure 23.30. The front Web Print page before any jobs have been submitted
The message at the top of this page may be customized e.g. to include site specific information or other details
Figure 23.31. Customizable Web Print introductory message
The administrator may restrict access to the Web Print feature by group, by IP address/range, or disable the
feature entirely. See Section 23.5.5.3, “Advanced Web Print Configuration” for details.
3.
Click Submit a Job to start the Web Print wizard.
4.
The first step of the Web Print wizard is selecting a printer. This is the printer that the uploaded document will print to.
399
Mobile & BYOD Printing
Figure 23.32. Web Print wizard step 1: list of printers available for Web Print
The printers available for Web Print are chosen by the administrator. See Section 23.5.5, “Web Print
Configuration” [403] for details.
Printer Maps / Custom Printer Selection Lists” for details.
Tip
5.
After selecting a printer, the second step is to select the print and/or account selection options. Most users will simply see an option to select the number of copies to print:
Figure 23.33. Web Print wizard step 2: selecting the number of copies for a Web Print job
The maximum number of copies a user may submit is configurable via the user.web-print.max-copies
config editor key. See Section 23.5.5.3, “Advanced Web Print Configuration” for details.
Users with print account selection options will see additional options on this page, equivalent to what they would see on their popup:
400
Mobile & BYOD Printing
Figure 23.34. Web Print wizard step 2: account selection options
Note
The developers hope to be able to support grayscale and duplex print options in the near future.
6.
After selecting the print options and/or account selection settings, the third and final step in the Web Print wizard is to upload a document to print. This page lists the applications and associated file extensions that are supported.
401
Mobile & BYOD Printing
Figure 23.35. Web Print wizard step 3: upload a document
for assistance.
Once a document has been selected and Upload & Complete » is pressed, the file will begin uploading to the server.
402
Mobile & BYOD Printing
Figure 23.36. Web Print wizard step 3: document upload in progress
The maximum file size a user may upload is configurable, with a default of 100MB. See the option Maximum
document/file upload size in Section 23.5.5.3, “Advanced Web Print Configuration” for details.
7.
Once the document upload is complete, the user is returned to the front Web Print page. The table now displays the status of the user's job. The status will change to indicate the progress of the job from rendering to printing, and job details such as cost and number of pages will be populated when known. The user may stay at this page to track the status of the job, or navigate away / close their browser - the job will not be affected.
Figure 23.37. List of active Web Print jobs
At this stage the PaperCut application server accepts the uploaded document and sends it to the Web Print server. The Web Print server renders the document into a print queue by automating the process of opening the application (e.g. Adobe Reader) and printing to the target printer.
23.5.5. Web Print Configuration
Administrators must nominate which printers are available with Web Print. Smaller organizations may wish to make all printers available, while larger organizations may want to restrict to a subset e.g. limiting access to printers located in public areas. A printer can be web print enabled via Printers
→
[select printer]
→
Advanced
Configuration
→
Enable Web Print (users may upload documents to print).
Tip
To easily enable all printers for use with Web Print:
1.
Select Enable Web Print (users may upload documents to print) on the [Template printer].
2.
Copy the setting to all other printers using Copy settings from printer to printer.
General Web Print configuration settings can be found in the admin interface at Options
→
Mobile & BYOD
→
Web
403
Print.
Mobile & BYOD Printing
Figure 23.38. Web Print settings in the admin interface
Setting
Enable Web Print (allow users to uploads documents for printing)
Maximum document/file upload size
Only allow uploads from users in this group
Allowed user IP addresses
Introductory message
Table 23.7. Web Print Settings
23.5.5.1. Print Options for Web Print Jobs
404
Description
When enabled, a Web Print item appears in the navigation menu of the user web interface, and users are able to use Web Print functionality. When disabled, this item is not visible, and the Web Print functionality is not available to users.
If a user uploads a document greater than the specified size (in MB), their upload will be rejected.
This option may be used to restrict Web Print access to a particular group of users. When this option is enabled users not in the specified group will not see the Web Print item in the navigation menu.
This option may be used to restrict Web Print access to a selected IP address range. For example, access might be limited to systems on a wireless network
(i.e. force users on the wired network to use standard print queues).
Address ranges may be entered in the format: 1.2.3.0/255.255.255.0
.
This message appears on the first page after a user clicks the Web Print item, and can be used to explain the service, offer site-specific advice or other information to assist the user.
HTML is supported, e.g. <p> tags may be used to start a new paragraph, or an
<a> tag may be used to provide a link.
Mobile & BYOD Printing
print options such as grayscale, duplex, paper size etc. are selected based on the default options of the print queue.
If it is important to provide the user with a print option choice (e.g. when the same printer has trays for Letter and
Legal paper), two print queues may be created and set up with different default settings e.g. one print queue called
Library Printer (Letter) defaulting to the Letter size and tray, and a second print queue (pointing to the same physical printer) called
Library Printer (Legal) defaulting to the Legal size and tray.
Note
The developers hope to be able to support grayscale and duplex print options in the near future.
23.5.5.2. Designing Printer Maps / Custom Printer Selection Lists
Part of the Web Print wizard involves selecting the target printer from a list. This is great for most environments, but organizations with many printers or large sites may prefer something that provides users with more context about the printer they are selecting.
Figure 23.39. Web Print: selecting a printer from the list, which may be replaced with a map or custom list
Using a graphical map can assist users to find the most convenient printer. A map allows a user to select a printer by location, rather than guessing the printer's location based on its name. Using printer maps or other types of custom printer lists in PaperCut NG does not require any special or proprietary software - they can easily be implemented using open standards and free software.
405
Mobile & BYOD Printing
Figure 23.40. Web Print: printer selection map with a simple floor plan
Custom content is loaded in place of the printer list, by placing the appropriate file at
[app-path]/server/custom/web/ as described in the following table:
File Name
printer-map.html
printer-map.svg
Description
If this file exists, it will be loaded as an HTML page and displayed in an in-line frame (iframe), in place of the printer selection list. The HTML may contain any content or images, including links to other pages (which will also be loaded in the iframe by default).
If this file exists, it will be loaded as an SVG page, and displayed in an iframe in place of the printer selection list. The SVG may contain links to other pages or other SVGs. An SVG can be created using software such as Microsoft Visio or the free/open source Inkscape [http://inkscape.org/], and is a convenient way of displaying a map or floor plan with clickable links.
Table 23.8. Files used for custom printer selection in the Web Print wizard
Tip
Any custom content placed in
[app-path]/server/custom/web/
, such as additional images, can be accessed via a URL beginning with
/custom/
. For example if a file named floor-plan.png
is placed in
[app-path]/server/custom/web/ it can be accessed via the URL
/custom/floor-plan.png
.
406
Mobile & BYOD Printing
Tip
The custom printer map is displayed in an iframe with dimensions 776px x 400px. If the content is larger than this, then scrollbars will be visible (the area will not be expanded to fit the content).
23.5.5.2.1. Example 1: Creating a Printer Map Using an HTML Image Map
This example runs through the process of creating a printer map using HTML with image maps. This method is most suitable if you have floor plan images and/or aerial photos of your site (in PNG or JPEG format). If you have a plan
suitable.
The source for this example can
[app-path]/server/examples/printer-maps/html-image-map/
.
be found at
For this example, we will create a printer selection map with two layers: a site plan, and floor plans. Users first choose a building from the site plan, then a printer from the building's floor plan. We have two buildings: Building A and Building B. Each building has one floor of interest, with identical floor plans and five selectable printers.
Figure 23.41. Web Print: printer selection map with a simple site plan
1.
The first step is to create a file named printer-map.html
at
[app-path]/server/custom/web/
. This file will be loaded as an HTML page in an iframe in place of the default printer selection list, and may contain any content you choose; including links to further pages. Open this file in a text editor.
2.
We then add the site plan image:
407
Mobile & BYOD Printing
<img src="site-plan.png" usemap="#buildings" style="width: 422px; height: 190px; border: none;" />
The usemap="#buildings" attribute tells the image to look for an image map with the name buildings
.
Image maps allow you to make parts of an image "clickable". For more information about the HTML
<map> element see xhtml.com's map element reference [http://xhtml.com/en/xhtml/reference/map/].
3.
Now we define the image map.
<map name="buildings">
<area shape="poly" coords="" href="building-a.html" alt="Building A" title="Building A" />
<area shape="poly" coords="" href="building-b.html" alt="Building B" title="Building B" />
</map>
Here we have defined a new image map called buildings
, with two clickable areas. These areas are polygon shapes ( shape="poly"
), which means we can specify a list of points that will form the outline of the clickable area (i.e. the area inside the points will be clickable).
Clicking the first area will load the page building-a.html
. The alt and title tags provide information about the link, and display a tooltip when the user hovers over the area.
4.
We have defined two areas and the pages they will link to, but we have not yet defined the coordinates for these areas. This is done using the coords attribute of the two area tags. Using an image editor, we can find coordinates for the outline of the two areas. Most image editors, including MS Paint, display pixel coordinates when hovering the mouse over the image.
Using the image editor, we find the following points for Building A (the lefthand building), starting from the top left corner, in
(x,y) format:
(0,48), (84,0), (143,34), (143,142), (60,190), (0,155)
. Pixels are counted from the top-left corner of an image, so the coordinate
(60,190) means "60 pixels from the top,
190 pixels from the left".
5.
We repeat the previous step for the second building to get coordinates similar to:
(242,50), (320,4),
(422,63), (422,135), (332,190), (226,131)
.
6.
Now that we have the clickable area coordinates, we can define them in our image map.
The definition for the area tag when using a poly type shape, tells us that the coordinates are specified in a list of x,y coordinates (i.e. "x1,y1,x2,y2...xn,yn"), so we enter the coordinates in the coords attributes as follows:
<map name="buildings">
<area shape="poly" coords="0,48,84,0,143,34,143,142,60,190,0,155" href="building-a.html" alt="Building A" title="Building A" />
<area shape="poly" coords="242,50,320,4,422,63,422,135,332,190,226,131" href="building-b.html" alt="Building B" title="Building B" />
</map>
7.
Opening printer-map.html
in a web browser should now display the site plan image. Hovering the mouse over each building should display the link cursor, and indicate a link to the respective pages.
8.
The next step is to create the building-a.html
page. Using a similar process to the existing page, we add floor-plan.png
and create an image map for it:
<img src="floor-plan.png" usemap="#printers" style="width: 600px; height: 362px; border: none;" />
<map name="printers">
<area shape="rect" coords="4,289,22,307" href="" alt="building-a\Printer 1"
408
Mobile & BYOD Printing title="building-a\Printer 1" />
<area shape="rect" coords="33,342,51,360" href="" alt="building-a\Printer 2" title="building-a\Printer 2" />
<area shape="rect" coords="58,342,76,360" href="" alt="building-a\Printer 3" title="building-a\Printer 3" />
<area shape="rect" coords="521,7,566,23" href="" alt="building-a\Plotter 1" title="building-a\Plotter 1" />
<area shape="rect" coords="571,88,592,129" href="" alt="building-a\MFP 1" title="building-a\MFP 1" />
</map>
<div>Building A (<a href="printer-map.html">back</a>)</div>
This map is mostly similar to the previous one, except that we have defined five rectangle shapes
( shape="rect"
) and provided a link back to the main site plan ( printer-map.html
).
Rectangle shapes in an
<area> element are defined with the coordinates of top-left and bottom-right corners
(
"x1,y1,x2,y2"
).
9.
Now we have the images and shapes in place for the site plan and one building's floor plan. To finish off this building, we now need to define what happens when each printer is clicked. This is done using a JavaScript function selectPrinter
. Calling selectPrinter('my-server', 'Library Printer') will submit the form on this step of the Web Print wizard, selecting the printer called
Library Printer
, hosted on the print server called my-server
.
We can call this JavaScript function when one of the defined areas is clicked by setting the href attribute as follows:
<area shape="rect" coords="4,289,22,307" href="javascript:parent.selectPrinter('building-a',
'Printer 1');" alt="building-a\Printer 1" title="building-a\Printer 1" />
10. Repeat the previous step for the remaining printers, taking care that the server and printer names are entered correctly. Note that the printer name is the printer's unique name on the print server, and may be different to the printer's "share name".
11. Repeat the steps for creating building-a.html
to create building-b.html
(or simply copy the file and modify to suit).
12. Test the Web Print wizard to ensure that clicking on a building takes you to that building's floor plan, and clicking on a printer submits the form to select that printer. Note that if the names you've used for the printers don't actually exist in your PaperCut NG server, then you'll see an error message about the printer not being available. You may like to modify the details for one of the printers to match a real printer so that the wizard can be tested end-to-end.
The source for this example contains some additional tweaks to improve browser consistency, such as removing the border and white background of the iframe in Internet Explorer.
23.5.5.2.2. Example 2: Creating a Printer Map Using SVG
This example explains how to use an SVG image for a clickable printer map. This method is most suitable if you
Creating a Printer Map Using an HTML Image Map” may be more suitable.
An example SVG floor plan with clickable printers
[app-path]/server/examples/printer-maps/html-image-map/
.
can be found at
Modern web browsers are capable of displaying an SVG file in a similar way to displaying a web page. Mozilla
409
Mobile & BYOD Printing
Firefox and Opera can display SVGs "out of the box", and Microsoft Internet Explorer can display SVGs using the
Adobe SVG Viewer [http://www.ieaddons.com/en/details/Time_Savers/Adobe_SVG_Viewer/] add-on. In addition to drawing the image, parts of the image may be made "clickable" to provide links to other pages or, as in this case, to call a JavaScript function that selects a printer.
In this example we will describe how to take an existing SVG image, and make parts of it clickable so a printer may be selected.
Tip
A Microsoft Office Visio drawing can be saved as SVG and used in this example.
1.
Download and install Inkscape [http://inkscape.org/], the free/open source vector graphics editor, and use it to open your SVG.
2.
Select the object that should be made "clickable". You should see a dotted background around the object.
3.
Right-click the object and select Create Link.
4.
Right-click the object and select Link Properties.
5.
In the
Link Properties
dialog that appears, enter a value for the
Href
field like: javascript:parent.selectPrinter('server', 'printer');
, where server is the name of the print server, and printer is the name of the print queue.
6.
Repeat to create links for each printer in the image.
7.
Select File
→
Save As... and choose a file type of
Plain SVG (*.svg)
. Save the image to
[app-path]/server/custom/web/printer-map.svg
on the PaperCut NG server.
8.
Try testing with the Web Print wizard. The SVG should be visible on the first step of the Web Print wizard, in place of the printer list. Clicking a printer should move on to the next step.
23.5.5.3. Advanced Web Print Configuration
Config Editor” for information about using the config editor.
Config Name
web-print.job-idle-timeout-mins web-print.job-rendering-timeout-mins web-print.max-copies web-print.hot-folder
Description
If a Web Print job remains unchanged for longer than this period of time, it is considered finished and is "cleaned up". The document and associated files are removed, and the job will no longer appear in the user's list of current Web Print jobs.
The default idle job timeout is 20 minutes.
The Web Print server is given this length of time to render a Web Print document. If a print job has not been generated from the document after this time, the job is marked as errored and associated files are removed.
The default job rendering timeout is 5 minutes.
This is the maximum number of copies a user may print via Web Print. This option exists to prevent users accidentally (or thoughtlessly!) printing too much.
When a user uploads a file via the Web Print interface, it is written into the "hot folder", along with a
.metadata
file containing information about how to print the job (the data selected by the user in the Web Print wizard). The Web Print server looks for new files in this folder, and prints them as required. The default hot folder location is
[app-path]/server/data/web-print-hot-folder/
.
An alternate location can be specified using this config key. The location must be local to the
PaperCut NG primary server (it cannot be a network share or mapped drive due to Windows denying share access to the
SYSTEM account).
Table 23.9. Web Print Config Editor Keys
410
Mobile & BYOD Printing
The following configuration options are available in the Web Print server configuration file, located at
[app-path]/providers/web-print/[platform]/web-print.conf
.
Config Name
hotfolder debug options.pdf
Description
The location of the Web Print hot folder. This is generally a mapped drive letter
(Windows) or a mount point that maps to a file share (Mac, Linux). It may also be a local path, if the Web Print server software is running on the same system as the PaperCut NG primary server.
Set to on to enable debug logging.
Set to xpdf to force PDF printing to use the built-in PDF printing routines.
Set to acrobat to force PDF printing to use Adobe Reader.
Table 23.10. Web Print Server Config File
23.5.6. Troubleshooting Web Print Problems
Q:
Applications and File Formats” are not listed under Options
→
Mobile & Print
→
Web Print
→
Status page, or not accepted when uploading a file.)
A:
in the mode that the Web Print server is running in. Some file formats are only supported in sandbox mode.
Next, ensure that the associated application is installed and working. If running in sandbox mode, log in as the webprint user, then open and print a document with the application to ensure the user has the correct permissions.
The next step is to check the Web Print log files. The Web Print server has a handler for each supported application. Each handler has a log file, which may provide more information about why the file format is not available. The handler log files are named web-print-handler-*.log
, where
* is the name of the
application. See Q: for the location of the Web Print logs folder.
Open the log file that matches the application of interest in a text editor (e.g.
web-print-handler-mso-word.log
for Microsoft Office Word documents). Check the log file for any obvious errors, such as not being able to find the application or problems launching it.
For further assistance, contact support.
Q:
The status in the admin interface or on the Web Print dialog is indicating an error. What can I do?
A:
The Web Print server is not running or could not be contacted
When running in Default Mode:
• The service
PaperCut Web Print Server should be running.
When running in sandbox mode:
• The Web Print dialog should be visible on the Web Print server, and the Status should not indicate any error.
• While logged onto the Web Print server as the webprint user, ensure that the mapped
W: drive is accessible and maps to
[app-path]/server/data/web-print-hot-folder/ on the PaperCut NG primary server.
• Open
[app-path]/providers/web-print/[platform]/web-print.conf
on the Web Print server in a text editor, and ensure the hotfolder= option is set to
W:
.
For further assistance, contact support.
411
Mobile & BYOD Printing
Q:
The Web Print service is running as the SYSTEM account, and does not have access to render print jobs.
A:
Default Mode
If running Web Print in Default Mode, check if the printer being printed to is running on the local computer. The
SYSTEM account will not have privileges for printing to remote printers.
service has been correctly configured to run as the webprint user account.
If the printer is local, then check the printer's privileges allow the SYSTEM account to print to it.
If the above steps do not fix the problem, then the failure should be logged in
[app-path]/providers/web-print/[platform]/logs/web-print-handler-pdf.log
support will be able to analyze this file, and help you find out the cause of the failure.
.
Tech
Sandbox mode
If running Web Print in Sandbox Mode, this error may indicate that the service
PaperCut Web Print
Server is running. This service is not required in sandbox mode, and should be disabled.
No valid handler programs installed/defined
The configured hot folder location is not writable.
• Check that the location indicated by Hot folder on the Web Print dialog is correct.
• As the webprint user, navigate to the drive/directory that is mapped to the
PCWebPrint share (
W: on
Windows). Try creating an empty text file. If this action fails, there is a problem with permissions. Check the
Sharing and Security (NTFS/file) permissions for the
PCWebPrint share on the PaperCut primary server.
The webprint user should be allowed read and write access.
• For further assistance contact support.
Other error messages
Check the Web Print server log file web-print.log
. See Q: for the location of the logs directory. For further
assistance, contact support.
Q:
Where is the Web Print logs folder?
A:
Q:
Why is my print queue "currently not available"?
A:
The logs folder is located on the system running the Web Print server software.
On Windows the location of the logs folder depends on configuration and the Windows edition. Logs may be written to
[app-path]\providers\web-print\win\logs\
, or to
%USERPROFILE%\web-print-logs\
(e.g.
C:\Users\[username]\web-print-logs\ on Windows Vista/2008. For a definitive answer, open the file
[app-path]\server\data\web-print-hot-folder\web-print-server.status
on the primary PaperCut NG server in a text editor, and check the line beginning with server.log-file=
.
When using the Web Print interface, some print queues may be giving you the error message: Errored:
Printer '\\servername\queuename' is currently not available.
This can be caused by trying to use Web Print on a print queue that has been deleted, or by trying to print to a print queue that is not installed on the Web Print Sandbox. Please confirm this, by logging into the Web Print
Sandbox as the Web Print user, and attempting to print to the above print queue.
Note
It is important that the jobs pass via the queue on the server - do not add a Local Printer. You should also add the printers using the print server's machine name and not an IP address.
412
Mobile & BYOD Printing
23.5.7. XPS Viewer Installation Instructions
Microsoft Windows XP and Server 2003 administrators can easily install the Microsoft XML Paper Specification
Essentials Pack (XPSEP), which contains the XPS viewer from the Microsoft website. Versions for both 32bit and
64bit are available. By default, Windows Vista and Windows 7 will include a compatible XPS Viewer if .NET
Framework 3.0 is already installed [http://windows.microsoft.com/en-au/windows-vista/what-is-the-xps-viewer].
• Microsoft XML Paper Specification Essentials
[http://www.microsoft.com/downloads/details.aspx?FamilyID=b8dcffdd-e3a5-44cc-8021-7649fd37ffee]
Pack
Customers running Microsoft Windows Server 2008, must install the XPS Viewer from the Features module of the
Server Manager MMC snap-in.
1.
Load the Server Manager MMC snap in via Start menu
→
Administrative Tools
→
Server Manager.
2.
Right-click on Features and select Add Feature.
3.
Check the tickbox for "XPS Viewer", and click Next.
Figure 23.42. Installing the XPS Viewer for Windows Server 2008
4.
Click Install on the 'Confirm Installation Selections' dialog box.
5.
Click Close when the installation is complete.
23.6. Windows 8 Tablets & Windows RT Printing
With the Windows platform being adopted on more and more device types, organizations are seeking knowledge and information on how to support printing and integration with PaperCut. This section discusses Windows mobile device printing and shares some hints and tips.
Please note, this is not a step-by-step guide on everything Windows Mobile. Rather, it will cover the main concepts that will help administrators integrate Windows RT and Windows 8 tablet devices into existing print infrastructure.
413
Mobile & BYOD Printing
The following information comes from our own experiences and customer feedback.
In most cases Windows devices are able to print and use existing Windows server-based print queues. The best approach for supporting users and devices will vary with the device type and purpose. They can be categorized as follows:
• Windows 8 Intel-based devices predominantly used in Desktop Mode
• Windows 8 Intel-based devices predominantly used in Tile Mode
• Windows RT devices
23.6.1. Client Software
Windows 8 Intel-based devices predominantly used in desktop mode are best treated in the same way as Windows laptops. If the user requires the client software (e.g. for shared account selection), install the PaperCut User Client software locally.
If the device is Windows RT based, or is predominantly used in Tile Mode, bookmark or pin the Mobile Client to the
Start Screen. The Mobile Client is located at the URL: http://[server-name]:9191/client
The Mobile Client provides most of the functionality of the desktop client software, but does not require local installation, as it runs in a web browser. If your users need to interact with the client (e.g. for shared account selection), you'll need to instruct them to open the client after printing their job.
23.6.2. How do I print via a server with Windows RT?
You will need:
• A print server running Windows Server 2012 or Windows 8
• A printer that is supported by one of the Windows Server 2012 or Windows 8 built-in "class drivers".
Windows RT comes with many in-built or in-OS drivers. These are called class or mode 4 drivers. Printers that require specialized drivers may not work.
Tip
If your primary print server runs an older version of Windows and you are not able to upgrade it, consider setting up a new secondary print server to support Windows RT. PaperCut is able to track printing on multiple servers and multiple operating systems.
When selecting a print driver to use for the printer, you will need to find a compatible "Class" driver as shown below.
414
Mobile & BYOD Printing
Figure 23.43. Select a Class Driver
This manual does not address how to best deploy these printers to your Windows RT users. A manual approach is however adopted by many organizations.
If you'd like to read the latest information on Windows RT, or would like to share your preferred deployment method, please check out PaperCut's Knowledge Base article on the topic
[http://www.papercut.com/kb/Main/KnownIssuesGCP].
23.6.2.1. I'd like to continue to use my standard driver on other systems. Is this possible?
At the time of writing, the suitability of mode 4 drivers with regards to Windows XP, Vista and Windows 7 is unknown. In this situation you could consider setting up duplicate printer queues on the Windows Server 2012 machine, perhaps with "RT" on the end of them, giving you something like this:
\\printserver\library
\\printserver\libraryrt
You can then select the different "class" driver on the RT specific queue. To help with reporting, consider using
PaperCut's inbuilt "Printer Groups" or physical printer reports to consolidate usage information from both queues.
23.6.3. Other Options for Windows RT and Windows 8 tablet devices
Windows 8 tablet environments. Although the print experience is not native, the simpler setup and management may be attractive to many organizations.
23.7. Mobile Print Release - Releasing print jobs on your mobile
Document security is an important requirement in the modern print environment. In a standard environment a user's job prints immediately and may accidentally be collected by another user. This problem is usually addressed with
PaperCut NG's Mobile Print Release provides an alternate cost effective solution that leverages the powerful devices that exist in almost everyone's pocket - the mobile phone.
Features:
415
Mobile & BYOD Printing
• Release held jobs from any print queue with Hold/Release enabled
• Simple intuitive interface, optimized for touch screens
• Designed to work with most modern cell and tablet devices
• Quickly locate printers with keyword searching (location, name or code)
• Can be used in environments with Find Me Printing configured, giving the user ultimate control over where and when their jobs are released
• Support for QR code printer location/lookup
Requirements:
• iPhone iOS 5 and newer (both iPhone and iPad)
• Android ICS and newer (Chrome recommended)
• Other modern mobile web browsers
23.7.1. Usage and features
Once logged in, the user is able to see a list of printers that are available to them. The printer's name, location, and alternate ID (if set) are displayed. Mobile Print Release also displays recently used printers, as well as popular printers.
Figure 23.44. The Mobile Print Release printer list
Selecting a printer will show the held jobs that the user can release on the printer. The list includes jobs held in virtual queues that redirect to the selected printer. In the screenshot below there are no jobs available for release.
416
Mobile & BYOD Printing
Figure 23.45. An empty job list
In the screenshot below we can see there are many jobs available to release. Simple details such as the job name, cost, number of pages, and time that it was queued are displayed.
Figure 23.46. Jobs display in a held jobs list
Clicking the arrow next to a job will display more detailed information about the job. In the case where there are multiple jobs with similar names, users can utilize this information to differentiate jobs.
417
Mobile & BYOD Printing
Figure 23.47. Showing the details of a job in the held job list
If the user only wants the perform an action on a subset of jobs, they can use the checkboxes to the left of the job titles to either select or deselect them. By default, all jobs in the list are selected. Users can release or cancel the selected jobs by clicking on either the green or red buttons at the bottom of the screen.
Figure 23.48. Selecting the disired jobs in the held job list
Other highlights for Mobile Print Release include:
• Avoid logging in every time with the "Remember Me" option
• Search for printers using name, location or alternate ID
418
Mobile & BYOD Printing
• Jump straight to your favorite printer simply by bookmarking the page (or adding to home screen)
23.7.2. Mobile Print Release Deployment/Install
One of the benefits of Mobile Printer Release is that it allows you to offer secure release on any type of printer.
There is no need for any dedicated hardware. A common configuration is to have two queues for a physical printer; one direct queue (normal printing) and one secure queue (a hold/release queue). When document security is important users can select the secure queue and release the job from their mobile phone. Alternatively, many sites opt for a 100% secure environment, mandating release on every job. Mobile Print Release leverages the existing
Mobile Print Release is a core feature included in PaperCut NG. It's a mobile web application, which means there's no need for users to install 3rd party applications or access an off-site App store (such as Apple's iTunes store). The advantage of this model is that all network traffic and application deployment is managed securely in your own network.
The application can be accessed by opening the phone's Internet browser (while connected to your network's local
WiFi) and going to any of the follow URLs:
HTTPS
• https://[servername]:9192/mr
• https://[servername]:9192/mobile/release
HTTP
• http://[servername]:9191/mr
• http://[servername]:9191/mobile/release
"/mr" is a shortened version provided for convenience. HTTPS is highly recommended, as users will authenticate themselves via this connection. By default PaperCut NG installs with self-signed certificate and will raise warnings in
as secondary option, and only on secured WiFi.
Users can bookmark or "Add to Home Screen" the Mobile Print Release App on their device to quickly access the application. Held job pages can also be bookmarked, which is convenient for users who often release from the same device.
Tip
Mobile Print Release can also be deployed to iOS devices as an App. Simply have the user access https://[servername]:9192/mr/install
. This will install a web profile that automatically creates the home screen icon, which may be preferred to manual bookmarking on some sites.
can be used together to provide a comprehensive mobile printing solution.
23.7.3. Management tips for large networks
Here are some tips to help educate your users to get the most out of Mobile Print Release:
23.7.3.1. User education
When implementing Mobile Print Release across a large network, it can be hard to educate the users of how and when to use the application. Many administrators have used stickers with URLs printed on them to direct users to access the application. Informational posters give administrators a more noticeable and detailed space to explain the enhanced printing architecture.
419
Mobile & BYOD Printing
23.7.3.2. Power features
Regular users of Mobile Print Release can improve their experience by bookmarking the printers that they use the most. When used in conjunction with the "Remember Me" option, users can release their jobs extremely quickly.
This allows users to click on a single icon on their mobile device and go straight to the held job list that their print job can be released from.
23.7.3.3. Quick printer location
Sites with hundreds of printers will want to educate their users to utilize the search function in Mobile Print Release.
The Mobile Print Release printer search field provides a quick way for users to find their desired printer. The search terms are matched against the printer's name, location and alternate ID. The alternate ID is a short admin-defined code that can be assigned to a print queue. Printer names are usually designed to be read on a desktop, assigning an alternate ID gives users identifiers which are easy to remember and type on a mobile device. A suggested approach is to use a 4 digit code (eg 1234) as the alternate ID. Printers can be labelled with stickers with the alternate ID to indicate what term users should search for.
You can use the location or alternate ID to access the printer's Mobile Print Release page directly:
• https://[servername]:9192/mr/[location]
• https://[servername]:9192/mr/[alternate_id]
23.7.3.4. Using QR Codes
While your users can use printer search to locate a device, QR codes provide a mechanism to launch Mobile Print
Release directly with the printer automatically selected. The process would work as follows:
1.
The user scans the QR code using their mobile
2.
The mobile's browser opens listing their print jobs (They may need to authenticate if they have not before)
3.
The user selected their jobs, and clicks "Release". The jobs will print immediately.
Below is an example of a sticker that could be adhered to a printer. The QR code results in the URL https://printerserver:9192/mr/1234
. Note that this URL uses the alternate printer ID of 1234 (See above).
420
Mobile & BYOD Printing
23.7.4. Advanced Options
The following configuration keys can be used to configure Mobile Print Release. Configuration keys can be edited at
Options
→
Actions
→
Config editor (advanced).
Config name
mobile-release.max-recent-printers mobile-release.max-popular-printers mobile-release.session-timeout-mins
Description
The maximum number of recently used printers displayed in Mobile Print
Release interface. These printers are the ones that have been recently used to release jobs via Mobile Print Release. It helps users in selecting their preferred printer quickly. The default value is
4
.
The maximum number of popular printers displayed in Mobile Print Release interface. These printers are organization's popular printers. The default value is
3
.
Inactivity timeout for Mobile Print Release interface. The value of 0 indicates that the session will never time out. The special value DEFAULT indicates that the PaperCut's default value will be used. The default value is
1440 minutes
(24 hours)
.
Table 23.11. Advanced Mobile Print Release Config Keys
Please see Section 15.10, “Using the Config Editor” to find out how to change config keys.
23.7.4.1. Mobile Release Customization
“Customizing Mobile Print Release” for details.
23.8. Mobile Client
421
Mobile & BYOD Printing
functionality such as
• showing the user their balance / quota,
• delivering notification messages,
• confirming the cost of jobs and
• allocating jobs to shared accounts.
For user-owned and mobile devices it may not be possible or practical to deploy (or have the user install) the desktop client. Instead, the Mobile Client offers most of the same functionality and can run in a web browser on nearly any device.
In most cases use of the Mobile Client is optional and serves only to provide information to users about their print jobs. Its use is required when
• user interaction is required, such as pop-ups for confirmation, account selection or from a print script,
• printing from an iOS device, where the Mobile Client is required to authenticate the user.
The Mobile Client can be accessed from a web browser at http://[servername]:9191/client
. Rather than have users type the URL into their browser, we recommend providing a prominent link, for example on an intranet page, or deploying a link to devices where possible. Specific instructions for deploying to iOS devices are available
in Section 23.3.3, “The PaperCut iPad / iPhone App (Mobile Client)”.
In cases where user interaction is required, users may require some prompting to remind them to use the Mobile
for some time (90 seconds after submitting the job by default). This functionality can be configured at Options
→
Mobile & BYOD
→
Common Mobile Printing Options
→
Send a reminder email when a job requires user
action (e.g. account selection).
23.9. Self association for emails and email verification/validation
23.9.1. Unknown emails and email self-association
When mobile printing technologies identify job owners by email address, PaperCut needs a way to identify and
email address. With Email to Print, the job's owner is identified by the sending email address.
PaperCut provides three main ways to populate email addresses. Select the method that best suits your organization.
1.
Email addresses are automatically imported from the user directory. If you have configured organization /
"official" addresses in your user directiory then these will be imported to PaperCut and further configuration may not be required.
2.
Manual configuration. An administrator may add and remove email addresses on behalf of a user in the Users tab of the PaperCut Admin interface. We recommend using the Other emails section for this purpose if you are adding "official" organization addresses in case you later decide to add them to your user directory.
3.
Email self-association, allowing users to add an email address to their user account by themselves.
In the case that a job arrives from an email address that is not known to the system, you may choose to have
PaperCut cancel the job, or hold the job and offer the user to verify (self-associate) their address. Canceling the job is the appropriate response if you are choosing to manually configure the email addresses.
This option is available at Options
→
Mobile & BYOD
→
Common Mobile Printing Options
→
When a job
arrives from an unknown email address. Email self-association is enabled by setting this option to Hold the job
and email the user with instructions for verifying the address.
Email self-association works as follows:
422
Mobile & BYOD Printing
1.
When a job arrives from an unknown user, the job is held and an email response is sent to the user that includes a link.
2.
Clicking the link prompts the user to log in.
3.
The user logs into their PaperCut account and the email address is added to their account. When viewing the user in the admin interface, it will appear under Other emails.
4.
The job is assigned to the verified user and proceeds to print.
5.
Future jobs are automatically assigned to the verified user.
423
Chapter 24. Print Archiving (viewing and content capture)
24.1. Introduction
Print data is typically short-lived, the user prints the job and then the print job content is lost. PaperCut NG's Print
Archiving feature changes that. With Print Archiving, in addition to PaperCut's standard print job information logging, it is now possible to:
• Save and archive print jobs for a defined period of time
• Interactively view what has been printed
Print Archiving is a very visual feature and is best explained with a few screen shots.
Figure 24.1. Grid view is a great way to locate jobs visually
424
Print Archiving (viewing and content capture)
Figure 24.2. Inspecting a print log in the full screen viewer. The viewer toolbar supports navigation, zoom, image rotation and PDL file download.
Print Archiving, including the ability to view previous print jobs, gives administrators a new set of tools to improve print management. Common uses include:
Information Security, data retention and audit policies
Many corporations now have defined data management objectives and specific policies around the tracking of data in emails, using thumb drives, cloud storage services, etc. This allows organizations to:
• Comply with externally mandated and legal requirements such as Sarbanes-Oxley and best practice audit procedures.
• Support an organization's needs to protect its customers' and own intellectual property.
• Monitor inappropriate material and potential illegal activity.
• Ensure business resources are being used appropriately and not being wasted.
Print Archiving now allows organizations to extend these security policies to the printer fleet and closes a potentially big loophole in governance processes.
Fleet Optimization
Inspecting a sample of print jobs held by Print Archiving can help with key resource decision making questions. Is the inkjet photo printer being used for photos? Or should it be replaced with a more appropriate device for color text document output like a laser printer?
Validating user refund requests
In education environments, it is common for refund requests to be submitted via PaperCut. The ability for administration staff to review the job via Print Archiving can greatly assist in this scenario. See Section 7.17.2,
425
Print Archiving (viewing and content capture)
“Managing Refunds” for more on this feature.
Caution
In the same way that email and server administrators have privileged access to a user's email and documents, a PaperCut administrator can access the user's print job content. A System
Administrator's privilege to view archived print jobs should be treated with the same professional caution as similar access privileges to a user's private data. PaperCut has granular control on
administrative rights so that this can be managed, as described in Section 15.4.2, “Assigning
Administrator Access to a User”.
Feature Highlights:
• Store an historic record of all printed content, limited only by available storage space.
• View past print jobs interactively in the browser.
• Control which administrators have access to view or remove archived content.
• Download the original spool file for 100% fidelity when reprinting.
• Remove archived data from the system and disk.
• Move older archives to external storage, such as offline backup or offsite cloud repository, for long term data retention.
• Enable or disable archiving on selected printers and users.
When Print Archiving is enabled new options are available for viewing print logs (e.g. the global job log at Printers
→
Job Log, or the per-printer or per-user job logs).
•
Details view:
This is the traditional text-only job log view and is best for finding and browsing by non-visual job log information.
•
Hybrid view (thumbnails + details):
426
Print Archiving (viewing and content capture)
The hybrid view is the most flexible view option. It adds a thumbnail column to the details view. This allows for easy filtering and sorting of the print logs table while also being able to view print logs visually.
•
Thumbnails / grid view:
This view favors images over text and is the best view for visually scanning to identify documents of interest.
427
Print Archiving (viewing and content capture)
24.2. Technical Overview: How does archiving work?
The Print Archiving system can be explained by looking at three processes:
Process 1: The job archiving process
1.
A user prints a job from a network device (desktop workstation, mobile, etc.).
2.
The job is sent to the print server.
3.
On the server, the job is intercepted and the job's spool file is copied into the archive. This is usually a file containing the print data in a Page Description Language (PDL) such as PostScript, PCL, EMF or XPS. The copy process is carried out while spooling takes place, with minimal impact on printing performance.
4.
If the spool file is in a PDL format known to the system, images of the printed pages are created.
Process 2: Archive access and preview process
1.
The administrator logs into the PaperCut admin interface.
2.
In the print log, the archived jobs appear as thumbnails or icons.
3.
If the job is in a supported PDL format, clicking on the thumbnail brings up a viewer. From there you can page through and view the document.
4.
As the administrator pages through a document, further images are generated as required.
Process 3: The overnight management process
At the set system maintenance time overnight, the archive is inspected for any content older that the Keep jobs for
up to: X days option set by the administrator. Any content that matches is permanently removed from the archive.
24.3. Setting Up Print Archiving
428
Print Archiving (viewing and content capture)
Print Archiving is an optional feature disabled by default. Before enabling the system administrator should consider:
• Disk space implications.
• Privacy and data access.
• CPU load - particularly on low resourced Virtual Machines.
• The additional load on backup storage.
24.3.1. Step 1: Install print spool file viewer technology
To get the full benefit of Print Archiving we recommended installing additional software that assists with the conversion of selected printer language files, such as PostScript, into images. This software should be installed on the primary PaperCut server. PaperCut will detect the software and automatically start using it.
The recommended software:
24.3.1.1. Windows servers
Install Ghost Trap - a security-hardened PostScript and PDF-to-image converter.
Download:
[http://www.papercut.com/products/free_software/ghost-trap/download/].
Ghost Trap is a security hardened version of Ghostscript. It's open source software supported by PaperCut
Software. It brings best-of-breed security to the popular PostScript and PDF conversion software by utilizing the same sandbox security technology used by the Google Chrome Browser. You can read more about this project here: The Ghost Trap Project Page [https://github.com/PaperCutSoftware/GhostTrap].
Note
Ghost Trap
[http://www.papercut.com/products/free_software/ghost-trap/download/] is strongly recommended.
An alternate option is to install the following components:
Ghostscript
[http://www.ghostscript.com/download/gsdnld.html],
[http://www.ghostscript.com/download/gpcldnld.html],
[http://www.ghostscript.com/download/gxpsdnld.html] (v9.07).
and
GhostPCL
GhostXPS
24.3.1.2. Mac servers
Install the PostScript viewing software Ghostscript version 9.06. Richard Koch from the University of Oregon maintains a Mac version of Ghostscript. This can be downloaded here. [http://pages.uoregon.edu/koch/]
Note
If you're using the Homebrew [http://mxcl.github.com/homebrew/] package manager, there is a ghostscript package available for install.
24.3.1.3. Linux and Novell OES servers
All major Linux distributions either come with Ghostscript automatically installed, or an option to install via the standard package manager. See your distribution's documentation for further details. You should ensure that the gs command is on the
PATH
(for the papercut user).
429
Print Archiving (viewing and content capture)
Ghostscript version 9.07
is recommended.
[http://www.ghostscript.com/download/gpcldnld.html]
[http://www.ghostscript.com/download/gxpsdnld.html].
We
24.3.2. Step 2: Enable Print Archiving
Print Archiving can be enabled by an administrator as follows:
1.
Log in as admin
.
2.
Navigate to the Options tab.
3.
Enable the Print Archiving option.
4.
Click Apply at the bottom of the page.
also recommend and installing,
GhostPLC
GhostXPS
Once enabled you should perform some testing across your printer fleet.
24.3.3. Step 3: Review Configuration Options
System Administrators should first familiarize themselves with the archive disk management options. These are found under Options
→
General
→
Print Archiving
Figure 24.3. Print Archiving options on the Options tab
The important options are:
Keep jobs for up to: X days
This option determines the number of days a job will be kept in the archive. The default value is 30 days, with a minimum value of 1. If you are planning on setting a high value make sure you consider consumption of drive storage. It is advisable to monitor disk space growth during the first full week of usage and use this as a basis to extrapolate your storage requirements.
For reference
[app-path]/server/data/archive on the primary PaperCut server.
the default archive path is
Note
Any change to the Keep up to: X days option will be applied when archive maintenance is performed overnight.
Stop if free space falls below:
This is an emergency stop option. If free disk space falls below the set value all archiving is immediately suspended.
This ensures a growing archive will not take down a production server. The default value is 2GB. If the server runs other production software it may be advisable to increase this value. If email notifications are configured (see
430
Print Archiving (viewing and content capture) when disk space drops to this limit.
Tip
It is recommended that you proactively monitor disk space usage as a matter of course during your regular service maintenance and assessment procedures.
Turning off archiving on selected printers, users or groups:
Once enabled, Print Archiving will occur on all queues for all users. In some situations it may be necessary to selectively disable archiving. Examples include:
• Tuning off archiving on selected users, such as human resources managers who routinely print sensitive information.
• Turning off archiving on printers that don't support interactive viewing - for example a printer that only supports
GDI drivers. Without imaging support, archiving may be of reduced benefit as the only option to review the document is to reprint it.
To disable archiving on a specific printer:
1.
As an administrator, log in and select the Printers tab.
2.
Select the printer you wish to disable.
3.
Deselect Enable Print Archiving.
4.
Click OK.
To disable archiving for a specific user:
1.
As an administrator, log in and select the Userstab.
2.
Select the user you wish to disable archiving for.
3.
Enable Override printer-level settings.
4.
Enable Don't archive this user's jobs.
5.
Click OK.
To disable archiving on a group of users:
1.
As an administrator, log in and select the Groups tab.
2.
Select Bulk user actions... from the Actions menu.
3.
Select the group to perform the change on
4.
Enable Change advanced user settings.
5.
Enable Override printer-level settings.
6.
Enable Don't archive this user's jobs.
7.
Click OK.
24.4. Advanced Archiving Options and Features
24.4.1. Changing the archive storage directory
The default archive storage location is
[app-path]/server/data/archive
. Reasons for changing this location may include:
• Allowing site servers and secondary print servers to archive to a common location.
431
Print Archiving (viewing and content capture)
• Storage restrictions on the drive where PaperCut is installed.
• You want to exclude the archive from your backups.
Note
For performance and security reasons using a local disk on the primary server as the storage location is recommended. If a remote network location such as a SAN device is intended to be used, we'd recommend a low-level drive mount such as iSCSI or better if possible. The server must have a reliable connection to the storage.
On a Windows server, if the desired location is accessible only via a UNC path, some additional security configuration will be required. By default the
PaperCut Application Server and the
PaperCut Print Provider services run under the SYSTEM account. This account is restricted and does not have remote network drive access. You'll need to change the
Log On account assigned
both services to one which has full read/write access to the remote location. The change should only be considered and performed by an experienced Windows server administrator.
24.4.1.1. Phase 1: Moving the central archive:
Important
If you have existing archived spool files you wish to move to the new location, it is recommended to perform this process at a period of low printing activity.
To change the location:
1.
Create the new directory in the desired location, e.g.
D:\print-archive
. (If the PaperCut Application Server
2.
Ensure the
PaperCut Application Server service will have read and write access.
3.
Log into the PaperCut admin interface.
4.
Navigate to Options
→
Actions
→
Config Editor (Advanced).
5.
Search for the key archiving.path
.
6.
Enter the new path (e.g.
D:\print-archive
).
7.
Click the Update button to the right of the value.
8.
Navigate to the Options page and verify the Archive status.
9.
A
README.txt
file should now appear in the top level of the location.
10. Consider copying any existing archived content from the previous archive location. If existing content is not copied, job previews will no longer appear for historical print jobs.
24.4.1.2. Phase 2: Changing Print Provider Configuration:
The print provider component needs to know the new location. To set this location:
1.
Open Notepad (or your preferred text editor) with Administrator rights.
2.
Open the file located at
[app-path]/providers/print/win/print-provider.conf
.
3.
Locate the line:
ArchiveDir= and change the value to point to the new location set up in Phase 1. For example:
432
Print Archiving (viewing and content capture)
ArchiveDir=D:\print-archive
Note: if you have upgraded from an older version you may need to add the
ArchiveDir= option to the print-provider.conf
.
4.
Save the file.
5.
Restart the print provider service.
6.
Note: If you have multiple print servers, repeat this on any other secondary print server or site server, as
outlined in Section 24.4.3, “Setting up Secondary Print Servers or Site Servers”.
24.4.2. Backup Considerations
The print archive can potentially grow to a large size and this can have implications for your backup planning. You have various options around archive backup:
• You can opt to to fully backup the directory using your backup solution of choice, provided you have sufficient capacity.
• You can opt to not backup the directory at all. PaperCut will be resilient to a restoration with an empty archive directory.
• You can opt to back up part of the directory. For example the current month only. PaperCut will be resilient to a restoration with a partially constructed archive directory. There is a
README.txt
in the archive directory that explains more about partial backups and the directory structure layout.
24.4.3. Setting up Secondary Print Servers or Site Servers
24.4.3.1. Introduction
The setup described previously was for the common case where the PaperCut application is installed on a single
printed via a server other than the primary server. If Print Archiving is enabled, the secondary server must also participate and facilitate archiving.
In larger print environments it is common to have multiple PaperCut secondary servers located on various machines across the network. In this case Print Archiving can still be used, however this is an advanced setup procedure and will require additional planning and implementation time.
To support the central tracking and viewing of print archives, all spool files need to be transferred across to the primary application server's central archive directory. Each secondary server needs to be correctly configured with write access to this central archive directory. This will require running the
PaperCut Print Provider service under an account with write access to this directory.
One consequence of this approach, designed to simplify the management of archives, is that it increases bandwidth requirements because all print archives are transferred across the network to the application server. The impact of this will depend on your specific environment, e.g. number of print jobs, network setup, PDL used, etc. As such you may need to monitor and experiment before a large scale deployment of this feature.
24.4.3.2. The Setup process
The process to set up a secondary server under Print Archiving involves four key phases. Before undertaking this process you should ensure that the secondary print server or site server is operating correctly for standard print tracking. The following section documents configuring secondary servers on the Windows operating system.
24.4.3.2.1. Phase 1: Creating domain service account
By default the
PaperCut Print Provider service running on the secondary server(s) operates under a limited rights account called SYSTEM. This account does not have access to network resources and hence can't access the file system on the primary PaperCut server. You'll need to create a new service account and set the service to
Log On as this account:
433
Print Archiving (viewing and content capture)
1.
Create a new domain account with access to the share on the primary server and full management rights of print spooler on the local machine. An appropriate name may be svc-papercut
.
2.
Set the new account's password to never expire.
24.4.3.2.2. Phase 2: Sharing the central archive directory
The secondary server needs the ability to copy print jobs into the central archive. You must first share the central archive folder. On Windows, assuming the archive directory is the default, the procedure would be:
1.
Open Explorer and navigate to
[app-path]/server/data/
.
2.
Right-click on the archive directory and select Properties...
→
Sharing.
3.
Share the directory with a name print-archive
.
4.
Ensure the service account created in Phase 1 has full read/write access.
5.
Ensure all other non-Administrator users do not have any access.
6.
Click OK.
24.4.3.2.3. Phase 3: Change the configured archive path on the secondary server
The secondary server needs to know the location of the recently shared central archive directory. To set this location:
1.
Log on to the secondary print server or site server as an administrator.
2.
Open Notepad (or your preferred text editor) with Administrator rights.
3.
Open the file located at
[app-path]/providers/print/win/print-provider.conf
.
4.
Locate the line:
ArchiveDir= and change the value to point to the UNC share name set up in Phase 2.For example:
ArchiveDir=\\my-primary-server\print-archive
Note: If you have upgraded from a previous version you will need to add the
ArchiveDir= option to the print-provider.conf
.
5.
Save the file.
24.4.3.2.4. Phase 4: Assigning rights to the service account
The
PaperCut Print Provider service (service responsible for monitoring the print queues and transferring print job spool files to the central archive) needs to be able to access the directory shared in Phase 3. Assign the service account set up in Phase 1 to the
PaperCut Print Provider service as follows:
1.
Open Control Panel
→
Administrative Tools
→
Services
2.
Double-click on the
PaperCut Print Provider service.
3.
Select the Log On tab.
4.
Click This account.
5.
Enter the username and password for the service account set up in Phase 1.
6.
Click OK.
7.
Restart the service and manually check the file
[app-path]/providers/print/print-provider.log
for any error messages at end.
24.4.3.2.5. Phase 5: Test
434
Print Archiving (viewing and content capture)
Take some time now to perform some testing and ensure any jobs printed on a print queue on this secondary server are correctly archived.
Important
Archived files are partitioned based on the date and time of the print job. In order for the print archives to appear in a consistent manner it is important that all secondary print servers and site servers share a common time synchronization. An inconsistent time between servers of more than one hour may cause an error.
24.4.3.2.6. Troubleshooting Secondary Server Setup
Here is a list of common issues leading to problems with Print Archiving and secondary server setups:
• Incorrect paths: It's important that all secondary servers are configured to point to the shared central archive directory. Double-check the value entered in
ArchiveDir
. See Section 24.4.1.2, “Phase 2: Changing Print
• System Services can't access user mapped drives. On Windows it's important that you use a UNC path rather than a mapped drive letter.
• You'll need to ensure that all secondary servers have full write access to the central archive. Take time to double-check permissions.
24.4.4. Advanced Configuration Keys
The following configuration keys are accessed via Options
→
Actions
→
Config editor (advanced) and influence the behavior of Print Archiving
Key
archiving.images.creator.non-interactive.max-concurrent archiving.images.creator.interactive.max-concurrent archiving.images.creator.pages-to-initially-image
Description
This value determines the maximum number of image creator processes used to process new print jobs in the background. The system may use this maximum number when it is under high load. The default value is
1
. Sites running on fast multiprocessor servers may choose to increase this number. As a guide, this value should not exceed the number of available processor cores.
NOTE: The Application Server must be restarted after changing this setting.
This value determines the maximum number of image creator processes that may be used to support interactive viewing of print jobs in the admin interface.
The default value is
2
. Sites running on fast multiprocessor servers may choose to increase this number.
NOTE: The Application Server must be restarted after changing this setting.
This value determines the number of pages that will be imaged (pre-rendered) when a print job first arrives. Pre-generation of images speeds up viewing. The default value is
4
.
The maximum pages into a document that can be explored.
archiving.images.viewer.max-pages
Table 24.1. Print Archiving Advanced Config Keys
24.4.5. Downloading PDL / spool files for reprinting
Along with image previews, Print Archiving stores a copy of the print job's PDL / spool file. This can be later downloaded and reprinted. Common reasons for reprinting a job include:
• To produce another hard copy of the print job (e.g. if the original was lost).
• To view, when image previews are not available (such as when the printer is using a proprietary / GDI print language).
435
Print Archiving (viewing and content capture)
• To help diagnose or reproduce printing problems.
To download a job's PDL / spool file,
1.
Find the job of interest in the job log
2.
Click on the job's thumbnail to open the job viewer (full page view)
3.
Click the download icon in the toolbar at the top left (see below)
4.
Save the PDL file to your computer
Figure 24.4. The print job viewer showing the download PDL option in the toolbar
24.4.6. Remove archived data
Archived data may be removed permanently by clicking the remove icon or pressing 'delete' in the archive viewer.
Removal is available when the user has the administrator right "remove archived jobs" assigned.
436
Print Archiving (viewing and content capture)
To remove archived data,
1.
Find the job of interest in the job log
2.
Click on the job's thumbnail to open the job viewer (full page view)
3.
Click the delete icon in the toolbar at the top left (see below) or press 'delete' key
4.
Confirm deletion
Figure 24.5. The print job viewer showing the remove option in the toolbar
24.5. Troubleshooting and Known Limitations
24.5.1. No preview image available
In some cases print jobs may not have a preview image available. This can be for two possible reasons:
1.
Archiving was disabled
Archiving may be disabled / overridden in the following ways:
• Printer-level override (disable archiving for a printer)
• User-level override (disable archiving for a user)
• Print scripting (archiving disabled per-job from within a script)
2.
A preview could not be produced for the archived job
There are several reasons why image previews could not be produced:
• The print driver is using a proprietary or GDI / unsupported print language (see Section 24.5.2, “GDI Printers
437
Print Archiving (viewing and content capture)
(GDI Print Description Language)”).
•
•
• The archived PDL / spool file may be corrupt or partially copied.
• The conversion software (e.g. Ghostscript) may not be capable of producing a preview (e.g. for a complicated document).
“Downloading PDL / spool files for reprinting”).
24.5.2. GDI Printers (GDI Print Description Language)
GDI printers produce spool files which are proprietary binary format files and currently there is no standard technology or tools to allow the visual display of printed content, however it is possible to reprint GDI print jobs by
hopes to approach printer vendors in the future to address this limitation.
24.5.3. There may be issues viewing some print jobs
Because of its flexibility some PostScript drivers can create spool files that cannot be rendered with the standard viewer. If you find a consistent issue with a particular printer, please first see if there is an alternate driver format available (i.e.. another PDL language). If the issue persists after trying other drivers, please contact PaperCut support. We may be able to address the issue in a future release.
24.5.4. Preview images may differ slightly from the printed document
Depending on the print driver used, certain attributes of preview images generated may differ slightly from those of the actual document (e.g. in some cases a color print-job may have a black-and-white preview image). This is also
the case when using conversion filters.
24.5.5. No watermarking in preview images
Document watermarks applied by PaperCut's watermarking feature will not display in preview images.
24.5.6. Latest Information
New printers and print drivers are being released every week. For the most up to date information as well as a detailed explanation of known issues, please see this article in the PaperCut Software knowledge base: Known
Issues with Print Archiving [http://www.papercut.com/kb/Main/KnownIssuesWithPrintArchiving]
438
Chapter 25. Web Cashier
The Web Cashier is a simple web interface that provides a till/cashier to facilitate simple transactions using
PaperCut NG accounts. It's specially designed for non-technical staff in educational organizations. For example the cashier user may:
• Charge end-user accounts, or shared accounts, for ad-hoc services such as laminating, binding or library fines.
• Deposit funds to a user's personal printing account, usually after receiving a cash or electronic payment.
Although it is possible for an administrator to perform account adjustments at any time, the Web Cashier interface is a simpler interface designed specifically for non-technical users such as office administration staff, library staff and service counter staff.
Web Cashier can be used in a variety of ways. Some examples:
• The library teacher can use Web Cashier to charge students for various services such as document binding, laminating, or library fees without handling cash. Services are charged to the user's balance and they receive an itemised transaction acknowledgment slip, which can be printed or automatically emailed if needed.
• Office staff can accept payments from users and then credit the user's balance using the simple Web Cashier
Deposit screen (e.g. add extra quota or top-up an account over the counter). Web Cashier screens are simple and only present information tailored specifically to the cashier user's role. (Purchase, Deposit or Both). This approach is ideal for smaller organizations who do not have the transaction volumn to justify Pre-Paid TopUp
cards or an online payment gateway (see Chapter 16, TopUp/Pre-Paid Cards).
• When people leave an organisation they can be provided with the balance of their account and the transaction can be recorded as a "refund" item, created by the PaperCut NG administrator. The items are configurable and depend on the services the organization may want to provide.
25.1. Setting Up Web Cashier
Web Cashier is not enabled by default and must first be set up by the PaperCut NG administrator. To set up Web
Cashier:
1.
Enable it by clicking the button Enable and set up Web Cashier under Options
→
General
→
Web Cashier.
2.
To set up Web Cashier to sell ad-hoc services or products (items) the administrator should first define them. To add an item: a.
Press the Add New Item button.
b.
Give the item a name or short description.
c.
Enter a default cost.
d.
Press Add Item.
e.
To delete an item click on the delete link. It is also possible to change the default cost of the item later.
439
Web Cashier
Figure 25.1. Web Cashier items
3.
Optionally customize the text displayed on the Purchase and Depositscreens or header of acknowledgment
slips. Examples are provided. For more configuration details see Section 25.5, “Advanced Web Cashier
4.
Access Web Cashier using the URL http://[server-name]:9191/webcashier.
This will be the URL you provide to your Web Cashier users later (e.g. Office/Admin/Service-desk staff).
5.
Perform some test transactions and ensure Web Cashier is set up to your requirements.
6.
Grant Web Cashier user privileges to the users that will require access (i.e. teacher, office staff, librarian, etc.).
To read more about assigning Web Cashier access to users or groups see Section 25.6, “Assigning Web
25.2. Purchasing Items
To charge Tom's personal account for "Binding" and "Postage" the Web Cashier user will:
1.
Log into the PaperCut Web Cashier using the URL http://[server-name]:9191/webcashier
.
2.
Enter your network credentials.
3.
Search for the user by entering their username or full name. It will display user's full name and current balance on the left.
440
Web Cashier
Figure 25.2. Web Cashier Purchase example
4.
Select the "Personal account".
5.
Now select "Binding" from the item list.
6.
The default item price will be visible when you select the item. It can be modified if needed. (e.g. give discount for teaching staff)
7.
Enter the quantity. PaperCut will calculate the total item price.
8.
Now add a second item - "Postage"
9.
Give a discount by changing the cost (per item).
10. Enter an optional comment.
For example this may be used for recording the reason for an exception/discount/charge.
11. Press Purchase button. Tom's balance will be debited with the transaction value and an entry is made in the account's transaction history.
12. An Acknowledgement slip is displayed on the screen and may be printed using the Print button.
Cashier Configuration” for more information.
441
Web Cashier
Figure 25.3. Web Cashier Purchase Acknowledgement Slip
14. If previoulsy configured by the PaperCut NG adminstrator, Tom is automatically emailed a copy of the
25.3. Depositing Funds
Deposit $10.00 to a user's personal account.
1.
Log into PaperCut Web Cashier using the URL http://[server-name]:9191/webcashier
.
2.
Enter your network credentials.
3.
Navigate to Deposit tab.
4.
Search for the user by entering their username or full name. It will display user's full name and current balance on the left.
442
Web Cashier
Figure 25.4. Web Cashier Deposit example
5.
Collect $10.00 cash from the user and enter $10.00.
6.
Select one of the predefined payment methods. (i.e. Cash in this example)
7.
Enter an optional comment.
8.
Press Deposit button. User's personal balance will be credited with $10.00.
9.
An Acknowledgement slip is displayed on the screen and may be printed using the Print button.
Cashier Configuration” for more information.
Figure 25.5. Web Cashier Deposit Acknowledgement Slip
443
Web Cashier
11. User Tom is automatically emailed a copy of the acknowledgement slip if configured, or it may be printed.
$10.00 will be immediately added to Tom's account and available for use.
25.4. Web Cashier Order History
A history of Web Cashier orders can be displyed via Order History tab. This useful screen allows the Web Cashier to:
• Validate the existence of a transaction/order by searching (e.g. on a reference number).
• Bring up an order/transaction history for a given user or for a given account.
• Quickly review recent transaction.
• Access basic reports or export data.
Previous acknowledgement slips may be viewed by clicking the reference number. A filter can also be set up. e.g. to view the transactions for a specific user. The list of orders can be exported using the Export / Print link.
All Web Cashier reports can be accessed via the PaperCut admin interface by navigating to Reports
→
Transaction. (See Section 25.7, “Web Cashier Reports” for more information.)
25.5. Advanced Web Cashier Configuration
Setting
Purchase page instructions
Purchase acknowledgement slip header
Deposit page instructions
Deposit acknowledgement slip header
Payment methods
Copy acknowledgement slip to user via email
Description
This text is displayed on the Web Cashier Purchase tab. It might include information on how to charge users. It supports basic HTML markup.
This text is displayed on top of the Web Cashier Purchase acknowledgement slips. It supports basic HTML markup.
This text is displayed on the Web Cashier Deposit tab. It might include information on how to charge users. It supports basic HTML markup.
This text is displayed on top of the Web Cashier Deposit acknowledgement slips. It supports basic HTML markup.
This is a comma separated list of user defined payment methods used for crediting users' accounts. (i.e. Cash) It can be left blank.
Select this option to send acknowledgement slips to users via email. To set up a
SMTP server see Section 15.6.1.4, “Configuring Email Notifications”.
Table 25.1. Web Cashier Settings
Tip
Most text configuration options supports HTML markup. For example this allows custom font colors, size and reference images (e.g. logos). The most common requirement is to bold text and this can be done by surrounding with
<strong> tags. If you are not familiar with HTML, your webmaster or website administrator should be able to offer some advice.
444
Web Cashier
Figure 25.6. Web Cashier default configuration
25.6. Assigning Web Cashier User
Web Cashier users are administrator type users who usually have limited rights. For example a Web Cashier user may be a service desk staff member and you may choose to grant them access to the Web Cashier option only and not other administrator rights. Web Cashier users are assigned via Options
→
Admin Rights
To assign a user or group as a Web Cashier user:
•
information.)
• If you only want to provide them access to the Web Cashier then clear all the other options and only select Web
Cashier user.
445
Web Cashier
Figure 25.7. Web Cashier user
• It is possible to allow user to perform Purchase or Deposit only. For example, library or print room staff may have rights to apply purchases (e.g. binding or bulk printing), while not being given access to deposit money onto accounts for security reasons.
Important
Many Web Cahsier users are non-technical staff. After setting up a new user as a Web Cashier user make sure you provider them with the browser access URL (i.e.
http://[server-name]:9191/webcashier
) and take a few moments to demonstrate common functionality such as performing a purchase/deposit.
25.7. Web Cashier Reports
All the Web Cashier reports are accessible via Reports
→
Transaction
→
Web Cashier Transaction Reports. To see a sample click on Show sample.
Report name
Web Cashier orders
Web Cashier purchases - details
Web Cashier items - summary
Table 25.2. Web Cashier Reports
Description
It is a list of all the Purchase and Deposit orders sorted by date.
It gives detailed information for all purchases done via Web Cashier.
It is a summary of all the items purchased within a certain period.
446
Web Cashier
To know more about reports see Chapter 9, Reports.
Tip
All these reports can be scheduled to be automatically emailed via Reports
→
Schedule on a daily, weekly or monthly basis to designated staff as appropriate.
447
Chapter 26. Clustering and High
Availability
26.1. About Clustering
PaperCut NG is designed to scale to networks over 50,000 users (largest deployments are running over 300,000 users). To ensure reliability on networks of this size, network architects may adopt strategies including:
• Load balancing - spreading tasks across multiple servers.
• Clustering - building in redundancy by implementing a failover strategy.
PaperCut NG is a cluster compatible application. It supports clustering at all levels of the application, including
• Clustering at the print spooler service layer by integrating with clustering services.
• Failover based clustering at the application server layer using clustering services. (PaperCut's application server is web and web services based, and hence can support other failover methods such as heartbeat driven DNS).
• At the database layer by utilizing cluster aware databases such as Microsoft SQL Server or Oracle.
Setting up PaperCut in a cluster environment is an advanced operation. This chapter assumes the reader has a high level of expertise in system and cluster configuration. The cluster environment should be operational before undertaking the PaperCut installation. Readers should also have a good understanding of PaperCut's Service
Oriented Architecture - specifically its two main components, the Application Server and the Print Provider and how
they work together (Section 17.4, “Print Monitoring Architecture”).
In a cluster environment, PaperCut can be set up in one of two possible configurations.
Mode 1 is the simplest configuration and is suitable for most organizations. It implements clustering in the “front line”, that is, the printers and print monitoring layer. The cluster print server is configured as a secondary print server reporting back to a primary PaperCut server hosted on another system outside the cluster.
Mode 2 implements clustering on all levels of the application for maximum fault tolerance - In addition to the print queues, the PaperCut Application Server is also hosted in the cluster. Mode 2 is somewhat more demanding to configure and should only be attempted by organizations with staff experienced with advanced cluster and database management.
Please refer to the subsequent sections for an explanation on how to set up Mode 1 or Mode 2 in your environment.
This section assumes that you have an already installed and working clustered printing environment.
26.2. Microsoft Failover Cluster Manager (MSFCM) on Windows 2008 R2 or later
Microsoft Windows 2008 R2 and later offers clustering capabilities through its Microsoft Failover Cluster Manager
(MSFCM).
Novell Cluster Services should jump to their respective sections.
This section assumes that you have an already installed and working clustered server environment.
Mode 1 is the simplest configuration and is suitable for most organizations. It implements clustering in the “front line”, that is, the printer and print monitoring layer. The cluster print server is configured as a secondary print server reporting back to a primary PaperCut server hosted on another system outside the cluster.
Mode 2 implements clustering on all levels of the application for maximum fault tolerance - In addition to the print queues, the PaperCut Application Server is also hosted in the cluster. Mode 2 is somewhat more demanding to configure and should only be attempted by organizations with staff experienced with advanced cluster and database
448
Clustering and High Availability management.
Please refer to the subsequent sections for an explanation on how to set up Mode 1 or Mode 2 in your environment.
Important
Windows Server 2008 R2 installations may experience a Windows bug where print jobs are not
removed from the print queue when completed. For more information please see Section 2.1.2.3,
“Windows Server 2008 R2 only”. This work around will need to be performed on the clustered print
server, not the nodes.
26.2.1. Mode 1 - Clustering at the print layer
Note
Windows 2012 no longer support high-availability of printing servers using Failover Cluster Manager.
Microsoft now only supports printing high availability through the use of highly available VM clusters.
This is described in detail in the Microsoft document High Availablity Printing Overview
Machine Clustering” for more information on VM clustering.
To setup Mode 1 clustering on Windows 2012 the printer server must be installed on a highly available
VM cluster.
The remainder of this section described setting up Mode 1 on Windows 2008.
26.2.1.1. Step 1 - Application Server (Primary Server) Setup
Install the Application Server component (Standard Install option) on your nominated system. This system will be responsible for providing PaperCut NG's web based interface and storing data. In most cases this system will not host any printers and is dedicated to the roll of hosting the PaperCut Application Server. It may be one of the nodes in the cluster; however a separate system outside the cluster is generally recommended. An existing domain controller, member server or file server will suffice.
26.2.1.2. Step 2 - Installing the Print Provider components on each node
The Print Provider component needs to be separately installed on each node involved in the print spooler cluster.
This is done by selecting the Secondary Print Server option in the installer. Follow the secondary server set up
define the correct name or IP address of the nominated application server set up in step 1.
26.2.1.3. Step 3 - Decouple service management from nodes
By default the Print Provider component is installed under the management of the node. To hand over management to the cluster, the service start-up type needs to be set to manual. On each node navigate to Administrative Tools
→
Services, locate the
PaperCut Print Provider service. Stop the service and set the start-up type to
Manual. Repeat for each node in the cluster.
449
Clustering and High Availability
Figure 26.1. Stopping the service and setting to Manual startup
26.2.1.4. Step 4 - Adding the Print Provider service as a resource under the print spooler's cluster group
1.
Open the Failover Cluster Manager.
2.
Right-click on the cluster group hosting the spooler service and select Add a resource
→
4 - Generic Service.
Figure 26.2. Adding a new Generic Service Resource
3.
In the new resource wizard, select the name
PaperCut Print Provider and click Next.
4.
Click Next at Confirmation.
5.
Click Finish at Summary.
6.
Right click on the
PaperCut Print Provider and click Properties. On the PaperCut Print Provider
Properties page ensure the Use Network Name for computer name option is checked.
450
Clustering and High Availability
Figure 26.3. Cluster service parameters configuration
7.
Next, click the Dependencies tab and ensure the Print Spooler is added as a resource. Click Ok.
8.
Right click on the
PaperCut Print Provider and click Bring this resource online.
26.2.1.5. Step 5 - Shared active job spool
To ensure the state of jobs currently active (e.g. held in a hold/release queue) are not lost during a failover event,
PaperCut NG is able to save job state in a shared drive/directory. If a shared disk resource is available and can be added to the cluster resource, PaperCut can use this to host a shared spool directory to ensure no active job state is lost.
1.
Add a shared drive to the cluster resource. e.g. (Q: drive). It is advisable to use the same drive as used for the shared print spool directory.
2.
Create a directory in this drive called
PaperCut\Spool
3.
On each node, edit the file:
[app-path]/providers/print/win/print-provider.conf
and add a line pointing to the shared active job spool directory:
SpoolDir=Q:\\PaperCut\\Spool
Change the drive letter as appropriate.
Important
If running an "Active-Active" print cluster you must use a separate active job spool directory for each node. To configure this use the
%service-name% value in the
SpoolDir setting. The
%service-name% value is replaced by the service name of the running PaperCut Print Provider instance. e.g.
SpoolDir=Q:\\PaperCut\\Spool\\%service-name%
451
Clustering and High Availability
See below for details on "Active-Active".
4.
Restart the cluster resource to ensure the change is picked up.
26.2.1.6. Step 6 - Test
Perform operations to verify that:
1.
Print jobs are logged as expected.
2.
No error message appear in the Print Providers text log located at:
C:\Program Files\PaperCut
NG\providers\print\win\print-provider.log
on each node.
26.2.1.7. Active/Active Clustering - Special notes regarding multiple virtual servers
On large networks it is common to distribute load by hosting print spooler services under two or more virtual servers.
For example, two virtual servers may each host half of the organization's printers and hence sharing the load. This is sometimes referred to as Active/Active clustering - albeit not an entirely correct term, as the print spooler is still running in Active/Passive.
Virtual servers cannot share the same service on any given node. For this reason if the virtual servers share nodes, you'll need to manually install the
PaperCut Print Provider service a second time under a different name. This can be done via the command line as follows: cd \Program Files\PaperCut NG\providers\print\win pc-print.exe PCPrintProvider2 /install
The argument proceeding
/install is the unique name to assign to the service. The recommended procedure is to suffix the standard service name with a sequential number. You'll need to repeat this on each physical node.
You'll use a unique service name for each "active" virtual server hosted in the cluster group.
You will also need to make sure that you have unique
SpoolDir settings for each node of your cluster. Ensure that the
SpoolDir setting in the print-provider.conf
file has a
%service-name% expansion variable as explained above. This will ensure each service has it's own spool directory.
26.2.2. Mode 2 - Clustering at all application layers
Mode 2 implements failover clustering at all of PaperCut NG's Service Oriented Architecture software layers, including:
• Clustering at the Print monitoring layer
• Clustering at the Application Server layer
• Optional clustering at the database layer
Mode 2 builds upon Mode 1 by introducing failover (Active/Passive) clustering in the Application Server layer. This involves having an instance of the application server on each of the cluster nodes. When one node fails, the other automatically takes over the operation. Both instances use a share data source in the form of an external database
database such as Microsoft SQL Server.
This section assumes that you have an already installed and working Service and Application group hosting a clustered printing environment.
26.2.2.1. Step 1 - Application Server Installation
On one of the cluster's nodes, install the PaperCut Application Server component by selecting the Standard Install
452
Clustering and High Availability option in the installer. Follow the setup wizard and complete the process of importing all users into the system.
26.2.2.2. Step 2 - Convert the system over to an external database
The system needs to be configured to use an external database as this database will be shared between both instances of the Application Server. Convert the system over to the required external database by following the
another system, or inside a cluster. As per the external database setup notes, reference the database server by IP address by entering the appropriate connection string in the server.properties
file.
26.2.2.3. Step 3 - Setup of 2nd Node
Repeat steps 1 and 2 on the second and any subsequent cluster nodes.
26.2.2.4. Step 4 - Distributing Application Licence
Your licence will need to be installed on your 2nd node and any subsequent cluster nodes. To do this Log into the administration console by browsing to http://[IP-Address-Of-Your-Node]:9191/admin Navigate to the About section, scroll down to the Register section and click the Browse... button. Locate the license file, click the Install license button, verify license information is correctly listed in the About page.
26.2.2.5. Step 5 - Decouple service management from the nodes
By default the
PaperCut Application Server component is installed under the management of the node. It needs to be managed inside the cluster, so the service's start-up type should be set to manual. On each node navigate to Administrative Tools
→
Services locate the PaperCut Application Server. Stop the service and set its start-up type to Manual. Repeat this on all nodes.
26.2.2.6. Step 6 - Create a new Services and Applications group
Create a new Services and Applications group containing the two nodes. Make note of the IP Address that you assign as it will be used later. Add the Generic Service PaperCut Application Server. Give the Client Access Point an appropriate title such as
PaperCutAppCluster
.
Figure 26.4. Adding a new Generic Service Resource
This Services and Applications group is separate to the existing clustered printing environment. It is recommended to set up two Services and Application groups where you can later set the node affinity to better distribute the application load across nodes.
26.2.2.7. Step 7 - Configure PaperCut Application Server
Right click on the
PaperCut Application Server and click Properties. On the PaperCut Application Server
Properties page ensure the Use Network Name for computer name option is checked. On the Dependencies tab make sure the Service and Application group is added as a Resource. Click Ok.
453
Clustering and High Availability
Figure 26.5. PaperCut Application Server Properties configuration
Figure 26.6. PaperCut dependencies configuration
26.2.2.8. Step 8 - Confirm PaperCut Application Server active
Right-click on the Service and Applications group and select Bring online. Wait until the application server has started, then verify that you can access the system by pointing a web browser to:
454
Clustering and High Availability http://[Virtual Server Name]:9191/admin
Login, and perform some tasks such as basic user management and User/Group Synchronization to verify the system works as expected.
26.2.2.9. Step 9 - Set up the Print Provider layer
that the IP address of the application server will be the IP address assigned to the Virtual Server.
26.2.2.10. Step 10 - Client Configuration
The client and release station programs are located in the directories:
•
[app-path]/client/
•
[app-path]/release/
These directories contain configuration files that instruct the client to the whereabouts of the server. The IP address and the server name in the following set of files will need to be updated to the Virtual Server's details (Name and IP address):
•
[app-path]/client/win/config.properties
•
[app-path]/client/linux/config.properties
•
[app-path]/client/mac/PCClient.app/Contents/Resources/config.properties
•
[app-path]/release/connection.properties
26.2.2.11. Step 11 - Test
Mode 2 setup is about as complex as it gets! Take some time to verify all is working and that PaperCut NG is tracking printing on all printers and all virtual servers.
26.2.2.12. Advanced: Load distribution and independent groups
Separating these resources into to groups, running on different IP addresses allows you to set up different node affinities so the two groups usually run on separate physical nodes during normal operation. This ensures the load is spread across multiple nodes.
To make this change after setting up the single group Mode 2 configuration:
1.
Set the Preferred owners of each Services and Applications group to different physical nodes.
2.
Restart or bring on line each group, and independently test operation and operation after fail-over.
26.2.3. Clustering Tips
1.
Take some time to simulate node failure. Monitoring may stop for a few seconds while the passive server takes over the role. Simulating node failure is the best way to ensure both sides of the Active/Passive setup is configured correctly.
2.
It is important that the version of PaperCut running on each node is identical. Ensure that any version updates are applied to all nodes so versions are kept in sync.
3.
The PaperCut installation sets up a read-only share exposing client software to network users. If your organization is using the zero-install deployment method, the files in this share will be accessed each time a user logs onto the network. Your network may benefit from exposing the contents of this share via a clustered file share resource.
455
Clustering and High Availability
4.
PaperCut regularly saves transient state information (such as print job account selections) to disk so that this state can be recovered on server restart. If failing over to a new cluster server, you should ensure this state information is saved to a location available to the new server.
By default the state information is located in
[app-path]/server/data/internal/state/systemstate
.
You can change this location if required by setting the property server.internal-state-path in your server.properties file.
26.2.4. Additional configuration to support Web Print
By default the Application Server will look in
[app-path]\server\data\web-print-hot-folder for Web
Print files. This location is generally only available on one node in the cluster. To support Web Print in a cluster you will need to add a Shared Folder on the Shared Storage in your cluster. This can be done on the same disk that the spool files reside and the Print Provider point to.
To change this location you will need to use the Config Editor and modify the web-print.hot-folder key.
1.
Add a Shared Folder on the Shared Storage, an example would be
E:\web-print-hot-folder and share it as
\\clustername\web-print-hot-folder\
.
2.
Log in to the PaperCut NG administration console, naviate to Options
→
Config Editor
3.
Modify web-print.hot-folder to
E:\web-print-hot-folder
4.
Map your selected network drive
\\clustername\web-print-hot-folder\ on the Web Print Sandbox machine to
5.
Add all relevant printer queues from
\\clustername\web-print-hot-folder\ to the Web Print Sandbox server.
26.2.5. Additional configuration to support Print Archiving
If you have enabled Print
Applications Server stores archived print jobs in
[app-path]\server\data\archive
. This location is generally only available on one node in the cluster. To support Print Archiving in a cluster you will need to add a Shared Folder on the Shared Storage in your cluster.
This location must be accessible to all cluster nodes and also any print servers that are collecting print archives.
describes how to configure both the application server and your print servers to use the same shared storage location.
26.3. Microsoft Cluster Server (MSCS) on Windows
Microsoft Windows 2003/2008 offers clustering capabilities through its Microsoft Cluster Server (MSCS)
This section assumes that you have an already installed and working clustered printing environment.
26.3.1. Mode 1 - Clustering at the Print Provider layer
The PaperCut Print Provider is the component that integrates with the print spooler service and provides information about the print events to the PaperCut Application Server. At a minimum, in a cluster environment, the Print Provider component needs to be included and managed within the cluster group. The Application Server component (The
Standard Install option in the installer) is set up on an external server outside the cluster. Each node in the cluster is configured to report back to the single application server using XML web services over TCP/IP.
26.3.1.1. Step 1 - Application Server (Primary Server) Setup
Install the Application Server component (Standard Install option) on your nominated system. This system will be responsible for providing PaperCut NG's web based interface and storing data. In most cases this system will not host any printers and is dedicated to the roll of hosting the PaperCut Application Server. It may be one of the nodes
456
Clustering and High Availability in the cluster; however a separate system outside the cluster is generally recommended. An existing domain controller, member server or file server will suffice.
26.3.1.2. Step 2 - Installing the Print Provider components on each node
The Print Provider component needs to be separately installed on each node involved in the print spooler cluster.
This is done by selecting the Secondary Print Server option in the installer. Follow the secondary server set up
define the correct name or IP address of the nominated application server set up in step 1.
26.3.1.3. Step 3 - Decouple service management from nodes
By default the Print Provider component is installed under the management of the node. To hand over management to the cluster, the service start-up type needs to be set to manual. On each node navigate to Control Panel
→
Administrative Tools
→
Services, locate the
PaperCut Print Provider service. Stop the service and set the start-up type to Manual. Repeat for each node in the cluster.
Figure 26.7. Stopping the service and setting to Manual startup
26.3.1.4. Step 4 - Adding the Print Provider service as a resource under the print spooler's cluster group
1.
Open the Cluster Administrator.
2.
Right-click on the cluster group hosting the spooler service and select New
→
Resource.
457
Clustering and High Availability
Figure 26.8. Creating a new cluster resource
3.
In the new resource wizard, enter a name of
PaperCut Print Provider and select a resource type of
Generic Service. Click Next.
4.
Click Next at Possible Owners.
5.
Ensure that the
Print Spooler Service resource is set as a required dependency, then click Next.
6.
On the Generic Service Parameters page, enter a service name of
PCPrintProvider and ensure the Use
Network Name for computer name option is checked. Click Next.
Figure 26.9. Cluster service parameters configuration
7.
Click Finish at the Registry Replication page.
26.3.1.5. Step 5 - Shared active job spool
To ensure the state of jobs currently active (e.g. held in a hold/release queue) are not lost during a failover event,
PaperCut NG is able to save job state in a shared drive/directory. If a shared disk resource is available and can be added to the cluster resource, PaperCut can use this to host a shared spool directory to ensure no active job state is lost.
1.
Add a shared drive to the cluster resource. e.g. (Q: drive). It is advisable to use the same drive as used for the shared print spool directory.
458
Clustering and High Availability
2.
Create a directory in this drive called
PaperCut\\Spool
.
3.
On each node, edit the file:
[app-path]/providers/print/win/print-provider.conf
and add a line pointing to the shared active job spool directory:
SpoolDir=Q:\\PaperCut\\Spool
Change the drive letter as appropriate.
Important
If running an "Active-Active" print cluster you must use a separate active job spool directory for each node. To configure this use the
%service-name% value in the
SpoolDir setting. The
%service-name% value is replaced by the service name of the running PaperCut Print Provider instance. e.g.
SpoolDir=Q:\\PaperCut\\Spool\\%service-name%
See below for details on "Active-Active"
26.3.1.6. Step 6 - Bring up all cluster resources and test
Perform operations to verify that:
1.
Print jobs log as expected.
2.
No error message appear in the Print Providers text log located at:
C:\Program Files\PaperCut
NG\providers\print\win\print-provider.log
on each node.
26.3.1.7. Active/Active Clustering - Special notes regarding multiple virtual servers
On large networks it is common to distribute load by hosting print spooler services under two or more virtual servers.
For example, two virtual servers may each host half of the organization's printers and hence sharing the load. This is sometimes referred to as Active/Active clustering - albeit not an entirely correct term, as the print spooler is still running in Active/Passive.
Virtual servers cannot share the same service on any given node. For this reason if the virtual servers share nodes, you'll need to manually install the
PaperCut Print Provider service a second time under a different name. This can be done via the command line as follows: cd \Program Files\PaperCut NG\providers\print\win pc-print.exe PCPrintProvider2 /install
The argument proceeding
/install is the unique name to assign to the service. The recommended procedure is to suffix the standard service name with a sequential number. You'll need to repeat this on each physical node.
You'll use a unique service name for each "active" virtual server hosted in the cluster group.
You will also need to make sure that you have unique
SpoolDir settings for each node of your cluster. Ensure that the
SpoolDir setting in the print-provider.conf
file has a
%service-name% expansion variable as explained above. This will ensure each service has it's own spool directory.
26.3.2. Mode 2 - Clustering at all application layers
Mode 2 implements failover clustering at all of PaperCut NG's Service Oriented Architecture software layers, including:
459
Clustering and High Availability
• Clustering at the Print monitoring layer
• Clustering at the Application Server layer
• Optional clustering at the database layer
Mode 2 builds upon Mode 1 by introducing failover (Active/Passive) clustering in the Application Server layer. This involves having an instance of the application server on each of the cluster nodes. When one node fails, the other automatically takes over the operation. Both instances use a shared data source in the form of an external database
database such as Microsoft SQL Server.
This section assumes that you have an already installed and working clustered printing environment.
26.3.2.1. Step 1 - Application Server Installation
On one of the cluster's nodes, install the PaperCut Application Server component by selecting the Standard Install option in the installer. Follow the setup wizard and complete the process of importing all users into the system.
26.3.2.2. Step 2 - Convert the system over to an external database
The system needs to be configured to use an external database as this database will be shared between both instances of the application server. Convert the system over to the required external database by following the
another system, or inside a cluster. As per the external database setup notes, reference the database server by IP address by entering the appropriate connection string in the server.properties
file.
26.3.2.3. Step 3 - Setup of 2nd Node
Repeat steps 1 and 2 on the second cluster node.
26.3.2.4. Step 4 - Distributing Application Licence
Your licence will need to be installed on each node in your cluster. To do this log into the administration console by browsing to http://[IP-Address-Of-Your-Node]:9191/admin Navigate to the About section, scroll down to the Register section and click the Browse... button. Locate the license file, click the Install License button, verify license information is correctly listed in the About page.
26.3.2.5. Step 5 - Decouple service management from the nodes
By default the
PaperCut Application Server component is installed under the management of the node. It needs to be managed inside the cluster, so the service's start-up type should be set to manual. On each node navigate to Control Panel
→
Administrative Tools
→
Services locate the PaperCut Application Server. Stop the service and set its start-up type to Manual. Repeat this on each node.
26.3.2.6. Step 6 - Create a new cluster group
The
PaperCut Application Server should be designated to run inside its own cluster group. Create a new cluster group containing the each of the nodes. Add an IP Resource and a Network Name resource. Give the network name resource an appropriate title such as
PCAppSrv
.
The need for a new cluster group is not required. It is however recommended as it gives the most flexibility in terms of load balancing and minimizes the potential for conflicts.
26.3.2.7. Step 7 - Adding the PaperCut Application Service as a resource managed under the new cluster group.
1.
Open the Cluster Administrator.
2.
Right-click on the cluster group hosting the spooler service and select New
→
Resource.
3.
In the new resource wizard, enter a name of
PaperCut Application Server and select a resource type of
Generic Service. Click Next.
460
Clustering and High Availability
4.
Click Next at Possible Owners page.
5.
Click Next at Dependency page.
6.
On the Generic Service Parameters page, enter a service name of
PCAppServer and ensure the Use
Network Name for computer name option is checked. Click Next.
7.
Click Finish at the Registry Replication page.
26.3.2.8. Step 8 - Bring the cluster group online
Right-click on the cluster group and select Bring online. Wait until the application server has started, then verify that you can access the system by pointing a web browser to : http://[Virtual Server Name]:9191/admin
Login, and perform some tasks such as basic user management and User/Group Synchronization to verify the system works as expected.
26.3.2.9. Step 9 - Set up the Print Provider layer
Interface the PaperCut Print Provider layer with the clustered spooler service by following the same setup notes as described for Mode 1. The exception being that the IP address of the application server will be the IP address assigned to the Virtual Server assigned in step 6.
26.3.2.10. Step 10 - Client Configuration
The client and release station programs are located in the directories:
•
[app-path]/client/
•
[app-path]/release/
These directories contain configuration files that instruct the client to the whereabouts of the server. The IP address and the server name in the following set of files will need to be updated to the Virtual Server's details (Name and IP address):
•
[app-path]/client/win/config.properties
•
[app-path]/client/linux/config.properties
•
[app-path]/client/mac/PCClient.app/Contents/Resources/config.properties
•
[app-path]/release/connection.properties
26.3.2.11. Step 11 - Test
Mode 2 setup is about as complex as it gets! Take some time to verify all is working and that PaperCut NG is tracking printing on all printers and all virtual servers.
26.3.2.12. Advanced: Load distribution and independent groups
It is possible to split the two application layers (Resources) into two separate Cluster Groups:
• Group 1: Containing only the
PaperCut Application Server service.
• Group 2: Containing the
PaperCut Print Provider and
Print Spooler services. These services are dependent and hence must be hosted in the same group.
Separating these resources into to groups allows you to set up different node affinities so the two groups usually run on separate physical nodes during normal operation. The advantage is that the load is spread further across the systems and a failure in one group will not necessarily fail-over the other.
461
Clustering and High Availability
To make this change after setting up the single group Mode 2 configuration:
1.
Change the
ApplicationServer= option in
[app-path]/providers/print/win/print-provider.conf
on each physical node to the IP or DNS name of the virtual server.
2.
Create a new group called
PaperCut Application Server Group
.
3.
Set the Preferred owners of each group to different physical nodes.
4.
Restart or bring on line each group, and independently test operation and operation after fail-over.
26.3.3. Clustering Tips
1.
Take some time to simulate node failure. Monitoring may stop for a few seconds while the passive server takes over the role. Simulating node failure is the best way to ensure both sides of the Active/Passive setup is configured correctly.
2.
It is important that the version of PaperCut running on each node is identical. Ensure that any version updates are applied to all nodes so versions are kept in sync.
3.
The PaperCut installation sets up a read-only share exposing client software to network users. If your organization is using the zero-install deployment method, the files in this share will be accessed each time a user logs onto the network. Your network may benefit from exposing the contents of this share via a clustered file share resource.
4.
PaperCut regularly saves transient state information (such as print job account selections) to disk so that this state can be recovered on server restart. If failing over to a new cluster server, you should ensure this state information is saved to a location available to the new server.
By default the state information is located in
[app-path]/server/data/internal/state/systemstate
.
You can change this location if required by setting the property server.internal-state-path in your server.properties file.
26.3.4. Additional configuration to support Web Print
By default the Application Server will look in
[app-path]\server\data\web-print-hot-folder for Web
Print files. This location is generally only available on one node in the cluster. To support Web Print in a cluster you will need to add a Shared Folder on the Shared Storage in your cluster. This can be done on the same disk that the spool files reside and the Print Provider points to.
To change this location you will need to use the Config Editor and modify the web-print.hot-folder key.
1.
Add a Shared Folder on the Shared Storage, an example would be
E:\web-print-hot-folder and share it as
\\clustername\web-print-hot-folder\
.
2.
Log in to the PaperCut NG administration console, naviate to Options
→
Config Editor
3.
Modify web-print.hot-folder to
E:\web-print-hot-folder machine to 4.
Map your selected network drive
\\clustername\web-print-hot-folder\ on the Web Print Sandbox
5.
Add all relevant printer queues from
\\clustername to the Web Print Sandbox server.
26.3.5. Additional configuration to support Print Archiving
If you have enabled Print
Applications Server stores archived print jobs in
[app-path]\server\data\archive
. This location is generally only available on one node in the cluster. To support Print Archiving in a cluster you will need to add a Shared Folder on the Shared Storage in your cluster.
This location must be accessible to all cluster nodes and also any print servers that are collecting print archives.
describes how to configure both the application server and your print servers to use the same shared storage
462
Clustering and High Availability location.
26.4. Virtual Machine Clustering
Virtual Machine (VM) technologies, such as VMWare, Microsoft Hyper-V are becoming increasingly popular. They provide great flexibility in deploying servers within an organization. VM implementaions can also provide high-availability through the use of VM clusters. When a VM is running in a highly available VM cluster, any failure of the physical hardware will not affect the running VM as it is seemlessly transferred to another node in the cluster.
Implementing high-availability using VM infrastructure is much simpler to install and manage than using the built-in operating system and application clustering support. You simply set up your VM instances and the VM infrastructure ensures they continue to run uninterrupted.
This allows you to setup PaperCut just like on a physical server, but allow the VM infrastructure to provide the high availability.
This section discusses a generic clustered Virtual Machine setup.
PaperCut offers great flexibility and allows you to easily structure your installation into physical multi-tiered clustered components.
Clustering at Virtual Machine level offers these advantages over other “traditional” clustering setups:
• Your software, drivers, settings, etc. are installed and configured once, in a single VM
• Depending on your VM infrastructure, when a physical node fails the VM can be shifted to another node with marginal or no downtime
• Backup processes can be dramatically simplified
• Disaster recovery capabilities are inherently available
Virtual Machine hosts can automatically detect when a VM crashes or becomes unresponsive. You should consider whether you will augment this with application level monitoring. Although the VM might be running normally, the underlying application may have problems and application level monitoring may detect this. Ways of perform application level monitoring can be achieved through (but not limited to):
• Loading an application server URL to test server is running
• IP pings
• Checking that PaperCut services are running
26.4.1. Define your VM Clustering Environment
Define your Virtual Machine Vendor/Product and how you want configure the VM cluster for high availability.
There are many VM deployment strategies you can leverage depending on the VM platform you are utilizing, including VMs that might be hosted in different physical boxes, or even in different sites, which might configure a typical Disaster Recover (DR) scenario.
When selecting a VM product, it's particularly important to consider the following product features:
• Fault Tolerance (FT): FT provides continuous availability for virtual machines by automatically creating and maintaining a secondary virtual machine that is identical to the primary virtual machine.
• High Availability (HA): Should a VM fail, a new VM can be made available minimizing down time. Generally, FT is a functionality added on top of HA which provides seamless switch over if no loss of state.
• Application High Availability (App HA): It's important that your VM vendor product offers Application Level monitoring. If the application fails, a new VM can be make available minimizing down time.
• Data Replication and Backup: Consider features on how the application data can be backup and restored.
Generally tape based backups are slow and can very often get corrupted. Replication of in memory data in case of FT or Disaster Recovery (DR) features might also play an important role. Specific proprietary algorithms for memory segments replication usually reduce the bandwidth needs and are very efficient.
463
Clustering and High Availability
26.4.2. VM Clustering Setup
There are many ways in which PaperCut can be deployed on VM infrastructure. Rather than be prescritive, we offer general considerations for implementing a VM-based clustered PaperCut installation.
26.4.2.1. Mode 1 - Clustering at the Print Layer
Setup and configure print servers as required in your VM environment and configure them for VM high availability.
You then just need to install the PaperCut Secondary Server components to monitor printing on the print servers.
See Chapter 17, Configuring Secondary Print Servers and Locally Attached Printers.
Tip
Microsoft have a guide to high availability printing that discusses the setup of printing in highly available VM enironments (in particular Hyper-V). See the Microsoft High Availablity Printing Overview
[http://technet.microsoft.com/en-us/library/jj556311.aspx].
26.4.2.2. Mode 2 - Clustering at the Application Server layer
Setup and configure a new server in your VM infrastructure to host the Application Server component. Configure this
VM with high-availability. Then install the PaperCut Application Server as per the normal setup process.
Clustering at the Print Layer”.
26.5. Veritas Cluster Server (VCS) on Windows
This section discusses configuring PaperCut NG on a Veritas Cluster Server (VCS). The section provides a brief overview and is designed to supplement guidance from the PaperCut NG development team. If you are about to commence a production deployment on VCS, please feel free to get in touch with the development team for further assistance if required.
Note that Mode 1 only is supported for deploying on VCS.
This section assumes that you have an already installed and working clustered printing environment.
26.5.1. Mode 1 - Clustering at the print layer
The
PaperCut Print Provider is the component that integrates with the
Print Spooler service and provides information about the print events to the PaperCut Application Server. At a minimum, in a cluster environment, the PaperCut Print Provider component needs to be included and managed within the cluster group.
The PaperCut Application Server component (The Standard installation (primary server) option in the installer) is set up on an external server outside the cluster. Each node in the cluster is configured to report back to the single application server using XML web services over TCP/IP.
26.5.1.1. Single Virtual Server (Active/Passive)
PaperCut NG supports both Active/Passive and virtual Active/Active in VCS. This section discusses configurating
PaperCut NG on a single virtual server running Active/Passive. If your organization hosts mutliple virtual servers, jump to the following section covering Active/Active.
26.5.1.1.1. Step 1 - Set up the cluster, print spooler and printers
First, set up and verify that the cluster and print server is working as expected. The system should be fully configured and tested before proceeding to the next step and installing PaperCut NG.
26.5.1.1.2. Step 2 - Set up the PaperCut application server (primary server) on a system outside the cluster
Install the
PaperCut Application Server component (Standard installation option) on your nominated system. This system will be responsible for providing PaperCut NG's web based interface and storing data. In most
464
Clustering and High Availability cases this system will not host any printers and is dedicated to the role of hosting the PaperCut Application Server.
It may be one of the nodes in the cluster; however a separate system outside the cluster is generally recommended.
An existing domain controller, member server or file server will suffice.
26.5.1.1.3. Step 3 - Install PaperCut Print Provider on both nodes
The Print Provider component needs to be installed separately on each node involved in the print spooler cluster.
This is done by selecting the Secondary Print Server option in the installer. Follow the secondary server set up
define the correct name or IP address of the nominated application server set up in step 1.
26.5.1.1.4. Step 4 - Configure the PaperCut Print Provider Service to bind to the virtual server
By default the PaperCut Print Provider component will associate itself with the physical node. A configuration change is required to force it to bind to the virtual server. Add the following lines (or uncomment the example lines) to the file:
C:\Program Files\PaperCut NG\providers\print\win\print-provider.conf
ServerName=[VIRTUAL SERVER NAME]
PrintServerName=\\[VIRTUAL SERVER NAME]
Where
[VIRTUAL SERVER NAME] is the network name associated with your virtual server. Note that the
PrintServerName must be prefixed with two back-slashes (
\\
). The first setting is used to override the name reported to the PaperCut NG Application Server. The
PrintServerName setting instructs the print provider to search for printers on the virtual server rather than on the physical server.
26.5.1.1.5. Step 5 - Decouple service management from nodes
By default the Print Provider component is installed under the management of the node. To hand over management to the cluster, the service start-up type needs to be set to manual. On each node navigate to Control Panel
→
Administrative Tools
→
Services and locate the
PaperCut Print Provider service. Stop the service and set the start-up type to Manual. Repeat for each node in the cluster.
Figure 26.10. Stopping the service and setting to Manual startup
26.5.1.1.6. Step 6 - Add the PaperCut Print Provider Service as a Generic Service
The PaperCut Print Provider service needs to be added to the Veritas Cluster group associated with the virtual server. This is to ensure that the service is managed within the same group as the print server and will fail-over as
465
Clustering and High Availability part of the group. Create a new GenericServer resource called
PaperCutPrintProvider01
. Set the service name to
PCPrintProvider
. The account, password and domain can be left as defaults.
26.5.1.1.7. Step 7 - Set up dependencies
The
PCPrintProvider service must start after the print spool resource. Create a dependency link between
PaperCutPrintProvider01 and the
PrintSpooler using the tools on the Veritas Cluster Resources tab associated with this virtual server.
26.5.1.1.8. Step 8 - Test
Take some time to test and ensure printing is monitored as expected. Use the Veritas Cluster administration console to simulate node failure and ensure monitoring continues after failure.
26.5.1.2. Multiple Virtual Servers (Active/Active)
On large networks it is common to distribute load by hosting print spooler services under two or more virtual servers.
For example, two virtual servers may each host half of the organization's printers and hence share the load. This is sometimes referred to as Active/Active clustering - albeit not an entirely correct term, as the print spooler is still running in Active/Passive.
Virtual servers cannot share the same service on any given node. For this reason if the virtual servers share nodes, you'll need to manually install the
PaperCut Print Provider service a second time under a different name. Use the following procedure.
26.5.1.2.1. Step 1 - Set up one Virtual Server
Set up one virtual server using all steps in the preceding section. After this virtual server is tested, perform the steps below to set up the 2nd virtual server.
26.5.1.2.2. Step 2 - Create a 2nd instance of the PaperCut Print Provider on each physical node
A 2nd copy of the PaperCut Print Provider needs to be created on each physical node. This is required so that a separate service can be installed and configured to bind to the 2nd virtual server. Copy the following directory, and all its contents:
C:\Program Files\PaperCut NG\providers\print to
C:\Program Files\PaperCut
NG\providers\print2
. Repeat this step on both physical nodes.
26.5.1.2.3. Step 3 - Configure the copied instance to bind to the 2nd virtual server
Add the following lines (or uncomment the example lines) to the file at
C:\Program Files\PaperCut
NG\providers\print\win\print-provider.conf
:
ServerName=[VIRTUAL SERVER NAME 2]
PrintServerName=\\[VIRTUAL SERVER NAME 2]
Where
[VIRTUAL SERVER NAME 2] is the network name associated with your 2nd virtual server. Note that the
PrintServerName must be prefixed with two back-slashes (
\\
).
Repeat this step on both physical nodes.
26.5.1.2.4. Step 4 - Manually install the a 2nd instance of the PCPrintProvider service
Services need a unique name. We'll install a 2nd instance of the service under the name
PCPrintProvider2
. This is done by typing the following commands at the command prompt.
cd C:\Program Files\PaperCut NG\providers\print2\win pc-print.exe PCPrintProvider2 /install
The argument preceding
/install is the unique name to assign to the service. The recommended procedure is to suffix the standard service name with a sequential number. You'll need to repeat this on each physical node. You'll use a unique service name for each "active" virtual server hosted in the cluster group.
466
Clustering and High Availability
26.5.1.2.5. Step 5 - Add this service to the resource group associated with the 2nd virtual server
Repeat steps 5 through 8 in the preceding section, this time using the service name
PCPrintProvider2 rather than
PCPrintProvider
.
The recommend unique name for the cluster resource in step 6 is
PaperCutPrintProvider01
.
26.6. Novell Cluster Services (NCS) on Novell OES Linux
This section assumes that you have an already installed and working clustered printing environment.
26.6.1. Mode 1 - Clustering at the print layer
26.6.1.1. Step 1 - Application Server (Primary Server) Setup
Before installing a secondary server/clustered print provider you should take some time to ensure the primary
PaperCut server (central Application Server) is set up and running correctly. The primary server will be responsible for providing PaperCut NG's web based interface and storing data. In most cases where a cluster is involved the primary server will not host any printers and is dedicated to the role of hosting the PaperCut Application Server. If it is not running fine now, adding an extra server will only "add an extra variable to the equation" and complicate troubleshooting. Take some time now to verify that the primary server is functioning correctly. For example, verify that:
• Install and configuration is completed
• Administrators can access the system via a web browser for administration.
• Users can log into the user web interface from their workstations.
26.6.1.2. Step 2 - Ensure firewall allows access to port 9191
Cluster nodes needs to communicate (initiate a TCP connection) with the primary PaperCut server on port 9191.
Administrators should ensure that any firewall software on the primary application server is not set to block any incoming local network traffic on this port. A good way to test is to open a browser on the planned cluster nodes and confirm you can access the administration web interface on port 9191.
26.6.1.3. Step 3 - Create eDirectory user account
The papercut user's home directory denotes the application install location. For the fact that it is the default for
LUM enabled users,
/home/papercut is recommended, and assumed through the rest of this guide.
1.
In iManager open Users
→
Create User.
2.
For username, enter papercut
.
3.
For Last name enter
PaperCut LUM user
.
4.
For context choose the same eDirectory context as your the iPrint user and iprintgrp group created during your clustered iPrint installation.
5.
Assign the user a secret password during creation, and ensure the user's password is set to not expire. This may require associating the user with an appropriate password policy after creation if you are using eDirectory password policies.
6.
Click the tickbox next to Create home directory.
7.
For Volume choose the volume that is holding your clustered iPrint resource.
8.
For Path ensure that it reads papercut
.
9.
Click OK to create the user.
We now need to LUM enable this PaperCut eDirectory user and add it to the already LUM enabled iprintgrp used by the clustered iPrint resource.
1.
In iManager open Linux User Management
→
Enable Users for Linux.
467
Clustering and High Availability
2.
Select your papercut eDirectory user and continue.
3.
Select An Existing Linux-Enabled Group and choose the iprintgrp created during your clustered iPrint installation and press Next.
4.
Confirm that Workstation list includes all of the servers in your cluster and press next.
5.
On your clustered iPrint volume, navigate to the papercut user's NSS home folder
(
/media/nss/[volume]/papercut
) using for example Windows Explorer or ConsoleOne and add
RWECMF file rights for the eDirectory group iprintgrp created during your clustered iPrint installation. This ensures the iPrint services have access to the installed files.
6.
As root
, on each node that will run the iPrint resource, run the following command, replacing
[volume] with the volume name of your iPrint resource.
shell> ln -s /media/nss/[volume]/papercut /home/papercut
Note: The symlink target will only exist on the active node and will "dangle" on the other nodes ready for when it becomes the active node.
7.
To confirm all the above stages are working, using any method you like (such as the traditional Novell client for
Windows, logged in as an admin user), create a folder or test files inside the papercut folder on your iPrint cluster volume, then on the server holding that resource run: shell> su - papercut shell> ls
You should be able to see the files created on the NSS volume. They should also be able to be viewed via
/home/papercut on the active node.
26.6.1.4. Step 4 - Install the Print Provider
Important
The instructions below assume x64 architecture. If your system OS is 32-bit, replace x64 with i686 in all file paths.
Install the print provider software onto the secondary server by copying all files and directories from the primary application server's directory:
[app-path]/providers/print/linux-x64/* to the equivalent location on the node currently holding the iPrint resource:
/home/papercut/providers/print/linux-x64/
Perform the copy operation as the papercut user so that files are owned by the papercut user. You may use any method to copy the files, including over the network or via a USB key. If the primary server is also Linux, the simplest way would be to use secure copy ( scp
) as follows: shell> su - papercut shell> mkdir -p providers/print
468
Clustering and High Availability shell> cd providers/print shell> scp -r primary.server.name:/home/papercut/providers/print/* .
After the copy operation is performed, execute the setperms and roottasks scripts as root:
64bit shell> su - root shell> sh ~papercut/providers/print/linux-x64/setperms shell> sh ~papercut/providers/print/linux-x64/roottasks
32bit shell> su - root shell> sh ~papercut/providers/print/linux-i686/setperms shell> sh ~papercut/providers/print/linux-i686/roottasks
26.6.1.5. Step 5 - Configuration
The print provider on the cluster needs to know where the primary server is installed (i.e. its IP address). It also needs to correctly report the cluster name to the primary server.
1.
Open the file
/home/papercut/providers/print/linux-x64/print-provider.conf
in a text editor.
2.
Locate the line starting with
ApplicationServer= and change
127.0.0.1
to the hostname or IP address of the primary server.
3.
Locate the line starting with
ServerName=
, uncomment it and add the hostname of the cluster. This tells
PaperCut NG to report printers as being hosted on the cluster rather than on the node running the resource.
26.6.1.6. Step 6 - Cluster Configuration
1.
Configuring services
As the services are going to be managed by Novell clustering, the services on the physical nodes must be
→
System
→
System Services (Runlevel), disable papercut-event-monitor
.
2.
Installing services and disabling them on all other nodes
On each other node in the cluster perform the following steps: a.
As root run the following command ([resource-name] is the name for your iPrint resource, and
[node-name] is the server name of the node you are now working on): shell> cluster migrate [resource-name] [node-name] b.
Once the resource has successfully migrated run the following command (still as root): shell> /home/papercut/providers/print/linux-[arch]/roottasks shell> chown root:iprintgrp /opt/novell/iprint/bin/papercut c.
In YaST
→
System
→
System Services (Runlevel), disable papercut-event-monitor
.
d.
Repeat steps 1-3 on the other nodes in the cluster.
469
Clustering and High Availability
return here once completed.
26.6.1.7. Step 7 - Test
Mode 1 clustering should now be configured. Perform some test printing on all of this secondary server's printers.
Log into the PaperCut admin interface as admin and verify that the printers are now listed under the Printers tab.
Simulate a node failover and test again (wait a minute or two between failures for the new node to engage).
26.6.2. Mode 2 - Clustering at all application layers
This section assumes that you have an already installed and working clustered printing environment.
26.6.2.1. Step 1 - Prerequisites
This guide assumes you have iPrint up and working within an existing cluster. It is assumed the cluster is set up following Novell's documentation at http://www.novell.com/documentation/oes2/iprint_lx/?page=/documentation/oes2/iprint_lx/data/akujhhq.html.
Ensure the size of the shared disk partition and NSS Pools are sufficient for your print manager, driver store, and
PaperCut installation. This may mean making it larger than Novell's recommended 20GB if you are intending to use the internal database and store large amounts of data over time.
26.6.2.2. Step 2 – Create eDirectory user account
The papercut user's home directory denotes the application install location. For the fact that it is the default for
LUM enabled users,
/home/papercut is recommended, and assumed through the rest of this guide.
1.
In iManager open Users
→
Create User.
2.
For username, enter papercut
.
3.
For Last name enter
PaperCut LUM user
.
4.
For context choose the same eDirectory context as your the iPrint user and iprintgrp group created during your clustered iPrint installation.
5.
Assign the user a secret password during creation, and ensure the user's password is set to not expire. This may require associating the user with an appropriate password policy after creation if you are using eDirectory password policies.
6.
Click the tickbox next to Create home directory.
7.
For Volume choose the volume that is holding your clustered iPrint resource.
8.
For Path ensure that it reads papercut
.
9.
Click OK to create the user.
We now need to LUM enable this PaperCut eDirectory user and add it to the already LUM enabled iprintgrp used by the clustered iPrint resource.
1.
In iManager open Linux User Management
→
Enable Users for Linux.
2.
Select your papercut eDirectory user and continue.
3.
Select An Existing Linux-Enabled Group and choose the iprintgrp created during your clustered iPrint installation and press Next.
4.
Confirm that Workstation list includes all of the servers in your cluster and press next.
5.
On your clustered iPrint volume, navigate to the papercut user's NSS home folder
(
/media/nss/[volume]/papercut
) using for example Windows Explorer or ConsoleOne and add
RWECMF file rights for the eDirectory group iprintgrp created during your clustered iPrint installation. This ensures the iPrint services have access to the installed files.
470
Clustering and High Availability
6.
As root
, on each node that will run the iPrint resource, run the following command, replacing
[volume] with the volume name of your iPrint resource.
shell> ln -s /media/nss/[volume]/papercut /home/papercut
Note: The symlink target will only exist on the active node and will "dangle" on the other nodes ready for when it becomes the active node.
7.
To confirm all the above stages are working, using any method you like (such as the traditional Novell client for
Windows, logged in as an admin user), create a folder or test files inside the papercut folder on your iPrint cluster volume, then on the server holding that resource run: shell> su - papercut shell> ls
You should be able to see the files created on the NSS volume.
26.6.2.3. Downloading and installing
On the node that is currently hosting the iPrint resource, perform a primary server PaperCut installation as per steps
3 and 4 in Section 2.3, “Installation on Novell OES Linux (iPrint)”.
Important
Ensure this only done on the node that is currently holding the iPrint/PaperCut resource.
26.6.2.4. Step 4 - Installing services
1.
As the services are going to be managed by Novell clustering, the services on the physical nodes must be
→
System
→
System Services (Runlevel), disable both papercut and papercut-event-monitor
.
2.
Installing services and disabling them on all other nodes
On each other node in the cluster perform the following steps: a.
As root run the following command ([resource-name] is the name for your iPrint resource, and
[node-name] is the server name of the node you are now working on): shell> cluster migrate [resource-name] [node-name] b.
Once the resource has successfully migrated run the following two commands (still as root): shell> /home/papercut/server/bin/linux-[arch]/roottasks shell> /home/papercut/providers/print/linux-[arch]/roottasks shell> chown root:iprintgrp /opt/novell/iprint/bin/papercut c.
In
YaST
→
System
→
System Services
(Runlevel), disable both papercut and papercut-event-monitor
.
d.
Repeat steps 1-3 on the other nodes in the cluster.
471
Clustering and High Availability
26.6.2.5. Step 5 - File permissions
root
: shell> chown root:iprintgrp /opt/novell/iprint/bin/papercut
26.6.2.6. Step 6 - Configure the nodes to report the virtual server hostname
Note
This step only has to be completed on whichever node is currently holding the iPrint resource, as the print provider config file is on the portable volume and will automatically be picked up when the resource moves.
1.
Open the file
/home/papercut/providers/print/linux-x64/print-provider.conf
in a text editor.
2.
Locate the line starting with
ServerName=
, uncomment it and add the hostname of the cluster. This tells
PaperCut NG to report printers as being hosted on the cluster rather than on the node running the resource.
26.6.2.7. Step 7 – Update iPrint cluster resource scripts to load/unload the PaperCut application server
1.
In iManager
→
Clusters
→
Cluster Options open the cluster hosting your iPrint resource.
2.
Click on the iPrint resource, then Scripts.
3.
This screen displays the load script, which should something like the following:
#!/bin/bash
. /opt/novell/ncs/lib/ncsfuncs exit_on_error nss /poolact=IPRINT exit_on_error ncpcon mount IPRINT=250 exit_on_error add_secondary_ipaddress 10.10.55.7
exit_on_error ncpcon bind --ncpservername=FPCL_IPRINT_SERVER --ipaddress=10.10.55.7
ignore_error mv /media/nss/IPRINT/var/opt/novell/iprint/iprintgw.lpr /media/nss/IPRINT/var/opt/novell/iprint/iprintgw.lpr.bak
exit_on_error rcnovell-idsd start exit_on_error rcnovell-ipsmd start exit 0
4.
Add the following line between exit_on_error rcnovell-ipsmd start and exit 0
: exit_on_error /etc/init.d/papercut start exit_on_error /etc/init.d/papercut-event-monitor start
5.
Click Apply, then Unload Script. The unload script should look something like the following:
#!/bin/bash
. /opt/novell/ncs/lib/ncsfuncs ignore_error rcnovell-ipsmd stop ignore_error rcnovell-idsd stop ignore_error ncpcon unbind --ncpservername=FPCL_IPRINT_SERVER --ipaddress=10.10.55.7
ignore_error del_secondary_ipaddress 10.10.55.7
ignore_error nss /pooldeact=IPRINT exit 0
472
Clustering and High Availability
6.
Insert the following two lines between
.
/opt/novell/ncs/lib/ncsfuncs and ignore_error rcnovell-ipsmd stop
: ignore_error /etc/init.d/papercut-event-monitor stop ignore_error /etc/init.d/papercut stop
7.
Click Apply, then offline and online the iPrint resource to load it with these new scripts.
26.6.2.8. Step 8 - Config files
will have been automatically detected and stored in config files to simplify the deployment of remote components.
These config files will require modification so that the components connect to the cluster / virtual server resource instead.
Update the server IP address and hostname to the cluster / virtual server resource in the following configuration files:
• /home/papercut/client/win/client.properties
• /home/papercut/client/mac/PCClient.app/Contents/Resources/config
• /home/papercut/release/connection.properties
• client-config.js in each Gadget in /home/papercut/client/win/
• /home/papercut/client/mac/Widget/PCWidget/config
• /providers/net/connection.properties
• /providers/hardware/ricoh/*/connection.properties
As these config files are all on the shared resource they only need to be changed once on the node currently hosting the resource.
26.6.2.9. Step 9 - Printer / iPrint configuration
Each printer in the cluster that will be managed/tracked by PaperCut needs further configuration via iManager.
(iPrint)” and return here once completed.
26.6.2.10. Step 10 – Test
Mode 2 clustering should now be configured. Perform some test printing on all of this secondary server's printers.
Log into the PaperCut admin interface as admin and verify that the printers are now listed under the Printers tab.
Simulate a node failover and test again (wait a minute or two between failures for the new node to engage).
26.6.2.11. Step 11 – Sharing Client Software
As the clustered solution uses NSS, the client folder is already available as an NCP share at
\\[cluster-virtual-server]\[volume-name]\papercut\client
. Users should be able to access this folder once they are given file rights. Alternatively, consider making these files available via an alternate share/path/location.
26.7. Client/Workstation Configuration
In a clustered environment the behavior of PaperCut NG on the workstations is identical to that of a non-clustered environment. The one exception however is in terms of configuration - The clients need to be configured to connect to the Virtual Server rather that directly connecting to a node (i.e. network connections need to be made via virtual server's designated IP address). The changes necessary are:
1.
Update User Client's configuration file config.properties
with the Virtual Server's details as per
473
Clustering and High Availability
Section 26.2.2.10, “Step 10 - Client Configuration”.
2.
Ensure that any URL's pointing to PaperCut NG's web administration and user interfaces; http://[server]:9192/admin and http://[server]:9192/user user the virtual server's name. For example, any links on the organization's intranet site or links supplied to other system administrators.
474
Chapter 27. PaperCut NG on Linux
Information in this chapter is technical in nature. It is expected that readers have prior experience with:
• The Unix command line environment
• Unix file permissions
• Configuring CUPS and/or Linux print queues
• Or basic Samba configuration
27.1. The Installation Process
The Linux version of PaperCut NG is supplied as a pre-compiled self-installing application. The installation process is designed to work with all major Linux distributions. Due to the varied nature of some installations and administrator preferences, often some manual configuration is required. This section describes the installation process in detail as well as some additional options available to system administrators.
27.1.1. Manual extraction
The Linux version of PaperCut NG is supplied in a self-extracting, self-installing archive. The archive is simply a tar archive compressed with gzip
, and headed with a shell script to facilitate self-extracting. After extraction is complete, the installation script named install is executed to begin the install process. Some system administrators may like to inspect the contents of the archive, and possibly the installation process itself prior to the actual install. The self-extracting installer takes a number of command line arguments. The
-e argument will extract the archive into the current working directory ready for inspection. Further options and documentation is available via the
--help option.
Usage: pcng-setup.sh [-e|-i|-l] [-v] [-n] [list ...]
-e Extract the files and then exit without installing.
-i
-l
Install after extracting the files (default).
List the contents of the archive and exit without extracting.
-v list
Verbose. Print the names of the files as they are extracted.
The list of files to extract."
27.1.2. The install process
Even though the majority of the installation process is completed under the identity of the non-privileged user account called papercut
, most administrators would like to know what the install process does. The main steps are outlined below:
27.1.2.1. Extraction
The first stage in the install process extracts the archive to
/tmp or a location as defined by an environment variable
TMPDIR
. The command-line programs tar and gunzip are used during this phase.
27.1.2.2. Installation
After extraction is complete the installation script is called. The install script, called install
, will present the EULA and request acceptance. The script then determines the install location. This is the papercut user's home directory. The home directory is determined by the
HOME environment variable, or if not set, the result of a call to getpwnam()
.
475
PaperCut NG on Linux
Files are then copied into the papercut user's home directory. Care is taken not to overwrite any existing data or configuration files if this is an install-over-the-top upgrade.
27.1.2.3. Permissions
To ensure the default installation is secure by default, permissions are applied to key files. The following area of the application are restricted to the papercut user only:
Area
~/server/server.properties
~/server/data
~/server/bin/linux-[x64|i686]
Comments
Contains server configuration including the default admin password.
This directory contains application data including database files. Some of this data may contain sensitive information.
This directory contains a setuid-root binary. Even though the binary is no use to an end-user or hacker, good security practice stipulates that we should only allow the papercut user access to this directory.
Table 27.1. Secured Application Areas
Permissions can be checked and re-applied at any time post-install by running the scripts:
~/server/bin/linux-*/setperms
~/providers/print/linux-*/setperms
27.1.2.4. Firewall
The PaperCut NG Application Server ( pc-app process) listens on port 9191. This port is used for browser based administration access, for client access, and other services. Ensure that any firewall or local IP filtering software such as iptables is set to allow local network traffic access to this port.
27.1.2.5. Root Level Tasks
A small part of the install process needs to run as the root account. The tasks conducted as root include:
• Setting the authpam binary as setuid-root. This binary is used for password verification.
• Installing a CUPS backend. This is done by placing a symlink in the CUPS lib/backend directory.
• Setting up SYSV style start scripts if the system uses this boot process. This is done by placing symlinks in the:
/etc/init.d/
/etc/rc3.d/
/etc/rc5.d/ and so on...
If the administrator decides not to run the root-level tasks during the install process, the tasks can be run again post-install by executing the shell scripts:
~/server/bin/linux-*/roottasks
~/providers/print/linux-*/roottasks
Alternatively the administrator can view the scripts and make the required changes by hand.
27.1.3. Linux Print Queue Integration
476
PaperCut NG on Linux
PaperCut NG is able to integrate with and monitor CUPS, Samba and Novell iPrint based print queues. The configuration and an explanation of the integration methods follows:
27.1.3.1. CUPS Configuration Overview
If the print queues are managed and controlled via CUPS, the Device URI on each printer should be modified so the papercut backend is incorporated into the print process. This can be done automatically by running the configure-cups script as root
(the simplest option):
~/providers/print/linux-*/configure-cups and following the interactive instructions. Alternatively, it can be done manually via the CUPS web admin interface or by editing the CUPS printers.conf
file:
1.
Open printers.conf
(e.g.
/etc/cups/printers.conf
)
2.
Prefix the DeviceURL for each printers with " papercut:
". For example:
DeviceURI socket://192.168.1.200:9100
Would become:
DeviceURI papercut:socket://192.168.1.200:9100
3.
Restart cupsd so the new configuration is detected (e.g.
/etc/init.d/cupsd reload
)
27.1.3.2. CUPS Integration Explained
CUPS, the Common UNIX Printing System, is a popular system for managing printers on Linux servers. CUPS uses a chain-of-commands concept where filters and backends combine together to form a process steam - a workflow. PaperCut NG hooks into this workflow at the backend level, intercepting the job before it's passed on to physical printer hardware.
The interception is done by wrapping or proxying the real CUPS backend
. CUPS calls the PaperCut NG backend which processes the job. If the job is approved, it passes the document onto the real backend. If the job is denied, it is deleted and proceeds no further. The PaperCut NG backend is usually set up and installed by default during the standard installation.
Setting up the PaperCut NG CUPS backend proxy is a relatively simple task. All the administrator needs to do is prefix the existing
DeviceURI with papercut:
. For example the entry:
DeviceURI socket://192.168.1.200:9100 would become:
DeviceURI papercut:socket://192.168.1.200:9100
The printer will register itself with PaperCut NG on the first print event.
27.1.3.2.1. PaperCut NG CUPS Architecture
The PaperCut NG CUPS backend is a native compiled binary. In PaperCut NG documentation it is referred to it as a
Print Provider - a component that provides print event information to the Application Server. It's responsible for
477
PaperCut NG on Linux analyzing the print job and then communicating this information to the Application Server component.
Communication is via an XML-RPC based Web Services call. This means that the backend does not even need to be on the same server as the system hosting the Application Server component.
27.1.3.3. Samba Configuration Overview
If the print queues are exposed to network workstations using Samba (Samba Website) [http://www.samba.org/], and a print system other than CUPS is used (e.g. BSD, LPRNG, SYSV, etc.) the smb.conf
needs some additional configuration. The " print command
" needs to be replaced with a PaperCut NG command.
1.
Open the smb.conf
(e.g.
/etc/samba/smb.conf
)
2.
Under the
[global] section insert the line: print command=/home/papercut/providers/print/linux-i686/samba-print-provider
-u "%u" -J "%J" -h "%h" -m "%m" -p "%p" -s "%s"
-a "[standard print command]" &
(IMPORTANT: The above information should appear all on a single line. Note the use of the & (ampersand) on the end of the line.) where
[standard print command] is the command that would normally called for printing. Typical examples of commands usually used for printer are listed below:
Type
BSD, AIX, QNX, LPRNG or PLP
SYSV or HPUX
Table 27.2. Standard print commands
Command
lpr -r -P%p %s lp -c -d%p %s; rm %s
More information on standard print commands is available under the Samba documentation installed on your system (see man smb.conf
).
27.1.3.4. Samba Integration Explained
Samba is used to provide file and print sharing to Windows systems and is a popular solution. One of the main reasons for its popularity is that it avoids the need for expensive Microsoft Windows server licenses!
Samba exposes the locally set up Linux/Unix printers as network shared Windows printers. It does this by wrapping the underlying print system - usually CUPS or LPR/LPD. In the case of LPR, Samba calls the standard lp command line programs to perform printing. PaperCut NG works by wrapping or proxying the " print command
". More information on how Samba interacts with the underlying print system is available in the Samba documentation.
A typical entry in the Samba configuration file smb.conf
defining the PaperCut NG print command wrapper would be: print command=/home/papercut/providers/print/linux-i686/samba-print-provider
-u "%u" -J "%J" -h "%h" -m "%m" -p "%p" -s "%s"
-a "[standard print command]" &
(IMPORTANT: The above information should appear all on the one line.
Note the use of the & (ampersand) on the end of the line.) where
[standard print command] is the command that would normally be called for printing.
The
%u
,
%p
, etc., are Samba substitution variables. These are replaced with content such as the username, printer name, etc. and are used by PaperCut NG in the reporting and logging.
478
PaperCut NG on Linux
The printer will register itself with the PaperCut NG web interface after the first print is received.
27.1.3.4.1. PaperCut NG Samba Architecture
The PaperCut NG Samba print command wrapper is a native compiled executable. The PaperCut NG documentation refers to it as a Print Provider. It's responsible for analyzing the print job and then communicating this information to the Application Server component. Communication is via an XML-RPC based Web Services call. This means that the command does not even need to be on the same server as the system hosting the Application
Server component.
27.1.3.5. Novell iPrint Configuration
PaperCut NG works by directly integrating with the Novell iPrint Print Manager. The configuration process is detailed
with the Novell iPrint engineers during 2008 to ensure an iPrint API was available that allow iPrint users to have access to the same feature set as seen on Windows, Mac and Linux CUPS. PaperCut NG uses this API set to intercept and account for jobs as they pass into the iPrint queue.
27.2. Advanced Configuration & Logs
The majority of PaperCut NG configuration is conducted in the Application Server's web interface. Some additional configuration options are available in the following configuration files:
Config File
~/server/server.properties
~/providers/print/linux-[x64|i686]/print-provider.conf
Comments
Contains server configuration including the default admin password, the server's
TCP port and external database connection parameters.
The Print Provider's configuration file used by both the Samba and CUPS Print
Providers. This file defines items such as the Application Server's IP address and port, process timeouts and other.
Table 27.3. Advanced Configuration
27.2.1. Advanced Logging
Most important application logging is available via the Application Log section of the Application Server's web interface. Some additional advanced level logging is maintained in standard text files located at:
~/server/logs/*
~/providers/print/linux-[x64|i686]/print-provider.log
Administrators may wish to consult these logs when attempting to diagnose or troubleshoot problems.
27.2.2. Maintain correct user name when print jobs are redirected on CUPS
When print jobs on CUPS are redirected to a second print queue the job appears to come from a user account called lp
. Note that the job is still correctly tracked against the user and the approriate accounts are charged as needed. However some users may be confused when their jobs appear to be printed by another user at the device.
Administrators can edit the file
~/providers/print/linux-[x64|i686]/print-provider.conf
and uncomment the
RedirectCommand entry. This forces PaperCut NG to pass the user's name to the CUPS subsystem on redirection. This is not the default behaviour as it can cause authentication problems, depending on how your network printer queues are configured, and you should verifty that users can still print after making this change.
27.3. Backups & System Management
Suggested backup procedures are detailed in Section 15.5, “System Backups”. Common system management
functions are covered in Chapter 15, System Management.
479
PaperCut NG on Linux
Administrators managing Linux servers should also consider adopting the following management policies:
• Regularly check for PaperCut NG updates. Updates can be applied with a simple, install-over-the-top procedure.
• Remember to add the PaperCut NG backend or command when configuring new printers.
• Always check PaperCut NG's functionality after a system updates (i.e. new versions of CUPS or Samba, or configuration changes).
27.4. User Directory and Authentication
PaperCut NG synchronizes its user directory with the underlying operating system or network. The Linux version of
PaperCut NG ships with two user directory implementations. Due to the nature of Linux, some organizations may have customized user directory implementations. PaperCut NG can support customization in this area. This section details the user/group/authentication options available as standard, as well has how one would go about developing customized implementation.
27.4.1. Standard Unix
The Standard Unix user directory provider uses standard Unix API's to enumerate user and group information. This allows group information to be defined on either the local system or via another source as configured via nsswitch.conf
. For example, the system may be configured via nsswitch.conf
to obtain user directory information from a centralized LDAP server or Novell's eDirectory.
User password authentication is performed via PAM. (Note: For administrators wishing to customize the PAM authentication method at the application level, PaperCut NG reports itself as "papercut".)
27.4.2. Samba/Windows Domain
If the user and group information is provided by a Windows Domain such as an NT Style Domain or Active Directory, the Samba option is most appropriate. This option would normally be used on networks where the printers are hosted on a Linux server and exposed to Windows users via Samba. The server needs Samba installed and configured, but does not need to be a member of the domain.
At the technical level, the Samba support is implemented as a set of Perl script wrappers around standard Samba commands such as net and smbclient
. Administrators should ensure these Samba commands are on the papercut user's path.
The wrapper script can be found in
[app-path]/server/bin/[arch]/sambauserdir
.
27.4.3. Custom
Some large networks, particularly those found at established universities, may have custom user directory and authentication services not directly supported by PaperCut NG. To support these networks, administrators can use scripting and other technologies to build a new custom User Directory Information Provider.
PaperCut NG works by handing off user, group and user authentication tasks to a separate program/process. The external process must accept a set of commands as command-line arguments and return the answer in a tab
Information Provider are also supplied as part of the installation, and these may prove to be a good example. The source code is provided in:
~/server/examples/providers/
Organizations wishing to build a custom User Directory Information Provider are encouraged to contact the
PaperCut NG development team. They will be more than happy to assist.
27.5. Unix Command-Line Release Station Client
480
PaperCut NG on Linux
In a modern Linux environment, the most commonly used print system is usually CUPS. PaperCut NG can be configured to integrate with CUPS to conveniently track printing. On Legacy Unix systems CUPS is often not an option and printing is performed via the Line Printer tools such as lp or lpr
. LPR/LPD is a non-authenticated printing protocol so the identity of the user associated with a print job can't be trusted. Instead, the authentication must be performed at the PaperCut NG application layer. The PaperCut NG client tool with popup authentication as
appropriate for a terminal-only environment. Terminal-only environments can be supported via a release station
station queue are normally accessed and released via a dedicated terminal or a web browser based interface, however for the benefit of terminal-only users, a command-line job release client is also provided.
This process is best explained using an example:
1.
John uses the lp command to print a Postscript document from his Unix terminal session. The job arrives in the queue under the username identity "john". (Although the name can't be trusted.)
2.
The administrator has enabled the PaperCut NG release station on this print queue. The job is placed into a holding state.
3.
John must now authenticate, proving his identity and release the job. He chooses to do this via the command-line release station client.
4.
John enters the command release-print-job
. This command was set up by the system administrator.
5.
John enters his username and password, confirms the job's name, cost and page count and releases the job for print. The following is an example of the output seen:
Please enter your username: john
Please enter your password:
Current balance: $8.00
18:04:13 - Name: "Configuring Linux", Pages: 2, Cost: $0.40
Print this job? [yes]
Released 1 job(s).
6.
The job prints and John's account is charged.
Enabling the release station on a printer is a global option - it affects all jobs from all users. In some environments it may not be appropriate to have all jobs controlled via a release station - for example, jobs originating from Windows systems are already authenticated and should print directly. An alternate strategy is to have two queues for the same printer. The first queue does not use the release station option and only allows printing from authenticated workstations/users, while the other queue has the release station option enabled.
PaperCut NG managed print queues can be exposed for access via LRP/LPD using various methods. The optional
Windows system component, "Print Services for Unix" can be used if the queues are hosted on a Windows system.
An LPD interface is available for CUPS if the queues are hosted on Linux.
Tip
Windows system administrators can control which queues are exposed via LPR/LPD by setting printer permissions. Queues set up to explicitly deny permission to access from the SYSTEM account will not be accessible via LPR.
27.5.1. Installing the Command-Line Release Station Client
The following installation instructions assume the reader has prior Unix system administration experience.
1.
Ensure that Java 1.5 or newer is installed on your system. To check, type java -version at the terminal. If you do not have Java 5 (1.5) or higher, please install it before continuing. Java is available for all major Unix operating systems.
481
PaperCut NG on Linux
2.
Copy the release station files from your primary server to the system for which you wish to set up the command line release station client. These can be found in
[app-path]/release
. If your primary server is running
Windows, this folder will be shared by default (accessible via smb://[server]/release
). You may be able to use tools such as Samba ( smbclient
) to help copy these files. Ensure all files in the folder are copied taking care to preserve the existing heirarchy.
The recommended location to install the release station command line client is
/usr/local/papercut/release/
.
3.
Ensure that the command line release station client has execute permissions for all users. This can be achieved with the following command when in the release directory: chmod 755 ./pc-release-cmd-line.sh
4.
For convenience, an alias can be created for the command line release station client. This is typically done by entering the following line in a global profiles file, or each user's
.profile
file: alias "release-print-job" = \
"/usr/local/papercut/release/pc-release-cmd-line.sh
5.
Users will now be able to release their print jobs by typing release-print-job
.
It may also be useful to create a 'wrapper' for lp to run the command line release station client after a user has sent a print job. The following script print-doc provides an example:
#!/bin/sh echo "Printing document using lpr..."
/usr/bin/lpr "$@" echo "Printing done, calling program to release job..." sleep 1 cd /usr/local/papercut/release
./pc-release-cmd-line.sh
echo "Done."
For the convenience of users, the command line release station client should be installed on all systems where printing from the terminal may be performed.
27.6. Removing PaperCut NG from a Linux server
PaperCut NG can be completely removed from a system with the following procedure:
• Remove all files from the papercut user's home directory.
• Remove the papercut user account and home directory.
• Remove any server start scripts matching:
/etc/init.d/papercut
/etc/rc*.d/*papercut
27.7. Linux FAQ
27.7.1. Troubleshooting & Installation Questions
482
PaperCut NG on Linux
Q:
How can I run the root installation tasks manually?
A:
If you opt not to run the root level tasks during installation, or if they fail, they can be manually run later by running the following shell scripts as root:
~/server/bin/linux-*/roottasks
~/providers/print/linux-*/roottasks
Q:
I am unable to open a browser to http://[server_name]:9191/admin
. What is wrong?
A:
The first step is to check to see if the PaperCut NG is listening on the port. The command: netstat -anp | grep 9191 should list the pc-app as the owner of the process on port 9191. If nothing is listed, check that the application server has started (e.g.
ps -ef | grep pc-app
).
If the server is already running, the next step is to ensure no IP filtering is applied to the port. Some Linux distributions have strict iptables filters enabled by default. Ensure that port 9191 is accessible from all local network systems.
Q:
I would like to use a custom script to start the server. Is this possible?
A:
Q:
Can I run/install PaperCut NG under an account other than "papercut"?
A:
The SYSV style start script included should work with all systems using an
/etc/rc*.d
style boot process.
Some administrators may wish to replace the app-server with a custom script that better fits in with their
Linux distributions style guide. Administrators should consider storing this script outside the PaperCut NG install structure so it's not overwritten in any further upgrade.
No. At the moment the installation, and other scripts, assume the existence of a user called papercut
. This may however change in the future. E-mail your thoughts to the development team!
Q:
Is an RPM or .deb package available?
A:
No. At the moment we're supplying it as a self-extracting and self-installing archive. This gives us the flexibility to support install-over-the-top for upgrades and maintain full control over the installation process. The process will also allow PaperCut NG to run and install on systems not using RPM or apt. We also plan on supporting other Unix based operating systems in the future such as FreeBSD and Solaris. The current installation method should work with all standard Linux distributions.
27.7.2. General Questions
Q:
Is PaperCut NG open source?
A:
PaperCut NG in not "open source" in reference to it being available under the GPL or another popular open source license. Source code is however provided to customers. As a company we are transparent in our development approach, work closely with our users, and support a number of open source projects both financially and with code submission. PaperCut NG however remains a commercial application with commercial support at the current time.
483
Chapter 28. Print Authentication
Modern large multiuser networks, like those typically seen in Higher Education, are made up of mix of operating systems, authentication methods, personal student laptops, print protocols and disparate networks. This heterogeneous mix poses problems for system administrators working towards a unified and centralized print management system. PaperCut NG sports an array of tools to help administrators meet their unification goals.
PaperCut NG's flexibility is however a double-edged sword and the multitude of options also bring complexity. This section discusses cross-platform support in detail, and hopes to arm the reader with the knowledge needed to make the correct architecture decisions. Solutions are presented as "recipes" with the aim of directing the reader to appropriate procedures and other chapters.
The objective of a centralized and unified PaperCut NG system is to offer all users, irrespective of their operating system or access method, access to the full array of features in a secured and authenticated way. PaperCut NG offers cross-platform client software providing end-user features on all major operating systems, however the need for secured and authenticated access adds an extra, somewhat complex dimension.
28.1. About Authentication and Printing
28.1.1. What is authentication?
Authentication in a printing environment is the act of confirming the digital identity of the person who issued a print job. Knowledge of the user's identity allows PaperCut NG to offer the user access to functions such as allocating the cost of a job to their account, or offering them access to shared accounts. In a Windows domain environment, authentication is handled at the point of login using a username and password. A web-of-trust is then established between servers and services.
28.1.2. Why does authentication pose a problem?
By default PaperCut NG assumes the printer queues are authenticated and trusts the username that is associated with the print job. It is this user is charged for for the printing. On fully authenticated networks (like 100% Windows
Active Directory networks), PaperCut NG can trust the username associated with the job. There are a few common scenarios where authentication is not as simple:
1.
Generic, common, or shared user accounts. (e.g. generic "student" login).
2.
Systems that auto-login as a set user.
3.
Unauthenticated print queues or print protocols (e.g. LPR).
4.
Users' personal laptops that are not authenticated on the network.
Generic or shared login accounts are seen in some computer lab and network environments. In these environments administrators ask users to log into selected systems using standard user names such as "student" or "user". This practice is particularly common on the Apple Mac operating system as a single login helps streamline system and application management. The use of the Window auto-login feature also poses a similar problem - authentication is not enforced at the time of system startup. An extra layer of authentication is required on these systems to correctly identify the person that performs printing.
Unauthenticated print queues also pose problems in cross platform environments. In an ideal world all computers would talk the same protocols and happily work together in a single centrally authenticated environment. We can come close to this goal in a 100% Microsoft Windows environment, however if we mix in Unix, Linux and Mac, it's a different story. Although initiatives such as CUPS (Common Unix Printing System) and the Internet Printing Protocol
(IPP) offer some hope, unification in the area of authenticated printing is still some way off. Unfortunately technical reasons often prevent networks from using CUPS authentication or exclusively using the authenticated Microsoft printing protocol.
The use of personal laptops or other unauthenticated workstations in an otherwise authenticated network is another cause of problems. These machines may not be able to authenticate to your network for number of reasons:
• The operating system does not support authentication (like Windows Home editions).
484
Print Authentication
• It is too complex to configure authentication on personal laptops.
• Users log in to their laptop with their personnally chosen username and password.
• You cannot force users to change the configuration of their personal laptops.
28.1.3. How does PaperCut NG address authentication?
If technical reasons prevent authentication at the print queue level, PaperCut NG provides a number of alternate authentication options. These options change PaperCut NG's default behavior of trusting the username associated with a print jobs, and instead the user will be required to re-authenticate before the job is printed. The two alternate authentication options are described below.
28.1.3.1. Popup Authentication (IP session based authentication)
This method involves associating the workstation's IP address with a user for a specified period of time - a session.
Any print jobs arriving from this IP address are deemed to be associated with this user. Authentication is provided by the PaperCut NG client software in the form of a popup dialog requesting a username and password. Data is transmitted to the server via an SSL encrypted connection. To print with popup authentication the client software must be running on the workstations or laptops.
Popup authentication can be used to:
• Authenticate users that print from a generic login or auto-login account. This is done by flagging the generic account as unauthenticated in PaperCut NG.
• Authenticate users not authenticated to the network (e.g. personal laptop users). This is done by marking the print queues as unauthenticated in PaperCut NG.
Figure 28.1. PaperCut NG client requesting authentication
More information on popup authentication can be found in Section 7.10, “Popup Authentication”.
28.1.3.2. Web Print
Web Print is a service for printing documents that are uploaded via a web browser. This provides a simple way to enable printing for laptop, wireless and anonymous users without the need to install print drivers.
With Web Print users are authenticated when they log into the PaperCut NG user web interface. Any documents they upload can then be tracked against their user name.
28.1.3.3. Release Station Authentication
Release stations work by placing print jobs in a holding queue. Users must authenticate at a release station before
485
Print Authentication being given access to release their job. A release station normally takes the form of a dedicated terminal located next to the printer(s), however the holding queue may also be accessed via a web browser. The act of a user releasing a job causes it to be charged to their account. Release stations can be used without installing the client software on user's workstations.
The hold/release queues are enabled on a printer queue level within PaperCut NG
Release Stations. To achieve authentication, the Release Station will be run in "release any" mode.
28.1.3.4. Choosing the right authentication option for your network
The choice of the authentication approach depends on the constraints of your network and your requirements.
Below are some points to consider when making this decision:
• Popup Authentication: Usually the most user-friendly option, but it requires the client software to be installed and running on all workstations that print. In some environments it is not possible to mandate that software be installed on personal laptops.
• Release Station Authentication: Users do not need any additional software installed but the process of releasing
them for authentication.
28.1.3.5. Handling partially authenticated networks
Many sites have a heterogenous network with a mix of both authenticated an unauthenticated printing. A common example, is a college where all lab computers are connected to the domain and users must login to the workstations to print. The college also allows students to print using their personal laptops that are not authenticated on the network.
An administrator can choose to enable PaperCut NG authentication for all users. This is the simplest to set up but may be inconvenient for users who are already fully authenticated. Why should an authenticated user have to re-authenticate with PaperCut NG to print?
To overcome this it is recommended to set up two sets of print queues, one for the authenticated users and another for the unauthenticated users. These queues can point to the same physical printers, but are configured differently in both PaperCut NG and the operating system. The authenticated print queues:
• Must only be accessible to authenticated users (i.e. through network security or operating system permissions).
• Should not have the authentication enabled within PaperCut NG (i.e. do not enable the hold/release queue or unauthenticated printer options on the print queue).
• Should not be published to unauthenticated users.
The unauthenticated print queues:
• Must be configured to allow printing by unauthenticated users.
• Must have the authentication enabled within PaperCut NG. i.e. Enable the hold/release queue or flag the printer as unauthenticated.
• Must be published to anonymous users so they know how to connect/user the printers.
If the decision as been made to split up printers into two separate queues (authenticated and unauthenticated), administrators can use tools such as IP address filtering, firewalls, or user/group access permissions to control who has access to which set of queues (i.e. deny "guest" account access on authenticated queues in Windows).
“Handling Unauthenticated (non-domain) Laptops”
For discussion of many other authentication scenarios see Section 28.3, “The Authentication Cookbook - Recipes
486
Print Authentication
28.2. Handling Unauthenticated (non-domain) Laptops
Schools and colleges commonly allow students to use their personal laptops for printing to campus printers. They also want to allocate/charge printing from these unauthenticated users to the correct person. However if the systems haven't authenticated with the network, then user credentials are not provided with the print job (or worse, their personal laptop username is associated with the job). For example, on Windows networks, the jobs may list as guest
. PaperCut NG addresses this this problem by providing alternate print authentication options. This section provides a step-by-step guide to configuring these authentication options.
28.2.1. Option 1: Popup Authentication for Unauthenticated Laptops
Authentication” for a detailed explanation of the feature.
28.2.1.1. Step 1: Decide whether to enable popup authentication on all printer queues
First decide whether to enable authentication for all queues, or only the queues accessed by unauthenticated laptop
If you choose to only enable authentication for your unauthenticated laptops, you must configure a second set of unauthenticated print queues. These queues can point to the same physical printers as your authenticated queues.
Often the simplest way to set up these unauthenticated queues is to configure a separate print server that allows anonymous printing. You can make use of a firewall or operating system permissions to ensure that the anonymous users cannot access the "authenticated queues". On Windows networks, you may need to enable the guest account on the domain/system so users running the "Home" editions of Windows can print to these queues.
28.2.1.2. Step 2: Install/run the user client software on laptops
To use popup authentication, the client software must be installed and running on the unauthenticated laptops. You should make the client available for your users along with instructions of how to install the software on their laptops.
The software can be easily installed on all common operating systems (Windows, Mac and Linux).
28.2.1.3. Step 3: Mark the printer queue as "Unauthenticated"
By default PaperCut NG trusts the usernames that are associated with the print job. When printing from unauthenticated laptops this username cannot be trusted. By flagging the printer queue as "unauthenticated",
PaperCut NG will no longer trust the username and will prompt the user to authenticate.
Advanced: An alternate approach on Windows networks is to enable the unauthenticated option at the user-level on guest only rather than at the queue level.
To flag the printer as Unauthenticated:
1.
Log in as the built-in admin user.
2.
Click on the Printers section.
3.
Select the printer you wish to mark as Unauthenticated.
4.
In the Configuration section, enable the Unauthenticated printer checkbox.
5.
Press the OK button to save the changes.
6.
Repeat this process for each printer that requires popup authentication enabled.
487
Print Authentication
Important
Once the printer is flagged as Unauthenticated, no print jobs will be printed until the user has authenticated using the client software. It is important that all workstations using these print queues are running the client software.
28.2.1.4. Step 4: Test the popup authentication
It is important to test the popup authentication once enabled. To do this:
1.
Start-up an unauthenticated laptop/workstation.
2.
Ensure that the user client software is installed and running.
3.
Perform a test print job to the queue on the print server you flagged as Unauthenticated.
4.
The client software should popup the authentication dialog box. The print job should not print until you successfully authenticate.
5.
Once authenticated, verify that the print job completes and the job is logged against the correct username in
Printers->Print Jobs.
28.2.2. Option 2: Release Station Authentication for Unauthenticated Laptops
Queues & Print Release Stations for a detailed explanation of the feature.
28.2.2.1. Step 1: Decide whether to enable release station authentication on all print queues
First decide whether to enable the hold/release queue for all print queues, or only the queues accessed by
If you choose to only enable the hold/release queue for your unauthenticated laptops, you must configure a second set of unauthenticated print queues. These queues can point to the same physical printers as your authenticated queues.
Often the simplest way to set up these unauthenticated queues is to configure a separate print server that allows anonymous printing. You can make use of a firewall or operating system permissions to ensure that the anonymous users cannot access the "authenticated queues".
28.2.2.2. Step 2: Choose which Release Station interface to use
standard release station:
• Requires a dedicated workstation nearby the printers that is configured to run the release station.
• Requires less user education because when they walk up to fetch their print jobs it is obvious they need to use the release station to user the job.
The end-user web release station:
• Requires no workstations configured near the printers. Users simply use a web browser to login to the end-user web interface and release their jobs.
• Users must be provided with instructions on how to print and then login to the web release station to release their print jobs.
After choosing the release station interface, proceed to the appropriate step below.
488
Print Authentication
28.2.2.3. Step 3a: Run and configure the Standard Release Station
If using the standard release station:
1.
Station Configuration” for information on deploying the release station.
2.
Run the release station in "Release Any" mode which allows users to login and see all print jobs awaiting release. When they release a job it will be charged to their user account. For more information see
Section 13.3.3.1, “Release Station Modes”.
28.2.2.4. Step 3b: Enable and configure the End-user Web Release Station
If using the end-user web release station:
1.
Log in as the built-in admin user.
2.
Click on the Options section.
3.
In the User Features section, enable the Allow users to view held jobs (hold/release queues) option.
4.
Change the Users have permission to setting to Release any jobs (charge to their account).
5.
Press the Apply button to save the changes.
28.2.2.5. Step 4: Enable the Hold/Release queue for the print queues
By default, PaperCut NG allows the jobs to be printed without any interaction from the user. The hold/release queue feature will hold the print job until the user logs into a release station and releases the job. To enable the hold/release queue for a printer:
1.
Log in as the built-in admin user.
2.
Click on the Printers section.
3.
Select the printer you wish to enable the Hold/Release queue on.
4.
In the Configuration section, enable the Enable hold/release queue checkbox.
5.
Press the OK button to save the changes.
6.
Repeat this process for each printer that requires the hold/release queue enabled.
Important
Once the hold/release queue is enabled, no jobs will print until released using a release station. It is important to instruct your users how to use the release station, otherwise they will not be able to print.
28.2.2.6. Step 5: Test the release station
It is important to test the release station once enabled. To do this:
1.
Start-up an unauthenticated laptop/workstation.
2.
Perform a test print to a print queue with the hold/release queue enabled.
3.
For the standard release station, go to the print release station and login as a user. Select the job you printed and press the Print link to release the job. The job should begin to print.
4.
For the end-user web release station, login to the end-user web pages at http://yourserver:9191/user
.
Select the Jobs pending release link. Select the job you printed and press the [print] link to release the job.
The job should begin to print.
5.
Login to the PaperCut NG admin pages and verify the print job was allocated to the correct user in the
Printers->Print Jobs section.
489
Print Authentication
28.3. The Authentication Cookbook - Recipes by example
This section discusses various solutions to the "authentication problem" in recipe style. The aim is not to provide detailed step by step instructions, but rather guide the user to the relevant procedures and chapters in other parts of the manual.
28.3.1. Windows systems with generic logins
This scenario arises either when users log into systems using a common username such as user or student
, or if the workstations auto-login as a generic user. See introduction for details.
28.3.1.1. Preferred Method:
• Ensure all users have an account (username and password) on the server (or domain) hosting the PaperCut NG software.
•
Install client software on all systems. See Section 5.2, “User Client” for more detail.
• Enable popup authentication by selecting the Unauthenticated option on the corresponding generic user account.
•
See Section 7.10, “Popup Authentication” for more detail.
28.3.1.2. Other Methods:
1.
users to release any jobs. See Chapter 13, Hold/Release Queues & Print Release Stations.
2.
Consider implementing domain level logins.
28.3.2. Windows laptops that do not authenticate against a domain
Portable systems may spend most of their time outside the organization's network and hence setting up domain authentication may not be desirable. The laptops/notebooks are often owned by a single individual and are not under the control of a central administrator.
28.3.2.1. Preferred Method:
28.3.2.2. Alternate Method 1:
If using a version of Windows that can authenticate with a domain (i.e. not the Windows Home editions), then the laptop can be configured to authenticate with the network as follows.
• Teach the user how add their domain username and password to their Stored usernames and passwords:
1.
Start
→
Control Panel
→
User Accounts
2.
Select the user's laptop login account
3.
Click Manage my network passwords
4.
Click Add
5.
Enter the name of the server and the user's network domain username and password
• Teach the user how to add a network printer in the form
\\server\printer
.
• Optional: Locally install client software using the client-local-install.exe
install program. This is located on the
\\Server\PCClient\win share. At the end of the install process the client will open asking the user to
confirm their network identity. See Section 5.2, “User Client” for more detail.
490
Print Authentication
28.3.2.3. Alternate Method 2:
• Add a generic "LaptopUser", or "guest" user account to the domain. Make the password known to all users (e.g.
password
).
• Set the unauthenticated option on this user (enable popup authentication).
• Locally install client software using the client-local-install.exe
install program. This is located on the
\\Server\PCClient\win share. At the end of the install process the client will open asking the user to
confirm their network identity. See Section A.5, “User Client Options” for details.
• Teach the user how to add a network printer pointing to
\\server\printer
.
• See the preceding scenario for more detail.
28.3.3. Windows print server using LDAP or eDirectory authentication
The Microsoft Windows operating system does not play well in non Active Directory domain environments such as
LDAP or eDirectory. Although it is possible to configure a Windows print server on any network, Windows does not normally provide the ability to use LDAP as an authentication source. Jobs will either list under a local Windows user identity or a guest account. PaperCut NG's popup authentication, bound to LDAP, can be used to work around this limitation.
28.3.3.1. Preferred Method:
• Set up the Windows server and install and share printers.
• Set printer permission to allow printing from a general "guest" type account. This will usually take the form of the built-in guest account, or a local account with a known username and password (e.g.
printuser
).
• Configure printers on each workstation. Ensure all workstation users can print and jobs list in the print queue under the guest account configured in the previous step.
• Install the PaperCut NG software. Select the LDAP server as your user/group source. PaperCut NG will then use
more information about LDAP.
• Set the Unauthenticated option on each printer (print queue). This will enable popup authentication. See
Section 7.10, “Popup Authentication” for more information.
•
Install client software. See Section 5.2, “User Client” for more detail.
28.3.3.2. Other Methods:
1.
Use release station. See Chapter 13, Hold/Release Queues & Print Release Stations.
28.3.4. Mac OS X systems with generic user accounts
Mac OS X workstations in a lab environment are often set up so users log in using a common, generic, or standard account. For example, "macuser" or "student".
28.3.4.1. Preferred Method:
•
Install client software. See Section 5.2, “User Client” for more detail.
• Add a domain/network user account that matches the generic login account (i.e. "macuser"). This ensures that account will list in PaperCut NG.
• Set the Unauthenticated option on the "macuser" account.
• Add the printer(s) so jobs list under the "macuser" account. If the print queues are hosted on Windows, add the printer using Samba. (e.g. A
DeviceURI like smb://macuser:password@servername/printer
). See
Chapter 29, Mac Printing in Detail for an explanation on how to add a printer using this method.
491
Print Authentication
Tip
If you are running Mac OS 10.7, you may need to include the port in the DeviceURL: smb://username:password@server_name:139/printer_name
28.3.4.2. Other Methods:
1.
users to release any jobs. See Chapter 13, Hold/Release Queues & Print Release Stations.
2.
Consider setting up domain-level authentication.
28.3.5. Mac OS X systems using domain authentication via Open Directory
Mac systems can be configured to authenticate users via a central Mac OS X server running Open Directory. Each user has their own login account.
28.3.5.1. Preferred Method:
• Set up print queues on the Mac OS X Server.
• Set up PaperCut NG on the server either as a primary server, or as a secondary server reporting to another
primary server (either Mac, Linux or a Windows system). See Chapter 2, Installation.
• Add printers to each Mac workstation. Ensure the local printers point to the shared print queue set up on the server.
•
Optional: Install client software as discussed in Section 5.2, “User Client”.
28.3.5.2. Other Methods:
1.
users to release any jobs. See Chapter 13, Hold/Release Queues & Print Release Stations.
2.
Set up print queues on a Windows system and use popup authentication - see next recipe.
28.3.6. Mac OS X systems using domain authentication via Windows Active Directory
Mac systems can be configured so users log in using their Windows Active Directory domain username and password. The Mac Windows printer support using Samba/SMB however requires printers to be added using a single username and password and this is shared by all users. For this reason an extra layer of authentication is required.
28.3.6.1. Preferred Method:
• Host printers and the PaperCut NG system on the Windows server.
• Ensure the print server is running in Mixed mode or Pre-Windows 2000 Compatibility Mode. Macs currently have problems with
Native Mode networks.
• Add a domain/network user account that matches the generic login account (i.e. "macuser"). This ensures that the macuser account will appear in PaperCut NG's user list.
• In PaperCut NG, turn on the Unauthenticated option on the "macuser" account to enable popup authentication.
Also ensure that the account has zero balance and is restricted.
• Add the printer(s) so jobs list under the "macuser" account. If the print queues are hosted on Windows, add the printer using Samba. (e.g. A
DeviceURI like smb://macuser:password@servername/printer
). See
492
Print Authentication
Chapter 29, Mac Printing in Detail for an explanation on how to add a printer using this method.
Tip
If you are running Mac OS 10.7, you may need to include the port in the DeviceURL: smb://username:password@server_name:139/printer_name
•
Install client software as discussed in Section 5.2, “User Client”.
28.3.6.2. Other Methods:
1.
Directory authentication” in detail.
2.
users to release any jobs. See Chapter 13, Hold/Release Queues & Print Release Stations.
3.
Host printers on a Mac Server (see the previous recipe).
28.3.7. Mac OS X laptops (or single user systems) printing to Windows print queues
Mac systems that are owned/used by a single user can benefit from having the printers added in such a way in that they automatically authenticate under their identity.
28.3.7.1. Preferred Method:
•
•
28.3.7.2. Other Methods:
1.
Locally install client software using the client-local-install program located in the directory
[app-path]/client/mac
. This install script will cause the client to display a popup asking them to confirm their network identity (via username/password).
28.3.8. Linux Workstations in a lab environment with printers hosted on a Windows server
Linux workstations typically use the CUPS print system. CUPS, through the use of Samba, can print directly to
Windows print queues.
28.3.8.1. Preferred Method:
• Ensure the system is configured to deny remote shell access to standard users - that is, only allow direct screen/console access. This ensures the system's IP address can be associated with a single user providing a suitable environment for popup authentication.
• Ensure the print server is running in Mixed mode or Pre-Windows 2000 Compatibility Mode. Some Linux distributions currently have problems with
Native Mode networks.
• Add a domain/network user account that matches the generic login account (i.e. "linuxuser"). This ensures the
"linuxuser" account will appear PaperCut NG's user list.
• In PaperCut NG, turn on the Unauthenticated option on the "linuxuser" account to enable popup authentication.
Also ensure that the account has zero balance and is restricted.
493
Print Authentication
• Add the printer(s) so jobs list under the "linuxuser" account. If the print queues are hosted on Windows, add the printer using Samba. (e.g. A
DeviceURI like smb://linuxuser:password@servername/printer
). Please refer to the CUPS or distribution documentation to read more how to add a CUPS printer using an smb backend.
•
the workstations using a username that matches their Active Directory password, no additional client configuration is required. If users log in using a generic or non-matching account, use command-line options or the config.properties
file to force the client to display under the user's domain identity. See Section A.5,
“User Client Options” for more information.
28.3.8.2. Other Methods:
1.
users to release any jobs. See Chapter 13, Hold/Release Queues & Print Release Stations.
2.
Host printers on a CUPS server running on Linux.
3.
Install "Print Services for Unix on the Windows server" and use a LPR rather than CUPS (or CUPS with an LPR backend).
28.3.9. Linux Workstations in a lab environment with printers hosted on Linux CUPS server
Many network administrators running Linux labs may be most comfortable hosting the printers on a Linux server running CUPS. For convenience, CUPS is set up without authentication.
28.3.9.1. Preferred Method:
• Set up CUPS print queues on a Linux server.
• Ensure each user has an account on this system (or the domain depending on PaperCut NG's selected user list source)
• Set up PaperCut NG on the server either as a primary server, or as a secondary server reporting to another
primary server (either Mac, Linux or a Windows system). See Chapter 2, Installation.
• Set the Unauthenticated option on each printer (print queue). This will enable popup authentication. See
Section 7.10, “Popup Authentication”.
• Ensure the system is configured to deny remote shell access to standard users - that is, only allow direct screen/console access. This ensures the system's IP address can be associated with a single user providing a suitable environment for popup authentication.
•
Install client software as discussed in Section 5.2, “User Client”.
28.3.9.2. Other Methods:
1.
users to release any jobs. See Chapter 13, Hold/Release Queues & Print Release Stations.
2.
Use CUPS Authentication.
28.3.10. Linux laptops (or single user systems)
Modern Linux laptops will make use of the CUPS print system. This environment is equivalent to the Mac laptop recipes described above.
28.3.11. Multiuser Unix terminal servers
Unix or Linux systems allowing remote SSH, Telnet, VNC, or X connections differ from the other scenarios discussed above. These systems can not use the popup authentication as it is not possible to uniquely identify a user from the system's IP address. The only secure option is to use the release station.
494
Print Authentication
28.3.11.1. Preferred Method:
• Setup PaperCut NG on your preferred server - this does not need to be the multiuser terminal system itself. It could be another Windows or Linux server.
• Ensure PaperCut NG sources its user list from the same source as that used by the multiuser terminal server most likely an LDAP server.
• Enable the release station option on all printers that will be accessed via users of the multiuser terminal system.
Important: Enabling the release station option may be incompatible with objectives of other operating systems so it may be appropriate to set up a separate set of print queues. See Further Recommendations below for more detail.
• Set up a release station. This commonly takes the form of a dedicated terminal located near the printers, however other options worth considering using the PaperCut NG end-user web interface to release jobs, or the
• Instruct users on how to use the release station.
28.3.11.2. Other Methods:
1.
No alternate methods.
28.3.12. Further Recommendations
1.
Decide on an authentication method and use it consistently throughout the organization and network. For example, using popup authentication on some systems and release stations on others may be confusing for users. Try to offer a consistent user experience.
2.
Where possible, configure workstations to communicate with the server using the server's native print protocol.
For example, use SMB or standard Windows printing when printing to a Windows server, and Internet Printing
Protocol (IPP) when printing to a CUPS server. Servers are most reliable when talking their own language!
3.
Consider the scope of any configuration change. For example, enabling popup authentication or release station on a print queue will affect ALL users of that printer. For example it may be desirable to ask Linux users to use the release station, however this may be regarded as an inconvenience for Windows users. In these cases, it may be advantageous to set up two print queues for each physical printer - the first queue without release station enabled for Windows users and the other with the release station option enabled for Linux users.
495
Chapter 29. Mac Printing in Detail
29.1. Mac Printing Overview
This chapter of the manual is split into different sections for ease of use, one section covering Mac OS 10.8+ installations, and another covering Windows hosted print queue setup. In most cases only one section will apply on your network. As Mac systems have become more popular recently, many sites are opting for Mac print servers to support their Mac workstations. PaperCut can be installed directly on a Mac print server, offering native, end-to-end
Mac printing.
29.1.1. Terminology
Before we move on to configuring server-based print queues in a Mac environment, we'll first cover common terminology.
Print Queue: There are typically two ways of providing shared multi-system access to a printer:
1.
Configure each system to print directly to the device. The device needs to be networkable (e.g. have an
Ethernet connection) and support multiple connections.
2.
Configure a shared print queue. In this setup, only one system connects directly to the device (e.g. a server) and in turn the device is shared on the network via a print queue. Other systems on the network print to the shared queue rather than directly to the device.
Option 2 is regarded as a better solution on multi-user networks as it provides a higher level of scalability, allows for centralized administration, and allows administrators to move or remap devices without needing to propagate changes to workstations. PaperCut NG requires a shared print queue as it works by intercepting the jobs as they pass through the server's queue.
CUPS: CUPS is the print queue system used by Mac. This is the same queue system used by many other UNIX based platforms including popular Linux distributions. Apple is a major supporter of CUPS.
IP Printing: This is a generic term used to describe a number of print protocols that are used to exchange print documents between a computer, a server queue, or a physical printer. (Note: This term is also occasionally used incorrectly to describe the "JetDirect" print protocol discussed below)
IPP: This is an acronym for Internet Printing Protocol. This is the "native" print protocol used by CUPS and hence the Mac. It's a modern protocol designed to work well on modern networks including local networks, or even over the internet or a WAN.
LPR: LPR/LPD is the traditional UNIX based print protocol.
JetDirect/Socket: This is a very simple print protocol used to transmit print jobs to a physical printer on a TCP network. The printer simply accepts connections on port 9100. In Windows, this print protocol is often referred to as a
Standard TCP/IP Port
, and in some cases generally as IP Printing. Almost all network printers support this method.
Bonjour Printing: This is not a print protocol, but instead is Apple’s method of publishing printers on a network so workstations can locate the device/queue.
Where possible we have designed PaperCut NG to work with all print protocols, however we do recommend some over others. The following setup procedure highlights methods that have shown to work in most environments.
PaperCut’s recommended setup procedure can be summarized as follows:
• Install the printers on the server using a compatible driver.
• Test printing from the server.
• Share your printers.
• Set up the workstations to connect to the server's shared print queues.
496
Mac Printing in Detail
29.1.2. Optional Hardware Configuration
Some printer models support several of the connection methods listed above. If the printer offers the option to disable these protocols through their web administration page, you should turn off all but the connection method that you will use. This will minimize the chance of incorrect configuration, and the chance of a workstation user discovering the printer directly. Some printers also support access control via IP address. If this is available, consider setting access control so only the server IP can submit print jobs directly to the printer.
29.1.3. Handling unauthenticated systems (e.g. Laptops)
Print queues in Mac OS X by default are unauthenticated. Authentication in an Open Directory environment is instead performed at the time of system login. Unauthenticated systems such as laptops fall outside this. The introduction of unauthenticated systems on your network mandates the need for an extra layer of authentication. To address this need, PaperCut offers two options:
1.
Popup authentication via the PaperCut client software.
2.
Authentication via a release station or the web-based release interface (end-user login -> Jobs pending
release).
It is your decision whether or not the authentication policy/procedure should be applied to all systems on the network, or just "untrusted" laptops.
29.1.3.1. Network-wide policy
This is the simplest solution and provides a consistent procedure and policy across all your users irrespective of their access method (such as via workstation or their own laptop). Select your authentication method and enable this option on ALL print queues. The setup procedure for both methods is summarized as follows:
Using Popup Authentication
1.
Select the Unauthenticated printer option on all printers. (This can be applied to multiple printers via Copy
settings from Printer to Printer.)
2.
Ensure that all workstations have the PaperCut client software installed. This includes both authenticated lab systems and laptops. The PaperCut client must be running to be able to print successfully.
3.
Instruct users that they will need to enter their username and password in the PaperCut client, which can be set to save their credentials for an X amount of time if required.
Using Hold/Release Queue Authentication
1.
Check the Enable the hold/release queue option on all print queues. Jobs will not print until a user has authenticated and released the job.
2.
Set up release stations, or ensure the Allow users to view held jobs option is enabled on the Options tab in the PaperCut administration console.
3.
Instruct users on how to release their jobs. This procedure must be followed by all users.
29.1.3.2. Laptop Only Policy (Advanced)
One problem with the network-wide policy discussed above is that it the authentication method (e.g. client popup or hold/release queue) also applies to authenticated systems. In some ways this is a positive (i.e. provides a consistent policy), while in other ways it can be viewed as an unnecessary on trusted authenticated systems. This section discusses a solution appropriate for larger sites.
The solution is to set up two servers. One server hosts a set of queues for authenticated systems, while the other server provides queues for unauthenticated systems. Network router or firewall rules are used to ensure that only authenticated systems have access to the authenticated queues. Laptops systems must use the other queues. This is best done with partitioned IP address ranges and/or subnets. An experienced network administrator will be able to assist with restricted server access by IP address.
497
Mac Printing in Detail
29.1.4. Eliminating PopUp Authentication via Mac Login Hook
There may be the requirement to use popup authentication to provide a secure environment. For example, there may be a mix of lab systems and unauthenticated laptops. The lab systems are managed and secured via authentication against a central user directory source, while the unmanaged systems (e.g. laptops) are limited to local user authentication only and hence user identity is indeterminate. Popup authentication at the print queue level can be used to provide an added level of user verification.
This is an advanced topic and is targeted at experienced Mac administrators with command-line knowledge. The double-authentication is eliminated by having the system login also perform the PaperCut login via the system login hook. After the administrator has confirmed that the workstation is securely authenticating via a central directory service, they endorse the system by copying a shared secret file onto the workstation. To perform this endorsement, follow these steps:
1.
Setup the PaperCut client on the workstation and configure it to start via the login hook as explained in detail
here Section 5.2.1.5.3, “Multi-User Install”.
2.
Use a secure method (e.g. USB key or scp
) to copy the file located on the PaperCut primary server at:
[app-path]/server/data/pc-shared-secret.dat
to the workstation in either of the following locations:
/etc/pc-shared-secret.dat
or
/Library/PCClient/pc-shared-secret.dat
3.
Set ownership and permissions on the file via the command line as follows: sudo chown root /etc/pc-shared-secret.dat
sudo chmod 600 /etc/pc-shared-secret.dat
4.
Test login and verify that PaperCut popup authentication step has been eliminated by printing to an unauthenticated printer. Confirm that the job prints and logs as expected.
5.
Repeat steps above for each trusted directory authenticated system (e.g. lab system) on the network, or use system imaging processes.
29.2. Mac hosted print queues for OS 10.8+
This section discusses printer setup on systems where print queues are hosted on Mac OS 10.8+. There are some
“Windows hosted print queues” if you have Windows hosted print queues.
29.2.1. Installing the printers
Install the printer on the system running PaperCut using a compatible driver. For example, a driver supplied by
Apple or the manufacturer. If there is a choice of driver, our recommended choice would be a Postscript or PPD based driver. It is recommended you follow the manufacturer's suggested setup procedure for this part of the implementation. If the manufacturer supports various connection methods, we recommend using JetDirect/Socket if possible. Here is an example of a procedure that will set up a standard printer using a plain JetDirect/Socket connection:
1.
Select System Preferences...
2.
Select Print & Scan (in 10.9, this is named Printers and Scanners)
3.
Click on the + button to add a new printer
498
Mac Printing in Detail
4.
Click the IP tab
5.
Select HP Jetdirect - Socket in the Protocol list
6.
Enter the printer's IP address
7.
Give the printer a simple name without spaces
8.
Select the driver or printer model from the list and press Add
Now this has been done, print some test pages to the newly configured printer, such as printing a web page from
Safari. Confirm that printing works as expected before continuing. Be sure to test multiple options such as Duplex and Grayscale. If printing is not working as expected, see our troubleshooting section below.
Please note, if you are adding new printers, it is necessary to configure PaperCut to monitor the new print queues.
This is discussed in the section called Adding and Removing/Deleting/Ignoring Printers.
Figure 29.1. Setting up a printer on Mac OS 10.8 / 10.9 Server using Jetdirect
29.2.1.1. Tips and Troubleshooting
• Always try HP Jetdirect/Socket first, and use proprietary connection methods as a last resort
• If your printer does not support HP JetDirect/Socket, consider using IPP as an alternative
• If you are not able to install or find a driver for your printer, try the Generic Postscript Driver/Printer
29.2.2. Sharing the Printers
On Mac OS 10.8, Apple removed the ability to share printers using the Server Admin app. Sharing printers is now easier, however LPD has since been removed as an sharing option, and the default sharing method is now IPP. To share your printers, follow the below steps:
1.
Open System Preferences # Print & Scan on the print server (in 10.9, this is named Printers and Scanners)
2.
Click on the printer you want to share
3.
Tick Share this printer on the network
499
Mac Printing in Detail
Figure 29.2. Sharing printers for a print queue in Mac OS 10.8 / 10.9
29.2.3. Setting up the printers on Mac workstations
Once the printers are set up on the server and shared, the next step is to install the printers on the workstations. In this section we go over manual setup of print queues to workstations, as well as discussing a method of automating deployment via the Workgroup Manager. The goal is to add the printer on the workstation so it communicates with the server’s print queues rather than directly to the printer. Protocols include IPP, LPD, or LPD added via Bonjour.
The recommended setup is to use IPP, as this is the native protocol.
29.2.3.1. Manual Setup
1.
Open System Preferences # Print & Scan on the workstation (in 10.9, this is named Printers & Scanners)
2.
Click the + button
3.
Select IP as the type and select Internet Printing Protocol - IPP as the Protocol. If IPP is not compatible with this device, choose Line Printer Daemon - LPD as the Protocol)
4.
Enter your server name (or IP Address) in the Address field.
5.
Enter the the printer's Queue Name prefixed with printers/ in the Queue field. For example:
printers/my_office_printer.
6.
Select the appropriate driver under Print Using # Select Printer Software. If your model is not listed here, you may need to install the manufacturer's driver and repeat these steps again
7.
Take some time to test printing from the workstation, and confirm that all functions of the printer are working.
Note: If you have trouble connecting, ensure the queue name you are entering is correct. The queue name of the printer will have been set when the print queue was first created on the Mac server, and may be different to the visible printer name. The queue name can be found on the print server under System Preferences # Print & Scan
# [select printer] # Options & Supplies # General # Device Name.
If you have problems obtaining a driver for your printer, try the Generic Postscript Driver. This option will work with most printers. If after a test print the printer stops with a connection error, check the printer sharing permissions on the server or try the alternate method discussed below.
500
Mac Printing in Detail
Figure 29.3. Setting up a workstation printer on Mac OS 10.8 / 10.9
29.2.3.2. Publishing the printer via Workgroup Manager
Manually installing the printer on each desktop on a large network can be tedious. Large networks using Open
Directory may benefit from automating the process with Workgroup Manager. The key to successfully deploying/publishing printers via the Workgroup Manager is to publish the configuration from a working workstation rather than the server itself. The reason behind this is that it would publish the server's printer configuration. Since the server is configured to print direct to the device and not to the queue, this would be the incorrect configuration for user workstations. Instead we need to install the Workgroup Manager software on a configured workstation/client and publish its known configuration. We recommend having a workstation setup that is for Workgroup Manager administration and deployment only.
1.
Select one workstation on your network. Follow the manual setup procedure as discussed above.
2.
Test and confirm this workstation is configured and printing correctly. Also choose other settings as appropriate such as tray, duplex and other defaults. It is important to test this step before continuing. If printing is not working, this needs to be fixed before Workgroup Manager is used to publish your print queues.
3.
Install the Workgroup Manager on this client workstation found on the Mac OS X Server install disk).
4.
Open the Workgroup Manager, connect to your directory and select an appropriate user group or computer group used to manage client settings.
5.
Enter the Settings/Preferences area and select Printing.
6.
Select Manage Always and add printer(s) set up in step 1.
7.
Save settings and exit (e.g. click Done).
8.
Log onto another workstation and confirm that printer settings are being published as expected.
501
Mac Printing in Detail
Figure 29.4. Publishing printers using Server Admin on Mac 10.8
29.3. Windows hosted print queues
This section discusses printer configuration on Mac OS X workstation in environments systems where the print
your print queues are hosted on Mac OS 10.8+.
When a printer from a Windows environment is shared and added to a Mac system, Print and Scan requests printer access credentials in the form of username and password. Any user that prints to this printer uses these supplied credentials. This means that the administrator that added the printer to the workstation will be the owner of all documents printed from the workstation irrespective of the current logged in user.
The ideal solutions will vary from network to network and will depend on factors including:
1.
Your existing network configuration
2.
The mix and makeup of operating systems used on the network
3.
The underlying directory technologies (Active Directory, LDAP, etc.) if used
4.
Whether Macs are used by a single owner or multiple users
The following sections outline common set up scenarios and their pros and cons. Your solution may fit one of these scenarios or may be composed of a combination.
29.3.1. Scenario One: My Own Mac (Single User)
Many networks, particularly those in a business environment, have a dedicated desktop system for each user. This allows the desktop system's global settings to be customized for the user. Common examples include:
• Dedicated computers used in a business
• Staff laptops or desktops used in education
29.3.1.1. Requirements
• Printers hosted and shared from a Windows or Linux server.
• Mac systems used by a single user (or small group of known users).
• Each user has a domain account and password.
502
Mac Printing in Detail
• The username associated with the account on the Mac matches the domain username (either the account used to login, or the account set up as the automatic log in account).
• Running Mac OS X 10.8 or higher.
29.3.1.2. Installation
Check the user account information:
1.
Start up the Mac, login as the local administrator, and ensure the system is connected to the network.
2.
Select System Preferences...
3.
Depending on your Mac OS version, select Accounts or Users and Groups.
4.
Click MyAccount. (This step can be skipped in Mac OS 10.8 and 10.9)
5.
Ensure that the Short name associated with the account matches the user's domain account username. If not, create a new working account as appropriate.
29.3.1.3. Setting up the printers:
1.
Navigate to System Preferences -> Print and Scan.
2.
Click the + button to add a new printer.
3.
Control-Click on the Toolbar and select Customize Toolbar....
Drag the Advanced icon onto the bar, then click the newly added Advanced button
4.
Select the Windows printer via spoolss device type.
5.
Enter a Device URL, such as: smb://username:password@server_name/printer_name
• Tip: server_name is the name of the server hosting the printer, and printer_name is the printer's share name
• You may need to include the port in the DeviceURL: smb://server_name:139/printer_name
• OS X can struggle with printer share names containing spaces. We recommend a share name without spaces
6.
In Name field, enter a friendly and informative printer name.
7.
Choose a driver for this printer by pulling down the drop-down box and selecting Select Software...
8.
Click the Add button.
9.
Test print and ensure jobs are logged in PaperCut NG as the correct user.
503
Mac Printing in Detail
Figure 29.5. Connecting the printers to the Mac OS X server
29.3.1.4. Installing the PaperCut NG Client software
1.
Open Finder and select Go -> Connect to Server....
2.
Enter smb://servername/pcclient where servername is the name of the server hosting PaperCut NG. If you are prompted for a username and password, this will be a username that has access to connect to the SMB share on your Windows server.
3.
Drag the
PCClient application across to the local Applications directory.
4.
Open System Preferences...
5.
Select Users & Groups.
6.
Slect the Login items tab.
7.
Click the + button and select the newly installed
PCClient application. Ensure to tick the PCClient option once it appears.
8.
Restart the system and ensure the client starts upon login.
504
Mac Printing in Detail
Figure 29.6. Installing the PaperCut Client software
29.3.1.5. Tips and Troubleshooting
• Get the user to log into the Mac. Verify that the
PCClient program starts automatically and shows the user’s balance.
• Print to the newly set up printer. On the server's print queue, ensure that the job appears under the correct username.
• Ensure that the print job successfully reaches the printer and that the user gets charged in PaperCut.
• Check that the balance has changed to reflect the new balance in the
PCClient program.
29.3.2. Scenario Two: The Multi-User Mac with Popup Authentication
Schools and universities often have Macs available for student use in dedicated computer labs. In these environments the Macs are shared by many users and Scenario One is not appropriate. Larger Mac networks already using LDAP or Active Directory authentication, or planning on doing so, may wish to consider Scenario
Three explained in the next section.
and discussed further below:
The end-user's perspective:
1.
The user sees the
PCClient program running.
2.
When the user prints a job, the client pops up a window requesting the user to enter a username and password.
See Section 7.10, “Popup Authentication”.
3.
The user enters a domain username and password.
4.
If the credentials are valid, the job is charged to the user account.
The explanation:
1.
The print event is performed as a generic user - for example " macuser
", " student
", etc.
2.
In PaperCut NG, the "macuser" account is set up to use popup authentication by enabling the option
505
Mac Printing in Detail
Unauthenticated user. See Section 7.10, “Popup Authentication” for further details.
3.
The popup requests the user to enter a username and password.
4.
The password is authenticated and printing is charged against the supplied account.
29.3.2.1. Requirements
• Printers are hosted and shared off a Windows, Mac or Linux server.
• The Mac systems are set up to login under a generic account name. (e.g. macuser, student, etc.)
• The domain contains a user account matching the generic account.
29.3.2.2. Installation
Domain account set up:
1.
Log onto the print server or the domain controller as a domain administrator.
2.
Open Active Directory Users and Computers (or equivalent user management tool) from Start ->
Administrative Tools.
3.
Add a new domain user called macuser
.
4.
Define a password for macuser and set the password to never expire.
Mac account set up
1.
Start up the Mac, login as the local administrator, and ensure the system is connected to the network.
2.
Select System Preferences...
3.
Depending on your Mac OS version, select Accounts or Users and Groups.
4.
Create an account called macuser
. Ensure the account's short name is macuser
.
5.
Set this account as the automatic login account, or alternatively make the password known to all users.
Set up the printers that the user requires access to:
1.
Navigate to System Preferences -> Print and Scan.
2.
Click the + button to add a new printer.
3.
Control-Click on the Toolbar and select Customize Toolbar....
Drag the Advanced icon onto the bar, then click the newly added Advanced button.
4.
Select the Windows printer via spoolss device type.
5.
Enter a Device URL, such as: smb://username:password@server_name/printer_name
• Tip: server_name is the name of the server hosting the printer, and printer_name is the printer's share name
• You may need to include the port in the DeviceURL: smb://server_name:139/printer_name
• OS X can struggle with printer share names containing spaces. We recommend a share name without spaces
6.
In Name field, enter a friendly and informative printer name.
7.
Choose a driver for this printer by pulling down the drop-down box and selecting Select Software...
8.
Click the Add button.
9.
Test print and ensure jobs are logged in PaperCut NG as the correct user.
29.3.2.3. Installing the PaperCut NG Client software
506
Mac Printing in Detail
1.
Open Finder and select Go -> Connect to Server....
2.
Enter smb://servername/pcclient where servername is the name of the server hosting PaperCut NG. If you are prompted for a username and password, this will be a username that has access to connect to the SMB share on your Windows server.
3.
Enter account details for an account able to connect to the SMB share if requested
4.
Drag the
PCClient application across to the local Applications directory.
5.
Command-click on the newly copied
PCClient application in the Applications directory. Select Open
Package Contents.
6.
Navigate to
Contents/Resources/
.
7.
Double-click on the install-login-hook.command
script.
8.
Restart the system and ensure the client starts upon login.
29.3.2.4. Configure the popup settings:
1.
Log on to the PaperCut NG administration interface as built-in admin user.
2.
Select the macuser account from Users.
3.
On the macuser's details screen, set the account balance to zero.
4.
Ensure the user is set to Restricted.
5.
Check the Unauthenticated option and save the changes.
6.
Click the Apply button to save the changes.
If users login to the Mac using their AD/LDAP username then it's possible to eliminate the authentication popup by
configuring the client as described in Section 7.10, “Popup Authentication”.
29.3.2.5. Tips and Troubleshooting
• Get the user to log into the Mac. Verify that the
PCClient program starts automatically.
• Print to the newly set up printer. On the server's print queue, ensure that the job appears under the correct username.
• An authentication popup should display on the Mac. Enter a valid domain username and password.
• The corresponding user should be charged for the job. Also check that the balance has changed to reflect the new balance in the
PCClient program.
29.3.3. Scenario Three: Multi-user Macs using LDAP or Active Directory authentication
Larger networks often run the Macs in a domain environment either authenticating with an Active Directory or an
LDAP network. In an authenticated domain environment, the identity of the user (the user's username) is known and verified at the time of login. With the help of the TCP/IP Printing Services for Microsoft Windows, and the LPR/LPD support on the Mac, print jobs can be identified on the server and associated with the user's login name. This avoids the need for the popup authentication used in Scenario Two.
29.3.3.1. Using the LPR and IPP printing protocols on Windows print servers
LPR is a legacy protocol developed for UNIX that clients use to send print jobs to print servers. Microsoft has supported this protocol for a number of years via an add-on module called Print Services for UNIX (PSfU). Under certain conditions Windows LPD printers can cause issues when using PaperCut hold/release print queues. The information included here is to help customers understand the issue and document suggested workarounds.
The mechanism used by the Windows PSfU subsystem to accept LPR and IPP print jobs is different from other implementations in Windows such native SMB based printers. In SMB the event notification to applications such as
PaperCut is well behaved and reliable. Event notification for LPR and IPP based printing does not use the same set
507
Mac Printing in Detail of underlying APIs and under some conditions the PaperCut print monitoring layer receives notification after the print job has started. This means that some print jobs may start to print before the hold instruction is issued. This job is then suspended in a Paused Printing state (i.e. both paused and printing) and this results in all other jobs on that queue being held up by the paused job.
The information we have from customers who have experienced this problem shows that the symptoms are generally not consistent, suggesting an underlying race condition bug in Windows. Things that can affect the problem include:
• Running the print server on a virtual machine
• The number of processors/cores
• The current load on the print server
• The version and patch level of Windows
Because the issue is in the underlying Windows print subsystem it not possible for PaperCut to quickly implement a reliable solution and we do not expect Microsoft to implement a fix to this legacy subsystem. If a site does experience this issue there are some steps that can help alleviate or fix the issue.
1.
Use the SMB protocol for Windows based print server queues. Note that using SMB may place some constraints on how users authenticate and how anonymous users are able to print at your site. This is the recommended approach.
2.
Use two print queues. Queue A is virtual and queue B is the real queue attached to the physical printer. Users print to A using LPR and PaperCut can always place a hold on the print job. PaperCut then redirects the job to
Load Balancing. Queue A should be configured to use a port with no printer (e.g.
LPT1:
), it should be permanently paused (Printer
→
Pause Printing), and the virtual queue configuration for A in PaperCut should forward jobs to B (setting Jobs may be forwarded to these queues).
If queue A is un-paused then the job will error, however it can still be re-directed as needed.
29.3.3.2. Requirements
• Macs set up in multi-user mode authenticating off a domain. Either Active Directory or LDAP.
• Printers hosted on a Windows print server.
• The server needs the TCP Printing Services installed (also known as Print Services for Unix).
29.3.3.3. Installation
On the server hosting the printers, setup TCP/IP Printing:
1.
Log into the server as a system administrator
.
2.
Select Control Panel -> Add Remove Programs.
3.
Click on Add/Remove Windows Components.
4.
Select Other Network File and Print Services.
5.
Click Details... and ensure Print Services for Unix is selected.
6.
Click Next to complete the installation.
Some systems running firewall software may block LPD printing. On systems running firewall software, ensure that incoming connections from the local network are allowed on port 515.
On each Mac, add the required printers:
1.
Open the Printer Setup Utility from Applications -> Utilities.
508
Mac Printing in Detail
2.
Click the + button to add a new printer.
3.
Click the IP tab at the top toolbar.
4.
From the Protocol dropdown, select Line Printer Daemon - LPD.
5.
Enter the IP address of the server hosting the printers in the Address field.
6.
Enter the printer's share name in the Queue field.
7.
Define a user friendly name in the Name field and select the printer type.
8.
Click the Add button.
9.
Repeat for other printers as necessary.
29.3.3.4. Installing the PaperCut NG Client software
1.
Open Finder and select Go -> Connect to Server....
2.
Enter smb://servername/pcclient where servername is the name of the server hosting PaperCut NG. If you are promted for a username and password, this will be a username that has access to connect to the SMB share on your Windows server.
3.
Enter account details for an account able to connect to the SMB share if requested
4.
Drag the
PCClient application across to the local Applications directory.
5.
Command-click on the newly copied
PCClient application in the Applications directory. Select Open
Package Contents.
6.
Navigate to
Contents/Resources/
.
7.
Double-click on the install-login-hook.command
script.
8.
Restart the system and ensure the client starts upon login.
29.3.3.5. Tips and Troubleshooting
• Restart the system and ensure the
PCClient application starts on login and lists the user's account balance.
• Ensure print jobs correctly show in the PaperCut job logs under the user's PaperCut account.
• The corresponding user should be charged for the job. Also check that the balance has changed to reflect the new balance in the
PCClient program.
29.3.3.6. Additional information and tips
appropriate to provider to end-users or other system administrators.
The
PCClient
/Applications/PCClient.app/Contents/Resources/login-hook-start
Look for the line starting with client_args and the associated comments above.
509
Chapter 30. Running in a Workgroup
Environment
A workgroup environment differs from a network domain model. In the domain model, users authenticate using a common username/password as defined in a central server. Users can typically access and use any PC on the network by using their username and password. In a workgroup, the PC's are loosely coupled and user identity is validated locally rather than centrally. The PC's are either set up to automatically log in as a general "user", or user accounts are set up on the PC's as required.
For systems running Windows XP Home, 'simple file sharing' cannot be disabled, forcing client machines to try to authenticate as the Guest user. For this reason, we do not recommend the use of Windows XP Home in multi-user environments.
Users may still authenticate with PaperCut NG on Windows XP Home by entering their details into the User Client utility. This is similar to how user authentication is performed with Mac clients. For more information see
Section 30.2, “Option 2: Authenticating via popup”.
PaperCut NG offers a number of options for running and authenticating users in a workgroup. The two common options are:
30.1. Option 1: Common username and passwords on all systems
This option is suitable for networks running Windows 2000 or Windows XP Pro.
1.
Nominate a system to host the printers and the PaperCut NG server software.
2.
Set up the printers and share with appropriate names.
3.
Windows XP only: Turn off simple file sharing by opening Windows Explorer, select Tools
→
Folder Options..., and un-ticking the appropriate option on the View tab.
Figure 30.1. Turn off simple file sharing
4.
On the nominated host system, ensure that the
Guest account is disabled. To do this on a system running
510
Running in a Workgroup Environment
Windows XP: a.
Open the
Local Users screen: Start
→
Control Panel
→
Administrative Tools
→
Computer
Management
→
Local Users and Groups
→
Users
b.
Right-click on the
Guest user and select Properties.
c.
On the General tab, check Account is disabled.
d.
Press the OK button.
This should also be performed for any system running a release station.
5.
On the nominated host system, set up user accounts for all users. This can be done via under User Accounts in the Windows Control Panel.
6.
Set permission on the printer so only these users can access the printer shares (i.e. don't allow guest).
7.
Install the PaperCut NG server software and complete the configuration wizard.
8.
Instruct each user to log onto their workstation using an account with the same username and password as set up for them on the nominated host system. This will ensure that their jobs list in the queue under their username.
30.2. Option 2: Authenticating via popup
that ensures that all users list as "guest" when printing to a remote printer. This limitation can be worked around with popup authentication.
1.
Nominate a system to host the printers and the PaperCut NG server software.
2.
Windows XP only: Turn off simple file sharing by opening Windows Explorer, select Tools
→
Folder Options..., and un-ticking the appropriate option on the View tab.
Figure 30.2. Turn off simple file sharing
3.
On the nominated host system, ensure that the
Guest account is disabled. To do this on a system running
Windows XP: a.
Open the
Local Users screen: Start
→
Control Panel
→
Administrative Tools
→
Computer
Management
→
Local Users and Groups
→
Users
511
Running in a Workgroup Environment b.
Right-click on the
Guest user and select Properties.
c.
On the General tab, check Account is disabled.
d.
Press the OK button.
This should also be performed for any system running a release station.
4.
On the nominated system, set up user accounts for all users.
5.
Install the PaperCut NG server software and complete the configuration wizard.
6.
Print from another workstation. The job should list in PaperCut NG under the user "guest".
7.
In the PaperCut NG admin interface, enable the account selection popup and turn off the Allow user to
charge to their personal account option and enable the Allow user to perform printing as another user.
Figure 30.3. Enable perform printing as other user
8.
Install the client software on each workstation. See Section 5.2, “User Client”.
9.
When the user prints to the shared printer, a popup will now ask users to enter their username and password.
512
Chapter 31. Printing Solutions for Guests and Anonymous users
PaperCut tracks print activity against individual users. In most cases, these users belong to your organization, and user information is synchronized against an external user directory source such as Active Directory, Open Directory, eDirectory or LDAP. If you are able to synchronize your users against an external directory source - this should be your first choice.
There are a number of scenarios where it is not practical to synchronize all users from an external directory. They typically involve visitors and guest users printing from BYOD mobile devices that may not even have access to the corporate wired or wireless networks.
Guest Printing for Business
• Requirement: Need a printing solution for visitors and casual guests - often using BYOD devices with no network access.
• Considerations: Tracking of individual guest users is not important.
•
Recommend: Anonymous Email to Print (direct print or managed release)
Guest Printing for K-12 Schools
• Requirement: Need a printing solution for visitors and casual guests.
• Considerations: Tracking of individual guest users is not important, but need controls in place to prevent student use.
•
Recommend: Anonymous Email to Print with hold/release queue managed by front desk.
Guest Printing for Higher Education / Library Pay-for-Print
• Requirement: Need a pay-for-print solution for students and guest users.
• Considerations: Each user has their own account and account balance.
513
Printing Solutions for Guests and Anonymous users
•
Recommend: Internal users with self-registration.
To address these varied requirements, PaperCut offers multiple solutions for guest and anonymous printing:
•
Internal users may be added by a PaperCut administrator or self-registered.
• Shared or Generic User: A shared username and password is provided to guests to allow them to login and print using company equipment. All guest jobs are logged in against this generic user.
•
for printing. Jobs are logged against a single internal guest user.
31.1. Internal Users (users managed by PaperCut NG)
Internal users are best thought of as user accounts that only exist inside PaperCut and are independent of the domain, network or operating system. Internal users are managed inside PaperCut, removing the need to create or manage them in an external user directory.
There are several ways the feature can be utilized:
• Selected staff can be given access to create internal user accounts. This gives staff control over who can receive a new account, preventing the creation of unwanted accounts (e.g. with offensive usernames).
• Users can be given the ability to create their own internal accounts via a web based registration form. This can be useful for providing guests the ability to register their own accounts and begin printing immediately, removing the need for staff intervention.
• Administrators can create a new batch of internal users via a text based file import. This can be used to import or update a set of users that are managed separately to the regular domain users. For more information about the
The following sections present several different environments and how the internal users feature can be used to
full details about each available option.
31.1.1. Implementation by Example
Several examples are provided below demonstrating how the internal user feature may be applied.
Important
In PaperCut NG all internal usernames must only contain characters that can be printed (e.g. not newline
) and must not contain
/
,
\ or
@
.
31.1.1.1. Scenario One: Manually Managed Guest Accounts
North Shore University has a campus that occasionally hosts students from other universities. These guest students do not have a login in the universities domain, and it is considered too much effort to go through "official channels" to create one for them.
The administrator would like to provide selected staff the ability to create PaperCut NG accounts for these guest students as needed. To go about this, the administrator performs the following:
1.
The guest students are first provided with access to computers or network resources using the generic login guest
, password guest
.
2.
The generic guest login is marked as Unauthenticated using the PaperCut NG administration interface. This option is available on the user's details page.
3.
Navigates to Options
→
User/Group Sync
→
Internal User Options.
514
Printing Solutions for Guests and Anonymous users
4.
Checks the Enable internal users option, and under Access control selects Only admins can create users.
5.
The Confirmation message is tailored to provide relevant information such as how to log in.
6.
Presses Apply.
7.
PaperCut NG administrator access is assigned to the staff who will be responsible for creating the new student guest accounts. The administrator right Create internal users is required for this purpose. For more information
about assigning administrator rights see Section 15.4, “Assigning Administrator Level Access”.
8.
Ensures that the PaperCut NG client software is running on workstations where guest printing will be allowed.
The system is now configured to allow selected staff the ability to create internal accounts for the guest students.
When a guest student prints from the generic guest login, the PaperCut NG client tool will display the
authentication popup. This will allow them to enter their personal username and password, assigned by the administrator when registering their internal user account.
Staff can create an internal user account for a guest student as follows:
1.
Log into the PaperCut NG administration interface, and select the Create internal user... action from the
Actions menu of the Users tab.
2.
Complete the from and press Register.
31.1.1.2. Scenario Two: Automated Guest Management (self-registration)
West Face College is a large community college that regularly has members of the public visiting to use the library resources.
It is not feasible to create a domain login for every visitor, and manually creating an internal user account for each guest would require too much time of the administrators or staff, so the decision is made to automate the process and allow guests to register their own internal user accounts.
To set up the internal users feature and allow guest self-registration, the administrator performs the following:
1.
The guests are first provided with access to computers or network resources using the generic login guest
, password guest
.
2.
The generic guest login is marked as Unauthenticated using the PaperCut NG administration interface. This option is available on the user's details page.
3.
Navigates to Options
→
User/Group Sync
→
Internal User Options.
4.
Checks the Enable internal users option, and under Access control selects Users can register their own
account.
5.
Checks Display registration links on login screens so that users will have easy access to the registration interface.
6.
Changes the Link text to
Guests click here to register
, to provide a better clue for guests.
7.
Adds more information about the organization's printing policy, how to access printing resources, etc. under
Additional registration instructions. A note is also added to specify that only guests need to register to access printing resources - students or users with existing accounts do not need to register.
8.
Presses Apply.
9.
Ensure that the PaperCut NG client software is running on workstations where guest printing will be allowed.
10. Creates an information sheet for guests, providing instructions about how to register, how to print, and where to find additional help. Most people will not need this kind of information to work out how to use the system for themselves, but some people appreciate step-by-step instructions.
The system is now configured to allow guests to register their own internal user accounts. When a guest user prints from the generic guest login, the PaperCut NG client tool will display the authentication popup. This will allow them to enter their personal username and password, chosen when registering their internal user account.
For a guest to create an internal user account, they must:
515
Printing Solutions for Guests and Anonymous users
1.
Click the Register as a New User link on a login screen (the web interface login screen, or on the authentication popup), or access the registration web interface directly at http://[server-name]:9191/register
.
2.
Complete the from and press Register.
31.1.1.3. Scenario Three: Managing Users in a Non-Domain Environment
Southmark Inc. is a medium sized ten person real estate office service the local area. Their network consists of a mix of Windows XP and Windows Vista workstations connected to a workgroup based network. No user directory / domain exists, and setting one up is not a current priority. They would like to take control of their printing costs and volumes, and use PaperCut NG to identify the amount of printing performed by each staff member.
Because no user directory exists, PaperCut NG will be used to maintain user accounts, details and passwords for all staff. To set this up, the administrator performs the following:
1.
Navigates to Options
→
User/Group Sync
→
Internal User Options in the PaperCut NG administration interface.
2.
Ensures that the Enable internal users option is enabled.
3.
Removes (sets to blank) the value for Prefix usernames with:. There is no need for an internal username prefix, because all users will be internal!
4.
Collects a chosen username and password from each staff member. This is used to construct a batch import
file, using the format specified in Section 31.1.4.1, “Batch Internal User Import File Format”.
5.
Imports the batch file into PaperCut NG using server-command to create a new internal user account for each
staff member, following the directions in Section 31.1.4, “Batch Internal User Import and Update”.
6.
workstation in the office.
7.
When staff send print jobs from their workstations, they arrive at the print server under the generic guest username. The administrator marks this generic account as Unauthenticated using the PaperCut NG administration interface. This option is available on the user's details page.
The batch of internal user accounts has now been imported, ready for the staff to use them. When a staff member next sends a print job, the PaperCut NG client tool will display the authentication popup. This will allow them to enter their personal username and password, provided to them on arrival, having been assigned by the administrator in the batch import file.
31.1.2. Internal Users Options
The options for configuring internal users are located at Options
→
User/Group Sync
→
Internal User Options in the administration interface.
516
Printing Solutions for Guests and Anonymous users
Figure 31.1. Internal users options
The available options are:
• Enable internal users - enables or disables the feature in general. If the feature is disabled, internal users will not be able to be created.
• Access control - determines who may create internal users. The available options are:
• Users can register their own account - A web based interface will be available for users to register their own account. This allows users to register their own accounts without intervention from staff or administrators.
Figure 31.2. Web based internal user registration interface
• Only admins can create users - Only administrators will be able to create users via the PaperCut NG
517
Printing Solutions for Guests and Anonymous users
“Assigning Administrator Level Access”.
Figure 31.3. Creating an internal user from the administration interface
• Display registration links on login screens - When enabled, PaperCut NG login screens will display a
Register as a New User link. Clicking this link takes the user to the web based registration interface, allowing the user to create their own internal user account. If disabled, registration links will not appear, and users may only access the web based registration interface by navigating to the URL at http://[server-name]/register
.
Figure 31.4. Login screen showing the registration link
• Link text - The text used for registration links on login screens. The default link text is
Register as a New
User
. An example of alternate link text might be
Guests click here to register
.
• Additional registration instructions - This option allows providing additional instructions to users when registering, and are displayed above the web based registration form. Specific instructions will vary from site to
518
Printing Solutions for Guests and Anonymous users site, but could include information such as how to log in and print, how to add credit to their account, or where to find additional help.
• User must enter an email address - Enable this option to require that the user enters an email address. If disabled, entering an email address is optional.
• Allow user to choose their own identity number - If enabled, the user will be able to enter/choose their own identity number. The chosen identity number must be at least 6 digits, and must be unique. If disabled, a unique identity number will be automatically generated for the user. Identity numbers may be used for logging into some devices where only a numeric keypad is available.
• Allow user to choose their own ID PIN - If enabled, the user will be able to enter/choose their own ID PIN. The chosen PIN must be at least 4 digits. If disabled, a random PIN will be automatically generated for the user.
• Prefix usernames with: (optional) - This prefix will be applied to the username of all users registering via the web based interface. E.g. if a user chooses the name john
, and the username prefix is guest-
, their allocated username will be guest-john
. This prevents name clashes with existing or future users from the configured user/group sync source, and immediately identifies the user as being internal.
• Confirmation message - This message is displayed to the user after they have completed registration. It may also be emailed to the user (see next option).
• Also email confirmation message to user - If this option is enabled the confirmation message will be emailed to the user after registration (if an email address was provided).
Tip
• An alternative to the PaperCut NG client tool's authentication popup is to use a print release station in
Release Any mode. After ensuring that guest users have their own internal account, this will allow users to submit a print job under a guest/generic login, then authenticate at the release station and choose which job(s) they would like to release. For more information about setting up a
release station see Chapter 13, Hold/Release Queues & Print Release Stations.
• To delete an internal user, navigate to their User Details page in the administration interface by clicking on the user in the User List, then select the Delete user item from the Actions list. The
domain/network-level User and Group Synchronization settings and opperations do not affect and
will not delete internal users.
• The special
[Internal Users] group contains all internal users. It can be used to produce reports showing information about internal users, or to apply a bulk user operation on all internal users.
31.1.3. Changing Internal User Passwords
When using the Internal User functionality of PaperCut NG, there may be a need for the Internal User to change their password. This can be done by users and administrators.
• Administrators can reset the password via the users details page in the PaperCut NG Application Server
Administration Console. There is a "Change Password Link" located near the Internal User Settings heading.
Figure 31.5. Changing an internal user password from the administration interface
• The Internal User can reset their password via the User Web pages by clicking on Change Details.
519
Printing Solutions for Guests and Anonymous users
Figure 31.6. Changing an internal user password from the user web page
Tip
Administrators can turn on or off the ability for Internal Users to change their password by using the
Config Editor and modifying the key: internal-users.user-can-change-password
31.1.4. Batch Internal User Import and Update
This section covers the batch importing and updating of internal users. Internal users are managed internally by
PaperCut NG, and may be used in addition to those in the configured user directory source. For more information
importing and updating regular users see Section 6.6, “Batch User Data Import and Update”.
The batch internal user import and update feature allows the administrator to import users, user information and optionally update existing internal user details by reading data from a simple text file. In addition to being able to create internal users, it enables administrators to update the following user data:
• Password
• Credit balance
• Restriction status
• Full name
• Email address
• Department
• Office
• Card/ID Number
• Card/ID PIN
• Notes
• Secondary Card/ID Number
Important
An internal user can be deleted by selecting the Delete user action while viewing the user. Features to simplify the deletion of multiple users (a 'batch delete') will be introduced in a future version.
Examples of where the batch user import feature is useful include:
520
Printing Solutions for Guests and Anonymous users
• Several guests to the organization will be arriving at the same time and will require their own accounts in
PaperCut NG.
• A set of users needs to be managed separately / externally to the existing user directory source. For example, the users of a certain computer lab require their own accounts in PaperCut NG, but it is not possible to create accounts for them in the existing user directory.
• Details for existing internal users needs to be updated.
To perform a batch internal user import:
1.
Manually inspect your file in a text editor and ensure it's in the prescribed tab-delimited format as detailed at
Section 31.1.4.1, “Batch Internal User Import File Format”.
2.
Follow the directions in Section A.1, “Server Commands (server-command)” to run the server-command
batch-import-internal-users
.
For example, to import/update internal users from a file import.tsv
on a Windows system:
C:\> cd "C:\Program Files\PaperCut NG\server\bin\win" server-command batch-import-internal-users "C:\extra users\import.tsv"
Note that the import path should be quoted if it contains spaces.
On a Mac OS X system: mac-server:~ jason$ cd "/Applications/PaperCut NG/server/bin/mac/" mac-server:mac jason$ ./server-command batch-import-internal-users /path/to/the/file/import.tsv
If your import path has spaces, remember to escape them if you don't use quotes:
/path/to\ the\ file/import.tsv
3.
The import process will start running in the background. See the App. Log tab in the administration interface to check the status of the import or if any errors were encountered.
Caution
Batch imports are a major operation, modifying data en masse. Best practice suggests:
• Always run a backup before proceeding with the import.
• First experiment/test the import process with a small batch of users before moving onto the full batch.
31.1.4.1. Batch Internal User Import File Format
The import file is in tab delimited format and contains the following fields in the given order:
No.
1.
Field
Username
Description Optional?
The internal user's username.
If the policy is to use a username prefix for internal users, include the prefix here
(e.g.
guest-user123
).
Mandatory
Limitations
Max. 50 characters
521
Printing Solutions for Guests and Anonymous users
No.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
Field
Password
Credit Balance
Restricted Status
Full Name
Department
Office
Primary Card/ID Number
Card/ID PIN
Notes
Secondary Card/ID Number
Description
The user's password
The user's credit balance
Optional?
Limitations
Optional - although internal users cannot log in without a password
Optional - balance not set if blank
A number with no currency symbol or separators, using a full stop for the decimal separator.
Correct:
1.23
Incorrect:
$1.23
or
1,23 or
1,023.00
The user's restricted status.
(Y/N)
Optional - restricted status not set if blank
The user's full name Optional - full name not set if blank
Max. 255 characters
The user's email address
The user's department or faculty
Optional - department not set if blank
Max. 200 characters
The user's office or location
Optional - email not set if blank
Max. 255 characters
Optional - office not set if blank
Max. 200 characters
The user's identity/card number primary Optional - card/id number not set if blank
Max. 200 characters, case insensitive
The user's card PIN number Optional - card/id PIN not set if blank. If the field is '-' then the PIN is set to zero.
Max. 20 digits
Notes about the user.
Optional - notes not set if blank
Max. 2000 characters
The user's secondary identity/card number
Optional - card/id number not set if blank
Max. 100 characters, case insensitive
Table 31.1. Internal User Import File Format
Other limitations: Although any actual limit to the size of an import file should be large enough for any purpose, we recommend keeping the file size below 10MB.
Tip
• If an optional field is not specified in the import file then it will not be updated. To remove or "blank out" an existing value, use a single "-" (hyphen / dash).
• A simple way to create a tab delimited file is to create a spreadsheet in Microsoft Excel, then save it in the
Text (Tab delimited) format.
For some examples of using tab-delimited files, see Section 6.6.1.1, “Import File Format Examples”.
31.2. Anonymous Guest Printing
In the normal case, PaperCut must identify the user responsible for each print job so that jobs can be correctly tracked and charged. However for ad-hoc guest printing by visitors, it is often more important to provide a convenient printing solution than to provide individual print tracking per visitor.
In addition, visitors and guests often wish to print from their BYO mobile devices so a generic, widely available printing solution is required.
522
Printing Solutions for Guests and Anonymous users
solution provides a simple and convenient printing experience from any device, imposing minimal or no administrative inconvenience on the guest user as there is no need to set up accounts or network access for the guest.
Anonymous email printing may be implemented in three ways:
•
Direct Print
Guests can send their job directly to the anonymous email defined for a physical printer. This is the most convenient way to provide printing access for guests or visitors.
•
Managed Release
Guest users send their job to the printer’s anonymous email address where they are held in a hold/release queue. Jobs are released by the receptionist or a trusted person in the organization. Jobs sent by different guests can be identified by the guest’s email address which is appended to the document name.
•
Guest Self-Release
Guest users send their job to the printer’s anonymous email address where they are held in a hold/release queue. Guests are provided with a common username and password by which they can login to the MFD to release their job. Jobs are identified by their email address appended to the document name.
Each of these options has advantages. The following table may help you make the best choice for your organization:
Direct Print
Managed Release
Guest Self-Release
Suitable For
Business
Business and Education
Business
Benefits
Very convenient - no staff envolvement
Convenient for guest. Printing is supervised and managed by staff.
Convenient for site staff.
Trade-Off
Low security.
Printing is uncontrolled with potential for paper wastage.
Separate email aliases are required for each printer (no virtual queue).
Staff must be available and interrupted to release jobs for guests.
Moderate.
Printing is uncontrolled with potential for paper wastage. Guests can see and release each others jobs.
Document Privacy
Low
Good
Low-Moderate
Table 31.2. Guest Email to Print Modes
31.2.1. Anonymous Setup
The starting point for all three anonymous printing modes is the Options
→
Mobile & BYOD page. Email to Print
“Email to Print”), then return to this section.
• Step 1:
• On the Options
→
Mobile & BYOD page, under Email to Print, check the box
Enable anonymous printer email addresses
.
• Optionally change the user that anonymous jobs will be logged to. The default user is guest-user
.
• If you wish guests to receive a reply email in response to sending a print job, check the box
Send a response email
. You can customize the email body as required.
523
Printing Solutions for Guests and Anonymous users
Figure 31.7. Setting up anonymous printing
Important
If the guest user (default guest-user
) does not already exist, it will be created for you, as an internal user. If you wish to be able to login as this guest user, you will need to either:
• Create the user beforehand in AD/LDAP as a regular user and sync it with PaperCut. This will allow you to manage the guest user in the same way as any other user. Ensure the user is configured as unrestricted
.
• or Enable Internal Users in Options
→
User/Group Sync. If internal users are not enabled, the internal guest user can still be used to log jobs, but you will not be able to log in to this user.
• Step 2: Enable a printer for anonymous printing by configuring an anonymous printing email alias.
• Go to Printers and select a printer
• In the Email to Print section, add a valid email address or alias in the
Anonymous email address text box.
• Click Apply
The remaining steps are specific to your selected anonymous printing mode:
31.2.1.1. Direct Print Setup
• Step 3: Ensure your printer does not have
Enable hold/release queue checked in the Printer Details page.
You are now ready to test. Email to Print jobs sent to the printer's guest email alias will print without intervention.
Tip
When using direct print, consider implementing a print script to force printing policy. For example, converting jobs to duplex, or redirecting large jobs to a high volume printer.
31.2.1.2. Managed Release Setup
• Step 3: Configure your printer to use a hold/release queue.
• Check
Enable hold/release queue in the Printer Details page.
•
User Release is the correct option for most scenarios.
• Step 4: Make the receptionist or person responsible for releasing guest jobs a delegated release manager for the guest user.
524
Printing Solutions for Guests and Anonymous users
• Go to Users, and select your receptionist user.
• In the Advanced Options section, check the box:
Allow this user to release jobs printed by others (Delegated print release)
.
• Add your configured guest user (default guest-user
) to the list of Users and click Apply.
Figure 31.8. Setting a delegate for the guest-user account
The receptionist may now log into a release station or MFD and see the guest print jobs. Anonymous Email to Print jobs can be identified by the source email address appended to the document name.
Tip
If using swipe cards, reception can simply swipe their card to login and release jobs.
31.2.1.3. Guest Self-Release Setup
• Step 3: Configure your printer to use a hold/release queue.
• Check
Enable hold/release queue in the Printer Details page.
•
User Release is the correct option for most scenarios.
• Step 4: Set a password for the configured guest user (default guest-user
). This password should be changed regularly - e.g. daily or weekly.
Tip
• You can edit the response email to include the guest username and password - or you can direct the user to ask reception for this information.
• Keep the guest password secure to avoid abuse of the guest printing facility.
• Run regular reports of printing by your guest user to audit usage of guest printing.
• Change the guest user password regularly. This can be automated using server-command
31.2.1.4. Known users and anonymous printing
The anonymous printing feature is designed for ad-hoc use by guests and visitors. It should not be used by people within your organization, as printing is not tracked by user and many important features such as account selection, script pop-ups etc are not supported.
If an Email to Print job is sent to an anonymous printer email address by a known user (i.e. the source email matches a user in the PaperCut database) the job will not be logged to the guest-user account. Instead, the normal print workflow for the known user will be performed and the job logged against that user.
525
Chapter 32. Multiple Personal Accounts
Users in PaperCut have a personal balance used to fund their personal printing. This balance can be treated like a bank account used for printing. When the account is out of credit the user can no longer print until more funds are added to the account. By default users have a single account to store their balance, but this may be too restrictive in some situations. For example, it's often useful to have separate accounts for "free" print quotas and cash payments.
The multiple personal accounts feature discussed in this chapter is an advanced feature that has been carefully architected with the assistance and feedback from leading Universities and Colleges from around the globe.
When multiple personal accounts are enabled, a user has multiple accounts with credit available for printing. Each account is a separate pool of credit that adheres to the following rules:
• Credit is deducted from the available funds in the order configured by the administrator.
• If the designated account does not have enough credit, the next account in sequence will be used until all of the credit is used.
• If a print job costs more than the total credit in all accounts, the job is disallowed.
From the perspective of the end-user little changes when multiple accounts are enabled:
• The total balance of all accounts is displayed in the user client, release station, and end-user web interface.
•
they do with a single account.
• The fact that there are multiple balances can optionally be effectively hidden from the user.
Important
Although the concept of multiple personal accounts is quite simple, the management may be complex depending on implementation. Readers are advised to read this chapter in full and conduct some planning before full deployment. Good print management in large organizations is hard enough, and multiple accounts if not implemented right could make it just that little bit harder!
32.1. Why use multiple personal accounts?
There are a number of reasons why a site might choose to enable multiple personal accounts, but the most common is the need to separate "free" print quotas from cash payments. Common reasons for considering multiple accounts are:
32.1.1. Separating Quota and Cash
via credit card using a payment gateway like PayPal or Authorize.Net. When cash payments and "free" quota are combined into a single account balance it is not possible to give cash refunds without potentially refunding quota amounts.
Using multiple accounts to separate "quotas" and "cash" has a number of benefits:
1.
Simplified auditing and tracking of cash payments and refunds.
2.
Allows for refunding of unused cash payments at the end of year or enrollment.
3.
Making cash payments does not interfere with "not to exceed" quota thresholds.
This configuration is discussed detail in Section 32.3.1, “Example 1: Separate Cash/Quota Accounts”.
526
Multiple Personal Accounts
32.1.2. Independently Managed Work Areas
In some more large and complex environments each department or faculty independently manage and control their own printer fleet. In these situations the departments may want to assign a "free" quota to their members/students that should only be used on their own printers. Any "free" quotas allocated from other departments must not be used on this department's printers. If the user adds cash to their account this may be used in any department.
In most environments this configuration is not required because the print policy is managed centrally. This is most useful when implementing a centralised PaperCut installation in an environment where the departments historically had independent control of print policy. Using this configuration can be the first phase in a transition to a fully centralised system.
32.2. Configuration
Enabling and configuring multiple personal accounts is quite simple. However before enabling this feature it is recommended that you read this section and understand the concepts involved.
32.2.1. Enabling Multiple Personal Accounts
To enable multiple personal accounts:
1.
Navigate to Options
→
Advanced
→
Go to multiple personal account setup.
2.
Enable the Enable multiple personal accounts option.
3.
The built-in default account is where initial credit is assigned and quota allocated.
Figure 32.1. Enabling Multiple Personal Accounts for the first time
4.
Press the Add Account button to add a new account. This will add a new account to the list with a blank description, and default options for priority and overdraft.
5.
Enter a descriptive name for the account. This can be changed at any time.
6.
Edit the account priority to change the order in which the account balances are used. Accounts at the top of the list (i.e. the lowest priority number) will be used first. The priority can be changed at any time. For more
information on priorities see Section 32.2.2, “How Account Priorities Work”.
7.
(Optional) Edit the overdraft value. This allows this account to go into negative. e.g. If the overdraft is set to
$5.00, then the account will be allowed to go to $5.00 into negative.
8.
Repeat these steps adding accounts as necessary. Take care to add only the accounts you require (See
Section 32.2.4, “Why can't I delete accounts?”).
9.
When the accounts are configured as required, press the Set Up Accounts button. This will start the process of creating the new accounts for all of your users.
32.2.2. How Account Priorities Work
When a user has multiple accounts it's important to have a well-defined order for how the balances are used. If one account is used for cash and the other for quotas, the quota credit should be used first before cash. The account
527
Multiple Personal Accounts priority defines this order. This is best explained with some examples.
The account priorities are configured with the "Default" account first and the "Cash" account second (as shown in the screenshot below).
Figure 32.2. Multiple Account Priorities
Example 1: If a user has $1.00 in each of the "Default" and "Cash" accounts, and a $0.25 job is printed the cost of the job is deducted from the "Default" account, leaving a balance of $0.75.
Example 2: If a user has $1.00 in each of the "Default" and "Cash" accounts, and a $1.30 job is printed the cost of the job split between both accounts. First, the $1.00 available in the "Default" account is used, then the remaining
$0.30 is deducted from the "Cash" account. The user is then left with $0.00 in the "Default" account and $0.70 in the
"Cash" account.
Whenever a print job is refunded, the credit is refunded to the accounts in the reverse order.
32.2.3. Configuring the Payment Accounts
When a user has multiple personal accounts, user payments may be configured to credit different accounts for different payment sources:
•
• Payment gateways (like PayPal or Authorize.Net),
• User transfers
• Other payments, including web cashier, value loaders, etc.
Figure 32.3. User payment accounts
To configure the "Cash/Payment" account:
1.
Navigate to Options
→
Advanced
→
Go to multiple personal account setup.
2.
Towards the bottom of the screen, select the accounts you'd like to use for each of the payment types using the
User payment accounts option.
528
Multiple Personal Accounts
3.
Press the Apply button.
32.2.4. Why can't I delete accounts?
Once an account has been configured and created it cannot be deleted. Once an account is created it may be used immediately by users for their printing activity. If the account could be subsequently deleted, any transaction associated with that account would also need to be deleted, resulting in a confusing transaction history for the user.
Although accounts cannot be deleted, they can be disabled. Disabling the account means that it is no longer available to the user, nor displayed in their account details. From the perspective of the user the account no longer exists, and any associated balance is also no longer available. If the account is later re-enabled any previous balances will be made available to the user again.
Caution
Because accounts can't be deleted it's prudent to carefully plan accounts and their use before deployment.
32.2.5. Other Options
By default the end-user web interface displays just the total of all of the user accounts. To display an itemized list of each of the account balances enable the option on Options
→
User Features
→
Itemize multiple personal
accounts, then press Apply.
If there is a need to change the available personal accounts or the order that they are used, the Advanced Printer
32.3. Configuration Examples
This section describes in detail how to set up PaperCut for the most common uses for multiple personal accounts.
32.3.1. Example 1: Separate Cash/Quota Accounts
In environments where users have both freely allocated quotas and the option for users to pay for printing it's useful
To configure multiple accounts for this situation:
1.
Navigate to Options
→
Advanced
→
Go to multiple personal account setup.
2.
Enable the Enable multiple personal accounts option.
3.
The "Default" (built-in) account is used for quotas. Rename it to something appropriates (e.g. "Quotas").
4.
Press the Add Account button to add a new account. This account will be used for user payments. Name it appropriately, and set the priority to a value higher than the default/built-in account. i.e. like the screenshot below.
529
Multiple Personal Accounts
Figure 32.4. Separate Cash and Quota accounts
It is important that the accounts are given this priority order. This way any freely allocated quotas will be used before using the cash payments. This allows a user to add credit to their account and know that it will only be used when they run out of allocated quota.
5.
Press the Set Up Accounts button to start applying the change.
6.
When the account setup is complete, select the "Cash" account as the account for user payments. To do this choose this account under the User payment accounts option.
7.
Press the Apply button.
At this point the system is ready to use. Any cash payments from TopUp/Pre-Paid Cards or Payment Gateways are added to the selected cash account. The quotas will be added to the default/built-in account. (Note: Site running a
Payment Gateway module released prior to version 10.5 may need to upgrade the gateway to leverage this setting.)
32.3.2. Example 2: Department/Faculty Quotas (Advanced)
A much more advanced configuration is required when different departments/faculties/areas want to each have their own quotas that are only available for use by their users on their printers. Department quotas are also often combined with user cash payments which can be used anywhere on site. For a description of this scenario see
Section 32.1.2, “Independently Managed Work Areas”.
One prominent PaperCut customer, Cambridge University in the UK uses this configuration. At Cambridge each of the independent schools/colleges want to allocate quotas to their students at enrollment. These quotas may only be used on the printers owned by the school. Cambridge also offers user-paid printing, and where the cash can be used on any printer across the campus. The multiple personal account feature in PaperCut has been designed to meet the demanding requirements at The University of Cambridge and other leading colleges.
This configuration requires the use of many advanced PaperCut features. This section gives a brief outline of how this is configured.
• Enable multiple personal accounts and create the accounts for each of the work-areas or departments required.
If users can also pay for printing, also create a cash account. The priority/order of the quota accounts is not important, as long as the "Cash" account appears last. The screenshot below shows a possible configuration.
Figure 32.5. Example of an advanced account setup
Press the Set Up Accounts button to start applying the change.
• When the account setup is complete, select the "Cash" account as the account for user payments. To do this choose this account under the User payment accounts option. Then press the Apply button.
• At this point all the accounts are enabled and can be used on any printers. To restrict the accounts that can be used on different printers, the Advanced Printer Scripting feature can be used (see Chapter 20, Advanced
530
Multiple Personal Accounts
Scripting)).
The advanced scripting provides a method
( actions.job.changePersonalAccountChargePriority
) that allows for changing both the accounts
For example, the following script snippet, shows how to limit the available accounts to only "Science Quotas" and
"Cash" (in that order).
actions.job.changePersonalAccountChargePriority(["Science Quotas", "Cash"]);
• Departments can allocate initial quotas at enrollment or periodically throughout the year using the web-service
APIs or server-command to adjust user balances. All the balances affecting APIs/commands have a parameter to specify which of the accounts to adjust/set. For example, to use server-command to set the balance of the
"Science Quotas" account to $10.00 for all members of the "Science Students" group: server-command set-user-account-balance-by-group "Science Students" 10.0 \
"Enrollment quota" "Science Quotas"
This technique can be integrated with existing student management systems to automate the allocation of free print quota at the time of enrollment.
For more information on web-service APIs or server-command
see Section A.3, “The XML Web Services API”
and Section A.1, “Server Commands (server-command)”.
With the power of Advanced Print Scripting and Multiple Personal Accounts much can be achieved. Large universities and colleges needing this level of flexibility also tend to have very competent IT staff. Take some time to bounce around some ideas. Here are a few:
• Use advanced print scripting to tune on/off access to accounts based on conditions such as group membership, time of day, device, etc.
• Automate account management tasks such as free quota assignment on course enrollment using scripts.
• Complex rules on which accounts are used and under which conditions, need to be clearly explained to users.
Take some time to document this and communicate policy with staff/students/members.
531
Chapter 33. Advanced Server Management
This chapter contains advanced configuration related to PaperCut's internal web server (powered by Apache Jetty).
The configuration options mentioned here should generally only be used as a reference for specific requirements, as some changes could negatively impact on system functionality.
33.1. Server Address
33.1.1. Server address presented to users
Some features in PaperCut require being able to create a link or address for the application server. One example of this is when using Email to Print - the verification email sent to users contains a link that they must click. This link must resolve to the PaperCut server both from the internet and from the local network.
The default address presented in these cases is an automatically detected IP address. In some cases this may not be suitable, for example where it needs to be resolved from the internet.
The recommended approach is to configure a DNS name for your PaperCut server that can be resolved and accessed wherever your users require it. This may involve creating a public/external DNS name and opening the appropriate ports in your firewall. After the name is configured, navigate to Options
→
Advanced
→
Server
Address
→
Server address presented to users, choose DNS name and enter your chosen (fully qualified) name.
33.1.1.1. Server port presented to users
In some circumstances, you may also need to customize the server HTTP port presented to users. An example scenario is when a reverse proxy server for WebAuth or Shibboleth SSO is placed in front of the PaperCut NG server. For this situation, PaperCut provides two advanced config keys to allow the user facing server port to be customized: system.network-port-http.user-facing and system.network-port-https.user-facing
. (See Section 15.10, “Using the Config Editor” for instructions on
using the Config Editor.)
33.1.2. Server address presented to external components
In some cases PaperCut will publish its address to external components (e.g. MFDs) to allow them to establish a connection back to the server. The published address is an automatically detected IP address by default. If your server has multiple IP addresses then the detected IP may not be suitable and may cause components to fail to connect.
To resolve this you can configure the network address (e.g. DNS name or IP address) that PaperCut publishes to
change the system.network-address to your chosen address.
This is configured separately from the Server address presented to users to provide the option to use an IP address for components and a DNS name for users (for example, to avoid DNS lookups on devices that do not cache the result).
PaperCut Site Servers can have their published network address configured by navigating to Sites
→
(site name)
→
Configuration
→
Network address used by devices.
33.2. Changing the network interface that PaperCut listens on
PaperCut will listen on all available network interfaces by default. If your server has multiple IP addresses (i.e. is multi-homed), PaperCut will accept connections to all these addresses. Alternatively, it may be configured to listen on a single, defined interface. To configure PaperCut to listen on a single network interface:
1.
Open
[app-path]/server/server.properties
in a text editor.
2.
Add a new line: server.listen-interface=1.2.3.4
532
Advanced Server Management where
1.2.3.4
is the (static) IP address of the network interface for PaperCut to listen on.
3.
Restart the service PaperCut Application Server
33.3. Overriding the "Host" header for redirects
PaperCut's web server requires the ability to redirect users to new pages. When performing a redirect, the target location is based on the Host header that the web browser requested. If the host header is omitted (e.g. by manually crafting an HTTP request), the target location is based on the server's own hostname or IP address. In a NAT environment this may not be ideal if the server's IP address is considered private.
This may also apply if security audit software reports Web Server HTTP Header Internal IP Disclosure or similar.
To configure PaperCut to always forward to a specified host:
1.
Open
[app-path]/server/server.properties
in a text editor.
2.
Add a new line: server.force-host-header=printing.uni.edu
where printing.uni.edu
is the fully qualified host name that all users will access PaperCut on.
3.
Restart the service PaperCut Application Server
4.
Test access to the web interface (using both HTTP and HTTPS if applicable).
Note that when this option is used, PaperCut should not be accessed using any hostname other than the one configured. Doing so may cause problems.
533
Appendix A. Tools - database, server-command scripting, and APIs
(Advanced)
This appendix outlines the command line tools and advanced programming tools that come with PaperCut NG.
Using these tools has been discussed throughout this manual, however this provides a reference guide to these tools and their use.
Caution
The advanced tools provided with PaperCut NG are very powerful and offer opportunities for all manner of customizations and enhancements. However, if used incorrectly, these tools could lead to unexpected results. Many of the advanced tools are written for software and script developers. It is expected that readers intending to use advanced tools are comfortable with using the command-prompt, and developing system management and server monitoring programs.
A.1. Server Commands (server-command)
The server-command tool provides access to dozens of server operations ranging from user management, system maintenance, account manipulation and printer control. The server-command tool is ideal for controlling the
PaperCut NG Application Server via the command-line or automating via scripts.
Some examples of how an Administrator may choose to use the server-command tool:
• Scheduling of online backups and data snapshots.
• Scheduling user and/or group synchronization tasks.
• Automating the addition of new users after the accounts are added to the network.
• Performing account transactions such as adding funds/quota to user accounts.
• Automating user account creation using custom scripts.
• Disabling/Enabling printers.
• Disabling/Enabling printing for users.
• Controlling user restriction levels.
• Managing shared accounts.
The server-command program is a command-line tool. It accepts the commands as arguments and outputs the results of the command on the console (standard-out). For security reasons only users with read access to the server.properties
(normally only the
Administrators group) have rights to execute the commands.
Typical use on a Windows system:
Add $10.00 to a user named 'testuser':
C:\> cd [app-path]\server\bin\win
C:\> server-command adjust-user-account-balance "testuser" 10.00 \
"Added $10.00 to your account"
Note: backslash indicates text should be on the same line.
A.1.1. Accessing Server Commands remotely
534
Tools - database, server-command scripting, and
APIs (Advanced)
Server commands can also be called remotely using standard remote command tools.
A.1.1.1. On Windows
Use PsExec [http://technet.microsoft.com/en-us/sysinternals/bb897553.aspx] - a remote command program provided by the Sysinternals team at Microsoft. For example (all on one line): psexec.exe \\remoteserver \
"C:\Program Files\PaperCut NG\server\bin\win\server-command.exe" \ disable-printer printsrv1 labprinter -1
A.1.1.2. On Linux/Novell/Mac
Use SSH [http://en.wikipedia.org/wiki/Secure_Shell] - a secure remote command/shell program. SSH can be run non-interactively in scripts with the use of an authorized public key added under the papercut account's
~/.ssh/authorized_keys list. For example (all on one line): ssh papercut@remoteserver \
"/home/papercut/server/bin/linux-[x64|i686]/server-command \ disable-printer printsrv1 labprinter -1"
A.1.2. Available Commands
A full list of commands is available via server-command --help
.
Usage: server-command COMMAND [ARGS...]
COMMAND : The server command name.
ARGS : A list of arguments to supply to the command.
COMMANDS: user-exists <username>
Test to see if a user exists.
<username> - the username to test.
get-user-account-balance <username> [<account>]
Get a user's current account balance.
<username> - the user's username.
[<account>] - Optional personal account name. Only used when multiple personal accounts are enabled. Leave blank to get total balance.
get-user-property <username> <property>
Gets a user property.
<username> - the name of the user.
<property> - the name of the property to get. Valid properties include: balance - the user's current account balance primary-card-number - the user's primary card number secondary-card-number - the user's secondary card number card-pin - the user's card pin number default-shared-account - the user's default shared account name auto-shared-account - the user's automatically selected shared account name department - the user's department disabled-net - whether or not the user's internet access is currently disabled disabled-print - whether or not the user's printing is currently disabled email - the user's email full-name - the user's full name notes - notes for the user office - the user's office print-stats.job-count - the total print job count for the user
535
Tools - database, server-command scripting, and
APIs (Advanced) print-stats.page-count - the total printed page count for the user net-stats.data-mb - the internet data used by the user (in MB) net-stats.time-hours - the internet time used by the user (in hours) restricted - whether or not the user is currently restricted account-selection.mode - the user's current account selection mode account-selection.can-charge-personal - whether or not the user can charge to their personal account account-selection.can-charge-shared-from-list - whether or not the user can charge to a shared account, selected from a list account-selection.can-charge-shared-by-pin - whether or not the user can charge to a shared account, selected by PIN other-emails - the user's other emails username-alias - the user's alias.
Only used when username aliasing is enabled.
set-user-property <username> <property> <value>
Sets a user property.
<username> - the name of the user.
<property> - the name of the property to set. Valid properties and values include: balance - the user's current account balance (a decimal number) primary-card-number - the user's card number (any text) secondary-card-number - the user's secondary card number (any text) card-pin - the user's card pin number (any text) default-shared-account - the user's default shared account name department - the user's department (any text) disabled-net - whether or not the user's internet access is currently disabled (TRUE or FALSE) disabled-print - whether or not the user's printing is currently disabled (TRUE or FALSE) email - the user's email (an email address, or any text) full-name - the user's full name (any text) notes - notes for the user (any text) office - the user's office (any text) password - the user's password (for internal users only) (any text) restricted - whether or not the user is currently restricted
(TRUE or FALSE) other-emails - the user's other emails
(a comma separated list)
Use blank to clear all other emails username-alias - the user's alias.
Only used when username aliasing is enabled.
<value> - the value to set (see <property> for valid values).
adjust-user-account-balance <username> <adjustment> <comment> [<account>]
Adjust a user's account balance.
<username> - the user's username.
<adjustment> - the adjustment amount as a number. +ve or -ve.
<comment> - a comment to be associated with the transaction.
[<account>] - Optional personal account name. Only used when multiple personal accounts are enabled.
adjust-user-account-balance-if-available <username> <adjustment> \
<comment> [<account>]
Adjust a user's account balance if there is enough credit available.
<username> - the user's username.
<adjustment> - the adjustment amount as a number. +ve or -ve.
<comment> - a comment to be associated with the transaction.
[<account>] - Optional personal account name. Only used when multiple personal accounts are enabled.
adjust-user-account-balance-if-available-leave-remaining <username> \
<adjustment> <leave-remaining> <comment> [<account>]
Adjust a user's account balance if there is enough credit available to leave the given amount available in the account.
<username> - the user's username.
<adjustment> - the adjustment amount as a number. +ve or -ve.
<leave-remaining> - the amount to leave in the account.
<comment> - a comment to be associated with the transaction.
[<account>] - Optional personal account name. Only used when multiple
536
Tools - database, server-command scripting, and
APIs (Advanced) personal accounts are enabled.
adjust-user-account-balance-by-group <group> <adjustment> <comment> \
[<account>]
Adjust the account balance for all users in a group.
This process happens in the background.
<group> - the group for which all users' accounts are to be adjusted.
<adjustment> - the adjustment amount as a number. +ve or -ve.
<comment> - a comment to be associated with the transaction.
[<account>] - Optional personal account name. Only used when multiple personal accounts are enabled.
adjust-user-account-balance-by-group-up-to <group> <adjustment> <limit>
<comment> [<account>]
Adjust the account balance for all users in a group, but don't increase user balance beyond the given limit.
This process happens in the background.
<group> - the group for which all users' accounts are to be adjusted.
<adjustment> - the adjustment amount as a number. Must be +ve.
<limit> - don't increase user balance beyond this limit.
<comment> - a comment to be associated with the transaction.
[<account>] - Optional personal account name. Only used when multiple personal accounts are enabled.
set-user-account-balance <username> <balance> <comment> [<account>]
Set a user's account balance to a set value.
<username> - the user's username.
<balance> - set the account to this value. +ve or -ve.
<comment> - a comment to be associated with the transaction.
[<account>] - Optional personal account name. Only used when multiple personal accounts are enabled.
set-user-account-balance-by-group <group> <balance> <comment> [<account>]
Set the balance for each member of a group to the given value.
This process happens in the background.
<group> - the group for which all users' balance is to be set.
<balance> - the value to set all users' balance to. +ve or -ve.
<comment> - a comment to be associated with the transaction.
[<account>] - Optional personal account name. Only used when multiple personal accounts are enabled.
reset-user-counts <username> <reset_by>
Reset the page and job counts associated with a user.
<username> - the user's username.
<reset_by> - name of the user/script/process resetting the counts.
re-apply-initial-user-settings <username>
Re-applies initial settings on the user. Initial user settings are based on group membership.
<username> - the user's username.
disable-printing-for-user <username> <minutes_disabled>
Disable printing for a user for a set period of time.
<username> - the name of the user to disable printing for.
<minutes_disabled> - the time in minutes to disable. -1 indicates forever.
add-new-user <username>
Trigger the process of adding a new user account. Assuming the user exists in the OS/Network/Domain user directory, the account will be created with the correct initial settings as defined by the rules set up in the admin interface under the Groups section.
<username> - the user's system username.
rename-user <current_username> <new_username>
Rename the given existing user. Use this method with care. Renaming a user should be performed in conjunction with renaming the user in the
OS/Network/Domain.
<current_username> - the name of the user to rename.
<new_username> - the user's new name.
537
Tools - database, server-command scripting, and
APIs (Advanced) delete-existing-user <username>
Delete a user account from the system.
Use this method with care.
Calling this will permanently delete the user account from the user list (print history records remain).
<username> - the user's system username.
add-new-internal-user <username> <password> <full_name> <email> <card-id>
<pin>
Create a new internal user.
Username and password are required.
Other properties may be omitted.
Properties may be changed after creation using 'set-user-property'.
For more information about internal users
See the user manual chapter 'Managing Guests and Internal Users'.
<username> - (required) the username of the new internal user.
<password> - (required) user's password.
<full_name> - (optional) user's full name.
<email> - (optional) user's email address.
<card-id> - the user's card or identity number.
<pin> - the user's card/id PIN.
look-up-user-name-by-id-no <id-no>
Looks up the user with the given user id number and prints out their user name.
If no match was found an empty line is printed out.
<id-no> - The user id number to look up.
look-up-user-name-by-card-no <card-no>
Looks up the user with the given user card number and prints out their user name.
If no match was found an empty line is printed out.
<card-no> - The user card number to look up.
add-user-to-group <username> <group>
Add a user to the specified group. It changes the group membership within the application not in the OS/Network/Domain user directory.
<username> - the name of the user.
<group> - the name of the group to which the user needs to be added.
remove-user-from-group <username> <group>
Remove a user from the specified group. It changes the group membership within the application not in the OS/Network/Domain user directory.
<username> - the name of the user.
<group> - the name of the group from which the user needs to be removed.
add-admin-access-user <username>
Add a user as an admin with default admin rights.
<username> - the name of the user.
remove-admin-access-user <username>
Remove an admin user from the list of admins.
<username> - the name of the user.
add-admin-access-group <groupname>
Add a group as an admin group with default admin rights.
<groupname> - the name of the group.
remove-admin-access-group <groupname>
Remove a group from the list of admin groups.
<groupname> - the name of the group.
set-user-account-selection-auto-select-shared-account <username>
<account_name>
<charge_personal>
Sets a user's account selection to charge to a single shared account.
<username> - the name of the user.
<account_name> - Full name of the shared account to charge to.
<charge_personal> - whether or not personal account should be charged.
(TRUE or FALSE) set-user-account-selection-auto-charge-personal <username>
538
Tools - database, server-command scripting, and
APIs (Advanced)
Sets a user's account selection to automatically charge to personal.
account.
<username> - the name of the user.
set-user-account-selection-standard-popup <username> <allow_personal>
<allow_list_selection>
<allow_pin_code>
<allow_printing_as_another_user>
<charge_to_personal>
[<default_shared_account>]
Sets a user's account selection to standard account selection popup.
<username> - the name of the user.
<allow_personal> - allow user to charge to personal account.
<allow_list_selection> - allow user to select a shared account from list. (TRUE or FALSE)
<allow_pin_code> - allow user to select a shared account using pin.
<allow_printing_as_another_user> - allow user to print as another user.
<charge_to_personal> - when shared account is selected charge to personal account. (TRUE or FALSE)
[<default_shared_account>] - Optional default shared account list-user-accounts
List the names of all the user accounts in the system, sorted by username, one per line.
get-total-users
Gets a count of all the users in the system.
list-shared-accounts
List the names of all the shared accounts in the system, sorted by shared account name, one per line.
list-user-shared-accounts <username> [<ignoreAccountMode>]
List the names of all the shared accounts accessible by the given user sorted by account name, one per line.
<username> - User for which to list accounts
[<ignoreAccountMode>] - Optional. Specify TRUE to ignore user's account selection mode. (TRUE or FALSE) shared-account-exists <account_name>
Test to see if a shared account exists.
<account_name> - the shared account name to test.
get-shared-account-account-balance <account_name>
Get shared account's current account balance.
<account_name> - the shared account's full name.
get-shared-account-property <account_name> <property>
Gets a shared account property.
<account_name> - the name of the user.
<property> - the name of the property to get. Valid properties include: access-groups - the shared account's access groups
(a comma separated list)
Use blank to clear all groups access-users - the shared account's access users
(a comma separated list)
Use blank to clear all users balance - the shared account's current balance comment-option - the shared account's commenting option disabled - whether or not the shared account is currently disabled invoice-option - the shared account's invoicing option notes - notes for the shared account pin - the shared account's PIN restricted - whether or not the shared account is currently restricted set-shared-account-property <account_name> <property> <value>
Sets a shared account property.
<account_name> - the name of the shared account.
<property> - the name of the property to set. Valid properties and
539
Tools - database, server-command scripting, and
APIs (Advanced) values include: access-groups - the shared account's access groups)
(a comma separated list) access-users - the shared account's access users
(a comma separated list) balance - the shared account's current balance (a decimal number) comment-option - the shared account's commenting option. One of:
NO_COMMENT - no comment may be entered
COMMENT_REQUIRED - a comment must be entered
COMMENT_OPTIONAL - the user may enter a comment or not disabled - whether or not the shared account is currently disabled
(TRUE or FALSE) invoice-option - the shared account's invoicing option. One of:
ALWAYS_INVOICE - print jobs will always be invoiced
NEVER_INVOICE - print jobs will never be invoiced
USER_CHOICE_ON - the user can choose (default on/yes)
USER_CHOICE_OFF - the user can choose (default off/no) notes - notes for the shared account (any text) pin - the shared account's PIN (any text, must be unique) restricted - whether or not the shared account is currently restricted (TRUE or FALSE)
<value> - the value to set (see <property> for valid values).
adjust-shared-account-account-balance <account_name> <adjustment> <comment>
Adjust a shared account's account balance.
<account_name> - the shared account's full name.
<adjustment> - the adjustment amount as a number. +ve or -ve.
<comment> - a comment to be associated with the transaction.
set-shared-account-account-balance <account_name> <balance> <comment>
Set a shared account's balance to a set value.
<account_name> - the shared account's full name.
<balance> - set the account to this value. +ve or -ve.
<comment> - a comment to be associated with the transaction.
add-new-shared-account <shared_account_name>
Add a new shared account.
<shared_account_name> - the name of the shared account.
rename-shared-account <curr_shared_account_name> <new_shared_account_name>
Rename an existing shared account.
<curr_shared_account_name> - Current shared account name. Use a '\' to denote a subaccount e.g.: 'parent\sub'
<new_shared_account_name> - New shared account name.
delete-existing-shared-account <shared_account_name>
Delete a shared account from the system.
Use this method with care.
Calling this will permanently delete it from the shared account list
(print history records will remain).
<shared_account_name> - the name of the shared account to delete.
add-shared-account-access-user <shared_account_name> <username>
Allow the given user access to the given shared account without using a pin.
<shared_account_name> - the name of the shared account to allow access to.
<username> - the name of the user to give access to.
add-shared-account-access-group <shared_account_name> <group_name>
Allow the given group access to the given shared account without using a pin.
<shared_account_name> - the name of the shared account to allow access to.
<group_name> - the name of the group to give access to.
remove-shared-account-access-user <shared_account_name> <username>
Revoke the given user'- access to the given shared account.
<shared_account_name> - the name of the shared account to revoke access to.
<username> - the name of the user to revoke access for.
540
Tools - database, server-command scripting, and
APIs (Advanced) remove-shared-account-access-group <shared_account_name> <group_name>
Revoke the given group's access to the given shared account.
<shared_account_name> - the name of the shared account to revoke access to.
<group_name> - the name of the group to revoke access for.
get-printer-property <server_name> <printer_name> <property>
Gets a printer property.
<server_name> - the name of the server the printer is hosted on.
<printer_name> - the name of the printer.
<property> - the name of the property to get. Valid properties include: disabled - whether or not the printer is currently disabled print-stats.job-count - the total print job count for this printer print-stats.page-count - the total printed page count for this printer cost-model - the cost model used by the printer (e.g. SIMPLE) custom-field-1 - the value for custom field 1 if set.
custom-field-2 - the value for custom field 2 if set.
custom-field-3 - the value for custom field 3 if set.
custom-field-4 - the value for custom field 4 if set.
custom-field-5 - the value for custom field 5 if set.
custom-field-6 - the value for custom field 6 if set.
set-printer-property <server_name> <printer_name> <property> <value>
Sets a printer property.
<server_name> - the name of the server the printer is hosted on.
<printer_name> - the name of the printer.
<property> - the name of the property to set. Valid properties and values include: disabled - whether or not the printer is currently disabled
(TRUE or FALSE) custom-field-1 - the value for custom field 1 custom-field-2 - the value for custom field 2 custom-field-3 - the value for custom field 3 custom-field-4 - the value for custom field 4 custom-field-5 - the value for custom field 5 custom-field-6 - the value for custom field 6 override-user-level-settings - whether or not printer should override user level settings.
(TRUE or FALSE) override-user-level-settings-charge-to - the name of the shared account. Use "[personal]" for personal account. Use blank to disable charge to settings.
<value> - the value to set (see <property> for valid values).
list-printers
List the names of all the printers in the system, sorted by printer name, one per line.
set-printer-cost-simple <server_name> <printer_name> <cost_per_page>
Sets the printer's page cost (using SIMPLE charging model).
<server_name> - the name of the server the printer is hosted on.
<printer_name> - the name of the printer.
<cost_per_page> - the cost per page (simple charging model) get-printer-cost-simple <server_name> <printer_name>
Get the printer's page cost (using SIMPLE charging model).
<server_name> - the name of the server the printer is hosted on.
<printer_name> - the name of the printer.
reset-printer-counts <server_name> <printer_name> <reset_by>
Reset the page and job counts associated with a printer.
<server_name> - the name of the server hosting the printer.
<printer_name> - the printer's name.
<reset_by> - name of the user/script/process resetting the counts.
add-printer-group <server_name> <printer_name> <printer_group_name>
541
Tools - database, server-command scripting, and
APIs (Advanced)
Add a printer to a single printer group in addition to existing printer group membership.
<server_name> - the name of the server hosting the printer.
<printer_name> - the printer's name.
<printer_group_name> name of a printer group.
set-printer-groups <server_name> <printer_name> <printer_group_names>
Set the printer groups a printer belongs to, overwriting any existing group membership.
<server_name> - the name of the server hosting the printer.
<printer_name> - the printer's name.
<printer_group_names> - a comma separated list of printer group names.
To clear all group association set to "".
enable-printer <server_name> <printer_name>
Enable a printer.
<server_name> - the name of the server hosting the printer.
<printer_name> - the printer's name.
disable-printer <server_name> <printer_name> <minutes_disabled>
Disable a printer for a set period of time.
<server_name> - the name of the server hosting the printer.
<printer_name> - the printer's name.
<minutes_disabled> - the time in minutes to disable. -1 indicates forever.
delete-printer <server_name> <printer_name>
Delete a printer.
<server_name> - the name of the server hosting the printer.
<printer_name> - the printer's name. Use "[All Printers]" to delete all printers on the specified server.
rename-printer <server_name> <printer_name> <new_server_name>
<new_printer_name>
Rename a printer. This can be useful after migrating a print queue or print server (i.e. the printer retains its history and settings under the new name). Note that in some cases case sensitivity is important, so care should be taken to enter the name exactly as it appears in the OS.
<server_name> - the existing printer's server name
<printer_name> - the existing printer's queue name
<new_server_name> - the new printer's server name
<new_printer_name> - the new printer's queue name add-printer-access-group <server_name> <printer_name> <group_name>
Adds the user group to the printer's access group list.
<server_name> - the printer's server name
<printer_name> - the printer's queue name
<group_name> - the name of the user group that needs to be added.
remove-printer-access-group <server_name> <printer_name> <group_name>
Removes the user group from the printer's access group list.
<server_name> - the printer's server name
<printer_name> - the printer's queue name
<group_name> - the name of the user group that needs to be removed.
add-new-group <group_name>
Add a new group to the system's group list. The group should already exist in network directory.
<group_name> - The name of the group to add.
sync-group <group_name>
Syncs an existing group with the configured directory server, updates group membership in the system.
<group_name> - The name of the group to sync.
remove-group <group_name>
Removes the group.
<group_name> - The name of the group to remove.
get-user-groups <user_name>
542
Tools - database, server-command scripting, and
APIs (Advanced)
Retrieves all groups a single user belongs to.
<user_name> - The name of the user to query.
list-user-groups
List the names of all the user groups in the system, sorted by groupname, one per line.
group-exists <group_name>
Test to see if a group exists.
<group_name> - the group name to test.
set-group-quota <group_name> <quota_amount> <period> <quota_max_accum>
<group_name> - the name of the group to set.
<quota_amount> - the quota amount.
<period> - the schedule period (i.e. DAILY, WEEKLY, MONTHLY).
<quota_max_accum> - the quota maximum accumulation amount. Set to
0.0 to have no limit.
get-group-quota <group_name>
Get the group quota allocation settings on a given group.
Returns the quota amount, the schedule period and the quota maximumn accumulation amount.
<group_name> - the name of the group to get.
use-card <user_name> <card_number>
Redeem a card and place the credit on the user's account.
<user_name> - the name of the user with the account to credit.
<card_number> - the number of the card to use.
perform-online-backup
Start an online backup.
The back file is written to
~/server/data/backups. as a dated, zipped XML file. This process happens in the background.
perform-group-sync
Start the process of synchronizing the system's group membership with the OS/Network/Domain's group membership. A call to this method will commence the sync process and the operation will complete in the background.
perform-user-and-group-sync
Start a full user and group synchronization. This is equivalent to pressing the "Synchronize Now" button in the admin interface. No existing users will be removed. Whether or not full details for existing users will be updated depends on the current user/group sync settings as defined in the admin interface. A call to this method will commence the sync process and the operation will complete in the background.
perform-user-and-group-sync-advanced <delete_old_users> <update_details>
An advanced version of the user and group synchronization process providing control over the sync settings. A call to this method will commence the sync process and the operation will complete in the background.
<delete_old_users> - set to TRUE remove old users, else FALSE.
<update_details> - set to TRUE if existing users details (e.g. email, full-name, etc. ) are to be updated.
add-new-users
Calling this method will start a specialized user and group synchronization process optimized for tracking down adding any new users that exist in the OS/Network/Domain user directory and not in the system. Any existing user accounts will not be modified. A group synchronization will only be performed if new users are actually added to the system.
is-task-complete
Returns TRUE if a long running task such as perform-group-sync, perform-user-and-group-sync, or add-new-users has completed.
get-task-status
543
Tools - database, server-command scripting, and
APIs (Advanced)
Returns status information such as progress, completion status and, error messages, on the current or last run long running task such as perform-group-sync, perform-user-and-group-sync, or add-new-users.
batch-import-shared-accounts <import_file> <test>
<delete_non_existent_accounts>
Import the shared accounts contained in the given tab-delimited import file.
<import_file> - the import file location.
<test> - (TRUE or FALSE) If TRUE, perform a test only. The printed statistics will show what would have occurred if testing wasn't enabled. No accounts will be modified.
<delete_non_existent_accounts> - (TRUE or FALSE) If TRUE, accounts that do not exist in the import file but exist in the system will be deleted.
If FALSE, they will be ignored.
batch-import-users <import_file> <create_new_users>
Import the users contained in the given tab-delimited import file.
See the user manual chapter 'Batch User Data Import and Update' for a description of the file format.
<import_file> - the import file location.
<create_new_users>
If TRUE, users only existing in the import file will be newly created, otherwise ignored.
batch-import-internal-users <import_file> <overwrite_existing_passwords>
<overwrite_existing_pins>
Import the internal users contained in the given tab-delimited import file.
See the user manual chapter 'Managing Guests and Internal Users' for a description of the file format.
<import_file> - the import file location.
<overwrite_existing_passwords> (optional, default TRUE) - (TRUE or
FALSE) If TRUE, passwords from the import file will overwrite existing passwords where a user already has a has a password set.
If FALSE, existing passwords will not be changed.
<overwrite_existing_pins> (optional, default TRUE) - (TRUE or FALSE) If
TRUE, PINs from the import file will overwrite existing PINs where a user already has a has a PIN set.
If FALSE, existing PINs will not be changed.
batch-import-user-card-id-numbers <import_file> <overwrite_existing_pins>
Import the user card/ID numbers and PINs contained in the given tab-delimited import file.
See the user manual chapter 'Advanced User
Management' for a description of the file format).
<import_file> - the import file location.
<overwrite_existing_pins> (optional, default TRUE) - (TRUE or FALSE) If
TRUE, PINs from the import file will overwrite existing PINs where a user already has a has a PIN set.
If FALSE, existing PINs will not be changed.
create-user-client-accounts-file
Saves a file containing shared accounts data for the user client.
See the manual for more information on how this feature can be used.
The file will be saved on the server to the location:
[app-path]\server\data\client\client-accounts.dat
If this file already exists it will be over-written.
get-config <config-name>
Gets the value of the given config value printing the result.
If the config value does not exist, a blank string is displayed.
<config-name> - the name of the config value to get.
set-config <config-name> <config-value>
Sets the value of the give config item.
NOTE: Take care updating config values. You may cause serious problems which can only be fixed by reinstallation of the application. Use the set-config command at your own risk.
<config-name> - the name of the config value to set.
544
Tools - database, server-command scripting, and
APIs (Advanced)
<config-value> - the value to set.
process-job <job-details>
Takes the details of a job and logs and charges as if it were a "real" job.
Jobs processed via this method are not susceptible to filters, pop-ups, hold/release queues etc., they are simply logged.
See the user manual section "Importing Job Details" for more information and the format of <job-details>.
<job-details> - the details of the job to log.
run-command command-name [command args]
Runs a custom command on the server. By default the server does not include any custom commands.
The command arguments depend on the custom command being run.
Tip
server-command is ideal for scripting via batch files or shell scripts. Some example scripts can be found at
[app-path]/server/examples/scripting/
.
Administrators wishing to control PaperCut NG using a programming language such as C#, Java,
Visual Basic, Perl, Ruby or Python should consider the XML Web Services APIs. All commands available via the server-command tool are also accessible via calls to the Web Services layer.
More information on the XML Web Services API is available in Section A.3, “The XML Web Services
Tip
Checking for errors: generally server-command will return an exit value of 0. When writing your script you should check the string value that server-command prints on standard output instead.
server-command will return a non-zero return value if it detects an error with the parameters passed on the command line.
Tip
Some commands (e.g.
batch-import-internal-users
) expect values that are true or false
. In this case the command parameter is compared to the value true using a case insensitive compare, all other values are assumed to be false
.
A.2. Database Tool (db-tools)
The db-tools command-line tool provides a variety of functionality manipulating the PaperCut NG database and data. The tool is located in
[app-path]/server/bin/<platform>/ and needs to be executed from a command prompt. The syntax of the command is: db-tools command [options]
The valid commands are:
545
Tools - database, server-command scripting, and
APIs (Advanced)
• export-db
- export/backup the database data
• import-db
- import/restore the database data
• init-db
- create tables and initial data in a new database
• delete-old-logs
- delete old log data (transaction, print, app log, etc) db-tools is a command-line application accessed via the Command Prompt on Windows, or a Command Shell
(e.g. bash or a terminal) on Linux and Mac. On Linux or Mac the command must be run as the papercut user.
Example use on the Apple Mac: sudo su - papercut db-tools import-db -f /Users/bob/papercut-backup.zip
A Windows example is: cd "C:\Program Files\PaperCut NG\server\bin\win\" db-tools delete-old-logs 90
An Apple Mac example is: sudo su - papercut cd "/Applications/PaperCut NG/server/bin/mac/" db-tools import-db /Users/bob/papercut-backup.zip
db-tools needs exclusive access to the database. It is important that any PaperCut NG services and processes are stopped before executing any commands. Failure to do so will result in a "database in use" error message. The db-tools command is a powerful low-level utility and its use on a production system should be carefully considered. The available commands are discussed in detail below.
A.2.1. export-db Command
The export-db command exports the data from the database. The application server must be stopped before performing the export. The syntax and options for the export-db command are:
Tip
If you want to perform an online backup without stopping the application server you can use the inbuilt perform-online-backup server command.
More information on the server commands is available in Section A.1, “Server Commands
usage: db-tools export-db [options]
-d,--dir <dir> Exports the database to the given directory.
-f,--file <file> Exports the database to the given file.
-h,--help Displays this help.
If no options are specified then the database export file is created in the
[app-path]\server\data\backups directory and the file is named export-[date-time].zip
.
The
--dir option is used to override the default backup directory. The filename will still be named export-[date-time].zip
.
The
--file option is used to specify the full path and filename where the backup is saved.
546
Tools - database, server-command scripting, and
APIs (Advanced)
Caution
If the directory or filename parameters contains space, then the argument needs to be quoted.
A.2.2. import-db Command
The import-db command imports the data (from a previous export) into the database. The application server must be stopped to perform the import. The syntax and options for the import-db command are: usage: db-tools import-db [options] import-file
-f,--force Deletes any existing data before loading the data.
-h,--help Displays this help.
The
--force option is required when the data is loaded into a database that already contains data. In this situation, the force option indicates that existing data will be deleted first.
Caution
If the import-file contains spaces this argument will need to be quoted.
A.2.3. init-db Command
The init-db command initializes a database, creating the required tables and initial data. The application server must be stopped before you initialize the database. The syntax and options for the init-db command are: usage: db-tools init-db [options]
-f,--force Re-initializes the database even if it already exists.
-h,--help Displays this help.
The
--force option is required to initialize a database that already contains the tables and data. In this case the force option will drop the existing tables before recreating the tables.
A.2.4. delete-old-logs Command
The delete-old-logs is used to delete old log data from the system. This command will permanently delete the following data.
• Printer usage logs - Record all print history and statistics
• Account transactions - Record all adjustments to user and shared accounts
• Application logs - Record application status and error messages usage: db-tools delete-old-logs [options] delete-older-than-days
-n,--non-interactive Perform deletion without confirmation.
-h,--help Displays this help.
The
--non-interactive option will perform the deletion without confirmation from the user. This can be useful when automating this deletion through a scheduled task or cron job.
The delete-older-than-days option determines what data will be deleted. If delete-older-than-days is
547
Tools - database, server-command scripting, and
APIs (Advanced)
90, then all log data more than 90 days old will be deleted. A value of zero (0) will remove all historical log data from the system.
A.3. The XML Web Services API
Any quality software product comes with a comprehensive API for deep integration, and PaperCut is no exception!
Our industry standard Web Services API allows you to integrate with PaperCut with a programming language of your choice. Web Services data is transmitted over standard HTTP or HTTPS and uses standardized XML mark-up.
There are two main Web Services implementations used for Remote Procedure Call (RPC):
• SOAP/WSDL
• XML-RPC
PaperCut NG uses XML-RPC. XML-RPC is a lightweight web services implementation and has good support for all major programming and scripting languages such as C#, Java, Visual Basic, Perl, Ruby and Python.
API methods are accessed by the URL http://[server_name]:9191/rpc/api/xmlrpc
, or https://[server_name]:9192/rpc/api/xmlrpc for secure connections. You will also need to ensure you
Method
api.isUserExists
api.getUserAccountBalance
api.getUserProperty
api.getUserProperties
api.setUserProperty
api.setUserProperties
api.adjustUserAccountBalance
api.adjustUserAccountBalanceIfAvailable
api.adjustUserAccountBalanceIfAvailableLeaveRemaining
api.adjustUserAccountBalanceByGroup
api.adjustUserAccountBalanceByGroupUpTo
api.setUserAccountBalance
api.setUserAccountBalanceByGroup
api.resetUserCounts
api.reapplyInitialUserSettings
api.disablePrintingForUser
api.addNewUser
Description
Test to see if a user exists in the system/database.
Get the user's current account balance.
Gets a user property. Properties include the user's full name, department, email, notes, office and restriction status among others.
Get multiple user properties at once. Properties include the user's full name, department, email, notes, office and restriction status among others.
Sets a user property. Properties include the user's full name, department, email, notes, office, password (for internal users) and restriction status among others.
Set multiple user properties at once. Properties include the user's full name, department, email, notes, office, password (for internal users) and restriction status among others.
Adjust a user's account balance by an adjustment amount. An adjustment may be positive (add to the user's account) or negative (subtract from the account).
Adjust a user's account balance if there is enough credit available.
Adjust a user's account balance if there is enough credit available to leave the given amount available in the account.
Adjust the account balance for all users in a group by an adjustment amount. An adjustment may be positive (add to the user's account) or negative (subtract from the account).
Adjust the account balance for all users in a group by an adjustment amount, but not above the given limit. An adjustment may be positive (add to the user's account) or negative (subtract from the account).
Set the balance on a user's account to a set value. This is conducted as a transaction.
Set the balance for each member of a group to the given value.
Reset the counts (pages and job counts) associated with a user account.
Re-applies initial settings on the user. Initial user settings are based on group membership.
Disable printing for a user for selected period of time.
Triggers the process of adding a new user account defined by a given username . Assuming the user exists in the OS/Network/Domain user directory,
548
Method
api.renameUserAccount
api.getUserGroups
api.deleteExistingUser
api.addNewInternalUser
Tools - database, server-command scripting, and
APIs (Advanced) api.lookUpUserNameByIDNo
api.lookUpUserNameByCardNo
api.addAdminAccessUser
api.removeAdminAccessUser
api.addAdminAccessGroup
api.removeAdminAccessGroup
api.setUserAccountSelectionAutoSelectSharedAccount
api.setUserAccountSelectionAutoChargePersonal
api.setUserAccountSelectionStandardPopup
api.listUserAccounts
Description
the account will be created with the correct initial settings as defined by the rules set up in the admin interface under the Group's section. Calling this method is equivalent to triggering the "new user" event when a new user performs printing for the first time.
Rename a user account. Useful when the user has been renamed in the domain
/ directory, so that usage history can be maintained for the new username. This should be performed in conjunction with a rename of the user in the domain / user directory, as all future usage and authentication will need to use the new username.
Retrieves all groups a single user is a member of.
Delete/remove an existing user from the user list. Use this method with care.
Calling this will perminently delete the user account from the user list (print and transaction history records remain).
Creates and sets up a new internal user account.
In PaperCut NG all internal usernames must only contain characters that can be printed (e.g. not newline
) and must not contain
/
,
\ or
@
.
Looks up the user with the given user id number and returns their user name. If no match was found an empty string is returned.
Looks up the user with the given user card number and returns their user name.
If no match was found an empty string is returned.
Add a user as an admin with default admin rights.
Remove an admin user from the list of admins.
Add a group as an admin group with default admin rights.
Remove a group from the list of admin groups.
Sets a user's account selection to charge to a single shared account.
Sets a user's account selection to automatically charge to personal account
Sets a user's account selection to standard account selection popup.
List all user accounts (sorted by username) starting at offset and ending at limit . This can be used to enumerate all user accounts in 'pages'. When retrieving a list of all user accounts, the recommended page size / limit is
1000
.
Batching in groups of 1000 ensures efficient transfer and processing.
E.g.: listUserAccounts("authToken", 0, 1000) returns users 0 through 999 listUserAccounts("authToken", 1000, 1000) returns users 1000 through 1999 listUserAccounts("authToken", 2000, 1000) returns users 2000 through 2999 api.getTotalUsers
api.listSharedAccounts
Gets a count of all the users in the system.
List all shared accounts (sorted by account name) starting at offset and ending at limit . This can be used to enumerate all shared accounts in 'pages'.
When retrieving a list of all accounts, the recommended page size / limit is
1000
. Batching in groups of 1000 ensures efficient transfer and processing.
E.g.: listSharedAccounts("authToken", 0, 1000) returns shared accounts 0 through 999 listSharedAccounts("authToken", 1000, 1000) returns shared accounts 1000 through 1999 listSharedAccounts("authToken", 2000, 1000) returns shared accounts 2000 through 2999 api.listUserSharedAccounts
549
List all shared accounts the user has access to (sorted by account name), starting at offset and ending at limit
. This can be used to enumerate the
Method
api.getSharedAccountProperty
api.addSharedAccountAccessUser
api.renameSharedAccount
api.deleteExistingSharedAccount
api.addSharedAccountAccessGroup
api.removeSharedAccountAccessUser
api.removeSharedAccountAccessGroup
api.getPrinterProperty
api.setPrinterProperty
api.listPrinters
Tools - database, server-command scripting, and
APIs (Advanced)
Description
accounts in 'pages'. When retrieving a list of all accounts, the recommended page size / limit is
1000
. Batching in groups of 1000 ensures efficient transfer and processing.
You may optionally specify
TRUE to list accounts even if the user is currently not configured to charge to a shared account.
E.g.: listUserSharedAccounts("authToken", "username", 0, 1000) returns shared accounts 0 through 999 listUserSharedAccounts("authToken", "username", 1000, 1000) returns shared accounts 1000 through 1999 listUserSharedAccounts("authToken", "username", 2000, 1000) returns shared accounts 2000 through 2999 listUserSharedAccounts("authToken", "username", 0, 1000, TRUE) returns shared accounts 0 through 999 even if "username" is not configured to charge to a shared account.
api.isSharedAccountExists
api.setSharedAccountAccountBalance
api.getSharedAccountAccountBalance
api.setSharedAccountProperty
api.setSharedAccountProperties
api.getSharedAccountProperties
api.adjustSharedAccountAccountBalance
api.setSharedAccountAccountBalance
api.addNewSharedAccount
api.deleteExistingSharedAccount
Test to see if a shared account exists in the system/database.
Sets a shared account's current account balance.
Gets a shared account's current account balance.
Sets a shared account property. Properties include access groups, balance, comment options, disabled status, notes, pin and restriction status among others.
Sets multiple shared account properties at once. Properties include access groups, balance, comment options, disabled status, notes, pin and restriction status among others.
Gets a shared account property. Properties include access groups, balance, comment options, disabled status, notes, pin and restriction status among others.
Gets multiple shared account properties at once. Properties include access groups, balance, comment options, disabled status, notes, pin and restriction status among others.
Adjust a shared account's account balance by an adjustment amount. An adjustment may be positive (add to the account) or negative (subtract from the account).
Set the balance on a shared account to a set value. This is conducted as a transaction.
Create a new shared account with the given name.
Delete a shared account from the system. Use this method with care. Deleting a shared account will permanently delete it from the shared account list (print history records will remain).
Allow the given user access to the given shared account without using a pin.
Rename an existing shared account.
Delete a shared account from the system. Use this method with care. Calling this will permanently delete it from the shared account list.
Allow the given group access to the given shared account without using a pin.
Revoke the given user's access to the given shared account.
Revoke the given group's access to the given shared account.
Gets a printer property.
Available properties include: disabled, print-stats.job-count, print-stats.page-count.
Sets a printer property.
List all printers (sorted by printer name), starting at offset and ending at limit
. This can be used to enumerate the printers in 'pages'. When retrieving a list of all printers, the recommended page size / limit is
1000
. Batching in
550
Method
api.setPrinterCostSimple
api.getPrinterCostSimple
api.resetPrinterCounts
api.addPrinterGroup
api.setPrinterGroups
api.enablePrinter
api.disablePrinter
api.deletePrinter
api.renamePrinter
api.addPrinterAccessGroup
api.removePrinterAccessGroup
api.addNewGroup
api.RemoveGroup
api.listUserGroups
Tools - database, server-command scripting, and
APIs (Advanced)
Description
groups of 1000 ensures efficient transfer and processing.
E.g.: listPrinters("authToken", 0, 1000) returns printers 0 through 999 listPrinters("authToken", 1000, 1000) returns printers 1000 through 1999 listPrinters("authToken", 2000, 1000) returns printers 2000 through 2999
Set a page cost using the Simple Charging Model.
Get the page cost if, and only if, the printer is using the Simple Charging Model.
Reset the counts (pages and job counts) associated with a printer.
Add a printer to a single printer group.
Set the printer groups a printer belongs to, overwriting any existing group.
Enables a printer.
Disable a printer for select period of time.
Delete a printer. Use the special text "[All Printers]" to delete all printers on the specified server.
Rename a printer. This can be useful after migrating a print queue or print server (i.e. the printer retains its history and settings under the new name). Note that in some cases case sensitivity is important, so care should be taken to enter the name exactly as it appears in the OS.
Add a user group to the printer's access group list.
Remove a user group from the printer's access group list.
Add a new group to system's group list.
Remove a group.
List all groups (sorted by group name), starting at offset and ending at limit
. This can be used to enumerate the groups in 'pages'. When retrieving a list of all groups, the recommended page size / limit is 1000 . Batching in groups of 1000 ensures efficient transfer and processing.
E.g.: listUserGroups("authToken", 0, 1000) returns groups 0 through 999 listUserGroups("authToken", 1000, 1000) returns groups 1000 through 1999 listUserGroups("authToken", 2000, 1000) returns groups 2000 through 2999 api.isGroupExists
api.addUserToGroup
api.removeUserFromGroup
api.setGroupQuota
api.getGroupQuota
api.useCard
api.performOnlineBackup
Test to see if a group exists in the system.
Adds a user to a specified group. Changes the group membership within the application, not in the OS/Network/Domain user directory.
Removes a user from a specified group. Changes the group membership within the application, not in the OS/Network/Domain user directory.
Set the group quota allocation settings on a given group.
Get the group quota allocation settings on a given group.
Redeem a card and place the credit on the user's account.
Instigate an online backup. This process is equivalent to pressing the manual backup button in the web based admin interface. The data is exported into the
551
Method
api.performGroupSync
api.performUserAndGroupSync
api.addNewUsers
api.getTaskStatus
api.batchImportSharedAccounts
api.batchImportUsers
api.batchImportInternalUsers
api.batchImportUserCardIdNumbers
api.createUserClientAccountsFile
api.getConfigValue
api.setConfigValue
api.processJob
Tools - database, server-command scripting, and
APIs (Advanced) api.performUserAndGroupSyncAdvanced
Description
server/data/backups directory as a timestamped, zipped XML file.
Start the process of synchronizing the system's group membership with the
OS/Network/Domain's group membership. A call to this method will commence the sync process and the operation will complete in the background.
Start a full user and group synchronization. This is equivalent to pressing the
Synchronize Now button in the admin interface. No existing users will be removed. Whether or not full details for existing users will be updated depends on the current user/group sync settings as defined in the admin interface. A call to this method will commence the sync process and the operation will complete in the background.
An advanced version of the user and group synchronization process providing control over the sync settings. A call to this method will commence the sync process and the operation will complete in the background.
Calling this method will start a specialized user and group synchronization process optimized for tracking down and adding any new users that exist in the
OS/Network/Domain user directory and not in the system. Any existing user accounts will not be modified. A group synchronization will only be performed if new users are actually added to the system.
Return the status (completed flag and a status message) associated with a backgrounded task such as a sync operation started by the performGroupSync
API. This method returns a struct (hashtable/map) containing elements with keys completed and message
. This method may be polled to determine if a sync has completed.
Import the shared accounts contained in the given tab separated import file
(located on the server).
Import the users contained in the given tab-delimited import file (located on the
server). See Section 6.6, “Batch User Data Import and Update” for a description
of the file format.
Import the internal users contained in the given tab-delimited import file (located
on the server). See Section 31.1.4, “Batch Internal User Import and Update” for
details of the required file format.
Import the user card/ID numbers and PINs contained in the given tab-delimited import file.
Saves a file containing shared accounts data for the user client. See the manual for more information on how this feature can be used. The file will be saved on the server to the location:
[app-path]\server\data\client\client-accounts.dat
If this file already exists it will be over-written.
Gets the value of a configuration settings.
Sets the value of a configuration setting. NOTE: Take care updating config values. You may cause serious problems which can only be fixed by reinstallation of the application. Use the setConfigValue API at your own risk.
Takes the details of a job and logs and charges as if it were a "real" job. Jobs processed via this method are not susceptible to filters, pop-ups, hold/release queues etc., they are simply logged. See the user manual section "Importing
Print Job Details" for more information and the format.
Table A.1. XML Web Services Methods
A.3.1. Web Services Example Code
The best way to demonstrate how to use the Web Services interface is using example code. PaperCut NG ships with example code for Java, C#, Python and Ruby located in:
[app-path]/server/examples/webservices/
552
Tools - database, server-command scripting, and
APIs (Advanced)
The C# and Java examples also include a full documented Proxy class - a proxy is a common program design pattern. The Proxy wraps and exposes the Web Services methods as standard methods. The setup and use of the underlying XML-RPC library is all handled in the proxy class meaning you can just focus on calling the methods.
Please see the
README.txt
files in the examples directories for more information. The Java example includes full
JavaDoc style documentation under
[app-path]/server/examples/webservices/java/docs/api
.
Developers using other languages such as Perl or Python will need to use an XML-RPC library to call the methods directly. All methods are exposed via the URL http://[server_name]:9191/rpc/api/xmlrpc
.
Tip
All the XML Web Services commands are also accessible via the server-command program. An alternative to using a full programming environment to automate PaperCut NG via Web Services is to use the server-command program to call the commands via a script such as a batch file or shell script. This may be a simpler solution for common automation tasks such as scheduling a User/Group synchronization each night.
More information on the server-command
program can be found in Section A.1, “Server Commands
Tip
Programmers often report that they get an error message "
ERROR: java.lang.NoSuchMethodException:
" and this is frequently because they are calling the API method with the wrong number or type of parameters. Consult the Javadoc API documentation (see above) for information on what parameters you need to use.
A.3.2. Security
The Web Services API's provide full access to the system's internals and hence need to be secured. PaperCut NG secures access using two security layers:
1.
IP address level security
2.
Authentication tokens - required for each method call
The IP address level security is used to control which systems, denoted by IP address, are allowed to connect to the server and call the API's. By default this is restricted to localhost
(127.0.0.1) only. If the program/script making use of the API's resides on another system, then this system's IP address will need to be added to the list of approved addresses under Options
→
Advanced
→
Allowed XML Web Services callers.
The first argument to all method calls is an authentication token ( authToken
). In the default setup the authentication token is the built-in admin user's password (This is password defined for the admin during the initial configuration wizard). Optionally an alternative web service authentication token may be defined via configuration see below. This token must be supplied with all method calls.
To specify an alternative web service authentication token, to avoid the need to use/share the built-in admin user's password:
1.
Login to the system.
2.
Navigate to the Options section.
3.
Click on the Config editor link in the list of actions.
553
Tools - database, server-command scripting, and
APIs (Advanced)
4.
Find the auth.webservices.auth-token config setting.
5.
Enter a new value that will be the new web services authentication token.
6.
Press the Update button to the right to apply the change.
7.
This authentication token can now be used in addition to the built-in admin user's password.
A.4. SSL/HTTPS Key Generation
During the install process, PaperCut NG generates a self-signed key/certificate issued for the host's machine name.
This key is used by default when the system is accessed via HTTPS on port 9192.
The default SSL certificate provides good security, however there are two downsides to using a self-signed certificate:
1.
When users access the HTTPS site using a fully-qualified domain name, the browser will issue a "Domain mismatch warning". To avoid this warning, re-create the self-signed certificate with the machine's fully qualified
domain name, see Section A.4.1, “Re-create the self-signed certificate”.
2.
The browser will also warn the user that the certificate is not signed by a trusted authority. To overcome this you
you already have one, see Section A.4.3, “Importing an existing SSL key”.
Eliminating these warnings provides a smoother experience for the end users of PaperCut NG.
A.4.1. Re-create the self-signed certificate
The tool create-ssl-keystore can be used to re-create the key/certificate (stored in a keystore file) for a different hostname eliminating the browser domain mismatch warning. An example of the command's use: cd [app-path]/server/bin/win create-ssl-keystore -f "myserver.fullname.com"
More information is available via the
--help command line option.
Usage: create-ssl-keystore [-f] [-k FILE] [SYSTEM_NAME]
-f Force. Overwrite any existing keystore file.
-k FILE: Define a keystore file location. If not set the keystore is created in the default location
(server/data/default-ssl-keystore).
SYSTEM_NAME: The name of the computer/server used to generate keystore.
If not defined, the current computer name is used.
A.4.2. Using a custom signed SSL key
Large organizations may wish to use their own SSL key signed by a commercial certificate authority (CA) that is recognized by all popuplar web browsers including Internet Explorer, Mozilla Firefox, Safari and Chrome. A complete list can be found in Windows under Control Panel > Internet Options > Content > Certificates > Trusted
Root Certification Authorities.
Some large organizations also operate a certificate authority of their own that is recognized by their users' web browsers by way of a root certificate that has been installed into all users' web browsers in a manual or automated way.
The advantage of a signed certificate is that it eliminates the browser warning, "The security certificate presented by this website was not issued by a trusted certificate authority."
554
Tools - database, server-command scripting, and
APIs (Advanced)
If you are already in posession of a signed SSL key and certificate for the domain name of the PaperCut NG
application server please see Section A.4.3, “Importing an existing SSL key” below.
To create your own SSL key and have it signed by a commercial or intra-organizational certificate authority you can use the 'keytool' tool supplied in the directory
[app-path]/runtime/jre/bin
.
1.
Open a command prompt window and change to the directory
[app-path]/runtime/jre/bin
. Any existing files called 'my-ssl-keystore' in this directory are leftovers from previous attempts and need to be deleted at this point.
2.
Enter this command to produce the SSL key: keytool -keystore [app-path]\server\custom\my-ssl-keystore -alias jetty -genkeypair
-keyalg RSA
Caution
This process creates a 'my-ssl-keystore' file. Don't lose this file! You will need it when adding the public key later.
We recommend making a copy of this 'my-ssl-keystore' and keeping it in a safe place. If it is lost or changed, your certificate will need to be re-issued, often resulting in costs from your SSL provider.
As keystore password choose 'password' or another simple password as it is not very important. Enter the same password again later when asked for a key password.
Note: Some organizations require larger key sizes than the default 1024 bit. In this case add the "-keysize
2048" or "-keysize 4096" parameter to the end of the above command line.
You will be asked a series of questions. Enter the exact fully-qualified domain name of the PaperCut NG
Application Server where it asks you for "first and last name". The server name must be the exact one that users will enter into their browsers to access PaperCut NG's web interface, e.g. 'printing.myschool.edu'.
Depending on the certification authority's requirements you may also need to fill in some of the other fields.
Enter keystore password: password
What is your first and last name?
[Unknown]: printing.myschool.edu
What is the name of your organizational unit?
[Unknown]:
What is the name of your organization?
[Unknown]:
What is the name of your City or Locality?
[Unknown]:
What is the name of your State or Province?
[Unknown]:
What is the two-letter country code for this unit?
[Unknown]:
Is CN=printing.myschool.edu, OU=Unknown, O=Unknown,
L=Unknown, ST=Unknown, C=Unknown correct?
[no]: yes
Enter key password for <jetty>
(RETURN if same as keystore password): password
3.
Prepare your new SSL key for certification by the certificate autority: keytool -certreq -alias jetty -keystore [app-path]\server\custom\my-ssl-keystore
555
Tools - database, server-command scripting, and
APIs (Advanced)
-file [app-path]\server\custom\jetty.csr
The contents of the resulting jetty.csr
can be pasted into the online order forms of abovementioned commercial certificate authorities or passed to your organization's own certificate authority. When the certification process has completed, the authority will provide you with a certificate file that can be downloaded from the autority's web site. The filename will usually end in
.crt
,
.cer
or
.cert
. The contents of the file should look something like this:
-----BEGIN CERTIFICATE-----
MIIDLTCCApagAwIBAgIQJc/MOTjAW0HrPI/4rGtDCDANBgkqhkiG9w0BAQUFADCB hzELMAkGA1UEBhMCWkExIjAgBgNVBAgTGUZPUiBURVNUSU5HIFBVUlBPU0VTIE9O
... more here ...
Awjhfz9EfxN2l1UYP15xZZyNO4DO3X/LliCG9pdFf4hUHl8tRnhQBvRR1F0v9UHB
PC6L9jNjMbQUoQ9NG/S8Nn7ZcSHNy+P53ntIBaEfTv7+qvXNWvSb5wj4pd05wGF1
Bw==
-----END CERTIFICATE-----
Save the file as jetty.crt
.
4.
Before you can make use of your newly obtained certificate, you may have to import the certificate authorities
"root certificate". PaperCut comes with a number of root certificates pre-installed that you can list using this command (still from the directory
[app-path]/runtime/jre/bin as above): keytool -keystore ../lib/security/cacerts -storepass changeit -list
Add the option "-v" at the end to obtain the same list with more details, such as expiration dates.
If your certificate authority is not listed there, or you have been notified that they have recently started using new root certificates, then you need to first import the certificate authority's root certificate into your keystore before importing your newly obtained own certificate. The CA's root certificate will usually be available for download on the CA's web site as a file ending on
.pem
or
.crt
. Save the file using a filename indicative of the
CA's name, e.g.
globaltrust.pem
. Import the root certificate using this command, specifying an alias that is indicative of the CA's name (type this all in one line): keytool -keystore [app-path]\server\custom\my-ssl-keystore -importcert -alias globaltrust
-file globaltrust.pem
When asked whether to trust this certificate, answer yes:
Trust this certificate? [no]: yes
Some certificate authorities also provide additional "intermediate certificates" that will have to be imported the same way as the root certificate.
5.
Now you can import your own certificate previously saved as jetty.crt
(type this all in one line): keytool -keystore [app-path]\server\custom\my-ssl-keystore -import -alias jetty
-file jetty.crt -trustcacerts
Caution
The 'my-ssl-keystore' in the above command is the original my-ssl-keystore you created in step 2.
556
Tools - database, server-command scripting, and
APIs (Advanced)
6.
Your new keystore file my-ssl-keystore is now ready and should be moved to the location
[app-path]/server/custom
.
start serving up your new SSL certificate.
A.4.3. Importing an existing SSL key
If you have an existing SSL key with certificate you can import it into the PaperCut NG keystore. Reasons for having an existing signed key include:
• You have obtained an SSL key specifically for use with your PaperCut NG Application Server using a method other than using 'keytool' as described above. As a result you have – on Windows – a certificate with an attached private key either stored in the Windows certificate store or in a so-called PCKS#12 file (
*.p12
/
*.pfx
), or, – on
Linux – separate 'PEM encoded' key and certificate files.
• Your organization's intranet as served by Internet Information Server (Windows), Apache (Linux) or another web server uses a certificate that can be re-used for PaperCut NG. NOTE: Unless your intranet server and PaperCut
NG run on the same server (i.e. on different ports), the server name of your intranet server will be different from your PaperCut NG Application Server. E.g. the intranet address might be internal.myschool.edu
while the
PaperCut NG Application Server can be reached at printing.myschool.edu
. In this case the certificate can only be re-used if it is a so-called wild-card certificate that allows arbitrary subdomains under the myschool.edu
domain name that it was issued for.
On Windows, if the certificate with key exist in the Windows certificate store only, export it:
1.
Open the Windows Control Panel and open Internet Options.
2.
On the "Content" tab click "Certificates".
3.
On the Personal tab select the certificate and click "Export ..." and click "Next" at the initial screen
4.
Select 'Yes, export the private key' and click Next
5.
If you selected the last option correctly, you will only be able to export as a .PFX file
• TICK 'Include all the certificates in the certification path if possible'
• UNTICK 'Enable strong protection'
• UNTICK 'Delete the private key if the export is successful'
6.
Type in a password for the PFX file. This is only used temporarily.
7.
Save the PFX file to with the extension
.pfx
. (This is just temporary, you MUST delete this file later on.)
8.
Finish the wizard to export the certificate.
On Windows, if the certificate with key exists in the IIS Server Certificates store, export it:
1.
Open the Windows management console, select your IIS server and open "Server Certificates".
2.
Right-click the certificate and click "Export ...".
3.
Choose a filename with the extension
.pfx
. (This is just temporary, you MUST delete this file later on.)
4.
Type in a password for the PFX file. This is only used temporarily.
5.
Click OK.
On Linux, if the key and certificate are in separate 'PEM encoded' files:
• Use the 'OpenSSL' tool that is part of many Linux distributions to combine both files to a PKCS#12 file with the following command (type this all in one line): openssl pkcs12 -export -inkey <key file> -in <certificate file>
-out <pfx file>
<pfx file> is the target PKCS#12 file for which you should choose a filename with the extension
.pfx
. (This is
557
Tools - database, server-command scripting, and
APIs (Advanced) just temporary, you MUST delete this file later on.)
Then import the certificate into your own PaperCut NG keystore:
1.
Open a command prompt and change to the installation directory. E.g. on Windows: cd c:\Program Files\PaperCut NG\
2.
Enter the following command (type this all in one line):
"runtime/jre/bin/java" -classpath server/lib/jetty-6.1.22.jar
org.mortbay.jetty.security.PKCS12Import "<pfx file>" server/custom/my-ssl-keystore
Substitute
<pfx file> with the
.pfx
or
.p12
file containing your certificate and key.
The Jetty version number (
6.1.22
) changes from time to time. If you receive a
NoClassDefFoundError message look for a jetty-*.jar
file in the
[app-path]/server/lib/ directory and update the command as appropriate.
3.
You will be asked to enter the 'input keystore passphrase'. Enter the password that you used when you saved the file.
4.
You will be asked to enter the 'output keystore passphrase'. Enter a new password such as 'password'. Once this command completes a new file should be created at
[app-path]/server/custom/my-ssl-keystore
.
This file is your keystore and contains your certificate and key.
5.
and start serving up your new SSL certificate.
A.4.4. Installing the Keystore
your keystore so that PaperCut can start serving up your new certificate.
To configure the PaperCut Application Server to use the new key/certificate:
1.
Copy your signed keystore onto the server running the PaperCut NG Application Server. The suggested location is
[app-path]/server/custom/my-ssl-keystore
2.
Open the file
[app-path]/server/server.properties
with a text editor (e.g. Notepad).
3.
Locate the section titled
SSL Key/Certificate
.
4.
Remove the
#
(hash) comment marker from all lines starting with " server.ssl
".
5.
Define the location of your keystore, keystore password and key password as chosen previously. The file should look something like this: server.ssl.keystore=custom/my-ssl-keystore server.ssl.keystore-password=password server.ssl.key-password=password
NOTE: On Mac OS please specify the FULL path to your keystore, e.g.
/Applications/PaperCut
NG/server/custom/my-ssl-keystore
6.
Restart the PaperCut NG Application Server and verify all is working. If the server fails to start, error messages will be recorded in logs located in the server's logs directory.
558
A.5. User Client Options
The user client is used to display user balances, system notifications and request information from the users. This is
that change its behavior.
A.5.1. Command-line options
Tools - database, server-command scripting, and
APIs (Advanced)
Option
--silent
--debug
--minimized
--noquit
--disabletasktrayicon
--disable-balloon-tips
--hide-balance
--user <username>
--cache <cache directory>
--neverrequestidentity
Description
The silent option tells the client not to report errors if it has problems connecting to the server. If the server is unavailable at time of startup (e.g. the client is not connected to the network), or if the user does not currently exist in the database, the client will simply sleep, waiting for the condition to change.
This option can also be set by adding a silent=Y line to the client config.properties
.
The debug option tells the client to log activity to a file called user-client.log
which will be created in the user's home directory.
This option can also be set by adding a debug=Y line to the client config.properties
.
The minimized option tells the client to start minimized. On Windows, the client will be minimized to the task tray.
This option is recommended if the user's balance is not important to the user.
For example, if a user is only allowed to assign print jobs to a shared account, then their personal balance is of little importance, so the user client should be minimized.
This option can also be set by adding a minimized=Y line to the client config.properties
.
Stops the user from closing or quitting the client where possible.
This option can also be set by adding a noquit=Y line to the client config.properties
.
The option tells the client to hide the task tray icon.
This option can also be set by adding a disabletasktrayicon=Y line to the client config.properties
.
This option instructs the client to display messages in dialog boxes rather than notification area balloon tips. (Windows only)
This option can also be set by adding a disable-balloon-tips=Y line to the client config.properties
.
This option instructs the client to hide the user balance.
On Windows, the balance window is not displayed. On other platforms, the balance is hidden from the balance window.
This option can also be set by adding a hide-balance=Y line to the client config.properties
.
The user option allows the client to be run using a different username.
This can be useful if the user is logged into a machine with a username different to the username authenticated with the server/printers. For example, if a user is using a laptop that is not a part of the domain.
This option can also be set by adding a user=<username> line to the client config.properties
.
This argument is actioned by pc-client-local-cache.exe
. It defines the location of the globally writable cache directory on the system's local hard drive.
The cache is used to minimize network traffic on future launches. The default location is C:\Cache . Standard users will require WRITE and READ access to this directory.
The client will use the username of the logged-in user to identify itself with the server. In a domain environment, users always log in using their network identity and the names will always match. However on non-domain systems where local accounts are used (e.g. laptops), these names may not match. The client will display a popup requesting the user to confirm their identity. This option will suppress this dialog.
559
Option
--windowposition <position>
--windowtitle <title>
--background-color <color>
--text-color <color>
--link-color <color>
--link-hover-color <color>
--default-selection <option>
Tools - database, server-command scripting, and
APIs (Advanced)
Description
This option can also be set by adding a neverrequestidentity=Y line to the client config.properties
.
Specify where the client window should appear. The valid options include top-left
, top-right
, bottom-left or bottom-right
.
In addition to the above set of fixed positions, coordinates of the window can also be specified by setting the
<position> parameter to
XY<x>,<y>
. The
<x> value sets the x-coordinate of the window (if negative, the value indicates the distance from the right of screen). The
<y> value sets the y-coordinate of the window (if negative, the value indicates the distance from the bottom of screen). Some examples include:
•
XY100,100
- position the window 100 pixels from the left and 100 pixels from the top of the screen.
•
XY-50,100
- position the window 50 pixels from the right and 50 pixels from the top of the screen.
•
XY50,-100
- position the window 50 pixels from the left and 100 pixels from the bottom of the screen.
The window position can also be set by adding windowposition=<position> line to the client config.properties
.
a
Allows the window title to be customized. If the
<title> includes
{0} then this will be replaced by the user's username.
The window title can also be set by adding a windowtitle=<title> line to the client config.properties
.
Changes the background color of the client's balance window. The colors are coded in standard hexadecimal RGB ("web colors", see http://en.wikipedia.org/wiki/Web_colors for an explanation). E.g. to set the background color to red, use:
--background-color=FF0000
The balance window background color can also be set by adding a background-color=<color> line to the client config.properties
.
Changes the text color of the client's balance window. The colors are coded in standard hexadecimal RGB ("web colors", see http://en.wikipedia.org/wiki/Web_colors for an explanation). E.g. to set the text color to blue, use:
--text-color=0000FF
The balance window text color can also be set by adding a text-color=<color> line to the client config.properties
.
Changes the color of the link on the client's balance window. The colors are coded in standard hexadecimal RGB ("web colors", see http://en.wikipedia.org/wiki/Web_colors for an explanation). E.g. to set the link color to a dark gray, use:
--link-color=333333
The balance window link color can also be set by adding a link-color=<color> line to the client config.properties
.
Changes the color of the mouseover link on the client's balance window. The colors are coded in standard hexadecimal RGB ("web colors", see http://en.wikipedia.org/wiki/Web_colors for an explanation). E.g. to set the link color to a black, use:
--link-hover-color=000000
The balance window mouseover link color can also be set by adding a link-hover-color=<color> line to the client config.properties
.
Specifies the default selected option on the account selection popup. This option can be used to save mouse clicks / keyboard presses by setting the
560
Option
--default-account <option>
Tools - database, server-command scripting, and
APIs (Advanced)
--default-account-pin <option>
--accounts-file <account-file-path>
--auth-ttl-values <ttl-value-mins>
--auth-ttl-default <default-mins>
--lockdir <lockdir>
--disable-auth-by-id-number
Table A.2. User Client command-line options
Description
default selected option to the one that is most commonly used.
Options include:
• charge-personal
- The "Charge to my personal account" option is selected.
• charge-account-list
- The "Charge to shared account" option is selected.
• charge-account-pin
- The "Charge to shared account using PIN / Code" option is selected.
• print-as-user
- The "Perform print as user" option is selected.
For example, applying a default selection of charge-account-list ensures that the option Charge to shared account is selected, and the dropdown list of accounts is highlighted. This allows the user to begin navigating the list of shared accounts immediately via the keyboard, and saves them having to select the option first.
This option can also be set by adding or enabling the default-selection=<option> line in the client config.properties
file.
Specifies the default selected account on the account selection popup. This option can be used to save mouse clicks / keyboard presses by setting the default selected account to the one that is most commonly used. NOTE: The default shared account can also be set on the user's account selection options.
See Section 8.4, “The Account Selection Popup”.
For example, setting the default account to "sales\invoices" results in this account being selected when the account selection popup shows. This allows the user to quickly confirm the selection by just clicking OK in those cases that the print should be charged to this account. The selection can still be changed in case the print should not be charge to this account.
This option can also be set by adding or enabling the default-account=<option> line in the client config.properties
file.
If set, this overrides the default account setting on the user's account selection options.
Specifies the default account PIN entered on the account selection popup. This option can be used to save typing by setting the default account PIN to the one that is most commonly used.
Without this option, the account PIN field on the account selection popup shows the account PIN last entered in this field.
If the option is specified but left blank (
--default-account-pin ""
), the account PIN field will be blank on every popup.
This option can also be set by adding or enabling the default-account-pin=<option> line in the client config.properties
file.
Specifies the location of the local accounts file to load. For more information,
see Section D.4, “Managing Large Client Account Lists on Distributed Sites”.
Comma-separated list of authentication time-to-live values in minutes. This
overrides the values configured on the server. See Section 7.10, “Popup
This option can also be set by adding or enabling the auth-ttl-values= line in the client config.properties
file.
The default time-to-live value automatically selected when the login authentication window displays. This overrides the value configured on the server.
This option can also be set by adding or enabling the auth-ttl-default= line in the client config.properties
file.
Define an alternate lock directory location.
Reverts user authentication method to user/password instead of ID Number and
PIN.
561
Tools - database, server-command scripting, and
APIs (Advanced)
The command-line arguments listed above are usually used in the area/method used to start the client - a login script, shortcut, or the relevant registry key in
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Run\
.
A.5.2. Configuration properties file
The command-line arguments may also be set in the config.properties
file. This is particularly helpful on Apple
Mac systems where command-line arguments are difficult to implement. The config.properties
file is located in the same directory as the client executable on Linux and Windows. On the Mac it can be found at:
[app-path]/PCClient.app/Contents/Resources/config.properties
Additionally, settings may be changed at the user-level by placing a file in the user's Library Preferences folder located at:
~/Library/Preferences/PCClient/config.properties
The file should contain the options in a properties file form like: user=mary minimized=Y windowposition=top-left windowtitle=Print Balance: {0}
Other options allow text in the Print Job Notification window to be customized. For example: account-from-list-text=Charge to a cost center
client is restarted. The full set of options is defined in the config.properties.tmpl
file in the client directory above.
Figure A.1. Customized Print Job Notification window
562
Tools - database, server-command scripting, and
APIs (Advanced)
A.5.3. Changing the time after which jobs are deleted when awaiting popup response
If a user does not respond to the account selection popup after a defined time, their print job will be automatically deleted. This is to prevent a buildup of old jobs in the print queue. The default timeout is
10 minutes, and can be changed as follows:
1.
Navigate to the Options tab
2.
In the section Client Software, find the option Delete jobs awaiting popup response after...
3.
Enter the number of minutes to wait for users to respond to the popup before their job is deleted
4.
Press Apply
A.6. Stopping and Starting the Application Server
Most of the time it will not be necessary to stop or start the server; however there are some circumstances where this is required:
• Performing an offline backup
• Upsizing the database to an external database
• Upgrading the application
The procedure for stopping the server depends on the platform the server is run on.
Important
When you start the application server, wait approximately 15-20 seconds for the service to start before accessing the admin interface. This gives the system time to initialize.
A.6.1. Stopping and Starting the Application Server on Windows
The PaperCut NG application server runs as a Windows service when installed on Windows, and it can be stopped and started using the Services control panel applet. To stop/start/restart the application server:
1.
Open the services control panel. (Start
→
Control Panel
→
Administrative Tools
→
Services)
2.
Find the service named PaperCut Application Server.
3.
Right-click on the service.
4.
Select the option you want to perform (e.g. Stop/Start/Restart).
An alternative to using the services applet is to run the batch files located in the directory
[app-path]\server\bin\win
. Using the batch files might be more convenient when the process needs to be automated (like scripting a database backup). The batch files to stop/start the server are called:
• start-server.bat
- starts the service
• stop-server.bat
- stops the service
A.6.2. Stopping and Starting the Application Server on Mac
The PaperCut NG application server may be stopped or started on Mac by using the following scripts found at
[app-path]/server/bin/mac/
:
• start-server.command
- starts the application server
• stop-server.command
- stops the application server
563
Tools - database, server-command scripting, and
APIs (Advanced)
A.6.3. Stopping and Starting the Application Server on Linux
The PaperCut NG application server may be stopped or started on Linux by using the following scripts found at
[app-path]/server/bin/linux-[x64|i686]/
:
• start-server
- starts the application server
• stop-server
- stops the application server
A.7. Automating / Streamlining Installation on Windows
In some cases organizations may wish to streamline the installation of PaperCut NG or a particular PaperCut NG component for automating deployment. For example when installing on many secondary print servers, or installing the user client tool locally on many desktops (although the recommended installation procedure is the "zero install"
strategy - see Section 5.2.1, “User Client Deployment”).
The installer command-line options provide the ability to pre-select the installer options, such that there is no need to
valid for the Windows installers having those options available for PaperCut NG (the main installer), the user client tool and the card wizard.
Option
/SILENT or /VERYSILENT
/DIR="x:\dirname"
/TYPE=secondary_print
Description
Instructs the installer to be 'silent' or 'very silent'. When silent the installation begins immediately, and only the progress window is displayed. When very silent, installation begins immediately with nothing displayed.
If any errors are encountered, the error messages are still displayed with either option.
Overrides the default installation directory. This can be used to install PaperCut
NG to a different directory than the default.
Selects the install type/options:
Server installer:
• full
- The PaperCut NG server. The default option.
• secondary_print
- Install option to set up a secondary print server. Only installs the print provider component.
• secondary_web_print
- Only install the web print component.
/GROUP="folder name"
/NOICONS
/LANG=language
Overrides the default Start menu group / folder into which PaperCut NG is installed.
Disables the creation of a Start menu group / folder.
Specifies the language to use during installation. By default this is automatically detected based on your language settings, but can be overridden by specifying a language. The available languages are:
• de
- German
• en - English
• es
- Spanish
• fi
- Finnish
• fr - French
• it
- Italian
• nl
- Dutch
• pt
- Portuguese
• pt_BR
- Brazilian Portuguese
• zh_CN
- Chinese (Simplified)
• zh_HK
- Chinese (Traditional)
Note: This option only specifies the language during installation. More languages and regional options are available in PaperCut NG once installed, which are configured separately.
Table A.3. Windows installer command-line options
564
Tools - database, server-command scripting, and
APIs (Advanced)
A.8. Importing Print Job Details
In some environments it may be desirable to import print jobs that have been tracked by external or third party systems into PaperCut NG. This could be because the external system is not easily tracked directly, or to import data that was previously tracked for logging and reporting purposes.
Job details may be importing using the server-command scripting tool ( process-job
“Server Commands (server-command)”) or using the web services API (
api.processJob
script or program).
The server-command and web services call accept a single argument (string) containing all the job details. Each field is specified as a name-value pair separated by an equals sign (i.e.
name=value
), and fields are separated by commas.
For example, to process a job and specify the user, printer server and printer name (the minimum required details): user=bob,server=papercut,printer=My Printer
If any fields contain a comma, surround the name-value pair with quotation marks ("). E.g. for a printer named
Library, rear
: user=bob,server=papercut,"printer=Library, rear"
Spreadsheet applications such as Excel with automatically add quotation marks as above when saving a document in CSV format.
If any fields contain quotation marks, escape them by adding another quotation mark, i.e. two in a row. E.g. for a printer named
"John Smith" Library
: user=bob,server=papercut,printer=""John Smith"" Library
The names of all the available fields are listed in the table below.
Field
user server printer time cost total-pages total-color-pages copies document-name
Required
Yes
Yes
Yes
No
No
No
No
No
No
Description Default
N/A
The username of the user associated with the job.
The name of the server the job was submitted to.
N/A
N/A
The name of the printer or print queue the job was submitted to.
(current time)
The time the job was submitted/printed. This is formatted as an ISO8601 simple date-time: yyyyMMddTHHmmss.
E.g.
"20091224T133602" represents the
24th of December 2009 at 13:36:02
(1:36 pm, local time).
The cost of the job. If the cost is not set it will be automatically calculated as for a normal job (based on the job details and configuration of the printer, user etc.).
(auto)
The total number of pages in the job.
1
The total number of color pages in the job.
(same as total-pages)
The number of copies in the job.
The document name.
1
(empty)
565
Field
duplex grayscale job-type paper-size-name paper-width-mm paper-height-mm document-size-kb invoice comment client-machine client-ip shared-account
Tools - database, server-command scripting, and
APIs (Advanced)
No
No
No
No
Required
No
No
No
No
No
No
No
No
Description Default
TRUE or FALSE to indicate if the job is duplex (printed on both sides)
FALSE
TRUE or FALSE to indicate if the job is grayscale (no color)
FALSE
The type of job to import. Options include: COPY, FAX, PRINT, SCAN.
The name of a standard paper size, e.g. "Letter" or "A4".
(empty)
The width of the paper in millimeters.
Determined automatically if using paper-size-name.
(empty)
The height of the paper in millimeters.
Determined automatically if using paper-size-name.
(empty)
The size of the document's spool file in kilobytes.
0
TRUE to mark the job as invoiced,
FALSE to mark as not invoiced. The default value is determined automatically, as for a regular job.
(auto)
A comment to be associated with the job.
(empty)
The hostname of the client machine the job was submitted from.
(empty)
The IP address of the client machine the job was submitted from.
(empty)
The name of the shared account to charge this job to. Sub-accounts may be selected using a backslash, i.e.
"parent\child".
(empty)
Table A.4. Fields for Importing Print Job Details
566
Appendix B. Troubleshooting & Technical
FAQ's
There are a number of problems you may run into in the course of installing and using PaperCut NG. Many will be resolved once you get a better idea of how PaperCut NG works, while others may require you to dig deeper into the application's workings.
The following list has been compiled over the course of years of PaperCut NG usage. If you can't find a reference to the problem you're having here, look at the most up-to-date version of the FAQ and Knowledge Base
[http://www.papercut.com/kb/] at the PaperCut NG website [http://www.papercut.com/].
B.1. Troubleshooting & Installation Questions
Q:
I am running PaperCut NG server on Windows XP Professional. Is this supported?
A:
Yes, PaperCut NG server is supported on Windows XP Professional. It is recommended that you disable
Simple File Sharing. This feature causes Windows XP to authenticate all users as Guest, which causes two problems:
• All printing is recorded as being printed by the Guest user.
• Username/password authentication does not work correctly, because Windows XP will authenticate as
Guest, even if the username/password is entered incorrectly.
To disable Simple File Sharing, open Windows Explorer, select Tools
→
Folder Options..., and un-tick the appropriate option on the View tab.
Figure B.1. Disable simple file sharing
567
Troubleshooting & Technical FAQ's
Q:
I have just added a print queue to my Windows XP Professional computer that hosts the print queues but
PaperCut NG is not tracking it. What could be causing this?
A:
Due to the way Windows XP handles some print jobs, a small number of changes are made by PaperCut NG.
These changes are made when PaperCut NG starts. However, these changes do not take effect until the
Windows Print Spooler has been restarted. This can be easily done by restarting the Windows XP computer if you have issues tracking print jobs after installing PaperCut NG or creating a new print queue.
This functionality can be referred to as the Shared Spool File feature.
Q:
I am running PaperCut NG in a workgroup environment (i.e. not as part of a domain). What considerations should be taken into account?
A:
See Chapter 30, Running in a Workgroup Environment.
Q:
PaperCut NG is not detecting jobs printed from a network clients. How can I fix this?
A:
There are two main causes of this problem:
• Users are not correctly logging on to your network domain or computer. If the domain server does NOT authorize users, PaperCut NG has no way of knowing who submitted the print job. With system policies, login onto the domain can be made mandatory, eliminating this problem. Alternatively printer permissions can be set on the print server to ensure only valid users may print to the printers.
• Alternatively the client computer may be configured to print directly to the network interface printer. Ensure all network clients are configured as outlined in the PaperCut NG installation guide. All print jobs must pass through the print server running PaperCut NG.
Q:
PaperCut NG is not counting/detecting pages correctly. What's causing this?
A:
PaperCut NG currently supports about 90% of printers on the market. If a printer's language is not recognized,
PaperCut NG will not detect any pages and record the print job as a zero page count. This is usually accompanied with an error message in the Application Event Log. We recommend you try the following problem resolution actions in this order:
1.
Many printers come with a variety of driver options. Install the Postscript drivers if one is available for the printer. Do this on both the Print Server and all network clients.
2.
Try the drivers included with the Windows CD. PaperCut NG supports the majority of drivers distributed with recent Windows releases.
3.
Try turning Enable advanced printing features as follows: a.
On the print server, Start->Settings->Printers.
b.
Right-click on the printer and select Properties... c.
Select the Advanced Tab.
d.
Turn off (disable) the Enable advanced printing features.
More information is available in
[http://www.papercut.com/kb/Main/EnableAdvancedPrintingFeatures].
our Knowledge Base
4.
If you're still having problems, email PaperCut Software support. The development team may be able to recommend a suitable set up or even supply a recent update supporting your hardware.
5.
Specific information on printer compatibility is discussed in the PaperCut Knowledge Base
[http://www.papercut.com/kb/]. Information here might be of assistance.
Q:
How do I ignore (not monitor or delete) a printer?
A:
568
Troubleshooting & Technical FAQ's
Q:
The system is not displaying the correct currency sign.
A:
The Print Provider may be configured via its configuration to ignore a printer. For more information see
Section 7.1, “Adding and Removing/Deleting/Ignoring Printers”.
PaperCut NG will format the currency based off the operating system's default regional settings. If the default regional settings are incorrect, the format can be changed by defining your location under Options
→
General
→
Display Settings
→
Location.
Q:
I've setup a secondary print server. The printers on this server are not listed and not being monitored. What's wrong?
A:
There are a number of possible explanations. The first step is to open the Print Provider's log file on the secondary server. This file will often contain error messages indicating the cause or type of error. On a
Windows system the log file is located at:
[app-path]\providers\print\win\print-provider.log
The file can be opened from any text editor such as Notepad.
Some common issues are:
1.
Verify that the secondary server's name is correctly defined in the print-provider.conf
file. Open a command prompt on the secondary server and use the ping command to verify that the server can be contacted under this name. A server restart (or a manual restart of the PaperCut Print Provider service) is required for any changes to the file to take effect.
2.
Ensure that firewall software on the primary server is not preventing the secondary server from connecting on port 9191. Firewalls should be configured to allow all local network traffic on this particular port.
A quick way to see if the secondary server can connect to the primary server is to use the command-line telnet program. Simply type: telnet servername 9191 at a command prompt.
• If you receive an error like
Could not open connection to host
, then there is probably a network/firewall issue not letting the connection through.
• If the screen goes blank then the connection was established successfully. Press
Ctrl+] then type quit to close the telnet session.
3.
Check that the Print Provider process/service is in fact installed and running. On a Windows system this is located under: Start
→
Control Panel
→
Administrative Tools
→
Services
Q:
The client software is not displaying the user's account balance and is displaying a network error. How do I fix this?
A:
The client software needs to contact the application server. For the technical readers, the client makes an XML web services request to the server on port 9191. Most problems relate to either firewalls blocking access or the application server's name is not correctly defined. Ensure that:
1.
Any firewalling software on the server allows local network access to port 9191.
2.
The client.properties
file (a text file) lists the correct server name or IP address of the server. If you've used the zero-install deployment option, this file is located on the server in the directory:
[app-path]/client/client.properties
B.2. General Questions
Q:
How do I change the built-in admin user's password?
A:
The admin user's password is set up on initial install during the configuration wizard. This password can be changed post-install by logging into the application as the admin user and navigating to the Options
→
569
Troubleshooting & Technical FAQ's
Q:
I run a small peer-to-peer network and my users don't log onto the workstations. Can I still use PaperCut NG?
A:
Advanced tab, and selecting the Change internal admin password option.
If you have forgotton the internal admin password, it can be reset by editing the admin.password
property in the text file located at
[app_dir]/server/server.properties
.
PaperCut NG is primarily designed for networks managed under a domain and/or authenticated environments.
Peer-to-peer networks or Workgroups are however supported. The first option should be to consider requiring users to log onto the workstations using their username and password. If this is not possible, an alternate option is to set up the user accounts on system hosting the printers (system running the PaperCut NG server software) and configuring the account selection popup with the Charge to other users option selected.
Users can then enter their username and password in the popup that displays each time they print.
Q:
I would like to start the user inquiry tool (client software) with the window minimized. Is this possible?
A:
Yes. The client software can be started minimized by executing the program with a command-line switch
-minimized
. See Section A.5, “User Client Options”.
Q:
How do I stop users from closing/shutting down the client software?
A:
If the user running the client software is configured to either:
• select shared accounts
• confirm the print job via a popup the client software must be running at all times. If the user is configured in either of these modes, the client software's exit option is disabled. Note: The client software will need to be restarted to pick up this option after the user's options have been changed.
Q:
Why does PaperCut NG cache the group membership?
A:
PaperCut NG caches group membership by replicating the user/group relationship structure internally in the system. Typically network group membership is relatively static, and is usually set up when a user account is initially created. PaperCut NG tries to be a good network application by avoiding common no-no's such as flooding domain controllers with group lookup requests. This is achieved by caching. Operations such as Bulk
user operations, quota allocations, group reports and group filtering all need to do group membership lookups. Caching speeds up these operations and prevents excessive callouts to the domain servers.
The downside to caching is that group membership changes are not immediately reflected inside PaperCut
NG. To force PaperCut NG to detect the change perform a User/Group synchronization under the Options section. The system will also automatically refresh group membership overnight during low network activity.
Q:
I have noticed a lot of extra options available under the Config Editor (Advanced) area. Can I change these?
A:
The config area contains all of the PaperCut NG system wide settings. Some of these can be changed via the normal options interface while others are designed for internal developer use and tuning and are only accessible via the config editor. Any changes made in the config editor should be done with care as an invalid entry may require you to reinstall the system!
Q:
I'd like to write some custom extensions. Do you support this?
A:
One of the business objectives of PaperCut NG was openness. The development team actually encourages this and can assist with detailed API documentation. If you would like feedback on your ideas, please email our support team. They would be more than happy to offer advice.
Q:
What external databases are supported?
570
Troubleshooting & Technical FAQ's
A:
Q:
What is the internal database format?
A:
Running PaperCut NG on top of an external database is an advanced option. This is discussed in details in system management section.
PaperCut NG's internal database is Apache Derby - an open source database written by IBM and based on
IBM's DB2 Cloudscape database system. The internal database has proven to scale very well and is suitable for networks of all sizes.
Q:
What language is PaperCut NG developed in?
A:
PaperCut NG is developed under a number of languages and development environments. The printer monitoring component and other native operating system interfaces such as user authentication are written in
C/C++. The application server and web services are written in server-side Java.
Q:
I'd like to investigate server cluster support?
A:
The PaperCut NG is designed as a cluster compatible application and supports clustering at all layers of the application. For more information on configuring PaperCut NG in a Microsoft Cluster environment, please see
(Linux) please contact our support team.
Q:
How do I print a spool file?
A:
have otherwise captured a spool file for debugging purposes - you can print this document by copying it to a printer, using it's full network path.
Windows:
copy /B my-spool-file.pcl6 \\servername\printer
MacOS and Linux:
lp -h servername -d printer -o raw my-spool-file.pcl6
571
Appendix C. Advanced LDAP
Configuration
PaperCut NG supports the following LDAP server types out-of-the-box:
• Novell eDirectory
• Microsoft Active Directory
• Unix/NIS/Posix
However, other server/schema types can be supported by defining the fields to query and the LDAP searches to perform. These options are configured by adjusting config entries in the Config Editor, which can be opened from the Options tab. The following config items are available:
Config name
ldap.schema.user-name-field ldap.schema.user-full-name-field ldap.schema.user-email-field ldap.schema.other-emails-field ldap.2.schema.other-emails-field ldap.schema.user-second-card-id-field ldap.2.schema.user-second-card-id-field ldap.schema.user-department-field ldap.schema.user-office-field ldap.schema.user-card-id-field ldap.schema.user-second-card-id-field ldap.schema.user-name-search ldap.schema.group-name-field ldap.schema.group-member-field ldap.schema.group-search ldap.schema.posix-groups
Description
The LDAP field that contains the user's username.
The LDAP field that contains the user's full name.
The LDAP field that contains the user's email address.
The LDAP field that contains the user's other email addresses. If the user has only one other email then a single value or a multi-value LDAP field can be used. If the user has multiple other email addresses then a multi-value LDAP field must be used.
If using a secondary sync source, this is the LDAP field that contains the user's other email addresses. If the user has only one other email then a single value or a multi-value LDAP field can be used. If the user has multiple other email addresses then a multi-value LDAP field must be used.
The LDAP field that contains the user's second card id.
If using a secondary sync source, this is the LDAP field that contains the user's second card id.
The LDAP field that contains the user's department.
The LDAP field that contains the user's office location.
The LDAP field containing the user's primary card ID value.
The LDAP field containing the user's secondary card ID value.
The LDAP search to retrieve the user. The
{0} in the search is replaces with
* when listing all users, and
[username] when searching for a specific user. If no search is defined, the default is ([userNameField]={0}) .
IMPORTANT: The search must include the {0} value.
The LDAP field that contains the group's name.
The LDAP field that contains the group members.
The LDAP search to retrieve the group. The
{0} in the search is replaced with
* for all group searches.
If no search is defined, the default is
([groupMemberField]={0})
, which means get all entries with at least one member.
IMPORTANT: The search must include the
{0} value.
If
Y
, then the group member field contains the user's username. If
N
, then the group member field contains the user's DN.
572
Advanced LDAP Configuration
Table C.1. LDAP Config entries
C.1. LDAP Server Default Configuration
When a particular LDAP server type is selected (e.g. Novell eDirectory), PaperCut NG uses the following defaults to query the LDAP server. These defaults can be used as a starting point for customizing the LDAP searches or for supporting other server types.
C.1.1. Standard (Unix / Open Directory)
If the LDAP server is configured to support Unix based authentication then this schema type can be used. The following defaults are used.
Config name
ldap.schema.user-name-field ldap.schema.user-full-name-field ldap.schema.user-email-field ldap.schema.user-department-field ldap.schema.user-office-field ldap.schema.user-name-search ldap.schema.group-name-field ldap.schema.group-member-field ldap.schema.group-search ldap.schema.posix-groups
Table C.2. Unix / Open Directory LDAP default settings
Default value
uid cn mail departmentNumber
[not set]
(uid={0}) cn memberUid
(memberUid={0})
Y
C.1.2. Novell eDirectory Defaults
If the LDAP server is a Novell eDirectory then the following defaults are used.
Config name
ldap.schema.user-name-field ldap.schema.user-full-name-field ldap.schema.user-email-field ldap.schema.user-department-field ldap.schema.user-office-field ldap.schema.user-name-search ldap.schema.group-name-field ldap.schema.group-member-field ldap.schema.group-search ldap.schema.posix-groups
Table C.3. Novell eDirectory LDAP default settings
Default value
cn fullName mail
OU l
(&(cn={0})(objectClass=person)) cn member
(&(member={0})(objectClass=groupOfNames))
N
573
Advanced LDAP Configuration
C.1.3. Microsoft Active Directory Defaults
If the LDAP server is a Microsoft Active Directory then the following defaults are used.
Config name
ldap.schema.user-name-field ldap.schema.user-full-name-field ldap.schema.user-email-field ldap.schema.user-department-field ldap.schema.user-office-field ldap.schema.user-name-search ldap.schema.group-name-field ldap.schema.group-member-field ldap.schema.group-search ldap.schema.posix-groups
Table C.4. Active Directory LDAP default settings
Default value
sAMAccountName displayName mail department physicalDeliveryOfficeName
(&(sAMAccountName={0})(objectCategory=person)
(objectClass=user)(sAMAccountType=805306368)) sAMAccountName member
(&(member={0})(objectCategory=group))
N
574
Appendix D. Capacity Planning
This section discusses capacity planning considerations to allow administrators to plan future infrastructure requirements and make decisions about how to deploy the application.
PaperCut NG is designed to be self-maintaining, however it is important that the administrator understands the disk-space requirements and how this changes overtime.
D.1. Database Sizing and Growth
The most important part of capacity planning for PaperCut NG is the size and growth of the underlying database. All other aspects of the system manages itself, but care must be taken to ensure there is enough disk space to hold the growing database.
The size and growth of the database depends on the database being used. Each database uses a different format to store their data, therefore the growth characteristics of databases will differ. This section outlines the database growth characteristics of:
• The internal database (Apache Derby)
• Microsoft SQL Server
Database growth is very dependent on the usage patterns and therefore differs significantly from site to site. The best way to predict database growth is based on the rate of print jobs performed. Although, there is some overhead for other data (like users, groups, printers, etc.), this data is static and does not grow over-time. The majority of database growth is caused by print and transaction logs.
The growth calculations performed below provide an indication of growth per 1000 or 10000 print jobs. Then using these numbers and your estimate of the rate of printing in your organization a growth estimate can be made. See
Section D.1.3, “Sample database growth calculation” for an example of this calculation.
D.1.1. Internal database growth
Most PaperCut NG installations use the internal database. This database is suitable for most organizations,
The following graph shows the database size increase with the number of print jobs.
575
Capacity Planning
Figure D.1. Database growth using the internal database
These results show that the internal database grows by approximately 8.5MB per 10,000 print jobs.
D.1.2. SQL Server database growth
576
Capacity Planning
Figure D.2. Database growth using a Microsoft SQL Server database
These results show that a Microsoft SQL Server database grows by approximately 4.5MB per 10,000 print jobs.
D.1.3. Sample database growth calculation
This section provides a sample of how to estimate the database growth for your environment. To perform this calculation we need to make a number of assumptions. These assumptions should be adjusted to suit your organization. The assumptions are:
• 1 print job per user per day
• 20 working days in a month
• Therefore, 20 print jobs per user per month
Here is a sample database growth calculation based on a 500 user site using the internal database:
1.
Calculate the total number of print jobs expected for the month. (i.e. the total number of users multiplied by the number of print jobs). 500 * 20 = 10,000. So in this example, PaperCut NG is handling 10,000 print jobs a month.
2.
Calculate the monthly growth rate by dividing the jobs per month by 10,000 and then multiplying by the database growth rate (i.e. for the internal DB this is 8.5MB for 10,000 jobs). So, 10,000 / 10,000 * 8.5 =
8.5MB/Month. Therefore in this situation the internal database will grow by approximately 8.5MB per month.
3.
To estimate the growth per year, multiply the above by 12. Therefore in this situation, the database will grow by
10.2 * 12 = 122.4MB per year.
D.2. Print Archives Sizing and Growth
577
Capacity Planning
If PaperCut NG is configured to use Print Archiving then additional disk space will be required to store the archive files. The amount of space required will depend on a number factors unique to your site:
• Number of print jobs
• Average size of print jobs spool files
• Archive retension policy
• Backup plan
You will need to proactivly monitor your archive directorty size over time to understand your specific requirements.
For further information please see Chapter 24, Print Archiving (viewing and content capture).
D.3. Network Bandwidth Planning
With modern switched Ethernet networks, bandwidth is rarely a factor when planning PaperCut NG deployments.
The bandwidth consumed by PaperCut NG is usually dwarfed by the print document data - e.g. the Postscript spool data sent across the network. Bandwidth does however become a consideration when planning deployments crossing physical site boundaries such as networks linked via a WAN.
PaperCut NG uses an XML based web services protocol for communication between client-to-server and server-to-server. This protocol is very bandwidth efficient and designed to work well on low bandwidth and high latency networks.
D.3.1. Bandwidth Estimates
Bandwidth consumption can be summarized as follows:
D.3.1.1. Server-to-Server
Other than normal print server traffic (standard job spooling), PaperCut NG will generate XML-RPC based Web
Services based traffic on port 9191. Connections are made from the print server to the main PaperCut NG server
(Primary Server). Normal activity is around 1-2kb of traffic for for each print job. Connections are instigated from the secondary server. Network packets are only sent during printing activity.
D.3.1.2. Client-to-Server
Connections are instigated by the client inbound to the server on port 9191 and 9192 (Encrypted SSL). While at idle, the client consumes a few bytes once every minute (a keep-alive heartbeat). During print activity, up to 1-2kb per print job may be consumed depending on client popup settings.
If using account selection popups, the client must download the latest account list from the server whenever it is updated. The accounts are downloaded in a very efficient compressed format (approximately 20 bytes per account).
If you have 10's of thousands of accounts, and many clients running on remote sites with limited bandwidth, please
see Section D.4, “Managing Large Client Account Lists on Distributed Sites”.
D.4. Managing Large Client Account Lists on Distributed Sites
choose from. This account list is downloaded from the server whenever the account list is updated (i.e. new accounts added). The accounts are downloaded in a very efficient compressed format (taking approximately 10-20 bytes per account). This works very well on the vast majority of sites that have less than 10,000 accounts and are running on fast network connection.
On sites that have 10's of thousands of accounts and many workstations on remotes with bandwidth-limited WAN connections the accumulated bandwidth usage could be significant. To reduce this bandwidth usage, the clients can be configured to load the accounts from a file stored locally at each site. When the accounts are updated on the server, the file can be re-copied to each site. This distributes the client account list to all users at a site by sending the account list over the network only once, instead of one copy per workstation/client.
The process works as follows:
578
Capacity Planning
1.
On the server the administrator sets up a scheduled task to run the server command to generate the client accounts file as follows: server-command create-user-client-accounts-file
This creates the client account file in
[app-path]/server/data/client/client-accounts.dat
.
For more information running server-command
see Section A.1, “Server Commands (server-command)”. See
below for a sample batch file.
2.
Copy the client-accounts.dat
to each of the sites running the client software. It should be copied to a shared location accessible by all users running the client (e.g. a file share).
Tip
If you are using Microsoft distributed file system (DFS), you can copy the client account file to the distributed share. DFS will then efficiently distribute the file to all your remote sites.
3.
Configure the user client to run with the
--accounts-file "\\fileserver\path\to\client-accounts.dat" option. Clients at each site should use the accounts file stored locally at that site. The account file location can also be specified in the client's config.properties
file. For more information on client configuration settings
see Section A.5, “User Client Options”.
4.
Clients then load the accounts from the file and not directly from the server. The client will only load the accounts from the server if it fails to load the accounts file (i.e. the file does not exist).
Below is an example batch script that can be scheduled to run regularly on your PaperCut NG server. This should be scheduled to run whenever your shared accounts are updated (e.g. once a day). You will need to modify the script to reflect where PaperCut NG is installed and where the client file should be distributed.
REM Batch file to create and distribute the client accounts file
REM Create the client account file
[app-path]\server\bin\win\server-command create-user-client-accounts-file
REM === COPY TO SERVER 1 ===
REM Copy to destination server
REM Create temp file, so clients do not load an incomplete file.
copy /y [app-path]\server\data\client-accounts.dat \\svr1\share\accounts.tmp
REM Rename the temp file the final account file name used by the user clients move /y \\svr1\share\accounts.tmp \\svr1\share\client-accounts.dat
REM === COPY TO SERVER 2 === copy /y [app-path]\server\data\client-accounts.dat \\svr2\share\accounts.tmp
move /y \\svr2\share\accounts.tmp \\svr2\share\client-accounts.dat
D.4.1. Known limitations
There is one minor limitation of using the client account file approach. When the account selection popup appears, it will list all the defined accounts (even if the user does not have permission to charge to these accounts). The server still enforces security to ensure that users can only charge to the accounts they have permission to access.
579
Appendix E. PDL Transform Language
E.1.
PDL Transforms are an advanced PaperCut NG feature. This appendix is written assuming the reader has an understanding of printer description languages, and a basic knowledge of scripting.
A transform is a process that defines how to convert an input into a different output. In PaperCut NG, transforms are defined as simple scripts. There are a number of reasons for performing transforms on a print job. These include:
E.1.1.
E.1.1.1. Extending Compatibility
The output produced by one driver (such as PostScript) may not work on other printer brands without modification.
For example, "TRAY = 1" on one printer may map to "TRAY = UPPER" on another. Transforms can be used to automatically make this adjustment to a print job. This is particularly important in a Find-Me printing environment where a job rendered by one driver may not print correctly on another printer type without modifying the print job.
E.1.1.2. Modify Behaviour/Output
Much is possible with the power of transforms. Maybe it’s always enabling the "eco print" mode when an email is printed, or automatically removing the "stapling" option if accidently selected on a printer the does not support stapling. Another use-case is "virtual stationery". Legacy reports could for example have a logo automatically added to each page.
E.1.2.
Of note, PaperCut performs page analysis before transforms are applied. As such, a color logo added to a grayscale page, will be recorded in PaperCut as grayscale.
E.1.3. Definitions
Before covering the details of the transform language, it’s important to understand the following terms:
E.1.3.1. Page Description Language (PDL)
A language used to describe the appearance of a printed page e.g. PostScript, Printer Control Language (PCL).
E.1.3.2. Printer Job Language (PJL) Header
Attributes in a PJL header define print job characteristics such as duplex, color, paper sizes, or media trays. Many printers rely on a PJL header, though many attributes are printer/manufacturer specific.
E.1.3.3. Transform Script
A transform script defines a transform process to apply to a print job’s PDL. Transform scripts are written in a very simple scripting Domain Specific Language (DSL).
E.1.3.4. Source & Target
The transform process refers to source and target print queues. A desired transform is applied when a job is transferred from a specific source queue (a global queue) to a specific target queue.
E.1.4. Writing a transform
Transforms are text files placed in a location (directory structure) that determines when the script applies. The file’s name and location must conform to the following path:
580
PDL Transform Language
[install-path]/providers/print/[platform]/transforms/custom/[language]/[source]/[target].transform
language
- the PDL language of the print job (e.g. Postscript).
source
- the name of the queue that first received the print job (e.g. a global queue).
target
- the name of the queue the job is being transferred to print to.
For example, to apply a transform when a job is transferred from the queue named "Global Queue" to "Printer A", the transform file should be located at:
[install-path]/providers/print/[platform]/transforms/custom/postscript/global queue/printer a.transform
E.1.4.1. Matching rules for running a transform script
The following steps select the transform script to run for a redirection from printer type source to printer type
destination which both use printer language language.
1.
Look first in the the custom directory then in the system directory.
2.
Find the subdirectory whose name matches language e.g. if language is PostScript then look in
custom/postscript.
3.
Find the subdirectory whose name matches source. e.g. if source is PaperCut Global PostScript then look in
custom/postscript/pc-win. (NOTE: On PaperCut NG systems, pc-win is an alias that matches printer type
PaperCut Global PostScript).
4.
Find the file whose name matches destination. e.g. if destination is HP Color LaserJet then look for
custom/postscript/pc-win/hp.color.laserjet.transform. This does not exist so backtrack.
5.
Backtracking takes us to
custom/postscript/pc-win/default.transform
which does not exist, then
custom/postscript/default.transform
which does not exist, then
system/postscript/pc-win/hp.color.laserjet.type.transform which does exist. (NOTE: printer type is matched against *.type.transform and printer name is matched agaist *.name.transform before printer type and name are matched against *.transform*)
6.
Thus system/postscript/pc-win/hp.color.laserjet.transform is selected.
E.1.5. Examples
There are two example sources that script authors may find useful as starting points or reference:
[install-path]/providers/print/[platform]/transforms/examples
[install-path]/providers/print/[platform]/transforms/system
Important
Transforms in the system directory are used by the PaperCut Global Print Driver. They are system provided. You should not place your own scripts in the system directory. Your own scripts should be in the custom directory. Any changes made in the system directory will be overwritten in an upgrade.
E.1.6. Transform Language Functions & Specification
Command
var = expression
Description
Evaluate the expression and assign the variable var with the result.
581
PDL Transform Language
Command
IF condition THEN statement
FIND pattern [options]
FIND pattern REPLACE text [options]
STRIP_HEADER
DELETE_UNTIL text
INSERT ofs len text
DELETE ofs, len
REPEAT_ALL num_copies
Table E.1. PDL transform command functions
Description
Evaluate the condition expression, and if true execute the statement.
Find the pattern in the spool file, and assign $0, $1, ... with the regular expression capture group.
FIND as above, then replace the string matched by the pattern with text.
Strip any PJL, XPIF, PostScript or other header in the spool file.
Delete from the start of the spool file up to but not including the first occurrence of text.
Insert the string text at the spool file offset ofs, after deleting len bytes.
Delete len bytes from the spool file, starting at the offset ofs.
Make num_copies of the input spool file in the output spool file after applying all other modifications.
E.1.6.1. Assignment
var = expression
e.g. x = 1
Evaluate the expression and assign the variable var with the result. If the expression contains any
$[N] and/or
%variable% tokens, they are replaced with their current values. To prevent variable substitution, include
__no_replace__ in the variable name e.g. __no_replace__template.
E.1.6.2. IF THEN
IF condition THEN statement
e.g.
IF duplex THEN pjl_duplex = "ON"
Evaluate the condition expression, and if true execute the statement.
E.1.6.3. Rules for evaluating expressions
1.
A number x is true if x != 0.
2.
A string pattern is true if it can be found in the spool file using the rules in the FIND pattern [options] below.
Strings can be regular expressions or plain strings, and have two optional attributes FIRST | LAST and a search distance. FIRST | LAST does not affect logical evaluation. Search distance does. e.g.
/<<.*?\/ProcessColorModel\s*\/(DeviceCMYK|DeviceGray).*?>>\s*setpagedevice/ 10000 will be true if this regular expression is matched in the first 10,000 bytes of the spool file.
3.
Numbers can be compared with
==
,
!=
,
<
,
>
,
<= and
>=
.
4.
Strings can be compared with
== and
!=
. These comparisons are case insensitive and do not perform the searches in rule 2 above.
5.
Logical expressions, such as the results of 1-4 above, can be combined with NOT, AND, OR, XOR, and
(...)
582
PDL Transform Language parentheses. e.g.
x == 1 AND NOT (y > 2 OR z <= 3)
E.1.6.4. FIND
FIND pattern [options]
where the pattern is a regular expression (regex) or string.
FIND /regex/ [REPLACE text] [options]
FIND "string" [REPLACE text] [options]
FIND searches for the pattern (a string or a regex) in the spool file and assigns
$0
,
$1
, ... from the resulting regular expression capture groups. If the pattern is a string, then only
$0 is assigned.
e.g
FIND /<<.*?\/ProcessColorModel\s*\/(DeviceCMYK|DeviceGray).*?>>\s*setpagedevice/ could set $0 to "<< /ProcessColorModel /DeviceCMYK >> setpagedevice" and $1 to "DeviceCMYK" on a match.
E.1.6.4.1. Options
• FIRST: Return the first match in the spool file. This is the default
• LAST: Return the last match in the spool file.
• n: Any positive integer. Search n bytes of the spool file. The default is to search one megabyte. A value of zero
(0) will search through the entire spool file.
E.1.6.5. FIND REPLACE
FIND pattern REPLACE text [options]
where the pattern is a regular expression (regex) or string.
e.g
FIND "Letter" REPLACE "A4"
FIND /(\w+)\s=\sGrayscale/ REPLACE "$1 = BlackAndWhite"
FIND /MODE = \w+/ REPLACE "MODE = %my_var%"
FIND /MODE = \w+/ REPLACE "MODE = %my_var%" 2000
The FIND works as described above. Then REPLACE substitutes all the
$[N] and
%variable% values in the text, before replacing the string matched in the spool file with the substituted text.
E.1.6.6. ADD_HEADER
ADD_HEADER text
e.g.
ADD_HEADER my_header
Insert the string text as a header in the spool file.
583
PDL Transform Language
E.1.6.7. STRIP_HEADER
STRIP_HEADER
Strip any PJL, XPIF, PostScript or other header (that our developers know about) from the spool file.
E.1.6.8. DELETE_UNTIL
DELETE_UNTIL text
e.g
DELETE_UNTIL "%!PS-Adobe-3.0"
Delete from the start of the spool file up to but not including the first occurrence of text.
E.1.6.9. REPEAT_ALL
REPEAT_ALL num_copies
e.g
REPEAT_ALL 3
Make num_copies of the input spool file in the output spool file after applying all other modifications.
Use this option for printers that don't support spool files copies commands, typically printers without hard disks. You will usually detect the copies command in the source spool file then use REPEAT_ALL to repeat the source spool files the same number of copies.
Important
Changes to the number of copies of a printed made here will not be reflected in the Job Log.
E.1.6.10. INSERT
INSERT ofs len text
e.g
INSERT regex_ofs regex_len my_replacement
Insert the string text at the spool file offset ofs, after deleting len bytes.
Setting ofs to
-1 will append text to the end of the spool file. In general, setting ofs to
-n will insert text n - 1 bytes before the end of the spool file.
E.1.6.11. DELETE
DELETE ofs len
e.g
584
PDL Transform Language
DELETE regex_ofs regex_len
Delete len bytes from the spool file, starting at offset ofs.
It is equivalent to:
INSERT ofs len ""
E.1.6.12. Pre-Populated Variables
Variable Description Example Type
pc_pages pc_copies pc_page_width pc_page_height pc_paper_name pc_grayscale pc_duplex pc_tumble
Number of pages in the spool file
11
Number of copies in copies command in spool file, if one is detected. 1 otherwise.
1
Page width in mm
210
Page height in mm
Paper size name
Is the document grayscale?
Is the document duplex?
297
"A4"
True
False
Is the back side of a duplex job rotatated 180 degrees?
False number number pc_docname pc_user pc_server pc_printer pc_driver
Name of the document
Name of the user
Print server name
Printer name
Name of the printer driver
"Homework.doc"
"Josh"
"Server1"
"Hall printer"
"HP Color LaserJet CM4540 MFP
PCL 6 (0.3.1545.9108)" string
"2014-08-15" string pc_iso_date pc_uid
Current date in ISO format
A randomly generated ID
pc_docname__clean__
'Cleaned' version of pc_docname. All character that will prevent display in
PostScript, PJL or XML removed.
"Homework.doc"
"Josh" pc_user__clean__
'Cleaned' version of pc_user.
Table E.2. Pre-populated PDL transform script variables
string string string string string string number number string boolean boolean boolean
E.1.7. Test Mode
Test mode is designed to accelerate the development, testing and debugging of transform scripts. Test mode is enabled by adding the following line to a transform script:
ENABLE_TEST_MODE or by setting
585
PDL Transform Language
EnableTransformTestMode=yes in the print-provider.conf file. The test mode option should only be enabled while developing scripts.
Test mode causes the system to output additional log files to assist in developing and validating transforms. These files are located at:
[install-path]/providers/print/[platform]/transforms/logs/
The test mode files created are:
[job-id].log
[job-id].before
[job-id].after
Table E.3. PDL transform test mode output files
This file contains logging information to help you understand the transform script’s state and variables.
The print job spool file BEFORE transformation.
The print job spool file AFTER transformation.
Tip
Consider using a "visual diff" program to help compare before and after files.
Important
Always disable test mode after developing your transform script. Test mode adds a considerable performance overhead and should not be used in a production environment.
E.1.8. Tips & Tricks
• Develop your scripts in TEST_MODE to help compare script behavior.
• Use existing examples as starting points.
• Print the same documents from source and destination printer drivers, and diff the resulting spool files. In most cases the things you will need to modify are in the diff. e.g. One file has a header and the other does not, or one file sets color/grayscale with one string and the other file uses a different string.
• Look at a PostScript Printer Description (PPD) file of the destination printer, and copy PostScript snippets into a transform.
586
Appendix F. Upgrading From a Previous
Version
This appendix describes the PaperCut NG standard upgrade procedure. PaperCut NG supports upgrades using a simple install-over-the-top procedure. We recommend reviewing all steps prior to commencing the upgrade procedure.
F.1.
F.1.1. Before you start
1.
user clients and release stations. As we strive to maintain backwards compatibility between versions, it is generally not required to upgrade these components along with an Application Server upgrade. However we do recommend that you do upgrade all components as best practice.
By contrast, all site servers must normally be upgraded at the same time as your Application Server.
2.
Check the release notes to determine if a database schema upgrade is to be performed. If the release does require a database schema upgrade, you may need to allow extra time for the upgrade process.
F.1.2. The recommended upgrade procedure
1.
Download the PaperCut NG installer for your platform. In accordance with best practice we recommend that you archive your install programs just in case you need to reinstall in the future or roll back to a previous version.
2.
Download the PaperCut NG installer for your platform. In accordance with best practice we recommend that you archive your install programs just in case you need to reinstall in the future or roll back to a previous version.
Take some time to read the release notes for this version as they may highlight considerations during upgrades.
3.
Schedule approximately 10 minutes downtime. It is suggested to choose a time of day with minimal network activity. If there is a large volume of data in the system (for example if the system has been running for more than a year, or there are more than 5,000 users) the upgrade may take longer. With very large installations it may be appropriate to schedule an hour or more of downtime.
4.
Take a point-in-time backup of the data by pressing the Backup Now button located under Options
→
Backups. This will ensure you have a copy of the important data.
5.
As a precaution on very large systems, we recommend backing up the whole PaperCut NG directory. Existing overnight backups may have taken care of this task, however take a few moments to grab an up-to-date backup now. For example, create a zip archive of the directory:
C:\Program Files\PaperCut NG\ or the equivalent path on Linux or Mac.
6.
Run the installer downloaded in step 1 and install into the same location as the existing install.
7.
After the install has completed allow a few minutes before accessing the system. The system may need to perform a database upgrade and this will be performed in the background. If you try to access the application while a database upgrade is in progress a message displaying the upgrade status will be displayed.
IMPORTANT: Do not shutdown the application while an upgrade is in progress. Wait for the upgrade to complete.
8.
After the install is complete, log into the system and perform some tests to ensure all is working as expected and the system is monitoring user activity as expected. Sites running on Novell OES Linux are advised to restart their iPrint Print Manager.
Administrators may find the post upgrade test plan
[http://www.papercut.com/kb/Main/PostUpgradeTestPlan] useful.
587
Appendix G. Upgrading from PaperCut
Quota
This appendix describes the process for moving from PaperCut Quota to PaperCut NG, and includes instruction of importing user balances and restriction settings from the old PaperCut Quota installation.
These instructions assume that PaperCut NG will be installed on the same machine as PaperCut Quota, however the instructions can also be applied when PaperCut NG is installed on a new machine.
G.1. Upgrade process
G.1.1. Step 1 - Stop and disable PaperCut Quota
Firstly the PaperCut Quota services should be stopped to ensure that they do not interfere with PaperCut NG. You should not uninstall PaperCut Quota at this stage because we need the user database to import user balances into
PaperCut NG.
To stop and disable the PaperCut Quota services:
1.
Open the Windows services manager ( Start
→
Control Panel
→
Administrative Tools
→
Services).
2.
Find the PaperCut Print Charging service.
3.
Right-click on the server and select the Properties menu.
4.
Change the Startup Type to Disabled
5.
Press the Stop button to stop the service.
6.
Press OK to save the settings changes.
G.1.2. Step 2 - Install PaperCut NG
Install PaperCut NG as discussed in Chapter 2, Installation.
During the setup wizard, it is recommended that the user import settings be set up in the same way as was configured in PaperCut Quota. For example, if you import users from the full Active Directory domain in PaperCut
Quota, also set this up in PaperCut NG.
Check that the users have been imported correctly. To adjust the user import settings and re-perform the user synchronization process, go to the Options
→
User/Group Sync screen. This is similar to the Tune-up function in
PaperCut Quota.
Once installed it is recommended that the groups are set up in the same way as in PaperCut Quota. Groups are used to determine the default settings for new users and also how quotas are allocated. For more information on
groups see Section 6.1, “Groups in PaperCut NG”.
G.1.3. Step 3 - Configure and test printers
The next step is to set up the printers in PaperCut NG to reflect the require page costs and print restrictions. To do this:
1.
Navigate to the Printers section.
2.
Select the printer to adjust by clicking on the printer name.
3.
Enter the cost and filter settings.
4.
Press the OK or Apply buttons to save the changes.
588
Upgrading from PaperCut Quota
Tip
If all your printers are configured with similar costs and filters then the settings can be copied from one
printer to the other printers. This is discussed in Section 7.3, “Copying Printer Settings”.
Tip
It is recommended that the administrator set up the
[template printer]
. This printer is used as a template when new printers are added to the system. The template printer is discussed in detail in
Section 7.2, “The Template Printer”.
To ensure that the printers are setup correctly, perform a test print to one of the configured printers. Once printed, check the print log (Printers
→
Print Log) that the job was recorded and the correct cost calculated.
G.1.4. Step 4 - Import the existing User Balances
In Professional (Client Billing) installations, this step can be optional because shared accounts are used instead of user account balances. If you do not wish to import user balances, skip to the next step.
Moving the user balances and restricted status from PaperCut Quota to PaperCut NG is a simple process. If the server is running Windows then:
1.
Navigate to the Users section.
2.
Click the Batch import ... action (on the left).
3.
Press the Browse and locate the PaperCut Quota user database (
PCUserDB.mdb
). This is typically located at:
C:\Program Files\PaperCut\Database\PCUserDB.mdb
4.
Press the Import button to start the import process.
5.
Upon successful completion, the number of users updated and created will be displayed.
6.
Perform some checks of the user balances and restricted statuses to ensure they are set to the values from
PaperCut Quota.
If the PaperCut NG server is not running on Windows, the PaperCut Quota database converter can be run manually on a Windows system, and the resulting text file can then be imported in a process similar to the above. To convert the PaperCut Quota user database manually:
1.
Copy the
[app-path]/server/bin/win/PCQuotaExport.exe
file from the server (running the non-windows OS), to the Windows machine running PaperCut Quota. Copy the exporter to the PaperCut Quota database directory (usually c:\Program Files\PaperCut\Database
).
2.
Open the command prompt, by running cmd.exe
from Start
→
Run.
3.
Change to the PaperCut Quota database directory. e.g.
cd "c:\Program Files\PaperCut\Database"
4.
Run the converter, with the location of the
PCUserDB.mdb
as the argument. For example:
PCQuotaExport.exe "PCUserDB.mdb" > user-export.txt
If running the exporter from a different directory to the database, the full path to the database should be provided.
589
Upgrading from PaperCut Quota
5.
The above command creates a text file called user-export.txt
that contains the user data from PaperCut
Quota. The file can be opened in a text editor to review the contents.
6.
The file can then be imported into PaperCut NG. First log in to PaperCut NG.
7.
Navigate to the Users section.
8.
Click the Batch import ... action (on the left).
9.
Press the Browse and locate the user-export.txt
file, created in the above step.
10. Press the Import button to start the import process.
11. Upon successful completion, the number of users updated and created will be displayed.
12. Perform some checks of the user balances and restricted statuses to ensure they are set to the values from
PaperCut Quota.
G.1.5. Step 4b - Import the existing Accounts
Moving the accounts and their settings from PaperCut Quota to PaperCut NG is a simple process, that is described in detail below. This is particularly important in a Professional (Client Billing) installation where shared accounts are used to charge print jobs to client accounts. If this is not important in your environment then please skip this step.
Tip
When accounts are imported they inherit the access control settings from the
Template Account
.
By default the
Template Account is configured to allow all users access to the account. If you do not want all users to have access the imported accounts, change the security settings on the
Template Account before importing.
To import the accounts when the server is running Windows then:
1.
Navigate to the Accounts section.
2.
Click the Batch import ... action (on the left).
3.
Press the Browse and locate the PaperCut Quota database (
PCUserDB.mdb
). This is typically located at:
C:\Program Files\PaperCut\Database\PCUserDB.mdb
. This database contains all of the accounts.
4.
Press the Import button to start the import process.
5.
Upon successful completion, the number of users updated and created will be displayed.
6.
Perform some checks of the accounts and settings to ensure they are set to the values from PaperCut Quota.
If the PaperCut NG server is not running on Windows, the PaperCut Quota database converter can be run manually on a Windows system, and the resulting text file can then be imported in a process similar to the above. To convert the PaperCut Quota user database manually:
1.
Copy the
[app-path]/server/bin/win/PCCBAccountExport.exe
file from the server (running the non-windows OS), to the Windows machine running PaperCut Quota. Copy the exporter to the PaperCut Quota database directory (usually c:\Program Files\PaperCut\Database
).
2.
Open the command prompt, by running cmd.exe
from Start
→
Run.
3.
Change to the PaperCut Quota database directory. e.g.
cd "c:\Program Files\PaperCut\Database"
4.
Run the converter, with the location of the
PCUserDB.mdb
as the argument. For example:
PCCBAccountExport.exe "PCUserDB.mdb" > account-export.txt
590
Upgrading from PaperCut Quota
If running the exporter from a different directory to the database, the full path to the database should be provided.
5.
The above command creates a text file called account-export.txt
that contains the user data from
PaperCut Quota. The file can be opened in a text editor to review the contents.
6.
The file can then be imported into PaperCut NG. First log in to PaperCut NG.
7.
Navigate to the Accounts section.
8.
Click the Batch import ... action (on the left).
9.
Press the Browse and locate the account-export.txt
file, created in the above step.
10. Press the Import button to start the import process.
11. Upon successful completion, the number of accounts updated and created will be displayed.
12. Perform some checks of the accounts and settings to ensure they are set to the values from the previous version.
G.1.6. Step 5 - Upgrade client software
The old PaperCut Quota client software is not compatible with PaperCut NG. The old client software must be uninstalled off all workstations and the new client software deployed. The zero-install deployment method can
Note: It is not 100% accurate to claim that the old client software must be removed. Once the old server-side software is disabled, the old client will sit in an inactive state and do no harm. Having said that however, it will consume some system resources on the workstations and hence it is generally recommended that it be uninstalled.
G.1.7. Step 6 - Optionally uninstall PaperCut Quota
Once the PaperCut NG installation is completed and tested you can optionally uninstall PaperCut Quota. If you would like to view historical print data then we recommend keeping the old application installed so you can view the historical data. If this is not important then the application can be uninstalled.
To uninstall:
1.
On the Windows server running PaperCut Quota, go to: Start
→
Control Panel
→
Add or Remove
Programs).
2.
Find and select PaperCut Quota in the list of installed programs.
3.
Click the Remove button to start the uninstall process.
591
Appendix H. Example User Information
Sheets
Usually administrators are responsible for educating users about policy or system changes when PaperCut NG is deployed on their network. Providing the right information and guidelines for users is important for the success of any new system.
This chapter contains examples of information sheets which could be distributed to users. The purpose of these information sheets is to assist the administrator in providing important information about the new system and how to use it. These examples can act as templates or starting points for your own information sheets.
We suggest you enhance the information sheets to include information such as:
• Details of your organization's printing policy, such as the standard cost per page and whether or not more printing balance may be added after the user has run out.
• Location of the printers.
• How to report problems or receive assistance, such as refunding a failed print job.
• How to contact the help desk.
• How to provide feedback about the new system.
H.1. Example 1: Printing with the popup confirmation window
New software to manage printing costs has been installed on the network. To allow effective printing please make sure you understand the following points:
H.1.1. Popup Confirmation Dialog
After sending a print job a popup dialog will appear and ask you to confirm the details. Click Print to confirm the job and agree to the cost. Otherwise, click Cancel if you no longer wish to print the job.
Figure H.1. Client Popup Confirmation Window
Note: Large documents might take a while to display the number of pages and cost.
H.1.2. The Printing Balance Window
After logging on to a workstation you will see a window showing your printing balance.
592
Example User Information Sheets
Figure H.2. Printing balance window showing $10.00 of printing balance
If the balance window is not visible (or if you have closed or minimized it) click the icon in your system tray to show it again.
Figure H.3. Printing balance icon in the system tray
When you confirm a print job by pressing Print in the popup dialog the cost will be deducted from your printing balance.
H.1.3. Resolving Problems
If the popup window does not appear or the icon is missing from your system tray, the print control system may not be active and printing will be denied. Please try restarting your system, or ask for assistance if problems continue.
H.1.4. Printing Denied Message
If you do not have enough printing balance for a job you will see a Printing Denied message, and your document will not be printed.
Figure H.4. Printing denied message
H.2. Example 2: Printing with shared accounts (for staff)
New software to manage printing costs has been installed on the network. The system will allow the college to track printing expenses according to the individual, faculty or department. To allow effective printing please make sure you understand the following points:
H.2.1. Shared Account Selection Popup Window
593
Example User Information Sheets
After sending a print job a popup dialog will appear and ask you to confirm the details. The print job may be charged to your personal account (using your personal printing balance), or to a shared account (a faculty, using the faculty budget). After choosing an account to charge, click Print to confirm the job and agree to the cost. Otherwise, click
Cancel if you no longer wish to print the job.
Your personal account should be selected when printing non-faculty related documents. For example:
• Printing your personal bank or phone statement.
• Occasional personal use of a photo printer.
A shared account should be selected for faculty printing. For example:
• Student handouts.
• Student reports.
• Course syllabus.
• Class lists.
Selecting the right faculty account from the drop-down list is important. Different staff members will have access to different faculty accounts. If an account that you require is missing from the list, please contact the system administrator. Please note that the use of faculty accounts is monitored and faculty heads are provided with printing reports.
Figure H.5. Shared Account Selection Popup
Note: Large documents might take a while to display the number of pages and cost.
H.2.2. Resolving Problems
If the popup window does not appear or the icon is missing from your system tray, the print control system may not be active and printing will be denied. Please try restarting your system, or contact the network administrator if problems continue.
594
Example User Information Sheets
Figure H.6. Printing balance icon in the system tray
H.2.3. Printing Denied Message
If you do not have enough printing balance for a job you will see a Printing Denied message, and your document will not be printed.
Figure H.7. Printing denied message
H.3. Example 3: Printing using a release station
The printing procedure has been changed on the network. Now when you print a job, it will not print it immediately, but instead will be held in a queue. You will need to attend a release station and release the job to print. This new system ensures that you are present and ready to collect your job. Please follow the steps listed below:
1.
Select Print from your application (e.g. File
→
Print...)
2.
Walk up to the release station located next to the printer.
3.
Log in to the release station using your network username and password.
Figure H.8. Login screen
4.
After login the system will display a list of print jobs. Search for your document by looking for your user name or document name.
595
Example User Information Sheets
Figure H.9. Print jobs waiting in a release station
Note: If you can't find your print job it may have 'timed out'. Print jobs are held by the release station for 30 minutes. If they have not been released after this time they will be deleted.
5.
Check the cost and details of the job.
6.
Click Print to release the job. Please note that it may take up to 30 seconds for the printer to warm up after clicking Print.
H.4. Example 4: Refunding a print job (for staff)
Selected staff members have been granted access to refund print jobs in the new print control system.
Reasons for refunding a print job may include:
• There was a paper jam or the document failed to print correctly.
• The document failed to print at an acceptable quality.
As a staff member you will need to make an assessment about whether or not to issue a refund. A print job may be fully or partially refunded. A full refund is the more common scenario.
H.4.1. Refund
To issue a refund:
• Log in to the PaperCut NG administration interface at http://servername:9191/admin using your network username and password.
• Find the user to refund from the Users tab by entering their username in the Quick find box or clicking on their username.
• Click on the Job Log tab. This will list recent print jobs printed by the user, with the most recent at the top.
• Look for the print job that needs refunding and click the refund link next to it.
Figure H.10. Job Log
• Enter a comment and press OK.
596
Example User Information Sheets
Figure H.11. Refunding print job
H.4.2. Action Refund Requests
To action a refund request:
• Log in to the PaperCut NG administration interface at http://servername:9191/admin using your network username and password.
• Navigate to Printers
→
Refunds.
• Locate the user's refund request.
• To approve/reject click the approve/ reject link.
Figure H.12. Approving a refund request from the Refunds tab in the admin interface.
• To get an overview of user's refund requests click the other link. Use this to edit the refund amount and write a comment.
597
Example User Information Sheets
Figure H.13. Overview of user's refund request
H.5. Example 5: Adding credit using a TopUp/Pre-Paid Card
New software to manage printing costs has been installed on the network. Without sufficient printing credit in your account printing will be denied. To add more credit you can buy TopUp/Pre-Paid Cards from the nominated venues around the college. Each card is a voucher or coupon with a unique number. Please make sure your card number is kept secret until use.
To add credit to your account using a card:
• Log in to a computer. Soon after login, your printing balance window will appear.
• Click the Details ... link on the balance window.
Figure H.14. Balance window showing the Details link
• A web page will open requesting your network username and password.
• After logging in click the Redeem Card link from the left menu.
598
Example User Information Sheets
• Enter the number from the card. It should be entered exactly as shown on the card including any dashes (-).
Figure H.15. Redeem Card page
• Click Redeem Card. The value of the card will immediately be added to your printing balance.
• Click Summary from the left menu and check your balance to confirm the card's value has been added to your account.
Note: The card is valid for a single usage only. The card should be recycled or disposed of after use.
H.6. Example 6: Printing from a wireless network or laptop (Web Print)
The Web Print system allows students to print to college printers from their own laptops without the need to install drivers. It works by offering a facility to upload documents in formats such as PDF, DOC etc using a standard web browser. You access Web print from the print system's User Web Tools.
The system can print documents that have the following file formats:
Application
Adobe Reader 9
Microsoft Office Excel 2007
Microsoft Office PowerPoint 2007
Microsoft Office Word 2007
Microsoft XPS Document Writer
Table H.1. Web Print Supported Applications and File Formats
File Format(s)
XLS, XLSX, etc.
PPT, PPTX, etc.
DOC, DOCX, etc.
XPS
Free PDF printers are available for download from several websites such as PDF Creator
[http://sourceforge.net/projects/pdfcreator/files/]. Printing from any application using the normal print function will produce a PDF document that can be uploaded using this system.
All Vista and higher versions of Microsoft Operating Systems have a virtual XPS printer that works similarly to the
PDF printers.
599
Example User Information Sheets
Figure H.16. Printing using PDF Creator or XPS Document Writer
To print a document:
1.
Open your browser to https://[server-name]:9192/user and log in using you network username and password. Select the Web Print link in the navigation menu.
Figure H.17. Web Print link
2.
The front page contains a list of your active and recently submitted Web Print jobs. At first the list will be blank.
Later the list will show the status of submitted jobs.
600
Example User Information Sheets
Figure H.18. Web Print front page showing active jobs
You may see a message at the top of the Active Jobs page with other information that you may need to know to use Web Print.
Figure H.19. Instructions for using the system
3.
Click Submit a Job to start the Web Print wizard.
4.
The first step of the Web Print wizard is selecting a printer where your job will be printed.
Figure H.20. Choosing the printer
Instead of the Printer List you may see a clickable map or other graphical representation of the printers that are available.
5.
Select the number of copies to print. (Users that have permission to print to shared accounts will see additional options on this page.)
601
Example User Information Sheets
Figure H.21. Enter the number of copies
6.
After selecting the print options and/or account selection settings, the third and final step in the Web Print wizard is to upload a document to print. This page lists the applications and associated file extensions that are supported. Once a document has been selected and Upload & Complete is pressed the file will begin uploading to the server.
602
Example User Information Sheets
Figure H.22. Upload a document
7.
Once the document upload is complete you will be returned to the front Web Print page. The table now displays the status of your job. Jobs may be queued during times of high load. The status will change to indicate the progress of the job from rendering to printing, and job details such as cost and number of pages will be populated when known. You may stay at this page to track the status of the job or navigate away or close the browser. The job will not be affected.
603
Example User Information Sheets
NOTE: If the printer selected in step 4 has print release enabled, your job will be held until you release it by logging into the release station.
604
Appendix I. END USER LICENSE
AGREEMENT (EULA)
END USER LICENSE AGREEMENT
•
1 - AGREEMENT
• This End User License Agreement is between PaperCut Software International Pty Ltd (ACN 124 440 400) of
Ground Floor, 1 Oxley Road, Hawthorn, Victoria 3122, Australia (PaperCut), and:
• (a) if there has been no charge for the license (an Evaluation License), the company or other entity that installed the Software for the purpose of the evaluation; or
• (b) if there has been a charge for the license (a Production License), the company or other entity that applied for the Production License as set out in the Company Details tab on the Website.
•
2 - DEFINITIONS
• Affiliate means an entity owned by, controlling, controlled by, or under common control with, directly or indirectly, an entity. For this purpose, one entity "controls" another entity if it has the power to direct the management and policies of the other entity (for example, through the ownership of voting securities or other equity interest, representation on its board of directors or other governing body, or by contract).
• Agreement means the terms and conditions in this End User License Agreement and the Support Policies, and, if this is a Production License any details in the Contract Details, as may be amended by a Variation.
• Authorised Platform means servers, workstations, printers, multi-function devices and mobile devices that are owned, leased or controlled by You or Your Affiliates on which the Software is designed to be used.
• Confidential Information means any non-trivial non-public information however recorded, preserved, disclosed or communicated (whether directly, indirectly, orally or by writing), disclosed by either party or its
Representatives to the other party or its Representatives in connection with this Agreement that is or, ought to have been, understood by the Parties, using reasonable business judgment, to be confidential. The
Software and related documentation, License Keys and this Agreement, including the terms, pricing and Fees payable, are agreed to be the Confidential Information of PaperCut.
• Contract Details means the details of any transaction for a Production License that relate to the Software license, including the maximum number of Users (or other license metric that is applicable to the particular
Software program), the Premium Upgrade Assurance service and applicable Fees and Taxes, that are advised to You and/or are selected, or entered, by You on the Website prior to You placing Your order for the
Production Licence, or to which You have otherwise agreed in writing with PaperCut.
• Discloser means the party that makes a disclosure of Confidential Information.
• Effective Date means:
• (a) for an Evaluation License, the first date of installation of the Software on any of Your Authorised
Platforms; or
• (b) for a Production License, the date that the person clicked "I Agree" during the sign on process.
• Evaluation License means the right to use the Software in accordance with clause 4.1.
• Fees means the amount payable for the relevant Software license, the Premium Upgrade Assurance service or other items acquired under the Agreement, as applicable, exclusive of Taxes.
• Intellectual Property Rights means copyright, moral rights, trade mark, design rights, service marks, patent, semiconductor or circuit layout right, trade secrets, know-how, database rights or other rights in the nature of intellectual property rights (whether registered or unregistered), or any right to registration of such rights, existing anywhere in the world, or protected by statute from time to time, whether created before, on or after the Effective Date.
• License Key means any form of license file, lock, password or other mechanism that may be used to control access to, or manage use of, the Software.
• PaperCut Marks means all trademarks, service marks, logos or other words or symbols identifying the
605
END USER LICENSE AGREEMENT (EULA)
Software, Premium Upgrade Assurance service, PaperCut Customer Care service or PaperCut's business
(whether owned by PaperCut or any PaperCut Affiliate), and all trademarks, service marks, logos or other words or symbols identifying any third party software that is licensed by the third party to Papercut and integrated in the Software.
• Premium Upgrade Assurance means the services described in clause 5.
• Production License means the right to use the Software in accordance with clause 4.2.
• Recipient means the party that receives a disclosure of Confidential Information.
• Representatives means the employees, agents, contractors of a party, or those of any Affiliate, and the professional representatives of a party providing advice in relation to this Agreement, including the lawyers, bankers, auditors, accountants and insurers of a party.
• Software means the object code version of PaperCut's software program made available to You, and any
Updates and Upgrades that may be made available to You by PaperCut in its discretion, under this
Agreement. The term Software does not include any beta, pre-release or other special release programs.
• Support Polices means PaperCut's document that describes the policies, processes and scope of support services for the Software, as are posted on the Website under the heading Support. The Support Policies may be updated by PaperCut in its discretion from time to time.
• Taxes includes goods and services taxes or other sales taxes, duties, withholding taxes, levies, imposts or other charges or duties levied by any federal, state or local government which arise out of or in connection with the Software, Premium Upgrade Assurance service or this Agreement, and any interest, penalties or liabilities incurred on such amounts, but excludes taxes based on the net income of PaperCut.
• Update means any bug fixes, patches or workarounds for the Software that have been produced primarily to overcome defects in the Software without significantly altering the functionality of the Software.
• Upgrade means a version of the Software that has been produced primarily to extend, alter or improve the
Software by providing additional functionality or performance enhancements (whether or not defects are also corrected). Upgrades do not include any software that is marketed by PaperCut as a different product.
PaperCut shall determine in its discretion whether any software is an Upgrade or a different product.
• User means an identifier (individual's name or generic term such as "purchasing officer") that is listed as a user in the Software's database. Any User that is defined by a generic term may only be used by a single individual. All Users from You and/or Your Affiliates who have identifiers listed as users in the Software's database are included in aggregate in the total number of Users.
• Variation means any addition, deletion or substitution to any part of this Agreement that is made in accordance with this Agreement.
• You (and Your) refer to the other party to this Agreement, being the entity that is the licensee of the Software.
• Website means PaperCut's website from which You can acquire the Software, Premium Upgrade Assurance service, additional Software programs, add more Users or other license usage or extended Your Premium
Upgrade Assurance service.
•
3 - AGREEMENT AND LICENSE
• 3.1 In the case of an Evaluation License, the person that installs the Software and clicks "I Agree" during the installation process warrants to PaperCut that he/she has authority to enter into this Agreement on behalf the entity that is his/her employer.
• 3.2 In the case of a Production License, the person that clicked "I Agree" during the sign-on process warrants to PaperCut that he/she has authority to enter into this Agreement on behalf the entity that was entered into the Company Details tab on the Website during the sign-on process.
• 3.3 By using the Software You accept this Agreement as from the Effective Date, and acknowledge that You are bound by the terms and conditions of the Agreement.
• 3.4 PaperCut may send a "proof of purchase" confirmation email or other document (Order Confirmation) after You acquire a Production License, summarising the Contract Details. If You do not notify PaperCut in writing of any discrepancy in the Contract Details as set out in the Order Confirmation within 48 hours of receiving it, then you accept the Contract Details as set out in the Order Confirmation.
•
Evaluation
3.5 If You requested a free of charge Evaluation License for the Software (via the Website or other means)
606
END USER LICENSE AGREEMENT (EULA) then PaperCut will make the Software available for You to download from the Website, subject to Your acceptance of this Agreement. If You accept this Agreement then You acquire an Evaluation License, from the Effective Date until the license is terminated in accordance with clause 3.7. There is no Fee payable for an Evaluation License.
• 3.6 PaperCut does not provide Premium Upgrade Assurance services for Evaluation Licenses, but may, in its discretion, provide assistance, advice and error correction services to support Your evaluation of the
Software.
• 3.7 A Evaluation License:
• (a) terminates automatically after 40 days from the Effective Date, unless extended by agreement with
PaperCut;
• (b) will be terminated if the Agreement terminates in accordance with clause 12.
•
Upgrading to a Production License
3.8 You may upgrade an Evaluation License to a Production License by completing and agreeing the
Contract Details via the sign-on process on the Website and agreeing to pay the relevant Fees and Taxes.
You may also order Premium Upgrade Assurance services at the same time. The Production License and any Premium Upgrade Assurance service will be provided on the terms and conditions of this Agreement. In the case of a Production License, PaperCut will provide You with a License Key to enable You to use the
Software.
•
Production License
3.9 Where you acquire a Production License by agreeing the Contract Details with PaperCut, including by completing the Contract Details on the sign on process, then You acquire a license for the Software in accordance with clause 4.2 and the right to receive and install any Updates for that Software that may be issued by PaperCut from time to time. You must install Updates promptly, especially Updates that have been made available for security issues. There are no additional Fees for this right to receive Updates.
•
Premium Upgrade Assurance
3.10 Where You ordered Premium Upgrade Assurance services in the Contract Details, upon acceptance of your order PaperCut will provide the Premium Upgrade Assurance services for 12 months from the Effective
Date in accordance with clause 5.
•
Additional Licenses, Usage or Premium Upgrade Assurance.
3.11 If You wish to add more Software programs, add more Users or other license usage or extended Your
Premium Upgrade Assurance service and such items are available from PaperCut at the time, You may order those items by completing and agreeing the relevant Contract Details with PaperCut via the Website and agreeing to pay PaperCut's then current Fees and Taxes for such items. Any such items will be provided on the terms and conditions of this Agreement.
• 3.12 If You do not extend Your Premium Upgrade Assurance service so that Premium Upgrade Assurance service is provide continuously, and subsequently wish to re-instate Premium Upgrade Assurance service, then You must pay PaperCut's then current support re-instatement fee in addition to the then current Fees for the Premium Upgrade Assurance service prior to the Premium Upgrade Assurance service being re-instated.
•
Variations
3.13 Subject to clauses 3.8 and 3.11, this Agreement, or any part of it, may be varied by the parties agreeing to the Variation in writing (and the Variation will be binding when both parties have signed the Variation).
•
4 - LICENSES
•
Evaluation License
4.1 From the Effective Date until the license is terminated in accordance with this Agreement, PaperCut grants You a non-exclusive, non-transferable, limited use license solely to install and run the Software on one or more computers that are Authorised Platforms for You and your Affiliates to evaluate the Software to determine whether to acquire a Production License. Under this Evaluation License You and Your Affiliates may use the Software for testing and evaluation in a production environment prior to the termination of the
Evaluation License.
607
END USER LICENSE AGREEMENT (EULA)
•
Production License
4.2 Subject to PaperCut's receipt of the applicable Fees and related Taxes in accordance with the Contract
Details, PaperCut grants You a non-exclusive, non-transferable, indivisible, limited use license solely to install and run the Software on one or more computers that are the Authorised Platforms, for use by You or Your
Affiliates from the Effective Date until the license is terminated in accordance with this Agreement, for:
• (a) up to the maximum number of Users or other license metric set out in the Contract Details, for Your internal business data processing/printing requirements in accordance with, and subject to any other limitation of use set out in, the Contract Details; and
• (b) for testing, disaster recovery and back up (hot or cold), without additional Fees.
•
Delivery and installation
4.3 PaperCut will make the Software available for download from the Website. If You specifically request,
PaperCut will ship to You a physical copy of media with the software loaded on it, at additional cost. You are responsible for copying and installing the Software on the Authorised Platforms. You must follow any instructions provided by PaperCut when installing the Software. All Software is deemed to be accepted by
You upon successful installation on the first Authorised Platform.
•
Prohibited Actions
4.4 Nothing in this Agreement permits You to:
• (a) use the Software to provide any facility management or service bureau service, or for the benefit of any third party (other than an Affiliate);
• (b) disclose the Software or any online or hard copy documentation related to the Software to any third party (other than an Affiliate);
• (c) adapt, translate, publish, communicate to the public, or create any derivative work or translation of the
Software, unless expressly permitted by law;
• (d) sub-license, lease, rent, loan, assign, novate or otherwise transfer the Software to any third party;
• (e) reverse engineer, reverse compile, de-compile or disassemble the object code of the Software or any part of the Software (or other underlying data), or otherwise attempt to derive the source code of the
Software, except to the extent the permitted by law;
• (f) use any part of the Software other than as an integrated part of the overall Software program;
• (g) remove, alter or obscure any PaperCut Marks, or any proprietary or restricted use notice on the
Software;
• (h) allow the Software to become the subject of any charge, lien, encumbrance or security interest; or
• (i) deal in any other manner with any or all of Your rights and obligations under this Agreement.
•
Compliance
4.5 You acknowledge and agree that the License Key may prevent, hinder or reduce availability of features where You are using the Software in excess of the usage rights that You have agreed to pay for.
• 4.6 During the period of this Agreement and for 2 years thereafter, You must permit PaperCut, or its nominee, to inspect and have access to the Software, the usage logs in the Software and to any records kept in connection with this Agreement, for the purposes of ensuring that You (and Your Affiliates) are complying with the terms of this Agreement. If PaperCut requires access to Your offices (or those of Your Affiliates) in order to access the Software or the relevant records then:
• (a) PaperCut must provide reasonable advance notice to You;
• (b) any access must be during business hours or other times agreed by You;
• (c) PaperCut must use reasonable endeavors to minimize any disruption to Your business; and
• (d) if PaperCut uses a nominee to conduct the inspection, such nominee must not be a competitor to You and must sign a non-disclosure agreement with PaperCut that protects any information found during the inspection on terms that are no less protective than those terms that are included in clause 9 of this
Agreement.
•
5 - PREMIUM UPGRADE ASSURANCE
608
END USER LICENSE AGREEMENT (EULA)
• 5.1 This clause 5 applies during the period when You have acquired Premium Upgrade Assurance services for a Production License.
• 5.2 If and when PaperCut makes an Update or Upgrade generally available to customers with Premium
Upgrade Assurance services for the Software, the Update or Upgrade will be made available to You at no additional charge. You must, at your own cost, download and install the Update or Upgrade within a reasonable period.
• 5.3 If You (or any of Your employees or employees of any of Your Affiliates) believe that there is a defect in the Software those employees should report it to Your internal support desk personnel, and Your internal support desk personnel should report it to PaperCut's support email address 24/7 or call PaperCut's support helpline during business hours. You must ensure that Your internal support desk personnel are technical competent and trained in the use of Software. They must use reasonable efforts to resolve the issue prior to contacting PaperCut for assistance.
• 5.4 PaperCut will use its best efforts to provide a remedy or a workaround for any defect in the Software that is reported to its support helpline in a timeframe that is reasonable given the nature of the issue and the impact on Your business operations.
• 5.5 PaperCut shall have no obligation to provide Premium Upgrade Assurance services:
• (a) in respect of any Software which has not had any Update or Upgrade installed prior to the date that
PaperCut has notified its customers generally that is the "end of life" date for that version. PaperCut shall provide its customers with at least 90 days notice, including by posting notice on the Website, of an "end of life" date for that particular version;
• (b) to any adaptations, translations or derivative works made to the Software; or
• (c) for any Evaluation License.
• 5.6 PaperCut shall have no obligation to provide Premium Upgrade Assurance services where faults arise from:
• (a) misuse, incorrect use of or damage to the Software from whatever cause (other than any act or omission by PaperCut), including failure or fluctuation of electrical power;
• (b) failure to maintain the necessary environmental conditions for use of the Software;
• (c) use of the Software in combination with any equipment or software other than Authorised Platforms;
• (d) any breach of Your obligations under this Agreement;
• (e) having the Software maintained by a third party; or
• (f) user error.
• 5.7 If it is necessary for PaperCut to attend Your (or Your Affiliates') premises to provide Premium Upgrade
Assurance services, or PaperCut determines that the work it performed in relation to a logged issue was caused by any of the items in clause 5.6, then You must pay for such work at PaperCut's then current Fees and charges as well as any expenses (and travel time) incurred by PaperCut in performing such work.
•
6 - FEES AND TAXES
• 6.1 PaperCut will provide You with the ability to download the Software from our Website as an Evaluation
License for use in accordance with this Agreement without charge.
• 6.2 Where You agree on the Contract Details to pay the Fees, charges and Taxes for any Production
License, Premium Upgrade Assurance, additional Software, additional Users or extended usage rights, further period of Premium Upgrade Assurance or other thing acquired under this Agreement by credit card (or other online payment mechanism supported by PaperCut) then you must complete the relevant details and authorizations stated on the Website. PaperCut will provide you with a tax invoice/receipt promptly following receipt of Your payment.
• 6.3 Where You agree on the Contract Details to pay the Fees, charges and Taxes for any Production
License, Premium Upgrade Assurance, additional Software, additional Users or extended usage rights, further period of Premium Upgrade Assurance or other thing acquired under this Agreement following receipt of a tax invoice, PaperCut will provide You with a tax invoice for the Fees and Taxes at the start of the license or the supply of the service and You must pay this tax invoice within 14 days of receipt.
• 6.4 You are solely responsible for ensuring that PaperCut receives the net amount of the Fees for any
609
END USER LICENSE AGREEMENT (EULA) transaction under this Agreement, including:
• (a) You must pay any fee for receiving the Software on physical media;
• (b) You must pay any fee associated with the use of a credit card (or other payment mechanism accepted by PaperCut);
• (c) You must pay any fee associated with a bank charge or transfer fee;
• (d) You must pay any fee incurred by PaperCut for any charge back or other payment failure, plus
PaperCut's administration fee for dealing with a failed payment (other than where a refund of the Fees is required to be provided by law);
• (e) You are responsible to pay all Taxes. All payments under the Agreement must be made free and clear and without deduction for any and all present and future Taxes. Payments due to PaperCut under the
Agreement must be increased so that the amounts received by PaperCut, after provision for Taxes and all
Taxes on such increase, will be equal to the amounts required under the Agreement as if no Taxes were due on such payments.
• 6.5 You irrevocably authorize PaperCut to deduct from your credit card (or any debit card accepted by
PaperCut) any amount due and payable under this Agreement without further reference to You.
• 6.6 You must pay a late charge for any failure to make any payment by the date required under the
Agreement, calculated daily using a rate that is 4% over the Reserve Bank of Australia's Cash Rate, from the date that the payment first becomes overdue, to the date that the payment is received by PaperCut, both dates inclusive.
• 6.7 If any Fee, charge or Tax is not received by the required date, PaperCut may suspend Your access to the
Software or suspend or cease providing services to You until the outstanding amounts (including applicable late charges, damages, costs and expenses) are paid. You do not have any claim for breach of contract or otherwise for any action taken by PaperCut under this clause.
•
7 - TRADEMARKS
• 7.1 You acknowledge and agree that PaperCut is the owner and/or licensee of the PaperCut Marks. You do not acquire any right to use, or interest in, any of the PaperCut Marks. You must not at any time or in any way assert any ownership of, or any right in, the PaperCut Marks and You must not contest the right of PaperCut or any PaperCut Affiliate or any of their licensors to the use of any of the PaperCut Marks.
• 7.2 PaperCut will not use Your (or those of Your Affiliates) trademarks, logos or branding without your prior written consent. You give us consent to incorporate any trademark, logo or branding that You provide us into the Software in order to take advantage of the Software features that allow the use of customers' branding.
PaperCut may disclose the fact that You (and Your Affiliates) are customers and the nature of Your (and Your
Affiliates') use of the Software to third parties in private conversations and documentation, but PaperCut will not use Your name (or the names of Your Affiliates) in PaperCut's general marketing materials or websites etc without Your prior written consent.
•
8 - PROPRIETARY RIGHTS
• 8.1 All Intellectual Property Rights that are created by any person that are adaptations, translations and derivative works in the Software or related documentation, are and shall remain the exclusive property of
PaperCut (and its licensors, if any) or shall vest in or be transferred to PaperCut immediately upon creation, as the case may be.
• 8.2 Except for the rights expressly granted by PaperCut to You under this Agreement:
• (a) PaperCut and its licensors, if any, reserve all right, title and interest in and to the Software or related documentation and all Intellectual Property Rights in them;
• (b) no right, title or ownership interest in or to the Software or related documentation whether by implication, estoppel or otherwise, is granted, assigned or transferred to You under or in connection with this Agreement.
• 8.3 You must not make any unauthorized copies of the whole or part of the Software or related documentation. You acknowledge and agree that the unauthorized disclosure, use or copying of the Software or related documentation may cause PaperCut serious financial loss that may not be adequately compensated by monetary damages. Accordingly, in the event of any unauthorized disclosure, use or copying of the Software or related documentation, You agree that PaperCut shall have the right to seek injunctive relief to stop such unauthorized disclosure, use or copying.
610
END USER LICENSE AGREEMENT (EULA)
•
9 - CONFIDENTIAL INFORMATION
• 9.1 The Recipient must not use any of the Discloser's Confidential Information except in connection with the performance of its obligations specified in this Agreement.
• 9.2 The Recipient must not disclose the Discloser's Confidential Information to any third party without obtaining the Discloser's prior written consent, provided that the Recipient may disclose the Discloser's
Confidential Information to:
• (a) its employees, agents and contractors, and those of any of its Affiliates, who have entered into a written agreement with the Recipient that is no less protective of the Discloser's Confidential Information than this Agreement provided those persons have a need to know such information for the purposes of this Agreement;
• (b) to its lawyers, bankers, auditors, accountants and insurers, who have a need to know the information in order to provide professional advice to the Discloser relating to this Agreement.
• 9.3 You must ensure that each person who is issued with a License Key does not disclose their License Key to any other person.
• 9.4 The Recipient must use, and must ensure that any person to whom it is permitted by this Agreement to disclose the Discloser's Confidential Information to uses, the same measures to protect the Discloser's
Confidential Information as it uses to protect its own confidential information, but in no event less than reasonable measures.
• 9.5 The restrictions in this clause 9 shall not apply to information that:
• (a) is independently developed by the Recipient without any access to the Confidential Information of the
Discloser;
• (b) becomes known to the Recipient without restriction, from a third party who, to the Recipient's knowledge, was not bound by a confidentiality agreement with the Discloser, or otherwise prohibited from disclosing the information to the Recipient, or had the right to disclose it;
• (c) was available to the Recipient on a non-confidential basis prior to disclosure by the Discloser;
• (d) was lawfully in the possession of the Recipient before the information was disclosed to it by the
Discloser, and that was not subject to a confidentiality obligation;
• (e) is or becomes in the public domain through no act or omission of the Recipient;
• (f) the parties agree in writing is not confidential or may be disclosed; or
• (g) is required to be disclosed under an order or requirement of a court, administrative agency, or other governmental body (but only to the minimum extent required to comply), provided however, that Recipient shall provide prompt notice to Discloser of any potential disclosure and shall use its reasonable efforts to prevent disclosure of such information.
•
Privacy
9.6 The parties must:
• (a) comply with the requirements of the any privacy law in the country in which the party is located and in any country to which the personal information is to be sent; and
• (b) only use, manipulate, store and handle personal information for the purposes of meeting its obligations under this Agreement.
• 9.7 You warrant that:
(a) You have obtained the informed consent from each individual about whom PaperCut will obtain personal information from You as a result of this Agreement; and (b) PaperCut, its Representatives and their permitted successors, assignees and sublicensees may use that individual's personal information in any manner that may be reasonably contemplated by this Agreement, including a transfer overseas for the purpose of providing support and error correction services.
•
10 - LIMITATION OF LIABILITY
• 10.1 Except as set out in this Agreement, to the extent permitted by law, and subject to clause 10.2,
PaperCut's total, cumulative liability to You (and Your Affiliates) for any claim whether it be for breach of contract (including under an indemnity), in tort (including negligence), breach of statutory duty or otherwise,
611
END USER LICENSE AGREEMENT (EULA) arising out of or in connection with the Software, the Premium Upgrade Assurance service, this Agreement or the relationship between the parties, shall be limited to:
• (a) where the claim arises in connection with the Software, the total of all Fees paid by You for the
Production License; or
• (b) where the claim arises in connection with the Premium Upgrade Assurance, the total of all Fees paid by You for the Premium Upgrade Assurance during the Premium Upgrade Assurance year in which the claim first arose; or
• (c) for any other claim, USD$10,00
• 10.2 To the extent permitted by law, PaperCut will not be liable for any loss, damage or expense which is indirect, consequential, special or exemplary damages, nor for any lost profits, lost revenue, lost data or business interruption, even if PaperCut has been advised of, knows of, or should have known of the possibility of such loss, damage or expense.
• 10.3 You acknowledge and agree that owing to the nature of the Software, PaperCut does not represent or warrant that:
• (a) access to the Software will be continuously available; or
• (b) the Software will be error free.
• 10.4 You act as agent for Your Affiliates in respect of this Agreement and are responsible to PaperCut for their acts and omissions.
•
11 - INDEMNIFICATION
• 11.1 In addition to any rights You may have at law, PaperCut undertakes at its own expense to indemnify and defend You or, at PaperCut's option, settle any claim or action brought against You alleging that the use or possession of the Software in accordance with this Agreement infringes any Intellectual Property Right enforceable in the United States, Canada, any country in the EU, Switzerland, Australia, New Zealand, Hong
Kong, Singapore and Japan (an "Infringement Claim") and shall be responsible for any losses, damages, expenses or costs (including reasonable legal fees) incurred by, or awarded against You as the result of, or in connection with, any such Infringement Claim, provided that:
• (a) You promptly notify PaperCut of the Infringement Claim in writing, specifying the nature of the claim in reasonable detail and providing access to, and copies of, documents, software any other material, that are relevant to the Infringement Claim, as well as providing prompt access to any Representative who may be relevant to PaperCut's defense of Infringement Claim;
• (b) You do not make any admission of liability, agreement or compromise in relation to the Infringement
Claim without the prior written consent of PaperCut;
• (c) You grant PaperCut the sole right to defend, negotiate and settle the Infringement Claim, at PaperCut's expense, or at PaperCut's option, PaperCut may permit You to defend the Infringement Claim in which case:
• (i) PaperCut will pay any costs associated with Your defense, and will provide security for such costs; and
• (ii) You must follow any reasonable request from PaperCut to avoid, dispute, defend and/or compromise the Infringement Claim;
• (d) You provide PaperCut with reasonable assistance, at PaperCut's expense, to defend, negotiate and settle the Infringement Claim.
• 11.2 PaperCut will have no obligation under this clause 11 or otherwise with respect to any Infringement
Claim based upon:
• (a) any use of the Software not in accordance with this Agreement, or documentation provided by
PaperCut;
• (b) the combination, operation or use of the Software with any other product, equipment, business method, software or data;
• (c) any modification of the Software by any person other than PaperCut or its authorized agents or subcontractors; or
• (d) any use of the Software after PaperCut has provided You a new software version, patch or correction that would have overcome the infringement.
612
END USER LICENSE AGREEMENT (EULA)
• 11.3 If any Infringement Claim is made, or in PaperCut's opinion is likely to be made, then PaperCut may (at its sole option and expense) either:
• (a) procure for You the right to continue using the affected Software, or substantially similar software that does not substantially affect the functionality of the Software, in accordance with this Agreement;
• (b) replace or modify the affected Software so that it becomes non-infringing but performs substantially the same functions; or
• (c) if neither (a) or (b) is commercially reasonable, as determined in PaperCut's sole discretion, then
PaperCut may terminate Your rights to use the affected Software and pay damages of up to an amount of the Fees paid for the license for the Software.
• 11.4 Subject to any rights that You may have under statute, this clause 11 states PaperCut's entire liability and Your sole and exclusive remedy for any claims related to any infringement of the Intellectual Property
Rights in respect of the Software.
•
12 - TERMINATION
• 12.1 PaperCut may immediately terminate this Agreement for cause by giving You written notice if You:
• (a) breach any of the provisions of clauses 4, 6, 7.2, 8.3, 9 or 13.5;
• (b) breach any other provision of the Agreement and You do not remedy it within 14 days of PaperCut providing You written notice of the breach;
• (c) cease to carry on business, are unable to pay Your debts as they fall due, You enter into liquidation or have a controller, managing controller, liquidator or administrator appointed or suffer any similar event in any jurisdiction; or
• (d) merge with, sell substantially all of Your assets, or You are subject to a change of control. A "change of control" shall be deemed to occur when an entity acquires fifty percent (50%) or more of Your voting shares or equity interest or fifty percent (50%) or more of Your assets, in the event of a change of a majority of Your Board of Directors (or majority of the partners if a partnership) or if there is any other effective change of control.
• 12.2 You may immediately terminate this Agreement for cause by giving PaperCut written notice if PaperCut:
• (a) breaches any of the provisions of this Agreement and PaperCut does not remedy it within 30 days of
You providing PaperCut written notice of the breach; or
• (b) ceases to carry on business, is unable to pay its debts as they fall due, enters into liquidation or has a controller, managing controller, liquidator or administrator appointed or suffer any similar event in any jurisdiction.
• 12.3 If this Agreement terminates:
• (a) any license for Software and its related Premium Upgrade Assurance terminates immediately;
• (b) each party shall immediately return to the other (or at the other party's request destroy) any of the other's Confidential Information;
• (c) You must ensure that all copies of the Software installed pursuant to this Agreement are uninstalled and deleted from all hardware in your possession or control within 14 days of the date this Agreement is terminated.
• 12.4 Any termination of this Agreement shall not prejudice, limit or restrict any other rights or remedies either party may have arising prior to such termination. To the extent permitted by law, PaperCut shall be under no obligation to refund any amounts paid by You for any of the Software or Premium Upgrade Assurance services that have been provided prior to any termination of this Agreement.
•
13 - GENERAL
•
Notices
• 13.1 Any notice that is given under this Agreement:
• (a) by PaperCut may be:
• (i) posted to You;
613
END USER LICENSE AGREEMENT (EULA)
• (ii) emailed to You at any email address provided by You;
• (iii) included on any invoice (which may be emailed or posted to You); or
• (iv) posted on the Website. You must review the Website regularly for notices.
• (b) by You must be posted to PaperCut at the address stated on the latest invoice.
• 13.2 A notice is deemed to be received:
• (a) when posted from Australia to an address in Australia; within 3 business days of the date when it was posted;
• (b) when posted from an address outside of Australia, within 7 days of the date when it was posted; or
• (c) when emailed; within 1 business day of the date that the email was sent, provided no notice of failure has been received by the sender;
• (d) when posted on the Website, within 3 business days of the date it was posted.
•
Relationship of Parties
• 13.3 The parties to this Agreement are independent contractors. Nothing in this Agreement shall be deemed to create an agency, employment, partnership, fiduciary or joint venture relationship between the parties, constitute any party the agent of another party, nor authorize any party to make or enter into any commitments for or on behalf of any other party. Compliance with Laws
• 13.4 You must comply with all laws which are relevant to You performing Your obligations under this
Agreement.
•
Assignment
• 13.5 You must not assign or transfer this Agreement or any rights or obligations under this Agreement, in whole or part, without the prior written consent of PaperCut.
• 13.6 PaperCut may assign or transfer this Agreement, in whole or part, without Your consent to any PaperCut
Affiliate or in connection with a merger, acquisition, or purchase of fifty percent (50%) or more of its assets.
This Agreement will bind and inure to the benefit of each party's permitted successors and assigns. PaperCut may assign or transfer all or part of any of its rights to receive any Fees and Taxes or other monies due under this Agreement, to any person without Your consent. Notwithstanding clause 9, PaperCut may disclose any of Your Confidential Information which is reasonably necessary to affect any assignment or transfer.
•
Waiver
• 13.7 No failure or delay by a party to exercise any right or remedy provided under this Agreement or by law shall constitute a waiver of that or any other right or remedy, nor shall it preclude or restrict the further exercise of that or any other right or remedy. No single or partial exercise of such right or remedy shall preclude or restrict the further exercise of that or any other right or remedy.
•
Remedies
• 13.8 Except as specifically provided otherwise in this Agreement, the rights and remedies provided under this
Agreement are cumulative and in addition to, and not exclusive of, any rights or remedies provided by law.
•
Severability
• 13.9 If any part of this Agreement is determined to be invalid, illegal or unenforceable by any court or competent authority, such part will be severed from the remainder of the Agreement and the remaining provisions will continue in force.
•
Force Majeure
• 13.10 Except for Your obligations to pay PaperCut under this Agreement, neither party shall be in breach of this Agreement nor liable to the other party for any failure or delay in performance caused by events beyond the party's reasonable control.
•
Agreement
• 13.11 All clauses which naturally survive termination of the Agreement, including clauses 4.6, 7.1, 8, 9, 10,
12.3(b), 12.4 and 13, will survive termination of this Agreement.
• 13.12 The parties are entitled to rely on any notice or communication in electronic format, including any facsimile or email, that on its face appears authentic, and that has the purported author's name on it to the same extent as if it were a document written by the author. The parties consent to this Agreement being
614
END USER LICENSE AGREEMENT (EULA) signed or varied through electronic communication.
• 13.13 To the extent permitted by law:
• (a) PaperCut excludes any warranty or guarantee not expressly stated in this Agreement, whether express, implied or statutory, including any guarantees or warranties of acceptability and fitness for a particular purpose;
• (b) this Agreement constitutes the entire agreement between the parties regarding the subject matter and supersedes all prior or contemporaneous agreements, arrangements, understandings and communications, whether written or oral.
•
Export
• 13.14 You acknowledge and agree that the Software may be subject to applicable export and import laws.
You agree not to export the Software or any direct product thereof, directly or indirectly in violation of these laws, nor will they be used for any purpose prohibited by these laws, including nuclear, chemical or biological weapons proliferation.
•
Governing Law
• 13.15 If You are resident, domiciled or incorporated in the USA, this Agreement will be governed by the laws of the State of Oregon, USA, without regard to its conflict of law principles. The parties submit to the exclusive jurisdiction of the courts in the State of Oregon. You hereby agree any claims will be brought exclusively in the federal or state courts located in Oregon and the parties hereby irrevocably consent to the personal jurisdiction and venue of the courts located in Oregon for the purpose of litigating any and all such claims.
• 13.16 In all other cases, this Agreement will be governed by the laws of the State of Victoria, Australia, without regard to its conflict of law principles. The parties submit to the exclusive jurisdiction of the courts in the State of Victoria, Australia.
•
14 - COUNTRY-SPECIFIC PROVISIONS
• The following provisions apply to the extent required under local laws.
•
Australia:
Australian Consumer Law
• 14.1 Our goods come with guarantees that cannot be excluded under the Australian Consumer Law (ACL).
You are entitled to a replacement or refund for a major failure and for compensation for any other reasonably foreseeable loss or damage. You are also entitled to have the goods repaired or replaced if the goods fail to be of acceptable quality and the failure does not amount to a major failure.
• 14.2 The Premium Upgrade Assurance services that are provided to remedy any defect in the Software may be a "Warranty Against Defects" as defined in the ACL.
The Premium Upgrade Assurance services are provided by PaperCut Software International Pty Limited
(ACN 124 440 400) of Ground Floor, 1 Oxley Rd, Hawthorn, 3122, tel +61 3 9809 5194, email address
.
In order to make use of the Premium Upgrade Assurance services, You must contact PaperCut's support helpline during the period of your agreement for Premium Upgrade Assurance service using process in clause 5.3. When you make use of the Premium Upgrade Assurance services, PaperCut will use its best efforts to provide a remedy or a workaround for any defect in the Software in a timeframe that is reasonable given the nature of the issue and the impact on your business operations. This service is not available for
Evaluation Licenses. The costs for the service in respect of the Production Licenses are included within the
Fees that are set out in the Contract Details. No additional fees are payable by you for the Premium Upgrade
Assurance for Production Licenses. You are responsible for any expenses you incur in using the Premium
Upgrade Assurance. The benefits that we provide to consumers under our Warranty Against Defects are in addition to any other rights or remedies a consumer may have in respect of these goods or services under the ACL. The provision of Premium Upgrade Assurance services may result in the loss of user generated data.
• 14.3 To the extent permitted by law, PaperCut's liability for a failure to comply with any statutory guarantee is limited to one or more of the following, at PaperCut's option:
• (a) the replacement of the goods or the supply of equivalent goods;
615
END USER LICENSE AGREEMENT (EULA)
• (b) the repair of the goods;
• (c) the payment of the cost of replacing the goods or of acquiring equivalent goods;
• (d) the payment of the cost of having the goods repaired,
• unless it is not fair or reasonable for PaperCut to rely on this term of the Agreement.
• 14.4 If You are entitled to the benefit of a guarantee under the ACL then in respect of goods and/or services which are not of a kind that are ordinarily acquired for personal, domestic or household use or consumption,
PaperCut's liability for a failure to comply with such guarantee is limited to one of the following, at PaperCut's option:
• (a) supplying the goods and/or services again; or
• (b) payment of the cost of having the goods and/or services supplied again,
• unless it is not fair or reasonable for PaperCut to rely on this term of the Agreement.
•
USA:
USA Government Rights
14.5 If You are a US civilian agency, the US government acquires certain parts of this commercial computer software and/or commercial software documentation or other technical data subject to the terms of this
Agreement as specified in the 48 C.F.R. 12.212 (Computer Software) and 12.211 (Technical Data) of the
Federal Acquisition Regulation (FAR) and its successors. If acquired by or on behalf of any agency within the
Department of Defence (DOD), the US Government aquires certain parts of this commercial computer software and/or commercial software documentation subject to the terms of this Agreement as specified in 48
C.F.R. 227.7202-3 of DOD FAR Supplement (DFARS) and its successors. The US Government Rights clause is in lieu of, and supersedes any other FAR, DFARS or other clause or provision that addresses US
Government rights in computer software or technical data.
Copyright (c) 1999-2015 PaperCut Software International Pty. Ltd.
616
Download
Public link updated
The public link to your chat has been updated. You may view and manage your chat links after registration here.
Document public link
Advertisement
Key features
Track, control, audit, and report print usage
Manage user and group quotas
Implement differential charging for color and duplex printing
Web-based administration and user interfaces
Support for shared accounts and client billing
Mobile printing and BYOD capabilities
Advanced scripting for custom print logic
Multi-server and multi-site deployment options
Hold/Release queues and secure print release stations
User card and ID number integration
Frequently asked questions
PaperCut NG is a print management software solution designed to manage, control, track, audit, and report on print usage across various operating systems and network environments.
The key benefits include reducing print waste, recovering costs, simplifying print management, securely controlling print queues, and enabling mobile and BYOD printing.
PaperCut NG supports installation on Windows, Apple Mac, and Novell OES Linux, and Linux (CUPS and/or Samba) print servers.
The client software can be deployed using zero-install methods, login scripts, group policy, or third-party deployment tools, as described in the manual's installation section.
