ganesha-core-config

title: ganesha-core-config(8)

summary: NFS Ganesha Core Configuration File

text:
# ganesha-core-config(8)

## NAME
ganesha-core-config - NFS Ganesha Core Configuration File

## SYNOPSIS

```
/etc/ganesha/ganesha.conf
```

## DESCRIPTION
NFS-Ganesha reads the configuration data from: | /etc/ganesha/ganesha.conf

This file lists NFS related core config options.

### NFS_CORE_PARAM {}
Core parameters:

HAProxy_Hosts (host list, empty)

This is the list of hosts that can serve as HAProxy load balancers/proxies that will use the HAProxy protocol to indicate to Ganesha the actual end client IP address. This parameter may be repeated to extend the list. Host list entries can take on one of the following forms:

* Match any host @name Netgroup name x.x.x.x/y IPv4 network address, IPv6 addresses are also allowed but the format is too complex to show here

wildcarded If the string contains at least one ? or *

character (and is not simply "*"), the string is used to pattern match host names. Note that [] may also be used, but the pattern MUST have at least one ? or *

hostname Match a single host (match is by IP address, all

addresses returned by getaddrinfo will match, the getaddrinfo call is made at config parsing time)

IP address Match a single host

NFS_Port (uint16, range 0 to UINT16_MAX, default 2049)

Port number used by NFS Protocol.

MNT_Port (uint16, range 0 to UINT16_MAX, default 0)

Port number used by MNT Protocol.

NLM_Port (uint16, range 0 to UINT16_MAX, default 0)

Port number used by NLM Protocol.

Rquota_Port (uint16, range 0 to UINT16_MAX, default 875)

Port number used by Rquota Protocol.

NFS_RDMA_Port (uint16, range 0 to UINT16_MAX, default 20049)

Port number used by NFS Over RDMA Protocol.

NFS_RDMA_Protocol_Versions(enum list, default [4.0])

Possible values:

(NONE, 3, v3, NFS3, NFSv3, 4.0, v4.0, NFS4.0, NFSv4.0, 4.1, v4.1, NFS4.1, NFSv4.1, 4.2, v4.2, NFS4.2, NFSv4.2, ALL)

Supported NFS Version for NFS Over RDMA. By default, NFSv3, NFSv4.0, NFSv4.1 & NFSv4.2 are enabled.

Monitoring_Addr(IPv4 or IPv6 addr, default 0.0.0.0)

The address to which to bind for listening the monitoring port. If not specified, then makes use of Bind_Addr config value.

Monitoring_Port (uint16, range 0 to UINT16_MAX, default 9587)

Port number used to export monitoring metrics.

Enable_Dynamic_Metrics (bool, default true)

Whether to create metrics labels on the fly based on client-ip, export name, etc. Provides more debugging information, but significantly reduces performance. Enabled by default for backward compatibility.

Enable_Metrics (bool, default false)

Controls whether metrics collection is enabled, even when the USE_MONITORING macro is defined. This option provides additional flexibility to enable or disable the monitoring module based on configuration, regardless of the compile-time macro setting.

Bind_addr(IPv4 or IPv6 addr, default 0.0.0.0)

The address to which to bind for our listening port.

Interface_Name(string, default NULL)

If present, binds all TCP sockets to the specified interface. If not present, has no effect. On systems with mutliple NICs, this option will ensure all TCP traffic goes through a specified interface.

NFS_Program(uint32, range 1 to INT32_MAX, default 100003)

RPC program number for NFS.

MNT_Program(uint32, range 1 to INT32_MAX, default 100005)

RPC program number for MNT.

NLM_Program(uint32, range 1 to INT32_MAX, default 100021)

RPC program number for NLM.

Drop_IO_Errors(bool, default false)

For NFSv3, whether to drop rather than reply to requests yielding I/O errors. It results in client retry.

Drop_Inval_Errors(bool, default false)

For NFSv3, whether to drop rather than reply to requests yielding invalid argument errors. False by default and settable with Drop_Inval_Errors.

Drop_Delay_Errors(bool, default false)

For NFSv3, whether to drop rather than reply to requests yielding delay errors. False by default and settable with Drop_Delay_Errors.

Plugins_Dir(path, default "/usr/lib64/ganesha")

Path to the directory containing server specific modules

Enable_NFS_Stats(bool, default true)

Whether to collect performance statistics. By default the performance counting is enabled. Enable_NFS_Stats can be enabled or disabled dynamically via ganesha_stats.

Enable_Fast_Stats(bool, default false)

Whether to use fast stats. If enabled this will skip statistics counters collection for per client and per export.

Enable_FSAL_Stats(bool, default false)

Whether to count and collect FSAL specific performance statistics. Enable_FSAL_Stats can be enabled or disabled dynamically via ganesha_stats

Enable_FULLV3_Stats(bool, default false)

Whether to count and collect "detailed statistics" for NFSv3. Enable_FULLV3_Stats can be enabled or disabled dynamically via ganesha_stats.

Enable_FULLV4_Stats(bool, default false)

Whether to count and collect "detailed statistics" for NFSv4. Enable_FULLV4_Stats can be enabled or disabled dynamically via ganesha_stats.

Enable_CLNT_AllOps_Stats(bool, default false)

Whether to count and collect statistics for all NFS operations requested by NFS clients. Enable_CLNT_AllOps_Stats can be enabled or disabled dynamically via ganesha_stats.

Short_File_Handle(bool, default false)

Whether to use short NFS file handle to accommodate VMware NFS client. Enable this if you have a VMware NFSv3 client. VMware NFSv3 client has a max limit of 56 byte file handles.

Manage_Gids_Expiration(int64, range 0 to 7*24*60*60, default 30*60)

How long the server will trust information it got by calling getgroups() when "Manage_Gids = TRUE" is used in a export entry.

heartbeat_freq(uint32, range 0 to 5000 default 1000)

Frequency of dbus health heartbeat in ms.

Enable_NLM(bool, default true)

Whether to support the Network Lock Manager protocol.

Disable_NLM_SHARE(bool, default false)

This option allows disabling support for the NLM4PROC_SHARE and NLM4PROC_UNSHARE RPC procedures that implement share reservations for NFSv3 via NLM. With this set to true, these procedures will fail.

Blocked_Lock_Poller_Interval(int64, range 0 to 180, default 10)

Polling interval for blocked lock polling thread

Protocols(enum list, default [3,4,9P])

Possible values:

3, 4, NFS3, NFS4, V3, V4, NFSv3, NFSv4, 9P

Support for NFS Over RDMA: [3 or 4 or 3,4], nfsrdma, rpcrdma

The protocols that Ganesha will listen for. This is a hard limit, as this list determines which sockets are opened. This list can be restricted per export, but cannot be expanded.

NSM_Use_Caller_Name(bool, default false)

Whether to use the supplied name rather than the IP address in NSM operations.

Clustered(bool, default true)

Whether this Ganesha is part of a cluster of Ganeshas. Its vendor specific option.

fsid_device(bool, default false)

Whether to use device major/minor for fsid.

resolve_fs_retries(uint32_t, range 1 to 1000, default 10)

How many times to attempt stat while resolving POSIX filesystems for exports.

resolve_fs_delay(uint32_t, range 1 to 1000, default 100)

How long to delay between stat attempts while resolving POSIX filesystems for exports.

mount_path_pseudo(bool, default false)

Whether to use Pseudo (true) or Path (false) for NFS v3 and 9P mounts. This option defaults to false for backward compatibility, however, for new setups, it's strongly recommended to be set true since it then means the same server path for the mount is used for both v3 and v4.x.

Note that as an export related option, it seems very desirable to be able to change this on config reload, unfortunately, at the moment it is NOT changeable on config reload. A restart is necessary to change this.

Dbus_Name_Prefix

DBus name prefix. Required if one wants to run multiple ganesha instances on single host. The prefix should be different for every ganesha instance. If this is set, the dbus name will be <prefix>.org.ganesha.nfsd

Enable_UDP(list, valid values [False, True, Mount, NLM, RQuota], default True)

Whether to create UDP listeners for Mount, NFS, NLM, RQUOTA, and register them with portmapper. Set to false, e.g., to run as non-root. Set to Mount to enable only Mount UDP listener. Set to RQuota to enable only RQUOTA UDP listener. Multiple values can be combined, e.g., Mount, RQuota to enable only Mount and RQUOTA UDP listeners.

Max_Uid_To_Group_Reqs(uint32, range 0 to INT32_MAX, default 0)

Maximum number of concurrent uid2grp requests that can be made by ganesha. In environments with a slow Directory Service Provider, where users are part of large number of groups, and Manage_Gids is set to True, uid2grp queries made by ganesha can fail if a large number of them are made in parallel. This option throttles the number of concurrent uid2grp queries that ganesha makes.

Enable_V3fh_Validation_For_V4(bool, default false)

Set true to enforce when v3 file handle used for v4

Readdir_Res_Size(uint32, range 4096 to 64*1024*1024, default 32*1024)

Response size of readdir request. Suggested values are 4096,8192,16384 and 32768. Recommended 16384(16K) if readdir(ls command) operation performed on directory which has more files.

Readdir_Max_Count(uint32, range 32 to 1024*1024, default 1024*1024)

Maximum number of directory entries returned for a readdir request. Suggested values are 4096,8192,16384 and 32768. Recommended 16384(16K) if readdir(ls command) operation performed on directory which has more files.

Getattrs_In_Complete_Read(bool, default true)

Whether to call extra getattrs after read, in order to check file size and validate the EOF flag correctness. Needed for ESXi client compatibility when FSAL's don't set it correctly.

Enable_malloc_trim(bool, default false)

Set true to enable dynamic malloc_trim support.

Malloc_trim_MinThreshold(uint32, range 1 to INT32_MAX, default 15*1024)

Minimum threshold value to call malloc_trim. The malloc_trim will be called once memory allocation exceeds minimum value. Size in MB's. Note, this setting has no effect when Enable_malloc_trim is set to false.

enable_rpc_cred_fallback(bool, default false)

if Manage_Gids=True and group resolution fails, then use gid data from rpc request.

Enable_Connection_Manager(bool, default false)

When enabled, a client (from the same source IP address), is allowed to be connected to a single Ganesha server at a specific point in time. See details in connection_manager.h

Connection_Manager_Timeout_sec(uint32, range 0 to UINT32_MAX, default 2*60)

Timeout for waiting until client is fully disconnected from other Ganesha servers.

Unique_Server_Id(uint32, range 0 to UINT32_MAX, default 0)

Unique value to the ganesha node, to diffrintiate it for the rest of the node. will be used as prefix for the Client id, to make sure it is unique between ganesha nodes and file write verifier. if 0 is supplied server boot epoch time in seconds will be used

Allow_Set_Io_Flusher_Fail(bool, default false)

In linux, we need to set PR_SET_IO_FLUSHER to avoid a potential deadlock when mounting ganesha locally in a system that nears out memory. This is not possible due to lacking permissions in some environments (specifically unprivileged containers). If you are running in an unprivileged environment and you are sure your use case doesn't require setting PR_SET_IO_FLUSHER, you can enable this option and Ganesha will not fail on startup if it can't set it. For more info, see: <https://git.kernel.org/torvalds/p/8d19f1c8e1937baf74e1962aae9f90fa3aeab463>

### Parameters controlling TCP DRC behavior:
DRC_Disabled(bool, default false)

Whether to disable the DRC entirely.

DRC_Recycle_Hiwat(uint32, range 1 to 1000000, default 1024)

High water mark for number of DRCs in recycle queue.

TCP_Npart(uint32, range 1 to 20, default 1)

Number of partitions in the tree for the TCP DRC.

DRC_TCP_Size(uint32, range 1 to 32767, default 1024)

Maximum number of requests in a transport's DRC.

DRC_TCP_Cachesz(uint32, range 1 to 255, default 127)

Number of entries in the O(1) front-end cache to a TCP Duplicate Request Cache.

DRC_TCP_Hiwat(uint32, range 1 to 256, default 64)

High water mark for a TCP connection's DRC at which to start retiring entries if we can.

DRC_TCP_Recycle_Npart(uint32, range 1 to 20, default 7)

Number of partitions in the recycle tree that holds per-connection DRCs so they can be used on reconnection (or recycled.)

DRC_TCP_Recycle_Expire_S(uint32, range 0 to 60*60, default 600)

How long to wait (in seconds) before freeing the DRC of a disconnected client.

DRC_TCP_Checksum(bool, default true)

Whether to use a checksum to match requests as well as the XID

### Parameters controlling UDP DRC behavior:
DRC_UDP_Npart(uint32, range 1 to 100, default 7)

Number of partitions in the tree for the UDP DRC.

DRC_UDP_Size(uint32, range 512, to 32768, default 32768)

Maximum number of requests in the UDP DRC.

DRC_UDP_Cachesz(uint32, range 1 to 2047, default 599)

Number of entries in the O(1) front-end cache to the UDP Duplicate Request Cache.

DRC_UDP_Hiwat(uint32, range 1 to 32768, default 16384)

High water mark for the UDP DRC at which to start retiring entries if we can

DRC_UDP_Checksum(bool, default true)

Whether to use a checksum to match requests as well as the XID.

### Parameters affecting the relation with TIRPC:
RPC_Max_Connections(uint32, range 1 to 1000000, default 1024)

Maximum number of connections for TIRPC.

RPC_Idle_Timeout_S(uint32, range 0 to 60*60, default 300)

Idle timeout (seconds). Default to 300 seconds.

MaxRPCSendBufferSize(uint32, range 1 to 1048576*9, default 1048576)

Size of RPC send buffer.

MaxRPCRecvBufferSize(uint32, range 1 to 1048576*9, default 1048576)

Size of RPC receive buffer.

RPC_Max_RDMA_Connections(uint32, range 1 to 1024, default 64)

Maximum number of RDMA connections for TIRPC. Limiting the number of RDMA connections to 64 by default to avoid memory exhaustion.

MaxRPCRdmaCredits(uint32, range 1 to 4096, default 64)

Max credits of RDMA channel, representing the max number of outstanding NFS operations on the channel.

RPC_Ioq_ThrdMax(uint32, range 1 to 1024*128 default 200)

TIRPC ioq max simultaneous io threads

RPC_GSS_Npart(uint32, range 1 to 1021, default 13)

Partitions in GSS ctx cache table

RPC_GSS_Max_Ctx(uint32, range 1 to 1048576, default 16384)

Max GSS contexts in cache. Default 16k

RPC_GSS_Max_Gc(uint32, range 1 to 1048576, default 200)

Max entries to expire in one idle check

### Parameters for TCP:
Enable_TCP_keepalive(bool, default true)

Whether tcp sockets should use SO_KEEPALIVE

TCP_KEEPCNT(UINT32, range 0 to 255, default 0 -> use system defaults)

Maximum number of TCP probes before dropping the connection

TCP_KEEPIDLE(UINT32, range 0 to 65535, default 0 -> use system defaults)

Idle time before TCP starts to send keepalive probes

TCP_KEEPINTVL(INT32, range 0 to 65535, default 0 -> use system defaults)

Time between each keepalive probe

### NFS_IP_NAME {}
Index_Size(uint32, range 1 to 51, default 17)

Configuration for hash table for NFS Name/IP map.

Expiration_Time(uint32, range 1 to 60*60*24, default 3600)

Expiration time for ip-name mappings.

### NFS_KRB5 {}
PrincipalName(string, default "nfs")

KeytabPath(path, default "")

Kerberos keytab.

CCacheDir(path, default "/var/run/ganesha")

The ganesha credential cache.

Active_krb5(bool, default false)

Whether to activate Kerberos 5. Defaults to true (if Kerberos support is compiled in)

### DIRECTORY_SERVICES {}
DomainName(string, default "localdomain")

Domain to use if we aren't using the nfsidmap.

Idmapping_Active(bool, default true)

Whether to enable idmapping

Idmapped_User_Time_Validity(int64, range -1 to INT64_MAX, default -1)

Cache validity in seconds for idmapped-user entries. The default value is -1, which indicates fallback to older config -- "NFS_CORE_PARAM.Manage_Gids_Expiration", for backward compatibility.

Idmapped_Group_Time_Validity(int64, range -1 to INT64_MAX, default -1)

Cache validity in seconds for idmapped-group entries. The default value is -1, which indicates fallback to older config -- "NFS_CORE_PARAM.Manage_Gids_Expiration", for backward compatibility.

Root_Kerberos_Principal(enum list, values [none,nfs,root,host,all], default [all])

List of primary users/service name parts of the principal that should be assigned root privilege. Setting "all" will assign root privilege to all the options. Setting "none" in the list will override the other options in the list.

Cache_Users_Max_Count(uint32, range 0 to INT32_MAX, default INT32_MAX)

Max number of cached idmapped users

Cache_Groups_Max_Count(uint32, range 0 to INT32_MAX, default INT32_MAX)

Max number of cached idmapped groups

Cache_User_Groups_Max_Count(uint32, range 0 to INT32_MAX, default INT32_MAX)

Max number of cached user-groups entries

Negative_Cache_Time_Validity(int64, range 0 to INT64_MAX, default 300)

Cache validity in seconds for negative entries

Negative_Cache_Users_Max_Count(uint32, range 0 to INT32_MAX, default 50000)

Max number of negative cache users (the ones that failed idmapping)

Negative_Cache_Groups_Max_Count(uint32, range 0 to INT32_MAX, default 50000)

Max number of negative cache groups (the ones that failed idmapping)

Cache_Reaping_Interval(int64, range 0 to 3650*86400, default 0)

Cache reaping interval in seconds for idmapped cached entites. Its default value is set to 0, which basically means that the cache-reaping is disabled.

Max_Groups_Membership (uint32, range 0 to INT32_MAX, default 2000)

Max number of groups we allow a user to be a member of.

Pwutils_Use_Fully_Qualified_Names(bool, default false)

Whether to use fully qualified names for idmapping with pw-utils

Pwnam_Implementation (enum, default "nsswitch")

The implementation to use for pwnam idmapping

- nsswitch : use the system's nsswitch for idmapping

- sssd: use sssd directly for idmapping

Sssd_Implementation_Timeout(uint32, range 0 to INT32_MAX, default 30)

The timeout to use for each direct to sssd idmapping operations, in seconds. This is effective only when using SSSD pwnam implementation. * A value of zero doesn't mean infinity.

Sssd_Implementation_Skip_Cache(bool, default false)

Whether to skip SSSD cache when performing SSSD direct idmapping operations. This is effective only when using SSSD pwnam implementation.

### NFSv4 {}
This block is reloaded, however, only one parameter (Enforce_UTF8_Validation) is updated.

Sticky_Grace(bool, default false)

Whether to disable the sticky grace.

Graceless(bool, default false)

Whether to disable the NFSv4 grace period.

Lease_Lifetime(uint32, range 1 to 120, default 60)

The NFSv4 lease lifetime.

Grace_Period(uint32, range 0 to 180, default 90)

The NFS grace period.

DomainName(string, default NULL)

This config param is deprecated. Use DomainName in DIRECTORY_SERVICES config section.

IdmapConf(path, default "/etc/idmapd.conf")

Path to the idmap configuration file.

UseGetpwnam(bool, default false if using idmap, true otherwise)

Whether to use local password (PAM, on Linux) rather than nfsidmap.

Allow_Numeric_Owners(bool, default true)

Whether to allow bare numeric IDs in NFSv4 owner and group identifiers.

Only_Numeric_Owners(bool, default false)

Whether to ONLY use bare numeric IDs in NFSv4 owner and group identifiers.

Delegations(bool, default false)

Whether to allow delegations.

Deleg_Recall_Retry_Delay(uint32_t, range 0 to 10, default 1)

Delay after which server will retry a recall in case of failures

Preserve_Unlinked(bool, default false)

Whether to allow preserve unlinked. Refer to RFC5661, In traditional NFS, "silly rename" is used to handle open files deleted by another client by renaming them to hidden temporary names. With NFSv4.1, the OPEN4_RESULT_PRESERVE_UNLINKED flag allows the server to preserve unlinked files until all references are closed, eliminating the need for "silly rename" and simplifying client logic while ensuring efficient file lifecycle management. The support on NFS client is now generally available in RHEL8.7 and RHEL9.1.

pnfs_mds(bool, default false)

Whether this a pNFS MDS server. For FSAL Gluster, if this is true, set pnfs_mds in gluster block as well.

pnfs_ds(bool, default false)

Whether this a pNFS DS server.

RecoveryBackend(enum, default "fs")

Use different backend for client info:

- fs : filesystem

- fs_ng: filesystem (better resiliency)

- rados_kv : rados key-value

- rados_ng : rados key-value (better resiliency)

- rados_cluster: clustered rados backend (active/active)

RecoveryBackendIPBased(bool, default false)

Whether recovery backend to be used is based on the IP hosted by that Ganesha instance. By default the recovery backend is based on the node name / node id. The IP based recovery backend will help in assigning / removing IPs to Ganesha instances on the fly. Useful in case of virtual/floating IPs are in use and which need to be moved across for HA purpose.

RecoveryRoot(path, default "/var/lib/nfs/ganesha")

Specify the root recovery directory for fs or fs_ng recovery backends.

RecoveryDir(path, default "v4recov")

Specify the recovery directory name for fs or fs_ng recovery backends.

RecoveryOldDir(path, "v4old")

Specify the recovery old directory name for fs recovery backend.

Minor_Versions(enum list, values [0, 1, 2], default [0, 1, 2])

List of supported NFSV4 minor version numbers.

Slot_Table_Size(uint32, range 1 to 1024, default 64)

Size of the NFSv4.1 slot table

Enforce_UTF8_Validation(bool, default false)

Set true to enforce valid UTF-8 for path components and compound tags. Updates dynamically when a new configuration is loaded via SIGHUP.

Max_Client_Ids(uint32, range 0 to UINT32_MAX, default 0)

Specify a max limit on number of NFS4 ClientIDs supported by the server. With filesystem recovery backend, each ClientID translates to one directory. With certain workloads, this could result in reaching inode limits of the filesystem that /var/lib/nfs/ganesha is part of. The above limit can be used as a guardrail to prevent getting into this situation.

Server_Scope(string, default "")

Specify the value which is common for all cluster nodes. For e.g., Name of the cluster or cluster-id.

Server_Owner(string, default "")

Connections to servers with the same server owner can be shared by the client. This is advertised to the client on EXCHANGE_ID.

Virtual_Server(bool, default false)

When set true, Ganesha will make each IP address appear to NFSv4 clients as a separate server (trunking will not be allowed).

Ip_Based_Client_Owner_Separation(bool, default false)

Whether to distinguish between clients based on their IP address in addition to the client owner identifier provided by them for NFS4.1 and above.

Max_Open_States_Per_Client(uint32, range 0 to UINT32_MAX, default 0)

Specify the maximum number of files that could be opened by a client. One misbehaving client could potentially open multiple files and exhaust the open FD limit allowed by ganesha's cgroup. Beyond this limit, client gets denied if it tries to open too many files. To disable set to ZERO.

Expired_Client_Threshold(uint32, range 0 to 256, default 16)

Specify the threshold of number of expired clients to be kept in memory post lease period, unless the number of unresponsive clients go over this limit. Ganesha keeps track of all expired clients in LRU fashion and picks the oldest expired client when the number of clients exceeds the max limit. This allows Ganesha to retain the open & lock state and there by helping certain client workloads like MLPerf to run smoothly, even after a network partition.

Max_Open_Files_For_Expired_Client(uint32, range 0 to UINT32_MAX, default 4000)

Specify the maximum number of open files that an unresponsive client could have, beyond which Ganesha won't keep client intact in memory and expire it. Comes to play if the config Expired_Client_Threshold is not set to ZERO.

Max_Alive_Time_For_Expired_Client(uint64, range 0 to UINT64_MAX, default 86400)

Specify the max amount of time till which to keep the unresponsive client in memory, beyond which Ganesha would start reaping and expire it off. Comes to play if the config Expired_Client_Threshold is not set to ZERO.

Blocking_Locks(bool, default true)

Whether to allow blocking locks (READW_LT/WRITEW_LT) for NFSv4. When set to false, blocking lock requests will be treated as non-blocking locks (READ_LT/WRITE_LT). This means that if a lock cannot be granted immediately due to a conflict, the server will return NFS4ERR_DENIED instead of blocking the request and waiting for the lock to become available.

### RADOS_KV {}
ceph_conf(string, no default)

Connection to ceph cluster, should be file path for ceph configuration.

userid(path, no default)

User ID to ceph cluster.

namespace(string, default NULL)

RADOS Namespace in which to store objects

pool(string, default "nfs-ganesha")

Pool for client info.

grace_oid(string, default "grace")

Name of the object containing the rados_cluster grace DB

nodeid(string, default result of gethostname())

Unique node identifier within rados_cluster. If nodeid is numeric string, then internally a string is formed like "node<nodeid>" to register membership within rados_cluster. If nodeid is non-numeric string, then it is used as is. If no nodeid present, then hostname (returned via gethostname()) is used for registering the membership

### RADOS_URLS {}
ceph_conf(string, no default)

Connection to ceph cluster, should be file path for ceph configuration.

userid(path, no default)

User ID to ceph cluster.

watch_url(url, no default)

rados:// URL to watch for notifications of config changes. When a notification is received, the server will issue a SIGHUP to itself.

### FSAL_LIST {}
name(string, no default)

This allows listing of the FSALs that will be used. This assures that the config blocks for those FSALs will not result in an error if no exports are configured using that FSAL. This parameter takes a list of FSAL names and the parameter may be listed multiple times.


ganesha-export-config

package: nfs-ganesha

title: ganesha-export-config(8)

summary: NFS Ganesha Export Configuration File

text:
# ganesha-export-config(8)

## NAME
ganesha-export-config - NFS Ganesha Export Configuration File

## SYNOPSIS
/etc/ganesha/ganesha.conf

## DESCRIPTION
NFS-Ganesha obtains configuration data from the configuration file:

/etc/ganesha/ganesha.conf

This file lists NFS-Ganesha Export block config options.

### EXPORT PERMISSIONS
These options are all "export permissions" options, and are available in EXPORT_DEFAULTS {}, EXPORT {} and CLIENT {} blocks.

These options will all be dynamically updateable.

Access_Type(enum, default None)

Possible values:

None, RW, RO, MDONLY, MDONLY_RO

Protocols(enum list, default none)

Possible values:

3, 4, NFS3, NFS4, V3, V4, NFSv3, NFSv4, 9P

Transports(enum list, values [UDP, TCP, RDMA], default [UDP, TCP])

Anonymous_uid(anonid, range INT32_MIN to UINT32_MAX, default -2)

Anonymous_gid(anonid, range INT32_MIN to UINT32_MAX, default -2)

SecType(enum list, default [none, sys])

Possible values:

none, sys, krb5, krb5i, krb5p

PrivilegedPort(bool, default false)

Manage_Gids(bool, default false)

Squash(enum, default root_sqaush)

Possible values:

root, root_squash, rootsquash, rootid, root_id_squash, rootidsquash, all, all_squash, allsquash, all_anomnymous, allanonymous, no_root_squash, none, noidsquash

Each line of defaults above are synonyms

NFS_Commit(bool, default false)

Delegations(enum, default None)

Possible values:

None, read, write, readwrite, r, w, rw

### CLIENT {}
CLIENT blocks are used in EXPORT_DEFAULTS {}, EXPORT {}, and PSEUDOFS {} blocks.

Each CLIENT block provides a list of clients and the permissions granted those clients. These blocks form an ordered "access control list" for the export. If no client block matches for a particular client, then the permissions in the EXPORT {} block will be used (and if any permissions are not set between the CLIENT and the EXPORT, then the permissions set in EXPORT_DEFAULTS will be used and if still not set, then the code default will be used.

If an EXPORT does not have any CLIENT blocks then the list of CLIENT blocks in EXPORT_DEFAULTS (if any) will be used. No matter the source of the CLIENT blocks, if the client matches none, then the permissions in the EXPORT will be applied next.

To override a restrictive default client list with "everyone" a non-empty client list would have to be specified. Clients = "*" would do the trick.

Even when a CLIENT block matches a client, if a particular export permission is not explicit in that CLIENT block, the permission specified in the EXPORT block will be used, or if not specified there, from the EXPORT_DEFAULTS block, and if not specified there, the permission will default to the default code value noted in the permission option descriptions above.

Note that when the CLIENT blocks are processed on config reload, a new client access list is constructed and atomically swapped in. This allows adding, removing, and re-arranging clients as well as changing the access for any give client.

CLIENT blocks use all the EXPORT PERMISSIONS options (except PSEUDOFS CLIENT blocks which are limited to the same options the PSEUDOFS block is allowed) plus:

HA_Proxy_Protocol(enum, default any)

Possible values:

with_ha_proxy, without_ha_proxy, any

Clients(client list, empty)

Client list entries can take on one of the following forms. This parameter may be repeated to extend the list.

* Match any client @name Netgroup name x.x.x.x/y IPv4 network address, IPv6 addresses are also allowed but the format is too complex to show here

wildcarded If the string contains at least one ? or *

character (and is not simply "*"), the string is used to pattern match host names. Note that [] may also be used, but the pattern MUST have at least one ? or *

hostname Match a single client (match is by IP address, all

addresses returned by getaddrinfo will match, the getaddrinfo call is made at config parsing time)

IP address Match a single client

Any option not set in the client or export block are taken from the EXPORT_DEFAULTS block. For example, below are few scenarios: 1.If protocols=3 set in Export_Defaults block and protocols=4 set in CLIENT block of the export, then export can only be mounted via NFSv4 from client and not using NFSv3. 2.If protocols=4 set in Export_Defaults, protocols=3 set in CLIENT block of the export, then that client can mount the export using only NFSv3 3.If protocol=3,4 set in Export_Defaults, protocol=4 set in CLIENT block of the export, then that client can mount the export using only NFSv4.

If protocol not set in CLIENT block then export options will be set using Export_Defaults protocols.

### EXPORT_DEFAULTS {}
All the EXPORT PERMISSIONS options plus:

Attr_Expiration_Time(int32, range -1 to INT32_MAX, default 60)

CLIENT (optional)

See the CLIENT {} block description. There may be any number of these.

### EXPORT_DEFAULTS { CLIENT {} }
See the CLIENT {} block description.

### EXPORT {}
All options below are dynamically changeable with config update unless specified below. This block may be repeated to define multiple exports.

All the EXPORT_PERMISSIONS plus:

Export_id (required):

An identifier for the export, must be unique and between 0 and 65535. If Export_Id 0 is specified, Pseudo must be the root path (/). Export_id is not dynamic per se, changing it essentially removes the old export and introduces a new export.

Path (required)

The directory in the exported file system this export is rooted on (may be ignored for some FSALs). It need not be unique if Pseudo and/or Tag are specified. Note that if it is not unique, and the core option mount_path_pseudo is not set true, a v3 mount using the path will ONLY be able to access the first export configured. To access other exports the Tag option would need to be used.

This option is NOT dynamically updateable since it fundamentally changes the export. To change the path exported, export_id should be changed also.

Pseudo (required v4)

This option specifies the position in the Pseudo Filesystem this export occupies if this is an NFS v4 export. It must be unique. By using different Pseudo options, the same Path may be exported multiple times. This option is used to place the export within the NFS v4 Pseudo Filesystem. This creates a single name space for NFS v4. Clients may mount the root of the Pseudo Filesystem and navigate to exports. Note that the Path and Tag options are not at all visible to NFS v4 clients.

Export id 0 is automatically created to provide the root and any directories necessary to navigate to exports if there is no other export specified with Pseudo = /;. Note that if an export is specified with Pseudo = /;, it need not be export id 0. Specifying such an export with FSAL { name = PSEUDO; } may be used to create a Pseudo Filesystem with specific options. Such an export may also use other FSALs (though directories to reach exports will ONLY be automatically created on FSAL PSEUDO exports).

This option is dynamically changeable and changing it will move the export within the pseudo filesystem. This may be disruptive to clients. Note that if the mount_path_pseudo NFS_CORE_PARAM option is true, the NFSv3 mount path will also change (that should not be disruptive to clients that have the export mounted).

Tag (no default)

This option allows an alternative access for NFS v3 mounts. The option MUST not have a leading /. Clients may not mount subdirectories (i.e. if Tag = foo, the client may not mount foo/baz). By using different Tag options, the same Path may be exported multiple times. This option is not dynamically updatable.

Filesystem_id(fsid, format is uint64.uint64, default unused)

This option allows overriding the filesystem ID provided by the underlying filesystem. Use of this option is discouraged, It will not work if VFS or GPFS is exporting a filesystem that has other filesystems mounted on sub-directories and exported with the same export. This option is not dynamically updateable.

Read_Access_Check_Policy(enum, values [pre, post, all], default pre)

Whether to run permission check for read before sending the read to the FSAL, after getting the read response from the FSAL, or both before and after. This allows to optimize performance for failure flow by always checking access before sending the read, or to optimize performance for success path by storing access check result in the FSAL cache during the read and perform the access check after the read (requires the FSAL implementation to support it, so should only be used with supported FSALs). It also allow to optimize for security by running permission check both before and after.

MaxRead (64*1024*1024)

The maximum read size on this export

MaxWrite (64*1024*1024)

The maximum write size on this export

PrefRead (64*1024*1024)

The preferred read size on this export. Note that some older nfs client (e.g. libnfs 1.x) would not handle well for large preferred read size. If so, please try to decrease this size (usually less than 1M is suitable for older nfs client).

PrefWrite (64*1024*1024)

The preferred write size on this export. Note that some older nfs client (e.g. libnfs 1.x) would not handle well for large preferred write size. If so, please try to decrease this size (usually less than 1M is suitable for older nfs client).

PrefReaddir (16384)

The preferred readdir size on this export

MaxOffsetWrite (INT64_MAX)

Maximum file offset that may be written Range is 512 to UINT64_MAX

MaxOffsetRead (INT64_MAX)

Maximum file offset that may be read Range is 512 to UINT64_MAX

DisableReaddirPlus(bool, default false)

DisableDirChaching(bool, default false)

One can disable directory chaching using this option. Default value is enable directory chaching which helps in better performance for readdir operation. For highly changing export (outside of NFS workload) or where FSAL is recommending not to use directory chaching (like CEPH), then one can use this option to disable it.

Trust_Readdir_Negative_Cache(bool, default false)

The following options may have limits on dynamic effect

UseCookieVerifier(bool, default true)

Updating UseCookieVerifier while a readdir is in progress may result in unexpected behavior.

Disable_ACL(bool, default false)

Disable_ACL is processed at create_export time currently which makes it effectively a static option.

Security_Label(bool, default false)

Attr_Expiration_Time(int32, range -1 to INT32_MAX, default 60)

Attr_Expiration_Time is evaluated when an MDCACHE entry is created, so the dynamic effect of this option may be constrained to new entries.

CLIENT (optional)

See the CLIENT {} block description. There may be any number of these.

FSAL (required)

See the EXPORT { FSAL {} } block. The FSAL for an export can not be changed dynamically. In order to change the FSAL, a new export must be created.

At this time, no FSAL actually supports any updatable options.

### EXPORT { CLIENT {} }
See the CLIENT {} block description.

### EXPORT { FSAL {} }
NFS-Ganesha supports the following FSALs: Ceph Gluster GPFS PROXY_V3 PROXY_V4 RGW VFS XFS LUSTRE LIzardFS KVSFS

Refer to individual FSAL config file for list of config options.

The FSAL blocks generally are less updatable

### PSEUDOFS {}
This block allows specifying some options for the pseudofs root export. It is very similar to an EXPORT block, except only the following options may be specified. CLIENT blocks may be used just like an EXPORT block, however, they are also limited to the same options. Same is applicable to QOS_BLOCK.

This is basically a shortcut rather than having to fill out options in an EXPORT block. Note that Path, Pseudo, and Export_Id are not included as those values will be fixed ("/" for the paths, and 0 for Export_Id). Other options that don't make sense for the pseudofs root are also not allowed.

An empty PSEUDOFS {} block will produce the same default pseudofs root export as generated if no pseudofs root export is otherwise specified.

This block is most useful to override a restrictive CLIENT list in EXPORT_DEFAULTS {}.

These options will all be dynamically updateable.

Access_Type(enum, default MDONLY_RO)

Possible values:

None, MDONLY_RO

Transports(enum list, values [UDP, TCP, RDMA], default [TCP])

SecType(enum list, default [none, sys, krb5, krb5i, krb5p])

Possible values:

none, sys, krb5, krb5i, krb5p

PrivilegedPort(bool, default false)

Export_id(uint16, range 0 to UINT16_MAX, default 0)

An identifier for the export, must be unique and between 0 and 65535. Export_id is not dynamic per se, changing it essentially removes the old export and introduces a new export.

Filesystem_id(fsid, format is uint64.uint64, default 152.152)

Unlike standard exports, there is no underlying filesystem to get an ID from, so this option is important, however the default value may be used so it need not be specified. This option is not dynamically updateable.

DisableReaddirPlus(bool, default false)

Trust_Readdir_Negative_Cache(bool, default false)

The following options may have limits on dynamic effect

UseCookieVerifier(bool, default true)

Updating UseCookieVerifier while a readdir is in progress may result in unexpected behavior.

### EXPORT { QOS_BLOCK {} }
This is optional : Refer ManPage(8) ganesha-qos-config

### PSEUDOFS { QOS_BLOCK {} }
This is optional : Refer ManPage(8) ganesha-qos-config

### PSEUDOFS { CLIENT {} }
See the CLIENT {} block description but note that beyond the Clients and HA_Proxy_Protocol options that works as described, the other options available are as for the PSEUDOFS {} block.

If it is desired to override a restrictive CLIENT list in EXPORT_DEFAULTS, the following PSEUDOFS could be defined that will give all clients the default access to the pseudofs root that otherwise would have been granted if EXPORT_DEFAULTS was not used.

PSEUDOFS {

CLIENT {

Clients =

```
*
```

;

}

}

## DISCUSSION
The EXPORT blocks define the file namespaces that are served by NFS-Ganesha.

In best practice, each underlying filesystem has a single EXPORT defining how that filesystem is to be shared, however, in some cases, it is desirable to sub-divide a filesystem into multiple exports. The danger when this is done is that rogue clients may be able to spoof file handles and access portions of the filesystem not intended to be accessible to that client.

Some FSALs (currently FSAL_VFS, FSAL_GPFS, FSAL_XFS, and FSAL_LUSTRE) are built to support nested filesystems, for example:

/export/fs1 /export/fs1/some/path/fs2

In this case, it is possible to create a single export that exports both filesystems. There is a lot of complexity of what can be done there.

In discussions of filesystems, btrfs filesystems exported by FSAL_VFS may have subvolumes. Starting in NFS-Ganesha V4.0 FSAL_VFS treats these as separate filesystems that are integrated with all the richness of FSAL_VFS exports.

Another significant FSAL from an export point of view is FSAL_PSEUDO. This is used to build glue exports to build the unified NFSv4 name space. This name space may also be used by NFSv3 by setting the NFS_CORE_PARAM option:

mount_path_pseudo = TRUE;

If no FSAL_PSEUDO export is explicitly defined, and there is no EXPORT with:

Pseudo = "/";

NFS-Ganesha will build a FSAL_PSEUDO EXPORT with this Pseudo Path using Export_Id = 0. This automatic EXPORT may be replaced with an explicit EXPORT which need not have Export_Id = 0, it just must have Pseudo = "/" and Protocols = 4.

In building the Pseudo Filesystem, there is a subtle gotcha. Since NFSv4 clients actually mount the root of the Pseudo Filesystem and then use LOOKUP to traverse into the actual directory the sysadmin has mounted from the client, any EXPORTs from "/" to the desired EXPORT MUST have Protocols = 4 specified either in EXPORT_DEFAULTS {}, EXPORT {}, or EXPORT { CLIENT {} }. This is to assure that the client is allowed to traverse each EXPORT.

If Mount_Path_Pseudo = TRUE is being used and an export is desired to be NFSv3 only, Protocols = 3 MUST be specified in the EXPORT {} block. If Protocols is not specified in the EXPORT {} block and is only specified in an EXPORT { CLIENT {} } block, then that export will still be mounted in the Pseudo Filesystem but might not be traversable. Thus if the following two filesystems are exported:

/export/fs1 /export/fs1/some/path/fs2

And the EXPORTs look something like this:

EXPORT { Export_Id = 1; Path = /export/fs1; Pseudo = /export/fs1; FSAL {

Name = VFS;

}

CLIENT {

Clients="*"; Protocols=3;

}

}

EXPORT {

Export_Id = 1; Path = /export/fs1/some/path/fs2; Pseudo = /export/fs1/some/path/fs2; FSAL {

Name = VFS;

}

CLIENT {

Clients="*"; Protocols=3,4;

}

}

NFSv4 clients will not be able to access /export/fs1/some/path/fs2. The correct way to accomplish this is:

EXPORT { Export_Id = 1; Path = /export/fs1; Pseudo = /export/fs1; Protocols=3;

FSAL

{

Name = VFS;

}

}

Note that an EXPORT { CLIENT {} } block is not necessary if the default export permissions are workable.

Note that in order for an EXPORT to be usable with NSFv4 it MUST either have Protocols = 4 specified in the EXPORT block, or the EXPORT block must not have the Protocols option at all such that it defaults to 3,4,9P. Note though that if it is not set and EXPORT_DEFAULTS just has Protocols = 3; then even though the export is mounted in the Pseudo Filesystem, it will not be accessible and the gotcha discussed above may be in play.

## CONFIGURATION RELOAD
In addition to the LOG {} configuration, EXPORT {} config is the main configuration that can be updated while NFS-Ganesha is running by issuing a SIGHUP.

This causes all EXPORT and EXPORT_DEFAULTS blocks to be reloaded. NFS-Ganesha V4.0 and later have some significant improvements to this since it was introduced in NFS-Ganesha V2.4.0. V2.8.0 introduced the ability to remove EXPORTs via SIGHUP configuration reload.

Significantly how things work now is:

On SIGHUP all the EXPORT and EXPORT_DEFAULTS blocks are re-read. There are three conditions that may occur:

An export may be added An export may be removed An export may be updated

A note on Export_Id and Path. These are the primary options that define an export. If Export_Id is changed, the change is treated as a remove of the old Export_Id and an addition of the new Export_Id. Path can not be changed without also changing Export_Id. The Tag and Pseudo options that also contribute to the uniqueness of an EXPORT may be changed.

Any removed exports are removed from the internal tables and if they are NFSv4 exports, unmounted from the Pseudo Filesystem, which will then be re-built as if those exports had not been present.

Any new exports are added to the internal tables, and if the export is an NFSv4 export, they are mounted into the Pseudo Filesystem.

Any updated exports will be modified with the least disruption possible. If the Pseduo option is changed, the export is unmounted from the Pseduo Filesystem in it's original location, and re-mounted in it's new location. Other options are updated atomically, though serially, so for a short period of time, the options may be mixed between old and new. In most cases this should not cause problems. Notably though, the CLIENT blocks are processed to form a new access control list and that list is atomically swapped with the old list. If the Protocols for an EXPORT are changed to include or remove NFSv4, the Pseduo Filesystem will also be updated.

Note that there is no pause in operations other than a lock being taken when the client list is being swapped out, however the export permissions are applied to an operation once. Notably for NFSv4, this is on a PUTFH or LOOKUP which changes the Current File Handle. As an example, if a write is in progress, having passed the permission check with the previous export permissions, the write will complete without interruption. If the write is part of an NFSv4 COMPOUND, the other operations in that COMPOUND that operate on the same file handle will also complete with the previous export permissions.

An update of EXPORT_DEFAULTS changes the export options atomically. These options are only used for those options not otherwise set in an EXPORT {} or CLIENT {} block and are applied when export permissions are evaluated when a new file handle is encountered.

The FSAL { Name } may not be changed and FSALs offer limited support for changing any options in the FSAL block. Some FSALs may validate and warn if any options in the FSAL block are changed when such a change is not supported.

## SEE ALSO
ganesha-config <>(8) ganesha-rgw-config <>(8) ganesha-vfs-config <>(8) ganesha-lustre-config <>(8) ganesha-xfs-config <>(8) ganesha-gpfs-config <>(8) ganesha-9p-config <>(8) ganesha-proxy-config(8) ganesha-ceph-config <>(8) ganesha-qos-config <>(8)

branch: sisyphus


ganesha-log-config

title: ganesha-log-config(8)

summary: NFS Ganesha Log Configuration File

text:
# ganesha-log-config(8)

## NAME
ganesha-log-config - NFS Ganesha Log Configuration File

## SYNOPSIS

```
/etc/ganesha/ganesha.conf
```

## DESCRIPTION
NFS-Ganesha reads the configuration data from: | /etc/ganesha/ganesha.conf

This file lists NFS-Ganesha Log config options.

These options may be dynamically updated by issuing a SIGHUP to the ganesha.nfsd process.

### LOG {}
Default_log_level(token,default EVENT)

If this option is NOT set, the fall back log level will be that specified in the -N option on the command line if that is set, otherwise the fallback level is EVENT. If a SIGHUP is issued, any components not specified in LOG { COMPONENTS {} } will be reset to this value.

The log levels are:

NULL, FATAL, MAJ, CRIT, WARN, EVENT, INFO, DEBUG, MID_DEBUG, M_DBG, FULL_DEBUG, F_DBG

RPC_Debug_Flags(uint32, range 0 to UINT32_MAX, default 7)

Debug flags for TIRPC (default 7 matches log level default EVENT). These flags are only used if the TIRPC component is set to DEBUG

Display_UTC_Timestamp(bool, default false)

Flag to enable displaying UTC date/time in log messages instead of localtime.

Match_Policy(token, default MATCH_ANY)

Specifies how conditional logging rules are evaluated when Clients and/or Exports are configured.

MATCH_ANY

Enable conditional logging if either the client OR the export matches.

MATCH_ALL

Enable conditional logging only if both the client AND the export match.

### LOG { COMPONENTS {} }
Default_log_level(token,default EVENT)

These entries are of the form:

COMPONENT = LEVEL;

The components are:

ALL, LOG, MEMLEAKS, FSAL, NFSPROTO, NFS_V4, EXPORT, FILEHANDLE, DISPATCH, MDCACHE, MDCACHE_LRU, HASHTABLE, HASHTABLE_CACHE, DUPREQ, INIT, MAIN, IDMAPPER, NFS_READDIR, NFS_V4_LOCK, CONFIG, CLIENTID, SESSIONS, PNFS, RW_LOCK, NLM, TIRPC, NFS_CB, THREAD, NFS_V4_ACL, STATE, 9P, 9P_DISPATCH, FSAL_UP, DBUS, NFS_MSK, XPRT

Some synonyms are:

FH = FILEHANDLE HT = HASHTABLE CACHE_INODE_LRU = MDCAHCE_LRU CACHE_INODE = MDCACHE INODE_LRU = MDCAHCE_LRU INODE = MDCACHE DISP = DISPATCH LEAKS = MEMLEAKS NFS3 = NFSPROTO NFS4 = NFS_V4 HT_CACHE = HASHTABLE_CACHE NFS_STARTUP = INIT NFS4_LOCK = NFS_V4_LOCK NFS4_ACL = NFS_V4_ACL 9P_DISP = 9P_DISPATCH

The log levels are:

NULL, FATAL, MAJ, CRIT, WARN, EVENT, INFO, DEBUG, MID_DEBUG, M_DBG, FULL_DEBUG, F_DBG default none

ALL is a special component that when set, sets all components to the specified value, overriding any that are explicitly set. Note that if ALL is then removed from the config and SIGHUP is issued, all components will revert to what is explicitly set, or Default_Log_Level if that is specified, or the original log level from the -N command line option if that was set, or the code default of EVENT.

TIRPC is a special component that also sets the active RPC_Debug_Flags. If the level for TIRPC is DEBUG or MID_DEBUG, the custom RPC_Debug_Flags set by that parameter will be used, otherwise flags will depend on the level the TIRPC component is set to:

NULL or FATAL: 0 CRIT or MAJ: TIRPC_DEBUG_FLAG_ERROR

WARN: TIRPC_DEBUG_FLAG_ERROR | TIRPC_DEBUG_FLAG_WARN

EVENT or INFO: TIRPC_DEBUG_FLAG_ERROR | TIRPC_DEBUG_FLAG_WARN | TIRPC_DEBUG_FLAG_EVENT

DEBUG or MID_DEBUG: RPC_Debug_Flags

FULL_DEBUG: 0xffffffff

### LOG { CONDITIONAL {} }
Conditional logging allows selective override of log levels for specific clients or exports, while all other traffic continues to use the global COMPONENTS settings. This mechanism is useful for debugging targeted activity without increasing verbosity system-wide.

How It Works

Global Filtering (COMPONENTS block) All requests are first evaluated against the log levels defined in the top-level COMPONENTS block.These levels serve as the default for all clients and exports.

Conditional Overrides (Conditional block) The Conditional block provides a way to override component log levels only for the clients or exports explicitly listed.

If a request matches a client and/or export mentioned in the Conditional block: → Logging levels defined inside Conditional apply.

If a request does not match any entry in the Conditional block: → Logging uses only the global COMPONENTS settings.

This behavior ensures that only selected traffic receives more or less verbose logging, while all remaining traffic follows the normal log-level configuration.

Example:

```
LOG {

  COMPONENTS {

    FSAL = WARN;

    NFS4 = CRIT;

  }

  Match_Policy = MATCH_ANY;

  Conditional {

    Clients = 192.0.2.25;

    Exports = 101;

    COMPONENT_ALL = EVENT;

    NFS4 = DEBUG;

  }
}
```

Explanation:

```
* Requests originating from client/export inside the Conditional block

  are logged strictly according to conditional components (e.g. NFS4 = DEBUG,

  ALL = EVENT).
* Requests from all other clients or exports are logged strictly according to

  the top-level COMPONENTS block (e.g., FSAL = WARN, NFS4 = CRIT).
```

Clients(client list, default: empty)

- Client list entries can take on one of the following forms. This parameter may be repeated to extend the list.

- x.x.x.x IPv6 addresses are only allowed

Exports(Export list, default: empty)

•

Export list entries can take list of Export_IDs.

COMPONENT = LEVEL

The components are:

ALL, LOG, MEMLEAKS, FSAL, NFSPROTO, NFS_V4, EXPORT, FILEHANDLE, DISPATCH, MDCACHE, MDCACHE_LRU, HASHTABLE, HASHTABLE_CACHE, DUPREQ, INIT, MAIN, IDMAPPER, NFS_READDIR, NFS_V4_LOCK, CONFIG, CLIENTID, SESSIONS, PNFS, RW_LOCK, NLM, TIRPC, NFS_CB, THREAD, NFS_V4_ACL, STATE, 9P, 9P_DISPATCH, FSAL_UP, DBUS, NFS_MSK, XPRT

Some synonyms are:

FH = FILEHANDLE HT = HASHTABLE CACHE_INODE_LRU = MDCAHCE_LRU CACHE_INODE = MDCACHE INODE_LRU = MDCAHCE_LRU INODE = MDCACHE DISP = DISPATCH LEAKS = MEMLEAKS NFS3 = NFSPROTO NFS4 = NFS_V4 HT_CACHE = HASHTABLE_CACHE NFS_STARTUP = INIT NFS4_LOCK = NFS_V4_LOCK NFS4_ACL = NFS_V4_ACL 9P_DISP = 9P_DISPATCH

The log levels are:

NULL, FATAL, MAJ, CRIT, WARN, EVENT, INFO, DEBUG, MID_DEBUG, M_DBG, FULL_DEBUG, F_DBG], default FULL_DEBUG

ALL is a special component that when set, sets all components to the specified value, overriding any that are explicitly set. default is set to FULL_DEBUG. COMPONENT_ALL in Conditional acts as fallback for any unspecified components.

### LOG { FACILITY {} }
This block may be repeated to configure multiple log facilities.

name(string, no default)

destination(string, no default, must be supplied)

max_level(token,default FULL_DEBUG)

The log levels are:

NULL, FATAL, MAJ, CRIT, WARN, EVENT, INFO, DEBUG, MID_DEBUG, M_DBG, FULL_DEBUG, F_DBG

headers(token, values [none, component, all], default all)

enable(token, values [idle, active, default], default idle)

### LOG { FORMAT {} }
date_format(enum,default ganesha)

Possible values:

ganesha, true, local, 8601, ISO-8601, ISO 8601, ISO, syslog, syslog_usec, false, none, user_defined

time_format(enum,default ganesha)

Possible values:

ganesha, true, local, 8601, ISO-8601, ISO 8601, ISO, syslog, syslog_usec, false, none, user_defined

user_date_format(string, no default)

user_time_format(string, no default)

EPOCH(bool, default true)

CLIENTIP(bool, default false)

HOSTNAME(bool, default true)

PROGNAME(bool, default true)

PID(bool, default true)

THREAD_NAME(bool, default true)

FILE_NAME(bool, default true)

LINE_NUM(bool, default true)

FUNCTION_NAME(bool, default true)

COMPONENT(bool, default true)

LEVEL(bool, default true)

OP_ID(bool, default false)

CLIENT_REQ_XID(bool, default false)

## SEE ALSO
ganesha-config <>(8)


ganesha-ceph-config

package: nfs-ganesha-ceph

title: ganesha-ceph-config(8)

summary: NFS Ganesha CEPH Configuration File

text:
# ganesha-ceph-config(8)

## NAME
ganesha-ceph-config - NFS Ganesha CEPH Configuration File

## SYNOPSIS

```
/etc/ganesha/ceph.conf
```

## DESCRIPTION
NFS-Ganesha install config example for CEPH FSAL: | /etc/ganesha/ceph.conf

This file lists CEPH specific config options.

### EXPORT { FSAL {} }
Name(string, "Ceph")

Name of FSAL should always be Ceph.

Filesystem(string, no default)

Ceph filesystem name string, for mounting an alternate filesystem within the cluster. The default is to mount the default filesystem in the cluster (usually, the first one created).

User_Id(string, no default)

cephx userid used to open the MDS session. This string is what gets appended to "client.". If not set, the ceph client libs will sort this out based on ceph configuration.

Secret_Access_Key(string, no default)

Key to use for the session (if any). If not set, then it uses the normal search path for cephx keyring files to find a key.

sec_label_xattr(char, default "security.selinux xattr of the file")

Enable NFSv4.2 security label attribute. Ganesha supports "Limited Server Mode" as detailed in RFC 7204. Note that not all FSALs support security labels.

cmount_path(string, no default)

If specified, the path within the ceph filesystem to mount this export on. It is allowed to be any complete path hierarchy between / and the EXPORT {path}. (i.e. if EXPORT { Path } parameter is /foo/bar then cmount_path could be /, /foo or /foo/bar). If this and the other EXPORT { FSAL {} } options are the same between multiple exports, those exports will share a single cephfs client. With the default, this effectively defaults to the same path as EXPORT { Path }.

### CEPH {}
Ceph_Conf(path, default "")

Path to the ceph config file to inherit ceph configuration from.

umask(mode, range 0 to 0777, default 0)

client_oc(bool, default false)

Enable or disable client_oc (object cache). This defaults to false because Ganesha runs better with it disabled.

async(bool, default false)

Enable ceph async operations (read and write).

zerocopy(bool, default false)

Enable ceph zero copy I/O. Zero copy and client_oc are incompatible.

use_old_uuid(bool, default false)

Use old uuid logic for ceph client. Useful when upgrading from pre 7.0 version to latest. If this flag is set, then continue using it. As per old logic the uuid is formed as "ganesha-<nodeid>-<export-id>". As per new logic the uuid is formed as "ganesha-<64-bytes-hash>", and the hash is formed using nodeid, userid, fs_name and mount path. For fresh deployments of 7.0 and later versions do not set this parameter.

register_service(bool, default false)

Enable registration of the NFS service with the Ceph cluster. This allows Ceph to track the NFS service for health monitoring and service discovery.

nodeid(string, default "")

Identifier used when registering this NFS instance with Ceph. This value must be unique per NFS node within the same Ceph cluster. Required only when register_service is set to true.

## SEE ALSO
ganesha-config <>(8) ganesha-log-config <>(8) ganesha-core-config <>(8) ganesha-export-config <>(8)


ganesha-gluster-config

package: nfs-ganesha-gluster

title: ganesha-gluster-config(8)

summary: NFS Ganesha Gluster Configuration File

text:
# ganesha-gluster-config(8)

## NAME
ganesha-gluster-config - NFS Ganesha Gluster Configuration File

## SYNOPSIS

```
/etc/ganesha/gluster.conf
```

## DESCRIPTION
NFS-Ganesha installs the following sample config file for Gluster FSAL: | /etc/ganesha/gluster.conf

This file lists Gluster specific config options.

### EXPORT { FSAL {} }
Name(string, "GLUSTER")

Name of FSAL should always be GLUSTER.

volume(string, no default, required)

hostname(string, no default, required)

volpath(path, default "/")

glfs_log(path, default "/var/log/ganesha/ganesha-gfapi.log")

up_poll_usec(uint64, range 1 to 60*1000*1000, default 10)

enable_upcall(bool, default true)

transport(enum, values [tcp, rdma], default tcp)

sec_label_xattr(char, default "security.selinux xattr of the file")

### GLUSTER {}
PNFS_MDS(bool, default FALSE)

Set this parameter to true to select this node as MDS

## SEE ALSO
ganesha-log-config <>(8) ganesha-core-config <>(8) ganesha-export-config <>(8)


title: ganesha-proxy-v3-config(8)

summary: NFSv3 Ganesha Proxy Configuration File

text:
# ganesha-proxy-v3-config(8)

## NAME
ganesha-proxy-v3-config - NFSv3 Ganesha Proxy Configuration File

## SYNOPSIS

```
/etc/ganesha/ganesha.conf
```

## DESCRIPTION
NFS-Ganesha install the following config file for Proxy FSAL: | /etc/ganesha/ganesha.conf

This file lists Proxy specific config options.

### EXPORT { FSAL {} }
Name(string, "proxy_v3")

Name of FSAL should always be proxy_v3.

Srv_Addr(ipv4_addr default "127.0.0.1")

FSAL_MAXIOSIZE(default 64 MB)

### PROXY_V3 {}
FSAL_MAXIOSIZE(default 64 MB)

maxread(uint64, default 1 MB)

range 1024 to FSAL_MAXIOSIZE Note that this value will get clamped to the backend's FSINFO response.

maxwrite(uint64, default 1 MB)

range 1024 to FSAL_MAXIOSIZE Note that this value will get clamped to the backend's FSINFO response.

num_sockets(uint32, default 32)

range 1 to 1000 Note that these sockets must be privileged ports, which may be limited on a given system. It is unlikely that 1000 privileged ports are available.

allow_lookup_optimization(bool, default true)

Set this to false to disable lookup optimization for current working directory and current working directory parent from the cache

## SEE ALSO
ganesha-log-config <>(8) ganesha-core-config <>(8) ganesha-export-config <>(8)


title: ganesha-proxy-v4-config(8)

summary: NFS Ganesha Proxy V4 Configuration File

text:
# ganesha-proxy-v4-config(8)

## NAME
ganesha-proxy-v4-config - NFS Ganesha Proxy V4 Configuration File

## SYNOPSIS

```
/etc/ganesha/ganesha.conf
```

## DESCRIPTION
NFS-Ganesha install the following config file for Proxy V4 FSAL: | /etc/ganesha/ganesha.conf

This file lists Proxy V4 specific config options.

### EXPORT { FSAL {} }
Name(string, "proxy_v4")

Name of FSAL should always be proxy_v4.

Retry_SleepTime(uint32, range 0 to 60, default 10)

Srv_Addr(ipv4_addr default "127.0.0.1")

NFS_Service(uint32, range 0 to UINT32_MAX, default 100003)

NFS_SendSize

must be greater than maxwrite+SEND_RECV_HEADER_SPACE

NFS_RecvSize

must be greater than maxread+SEND_RECV_HEADER_SPACE

MAX_READ_WRITE_SIZE(default 1 MB)

SEND_RECV_HEADER_SPACE(default 512 Bytes)

FSAL_MAXIOSIZE(default 64 MB)

NFS_SendSize(uint64, default MAX_READ_WRITE_SIZE + SEND_RECV_HEADER_SPACE)

range 512 + SEND_RECV_HEADER_SPACE to FSAL_MAXIOSIZE

NFS_RecvSize(uint64, default MAX_READ_WRITE_SIZE + SEND_RECV_HEADER_SPACE)

range 512 + SEND_RECV_HEADER_SPACE to FSAL_MAXIOSIZE

NFS_Port(uint16, range 0 to UINT16_MAX, default 2049)

Use_Privileged_Client_Port(bool, default true)

RPC_Client_Timeout(uint32, range 1 to 60*4, default 60)

Remote_PrincipalName(string, no default)

KeytabPath(string, default "/etc/krb5.keytab")

Credential_LifeTime(uint32, range 0 to 86400*2, default 86400)

Sec_Type(enum, values [krb5, krb5i, krb5p], default krb5)

Active_krb5(bool, default false)

Enable_Handle_Mapping(bool, default false)

HandleMap_DB_Dir(string, default "/var/ganesha/handlemap")

HandleMap_Tmp_Dir(string, default "/var/ganesha/tmp")

HandleMap_DB_Count(uint32, range 1 to 16, default 8)

HandleMap_HashTable_Size(uint32, range 1 to 127, default 103)

### PROXY_V4 {}
link_support(bool, default true)

symlink_support(bool, default true)

cansettime(bool, default true)

MAX_READ_WRITE_SIZE(default 1MB)

FSAL_MAXIOSIZE(default 64 MB)

SEND_RECV_HEADER_SPACE(default, 512 Bytes)

maxread(uint64, default MAX_READ_WRITE_SIZE)

range 512 to FSAL_MAXIOSIZE - SEND_RECV_HEADER_SPACE

maxwrite(uint64, default MAX_READ_WRITE_SIZE)

range 512 to FSAL_MAXIOSIZE - SEND_RECV_HEADER_SPACE

umask(mode, range 0 to 0777, default 0)

auth_xdev_export(bool, default false)

## SEE ALSO
ganesha-log-config <>(8) ganesha-core-config <>(8) ganesha-export-config <>(8)


ganesha-rados-cluster-design

package: nfs-ganesha-rados-grace

title: ganesha-rados-cluster-design(8)

summary: Clustered RADOS Recovery Backend Design

text:
# ganesha-rados-cluster-design(8)

## NAME
ganesha-rados-cluster-design - Clustered RADOS Recovery Backend Design

## OVERVIEW
This document aims to explain the theory and design behind the rados_cluster recovery backend, which coordinates grace period enforcement among multiple, independent NFS servers.

In order to understand the clustered recovery backend, it's first necessary to understand how recovery works with a single server:

## SINGLETON SERVER RECOVERY
NFSv4 is a lease-based protocol. Clients set up a relationship to the server and must periodically renew their lease in order to maintain their ephemeral state (open files, locks, delegations or layouts).

When a singleton NFS server is restarted, any ephemeral state is lost. When the server comes comes back online, NFS clients detect that the server has been restarted and will reclaim the ephemeral state that they held at the time of their last contact with the server.

## SINGLETON GRACE PERIOD
In order to ensure that we don't end up with conflicts, clients are barred from acquiring any new state while in the Recovery phase. Only reclaim operations are allowed.

This period of time is called the grace period. Most NFS servers have a grace period that lasts around two lease periods, however nfs-ganesha can and will lift the grace period early if it determines that no more clients will be allowed to recover.

Once the grace period ends, the server will move into its Normal operation state. During this period, no more recovery is allowed and new state can be acquired by NFS clients.

## REBOOT EPOCHS
The lifecycle of a singleton NFS server can be considered to be a series of transitions from the Recovery period to Normal operation and back. In the remainder of this document we'll consider such a period to be an epoch, and assign each a number beginning with 1.

Visually, we can represent it like this, such that each Normal -> Recovery transition is marked by a change in the epoch value:

```
+-------+-------+-------+---------------+-------+
| State | R | N | R | N | R | R | R | N | R | N |
+-------+-------+-------+---------------+-------+
| Epoch |   1   |   2   |       3       |   4   |
+-------+-------+-------+---------------+-------+
```

Note that it is possible to restart during the grace period (as shown above during epoch 3). That just serves to extend the recovery period and the epoch. A new epoch is only declared during a Recovery -> Normal transition.

## CLIENT RECOVERY DATABASE
There are some potential edge cases that can occur involving network partitions and multiple reboots. In order to prevent those, the server must maintain a list of clients that hold state on the server at any given time. This list must be maintained on stable storage. If a client sends a request to reclaim some state, then the server must check to make sure it's on that list before allowing the request.

Thus when the server allows reclaim requests it must always gate it against the recovery database from the previous epoch. As clients come in to reclaim, we establish records for them in a new database associated with the current epoch.

The transition from recovery to normal operation should perform an atomic switch of recovery databases. A recovery database only becomes legitimate on a recovery to normal transition. Until that point, the recovery database from the previous epoch is the canonical one.

## EXPORTING A CLUSTERED FILESYSTEM
Let's consider a set of independent NFS servers, all serving out the same content from a clustered backend filesystem of any flavor. Each NFS server in this case can itself be considered a clustered FS client. This means that the NFS server is really just a proxy for state on the clustered filesystem.

The filesystem must make some guarantees to the NFS server. First filesystem guarantee:

1.

The filesystem ensures that the NFS servers (aka the FS clients) cannot obtain state that conflicts with that of another NFS server.

This is somewhat obvious and is what we expect from any clustered filesystem outside of any requirements of NFS. If the clustered filesystem can provide this, then we know that conflicting state during normal operations cannot be granted.

The recovery period has a different set of rules. If an NFS server crashes and is restarted, then we have a window of time when that NFS server does not know what state was held by its clients.

If the state held by the crashed NFS server is immediately released after the crash, another NFS server could hand out conflicting state before the original NFS client has a chance to recover it.

This must be prevented. Second filesystem guarantee:

2.

The filesystem must not release state held by a server during the previous epoch until all servers in the cluster are enforcing the grace period.

In practical terms, we want the filesystem to provide a way for an NFS server to tell it when it's safe to release state held by a previous instance of itself. The server should do this once it knows that all of its siblings are enforcing the grace period.

Note that we do not require that all servers restart and allow reclaim at that point. It's sufficient for them to simply begin grace period enforcement as soon as possible once one server needs it.

## CLUSTERED GRACE PERIOD DATABASE
At this point the cluster siblings are no longer completely independent, and the grace period has become a cluster-wide property. This means that we must track the current epoch on some sort of shared storage that the servers can all access.

Additionally we must also keep track of whether a cluster-wide grace period is in effect. Any running nodes should all be informed when either of this info changes, so they can take appropriate steps when it occurs.

In the rados_cluster backend, we track these using two epoch values:

C: is the current epoch. This represents the current epoch value

of the cluster

R: is the recovery epoch. This represents the epoch from which

clients are allowed to recover. A non-zero value here means that a cluster-wide grace period is in effect. Setting this to 0 ends that grace period.

In order to decide when to make grace period transitions, each server must also advertise its state to the other nodes. Specifically, each server must be able to determine these two things about each of its siblings:

1.

Does this server have clients from the previous epoch that will require recovery? (NEED)

2.

Is this server enforcing the grace period by refusing non-reclaim locks? (ENFORCING)

We do this with a pair of flags per sibling (NEED and ENFORCING). Each server typically manages its own flags.

The rados_cluster backend stores all of this information in a single RADOS object that is modified using read/modify/write cycles. Typically we'll read the whole object, modify it, and then attempt to write it back. If something changes between the read and write, we redo the read and try it again.

## CLUSTERED CLIENT RECOVERY DATABASES
In rados_cluster the client recovery databases are stored as RADOS objects. Each NFS server has its own set of them and they are given names that have the current epoch (C) embedded in it. This ensures that recovery databases are specific to a particular epoch.

In general, it's safe to delete any recovery database that precedes R when R is non-zero, and safe to remove any recovery database except for the current one (the one with C in the name) when the grace period is not in effect (R==0).

## ESTABLISHING A NEW GRACE PERIOD
When a server restarts and wants to allow clients to reclaim their state, it must establish a new epoch by incrementing the current epoch to declare a new grace period (R=C; C=C+1).

The exception to this rule is when the cluster is already in a grace period. Servers can just join an in-progress grace period instead of establishing a new one if one is already active.

In either case, the server should also set its NEED and ENFORCING flags at the same time.

The other surviving cluster siblings should take steps to begin grace period enforcement as soon as possible. This entails "draining off" any in-progress state morphing operations and then blocking the acquisition of any new state (usually with a return of NFS4ERR_GRACE to clients that attempt it). Again, there is no need for the survivors from the previous epoch to allow recovery here.

The surviving servers must however establish a new client recovery database at this point to ensure that their clients can do recovery in the event of a crash afterward.

Once all of the siblings are enforcing the grace period, the recovering server can then request that the filesystem release the old state, and allow clients to begin reclaiming their state. In the rados_cluster backend driver, we do this by stalling server startup until all hosts in the cluster are enforcing the grace period.

## LIFTING THE GRACE PERIOD
Transitioning from recovery to normal operation really consists of two different steps:

1.

the server decides that it no longer requires a grace period, either due to it timing out or there not being any clients that would be allowed to reclaim.

2.

the server stops enforcing the grace period and transitions to normal operation

These concepts are often conflated in singleton servers, but in a cluster we must consider them independently.

When a server is finished with its own local recovery period, it should clear its NEED flag. That server should continue enforcing the grace period however until the grace period is fully lifted. The server must not permit reclaims after clearing its NEED flag, however.

If the servers' own NEED flag is the last one set, then it can lift the grace period (by setting R=0). At that point, all servers in the cluster can end grace period enforcement, and communicate that fact to the others by clearing their ENFORCING flags.


ganesha-rados-grace

title: ganesha-rados-grace(8)

text:
# ganesha-rados-grace(8)

## NAME
ganesha-rados-grace - manipulate the shared grace management database

## SYNOPSIS

```
ganesha-rados-grace [ --cephconf /path/to/ceph.conf ] [--ns namespace] [ --oid obj_id ] [ --pool pool_id ] [ --userid cephuser ] dump|add|start|join|lift|remove|enforce|noenforce|member [ nodeid ... ]
```

## DESCRIPTION
This tool allows the administrator to directly manipulate the database used by the rados_cluster recovery backend. Cluster nodes use that database to indicate their current state in order to coordinate a cluster-wide grace period.

The first argument should be a command to execute against the database. Any remaining arguments represent the nodeids of nodes in the cluster that should be acted upon.

Most commands will just fail if the grace database is not present. The exception to this rule is the add command which will create the pool, database and namespace if they do not already exist.

Note that this program does not consult ganesha.conf. If you use non-default values for ceph_conf, userid, grace_oid, namespace or pool in your RADOS_KV config block, then they will need to passed in via command-line options.

## OPTIONS
--cephconf

Specify the ceph.conf configuration that should be used (default is to use the normal search path to find one)

--ns

Set the RADOS namespace to use within the pool (default is NULL)

--oid

Set the object id of the grace database RADOS object (default is "grace")

--pool

Set the RADOS poolid in which the grace database object resides (default is "nfs-ganesha")

--userid

Set the cephx user ID to use when contacting the cluster (default is NULL)

## COMMANDS
dump

Dump the current status of the grace period database to stdout. This will show the current and recovery epoch serial numbers, as well as a list of hosts currently in the cluster and what flags they have set in their individual records.

add

Add the specified hosts to the cluster. This must be done before the given hosts can take part in the cluster. Attempts to modify the database by cluster hosts that have not yet been added will generally fail. New hosts are added with the enforcing flag set, as they are unable to hand out new state until their own grace period has been lifted.

start

Start a new grace period. This will begin a new grace period in the cluster if one is not already active and set the record for the listed cluster hosts as both needing a grace period and enforcing the grace period. If a grace period is already active, then this is equivalent to join.

join

Attempt to join an existing grace period. This works like start, but only if there is already an existing grace period in force.

lift

Attempt to lift the current grace period. This will clear the need grace flags for the listed hosts. If there are no more hosts in the cluster that require a grace period, then it will be fully lifted and the cluster will transition to normal operations.

remove

Remove one or more existing hosts from the cluster. This will remove the listed hosts from the grace database, possibly lifting the current grace period if there are no more hosts that need one.

enforce

Set the flag for the given hosts that indicates that they are currently enforcing the grace period; not allowing the acquisition of new state by clients.

noenforce

Clear the enforcing flag for the given hosts, meaning that those hosts are now allowing clients to acquire new state.

member

Test whether the given hosts are members of the cluster. Returns an error if any of the hosts are not present in the grace db omap.

## FLAGS
When the dump command is issued, ganesha-rados-grace will display a list of all of the nodes in the grace database, and any flags they have set. The flags are as follows:

E (Enforcing)

The node is currently enforcing the grace period by rejecting requests from clients to acquire new state.

N (Need Grace)

The node currently requires a grace period. Generally, this means that the node has clients that need to perform recovery.

## NODEID ASSIGNMENT
Each running ganesha daemon requires a nodeid string that is unique within the cluster. This can be any value as ganesha treats it as an opaque string. By default, the ganesha daemon will use the hostname of the node where it is running.

This may not be suitable when running under certain HA clustering infrastructure, so it's generally recommended to manually assign nodeid values to the hosts in the RADOS_KV config block of ganesha.conf.

## GANESHA CONFIGURATION
The ganesha daemon will need to be configured with the RecoveryBackend set to rados_cluster. If you use a non-default pool, namespace or oid, nodeid then those values will need to be set accordingly in the RADOS_KV config block as well.

## STARTING A NEW CLUSTER
First, add the given cluster nodes to the grace database. Assuming that the nodes in our cluster will have nodeids ganesha-1 through ganesha-3:

ganesha-rados-grace add ganesha-1 ganesha-2 ganesha-3

Once this is done, you can start the daemons on each host and they will coordinate to start and lift the grace periods as-needed.

## ADDING NODES TO A RUNNING CLUSTER
After this point, new nodes can then be added to the cluster as needed using the add command:

ganesha-rados-grace add ganesha-4

After the node has been added, ganesha.nfsd can then be started. It will then request a new grace period as-needed.

## REMOVING A NODE FROM THE CLUSTER
To remove a node from the cluster, first unmount any clients that have that node mounted (possibly moving them to other servers). Then execute the remove command with the nodeids to be removed from the cluster. For example:

ganesha-rados-grace remove ganesha-4

This will remove the ganesha-4's record from the database, and possibly lift the current grace period if one is active and it was the last one to need it.


ganesha-rgw-config

package: nfs-ganesha-rgw

title: ganesha-rgw-config(8)

summary: NFS Ganesha RGW Configuration File

text:
# ganesha-rgw-config(8)

## NAME
ganesha-rgw-config - NFS Ganesha RGW Configuration File

## SYNOPSIS

```
/etc/ganesha/rgw.conf
```

```
/etc/ganesha/rgw_bucket.conf
```

## DESCRIPTION
NFS-Ganesha install two config examples for RGW FSAL:

```
/etc/ganesha/rgw.conf
```

```
/etc/ganesha/rgw_bucket.conf
```

This file lists RGW specific config options.

### EXPORT { }
RGW supports exporting both the buckets and filesystem.

### EXPORT { FSAL {} }
Name(string, "RGW")

Name of FSAL should always be RGW.

User_Id(string, no default)

Access_Key(string, no default)

Secret_Access_Key(string, no default)

### RGW {}
The following configuration variables customize the startup of the FSAL's radosgw instance.

ceph_conf

optional full-path to the Ceph configuration file (equivalent to passing "-c /path/to/ceph.conf" to any Ceph binary

name

optional instance name (equivalent to passing "--name client.rgw.foohost" to the radosgw binary); the value provided here should be the same as the section name (sans brackets) of the radosgw facility in the Ceph configuration file (which must exist)

cluster

optional cluster name (equivalent to passing "--cluster foo" to any Ceph binary); use of a non-default value for cluster name is uncommon, but can be verified by examining the startup options of Ceph binaries

init_args

additional argument strings which will be passed verbatim to the radosgw instance startup process as if they had been given on the radosgw command line provided for customization in uncommon setups

## SEE ALSO
ganesha-log-config <>(8) ganesha-core-config <>(8) ganesha-export-config <>(8)


package: nfs-ganesha-utils

title: ganesha_conf(8)

summary: Ganesha configuration editor

text:
# ganesha_conf(8)

## NAME
ganesha_conf - Ganesha configuration editor

## SYNOPSIS
ganesha_conf set <block-description> [--key1 value1 [--key2 value2]...]

ganesha_conf del <block-description> [--key1 [--key2 ]...]

## DESCRIPTION
The set command adds or changes the given key value parameters in the block. It also creates the block if the block corresponding to the given block description (see section BLOCK DESCRIPTION below) is not present in the configuration.

The del command deletes given keys from the ganesha configuration block described by the block description. It will delete the block itself if no keys are provided.

## BLOCK DESCRIPTION:
Block description is a list of block names and possibly some key value parameters that uniquely identify a ganesha configuration block.

NFS Ganesha configuration file contains a list of blocks. Each block starts with a block name followed by a left brace, then a list of key = value; entries. The block may optionally have sub blocks (note the recursive definition!). Finally, the block ends with a right brace. (Note that key = value; entries can come after a sub block as well, but we don't allow this with ganesha_conf editor! All key value entries should come before any sub blocks.)

An example of a ganesha configuration block:

```
nfs_core_param {

    Nb_Worker = 256;

    Clustered = TRUE;

    NFS_Protocols = 3,4;
}
```

Since there should be only one nfs_core_param block, we just need the name of the block to uniquely identify it. So "nfs_core_param" would be its block description!

An example of a ganesha configuration block with a couple sub blocks:

```
log {

    default_log_level = EVENT;

    format {

        date_format = ISO-8601;

        time_format = ISO-8601;

        thread_name = TRUE;

    }

    components {

        all = EVENT;

    }
}
```

Ganesha configuration should have only one log block as well, so "log" would identify the log block. To identify format sub block inside the log block, "log format" would be the block description for the above format sub block. Similarly "log components" would be the block description for the above components sub block.

An export block is special in that there can be many export blocks, one for each export. A client block is also special. There can be many client blocks and they are always sub blocks inside export blocks. export_id key value uniquely identifies an export block. clients key value uniquely identifies a client block inside a given export block.

Here are couple export blocks with couple client blocks in them:

```
export {

    export_id = 1;

    path = /fs1/export1;

    pseudo = /fs1/export1;

    manage_gids = true;

    client {

        clients = 192.168.122.31;

        access_type = RW;

    }

    client {

        clients = *;

        access_type = RO;

    }
}
export {

    export_id = 2;

    path = /fs1/export2;

    pseudo = /fs1/export2;

    manage_gids = true;

    client {

        clients = 192.168.122.31;

        access_type = RW;

    }

    client {

        clients = 192.168.122.32;

        access_type = RO;

    }
}
```

To identify the correct export block, we need to supply its export_id. For example "export export_id 2" identifies the second export block above. export blocks can be uniquely identified by pseudo or path keys in some environments. One could specify "export path /fs1/export2" to identify the second export block as well. Similarly, a client block needs additional clients key value to identify the correct client block. For example, "export export_id 2 client clients 192.168.122.31" identifies the first client block in the second export block above!

## EXAMPLES:
1. To change number of ganesha worker threads:

ganesha_conf set nfs_core_param --nb_worker 256

2. To change the date and time format of ganesha log messages:

ganesha_conf set log format --date_format ISO-8601 --time_format ISO-8601

3. Create an export and allow client with IP address 192.168.122.31 to be able to do read write and all other clients to do read only:

ganesha_conf set export path /fs1/export2 --export_id 2 --pseudo /fs1/export2 --manage_gids true

ganesha_conf set export path /fs1/export2 client clients 192.168.122.31 --access_type RW

ganesha_conf set export path /fs1/export2 client clients 192.168.122.32 --access_type RO

## NOTES:
ganesha_conf by default uses /etc/ganesha/ganesha.conf file as the configuration file. If your environment uses a different file (or set of files), you can use CONFFILE environment variable to override the default configuration file. For example, "CONFFILE=/etc/ganesha/ganesha.main.conf ganesha_conf set nfs_core_param --nb_worker 256" will use /etc/ganesha/ganesha.main.conf file for changing the worker threads.

ganesha_conf can't handle comments within a block at this point.

Neither block descriptions nor key value parameters are verified to be valid ganesha configuration blocks or parameter values currently.


ganesha-vfs-config

package: nfs-ganesha-vfs

title: ganesha-vfs-config(8)

summary: NFS Ganesha VFS Configuration File

text:
# ganesha-vfs-config(8)

## NAME
ganesha-vfs-config - NFS Ganesha VFS Configuration File

## SYNOPSIS

```
/etc/ganesha/vfs.conf
```

## DESCRIPTION
NFS-Ganesha installs the config example for VFS FSAL: | /etc/ganesha/vfs.conf

This file lists VFS specific config options.

### EXPORT { FSAL {} }
Name(string, "vfs")

Name of FSAL should always be vfs.

pnfs(bool, default false)

fsid_type(enum)

Possible values: None, One64, Major64, Two64, uuid, Two32, Dev,Device

### VFS {}
link_support(bool, default true)

symlink_support(bool, default true)

cansettime(bool, default true)

maxread(uint64, range 512 to 64*1024*1024, default 64*1024*1024)

maxwrite(uint64, range 512 to 64*1024*1024, default 64*1024*1024)

umask(mode, range 0 to 0777, default 0)

auth_xdev_export(bool, default false)

only_one_user(bool, default false)

## SEE ALSO
ganesha-log-config <>(8) ganesha-core-config <>(8) ganesha-export-config <>(8)


exportd

package: nfs-server

title: exportd(8)

summary: NFSv4 Server Mount Daemon

text:
# exportd(8)

## NAME
nfsv4.exportd - NFSv4 Server Mount Daemon

## SYNOPSIS
/usr/sbin/nfsv4.exportd [options]

## DESCRIPTION
The nfsv4.exportd is used to manage NFSv4 exports. The NFS server (nfsd) maintains a cache of authentication and authorization information which is used to identify the source of each request, and then what access permissions that source has to any local filesystem. When required information is not found in the cache, the server sends a request to nfsv4.exportd to fill in the missing information. nfsv4.exportd uses a table of information stored in /var/lib/nfs/etab and maintained by exportfs(8), possibly based on the contents of exports(5), to respond to each request.

## OPTIONS
-d kind or --debug kind

Turn on debugging. Valid kinds are: all, auth, call, general and parse.

-l or --log-auth

Enable logging of responses to authentication and access requests from nfsd. Each response is then cached by the kernel for 30 minutes (or as set by --ttl below), and will be refreshed after 15 minutes (half the ttl time) if the relevant client remains active. Note that -l is equivalent to -d auth and so can be enabled in /etc/nfs.conf with "debug = auth" in the [exportd] section.

-i or --cache-use-ipaddr

Normally each client IP address is matched against each host identifier (name, wildcard, netgroup etc) found in /etc/exports and a combined identity is formed from all matching identifiers. Often many clients will map to the same combined identity so performing this mapping reduces the number of distinct access details that the kernel needs to store. Specifying the -i option suppresses this mapping so that access to each filesystem is requested and cached separately for each client IP address. Doing this can increase the burden of updating the cache slightly, but can make the log messages produced by the -l option easier to read.

-T or --ttl

Provide a time-to-live (TTL) for cached information given to the kernel. The kernel will normally request an update if the information is needed after half of this time has expired. Increasing the provided number, which is in seconds, reduces the rate of cache update requests, and this is particularly noticeable when these requests are logged with -l. However increasing also means that changes to hostname to address mappings can take longer to be noticed. The default TTL is 1800 (30 minutes).

-F or --foreground

Run in foreground (do not daemonize)

-h or --help

Display usage message.

-t N or --num-threads=N or --num-threads N

This option specifies the number of worker threads that nfsv4.exports spawns. The default is 1 thread, which is probably enough. More threads are usually only needed for NFS servers which need to handle mount storms of hundreds of NFS mounts in a few seconds, or when your DNS server is slow or unreliable.

-g or --manage-gids

Accept requests from the kernel to map user id numbers into lists of group id numbers for use in access control. An NFS request will normally (except when using Kerberos or other cryptographic authentication) contain a user-id and a list of group-ids. Due to a limitation in the NFS protocol, at most 16 groups ids can be listed. If you use the -g flag, then the list of group ids received from the client will be replaced by a list of group ids determined by an appropriate lookup on the server. Note that the 'primary' group id is not affected so a newgroup command on the client will still be effective. This function requires a Linux Kernel with version at least 2.6.21.

-L or --no-netlink

Disable the use of netlink for kernel communication and force the use of the legacy /proc/net/rpc interfaces instead. This can be useful for debugging or working around kernel netlink issues.

## CONFIGURATION FILE
Many of the options that can be set on the command line can also be controlled through values set in the [exportd] or, in some cases, the [nfsd] sections of the /etc/nfs.conf configuration file. Values recognized in the [exportd] section include cache-use-ipaddr , ttl, manage-gids, no-netlink, and debug which each have the same effect as the option with the same name.

## FILES
/etc/exports

input file for exportfs, listing exports, export options, and access control lists

## SEE ALSO
exportfs(8), exports(5), showmount(8), nfs.conf(5), firewall-cmd(1),

RFC 7530 - "Network File System (NFS) Version 4 Protocol"

RFC 8881 - "Network File System (NFS) Version 4 Minor Version 1 Protocol"


exportfs

title: exportfs(8)

text:
# exportfs(8)

## NAME
exportfs - maintain table of exported NFS file systems

## SYNOPSIS
/usr/sbin/exportfs [-avi] [-o options,..] [client:/path ..]

/usr/sbin/exportfs -r [-v]

/usr/sbin/exportfs [-av] -u [client:/path ..]

/usr/sbin/exportfs [-v]

/usr/sbin/exportfs -f

/usr/sbin/exportfs -s

## DESCRIPTION
An NFS server maintains a table of local physical file systems that are accessible to NFS clients. Each file system in this table is referred to as an exported file system, or export, for short.

The exportfs command maintains the current table of exports for the NFS server. The master export table is kept in a file named /var/lib/nfs/etab. This file is read by rpc.mountd when a client sends an NFS MOUNT request.

Normally the master export table is initialized with the contents of /etc/exports and files under /etc/exports.d by invoking exportfs -a. However, a system administrator can choose to add or delete exports without modifying /etc/exports or files under /etc/exports.d by using the exportfs command.

exportfs does not communicate with the kernel directly. It writes export information to /var/lib/nfs/etab and relies on its partner programs rpc.mountd and nfsv4.exportd to manage kernel communication. These daemons work in one of two modes: a netlink mode and a /proc mode.

In the netlink mode, available on sufficiently recent kernels, rpc.mountd (or nfsv4.exportd) communicates with the kernel via generic netlink sockets. The kernel sends multicast notifications when cache entries need to be resolved, and the daemon responds with the appropriate export information. Cache flushing (via exportfs -f) is also performed over netlink. This mode can be disabled with the -L option.

In the /proc mode, used when netlink is unavailable, rpc.mountd manages kernel requests for information about exports via the /proc/net/rpc channel files.

## OPTIONS
-d kind or --debug kind

Turn on debugging. Valid kinds are: all, auth, call, general and parse. Debugging can also be turned on by setting debug= in the [exportfs] section of /etc/nfs.conf.

-a

Export or unexport all directories.

-o options,...

Specify a list of export options in the same manner as in exports(5).

-i

Ignore the /etc/exports file and files under /etc/exports.d directory. Only default options and options given on the command line are used.

-r

Reexport all directories, synchronizing /var/lib/nfs/etab with /etc/exports and files under /etc/exports.d. This option removes entries in /var/lib/nfs/etab which have been deleted from /etc/exports or files under /etc/exports.d, and removes any entries from the kernel export table which are no longer valid.

-u

Unexport one or more directories.

-f

If /proc/fs/nfsd or /proc/fs/nfs is mounted, flush everything out of the kernel's export table. Fresh entries for active clients are added to the kernel's export table by rpc.mountd when they make their next NFS mount request.

-v

Be verbose. When exporting or unexporting, show what's going on. When displaying the current export list, also display the list of export options.

-s

Display the current export list suitable for /etc/exports.

-L

Disable the use of netlink for kernel communication and force the use of the legacy /proc interfaces for cache flushing and export validation.

## CONFIGURATION FILE
The [exportfs] section of the /etc/nfs.conf configuration file can contain a debug value, which can be one or more from the list general, call, auth, parse, all. When a list is given, the members should be comma-separated.

exportfs will also recognize the state-directory-path and no-netlink values from both the [mountd] section and the [exportd] section. When no-netlink is set, exportfs will skip the netlink probe and use the legacy /proc interfaces for cache flushing and export validation

## DISCUSSION

### Exporting Directories
The first synopsis shows how to invoke exportfs when adding new entries to the export table. When using exportfs -a, all exports listed in /etc/exports and files under /etc/exports.d are added to /var/lib/nfs/etab. The kernel's export table is also updated as needed.

The host:/path argument specifies a local directory to export, along with the client or clients who are permitted to access it. See exports(5) for a description of supported options and access list formats.

IPv6 presentation addresses contain colons, which are already used to separate the "host" and "path" command line arguments. When specifying a client using a raw IPv6 address, enclose the address in square brackets. For IPv6 network addresses, place the prefix just after the closing bracket.

To export a directory to the world, simply specify :/path.

The export options for a particular host/directory pair derive from several sources. The default export options are sync,ro,root_squash,wdelay. These can be overridden by entries in /etc/exports or files under /etc/exports.d.

A system administrator may override options from these sources using the -o command-line option on exportfs. This option takes a comma-separated list of options in the same fashion as one would specify them in /etc/exports. In this way exportfs can be used to modify the export options of an already exported directory.

### Unexporting Directories
The third synopsis shows how to unexport a currently exported directory. When using exportfs -ua, all entries listed in /var/lib/nfs/etab are removed from the kernel export tables, and the file is cleared. This effectively shuts down all NFS activity.

To remove an export, specify a host:/path pair. This deletes the specified entry from /var/lib/nfs/etab and removes the corresponding kernel entry (if any).

### Dumping the Export Table
Invoking exportfs without options shows the current list of exported file systems. Adding the -v option causes exportfs to display the export options for each export.

## EXAMPLES
The following adds all directories listed in /etc/exports and files under /etc/exports.d to /var/lib/nfs/etab and pushes the resulting export entries into the kernel:

```
# exportfs -a
```

To export the /usr/tmp directory to host django, allowing insecure file locking requests from clients:

```
# exportfs -o insecure_locks django:/usr/tmp
```

To unexport the /usr/tmp directory:

```
# exportfs -u django:/usr/tmp
```

To unexport all exports listed in /etc/exports and files under /etc/exports.d:

```
# exportfs -au
```

To export the /usr/tmp directory to IPv6 link-local clients:

```
# exportfs [fe80::]/64:/usr/tmp
```

## USAGE NOTES
Exporting to IP networks or DNS and NIS domains does not enable clients from these groups to access NFS immediately. Rather, these sorts of exports are hints to rpc.mountd(8) to grant any mount requests from these clients. This is usually not a problem, because any existing mounts are preserved in rmtab across reboots.

When unexporting a network or domain entry, any current exports to members of this group will be checked against the remaining valid exports and if they themselves are no longer valid they will be removed.

## FILES
/etc/exports

input file listing exports, export options, and access control lists

/etc/exports.d

directory where extra input files are stored. Note: only files that end with .exports are used.

/var/lib/nfs/etab

master table of exports

/var/lib/nfs/rmtab

table of clients accessing server's exports

## SEE ALSO
exports(5), nfs.conf(5), rpc.mountd(8), exportd(8), netgroup(5)

## AUTHORS
Olaf Kirch <okir@monad.swb.de>

Neil Brown <neilb@cse.unsw.edu.au>