@@ -33,12 +33,12 @@ fedfs-create-junction \- send a FEDFS_CREATE_JUNCTION ADMIN protocol request
.IR nettype ]
.RB [ \-h
.IR hostname ]
-.BI "-p " path
-.BI "-u " fsn-uuid
.RB [ \-l
.IR nsdbname ]
.RB [ \-r
.IR nsdbport ]
+.I path
+.I fsn-uuid
.SH INTRODUCTION
RFC 5716 introduces the Federated File System (FedFS, for short).
FedFS is an extensible standardized mechanism
@@ -57,28 +57,40 @@ on remote FedFS-enabled file servers.
.SH DESCRIPTION
The
.BR fedfs-create-junction (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_JUNCTION request to a remote
FedFS ADMIN protocol service.
.P
-This request creates a FedFS junction in the local file system
-on a remote file server.
-The contents of a FedFS junction are a UUID and an NSDB name and port,
-which are specified on the command line.
+The FEDFS_CREATE_JUNCTION request creates a FedFS junction
+in a local file system on a remote file server.
+The contents of a FedFS junction are an FSN UUID and an NSDB name and port.
+.P
+The
+.BR fedfs-create-junction (8)
+command takes two positional parameters which specify
+the pathname on the remote server of the new junction, and the FSN UUID.
+This pathname is relative to the root
+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).
+.P
+The FEDFS_CREATE_JUNCTION request does not create an FSN record.
+To create an FSN record, use the
+.BR nsdb-create-fsn (8)
+command.
+Resolving a junction that contains an FSN UUID without
+a matching FSN record on the NSDB results in an error on the file server.
.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 junction.
+Enables debugging messages during operation.
.IP "\fB\-?, \-\-help"
-Prints a
+Displays
.BR fedfs-create-junction (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 +113,7 @@ Specifies the hostname of the NSDB to insert into the new FedFS junction.
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-junction (8)
command fails.
@@ -110,11 +122,6 @@ Specifies the IP port of the NSDB to insert into the new FedFS junction.
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 junction
-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,17 +198,20 @@ 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 junction on the remote server
+To create a new FedFS junction on the file server
.IR fs.example.net ,
use:
.RS
.sp
-$ fedfs-create-junction -h fs.example.net -l nsdb.example.net `uuidgen -t` -p /export/junction1
+$ fedfs-create-junction -h fs.example.net -l nsdb.example.net \\
+ /export/junction1 `uuidgen -t`
.sp
.RE
In this example, a new FSN UUID is created on the spot.
It can be read back from the remote server using the
.BR fedfs-lookup-junction (8)
+command, and added to the NSDB using the
+.BR nsdb-create-fsn (8)
command.
.SH SECURITY
RPCSEC GSSAPI authentication has not yet been implemented for this command.
@@ -209,6 +219,7 @@ RPCSEC GSSAPI authentication has not yet been implemented for this command.
.BR fedfs (7),
.BR rpc.fedfsd (8),
.BR fedfs-lookup-junction (8),
+.BR nsdb-create-fsn (8),
.BR rpc (3t)
.sp
RFC 5716 for FedFS requirements and overview
@@ -33,7 +33,7 @@ fedfs-delete-junction \- send a FEDFS_DELETE_JUNCTION ADMIN protocol request
.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,39 @@ on remote FedFS-enabled file servers.
.SH DESCRIPTION
The
.BR fedfs-delete-junction (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_JUNCTION request to a remote
FedFS ADMIN protocol service.
.P
-This request deletes a FedFS junction in the local file system
-on a remote file server.
+The FEDFS_DELETE_JUNCTION request deletes a FedFS junction
+in a local file system on a remote file server.
+The
+.BR fedfs-delete-junction (8)
+command takes a single positional parameter which is the
+pathname on the remote server of the junction to be deleted.
+This pathname is relative to the root
+of the local file system on the remote server.
+.P
+The FEDFS_DELETE_JUNCTION request does not remove the FSN record
+associated with the deleted junction.
+Other junctions may continue to refer to the FSN in the deleted junction.
+.P
+When no junction refers to this FSN, use the
+.BR nsdb-delete-fsn (8)
+command to delete the FSN and children FSL records.
+Resolving a junction that contains an FSN UUID
+without a matching FSN record on the NSDB
+results in an error on the file server.
+.P
.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-junction (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 +102,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 junction
-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.
@@ -158,12 +170,14 @@ The remote server does not support the specified procedure.
Suppose you are the FedFS administrator of the
.I example.net
FedFS domain.
-To delete an existing FedFS junction on the remote server
+To delete the existing FedFS junction
+.I /export/junction1
+on the file server
.IR fs.example.net ,
use:
.RS
.sp
-$ fedfs-delete-junction -h fs.example.net -p /export/junction1
+$ fedfs-delete-junction -h fs.example.net /export/junction1
.SH SECURITY
RPCSEC GSSAPI authentication has not yet been implemented for this command.
.SH "SEE ALSO"
@@ -35,7 +35,7 @@ fedfs-lookup-junction \- send a FEDFS_LOOKUP_JUNCTION ADMIN protocol request
.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,59 @@ on remote FedFS-enabled file servers.
.SH DESCRIPTION
The
.BR fedfs-lookup-junction (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_JUNCTION request to a remote
FedFS ADMIN protocol service.
.P
-This request causes a remote server to report FedFS junction resolution
-results as the remote server sees them.
-It can report cached results or can force a fresh junction 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_JUNCTION request causes a remote server
+to reveal the contents of a junction,
+or to report cached or immediate NSDB lookup results as that server sees them.
+The contents of a FedFS junction are an FSN UUID and an NSDB name and port.
.P
-The contents of a FedFS junction are a UUID and an NSDB name and port.
+The
+.BR fedfs-lookup-junction (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
+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 FSN UUID.
The meaning of these is described in more detail in
.BR fedfs (7).
-Resolving a junction means performing an NSDB query with the contents
-of the junction to obtain the list of fileset locations matching the FSN UUID.
.P
-There are three distinct types of junction resolution:
+There are three distinct types of junction lookup:
.TP
.B none
The remote server reports the actual contents of the junction stored
on its local disk.
This includes an FSN 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.
+The remote server reports lookup results it may have cached from
+previous junction lookup requests.
This includes an FSN UUID, the name and port of an NSDB, and the cached
-list of fileset locations matching the FSN UUID.
+list of fileset locations matching the FSN UUID in the junction.
Not all FedFS ADMIN service implementations support this type of request.
.TP
.B nsdb
-The remote server performs a fresh junction resolution,
+The remote server performs a fresh junction 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.
+and a list of fileset locations matching the FSN UUID in the junction.
.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-junction (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
@@ -271,10 +278,10 @@ FedFS domain and that your domain's NSDB hostname is
.IR nsdb.example.net .
You have created a FedFS junction on remote server
.IR fs.example.net .
-To see how the junction appears on the remote server, use:
+To see how the junction appears on the file server, use:
.RS
.sp
-$ fedfs-lookup-junction -h fs.example.net -p /export/junction1 -t none
+$ fedfs-lookup-junction -h fs.example.net /export/junction1
.br
Call completed successfully
.br
@@ -283,18 +290,18 @@ FSN UUID: 89c6d208-7280-11e0-9f1d-000c297fd679
NSDB: nsdb.example.net:389
.sp
.RE
-To see real-time junction resolution results as the remote server sees them, use:
+To see real-time junction lookup results as the remote server sees them, use:
.RS
.sp
-$ fedfs-lookup-junction -h fs.example.net -p /export/junction1 -t nsdb
+$ fedfs-lookup-junction -h fs.example.net -t nsdb /export/junction1
.br
Server returned FEDFS_ERR_NSDB_NOFSN
.sp
.RE
-In this example, the junction exists on the remote server,
+In this example, the junction 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 junction.
-The remote server is therefore not able to resolve the junction.
+fileset locations for the FSN UUID contained in the junction.
+The file server is therefore not able to resolve the junction.
.SH SECURITY
RPCSEC GSSAPI authentication has not yet been implemented for this command.
.SH "SEE ALSO"
@@ -55,20 +55,18 @@ static struct timeval fedfs_create_junction_timeout = { 25, 0 };
/**
* Short form command line options
*/
-static const char fedfs_create_junction_opts[] = "?dh:l:n:p:r:u:";
+static const char fedfs_create_junction_opts[] = "?dh:l:n:r:";
/**
* Long form command line options
*/
static const struct option fedfs_create_junction_longopts[] = {
{ "debug", 0, NULL, 'd', },
- { "fsnuuid", 1, NULL, 'u', },
{ "help", 0, NULL, '?', },
{ "hostname", 1, NULL, 'h', },
{ "nettype", 1, NULL, 'n', },
{ "nsdbname", 1, NULL, 'l', },
{ "nsdbport", 1, NULL, 'r', },
- { "path", 1, NULL, 'p', },
{ NULL, 0, NULL, 0, },
};
@@ -82,15 +80,14 @@ fedfs_create_junction_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] "
+ "pathname fsn-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");
@@ -204,7 +201,6 @@ main(int argc, char **argv)
hostname = "localhost";
nettype = "netpath";
- fsn_uuid = path = NULL;
while ((arg = getopt_long(argc, argv, fedfs_create_junction_opts,
fedfs_create_junction_longopts, NULL)) != -1) {
switch (arg) {
@@ -225,9 +221,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",
@@ -235,9 +228,6 @@ main(int argc, char **argv)
fedfs_create_junction_usage(progname);
}
break;
- case 'u':
- fsn_uuid = optarg;
- break;
default:
fprintf(stderr, "Invalid command line "
"argument: %c\n", (char)arg);
@@ -245,12 +235,15 @@ main(int argc, char **argv)
fedfs_create_junction_usage(progname);
}
}
- if (optind != argc) {
- fprintf(stderr, "Unrecognized command line argument\n");
+ if (argc == optind + 2) {
+ path = argv[optind];
+ fsn_uuid = argv[optind + 1];
+ } else {
+ fprintf(stderr, "Ambiguous positional parameters\n");
fedfs_create_junction_usage(progname);
}
- if (path == NULL || fsn_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_junction_usage(progname);
}
@@ -51,7 +51,7 @@ static struct timeval fedfs_delete_junction_timeout = { 25, 0 };
/**
* Short form command line options
*/
-static const char fedfs_delete_junction_opts[] = "?dh:n:p:";
+static const char fedfs_delete_junction_opts[] = "?dh:n:";
/**
* Long form command line options
@@ -61,7 +61,6 @@ static const struct option fedfs_delete_junction_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_junction_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 junction 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_junction_opts, fedfs_delete_junction_longopts, NULL)) != -1) {
switch (arg) {
case 'd':
@@ -159,21 +156,19 @@ main(int argc, char **argv)
case 'h':
hostname = optarg;
break;
- case 'p':
- path = optarg;
- break;
default:
fprintf(stderr, "Invalid command line argument: %c\n", (char)arg);
case '?':
fedfs_delete_junction_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_junction_usage(progname);
- }
- if (path == NULL) {
- fprintf(stderr, "Missing required command line argument\n");
+ } else {
+ fprintf(stderr, "No junction pathname was specified\n");
fedfs_delete_junction_usage(progname);
}
@@ -53,7 +53,7 @@ static struct timeval fedfs_lookup_junction_timeout = { 25, 0 };
/**
* Short form command line options
*/
-static const char fedfs_lookup_junction_opts[] = "?dh:n:p:t:";
+static const char fedfs_lookup_junction_opts[] = "?dh:n:t:";
/**
* Long form command line options
@@ -63,7 +63,6 @@ static const struct option fedfs_lookup_junction_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_junction_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 junction to resolve\n");
fprintf(stderr, "\t-t, --resolvetype Type of desired result (default: 'none')\n");
fprintf(stderr, "%s", fedfs_gpl_boilerplate);
@@ -289,7 +287,6 @@ main(int argc, char **argv)
hostname = "localhost";
nettype = "netpath";
resolvetype = "none";
- path = NULL;
while ((arg = getopt_long(argc, argv, fedfs_lookup_junction_opts,
fedfs_lookup_junction_longopts, NULL)) != -1) {
switch (arg) {
@@ -302,9 +299,6 @@ main(int argc, char **argv)
case 'n':
nettype = optarg;
break;
- case 'p':
- path = optarg;
- break;
case 't':
resolvetype = optarg;
break;
@@ -314,12 +308,13 @@ main(int argc, char **argv)
fedfs_lookup_junction_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_junction_usage(progname);
- }
- if (path == NULL) {
- fprintf(stderr, "Missing required command line argument\n");
+ } else {
+ fprintf(stderr, "No junction pathname was specified\n");
fedfs_lookup_junction_usage(progname);
}
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 junction management. Signed-off-by: Chuck Lever <chuck.lever@oracle.com> --- doc/man/fedfs-create-junction.8 | 57 ++++++++++++++++++------------- doc/man/fedfs-delete-junction.8 | 48 +++++++++++++++++--------- doc/man/fedfs-lookup-junction.8 | 67 ++++++++++++++++++++---------------- src/fedfsc/fedfs-create-junction.c | 27 +++++---------- src/fedfsc/fedfs-delete-junction.c | 21 ++++------- src/fedfsc/fedfs-lookup-junction.c | 21 ++++------- 6 files changed, 128 insertions(+), 113 deletions(-)