NSDB-LIST(8)						      System Manager's Manual						      NSDB-LIST(8)

NAME

       nsdb-list - list file set name and location entries on an NSDB

SYNOPSIS

       nsdb-list [-?d] [-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-list(8) command is part of a collection of low-level single-use programs that is intended for testing the NSDB protocol or for use
       in scripts.  It retrieves the list of file set name and location records stored on an NSDB under one NSDB Container Entry.

OPTIONS

       -d, --debug
	      Specifies that debugging messages be produced during operation.

       -?, --help
	      Prints an nsdb-list(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  envi-
	      ronment  variable  is  consulted.   If  the variable is not set and the --nsdbname option is not specified, the nsdb-list(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  envi-
	      ronment variable is consulted.  The default value if the variable is not set is 389.

       -e, --nce=NSDB-container-entry
	      Limits  the  query  to a particular NSDB Container Entry on the target NSDB.  If the --nce option is not specified, the value of the
	      FEDFS_NSDB_NCE environment variable is consulted.  If the variable is not set and the --nce option is not specified, or  the  speci-
	      fied NCE does not exist on the target NSDB, the nsdb-list(8) command fails.

EXIT CODES

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

       FEDFS_OK
	      The LDAP query succeeded.  A list of FSN and FSL records are summarized on stdout.

       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-list(8) command was unable to find a route to the specified NSDB.

       FEDFS_ERR_NSDB_DOWN
	      The nsdb-list(8) command determined that the specified NSDB was down.

       FEDFS_ERR_NSDB_CONN
	      The nsdb-list(8) command was unable to establish a connection with the specified NSDB.

       FEDFS_ERR_NSDB_AUTH
	      The nsdb-list(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-list(8) command and specified NSDB.

       FEDFS_ERR_NSDB_LDAP_VAL
	      An  LDAP	error occurred on the connection between the nsdb-list(8) command and specified NSDB.  The specific error may be displayed
	      on the command line.

       FEDFS_ERR_NSDB_NONCE
	      The nsdb-list(8) command was unable to locate the NCE on the specified NSDB.

       FEDFS_ERR_NSDB_RESPONSE
	      The nsdb-list(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-list(8) command received an LDAP referral that it was unable to follow.

       FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL
	      The nsdb-list(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-list(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-list(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-list -l ldap.example.net -e o=fedfs
	      NSDB: ldap.example.net:389

		NCE: o=fedfs

		  FSN UUID: c1c21720-1fcd-4ad6-a837-f57af4cf2972
		    FSL UUID: 4c887035-ad2f-4ba8-ab75-7118df9714cd
		    FSL UUID: 84445758-b5fb-4acc-814b-cc121b3bafe9

       There is a single file set name, with two file set location records, registered under "o=fedfs" on this NSDB.  To resolve  the  listed  FSN
       UUID, use the nsdb-resolve-junction(8) command.

SECURITY

       The NSDB protocol draft standard requires that FedFS FSN and FSL records are readable by everyone.  The nsdb-list(8) command uses anonymous
       binding when performing LDAP queries.

       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-resolve-junction(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-LIST(8)