> 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/administration-guide/start/where-settings-live.md). # Where settings live The four places an OpenIAM setting can come from, which one wins, and how to find the effective value. ## What this is, and when you need it This page exists first because almost every "I changed it and nothing happened" problem in OpenIAM is a layering problem. A setting can be defined in four places, and the Webconsole shows you only one of them. Before you change any configuration, you need to know which layer you are editing and which layer the service is actually reading. Read it and you will be able to name which of the four layers a given setting is coming from, and prove it. This page is only that model: the screen you edit is [System configuration](/administration-guide/platform/system-configuration.md), the shipped value of every property is [System properties](/administration-guide/reference/system-properties.md), and the discipline for making the change is [Change configuration safely](/administration-guide/start/change-safely.md). The four steps at the end are how you establish the effective value, not how you change it. ## The four layers Later layers win. | # | Layer | Where it lives | Who can change it | Takes effect | | - | -------------------------- | ------------------------------------------------------------------- | ------------------------------------ | ------------------------------------ | | 1 | **Compiled-in default** | `application*.properties` inside each service artifact | Nobody, without a build | Service start | | 2 | **Shipped database value** | `PROPERTY_FILE_VALUES` row, seeded by a Flyway migration | Migration, on install or upgrade | Service start or cache refresh | | 3 | **Container override** | `OPENIAM_PROP_*` environment variable on the service | Whoever owns the deployment manifest | Service restart | | 4 | **Administrator edit** | The same `PROPERTY_FILE_VALUES` row, updated through the Webconsole | Any authorised administrator | Immediately, per the service's cache | Layer 2 is what [System properties](/administration-guide/reference/system-properties.md) documents: the value a newly migrated database contains. {% hint style="warning" %} Layers 3 and 4 are the ones that catch people out. A container override is invisible from the Webconsole — the screen will keep showing the database value while the service uses the environment variable. If a setting appears correct on screen and the product behaves as though it is not, check the deployment manifest before you change anything else. {% endhint %} ## The container override convention In Docker or Kubernetes, any property can be set by converting its key to an environment variable: take the property ID, replace every `.` with `_`, and prefix `OPENIAM_PROP_`. {% code overflow="wrap" %} ``` org.openiam.mq.broker.reply.timeout -> OPENIAM_PROP_org_openiam_mq_broker_reply_timeout ``` {% endcode %} This is not a marginal mechanism. Shipped deployment manifests use it for real tuning — the message broker reply timeout, for example, has a compiled-in baseline that every shipped container manifest overrides. If you are debugging timing behaviour and reading the baseline value from a properties file, you are reading the wrong layer. ### The interface services take theirs a different way The convention above is for the backend services, which run as Spring Boot applications. **The user interfaces run under Tomcat, and take their properties as `-D` arguments on `CATALINA_OPTS`** rather than as `OPENIAM_PROP_*` variables. The shipped configuration uses it: {% code overflow="wrap" %} ``` CATALINA_OPTS: "-Dlogging.level.root=INFO -Dorg.openiam.docker.ui.container.name=ui …" ``` {% endcode %} It matters here for one reason. A `org.openiam.ui.*` property that the Webconsole shows as one value and the interface behaves as though it were another may be set this way, and the four layers above do not account for it — so a reader who has ruled out a container override has not yet ruled out everything. Where that argument lives depends on the deployment, which makes it the deployment owner's to read rather than yours. ## Settings that are not properties at all Not everything configurable is a property. Four other stores matter, and each has a different change and rollback story. **Policies.** Password and authentication rules are `POLICY_ATTRIBUTE` rows against a policy, not properties. See [Password and authentication policy parameters](/administration-guide/reference/policy-parameters.md). **Objects.** Managed systems, content providers, URI patterns, roles, page templates, approver associations and campaigns are first-class objects with their own screens. They are exported and promoted as objects, not as configuration files. **Files deployed with a service.** Approval workflows are BPMN definitions shipped with the workflow service, and Groovy extensions exist either as versions stored in the Groovy Manager or as files deployed alongside the service. You can edit and version a stored Groovy script from **Administration → Groovy Manager** and it takes effect without a restart; a change to a file deployed with a service does not take effect until the deployment owner restarts that service, which is outside this guide. Prefer the Groovy Manager for anything you expect to change. See [Shipped approval workflows](/administration-guide/reference/shipped-workflows.md) and [Create a Groovy script](/administration-guide/automation/manage-groovy-scripts.md). **Secrets.** Credentials referenced by properties such as the SMTP password are held in the secret store and referenced by key, not stored in the property row. ## Finding the effective value Do this in order. Stop at the first layer that explains the behaviour. {% stepper %} {% step %} ### Read the Webconsole value **Administration → System Configuration**, on the tab matching the property's category. This tells you layers 2 and 4 combined — the current database value. {% endstep %} {% step %} ### Compare it against the shipped default Look the property up in [System properties](/administration-guide/reference/system-properties.md). If the current value differs from the shipped default, somebody changed it deliberately; find out who and why before changing it back. {% endstep %} {% step %} ### Rule out a container override An `OPENIAM_PROP_` environment variable on the service silently beats the row the Webconsole shows you, and **there is no screen that will tell you it exists**. If you have access to the deployment's Compose files, Helm values or Kubernetes manifests, search them for that variable; if the variable is set, that is the value the service is using. If you do not have that access, this is the point at which you ask the deployment owner — do not keep editing the Webconsole value, because you can change it correctly any number of times and observe nothing. **For a `org.openiam.ui.*` property, ask about `CATALINA_OPTS` as well.** The interfaces run under Tomcat and take their properties as `-D` arguments there rather than as `OPENIAM_PROP_*` variables, so a search for the environment variable alone can come back clean on a property that is in fact being overridden. {% endstep %} {% step %} ### Confirm which service reads it A property is read by the service that implements the behaviour, not by all of them. A UI property will not appear to take effect if only the ESB was restarted, and vice versa. Establish which service owns the behaviour — the Webconsole for a `org.openiam.ui.*` property, the ESB for most of the rest — before you conclude the value is wrong. Restarting a service is not a Webconsole operation and is not covered here; if the value is correct in the database, no container override is set, and the behaviour still has not changed, that is the point to ask the deployment owner for a restart of the owning service. Name the service and the property when you ask. {% endstep %} {% endstepper %} ## A trap in the category names The `CATEGORY` column doubles as the Webconsole tab name, and one of them is misleading: {% hint style="danger" %} The **Gateway** category does not hold Access Gateway (rProxy) settings. It holds the SMTP mail gateway — `org.openiam.smtp.mail.*` and the mail secret keys. rProxy is configured from content providers and URI patterns in the Webconsole, not on this tab. See [Administer the Access Gateway](/administration-guide/gateway.md). {% endhint %} ## Before you change anything Record the property ID, the current value, the layer you are editing, the service that must restart, and who owns the rollback. That is the whole of the discipline, and it belongs in whatever change record you already keep — see [Change configuration safely](/administration-guide/start/change-safely.md). ## Related * [System properties](/administration-guide/reference/system-properties.md) — all 704 shipped properties with defaults * [Change configuration safely](/administration-guide/start/change-safely.md) — the change and rollback standard * [System configuration](/administration-guide/platform/system-configuration.md) — the screen itself, tab by tab *Applies to OpenIAM 2026.8.1. Last reviewed 7 August 2026.* --- # 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/administration-guide/start/where-settings-live.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.