Server Connections

HZN Queue Console lets you connect to multiple brokers simultaneously and switch between them instantly. Each connection is stored locally — credentials are kept in your OS keychain, never in plain text.

Adding a Server

Click Add Server (or the + icon in the server panel) to open the connection dialog.

Required fields

Optional fields

What the dialog checks

The dialog validates the settings as you type and shows the two URLs it will build from them — the management API URL and the Spy Mode target — so a wrong port or a stray path is visible before anything is sent.

• Red entries block saving: a missing scheme, a port typed into the hostname, an amqp:// URL, credentials in the URL, an API path that the app appends itself, or an AMQP port equal to the management port.
• Amber entries are saved but flag a likely mistake: the AMQP port used as the management port, a scheme and port that disagree about TLS, guest on a remote RabbitMQ, or a production broker reached over plain http://.
• Most entries come with a one-click correction.

Brokers published only on 443

Many brokers are reachable from a workstation only as https://myserver/ — a reverse proxy on 443, no port in the URL, and the broker’s own management port (15672) closed to the outside. Hosted services such as CloudAMQP work this way, and it is the most common reason a connection test times out.

The dialog flags it: entering a DNS hostname with the broker’s default port produces “A remote broker rarely exposes 15672 — 443 is far more likely”, with a one-click Use https + 443 correction. The rule of thumb: if the management UI opens in a browser as https://myserver/ without a port, the console needs https://myserver and port 443.

Fill the dialog in like this:

The management API works straight away: the app requests https://myserver:443/api/overview through the proxy.

The AMQP port does not follow the hostname. Spy Mode needs a real AMQP connection, so it dials myserver:<AMQP port> directly — the proxy is not involved. Three cases:

1. AMQP on its own port — the usual case. Enter 5672, or the port your platform team gives you. A management API on 443 does not move the AMQP listener; it stays where the broker put it.
2. Everything tunnelled through 443. Where only 443 is open outbound, a site may publish AMQP on 443 as well — the proxy tells HTTPS and AMQP apart during the TLS handshake (ALPN/SNI), so one port serves both. Entering 443 here is valid, and the dialog accepts it even when it equals the management port. It only reaches the broker if that front door terminates TLS and forwards plain AMQP: Spy Mode does not negotiate TLS, so an AMQPS endpoint fails the handshake.
3. AMQPS on 5671. Not supported by Spy Mode for the same reason — ask for the plaintext port.

Everything except Spy Mode and AsyncAPI recording keeps working regardless of what you put here, so a broker whose AMQP port is unreachable is still fully usable for browsing, publishing, search and export. If the port is not reachable from your machine, clear the field: the console then reports Spy Mode as off — in the dialog, in the connection test and on the Spy Mode button — instead of dialling a port that is not there.

Testing the Connection

Click Test Connection before saving. It reports two independent verdicts, because the two ports are two independent listeners:

A failed test names the cause (wrong port, auth failure, DNS, TLS, firewall) and suggests what to change. The AMQP verdict distinguishes not reachable — nothing answered on that port — from refused, where the listener answered but rejected the credentials or the vhost; the second is a permissions problem, not a connectivity one.

A failing — or unset — AMQP port only disables Spy Mode and AsyncAPI recording. Browsing, publishing, search, export and monitoring all run over the management API and are unaffected, so the server is still worth saving. With no AMQP port, the Spy Mode button on a queue says why it cannot start.

Findings appear when you ask for them

The dialog does not flag anything while you type — a half-written hostname is not a mistake yet. Pressing Test connection or Add server / Save changes runs the checks and shows what it found; from then on the list updates live, so corrections are seen to land. Neither button is ever disabled: pressing them is how you ask what is wrong.

Broker Types

RabbitMQ 3.x / 4.x

Connects via the RabbitMQ Management HTTP API. Requires the rabbitmq_management plugin to be enabled:

rabbitmq-plugins enable rabbitmq_management

Default management port: 15672.

ActiveMQ Classic 5.x

Connects via the ActiveMQ Web Console REST API. The Jolokia endpoint must be reachable.

Default management port: 8161.

ActiveMQ Artemis 2.x

Connects via the Artemis Management Console REST API.

Default management port: 8161.

Exporting and Importing Servers

Passwords live in your OS keychain, so copying servers.json to another machine leaves the credentials behind. Export servers is the way to move a set of connections — credentials included — from one installation to another.

Both actions are in the ⋮ menu at the top of the server panel.

Exporting

1. File name — prefilled with hzn-queue-console-servers-<date>.json. Change it to whatever names the set: brokers-new-laptop, prod-only. The .json suffix is added if you leave it off, and characters a filesystem would refuse are replaced.
2. Tick the servers to include. Everything is ticked to begin with.
3. Include passwords — on by default. Turn it off to share connection settings without the credentials; the importing side then keeps whatever passwords it already has.
4. Encrypt the file with a secret — on by default. The payload is sealed with AES-256-GCM under a key derived from your secret (PBKDF2-HMAC-SHA256, 210,000 iterations). The salt, IV and iteration count travel in the file; the secret does not.
5. Export writes the file to your downloads.

An unencrypted export that includes passwords contains them in plain text, and the dialog says so in as many words. Treat that file exactly as you would treat the passwords themselves.

There is no recovery path for a lost secret — the file cannot be opened without it.

Importing

1. Drop the file on the dialog, or browse for it.
2. If the file is encrypted, enter its secret. A wrong secret and a damaged file are indistinguishable, and both are reported the same way.
3. Tick the servers to import. Each row says what it will do: New, or Overwrites <name>.
4. Import applies only the ticked entries.

An imported server replaces the one it matches, credentials included, and that cannot be undone. Matching is by id first, then by name — so a server exported from another machine still lands on the one you recognise here, even though the two installations gave it different ids. A match keeps the existing id, which is what favourites, panel ordering and the active-server selection are stored against; re-importing therefore leaves all three intact.

An entry with no password never clears a stored one: servers that already exist here keep the password they have, and new ones simply arrive without one.

Neither action is available in the live demo.

Switching Between Servers

Click any server in the left panel to make it active. All views (queue list, message browser) update immediately to reflect the selected broker.

Editing and Deleting

Right-click a server in the panel (or click the … menu) to rename, edit credentials, or delete it. Deleting also removes the stored credentials from the OS keychain.

Security

Passwords are never written to disk in plain text. On macOS they go to Keychain, on Windows to the Windows Credential Manager, and on Linux to the secret service (Libsecret / KWallet).