NSDB-CREATE-FSN(8)					      System Manager's Manual						NSDB-CREATE-FSN(8)

NAME

       nsdb-create-fsn - create a fileset name (FSN) record on an NSDB

SYNOPSIS

       nsdb-create-fsn [-?d] [-D binddn] [-e nce] [-l nsdbname] [-r nsdbport] [-t ttl] fsn-uuid

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-create-fsn(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 creates a FedFS fileset name (FSN) record on an NSDB.

       A fileset name, or FSN, uniquely identifies a fileset in FedFS.	An FSN consists of a UUID and the hostname and port of an NSDB.  This pair
       is intended to be unique across all of FedFS.  The meaning of these items is described in more detail in fedfs(7).

       A  FedFS  junction contains an FSN.  There can be multiple junctions that contain a particular FSN.  There is exactly one FSN record stored
       on an NSDB that corresponds to this FSN.  The FSN record can have zero or more FSL records as children.	 Replicas  of  these  records  can
       exist on more than one LDAP server.

       The nsdb-create-fsn(8) command creates an FSN record on the named NSDB in preparation for use in FedFS junctions.  It does not create FedFS
       junctions.  To create a junction, use the fedfs-create-junction(8) command.  It does not create any FSL children records.  To create an FSL
       record, use the nsdb-create-fsl(8) command.

       This command has one positional parameter which specifies the UUID of the new FSN record.

OPTIONS

       -d, --debug
	      Enables debugging messages during operation.

       -?, --help
	      Displays nsdb-create-fsn(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-create-fsn(8) command fails.

       -e, --nce=NSDB-container-entry-distinguished-name
	      Specifies the distinguished name of the NSDB Container Entry under which this FSN record is to be created.  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 con-
	      nection parameter database is searched for this DN.  If none of these is specified, the nsdb-create-fsn(8) command fails.

       -l, --nsdbname=NSDB-host-name
	      Specifies the hostname of the NSDB where the new FSN record 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-create-fsn(8) command fails.

       -r, --nsdbport=NSDB-port
	      Specifies the IP port of the NSDB where the new FSN record 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.

       -t, --ttl=TTL
	      Specifies  the  number  of  seconds a file server may cache the information in this record.  If the --ttl option is not specified, a
	      value of 300 seconds is used.

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

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

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

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

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

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

       FEDFS_ERR_NSDB_NOFSN
	      The nsdb-create-fsn(8) command was unable to locate the specified FSN on the specified NSDB.

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

       FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL
	      The  nsdb-create-fsn(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-create-fsn(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-create-fsn(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 have created a new FSN for some fileset.  The new  FSN
       might look like:

		   FSN UUID: 8e246ddc-7b46-11e0-8252-000c297fd679
		   NSDB: nsdb.example.net:389

       Further	suppose  the NSDB nsdb.example.net:389 has an NSDB Container Entry whose distinguished name is o=fedfs.  To create a corresponding
       FSN record, you might use:

	      $ nsdb-create-fsn -D cn=Manager -e o=fedfs 
		   -l nsdb.example.net 
		   8e246ddc-7b46-11e0-8252-000c297fd679
	      Enter NSDB password:
	      Successfully created FSN record
		fedfsFsnUuid=8e246ddc-7b46-11e0-8252-000c297fd679,o=fedfs

       A new FSN record is created on nsdb.example.net:389 with a distinguished name of

	      fedfsFsnUuid=8e246ddc-7b46-11e0-8252-000c297fd679,o=fedfs.

       To see the new FSN record, use nsdb-list(8) or nsdb-resolve-fsn(8).

SECURITY

       Permission to modify the LDAP's DIT is required to create a new FSN record.  The nsdb-create-fsn(8) command must bind as an entity  permit-
       ted  to modify the DIT to perform this operation.  The nsdb-create-fsn(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), fedfs-create-junction(8), nsdb-create-fsl(8), nsdb-resolve-fsn(8), nsdb-list(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-CREATE-FSN(8)