Administrative command-line interface

This section describes the server-side administration of nevisLogRend.

Overview

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

Static commands

• nevislogrend pkg

  Print out the current component version.

• nevislogrend inst

  List instances.

• nevislogrend inst create {instance}

• Create a new instance, by creating a directory under /var/opt/nevislogrend, copying template files from /opt/nevislogrend, 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.

• nevislogrend inst exists {instance}

  Check the existence of the instance directory.

• nevislogrend inst remove {instance}

• Stop the running instance.

• Create a backup of the instance, by zipping the instance directory.

• Remove the instance directory /var/opt/nevislogrend/instance.

• Remove the system.d service entries.

Instance commands

• nevislogrend {instance} start: Start instance via system.d.
• nevislogrend {instance} stop: Stop instance via system.d.
• nevislogrend {instance} restart: Call stop and start.
• nevislogrend {instance} status: Show the aggregate status of the instance.
• nevislogrend {instance} config: Edit the application configuration.
• nevislogrend {instance} config env: Edit the environment configuration.
• nevislogrend {instance} config vmargs: Edit the configuration file containing the JVM arguments. This is an alias of the config env command.
• nevislogrend {instance} config log: Edit the log configuration.
• nevislogrend {instance} config server: Edit the instance server configuration.
• nevislogrend {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: nevislogrend 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/nevislogrend/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:

nevislogrend inst create <instance> LOGREND_SERVER_URL="https://localhost:8990" SERVER_SSL_KEYSTORE=/var/opt/neviskeybox/default/default/node_keystore.jks

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:

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

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

LOGREND_SERVER_URL=https://localhost:8990
SERVER_SSL_KEYSTORE=/var/opt/neviskeybox/default/default/node_keystore.jks

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/nevislogrend/template to /var/opt/nevislogrend/{instance}/
2. Copy template files found under the INST_CUSTOM_TEMPLATE to /var/opt/nevislogrend/{instance}/
3. Replace @VARIABLE@ in all non binary files in the /var/opt/nevislogrend/{instance}/ directory.

Example for using all three features together

nevislogrend 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.

• nevislogrend {instance} start

  The start command nevislogrend 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.

• nevislogrend {instance} stop

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

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

• nevislogrend {instance} restart

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

• nevislogrend {instance} status

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

  # nevislogrend status
  ------------------------------------------------------------------------ Status          : UP
  instance        : default
  Process ID      : 2020
  Ownership       : nvauser / nvbgroup
  Network port(s) : localhost:8988
  Filedescriptors : 1024
  Logfile(s)      : /var/opt/nevislogrend/default/log/nevislogrend.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.

• nevislogrend {instance} config

  The command nevislogrend config opens the main configuration file /var/opt/nevislogrend/$instance$/conf/logrend.properties for editing.

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

  • Login applications
  • Path
  • Caching

  Changing the configuration requires a server restart.

• nevislogrend {instance} config server

  Opens the configuration file /var/opt/nevislogrend/$instance$/conf/logrend.properties for editing.

  You can configure technical aspects of the server:

• Protocol

• TLS settings

• Management endpoints

  Changing the configuration requires a server restart.

• nevislogrend {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/nevislogrend/{instance}/conf/env.conf for editing.

  Changing the configuration requires a server restart.

• nevislogrend {instance} config vmargs

  The command behaves exactly the same as the config env command and exists only for legacy purposes.

• nevislogrend {instance} config log

  Log4j configuration