Skip to main content
Version: 7.2405.x.x LTS

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