Managing Nexfs with Nexfscli

Nexfs can be managed with the Linux command-line utility nexfscli which can be downloaded with nexfs.server.

 

Most management and configuration tasks can be made using nexfscli, and there is a small number of less used actions can only be performed using this tool.

Users may prefer to configure and manage Nexfs using the Admin Webconsole or to automate Nexfs Managment using the Nexfs API

Nexfscli is the only tool that can be used to configure and manage Nexfs when the Nexfs server is offline, or if the management API and Admin webconsole have been manually disabled.   

nexfscli is also released as opensource on github allowing the nexfs community to tailor it to their needs while providing a working example of how to manage nexfs through code using the nexfs file management interface.

 

To run Nexfs you must either be the root user, or belong to the nexfs admin cmd group, and the cmd group must have the appropriate rights assigned.

 

nexfscli is a command-line utility that must be run on the same environment as the Nexfs server.

 

It is also recommended that the nexfscli is used to start and stop the Nexfs server.

 

Using nexfscli

 

To use nexfscli simply run the command followed by the required command-line arguments. (Optionally) If the Nexfs configuration file default directory of /etc/nexfs is not used, then you can either specify the correct directory by adding --confdir={requireconfidir} as the last argument of the nexfscli command, or by setting the Linux environmental shell variable nexfsconfdir

For example, to get the Nexfs server status you will run:

 

nexfscli server status

 

  If the Nexfs configuration location is /nexfs/conf and not the default, to get the server status you will    run:

 

nexfscli server status --configdir=/nexfs/conf

   or use the export method to specify the configuration directory

export nexfsconfdir=/nexfs/conf 

nexfscli server status

To get to the current loglevel of the running nexfs server, run:

 

nexfscli liveconfig get loglevel

 

Getting help

 

To see a list of the most common nexfscli options run:

 

nexfscli help

 

To get a full list including less commonly used options:

 

nexfscli -allhelp

 

Starting, stopping nexfs

 

To start Nexfs run:

 

nexfscli server start

To nicely stop Nexfs, run:

 

nexfscli server stop


 

While it is always advisable to perform a nice Nexfs server stop, which pauses client traffic and attempts to flush any open buffers, if a  fast and hard stop of nexfs is required, run:

 

nexfscli server forcestop

 

Note: running a force stop is not recommended other than as a last resort, a force stop will not flush open data buffers to permanent storage, which could result in data corruption. 


 

Getting the Nexfs server status

 

To get the current Nexfs server status, run

 

nexfscli server status

 

Which for a running Nexfs server will result in output similar to:

 

Nexfs Mountpoint: /mnt/nexfs
Server Status: OK
Release: 0.9.2d
Software Expires: Tue 2024-12-17 12:39:22
License: Core 5TB
Managed Capacity 0TB (7GB)
Process ID: 60679
Uptime: 7 days 2 hours 48 minutes 22 seconds
Open Files: 3/7281
Tier1 Struct Status: OK
Tier2 Struct Status: OK
Tier1 Status: OK
Tier1 Threshold Level: LowWaterMark
Tier1 Floor Level: FloorWaterMark
Tier2 Status: Disabled
Tier2 Threshold Level: OK
Tier2 Floor Level: OK
Tier3 Status: OK
iSCSI Status: OK
NFS Status: Unknown
Mgmt Web Server: Unknown
Job Scheduler: Enabled
BG Migration Scheduler: Paused
Deletion Scheduler: Enabled
Manual Commands: Enabled

 

Getting Nexfs release information

 

To retrieve the version of a running Nexfs server, run

 

nexfscli release get nexfs 

 

and to get the version of nexfscli, run

 

nexfscli release get nexfscli

 

Getting and changing a running Nexfs servers log level

 

To retrieve the current (live) log level of a running Nexfs server, run

 

nexfscli liveconfig get loglevel

 

To change the current (live) log level of a running Nexfs server, run

 

nexfscli liveconfig set loglevel {NEWLOGLEVEL}

 

Replace {NEXLOGLEVEL} with one of:

 

CRIT, ERR, WARNING, NOTICE, INFO or DEBUG

 

For example to set the nexfs server to log at debug level, run

 

nexfscli liveconfig set loglevel DEBUG

 

Note: this will only change the loglevel for the running Nexfs server, when the server is restarted the loglevel will revert back to that set in the configuration file. See Nexfs Configuration below for more information.

 

Nexfs Configuration using nexfscli

 

Many of the Nexfs server settings can be made “live”, this means that there is no need to restart the Nexfs server for those changes to become active. 

 

But, just changing the live setting will not make that change permanent, when the Nexfs server starts it reads permanent settings from its configuration files. As such if you want to change the live setting and for that new setting to become permanent, you need to change it in both the “liveconfig” and also the configuration file “configfile”. Both of these can be updated using nexfscli


 

Note: configuration tag names are case sensitive 

 

Getting a list of all live Nexfs settings

 

To get a list of the current live configuration settings, which may be different from the permanent startup settings, run:

 

nexfscli liveconfig dump all


 

Which will result in a listing of all configurations settings along with their current “live” values. 

 

 

Getting a list of all permanent Nexfs settings

 

To get a list of the permanent configuration settings, which may be different to the current live process settings, run:

 

nexfscli configfile dump all


 

Which will result in a listing of all configurations settings along with their current “permanent” values. 


 

Getting the value of a single live Nexfs settings

 

To get a list of a single live configuration setting, which may be different from the permanent setting, run:

 

nexfscli liveconfig get value {CONFIGTAGNAME}

 

Replace  {CONFIGTAGNAME} with the configuration name you would like to retrieve the value of, a list of configuration names and their usage can be found here


 

Getting the value of a single permanent Nexfs settings

 

To get a list of a single permanent configuration setting, which may be different from the live setting, run:

 

nexfscli configfile get value {CONFIGTAGNAME}

 

Replace  {CONFIGTAGNAME} with the configuration name you would like to retrieve the value of, a list of configuration names and their usage can be found here


 

Getting more details on a single configuration setting

 

You can get more details of a configuration setting, including a basic description, allowed values and if a restart is needed to activate changes, run:

 

nexfscli configfile get all {CONFIGTAGNAME}

 

Replace  {CONFIGTAGNAME} with the configuration name you would like to retrieve the value of, a list of configuration names and their usage can be found here

 

For example to get more details about the MOUNTPOINT configuration setting (tag), run:

 

nexfscli configfile get all MOUNTPOINT

 

Which will result in output similar to:

 

Tag Label = 'MOUNTPOINT'

Value = '/mnt/nexfs'

Help Text = 'NEXFS Mountpoint, needed for nexfscli to work, must match the Nexfs mountpoint although this setting is not used here by the Nexfs storgae server itself"

Validation:String = '1'

Validation:Min(Value/StringLength) = '2'

Validation:Max(Value/StringLength) = '2048'


 

Change the value of a single live Nexfs settings

 

To set the value of a single live configuration setting, which may be different from the permanent setting set when the Nexfs server restarts, run:

 

nexfscli liveconfig set {CONFIGTAGNAME} {NEWVALUE}

 

Replace  {CONFIGTAGNAME} with the configuration name you would like to retrieve the value of, a list of configuration names and their usage can be found here

 

Replace {NEWVALUE} will the new required setting

 

For example, to pause the Nexfs server, run

 

nexfscli liveconfig set NEXFSPAUSED 1


 

Note: live configuration changes are not permanent and their values will revert back to the permanent configuration value when Nexfs is restarted, to make changes permanent you must change the permanent value, as detailed below.

 

Change the value of a single permanent Nexfs settings

 

To set permanent configuration settings, which may be different from the live setting unless the same change is made in the liveconfig or the Nexfs server restarts, run:

 

nexfscli configfile set {CONFIGTAGNAME} {NEWVALUE}

 

Replace  {CONFIGTAGNAME} with the configuration name you would like to retrieve the value of, a list of configuration names and their usage can be found here

 

Replace {NEWVALUE} will the new required setting

 

For example, to change the Nexfs mountpoint, run

 

nexfscli configfile set MOUNTPOINT /mnt/nexfs

 

Note: permanent configuration file changes do not become live unless the Nexfs server is restarted or the live value is updated, as detailed above.


 

Also, see managing Nexfs using the Nexfs management API and Admin Webconsole.