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

NAME

       nsdb-jumpstart - Administer a basic FedFS NSDB using OpenLDAP

SYNOPSIS

       nsdb-jumpstart [-h,--help] [--version]

       nsdb-jumpstart [--statedir= statedir] install [--security= mode]

       nsdb-jumpstart [--statedir= statedir] status

       nsdb-jumpstart [--statedir= statedir] backup

       nsdb-jumpstart [--statedir= statedir] restore [backup-name]

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).

       A FedFS domain's namespace is joined together via junctions.  When a file-access client encounters a junction on a file	server,  the  file
       server provides a list of locations where that client can access the target file set to which the juntion refers.

       In a FedFS domain, these location lists are stored on one or more LDAP servers, known as namespace databases, or NSDBs, for short.

       FedFS-enabled  file  servers  access  the  information stored on NSDBs via standard LDAP queries.  Tools that administer a FedFS domain use
       ldapmodify queries to manage information stored on an NSDB.  File-access clients have no need to access NSDBs directly.

       Further information about junctions and NSDBs is available in fedfs(7).

DESCRIPTION

       The FedFS NSDB Proposed Standard allows flexible use of any LDAP server and its Directory Information Tree to store and manage NSDB  infor-
       mation.

       The nsdb-jumpstart(8) command provides a simplified but fully capable stand-alone NSDB based specifically on OpenLDAP.  Using this command,
       you can install a fresh NSDB, or back up or restore your NSDB data.  It can even construct a self-signed x.509 certificate to enable secure
       NSDB queries.

   Operation
       The  install  subcommand  sets up an empty NSDB, ready to be used in a FedFS domain.  The new NSDB replaces any OpenLDAP configuration that
       may already exist on the system.  OpenLDAP must already be installed on the system.

       Once the new NSDB is running, FedFS fileset location information is stored as records in a Directory Information Tree under the NCE.   This
       information is managed with commands like nsdb-create-fsn(8).

       A  handful  of  parameters are needed to set up the new NSDB.  These are gathered via a brief interview.  The domain name and administrator
       credentials are provided during this interview.	Passwords are not checked for strength, however blank passwords are not permitted.

       The baseline security requirements for the NSDB are specified at install time using the --security= option.  See the SECURITY  section  for
       an in-depth discussion.

       Once set up with the install subcommand, OpenLDAP listens for LDAP queries on the standard LDAP port (389).  The underlying LDAP server can
       be configured like any other OpenLDAP server using the new-style cn=config configuration interface.

       To display the current status of the NSDB service on the local host, use the status subcommand.	Information about the local  NSDB  service
       is  displayed,  including  whether the LDAP service is started, whether it actually is an NSDB, and whether TLS security is required to use
       it.

       The nsdb-jumpstart(8) command also provides backup and restore facilities.  The backup subcommand saves location information stored on  the
       local  NSDB  to	a  dated  LDIF	file.	LDIF files created by the backup command are stored in the /var/lib/fedfs/nsdb-backup directory by
       default.

       The restore subcommand completely replaces the contents of the NSDB with a backup contained in of one of the previously saved  LDIF  files.
       The  restore subcommand takes one positional argument, which is the name of the backup to restore.  A list of backups is displayed by using
       the restore subcommand with no argument.

       The nsdb-jumpstart(8) command must run as root.	A audit log of each nsdb-jumpstart(8) operation  is  stored  in  /var/lib/fedfs/nsdb-jump-
       start.log.

   Subcommands
       Valid nsdb-jumpstart(8) subcommands are:

       install
	      Replace  the  OpenLDAP  configuration  on  the  local system with a ready-built NSDB.  The user is asked to confirm before action is
	      taken.

	      Specifying the --security= option sets the transport security that the NSDB requires clients to use when communicating with it.

       status Display the status of the NSDB on the local system.  This subcommand takes no arguments.

       backup Generate an LDIF containing the NSDB information stored on the local LDAP server.   The  LDIF  is  stored  in  a	dated  file  under
	      /var/lib/fedfs/nsdb-backup.  This subcommand takes no arguments.

       restore
	      Replace the NSDB information on the local LDAP server with the contents of an LDIF.  This subcommand takes a backup name as an argu-
	      ment.  If no backup name is given, a list of backups that can be restored is displayed.  The user is asked to confirm before  action
	      is taken.

   Command line options
       The following options are specified before the subcommand on the command line.

       --help Displays usage and copyright information, then exit.

       --version
	      Displays fedfs-utils version information, then exit.

       --stateidr=pathname
	      Specifies the pathname of the local directory under which NSDB data is maintained.  By default, this directory is /var/lib/fedfs.

   Subcommand options
       --security=mode
	      Selects the security mode of the NSDB.  This option may be specified only on the install subcommand.  Valid mode values are none and
	      tls.

       If none is specified, or the --security= option is not specified, clients can connect to this NSDB in the clear.

       If tls is specified, the install subcommand creates a self-signed x.509 certificate, and configures the NSDB so that clients  are  required
       to use TLS when connecting to the NSDB.

EXIT CODES

       The nsdb-jumpstart(8) command returns one of two values upon exit.

       0      The subcommand succeeded.

       1      The subcommand failed.

EXAMPLES

       Suppose you are the FedFS administrator of the example.net FedFS domain.  After you have chosen a reliable server in the example.net domain
       to act as your NSDB, log in on that server as root, ensure that OpenLDAP is installed, and that any configuration can be discarded.

       To create a new NSDB with a self-signed certificate for the example.net domain, use:

	      # ./nsdb-jumpstart install --security=tls
	      This command is about to replace the OpenLDAP configuration on this system.
	      Do you want to continue? [y/N] y
	      Enter the name of the Fedfs domain this NSDB will server
	      FedFS domain [ example.net ]:
	      Enter the LDAP administrator DN for this NSDB
	      Admin DN [ cn=admin,cn=config ]:
	      Enter the LDAP administrator password for this DN
	      New password:
	      Re-enter new password:
	      Enter the NSDB administrator password for this DN
	      New password:
	      Re-enter new password:
	      Last chance: about to replace the OpenLDAP configuration on this system.
	      Continue? [y/N] y
	      Setting up a self-signed x.509 certificate.  Please answer the following questions:

	      Country (C)? US
	      State or province (ST)? Massachusetts
	      City (L)? Boston
	      Organization (O)? Red Sox
	      Organizational unit (OU)? Fans

	      NSDB configuration was successful.

	      Slapd is enabled and running
	      The LDAP administrator DN is: cn=admin,cn=config
	      The NSDB administrator DN is: cn=NSDB Manager,dc=example,dc=net
	      The NCE is: ou=fedfs,dc=example,dc=net

	      Distribute the NSDB's certificate in /etc/openldap/nsdb-cert.pem
	      #

SECURITY

       The NSDB created by the nsdb-jumpstart(8) command allows anonymous read access to the NCE and all entries  under  it.   The  LDAP  server's
       rootDSE	is  also  readable  by	anyone.  An NSDB client must bind with administrator privileges to update NSDB records for a FedFS domain.
       ACLs may be adjusted after the NSDB is set up with nsdb-jumpstart(8).

       Before binding, however, NSDB clients must connect to the NSDB to use it.  The --security= setting determines what type of transport  layer
       security is required to connect to the NSDB.

       When  the --security=none option is specified during NSDB setup, or if no --security= setting is specified, NSDB clients can connect to the
       NSDB using an unencrypted connection to the standard LDAP port (389).

       By specifying the --security=tls option on the nsdb-jumpstart(8) command, a self-signed x.509 certificate is created that NSDB clients must
       use  to authenticate the NSDB and its contents.	The underlying LDAP server requires the use of TLS and the use of AES or better encryption
       when a client access the NSDB.  The NSDB never authenticates its clients.

       To use this NSDB, the new certificate material must be distributed to NSDB clients (fileservers and administrative systems)  and  installed
       using the nsdbparams(8) command, or it can be transferred directly to NSDB clients that are running the rpc.fedfsd(8) daemon.

       The  use  of  a transport encryption mechanism such as TLS is strongly recommended to protect NSDB requests on untrusted networks.  SASL is
       currently not supported for the NSDB protocol.

FILES

       /var/lib/fedfs/nsdb-jumpstart.log
	      Log file created during subcommand processing

       /etc/openldap/nsdb-cert.pem
	      File containing the server's x.509 certificate, in PEM format

       /etc/openldap/nsdb-key.pem
	      File containing the server's private key, in PEM format

       /var/lib/fedfs/nsdb-db
	      Directory containing back-end database for the LDAP server's domain controller root suffix

SEE ALSO

       fedfs(7), nfsref(8), nsdb-create-fsn(8), nsdbparams(8), rpc.fedfsd(8)

       RFC 5716 for FedFS requirements and overview

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-JUMPSTART(8)