quinzee.cloud

Development edition · 16 November 2026. Commands using repository paths, Make targets or sample projects require access to the Quinzee source checkout. No public installer is available. Examples use disposable local environments.

Contributor’s guide

20. Inspect a disposable instance from Linux

This exercise starts a separate native cloud, observes its Unix boundaries and stops only that instance. It uses no Docker services and changes no host DNS or trust store. Complete a native debug build first. You need Bash, Python 3, OpenSSL, curl and ordinary Linux procps/coreutils tools. ss, strace and inotifywait are optional diagnostics; absence of a tool is not a failed service.

Step 1: start a private HTTPS lab

Run the following in a dedicated Bash terminal from the repository root. Keep this terminal open for the remaining steps. The temporary path is printed; substitute your actual path/PID in another terminal when necessary.

umask 077
lab=$(mktemp -d /tmp/quinzee-internals.XXXXXX)
port=$(python3 - <<'PY'
import socket
with socket.socket() as sock:
    sock.bind(('127.0.0.1', 0))
    print(sock.getsockname()[1])
PY
)
openssl req -x509 -newkey rsa:2048 -nodes -days 1 \
  -keyout "$lab/server.key" -out "$lab/server.crt" \
  -subj '/CN=localhost' \
  -addext 'subjectAltName=DNS:localhost,IP:127.0.0.1' \
  -addext 'basicConstraints=critical,CA:TRUE' \
  >"$lab/certificate.log" 2>&1
bin/debug/quinzee.cloud --address 127.0.0.1 --port "$port" \
  --tls-cert "$lab/server.crt" --tls-key "$lab/server.key" \
  --ca-cert "$lab/server.crt" --data-dir "$lab/data" \
  --modules identity,resource_manager,storage \
  >"$lab/cloud.log" 2>&1 &
cloud_pid=$!
trap 'kill -TERM "$cloud_pid" 2>/dev/null || true; wait "$cloud_pid" 2>/dev/null || true' EXIT
printf 'Lab directory: %s\nCloud PID: %s\nHTTPS port: %s\n' "$lab" "$cloud_pid" "$port"

The temporary certificate is trusted only by commands explicitly given that file. It is a disposable test certificate, not a new machine-wide root. The port selection has a small bind/rebind race; if another process takes it, this cloud fails startup. Inspect this lab's log and retry with a new lab rather than killing the other listener. Only the selected modules and their required dependencies load; no AMQP, LDAP, DNS server or external runtime starts in this exercise.

Step 2: prove the process and endpoint agree

Allow a few seconds for startup, then run in the same terminal:

ps -p "$cloud_pid" -o pid,ppid,user,stat,comm
ps -L -p "$cloud_pid" -o tid,stat,wchan:28,comm
curl --fail --silent --show-error --cacert "$lab/server.crt" \
  "https://localhost:$port/health"
stat -c '%a %U:%G %n' "$lab" "$lab/data/credentials.json"
ls -l "/proc/$cloud_pid/fd"

Expect a running native process, several threads, a healthy HTTPS response and private bootstrap credentials. Do not print that credential file. You can see the listening descriptor, event-loop descriptors and module database files without reading their contents. Thread names may be identical; use TIDs and wait channels as clues, not as a stable module-to-thread API.

With iproute2 installed, ss -ltnp identifies the listening TCP endpoint when your permissions allow process attribution. A second terminal's plain curl without --cacert should not be used as the health test: it has not been given this lab's private trust root.

Step 3: observe file activity without exposing data

If inotify-tools is installed, watch only filenames and events in this lab:

inotifywait -m -r -e create,close_write,moved_to,delete "$lab/data"

In another terminal, point QHQ at this origin with this lab's credentials.json and server.crt, then create a synthetic resource group. Expect temporary-file writes and a move into the final state filename. Inotify reports events, not transaction contents or a durability proof. Stop the watcher with Ctrl+C when finished. A read-only health request should not be expected to create an ARM resource or continuously rewrite its state.

Step 4: sample system calls deliberately

If strace is available and local ptrace policy permits attaching to your own lab process, use a narrow syscall selection:

strace -f -p "$cloud_pid" \
  -e trace=epoll_wait,epoll_pwait,poll,ppoll,futex,fsync,fdatasync,rename,renameat,renameat2 \
  -o "$lab/scheduling-and-flush.trace"

Generate one health request or synthetic QHQ operation from another terminal, then Ctrl+C the tracer to detach. Event-loop waits, worker futex waits and flush/rename activity explain different parts of the request. Exact syscalls vary with the installed libraries and build. No trace event is proof that every request must follow the same path.

This command omits read/write/send/receive payloads. Broad syscall tracing can capture passwords, tokens, settings or directory bind credentials after TLS has been decrypted in the process. Keep even these narrower traces private. Do not weaken ptrace policy, disable ASLR or add container privileges to make this exercise work; use the /proc, socket and application diagnostics when attaching is unavailable. Tracing also changes timing, so it is not a benchmark.

Step 5: follow the UI's Unix path

In the ordinary F5/Rasta environment, QHQ renders into the shared framebuffer file and Rasta displays it. Input returns over UDP. The UI process then schedules HTTPS work; it does not read provider JSON to make changes. The QHQ job timer polls completed work every 40 ms while jobs exist and delivers widget updates on the UI thread. A frozen viewer, a waiting HTTPS job and a stalled cloud worker are separate failure layers.

Inspect the viewer process, framebuffer file and UDP socket before concluding that a blank window means the cloud is down. Do not copy the live framebuffer while showing a secret: its pixels are ordinary data in a file. The offscreen screenshot backend uses the same real client/API path without requiring a viewer.

Step 6: observe graceful exit and retain evidence

Return to the original lab terminal:

kill -TERM "$cloud_pid"
wait "$cloud_pid"
trap - EXIT
printf 'Private lab evidence remains in %s\n' "$lab"

The wait should return successfully. The process and its listening socket disappear; private on-disk state remains. The trap is cleared because this instance has already been reaped. The lab directory contains credentials and key material: retain it privately only as long as needed, then deliberately remove that specific disposable directory. Do not use a wildcard over other instances' state. A clean shutdown test establishes this process lifecycle; it does not establish recovery after power loss or prove an external engine's backup is consistent.