Installing nevisAdapt

Hardware recommendations

We recommend running nevisAdapt on a system with at least 4 CPU cores and 8 GB of RAM.

caution

If you use the extended version of the Geolocation database (which also includes the GPS coordinates), it is recommended that you allocate at least 5 GB memory for the nevisAdapt service. The size of the database file should be less than 500 MB.

The installation of the nevisAdapt service includes the following software packages:

Package name	Component	Remarks
nevisadapt-<version>.noarch.rpm	nevisAdapt service	- Contains an embedded Tomcat servlet container.- Contains the database schema.
nevisdetectcl-<version>.noarch.rpm	nevisAdapt AuthStates	Contains the AuthStates DeviceCookieAuthState and NevisAdaptAuthState.

Install all software packages with the user "nvauser" and the group "nvbgroup". As a precondition, this user and group must exist.

File system layout

The table below describes the layout of the nevisAdapt file system:

Path	Description	Type
/opt/nevisadapt/	Read-only base directory of the installation, owned by the user "nevisdetect" and group "nevisdetect".	Installation directory
/opt/nevisadapt/template/conf/	Templates for runtime configuration files in /var/opt/nevisadapt/conf/
/opt/nevisadapt/util/nevisadapt	Command line interface (CLI) for administration. A link in /usr/bin is created during installation.
/opt/nevisadapt/util/util.sh	Helper script used during the post-install- and pre-remove-phase of the package.
/opt/nevisadapt/bin/nevisadapt-exec.jar	Spring Boot jar containing the application. As of nevisAdapt 7.2605.0.5 (Spring Boot 4), this is a plain jar and can no longer be invoked directly (for example ./nevisadapt-exec.jar); it must be started via the nevisadapt-server wrapper script or an explicit java -jar call.
/opt/nevisadapt/bin/nevisadapt-server	Wrapper script that sources env.conf (JAVA_HOME, JAVA_OPTS) and starts nevisadapt-exec.jar via java -jar. Used as ExecStart in the shipped nevisadapt.service systemd unit.
/opt/nevisadapt/template/conf/env.conf	Template for /var/opt/nevisadapt/conf/env.conf
/usr/lib/systemd/system/nevisadapt.service	Systemd unit file for the component.
/usr/bin/nevisadapt	Alias for /opt/nevisadapt/util/nevisadapt.
/var/opt/nevisadapt/	Read/write directory of the installation, owned by the user "nevisdetect" and group "nevisdetect".	Spool directory
/var/opt/nevisadapt/conf/env.conf	Configuration file for the init.d service.
/var/opt/nevisadapt/conf/nevisadapt.properties	nevisAdapt service configuration file.
/var/opt/nevisadapt/conf/logback.xml	logback configuration file.
/var/opt/nevisadapt/conf/riskscore-mapping.properties	Configuration file for the risk score mapping.
/var/opt/nevisadapt/conf/role-to-permission.properties	Role-to-permission mapping file.
/var/opt/nevisadapt/logs/nevisadapt.log	Log file(s).
/var/opt/nevisadapt/logs/nevisadapt.stdout	The system redirects stdout to this file.

Software package installation - nevisAdapt service

To install the nevisAdapt service, proceed with the next steps.

The installation of the nevisAdapt plug-in is described further below.

1. Execute the following commands to install the component's software package:

rpm -i nevisadapt-<version>.noarch.rpm
rpm -i nevisdetectcl-<version>.noarch.rpm

During the installation, the following happens:

• Registration of the component as a systemd service with the name nevisadapt. The shipped nevisadapt.service unit sets WorkingDirectory=/var/opt/nevisadapt and User=nvauser, and its ExecStart points to the /opt/nevisadapt/bin/nevisadapt-server wrapper script (not directly to the jar).

• Creation of the spool directory structure (if not already existing).

• Extraction of the following files from the file /opt/nevisadapt/bin/nevisadapt-exec.jar:

  • /var/opt/nevisadapt/conf/nevisadapt.properties
  • /var/opt/nevisadapt/conf/env.conf
  • /var/opt/nevisadapt/conf/logback.xml

2. Administer the component with the following commands:

service nevisadapt start
service nevisadapt status
service nevisadapt stop
service nevisadapt restart

The configuration of the runtime environment of a service is located in the file env.conf.

caution

As of nevisAdapt 7.2605.0.5, nevisadapt-exec.jar is a plain (non-executable) Spring Boot jar and can no longer be run directly (for example ./nevisadapt-exec.jar). Instances are started through the nevisadapt.service systemd unit, whose ExecStart points to the /opt/nevisadapt/bin/nevisadapt-server wrapper script.

If you maintain a custom systemd unit for nevisAdapt, stop pointing ExecStart directly at nevisadapt-exec.jar. Set ExecStart=/opt/nevisadapt/bin/nevisadapt-server and WorkingDirectory=/var/opt/nevisadapt instead so that env.conf is found, and move any custom JAVA_HOME/JAVA_OPTS into that instance's env.conf.

The following sample code block illustrates the installation of the nevisAdapt service:

Installation of the nevisAdapt service

# variables used by the wrapper script /opt/nevisadapt/bin/nevisadapt-server,
# which is invoked by the nevisadapt.service systemd unit and starts
# /opt/nevisadapt/bin/nevisadapt-exec.jar via "java -jar"
APP_NAME=nevisadapt
JAVA_OPTS="-Xmx1024M -XX:+UseG1GC -Dlogback.configurationFile=/var/opt/nevisadapt/conf/logback.xml"
LOG_FOLDER=/var/opt/nevisadapt/logs
LOG_FILENAME=nevisadapt.stdout
  
# variables used by the application i.e. logback and spring
export NEVISADAPT_SPOOL_DIR=/var/opt/nevisadapt
export NEVISADAPT_APP_NAME=nevisadapt

Uninstalling the software package

To uninstall the nevisAdapt components, run the following commands:

rpm -e nevisadapt-<version>.noarch
rpm -e nevisdetectcl-<version>.noarch

During the uninstalling process, the service is stopped and deregistered. The spool directory is not modified, so a subsequent installation will have the same configuration.

Considerations for Kubernetes deployment

nevisAdapt requires the real source IP addresses of the login attempts in order to determine various risk factors such as geolocation or blacklisting. The ingress must be able to provide this data by populating the X-Original-Forwarded-For request header.

Internal Kubernetes services

If the container orchestration happens with first-party services, enable the PROXY protocol in NGINX (described in Accepting the PROXY Protocol) and add the following command to the setup configuration for the ingress rules:

start {
  ...
  
  proxy_set_header X-Original-Forwarded-For $proxy_protocol_addr;
  
  ...
}

Kubernetes deployment with nevisAdmin4

If the container orchestration happens with nevisAdmin4, add a new NGINX Ingress Settings to the nevisProxy Instance under Advanced Settings / Additional Settings.

Add a new annotation with the key nginx.ingress.kubernetes.io/configuration-snippet and value proxy_set_header X-Original-Forwarded-For $proxy_protocol_addr;.