Documentation
Print Server
- ✅ 2.2 | ✅ 2.1 | ✅ 2.0 | ✅ 1.9 | ...
- Run QZ Tray as a dedicated service, useful for machines that cannot have QZ Tray installed (such as a Terminal Services/Citrix environment and mobile/sandboxed devices such as iOS, Android, ChromeOS).
Note: If you're looking for step-by-step instructions for installing QZ Tray as a Windows service, please see this tutorial instead.
The steps will be the same for each platform, however, the way you regenerate the certificate and install it on the client will vary.
- Install QZ Tray
- Connect to QZ Tray
- Remove localhost Bindings
- Copy Files to the Client
- Install the new certificate on the client
- Import Firefox Certificates
- Verify secure connection
Install QZ Tray onto the server via the desktop installer. Refer to this guide if unsure how to do this.
By default, the qz.websocket.connect();
functions are bound to localhost
. This can be overridden.
Note:
foo.bar
is the hostname of the server.
-
Replace all calls to
qz.websocket.connect();
withqz.websocket.connect({host: "foo.bar"});
//qz.websocket.connect(); qz.websocket.connect({host: "192.168.1.2"});
Deprecated
-
Replace all calls to
deployQZ
withdeployQZ("foo.bar");
//deployQZ(); deployQZ("192.168.1.2");
That's it! At this point, an HTTP connection can be made from a client to the server running QZ Tray. The steps below illustrate how to establish an HTTPS connection.
-
Organizations wishing to use a 3rd-party Trusted CA SSL certificate can do so by manually shimming it into the software. If you do not have or do not wish to use a CA certificate, please see remove localhost bindings section instead.
java -jar qz-tray.jar certgen --key "privkey.pem" --cert "fullchain.pem" # or for a pfx/pkcs#12 file java -jar qz-tray.jar certgen --pfx "mycert.pfx" --pass "12345" # ... or for 2.0 please see https://github.com/qzind/tray/pull/89
HTTPS: The steps provided in this section illustrate how to create a self-signed certificate for a secure (HTTPS) connection. These steps are not needed for connections made via HTTP or connections that use a 3rd-party Trusted CA Certificate file.
For secure websockets support (HTTPS), QZ Tray generates a certificate for localhost
traffic at install time called root-ca.crt
. In order for QZ Tray to run on a separate machine, the hostname
(usually "localhost") must exist in the certificate. This is an override which is done by running a custom script.
-
Re-run the certificate generation (
"foo.bar"
is the hostname that QZ Tray will run on). If you require Firefox HTTPS support, Firefox needs to be installed prior to this step.- This will re-generate the
qz-tray.properties
,root-ca.crt
andqz-tray.jks
Open a command prompt as an administrator and run the following commands:
REM Regenerate the certificate cd "%PROGRAMFILES%\QZ Tray\" qz-tray-console.exe certgen --host "192.168.1.5" REM -- OR -- qz-tray-console.exe certgen --hosts "domain1;domain2;..."
REM Regenerate the certificate cd "%PROGRAMFILES%\QZ Tray\" java -jar qz-tray.jar certgen --host "192.168.1.5" REM -- OR -- java -jar qz-tray.jar certgen --hosts "domain1;domain2;..."
*Since 2.1.0-RC9
REM Regenerate the certificate cd "%PROGRAMFILES%\QZ Tray\" cscript auth\windows-keygen.js . install "foo.bar"
# Regenerate the certificate sudo /opt/qz-tray/qz-tray certgen --host "192.168.1.5" # -- OR -- sudo /opt/qz-tray/qz-tray certgen --hosts "domain1;domain2;..."
# Regenerate the certificate cd /opt/qz-tray sudo java -jar qz-tray.jar certgen --host "192.168.1.5" # -- OR -- sudo java -jar qz-tray.jar certgen --hosts "domain1;domain2;..."
*Since 2.1.0-RC9
# Reinstall completely with specified hostname sudo bash qz-tray-2.0.x.run -- -y "foo.bar"
# Regenerate the certificate sudo "/Applications/QZ Tray.app/Contents/MacOS/QZ Tray" certgen --host "192.168.1.5" # -- OR -- sudo "/Applications/QZ Tray.app/Contents/MacOS/QZ Tray" certgen --hosts "domain1;domain2;..."
# Regenerate the certificate cd "/Applications/QZ Tray.app/" sudo java -jar qz-tray.jar certgen --host "192.168.1.5" # -- OR -- sudo java -jar qz-tray.jar certgen --hosts "domain1;domain2;..."
*Since 2.1.0-RC9
# Regenerate the certificate sudo /Applications/QZ\ Tray.app/auth/apple-keygen.sh install "foo.bar" # Optionally, regenerate the Firefox configuration files sudo /Applications/QZ\ Tray.app/auth/firefox/firefox-cert.sh install "foo.bar"
- This will re-generate the
-
Relaunch QZ Tray. This must be done every time you regenerate a certificate.
Note: Alternatively, you may provide an custom
.properties
file directly to Java using-DsslPropertiesFile=path/to/my.properties
.
-
For iOS (iPad, iPhone), skip to the iOS section below
-
Copy
root-ca.crt
from the server's QZ Tray shared directory to the clientThis is in Advanced, Troubleshooting, Browse Shared Folder.
-
Optional: Copy the
demo
folder for testing (located inQZ Tray\demo
) from QZ Tray to the client. -
Optionally, if Firefox support is needed, enable the Enterprise Roots policy
Note: If unsure of the location of these files on your system install QZ Tray on a test system and search for them by name. They are both created by QZ Tray and can safely be overwritten.
The rest of the steps must be completed on the client
Certificate installation varies between browsers and platforms. Distributing a certificate marked for a custom hostname is a manual process which must be done on all workstations requiring HTTPS + QZ Tray.
-
Double click
root-ca.crt
-
Click Install Certificate
-
Local Machine, Next
-
Choose "Trust Root Certificate Authorities" and hit Next
-
Click Finish. If successful, the following screen will appear:
-
Run the following command to install the certificate
certutil -d sql:$HOME/.pki/nssdb -A -t TC -n "QZ Industries, LLC" -i /path/to/root-ca.crt
-
As of 2.0.9
root-ca.crt
is automatically hosted on the about status page of QZ Tray-
To access the about page, navigate (in Safari) to the printer server on port 8182 (e.g. http://foobar:8182/)
⚠️ Warning: A bug with 2.1.0 prevents theroot-ca
Download from working properly on iOS and manual installation (e.g. email) is needed instead. This is fixed in 2.1.1. -
Under the SSL section, click the "Download certificate" with the alias of the newly created certificate.
-
-
If you are not running QZ Tray 2.0.9 +, you will need to host the
root-ca.crt
somewhere so you can download it from the web (e.g. temporarily on a webpage, Google drive, etc.). The about page will not have the certificate to download. -
Use Safari to download the
root-ca.crt
. Safari will automatically prompt the installation of the certificate. Chrome and other browsers will not. When Prompted, select "Allow" -
The profile installer screen should automatically appear. Select "Install"
-
Next, go to Settings > General > About > Certificate Trust Settings. The newly installed certificate should appear. Toggle to enable full trust for root certificates
- As of the publication of this section of the tutorial (April 2, 2021), Android must have a server-side modification for the IP address of the local print-server:
qz.websocket.connect({ host: 'IPv4.ADDRESS.OF.LAN-PRINT-SERVER', usingSecure: false });
- Next, the client (tablet, smart phone) must make an exception in Chrome to allow insecure traffic from this particular address.
- Open Chrome on the smart device, and navigate to:
chrome://flags/#unsafely-treat-insecure-origin-as-secure
-
From here, ENABLE the ability to use this feature, and add ws://IPv4.ADDRESS.OF.LAN-PRINT-SERVER:8182 (8182 is our first default for ws://) to the exception list
-
You should then be able to navigate to that page from your Android Chrome browser:
- Install the certificate to the OS per above instructions
- Navigate to
about:config
- Search for
security.enterprise_roots.enabled
, change the value totrue
.
- Use the
Certificates > Install
directive usingpolicies.json
as described here: https://github.com/mozilla/policy-templates/blob/master/README.md#policiesjson-9
Legacy Firefox Versions
Firefox does not allow self-signed certificates to be imported directly, instead a manual import process is needed.
-
Overlay the existing Firefox files with the ones transferred over from the server.
defaults/pref/firefox-prefs.js firefox-config.cfg
-
Again, these may be located in
C:\Program Files (x86)\Mozilla Firefox\
-
Open
sample.html
in a browser -
Right Click, Inspect Element on the sample page
-
Click the Console tab
-
Verify the secure websocket connection to 8181 succeeds. If a connection is made on a different port, reference the table below
Secure (HTTPS) Insecure (HTTP) 8181 8182 8282 8283 8383 8384 8484 8485 Note: If HTTPS still fails, or you are experiencing long timeouts before a connection is made, a firewall may be blocking the connection. Try disabling the firewall, or allowing the port on the server.