Administrative command-line interface

This section describes the server-side administration of nevisAuth.

Overview

You can use the administrative nevisAuth command-line interface (CLI) to create and manage instances of nevisAuth. The command-line interface consists of the following commands:

Static commands

• nevisauth pkg

  Print out the current component version.

• nevisauth inst

  List instances.

• nevisauth inst create {instance}

  • Create a new instance, by creating a directory under /var/opt/nevisauth, copying template files from /opt/nevisauth, and replacing the variables in the template.
  • Register the component instance as a service in system.d.
  • Use key=value command line arguments for the variable replacement in the template files.
  • Use the INST_CUSTOM_TEMPLATE=<path> command line argument to provide custom configuration templates.

• nevisauth inst exists {instance}

  Check the existence of the instance directory.

• nevisauth inst remove {instance}

  • Stop the running instance.
  • Create a backup of the instance, by zipping the instance directory.
  • Remove the instance directory /var/opt/nevisauth/instance.
  • Remove the system.d service entries.

Instance commands

• nevisauth {instance} start: Start instance via system.d.
• nevisauth {instance} stop: Stop instance via system.d.
• nevisauth {instance} restart: Call stop and start.
• nevisauth {instance} status: Show the aggregate status of the instance.
• nevisauth {instance} config: Edit the application configuration.
• nevisauth {instance} config env: Edit the environment configuration.
• nevisauth {instance} config log: Edit the log configuration.
• nevisauth {instance} config server: Edit the instance server configuration.
• nevisauth {instance} log: List the server log files.

info

When you execute a command without specifying the instance name, the command is performed against the default instance.

Setting up servers

The base command for creating an instance is: nevisauth inst create {name}

This will create an instance using default settings for all configurations. Depending on your requirements or environment this might not result in a working setup out of the box.

The template files for configuration can be found at /opt/nevisauth/template/conf which contains variable placeholders in the following syntax: @VARIABLE@.

Example from the *esauth4.xml* configuration template

<KeyStore name="DefaultKeyStore">
  <KeyObject id="DefaultSigner"
    certificate="@AUTH_SIGNER_TRUSTSTORE@"
    privateKey="@AUTH_SIGNER_KEYSTORE@"
    passPhrase="@AUTH_SIGNER_PASSWORD@"
  />

For the full list of out of the box supported variables see Built in variables in templates.

Overriding default variables from command line arguments

To use values specific to your requirements, you can provide key=value pairs in the command line after the instance name:

nevisauth inst create {instance} AUTH_SERVER_URL="https://localhost:8990" AUTH_SIGNER_KEYSTORE=/var/opt/neviskeybox/default/default/node_keystore.jks?alias=node

Overriding default variables from files

A properties file can be used to store and override multiple variables. A properties file can be leveraged like this:

nevisauth inst create {instance} /tmp/setup.properties

Where the /tmp/setup.properties contains key value pairs like this:

AUTH_SERVER_URL=https://localhost:8990
AUTH_SIGNER_KEYSTORE=/var/opt/neviskeybox/default/default/node_keystore.jks?alias=node

Notes:

• The values specified in command line arguments will overwrite variables defined in a properties file.
• All files ending with .properties will be loaded.

Using custom templates

You can provide your own templates if the default configuration templates do not suit your needs.

This can be done via the INST_CUSTOM_TEMPLATE command line argument, where you define a directory containing your templates.

The inst create command will always:

1. Copy the default template files from /opt/nevisauth/template to /var/opt/nevisauth/{instance}/
2. Copy template files found under the INST_CUSTOM_TEMPLATE to /var/opt/nevisauth/{instance}/
3. Replace @VARIABLE@ in all non binary files in the /var/opt/nevisauth/{instance}/ directory.

Example for using all three features together

nevisauth inst create {instance} INST_CUSTOM_TEMPLATE=/tmp/testtemplate/ OTHERCOMMANDLINEVARIABLE=myvalue /tmp/setup.properties

info

Note that templates are not restricted to the configuration files, but everything under the instance directory. You can also use this approach, for example, to always provide your custom AuthStates in the plugin directory.

Controlling the server

This section describes the commands for controlling the server. See the list below for an overview of the relevant commands.

You can use all, to execute commands on all instances.

• nevisauth {instance} start

  The start command nevisauth start uses the system.d service to start the server process if it is not already running.

  The command will wait, for maximum 1 minute, for the ports to be bound for the process, then it shows the status. Port binding is the last step after the AuthStates are initialized.

• nevisauth {instance} stop

  To shut down a running server, issue the nevisauth stop command, which stops the system.d service.

  nevisAuth executes a graceful shutdown with a 30 seconds timeout to finish ongoing tasks. New requests will be not accepted during this time.

• nevisauth {instance} restart

  This command performs a stop command nevisauth stop, followed by a start command nevisauth start.

• nevisauth {instance} status

  This command displays basic information on the current runtime state of the server:

  # nevisauth status
  ------------------------------------------------------------------------
  Status          : UP
  instance        : default
  Process ID      : 382647
  Ownership       : nvauser / nvbgroup
  Network port(s) : localhost:8991
  Filedescriptors : 1024
  Logfile(s)      : /var/opt/nevisauth/default/log/nevisauth-events.log
  /var/opt/nevisauth/default/log/gc.log
  /var/opt/nevisauth/default/log/audit.log
  /var/opt/nevisauth/default/log/esauth4sv.log
  ------------------------------------------------------------------------

Configuration editing

Configuration editing is usually not an everyday administration task and is not required for operation. In production, manual changes of parameters should only be done in emergency cases and only by experienced staff who knows exactly about the effect of such changes.

The list below describes the relevant configuration commands. Those commands use either the editor defined in EDITOR environment variable or in case that is not set vim. If vim is not available than vi is used.

• nevisauth {instance} config

  The command nevisauth config opens the main configuration file /var/opt/nevisauth/instance/conf/esauth4.xml for editing.

  You can configure the following aspects in the main configuration file:

  • Authentication plug-ins and their interaction
  • Session management setup
  • Access control

  Changing the configuration requires a server restart.

• nevisauth {instance} config server

  Opens the configuration file /var/opt/nevisauth/{instance}/conf/nevisauth.yml for editing.

  You can configure technical aspects of the server:

  • Protocol
  • TLS settings
  • Management endpoints

  Changing the configuration requires a server restart.

• nevisauth {instance} config env

  This command allows specifying arguments to be passed to the JVM initialization, the JAVA_OPTS. It opens the configuration file /var/opt/nevisauth/{instance}/conf/env.conf for editing.

  Changing the configuration requires a server restart.

• nevisauth {instance} config log

  Log4j configuration