.\" Man page generated from reStructuredText.
.
.TH "GANESHA-RADOS-GRACE" "8" "Jan 20, 2023" "" "NFS-Ganesha"
.SH NAME
ganesha-rados-grace \- manipulate the shared grace management database
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.nf
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 ... ]
.fi
.sp
.SH DESCRIPTION
.sp
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.
.sp
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.
.sp
Most commands will just fail if the grace database is not present. The
exception to this rule is the \fBadd\fP command which will create the
pool, database and namespace if they do not already exist.
.sp
Note that this program does not consult ganesha.conf. If you use
non\-default values for \fBceph_conf\fP, \fBuserid\fP, \fBgrace_oid\fP,
\fBnamespace\fP or \fBpool\fP in your RADOS_KV config block, then they will
need to passed in via command\-line options.
.SH OPTIONS
.sp
\fB\-\-cephconf\fP
.sp
Specify the ceph.conf configuration that should be used (default is to
use the normal search path to find one)
.sp
\fB\-\-ns\fP
.sp
Set the RADOS namespace to use within the pool (default is NULL)
.sp
\fB\-\-oid\fP
.sp
Set the object id of the grace database RADOS object (default is "grace")
.sp
\fB\-\-pool\fP
.sp
Set the RADOS poolid in which the grace database object resides (default is
"nfs\-ganesha")
.sp
\fB\-\-userid\fP
.sp
Set the cephx user ID to use when contacting the cluster (default is NULL)
.SH COMMANDS
.sp
\fBdump\fP
.sp
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.
.sp
\fBadd\fP
.sp
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.
.sp
\fBstart\fP
.sp
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 \fBjoin\fP\&.
.sp
\fBjoin\fP
.sp
Attempt to join an existing grace period. This works like \fBstart\fP, but
only if there is already an existing grace period in force.
.sp
\fBlift\fP
.sp
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.
.sp
\fBremove\fP
.sp
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.
.sp
\fBenforce\fP
.sp
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.
.sp
\fBnoenforce\fP
.sp
Clear the enforcing flag for the given hosts, meaning that those hosts
are now allowing clients to acquire new state.
.sp
\fBmember\fP
.sp
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.
.SH FLAGS
.sp
When the \fBdump\fP 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:
.sp
\fBE (Enforcing)\fP
.sp
The node is currently enforcing the grace period by rejecting requests from
clients to acquire new state.
.sp
\fBN (Need Grace)\fP
.sp
The node currently requires a grace period. Generally, this means that the
node has clients that need to perform recovery.
.SH NODEID ASSIGNMENT
.sp
Each running ganesha daemon requires a \fBnodeid\fP 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.
.sp
This may not be suitable when running under certain HA clustering
infrastructure, so it\(aqs generally recommended to manually assign nodeid values
to the hosts in the \fBRADOS_KV\fP config block of \fBganesha.conf\fP\&.
.SH GANESHA CONFIGURATION
.sp
The ganesha daemon will need to be configured with the RecoveryBackend
set to \fBrados_cluster\fP\&. If you use a non\-default pool, namespace or
oid, nodeid then those values will need to be set accordingly in the
\fBRADOS_KV\fP config block as well.
.SH STARTING A NEW CLUSTER
.sp
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:
.sp
\fBganesha\-rados\-grace add ganesha\-1 ganesha\-2 ganesha\-3\fP
.sp
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.
.SH ADDING NODES TO A RUNNING CLUSTER
.sp
After this point, new nodes can then be added to the cluster as needed using
the \fBadd\fP command:
.sp
\fBganesha\-rados\-grace add ganesha\-4\fP
.sp
After the node has been added, ganesha.nfsd can then be started. It will
then request a new grace period as\-needed.
.SH REMOVING A NODE FROM THE CLUSTER
.sp
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:
.sp
\fBganesha\-rados\-grace remove ganesha\-4\fP
.sp
This will remove the ganesha\-4\(aqs record from the database, and possibly lift
the current grace period if one is active and it was the last one to need it.
.\" Generated by docutils manpage writer.
.