Table of Contents
- C.1. Server Commands
- C.1.1. Common Options
- C.1.2. addInternalUser
- C.1.3. addUserGroup
- C.1.4. changeBaseCurrency
- C.1.5. deleteUser
- C.1.6. deleteUserGroup
- C.1.7. deleteUserGroupAccount
- C.1.8. eraseUser
- C.1.9. getConfigProperty
- C.1.10. listUsers
- C.1.11. listUserGroups
- C.1.12. listUserGroupMembers
- C.1.13. listUserGroupMemberships
- C.1.14. listUserSourceGroups
- C.1.15. listUserSourceGroupMembers
- C.1.16. listUserSourceGroupNesting
- C.1.17. printerAccessControl
- C.1.18. printerSnmp
- C.1.19. setConfigProperty
- C.1.20. setUserProperties
- C.1.21. setUserGroupProperties
- C.1.22. syncUserGroup
- C.1.23. syncUsersAndGroups
- C.1.24. systemStatus
- C.2. Web Services
- C.3. Atom Feed Service
- C.4. Database Commands
- C.5. Stopping and Starting the Server
- C.6. SSL Key Generation
The savapage-cmd tool provides a command-line interface to SavaPage Server methods. It can directly be executed on the command-line or be part of more elaborate shell scripts.
For security reasons only users with read access to the
/opt/savapage/server/server.properties file have the
right to execute the command. So, the sure way to go is ...
sudo su - savapage cd server/bin/linux-x64
... and to execute
savapage-cmd from here, and ...
./savapage-cmd --help
... will echo all methods available:
________________________________
SavaPage Command Line Interface
Note: use METHOD --help for method details.
usage: [METHOD] [OPTION]...
--add-internal-user Creates a new or Updates an existing Internal
User.
--add-user-group Adds a user group from the external user
source: synchronized external users belonging
to this group are added as member.
--change-base-currency Changes the base currency of the application.
--delete-user Logically deletes a User.
--delete-user-group Deletes a user group.
--delete-user-group-account Logically deletes a User Group Account.
--erase-user Erases a User, complying to GDPR Data Erasure
(Right to be Forgotten).
--get-config-property Gets configuration property value.
--list-users Lists the names of all the Users in the
system, sorted by user name, one per line.
--list-user-groups Lists the names of all the User Groups in the
system, sorted by name, one per line.
--list-user-group-members Lists the names of the user group members in
the system, sorted by user name, one per line.
--list-user-group-memberships Lists the names of the groups a user belongs
to, sorted by name, one per line.
--list-user-source-groups Lists the names of all the groups in the user
source, sorted by name, one per line.
--list-user-source-group-members Lists the names of the (nested) user group
members in the user source, sorted by user
name, one per line.
--list-user-source-group-nesting Lists a space indented hierarchy of nested
groups within a group. Nested groups are only
supported by Active Directory, all other user
sources return an empty list.
--printer-access-control Controls user groups to either allow or deny
access to a proxy printer.
--printer-snmp Reads SNMP info from a printer.
--set-config-property Sets configuration property value.
--set-user-properties Sets properties for an existing Internal or
External User.
--set-user-group-properties Sets properties of an Internal or External
User Group.
--sync-user-group Synchronizes a user group with the external
user source, updating group membership.
--sync-users-and-groups Starts user and group synchronization with
external user source.
--system-status Gets the system status enum value: READY,
SETUP, UNAVAILABLE, MAINTENANCE.
-help,--help Displays this help text.
--help-all Displays help text of all methods.
Note
The number of available methods will grow according to customer needs. Please contact support if you need a method that is missing.
--keep-* option switches are used to not
overwrite existing values.
For example, the --keep-card, --keep-pin and
--keep-password switches make their corresponding
--card, --pin and --password
options act as defaults in those cases where values have not yet been set.
Some examples:
# Overwrite any PIN set by user. --add-internal-user --username "guest-john" --pin "1234" # Preserve any PIN set by user. --add-internal-user --username "guest-john" --pin "1234" --keep-pin
--remove-* option switches are used to
clear values. Since the
absence of a command-line option (or an empty value
in batch mode CSV/TSV
files) can not be interpreted as no
value (null), the --remove switch
comes to help to explicitly nullify values.
This implies that blank values on the command-line and in batch mode input files are ignored. So, this command has no effect ...
--add-internal-user --username "guest-john" --pin ""
... use this command instead ...
--set-user-properties --username "guest-john" --remove-pin
When an option does not have a
--remove-* switch, there is no way to clear the
corresponding field. For example, since --remove-full-name is
not available, there is no way to clear the User field
“full-name” from the command-line (see Section C.1.20, “setUserProperties”).
Some methods pass numeric values that are formatted according to the locale. In these cases the locale can be specified with a separate option like this:
-locale <arg> The IETF BCP 47 Locale used for numeric values.
Example values are: en, en-GB, en-US, nl,
nl-NL, nl-BE. [defaults to system default
en-US].Note
The actual system default locale depends on your
terminal session settings.
Some methods have options for passing values in batch mode. Below are the standard batch mode parameters:
-batch Enables batch mode: executing from CSV or TSV
input.
-continue Continues batch processing after a batch line
execution error.
-input <arg> Batch input file: optional with stdin as
default.
-charset <arg> IANA Charset Name of batch input character
encoding [default: utf-8].
So instead of using these three commands ...
./savapage-cmd --add-internal-user --username john --password rTf4g ./savapage-cmd --add-internal-user --username dave --password 9j6Tw ./savapage-cmd --add-internal-user --username mick --password f75L2
... you can use this single batch command ...
./savapage-cmd --add-internal-user -batch -input /home/rijk/add-internal-user.csv
.. where the file add-internal-user.csv looks like
this:
"username","password" "john","rTf4g" "dave","9j6Tw" "mick","f75L2"
Input files must have the extension .csv or
.tsv as indication for a comma or tab separated
file format.
The first line in the file must be the comma or tab separated list of
parameters. The convention is that the parameter names are identical to
their command line counterpart, except for the -- prefix. The
next lines simply contain the comma or tab separated parameter
values.
Option switches like applied in the command below ...
--set-user-properties --username "john" --pin 1234 --remove-card --full-name "John Brown" --set-user-properties --username "carol" --pin 4713 --keep-pin --full-name "Carol Johnson"
... can be applied in a CSV file like this:
"username,"pin","keep-pin","remove-card","full-name" "john",1234,,"true","John Brown" "carol",4713,"true",,"Carol Johnson"
Important
By default, batch processing is interrupted after a batch line
execution error. With the -continue switch set, it will
instead continue processing. After the batch finishes it will return
error code 5 to distinguish continuation from an immediate
termination, which is reported with error return code 1.
Note
In a CSV/TSV file any blank switch value is
interpreted as not present (false), any non-blank value
as present (true).
./savapage-cmd --add-internal-user --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : addInternalUser
Version : 0.30
Creates a new or updates an existing Internal User.
usage: --add-internal-user [OPTION]...
--username <text(50)> [required] Unique user name.
--password <text(64)> [optional] Password.
--full-name <text(255)> [optional] Full user name.
--email <text(255)> [optional] Primary Email address.
--email-other <list> [optional] List of space separated other
(secondary) Email addresses.
--card <text(16)> [optional] NFC Card Number.
--card-format <HEX|DEC> [optional] NFC Card Number Format [default:
HEX].
--card-first-byte <LSB|MSB> [optional] NFC Card Number First Byte [default:
LSB].
--id <text(16)> [optional] ID Number.
--pin <text(16)> [optional] PIN for ID and Card.
--yubikey <text(12)> [optional] YubiKey Public ID.
--uuid <text(36)> [optional] The user's secret UUID.
--balance <decimal> [optional] The user's initial account balance.
This value is ignored when a balance is already
assigned.
--balance-comment <text(255)> [optional] A comment to be associated with the
--balance transaction.
--credit-limit [optional] Assign default credit limit amount.
--credit-limit-amount <decimal> [optional] Assign custom credit limit amount.
--credit-limit-none [optional] no credit limit restriction (opposed
to --credit-limit and --credit-limit-amount).
--keep-card [optional] Keep existing Card Number, or use
--card value when not present.
--keep-id [optional] Keep existing ID Number, or use --id
value when not present.
--keep-email-other [optional] Keep existing other (secondary)
Email addresses, or use --email-other value
when not present.
--keep-password [optional] Keep existing Password, or use
--password value when not present.
--keep-pin [optional] Keep existing PIN, or use --pin
value when not present.
--keep-uuid [optional] Keep existing UUID, or use --uuid
value when not present.
-h,--help Displays this help text.
-batch Enables batch mode: executing from CSV or TSV
input.
-continue Continues batch processing after a batch line
execution error.
-input <arg> Batch input file: optional with stdin as
default.
-charset <arg> IANA Charset Name of batch input character
encoding [default: utf-8].
-locale <arg> The IETF BCP 47 Locale used for numeric values.
Example values are: en, en-GB, en-US, nl,
nl-NL, nl-BE. [defaults to system default
en-US].
./savapage-cmd --add-user-group --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : addUserGroup
Version : 0.10
Adds a user group from the external user source: synchronized external users
belonging to this group are added as member.
usage: --add-user-group [OPTION]...
--groupname <text(255)> [required] Unique group name.
-h,--help Displays this help text.
./savapage-cmd --change-base-currency --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : changeBaseCurrency
Version : 0.10
Changes the base currency of the application.
This action creates financial transactions to align each account to the new
currency: the current account balance is nullified by a debit transaction
and replaced with the new currency according to the exchange rate via a
credit transaction.
Individual credit limits are converted as well, default credit limits are not.
WARNING: Create a database back-up before executing this command!
usage: --change-base-currency [OPTION]...
--from <text(3)> [required] The current currency code (ISO 4217).
--to <text(3)> [required] The new currency code (ISO 4217).
--exchange-rate <decimal> [required] The exchange rate.
--test [optional] Dry run, changes are not committed.
-h,--help Displays this help text.
./savapage-cmd --delete-user --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : deleteUser
Version : 0.10
Logically deletes a User.
usage: --delete-user [OPTION]...
--username <text(50)> [required] Unique user name.
-h,--help Displays this help text.
-batch Enables batch mode: executing from CSV or TSV input.
-continue Continues batch processing after a batch line
execution error.
-input <arg> Batch input file: optional with stdin as default.
-charset <arg> IANA Charset Name of batch input character encoding
[default: utf-8].
./savapage-cmd --delete-user-group --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : deleteUserGroup
Version : 0.10
Deletes a user group.
usage: --delete-user-group [OPTION]...
--groupname <text(255)> [required] Unique group name.
-h,--help Displays this help text.
./savapage-cmd --delete-user-group-account --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : deleteUserGroupAccount
Version : 0.10
Logically deletes a User Group Account.
usage: --delete-user-group-account [OPTION]...
--groupname <text(255)> [required] Unique group name.
-h,--help Displays this help text.
This method has the same effect as ticking the checkbox in the Edit Account dialog.
./savapage-cmd --erase-user --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : eraseUser
Version : 0.10
Erases a User, complying to GDPR Data Erasure (Right to be Forgotten).
usage: --erase-user [OPTION]...
--username <text(50)> [required] Unique user name.
-h,--help Displays this help text.
-batch Enables batch mode: executing from CSV or TSV input.
-continue Continues batch processing after a batch line execution
error.
-input <arg> Batch input file: optional with stdin as default.
-charset <arg> IANA Charset Name of batch input character encoding
[default: utf-8].
This command clears the user's personal data in the active database, including all identifying content from the transaction log, document log and personal account. Transaction and document log details are still held in the database for reporting purposes, but without any user related data. The user is also logically deleted, when not already done so: see Section C.1.5, “deleteUser” and Section 4.11.2, “User Creation”.
Caution
When a database is restored, erased users might be restored as identifiable users again. Therefore, keep Data Erasure requests in a separate administration, so that they can easily be retrieved and re-executed.
Warning
Erasing users without deleting them from their external user source has a temporary effect, since they will be created again at the next synchronization.
./savapage-cmd --get-config-property --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : getConfigProperty
Version : 0.10
Gets configuration property value.
This is an advanced command. Please contact SavaPage Support before use.
usage: --get-config-property [OPTION]...
--name <text(100)> [required] Property name.
-h,--help Displays this help text.Note
Values that are stored encrypted are returned decrypted. See Section 17.6, “Encrypted Secrets”.
Also see Section C.4.3, “db-config-get” and Section C.1.19, “setConfigProperty”.
./savapage-cmd --list-users --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : listUsers
Version : 0.10
Lists the names of all the Users in the system, sorted by user name, one per line.
usage: --list-users [OPTION]...
-h,--help Displays this help text.
./savapage-cmd --list-user-groups --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : listUserGroups
Version : 0.10
Lists the names of all the User Groups in the system, sorted by name, one per line.
usage: --list-user-groups [OPTION]...
-h,--help Displays this help text.
./savapage-cmd --list-user-group-members --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : listUserGroupMembers
Version : 0.10
Lists the names of the user group members in the system, sorted by user name,
one per line.
usage: --list-user-group-members [OPTION]...
--groupname <text(255)> [required] Unique group name.
-h,--help Displays this help text.
./savapage-cmd --list-user-group-memberships --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : listUserGroupMemberships
Version : 0.10
Lists the names of the groups a user belongs to, sorted by name, one per line.
usage: --list-user-group-memberships [OPTION]...
--username <text(50)> [required] Unique user name.
-h,--help Displays this help text.
./savapage-cmd --list-user-source-groups --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : listUserSourceGroups
Version : 0.10
Lists the names of all the groups in the user source, sorted by name, one per line.
usage: --list-user-source-groups [OPTION]...
-h,--help Displays this help text.
./savapage-cmd --list-user-source-group-members --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : listUserSourceGroupMembers
Version : 0.10
Lists the names of the (nested) user group members in the user source,
sorted by user name, one per line.
usage: --list-user-source-group-members [OPTION]...
--groupname <text(255)> [required] Unique group name.
--nested [optional] Accumulate members from nested groups
(Active Directory only).
-h,--help Displays this help text.
./savapage-cmd --list-user-source-group-nesting --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : listUserSourceGroupNesting
Version : 0.10
Lists a space indented hierarchy of nested groups within a group. Nested groups
are only supported by Active Directory, all other user sources return an empty list.
usage: --list-user-source-group-nesting [OPTION]...
--groupname <text(255)> [required] Unique group name.
-h,--help Displays this help text.
./savapage-cmd --printer-access-control --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : printerAccessControl
Version : 0.10
Controls user groups to either allow or deny access to a proxy printer.
usage: --printer-access-control [OPTION]...
--printername <text(255)> [required] CUPS name of the proxy printer.
--allow [optional] Allow access to --groupname (existing
denied user groups are removed).
--deny [optional] Deny access to --groupname (existing
allowed user groups are removed).
--remove [optional] Remove --groupname from the access list.
--groupname <text(255)> [optional] Name of the user group to --allow, --deny
or --remove access
--remove-all [optional] Remove all user groups from the access
list.
--list [optional] Echoes the access list to stdout in CSV
format.
-h,--help Displays this help text.
./savapage-cmd --printer-snmp --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : printerSnmp
Version : 0.20
Reads SNMP info from a printer.
usage: --printer-snmp [OPTION]...
--printername <text(255)> [optional] CUPS printer name used to resolve host
name (required when --host is not set).
--host <text> [optional] Host name or IP address of the printer
(required when --printername is not set).
--port <number> [optional] SNMP port number (default 161).
--community <text> [optional] SNMP community (default "public").
--version <1|2c> [optional] SNMP version (default "1").
-h,--help Displays this help text.
./savapage-cmd --set-config-property --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : setConfigProperty
Version : 0.10
Sets configuration property value.
The property must be present in the database. Not all properties are available for update.
This is an advanced command. Please contact SavaPage Support before use.
usage: --set-config-property [OPTION]...
--name <text(100)> [required] Property name.
--value <text(1000)> [required] Property value.
-h,--help Displays this help text.
-batch Enables batch mode: executing from CSV or TSV input.
-continue Continues batch processing after a batch line execution
error.
-input <arg> Batch input file: optional with stdin as default.
-charset <arg> IANA Charset Name of batch input character encoding
[default: utf-8].Note
Some values will be stored encrypted. See Section 17.6, “Encrypted Secrets”.
Also see Section C.4.4, “db-config-set” and Section C.1.9, “getConfigProperty”.
./savapage-cmd --set-user-properties --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : setUserProperties
Version : 0.30
Sets properties for an existing Internal or External User.
usage: --set-user-properties [OPTION]...
--username <text(50)> [required] Unique user name.
--password <text(64)> [optional] Password (Internal User only).
--full-name <text(255)> [optional] Full user name.
--email <text(255)> [optional] Primary Email address.
--email-other <list> [optional] List of space separated other
(secondary) Email addresses.
--card <text(16)> [optional] NFC Card Number.
--card-format <HEX|DEC> [optional] NFC Card Number Format [default:
HEX].
--card-first-byte <LSB|MSB> [optional] NFC Card Number First Byte [default:
LSB].
--id <text(16)> [optional] ID Number.
--pin <text(16)> [optional] PIN for ID and Card.
--yubikey <text(12)> [optional] YubiKey Public ID.
--uuid <text(36)> [optional] The user's secret UUID.
--balance <decimal> [optional] The user's current account balance.
--balance-comment <text(255)> [optional] A comment to be associated with the
--balance transaction.
--credit-limit [optional] Assign default credit limit amount.
--credit-limit-amount <decimal> [optional] Assign custom credit limit amount.
--credit-limit-none [optional] No credit limit restriction (opposed
to --credit-limit and --credit-limit-amount).
--keep-card [optional] Keep existing Card Number, or use
--card value when not present.
--keep-id [optional] Keep existing ID Number, or use --id
value when not present.
--keep-email-other [optional] Keep existing other (secondary)
Email addresses, or use --email-other value
when not present.
--keep-password [optional] Keep existing Password, or use
--password value when not present (Internal
User only).
--keep-pin [optional] Keep existing PIN, or use --pin
value when not present.
--keep-uuid [optional] Keep existing UUID, or use --uuid
value when not present.
--remove-email [optional] Remove Primary Email address
(opposed to --email).
--remove-email-other [optional] Remove other (secondary) Email
addresses (opposed to --email-other).
--remove-card [optional] Remove NFC Card Number (opposed to
--card).
--remove-id [optional] Remove ID Number (opposed to --id).
--remove-password [optional] Remove Password (Internal User
only).
--remove-pin [optional] Remove PIN (opposed to --pin).
--remove-yubikey [optional] Remove YubiKey Public ID (opposed to
--yubikey).
--remove-uuid [optional] Remove UUID (opposed to --uuid).
-h,--help Displays this help text.
-batch Enables batch mode: executing from CSV or TSV
input.
-continue Continues batch processing after a batch line
execution error.
-input <arg> Batch input file: optional with stdin as
default.
-charset <arg> IANA Charset Name of batch input character
encoding [default: utf-8].
-locale <arg> The IETF BCP 47 Locale used for numeric values.
Example values are: en, en-GB, en-US, nl,
nl-NL, nl-BE. [defaults to system default
en-US].
./savapage-cmd --set-user-group-properties --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : setUserGroupProperties
Version : 0.11
Sets properties of an Internal or External User Group.
usage: --set-user-group-properties [OPTION]...
--groupname <text(255)> [required] Unique group name.
--balance <decimal> [optional] The user's initial account
balance.
--credit-limit [optional] Assign default credit limit
amount to new users.
--credit-limit-amount <decimal> [optional] Assign custom credit limit amount
to new users.
--credit-limit-none [optional] Assign no credit limit
restriction to new users (opposed to
--credit-limit and --credit-limit-amount).
--role-job-ticket-creator <Y|N|U> [optional] Assign Job Ticket Creator role.
--role-job-ticket-operator <Y|N|U> [optional] Assign Job Ticket Operator role.
--role-print-creator <Y|N|U> [optional] Assign Print Creator role.
--role-print-delegate <Y|N|U> [optional] Assign Print Delegate role.
--role-print-delegator <Y|N|U> [optional] Assign Print Delegator role.
--role-web-cashier <Y|N|U> [optional] Assign Web Cashier role.
-h,--help Displays this help text.
-batch Enables batch mode: executing from CSV or
TSV input.
-continue Continues batch processing after a batch
line execution error.
-input <arg> Batch input file: optional with stdin as
default.
-charset <arg> IANA Charset Name of batch input character
encoding [default: utf-8].
-locale <arg> The IETF BCP 47 Locale used for numeric
values. Example values are: en, en-GB,
en-US, nl, nl-NL, nl-BE. [defaults to system
default en-US].
./savapage-cmd --sync-user-group --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : syncUserGroup
Version : 0.10
Synchronizes a user group with the external user source, updating group membership.
usage: --sync-user-group [OPTION]...
--groupname <text(255)> [required] The name of the group to synchronize.
-h,--help Displays this help text.
./savapage-cmd --sync-users-and-groups --help
... gives the options:
________________________________
SavaPage Command Line Interface
Method : syncUsersAndGroups
Version : 0.10
Starts user and group synchronization with external user source.
This is equivalent to clicking "Synchronize now" in the Admin Web App.
Synchronization completes in the background.
usage: --sync-users-and-groups [OPTION]...
--delete-users [optional] Remove users that do not exist in external user
source.
-h,--help Displays this help text.
./savapage-cmd ---system-status --help
... gives the options:
________________________________ SavaPage Command Line Interface Method : systemStatus Version : 0.10 Gets the system status enum value: READY, SETUP, UNAVAILABLE, MAINTENANCE. usage: --system-status [OPTION]... -h,--help Displays this help text.
This command is identical to Section C.2.2.1, “systemStatus”.