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 ${INST} start # start server
nevisproxy ${INST} stop # shutdown server
nevisproxy ${INST} restart # shutdown and start server
nevisproxy ${INST} status # show state of server
nevisproxy ${INST} config [proxy|server|log|env] # edit configuration
nevisproxy ${INST} log # display list of logfiles
nevisproxy ${INST} genrules # invokes the request filter rule generator
nevisproxy ${INST} whitelist # invokes the FormNameValueWhiteList rule generator
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
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.
The default installation comes with a test certficate (for frontend connections on navajo.xml) and a template configuration (in web.xml) for testing and ingtegration purposes. Adapt the instance configuration before using it in production!
A list of all available customization parameters can be retrieved with the following command:
nevisproxy inst create help
The list of available parameters:
- 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
- PROXY_CONCURRENCY: Configures the limit of parallel request (MaxClients Apache directive)
- PROXY_SESSION_INACTIVITY: Maximum inactive time interval of a new session
- PROXY_SESSION_LIFETIME: Maximum lifetime of a new session
- PROXY_PUBLIC_KEYSTORE: Configures the SSLCertificateFile Apache directive
- PROXY_CLIENT_TRUSTSTORE: Configures the SSLCACertificateFile Apache directive
- PROXY_CLIENT_KEYFILE: Configures the SSLCertificateKeyFile Apache directive
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
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 test 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:
nevisproxy <instance_name> stop - Removes all files related to the instance:
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> start checks 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.
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
--------------------------------------------------------------------------------
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.