1NSDB-DESCRIBE(8) System Manager's Manual NSDB-DESCRIBE(8)
3
7 nsdb-describe - modify an fedfsDescr attribute
8
10 nsdb-describe [-?dy] [-a description] [-D binddn] [-l nsdbname] [-r
11 nsdbport] distinguished-name
12
14 RFC 5716 introduces the Federated File System (FedFS, for short).
15 FedFS is an extensible standardized mechanism by which system adminis‐
16 trators construct a coherent namespace across multiple file servers
17 using file system referrals. For further details, see fedfs(7).
18 The bulk of FedFS junction information in a FedFS domain is stored on
20 one or more LDAP servers. These servers are known as namespace data‐
21 bases, or NSDBs, for short.
22 FedFS-enabled file servers and clients access the information stored on
24 NSDBs via standard LDAP queries. FedFS-enabled file servers use these
25 queries to resolve FedFS junctions. FedFS administrators use them to
26 manage information about file sets contained in a FedFS domain name
27 space.
28
30 The nsdb-describe(8) command is part of a collection of low-level sin‐
31 gle-use programs that is intended for testing the NSDB protocol or for
32 use in scripts. It allows FedFS administrators to update the fedfsDe‐
33 scr attribute of FedFS records stored on an NSDB.
34 This command has one positional parameter which specifies the LDAP dis‐
36 tinguished name of the FedFS record to be modified. All FedFS object
37 classes may have a fedfsDescr attribute, thus a fully qualified distin‐
38 guished name, rather than, say, an FSN UUID by itself, must be speci‐
39 fied.
40 The fedfsDescr attribute is multi-valued. Each attribute value is an
42 unstructured string. These strings may contain any valid UTF-8 charac‐
43 ter.
44 The nsdb-describe(8) command inserts new values or deletes or replaces
46 existing ones while maintaining the correct structure of the fedfsDescr
47 attribute.
48 Each value of the fedfsDescr attribute has no meaning to FedFS and is
50 ignored. Adding a description allows free-form documentation of a
51 FedFS record to be stored with it without requiring changes to the
52 NSDB's FedFS schema.
53
55 -a, --description=description-text
56 Specifies a single fedfsDescr string to be added to or deleted
57 from the attribute's value. The form of the string is not
58 checked by the nsdb-describe (8) command. If the --delete
59 option is specified and this string exists as a value of the
60 target record's fedfsDescr attribute, it is removed. Otherwise
61 the value is added.
62 -d, --debug
64 Enables debugging messages during operation.
65 -?, --help
67 Displays nsdb-describe(8) version information and a usage mes‐
68 sage on stderr.
69 -D, --binddn=bind-distinguished-name
71 Specifies a distinguished name of an entity used to bind to the
72 LDAP server where the NSDB resides. If the --binddn option is
73 not specified, the value of the FEDFS_NSDB_ADMIN environment
74 variable is consulted. If this variable is not set, the NSDB
75 connection parameter database is searched for this DN. If none
76 of these is specified, or if this entity does not have permis‐
77 sion to modify this area of the server's DIT, the nsdb-
78 describe(8) command fails.
79 -l, --nsdbname=NSDB-hostname
81 Specifies the hostname of the NSDB where the target record
82 resides. If the --nsdbname option is not specified, the value
83 of the FEDFS_NSDB_HOST environment variable is consulted. If
84 the variable is not set and the --nsdbname option is not speci‐
85 fied, the nsdb-describe(8) command fails.
86 -r, --nsdbport=NSDB-port
88 Specifies the IP port of the NSDB where the target record
89 resides. If the --nsdbport option is not specified, the value
90 of the FEDFS_NSDB_PORT environment variable is consulted. The
91 default value if the variable is not set is 389.
92 -y, --delete
94 Specifies that the specified value string is deleted rather than
95 added.
96
98 The NSDB returns a value that reflects the success of the requested
99 operation.
100 FEDFS_OK
102 The LDAP modify request succeeded.
103 FEDFS_ERR_ACCESS
105 The bound entity does not have permission to perform the
106 requested operation.
107 FEDFS_ERR_INVAL
109 One of the arguments was not valid.
110 FEDFS_ERR_SVRFAULT
112 An unanticipated non-protocol error occurred.
113 FEDFS_ERR_NSDB_ROUTE
115 The nsdb-describe(8) command was unable to find a route to the
116 specified NSDB.
117 FEDFS_ERR_NSDB_DOWN
119 The nsdb-describe(8) command determined that the specified NSDB
120 was down.
121 FEDFS_ERR_NSDB_CONN
123 The nsdb-describe(8) command was unable to establish a connec‐
124 tion with the specified NSDB.
125 FEDFS_ERR_NSDB_AUTH
127 The nsdb-describe(8) command was unable to authenticate and
128 establish a secure connection with the specified NSDB.
129 FEDFS_ERR_NSDB_LDAP
131 A non-specific LDAP error occurred on the connection between the
132 nsdb-describe(8) command and specified NSDB.
133 FEDFS_ERR_NSDB_LDAP_VAL
135 An LDAP error occurred on the connection between the nsdb-
136 describe(8) command and specified NSDB. The specific error may
137 be displayed on the command line.
138 FEDFS_ERR_NSDB_NONCE
140 The nsdb-describe(8) command was unable to locate the NCE on the
141 specified NSDB.
142 FEDFS_ERR_NSDB_NOFSN
144 The nsdb-describe(8) command was unable to locate the specified
145 FSN on the specified NSDB.
146 FEDFS_ERR_NSDB_NOFSL
148 The nsdb-describe(8) command was unable to locate any FSLs for
149 the specified FSN on the specified NSDB.
150 FEDFS_ERR_NSDB_RESPONSE
152 The nsdb-describe(8) command received a malformed response from
153 the specified NSDB.
154 FEDFS_ERR_NSDB_FAULT
156 An unanticipated error related to the specified NSDB occurred.
157 FEDFS_ERR_NSDB_PARAMS
159 The local NSDB connection parameter database does not have any
160 connection parameters on record for the specified NSDB.
161 FEDFS_ERR_NSDB_LDAP_REFERRAL
163 The nsdb-describe(8) command received an LDAP referral that it
164 was unable to follow.
165 FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL
167 The nsdb-describe(8) command received an LDAP referral that it
168 was unable to follow. A specific error may be displayed on the
169 command line.
170 FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED
172 The nsdb-describe(8) command received an LDAP referral that it
173 chose not to follow, either because the local implementation
174 does not support following LDAP referrals or LDAP referral fol‐
175 lowing is disabled.
176 FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL
178 The nsdb-describe(8) command received an LDAP referral that it
179 chose not to follow because the local NSDB connection parameter
180 database had no connection parameters for the NSDB targeted by
181 the LDAP referral.
182
184 Suppose you are the FedFS administrator of the example.net FedFS
185 domain, and you want to modify the record for FSN UUID
186 dc25a644-06e4-11e0-ae55-000c29dc7f8a on the NSDB nsdb.example.net. You
187 might use:
188 $ nsdb-describe -l nsdb.example.net \
190 -a "Hello, world\!" -D cn=Manager \
191 fedfsFsnUuid=dc25a644-06e4-\
192 11e0-ae55-000c29dc7f8a,o=fedfs
193 Enter NSDB password:
194 Successfully updated description value for
195 fedfsFsnUuid=dc25a644-06e4-11e0-ae55-000c29dc7f8a,o=fedfs
196 To see the new description, use nsdb-resolve-fsn(8).
198
200 Permission to modify the LDAP's DIT is required to update an LDAP
201 entry. The nsdb-describe(8) command must bind as an entity permitted
202 to modify the DIT to perform this operation. The nsdb-describe(8) com‐
203 mand asks for a password on stdin. Standard password blanking tech‐
204 niques are used to obscure the password on the user's terminal.
205 The target LDAP server must be registered in the local NSDB connection
207 parameter database. The connection security mode listed in the NSDB
208 connection parameter database for the target LDAP server is used during
209 this operation. See nsdbparams(8) for details on how to register an
210 NSDB in the local NSDB connection parameter database.
211
213 fedfs(7), nsdb-resolve-fsn(8), nsdbparams(8)
214 RFC 5716 for FedFS requirements and overview
216 RFC 4510 for an introduction to LDAP
218
220 This page is part of the fedfs-utils package. A description of the
221 project and information about reporting bugs can be found at
222 http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject.
223
225 Chuck Lever <chuck.lever@oracle.com>
226 3 February 2014 NSDB-DESCRIBE(8)