Version: 3.14.x.x LTS

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:
 nevisproxy            # get this usage
 nevisproxy start        # start nevisproxy server
 nevisproxy    # shutdown nevisproxy server (graceful: wait 300s for sessions)
 nevisproxy restart       # shutdown and start nevisproxy server
 nevisproxy     # show state of nevisproxy server
 nevisproxy test        # check, if server is running

 nevisproxy     # edit proxied resources configuration (web.xml)
 nevisproxy config server      # edit server configuration (navajo.xml)
 nevisproxy config log      # edit tracing configuration (bc.properties)
 nevisproxy config env      # edit additional environment parameters (env.conf)
 nevisproxy config export <tarfile>   # export configurations in <tarfile>
 nevisproxy config import <tarfile>   # import configurations from <tarfile>
 nevisproxy config backup list    # list available backups
 nevisproxy   # backup actual configurations
 nevisproxy config backup remove <stamp>  # remove specified backup
 nevisproxy   # restore last or specified backup

 nevisproxy cert         # display PKI setup for this server
 nevisproxy cert create       # create certificate for this server
 nevisproxy cert delete       # delete certificate of this server

 nevisproxy log         # display list of logfiles
 nevisproxy     # display errors in logfiles (default: all)
 nevisproxy    # display logfiles (default: all)
 nevisproxy     # start tailing logfile (default: server)
 nevisproxy log start       # display new server messages since start
 nevisproxy logmgr reopen      # reopen logfiles handled by logmgr
 nevisproxy genrules        # invokes the request filter rule generator
 nevisproxy whitelist       # invokes the FormNameValueWhiteList rule generator

 nevisproxy      # collect support info from servers and host
 nevisproxy checklibs  # checks library dependency and prints all unresolved libraries

 nevisproxy inst           # list all instances
 nevisproxy inst create <name>       # create an instance
 nevisproxy inst remove <name>        # remove an instance
 nevisproxy inst exists <name>        # check for existing instance
 nevisproxy handover          # Create default config/log area, start server
 nevisproxy pkg            # Show installed package versions
 nevisproxy pkg activate <version>       # Activate specified version of package
 nevisproxy memlimit        # Shows / configures the memory limitation

 [1] Optional: Specify 'help', 'try', 'force', a setup.conf file or a list of PARAM=value
 'nevisproxy inst create test help' displays the possible setup parameters.

Server instances

nevisproxy <instance_name> start

If no instance is explicitly 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: Deploying 71 proxy components....
nevisproxy: Setting ownership on /var/opt/nevisproxy/default: User root->nobody / Group root->nobody...
nevisproxy: 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 (including access to log files)
RTGROUP: OS group (should usually be the primary group of the OS user)
PROXY_RT_OWNER: 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: 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: Removing instance 'default'...
nevisproxy: Deleting temporary files in logs...
nevisproxy: Deleting temporary files in cache...
nevisproxy: Deleting temporary files in run...
nevisproxy: Backup instance 'default' as: /var/opt/nevisproxy/default_20190131145347.gtar.gz...
nevisproxy: Backup cleanup, found 1 backups, retain INST_BACKUP_LIMIT=5.
nevisproxy: Removing instance directory...
nevisproxy: 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.

A startup may look as follows:

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

-------------------------------------------------------------------------
Status    : UP
Component   : nevisproxy / 3.14.0.0
Instance   : default
Process   : navajosv2_4
Ownership   : root / root
Network port(s) : adnws058.zh.adnovum.ch:443 adnws058.zh.adnovum.ch: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
-------------------------------------------------------------------------

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: default>> Shutting down server on pid 4281...
nevisproxy: default>> Shutting down server on pid 4263...
nevisproxy: 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) : adnws058.zh.adnovum.ch:443 adnws058.zh.adnovum.ch: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
-------------------------------------------------------------------------

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

nevisproxy <instance_name> stop
nevisproxy <instance_name> start

$ nevisproxy testInst restart
nevisproxy: testInst>> Shutting down server on pid 11568...
nevisproxy: testInst>> Server processes 'navajosv2_4' terminated.
nevisproxy: 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
--------------------------------------------------------------------------------

Deprecated

The command "nevisproxy <instance_name> reinit" is deprecated and will be no longer supported. Instead, use the command "nevisproxy <instance-name> restart". 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.
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 in rvi (restricted vi). You therefore need to know vi commands to be able to edit the file. If you do not vi, enter ":q!" for quitting the editor without any changes.

Saving and reloading server configurations

It is possible to store and reload the configuration of a nevisProxy instance. With the export command nevisproxy <instance_name> config export <tar_file> the current configuration can be saved in the given tar file, while with the command nevisproxy <instance_name> config import <tar_file> it can be reloaded.

$ nevisproxy default config export defaultConf
nevisproxy: Exporting configuration to /tmp/conf/defaultConf...
nevisproxy: Export done.

The exported tar file contains the following configuration files in case of a default instance:

$ tar -tf /home/veszner/projects/navajo/defaultConf
conf/
conf/csrf-inject.js
conf/navajo_1_0.dtd
conf/bc.properties.last
conf/nevisproxy-krb5.conf
conf/isi3web.properties
conf/env.conf
conf/navajo.management.xml
conf/management.dtd
conf/mime.types
conf/navajo.xml
conf/web-app_2_3.dtd
conf/unblu.conf
conf/bc.properties
conf/nevisproxy_httpd.conf
work/WEB-INF/web.xml
work/WEB-INF/web.xml.last

Importing a tar file as configuration:

$ nevisproxy default config import defaultConf
nevisproxy: Backup existing configuration.
nevisproxy: Exporting configuration to /var/opt/nevisproxy/default/backup/conf.2019-01-31-16:33:21.tar...
nevisproxy: Export done.
nevisproxy: Backup done.
nevisproxy: Importing configuration.
nevisproxy: Import done.

It is also possible to create backups of the current configuration and reload the backups if it is needed. Use the command nevisproxy <instance_name> config backup to create a backup. This will save the configuration with a time stamp and with the optional description:

$ nevisproxy icf default backup save before upgrade
nevisproxy: Backup existing configuration.
nevisproxy: Exporting configuration to /var/opt/nevisproxy/default/backup/conf.2019-01-31-16:37:42.tar...
nevisproxy: Export done.
nevisproxy: Backup done.

The already existing backups can be listed with the command nevisproxy <instance_name> config backup list:

$ nevisproxy default config backup list

Timestamps of backups from /var/opt/nevisproxy/default/backup/ for config restore:
2019-01-31-16:33:21 # automatic backup, due to config import
2019-01-31-16:37:15 #
2019-01-31-16:37:42 # save before upgrade
2019-01-31-16:38:43 # automatic backup, due to config import

Restoring the configuration can be done with the command nevisproxy <instance_name> config restore. If no time stamp is added, it will restore the latest backup configuration:

$ nevisproxy default config restore 2019-01-31-16:33:21
nevisproxy: Backup existing configuration.
nevisproxy: Exporting configuration to /var/opt/nevisproxy/default/backup/conf.2019-01-31-16:38:43.tar...
nevisproxy: Export done.
nevisproxy: Backup done.
nevisproxy: Importing configuration.
nevisproxy: Import done.

How to recreate an instance

After upgrading a nevisProxy release, the recreation of an instance may be needed. For more information, see the chapters Generating a configuration snapshot in the nevisAdmin reference guide.