1NSDB-JUMPSTART(8) System Manager's Manual NSDB-JUMPSTART(8)
3
7 nsdb-jumpstart - Administer a basic FedFS NSDB using OpenLDAP
8
10 nsdb-jumpstart [-h,--help] [--version]
11 nsdb-jumpstart [--statedir= statedir] install [--security= mode]
13 nsdb-jumpstart [--statedir= statedir] status
15 nsdb-jumpstart [--statedir= statedir] backup
17 nsdb-jumpstart [--statedir= statedir] restore [backup-name]
19
21 RFC 5716 introduces the Federated File System (FedFS, for short).
22 FedFS is an extensible standardized mechanism by which system adminis‐
23 trators construct a coherent namespace across multiple file servers
24 using file system referrals. For further details, see fedfs(7).
25 A FedFS domain's namespace is joined together via junctions. When a
27 file-access client encounters a junction on a file server, the file
28 server provides a list of locations where that client can access the
29 target file set to which the juntion refers.
30 In a FedFS domain, these location lists are stored on one or more LDAP
32 servers, known as namespace databases, or NSDBs, for short.
33 FedFS-enabled file servers access the information stored on NSDBs via
35 standard LDAP queries. Tools that administer a FedFS domain use ldap‐
36 modify queries to manage information stored on an NSDB. File-access
37 clients have no need to access NSDBs directly.
38 Further information about junctions and NSDBs is available in fedfs(7).
40
42 The FedFS NSDB Proposed Standard allows flexible use of any LDAP server
43 and its Directory Information Tree to store and manage NSDB informa‐
44 tion.
45 The nsdb-jumpstart(8) command provides a simplified but fully capable
47 stand-alone NSDB based specifically on OpenLDAP. Using this command,
48 you can install a fresh NSDB, or back up or restore your NSDB data. It
49 can even construct a self-signed x.509 certificate to enable secure
50 NSDB queries.
51 Operation
53 The install subcommand sets up an empty NSDB, ready to be used in a
54 FedFS domain. The new NSDB replaces any OpenLDAP configuration that
55 may already exist on the system. OpenLDAP must already be installed on
56 the system.
57 Once the new NSDB is running, FedFS fileset location information is
59 stored as records in a Directory Information Tree under the NCE. This
60 information is managed with commands like nsdb-create-fsn(8).
61 A handful of parameters are needed to set up the new NSDB. These are
63 gathered via a brief interview. The domain name and administrator cre‐
64 dentials are provided during this interview. Passwords are not checked
65 for strength, however blank passwords are not permitted.
66 The baseline security requirements for the NSDB are specified at
68 install time using the --security= option. See the SECURITY section
69 for an in-depth discussion.
70 Once set up with the install subcommand, OpenLDAP listens for LDAP
72 queries on the standard LDAP port (389). The underlying LDAP server
73 can be configured like any other OpenLDAP server using the new-style
74 cn=config configuration interface.
75 To display the current status of the NSDB service on the local host,
77 use the status subcommand. Information about the local NSDB service is
78 displayed, including whether the LDAP service is started, whether it
79 actually is an NSDB, and whether TLS security is required to use it.
80 The nsdb-jumpstart(8) command also provides backup and restore facili‐
82 ties. The backup subcommand saves location information stored on the
83 local NSDB to a dated LDIF file. LDIF files created by the backup com‐
84 mand are stored in the /var/lib/fedfs/nsdb-backup directory by default.
85 The restore subcommand completely replaces the contents of the NSDB
87 with a backup contained in of one of the previously saved LDIF files.
88 The restore subcommand takes one positional argument, which is the name
89 of the backup to restore. A list of backups is displayed by using the
90 restore subcommand with no argument.
91 The nsdb-jumpstart(8) command must run as root. A audit log of each
93 nsdb-jumpstart(8) operation is stored in /var/lib/fedfs/nsdb-jump‐
94 start.log.
95 Subcommands
97 Valid nsdb-jumpstart(8) subcommands are:
98 install
100 Replace the OpenLDAP configuration on the local system with a
101 ready-built NSDB. The user is asked to confirm before action is
102 taken.
103 Specifying the --security= option sets the transport security
105 that the NSDB requires clients to use when communicating with
106 it.
107 status Display the status of the NSDB on the local system. This sub‐
109 command takes no arguments.
110 backup Generate an LDIF containing the NSDB information stored on the
112 local LDAP server. The LDIF is stored in a dated file under
113 /var/lib/fedfs/nsdb-backup. This subcommand takes no arguments.
114 restore
116 Replace the NSDB information on the local LDAP server with the
117 contents of an LDIF. This subcommand takes a backup name as an
118 argument. If no backup name is given, a list of backups that
119 can be restored is displayed. The user is asked to confirm
120 before action is taken.
121 Command line options
123 The following options are specified before the subcommand on the com‐
124 mand line.
125 --help Displays usage and copyright information, then exit.
127 --version
129 Displays fedfs-utils version information, then exit.
130 --stateidr=pathname
132 Specifies the pathname of the local directory under which NSDB
133 data is maintained. By default, this directory is
134 /var/lib/fedfs.
135 Subcommand options
137 --security=mode
138 Selects the security mode of the NSDB. This option may be spec‐
139 ified only on the install subcommand. Valid mode values are
140 none and tls.
141 If none is specified, or the --security= option is not specified,
143 clients can connect to this NSDB in the clear.
144 If tls is specified, the install subcommand creates a self-signed x.509
146 certificate, and configures the NSDB so that clients are required to
147 use TLS when connecting to the NSDB.
148
150 The nsdb-jumpstart(8) command returns one of two values upon exit.
151 0 The subcommand succeeded.
153 1 The subcommand failed.
155
157 Suppose you are the FedFS administrator of the example.net FedFS
158 domain. After you have chosen a reliable server in the example.net
159 domain to act as your NSDB, log in on that server as root, ensure that
160 OpenLDAP is installed, and that any configuration can be discarded.
161 To create a new NSDB with a self-signed certificate for the example.net
163 domain, use:
164 # ./nsdb-jumpstart install --security=tls
166 This command is about to replace the OpenLDAP configuration on
167 this system.
168 Do you want to continue? [y/N] y
169 Enter the name of the Fedfs domain this NSDB will server
170 FedFS domain [ example.net ]:
171 Enter the LDAP administrator DN for this NSDB
172 Admin DN [ cn=admin,cn=config ]:
173 Enter the LDAP administrator password for this DN
174 New password:
175 Re-enter new password:
176 Enter the NSDB administrator password for this DN
177 New password:
178 Re-enter new password:
179 Last chance: about to replace the OpenLDAP configuration on this
180 system.
181 Continue? [y/N] y
182 Setting up a self-signed x.509 certificate. Please answer the
183 following questions:
184 Country (C)? US
186 State or province (ST)? Massachusetts
187 City (L)? Boston
188 Organization (O)? Red Sox
189 Organizational unit (OU)? Fans
190 NSDB configuration was successful.
192 Slapd is enabled and running
194 The LDAP administrator DN is: cn=admin,cn=config
195 The NSDB administrator DN is: cn=NSDB Manager,dc=example,dc=net
196 The NCE is: ou=fedfs,dc=example,dc=net
197 Distribute the NSDB's certificate in /etc/openldap/nsdb-cert.pem
199 #
200
202 The NSDB created by the nsdb-jumpstart(8) command allows anonymous read
203 access to the NCE and all entries under it. The LDAP server's rootDSE
204 is also readable by anyone. An NSDB client must bind with administra‐
205 tor privileges to update NSDB records for a FedFS domain. ACLs may be
206 adjusted after the NSDB is set up with nsdb-jumpstart(8).
207 Before binding, however, NSDB clients must connect to the NSDB to use
209 it. The --security= setting determines what type of transport layer
210 security is required to connect to the NSDB.
211 When the --security=none option is specified during NSDB setup, or if
213 no --security= setting is specified, NSDB clients can connect to the
214 NSDB using an unencrypted connection to the standard LDAP port (389).
215 By specifying the --security=tls option on the nsdb-jumpstart(8) com‐
217 mand, a self-signed x.509 certificate is created that NSDB clients must
218 use to authenticate the NSDB and its contents. The underlying LDAP
219 server requires the use of TLS and the use of AES or better encryption
220 when a client access the NSDB. The NSDB never authenticates its
221 clients.
222 To use this NSDB, the new certificate material must be distributed to
224 NSDB clients (fileservers and administrative systems) and installed
225 using the nsdbparams(8) command, or it can be transferred directly to
226 NSDB clients that are running the rpc.fedfsd(8) daemon.
227 The use of a transport encryption mechanism such as TLS is strongly
229 recommended to protect NSDB requests on untrusted networks. SASL is
230 currently not supported for the NSDB protocol.
231
233 /var/lib/fedfs/nsdb-jumpstart.log
234 Log file created during subcommand processing
235 /etc/openldap/nsdb-cert.pem
237 File containing the server's x.509 certificate, in PEM format
238 /etc/openldap/nsdb-key.pem
240 File containing the server's private key, in PEM format
241 /var/lib/fedfs/nsdb-db
243 Directory containing back-end database for the LDAP server's
244 domain controller root suffix
245
247 fedfs(7), nfsref(8), nsdb-create-fsn(8), nsdbparams(8), rpc.fedfsd(8)
248 RFC 5716 for FedFS requirements and overview
250
252 This page is part of the fedfs-utils package. A description of the
253 project and information about reporting bugs can be found at
254 http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject.
255
257 Chuck Lever <chuck.lever@oracle.com>
258 3 February 2014 NSDB-JUMPSTART(8)