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.