PGX 20.2.2
Documentation

Server Configuration Guide

The PGX web server is configured by editing the $PGX_HOME/conf/server.conf file in the distribution. That file is read by the $PGX_HOME/bin/start-server script.

What Can Be Configured?

Field Type Description Default
working_dirstringthe working directory used by the server to store temporary files. Needs to be writeable by the process which started the server and should not be touched by any other process while the server is running.required
authorization (deprecated)stringpath to the JSON file mapping clients to roles for authorization
Deprecated: deprecated since 20.2, use native PGX authentication instead
server.auth.conf
ca_certsarray of stringlist of files storing trusted certificates (PEM format). If enable_tls is set to false, this field has no effect.[]
ciphersarray of stringlist of cipher suites to be used by the server. For example, [cipher1, cipher2][]
context_pathstringcan be used to change the context path. For example, if you specify port 7007 and context path /pgx, the server will listen on https://localhost:7007/pgx/
enable_client_authentication (deprecated)booleanif true, the client is authenticated during TLS handshake. Please see the TLS protocol for details. This flag does not have any effect if enable_tls is false.
Deprecated: deprecated since 20.2, use native PGX authentication instead
true
enable_tlsbooleanif true, the server enables transport layer security (TLS)true
portintegerport the PGX server should listen on7007
server_certstringthe path to the server certificate to be presented to TLS clients (PEM format). Note that this file must only contain one certificate. If your certificate is a chain and contains a root certificate, add it to ca_certs instead. If enable_tls is set to false, this field has no effectnull
server_private_keystringthe path to the file storing the private key of the server (PEM format). For security reasons, the file must have only Read and Write permissions and only for the owner (600 permissions in a POSIX filesystem), otherwise an error will raise. If enable_tls is set to false, this field has no effectnull
tls_versionstringTLS version to be used by the server. For example, TLSv1.2tlsv1.2

Example Configuration

For $PGX_HOME/conf/server.conf.

{
  "port": 7007,
  "enable_tls": true,
  "enable_client_authentication": true,
  "server_cert": "server_cert.pem",
  "server_private_key": "server_key.pem",
  "ca_certs": [
    "server_cert.pem"
  ],
  "authorization": "server.auth.json"
}

For an example on how to generate the certificates above, you can refer to TLS/SSL Configuration.

Authentication and Roles

On the server-side, client requests are authenticated and authorized using two-way SSL/TLS. By default, PGX defines two roles with different access privileges: USER and ADMIN. You have to assign users to those roles by declaring the client certificate's distinguished name (DN) entry of each user in the server.auth.json file, otherwise no one will be able to connect to the web server; below is an example server.auth.json configuration that maps a client certificate to the admin role.

{
  "authorization": [{
    "dn": "CN=Client, OU=Development, O=Oracle, L=Belmont, ST=California, C=US",
    "admin": true
  }]
}