--- title: Install IG in standalone mode description: Create a local installation directory for IG. The examples in this section use /path/to. component: pinggateway version: 7.2 page_id: pinggateway:installation-guide:install-standalone canonical_url: https://docs.pingidentity.com/pinggateway/7.2/installation-guide/install-standalone.html revdate: 2025-06-02T16:30:54Z section_ids: starting-standalone: Download and start IG in standalone mode download-project: Download the IG .zip file starting-default: Start IG with default settings starting-options: Start IG with custom settings stopping: Stop IG standalone-https: Configure IG For HTTPS (server-side) in standalone mode using-certs-in-examples: Using keys and certificates with IG in standalone mode standalone-https-keyManager: Serve the same certificate for TLS connections to all server names standalone-https-sni: Serve different certificates for TLS connections to different server names standalone-envvar-sysprop: Configure environment variables and system properties for IG in standalone mode start_ig_with_a_customized_router_scan_interval: Start IG with a customized router scan interval install-standalone-env-var: Define environment variables for startup, runtime, and stop standalone-jar-files.xml: Add .jar files for IG extensions in standalone mode --- # Install IG in standalone mode ## Download and start IG in standalone mode ### Download the IG .zip file 1. Create a local installation directory for IG. The examples in this section use `/path/to`. 2. Download `IG-7.2.0.zip` from the [Ping Identity Product Downloads](https://product-downloads.pingidentity.com/), and copy the .zip file to the installation directory: ```bash $ cp IG-7.2.0.zip /path/to/IG-7.2.0.zip ``` 3. Unzip the file: ```bash $ unzip IG-7.2.0.zip ``` The directory `/path/to/identity-gateway-7.2.0` is created. ### Start IG with default settings Use the following step to start the instance of IG, specifying the configuration directory where IG looks for configuration files. 1. Start IG: * Linux * Windows ```bash $ /path/to/identity-gateway-7.2.0/bin/start.sh ... ... started in 1234ms on ports : [8080 8443] ``` ```windows C:\path\to\identity-gateway-7.2.0\bin\start.bat ``` By default, the base location for IG configuration files is in `%appdata%\OpenIG`. To read the configuration from a different location, specify the base location as an argument. The following example reads the configuration from the `config` directory under the instance directory: * Linux * Windows ```bash $ /path/to/identity-gateway-7.2.0/bin/start.sh $HOME/.openig ... ... started in 1234ms on ports : [8080] ``` ```windows C:\path\to\identity-gateway-7.2.0\bin\start.bat %appdata%\OpenIG ... ... started in 1234ms on ports : [8080] ``` 2. Check that IG is running in one of the following ways: * Ping IG at `http://ig.example.com:8080/openig/ping`, and make sure an `HTTP 200` is returned. * Access the IG welcome page at `http://ig.example.com:8080`. * When IG is running in development mode, display the product version and build information at `http://ig.example.com:8080/openig/api/info`. ### Start IG with custom settings By default, IG runs on HTTP, on port `8080`, from the instance directory `$HOME/.openig`. To start IG with custom settings, add the configuration file `admin.json` with the following properties, and restart IG: * `vertx`: Finely tune Vert.x instances. * `connectors`: Customize server port, TLS, and Vert.x-specific configurations. Each `connectors` object represents the configuration of an individual port. * `prefix`: Set the instance directory, and therefore, the base of the route for administration requests. The following example starts IG on non-default ports, and configures Vert.x-specific options for the connection on port 9091: ```json { "connectors": [{ "port": 9090 }, { "port": 9091, "vertx": { "maxWebSocketFrameSize": 128000, "maxWebSocketMessageSize": 256000, "compressionLevel": 4 } }] } ``` For more information, see [AdminHttpApplication (admin.json)](../reference/RequiredConfiguration.html#AdminHttpApplication). ### Stop IG Use the `stop.sh` script to stop an instance of IG, specifying the instance directory as an argument. If the instance directory is not specified, IG uses the default instance directory: * Linux * Windows ```bash $ /path/to/identity-gateway-7.2.0/bin/stop.sh $HOME/.openig ``` ```windows C:\path\to\identity-gateway-7.2.0\bin\stop.bat %appdata%\OpenIG ``` ## Configure IG For HTTPS (server-side) in standalone mode When IG is *server-side*, applications send requests to IG or request services from IG. IG is acting as a server of the application, and the application is acting as a client. To run IG as a server over HTTPS, you must configure connections to TLS-protected endpoints, based on [ServerTlsOptions](../reference/MiscellaneousConfigurationObjects.html#ServerTlsOptions). ### Using keys and certificates with IG in standalone mode The examples in this doc set use self-signed certificates, but your deployment is likely to use certificates issued by a certificate authority (CA certificates). The way to obtain CA certificates depends on the certificate authority that you are using, and is not described in this document. As an example, see [Let's Encrypt](https://letsencrypt.org/getting-started.html). When IG is in web container mode, the way to integrate CA certificates depends on the web container type; see your web container documentation for more information. When IG is in standalone mode, integrate CA certificates by using secret stores: * For PEM files, use a [FileSystemSecretStore](../reference/FileSystemSecretStore.html) and [PemPropertyFormat](../reference/PemPropertyFormat.html) * For PKCS12 keystores, use a [KeyStoreSecretStore](../reference/KeyStoreSecretStore.html) For examples, see [Serve the same certificate for TLS connections to all server names](#standalone-https-keyManager). Note the following points about using secrets: * When IG in standalone mode starts up, it listens for HTTPS connections, using the ServerTlsOptions configuration in `admin.json`. The keys and certificates are fetched only once, at startup. * Keys and certificates must be present at startup. * If keys or certificates change, you must to restart IG. For information about secret stores provided in IG, see [Secrets object and secret stores](../reference/secrets.html). ### Serve the same certificate for TLS connections to all server names This example uses PEM files and a PKCS12 keystore for self-signed certificates, but you can adapt it to use official (non self-signed) keys and certificates. Before you start, install IG in standalone mode, as described in [Download and start IG in standalone mode](../getting-started/start-product.html#starting-standalone). 1. Locate a directory for the secrets, for example, `/path/to/secrets`. 2. Create self-signed keys in one of the following ways. If you have your own keys, use them and skip this step. > **Collapse: Use your own keys** > > If you have your own keys, use them and skip this step. > **Collapse: Set up a self-signed certificate in a (PKCS12) keystore** > > 1. Create the keystore, replacing `/path/to/secrets` with your path: > > ```bash > $ keytool \ > -genkey \ > -alias https-connector-key \ > -keyalg RSA \ > -keystore /path/to/secrets/IG-keystore \ > -storepass password \ > -keypass password \ > -dname "CN=ig.example.com,O=Example Corp,C=FR" > ``` > > | | | > | - | ------------------------------------------------------------------------------------------------------------------------------- | > | | Because keytool converts all characters in its key aliases to lowercase, use only lowercase in alias definitions of a KeyStore. | > > 2. In the secrets directory, add a file called `keystore.pass`, containing the keystore password `password`: > > ```bash > $ cd /path/to/secrets/ > $ echo -n 'password' > keystore.pass > ``` > > Make sure that the password file contains only the password, with no trailing spaces or carriage returns. > **Collapse: Set up self-signed certificate stored in PEM file** > > 1. Locate a directory for secrets, and go to it: > > ```bash > $ cd /path/to/secrets > ``` > > 2. Create the following secret key and certificate pair as PEM files: > > ```bash > $ openssl req \ > -newkey rsa:2048 \ > -new \ > -nodes \ > -x509 \ > -days 3650 \ > -subj "/CN=ig.example.com/OU=example/O=com/L=fr/ST=fr/C=fr" \ > -keyout ig.example.com-key.pem \ > -out ig.example.com-certificate.pem > ``` > > Two PEM files are created, one for the secret key, and another for the associated certificate. > > 3. Map the key and certificate to the same secret ID in IG: > > ```bash > $ cat ig.example.com-key.pem ig.example.com-certificate.pem > key.manager.secret.id.pem > ``` 3. Set up TLS on IG in one of the following ways: > **Collapse: Keys stored in a (PKCS12) keystore** > > Add the following file to IG, replacing `/path/to/secrets` with your path: > > * Linux > > * Windows > > ``` > $HOME/.openig/config/admin.json > ``` > > ``` > %appdata%\OpenIG\config\admin.json > ``` > > ```json > { > "connectors": [ > { > "port": 8080 > }, > { > "port": 8443, > "tls": "ServerTlsOptions-1" > } > ], > "heap": [ > { > "name": "ServerTlsOptions-1", > "type": "ServerTlsOptions", > "config": { > "keyManager": { > "type": "SecretsKeyManager", > "config": { > "signingSecretId": "key.manager.secret.id", > "secretsProvider": "ServerIdentityStore" > } > } > } > }, > { > "type": "FileSystemSecretStore", > "name": "SecretsPasswords", > "config": { > "directory": "/path/to/secrets", > "format": "PLAIN" > } > }, > { > "name": "ServerIdentityStore", > "type": "KeyStoreSecretStore", > "config": { > "file": "/path/to/secrets/IG-keystore", > "storePassword": "keystore.pass", > "secretsProvider": "SecretsPasswords", > "mappings": [ > { > "secretId": "key.manager.secret.id", > "aliases": ["https-connector-key"] > } > ] > } > } > ] > } > ``` > > Notice the following features of the file: > > * IG starts on port `8080`, and on `8443` over TLS. > > * IG's private keys for TLS are managed by the SecretsKeyManager, whose ServerIdentityStore references a KeyStoreSecretStore. > > * The KeyStoreSecretStore maps the keystore alias to the secret ID for retrieving the server keys (private key + certificate). > > * The password of the KeyStoreSecretStore is provided by the FileSystemSecretStore. > **Collapse: Keys stored in PEM file** > > Add the following file to IG, replacing `/path/to/secrets` with your path: > > * Linux > > * Windows > > ``` > $HOME/.openig/config/admin.json > ``` > > ``` > %appdata%\OpenIG\config\admin.json > ``` > > ```json > { > "connectors": [ > { > "port": 8080 > }, > { > "port": 8443, > "tls": "ServerTlsOptions-1" > } > ], > "heap": [ > { > "name": "ServerTlsOptions-1", > "type": "ServerTlsOptions", > "config": { > "keyManager": { > "type": "SecretsKeyManager", > "config": { > "signingSecretId": "key.manager.secret.id", > "secretsProvider": "ServerIdentityStore" > } > } > } > }, > { > "name": "ServerIdentityStore", > "type": "FileSystemSecretStore", > "config": { > "format": "PLAIN", > "directory": "/path/to/secrets", > "suffix": ".pem", > "mappings": [{ > "secretId": "key.manager.secret.id", > "format": { > "type": "PemPropertyFormat" > } > }] > } > } > ] > } > ``` > > Notice how this file differs to that for the keystore-based approach: > > * The ServerIdentityStore is a FileSystemSecretStore. > > * The FileSystemSecretStore reads the keys that are stored as file in the PEM standard format. 4. Start IG: * Linux * Windows ```bash $ /path/to/identity-gateway-7.2.0/bin/start.sh ... ... started in 1234ms on ports : [8080 8443] ``` ```windows C:\path\to\identity-gateway-7.2.0\bin\start.bat ``` By default, the base location for IG configuration files is in `%appdata%\OpenIG`. ### Serve different certificates for TLS connections to different server names This example uses PEM files for self-signed certificates, but you can adapt it to use official (non self-signed) keys and certificates. Before you start, install IG in standalone mode, as described in [Download and start IG in standalone mode](../getting-started/start-product.html#starting-standalone). 1. Locate a directory for secrets, for example, `/path/to/secrets`, and go to it. ```bash $ cd /path/to/secrets ``` 2. Create the following secret key and certificate pair as PEM files: 1. For `ig.example.com`: 1. Create a key and certificate: ```bash $ openssl req \ -newkey rsa:2048 \ -new \ -nodes \ -x509 \ -days 3650 \ -subj "/CN=ig.example.com/OU=example/O=com/L=fr/ST=fr/C=fr" \ -keyout ig.example.com-key.pem \ -out ig.example.com-certificate.pem ``` Two PEM files are created, one for the secret key, and another for the associated certificate. 2. Map the key and certificate to the same secret ID in IG: ```bash $ cat ig.example.com-key.pem ig.example.com-certificate.pem > key.manager.secret.id.pem ``` 2. For servers grouped by a wildcard: 1. Create a key and certificate: ```bash $ openssl req \ -newkey rsa:2048 \ -new \ -nodes \ -x509 \ -days 3650 \ -subj "/CN=*.example.com/OU=example/O=com/L=fr/ST=fr/C=fr" \ -keyout wildcard.example.com-key.pem \ -out wildcard.example.com-certificate.pem ``` 2. Map the key and certificate to the same secret ID in IG: ```bash $ cat wildcard.example.com-key.pem wildcard.example.com-certificate.pem > wildcard.secret.id.pem ``` 3. For other, unmapped servers 1. Create a key and certificate: ```bash $ openssl req \ -newkey rsa:2048 \ -new \ -nodes \ -x509 \ -days 3650 \ -subj "/CN=un.mapped.com/OU=example/O=com/L=fr/ST=fr/C=fr" \ -keyout default.example.com-key.pem \ -out default.example.com-certificate.pem ``` 2. Map the key and certificate to the same secret ID in IG: ```bash $ cat default.example.com-key.pem default.example.com-certificate.pem > default.secret.id.pem ``` 3. Add the following file to IG, replacing `/path/to/secrets` with your path, and then restart IG: * Linux * Windows ``` $HOME/.openig/config/admin.json ``` ``` %appdata%\OpenIG\config\admin.json ``` ```json { "connectors": [ { "port": 8080 }, { "port": 8443, "tls": "ServerTlsOptions-1" } ], "heap": [ { "name": "ServerTlsOptions-1", "type": "ServerTlsOptions", "config": { "sni": { "serverNames": { "ig.example.com": "key.manager.secret.id", "*.example.com": "wildcard.secret.id" }, "defaultSecretId" : "default.secret.id", "secretsProvider": "ServerIdentityStore" } } }, { "name": "ServerIdentityStore", "type": "FileSystemSecretStore", "config": { "format": "PLAIN", "directory": "path/to/secrets", "suffix": ".pem", "mappings": [ { "secretId": "key.manager.secret.id", "format": { "type": "PemPropertyFormat" } }, { "secretId": "wildcard.secret.id", "format": { "type": "PemPropertyFormat" } }, { "secretId": "default.secret.id", "format": { "type": "PemPropertyFormat" } } ] } } ] } ``` Notice the following features of the file: * The [ServerTlsOptions](../reference/ServerTlsOptions.html) object maps two servers to secret IDs, and includes a default secret ID * The secret IDs correspond to the secret IDs in the FileSystemSecretStore, and the PEM files generated in an earlier step. 4. Run the following commands to request TLS connections to different servers, using different certificates: 1. Connect to `ig.example.com`, and note that the certificate subject corresponds to the certificate created for `ig.example.com`: ```bash $ openssl s_client -connect localhost:8443 -servername ig.example.com ... Server certificate -----BEGIN CERTIFICATE----- MII...dZC -----END CERTIFICATE----- subject=/CN=ig.example.com/OU=example/O=com/L=fr/ST=fr/C=fr issuer=/CN=ig.example.com/OU=example/O=com/L=fr/ST=fr/C=fr ``` 2. Connect to `other.example.com`, and note that the certificate subject corresponds to the certificate created with the wildcard, `*.example.com`: ```bash $ openssl s_client -connect localhost:8443 -servername other.example.com ... Server certificate -----BEGIN CERTIFICATE----- MII...fY= -----END CERTIFICATE----- subject=/CN=*.example.com/OU=example/O=com/L=fr/ST=fr/C=fr issuer=/CN=*.example.com/OU=example/O=com/L=fr/ST=fr/C=fr ``` 3. Connect to `unmapped.site.com`, and note that the certificate subject corresponds to the certificate created for the default secret ID: ```bash $ openssl s_client -connect localhost:8443 -servername unmapped.site.com ... Server certificate -----BEGIN CERTIFICATE----- MII..rON -----END CERTIFICATE----- subject=/CN=un.mapped.com/OU=example/O=com/L=fr/ST=fr/C=fr issuer=/CN=un.mapped.com/OU=example/O=com/L=fr/ST=fr/C=fr ``` ## Configure environment variables and system properties for IG in standalone mode Configure environment variables and system properties for IG in standalone mode, as follows: * By adding environment variables on the command line when you start IG. * By adding environment variables in `$HOME/.openig/bin/env.sh`, where `$HOME/.openig` is the instance directory. After changing `env.sh`, restart IG to load the new configuration. ### Start IG with a customized router scan interval By default, IG scans every 10 seconds for changes to the route configuration files. Any changes to the files are automatically loaded into the configuration without restarting IG. For more information about the router scan interval, see [Router](../reference/Handlers.html#Router). The following example overwrites the default value of the Router scan interval to two seconds when you start up IG: * Linux * Windows ```bash $ IG_ROUTER_SCAN_INTERVAL='2 seconds' /path/to/identity-gateway-7.2.0/bin/start.sh ``` ```windows C:\IG_ROUTER_SCAN_INTERVAL='2 seconds' C:\start.bat %appdata%\OpenIG ``` ### Define environment variables for startup, runtime, and stop IG provides the following environment variables for Java runtime options: * IG\_OPTS (Optional) Java runtime options for IG and its startup process, such as JVM memory sizing options. Include all options that are not shared with the `stop` script. The following example specifies environment variables in the `env.sh` file to customize JVM options and keys: * Linux * Windows ```bash # Specify JVM options JVM_OPTS="-Xms256m -Xmx2048m" # Specify the DH key size for stronger ephemeral DH keys, and to protect against weak keys JSSE_OPTS="-Djdk.tls.ephemeralDHKeySize=2048" # Wrap them up into the IG_OPTS environment variable export IG_OPTS="${IG_OPTS} ${JVM_OPTS} ${JSSE_OPTS}" ``` ``` C:\set "JVM_OPTS=-Xms256m -Xmx2048m" C:\set "JSSE_OPTS=-Djdk.tls.ephemeralDHKeySize=2048" C:\set "IG_OPTS=%IG_OPTS% %JVM_OPTS% %JSSE_OPTS%" ``` * JAVA\_OPTS (Optional) Java runtime options for IG include all options that are shared by the `start` and `stop` script. ## Add .jar files for IG extensions in standalone mode IG includes a complete Java [application programming interface](../_attachments/apidocs/index.html) for extending your deployment with customizations. For more information, see [Extend IG through the Java API](../gateway-guide/extending.html#about-custom-extensions) Create a directory to hold .jar files for IG extensions: * Linux * Windows ```bash $HOME/.openig/extra ``` ```windows %appdata%\OpenIG\extra ``` When IG starts up, the JVM loads .jar files in the `extra` directory.