Setting up Failover of Pleasant Password Server

1. You will require two more hosts in addition to your existing PPASS host:

   • One to run the Nginx software (which we will call server_balance)

   • The backup server (server2)

2. Download Nginx for server_balance:

   • You can download it from https://nginx.org/ and unzip directly into the folder you want to install it to (e.g. C:\Program Files (x86)\nginx). There is no separate installer program.

3. Install a copy of Pleasant Password Server on server2.

4. Check the ports that Pleasant Password Server is using.

   • Run the Pleasant Service Configuration tool
   • Look under Port Configuration to determine the primary port the service is listening on (the service port). The default is 10001.

   • If you are using the SSO Proxy service, go to the SSO Proxy tab in the Pleasant Password Server web client as admin to check which port the SSO proxy server is listening on (the SSO proxy port). The default is 8877.

5. On server_balance, run Windows Firewall setup and make sure that TCP connections to the service port (and, if applicable, the SSO proxy port) are allowed.

6. You will need a certificate for https connections to work. We recommend using a signed third-party certificate.

   • Nginx requires it in the form of two separate files: the certificate proper and its private key, with no passphrase.

   • If you already have a certificate in the Windows Certificate Store, you can export it as a .pfx file and then split it into the requisite files using OpenSSL (found at https://www.openssl.org/ -- Windows binaries are under About > Binaries) with the following commands:

     • openssl pkcs12 -in filename.pfx -clcerts -nokeys -out cert.pem  (to generate the certificate file)
     • openssl pkcs12 -in filename.pfx -nocerts -out key.pem  (to generate the private key file, still with passphrase)

     • openssl rsa -in key.pem -out server.key  (to strip the passphrase from the private key)

7. Edit the file \conf\nginx.conf in your Nginx installation folder and replace its contents with the following (replacing IP addresses and ports with the relevant values for your Pleasant Password Servers):

   # Note that even Windows paths must be done with forward slashes, e.g. C:\ProgramData\
   
   worker_processes  1;
   
   error_log  C:\ProgramData\nginx_error.log;
   
   events {
       worker_connections  1024;
   }

   client_max_body_size 20M;
   proxy_buffer_size 128k;
   proxy_buffers 4 256k;
   proxy_busy_buffers_size 256k;
   
   http {
       upstream ppass_failover {
           # specify main and backup server IPs or hostnames with port number (default 10001)
           # max_fails is the number of failed requests before Nginx switches to the backup
           # timeout is how long before Nginx will try that server again after failure
           server server1:10001 max_fails=1 fail_timeout=60s;
           server server2:10001 backup;
       }
   
       server {
           # specify the port you want Nginx to listen on; it does not have to match your PPASS
           # we recommend using port 443 for most reliability
           # make sure the error 497 redirect matches the listen port
           listen 443 ssl;
           ssl_certificate C:\path\to\your\cert.pem;
           ssl_certificate_key C:\path\to\your\server.key;
           error_page 497 https://$host:443$request_uri;
   
       location / {
           proxy_pass https://ppass_failover;
           proxy_set_header Host $host;
           }
       }
   
       upstream ppass_failover_proxy {
           # specify main and backup server IPs or hostnames with port number (default 8877)
           server server1:8877 max_fails=1 fail_timeout=60s;
           server server2:8877 backup;
       }
   
       server {
           # specify the port you want Nginx to listen on; it does not have to match your PPASS
           listen 8877;
           ssl_certificate C:\path\to\your\cert.pem;
           ssl_certificate_key C:\path\to\your\server.key;
           error_page 497 https://$host:8877$request_uri;
   
       location / {
           proxy_pass https://ppass_failover_proxy;
           proxy_set_header Host $host;
           }
       }
   }

    

8. Run your Nginx server with the command "start nginx".

9. You should now be able to access your Pleasant Password Server and SSO Proxy Server through your load balancing server! For example:

   • https://server_balance

   • https://server_balance:8877

If you make any changes to nginx.conf while the Nginx server is running, you will need to reload the configuration with the command "nginx -s reload".