> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/installation/diagnostics.md). # Diagnostics Establish what is wrong before you ask anyone — a health snapshot, a symptom index, and the one script that collects everything a support case needs. Most deployment problems are one of about a dozen things, and each has a check that identifies it in seconds. This page is the shortest path from "something is wrong" to knowing what. **Work in this order.** The health snapshot tells you which tier is unhappy; the symptom index tells you what that means; the collection script packages the evidence if you do need to raise a case. *** ## 1. The health snapshot Run this first, every time. It is read-only and takes about twenty seconds. {% code overflow="wrap" expandable="true" %} ```bash echo "== services"; pgrep -c -u openiam java echo "== platform"; openiam-cli status 2>&1 | tail -25 echo "== proxy"; systemctl is-active httpd nginx echo "== secret store"; curl -sk https://localhost:8200/v1/sys/seal-status | jq -c '{sealed,initialized}' echo "== graph"; nodetool status 2>&1 | tail -5 echo "== broker"; rabbitmqctl -q status >/dev/null 2>&1 && echo running || echo NOT RUNNING echo "== search"; curl -sk -u "$OPENSEARCH_USER" https://localhost:9200/_cluster/health | jq -c '{status,number_of_nodes}' echo "== cache"; redis-cli -a "$REDIS_PASSWORD" --no-auth-warning info replication | grep -E '^role' echo "== disk"; df -h / /usr/local/openiam | tail -2 echo "== memory"; free -g | awk '/^Mem:/ {print " total "$2"G available "$7"G"}' echo "== interfaces" for p in 8082:webconsole 8086:openiam-ui-static 8081:idp \ 8083:selfservice 8084:selfservice-ext 8085:reportviewer; do port=${p%%:*}; app=${p##*:} printf ' %-22s %s\n' "$app" \ "$(curl -s -m 5 "http://localhost:$port/$app/actuator/health" | jq -r '.status // "no response"')" done ``` {% endcode %} `$REDIS_PASSWORD` and `$OPENSEARCH_USER` come from the secret store — [*Commands*](/installation/commands.md#reading-a-credential-from-the-secret-store) shows how to set them. ### What healthy looks like | Line | Healthy | | ------------ | ----------------------------------------------------------------------------------- | | services | 20 or more | | proxy | `active` for both | | secret store | `{"sealed":false,"initialized":true}` | | graph | one node `UN` on a single-node deployment, three on a cluster | | broker | `running` | | search | `yellow` on one node, `green` on a cluster | | cache | `role:master` on a single node; one `role:master` and two `role:slave` on a cluster | | disk | comfortably above 10% free | | interfaces | `UP` on all six | **On a cold start, allow 15 minutes** — 20 on a cluster — before treating anything as a fault. Services wait for the tier beneath them, and a platform that is still coming up looks very like one that has failed. *** ## 2. The symptom index Read down the first column until something matches. | What you observe | Most likely cause | Confirm it | Fix | | ----------------------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | Nothing responds, `pgrep` is 0 | The infrastructure tier is not up, so nothing above it started | The snapshot's secret store, graph, broker and search lines | Bring the tier up, then `openiam-cli start` | | Everything is up except one interface | That one service | Its health endpoint, then its log | Restart that unit | | The console is reachable on the host but not from elsewhere | Firewall | `firewall-cmd --list-ports` | Open 80 and 443 | | `Service Not Available` in the browser | The proxy cannot reach the interface router | `curl localhost:8080/idp/login` from the host | [*Configure the reverse proxy*](/installation/rpm/rpm-single-node/configure-the-reverse-proxy.md) | | Pages load, assets do not | The static assets service or the interface router | The `openiam-ui-static` health endpoint, then `nginx -t` | Restart the service or the router | | Everything fails after a host restart | The secret store is sealed | The snapshot's secret store line | See *sealed*, below | | Signing in fails for everyone | The secret store, or the identity provider | The secret store line, then the `idp` health endpoint | Bottom of the stack first | | Users signed out unpredictably | On a cluster: session state not shared. On one node: a service restarting | The cache line; `journalctl -u openiam-idp --since '1 hour ago'` | Confirm the cache is clustered | | Something worked yesterday and not today | Disk, or an expired certificate | The disk line; `openssl x509 -enddate -noout -in ` | Free space, or renew | | A connector stopped | The connector process, or the broker | `openiam-cli connector status` | Restart the connector after confirming the broker | | The platform is slow, nothing is down | Memory pressure or the database | The memory line; your database server's own monitoring | Sizing — see the architecture guide | | A search or report returns nothing | The search tier | The search line, then the index | Confirm the tier before assuming a data problem | ### The three that account for most cases **The secret store is sealed.** Everything the platform does needs a credential from it, so a sealed store produces failures that look like a dozen unrelated problems. {% code overflow="wrap" %} ```bash curl -sk https://localhost:8200/v1/sys/seal-status | jq '.sealed' ``` {% endcode %} `true` means sealed. Unseal it with the keys recorded at installation, then `openiam-cli start`. **Use `openiam-cli stop` before restarting a host** and it comes back unsealed on its own. **A tier was not ready when the services started.** The services wait, and if the wait expires they stop. The fix is always the same: confirm the tier, then restart the services above it — not the other way around. **The host ran out of disk or memory.** Both produce symptoms all over the platform. {% code overflow="wrap" %} ```bash df -h / /usr/local/openiam free -g du -sh /usr/local/openiam/logs ``` {% endcode %} *** ## 3. Collect the evidence If the checks above have not resolved it, run this. It gathers what a support engineer would ask for, in one archive. {% code overflow="wrap" expandable="true" %} ```bash #!/bin/bash # Collect an OpenIAM diagnostic bundle. Read-only; nothing is changed. set -u OUT="/tmp/openiam-diag-$(hostname -s)-$(date +%Y%m%d-%H%M%S)" mkdir -p "$OUT" # Platform openiam-cli status > "$OUT/status.txt" 2>&1 rpm -q openiam > "$OUT/version.txt" 2>&1 cat /usr/local/openiam/version >> "$OUT/version.txt" 2>&1 pgrep -a -u openiam java > "$OUT/processes.txt" 2>&1 systemctl list-units 'openiam*' --all --no-pager > "$OUT/units.txt" 2>&1 # Host uname -a > "$OUT/host.txt" 2>&1 cat /etc/os-release >> "$OUT/host.txt" 2>&1 free -g >> "$OUT/host.txt" 2>&1 df -h >> "$OUT/host.txt" 2>&1 ulimit -Hn >> "$OUT/host.txt" 2>&1 getenforce >> "$OUT/host.txt" 2>&1 ss -lntp > "$OUT/listening.txt" 2>&1 firewall-cmd --list-all > "$OUT/firewall.txt" 2>&1 # Infrastructure nodetool status > "$OUT/graph.txt" 2>&1 rabbitmqctl cluster_status > "$OUT/broker.txt" 2>&1 curl -sk https://localhost:8200/v1/sys/seal-status > "$OUT/secretstore.json" 2>&1 consul members > "$OUT/secretstore-backend.txt" 2>&1 # Logs — last 2000 lines of each, which is where the cause almost always is mkdir -p "$OUT/logs" for f in /usr/local/openiam/logs/*.log; do tail -2000 "$f" > "$OUT/logs/$(basename "$f")" 2>/dev/null done tail -2000 /var/log/openiam-start.log > "$OUT/logs/openiam-start.log" 2>/dev/null tail -2000 /var/log/httpd/mod_openiam_error_log > "$OUT/logs/proxy-error.log" 2>/dev/null journalctl -u 'openiam*' --since '24 hours ago' --no-pager > "$OUT/logs/journal.txt" 2>&1 tar -czf "$OUT.tar.gz" -C /tmp "$(basename "$OUT")" && rm -rf "$OUT" echo "Bundle: $OUT.tar.gz" ``` {% endcode %} **Review the bundle before sending it.** It deliberately excludes `env.conf` and the installation log, both of which record configuration values, but service logs can still contain identity data from your environment. Open the archive and check it against your own disclosure rules. On a three-node deployment, run it on **all three hosts** — the difference between them is usually the answer. ## 4. What to include when you raise a case Four things turn a case around in one exchange rather than four: 1. **The diagnostic bundle**, from every affected host. 2. **What changed.** A restart, a patch, a certificate, a configuration change, a load increase — the answer is almost never "nothing". 3. **When it started**, and whether it is constant or intermittent. 4. **What you already checked**, from the symptom index above. Include your OpenIAM version (`rpm -q openiam`) and the shape you are running — single node or three nodes, local or remote database. ## Related * [*Commands*](/installation/commands.md) — the `openiam-cli` surface, log names, and reading a credential from the secret store * [*Troubleshoot — single node*](/installation/rpm/rpm-single-node/troubleshoot.md) * [*Troubleshoot — three nodes*](/installation/rpm/rpm-ha/troubleshoot.md) * [*Start and verify*](/installation/rpm/rpm-single-node/start-and-verify.md) — the full verification pass *Applies to OpenIAM 2026.8.1.* --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.openiam.com/installation/diagnostics.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.