Configuration

These settings control how the server operates and manages itself.  All settings are stored in the server's configuration file, config.ini, and can be maintained there manually or via the browser interface.

General Settings

Data Path defines where operation data is stored, including company and site user settings.  This path defaults to the "data" directory where CirrusPrint is installed.  If desired, you can move the directory elsewhere and change the path setting here.  This is important in high-availability configuration, where multiple CirrusPrint servers share the same data.  A single network path can serve such environments.

Max Size sets the maximum file size that CirrusPrint will accept.  This should be a number high enough to accommodate your largest jobs, but no larger than necessary to prevent accidental huge jobs from going through the system and affecting system performance.

Min Pixels sets the minimum width and height dimension when images are sent through CirrusPrint.  The main purpose of this setting is to prevent logos and other small images found in emails from being delivered to devices.

Port Range is a range of TCP network ports that can be used when auto-generating network port types of input sources.  If an input source of that type is created and no port is manually assigned, a new port is taken from this range.  A similar setting is available in company settings and those settings take precedence over these if defined.

Web Server Settings

External URL defines an external URL, such as "https://printing.example.com", that is used when sending links to the server by email, such as for deployment links or password resets.  The server is often accessed by local network address when being administered, but remote users must access it via a public address.  This setting provides that address.

Portal Menu Redirect defines an external URL that the main menu portal will redirect users to.  Use this if you do not want anonymous users to access the portal menu.  Instead, when they browse to that page the system will redirect their browser to the URL you specify, for example your home page or another information page.  This value must be a full URL, starting with http or https.

Once this is active, access to other portions of the server must be specified with full URL paths, as described in the Browser Interface chapter.

HTTP Port sets the port for access using http URLs (as opposed to https).  This can be 80, the default http port, or another port if port 80 is in use by another web server.  The default alternate port is 27082.

HTTP Allow is a space-separated list of IP addresses or CIDR network specifications that are allowed to connect to the http port.  It defaults to local network addresses: 127.0.0.1 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16.  Note that 127.0.0.1 is always allowed access.  If empty, or it includes the word "any", all connections are allowed.  Note that your firewall still must allow connections to the port.

HTTPS Port sets the port for access using https URLs (as opposed to http).  This can be 443, the default http port, or another port if port 443 is in use by another web server.  The default alternate port is 27083.

HTTPS Allow is a space-separated list of IP addresses or CIDR network specifications that are allowed to connect to the https port.

Local Cert File Path is a path to a public SSL certificate file for the hostname or hostnames used to connect to the server.

Local Key File Path is a path to a public SSL key file for the hostname or hostnames used to connect to the server.

Global Cert File Path is a path to a public SSL certificate file for the hostname or hostnames used to connect to the server.

Global Key File Path is a path to a public SSL key file for the hostname or hostnames used to connect to the server.

The local certificate and key paths are stored and used by the current server only.  You must be connected to the server you want these applied to.  The global certificate and key paths are stored in the global configuration that applies to all systems using the same data path, and should support all domain names that all those systems support.  The local files are used in preference to the global files, if supplied.

If neither is not supplied, a default self-signed certificate is used, which will cause browsers to warn of insecure connections.

If you have configured high availability, be sure when you modify the web server configuration that you do so when accessing the desired machine directly rather than through a proxy server or multi-homed hostname, to ensure the correct machine receives the configuration change request.

Password Strength is a setting that enables enforcement of password strength for site users and locations.  The default setting is Unenforced, meaning the administrator can assign any password.  That may be suitable for local deployments.  Other settings are Moderate and Strong, which differ in the minimum length of password (8 and 14 respectively), both requiring at least one each of uppercase, lowercase, digit, and these special characters:! @ # $ % ^ & * ( ) - + = , . : ; /.

Email Receiving Settings

SMTPD Port, if not 0, will enable a site-wide SMTP server to receive email to the configured devices of any company that has its Enable SMTP Receiving checked.  If th server's https SSL certificate files are configured, the SMTP server will support STARTTLS for encryption.  Most email servers that would deliver to this site will either attempt or require STARTTLS to improve email security. Further notes:

•External mail servers will not deliver mail to an IP address, so you must have a domain name configured for the CirrusPrint server.  This domain must be specifically for the the CirrusPrint server to avoid normal email from getting sent to CirrusPrint and lost.  It is often a subdomain of an entity, like print.example.com.
 

•External mail servers will be connecting to port 25, so that should be the port configured for CirrusPrint.  That port must be open to any mail server that might send mail to CirrusPrint.  It is easiest to allow any system access, and rely on the other security features described below to prevent unwanted jobs from being processed, but if you know of specific addresses or CIDR ranges to allow, your firewall can be set up to restrict access to them.

Once enabled here and in a company, emails can be sent to one of two email addresses targeting any output device:

•compid.locid.devid@example.com

•locid.devid@compid.example.com

Companies can be further configured with allow-lists and subject authorization tags.

If you have configured high availability, be sure when you modify the email receiving server configuration that you do so when accessing the desired machine directly rather than through a proxy server or multi-homed hostname, to ensure the correct machine receives the configuration change request.

Jobs started by the email receiver have the following automatically defined properties:

•basename - the name of the attachment without an extension

•ext - the attachment file extension

•filename - the attachment file name

•from - the email from address

•replyto - the email reply-to address if present

•srcid - @smtp

•subject - the email subject

•title - the attachment file name

•to - the email to address

Email Receiving Security

Users can be rightly concerned about opening port 25 to external access, as email is a common vector for attacks on systems.  However, the CirrusPrint SMTP server is very different than a standard mail server.  CirrusPrint is simply using the SMTP protocol as an inbound delivery mechanism.  It is actually more secure than setting up an IMAP account, which could expose any user who has account access to spam, phishing, or other attacks.  Further, since the IMAP account must be dedicated for CirrusPrint's use, users who have access are typically admin users with elevated security credentials that present a larger risk to the enterprise.

Here are notes about security regarding the internal mail server:

•It is a receive-only server which cannot forward or relay mail it receives

•It cannot be used to send email, so no user or system can connect to it to send mail

•It doesn't maintain mailboxes to retain email - once processed, messages are discarded

•Only mail attachments are used, and you can limit what types of files are accepted

•The mail body, where links and phishing text might appear, is discarded and is never seen by a user

•You can define valid Subject values, and those that don't match are discarded

•You can define valid From addresses or domains, and those that don't match are discarded

•Only mail to known address formats shown above is accepted, with other To addresses being discarded

Email Sending Settings

When CirrusPrint needs to send an email, such as for deployment letters or multi-factor authentication, it will send email using a mail server configured here.  Companies can also be configured with these same settings, for use when company-specific emails are sent.

SMTP Server names the mail server to connect to when sending emails.  The server may contain a "ssl:" prefix to indicate the server uses SMTPS.  It may also contain a :port suffix if the server's port is not 587 for SMTP or 465 for SMTPS.  Many private mail servers use port 25, for example.  To enable support for unverified SSL/STARTTLS certificates, such as self-signed certificates on the mail server, add a "!" prefix in front of the full server specification, such as "!ssl:mail.example.com:465".

Note that STARTTLS and SMTPS are different protocols.  SMTPS begins with an encrypted connection, similar to how https works.  STARTTLS starts with an unencrypted connection, then if the server requests it, the connection is upgraded to a secure one via the STARTTLS protocol.

From Address is the address that will appear in the From header of the email.

Notify Address is used when sending automatic notifications.

Login and Password must be filled in if the mail server requires authentication.

OAuth Token Request Data

If the mail server requires OAuth2 authentication instead of simple password authentication,  you can configure that with text values returned by the registration procedure at https://cirrusprint.com/support/oauthcode.html.  After registering an application with your mail provider, such as the App Registration pages at Microsoft 365's Azure Active Directory, you can visit the above web page to configure, authorize, and receive the tokens required for CirrusPrint to perform this type of authentication.  Instructions are found at that page.

Once the token request data is returned, copy and paste into this field.  If the mail server requests this type of authentication, these settings are used rather than a standard password-based login.

Be sure the Login value is the same one you authorized while on the above page.  The token request data should look something like this (lines here are truncated):

cid=2991095c-2b2a-4...

cs=Z2F8Q~5dZSM4v...

ep=https://login.microsoftonline.com/ab44...

tk=LCJhbGciOiJSUzI1NiIsIng1dCI6ImpT...

rf=0.ARIAlplEqxeM...

Test SMTP Settings can be clicked to send a test email using the email settings above.

SendGrid API Key is used in preference to an email server when sending email.  SendGrid is a commercial email service provider that offers an API for high performance emailing.  You can use this service to avoid impacting a standard email server.

Test SendGrid API Key can be clicked to send a test email using SendGrid's API.

Logging Levels

Standard logging levels write log records for system and job events.  Further logging can be enabled with these checkboxes.

•Detailed logging for the service

•Detailed logging for http requests

•Detailed logging for api request, both http and command line

Further logging can be enabled by manually editing the config.ini file, setting debug=1 in [settings], or api=2 in [logs].

Site API Key

The Site API Key is a randomly generated value that can be used to authenticate API operations.  It is treated like a password, visible only upon clicking the Show Key button, which will allow copy and pasting into software code that uses the API.

If this value must be reset, click the Reset Key button and affirm the selection, then save the record to generate a new API key.  This new key must then be used for API access.