Table of Contents
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.
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.
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-dir]\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 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. shared-account-exists <account_name> Test to see if a shared account exists. <account_name> - the shared account name to test. get-user-account-balance <username> Get a user's current account balance. <username> - the user's username. get-shared-account-account-balance <account_name> Get shared account's current account balance. <account_name> - the shared acount's full name. adjust-user-account-balance <username> <adjustment> <comment> 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. adjust-user-account-balance-by-group <group> <adjustment> <comment> Adjust the account balance for all users in a group. <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. 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-user-account-balance <username> <balance> <comment> 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. 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. set-user-restriction <username> <restricted> Set a user's restriction status. <username> - the user's username. <restricted> - TRUE if restricted. FALSE for unrestricted set-shared-account-restriction <account_name> <restricted> Set a shared account's restriction status. <account_name> - the shared account's full name. <restricted> - TRUE if restricted. FALSE for unrestricted get-user-print-stats-page-count <username> Get a user's current page count value. <username> - the user's username. get-user-print-stats-job-count <username> Get a user's current print job count value. <username> - the user's username. 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. 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. 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. enable-printing-for-user <username> Enable printing for a user. <username> - the name of the user to enable printing for. 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. enable-printer <server_name> <printer_name> Enable a disabled printer. <server_name> - the name of the server hosting the printer. <printer_name> - the printer's name. 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. This process happens in the background. perform-user-and-group-sync Start a full user and group synchronization. This is equivalent to pressing on the "Synchronize Now" button in the admin user interface. The of the sync process, such as deleting old users, is determined by the current system settings as defined in the admin interface. This process happens in 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 This process will happen in the background. <delete_old_users> - set to TRUE remove old users, else FALSE. <update_details> - set to TRUE if exist 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. 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. add-new-shared-account <shared_account_name> <pin> <balance> <restricted> <notes> Add a new shared account with the given initial settings. <shared_account_name> - the name of the shared account. <pin> - the pin required to access the shared account (blank for none). <balance> - the shared account's initial balance. +ve or -ve. <restricted> - whether or not users should be able to print to the shared account when its balance reaches 0. (true or false). <notes> - a description of this shared account. 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. set-shared-account-access-users <shared_account_name> <usernames> Allow the given users access to the given shared account without using a pin. <shared_account_name> - the name of the shared account to allow access to. <usernames> - the comma separated names of the users to give access to. E.g. "user1,user2,user3" set-shared-account-access-groups <shared_account_name> <group_names> Allow the given groups access to the given shared account without using a pin. <shared_account_name> - the name of the shared account to allow access to. <group_names> - the comma separated names of the groups to give access to. E.g. "group1,group2,group3" 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. 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. delete-existing-user <username> Delete a user account from the system. Use this method with care. Calling this will perminently delete the user account from the user list (print history records remain). <username> - the user's system username. 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. batch-import-shared-accounts <import_file> <add_new_accounts> <delete_non_existent_accounts> Import the shared accounts contained in the given tab-delimited import file. <import_file> - the import file location relative to the application server. <add_new_accounts> - (true or false) If true, accounts that exist in the import file but not in the system will be created. If false, they will be ignored. <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.
server-command
is ideal for scripting via batch files or shell
scripts. Administrators wishing to control PaperCut NG using a programming
language such as C#, Java, Visual Basic, Perl or Python should consider the XML
Web Services API's. 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 the section called “The XML Web Services API”.
© Copyright 1999-2006. PaperCut Software Pty Ltd. All rights reserved.