Documentation

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

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

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.

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"

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:
  • Batch: start_if_active.bat
  • PowerShell: start_if_active.bat.ps1