---
title: Starting and stopping PingGateway
description: Start and stop PingGateway using default or custom settings, including port and TLS configuration, graceful shutdown, and forcible shutdown with a time limit
component: pinggateway
version: 2026
page_id: pinggateway:installation-guide:start-stop
canonical_url: https://docs.pingidentity.com/pinggateway/2026/installation-guide/start-stop.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: 2026-07-23T14:42:08Z
section_ids:
  starting-default: Start PingGateway with default settings
  starting-options: Start PingGateway with custom settings
  pidFileMode: Allow startup when there is an existing PID file
  stopping: Stop PingGateway
  forcible-shutdown: Forcible shutdown
  distroless: Start and stop PingGateway on distroless Linux containers
---

# Starting and stopping PingGateway

## Start PingGateway with default settings

When you start PingGateway, specify the configuration directory where PingGateway looks for configuration files.

1. Start PingGateway:

   * Linux

     `/path/to/ping-gateway-2026.9.0/bin/start.sh`

   * Windows

     `C:\path\to\ping-gateway-2026.9.0\bin\start.bat`

   By default, PingGateway configuration files are located under `$HOME/.openig` on Linux, `%appdata%\OpenIG` on Windows. Learn how to use a different location in [Configuration location](../configure/configure.html#configuration-location).

2. Check that PingGateway is running in one of the following ways:

   * Check the PingGateway endpoint at `http://ig.example.com:8085/health/startup` to make sure PingGateway it returns `HTTP 200 OK`.

     If PingGateway hasn't finished starting up or is shutting down, the endpoint returns `HTTP 503 Service Unavailable`.

   * Display the product version and build information at `http://ig.example.com:8085/api/info`.

## Start PingGateway with custom settings

By default, PingGateway runs on HTTP, on port `8080`, from the instance directory `$HOME/.openig`.

To start PingGateway with custom settings, add the configuration file `admin.json` with the following properties, and restart PingGateway:

* `vertx`: Finely tune Vert.x server-side properties.

* `connectors`: Customize server port, TLS, and Vert.x-specific configurations. Each `connectors` object represents the configuration of an individual port.

This example starts PingGateway with non-default connector ports and configures server-side WebSocket options for port 9091:

```json
{
  "connectors": [{
    "port": 9090
  },
  {
    "port": 9091,
    "vertx": {
      "maxWebSocketFrameSize": 131072,
      "maxWebSocketMessageSize": 262144
    }
  }]
}
```

For more information, refer to [AdminHttpApplication (`admin.json`)](../reference/AdminHttpApplication.html).

## Allow startup when there is an existing PID file

By default, if there is an existing PID file during startup the startup fails. Use one of the following ways to allow startup when there is an existing PID file. PingGateway then removes the existing PID file and creates a new one during startup.

1. Add the following configuration to `admin.json` and restart PingGateway:

   ```json
   {
     "pidFileMode": "override"
   }
   ```

   Source: [admin-pidfilemode.json](../_attachments/config/admin-pidfilemode.json)

2. Define an environment variable for the configuration token `ig.pid.file.mode`, and then start PingGateway in the same terminal:

   * Linux

   * Windows

   ```console
   $ IG_PID_FILE_MODE=override /path/to/ping-gateway-2026.9.0/bin/start.sh
   ```

   ```none
   C:\IG_PID_FILE_MODE=override
   C:\path\to\ping-gateway-2026.9.0\bin\start.bat %appdata%\OpenIG
   ```

3. Define a system property for the configuration token `ig.pid.file.mode` when you start PingGateway:

   * Linux

     `$HOME/.openig/env.sh`

   * Windows

     `%appdata%\OpenIG\env.sh`

   ```shell
   export "IG_OPTS=-Dig.pid.file.mode=override"
   ```

## Stop PingGateway

Use the `stop.sh` script to stop an instance of PingGateway, specifying the instance directory as an argument.

If the instance directory isn't specified, PingGateway uses the default instance directory as in these examples:

* Linux

  `/path/to/ping-gateway-2026.9.0/bin/stop.sh $HOME/.openig`

* Windows

  `C:\path\to\ping-gateway-2026.9.0\bin\stop.bat %appdata%\OpenIG`

### Forcible shutdown

By default, the `stop.sh` and `stop.bat` scripts let the PingGateway process terminate gracefully.

You can set a time limit in milliseconds after which the script forces PingGateway to shut down. Specify the time limit after the instance directory argument.

The following examples kill the PingGateway process after 20 seconds if it has failed to terminate gracefully:

* Linux

  `/path/to/ping-gateway-2026.9.0/bin/stop.sh $HOME/.openig 20000`

* Windows

  `C:\path\to\ping-gateway-2026.9.0\bin\stop.bat %appdata%\OpenIG 20000`

Make sure the time limit is longer than the grace period for connections to close (default: 1 second/1000 milliseconds). Learn about the `"gracePeriod"` settings in the `admin.json` reference documentation for [administrative connections](../reference/AdminHttpApplication.html#AdminHttpApplication-adminConnector-gracePeriod) and [client connections](../reference/AdminHttpApplication.html#AdminHttpApplication-connectors-gracePeriod)

## Start and stop PingGateway on distroless Linux containers

Distroless Linux container images usually don't include a shell (`/bin/sh`). Without a shell, you can't use the `start.sh` script. To start PingGateway in a distroless container without a shell, invoke `java` directly as in the following example `Dockerfile`:

```none
FROM debian:12-slim AS builder

WORKDIR /build

COPY *.zip ./
RUN apt-get update && \
    apt-get install -y --no-install-recommends unzip && \
    rm -rf /var/lib/apt/lists/* && \
    unzip *.zip && \
    mv ping-gateway-* /opt/gateway && \
    mkdir -p /var/gateway

FROM gcr.io/distroless/java21-debian12:nonroot

COPY --from=builder --chown=65532:65532 /opt/gateway /opt/gateway
COPY --from=builder --chown=65532:65532 /var/gateway /var/gateway

EXPOSE 8080 8085

ENTRYPOINT ["java", \
    "-classpath", "/opt/gateway/classes:/opt/gateway/lib/*", \
    "org.forgerock.openig.standalone.Start", \
    "/var/gateway"]
```

The `/var/gateway` folder in this example contains PingGateway configuration files. You mount it at runtime. Learn more about running PingGateway in a Docker container in [Deploying PingGateway with Docker](../devops-guide/preface.html).

To stop PingGateway in a distroless container, send SIGTERM to PID 1. The container runtime does this automatically when you run `docker stop` or when the container orchestrator terminates the container. SIGTERM is delivered to PID 1 (the JVM process), which triggers PingGateway's shutdown hooks for a graceful shutdown.

When the container gets the SIGTERM, `stop.sh` doesn't run, meaning:

* PingGateway doesn't remove its PID file, which causes the container to fail to restart by default.

  You must prevent the container from failing to start again when it finds the old PID file. Either set the [pidFileMode](../reference/AdminHttpApplication.html#AdminHttpApplication-pidFileMode) to `override` in `admin.json` or start the container with the `--env IG_OPTS=-Dig.pid.file.mode=override` option.

* There's no equivalent to the forcible-shutdown timeout option described in [Forcible shutdown](#forcible-shutdown).