1NSDB-ANNOTATE(8) System Manager's Manual NSDB-ANNOTATE(8)
3
7 nsdb-annotate - modify an fedfsAnnotation attribute
8
10 nsdb-annotate [-?dy] [-a annotation] [-D binddn] [-k keyword] [-l nsdb‐
11 name] [-r nsdbport] [-v value] 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-annotate(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 fedfsAn‐
33 notation 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 fedfsAnnotation attribute, thus a fully qualified
38 distinguished name, rather than, say, an FSN UUID by itself, must be
39 specified.
40 The fedfsAnnotation attribute itself is multi-valued. Each attribute
42 value is a structured string containing a keyword in double quotes, an
43 equals-sign, and a value in double quotes. The keyword and value may
44 contain any valid UTF-8 character. Escaping allows double quotes and
45 equals-signs to appear in the keyword and values.
46 The nsdb-annotate(8) command can construct the structured string from a
48 specified keyword and a value via the --keyword and --value command
49 line options, or it can take a single structured string as the full
50 keyword-value via the --annotation command line option. The nsdb-anno‐
51 tate(8) command inserts new values or deletes or replaces existing ones
52 while maintaining the correct structure of each value of the fedfsAnno‐
53 tation attribute.
54 Each value of the fedfsAnnotation attribute has no meaning to FedFS and
56 is ignored. Annotation allows local extensions of FedFS without
57 requiring changes to the NSDB's FedFS schema.
58
60 -a, --annotation=spelled-out-annotation
61 Specifies a properly formed fedfsAnnotation string to process.
62 The form of the string is not checked by the nsdb-annotate (8)
63 command. If the --delete option is specified and this string
64 exists as a value of the target record's fedfsAnnotation
65 attribute, it is removed. Otherwise the value is added.
66 -d, --debug
68 Enables debugging messages during operation.
69 -?, --help
71 Displays nsdb-annotate(8) version information and a usage mes‐
72 sage on stderr.
73 -D, --binddn=bind-distinguished-name
75 Specifies a distinguished name of an entity used to bind to the
76 LDAP server where the NSDB resides. If the --binddn option is
77 not specified, the value of the FEDFS_NSDB_ADMIN environment
78 variable is consulted. If this variable is not set, the NSDB
79 connection parameter database is searched for this DN. If none
80 of these is specified, or if this entity does not have permis‐
81 sion to modify this area of the server's DIT, the nsdb-anno‐
82 tate(8) command fails.
83 -k, --keyword=annotation-keyword
85 Specifies the keyword part of a fedfsAnnotation string. Use
86 either the --keyword and --value options or the --annotation
87 option to specify the fedfsAnnotation string to process, not
88 both. If the --delete option is specified and this string
89 exists as a value of the target record's fedfsAnnotation
90 attribute, it is removed. Otherwise the value is added.
91 -l, --nsdbname=NSDB-hostname
93 Specifies the hostname of the NSDB where the target record
94 resides. If the --nsdbname option is not specified, the value
95 of the FEDFS_NSDB_HOST environment variable is consulted. If
96 the variable is not set and the --nsdbname option is not speci‐
97 fied, the nsdb-annotate(8) command fails.
98 -r, --nsdbport=NSDB-port
100 Specifies the IP port of the NSDB where the target record
101 resides. If the --nsdbport option is not specified, the value
102 of the FEDFS_NSDB_PORT environment variable is consulted. The
103 default value if the variable is not set is 389.
104 -v, --value=annotation-value
106 Specifies the value part of a fedfsAnnotation string. Use
107 either the --keyword and --value options or the --annotation
108 option to specify the fedfsAnnotation string to process, not
109 both. If the --delete option is specified and this string
110 exists as a value of the target record's fedfsAnnotation
111 attribute, it is removed. Otherwise the value is added.
112 -y, --delete
114 Specifies that the specified value string is deleted rather than
115 added.
116
118 The NSDB returns a value that reflects the success of the requested
119 operation.
120 FEDFS_OK
122 The LDAP modify request succeeded.
123 FEDFS_ERR_ACCESS
125 The bound entity does not have permission to perform the
126 requested operation.
127 FEDFS_ERR_INVAL
129 One of the arguments was not valid.
130 FEDFS_ERR_SVRFAULT
132 An unanticipated non-protocol error occurred.
133 FEDFS_ERR_NSDB_ROUTE
135 The nsdb-annotate(8) command was unable to find a route to the
136 specified NSDB.
137 FEDFS_ERR_NSDB_DOWN
139 The nsdb-annotate(8) command determined that the specified NSDB
140 was down.
141 FEDFS_ERR_NSDB_CONN
143 The nsdb-annotate(8) command was unable to establish a connec‐
144 tion with the specified NSDB.
145 FEDFS_ERR_NSDB_AUTH
147 The nsdb-annotate(8) command was unable to authenticate and
148 establish a secure connection with the specified NSDB.
149 FEDFS_ERR_NSDB_LDAP
151 A non-specific LDAP error occurred on the connection between the
152 nsdb-annotate(8) command and specified NSDB.
153 FEDFS_ERR_NSDB_LDAP_VAL
155 An LDAP error occurred on the connection between the nsdb-anno‐
156 tate(8) command and specified NSDB. The specific error may be
157 displayed on the command line.
158 FEDFS_ERR_NSDB_NONCE
160 The nsdb-annotate(8) command was unable to locate the NCE on the
161 specified NSDB.
162 FEDFS_ERR_NSDB_NOFSN
164 The nsdb-annotate(8) command was unable to locate the specified
165 FSN on the specified NSDB.
166 FEDFS_ERR_NSDB_NOFSL
168 The nsdb-annotate(8) command was unable to locate any FSLs for
169 the specified FSN on the specified NSDB.
170 FEDFS_ERR_NSDB_RESPONSE
172 The nsdb-annotate(8) command received a malformed response from
173 the specified NSDB.
174 FEDFS_ERR_NSDB_FAULT
176 An unanticipated error related to the specified NSDB occurred.
177 FEDFS_ERR_NSDB_PARAMS
179 The local NSDB connection parameter database does not have any
180 connection parameters on record for the specified NSDB.
181 FEDFS_ERR_NSDB_LDAP_REFERRAL
183 The nsdb-annotate(8) command received an LDAP referral that it
184 was unable to follow.
185 FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL
187 The nsdb-annotate(8) command received an LDAP referral that it
188 was unable to follow. A specific error may be displayed on the
189 command line.
190 FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED
192 The nsdb-annotate(8) command received an LDAP referral that it
193 chose not to follow, either because the local implementation
194 does not support following LDAP referrals or LDAP referral fol‐
195 lowing is disabled.
196 FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL
198 The nsdb-annotate(8) command received an LDAP referral that it
199 chose not to follow because the local NSDB connection parameter
200 database had no connection parameters for the NSDB targeted by
201 the LDAP referral.
202
204 Suppose you are the FedFS administrator of the example.net FedFS domain
205 and that you want to modify the record for FSN UUID
206 dc25a644-06e4-11e0-ae55-000c29dc7f8a on the LDAP server nsdb.exam‐
207 ple.net. You might use:
208 $ nsdb-annotate -l nsdb.example.net \
210 -k readonly -v yes -D cn=Manager \
211 fedfsFsnUuid=dc25a644-06e4-\
212 11e0-ae55-000c29dc7f8a,o=fedfs
213 Enter NSDB password:
214 Successfully updated annotation "readonly" = "yes" for
215 fedfsFsnUuid=dc25a644-06e4-11e0-ae55-000c29dc7f8a,o=fedfs
216 To see the new annotation, use nsdb-resolve-fsn(8).
218
220 Permission to modify the LDAP's DIT is required to update an LDAP
221 entry. The nsdb-annotate(8) command must bind as an entity permitted
222 to modify the DIT to perform this operation. The nsdb-annotate(8) com‐
223 mand asks for a bind password on stdin. Standard password blanking
224 techniques are used to obscure the password on the user's terminal.
225 The target LDAP server must be registered in the local NSDB connection
227 parameter database. The connection security mode listed in the NSDB
228 connection parameter database for the target LDAP server is used during
229 this operation. See nsdbparams(8) for details on how to register an
230 NSDB in the local NSDB connection parameter database.
231
233 fedfs(7), nsdb-resolve-fsn(8), nsdbparams(8)
234 RFC 5716 for FedFS requirements and overview
236 RFC 4510 for an introduction to LDAP
238
240 This page is part of the fedfs-utils package. A description of the
241 project and information about reporting bugs can be found at
242 http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject.
243
245 Chuck Lever <chuck.lever@oracle.com>
246 3 February 2014 NSDB-ANNOTATE(8)