Initial Setup

This chapter explains how to set up nevisAdmin 4 after you have installed the software.

Database Setup

nevisAdmin 4 needs a local or a remote SQL database (MariaDB, PostgreSQL), which you can install either manually with the RPM-based installation or through nevisAppliance.

The nevisAppliance admin4 image includes a MariaDB instance that should be up and running after image installation and reboot.

MariaDB

Perform the next steps to set up the database:

1. Change the password of the root user interactively:

   mysqladmin -u root password

2. Connect and create a user and database for nevisAdmin 4, by running the following code:

   Uncomment the CREATE USER and GRANT lines if the database is not running on the same machine as nevisAdmin 4.

   In a production setup, give the 2 users different passwords by changing the IDENTIFIED BY.

   # Enter the password when asked
   mysql -u root -p <<SQL
     CREATE DATABASE nevisadmin4
     CHARACTER SET = 'utf8mb4'
     COLLATE = 'utf8mb4_unicode_ci';
   
     CREATE USER 'na4_owner'@'localhost' IDENTIFIED BY 'owner_password';
     GRANT ALL PRIVILEGES ON nevisadmin4.* TO 'na4_owner'@'localhost' WITH GRANT OPTION;
   # CREATE USER 'na4_owner'@'%' IDENTIFIED BY 'owner_password';
   # GRANT ALL PRIVILEGES ON nevisadmin4.* TO 'na4_owner'@'%' WITH GRANT OPTION;
   
     CREATE USER 'na4_user'@'localhost' IDENTIFIED BY 'user_password';
     GRANT SELECT, INSERT, DELETE, UPDATE, EXECUTE ON nevisadmin4.* TO 'na4_user'@'localhost';
   # CREATE USER 'na4_user'@'%' IDENTIFIED BY 'user_password';
   # GRANT SELECT, INSERT, DELETE, UPDATE, EXECUTE ON nevisadmin4.* TO 'na4_user'@'%';
   SQL

3. Set the maximum allowed package size by adding the following line in /etc/my.cnf under the section [mariadb] (or [mysqld] if you have an older database version):

   max_allowed_packet=100M

4. Database Connection:

   Configure the database connection in /var/opt/nevisadmin4/conf/nevisadmin4.yml.

   db:
    datasource:
      url: jdbc:mariadb://localhost:3306/nevisadmin4
      username: na4_user
      password: user_password
    migration:
      username: na4_owner
      password: owner_password
    auto-migration:
      enabled: true

PostgreSQL

1. Setup database:

   In a production setup, give the 2 users different passwords by changing the encrypted password.

   -- create users
   CREATE USER "na4_owner" with encrypted password 'owner_password';
   CREATE USER "na4_user" with encrypted password 'user_password';
   
   -- Optional step: grant role to root user so it has access on servers where root is not a real superuser, e.g. Azure
   -- GRANT "na4_owner" TO "{replace-with-root-user}";
   -- Optional step: required for MS/Azure/PostgreSQL flexy server to avoid error: 'Only members of azure_pg_admin are allowed to use CREATE EXTENSION'
   -- GRANT "azure_pg_admin" TO "na4_owner";
   
   -- create database
   CREATE DATABASE "nevisadmin4"
       with
       OWNER="na4_owner"
       ENCODING=UTF8
       LC_COLLATE="C"
       TEMPLATE template0;
   
   -- create schema and adjust search_path
   \connect nevisadmin4;
   CREATE SCHEMA IF NOT EXISTS "na4_owner" authorization "na4_owner";
   ALTER ROLE "na4_owner" IN DATABASE nevisadmin4 SET search_path TO "na4_owner";
   ALTER ROLE "na4_user" IN DATABASE nevisadmin4 SET search_path TO "na4_owner";
   
   -- grant privileges for standard user
   GRANT USAGE ON SCHEMA "na4_owner" to "na4_user";
   GRANT CONNECT ON DATABASE nevisadmin4 TO "na4_user";
   GRANT SELECT, INSERT, UPDATE, DELETE, TRIGGER ON ALL TABLES IN SCHEMA "na4_owner" TO "na4_user";
   GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA "na4_owner" TO "na4_user";
   GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA "na4_owner" TO "na4_user";
   
   -- default privileges for standard user for future tables
   ALTER DEFAULT PRIVILEGES FOR USER "na4_owner" IN SCHEMA "na4_owner"
   GRANT SELECT, INSERT, UPDATE, DELETE, TRIGGER ON TABLES TO "na4_user";
   ALTER DEFAULT PRIVILEGES FOR USER "na4_owner" IN SCHEMA "na4_owner"
   GRANT USAGE, SELECT ON SEQUENCES TO "na4_user";
   ALTER DEFAULT PRIVILEGES FOR USER "na4_owner" IN SCHEMA "na4_owner"
   GRANT EXECUTE ON FUNCTIONS TO "na4_user";

2. Database Connection:

   Configure the database connection in /var/opt/nevisadmin4/conf/nevisadmin4.yml.

   db:
    datasource:
      url: jdbc:postgresql://localhost:5432/nevisadmin4
      username: na4_user
      password: user_password
    migration:
      username: na4_owner
      password: owner_password
    auto-migration:
      enabled: true

3. Postgres Profile:

   Enable the postgres profile in /var/opt/nevisadmin4/conf/env.conf by extending the JAVA_OPTS.

   -Dnevisadmin.profiles=jpa,postgres,jwthmac,health

nevisAdmin 4 Configuration

During the installation of the nevisAppliance images or of the RPM, a nevisAdmin 4 instance is created. The instance home directory is /var/opt/nevisadmin4. Each server/VM supports one nevisAdmin 4 instance at the most.

Java Version

nevisAdmin 4 requires a Java 17 JDK to be installed on the server/VM.

You define the Java version in /var/opt/nevisadmin4/conf/env.conf by setting JAVA_HOME. The value of JAVA_HOME depends on the operating system. The following snippet shows the recommended configuration for nevisAppliance:

JAVA_HOME=/etc/alternatives/jre_17

If JAVA_HOME is not set, the Java binary will be searched on the PATH instead. In this case, run the following command to verify that the version is correct:

java -version

Register systemd Service

Run the following command to ensure that nevisAdmin 4 is managed by systemd and started automatically on server boot:

nevisadmin4 enable

DB Schema and secrets setup

Run the following commands to create the DB schema and the admin user, and to initialize the storage of secrets:

NEVISADMIN_ADMIN_USER_PASSWORD=$(tr -cd '[:alnum:]' < /dev/urandom | fold -w30 | head -n1)
NEVISADMIN_ADMIN_USER_PASSWORD=$NEVISADMIN_ADMIN_USER_PASSWORD nevisadmin4 bootstrap
echo "nevisAdmin 4 set up. Password of 'admin' user: $NEVISADMIN_ADMIN_USER_PASSWORD"

The DB is initialized and the admin user is created. The randomly generated password for the admin user is shown on the console.

caution

It is critical that you retain the password of the local admin user. Copy it to a safe place immediately.

The admin user's password also protects the encryption key a.k.a backup master key. This key allows you to recover access to secrets, such as passwords, managed by nevisAdmin 4. Therefore, store the admin password in a safe, protected place, to make recovery via the backup master key possible.

For background information, see Encryption and Storage of Secrets.

Start nevisAdmin 4

Run the following command to start nevisAdmin 4:

nevisadmin4 startService

• Point your browser at the following URL: http://<hostname>:9080/nevisadmin/
• You should see the login screen. You can test the login with the admin account.

See nevisAdmin 4 Log Files for debugging instructions, for example in case you need to analyze the activities of the nevisAdmin 4 server process.

Stop nevisAdmin 4

Run the following command to stop nevisAdmin 4:

nevisadmin4 stopService

Securing nevisAdmin 4

See Securing nevisAdmin 4 on how to switch to HTTPS and create additional user accounts.