Patchwork [8/9] fedfsc: Specify manadatory arguments as positional parameters (fedfs-*-replication)

login
register
mail settings
Submitter Chuck Lever
Date Nov. 28, 2011, 5:34 p.m.
Message ID <20111128173416.1136.95952.stgit@degas.1015granger.net>
Download mbox | patch
Permalink /patch/128030/
State Accepted
Headers show

Comments

Chuck Lever - Nov. 28, 2011, 5:34 p.m.
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 the FedFS ADMIN client tools that are concerned
with remote replication management.

Signed-off-by: Chuck Lever <chuck.lever@oracle.com>
---

 doc/man/fedfs-create-replication.8    |   49 ++++++++++++-----------
 doc/man/fedfs-delete-replication.8    |   32 ++++++++-------
 doc/man/fedfs-lookup-replication.8    |   69 ++++++++++++++++++---------------
 src/fedfsc/fedfs-create-replication.c |   27 +++++--------
 src/fedfsc/fedfs-delete-replication.c |   18 ++++-----
 src/fedfsc/fedfs-lookup-replication.c |   17 ++++----
 6 files changed, 104 insertions(+), 108 deletions(-)

Patch

diff --git a/doc/man/fedfs-create-replication.8 b/doc/man/fedfs-create-replication.8
index 464756e..781ab91 100644
--- a/doc/man/fedfs-create-replication.8
+++ b/doc/man/fedfs-create-replication.8
@@ -33,12 +33,12 @@  fedfs-create-replication \- send a FEDFS_CREATE_REPLICATION ADMIN protocol reque
 .IR nettype ]
 .RB [ \-h
 .IR hostname ]
-.BI "-p " path
-.BI "-u " fsn-uuid
 .RB [ \-l
 .IR nsdbname ]
 .RB [ \-r
 .IR nsdbport ]
+.I path
+.I uuid
 .SH INTRODUCTION
 RFC 5716 introduces the Federated File System (FedFS, for short).
 FedFS is an extensible standardized mechanism
@@ -57,28 +57,33 @@  on remote FedFS-enabled file servers.
 .SH DESCRIPTION
 The
 .BR fedfs-create-replication (8)
-command is part of a collection of low-level single-use programs that are
-intended for testing the FedFS ADMIN protocol or for use in scripts.
+command is part of a collection of low-level single-use programs
+that is intended for testing the FedFS ADMIN protocol or for use in scripts.
 It sends a single FEDFS_CREATE_REPLICATION request to a remote
 FedFS ADMIN protocol service.
 .P
-This request creates a FedFS replication in the local file system
-on a remote file server.
-The contents of a FedFS replication are a UUID and an NSDB name and port,
-which are specified on the command line.
+The FEDFS_CREATE_REPLICATION request creates a replication marker
+in a local file system on a remote file server.
+The contents of a replication marker are an UUID and an NSDB name and port.
+.P
+The
+.BR fedfs-create-replication (8)
+command takes two positional parameters which specify
+the pathname on the remote server of the replication, and an UUID.
+This pathname is relative to the roo
+of the local file system on the remote server.
+Required NSDB information can be inferred
+from the command's environment or specified on the command line.
 The meaning of these arguments is described in more detail in
 .BR fedfs (7).
 .SH OPTIONS
 .IP "\fB\-d, \-\-debug"
-Specifies that debugging messages be produced during operation.
-.IP "\fB\-u, \-\-fsnuuid=\fIuuid\fP"
-Specifies the FSN UUID to insert into the new FedFS replication.
+Enables debugging messages during operation.
 .IP "\fB\-?, \-\-help"
-Prints a
+Displays
 .BR fedfs-create-replication (8)
-version and usage message on
-.IR stderr ,
-then exits.
+version information and a usage message on
+.IR stderr .
 .IP "\fB\-h, \-\-hostname=\fIhostname\fP"
 Specifies the hostname of a remote FedFS ADMIN service.
 If this option is not specified, the default value is
@@ -101,7 +106,7 @@  Specifies the hostname of the NSDB to insert into the new FedFS replication.
 If this 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 fedfs-create-replication (8)
 command fails.
@@ -110,11 +115,6 @@  Specifies the IP port of the NSDB to insert into the new FedFS replication.
 If this 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\-p, \-\-path=\fIpathname\fP"
-Specifies the location on the remote server where the new FedFS replication
-should be created.
-This pathname is relative to the remote server's physical root directory,
-not the remote server's NFS pseudoroot.
 .SH EXIT CODES
 The remote administration service returns a value that reflects the
 success of the requested operation.
@@ -191,15 +191,16 @@  Suppose you are the FedFS administrator of the
 .I example.net
 FedFS domain and that your domain's NSDB hostname is
 .IR nsdb.example.net .
-To create a new FedFS replication on the remote server
+To create a new FedFS replication on the file server
 .IR fs.example.net ,
 use:
 .RS
 .sp
-$ fedfs-create-replication -h fs.example.net -l nsdb.example.net `uuidgen -t` -p /export/replication1
+$ fedfs-create-replication -h fs.example.net -l nsdb.example.net \\
+	/export/replication1 `uuidgen -t`
 .sp
 .RE
-In this example, a new FSN UUID is created on the spot.
+In this example, a new UUID is created on the spot.
 It can be read back from the server using the
 .BR fedfs-lookup-replication (8)
 command.
diff --git a/doc/man/fedfs-delete-replication.8 b/doc/man/fedfs-delete-replication.8
index c083b70..a8efc0b 100644
--- a/doc/man/fedfs-delete-replication.8
+++ b/doc/man/fedfs-delete-replication.8
@@ -33,7 +33,7 @@  fedfs-delete-replication \- send a FEDFS_DELETE_REPLICATION ADMIN protocol reque
 .IR nettype ]
 .RB [ \-h
 .IR hostname ]
-.BI "-p " path
+.I path
 .SH INTRODUCTION
 RFC 5716 introduces the Federated File System (FedFS, for short).
 FedFS is an extensible standardized mechanism
@@ -52,22 +52,27 @@  on remote FedFS-enabled file servers.
 .SH DESCRIPTION
 The
 .BR fedfs-delete-replication (8)
-command is part of a collection of low-level single-use programs that are
-intended for testing the FedFS ADMIN protocol or for use in scripts.
+command is part of a collection of low-level single-use programs
+that is intended for testing the FedFS ADMIN protocol or for use in scripts.
 It sends a single FEDFS_DELETE_REPLICATION request to a remote
 FedFS ADMIN protocol service.
 .P
-This request deletes a FedFS replication in the local file system
-on a remote file server.
+The FEDFS_DELETE_REPLICATION request deletes a replication marker
+in a local file system on a remote file server.
+The
+.BR fedfs-delete-replication (8)
+command taks a single positional parameter which is the
+pathname on the remote server of the replication marker to be deleted.
+This pathname is relative to the root
+of the local file system on the remote server.
 .SH OPTIONS
 .IP "\fB\-d, \-\-debug"
-Specifies that debugging messages be produced during operation.
+Enables debugging messages during operation.
 .IP "\fB\-?, \-\-help"
-Prints a
+Displays
 .BR fedfs-delete-replication (8)
-version and usage message on
-.IR stderr ,
-then exits.
+version information and a usage message on
+.IR stderr .
 .IP "\fB\-h, \-\-hostname=\fIhostname\fP"
 Specifies the hostname of a remote FedFS ADMIN service.
 If this option is not specified, the default value is
@@ -85,11 +90,6 @@  If this option is not specified, the default value is
 See
 .BR rpc (3t)
 for details.
-.IP "\fB\-p, \-\-path=\fIpathname\fP"
-Specifies the location on the remote server where the doomed FedFS replication
-resides.
-This pathname is relative to the remote server's physical root directory,
-not the remote server's NFS pseudoroot.
 .SH EXIT CODES
 The remote administration service returns a value that reflects the
 success of the requested operation.
@@ -163,7 +163,7 @@  To delete an existing FedFS replication on the remote server
 use:
 .RS
 .sp
-$ fedfs-delete-replication -h fs.example.net -p /export/replication1
+$ fedfs-delete-replication -h fs.example.net /export/replication1
 .SH SECURITY
 RPCSEC GSSAPI authentication has not yet been implemented for this command.
 .SH "SEE ALSO"
diff --git a/doc/man/fedfs-lookup-replication.8 b/doc/man/fedfs-lookup-replication.8
index 3fc7d8b..6e60a2e 100644
--- a/doc/man/fedfs-lookup-replication.8
+++ b/doc/man/fedfs-lookup-replication.8
@@ -35,7 +35,7 @@  fedfs-lookup-replication \- send a FEDFS_LOOKUP_REPLICATION ADMIN protocol reque
 .IR hostname ]
 .RB [ \-t
 .IR resolvetype ]
-.BI "-p " path
+.I path
 .SH INTRODUCTION
 RFC 5716 introduces the Federated File System (FedFS, for short).
 FedFS is an extensible standardized mechanism
@@ -54,52 +54,57 @@  on remote FedFS-enabled file servers.
 .SH DESCRIPTION
 The
 .BR fedfs-lookup-replication (8)
-command is part of a collection of low-level single-use programs that are
-intended for testing the FedFS ADMIN protocol or for use in scripts.
+command is part of a collection of low-level single-use programs
+that is intended for testing the FedFS ADMIN protocol or for use in scripts.
 It sends a single FEDFS_LOOKUP_REPLICATION request to a remote
 FedFS ADMIN protocol service.
 .P
-This request causes a remote server to report FedFS replication resolution
-results as the remote server sees them.
-It can report cached results or can force a fresh replication resolution if,
-for example, the contents of an NSDB are known to have changed.
-These capabilities are especially useful for tracking down
-configuration problems in a FedFS domain.
+The FEDFS_LOOKUP_REPLICATION request causes a remote server
+to reveal the contents of a replication marker,
+or to report cached or immediate NSDB lookup results as that server sees them.
+The
+.BR fedfs-lookup-replication (8)
+command takes a single positional parameter which is the
+pathname on the remote server of the junction to be looked up.
+The pathname is relative to the root
+of the local file system on the remote server.
 .P
-The contents of a FedFS replication are a UUID and an NSDB name and port.
+Resolving a junction means performing an NSDB query with the contents
+of the junction to obtain a list of fileset locations, or FSLs,
+matching the stored UUID.
 The meaning of these is described in more detail in
 .BR fedfs (7).
-Resolving a replication means performing an NSDB query with the contents
-of the replication to obtain the list of fileset locations matching the FSN UUID.
 .P
-There are three distinct types of replication resolution:
+There are three distinct types of replication lookup:
 .TP
 .B none
 The remote server reports the actual contents of the replication stored
 on its local disk.
-This includes an FSN UUID and the name and port of an NSDB.
+This includes a UUID and the name and port of an NSDB.
+If the
+.B \-t
+option is not specified, this type of lookup is performed.
 .TP
 .B cache
-The remote server reports resolution results it may have cached from
-previous NSDB resolution requests.
-This includes an FSN UUID, the name and port of an NSDB, and the cached
-list of fileset locations matching the FSN UUID.
+The remote server reports lookup results it may have cached from
+previous replication lookup requests.
+This includes a UUID, the name and port of an NSDB, and the cached
+list of fileset locations matching the UUID in the replication marker.
 Not all FedFS ADMIN service implementations support this type of request.
 .TP
 .B nsdb
-The remote server performs a fresh replication resolution,
+The remote server performs a fresh replication lookup,
 and the results are returned.
-This includes an FSN UUID, the name and port of an NSDB,
-and a list of fileset locations matching the FSN UUID.
+This includes an UUID, the name and port of an NSDB,
+and a list of fileset locations matching the UUID in the replication marker.
 .SH OPTIONS
 .IP "\fB\-d, \-\-debug"
-Specifies that debugging messages be produced during operation.
+Enables debugging messages during operation.
 .IP "\fB\-?, \-\-help"
-Prints a
+Displays
 .BR fedfs-lookup-replication (8)
-version and usage message on
-.IR stderr ,
-then exits.
+version information and a usage message on
+.IR stderr .
 .IP "\fB\-h, \-\-hostname=\fIhostname\fP"
 Specifies the hostname of a remote FedFS ADMIN service.
 If this option is not specified, the default value is
@@ -269,12 +274,12 @@  Suppose you are the FedFS administrator of the
 .I example.net
 FedFS domain and that your domain's NSDB hostname is
 .IR nsdb.example.net .
-You have created a FedFS replication on remote server
+You have created a FedFS replication on file server
 .IR fs.example.net .
 To see how the replication appears on the remote server, use:
 .RS
 .sp
-$ fedfs-lookup-replication -h fs.example.net -p /export/replication1 -t none
+$ fedfs-lookup-replication -h fs.example.net /export/replication1
 .br
 Call completed successfully
 .br
@@ -286,15 +291,15 @@  NSDB: nsdb.example.net:389
 To see real-time replication resolution results as the remote server sees them, use:
 .RS
 .sp
-$ fedfs-lookup-replication -h fs.example.net -p /export/replication1 -t nsdb
+$ fedfs-lookup-replication -h fs.example.net -t nsdb /export/replication1
 .br
 Server returned FEDFS_ERR_NSDB_NOFSN
 .sp
 .RE
-In this example, the replication exists on the remote server,
+In this example, the replication marker exists on the file server,
 but the domain's NSDB has not yet been updated to contain a list of
-fileset locations for the FSN contained in the replication.
-The remote server is therefore not able to resolve the replication.
+fileset locations for the UUID contained in the replication marker.
+The file server is therefore not able to resolve the replication.
 .SH SECURITY
 RPCSEC GSSAPI authentication has not yet been implemented for this command.
 .SH "SEE ALSO"
diff --git a/src/fedfsc/fedfs-create-replication.c b/src/fedfsc/fedfs-create-replication.c
index dc9950e..4aaea98 100644
--- a/src/fedfsc/fedfs-create-replication.c
+++ b/src/fedfsc/fedfs-create-replication.c
@@ -52,7 +52,7 @@  static struct timeval fedfs_create_replication_timeout = { 25, 0 };
 /**
  * Short form command line options
  */
-static const char fedfs_create_replication_opts[] = "?dh:l:n:p:r:u:";
+static const char fedfs_create_replication_opts[] = "?dh:l:n:r:";
 
 /**
  * Long form command line options
@@ -63,9 +63,7 @@  static const struct option fedfs_create_replication_longopts[] = {
 	{ "hostname", 1, NULL, 'h', },
 	{ "nsdbname", 1, NULL, 'l', },
 	{ "nettype", 1, NULL, 'n', },
-	{ "path", 1, NULL, 'p', },
 	{ "nsdbport", 1, NULL, 'r', },
-	{ "fsnuuid", 1, NULL, 'u', },
 	{ NULL, 0, NULL, 0, },
 };
 
@@ -74,15 +72,14 @@  fedfs_create_replication_usage(const char *progname)
 {
 	fprintf(stderr, "\n%s version " VERSION "\n", progname);
 	fprintf(stderr, "Usage: %s [-d] [-n nettype] [-h hostname] "
-			"-p path -u fsn-uuid [-l nsdbname] [-r nsdbport]\n\n",
+			"[-l nsdbname] [-r nsdbport] "
+			"path uuid\n\n",
 			progname);
 
 	fprintf(stderr, "\t-?, --help           Print this help\n");
 	fprintf(stderr, "\t-d, --debug          Enable debug messages\n");
 	fprintf(stderr, "\t-n, --nettype        RPC transport (default: 'netpath')\n");
 	fprintf(stderr, "\t-h, --hostname       ADMIN server hostname (default: 'localhost')\n");
-	fprintf(stderr, "\t-p, --path           Pathname of new junction\n");
-	fprintf(stderr, "\t-u, --fsnuuid        FSN UUID to set\n");
 	fprintf(stderr, "\t-l, --nsdbname       NSDB hostname to set\n");
 	fprintf(stderr, "\t-r, --nsdbport       NSDB port to set\n");
 
@@ -178,7 +175,6 @@  main(int argc, char **argv)
 
 	hostname = "localhost";
 	nettype = "netpath";
-	uuid = path = NULL;
 	while ((arg = getopt_long(argc, argv, fedfs_create_replication_opts,
 			fedfs_create_replication_longopts, NULL)) != -1) {
 		switch (arg) {
@@ -199,9 +195,6 @@  main(int argc, char **argv)
 		case 'n':
 			nettype = optarg;
 			break;
-		case 'p':
-			path = optarg;
-			break;
 		case 'r':
 			if (!nsdb_parse_port_string(optarg, &nsdbport)) {
 				fprintf(stderr, "Bad port number: %s\n",
@@ -209,9 +202,6 @@  main(int argc, char **argv)
 				fedfs_create_replication_usage(progname);
 			}
 			break;
-		case 'u':
-			uuid = optarg;
-			break;
 		default:
 			fprintf(stderr, "Invalid command line "
 				"argument: %c\n", (char)arg);
@@ -219,12 +209,15 @@  main(int argc, char **argv)
 			fedfs_create_replication_usage(progname);
 		}
 	}
-	if (optind != argc) {
-		fprintf(stderr, "Unrecognized command line argument\n");
+	if (argc == optind + 2) {
+		path = argv[optind];
+		uuid = argv[optind + 1];
+	} else {
+		fprintf(stderr, "Ambiguous positional parameters\n");
 		fedfs_create_replication_usage(progname);
 	}
-	if (path == NULL || uuid == NULL || nsdbname == NULL) {
-		fprintf(stderr, "Missing required command line argument\n");
+	if (nsdbname == NULL) {
+		fprintf(stderr, "No NSDB hostname was specified\n");
 		fedfs_create_replication_usage(progname);
 	}
 
diff --git a/src/fedfsc/fedfs-delete-replication.c b/src/fedfsc/fedfs-delete-replication.c
index d497aa7..052ca45 100644
--- a/src/fedfsc/fedfs-delete-replication.c
+++ b/src/fedfsc/fedfs-delete-replication.c
@@ -51,7 +51,7 @@  static struct timeval fedfs_delete_replication_timeout = { 25, 0 };
 /**
  * Short form command line options
  */
-static const char fedfs_delete_replication_opts[] = "?dh:n:p:";
+static const char fedfs_delete_replication_opts[] = "?dh:n:";
 
 /**
  * Long form command line options
@@ -61,7 +61,6 @@  static const struct option fedfs_delete_replication_longopts[] = {
 	{ "help", 0, NULL, '?', },
 	{ "hostname", 1, NULL, 'h', },
 	{ "nettype", 1, NULL, 'n', },
-	{ "path", 1, NULL, 'p', },
 	{ NULL, 0, NULL, 0, },
 };
 
@@ -70,13 +69,12 @@  fedfs_delete_replication_usage(const char *progname)
 {
 	fprintf(stderr, "\n%s version " VERSION "\n", progname);
 	fprintf(stderr, "Usage: %s [-d] [-n nettype] [-h hostname] "
-			"-p path\n\n", progname);
+			"path\n\n", progname);
 
 	fprintf(stderr, "\t-?, --help           Print this help\n");
 	fprintf(stderr, "\t-d, --debug          Enable debug messages\n");
 	fprintf(stderr, "\t-n, --nettype        RPC transport (default: 'netpath')\n");
 	fprintf(stderr, "\t-h, --hostname       ADMIN server hostname (default: 'localhost')\n");
-	fprintf(stderr, "\t-p, --path           Pathname of replication to delete\n");
 
 	fprintf(stderr, "%s", fedfs_gpl_boilerplate);
 
@@ -150,7 +148,6 @@  main(int argc, char **argv)
 
 	hostname = "localhost";
 	nettype = "netpath";
-	path = NULL;
 	while ((arg = getopt_long(argc, argv, fedfs_delete_replication_opts, fedfs_delete_replication_longopts, NULL)) != -1) {
 		switch (arg) {
 		case 'd':
@@ -168,12 +165,13 @@  main(int argc, char **argv)
 			fedfs_delete_replication_usage(progname);
 		}
 	}
-	if (optind != argc) {
-		fprintf(stderr, "Unrecognized command line argument\n");
+	if (argc == optind + 1)
+		path = argv[optind];
+	else if (argc > optind + 1) {
+		fprintf(stderr, "Unrecognized positional parameters\n");
 		fedfs_delete_replication_usage(progname);
-	}
-	if (path == NULL) {
-		fprintf(stderr, "Missing required command line argument\n");
+	} else {
+		fprintf(stderr, "No replication pathname was specified\n");
 		fedfs_delete_replication_usage(progname);
 	}
 
diff --git a/src/fedfsc/fedfs-lookup-replication.c b/src/fedfsc/fedfs-lookup-replication.c
index c0cd64d..19a6b09 100644
--- a/src/fedfsc/fedfs-lookup-replication.c
+++ b/src/fedfsc/fedfs-lookup-replication.c
@@ -53,7 +53,7 @@  static struct timeval fedfs_lookup_replication_timeout = { 25, 0 };
 /**
  * Short form command line options
  */
-static const char fedfs_lookup_replication_opts[] = "?dh:n:p:t:";
+static const char fedfs_lookup_replication_opts[] = "?dh:n:t:";
 
 /**
  * Long form command line options
@@ -63,7 +63,6 @@  static const struct option fedfs_lookup_replication_longopts[] = {
 	{ "help", 0, NULL, '?', },
 	{ "hostname", 1, NULL, 'h', },
 	{ "nettype", 1, NULL, 'n', },
-	{ "path", 1, NULL, 'p', },
 	{ "resolvetype", 1, NULL, 't', },
 	{ NULL, 0, NULL, 0, },
 };
@@ -73,13 +72,12 @@  fedfs_lookup_replication_usage(const char *progname)
 {
 	fprintf(stderr, "\n%s version " VERSION "\n", progname);
 	fprintf(stderr, "Usage: %s [-d] [-n nettype] [-h hostname] "
-			"[-t <none|cache|nsdb>] -p path\n\n", progname);
+			"[-t <none|cache|nsdb>] path\n\n", progname);
 
 	fprintf(stderr, "\t-?, --help           Print this help\n");
 	fprintf(stderr, "\t-d, --debug          Enable debug messages\n");
 	fprintf(stderr, "\t-n, --nettype        RPC transport (default: 'netpath')\n");
 	fprintf(stderr, "\t-h, --hostname       ADMIN server hostname (default: 'localhost')\n");
-	fprintf(stderr, "\t-p, --path           Pathname of replication to resolve\n");
 	fprintf(stderr, "\t-t, --resolvetype    Type of desired result (default: 'none')\n");
 
 	fprintf(stderr, "%s", fedfs_gpl_boilerplate);
@@ -319,12 +317,13 @@  main(int argc, char **argv)
 			fedfs_lookup_replication_usage(progname);
 		}
 	}
-	if (optind != argc) {
-		fprintf(stderr, "Unrecognized command line argument\n");
+	if (argc == optind + 1)
+		path = argv[optind];
+	else if (argc > optind + 1) {
+		fprintf(stderr, "Unrecognized positional parameters\n");
 		fedfs_lookup_replication_usage(progname);
-	}
-	if (path == NULL) {
-		fprintf(stderr, "Missing required command line argument\n");
+	} else {
+		fprintf(stderr, "No replication pathname was specified\n");
 		fedfs_lookup_replication_usage(progname);
 	}