Version: 5.7.x.x Java 8 ELS

Server handling

The command interface

The nevisProxy command-line interface integrates the op and SUDO command-line tools. It consists of the following commands:

$ nevisproxy
usage:
 ${ADMINNAME}${INST} start # start server
 ${ADMINNAME}${INST} stop # shutdown server
 ${ADMINNAME}${INST} restart # shutdown and start server
 ${ADMINNAME}${INST} status # show state of server

 ${ADMINNAME}${INST} config [proxy|server|log|env] # edit configuration
 ${ADMINNAME}${INST} log # display list of logfiles
 ${ADMINNAME}${INST} genrules # invokes the request filter rule generator
 ${ADMINNAME}${INST} whitelist # invokes the FormNameValueWhiteList rule generator

 ${ADMINNAME} inst ${SPCE}# list all instances
 ${ADMINNAME} inst create <name> ${SPCE}# create an instance
 ${ADMINNAME} inst remove <name> ${SPCE}# remove an instance
 ${ADMINNAME} inst exists <name> ${SPCE}# check for existing instance

 ${ADMINNAME} handover ${SPCE}# Create default config/log area, start server
 ${ADMINNAME} pkg ${SPCE}# Show installed package versions

Server instances

Individual server instances are addressed by including the instance name after the nevisproxy command, e.g.:

nevisproxy <instance_name> start

If no instance is specified, the default instance is managed. The instance name 'all' specifies that the corresponding command is executed on all available instances.

nevisproxy start   # starting the default server
nevisproxy all stop   # stopping all instances

Setting up server instances

The command nevisproxy inst lists the names of the configured service instances:

$ nevisproxy inst

Available instances are:
 test
 dev1
 prod

New server instances can be created by the command nevisproxy inst create <instance_name>. There is a "default" instance for easy installation:

$ nevisproxy inst create default

nevisproxy [MESSAGE]: Deploying 71 proxy components....
nevisproxy [MESSAGE]: Setting ownership on /var/opt/nevisproxy/default: User root->nobody / Group root->nobody...
nevisproxy [WARNING]: You need to restart the proxy because ownership has changed.

Setup parameters can be provided on the command line or by passing a setup property file:

nevisproxy inst create default /tmp/setup.properties        # using property file
nevisproxy inst create default PROXY_PUBLIC_HTTP_URL=http://localhost:80  # passing it on the command line

A list of all available customization parameters can be retrieved with the following command:

nevisproxy inst create help

The most important parameters are:

RTOWNER: OS user, under which the server will run
RTGROUP: OS group (should usually be the primary group of the OS user)
PROXY_RT_USER: OS user, under which the nevisProxy child process will run
PROXY_RT_GROUP: OS group, under which the nevisProxy child process will run
PROXY_PUBLIC_HTTP_URL, PROXY_PUBLIC_HTTPS_URL: The URL the server is reachable by a browser (may point to a load balancer)
PROXY_SERVER_HTTP_URL, PROXY_SERVER_HTTPS_URL: The network listener that the server should start
AUTH_SERVER_1_URL: The URL where the authentication service is reachable

The command nevisproxy inst exists <instance_name>is used by configuration scripts to query for already installed server instances. In case the given instance already exists, "true" is returned, else "false":

$ nevisproxy inst exists test
true

$ nevisproxy inst exists nonExistingInst
false

The command nevisproxy handover offers a quick way of installing and starting a nevisProxy default installation. This command performs the following steps:

nevisproxy inst create default
nevisproxy default start

Removing server instances

Removing an instance is possible with the command nevisproxy inst remove <instance_name>. This command:

Performs a backup of the existing instance (into /var/opt/nevisproxy).
Stops the server instance <instance_name> (nevisproxy <instance_name> stop).
Removes all files related to <instance_name> (rm -r /var/opt/nevisproxy/<instance_name>).

$ nevisproxy inst remove default
nevisproxy [MESSAGE]: default>> No server processes running.
--------------------------------------------------------------------------------
Status : DOWN
Component : nevisproxy
Instance : default
Process : navajosv2_4
Ownership : root / nobody
Network port(s) : localhost:443 localhost:80
Filedescriptors : 4096
--------------------------------------------------------------------------------
nevisproxy [MESSAGE]: Removing instance 'default'...
nevisproxy [MESSAGE]: Deleting temporary files in logs...
nevisproxy [MESSAGE]: Deleting temporary files in cache...
nevisproxy [MESSAGE]: Deleting temporary files in run...
nevisproxy [MESSAGE]: Backup instance 'default' as: /var/opt/nevisproxy/default_20190131145347.gtar.gz...
nevisproxy [MESSAGE]: Backup cleanup, found 1 backups, retain INST_BACKUP_LIMIT=5.
nevisproxy [MESSAGE]: Removing instance directory...
nevisproxy [MESSAGE]: Instance 'default' removed successfully.

Starting and stopping server instances

Before starting a server instance, the command nevisproxy <instance_name> startchecks whether the server is already running, and will in that case only provide status information. If the server is not running, the startup procedure may have to request a password required to log in to a HSM box or to decrypt a protected private key.

Starting a server instance

A startup may look as follows:

$ nevisproxy start
nevisproxy [MESSAGE]: default>> Starting server 'navajosv2_4'...
nevisproxy [MESSAGE]: Deploying 27 proxy components....

-------------------------------------------------------------------------
Status    : UP
Component   : nevisproxy / 3.14.0.0
Instance   : default
Process   : navajosv2_4
Ownership   : root / root
Network port(s) : host.nevis.net:443 host.nevis.net:80
Filedescriptors : 8192
Process ID   : 4281 (2 childs)
Logfile(s) :  /var/opt/nevisproxy/default/logs/navajo.log
    /var/opt/nevisproxy/default/logs/access.log
    /var/opt/nevisproxy/default/logs/apache.log
-------------------------------------------------------------------------

Stopping a Server instance

With the command nevisproxy <instance_name> stop a server can be shut down, terminating all running processes. The following output is displayed in stdout:

$ nevisproxy stop
nevisproxy [MESSAGE]: default>> Shutting down server on pid 4281...
nevisproxy [MESSAGE]: default>> Shutting down server on pid 4263...
nevisproxy [MESSAGE]: default>> Server processes 'navajosv2_4' terminated.
-------------------------------------------------------------------------
Status   : DOWN
Component  : nevisproxy / 3.14.0.0
Instance  : default
Process  : navajosv2_4
Ownership  : root / root
Network port(s) : host.nevis.net:443 host.nevis.net:80
Filedescriptors : 4096
Logfile(s)  : /var/opt/nevisproxy/default/logs/navajo.log
    /var/opt/nevisproxy/default/logs/access.log
    /var/opt/nevisproxy/default/logs/apache.log
-------------------------------------------------------------------------

Graceful Stop

A graceful stop will wait for all pending requests to terminate but will not accept any new requests. This may cause problems if you have slow back ends or big downloads. A graceful stop can take several minutes in such cases. In order to enable graceful stop you have to add those entries into the file env.conf:

GRACEFUL_STOP=true
GRACEFUL_STOP_TIMEOUT=<timeout in seconds>

The default GRACEFUL_STOP_TIMEOUT is set to 10 seconds.

Limitation

This feature is currently only supported for on premises installations not using nevisAdmin4.

Restarting a Server instance

The command nevisproxy <instance_name> restart can be used for restarting a server instance. This command is very convenient after applying configuration changes. It executes the following command:

nevisproxy <instance_name> stop
nevisproxy <instance_name> start

$ nevisproxy testInst restart
nevisproxy [MESSAGE]: testInst>> Shutting down server on pid 11568...
nevisproxy [MESSAGE]: testInst>> Server processes 'navajosv2_4' terminated.
nevisproxy [MESSAGE]: testInst>> Starting server 'navajosv2_4'...
--------------------------------------------------------------------------------
Status : UP
Component : nevisproxy/ 3.14.0.0
Instance : testInst
Process : navajosv2_4
Ownership : root / nobody
Network port(s) : localhost:80
Filedescriptors : 8192
Process ID : 13973
Logfile(s) : /var/opt/nevisproxy/testInst/logs/navajo.log
 /var/opt/nevisproxy/testInst/logs/access.log
 /var/opt/nevisproxy/testInst/logs/apache.log
--------------------------------------------------------------------------------

note

If graceful stop is enabled, then restarting the instance will do a graceful stop as well.

Retrieving status information

The command nevisproxy <instance-name> status displays basic information on the server's current runtime state. A server that is not running issues the following output:

$ nevisproxy support status
--------------------------------------------------------------------------------
Status : DOWN
Component : nevisproxy/ 3.14.0.0
Instance : support
Process : navajosv2_4
Ownership : root / nobody
Network port(s) : localhost:80
Filedescriptors : 4096
Logfile(s) : /var/opt/nevisproxy/support/logs/navajo.log
 /var/opt/nevisproxy/support/logs/access.log
 /var/opt/nevisproxy/support/logs/apache.log
--------------------------------------------------------------------------------

Configuration of server instances

The nevisProxy command interface offers the following commands for server configuration:

Command	Description
nevisproxy <instance_name> config	Use this command to edit the web-app configuration in the file web.xml. nevisProxy specific functionality such as authentication support, role-based user access, and reverse proxy functionality is implemented as a set of filters and servlets . These servlets and filters are configured via the web.xml file. The web.xml must be written in accordance with the specifications in the web-app.dtd file.
nevisproxy <instance_name> config server	Use this command to edit the container configuration in the file navajo.xml, the configuration file for the servlet container. The file navajo.xml is described in the navajo.dtd file. For a more detailed description, see the chapter Servlet container.
nevisproxy <instance_name> config log	Use this command to edit the tracing configuration in the file bc.properties. The bc configuration file bc.properties permits customization of system parameters, mainly tracing. For the complete list of configurable properties, see the chapter Debugging.
nevisproxy <instance_name> config env	Use this command to edit additional environment parameters in the file env.conf. The configuration file env.conf permits definition of additional environment variables (e.g., for PKCS#11).

All of these commands open the respective configuration files with the editor set in the environment variable EDITOR. If this variable is not set, then rvi (restricted vi) is used. You therefore need to know vi commands to be able to edit the files. If you are not familiar with vi, enter ":q!" to quit the editor without any changes.

Server handling

The command interface​

Server instances​

Setting up server instances​

Removing server instances​

Starting and stopping server instances​

Starting a server instance​

Stopping a Server instance​

Graceful Stop​

Restarting a Server instance​

Retrieving status information​

Configuration of server instances​