Appendix A. Tools (Advanced)

Table of Contents

Server Commands (server-command)
Available Commands
Database Tool (db-tools)
export-db Command
import-db Command
init-db Command
The XML Web Services API
Web Services Example Code
Security
SSL/HTTPS Key Generation
Using a custom SSL Key
User Client Options
Stopping and Starting the Application Server
Stopping/Starting the server on Windows

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.

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-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.

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.

    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.

                

Tip

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”.