EBF product documentation

Find help using and administering EBF applications

05. Configuration

It is recommended to configure the Print Proxy System first and then the Print Server System.

Print Proxy Configuration

EBF Print can address several enterprise printing systems (multi-tenant capability), requiring an assignment between tenants and their respective enterprise print server systems. This assignment is configured through the Print Proxy and stored in the configuration file:

/etc/ebf/print/proxy.yaml

An example of this file with a configured print server (rules section) and a given identity provider (identity section) looks as follows for a connected MobileIron EMM system.

# limit the supported SSL/TLS protocols
#  by removing unwanted from the brackets
server: 
  host: 127.0.0.1 
  port: 8443 
  ssl: 
    #############################################################################
    # Either enable or disable SSL support for the application
    enabled: true

    #############################################################################
    #   The supported SSL/TLS protocols can be limited
    # by removing unwanted from the brackets
    protocols: [TLSv1, TLSv1.1, TLSv1.2]
    
    #############################################################################
    #   The keystore file to use for SSL context of the application.
    #
    #   When provided keystore file has a proper extension
    # keystore_type can be resolved from it.
    #
    #   Listed extensions below automatically being recognized to choose 
    # corresponsing implementation:
    # .jceks    : The proprietary keystore implementation by the SunJCE provider.
    # .jks      : The proprietary keystore implementation by the SUN provider.
    # .keystore : Same as .jks
    # .pkcs12.  : The transfer syntax for personal identity information as defined
    #             in PKCS #12.
    keystore: /path/of/the/keystore/print-server-keystore.p12
    
    #############################################################################
    #   Keystore type defines which keystore implementation
    # will be used to manage the defined keystore file.
    #
    #   By default this option can be ommitted in favor of when the keystore file
    # has proper extension as mentioned above.
    #
    #   Available options: JCEKS, JKS, PKCS12
    keystore_type: PKCS12
    
    #############################################################################
    #   The used password to encrypt the keystore file.
    keystore_password: changeit
    
    #############################################################################
    #   Defined alias name of the certificate contained by the keystore
    # can be set with this option to use for the SSL contex of the application.
    cert_alias: cert

identity:
  provider:
    mobile_iron:
      type: mobile_iron
      default: true
      host: emm.example.com 
      username: 'admin' 
      password: 'admin' 

      # possible values: user_uuid, user_id, user_email, 
      #  user_first_name, user_last_name, user_display_name, 
      #  user_custom_1, user_custom_2, user_custom_3, user_custom_4, 
      # user_custom_<attribute_name> 
      user_attribute: user_id 

      # possible values: device_custom_<attribute_name> 
      # where <attribute_name> is case sensitive
      group_attribute: device_custom_Institute

rules: 
# - user: 'john doe' 
#   group: 'sales' 
#   printer:'ipp://sales.example.de:631/ipp/print/John%27s%20Printer' 

  - printer: 'ipp://print.example.de:631/ipp/print/QA%20Printer' 

Privileged ports (less than 1024) are not allowed as the service should be operated and started with a restricted user. Existing Print Servers can be linked to the users via user and/or group identifiers. The first rule that matches the transferred data (user/group) is applied and the print job will be forwarded accordingly. Only one printer can be assigned at the same time.

‚#‘ is used for comments and makes the entry inactive.

  1. Edit the system configuration file for Print Proxy using LINUX vi Editor as an example:
    $ vi /etc/ebf/print/proxy.yaml
  2. Start editing by entering ‚Insert mode‘ with ‚i‘, ESC to end ‚Insert mode‘.
  3. End the change with ESC ‚:x‘ to save the settings.
  4. Check the file with ‘cat’ ‘filename’.

 

Identity Provider

 

MobileIron

Name Required Possible values
type yes [1] mobile_iron
default yes [2] true / false
host yes
username yes
password yes
user_attribute yes user_uuid
user_id
user_email
user_first_name
user_last_name
user_display_name
user_custom_1
user_custom_2
user_custom_3
user_custom_4
user_custom_<attribute_name>
group_attribute no device_custom_<attribute_name>

Example in the proxy.yaml configuration file

identity:
  provider:
    mobile_iron:
      host: emm.example.com
      username: 'admin'
      password: 'admin'
      user_attribute: user_id
      group_attribute: device_custom_Group

 

Microsoft Intune

Name Required Possible values
type yes [1] intune
default yes [2] true / false
client_id yes
client_secret yes
tenant yes
user_attribute yes user_id
user_principal_name
user_display_name
user_employee_id
group_attribute no group_id
group_display_name

Example in the proxy.yaml configuration file

identity:
  provider:
    intune:
      client_id: 32f91de8-2d75-436c-8709-d491169add7e
      client_secret: GF23Zj~C~SGD62N_8e3kOZ2pO-n2X.5YaI
      tenant: 0142169f-fb83-43c4-9d19-5f2869fdb9f7
      user_attribute: user_id
      group_attribute: group_id

 

Workspace ONE

Name Required Possible values
type yes [1] workspace_one
default yes [2] true / false
host yes
username yes
password yes
tenant_code yes
user_attribute yes user_uuid
user_external_id
user_name
user_first_name
user_last_name
user_full_name
user_display_name
user_principal_name
user_email
user_custom_1
user_custom_2
user_custom_3
user_custom_4
user_custom_5
group_attribute no organization_group_id
organization_group_name

Example

identity:
  provider:
    workspace_one:
      host: emm.example.com
      username: 'admin'
      password: 'admin'
      tenant_code: 8nsrP0FSnlqWeizpCIh6yuw5WwV1MY5sskw4wVZA3e4=
      user_attribute: user_name
      group_attribute: organization_group_name
  1. Input your changes with ‚i‘ (enter Insert Mode)
  2. End Insert Mode with ‘ESC’
  3. End the input with ‘ESC :x’ to save the changes
  4. The server can now be started, and its status can be checked with the following commands:
    Server Start systemctl start ebf-print-proxy
    Server Status systemctl status ebf-print-proxy
    Logs journalctl -u ebf-print-proxy
    Detailed Logs journalctl -u ebf-print-proxy -o verbose
    Live Logs journalctl -f -u ebf-print-proxy
    Activate Service Autostart systemctl enable ebf-print-proxy
    Service Status Check systemctl status ebf-print-proxy(service should be enabled)

Rules

This configuration section defines the routing rules for the printers. The device’s designated printer was determined using the user group and name attributes obtained during identification.

Example:

identity:
  provider:
    ios:
      type: mobile_iron
      ...
    mac_os:
      type: workspace_one
      ...
rules:
  - user: jane
    group: finance
    printer: ipp://ebf-print-server.example.com:8631/ipp/print/finance
  - group: sales
    printer: ipp://ebf-print-server.example.com:8631/ipp/print/sales

Let’s say Jane Doe has an AirPrint profile configured to point “ipps://ebf-print-proxy.example.com:8443/ipp/printer/00000000-BEAD-0000-0000-000000000000!uem_id(mac_os) and during identification with mac_os (UEM) identity provider, the group determined to be “finance” and user to be “jane” then according to the rules shown above Jane Doe will be able to use ipp://ebf-print-server.example.com:8631/ipp/print/finance

Likewise, if John Doe has an AirPrint profile configured to point “ipps://ebf-print-proxy.example.com:8443/ipp/printer/00000000-CAFE-0000-0000-000000000000!uem_id(ios) and during identification with ios identity provider, the group determined to be „sales“ and user to be „john“ then according to the rules shown above Jane Doe will be able to use ipp://ebf-print-server.example.com:8631/ipp/print/sales but here regardless the user name John Doe would be able to use the printer because rule doesn’t the user to match the user as opposite the first rule. In other words, this means the printer is designated for any user part of the sales group like John Doe.

Notes

  1. [^mobile_iron] [^intune] [^workspace_one]
    Starting with EBF Proxy v2.5.0, multiple UEMs can be defined with arbitrary identifiers. Therefore, when the provider is defined with its predefined/known name, such as intune, the „type“ field can be omitted. However, the type field should be present when multiple UEMs are used with arbitrary identifiers.

    identity:
  provider:
    ios:                  # here the identifier is "ios"
      type: mobile_iron   # and here, the type defined that is Ivanti EPMM
      ...
    mac_os:               # and here the second identifer is "macos"
      type: workspace_one # and here, the type defined that is Workspace ONE
      ...
  2. [^mobile_iron] [^intune] [^workspace_one]
    Starting with EBF Proxy v2.5.0, multiple UEMs can be defined with arbitrary identifiers. Therefore, while pushing the EBF Print AirPrint profile to devices, the printer URL may or may not contain the!uem_id(…) parameter; in the case before EBF Proxy v2.4.0, this is the case. With the EBF Proxy v2.5.0, when a new identity provider is defined under providers, the default parameter should be present and set as “true” for the previously defined “only” provider to help preserve functionality. Otherwise, the devices that have no !uem_id(…) parameter on their AirPrint profile will be tried to be identified via implicitly chosen to be the default identity provider, which may or may not be the correct one. The default parameter here is essential in ensuring the system behaves as expected, like before EBF Proxy v2.4.0.

 

Firewall Setting

To enable the Print Proxy Admin Portal within a browser, firewall configuration within the Print Proxy appliances is required. The port previously defined in the configuration file for the Print Proxy Admin Portal must be enabled:

$ sudo firewall-cmd --zone=Public --add-port=8080/tcp -–permanent

$ sudo firewall-cmd -–reload

 

Network Appliance Configuration

If the print environment (Proxy or Server) networks require further configuration, this is also possible through the bash console of the respective appliances:

$ sudo nmtui

 

Proxy Portal (deprecated)

The configuration for the Print Proxy interface is contained in the configuration file:

/etc/ebf/print/admin.yaml

An example of this file is as follows:

server:
  port: 80

token:
  secret: 'secret'

mobile_iron:
  host: emm.example.com
  username: 'admin'
  password: 'admin'

  configuration_suffix: ' EBF Print'

profile:
  display_name: 'EBF Print'

The „configuration_suffix“ entry is appended to the profile name assigned by the administrator when the print profile is created to allow filtering in any EMM profile lists. The profile „display_name“ is visible in profile settings on the iOS device. Customize the file „admin.yaml“ for Print Proxy with the LINUX vi Editor for example:

$ vi /etc/ebf/print/admin.yaml

  1. Start editing with entering ‘Insert mode’ with ‘i‘, ESC to end ‚Insert mode’.
  2. End the change with ESC ‘:x’ to save the settings.
  3. Check the file with ‘cat’ ‘filename’.
  4. The Print Admin console can now be started and its status be checked:
    Server Start systemctl start ebf-print-admin
    Server Status systemctl status ebf-print-admin
    Logs journalctl -u ebf-print-admin
    Activate Service Autostart systemctl enable ebf-print-admin
    Service Status Check systemctl status ebf-print-admin(service should be enabled)

 

Print Server Configuration

The configuration of the Print Server occurs through the configuration file:

/etc/ebf/print/server.yaml

An example with two configured Print Servers in the section „printers“ is as follows:

server:
  host: "192.168.1.1" 
  port: 8631
  ssl:
    #############################################################################
    # Either enable or disable SSL support for the application
    enabled: true

    #############################################################################
    #   The supported SSL/TLS protocols can be limited
    # by removing unwanted from the brackets
    protocols: [TLSv1, TLSv1.1, TLSv1.2]
    
    #############################################################################
    #   The keystore file to use for SSL context of the application.
    #
    #   When provided keystore file has a proper extension
    # keystore_type can be resolved from it.
    #
    #   Listed extensions below automatically being recognized to choose 
    # corresponsing implementation:
    # .jceks    : The proprietary keystore implementation by the SunJCE provider.
    # .jks      : The proprietary keystore implementation by the SUN provider.
    # .keystore : Same as .jks
    # .pkcs12.  : The transfer syntax for personal identity information as defined
    #             in PKCS #12.
    keystore: /path/of/the/keystore/print-server-keystore.p12
    
    #############################################################################
    #   Keystore type defines which keystore implementation
    # will be used to manage the defined keystore file.
    #
    #   By default this option can be ommitted in favor of when the keystore file
    # has proper extension as mentioned above.
    #
    #   Available options: JCEKS, JKS, PKCS12
    keystore_type: PKCS12
    
    #############################################################################
    #   The used password to encrypt the keystore file.
    keystore_password: changeit
    
    #############################################################################
    #   Defined alias name of the certificate contained by the keystore
    # can be set with this option to use for the SSL contex of the application.
    cert_alias: cert
 
spool: /var/spool/ebf/print

printers: 
  -
    name: "QA Printer" 
    connection: "lpd://10.4.0.1/QAPrinter"
    driver: /usr/share/ebf/print/default.ppd
  -
    name: "DEV Printer" 
    location: "Dev Room" 
    connection: "lpd://10.4.0.2/DEVPrinter" 
    driver: /usr/share/ebf/print/default-pcl.ppd
    media: A4
  • Port: No privileged port (less than 1024) can be used for the server port, the service should be operated with a restricted user to allow the service to start.
  • Connection: The attribute „connection“ contains the address of the enterprise (FollowMe) printing solution or simply the raw printer IP. The printer name that appears on the iOS device is taken directly from the „name“ attribute and must match the name in the URL from the „printer“ attribute in „proxy.yaml“ from Print Proxy Configuration.
  • Location: The „location“ attribute is displayed as additional information in the printer properties on the iOS device.
  • Media:  Two options are available here: A4 and Letter. As a default A4 will be used, if this parameter is missing.

Editing the configuration file for the EBF Print Server can be achieved for example using the LINUX vi Editor on the appliance system with the following call:

$ vi systemctl /etc/ebf/print/server.yaml

  1. Start editing with entering ‘Insert mode’ with ‘i‘, ESC to end ‚Insert mode’.
  2. End the change with ESC ‘:x’ to save the settings.
  3. Check the file with ‘cat’ ‘filename’.
Parameter Description
Connection IP-Address of Print Proxy
Name Printer name the users see on iOS devices (matches the name from the URL „printer“ attribute in „proxy.yaml“ file.
Location Displayed as additional information in printer properties on the iOS device.

The server can now be started and its status checked. The commands are described below:

Server Start systemctl start ebf-print-server
Server Status systemctl status ebf-print-server
Logs journalctl -u ebf-print-server
Detailed Logs journalctl -u ebf-print-server -o verbose
Live Logs journalctl -f -u ebf-print-server
Activate Service Autostart systemctl enable ebf-print-server
Service Status Check systemctl status ebf-print-server # PS: service should be enabled

 

Logging

EBF Print services utilize Log4j2 [1] as a logging backend.

In addition to official Log4j2 appenders, EBF Print provides a custom high troughput low-latency/low-overhead appender implementation called SystemdJournalAppender to target systemd-journald logging infrastructure. systemd-journald is the default logging infrastructure for several Linux operating systems [2], such as CentOS, Ubuntu and EbfOS “that also based on CentOS”.

By default configuration file format choosen to be yaml to keep the consistency with application configuration files. That has been said, other file formats also can be used when desired such as xml, json.

When the configuration file format needed to be changed, there is three steps to folow:

1. Converting the configuration file format to desired file format and rename the file name
2. Edit the application service file (e.g., /etc/systemd/system/ebf-print-[server|proxy|admin].service) to point the new file name defined in ExecStart= property.
3. Restart the service.

PS: Location of ebf-print-[server|proxy|admin].service may differ with among operating system

 

Logging Configuration

Configuration file location

EBF Print Service The location of the logging configuration file
EBF Print Server /etc/ebf/print/server.log4j2.yaml
EBF Print Proxy /etc/ebf/print/proxy.log4j2.yaml
EBF Print Admin /etc/ebf/print/admin.log4j2.yaml

 

In-depth example of the configuration file with explanations

The scaffold of the EBF Print Server service configuration follows:

The only difference with other service configurations syslogIdentifier definition; “Configuartions > Appenders > SystemdJournal > syslogIdentifier: ebf-print-[server|proxy|admin]” beside that, the rest of the content is identical.

Configuration:                  # Root of the configuration
    status: INFO                # Logging backend related log level[3] can be set with this property;
                                # * e.g., when logging backend (Log4j2) encounters internal errrors
                                # *      such as "configuration file is misconfigured"
                                # *      then the systems default logging infrastructure
                                # *      will be informed with this error information
    monitorInterval: 30         # Configuration change detection worker interval (in seconds)

    Appenders:                  # List of appenders definitions

        # Console appender only applicable when the service being executed from os command line.
        #     Therefore this appender won't be used when the EBF Print service running normally
        #     as a sytem service.
        #     * This appender maybe required for in the case of troubleshooting sessions.
        Console:                # Console appender definition
            name: console       # Console appender identifier
            target: SYSTEM_OUT  # Appender output target
            PatternLayout:      # Individual log line format for the appender
                # The format of the log line (for further information please refer the Log4j2 docs.)
                pattern: "%d{HH:mm:ss.SSS} | %-5level | %thread | %logger{36} | %msg%n"

        # EBF Print service custom low latency/overhead appender implementation 
        #     for the systemd-journald logging infrastructure.
        SystemdJournal:         # SystemdJournal appender definition
            # Appender name (can not be empty)
            name: journald      # SystemdJournal appender identifier

            # Log data to be sent to journal log system
            # DEFAULT: Exception | ExceptionLocation | ThreadName
            # VALUES: List of possible log event data as follows
            #                               # When included occured log information will contain:
            #        Exception |            # * The occured exception (e.g., IOException)
            #        ExceptionLocation |    # * The source location of the exception
            #        ExceptionStackTrace |  # * The unwound exception stack information
            #        SourceLocation |       # * The source location of the log invocation
            #        LoggerName |           # * The name of the logger instance (e.g., com.ebf.print.server.ServerHandler )
            #        AppenderName |         # * The configured name of the appender (e.g., journald)
            #        ThreadName |           # * Executing thread name (e.g., main-3)
            #        ThreadContext          # * Executing thread context
            # <?> Desired values can be set with concatinating pipe(|) symbol,
            #   e.g.,
            #       includedLogEventData: Exception | SourceLocation
            includedLogEventData: DEFAULT

            # Thread content prefix
            # DEFAULT: `` (empty)
            threadContextPrefix:

            # Journal Syslog identifier (application name)
            # DEFAULT: if set; environment value via `JOURNALD_SYS_LOG_IDENTIFIER`
            #          or executing main class name `package.name.space.MainClassName`
            syslogIdentifier: ebf-print-server

            # Facility to log into
            # DEFAULT: 3 = daemon; https://en.wikipedia.org/wiki/Syslog#Facility
            syslogFacility: 3

            # Fallback appender if the underlying system is not supporting the Journald
            # DEFAULT: none
            fallbackAppender: console

    Loggers:                    # List of Logger definitions root
        Root:                   # Root logger
            level: INFO         # Root logger level[3] (ALL, TRACE, DEBUG, INFO, WARN, ERROR, FATAL, OFF)
            AppenderRef:        # Appender reference of the root logger
                - ref: journald # Reference appender definition

In addition to defined loggers**, additional loggers with different appenders also can be added to the system, such as FileAppender[4].

** In the default configuration, only the Root logger is defined, as can be observed above.

Automatic configuration change detection on runtime

By default, the logging configuration every 30 seconds is checked for configuration changes, such as log level.

In the case of troubleshooting, the support engineers may need to check detailed debugging or, in rare cases, even more, in-depth tracing information.

This means the EBF Print logging backend can produce this low-level logging information with simple configuration changes for the required time frame without needing the restart the services.

This capability is valuable; hence this capability can help to prevent either interruption of the currently running operations or any unrecoverable run-time data loss during a troubleshooting session.

References

[1] Log4j2 official documentation can be found at https://logging.apache.org/log4j/2.x/manual/configuration.html.

[2] Some of the systemd-based operating systems can be found at https://en.wikipedia.org/wiki/Systemd.

[3] Available log levels and details of each can be found at https://logging.apache.org/log4j/2.x/manual/architecture.html#:~:text=Event%20Level-,LoggerConfig%20Level,-TRACE

[4] A comprehensive list of usable Log4j2 appenders can be found at https://logging.apache.org/log4j/2.x/manual/appenders.html.

Was this article useful?