nsdbparams (8) - Linux Manuals

nsdbparams: manage local NSDB connection parameter database

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 administrators 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 nsdbparams(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 administrative 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. Therefore, 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 succeeds, 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 subcommands.

-?, --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

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 [at] oracle.com>