nsdb-jumpstart (8) - Linux Manuals

nsdb-jumpstart: Administer a basic FedFS NSDB using OpenLDAP

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 administrators 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 information.

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-jumpstart.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 argument. 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

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 [at] oracle.com>