nsdb-nces man page

nsdb-nces — list NSDB container entries on an LDAP server

Synopsis

nsdb-nces [-?d] [-l nsdbname] [-r nsdbport]

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 junction information in a FedFS domain is stored on one or more LDAP servers. These servers are known as namespace databases, or NSDBs, for short.

FedFS-enabled file servers and clients access the information stored on NSDBs via standard LDAP queries. FedFS-enabled file servers use these queries to resolve FedFS junctions. FedFS administrators use them to manage information about file sets contained in a FedFS domain name space.

Description

The nsdb-nces(8) command is part of a collection of low-level single-use programs that in intended for testing the NSDB protocol or for use in scripts. It queries an LDAP server for the existance of NSDB Container Entries, or NCEs, for short.

The top of the Directory Information Tree on an LDAP server has one or more naming contexts. Some LDAP server implementations call these contexts "root suffixes". All LDAP entries on that server are contained under one of these contexts.

The LDAP object under which FedFS-related entries reside is known as the NSDB Container Entry (or NCE). The NCE can be a naming context object, or it can be located somewhere below the naming context. Both the naming context and the NCE must be world-readable for FedFS-enabled clients and servers to access the NSDB.

The nsdb-nces(8) command displays each naming context on a target LDAP server and indicates whether that context contains an NCE. At its simplest, you can think of the nsdb-nces(8) command as a form of NSDB ping. However, it can also convey certain details about the organization of any NCEs on an LDAP server. Discovering NCEs on an NSDB is always the first step FedFS-enabled file servers perform when resolving a FedFS junction.

Options

-d, --debug
Specifies that debugging messages be produced during operation.
-?, --help
Prints an nsdb-nces(8) version and usage message on stderr, then exits.
-l, --nsdbname=NSDB-hostname
Specifies the hostname of the NSDB to enumerate. If the --nsdbname option is not specified, the value of the FEDFS_NSDB_HOST environment variable is consulted. If the variable is not set and the --nsdbname option is not specified, the nsdb-nces(8) command fails.
-r, --nsdbport=NSDB-port
Specifies the IP port of the NSDB to enumerate. If the --nsdbport option is not specified, the value of the FEDFS_NSDB_PORT environment variable is consulted. The default value if the variable is not set is 389.

Exit Codes

The NSDB returns a value that reflects the success of the requested operation.

FEDFS_OK
The LDAP query succeeded. One or more NSDB container entries were detected on the target LDAP server.
FEDFS_ERR_ACCESS
The anonymous entity does not have permission to perform the requested operation.
FEDFS_ERR_INVAL
One of the arguments was not valid.
FEDFS_ERR_SVRFAULT
An unanticipated non-protocol error occurred.
FEDFS_ERR_NSDB_ROUTE
The nsdb-nces(8) command was unable to find a route to the specified NSDB.
FEDFS_ERR_NSDB_DOWN
The nsdb-nces(8) command determined that the specified NSDB was down.
FEDFS_ERR_NSDB_CONN
The nsdb-nces(8) command was unable to establish a connection with the specified NSDB.
FEDFS_ERR_NSDB_AUTH
The nsdb-nces(8) command was unable to authenticate and establish a secure connection with the specified NSDB.
FEDFS_ERR_NSDB_LDAP
A non-specific LDAP error occurred on the connection between the nsdb-nces(8) command and specified NSDB.
FEDFS_ERR_NSDB_LDAP_VAL
An LDAP error occurred on the connection between the nsdb-nces(8) command and specified NSDB. The specific error may be displayed on the command line.
FEDFS_ERR_NSDB_NONCE
The nsdb-nces(8) command was unable to locate any NCEs on the specified NSDB.
FEDFS_ERR_NSDB_RESPONSE
The nsdb-nces(8) command received a malformed response from the specified NSDB.
FEDFS_ERR_NSDB_FAULT
An unanticipated error related to the specified NSDB occurred.
FEDFS_ERR_NSDB_PARAMS
The local NSDB connection parameter database does not have any connection parameters on record for the specified NSDB.
FEDFS_ERR_NSDB_LDAP_REFERRAL
The nsdb-nces(8) command received an LDAP referral that it was unable to follow.
FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL
The nsdb-nces(8) command received an LDAP referral that it was unable to follow. A specific error may be displayed on the command line.
FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED
The nsdb-nces(8) command received an LDAP referral that it chose not to follow, either because the local implementation does not support following LDAP referrals or LDAP referral following is disabled.
FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL
The nsdb-nces(8) command received an LDAP referral that it chose not to follow because the local NSDB connection parameter database had no connection parameters for the NSDB targeted by the LDAP referral.

Examples

Suppose you are the FedFS administrator of the example.net FedFS domain and that you want to know if the LDAP server ldap.example.net is an NSDB. Use:

$ nsdb-nces -l ldap.example.net
Host: ldap.example.net:389
namingContext 'dc=example,dc=net' does not host an NCE.
namingContext 'o=fedfs' hosts an NCE at 'o=fedfs'.
namingContext 'o=netscaperoot' does not host an NCE.

This shows there are three LDAP naming contexts on the target LDAP server. One of these is an NSDB Container Entry. Thus the target LDAP server is an NSDB.

Security

The nsdb-nces(8) command uses anonymous binding when performing LDAP queries. LDAP naming contexts are typically readable by everyone.

The target LDAP server must be registered in the local NSDB connection parameter database. The connection security mode listed in the NSDB connection parameter database for the target LDAP server is used during this operation. See nsdbparams(8) for details on how to register an NSDB in the local NSDB connection parameter database.

See Also

fedfs(7), nsdbparams(8)

RFC 5716 for FedFS requirements and overview

RFC 4510 for an introduction to LDAP

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.ph….

Author

Chuck Lever <chuck.lever@oracle.com>

Referenced By

fedfs(7), nsdb-delete-nsdb(8), nsdb-remove-nci(8), nsdb-simple-nce(8), nsdb-update-nci(8).

3 February 2014