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_dir`	`string`	the 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`	`string`	path to the JSON file mapping clients to roles for authorization	`server.auth.conf`
`ca_certs`	`array of string`	list of files storing trusted certificates (PEM format). If `enable_tls` is set to `false`, this field has no effect.	`[]`
`ciphers`	`array of string`	list of cipher suites to be used by the server. For example, [cipher1, cipher2]	`[]`
`context_path`	`string`	can 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`	`boolean`	if `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`.	`true`
`enable_tls`	`boolean`	if `true`, the server enables transport layer security (TLS)	`true`
`port`	`integer`	port the PGX server should listen on	`7007`
`server_cert`	`string`	the 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 effect	`null`
`server_private_key`	`string`	the 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 effect	`null`
`tls_version`	`string`	TLS version to be used by the server. For example, TLSv1.2	`tlsv1.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
  }]
}