Skip to main content
Version: 8.2405.x.x RR

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:

    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.