Troubleshoot PSSP connections

Use this guide when a client cannot connect, authenticate, subscribe, publish, bind UDP, or resume data. Work from top to bottom: a credential change cannot fix a broker that is not listening, and an ACL change cannot fix a failed login.

If the shell cannot find pssp-broker

The executable is not automatically installed into PATH by checking out this repository. Its source is in broker/; local builds are written to target/debug/pssp-broker or target/release/pssp-broker (with .exe on Windows). From the repository root, either run it through Cargo or use the built path directly:

cargo run -p pssp-broker -- --help
./target/debug/pssp-broker --help                 # macOS/Linux
.\target\debug\pssp-broker.exe --help             # Windows PowerShell

Use this diagnostic order

1. Start the Broker. Confirm that it remains running instead of exiting with a configuration, certificate, key, or database error.
2. Confirm TCP reachability. Verify the expected process is listening on TCP port 6688 and that the client can reach that host and port.
3. Match the security mode. TLS, PSSP AES, the TLS checkbox, certificate trust, and the AES-only public-key pin must agree.
4. Verify authentication. The exact clientId + username record must exist, be enabled, and match the current password.
5. Verify authorization. A successful login does not grant publish or subscribe access. Check the principal's topic ACLs.
6. Test data flow. Test TCP ping, subscribe/publish, UDP bind/ping, then replay and retention behaviour.

Case study: pssp-admin / admin could not connect

The following issues were found while investigating a client using client ID pssp-admin, username admin, and a supplied password. They are documented here because the same combination of failures is easy to reproduce during development.

Start the desktop client correctly

1. Install dependencies once.

   cd client
   npm install

2. Start the Tauri application, including its Rust backend.

   npm run tauri:dev

3. Do not use npm run dev as the complete client. That command starts only the Vite web interface; native Tauri commands such as connect require the desktop runtime.

If the application does not build, confirm Node.js 20+, a current Rust toolchain, and the operating-system packages required by Tauri 2. Build the Rust workspace separately to expose backend compiler errors:

cargo check --workspace

Confirm that the Broker is running and listening

Development start

cargo run -p pssp-broker -- serve \
  --config broker/config/pssp.example.toml

Keep the terminal open and read the first error. A healthy startup logs TCP and UDP listener addresses and the selected TLS/AES mode.

Listener checks

If the Broker listens on 127.0.0.1, only local clients can connect. Use an appropriate interface such as 0.0.0.0:6688 only when firewall policy restricts access to approved networks. Confirm that another process is not already using the port.

Service checks

Initialize SQLite and fix ownership safely

The Broker will not start against an absent, uninitialized, or unreadable database. SQLite stores principals, Argon2id password hashes, enabled state, ACLs, and credential audit events. Topic payloads and session state remain in memory.

1. Open the active TOML config and verify storage.sqlite_path. Do not diagnose one config and start the Broker with another.
2. Choose the identity that will run the Broker service. On Unix, set both storage.unix_owner_user and storage.unix_owner_group to that existing service account, or omit both for a user-owned development database. The two settings must be supplied together.
3. Initialize the schema and bootstrap administrator with that same config. The command creates missing parent directories and the SQLite file, securely prompts for a password of at least 12 characters, and on Unix restricts the database and existing sidecars to 0600. When the Unix owner pair is configured, it also restricts the parent directory to 0700 and applies the configured ownership; run setup as root or as that service identity so those changes are permitted.

   pssp-broker setup --config /etc/pssp/pssp.toml \
     --bootstrap-client-id pssp-admin \
     --bootstrap-username admin

4. Verify metadata without exposing password hashes.

   pssp-broker list-principals --config /etc/pssp/pssp.toml
   pssp-broker list-acls --config /etc/pssp/pssp.toml \
     --client-id pssp-admin --username admin

5. Start the service under the same identity and confirm the listener.

Filesystem access and topic grants are different

Run every principal and ACL command with the same --config used by serve. Mutating CLI commands preserve the configured Unix owner and secure modes; manually changing a file to be world-readable or world-writable grants no PSSP topic access.

Local repository alternative

For local development, use broker/config/pssp.example.toml. Run these commands from the repository root; the configured relative path then creates data/pssp-broker.sqlite3 inside the workspace and avoids mixing an installed-service database with a user-run Broker:

cargo run -p pssp-broker -- setup \
  --config broker/config/pssp.example.toml \
  --bootstrap-client-id pssp-admin --bootstrap-username admin

cargo run -p pssp-broker -- serve \
  --config broker/config/pssp.example.toml

Resolve authentication_failed

The wire login contains three independent values: clientId, username, and password. The first two select one exact SQLite record; the third is checked against its Argon2id hash.

1. List principals and confirm the exact spelling, case, and enabled state.

   pssp-broker list-principals --config /etc/pssp/pssp.toml

2. If the password is unknown, rotate it; it cannot be recovered from the hash.

   pssp-broker rotate-password --config /etc/pssp/pssp.toml \
     --client-id pssp-admin --username admin

3. Enable a disabled principal.

   pssp-broker set-principal-enabled --config /etc/pssp/pssp.toml \
     --client-id pssp-admin --username admin --enabled

4. Wait for storage.auth_cache_seconds—30 seconds by default—or restart the Broker before retesting a recently failed or changed credential.
5. Enter the values without leading/trailing spaces. The client sends the values as entered; it does not create accounts or substitute a default password.

Set up an AES-only connection step by step

AES-only means TLS is disabled while PSSP AES-256-GCM is enabled. The Broker has a long-lived X25519 identity key; every session derives a fresh AES key using the pinned Broker public key, an ephemeral client key, and HKDF-SHA-256. The AES session key is never transmitted.

1. Copy the AES-only template to the protected deployment config.

   cp broker/config/pssp.aes-only.example.toml /etc/pssp/pssp.toml

2. Generate a random private key and save it in a protected operator-only location.

   umask 077
   pssp-broker generate-aes-only-private-key \
     > /etc/pssp/aes-only-private-key

3. Copy that generated value into encryption.static_private_key in /etc/pssp/pssp.toml. Do not use AAAAAAAA...AAA; it is only a format example.
4. Derive the public key that clients must pin.

   pssp-broker aes-only-public-key \
     --private-key-file /etc/pssp/aes-only-private-key

5. Confirm the security configuration.

   [tls]
   enabled = false
   
   [encryption]
   enabled = true
   static_private_key = "GENERATED_PRIVATE_KEY"
   
   [transport]
   allow_insecure_tcp_udp = false

6. Initialize SQLite with this exact config, then start the Broker.

   pssp-broker setup --config /etc/pssp/pssp.toml \
     --bootstrap-client-id pssp-admin --bootstrap-username admin
   pssp-broker serve --config /etc/pssp/pssp.toml

7. In the desktop client, set the Broker host and port, leave TLS 1.3 transport off, paste the derived public key into Broker AES-only X25519 public key, enter the exact credentials, and select Connect.
8. Verify that the client reports AES session: active. Then test TCP Ping, subscribe/publish, Bind UDP, and UDP Ping.

Set up TLS + AES

1. Start from broker/config/pssp.production.example.toml.
2. Install a TLS certificate and private key readable by the Broker service identity. The certificate must include the DNS name clients use.
3. Configure both layers.

   [tls]
   enabled = true
   certificate_file = "/etc/pssp/tls/fullchain.pem"
   private_key_file = "/etc/pssp/tls/privkey.pem"
   
   [encryption]
   enabled = true
   
   [transport]
   allow_insecure_tcp_udp = false

4. Initialize SQLite, start the Broker, and confirm it logs tls=true and encryption=true.
5. In the client, connect using the certificate's DNS hostname and turn TLS 1.3 transport on. The AES-only public-key field is not used.

A TLS handshake error normally means the TLS checkbox does not match the Broker, the certificate is expired or untrusted, the hostname does not match, or an intermediate certificate is missing. Connecting by IP address will fail unless that IP address is present in the certificate's Subject Alternative Name.

Use plaintext only for isolated local testing

[tls]
enabled = false

[encryption]
enabled = false

[transport]
allow_insecure_tcp_udp = true

Leave the client's TLS checkbox off and leave the AES-only pin empty. The Broker intentionally rejects a no-TLS/no-AES configuration unless allow_insecure_tcp_udp = true; it also rejects that opt-in when either TLS or AES is enabled.

Fix publish and subscribe authorization

Authentication and authorization are separate. A principal can log in successfully while having no ACLs.

pssp-broker list-acls --config /etc/pssp/pssp.toml \
  --client-id pssp-admin --username admin

Grant an administrator test account access to all topics:

pssp-broker grant-acl --config /etc/pssp/pssp.toml \
  --client-id pssp-admin --username admin \
  --action publish --topic-filter '#'

pssp-broker grant-acl --config /etc/pssp/pssp.toml \
  --client-id pssp-admin --username admin \
  --action subscribe --topic-filter '#'

Fix UDP bind and ping failures

1. Complete the authenticated TCP connection first. UDP is associated with a live TCP session.
2. Select Bind UDP before UDP Ping.
3. Keep the TCP connection open; closing it invalidates the UDP token, AES material, and endpoint association.
4. Allow UDP port 6688 through the host firewall, cloud firewall, VPN policy, NAT, and container/VM forwarding.
5. Confirm TCP and UDP point to the same Broker host and configured port.
6. If TCP works but UDP times out, capture Broker logs while binding. A network policy can permit TCP while silently dropping UDP.

UDP is QoS 0: it has no replay, receipt guarantee, or retry. A lost heartbeat is not proof that the TCP session is dead; use TCP Ping to test the reliable control path.

Replay, GAP, disconnects, and slow clients

Common error and symptom reference

Collect a useful troubleshooting report

Before asking another developer for help, record the following without including passwords, private keys, raw session keys, or sensitive payloads:

• Operating system and whether the Broker is run from Cargo, systemd, launchd, or Task Scheduler.
• Broker and client versions or commit ID.
• Host and port, with private addresses redacted if necessary.
• Selected mode: TLS + AES, AES-only, or intentional plaintext.
• The exact displayed client error and the matching Broker log lines.
• Whether TCP 6688 is listening and remotely reachable.
• The configured SQLite path and its owner/mode—never the database contents or password hashes.
• Output of list-principals and relevant list-acls; these commands intentionally omit hashes.
• Whether the problem affects TCP connection, authentication, ACL, TCP data, UDP, or replay.

See the Broker guide for deployment and account administration, the client guide for UI operation, and the protocol reference for record-level behaviour. · Proprietary — © 2026 OX Recorder · License information