Skip to content

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.15 or ipp://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 file is sent to the printer in addition to checking the connection. If a protocol is specified in the connection, this protocol is also used to transmit the test file.

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
The answer could look like 
✓ 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
The answer could look like 
✓ ✓ 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 monitorConnection or as a fallback the connection value of the tested printer
  • the return code
  • the return code description
  • the ip address if available

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
Back to top