NSDB-UPDATE-NCI(8) System Manager's Manual NSDB-UPDATE-NCI(8)
NAME
nsdb-update-nci - update NSDB container information on an LDAP server
SYNOPSIS
nsdb-update-nci [-?dy] [-D binddn] [-e nce] [-l nsdbname] [-r nsdbport]
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 junction information in a FedFS domain is stored on one or more LDAP servers. These servers are known as namespace data-
bases, 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-update-nci(8) command is part of a collection of low-level single-use programs that are intended for testing the NSDB protocol or
for use in scripts. This command is an easy way to turn a standard LDAP server into an NSDB by adding NSDB container information to the
server's Directory Information Tree (or DIT, for short).
The top of the DIT on an LDAP server has one or more naming contexts. Some LDAP server implementations call these contexts root suffixes.
An LDAP server's naming contexts are easy for clients to locate with a well-known search query. All LDAP entries on that server are con-
tained under naming contexts.
The root LDAP object under which FedFS-related entries reside is known as the NSDB Container Entry (or NCE). The NCE can be a naming con-
text 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-update-nci(8) command promotes an unremarkable LDAP entry to become an NCE. This is the step that turns an LDAP server into an
NSDB. The target NCE object must exist before this operation can complete successfully.
OPTIONS
-d, --debug
Enables debugging messages during operation.
-?, --help
Displays nsdb-update-nci(8) version information and a usage message on stderr.
-D, --binddn=bind-distinguished-name
Specifies a distinguished name of an entity used to bind to the LDAP server where the NSDB resides. If the --binddn option is not
specified, the value of the FEDFS_NSDB_ADMIN environment variable is consulted. If this variable is not set, the NSDB connection
parameter database is searched for this DN. If none of these is specified, or if this entity does not have permission to modify
this area of the server's DIT, the nsdb-update-nci(8) command fails.
-e, --nce=NSDB-container-entry-distinguished-name
Specifies the distinguished name of the new NSDB container entry. If the --nce option is not specified, the value of the
FEDFS_NSDB_NCE environment variable is consulted. If this variable is not set, then the NSDB connection parameter database is
searched for this DN. If none of these is specified, the nsdb-update-nci(8) command fails.
-l, --nsdbname=NSDB-hostname
Specifies the hostname of the NSDB where the target NCE should reside. 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-
update-nci(8) command fails.
-r, --nsdbport=NSDB-port
Specifies the IP port of the NSDB where the target NCE should reside. 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.
-y, --delete
Specifies that NSDB Container Information for this NCE should be removed from this LDAP server. This operation cannot be undone.
EXIT CODES
The NSDB returns a value that reflects the success of the requested operation.
FEDFS_OK
The LDAP modify request succeeded.
FEDFS_ERR_ACCESS
The bound 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-update-nci(8) command was unable to find a route to the specified NSDB.
FEDFS_ERR_NSDB_DOWN
The nsdb-update-nci(8) command determined that the specified NSDB was down.
FEDFS_ERR_NSDB_CONN
The nsdb-update-nci(8) command was unable to establish a connection with the specified NSDB.
FEDFS_ERR_NSDB_AUTH
The nsdb-update-nci(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-update-nci(8) command and specified NSDB.
FEDFS_ERR_NSDB_LDAP_VAL
An LDAP error occurred on the connection between the nsdb-update-nci(8) command and specified NSDB. The specific error may be dis-
played on the command line.
FEDFS_ERR_NSDB_RESPONSE
The nsdb-update-nci(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-update-nci(8) command received an LDAP referral that it was unable to follow.
FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL
The nsdb-update-nci(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-update-nci(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-update-nci(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 make the LDAP server ldap.example.net into an
NSDB. After creating a naming context and root suffix object with a distinguished name of o=fedfs on the LDAP server, you might use:
$ nsdb-update-nci -l ldap.example.net -D cn=Manager -e o=fedfs
Enter NSDB password:
Successfully updated NCI
NSDB container information is inserted into o=fedfs, and this entry is changed to an NSDB Container Entry.
To see the new container information, use nsdb-nces(8).
o=fedfs is a typical location for an NCE on an LDAP server. However, suppose that instead of creating such a typical NCE, you would prefer
the entry ou=fedfs,dc=example,dc=net to contain FedFS information. Assuming your server set-up script has already created the dc=exam-
ple,dc=net naming context and root object, and after creating a generic object with the distinguished name ou=fedfs,dc=example,dc=net, you
might use:
$ nsdb-update-nci -e "ou=fedfs,dc=example,dc=net" -D cn=Manager
Enter NSDB password:
Successfully updated NCI
NSDB container information is inserted into dc=example,dc=net, and the entry at ou=fedfs,dc=example,dc=net is made into an NCE.
To see the new NCE, use nsdb-nces(8).
SECURITY
LDAP naming contexts are typically writable only by administrative entities. The nsdb-update-nci(8) command must bind as an administrative
entity to perform this operation. The nsdb-update-nci(8) command asks for a password on stdin. Standard password blanking techniques are
used to obscure the password on the user's terminal.
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), nsdb-nces(8), 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.php/FedFsUtilsProject.
AUTHOR
Chuck Lever <chuck.lever@oracle.com>
3 February 2014 NSDB-UPDATE-NCI(8)