--- title: Configuration files and routes description: "IG processes requests and responses by using the following JSON files: admin.json, config.json, Route, and Router." component: pinggateway version: 2023.11 page_id: pinggateway:configure:configure canonical_url: https://docs.pingidentity.com/pinggateway/2026/configure/configure.html llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2023-09-19T08:48:14Z superseded_by: https://docs.pingidentity.com/pinggateway/2026/configure/configure.html section_ids: configuration-location: Configuration location configuration_security: Configuration security configure-default-location: Change the base location routing-inline: Inline and heap objects config-comments: Comment the configuration restart-required: Restart after configuration change routing-lockdown: Prevent reload of routes routing-reserved: Reserved routes --- # Configuration files and routes IG processes requests and responses by using the following JSON files: [admin.json](../reference/AdminHttpApplication.html), [config.json](../reference/GatewayHttpApplication.html), [Route](../reference/Route.html), and [Router](../reference/Router.html). ## Configuration location The following table summarizes the default location of the IG configuration and logs. | Purpose | Default location on Linux | Default location on Windows | | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | --------------------------------- | | Log messages from IG and third-party dependencies | `$HOME/.openig/logs` | `%appdata%\OpenIG\logs` | | Administration ([admin.json](../reference/AdminHttpApplication.html))Gateway ([config.json](../reference/GatewayHttpApplication.html)) | `$HOME/.openig/config` | `%appdata%\OpenIG\config` | | Routes ([Route](../reference/Route.html#AdminHttpApplication)) | `$HOME/.openig/config/routes` | `%appdata%\OpenIG\config\routes` | | SAML 2.0 | `$HOME/.openig/SAML` | `%appdata%\OpenIG\SAML` | | Groovy scripts for scripted filters and handlers, and other objects | `$HOME/.openig/scripts/groovy` | `%appdata%\OpenIG\scripts\groovy` | | Temporary directoryTo change the directory, configure `temporaryDirectory` in [admin.json](../reference/AdminHttpApplication.html) | `$HOME/.openig/tmp` | `%appdata%\OpenIG\tmp` | | JSON schema for custom auditTo change the directory, configure `topicsSchemasDirectory` in [AuditService](../reference/AuditFramework.html#AuditService). | `$HOME/.openig/audit-schemas` | `%appdata%\OpenIG\audit-schemas` | ## Configuration security Allow the following access to `$HOME/.openig/logs`, `$HOME/.openig/tmp`, and all configuration directories: * Highest privilege the IG system account. * Least priviledge for specific accounts, on a case-by-case basis * No priviledge for all other accounts, by default ## Change the base location By default, the base location for IG configuration files is in the following directory: * Linux * Windows ``` $HOME/.openig ``` ``` %appdata%\OpenIG ``` Change the location in the following ways: * Edit the `prefix` property of [admin.json](../reference/AdminHttpApplication.html). * Use an argument with the startup command. The following example reads the configuration from the `config` directory under `/path/to/config-dir`: * Linux * Windows ``` $ /path/to/identity-gateway-2023.11.2/bin/start.sh /path/to/config-dir ``` ``` C:\path\to\identity-gateway-2023.11.2\bin\start.bat /path/to/config-dir ``` \== Route names, IDs, and filenames The filenames of routes have the extension .json, in lowercase. The router scans the `$HOME/.openig/config/routes` folder for files with the .json extension. It uses the route `name` property to order the routes in the configuration. If the route does not have a `name` property, the router uses the route ID. The route ID is managed as follows: * When you add a route manually to the routes folder, the route ID is the value of the `_id` field. If there is no `_id` field, the route ID is the filename of the added route. * When you add a route through the Common REST endpoint, the route ID is the value of the mandatory `_id` field. * When you add a route through Studio, you can edit the default route ID. | | | | - | ----------------------------------------------------------------------------------------------------------------- | | | The filename of a route can't be `default.json`, and the route's `name` property and route ID can't be `default`. | ## Inline and heap objects If you use an object only once in the configuration, you can declare it inline in the route and don't need to name it. However, when you need use an object multiple times, declare it in the heap, and then refer to it by name in the route. The following route shows an inline declaration for a handler. The handler is a router to route requests to separate route configurations: ```json { "handler": { "type": "Router" } } ``` The following route shows a named router in the heap, and a handler references the router by its name: ```json { "handler": "My Router", "heap": [ { "name": "My Router", "type": "Router" } ] } ``` Notice that the heap is an array. Because the heap holds all configuration objects at the same level, you can impose any hierarchy or order when referring to objects. Note that when you declare all objects in the heap and refer to them by name, neither hierarchy nor ordering are obvious from the structure of the configuration file alone. ## Comment the configuration JSON format doesn't specify a notation for comments. If IG does not recognize a JSON field name, it ignores the field. As a result, it's possible to use comments in configuration files. The following conventions are available for commenting: * A `comment` field to add text comments. The following example includes a text comment. ```json { "name": "capture", "type": "CaptureDecorator", "comment": "Write request and response information to the logs", "config": { "captureEntity": true } } ``` * An underscore (`_`) to comment a field temporarily. The following example comments out `"captureEntity": true`, and as a result it uses the default setting (`"captureEntity": false`). ```json { "name": "capture", "type": "CaptureDecorator", "config": { "_captureEntity": true } } ``` ## Restart after configuration change You can change routes or change a property that's read at runtime or that relies on a runtime expression without needing to restart IG to take the change into account. Stop and restart IG only when you make the following changes: * Change the configuration of any route, when the `scanInterval` of Router is `disabled` (see [Router](../reference/Handlers.html#Router)). * Add or change an external object used by the route, such as an environment variable, system property, external URL, or keystore. * Add or update `config.json` or `admin.json`. ## Prevent reload of routes To prevent routes from being reloaded after startup, stop IG, edit the router `scanInterval`, and restart IG. When the interval is set to `disabled`, routes are loaded only at startup: ```json { "name": "Router", "type": "Router", "config": { "scanInterval": "disabled" } } ``` The following example changes the location where the router looks for the routes: ```json { "name": "Router", "type": "Router", "config": { "directory": "/path/to/safe/routes", "scanInterval": "disabled" } } ``` ## Reserved routes For information about reserved routes, refer to [Reserved routes](../reference/preface.html#reserved-routes).