NSDBPARAMS(8) System Manager's Manual NSDBPARAMS(8)
NAME
nsdbparams - manage local NSDB connection parameter database
SYNOPSIS
nsdbparams delete [-?d] [-g gid] [-r nsdbport] [-u uid] nsdbname
nsdbparams list [-?d] [-u uid] [-g gid]
nsdbparams show [-?d] [-g gid] [-r nsdbport] [-u uid] nsdbname
nsdbparams update [-?d] [-D def-binddn] [-e def-nce] [-f certfile] [-g gid] [-R y|n] [-r nsdbport] [-t sectype] [-u uid] nsdbname
INTRODUCTION
RFC 5716 introduces the Federated File System (FedFS, for short). FedFS is an extensible standardized mechanism by which system adminis-
trators construct a coherent namespace across multiple file servers using file system referrals. For further details, see fedfs(7).
The bulk of FedFS metadata is stored on one or more LDAP servers. These servers are known as namespace databases, or NSDBs, for short. An
NSDB client is any system that communicates with an NSDB. This can be either a fileserver or an NSDB administrative client.
On NSDB clients, a small local database stores information about how to connect to each NSDB node. These NSDB connection parameters are
used when an NSDB client contacts an NSDB node to perform file server operations or when executing NSDB administrative commands.
The settings in this database effect only the behavior of the local NSDB client. They have no effect on the operation of NSDBs nodes.
DESCRIPTION
The nsdbparams(8) command is one way FedFS domain administrators can manage a system's local NSDB connection parameter database. This
database stores connection security preferences and default settings, such as the preferred bind DN and the location of the NSDB container
entry, for each NSDB the local system knows about.
Some NSDB connection parameters are also remotely accessible via rpc.fedfsd(8). The nsdbparams(8) command allows complete access to the
local system's NSDB database including access to some parameters which are not accessible to clients of rpc.fedfsd(8).
Typically rpc.fedfsd(8) runs only on FedFS-enabled file servers. FedFS administrators can manage NSDB connection parameters with nsdb-
params(8) on a system that is not running rpc.fedfsd(8), such as a system that is acting only as a FedFS administrative client. Connection
parameters for NSDBs must be stored in the local NSDB connection parameter database before FedFS junction resolution and NSDB administra-
tive commands can work.
Operation
The NSDB connection parameter database is stored in a directory (typically /var/lib/fedfs) that is owned by a special UID and GID. There-
fore, this command must be run as root. During operation, nsdbparams(8) drops its root privileges, running as the special user and group
instead.
The default value of these special IDs is determined when nsdbparams(8) is built. They can also be specified at run time using the --uid
or --gid command line options.
When executing a subcommand, nsdbparams(8) verifies that the local NSDB connection parameter database exists and is accessible. If it does
not exist, nsdbparams(8) attempts to create and initialize a new connection parameter database. If it cannot, the subcommand fails.
Subcommands
Valid nsdbparams(8) subcommands are:
delete Remove the connection parameters for the specified NSDB from the local NSDB connection parameter database. If this subcommand suc-
ceeds, subsequent attempts to access the specified NSDB on the local system fail.
list Display a list of all NSDBs in the local NSDB connection parameter database. An abbreviated form of the connection parameters for
each known NSDB are shown. This subcommand does not take an NSDB domain name parameter.
update Update the connection parameters for the specified NSDB in the local NSDB connection parameter database. Use this subcommand to add
a new entry for an NSDB to the local connection parameter database, or to modify an existing entry in the database.
show Display the recorded connection parameters for the specified NSDB. This subcommand displays all known settings for the specified
NSDB stored in the local NSDB connection parameter database.
The NSDB domain name and IP port number pair are used as the primary key to identify an NSDB to the NSDB connection parameter database.
The subcommands delete, update, and show require that an NSDB domain name be specified as a positional parameter. If no NSDB port number
is provided on the command line, the nsdbparams(8) command uses the default LDAP port (389).
The database matches NSDB domain names and ports by exact value. Details on NSDB connection parameters database entry matching can be
found in nsdb-parameters(7).
Command line options
-d, --debug
Enables debugging messages during subcommand operation. This option is valid for all subcommands.
-D, --binddn=bind-DN
Specifies the default LDAP distinguished name to use when binding to the specified NSDB for administrative operations. This option
is valid for the update subcommand.
-e, --nce=NCE-DN
Specifies the default LDAP distinguished name of the NSDB container entry for the specified NSDB for administrative operations.
This option is valid for the update subcommand.
-f, --certfile=pathname
Specifies the pathname of a local file containing security data appropriate for the --sectype specified on the command line. The
specified file may be deleted after the command succeeds. Details on security data can be found in nsdb-parameters(7). This option
is valid for the update subcommand.
-g, --gid=id
Specifies the numeric or text GID that the nsdbparams(8) command runs as after dropping root privileges. By default, the GID for
the group fedfs is used. If that group doesn't exist, then the GID for nobody is used instead. This option is valid for all sub-
commands.
-?, --help
Displays nsdbparams(8) version information and a subcommand usage message on stderr. This option is valid for all subcommands.
-r, --nsdbport=NSDB-port
Specifies the IP port for the specified NSDB. The default value if this option is not specified is 389. This option is valid for
any subcommand that requires an NSDB domain name to be specified.
-R, --referral=[yes|no]
Specifies whether or not the local system should follow LDAP referrals received from the specified NSDB. This option is valid for
the update subcommand.
-t, --sectype=security-type
Specifies the FedFS connection security type to use when connecting to the specified NSDB. Valid values for security-type are 0,
none, FEDFS_SEC_NONE, 1, tls, or FEDFS_SEC_TLS. This option is valid for the update subcommand.
-u, --uid=id
Specifies the numeric or text UID that nsdbparams(8) runs as after dropping root privileges. By default, the UID for the user fedfs
is used. If that user doesn't exist, then the UID for nobody is used instead. This option is valid for all subcommands.
CHANGING SECURITY TYPES
You can change connection security types used to contact an NSDB node using the update subcommand. Simply specify the new security type
with the --sectype option. Specifying the NONE type removes existing stored certificate material for that NSDB node. Specifying the TLS
type replaces existing stored certificate material with new material specified with the --certfile option.
EXAMPLES
If there is an NSDB called nsdb.example.net, the first command you might issue on a new administrative client might be:
# nsdbparams update nsdb.example.net
You can view the new connection parameter entry with
# nsdbparams show nsdb.example.net
The result of this command would look like:
nsdb.example.net:389:
connection security: FEDFS_SEC_NONE
follow referrals: no
To set up TLS security, use the update subcommand and specify the --sectype and --certfile options. For instance, if an x.509 certificate
for nsdb.example.net were contained in a local file called /tmp/nsdb.pem, you might use:
# nsdbparams update -t tls -f /tmp/nsdb.pem nsdb.example.net
To switch from TLS security back to no connection security for this NSDB, you might use:
# nsdbparams update nsdb.example.net -t none
FILES
/var/lib/fedfs/nsdbparam.sqlite3
database of NSDB connection parameters
/var/lib/fedfs/nsdbcerts
local directory that stores x.509 certificates for NSDBs
SEE ALSO
fedfs(7), nsdb-parameters(7), rpc.fedfsd(8)
RFC 5661 for a description of NFS version 4 referrals
RFC 5716 for FedFS requirements and overview
COLOPHON
This page is part of the fedfs-utils package. A description of the project and information about reporting bugs can be found at
http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject.
AUTHOR
Chuck Lever <chuck.lever@oracle.com>
3 February 2014 NSDBPARAMS(8)