--- title: Starting PingAuthorize Policy Editor description: For a manual software installation, use the start-server command-line interface (CLI) command to start the Policy Editor. Also, you can use environment variables to override configuration variables at startup. component: pingauthorize version: 11.0 page_id: pingauthorize:pingauthorize_server_administration_guide:paz_start_pe canonical_url: https://docs.pingidentity.com/pingauthorize/11.0/pingauthorize_server_administration_guide/paz_start_pe.html revdate: May 23, 2024 section_ids: overriding-the-configuration-at-startup: Overriding the configuration at startup environment-variables-you-can-use-to-override-configuration-variables: Environment variables you can use to override configuration variables example-use-an-existing-ssl-certificate-for-https-connections: "Example: Use an existing SSL certificate for HTTPS connections" example-override-the-configured-https-port: "Example: Override the configured HTTPS port" override_policy_db_location: "Example: Override the configured policy database location" troubleshooting-startup-errors: Troubleshooting startup errors --- # Starting PingAuthorize Policy Editor For a manual software installation, use the `start-server` command-line interface (CLI) command to start the Policy Editor. Also, you can use environment variables to override configuration variables at startup. To start PingAuthorize Policy Editor, use the `bin/start-server` command. ```shell $ bin/start-server ``` | | | | - | --------------------------------------------------------------------------------- | | | You can run `bin/start-server` manually from the command line or within a script. | ## Overriding the configuration at startup You can override a number of Policy Editor settings by defining specific environment variables before starting the server. By overriding some of the configuration, you can redefine certain aspects of the configuration without re-running the `setup` tool. To override the configuration, stop the Policy Editor, define one or more of the environment variables, and restart the Policy Editor. ## Environment variables you can use to override configuration variables The following table lists the environment variables that you can define, sorted based on expected frequency of use with related variables grouped together. | Environment variable | Example value | Description | | ----------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PING_EXTERNAL_BASE_URL` | pap.example.com:9443 | The Policy Editor hostname and port.PingAuthorize uses this value to construct AJAX requests.The port value must match the value of `PING_PORT` for web browsers to pass cross-origin resource sharing (CORS) *(tooltip: \
\

A mechanism to allow restricted resources, such as images and scripts, on a web page to be requested from a domain outside of the domain from which the first resource was served.\

\
)* checks. | | `PING_PORT` | 443 | The Policy Editor HTTPS port.The server binds to this listen port. | | `PING_KEYSTORE_TYPE` | JKS | The Policy Editor's key store type. Valid values include `JKS` and `PKCS12`. | | `PING_KEYSTORE_PATH` | `/path/to/keystore.jks` | The path to the Policy Editor's key store. | | `KEYSTORE_PIN_FILE` | `/path/to/keystore.pin` | The path to the Policy Editor's key store PIN file. When present, this environment variable takes precedence over `PING_KEYSTORE_PASSWORD` when validating and presenting the server certificate *(tooltip: \
\

A digital file used for identity verification and other security purposes. The certificate, which is often issued by a CA, contains a public key, which can be used to verify the originator's identity.\

\
)*. The key store PIN value itself does not persist to the `configuration.yml` file and is not visible on the command-line. For a more complete example, see the Demo mode (custom SSL certificate) tab of [Installing the Policy Editor non-interactively](../installing_and_uninstalling_pingauthorize/paz_install_pe_noninteractive.html). | | `PING_KEYSTORE_PASSWORD` | password1234 | The Policy Editor's key store password. | | `PING_CERT_ALIAS` | server-cert | The alias for the Policy Editor's server certificate. | | `PING_SHARED_SECRET` | pingauthorize | The Policy Editor's shared secret, which PingAuthorize Server needs to make policy requests to the Policy Editor. | | `PING_OIDC_​CONFIGURATION_ENDPOINT` | https\://oidc.example.com:9031/.well-known/openid-configuration | The OpenID Connect (OIDC) *(tooltip: \
\

An authentication protocol built on top of OAuth that authenticates users and enables clients (relying parties) of all types to request and receive information about authenticated sessions and users. OIDC is extensible, allowing clients to use optional features such as encryption of identity data, discovery of OpenID Providers (OAuth authorization servers), and session management.\

\
)* provider's discovery Uniform Resource Locator (URL) *(tooltip: \
\

Identifies a resource according to its internet location.\

\
)*. Used when the Policy Editor is set up in OIDC mode. | | `PING_SCOPE` | openid email profile additional\_scope | Space-separated OIDC scope *(tooltip: \
\

In OAuth, a parameter on an access request and resulting, issued access token that specifies a limitation or limitations on access to the protected resource or resources.\

\
)* that the Policy Editor requests during authorization and validates during token verification. Used to override the requested OIDC scopes configured during server setup. | | `PING_OIDC_TLS_VALIDATION` | NONE | The OIDC Transport Layer Security (TLS) validation setting. Set to `NONE` to configure the Policy Editor to accept self-signed Secure Sockets Layer (SSL) *(tooltip: \
\

A protocol for authenticated and encrypted links between networked machines, typically over HTTPS. SSL was deprecated in 1999 in favor of Transport Layer Security (TLS).\

\
)* certificates from the OIDC provider and skip hostname verification.Used when the Policy Editor is set up in OIDC mode. For non-production use only. | | `PING_CLIENT_ID` | 8cb9f2c9-c366-47e0-9560-db2132b2d813 | The Policy Editor's client ID with the OIDC provider. Used when the Policy Editor is set up in OIDC mode. | | `PING_USERNAMES` | admin, user1, user2 | Used in demo mode. A comma-separated list of usernames accepted by the Policy Editor for sign on. | | `PING_H2_FILE` | /Symphonic | The path to the policy database H2 file.Leave off the `.mv.db` extension. | | `PING_DB_APP_USERNAME` | db\_user | The username the application uses to access the server database. | | `PING_DB_APP_PASSWORD` | Pa$$w0rd!23 | The password the application uses to access the server database. | | `PING_DB_ADMIN_USERNAME` | db\_admin | The username the `setup` tool uses when upgrading the policy database (H2 only). | | `PING_DB_ADMIN_PASSWORD` | $3cr3T | The password the `setup` tool uses when upgrading the policy database (H2 only). | | `PING_OPTIONS_FILE` | `/path/to/options.yml` | The path to an `options.yml` file to use with the Policy Editor's setup tool. | | `PING_ADMIN_PORT` | 9444 | The admin port where the H2 database backup endpoint *(tooltip: \
\

One end in a communication channel, typically a URI.\

\
)* is available.The policy administration point (PAP) uses this endpoint to back up the H2 database, which stores your Trust Framework, policies, commit history, and other data.Related environment variables: `PING_BACKUP_SCHEDULE`, `PING_H2_BACKUP_DIR` | | `PING_BACKUP_SCHEDULE` | 0 0 0 \* \* ? | The periodic database backup schedule for the Policy Editor (also known as the PAP) in the form of a `cron` expression. The PAP evaluates the expression against the system timezone. For the PingAuthorize Docker images, the default timezone is UTC.The default is `0 0 0 * * ?`, which is midnight every day.For more information, see .quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html//\[Quartz 2.3.0 cron format].Related environment variables: `PING_ADMIN_PORT`, `PING_H2_BACKUP_DIR` | | `PING_H2_BACKUP_DIR` | `/opt/out/backup` | The directory in which to place the H2 database backup files.The default is `[.parmname]`SERVER\_ROOT`/policy-backup`.Related environment variables: `PING_ADMIN_PORT`, `PING_BACKUP_SCHEDULE` | | `PING_ENABLE_API_HTTP_CACHE` | false | Controls the API [HTTP caching](paz_http_caching.html) feature for the run-time instance of the server. APIs are cached by default.Provide this environment variable at run time and set it to `false` to disable API HTTP caching for that server instance. | | `PING_DISABLE_SNI_HOSTNAME_CHECKS` | false | Determines whether PingAuthorize performs SNI hostname checks. By default, these checks are disabled. | ## Example: Use an existing SSL certificate for HTTPS connections This example shows how to provide the environment variables necessary for the Policy Editor to present a different SSL certificate than the one configured during `setup`: ``` env PING_CERT_ALIAS= \ PING_KEYSTORE_PATH= \ PING_KEYSTORE_TYPE= \ KEYSTORE_PIN_FILE= \ bin/start-server ``` ## Example: Override the configured HTTPS port In this example, the Policy Editor is started using an HTTPS port that differs from the value configured during installation. The override requires two environment variables: `PING_PORT` and `PING_EXTERNAL_BASE_URL`. ```shell $ bin/stop-server $ export PING_PORT=9443 PING_EXTERNAL_BASE_URL=pap.example.com:9443; bin/start-server ``` ## Example: Override the configured policy database location This example changes the policy database location. The new value must be a policy server Java database connectivity (JDBC) *(tooltip: \
\

A Java API that allows Java programs to interact with databases.\

\
)* connection string for an H2 embedded database. To use a file located at `/opt/shared/Symphonic.mv.db`, use the following commands: ```shell $ bin/stop-server $ export PING_H2_FILE=/opt/shared/Symphonic $ bin/setup demo {ADDITIONAL_ARGUMENTS} && bin/start-server ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------ | | | Even though the actual filename of the policy database includes the extension `.mv.db`, the JDBC connection string excludes the extension. | If `/opt/shared/Symphonic.mv.db` does not exist, `setup` creates a new one. If the file does exist and is from an older PingAuthorize server, `setup` updates the file to the latest version. ## Troubleshooting startup errors The `bin/start-server` command prints an error message if it detects that an error has occurred during startup. For more information about the error, see the `logs/authorize-pe.log` and `logs/start-server.log` files.