Skip to content

Multiple Instances

Jump to bottom
Tres Finocchiaro edited this page Oct 21, 2024 · 12 revisions

Compatibility

  • ✅ 2.2 | ✅ 2.1* | ⛔ 2.0 | ⛔ 1.9 | ...

Objective

Explain the caveats and workarounds to running QZ Tray on a multi-user workstation.

Singleton

QZ Tray is a singleton application and it cannot support multiple simultaneous instances on the same machine because QZ Tray uses a localhost websocket connection (wss://) from the browser to a single port on the PC. If a second instance of QZ Tray were allowed, the websocket would only ever succeed to the first available port, rendering the second instance useless.

Some options to help with this limitation:

  • If your environment requires multiple users using QZ Tray simultaneously, consider setting up a dedicated Print Server for this.
  • If your environment is happy having a service account run the software, try to start QZ Tray as a persistent user on that machine. Note: The printers available will those available or assigned to the service account.
  • If it's suitable for ANY user to be running QZ Tray, consider globally-allowing the certificate.
  • If your environment only requires one user using QZ Tray at a time, see Stealing Instance below.

Symptoms

Since QZ Tray will start automatically with the computer, this singleton limitation can pose a problem on a shared workstation. By default, QZ Tray will attempt to start automatically upon login however if another user is running QZ Tray, it will detect the other instance and quietly shutdown. This is usually observed by the following behavior:

"QZ Tray icon disappears from the system tray"

"When I double-click on the QZ Tray icon, it shows up for a second and then goes away"

"There's link on the web page to start QZ Tray (e.g. qz:launch but it doesn't work if someone else is signed onto the computer"

Stealing Instance

Since 2.1.4, QZ Tray supports stealing another instance, which can be helpful on shared workstations. There are several ways to toggle this behavior on:

  • Administrators can set an environment variable called QZ_OPTS to -DstealWebsocket=true.
    -- OR --
  • Administrators can edit qz-tray.properties and add a line websocket.steal=true. This file can be found by clicking QZ Tray, Advanced, Diagnostic, Browse App folder (secure environments may store this file in the User or Shared folder) 
    #Sat Jan 1 00:00:00 BOT 2022
websocket.steal=true # <--------- Steal Websocket
wss.host=0.0.0.0
wss.alias=qz-tray
ca.alias=root-ca
ca.storepass=a1b2c3d4
wss.storepass=a1b2c3d4
ca.keystore=root-ca.p12
wss.keystore=qz-tray.p12
networking.hostname=yahoo.com
    -- OR --
  • Administrators can start QZ Tray with the command-line flag --steal
    -- OR --
  • Web developers can start QZ Tray with the hyperlink qz:steal (instead of qz:launch)
    • Note: qz:steal is NOT currently supported on Mac, please use the properties or environmental technique instead.
  • In a multi-user environment, client environments can choose to detect the user login event and steal the QZ instance. Examples provided here:
Clone this wiki locally