Administrate the Printers¶
The printers in an Output Engine system can be administrated via PLOSSYS CLI.
Hint - Web user interface
Some of the operations can be executed via PLOSSYS Administrator as well.
Requirements¶
For the requirements for using PLOSSYS CLI, refer to PLOSSYS CLI.
Options¶
Specific Output Engine Server¶
For administrating the printers of a specific Output Engine server, specify the --server <plossys_server> option. Default is https://localhost:8080.
plossys printer <command> --server https://<plossys_server>:8080
Example - show all printers of the plossys.server1.com server
plossys printer show --server https://plossys.server1.com:8080
Self-Signed Certificates¶
Specifying the --insecure option, you avoid that the certificate will be checked by the client.
plossys printer <command> --insecure
User Authentication¶
Depending on the type of user authentication activated for the seal-rest service, you have to specify the user and the password with PLOSSYS CLI. By default, the specified user is first checked via OpenID Connect and via basic authentication as fallback.
plossys printer <command> --auth <auth_type> --user <user> --pass <password>
Example - show all printers as user test authenticated via OpenID Connect
plossys printer show --auth oidc --user test --pass test
Using OpenID Connect, you can alternatively specify a JSON Web token (JWT) instead of a user and his password.
plossys printer <command> --auth oidc --bearer <jwt>
Example - show all printers as a user authenticated via JSON Web token
plossys printer show --auth oidc --bearer eyJ0eXAiOiJKV1QiLCJhbG...
The credentials, that means user and password or the token, can also be contained in a credential file which is specified with PLOSSYS CLI.
plossys printer <command> --auth oidc --credential <credential_file>
Commands¶
Show All Printers¶
plossys printer show
Show Specific Printers¶
plossys printer show <printer_name_1> <printer_name_2> ... <printer_name_n>
Show Specific Fields for Printers¶
plossys printer show --fields <field_name>
Example - show the connection data
plossys printer show --fields "config/connection"
Pause Specific Printers¶
plossys printer pause <printer_name_1> <printer_name_2> ... <printer_name_n>
Resume Specific Printers¶
plossys printer resume <printer_name_1> <printer_name_2> ... <printer_name_n>
Delete Specific Printers¶
plossys printer remove <printer_name_1> <printer_name_2> ... <printer_name_n>
Redirect a Printer¶
plossys printer redirect <source_printer_name> <target_printer_name>
Set Printer Message¶
plossys printer set-message <printer> <message>
Remove Printer Message¶
plossys printer remove-message <printer> <message>
Export the Configuration of a Specific Printer¶
plossys printer export <printer_config_file>.yml <printer_name>
Example - minimum printer configuration
printer: hp4050
connection: 'socket://194.49.3.130:9100'
server: spooler1
webUrl: 'http://194.49.3.130'
Caution - file extension
The standard Output Engine driver templates come with a printer configuration file in yml.in format. Files in yml.in format can be used for importing the printer configuration. They will be internally converted into yml format before being uploaded to PLOSSYS Output Engine.
PLOSSYS CLI recognizes the format by the file extension. In case of the yml.in file extension, the file will be converted.
When exporting a printer configuration to a file, the file always has the yml format. An automatic conversion from yml into yml.in is impossible.
If you export a printer configuration in order to modify it and import it again afterwards, do not give the export file the file extension yml.in, as you might expect if you worked with a yml.in file from a driver template before. Otherwise, an erroneous conversion would take place when you re-import the modified file. In most cases, the import would still work without an error, but PLOSSYS Output Engine would send erroneous jobs to the printers.
For the printer configuration export, always use file names with the yml extension!
Import a Printer Configuration File¶
plossys printer import <printer_config_file>.yml
Caution - allowed characters
The printer name must not contain UTF-8 or apostrophes. Although the printer will be imported, jobs cannot be processed via this printer.
Hint - printer not deleted
New printers are added. Existent printer configurations are overwritten with the new configuration data. The printer configurations already stored in PLOSSYS Output Engine are not deleted.
Validate a Printer Configuration File¶
plossys printer validate <printer_config_file>.yml
Example - valid printer configuration file
plossys printer validate valid.yml
results in
+ Successfully validated configuration from valid.yml.
Example - invalid printer configuration
plossys printer validate invalid.yml
results in
! Syntax of config file invalid.yml is invalid.
! bad indentation of a mapping entry at line 16, column 6:
- name: PJL Enter Language Posts ...
Hint - more options
For information about the additional options with validating a printer configuration file, execute:
plossys printer validate --help
Check Printer Connections¶
With the following command, you check one or more printer connections and send a test file to the printer optionally. All connections are tested from the server, so this command can be used even if no direct connection to the printer is possible from the computer PLOSSYS CLI runs on.
plossys printer check <connection_list> [--no-color] [--testfile <file_name>]
Connection List¶
The connection_list contains printer names and/or printer connections, either specified on command line separated by blanks or read from stdin separated by newline if - has been specified.
The following syntax is possible for specifying the connection:
- Name of the installed printer, for example,
myPrinter1 - Connection as
server:port, for example,printer1:9100 - URL providing the printer name, for example,
printer://myPrinter1 - URL providing the connection, for example
socket://printer1:9100,lpr://10.100.120.15oripp://10.100.120.15:63
If you don't specify a port for the connection, the respective default port will be used, i.e. 515 for the LPR protocol and 631 for the IPP protocol.
Messages Without Color¶
The --no-color option disables the coloration of the messages output to stdout and stderr. For the coloration, control characters are used which could interfere with the automated evaluation of the messages.
Output a Test File¶
With specifying the --testfile <file_name> option, the
Examples¶
Example - specifying the connections in a file
printer.txt contains the following lines:
printer1
printer2
printer3
The command
cat printer.txt | plossys printer check - --no-color
checks the connections to the printer1, printer2 and printer3 printers. For a configuration like
- printer: printer1
connection: 'socket://printer1:9100'
- printer: printer2
connection: 'socket://printer2-off:9200'
- printer: printer3
connection: 'socket://printer3:930'
the output would be:
✓ socket://printer1:9100 Ok Ok 192.168.192.6
✗ socket://printer2-off HostnameNotFound Hostname not found.
✗ socket://printer3:930 ErrorConnectToPort Cannot connect to port. 192.168.192.3
Example - specifying the connections on command line
plossys printer check printer1 printer2 printer3 --no-color
Example - checking if a printer supports the IPP protocol
plossys printer check ipp://10.100.120.15:631 --insecure --testfile testfile_A4_Skalen.ps
✓ ipp://10.100.120.15:631/ipp Ok Ok 10.100.120.15
Example - checking if a printer supports the LPR protocol
plossys printer check lpr://10.100.120.15 --insecure
✓ ✓ lpr://10.100.120.15:515 Ok Ok 10.100.120.15
Return Message and Return Codes¶
The printer check command returns on stderr for each check:
- the
monitorConnectionor as a fallback theconnectionvalue of the tested printer - the return code
- the return code description
- the ip address if available
Example - return messages"
The output could look like one of the three below.
```
✓ socket://printer1:9100 Ok Ok 192.168.192.6
✗ socket://printer2-off HostnameNotFound Hostname not found.
✗ socket://printer3:930 ErrorConnectToPort Cannot connect to port. 192.168.192.3
```
In the first case, the test was successful, the tested connection and the ip adress are returned.
In the second case, the hostname wasn't found, no ip address is returned.
In the third case, the printer was found but couldn't connect. The ip address is returned.
The following return codes are possible:
| Return Code | Description |
|---|---|
ErrorConnectionMissing |
Neither printer name nor connection has been specified. |
ErrorConnectToHost |
Server cannot be reached. |
ErrorConnectToPort |
Server was found but no application is listening on the port. |
ErrorDns |
Error with DNS lookup |
ErrorInvalidUrl |
The specified URL is invalid. |
ErrorPortMissing |
The port has not been specified in the URL. |
ErrorPrinterNotFound |
The specified printer is not configured in the system. |
ErrorReadDatabase |
Server-side error when reading the database |
ErrorReadingStream |
Error when reading the test file |
ErrorSendingData |
General error when sending the test file to the printer |
ErrorWritingStream |
Error when writing the test file to the printer |
HostnameNotFound |
The server name could not be find by DNS lookup. |
Advanced Printer Queries¶
For advanced printer queries, the query command is available. The query command supports the OData language. The result of the command is always a list of printers. In order to execute complex queries and operations, this list can be combined with other PLOSSYS CLI commands.
plossys printer query <query> --fields <field_name_1>,<field_name_2>,...,<field_name_n>
If the option --fields is omitted, only the Printer-IDs are returned. If --fields ALL is specified, all printer parameters are returned. For further usage of --fields see plossys printer show
Example - list the active printers
plossys printer query "runtime/status eq 'active'"
Example - pause the active printers
plossys printer query "runtime/status eq 'active'" | plossys printer pause -
Example - show all printers whose names begin with odm
plossys printer query "startswith(_id,'odm')" --fields ALL