mmnfs command

Availability

Available on all IBM Storage Scale editions.

Description

Use the mmnfs export commands to add, change, list, load, or remove NFS export declarations for IP addresses on nodes that are configured as CES types.

Use the mmnfs config commands to list and change NFS configuration.

The protocol functions provided in this command, or any similar command, are generally referred to as CES (Cluster Export Services). For example, protocol node and CES node are functionally equivalent terms.

Parameters

export

Manages the NFS export configuration for the cluster with one of the following actions:

add

Creates a new configuration file for the NFS server in case it does not yet exist. If there is already an export configuration file, then it is extended with the provided additional export parameters. This export configuration file is used by the NFS server to create an NFS export for the Path so that clients can connect to it. If there is already an existing export for the Path then an error is shown. Each export configuration set has internally its own unique identifier number. This number is automatically incremented for each added export. The mmnfs export add command attempts to add the new export also to running NFS server instances, and can fail if one or more instances are not running. This is not a critical issue, because the configuration changes are made in the repository and are applied later when restarting the NFS server instance.

The authentication method must be established before an NFS export can be defined.

The export Path must be an existing path in the GPFS file system.

Note: The paths that are not within the GPFS file system cannot be exported using the commands.

Creating nested exports (such as /path/to/folder and /path/to/folder/subfolder) is not recommended because doing so might lead to serious issues in data consistency. Remove the higher-level export that prevents the NFSv4 client from descending through the NFSv4 virtual file system path. In case nested exports cannot be avoided, ensure that the export with the common path, called as the top-level export, has all the permissions for this NFSv4 client. Also NFSv4 client that mounts the parent (/path/to/folder) export does not see the child export subtree (/path/to/folder/inside/subfolder) unless the same client is explicitly allowed to access the child export as well.

--client {ClientOption[;ClientOption...]}

Declares the client-specific settings. You can specify a list of one or more client definitions. To avoid incorrect parsing by the interpreter, put quotation marks around the argument list. For a list of client definitions that can be specified with the --client option, see List of supported client options for the mmnfs export {add | change} command.

Note: The sequence of client definitions does matter and the first match determines the effective access.

Therefore, some export configuration commands might allow multiple client declarations, and they have separators to distinguish them.

The following separators can be used:

• Colon to separate multiple allowed values for a specified attribute. For example, the key/value pair "Protocols=3:4" allows the NFS protocols v3 and v4 to be declared for an export.
• Comma to separate key/value pairs within a client declaration list and a Semicolon to separate client declaration lists.

  For example:

  --client "192.0.2.0/20(Access_Type=RW,Protocols=3:4); \
  198.51.100.0/20(Access_Type=RO,Protocols=3:4,Transports=TCP:UDP)"

Note: NFS service restarts after the first export creation.

Note: To take advantage of the GPFS independent fileset features such as quotas, snapshots, and data management, the export paths can be made from GPFS filesets (either dependent or independent).

--pseudo

Specifies the path name the NFSv4 client uses to locate the directory in the server's file system tree.

Note: This option is applicable to NFSv4 mounts only.

remove

Removes the requested export from the configuration file and also from running NFS server instances, and might fail if one or more instances are not running.

Note: This command does not remove data.

The --force option is not used.

change

Modifies an existing export configuration for the export that is specified by Path, if the export exists. If the export does not exist, then an error is shown.

Note: Only client-related attributes are modified by this command, but not the basic export settings such as path.

The --nfsposition flag can be only used together with either --nfsadd or --nfschange. It cannot be used stand-alone or together with --nfsremove. When --nfsadd and --nfsremove are given on the same command line, then the remove procedure is run first internally.

--nfsadd {ClientOption[;ClientOption...]}

Adds a new client declaration for the specified Path. You can list one or more client definitions. To avoid incorrect parsing by the interpreter, put quotation marks around the argument list. For a list of client definitions that can be specified with the --client option, see List of supported client options for the mmnfs export {add | change} command.

--nfsremove {Client[,Client...]}

Removes the NFS client that is specified by Client from the export configuration for the Path. Client can be a single client specifier, or a comma-separated list of client specifiers. If a client is the only one within a client declaration section in the configuration file, then this client section is removed.

Note: When the last client within a client declaration is removed, then the export section is also removed.

--nfschange {ClientOption[;ClientOption...]}

Modifies an existing client declaration for the specified Path. You can specify a list of one or more client definitions. To avoid incorrect parsing by the interpreter, put quotation marks around the argument list. For a list of client definitions that can be specified with the --client option, see List of supported client options for the mmnfs export {add | change} command. If a client specifier declared in ClientOption matches a client declaration section, which has further NFS clients that are assigned, then this section is split into a section containing that client specifier together with the modified attributes, and a section with the remaining client specifiers and their original attributes.

The --nfsposition option can be used to locate this modified entry.

--nfsposition {PositionIndex | Client}

This option can be used only together with --nfsadd or --nfschange. It reorders the client declaration section within the export declaration file. The sequence of client entries can be important when there are different client sections affecting the same NFS client. For example, NFS position can be important when defining export attributes for a specific NFS client, and '*' for all NFS clients, given the same export path. The first match in the sequence determines the effective access.

PositionIndex

This must be an unsigned numeric value, and it indicates the absolute sequence number after reordering the client declarations. The indexing is zero-based. 0 means the top of the list, 1 means the second entry, and so on. Any number higher than the number of existing entries indicates the end-of-list position.

Client

The reference client specifier to indicate the new position of the current client entry. The modified client entry is placed at the location where the Client reference declaration is, and that section is ordered below next to the modified client section.

list

Lists the declared exports and clients. The sequence of rows in the output for a given path reflects also the sequence of the internal client declaration list for each exported path. The sequence of client declarations within an export can be reordered using the mmnfs export change Path with the --nfschange and --nfsposition options. The output can be formatted human readable (default) or machine readable.

--nfsdefs Path

Lists the export configuration details for the specified Path.

-Y

Displays the command output in a parseable format with a colon (:) as a field delimiter. Each column is described by a header.

Note: Fields that have a colon (:) are encoded to prevent confusion. For the set of characters that might be encoded, see the command documentation of mmclidecode. Use the mmclidecode command to decode the field.

--nfsdefs-match Path

Lists the export configuration details of all export paths, which contain the specified string.

load

Overwrites (deletes) all existing NFS export declarations in the repository, if any. The export declarations are fetched from a file provided to the load operation, which could contain a larger number of export declarations. Some basic format checks are done during export load. After loading export declarations from a file, the NFS service is restarted across all the nodes in the cluster.

ExportCFGFile

The file name for the new exports declarations. This file is loaded and stored in the repository to be published on all CES nodes running the NFS server. This load procedure can be used to load a set of export declarations and that removes any previous configuration. The NFS servers are restarted in order to apply the changes.

List of supported client options for the mmnfs export {add | change} command:

ACCESS_TYPE

Allowed values are none, RW, RO, MDONLY, and MDONLY_RO. The default value is none.

PROTOCOLS

Allowed values are 3, 4, NFS3, NFS4, V3, V4, NFSv3, and NFSv4. The default value is 3,4.

TRANSPORTS

Allowed values are TCP and UDP. The default value is TCP.

ANONYMOUS_UID

Allowed values are between -2147483648 and 4294967295. The default value is -2.

ANONYMOUS_GID

Allowed values are between -2147483648 and 4294967295. The default value is -2.

SECTYPE

Allowed values are none, sys, krb5, krb5i, and krb5p. The default value is sys.

PRIVILEGEDPORT

Allowed values are true and false. The default value is false.

MANAGE_GIDS=true

In this configuration, NFS server discards the list of GIDs passed via the RPC and fetch the group information. For getting the group list, the server uses the default authentication configured on the system (CES node). So, depending on the configuration, the list is obtained by using (/etc/passwd + /etc/groups) or from LDAP or from AD. To reach AD and get the list of GIDs, the client must use sec=krb5, else NFS server is not able to get the list from AD.

MANAGE_GIDS=false

NFS server uses list of GIDs passed by RPC.

SQUASH

Allowed values are root, root_squash, all, all_squash, allsquash, no_root_squash, none, and noidsquash. The default value is root_squash.

NFS_COMMIT

Allowed values are true and false. The default value is false.

Important: Use NFS_COMMIT very carefully because it changes the behavior of how transmitted data is committed on the server side to NFS v2 like sync-mode on every write action.

CLIENTS

Allowed values are IP addresses in IPv4 or IPv6 notations, hostnames, netgroups, or * for all. A netgroup name must not start with a numeric character and otherwise must only contain underscore and/or hyphens ("[a-zA-Z_][0-9a-zA-Z_\- .]*"). The default value is *.

config

Manages NFS configuration for a CES cluster:

list

Displays the NFS configuration parameters and their values. This command also displays all the default export configurations. This is used as the defaults by the mmnfs export add command if no other client attributes are specified. The output can be formatted to be human readable or machine readable.

--exportdefs

If this option is specified, the command displays the default export configuration parameters.

-Y

Displays the command output in a parseable format with a colon (:) as a field delimiter. Each column is described by a header.

Note: Fields that have a colon (:) are encoded to prevent confusion. For the set of characters that might be encoded, see the command documentation of mmclidecode. Use the mmclidecode command to decode the field.

change

Modifies the NFS configuration parameters. NFS is restarted across all the nodes on which NFS is running, when this command is executed. Only some configuration options can be modified by this command.

The configuration options that can be modified and their allowed values are as follows:

ENABLE_RPC_CRED_FALLBACK

Allowed value is true or false. The default value is false. The false value implies that if GID resolution fails, NFS Ganesha returns the NFS4ERR_ACCESS error. The true value enables NFS Ganesha to use GID information from an RPC request from an NFS client.

NFS_PROTOCOLS

Allowed values are 3, 4, NFS3, NFS4, V3, V4, NFSv3, and NFSv4. The default value is 3,4.

MINOR_VERSIONS

Allowed values are 0 and 1. The default value is 0,1. The default value implies that NFS 4.0 and 4.1 is enabled by default.

ENFORCE_UTF8_VALIDATION

Allowed value is true or false. The default value is false. The false value implies that the UTF8 validation is disabled. The true value enforces the UTF8 validation.

MNT_PORT

Specifies the port for the NFSv3 Mount protocol. Allowed values are between 0 and 65535. The default value is 0.

NLM_PORT

Specifies the NLM port for NFSv3. Allowed values are between 0 and 65535. The default value is 0.

RQUOTA_PORT

Specifies the RQUOTA port for NFSv3. Allowed values are between 0 and 65535. The default value is 0.

STATD_PORT

Specifies the STATD port for NFSv3. Allowed values are between 0 and 65535. The default value is 0.

LEASE_LIFETIME

Specifies the value in seconds during which an NFS server requires an NFS client to do some operation to renew its lease. This is specific to NFSV4. Allowed values are between 0 and 120. The default value is 60.

GRACE_PERIOD

Specifies time duration in seconds for an NFS client to reclaim its locks for NFSv3, and reclaim its state for NFSv4.

The NFS grace period is triggered when an NFS server starts and CES IPs are moved. After the grace period is over, any NFS client that did not reclaim its state might receive an I/O error or might not re-establish the state.

Allowed values are between 0 and 180. The default value is 90.

The lower value must be sufficient to perform I/O into the file system that is needed to reclaim. Busy NFS servers queuing many I/O might need to wait for the file system and the reduction of the queue before reclaim requests can be processed.

Note: Before you change GRACE_PERIOD, the expected file system freeze time during a node leave needs to be considered.

Idle NFS clients, which have state, need to recognize the grace period. Any reduction in GRACE_PERIOD must be followed by reduction in LEASE_LIFETIME. So that, the client can receive an ERR_GRACE when the LEASE_LIFETIME timer triggers a session renew request. This can be achieved by setting the GRACE_PERIOD value higher than the LEASE_LIFETIME value.

DOMAINNAME

String. The default value is the "host's fully-qualified DNS domain name".

IDMAPD_DOMAIN

String. Domain in the ID Mapd configuration. The default value is the host's fully-qualified DNS domain name.

LOCAL_REALMS

String. Local-Realms in the ID Mapd configuration. The default value is the host's default realm name.

LOG_LEVEL

Allowed values are NULL, FATAL, MAJ, CRIT, WARN, EVENT, INFO, DEBUG, MID_DEBUG, and FULL_DEBUG. The default value is EVENT.

ENTRIES_HWMARK

The high watermark for NFS cache entries. Beyond this point, NFS tries to evict some objects from its cache. The default is 1500000.

When the high watermark value is increased, the maximum memory, which NFS can use, increases approximately by 10 KB per entry. This memory is not allocated statically. If the increased value is too high, an out of memory issue might occur under the high load condition.

RPC_IOQ_THRDMAX

Specifies the maximum number of RPC threads that process NFS requests from NFS clients. The valid values are 2 - 131072. The default value is 512.

If the system has high bandwidth but high latency, you can increase the value of this parameter to improve the system performance.

Important: This value must not exceed the value of GPFS worker threads. If performance with high disk system or GPFS load is causing any issue, decrease the number of NFS RPC threads to avoid overload on the GPFS or disk system. For more information, see Parameters for performance tuning and optimization

DIR_CHUNK

Specifies the size of per-directory dirent cache chunks. Zero (0) means directory chunking is not enabled. Allowed values are between 0 and 1024. The default value is 128.

READDIR_RES_SIZE

Specifies response size of readdir request. Zero (0) means use maxcount value from nfs request. Suggested values are 4096, 8192, 16384, and 32768. The default value is 16384.

SERVER_SCOPE

Specifies the string value which is common for all the cluster nodes. For example, name of the cluster or cluster-id. The default value is gpfs cluster name.

Note: Specifying a port number in the NFS service configuration with the value of '0' means that the service is picking a port number dynamically. This port number might change across service restarts. If a firewall is to be established between the NFS server and the NFS clients, specific port number can be configured via the command to establish discrete firewall rules. Note that the NFS_PORT 2049 is a well-known and established convention as NFS servers and clients typically expect this port number. Changing the NFS service port numbers impacts existing clients and a remount of the client is required.

The export defaults that can be set are:

ACCESS_TYPE

Allowed values are none, RW, RO, MDONLY, and MDONLY_RO. The default value is none.

Note: Changing this option to any value other than none exposes data to all NFS clients that can access your network, even if the export is created using add --client ClientOptions to limit that clients access. All clients, even if not declared with the --client in the mmnfs export add, has access to the data. The global value applies to an unseen *, even if showmount -e CESIP does not display it. Use caution if you change it in this global definition.

ANONYMOUS_UID

Allowed values are between -2147483648 and 4294967295. The default value is -2.

ANONYMOUS_GID

Allowed values are between -2147483648 and 4294967295. The default value is -2.

MANAGE_GIDS

Allowed values are true and false. The default value is false.

NFS_COMMIT

Allowed values are true and false. The default value is false.

Important: Use NFS_COMMIT very carefully because it changes the behavior of how transmitted data is committed on the server side to NFS v2 like sync-mode on every write action.

PRIVILEGEDPORT

Allowed values are true and false. The default value is false.

PROTOCOLS

Allowed values are 3, 4, NFS3, NFS4, V3, V4, NFSv3, and NFSv4. The default value is 3,4.

SECTYPE

Allowed values are none, sys, krb5, krb5i, and krb5p. The default value is sys.

SQUASH

Allowed values are root, root_squash, all, all_squash, allsquash, no_root_squash, none, and noidsquash. The default value is root_squash.

Note: Changing this option to no_root_squash exposes data to root on all NFS clients, even if the export is created using add --client ClientOptions to limit the root access of that client.

TRANSPORTS

Allowed values are TCP and UDP. The default value is TCP.

If export defaults are set, then new exports that are created pick up the export default values. If an export configuration value is not specified, the current export default value is used.

Note: For exports created before IBM Storage Scale 5.0.2, the export default value at the time of its creation is used.

Exit status

0

Successful completion.

nonzero

A failure has occurred.

Security

You must have root authority to run the mmnfs command.

The node on which the command is issued must be able to execute remote shell commands on any other CES node in the cluster without the use of a password and without producing any extraneous messages. For more information, see Requirements for administering a GPFS file system.

See also

Location