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.