1NSDB-UPDATE-NCI(8) System Manager's Manual NSDB-UPDATE-NCI(8)
3
7 nsdb-update-nci - update NSDB container information on an LDAP server
8
10 nsdb-update-nci [-?dy] [-D binddn] [-e nce] [-l nsdbname] [-r nsdbport]
11
13 RFC 5716 introduces the Federated File System (FedFS, for short).
14 FedFS is an extensible standardized mechanism by which system adminis‐
15 trators construct a coherent namespace across multiple file servers
16 using file system referrals. For further details, see fedfs(7).
17 The bulk of FedFS junction information in a FedFS domain is stored on
19 one or more LDAP servers. These servers are known as namespace data‐
20 bases, or NSDBs, for short.
21 FedFS-enabled file servers and clients access the information stored on
23 NSDBs via standard LDAP queries. FedFS-enabled file servers use these
24 queries to resolve FedFS junctions. FedFS administrators use them to
25 manage information about file sets contained in a FedFS domain name
26 space.
27
29 The nsdb-update-nci(8) command is part of a collection of low-level
30 single-use programs that are intended for testing the NSDB protocol or
31 for use in scripts. This command is an easy way to turn a standard
32 LDAP server into an NSDB by adding NSDB container information to the
33 server's Directory Information Tree (or DIT, for short).
34 The top of the DIT on an LDAP server has one or more naming contexts.
36 Some LDAP server implementations call these contexts root suffixes. An
37 LDAP server's naming contexts are easy for clients to locate with a
38 well-known search query. All LDAP entries on that server are contained
39 under naming contexts.
40 The root LDAP object under which FedFS-related entries reside is known
42 as the NSDB Container Entry (or NCE). The NCE can be a naming context
43 object, or it can be located somewhere below the naming context. Both
44 the naming context and the NCE must be world-readable for FedFS-enabled
45 clients and servers to access the NSDB.
46 The nsdb-update-nci(8) command promotes an unremarkable LDAP entry to
48 become an NCE. This is the step that turns an LDAP server into an
49 NSDB. The target NCE object must exist before this operation can com‐
50 plete successfully.
51
53 -d, --debug
54 Enables debugging messages during operation.
55 -?, --help
57 Displays nsdb-update-nci(8) version information and a usage mes‐
58 sage on stderr.
59 -D, --binddn=bind-distinguished-name
61 Specifies a distinguished name of an entity used to bind to the
62 LDAP server where the NSDB resides. If the --binddn option is
63 not specified, the value of the FEDFS_NSDB_ADMIN environment
64 variable is consulted. If this variable is not set, the NSDB
65 connection parameter database is searched for this DN. If none
66 of these is specified, or if this entity does not have permis‐
67 sion to modify this area of the server's DIT, the nsdb-update-
68 nci(8) command fails.
69 -e, --nce=NSDB-container-entry-distinguished-name
71 Specifies the distinguished name of the new NSDB container
72 entry. If the --nce option is not specified, the value of the
73 FEDFS_NSDB_NCE environment variable is consulted. If this vari‐
74 able is not set, then the NSDB connection parameter database is
75 searched for this DN. If none of these is specified, the nsdb-
76 update-nci(8) command fails.
77 -l, --nsdbname=NSDB-hostname
79 Specifies the hostname of the NSDB where the target NCE should
80 reside. If the --nsdbname option is not specified, the value of
81 the FEDFS_NSDB_HOST environment variable is consulted. If the
82 variable is not set and the --nsdbname option is not specified,
83 the nsdb-update-nci(8) command fails.
84 -r, --nsdbport=NSDB-port
86 Specifies the IP port of the NSDB where the target NCE should
87 reside. If the --nsdbport option is not specified, the value of
88 the FEDFS_NSDB_PORT environment variable is consulted. The
89 default value if the variable is not set is 389.
90 -y, --delete
92 Specifies that NSDB Container Information for this NCE should be
93 removed from this LDAP server. This operation cannot be undone.
94
96 The NSDB returns a value that reflects the success of the requested
97 operation.
98 FEDFS_OK
100 The LDAP modify request succeeded.
101 FEDFS_ERR_ACCESS
103 The bound entity does not have permission to perform the
104 requested operation.
105 FEDFS_ERR_INVAL
107 One of the arguments was not valid.
108 FEDFS_ERR_SVRFAULT
110 An unanticipated non-protocol error occurred.
111 FEDFS_ERR_NSDB_ROUTE
113 The nsdb-update-nci(8) command was unable to find a route to the
114 specified NSDB.
115 FEDFS_ERR_NSDB_DOWN
117 The nsdb-update-nci(8) command determined that the specified
118 NSDB was down.
119 FEDFS_ERR_NSDB_CONN
121 The nsdb-update-nci(8) command was unable to establish a connec‐
122 tion with the specified NSDB.
123 FEDFS_ERR_NSDB_AUTH
125 The nsdb-update-nci(8) command was unable to authenticate and
126 establish a secure connection with the specified NSDB.
127 FEDFS_ERR_NSDB_LDAP
129 A non-specific LDAP error occurred on the connection between the
130 nsdb-update-nci(8) command and specified NSDB.
131 FEDFS_ERR_NSDB_LDAP_VAL
133 An LDAP error occurred on the connection between the nsdb-
134 update-nci(8) command and specified NSDB. The specific error
135 may be displayed on the command line.
136 FEDFS_ERR_NSDB_RESPONSE
138 The nsdb-update-nci(8) command received a malformed response
139 from the specified NSDB.
140 FEDFS_ERR_NSDB_FAULT
142 An unanticipated error related to the specified NSDB occurred.
143 FEDFS_ERR_NSDB_PARAMS
145 The local NSDB connection parameter database does not have any
146 connection parameters on record for the specified NSDB.
147 FEDFS_ERR_NSDB_LDAP_REFERRAL
149 The nsdb-update-nci(8) command received an LDAP referral that it
150 was unable to follow.
151 FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL
153 The nsdb-update-nci(8) command received an LDAP referral that it
154 was unable to follow. A specific error may be displayed on the
155 command line.
156 FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED
158 The nsdb-update-nci(8) command received an LDAP referral that it
159 chose not to follow, either because the local implementation
160 does not support following LDAP referrals or LDAP referral fol‐
161 lowing is disabled.
162 FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL
164 The nsdb-update-nci(8) command received an LDAP referral that it
165 chose not to follow because the local NSDB connection parameter
166 database had no connection parameters for the NSDB targeted by
167 the LDAP referral.
168
170 Suppose you are the FedFS administrator of the example.net FedFS domain
171 and that you want to make the LDAP server ldap.example.net into an
172 NSDB. After creating a naming context and root suffix object with a
173 distinguished name of o=fedfs on the LDAP server, you might use:
174 $ nsdb-update-nci -l ldap.example.net -D cn=Manager -e o=fedfs
176 Enter NSDB password:
177 Successfully updated NCI
178 NSDB container information is inserted into o=fedfs, and this entry is
180 changed to an NSDB Container Entry.
181 To see the new container information, use nsdb-nces(8).
183 o=fedfs is a typical location for an NCE on an LDAP server. However,
185 suppose that instead of creating such a typical NCE, you would prefer
186 the entry ou=fedfs,dc=example,dc=net to contain FedFS information.
187 Assuming your server set-up script has already created the dc=exam‐
188 ple,dc=net naming context and root object, and after creating a generic
189 object with the distinguished name ou=fedfs,dc=example,dc=net, you
190 might use:
191 $ nsdb-update-nci -e "ou=fedfs,dc=example,dc=net" -D cn=Manager
193 Enter NSDB password:
194 Successfully updated NCI
195 NSDB container information is inserted into dc=example,dc=net, and the
197 entry at ou=fedfs,dc=example,dc=net is made into an NCE.
198 To see the new NCE, use nsdb-nces(8).
200
202 LDAP naming contexts are typically writable only by administrative
203 entities. The nsdb-update-nci(8) command must bind as an administra‐
204 tive entity to perform this operation. The nsdb-update-nci(8) command
205 asks for a password on stdin. Standard password blanking techniques
206 are used to obscure the password on the user's terminal.
207 The target LDAP server must be registered in the local NSDB connection
209 parameter database. The connection security mode listed in the NSDB
210 connection parameter database for the target LDAP server is used during
211 this operation. See nsdbparams(8) for details on how to register an
212 NSDB in the local NSDB connection parameter database.
213
215 fedfs(7), nsdb-nces(8), nsdbparams(8)
216 RFC 5716 for FedFS requirements and overview
218 RFC 4510 for an introduction to LDAP
220
222 This page is part of the fedfs-utils package. A description of the
223 project and information about reporting bugs can be found at
224 http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject.
225
227 Chuck Lever <chuck.lever@oracle.com>
228 3 February 2014 NSDB-UPDATE-NCI(8)