@@ -25,7 +25,7 @@
.\"
.TH NSDB-ANNOTATE 8 "@publication-date@"
.SH NAME
-nsdb-annotate \- modify the fedfsAnnotation attribute of an NSDB entry
+nsdb-annotate \- modify the fedfsAnnotation attribute of a FedFS NSDB record
.SH SYNOPSIS
.B nsdb-annotate
.RB [ \-?dy ]
@@ -33,8 +33,6 @@ nsdb-annotate \- modify the fedfsAnnotation attribute of an NSDB entry
.IR annotation ]
.RB [ \-D
.IR binddn ]
-.RB \-e
-.IR entry
.RB [ \-k
.IR keyword ]
.RB [ \-l
@@ -45,6 +43,7 @@ nsdb-annotate \- modify the fedfsAnnotation attribute of an NSDB entry
.IR bindpw ]
.RB [ \-v
.IR value ]
+.I distinguished-name
.SH INTRODUCTION
RFC 5716 introduces the Federated File System (FedFS, for short).
FedFS is an extensible standardized mechanism
@@ -68,48 +67,80 @@ about file sets contained in a FedFS domain name space.
.SH DESCRIPTION
The
.BR nsdb-annotate (8)
-command is part of a collection of low-level single-use programs that are
-intended for testing the NSDB protocol or for use in scripts.
-It allows FedFS administrators to update the fedfsAnnotation
-attribute of entries stored on an NSDB.
+command is part of a collection of low-level single-use programs
+that is intended for testing the NSDB protocol or for use in scripts.
+It allows FedFS administrators to update the
+.B fedfsAnnotation
+attribute of FedFS records stored on an NSDB.
.P
-An entry's fedfsAnnotation attribute is multi-valued.
-Each value of this attribute is a structured string containing
-a keyword in double quotes, an equals sign, and a value in double quotes.
-The keyword and value can contain any valid UTF-8 character.
-The whole string has no meaning to FedFS and is ignored.
+This command has one positional parameter which specifies the
+LDAP distinguished name of the FedFS record to be modified.
+All FedFS object classes may have a
+.B fedfsAnnotation
+attribute, thus a fully qualified distinguished name, rather than, say,
+an FSN UUID by itself, must be specified.
.P
-This allows local extensions of FedFS to be created without
-requiring changes to the NSDB's FedFS schema.
+The
+.B fedfsAnnotation
+attribute itself is multi-valued.
+Each attribute value is a structured string containing
+a keyword in double quotes, an equals-sign, and a value in double quotes.
+The keyword and value may contain any valid UTF-8 character.
+Escaping allows double quotes and equals-signs to appear in the keyword
+and values.
+.P
+The
+.BR nsdb-annotate (8)
+command can construct the structured string
+from a specified keyword and a value via the
+.B \-\-keyword
+and
+.B \-\-value
+command line options,
+or it can take a single structured string as the full keyword-value
+via the
+.B \-\-annotation
+command line option.
The
.BR nsdb-annotate (8)
-command can insert new values or delete or replace old ones,
+command inserts new values or deletes or replaces existing ones
while maintaining the correct structure of each value
-of the fedfsAnnotation attribute.
+of the
+.B fedfsAnnotation
+attribute.
+.P
+Each value of the
+.B fedfsAnnotation
+attribute has no meaning to FedFS and is ignored.
+Annotation allows local extensions of FedFS
+without requiring changes to the NSDB's FedFS schema.
.SH OPTIONS
.IP "\fB\-a, \-\-annotation=\fIspelled-out-annotation\fP"
-Specifies a properly formed fedfsAnnotation value.
-The form of the value is not checked by the
+Specifies a properly formed
+.B fedfsAnnotation
+string to process.
+The form of the string is not checked by the
.BR
nsdb-annotate (8)
command.
If the
-.B -y
-option is specified and this value exists in the target
-entry's fedfsAnnotation attribute, it is removed.
+.B \-\-delete
+option is specified and this string exists as a value of the target record's
+.B fedfsAnnotation
+attribute, it is removed.
Otherwise the value is added.
.IP "\fB\-d, \-\-debug"
-Specifies that debugging messages be produced during operation.
+Enables debugging messages during operation.
.IP "\fB\-?, \-\-help"
-Prints an
+Displays
.BR nsdb-annotate (8)
-version and usage message on
-.IR stderr ,
-then exits.
+version information and a usage message on
+.IR stderr .
.IP "\fB-D, \-\-binddn=\fIbind-distinguished-name\fP"
-Specifies a distinguished name of an entity used to bind to this LDAP server.
+Specifies a distinguished name of an entity used to bind to the LDAP server
+where the NSDB resides.
If the
-.B -D
+.B \-\-binddn
option is not specified,
the value of the FEDFS_NSDB_ADMIN environment variable is consulted.
If this variable is not set,
@@ -119,70 +150,69 @@ if this entity does not have permission to modify this area
of the server's DIT, the
.BR nsdb-annotate (8)
command fails.
-.IP "\fB-e, \-\-entry=\fIdistinguished-name\fP"
-Specifies the distinguished name of the target entry
-in the NSDB to modify.
-Since any FedFS entry can have a fedfsAnnotation attribute,
-a full distinguished name must be specified.
-If the
-.B -e
-option is not specified,
-.BR nsdb-annotate (8)
-command fails.
.IP "\fB-k, \-\-keyword=\fIannotation-keyword\fP"
-Specifies the keyword part of a fedfsAnnotation value.
-Use either the
-.B -k
+Specifies the keyword part of a
+.B fedfsAnnotation
+string. Use either the
+.B \-\-keyword
and
-.B -v
+.B \-\-value
options or the
-.B -a
-option to specify the fedfsAnnotation value, not both.
-If the
-.B -y
-option is specified and this value exists in the target
-entry's fedfsAnnotation attribute, it is removed.
+.B \-\-annotation
+option to specify the
+.B fedfsAnnotation
+string to process, not both. If the
+.B \-\-delete
+option is specified and this string exists as a value of the target record's
+.B fedfsAnnotation
+attribute, it is removed.
Otherwise the value is added.
.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP"
-Specifies the hostname of the NSDB where the target entry resides.
+Specifies the hostname of the NSDB where the target record resides.
If the
-.B -l
+.B \-\-nsdbname
option is not specified,
the value of the FEDFS_NSDB_HOST environment variable is consulted.
If the variable is not set and the
-.B -l
+.B \-\-nsdbname
option is not specified, the
.BR nsdb-annotate (8)
command fails.
.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP"
-Specifies the IP port of the NSDB where the target entry resides.
+Specifies the IP port of the NSDB where the target record resides.
If the
-.B -r
+.B \-\-nsdbport
option is not specified,
the value of the FEDFS_NSDB_PORT environment variable is consulted.
The default value if the variable is not set is 389.
.IP "\fB\-v, \-\-value=\fIannotation-value\fP"
-Specifies the value part of a fedfsAnnotation value.
+Specifies the value part of a
+.B fedfsAnnotation
+string.
Use either the
-.B -k
+.B \-\-keyword
and
-.B -v
+.B \-\-value
options or the
-.B -a
-option to specify the fedfsAnnotation value, not both.
+.B \-\-annotation
+option to specify the
+.B fedfsAnnotation
+string to process, not both.
If the
-.B -y
-option is specified and this value exists in the target
-entry's fedfsAnnotation attribute, it is removed.
+.B \-\-delete
+option is specified and this string exists as a value of the target record's
+.B fedfsAnnotation
+attribute, it is removed.
Otherwise the value is added.
.IP "\fB\-w, \-\-bindpw=\fIbinddn-password\fP"
-Specifies the password used for simple authentication to this LDAP server.
+Specifies the password used for simple authentication to the LDAP server
+where the NSDB resides.
If the
-.B -w
+.B \-\-bindpw
option is not specified,
the value of the FEDFS_NSDB_PASSWD environment variable is consulted.
If the variable is not set and the
-.B -w
+.B \-\-bindpw
option is not specified, the
.BR nsdb-annotate (8)
command asks for a password on
@@ -190,8 +220,7 @@ command asks for a password on
Standard password blanking techniques are used
to obscure the password on the user's terminal.
.IP "\fB\-y, \-\-delete\fP"
-Specifies that the specified fedfsAnnotation value is deleted
-rather than added.
+Specifies that the specified value string is deleted rather than added.
.SH EXIT CODES
The NSDB returns a value that reflects the success of the requested operation.
.TP
@@ -294,18 +323,18 @@ connection parameters for the NSDB targeted by the LDAP referral.
.SH EXAMPLES
Suppose you are the FedFS administrator of the
.I example.net
-FedFS domain and that you want to modify the entry for
+FedFS domain and that you want to modify the record for
FSN UUID dc25a644-06e4-11e0-ae55-000c29dc7f8a on
the LDAP server
-.IR ldap.example.net .
+.IR nsdb.example.net .
You might use:
.RS
.sp
-$ nsdb-annotate -l ldap.example.net \\
+$ nsdb-annotate -l nsdb.example.net \\
.br
-k readonly -v yes -D cn=Manager \\
.br
- -e fedfsFsnUuid=dc25a644-06e4-\\
+ fedfsFsnUuid=dc25a644-06e4-\\
.br
11e0-ae55-000c29dc7f8a,o=fedfs
.br
@@ -319,7 +348,7 @@ Successfully updated annotation "readonly" = "yes" for
To see the new annotation, use
.BR nsdb-resolve-fsn (8).
.SH SECURITY
-Modify access to the LDAP's DIT is required to update an LDAP entry.
+Permission to modify the LDAP's DIT is required to update an LDAP entry.
The
.BR nsdb-annotate (8)
command must bind as an entity permitted to modify the DIT
@@ -25,7 +25,7 @@
.\"
.TH NSDB-DESCRIBE 8 "@publication-date@"
.SH NAME
-nsdb-describe \- modify the fedfsDescr attribute of an NSDB entry
+nsdb-describe \- modify the fedfsDescr attribute of a FedFS NSDB record
.SH SYNOPSIS
.B nsdb-describe
.RB [ \-?dy ]
@@ -33,14 +33,13 @@ nsdb-describe \- modify the fedfsDescr attribute of an NSDB entry
.IR description ]
.RB [ \-D
.IR binddn ]
-.RB \-e
-.IR entry
.RB [ \-l
.IR nsdbname ]
.RB [ \-r
.IR nsdbport ]
.RB [ \-w
.IR bindpw ]
+.I distinguished-name
.SH INTRODUCTION
RFC 5716 introduces the Federated File System (FedFS, for short).
FedFS is an extensible standardized mechanism
@@ -64,45 +63,65 @@ about file sets contained in a FedFS domain name space.
.SH DESCRIPTION
The
.BR nsdb-describe (8)
-command is part of a collection of low-level single-use programs that are
-intended for testing the NSDB protocol or for use in scripts.
-It allows FedFS administrators to update the fedfsDescr
-attribute of entries stored on an NSDB.
+command is part of a collection of low-level single-use programs
+that is intended for testing the NSDB protocol or for use in scripts.
+It allows FedFS administrators to update the
+.B fedfsDescr
+attribute of FedFS records stored on an NSDB.
.P
-An entry's fedfsDescr attribute is multi-valued.
-Each value of this attribute is an unstructured string.
-Each value can contain any valid UTF-8 character.
-The whole string has no meaning to FedFS and is ignored.
+This command has one positional parameter which specifies the
+LDAP distinguished name of the FedFS record to be modified.
+All FedFS object classes may have a
+.B fedfsDescr
+attribute, thus a fully qualified distinguished name, rather than, say,
+an FSN UUID by itself, must be specified.
+.P
+The
+.B fedfsDescr
+attribute is multi-valued.
+Each attribute value is an unstructured string.
+These strings may contain any valid UTF-8 character.
.P
-This allows human-readable descriptions of an entry to be stored without
-requiring changes to the NSDB's FedFS schema.
The
.BR nsdb-describe (8)
-command can insert new values or delete or replace old ones.
+command inserts new values or deletes or replaces existing ones
+while maintaining the correct structure of the
+.B fedfsDescr
+attribute.
+.P
+Each value of the
+.B fedfsDescr
+attribute has no meaning to FedFS and is ignored.
+Adding a description allows
+free-form documentation of a FedFS record to be stored with it
+without requiring changes to the NSDB's FedFS schema.
.SH OPTIONS
.IP "\fB\-a, \-\-description=\fIdescription-text\fP"
-Specifies a fedfsDescr value.
-The form of the value is not checked by the
+Specifies a single
+.B fedfsDescr
+string to be added to or deleted from the attribute's value.
+The form of the string is not checked by the
.BR
nsdb-describe (8)
command.
If the
-.B -y
-option is specified and this value exists in the target
-entry's fedfsDescr attribute, it is removed.
+.B \-\-delete
+option is specified and this string exists as a value of the target record's
+.B fedfsDescr
+attribute, it is removed.
Otherwise the value is added.
.IP "\fB\-d, \-\-debug"
-Specifies that debugging messages be produced during operation.
+Enables debugging messages during operation.
.IP "\fB\-?, \-\-help"
-Prints an
+Displays
.BR nsdb-describe (8)
-version and usage message on
-.IR stderr ,
-then exits.
+version information and a usage message on
+.IR stderr .
.IP "\fB-D, \-\-binddn=\fIbind-distinguished-name\fP"
-Specifies a distinguished name of an entity used to bind to this LDAP server.
+Specifies a distinguished name of an entity used to bind to the LDAP server
+where the NSDB resides.
If the
-.B -D
+.B \-\-binddn
option is not specified,
the value of the FEDFS_NSDB_ADMIN environment variable is consulted.
If this variable is not set,
@@ -112,42 +131,33 @@ if this entity does not have permission to modify this area
of the server's DIT, the
.BR nsdb-describe (8)
command fails.
-.IP "\fB-e, \-\-entry=\fIdistinguished-name\fP"
-Specifies the distinguished name of the target entry
-in the NSDB to modify.
-Since any FedFS entry can have a fedfsDescr attribute,
-a full distinguished name must be specified.
-If the
-.B -e
-option is not specified,
-.BR nsdb-describe (8)
-command fails.
.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP"
-Specifies the hostname of the NSDB where the target entry resides.
+Specifies the hostname of the NSDB where the target record resides.
If the
-.B -l
+.B \-\-nsdbname
option is not specified,
the value of the FEDFS_NSDB_HOST environment variable is consulted.
If the variable is not set and the
-.B -l
+.B \-\-nsdbname
option is not specified, the
.BR nsdb-describe (8)
command fails.
.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP"
-Specifies the IP port of the NSDB where the target entry resides.
+Specifies the IP port of the NSDB where the target record resides.
If the
-.B -r
+.B \-\-nsdbport
option is not specified,
the value of the FEDFS_NSDB_PORT environment variable is consulted.
The default value if the variable is not set is 389.
.IP "\fB\-w, \-\-bindpw=\fIbinddn-password\fP"
-Specifies the password used for simple authentication to this LDAP server.
+Specifies the password used for simple authentication to the LDAP server
+where the NSDB resides.
If the
-.B -w
+.B \-\-bindpw
option is not specified,
the value of the FEDFS_NSDB_PASSWD environment variable is consulted.
If the variable is not set and the
-.B -w
+.B \-\-bindpw
option is not specified, the
.BR nsdb-describe (8)
command asks for a password on
@@ -155,8 +165,7 @@ command asks for a password on
Standard password blanking techniques are used
to obscure the password on the user's terminal.
.IP "\fB\-y, \-\-delete\fP"
-Specifies that the specified fedfsDescr value is deleted
-rather than added.
+Specifies that the specified value string is deleted rather than added.
.SH EXIT CODES
The NSDB returns a value that reflects the success of the requested operation.
.TP
@@ -259,18 +268,18 @@ connection parameters for the NSDB targeted by the LDAP referral.
.SH EXAMPLES
Suppose you are the FedFS administrator of the
.I example.net
-FedFS domain and that you want to modify the entry for
+FedFS domain, and you want to modify the record for
FSN UUID dc25a644-06e4-11e0-ae55-000c29dc7f8a on
-the LDAP server
-.IR ldap.example.net .
+the NSDB
+.IR nsdb.example.net .
You might use:
.RS
.sp
-$ nsdb-describe -l ldap.example.net \\
+$ nsdb-describe -l nsdb.example.net \\
.br
-a "Hello, world\\!" -D cn=Manager \\
.br
- -e fedfsFsnUuid=dc25a644-06e4-\\
+ fedfsFsnUuid=dc25a644-06e4-\\
.br
11e0-ae55-000c29dc7f8a,o=fedfs
.br
@@ -284,7 +293,7 @@ Successfully updated description value for
To see the new description, use
.BR nsdb-resolve-fsn (8).
.SH SECURITY
-Modify access to the LDAP's DIT is required to update an LDAP entry.
+Permission to modify the LDAP's DIT is required to update an LDAP entry.
The
.BR nsdb-describe (8)
command must bind as an entity permitted to modify the DIT
@@ -48,7 +48,7 @@
/**
* Short form command line options
*/
-static const char nsdb_annotate_opts[] = "?adD:e:k:l:r:v:w:y";
+static const char nsdb_annotate_opts[] = "?adD:k:l:r:v:w:y";
/**
* Long form command line options
@@ -58,7 +58,6 @@ static const struct option nsdb_annotate_longopts[] = {
{ "binddn", 1, NULL, 'D', },
{ "debug", 0, NULL, 'd', },
{ "delete", 0, NULL, 'y', },
- { "entry", 1, NULL, 'e', },
{ "help", 0, NULL, '?', },
{ "keyword", 1, NULL, 'k', },
{ "nsdbname", 1, NULL, 'l', },
@@ -78,15 +77,15 @@ nsdb_annotate_usage(const char *progname)
{
fprintf(stderr, "\n%s version " VERSION "\n", progname);
fprintf(stderr, "Usage: %s [ -d ] [ -D binddn ] [ -w bindpw ] "
- "[ -l nsdbname ] [ -r nsdbport ] -e entry "
- "[ -a annotation ] [ -k keyword ] [ -v value ] [ -y ]\n\n",
+ "[ -l nsdbname ] [ -r nsdbport ] [ -a annotation ] "
+ "[ -k keyword ] [ -v value ] [ -y ] "
+ "distinguished-name\n\n",
progname);
fprintf(stderr, "\t-?, --help Print this help\n");
fprintf(stderr, "\t-a, --annotation Full annotation\n");
fprintf(stderr, "\t-d, --debug Enable debug messages\n");
fprintf(stderr, "\t-D, --binddn Bind DN\n");
- fprintf(stderr, "\t-e, --entry DN of entry to update\n");
fprintf(stderr, "\t-k, --keyword Annotation keyword\n");
fprintf(stderr, "\t-l, --nsdbname NSDB hostname\n");
fprintf(stderr, "\t-r, --nsdbport NSDB port\n");
@@ -154,9 +153,6 @@ main(int argc, char **argv)
case 'D':
binddn = optarg;
break;
- case 'e':
- entry = optarg;
- break;
case 'k':
keyword = optarg;
break;
@@ -188,12 +184,17 @@ main(int argc, char **argv)
nsdb_annotate_usage(progname);
}
}
- if (optind != argc) {
- fprintf(stderr, "Unrecognized command line argument\n");
+ if (argc == optind + 1)
+ entry = argv[optind];
+ else if (argc > optind + 1) {
+ fprintf(stderr, "Unrecognized positional parameters\n");
+ nsdb_annotate_usage(progname);
+ } else {
+ fprintf(stderr, "No distinguished name was specified\n");
nsdb_annotate_usage(progname);
}
- if (nsdbname == NULL || entry == NULL) {
- fprintf(stderr, "Missing required command line argument\n");
+ if (nsdbname == NULL) {
+ fprintf(stderr, "No NSDB hostname was specified\n");
nsdb_annotate_usage(progname);
}
@@ -245,9 +246,13 @@ main(int argc, char **argv)
nsdb_display_fedfsstatus(retval));
goto out;
}
-
if (binddn == NULL)
binddn = (char *)nsdb_default_binddn(host);
+ if (binddn == NULL) {
+ fprintf(stderr, "No NDSB bind DN was specified\n");
+ goto out_free;
+ }
+
retval = nsdb_open_nsdb(host, binddn, bindpw, &ldap_err);
switch (retval) {
case FEDFS_OK:
@@ -48,7 +48,7 @@
/**
* Short form command line options
*/
-static const char nsdb_describe_opts[] = "?a:dD:e:l:r:w:y";
+static const char nsdb_describe_opts[] = "?a:dD:l:r:w:y";
/**
* Long form command line options
@@ -58,7 +58,6 @@ static const struct option nsdb_describe_longopts[] = {
{ "debug", 0, NULL, 'd', },
{ "delete", 0, NULL, 'y', },
{ "description", 1, NULL, 'a', },
- { "entry", 1, NULL, 'e', },
{ "help", 0, NULL, '?', },
{ "nsdbname", 1, NULL, 'l', },
{ "nsdbport", 1, NULL, 'r', },
@@ -75,16 +74,15 @@ static void
nsdb_describe_usage(const char *progname)
{
fprintf(stderr, "\n%s version " VERSION "\n", progname);
- fprintf(stderr, "Usage: %s [ -b ] [ -D binddn ] [ -w bindpw ] "
- "[ -l nsdbname ] [ -r nsdbport ] -e entry "
- "[ -a description] [-y]\n\n",
+ fprintf(stderr, "Usage: %s [ -d ] [ -D binddn ] [ -w bindpw ] "
+ "[ -l nsdbname ] [ -r nsdbport ] [ -a description] "
+ "distinguished-name [-y]\n\n",
progname);
fprintf(stderr, "\t-?, --help Print this help\n");
fprintf(stderr, "\t-a, --description Description value to modify\n");
fprintf(stderr, "\t-d, --debug Enable debug messages\n");
fprintf(stderr, "\t-D, --binddn Bind DN\n");
- fprintf(stderr, "\t-e, --entry DN of entry to update\n");
fprintf(stderr, "\t-l, --nsdbname NSDB hostname\n");
fprintf(stderr, "\t-r, --nsdbport NSDB port\n");
fprintf(stderr, "\t-w, --bindpw Bind password\n");
@@ -150,9 +148,6 @@ main(int argc, char **argv)
case 'D':
binddn = optarg;
break;
- case 'e':
- entry = optarg;
- break;
case 'l':
nsdbname = optarg;
break;
@@ -176,16 +171,21 @@ main(int argc, char **argv)
nsdb_describe_usage(progname);
}
}
- if (optind != argc) {
- fprintf(stderr, "Unrecognized command line argument\n");
+ if (argc == optind + 1)
+ entry = argv[optind];
+ else if (argc > optind + 1) {
+ fprintf(stderr, "Unrecognized positional parameters\n");
+ nsdb_describe_usage(progname);
+ } else {
+ fprintf(stderr, "No distinguished name was specified\n");
nsdb_describe_usage(progname);
}
- if (nsdbname == NULL || entry == NULL) {
- fprintf(stderr, "Missing required command line argument\n");
+ if (nsdbname == NULL) {
+ fprintf(stderr, "No NSDB hostname was specified\n");
nsdb_describe_usage(progname);
}
if (description == NULL && !delete) {
- fprintf(stderr, "Missing description\n");
+ fprintf(stderr, "No description was specified\n");
nsdb_describe_usage(progname);
}
@@ -203,9 +203,13 @@ main(int argc, char **argv)
nsdb_display_fedfsstatus(retval));
goto out;
}
-
if (binddn == NULL)
binddn = (char *)nsdb_default_binddn(host);
+ if (binddn == NULL) {
+ fprintf(stderr, "No NDSB bind DN was specified\n");
+ goto out_free;
+ }
+
retval = nsdb_open_nsdb(host, binddn, bindpw, &ldap_err);
switch (retval) {
case FEDFS_OK:
We're trying to keep the Solaris and Linux administrative interfaces roughly the same, to make it easy for admins to use either one without separate learning curves. Rob Thurlow mentions that Solaris user interface guidelines require that mandatory command line options must be specified as positional parameters rather than by using dash switches. The only reason I used dash switches for all the options was sheer laziness. This commit updates nsdb-annotate and nsdb-describe. Signed-off-by: Chuck Lever <chuck.lever@oracle.com> --- doc/man/nsdb-annotate.8 | 171 ++++++++++++++++++++++++++------------------- doc/man/nsdb-describe.8 | 113 ++++++++++++++++-------------- src/nsdbc/nsdb-annotate.c | 31 +++++--- src/nsdbc/nsdb-describe.c | 34 +++++---- 4 files changed, 198 insertions(+), 151 deletions(-)