--- title: PingGateway configuration files and routes description: "Configure PingGateway using JSON files and routes: understand file locations, route naming, inline and heap objects, and when to restart" component: pinggateway version: 2026 page_id: pinggateway:configure:configure canonical_url: https://docs.pingidentity.com/pinggateway/2026/configure/configure.html revdate: 2025-11-05T15:33:44Z section_ids: configuration-location: Configuration location configuration_security: Configuration security configure-default-location: Change the base location route-name-id-filename: Route names, IDs, and filenames 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 --- # PingGateway configuration files and routes PingGateway 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 PingGateway configuration and logs. | Purpose | Default location on Linux | Default location on Windows | | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | --------------------------------- | | Log messages from PingGateway 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)) | `$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 `topicSchemasDirectory` in [AuditService](../reference/AuditService.html). | `$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 PingGateway system account. * Least privilege for specific accounts, on a case-by-case basis * No privilege for all other accounts, by default ## Change the base location By default, the base location for PingGateway configuration files is in the following directory: * Linux `$HOME/.openig` * Windows `%appdata%\OpenIG` Change the location by using an argument with the startup command. The following example reads the configuration from the `config` directory under `/path/to/config-dir`: * Linux `/path/to/ping-gateway-2026.3.0/bin/start.sh /path/to/config-dir` * Windows `C:\path\to\ping-gateway-2026.3.0\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 doesn't 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 * Inline objects An inline object is declared in a route or configuration, outside of the heap. The following example shows an inline declaration for a handler to route requests: ```json { "handler": { "name": "My Router", "type": "Router" } } ``` The `name` property for inline objects is optional but useful for logging. Other objects in the configuration can never refer to named or unnamed inline objects. * Heap objects A heap object is declared inside the heap. The following example shows a named router in the heap, and a handler that refers to the router by its name: ```json { "handler": "My Router", "heap": [ { "name": "My Router", "type": "Router" } ] } ``` The `name` property for heap objects is required. Other objects in the configuration or its child configirations can refer to the heap obect by its `name` property. ## Comment the configuration JSON format doesn't specify a notation for comments. If PingGateway 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 } } ``` * Single-line comments with `//`. The following example comments out `"captureContext": true`: ```none { "name": "capture", "type": "CaptureDecorator", "config": { //"captureContext": true, "captureEntity": false } } ``` ## 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 PingGateway to take the change into account. Stop and restart PingGateway only when you make the following changes: * Change the configuration of any route, when the `scanInterval` of Router is `disabled` (refer to [Router](../reference/Router.html)). * 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 PingGateway, edit the router `scanInterval`, and restart PingGateway. 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 Learn more in [Reserved routes](../reference/preface.html#reserved-routes).