From patchwork Fri Jan 10 16:20:08 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Chuck Lever X-Patchwork-Id: 309334 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from userp1040.oracle.com (userp1040.oracle.com [156.151.31.81]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 030C12C007C for ; Sat, 11 Jan 2014 03:20:43 +1100 (EST) Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by userp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id s0AGKdhs000935 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Fri, 10 Jan 2014 16:20:40 GMT Received: from oss.oracle.com (oss-external.oracle.com [137.254.96.51]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s0AGKdMA002602 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Fri, 10 Jan 2014 16:20:39 GMT Received: from localhost ([127.0.0.1] helo=oss.oracle.com) by oss.oracle.com with esmtp (Exim 4.63) (envelope-from ) id 1W1ep5-00048Z-5X; Fri, 10 Jan 2014 08:20:39 -0800 Received: from acsinet21.oracle.com ([141.146.126.237]) by oss.oracle.com with esmtp (Exim 4.63) (envelope-from ) id 1W1eoi-00047F-1W for fedfs-utils-devel@oss.oracle.com; Fri, 10 Jan 2014 08:20:16 -0800 Received: from aserp1030.oracle.com (aserp1030.oracle.com [141.146.126.68]) by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s0AGKFre025813 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Fri, 10 Jan 2014 16:20:15 GMT Received: from mail-ie0-f179.google.com (mail-ie0-f179.google.com [209.85.223.179]) by aserp1030.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id s0AGKCEa011199 (version=TLSv1/SSLv3 cipher=RC4-SHA bits=128 verify=OK) for ; Fri, 10 Jan 2014 16:20:12 GMT Received: by mail-ie0-f179.google.com with SMTP id x13so5398471ief.10 for ; Fri, 10 Jan 2014 08:20:12 -0800 (PST) X-Received: by 10.43.106.137 with SMTP id du9mr1024297icc.93.1389370811743; Fri, 10 Jan 2014 08:20:11 -0800 (PST) Received: from seurat.1015granger.net (c-68-40-85-241.hsd1.mi.comcast.net. [68.40.85.241]) by mx.google.com with ESMTPSA id kt2sm4304128igb.1.2014.01.10.08.20.08 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 10 Jan 2014 08:20:10 -0800 (PST) To: fedfs-utils-devel@oss.oracle.com From: Chuck Lever Date: Fri, 10 Jan 2014 11:20:08 -0500 Message-ID: <20140110162008.32524.92516.stgit@seurat.1015granger.net> In-Reply-To: <20140110161428.32524.47303.stgit@seurat.1015granger.net> References: <20140110161428.32524.47303.stgit@seurat.1015granger.net> User-Agent: StGit/0.16 MIME-Version: 1.0 X-Flow-Control-Info: class=Pass-to-MM reputation=ipRisk-All ip=209.85.223.179 ct-class=R5 ct-vol1=-97 ct-vol2=8 ct-vol3=8 ct-risk=45 ct-spam1=70 ct-spam2=8 ct-bulk=6 rcpts=1 size=588522 X-Sendmail-CM-Score: 0.00% X-Sendmail-CM-Analysis: v=2.1 cv=D8h+dJhj c=1 sm=1 tr=0 a=LFjR4rNE8MGwP7hykJJA8w==:117 a=f4GS5uou6mMssVkgzQWOAg==:17 a=dzsqy3y4QnMA:10 a=RxjDRpUX6a4A:10 a=dPGociXpb70A:10 a=IkcTkHD0fZMA:10 a=yPCof4ZbAAAA:8 a=Lb1rMZzfAAAA:8 a=1XWaLZrsAAAA:8 a=C_IRinGWAAAA:8 a=dk lxdPka2uYA:10 a=mDV3o1hIAAAA:8 a=OK-8mIdLAAAA:8 a=P6JkxrBpAAAA:8 a=A1X0JdhQAAAA:8 a=4aNN2swayFGVnxZ23P8A:9 a=7B121WABU-efDoIH:21 a=SRZivEUHQuXdPfbz:21 a=rfenYci6HPNcWGAB:21 a=QEXdDO2ut3YA:10 a=Sf_gFPzhefAA:10 a=u37mErDvIGIA:10 a=nvz6EU7xhngA:10 a=7DSvI1 NPTFQA:10 a=MQEq1R4Qs-cA:10 X-Sendmail-CT-Classification: not spam X-Sendmail-CT-RefID: str=0001.0A090205.52D01DBF.003A, ss=1, re=0.000, recu=0.000, reip=0.000, cl=1, cld=1, fgs=0 Subject: [fedfs-utils] [PATCH 09/11] man: Have ./configure do variable substitution in man pages X-BeenThere: fedfs-utils-devel@oss.oracle.com X-Mailman-Version: 2.1.9 Precedence: list Reply-To: fedfs-utils Developers List-Id: fedfs-utils Developers List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: fedfs-utils-devel-bounces@oss.oracle.com Errors-To: fedfs-utils-devel-bounces@oss.oracle.com X-Source-IP: acsinet22.oracle.com [141.146.126.238] The publication date in the man page should reflect when the dist tarball is built, not when the man pages are installed. This also cleans up the Makefile in doc/man, removing open-coded substitution logic. Signed-off-by: Chuck Lever --- .gitignore | 2 configure.ac | 33 ++ doc/man/Makefile.am | 31 +- doc/man/fedfs-create-junction.8 | 198 -------------- doc/man/fedfs-create-junction.8.in | 198 ++++++++++++++ doc/man/fedfs-create-replication.8 | 189 ------------- doc/man/fedfs-create-replication.8.in | 189 +++++++++++++ doc/man/fedfs-delete-junction.8 | 168 ------------ doc/man/fedfs-delete-junction.8.in | 168 ++++++++++++ doc/man/fedfs-delete-replication.8 | 154 ----------- doc/man/fedfs-delete-replication.8.in | 154 +++++++++++ doc/man/fedfs-domainroot.8 | 322 ---------------------- doc/man/fedfs-domainroot.8.in | 322 ++++++++++++++++++++++ doc/man/fedfs-get-limited-nsdb-params.8 | 194 ------------- doc/man/fedfs-get-limited-nsdb-params.8.in | 194 +++++++++++++ doc/man/fedfs-get-nsdb-params.8 | 196 -------------- doc/man/fedfs-get-nsdb-params.8.in | 196 ++++++++++++++ doc/man/fedfs-lookup-junction.8 | 230 ---------------- doc/man/fedfs-lookup-junction.8.in | 230 ++++++++++++++++ doc/man/fedfs-lookup-replication.8 | 228 ---------------- doc/man/fedfs-lookup-replication.8.in | 228 ++++++++++++++++ doc/man/fedfs-map-nfs4.8 | 181 ------------- doc/man/fedfs-map-nfs4.8.in | 181 +++++++++++++ doc/man/fedfs-null.8 | 150 ---------- doc/man/fedfs-null.8.in | 150 ++++++++++ doc/man/fedfs-set-nsdb-params.8 | 200 -------------- doc/man/fedfs-set-nsdb-params.8.in | 200 ++++++++++++++ doc/man/fedfs.7 | 272 ------------------- doc/man/fedfs.7.in | 272 +++++++++++++++++++ doc/man/mount.fedfs.8 | 218 --------------- doc/man/mount.fedfs.8.in | 218 +++++++++++++++ doc/man/nfsref.8 | 273 ------------------- doc/man/nfsref.8.in | 273 +++++++++++++++++++ doc/man/nsdb-annotate.8 | 369 -------------------------- doc/man/nsdb-annotate.8.in | 369 ++++++++++++++++++++++++++ doc/man/nsdb-create-fsl.8 | 360 ------------------------- doc/man/nsdb-create-fsl.8.in | 360 +++++++++++++++++++++++++ doc/man/nsdb-create-fsn.8 | 332 ----------------------- doc/man/nsdb-create-fsn.8.in | 332 +++++++++++++++++++++++ doc/man/nsdb-delete-fsl.8 | 329 ----------------------- doc/man/nsdb-delete-fsl.8.in | 329 +++++++++++++++++++++++ doc/man/nsdb-delete-fsn.8 | 320 ---------------------- doc/man/nsdb-delete-fsn.8.in | 320 ++++++++++++++++++++++ doc/man/nsdb-delete-nsdb.8 | 266 ------------------ doc/man/nsdb-delete-nsdb.8.in | 266 ++++++++++++++++++ doc/man/nsdb-describe.8 | 314 ---------------------- doc/man/nsdb-describe.8.in | 314 ++++++++++++++++++++++ doc/man/nsdb-jumpstart.8 | 404 ---------------------------- doc/man/nsdb-jumpstart.8.in | 404 ++++++++++++++++++++++++++++ doc/man/nsdb-list.8 | 251 ----------------- doc/man/nsdb-list.8.in | 251 +++++++++++++++++ doc/man/nsdb-nces.8 | 260 ------------------ doc/man/nsdb-nces.8.in | 260 ++++++++++++++++++ doc/man/nsdb-parameters.7 | 161 ----------- doc/man/nsdb-parameters.7.in | 161 +++++++++++ doc/man/nsdb-remove-nci.8 | 284 -------------------- doc/man/nsdb-remove-nci.8.in | 284 ++++++++++++++++++++ doc/man/nsdb-resolve-fsn.8 | 303 --------------------- doc/man/nsdb-resolve-fsn.8.in | 303 +++++++++++++++++++++ doc/man/nsdb-simple-nce.8 | 292 -------------------- doc/man/nsdb-simple-nce.8.in | 292 ++++++++++++++++++++ doc/man/nsdb-update-fsl.8 | 353 ------------------------ doc/man/nsdb-update-fsl.8.in | 353 ++++++++++++++++++++++++ doc/man/nsdb-update-nci.8 | 322 ---------------------- doc/man/nsdb-update-nci.8.in | 322 ++++++++++++++++++++++ doc/man/nsdbparams.8 | 364 ------------------------- doc/man/nsdbparams.8.in | 364 +++++++++++++++++++++++++ doc/man/rpc.fedfsd.8 | 205 -------------- doc/man/rpc.fedfsd.8.in | 205 ++++++++++++++ 69 files changed, 8705 insertions(+), 8685 deletions(-) delete mode 100644 doc/man/fedfs-create-junction.8 create mode 100644 doc/man/fedfs-create-junction.8.in delete mode 100644 doc/man/fedfs-create-replication.8 create mode 100644 doc/man/fedfs-create-replication.8.in delete mode 100644 doc/man/fedfs-delete-junction.8 create mode 100644 doc/man/fedfs-delete-junction.8.in delete mode 100644 doc/man/fedfs-delete-replication.8 create mode 100644 doc/man/fedfs-delete-replication.8.in delete mode 100644 doc/man/fedfs-domainroot.8 create mode 100644 doc/man/fedfs-domainroot.8.in delete mode 100644 doc/man/fedfs-get-limited-nsdb-params.8 create mode 100644 doc/man/fedfs-get-limited-nsdb-params.8.in delete mode 100644 doc/man/fedfs-get-nsdb-params.8 create mode 100644 doc/man/fedfs-get-nsdb-params.8.in delete mode 100644 doc/man/fedfs-lookup-junction.8 create mode 100644 doc/man/fedfs-lookup-junction.8.in delete mode 100644 doc/man/fedfs-lookup-replication.8 create mode 100644 doc/man/fedfs-lookup-replication.8.in delete mode 100644 doc/man/fedfs-map-nfs4.8 create mode 100644 doc/man/fedfs-map-nfs4.8.in delete mode 100644 doc/man/fedfs-null.8 create mode 100644 doc/man/fedfs-null.8.in delete mode 100644 doc/man/fedfs-set-nsdb-params.8 create mode 100644 doc/man/fedfs-set-nsdb-params.8.in delete mode 100644 doc/man/fedfs.7 create mode 100644 doc/man/fedfs.7.in delete mode 100644 doc/man/mount.fedfs.8 create mode 100644 doc/man/mount.fedfs.8.in delete mode 100644 doc/man/nfsref.8 create mode 100644 doc/man/nfsref.8.in delete mode 100644 doc/man/nsdb-annotate.8 create mode 100644 doc/man/nsdb-annotate.8.in delete mode 100644 doc/man/nsdb-create-fsl.8 create mode 100644 doc/man/nsdb-create-fsl.8.in delete mode 100644 doc/man/nsdb-create-fsn.8 create mode 100644 doc/man/nsdb-create-fsn.8.in delete mode 100644 doc/man/nsdb-delete-fsl.8 create mode 100644 doc/man/nsdb-delete-fsl.8.in delete mode 100644 doc/man/nsdb-delete-fsn.8 create mode 100644 doc/man/nsdb-delete-fsn.8.in delete mode 100644 doc/man/nsdb-delete-nsdb.8 create mode 100644 doc/man/nsdb-delete-nsdb.8.in delete mode 100644 doc/man/nsdb-describe.8 create mode 100644 doc/man/nsdb-describe.8.in delete mode 100644 doc/man/nsdb-jumpstart.8 create mode 100644 doc/man/nsdb-jumpstart.8.in delete mode 100644 doc/man/nsdb-list.8 create mode 100644 doc/man/nsdb-list.8.in delete mode 100644 doc/man/nsdb-nces.8 create mode 100644 doc/man/nsdb-nces.8.in delete mode 100644 doc/man/nsdb-parameters.7 create mode 100644 doc/man/nsdb-parameters.7.in delete mode 100644 doc/man/nsdb-remove-nci.8 create mode 100644 doc/man/nsdb-remove-nci.8.in delete mode 100644 doc/man/nsdb-resolve-fsn.8 create mode 100644 doc/man/nsdb-resolve-fsn.8.in delete mode 100644 doc/man/nsdb-simple-nce.8 create mode 100644 doc/man/nsdb-simple-nce.8.in delete mode 100644 doc/man/nsdb-update-fsl.8 create mode 100644 doc/man/nsdb-update-fsl.8.in delete mode 100644 doc/man/nsdb-update-nci.8 create mode 100644 doc/man/nsdb-update-nci.8.in delete mode 100644 doc/man/nsdbparams.8 create mode 100644 doc/man/nsdbparams.8.in delete mode 100644 doc/man/rpc.fedfsd.8 create mode 100644 doc/man/rpc.fedfsd.8.in diff --git a/.gitignore b/.gitignore index b285f3a..0c09a4e 100644 --- a/.gitignore +++ b/.gitignore @@ -47,6 +47,8 @@ nsdb-update-fsl nsdb-update-nci nsdb-remove-nci nsdb-delete-nsdb +doc/man/*.7 +doc/man/*.8 doc/rpcl/fedfs_admin.h doc/rpcl/fedfs_admin_clnt.c doc/rpcl/fedfs_admin_svc.c diff --git a/configure.ac b/configure.ac index b692185..1120ff7 100644 --- a/configure.ac +++ b/configure.ac @@ -191,6 +191,39 @@ AC_CONFIG_FILES([Makefile doc/Makefile doc/ldap/Makefile doc/man/Makefile + doc/man/fedfs.7 + doc/man/nsdb-parameters.7 + doc/man/fedfs-create-junction.8 + doc/man/fedfs-create-replication.8 + doc/man/fedfs-delete-junction.8 + doc/man/fedfs-delete-replication.8 + doc/man/fedfs-domainroot.8 + doc/man/fedfs-get-limited-nsdb-params.8 + doc/man/fedfs-get-nsdb-params.8 + doc/man/fedfs-lookup-junction.8 + doc/man/fedfs-lookup-replication.8 + doc/man/fedfs-map-nfs4.8 + doc/man/fedfs-null.8 + doc/man/fedfs-set-nsdb-params.8 + doc/man/mount.fedfs.8 + doc/man/nfsref.8 + doc/man/nsdb-annotate.8 + doc/man/nsdb-create-fsl.8 + doc/man/nsdb-create-fsn.8 + doc/man/nsdb-delete-fsl.8 + doc/man/nsdb-delete-fsn.8 + doc/man/nsdb-delete-nsdb.8 + doc/man/nsdb-describe.8 + doc/man/nsdb-jumpstart.8 + doc/man/nsdb-list.8 + doc/man/nsdb-nces.8 + doc/man/nsdbparams.8 + doc/man/nsdb-remove-nci.8 + doc/man/nsdb-resolve-fsn.8 + doc/man/nsdb-simple-nce.8 + doc/man/nsdb-update-fsl.8 + doc/man/nsdb-update-nci.8 + doc/man/rpc.fedfsd.8 doc/rpcl/Makefile src/Makefile src/domainroot/Makefile diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index 1123dfc..1d34632 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -23,7 +23,8 @@ ## http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt ## -FEDFS_CLIENT_CMDS = fedfs-create-junction.8 fedfs-create-replication.8 \ +MISC_DOCS = fedfs.7 nsdb-parameters.7 +ADMIN_CLIENT_CMDS = fedfs-create-junction.8 fedfs-create-replication.8 \ fedfs-delete-junction.8 fedfs-delete-replication.8 \ fedfs-lookup-junction.8 fedfs-lookup-replication.8 \ fedfs-get-nsdb-params.8 fedfs-set-nsdb-params.8 \ @@ -35,29 +36,13 @@ NSDB_CLIENT_CMDS = nsdb-create-fsl.8 nsdb-create-fsn.8 \ nsdb-list.8 nsdb-nces.8 \ nsdb-update-nci.8 nsdb-remove-nci.8 \ nsdb-delete-nsdb.8 nsdb-simple-nce.8 +PYTHON_CMDS = fedfs-domainroot.8 nsdb-jumpstart.8 +MISC_CMDS = rpc.fedfsd.8 nsdbparams.8 nfsref.8 +MOUNT_CMDS = mount.fedfs.8 fedfs-map-nfs4.8 + +man_MANS = $(MISC_DOCS) $(MISC_CMDS) $(PYTHON_CMDS) \ + $(ADMIN_CLIENT_CMDS) $(NSDB_CLIENT_CMDS) -dist_man7_MANS = fedfs.7 nsdb-parameters.7 -dist_man8_MANS = rpc.fedfsd.8 mount.fedfs.8 fedfs-map-nfs4.8 nfsref.8 \ - nsdbparams.8 fedfs-domainroot.8 nsdb-jumpstart.8 \ - $(FEDFS_CLIENT_CMDS) $(NSDB_CLIENT_CMDS) CLEANFILES = cscope.in.out cscope.out cscope.po.out *~ DISTCLEANFILES = Makefile.in - -dist-hook: - (cd $(distdir) && \ - for p in $(dist_man7_MANS) $(dist_man8_MANS); do \ - $(SED) -i 's,[@]publication-date@,$(pubdate),' $$p ;\ - done) - -install-data-hook: - (cd $(DESTDIR)$(mandir)/man7 && \ - for p in $(dist_man7_MANS); do \ - $(SED) -i 's,[@]statedir@,$(statedir),' $$p ;\ - $(SED) -i 's,[@]fedfsuser@,$(fedfsuser),' $$p ;\ - done) - (cd $(DESTDIR)$(mandir)/man8 && \ - for p in $(dist_man8_MANS); do \ - $(SED) -i 's,[@]statedir@,$(statedir),' $$p ;\ - $(SED) -i 's,[@]fedfsuser@,$(fedfsuser),' $$p ;\ - done) diff --git a/doc/man/fedfs-create-junction.8 b/doc/man/fedfs-create-junction.8 deleted file mode 100644 index c7360a9..0000000 --- a/doc/man/fedfs-create-junction.8 +++ /dev/null @@ -1,198 +0,0 @@ -.\"@(#)fedfs-create-junction.8" -.\" -.\" @file doc/man/fedfs-create-junction.8 -.\" @brief man page for fedfs-create-junction client command -.\" - -.\" -.\" Copyright 2011, 2013 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH FEDFS-CREATE-JUNCTION 8 "@publication-date@" -.SH NAME -fedfs-create-junction \- send a FEDFS_CREATE_JUNCTION ADMIN protocol request -.SH SYNOPSIS -.B fedfs-create-junction -.RB [ \-?d ] -.RB [ \-n -.IR nettype ] -.RB [ \-h -.IR hostname ] -.RB [ \-l -.IR nsdbname ] -.RB [ \-r -.IR nsdbport ] -.RB [ \-s -.IR security ] -.I path -.I fsn-uuid -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -FedFS-enabled file servers allow remote administrative access via an -authenticated RPC protocol known as the -.IR "FedFS ADMIN protocol" . -Using this protocol, FedFS administrators manage -FedFS junctions and NSDB connection parameter information -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 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 -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" -Enables debugging messages during operation. -.IP "\fB\-?, \-\-help" -Displays -.BR fedfs-create-junction (8) -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 -.BR localhost . -.IP "\fB\-n, \-\-nettype=\fInettype\fP" -Specifies the transport to use when contacting the remote FedFS ADMIN service. -Typically the -.I nettype -is one of -.B tcp -or -.BR udp . -If this option is not specified, the default value is -.BR netpath . -See -.BR rpc (3t) -for details. -.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" -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 \--nsdbname -option is not specified, the -.BR fedfs-create-junction (8) -command fails. -.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" -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\-s, \-\-security=\fIflavor\fP" -Specifies the security flavor to use -when contacting the remote FedFS ADMIN service. -Valid flavors are -.BR sys , -.BR unix , -.BR krb5 , -.BR krb5i ", and" -.BR krb5p . -If this option is not specified, the -.B unix -flavor is used. -See the -.B SECURITY -section of this man page for details. -.SH EXAMPLES -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 file server -.IR fs.example.net , -use: -.RS -.sp -$ 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 -By default, or if the -.B sys -and -.B unix -flavors are specified with the -.BI \-\-security= flavor -option, the -.BR fedfs-create-junction (8) -command uses AUTH_SYS security for the Remote Procedure Call. -AUTH_SYS has known weaknesses and should be avoided on untrusted networks. -.P -The RPC client uses the Kerberos v5 GSS mechanism -if a Kerberos security flavor is specified. -When specifying a Kerberos security flavor, -the user must first obtain a valid Kerberos ticket using -.BR kinit (1) -before running -.BR fedfs-create-junction (8). -.P -The AUTH_NONE security flavor is no longer supported by this implementation. -.SH "SEE ALSO" -.BR fedfs (7), -.BR rpc.fedfsd (8), -.BR fedfs-lookup-junction (8), -.BR nsdb-create-fsn (8), -.BR kinit (1), -.BR rpc (3t) -.sp -RFC 5716 for FedFS requirements and overview -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/fedfs-create-junction.8.in b/doc/man/fedfs-create-junction.8.in new file mode 100644 index 0000000..cf47a96 --- /dev/null +++ b/doc/man/fedfs-create-junction.8.in @@ -0,0 +1,198 @@ +.\"@(#)fedfs-create-junction.8" +.\" +.\" @file doc/man/fedfs-create-junction.8 +.\" @brief man page for fedfs-create-junction client command +.\" + +.\" +.\" Copyright 2011, 2013 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH FEDFS-CREATE-JUNCTION 8 "@pubdate@" +.SH NAME +fedfs-create-junction \- send a FEDFS_CREATE_JUNCTION ADMIN protocol request +.SH SYNOPSIS +.B fedfs-create-junction +.RB [ \-?d ] +.RB [ \-n +.IR nettype ] +.RB [ \-h +.IR hostname ] +.RB [ \-l +.IR nsdbname ] +.RB [ \-r +.IR nsdbport ] +.RB [ \-s +.IR security ] +.I path +.I fsn-uuid +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +FedFS-enabled file servers allow remote administrative access via an +authenticated RPC protocol known as the +.IR "FedFS ADMIN protocol" . +Using this protocol, FedFS administrators manage +FedFS junctions and NSDB connection parameter information +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 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 +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" +Enables debugging messages during operation. +.IP "\fB\-?, \-\-help" +Displays +.BR fedfs-create-junction (8) +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 +.BR localhost . +.IP "\fB\-n, \-\-nettype=\fInettype\fP" +Specifies the transport to use when contacting the remote FedFS ADMIN service. +Typically the +.I nettype +is one of +.B tcp +or +.BR udp . +If this option is not specified, the default value is +.BR netpath . +See +.BR rpc (3t) +for details. +.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" +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 \--nsdbname +option is not specified, the +.BR fedfs-create-junction (8) +command fails. +.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" +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\-s, \-\-security=\fIflavor\fP" +Specifies the security flavor to use +when contacting the remote FedFS ADMIN service. +Valid flavors are +.BR sys , +.BR unix , +.BR krb5 , +.BR krb5i ", and" +.BR krb5p . +If this option is not specified, the +.B unix +flavor is used. +See the +.B SECURITY +section of this man page for details. +.SH EXAMPLES +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 file server +.IR fs.example.net , +use: +.RS +.sp +$ 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 +By default, or if the +.B sys +and +.B unix +flavors are specified with the +.BI \-\-security= flavor +option, the +.BR fedfs-create-junction (8) +command uses AUTH_SYS security for the Remote Procedure Call. +AUTH_SYS has known weaknesses and should be avoided on untrusted networks. +.P +The RPC client uses the Kerberos v5 GSS mechanism +if a Kerberos security flavor is specified. +When specifying a Kerberos security flavor, +the user must first obtain a valid Kerberos ticket using +.BR kinit (1) +before running +.BR fedfs-create-junction (8). +.P +The AUTH_NONE security flavor is no longer supported by this implementation. +.SH "SEE ALSO" +.BR fedfs (7), +.BR rpc.fedfsd (8), +.BR fedfs-lookup-junction (8), +.BR nsdb-create-fsn (8), +.BR kinit (1), +.BR rpc (3t) +.sp +RFC 5716 for FedFS requirements and overview +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/fedfs-create-replication.8 b/doc/man/fedfs-create-replication.8 deleted file mode 100644 index f4bb478..0000000 --- a/doc/man/fedfs-create-replication.8 +++ /dev/null @@ -1,189 +0,0 @@ -.\"@(#)fedfs-create-replication.8" -.\" -.\" @file doc/man/fedfs-create-replication.8 -.\" @brief man page for fedfs-create-replication client command -.\" - -.\" -.\" Copyright 2011, 2013 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH FEDFS-CREATE-REPLICATION 8 "@publication-date@" -.SH NAME -fedfs-create-replication \- send a FEDFS_CREATE_REPLICATION ADMIN protocol request -.SH SYNOPSIS -.B fedfs-create-replication -.RB [ \-?d ] -.RB [ \-n -.IR nettype ] -.RB [ \-h -.IR hostname ] -.RB [ \-l -.IR nsdbname ] -.RB [ \-r -.IR nsdbport ] -.RB [ \-s -.IR security ] -.I path -.I uuid -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -FedFS-enabled file servers allow remote administrative access via an -authenticated RPC protocol known as the -.IR "FedFS ADMIN protocol" . -Using this protocol, FedFS administrators manage -FedFS junctions and NSDB connection parameter information -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 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 -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" -Enables debugging messages during operation. -.IP "\fB\-?, \-\-help" -Displays -.BR fedfs-create-replication (8) -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 -.BR localhost . -.IP "\fB\-n, \-\-nettype=\fInettype\fP" -Specifies the transport to use when contacting the remote FedFS ADMIN service. -Typically the -.I nettype -is one of -.B tcp -or -.BR udp . -If this option is not specified, the default value is -.BR netpath . -See -.BR rpc (3t) -for details. -.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" -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 --nsdbname -option is not specified, the -.BR fedfs-create-replication (8) -command fails. -.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" -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\-s, \-\-security=\fIflavor\fP" -Specifies the security flavor to use -when contacting the remote FedFS ADMIN service. -Valid flavors are -.BR sys , -.BR unix , -.BR krb5 , -.BR krb5i ", and" -.BR krb5p . -If this option is not specified, the -.B unix -flavor is used. -See the -.B SECURITY -section of this man page for details. -.SH EXAMPLES -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 file server -.IR fs.example.net , -use: -.RS -.sp -$ fedfs-create-replication -h fs.example.net -l nsdb.example.net \\ - /export/replication1 `uuidgen -t` -.sp -.RE -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. -.SH SECURITY -By default, or if the -.B sys -and -.B unix -flavors are specified with the -.BI \-\-security= flavor -option, the -.BR fedfs-create-replication (8) -command uses AUTH_SYS security for the Remote Procedure Call. -AUTH_SYS has known weaknesses and should be avoided on untrusted networks. -.P -The RPC client uses the Kerberos v5 GSS mechanism -if a Kerberos security flavor is specified. -When specifying a Kerberos security flavor, -the user must first obtain a valid Kerberos ticket using -.BR kinit (1) -before running -.BR fedfs-create-replication (8). -.P -The AUTH_NONE security flavor is no longer supported by this implementation. -.SH "SEE ALSO" -.BR fedfs (7), -.BR rpc.fedfsd (8), -.BR fedfs-lookup-replication (8), -.BR nsdb-create-fsn (8), -.BR kinit (1), -.BR rpc (3t) -.sp -RFC 5716 for FedFS requirements and overview -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/fedfs-create-replication.8.in b/doc/man/fedfs-create-replication.8.in new file mode 100644 index 0000000..c851080 --- /dev/null +++ b/doc/man/fedfs-create-replication.8.in @@ -0,0 +1,189 @@ +.\"@(#)fedfs-create-replication.8" +.\" +.\" @file doc/man/fedfs-create-replication.8 +.\" @brief man page for fedfs-create-replication client command +.\" + +.\" +.\" Copyright 2011, 2013 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH FEDFS-CREATE-REPLICATION 8 "@pubdate@" +.SH NAME +fedfs-create-replication \- send a FEDFS_CREATE_REPLICATION ADMIN protocol request +.SH SYNOPSIS +.B fedfs-create-replication +.RB [ \-?d ] +.RB [ \-n +.IR nettype ] +.RB [ \-h +.IR hostname ] +.RB [ \-l +.IR nsdbname ] +.RB [ \-r +.IR nsdbport ] +.RB [ \-s +.IR security ] +.I path +.I uuid +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +FedFS-enabled file servers allow remote administrative access via an +authenticated RPC protocol known as the +.IR "FedFS ADMIN protocol" . +Using this protocol, FedFS administrators manage +FedFS junctions and NSDB connection parameter information +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 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 +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" +Enables debugging messages during operation. +.IP "\fB\-?, \-\-help" +Displays +.BR fedfs-create-replication (8) +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 +.BR localhost . +.IP "\fB\-n, \-\-nettype=\fInettype\fP" +Specifies the transport to use when contacting the remote FedFS ADMIN service. +Typically the +.I nettype +is one of +.B tcp +or +.BR udp . +If this option is not specified, the default value is +.BR netpath . +See +.BR rpc (3t) +for details. +.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" +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 --nsdbname +option is not specified, the +.BR fedfs-create-replication (8) +command fails. +.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" +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\-s, \-\-security=\fIflavor\fP" +Specifies the security flavor to use +when contacting the remote FedFS ADMIN service. +Valid flavors are +.BR sys , +.BR unix , +.BR krb5 , +.BR krb5i ", and" +.BR krb5p . +If this option is not specified, the +.B unix +flavor is used. +See the +.B SECURITY +section of this man page for details. +.SH EXAMPLES +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 file server +.IR fs.example.net , +use: +.RS +.sp +$ fedfs-create-replication -h fs.example.net -l nsdb.example.net \\ + /export/replication1 `uuidgen -t` +.sp +.RE +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. +.SH SECURITY +By default, or if the +.B sys +and +.B unix +flavors are specified with the +.BI \-\-security= flavor +option, the +.BR fedfs-create-replication (8) +command uses AUTH_SYS security for the Remote Procedure Call. +AUTH_SYS has known weaknesses and should be avoided on untrusted networks. +.P +The RPC client uses the Kerberos v5 GSS mechanism +if a Kerberos security flavor is specified. +When specifying a Kerberos security flavor, +the user must first obtain a valid Kerberos ticket using +.BR kinit (1) +before running +.BR fedfs-create-replication (8). +.P +The AUTH_NONE security flavor is no longer supported by this implementation. +.SH "SEE ALSO" +.BR fedfs (7), +.BR rpc.fedfsd (8), +.BR fedfs-lookup-replication (8), +.BR nsdb-create-fsn (8), +.BR kinit (1), +.BR rpc (3t) +.sp +RFC 5716 for FedFS requirements and overview +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/fedfs-delete-junction.8 b/doc/man/fedfs-delete-junction.8 deleted file mode 100644 index e7b4e7b..0000000 --- a/doc/man/fedfs-delete-junction.8 +++ /dev/null @@ -1,168 +0,0 @@ -.\"@(#)fedfs-delete-junction.8" -.\" -.\" @file doc/man/fedfs-delete-junction.8 -.\" @brief man page for fedfs-delete-junction client command -.\" - -.\" -.\" Copyright 2011, 2013 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH FEDFS-DELETE-JUNCTION 8 "@publication-date@" -.SH NAME -fedfs-delete-junction \- send a FEDFS_DELETE_JUNCTION ADMIN protocol request -.SH SYNOPSIS -.B fedfs-delete-junction -.RB [ \-?d ] -.RB [ \-n -.IR nettype ] -.RB [ \-h -.IR hostname ] -.RB [ \-s -.IR security ] -.I path -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -FedFS-enabled file servers allow remote administrative access via an -authenticated RPC protocol known as the -.IR "FedFS ADMIN protocol" . -Using this protocol, FedFS administrators manage -FedFS junctions and NSDB connection parameter information -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 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 -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" -Enables debugging messages during operation. -.IP "\fB\-?, \-\-help" -Displays -.BR fedfs-delete-junction (8) -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 -.BR localhost . -.IP "\fB\-n, \-\-nettype=\fInettype\fP" -Specifies the transport to use when contacting the remote FedFS ADMIN service. -Typically the -.I nettype -is one of -.B tcp -or -.BR udp . -If this option is not specified, the default value is -.BR netpath . -See -.BR rpc (3t) -for details. -.IP "\fB\-s, \-\-security=\fIflavor\fP" -Specifies the security flavor to use -when contacting the remote FedFS ADMIN service. -Valid flavors are -.BR sys , -.BR unix , -.BR krb5 , -.BR krb5i ", and" -.BR krb5p . -If this option is not specified, the -.B unix -flavor is used. -See the -.B SECURITY -section of this man page for details. -.SH EXAMPLES -Suppose you are the FedFS administrator of the -.I example.net -FedFS domain. -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 /export/junction1 -.SH SECURITY -By default, or if the -.B sys -and -.B unix -flavors are specified with the -.BI \-\-security= flavor -option, the -.BR fedfs-create-junction (8) -command uses AUTH_SYS security for the Remote Procedure Call. -AUTH_SYS has known weaknesses and should be avoided on untrusted networks. -.P -The RPC client uses the Kerberos v5 GSS mechanism -if a Kerberos security flavor is specified. -When specifying a Kerberos security flavor, -the user must first obtain a valid Kerberos ticket using -.BR kinit (1) -before running -.BR fedfs-create-junction (8). -.P -The AUTH_NONE security flavor is no longer supported by this implementation. -.SH "SEE ALSO" -.BR fedfs (7), -.BR rpc.fedfsd (8), -.BR kinit (1), -.BR rpc (3t) -.sp -RFC 5716 for FedFS requirements and overview -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/fedfs-delete-junction.8.in b/doc/man/fedfs-delete-junction.8.in new file mode 100644 index 0000000..ad3b1fb --- /dev/null +++ b/doc/man/fedfs-delete-junction.8.in @@ -0,0 +1,168 @@ +.\"@(#)fedfs-delete-junction.8" +.\" +.\" @file doc/man/fedfs-delete-junction.8 +.\" @brief man page for fedfs-delete-junction client command +.\" + +.\" +.\" Copyright 2011, 2013 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH FEDFS-DELETE-JUNCTION 8 "@pubdate@" +.SH NAME +fedfs-delete-junction \- send a FEDFS_DELETE_JUNCTION ADMIN protocol request +.SH SYNOPSIS +.B fedfs-delete-junction +.RB [ \-?d ] +.RB [ \-n +.IR nettype ] +.RB [ \-h +.IR hostname ] +.RB [ \-s +.IR security ] +.I path +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +FedFS-enabled file servers allow remote administrative access via an +authenticated RPC protocol known as the +.IR "FedFS ADMIN protocol" . +Using this protocol, FedFS administrators manage +FedFS junctions and NSDB connection parameter information +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 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 +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" +Enables debugging messages during operation. +.IP "\fB\-?, \-\-help" +Displays +.BR fedfs-delete-junction (8) +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 +.BR localhost . +.IP "\fB\-n, \-\-nettype=\fInettype\fP" +Specifies the transport to use when contacting the remote FedFS ADMIN service. +Typically the +.I nettype +is one of +.B tcp +or +.BR udp . +If this option is not specified, the default value is +.BR netpath . +See +.BR rpc (3t) +for details. +.IP "\fB\-s, \-\-security=\fIflavor\fP" +Specifies the security flavor to use +when contacting the remote FedFS ADMIN service. +Valid flavors are +.BR sys , +.BR unix , +.BR krb5 , +.BR krb5i ", and" +.BR krb5p . +If this option is not specified, the +.B unix +flavor is used. +See the +.B SECURITY +section of this man page for details. +.SH EXAMPLES +Suppose you are the FedFS administrator of the +.I example.net +FedFS domain. +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 /export/junction1 +.SH SECURITY +By default, or if the +.B sys +and +.B unix +flavors are specified with the +.BI \-\-security= flavor +option, the +.BR fedfs-create-junction (8) +command uses AUTH_SYS security for the Remote Procedure Call. +AUTH_SYS has known weaknesses and should be avoided on untrusted networks. +.P +The RPC client uses the Kerberos v5 GSS mechanism +if a Kerberos security flavor is specified. +When specifying a Kerberos security flavor, +the user must first obtain a valid Kerberos ticket using +.BR kinit (1) +before running +.BR fedfs-create-junction (8). +.P +The AUTH_NONE security flavor is no longer supported by this implementation. +.SH "SEE ALSO" +.BR fedfs (7), +.BR rpc.fedfsd (8), +.BR kinit (1), +.BR rpc (3t) +.sp +RFC 5716 for FedFS requirements and overview +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/fedfs-delete-replication.8 b/doc/man/fedfs-delete-replication.8 deleted file mode 100644 index 2a4ad79..0000000 --- a/doc/man/fedfs-delete-replication.8 +++ /dev/null @@ -1,154 +0,0 @@ -.\"@(#)fedfs-delete-replication.8" -.\" -.\" @file doc/man/fedfs-delete-replication.8 -.\" @brief man page for fedfs-delete-replication client command -.\" - -.\" -.\" Copyright 2011, 2013 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH FEDFS-DELETE-REPLICATION 8 "@publication-date@" -.SH NAME -fedfs-delete-replication \- send a FEDFS_DELETE_REPLICATION ADMIN protocol request -.SH SYNOPSIS -.B fedfs-delete-replication -.RB [ \-?d ] -.RB [ \-n -.IR nettype ] -.RB [ \-h -.IR hostname ] -.RB [ \-s -.IR security ] -.I path -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -FedFS-enabled file servers allow remote administrative access via an -authenticated RPC protocol known as the -.IR "FedFS ADMIN protocol" . -Using this protocol, FedFS administrators manage -FedFS junctions and NSDB connection parameter information -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 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 -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" -Enables debugging messages during operation. -.IP "\fB\-?, \-\-help" -Displays -.BR fedfs-delete-replication (8) -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 -.BR localhost . -.IP "\fB\-n, \-\-nettype=\fInettype\fP" -Specifies the transport to use when contacting the remote FedFS ADMIN service. -Typically the -.I nettype -is one of -.B tcp -or -.BR udp . -If this option is not specified, the default value is -.BR netpath . -See -.BR rpc (3t) -for details. -.IP "\fB\-s, \-\-security=\fIflavor\fP" -Specifies the security flavor to use -when contacting the remote FedFS ADMIN service. -Valid flavors are -.BR sys , -.BR unix , -.BR krb5 , -.BR krb5i ", and" -.BR krb5p . -If this option is not specified, the -.B unix -flavor is used. -See the -.B SECURITY -section of this man page for details. -.SH EXAMPLES -Suppose you are the FedFS administrator of the -.I example.net -FedFS domain. -To delete an existing FedFS replication on the remote server -.IR fs.example.net , -use: -.RS -.sp -$ fedfs-delete-replication -h fs.example.net /export/replication1 -.SH SECURITY -By default, or if the -.B sys -and -.B unix -flavors are specified with the -.BI \-\-security= flavor -option, the -.BR fedfs-create-junction (8) -command uses AUTH_SYS security for the Remote Procedure Call. -AUTH_SYS has known weaknesses and should be avoided on untrusted networks. -.P -The RPC client uses the Kerberos v5 GSS mechanism -if a Kerberos security flavor is specified. -When specifying a Kerberos security flavor, -the user must first obtain a valid Kerberos ticket using -.BR kinit (1) -before running -.BR fedfs-create-junction (8). -.P -The AUTH_NONE security flavor is no longer supported by this implementation. -.SH "SEE ALSO" -.BR fedfs (7), -.BR rpc.fedfsd (8), -.BR kinit (1), -.BR rpc (3t) -.sp -RFC 5716 for FedFS requirements and overview -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/fedfs-delete-replication.8.in b/doc/man/fedfs-delete-replication.8.in new file mode 100644 index 0000000..f5582c3 --- /dev/null +++ b/doc/man/fedfs-delete-replication.8.in @@ -0,0 +1,154 @@ +.\"@(#)fedfs-delete-replication.8" +.\" +.\" @file doc/man/fedfs-delete-replication.8 +.\" @brief man page for fedfs-delete-replication client command +.\" + +.\" +.\" Copyright 2011, 2013 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH FEDFS-DELETE-REPLICATION 8 "@pubdate@" +.SH NAME +fedfs-delete-replication \- send a FEDFS_DELETE_REPLICATION ADMIN protocol request +.SH SYNOPSIS +.B fedfs-delete-replication +.RB [ \-?d ] +.RB [ \-n +.IR nettype ] +.RB [ \-h +.IR hostname ] +.RB [ \-s +.IR security ] +.I path +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +FedFS-enabled file servers allow remote administrative access via an +authenticated RPC protocol known as the +.IR "FedFS ADMIN protocol" . +Using this protocol, FedFS administrators manage +FedFS junctions and NSDB connection parameter information +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 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 +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" +Enables debugging messages during operation. +.IP "\fB\-?, \-\-help" +Displays +.BR fedfs-delete-replication (8) +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 +.BR localhost . +.IP "\fB\-n, \-\-nettype=\fInettype\fP" +Specifies the transport to use when contacting the remote FedFS ADMIN service. +Typically the +.I nettype +is one of +.B tcp +or +.BR udp . +If this option is not specified, the default value is +.BR netpath . +See +.BR rpc (3t) +for details. +.IP "\fB\-s, \-\-security=\fIflavor\fP" +Specifies the security flavor to use +when contacting the remote FedFS ADMIN service. +Valid flavors are +.BR sys , +.BR unix , +.BR krb5 , +.BR krb5i ", and" +.BR krb5p . +If this option is not specified, the +.B unix +flavor is used. +See the +.B SECURITY +section of this man page for details. +.SH EXAMPLES +Suppose you are the FedFS administrator of the +.I example.net +FedFS domain. +To delete an existing FedFS replication on the remote server +.IR fs.example.net , +use: +.RS +.sp +$ fedfs-delete-replication -h fs.example.net /export/replication1 +.SH SECURITY +By default, or if the +.B sys +and +.B unix +flavors are specified with the +.BI \-\-security= flavor +option, the +.BR fedfs-create-junction (8) +command uses AUTH_SYS security for the Remote Procedure Call. +AUTH_SYS has known weaknesses and should be avoided on untrusted networks. +.P +The RPC client uses the Kerberos v5 GSS mechanism +if a Kerberos security flavor is specified. +When specifying a Kerberos security flavor, +the user must first obtain a valid Kerberos ticket using +.BR kinit (1) +before running +.BR fedfs-create-junction (8). +.P +The AUTH_NONE security flavor is no longer supported by this implementation. +.SH "SEE ALSO" +.BR fedfs (7), +.BR rpc.fedfsd (8), +.BR kinit (1), +.BR rpc (3t) +.sp +RFC 5716 for FedFS requirements and overview +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/fedfs-domainroot.8 b/doc/man/fedfs-domainroot.8 deleted file mode 100644 index c50a6e5..0000000 --- a/doc/man/fedfs-domainroot.8 +++ /dev/null @@ -1,322 +0,0 @@ -.\"@(#)fedfs-domainroot.8" -.\" -.\" @file doc/man/fedfs-domainroot.8 -.\" @brief man page for fedfs-domainroot tool -.\" - -.\" -.\" Copyright 2013 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH FEDFS-DOMAINROOT 8 "@publication-date@" -.SH NAME -fedfs-domainroot \- set up FedFS domain root infrastructure -.SH SYNOPSIS -.B fedfs-domainroot -.RB [ \-h ", " \-\-help ] -.RB [ \-\-version ] -.P -.B fedfs-domainroot -.RB [ \-\-silent ] -.RB [ \-\-statedir = -.IR statedir ] -.B add -.I domainname -.P -.B fedfs-domainroot -.RB [ \-\-silent ] -.RB [ \-\-statedir = -.IR statedir ] -.B remove -.I domainname -.RB [ \-\-force ] -.P -.B fedfs-domainroot -.RB [ \-\-silent ] -.RB [ \-\-statedir = -.IR statedir ] -.B status -.P -.B fedfs-domainroot -.RB [ \-\-silent ] -.RB [ \-\-statedir = -.IR statedir ] -.B clean -.RB [ \-\-force ] -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -The top directory of a FedFS domain namespace is known as a -.I domain root -directory. -FedFS-enabled clients discover the fileserver that exports -a FedFS domain's root directory using a DNS SRV query. -Using a well-known export path, -clients then mount the domain root directory -on that fileserver in the normal fashion. -.P -After a filesystem client mounts a domain's root directory, -applications on that client descend into the domain's name space -starting in that directory, -and are directed transparently to exports on other fileservers. -.P -Further information about domain roots is available in -.BR fedfs (7). -.P -.SH DESCRIPTION -A single fileserver may host domain root directories -for one or more FedFS domains. -The -.BR fedfs-domainroot (8) -command is a convenient way to securely manage domain root exports -on a Linux NFS fileserver. -FedFS itself is agnostic about the underlying file-access protocol, -but the -.BR fedfs-domainroot (8) -command supports only NFS at this time. -.P -FedFS domain root directories are exported using a standard well-known -pathname to make it simple for clients to find them. -The first component of the domain root's export pathname is always -.IR /.domainroot . -The second component is a FedFS domain name. -.P -For instance, the export pathname of the domain root of the -.I example.net -FedFS domain is -.IR /.domainroot/example.net . -.SS Operation -The -.B add -subcommand creates a directory under -.I @statedir@/domainroots -where the contents of the domain root directory reside. -A directory is also set up under -.I /.domainroot -for each doman root directory. -.BR fedfs-domainroot (8) -bind-mounts the domain root directory under -.I @statedir@/domainroots, -then exports the directory under -.IR /.domainroot . -.P -In this way, each domain root directory is exported via a well-known pathname, -and can have its own export settings separate from other domain root directories, -including security settings and client and network designations. -These can be modified by editing -.I /etc/exports -after the -domain root export is created. -.P -The -.BR fedfs-domainroot (8) -command must run as root in order to create and remove NFS exports -and entries in -.IR /etc/fstab . -.SS Subcommands -Valid -.BR fedfs-domainroot (8) -subcommands are: -.IP "\fBclean\fP" -Remove the -.I /.domainroot -directory and other infrastructure (as long as it is empty). -The user is asked to confirm before action is taken. -.IP -By default, this process stops when a step encounters an error. -Adding the -.B \-\-force -option forces the process to try each step even if an error occurs, -and bypasses the confirmation request. -.IP "\fBstatus\fP" -Display the status of the domain root infrastructure on the local system. -This includes whether NFSD is running, and what domain root directories -are currently configured and exported. -This subcommand takes no arguments. -.IP "\fBadd\fP" -Create a new FedFS domain root directory under -.I /.domainroot -and export it. -This subcommand takes a FedFS domain name as an argument. -.IP "\fBremove\fP" -Remove an existing FedFS domain root directory from -.IR /.domainroot . -This subcommand takes a FedFS domain name as an argument. -The user is asked to confirm before action is taken. -.IP -By default, this process stops when a step encounters an error. -Adding the -.B \-\-force -option forces the process to try each step even if an error occurs, -and bypasses the confirmation request. -.SS Command line options -The following options are specified before the subcommand on the command line. -.IP "\fB\-h, \-\-help" -Display usage and copyright information, then exit. -.IP "\fB\-\-version" -Display fedfs-utils version information, then exit. -.IP "\fB\-\-silent" -Process quietly. -.IP "\fB\-\-statedir=\fIstate-directory\fP" -Find FedFS domain root directories on the local system in the -.I domainroots -subdirectory of the specified directory. -By default, the state directory is -.IR @statedir . -.SH EXIT CODES -The -.BR fedfs-domainroot (8) -command returns one of two values upon exit. -.TP -.B 0 -The requested subcommand succeeded. -.TP -.B 1 -The requested subcommand failed. -.SH EXAMPLES -Suppose you are the FedFS administrator of the -.I example.net -FedFS domain. -After you have chosen a reliable NFS fileserver to serve your -FedFS domain root directory, log in on that fileserver as root -and ensure that NFSD is running. -.P -To create a new FedFS domain root for the -.I example.net -domain, use: -.RS -.sp -# fedfs-domainroot --silent add example.net -.br -Added domain root for FedFS domain "example.net" -.br -# -.sp -.RE -To populate the new domain root, change your current directory to -.IR /.domainroot/example.net , -then add junctions with the -.BR nfsref (8) -command on the fileserver. -.P -You can list the domain roots that are currently exported -by your fileserver with: -.RS -.sp -# fedfs-domainroot --silent status -.br -FedFS domain roots: -.br - example.net is exported with options - *(ro,subtree_check,mp,insecure,sec=sys:none) -.br -# -.sp -.RE -When you want to remove this domain root (say, because you have -moved it to another fileserver), remove it's contents, then use: -.RS -.sp -# fedfs-domainroot remove example.net -.br -Removed domain root for FedFS domain "example.net" -.br -# -.RE -.SH DOMAIN ROOT DISCOVERY -To enable discovery of new domain roots -by FedFS-enabled file-access clients, -a DNS SRV record must be added to an appropriate authoritative DNS server. -.P -If you created your domain root on the fileserver named -.IR foo.example.net , -a record for the above domain root should be added to the DNS -server authoritative for the -.I example.net -domain. -Such a record might look like -.RS -.sp - _nfs-domainroot._tcp IN SRV 0 0 2049 foo.example.net. -.sp -.RE -Adding DNS SRV records is outside the scope of the -.BR fedfs-domainroot (8) -command. -Consult with your network administrator for details -on how to add appropriate DNS SRV records for your FedFS domain root. -.SH SECURITY -FedFS domain root exports created by -.BR fedfs-domainroot (8) -are exported with -.BR *(ro,insecure,subtree_check,sec=sys:none) . -FedFS standards recommend that -FedFS domain root directories should be globally readable. -Specific access restrictions typically occur lower in a domain's name space. -.P -However, fileserver administrators can alter -a domain root export's security settings -by editing a domain root export's entry in -.IR /etc/exports , -and then refreshing the kernel's export cache with -.BR "exportfs -r" . -.P -For example, if the domain root fileserver has Kerberos configured, -an administrator might change a domain root export's -.B sec= -option to -.BR sec=krb5p:krb5i:krb5:sys:none . -Or, to restrict the range of clients that can access the -domain root, an administrator might replace the leading -.B * -with a specific netgroup or IP network designation. -.P -It is recommended to keep the -.B subtree_check -export option. -Refer to -.BR exports (5) -for details. -.SH FILES -.TP -.I @statedir@/domainroots -directory containing domain root directories -.TP -.I /.domainroot -directory containing domain root exports -.SH "SEE ALSO" -.BR fedfs (7), -.BR nfsref (8), -.BR rpc.fedfsd (8), -.BR exportfs (8), -.BR exports (5) -.sp -RFC 6641 for the specification of FedFS DNS SRV records -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/fedfs-domainroot.8.in b/doc/man/fedfs-domainroot.8.in new file mode 100644 index 0000000..d0c3e0a --- /dev/null +++ b/doc/man/fedfs-domainroot.8.in @@ -0,0 +1,322 @@ +.\"@(#)fedfs-domainroot.8" +.\" +.\" @file doc/man/fedfs-domainroot.8 +.\" @brief man page for fedfs-domainroot tool +.\" + +.\" +.\" Copyright 2013 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH FEDFS-DOMAINROOT 8 "@pubdate@" +.SH NAME +fedfs-domainroot \- set up FedFS domain root infrastructure +.SH SYNOPSIS +.B fedfs-domainroot +.RB [ \-h ", " \-\-help ] +.RB [ \-\-version ] +.P +.B fedfs-domainroot +.RB [ \-\-silent ] +.RB [ \-\-statedir = +.IR statedir ] +.B add +.I domainname +.P +.B fedfs-domainroot +.RB [ \-\-silent ] +.RB [ \-\-statedir = +.IR statedir ] +.B remove +.I domainname +.RB [ \-\-force ] +.P +.B fedfs-domainroot +.RB [ \-\-silent ] +.RB [ \-\-statedir = +.IR statedir ] +.B status +.P +.B fedfs-domainroot +.RB [ \-\-silent ] +.RB [ \-\-statedir = +.IR statedir ] +.B clean +.RB [ \-\-force ] +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +The top directory of a FedFS domain namespace is known as a +.I domain root +directory. +FedFS-enabled clients discover the fileserver that exports +a FedFS domain's root directory using a DNS SRV query. +Using a well-known export path, +clients then mount the domain root directory +on that fileserver in the normal fashion. +.P +After a filesystem client mounts a domain's root directory, +applications on that client descend into the domain's name space +starting in that directory, +and are directed transparently to exports on other fileservers. +.P +Further information about domain roots is available in +.BR fedfs (7). +.P +.SH DESCRIPTION +A single fileserver may host domain root directories +for one or more FedFS domains. +The +.BR fedfs-domainroot (8) +command is a convenient way to securely manage domain root exports +on a Linux NFS fileserver. +FedFS itself is agnostic about the underlying file-access protocol, +but the +.BR fedfs-domainroot (8) +command supports only NFS at this time. +.P +FedFS domain root directories are exported using a standard well-known +pathname to make it simple for clients to find them. +The first component of the domain root's export pathname is always +.IR /.domainroot . +The second component is a FedFS domain name. +.P +For instance, the export pathname of the domain root of the +.I example.net +FedFS domain is +.IR /.domainroot/example.net . +.SS Operation +The +.B add +subcommand creates a directory under +.I @statedir@/domainroots +where the contents of the domain root directory reside. +A directory is also set up under +.I /.domainroot +for each doman root directory. +.BR fedfs-domainroot (8) +bind-mounts the domain root directory under +.I @statedir@/domainroots, +then exports the directory under +.IR /.domainroot . +.P +In this way, each domain root directory is exported via a well-known pathname, +and can have its own export settings separate from other domain root directories, +including security settings and client and network designations. +These can be modified by editing +.I /etc/exports +after the +domain root export is created. +.P +The +.BR fedfs-domainroot (8) +command must run as root in order to create and remove NFS exports +and entries in +.IR /etc/fstab . +.SS Subcommands +Valid +.BR fedfs-domainroot (8) +subcommands are: +.IP "\fBclean\fP" +Remove the +.I /.domainroot +directory and other infrastructure (as long as it is empty). +The user is asked to confirm before action is taken. +.IP +By default, this process stops when a step encounters an error. +Adding the +.B \-\-force +option forces the process to try each step even if an error occurs, +and bypasses the confirmation request. +.IP "\fBstatus\fP" +Display the status of the domain root infrastructure on the local system. +This includes whether NFSD is running, and what domain root directories +are currently configured and exported. +This subcommand takes no arguments. +.IP "\fBadd\fP" +Create a new FedFS domain root directory under +.I /.domainroot +and export it. +This subcommand takes a FedFS domain name as an argument. +.IP "\fBremove\fP" +Remove an existing FedFS domain root directory from +.IR /.domainroot . +This subcommand takes a FedFS domain name as an argument. +The user is asked to confirm before action is taken. +.IP +By default, this process stops when a step encounters an error. +Adding the +.B \-\-force +option forces the process to try each step even if an error occurs, +and bypasses the confirmation request. +.SS Command line options +The following options are specified before the subcommand on the command line. +.IP "\fB\-h, \-\-help" +Display usage and copyright information, then exit. +.IP "\fB\-\-version" +Display fedfs-utils version information, then exit. +.IP "\fB\-\-silent" +Process quietly. +.IP "\fB\-\-statedir=\fIstate-directory\fP" +Find FedFS domain root directories on the local system in the +.I domainroots +subdirectory of the specified directory. +By default, the state directory is +.IR @statedir@ . +.SH EXIT CODES +The +.BR fedfs-domainroot (8) +command returns one of two values upon exit. +.TP +.B 0 +The requested subcommand succeeded. +.TP +.B 1 +The requested subcommand failed. +.SH EXAMPLES +Suppose you are the FedFS administrator of the +.I example.net +FedFS domain. +After you have chosen a reliable NFS fileserver to serve your +FedFS domain root directory, log in on that fileserver as root +and ensure that NFSD is running. +.P +To create a new FedFS domain root for the +.I example.net +domain, use: +.RS +.sp +# fedfs-domainroot --silent add example.net +.br +Added domain root for FedFS domain "example.net" +.br +# +.sp +.RE +To populate the new domain root, change your current directory to +.IR /.domainroot/example.net , +then add junctions with the +.BR nfsref (8) +command on the fileserver. +.P +You can list the domain roots that are currently exported +by your fileserver with: +.RS +.sp +# fedfs-domainroot --silent status +.br +FedFS domain roots: +.br + example.net is exported with options + *(ro,subtree_check,mp,insecure,sec=sys:none) +.br +# +.sp +.RE +When you want to remove this domain root (say, because you have +moved it to another fileserver), remove it's contents, then use: +.RS +.sp +# fedfs-domainroot remove example.net +.br +Removed domain root for FedFS domain "example.net" +.br +# +.RE +.SH DOMAIN ROOT DISCOVERY +To enable discovery of new domain roots +by FedFS-enabled file-access clients, +a DNS SRV record must be added to an appropriate authoritative DNS server. +.P +If you created your domain root on the fileserver named +.IR foo.example.net , +a record for the above domain root should be added to the DNS +server authoritative for the +.I example.net +domain. +Such a record might look like +.RS +.sp + _nfs-domainroot._tcp IN SRV 0 0 2049 foo.example.net. +.sp +.RE +Adding DNS SRV records is outside the scope of the +.BR fedfs-domainroot (8) +command. +Consult with your network administrator for details +on how to add appropriate DNS SRV records for your FedFS domain root. +.SH SECURITY +FedFS domain root exports created by +.BR fedfs-domainroot (8) +are exported with +.BR *(ro,insecure,subtree_check,sec=sys:none) . +FedFS standards recommend that +FedFS domain root directories should be globally readable. +Specific access restrictions typically occur lower in a domain's name space. +.P +However, fileserver administrators can alter +a domain root export's security settings +by editing a domain root export's entry in +.IR /etc/exports , +and then refreshing the kernel's export cache with +.BR "exportfs -r" . +.P +For example, if the domain root fileserver has Kerberos configured, +an administrator might change a domain root export's +.B sec= +option to +.BR sec=krb5p:krb5i:krb5:sys:none . +Or, to restrict the range of clients that can access the +domain root, an administrator might replace the leading +.B * +with a specific netgroup or IP network designation. +.P +It is recommended to keep the +.B subtree_check +export option. +Refer to +.BR exports (5) +for details. +.SH FILES +.TP +.I @statedir@/domainroots +directory containing domain root directories +.TP +.I /.domainroot +directory containing domain root exports +.SH "SEE ALSO" +.BR fedfs (7), +.BR nfsref (8), +.BR rpc.fedfsd (8), +.BR exportfs (8), +.BR exports (5) +.sp +RFC 6641 for the specification of FedFS DNS SRV records +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/fedfs-get-limited-nsdb-params.8 b/doc/man/fedfs-get-limited-nsdb-params.8 deleted file mode 100644 index c81fc3f..0000000 --- a/doc/man/fedfs-get-limited-nsdb-params.8 +++ /dev/null @@ -1,194 +0,0 @@ -.\"@(#)fedfs-get-limited-nsdb-params.8" -.\" -.\" @file doc/man/fedfs-get-limited-nsdb-params.8 -.\" @brief man page for fedfs-get-limited-nsdb-params client command -.\" - -.\" -.\" Copyright 2011, 2013 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH FEDFS-GET-LIMITED-NSDB-PARAMS 8 "@publication-date@" -.SH NAME -fedfs-get-limited-nsdb-params \- send a FEDFS_GET_LIMITED_NSDB_PARAMS ADMIN protocol request -.SH SYNOPSIS -.B fedfs-get-limited-nsdb-params -.RB [ \-?d ] -.RB [ \-n -.IR nettype ] -.RB [ \-h -.IR hostname ] -.RB [ \-l -.IR nsdbname ] -.RB [ \-r -.IR nsdbport ] -.RB [ \-s -.IR security ] -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -FedFS-enabled file servers allow remote administrative access via an -authenticated RPC protocol known as the -.IR "FedFS ADMIN protocol" . -Using this protocol, FedFS administrators manage -FedFS junctions and NSDB connection parameter information -on remote FedFS-enabled file servers. -.SH DESCRIPTION -The -.BR fedfs-get-limited-nsdb-params (8) -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_GET_LIMITED_NSDB_PARAMS request to a remote -FedFS ADMIN protocol service. -It is similar to the -.BR fedfs-get-nsdb-params (8) -command, but cannot retrieve an X.509 certificate. -.P -The FEDFS_GET_LIMITED_NSDB_PARAMS request retrieves NSDB connection -parameter information stored on a remote server. -For more on the specification and use of NSDB connection parameters, see -.BR nsdbparams "(8) or" -.BR fedfs (7). -.P -An NSDB hostname and port number (see below) are -are used as the primary key to identify an entry -in the remote server's NSDB connection parameter database. -The NSDB connection parameter database -matches NSDB hostnames and ports by exact value. -In other words, -if two unique hostnames point -to the IP address of the same physical NSDB, -they are still considered separate entries -in the local NSDB connection parameter database. -.SH OPTIONS -.IP "\fB\-d, \-\-debug" -Enables debugging messages during operation. -.IP "\fB\-?, \-\-help" -Displays -.BR fedfs-get-limited-nsdb-params (8) -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 -.BR localhost . -.IP "\fB\-n, \-\-nettype=\fInettype\fP" -Specifies the transport to use when contacting the remote FedFS ADMIN service. -Typically the -.I nettype -is one of -.B tcp -or -.BR udp . -If this option is not specified, the default value is -.BR netpath . -See -.BR rpc (3t) -for details. -.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" -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 \-\-nsdbname -option is not specified, the -.BR fedfs-get-limited-nsdb-params (8) -command fails. -.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" -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\-s, \-\-security=\fIflavor\fP" -Specifies the security flavor to use -when contacting the remote FedFS ADMIN service. -Valid flavors are -.BR sys , -.BR unix , -.BR krb5 , -.BR krb5i ", and" -.BR krb5p . -If this option is not specified, the -.B unix -flavor is used. -See the -.B SECURITY -section of this man page for details. -.SH EXAMPLES -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 . -If the file server -.IR fs.example.net -already knows about your domain's NSDB, you can query it with: -.RS -.sp -$ fedfs-get-limited-nsdb-params -h fs.example.net -l nsdb.example.net -.br -Call completed successfully -.br -ConnectionSec: FEDFS_SEC_NONE -.sp -.RE -The remote server knows about -.I nsdb.example.net -and does not use TLS when querying it to resolve junctions. -.SH SECURITY -By default, or if the -.B sys -and -.B unix -flavors are specified with the -.BI \-\-security= flavor -option, the -.BR fedfs-create-junction (8) -command uses AUTH_SYS security for the Remote Procedure Call. -AUTH_SYS has known weaknesses and should be avoided on untrusted networks. -.P -The RPC client uses the Kerberos v5 GSS mechanism -if a Kerberos security flavor is specified. -When specifying a Kerberos security flavor, -the user must first obtain a valid Kerberos ticket using -.BR kinit (1) -before running -.BR fedfs-create-junction (8). -.P -The AUTH_NONE security flavor is no longer supported by this implementation. -.SH "SEE ALSO" -.BR fedfs (7), -.BR rpc.fedfsd (8), -.BR fedfs-get-nsdb-params (8), -.BR nsdbparams (8), -.BR kinit (1), -.BR rpc (3t) -.sp -RFC 5716 for FedFS requirements and overview -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/fedfs-get-limited-nsdb-params.8.in b/doc/man/fedfs-get-limited-nsdb-params.8.in new file mode 100644 index 0000000..f36913f --- /dev/null +++ b/doc/man/fedfs-get-limited-nsdb-params.8.in @@ -0,0 +1,194 @@ +.\"@(#)fedfs-get-limited-nsdb-params.8" +.\" +.\" @file doc/man/fedfs-get-limited-nsdb-params.8 +.\" @brief man page for fedfs-get-limited-nsdb-params client command +.\" + +.\" +.\" Copyright 2011, 2013 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH FEDFS-GET-LIMITED-NSDB-PARAMS 8 "@pubdate@" +.SH NAME +fedfs-get-limited-nsdb-params \- send a FEDFS_GET_LIMITED_NSDB_PARAMS ADMIN protocol request +.SH SYNOPSIS +.B fedfs-get-limited-nsdb-params +.RB [ \-?d ] +.RB [ \-n +.IR nettype ] +.RB [ \-h +.IR hostname ] +.RB [ \-l +.IR nsdbname ] +.RB [ \-r +.IR nsdbport ] +.RB [ \-s +.IR security ] +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +FedFS-enabled file servers allow remote administrative access via an +authenticated RPC protocol known as the +.IR "FedFS ADMIN protocol" . +Using this protocol, FedFS administrators manage +FedFS junctions and NSDB connection parameter information +on remote FedFS-enabled file servers. +.SH DESCRIPTION +The +.BR fedfs-get-limited-nsdb-params (8) +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_GET_LIMITED_NSDB_PARAMS request to a remote +FedFS ADMIN protocol service. +It is similar to the +.BR fedfs-get-nsdb-params (8) +command, but cannot retrieve an X.509 certificate. +.P +The FEDFS_GET_LIMITED_NSDB_PARAMS request retrieves NSDB connection +parameter information stored on a remote server. +For more on the specification and use of NSDB connection parameters, see +.BR nsdbparams "(8) or" +.BR fedfs (7). +.P +An NSDB hostname and port number (see below) are +are used as the primary key to identify an entry +in the remote server's NSDB connection parameter database. +The NSDB connection parameter database +matches NSDB hostnames and ports by exact value. +In other words, +if two unique hostnames point +to the IP address of the same physical NSDB, +they are still considered separate entries +in the local NSDB connection parameter database. +.SH OPTIONS +.IP "\fB\-d, \-\-debug" +Enables debugging messages during operation. +.IP "\fB\-?, \-\-help" +Displays +.BR fedfs-get-limited-nsdb-params (8) +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 +.BR localhost . +.IP "\fB\-n, \-\-nettype=\fInettype\fP" +Specifies the transport to use when contacting the remote FedFS ADMIN service. +Typically the +.I nettype +is one of +.B tcp +or +.BR udp . +If this option is not specified, the default value is +.BR netpath . +See +.BR rpc (3t) +for details. +.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" +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 \-\-nsdbname +option is not specified, the +.BR fedfs-get-limited-nsdb-params (8) +command fails. +.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" +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\-s, \-\-security=\fIflavor\fP" +Specifies the security flavor to use +when contacting the remote FedFS ADMIN service. +Valid flavors are +.BR sys , +.BR unix , +.BR krb5 , +.BR krb5i ", and" +.BR krb5p . +If this option is not specified, the +.B unix +flavor is used. +See the +.B SECURITY +section of this man page for details. +.SH EXAMPLES +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 . +If the file server +.IR fs.example.net +already knows about your domain's NSDB, you can query it with: +.RS +.sp +$ fedfs-get-limited-nsdb-params -h fs.example.net -l nsdb.example.net +.br +Call completed successfully +.br +ConnectionSec: FEDFS_SEC_NONE +.sp +.RE +The remote server knows about +.I nsdb.example.net +and does not use TLS when querying it to resolve junctions. +.SH SECURITY +By default, or if the +.B sys +and +.B unix +flavors are specified with the +.BI \-\-security= flavor +option, the +.BR fedfs-create-junction (8) +command uses AUTH_SYS security for the Remote Procedure Call. +AUTH_SYS has known weaknesses and should be avoided on untrusted networks. +.P +The RPC client uses the Kerberos v5 GSS mechanism +if a Kerberos security flavor is specified. +When specifying a Kerberos security flavor, +the user must first obtain a valid Kerberos ticket using +.BR kinit (1) +before running +.BR fedfs-create-junction (8). +.P +The AUTH_NONE security flavor is no longer supported by this implementation. +.SH "SEE ALSO" +.BR fedfs (7), +.BR rpc.fedfsd (8), +.BR fedfs-get-nsdb-params (8), +.BR nsdbparams (8), +.BR kinit (1), +.BR rpc (3t) +.sp +RFC 5716 for FedFS requirements and overview +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/fedfs-get-nsdb-params.8 b/doc/man/fedfs-get-nsdb-params.8 deleted file mode 100644 index 1f8826d..0000000 --- a/doc/man/fedfs-get-nsdb-params.8 +++ /dev/null @@ -1,196 +0,0 @@ -.\"@(#)fedfs-get-nsdb-params.8" -.\" -.\" @file doc/man/fedfs-get-nsdb-params.8 -.\" @brief man page for fedfs-get-nsdb-params client command -.\" - -.\" -.\" Copyright 2011, 2013 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH FEDFS-GET-NSDB-PARAMS 8 "@publication-date@" -.SH NAME -fedfs-get-nsdb-params \- send a FEDFS_GET_NSDB_PARAMS ADMIN protocol request -.SH SYNOPSIS -.B fedfs-get-nsdb-params -.RB [ \-?d ] -.RB [ \-f -.IR certfile ] -.RB [ \-n -.IR nettype ] -.RB [ \-h -.IR hostname ] -.RB [ \-l -.IR nsdbname ] -.RB [ \-r -.IR nsdbport ] -.RB [ \-s -.IR security ] -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -FedFS-enabled file servers allow remote administrative access via an -authenticated RPC protocol known as the -.IR "FedFS ADMIN protocol" . -Using this protocol, FedFS administrators manage -FedFS junctions and NSDB connection parameter information -on remote FedFS-enabled file servers. -.SH DESCRIPTION -The -.BR fedfs-get-nsdb-params (8) -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_GET_NSDB_PARAMS request to a remote -FedFS ADMIN protocol service. -.P -The FEDFS_GET_NSDB_PARAMS request retrieves -NSDB connection parameter information stored on a remote server. -For more on the specification and use of NSDB connection parameters, see -.BR nsdbparams "(8) or" -.BR fedfs (7). -.P -An NSDB hostname and port number (see below) -are used as the primary key to identify an entry -in the remote server's NSDB connection parameter database. -Details on NSDB connection parameter database entry matching can be -found in -.BR nsdb-parameters (7). -.SH OPTIONS -.IP "\fB\-d, \-\-debug" -Enables debugging messages during operation. -.IP "\fB\-?, \-\-help" -Displays -.BR fedfs-get-nsdb-params (8) -version information and a usage message on -.IR stderr . -.IP "\fB-f, \-\-certfile=\fIpathname\fP" -Specifies the pathname of a local file to write received certificate -material into, when the specified NSDB's connection security type is -.BR TLS . -If no file is specified, the certificate is ignored. -The certificate is written to the specified file in PEM format. -.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 -.BR localhost . -.IP "\fB\-n, \-\-nettype=\fInettype\fP" -Specifies the transport to use when contacting the remote FedFS ADMIN service. -Typically the -.I nettype -is one of -.B tcp -or -.BR udp . -If this option is not specified, the default value is -.BR netpath . -See -.BR rpc (3t) -for details. -.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" -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 \-\-nsdbname -option is not specified, the -.BR fedfs-get-nsdb-params (8) -command fails. -.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" -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\-s, \-\-security=\fIflavor\fP" -Specifies the security flavor to use -when contacting the remote FedFS ADMIN service. -Valid flavors are -.BR sys , -.BR unix , -.BR krb5 , -.BR krb5i ", and" -.BR krb5p . -If this option is not specified, the -.B unix -flavor is used. -See the -.B SECURITY -section of this man page for details. -.SH EXAMPLES -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 . -If the file server -.IR fs.example.net -already knows about your domain's NSDB, you can query it with: -.RS -.sp -$ fedfs-get-nsdb-params -h fs.example.net -l nsdb.example.net -.br -Call completed successfully -.br -ConnectionSec: FEDFS_SEC_NONE -.sp -.RE -The remote server knows about -.I nsdb.example.net -and does not use TLS when querying it to resolve junctions. -.SH SECURITY -By default, or if the -.B sys -and -.B unix -flavors are specified with the -.BI \-\-security= flavor -option, the -.BR fedfs-create-junction (8) -command uses AUTH_SYS security for the Remote Procedure Call. -AUTH_SYS has known weaknesses and should be avoided on untrusted networks. -.P -The RPC client uses the Kerberos v5 GSS mechanism -if a Kerberos security flavor is specified. -When specifying a Kerberos security flavor, -the user must first obtain a valid Kerberos ticket using -.BR kinit (1) -before running -.BR fedfs-create-junction (8). -.P -The AUTH_NONE security flavor is no longer supported by this implementation. -.SH "SEE ALSO" -.BR fedfs (7), -.BR nsdb-parameters (7), -.BR rpc.fedfsd (8), -.BR fedfs-get-nsdb-limited-params (8), -.BR nsdbparams (8), -.BR kinit (1), -.BR rpc (3t) -.sp -RFC 5716 for FedFS requirements and overview -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/fedfs-get-nsdb-params.8.in b/doc/man/fedfs-get-nsdb-params.8.in new file mode 100644 index 0000000..5e7ee7e --- /dev/null +++ b/doc/man/fedfs-get-nsdb-params.8.in @@ -0,0 +1,196 @@ +.\"@(#)fedfs-get-nsdb-params.8" +.\" +.\" @file doc/man/fedfs-get-nsdb-params.8 +.\" @brief man page for fedfs-get-nsdb-params client command +.\" + +.\" +.\" Copyright 2011, 2013 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH FEDFS-GET-NSDB-PARAMS 8 "@pubdate@" +.SH NAME +fedfs-get-nsdb-params \- send a FEDFS_GET_NSDB_PARAMS ADMIN protocol request +.SH SYNOPSIS +.B fedfs-get-nsdb-params +.RB [ \-?d ] +.RB [ \-f +.IR certfile ] +.RB [ \-n +.IR nettype ] +.RB [ \-h +.IR hostname ] +.RB [ \-l +.IR nsdbname ] +.RB [ \-r +.IR nsdbport ] +.RB [ \-s +.IR security ] +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +FedFS-enabled file servers allow remote administrative access via an +authenticated RPC protocol known as the +.IR "FedFS ADMIN protocol" . +Using this protocol, FedFS administrators manage +FedFS junctions and NSDB connection parameter information +on remote FedFS-enabled file servers. +.SH DESCRIPTION +The +.BR fedfs-get-nsdb-params (8) +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_GET_NSDB_PARAMS request to a remote +FedFS ADMIN protocol service. +.P +The FEDFS_GET_NSDB_PARAMS request retrieves +NSDB connection parameter information stored on a remote server. +For more on the specification and use of NSDB connection parameters, see +.BR nsdbparams "(8) or" +.BR fedfs (7). +.P +An NSDB hostname and port number (see below) +are used as the primary key to identify an entry +in the remote server's NSDB connection parameter database. +Details on NSDB connection parameter database entry matching can be +found in +.BR nsdb-parameters (7). +.SH OPTIONS +.IP "\fB\-d, \-\-debug" +Enables debugging messages during operation. +.IP "\fB\-?, \-\-help" +Displays +.BR fedfs-get-nsdb-params (8) +version information and a usage message on +.IR stderr . +.IP "\fB-f, \-\-certfile=\fIpathname\fP" +Specifies the pathname of a local file to write received certificate +material into, when the specified NSDB's connection security type is +.BR TLS . +If no file is specified, the certificate is ignored. +The certificate is written to the specified file in PEM format. +.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 +.BR localhost . +.IP "\fB\-n, \-\-nettype=\fInettype\fP" +Specifies the transport to use when contacting the remote FedFS ADMIN service. +Typically the +.I nettype +is one of +.B tcp +or +.BR udp . +If this option is not specified, the default value is +.BR netpath . +See +.BR rpc (3t) +for details. +.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" +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 \-\-nsdbname +option is not specified, the +.BR fedfs-get-nsdb-params (8) +command fails. +.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" +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\-s, \-\-security=\fIflavor\fP" +Specifies the security flavor to use +when contacting the remote FedFS ADMIN service. +Valid flavors are +.BR sys , +.BR unix , +.BR krb5 , +.BR krb5i ", and" +.BR krb5p . +If this option is not specified, the +.B unix +flavor is used. +See the +.B SECURITY +section of this man page for details. +.SH EXAMPLES +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 . +If the file server +.IR fs.example.net +already knows about your domain's NSDB, you can query it with: +.RS +.sp +$ fedfs-get-nsdb-params -h fs.example.net -l nsdb.example.net +.br +Call completed successfully +.br +ConnectionSec: FEDFS_SEC_NONE +.sp +.RE +The remote server knows about +.I nsdb.example.net +and does not use TLS when querying it to resolve junctions. +.SH SECURITY +By default, or if the +.B sys +and +.B unix +flavors are specified with the +.BI \-\-security= flavor +option, the +.BR fedfs-create-junction (8) +command uses AUTH_SYS security for the Remote Procedure Call. +AUTH_SYS has known weaknesses and should be avoided on untrusted networks. +.P +The RPC client uses the Kerberos v5 GSS mechanism +if a Kerberos security flavor is specified. +When specifying a Kerberos security flavor, +the user must first obtain a valid Kerberos ticket using +.BR kinit (1) +before running +.BR fedfs-create-junction (8). +.P +The AUTH_NONE security flavor is no longer supported by this implementation. +.SH "SEE ALSO" +.BR fedfs (7), +.BR nsdb-parameters (7), +.BR rpc.fedfsd (8), +.BR fedfs-get-nsdb-limited-params (8), +.BR nsdbparams (8), +.BR kinit (1), +.BR rpc (3t) +.sp +RFC 5716 for FedFS requirements and overview +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/fedfs-lookup-junction.8 b/doc/man/fedfs-lookup-junction.8 deleted file mode 100644 index 60cc595..0000000 --- a/doc/man/fedfs-lookup-junction.8 +++ /dev/null @@ -1,230 +0,0 @@ -.\"@(#)fedfs-lookup-junction.8" -.\" -.\" @file doc/man/fedfs-lookup-junction.8 -.\" @brief man page for fedfs-lookup-junction client command -.\" - -.\" -.\" Copyright 2011, 2013 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH FEDFS-LOOKUP-JUNCTION 8 "@publication-date@" -.SH NAME -fedfs-lookup-junction \- send a FEDFS_LOOKUP_JUNCTION ADMIN protocol request -.SH SYNOPSIS -.B fedfs-lookup-junction -.RB [ \-?d ] -.RB [ \-n -.IR nettype ] -.RB [ \-h -.IR hostname ] -.RB [ \-s -.IR security ] -.RB [ \-t -.IR resolvetype ] -.I path -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -FedFS-enabled file servers allow remote administrative access via an -authenticated RPC protocol known as the -.IR "FedFS ADMIN protocol" . -Using this protocol, FedFS administrators manage -FedFS junctions and NSDB connection parameter information -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 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 -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 -.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). -.P -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 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 in the junction. -Not all FedFS ADMIN service implementations support this type of request. -.TP -.B nsdb -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 in the junction. -.SH OPTIONS -.IP "\fB\-d, \-\-debug" -Enables debugging messages during operation. -.IP "\fB\-?, \-\-help" -Displays -.BR fedfs-lookup-junction (8) -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 -.BR localhost . -.IP "\fB\-n, \-\-nettype=\fInettype\fP" -Specifies the transport to use when contacting the remote FedFS ADMIN service. -Typically the -.I nettype -is one of -.B tcp -or -.BR udp . -If this option is not specified, the default value is -.BR netpath . -See -.BR rpc (3t) -for details. -.IP "\fB\-p, \-\-path=\fIpathname\fP" -Specifies the location on the remote server where the target FedFS junction -resides. -This pathname is relative to the remote server's physical root directory, -not the remote server's NFS pseudoroot. -.IP "\fB\-t, \-\-resolvetype=\fItype\fP" -Specifies the desired type of resolution. Valid values for -.I type -are -.BR 0 , -.BR none , -.BR fedfs_resolve_none , -.BR 1 , -.BR cache , -.BR fedfs_resolve_cache , -.BR 2 , -.BR nsdb ", or" -.BR fedfs_resolve_nsdb . -The value is not case-sensitive. -If this option is not specified, the default value is -.BR none . -.IP "\fB\-s, \-\-security=\fIflavor\fP" -Specifies the security flavor to use -when contacting the remote FedFS ADMIN service. -Valid flavors are -.BR sys , -.BR unix , -.BR krb5 , -.BR krb5i ", and" -.BR krb5p . -If this option is not specified, the -.B unix -flavor is used. -See the -.B SECURITY -section of this man page for details. -.SH EXAMPLES -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 junction on remote server -.IR fs.example.net . -To see how the junction appears on the file server, use: -.RS -.sp -$ fedfs-lookup-junction -h fs.example.net /export/junction1 -.br -Call completed successfully -.br -FSN UUID: 89c6d208-7280-11e0-9f1d-000c297fd679 -.br -NSDB: nsdb.example.net:389 -.sp -.RE -To see real-time junction lookup results as the remote server sees them, use: -.RS -.sp -$ 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 file server, -but the domain's NSDB has not yet been updated to contain a list of -fileset locations for the FSN UUID contained in the junction. -The file server is therefore not able to resolve the junction. -.SH SECURITY -By default, or if the -.B sys -and -.B unix -flavors are specified with the -.BI \-\-security= flavor -option, the -.BR fedfs-create-junction (8) -command uses AUTH_SYS security for the Remote Procedure Call. -AUTH_SYS has known weaknesses and should be avoided on untrusted networks. -.P -The RPC client uses the Kerberos v5 GSS mechanism -if a Kerberos security flavor is specified. -When specifying a Kerberos security flavor, -the user must first obtain a valid Kerberos ticket using -.BR kinit (1) -before running -.BR fedfs-create-junction (8). -.P -The AUTH_NONE security flavor is no longer supported by this implementation. -.SH "SEE ALSO" -.BR fedfs (7), -.BR rpc.fedfsd (8), -.BR kinit (1), -.BR rpc (3t) -.sp -RFC 5716 for FedFS requirements and overview -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/fedfs-lookup-junction.8.in b/doc/man/fedfs-lookup-junction.8.in new file mode 100644 index 0000000..c140288 --- /dev/null +++ b/doc/man/fedfs-lookup-junction.8.in @@ -0,0 +1,230 @@ +.\"@(#)fedfs-lookup-junction.8" +.\" +.\" @file doc/man/fedfs-lookup-junction.8 +.\" @brief man page for fedfs-lookup-junction client command +.\" + +.\" +.\" Copyright 2011, 2013 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH FEDFS-LOOKUP-JUNCTION 8 "@pubdate@" +.SH NAME +fedfs-lookup-junction \- send a FEDFS_LOOKUP_JUNCTION ADMIN protocol request +.SH SYNOPSIS +.B fedfs-lookup-junction +.RB [ \-?d ] +.RB [ \-n +.IR nettype ] +.RB [ \-h +.IR hostname ] +.RB [ \-s +.IR security ] +.RB [ \-t +.IR resolvetype ] +.I path +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +FedFS-enabled file servers allow remote administrative access via an +authenticated RPC protocol known as the +.IR "FedFS ADMIN protocol" . +Using this protocol, FedFS administrators manage +FedFS junctions and NSDB connection parameter information +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 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 +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 +.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). +.P +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 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 in the junction. +Not all FedFS ADMIN service implementations support this type of request. +.TP +.B nsdb +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 in the junction. +.SH OPTIONS +.IP "\fB\-d, \-\-debug" +Enables debugging messages during operation. +.IP "\fB\-?, \-\-help" +Displays +.BR fedfs-lookup-junction (8) +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 +.BR localhost . +.IP "\fB\-n, \-\-nettype=\fInettype\fP" +Specifies the transport to use when contacting the remote FedFS ADMIN service. +Typically the +.I nettype +is one of +.B tcp +or +.BR udp . +If this option is not specified, the default value is +.BR netpath . +See +.BR rpc (3t) +for details. +.IP "\fB\-p, \-\-path=\fIpathname\fP" +Specifies the location on the remote server where the target FedFS junction +resides. +This pathname is relative to the remote server's physical root directory, +not the remote server's NFS pseudoroot. +.IP "\fB\-t, \-\-resolvetype=\fItype\fP" +Specifies the desired type of resolution. Valid values for +.I type +are +.BR 0 , +.BR none , +.BR fedfs_resolve_none , +.BR 1 , +.BR cache , +.BR fedfs_resolve_cache , +.BR 2 , +.BR nsdb ", or" +.BR fedfs_resolve_nsdb . +The value is not case-sensitive. +If this option is not specified, the default value is +.BR none . +.IP "\fB\-s, \-\-security=\fIflavor\fP" +Specifies the security flavor to use +when contacting the remote FedFS ADMIN service. +Valid flavors are +.BR sys , +.BR unix , +.BR krb5 , +.BR krb5i ", and" +.BR krb5p . +If this option is not specified, the +.B unix +flavor is used. +See the +.B SECURITY +section of this man page for details. +.SH EXAMPLES +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 junction on remote server +.IR fs.example.net . +To see how the junction appears on the file server, use: +.RS +.sp +$ fedfs-lookup-junction -h fs.example.net /export/junction1 +.br +Call completed successfully +.br +FSN UUID: 89c6d208-7280-11e0-9f1d-000c297fd679 +.br +NSDB: nsdb.example.net:389 +.sp +.RE +To see real-time junction lookup results as the remote server sees them, use: +.RS +.sp +$ 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 file server, +but the domain's NSDB has not yet been updated to contain a list of +fileset locations for the FSN UUID contained in the junction. +The file server is therefore not able to resolve the junction. +.SH SECURITY +By default, or if the +.B sys +and +.B unix +flavors are specified with the +.BI \-\-security= flavor +option, the +.BR fedfs-create-junction (8) +command uses AUTH_SYS security for the Remote Procedure Call. +AUTH_SYS has known weaknesses and should be avoided on untrusted networks. +.P +The RPC client uses the Kerberos v5 GSS mechanism +if a Kerberos security flavor is specified. +When specifying a Kerberos security flavor, +the user must first obtain a valid Kerberos ticket using +.BR kinit (1) +before running +.BR fedfs-create-junction (8). +.P +The AUTH_NONE security flavor is no longer supported by this implementation. +.SH "SEE ALSO" +.BR fedfs (7), +.BR rpc.fedfsd (8), +.BR kinit (1), +.BR rpc (3t) +.sp +RFC 5716 for FedFS requirements and overview +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/fedfs-lookup-replication.8 b/doc/man/fedfs-lookup-replication.8 deleted file mode 100644 index 898fdbc..0000000 --- a/doc/man/fedfs-lookup-replication.8 +++ /dev/null @@ -1,228 +0,0 @@ -.\"@(#)fedfs-lookup-replication.8" -.\" -.\" @file doc/man/fedfs-lookup-replication.8 -.\" @brief man page for fedfs-lookup-replication client command -.\" - -.\" -.\" Copyright 2011, 2013 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH FEDFS-LOOKUP-REPLICATION 8 "@publication-date@" -.SH NAME -fedfs-lookup-replication \- send a FEDFS_LOOKUP_REPLICATION ADMIN protocol request -.SH SYNOPSIS -.B fedfs-lookup-replication -.RB [ \-?d ] -.RB [ \-n -.IR nettype ] -.RB [ \-h -.IR hostname ] -.RB [ \-s -.IR security ] -.RB [ \-t -.IR resolvetype ] -.I path -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -FedFS-enabled file servers allow remote administrative access via an -authenticated RPC protocol known as the -.IR "FedFS ADMIN protocol" . -Using this protocol, FedFS administrators manage -FedFS junctions and NSDB connection parameter information -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 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 -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 -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). -.P -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 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 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 lookup, -and the results are returned. -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" -Enables debugging messages during operation. -.IP "\fB\-?, \-\-help" -Displays -.BR fedfs-lookup-replication (8) -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 -.BR localhost . -.IP "\fB\-n, \-\-nettype=\fInettype\fP" -Specifies the transport to use when contacting the remote FedFS ADMIN service. -Typically the -.I nettype -is one of -.B tcp -or -.BR udp . -If this option is not specified, the default value is -.BR netpath . -See -.BR rpc (3t) -for details. -.IP "\fB\-p, \-\-path=\fIpathname\fP" -Specifies the location on the remote server where the target FedFS replication -resides. -This pathname is relative to the remote server's physical root directory, -not the remote server's NFS pseudoroot. -.IP "\fB\-t, \-\-resolvetype=\fItype\fP" -Specifies the desired type of resolution. Valid values for -.I type -are -.BR 0 , -.BR none , -.BR fedfs_resolve_none , -.BR 1 , -.BR cache , -.BR fedfs_resolve_cache , -.BR 2 , -.BR nsdb ", or" -.BR fedfs_resolve_nsdb . -The value is not case-sensitive. -If this option is not specified, the default value is -.BR none . -.IP "\fB\-s, \-\-security=\fIflavor\fP" -Specifies the security flavor to use -when contacting the remote FedFS ADMIN service. -Valid flavors are -.BR sys , -.BR unix , -.BR krb5 , -.BR krb5i ", and" -.BR krb5p . -If this option is not specified, the -.B unix -flavor is used. -See the -.B SECURITY -section of this man page for details. -.SH EXAMPLES -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 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 /export/replication1 -.br -Call completed successfully -.br -FSN UUID: 89c6d208-7280-11e0-9f1d-000c297fd679 -.br -NSDB: nsdb.example.net:389 -.sp -.RE -To see real-time replication resolution results as the remote server sees them, use: -.RS -.sp -$ 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 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 UUID contained in the replication marker. -The file server is therefore not able to resolve the replication. -.SH SECURITY -By default, or if the -.B sys -and -.B unix -flavors are specified with the -.BI \-\-security= flavor -option, the -.BR fedfs-create-junction (8) -command uses AUTH_SYS security for the Remote Procedure Call. -AUTH_SYS has known weaknesses and should be avoided on untrusted networks. -.P -The RPC client uses the Kerberos v5 GSS mechanism -if a Kerberos security flavor is specified. -When specifying a Kerberos security flavor, -the user must first obtain a valid Kerberos ticket using -.BR kinit (1) -before running -.BR fedfs-create-junction (8). -.P -The AUTH_NONE security flavor is no longer supported by this implementation. -.SH "SEE ALSO" -.BR fedfs (7), -.BR rpc.fedfsd (8), -.BR kinit (1), -.BR rpc (3t) -.sp -RFC 5716 for FedFS requirements and overview -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/fedfs-lookup-replication.8.in b/doc/man/fedfs-lookup-replication.8.in new file mode 100644 index 0000000..710e257 --- /dev/null +++ b/doc/man/fedfs-lookup-replication.8.in @@ -0,0 +1,228 @@ +.\"@(#)fedfs-lookup-replication.8" +.\" +.\" @file doc/man/fedfs-lookup-replication.8 +.\" @brief man page for fedfs-lookup-replication client command +.\" + +.\" +.\" Copyright 2011, 2013 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH FEDFS-LOOKUP-REPLICATION 8 "@pubdate@" +.SH NAME +fedfs-lookup-replication \- send a FEDFS_LOOKUP_REPLICATION ADMIN protocol request +.SH SYNOPSIS +.B fedfs-lookup-replication +.RB [ \-?d ] +.RB [ \-n +.IR nettype ] +.RB [ \-h +.IR hostname ] +.RB [ \-s +.IR security ] +.RB [ \-t +.IR resolvetype ] +.I path +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +FedFS-enabled file servers allow remote administrative access via an +authenticated RPC protocol known as the +.IR "FedFS ADMIN protocol" . +Using this protocol, FedFS administrators manage +FedFS junctions and NSDB connection parameter information +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 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 +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 +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). +.P +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 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 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 lookup, +and the results are returned. +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" +Enables debugging messages during operation. +.IP "\fB\-?, \-\-help" +Displays +.BR fedfs-lookup-replication (8) +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 +.BR localhost . +.IP "\fB\-n, \-\-nettype=\fInettype\fP" +Specifies the transport to use when contacting the remote FedFS ADMIN service. +Typically the +.I nettype +is one of +.B tcp +or +.BR udp . +If this option is not specified, the default value is +.BR netpath . +See +.BR rpc (3t) +for details. +.IP "\fB\-p, \-\-path=\fIpathname\fP" +Specifies the location on the remote server where the target FedFS replication +resides. +This pathname is relative to the remote server's physical root directory, +not the remote server's NFS pseudoroot. +.IP "\fB\-t, \-\-resolvetype=\fItype\fP" +Specifies the desired type of resolution. Valid values for +.I type +are +.BR 0 , +.BR none , +.BR fedfs_resolve_none , +.BR 1 , +.BR cache , +.BR fedfs_resolve_cache , +.BR 2 , +.BR nsdb ", or" +.BR fedfs_resolve_nsdb . +The value is not case-sensitive. +If this option is not specified, the default value is +.BR none . +.IP "\fB\-s, \-\-security=\fIflavor\fP" +Specifies the security flavor to use +when contacting the remote FedFS ADMIN service. +Valid flavors are +.BR sys , +.BR unix , +.BR krb5 , +.BR krb5i ", and" +.BR krb5p . +If this option is not specified, the +.B unix +flavor is used. +See the +.B SECURITY +section of this man page for details. +.SH EXAMPLES +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 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 /export/replication1 +.br +Call completed successfully +.br +FSN UUID: 89c6d208-7280-11e0-9f1d-000c297fd679 +.br +NSDB: nsdb.example.net:389 +.sp +.RE +To see real-time replication resolution results as the remote server sees them, use: +.RS +.sp +$ 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 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 UUID contained in the replication marker. +The file server is therefore not able to resolve the replication. +.SH SECURITY +By default, or if the +.B sys +and +.B unix +flavors are specified with the +.BI \-\-security= flavor +option, the +.BR fedfs-create-junction (8) +command uses AUTH_SYS security for the Remote Procedure Call. +AUTH_SYS has known weaknesses and should be avoided on untrusted networks. +.P +The RPC client uses the Kerberos v5 GSS mechanism +if a Kerberos security flavor is specified. +When specifying a Kerberos security flavor, +the user must first obtain a valid Kerberos ticket using +.BR kinit (1) +before running +.BR fedfs-create-junction (8). +.P +The AUTH_NONE security flavor is no longer supported by this implementation. +.SH "SEE ALSO" +.BR fedfs (7), +.BR rpc.fedfsd (8), +.BR kinit (1), +.BR rpc (3t) +.sp +RFC 5716 for FedFS requirements and overview +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/fedfs-map-nfs4.8 b/doc/man/fedfs-map-nfs4.8 deleted file mode 100644 index 3046605..0000000 --- a/doc/man/fedfs-map-nfs4.8 +++ /dev/null @@ -1,181 +0,0 @@ -.\"@(#)fedfs-map-nfs4.8" -.\" -.\" @file doc/man/fedfs-map-nfs4.8 -.\" @brief man page for fedfs-map-nfs4 command -.\" - -.\" -.\" Copyright 2011, 2013 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH FEDFS-MAP-NFS4 8 "@publication-date@" -.SH NAME -fedfs-map-nfs4 \- generate automounter program map entries for FedFS -.SH SYNOPSIS -.B fedfs-map-nfs4 -.I domainname -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.SH DESCRIPTION -The -.BR fedfs-map-nfs4 (8) -command provides a FedFS program map for the local system's automounter. -Although it is typically intended to be invoked by the automounter, -it is also safe to invoke directly for scripting or debugging purposes. -See -.BR autofs (5) -for information about how program maps work. -.SS Operation -The -.BR fedfs-map-nfs4 (8) -command locates FedFS domains by looking for DNS SRV records -that advertise file servers exporting FedFS domain root replicas. -The -.I domainname -argument determines what FedFS domain is to be mounted. -.P -It retrieves and sorts the domain root replica records -according to SRV record sorting rules outlined in RFC 2782. -It then generates a sun format map entry on -.I stdout -representing the set of servers contained in the SRV record, -a standard export path to the domain root, -and appropriate NFS mount options. -Error messages are output on -.IR stderr . -.SS Globally useful names -Across all FedFS-enabled file system clients, -a unique file object in a FedFS domain is always accessed -via the same pathname. -Such pathnames are referred to as -.IR "globally useful names" . -See -.BR fedfs (7) -for a full discussion. -.P -The top-level directory of a globally useful name is always -the networked file system type (NFS version 4, CIFS, and so on). -A -.BR fedfs-map-nfs4 (8) -program map entry is used with the NFS version 4 top-level directory -to provide globally useful names via the NFS version 4 protocol. -.SH EXAMPLES -Typically, a -.BR fedfs-map-nfs4 (8) -entry in -.I /etc/auto.master -looks like this: -.RS -.sp -/nfs4 /usr/sbin/fedfs-map-nfs4 -.sp -.RE -Under the /nfs4 directory on the local system, the automounter uses -.BR fedfs-map-nfs4 (8) -to convert a FedFS domain name to a set of servers and an export path, -which are then passed to -.BR mount.nfs (8). -The automounter mounts this FedFS domain on the directory -.IR /nfs4/domainname . -.P -After configuring and restarting -.BR autofs , -to access files in the -.I example.net -FedFS domain, for instance, you can start with: -.RS -.sp -$ cd /nfs4/example.net -.sp -.RE -The automounter uses the -.BR fedfs-map-nfs4 (8) -command to look up the file servers that provide the domain root for the -.I example.net -domain. It then mounts one of these servers on -.IR /nfs4/example.net . -.P -If the -.BR fedfs-map-nfs4 (8) -command cannot find the requested domain, no local directory is created -and no mount operation is performed. Applications receive an ENOENT -error in this case. -.P -While these mounted domains remain active on the local system, -the mounted-on directories remain visible. -After a period of inactivity, the automounter automatically unmounts -a FedFS domain. -.P -Local applications browsing the top-level directory -do not see all available FedFS domains. They see only the ones that -are mounted and active. -.SS Mount option inheritance -The Linux NFS client treats an NFS referral -as a server-initiated mount request. -The referring fileserver provides only a list of server names and export paths. -The mount options for this new mount are inherited from the new mount -point's parent directory on the client. -.P -As applications proceed deeper into a domain's namespace, -they can encounter both file sets to which they have -read-only access, and file sets to which they have read-write -access. -To allow applications proper access to both types of file sets, -typically file-access clients mount domain root directories in read-write mode. -All submounts of the domain root are then mounted read-write as well. -Write access is controlled by fileservers. -.P -For example, a domain root may contain an NFS version 4 referral to an -export containing user home directories. -The domain root may be exported read-only so file-access clients cannot update it, -but user home directories would not be very useful if they could not be -written to by their owners. -The fileserver continues to employ user credentials to limit access -as appropriate. -.P -Network file system clients follow file system referrals -as applications encounter them, -which is similar to how an automounter works. -Consider the initial mount of the domain root -as if you are mounting a single whole file system, -even though underneath, additional NFS mounts come and go as needed. -.SH FILES -.TP 18n -.I /etc/auto.master -master automounter map -.SH "SEE ALSO" -.BR fedfs (7), -.BR nfs (5), -.BR autofs (5), -.sp -RFC 2782 for a discussion of DNS SRV records -.sp -RFC 5716 for FedFS requirements and overview -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/fedfs-map-nfs4.8.in b/doc/man/fedfs-map-nfs4.8.in new file mode 100644 index 0000000..87fe28f --- /dev/null +++ b/doc/man/fedfs-map-nfs4.8.in @@ -0,0 +1,181 @@ +.\"@(#)fedfs-map-nfs4.8" +.\" +.\" @file doc/man/fedfs-map-nfs4.8 +.\" @brief man page for fedfs-map-nfs4 command +.\" + +.\" +.\" Copyright 2011, 2013 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH FEDFS-MAP-NFS4 8 "@pubdate@" +.SH NAME +fedfs-map-nfs4 \- generate automounter program map entries for FedFS +.SH SYNOPSIS +.B fedfs-map-nfs4 +.I domainname +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.SH DESCRIPTION +The +.BR fedfs-map-nfs4 (8) +command provides a FedFS program map for the local system's automounter. +Although it is typically intended to be invoked by the automounter, +it is also safe to invoke directly for scripting or debugging purposes. +See +.BR autofs (5) +for information about how program maps work. +.SS Operation +The +.BR fedfs-map-nfs4 (8) +command locates FedFS domains by looking for DNS SRV records +that advertise file servers exporting FedFS domain root replicas. +The +.I domainname +argument determines what FedFS domain is to be mounted. +.P +It retrieves and sorts the domain root replica records +according to SRV record sorting rules outlined in RFC 2782. +It then generates a sun format map entry on +.I stdout +representing the set of servers contained in the SRV record, +a standard export path to the domain root, +and appropriate NFS mount options. +Error messages are output on +.IR stderr . +.SS Globally useful names +Across all FedFS-enabled file system clients, +a unique file object in a FedFS domain is always accessed +via the same pathname. +Such pathnames are referred to as +.IR "globally useful names" . +See +.BR fedfs (7) +for a full discussion. +.P +The top-level directory of a globally useful name is always +the networked file system type (NFS version 4, CIFS, and so on). +A +.BR fedfs-map-nfs4 (8) +program map entry is used with the NFS version 4 top-level directory +to provide globally useful names via the NFS version 4 protocol. +.SH EXAMPLES +Typically, a +.BR fedfs-map-nfs4 (8) +entry in +.I /etc/auto.master +looks like this: +.RS +.sp +/nfs4 /usr/sbin/fedfs-map-nfs4 +.sp +.RE +Under the /nfs4 directory on the local system, the automounter uses +.BR fedfs-map-nfs4 (8) +to convert a FedFS domain name to a set of servers and an export path, +which are then passed to +.BR mount.nfs (8). +The automounter mounts this FedFS domain on the directory +.IR /nfs4/domainname . +.P +After configuring and restarting +.BR autofs , +to access files in the +.I example.net +FedFS domain, for instance, you can start with: +.RS +.sp +$ cd /nfs4/example.net +.sp +.RE +The automounter uses the +.BR fedfs-map-nfs4 (8) +command to look up the file servers that provide the domain root for the +.I example.net +domain. It then mounts one of these servers on +.IR /nfs4/example.net . +.P +If the +.BR fedfs-map-nfs4 (8) +command cannot find the requested domain, no local directory is created +and no mount operation is performed. Applications receive an ENOENT +error in this case. +.P +While these mounted domains remain active on the local system, +the mounted-on directories remain visible. +After a period of inactivity, the automounter automatically unmounts +a FedFS domain. +.P +Local applications browsing the top-level directory +do not see all available FedFS domains. They see only the ones that +are mounted and active. +.SS Mount option inheritance +The Linux NFS client treats an NFS referral +as a server-initiated mount request. +The referring fileserver provides only a list of server names and export paths. +The mount options for this new mount are inherited from the new mount +point's parent directory on the client. +.P +As applications proceed deeper into a domain's namespace, +they can encounter both file sets to which they have +read-only access, and file sets to which they have read-write +access. +To allow applications proper access to both types of file sets, +typically file-access clients mount domain root directories in read-write mode. +All submounts of the domain root are then mounted read-write as well. +Write access is controlled by fileservers. +.P +For example, a domain root may contain an NFS version 4 referral to an +export containing user home directories. +The domain root may be exported read-only so file-access clients cannot update it, +but user home directories would not be very useful if they could not be +written to by their owners. +The fileserver continues to employ user credentials to limit access +as appropriate. +.P +Network file system clients follow file system referrals +as applications encounter them, +which is similar to how an automounter works. +Consider the initial mount of the domain root +as if you are mounting a single whole file system, +even though underneath, additional NFS mounts come and go as needed. +.SH FILES +.TP 18n +.I /etc/auto.master +master automounter map +.SH "SEE ALSO" +.BR fedfs (7), +.BR nfs (5), +.BR autofs (5), +.sp +RFC 2782 for a discussion of DNS SRV records +.sp +RFC 5716 for FedFS requirements and overview +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/fedfs-null.8 b/doc/man/fedfs-null.8 deleted file mode 100644 index 028ba30..0000000 --- a/doc/man/fedfs-null.8 +++ /dev/null @@ -1,150 +0,0 @@ -.\"@(#)fedfs-null.8" -.\" -.\" @file doc/man/fedfs-null.8 -.\" @brief man page for fedfs-null client command -.\" - -.\" -.\" Copyright 2011, 2013 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH FEDFS-NULL 8 "@publication-date@" -.SH NAME -fedfs-null \- send a FEDFS_NULL ADMIN protocol request -.SH SYNOPSIS -.B fedfs-null -.RB [ \-?d ] -.RB [ \-n -.IR nettype ] -.RB [ \-h -.IR hostname ] -.RB [ \-s -.IR security ] -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -FedFS-enabled file servers allow remote administrative access via an -authenticated RPC protocol known as the -.IR "FedFS ADMIN protocol" . -Using this protocol, FedFS administrators manage -FedFS junctions and NSDB connection parameter information -on remote FedFS-enabled file servers. -.SH DESCRIPTION -The -.BR fedfs-null (8) -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_NULL request to a remote -FedFS ADMIN protocol service. -.P -The FEDFS_NULL request performs a simple ping operation that determines -if there is an operational FedFS ADMIN service on the remote server. -.SH OPTIONS -.IP "\fB\-d, \-\-debug" -Enables debugging messages during operation. -.IP "\fB\-?, \-\-help" -Displays -.BR fedfs-null (8) -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 -.BR localhost . -.IP "\fB\-n, \-\-nettype=\fInettype\fP" -Specifies the transport to use when contacting the remote FedFS ADMIN service. -Typically the -.I nettype -is one of -.B tcp -or -.BR udp . -If this option is not specified, the default value is -.BR netpath . -See -.BR rpc (3t) -for details. -.IP "\fB\-s, \-\-security=\fIflavor\fP" -Specifies the security flavor to use -when contacting the remote FedFS ADMIN service. -Valid flavors are -.BR sys , -.BR unix , -.BR krb5 , -.BR krb5i ", and" -.BR krb5p . -If this option is not specified, the -.B unix -flavor is used. -See the -.B SECURITY -section of this man page for details. -.SH EXAMPLES -Suppose you are the FedFS administrator of the -.I example.net -FedFS domain and that you want to know if the FedFS ADMIN service -on the file server -.IR fs.example.net -is operational. Use: -.RS -.sp -$ fedfs-null -h fs.example.net -.br -Call completed successfully -.RE -.SH SECURITY -By default, or if the -.B sys -and -.B unix -flavors are specified with the -.BI \-\-security= flavor -option, the -.BR fedfs-create-junction (8) -command uses AUTH_SYS security for the Remote Procedure Call. -AUTH_SYS has known weaknesses and should be avoided on untrusted networks. -.P -The RPC client uses the Kerberos v5 GSS mechanism -if a Kerberos security flavor is specified. -When specifying a Kerberos security flavor, -the user must first obtain a valid Kerberos ticket using -.BR kinit (1) -before running -.BR fedfs-create-junction (8). -.P -The AUTH_NONE security flavor is no longer supported by this implementation. -.SH "SEE ALSO" -.BR fedfs (7), -.BR rpc.fedfsd (8), -.BR kinit (1), -.BR rpc (3t) -.sp -RFC 5716 for FedFS requirements and overview -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/fedfs-null.8.in b/doc/man/fedfs-null.8.in new file mode 100644 index 0000000..5e02ac6 --- /dev/null +++ b/doc/man/fedfs-null.8.in @@ -0,0 +1,150 @@ +.\"@(#)fedfs-null.8" +.\" +.\" @file doc/man/fedfs-null.8 +.\" @brief man page for fedfs-null client command +.\" + +.\" +.\" Copyright 2011, 2013 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH FEDFS-NULL 8 "@pubdate@" +.SH NAME +fedfs-null \- send a FEDFS_NULL ADMIN protocol request +.SH SYNOPSIS +.B fedfs-null +.RB [ \-?d ] +.RB [ \-n +.IR nettype ] +.RB [ \-h +.IR hostname ] +.RB [ \-s +.IR security ] +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +FedFS-enabled file servers allow remote administrative access via an +authenticated RPC protocol known as the +.IR "FedFS ADMIN protocol" . +Using this protocol, FedFS administrators manage +FedFS junctions and NSDB connection parameter information +on remote FedFS-enabled file servers. +.SH DESCRIPTION +The +.BR fedfs-null (8) +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_NULL request to a remote +FedFS ADMIN protocol service. +.P +The FEDFS_NULL request performs a simple ping operation that determines +if there is an operational FedFS ADMIN service on the remote server. +.SH OPTIONS +.IP "\fB\-d, \-\-debug" +Enables debugging messages during operation. +.IP "\fB\-?, \-\-help" +Displays +.BR fedfs-null (8) +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 +.BR localhost . +.IP "\fB\-n, \-\-nettype=\fInettype\fP" +Specifies the transport to use when contacting the remote FedFS ADMIN service. +Typically the +.I nettype +is one of +.B tcp +or +.BR udp . +If this option is not specified, the default value is +.BR netpath . +See +.BR rpc (3t) +for details. +.IP "\fB\-s, \-\-security=\fIflavor\fP" +Specifies the security flavor to use +when contacting the remote FedFS ADMIN service. +Valid flavors are +.BR sys , +.BR unix , +.BR krb5 , +.BR krb5i ", and" +.BR krb5p . +If this option is not specified, the +.B unix +flavor is used. +See the +.B SECURITY +section of this man page for details. +.SH EXAMPLES +Suppose you are the FedFS administrator of the +.I example.net +FedFS domain and that you want to know if the FedFS ADMIN service +on the file server +.IR fs.example.net +is operational. Use: +.RS +.sp +$ fedfs-null -h fs.example.net +.br +Call completed successfully +.RE +.SH SECURITY +By default, or if the +.B sys +and +.B unix +flavors are specified with the +.BI \-\-security= flavor +option, the +.BR fedfs-create-junction (8) +command uses AUTH_SYS security for the Remote Procedure Call. +AUTH_SYS has known weaknesses and should be avoided on untrusted networks. +.P +The RPC client uses the Kerberos v5 GSS mechanism +if a Kerberos security flavor is specified. +When specifying a Kerberos security flavor, +the user must first obtain a valid Kerberos ticket using +.BR kinit (1) +before running +.BR fedfs-create-junction (8). +.P +The AUTH_NONE security flavor is no longer supported by this implementation. +.SH "SEE ALSO" +.BR fedfs (7), +.BR rpc.fedfsd (8), +.BR kinit (1), +.BR rpc (3t) +.sp +RFC 5716 for FedFS requirements and overview +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/fedfs-set-nsdb-params.8 b/doc/man/fedfs-set-nsdb-params.8 deleted file mode 100644 index 71bee9e..0000000 --- a/doc/man/fedfs-set-nsdb-params.8 +++ /dev/null @@ -1,200 +0,0 @@ -.\"@(#)fedfs-set-nsdb-params.8" -.\" -.\" @file doc/man/fedfs-set-nsdb-params.8 -.\" @brief man page for fedfs-set-nsdb-params client command -.\" - -.\" -.\" Copyright 2011, 2013 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH FEDFS-SET-NSDB-PARAMS 8 "@publication-date@" -.SH NAME -fedfs-set-nsdb-params \- send a FEDFS_SET_NSDB_PARAMS ADMIN protocol request -.SH SYNOPSIS -.B fedfs-set-nsdb-params -.RB [ \-?d ] -.RB [ \-n -.IR nettype ] -.RB [ \-h -.IR hostname ] -.RB [ \-f -.IR certfile ] -.RB [ \-l -.IR nsdbname ] -.RB [ \-r -.IR nsdbport ] -.RB [ \-s -.IR security ] -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -FedFS-enabled file servers allow remote administrative access via an -authenticated RPC protocol known as the -.IR "FedFS ADMIN protocol" . -Using this protocol, FedFS administrators manage -FedFS junctions and NSDB connection parameter information -on remote FedFS-enabled file servers. -.SH DESCRIPTION -The -.BR fedfs-set-nsdb-params (8) -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_SET_NSDB_PARAMS request to a remote -FedFS ADMIN protocol service. -.P -The FEDFS_SET_NSDB_PARAMS request updates -NSDB connection parameter information stored on a remote server. -For more on the specification and use of NSDB connection parameters, see -.BR nsdbparams "(8) or" -.BR fedfs (7). -.P -An NSDB hostname and port number (see below) -are used as the primary key to identify an entry -in the remote server's NSDB connection parameter database. -.P -The NSDB connection parameter database -matches NSDB hostnames and ports by exact value. -Details on NSDB connection parameters database entry matching can be -found in -.BR nsdb-parameters (7). -.SH OPTIONS -.IP "\fB\-d, \-\-debug" -Enables debugging messages during operation. -.IP "\fB\-?, \-\-help" -Displays -.BR fedfs-set-nsdb-params (8) -version information and a usage message on -.IR stderr . -.IP "\fB-f, \-\-certfile=\fIpathname\fP" -Specifies the pathname of a local file containing an x.509 certificate -the remote system can use to authenticate the specified NSDB node. -The specified file may be deleted after the command succeeds. -Details on the contents of this file can be found in -.BR nsdb-parameters (7). -.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 -.BR localhost . -.IP "\fB\-n, \-\-nettype=\fInettype\fP" -Specifies the transport to use when contacting the remote FedFS ADMIN service. -Typically the -.I nettype -is one of -.B tcp -or -.BR udp . -If this option is not specified, the default value is -.BR netpath . -See -.BR rpc (3t) -for details. -.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" -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 \-\-nsdbname -option is not specified, the -.BR fedfs-set-nsdb-params (8) -command fails. -.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" -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\-s, \-\-security=\fIflavor\fP" -Specifies the security flavor to use -when contacting the remote FedFS ADMIN service. -Valid flavors are -.BR sys , -.BR unix , -.BR krb5 , -.BR krb5i ", and" -.BR krb5p . -If this option is not specified, the -.B unix -flavor is used. -See the -.B SECURITY -section of this man page for details. -.SH EXAMPLES -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 . -If the file server -.IR fs.example.net -does not know about your NSDB, you can inform it with: -.RS -.sp -$ fedfs-set-nsdb-params -h fs.example.net -l nsdb.example.net -.br -Call completed successfully -.sp -.RE -The remote server -.I fs.example.net -now knows about the -.I nsdb.example.net -NSDB and can use it for resolving FedFS junctions. -It will not use TLS when querying the NSDB to resolve junctions. -.SH SECURITY -By default, or if the -.B sys -and -.B unix -flavors are specified with the -.BI \-\-security= flavor -option, the -.BR fedfs-create-junction (8) -command uses AUTH_SYS security for the Remote Procedure Call. -AUTH_SYS has known weaknesses and should be avoided on untrusted networks. -.P -The RPC client uses the Kerberos v5 GSS mechanism -if a Kerberos security flavor is specified. -When specifying a Kerberos security flavor, -the user must first obtain a valid Kerberos ticket using -.BR kinit (1) -before running -.BR fedfs-create-junction (8). -.P -The AUTH_NONE security flavor is no longer supported by this implementation. -.SH "SEE ALSO" -.BR fedfs (7), -.BR nsdb-parameters (7), -.BR rpc.fedfsd (8), -.BR fedfs-get-nsdb-params (8), -.BR nsdbparams (8), -.BR kinit (1), -.BR rpc (3t) -.sp -RFC 5716 for FedFS requirements and overview -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/fedfs-set-nsdb-params.8.in b/doc/man/fedfs-set-nsdb-params.8.in new file mode 100644 index 0000000..e13d66d --- /dev/null +++ b/doc/man/fedfs-set-nsdb-params.8.in @@ -0,0 +1,200 @@ +.\"@(#)fedfs-set-nsdb-params.8" +.\" +.\" @file doc/man/fedfs-set-nsdb-params.8 +.\" @brief man page for fedfs-set-nsdb-params client command +.\" + +.\" +.\" Copyright 2011, 2013 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH FEDFS-SET-NSDB-PARAMS 8 "@pubdate@" +.SH NAME +fedfs-set-nsdb-params \- send a FEDFS_SET_NSDB_PARAMS ADMIN protocol request +.SH SYNOPSIS +.B fedfs-set-nsdb-params +.RB [ \-?d ] +.RB [ \-n +.IR nettype ] +.RB [ \-h +.IR hostname ] +.RB [ \-f +.IR certfile ] +.RB [ \-l +.IR nsdbname ] +.RB [ \-r +.IR nsdbport ] +.RB [ \-s +.IR security ] +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +FedFS-enabled file servers allow remote administrative access via an +authenticated RPC protocol known as the +.IR "FedFS ADMIN protocol" . +Using this protocol, FedFS administrators manage +FedFS junctions and NSDB connection parameter information +on remote FedFS-enabled file servers. +.SH DESCRIPTION +The +.BR fedfs-set-nsdb-params (8) +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_SET_NSDB_PARAMS request to a remote +FedFS ADMIN protocol service. +.P +The FEDFS_SET_NSDB_PARAMS request updates +NSDB connection parameter information stored on a remote server. +For more on the specification and use of NSDB connection parameters, see +.BR nsdbparams "(8) or" +.BR fedfs (7). +.P +An NSDB hostname and port number (see below) +are used as the primary key to identify an entry +in the remote server's NSDB connection parameter database. +.P +The NSDB connection parameter database +matches NSDB hostnames and ports by exact value. +Details on NSDB connection parameters database entry matching can be +found in +.BR nsdb-parameters (7). +.SH OPTIONS +.IP "\fB\-d, \-\-debug" +Enables debugging messages during operation. +.IP "\fB\-?, \-\-help" +Displays +.BR fedfs-set-nsdb-params (8) +version information and a usage message on +.IR stderr . +.IP "\fB-f, \-\-certfile=\fIpathname\fP" +Specifies the pathname of a local file containing an x.509 certificate +the remote system can use to authenticate the specified NSDB node. +The specified file may be deleted after the command succeeds. +Details on the contents of this file can be found in +.BR nsdb-parameters (7). +.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 +.BR localhost . +.IP "\fB\-n, \-\-nettype=\fInettype\fP" +Specifies the transport to use when contacting the remote FedFS ADMIN service. +Typically the +.I nettype +is one of +.B tcp +or +.BR udp . +If this option is not specified, the default value is +.BR netpath . +See +.BR rpc (3t) +for details. +.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" +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 \-\-nsdbname +option is not specified, the +.BR fedfs-set-nsdb-params (8) +command fails. +.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" +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\-s, \-\-security=\fIflavor\fP" +Specifies the security flavor to use +when contacting the remote FedFS ADMIN service. +Valid flavors are +.BR sys , +.BR unix , +.BR krb5 , +.BR krb5i ", and" +.BR krb5p . +If this option is not specified, the +.B unix +flavor is used. +See the +.B SECURITY +section of this man page for details. +.SH EXAMPLES +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 . +If the file server +.IR fs.example.net +does not know about your NSDB, you can inform it with: +.RS +.sp +$ fedfs-set-nsdb-params -h fs.example.net -l nsdb.example.net +.br +Call completed successfully +.sp +.RE +The remote server +.I fs.example.net +now knows about the +.I nsdb.example.net +NSDB and can use it for resolving FedFS junctions. +It will not use TLS when querying the NSDB to resolve junctions. +.SH SECURITY +By default, or if the +.B sys +and +.B unix +flavors are specified with the +.BI \-\-security= flavor +option, the +.BR fedfs-create-junction (8) +command uses AUTH_SYS security for the Remote Procedure Call. +AUTH_SYS has known weaknesses and should be avoided on untrusted networks. +.P +The RPC client uses the Kerberos v5 GSS mechanism +if a Kerberos security flavor is specified. +When specifying a Kerberos security flavor, +the user must first obtain a valid Kerberos ticket using +.BR kinit (1) +before running +.BR fedfs-create-junction (8). +.P +The AUTH_NONE security flavor is no longer supported by this implementation. +.SH "SEE ALSO" +.BR fedfs (7), +.BR nsdb-parameters (7), +.BR rpc.fedfsd (8), +.BR fedfs-get-nsdb-params (8), +.BR nsdbparams (8), +.BR kinit (1), +.BR rpc (3t) +.sp +RFC 5716 for FedFS requirements and overview +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/fedfs.7 b/doc/man/fedfs.7 deleted file mode 100644 index 556f41a..0000000 --- a/doc/man/fedfs.7 +++ /dev/null @@ -1,272 +0,0 @@ -.\"@(#)fedfs.7" -.\" -.\" @file doc/man/fedfs.7 -.\" @brief Introductory material for FedFS users -.\" - -.\" -.\" Copyright 2011, 2013 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.\" -.TH FEDFS 7 "@publication-date@" -.SH NAME -fedfs \- The Linux Federated File System implementation -.SH DESCRIPTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple fileservers using -.IR "file system referrals" . -.P -A file system referral is like a symbolic link -to another file system share, -but it is not visible to applications. -It behaves like an automounted directory where a mount operation -is performed when an application first accesses that directory. -.P -Today, file system referral mechanisms exist -in several standard network file system protocols. -Because FedFS uses a mechanism already built in to standard network protocols, -using it does not require any change -to file system protocols or file-access client implementations. -.P -A sideband protocol, such as NIS, is also unnecessary. -File-access clients automatically share a common view -of the network file system namespace with no need for -individual configuration on each client. -.P -Currently, the Linux FedFS implementation supports only -NFS version 4 referrals. -More on NFS version 4 referrals can be found in RFC 5661. -FedFS may support other network file system protocols in the future. -.SH FEDFS DOMAIN OPERATION -A file system referral whose target is managed by FedFS is called a -.IR "FedFS junction" . -Junctions join separate fileserver shares into a single coherent -FedFS namespace. -On FedFS-enabled Linux fileservers, the -.BR rpc.fedfsd (8) -daemon and the -.BR nfsref (5) -command create and remove FedFS junctions. -.P -An independently administered FedFS namespace is referred to as a -.IR "FedFS domain" . -FedFS domains are file namespaces only. -They do not represent authentication or ID-mapping realms, for example. -FedFS-enabled file-access clients and fileservers are not members -of a particular FedFS domain and do not have -.I "a priori" -knowledge of what FedFS domains exist. -.P -The top-level directory of a FedFS domain is referred to as its -.IR "domain root" . -Domain roots typically contain nothing but FedFS junctions -and a few other directories. -Useful data is contained in other shares -which file-access clients discover by following FedFS junctions -in the domain root directory. -.P -Although FedFS junctions are stored on fileservers, -they are lightweight objects that contain little actual data. -The bulk of FedFS junction information in a FedFS domain -is stored on an LDAP server. -LDAP servers that store FedFS information are known as -.IR "namespace databases" , -or NSDBs, for short. -Any standard LDAP server can become an NSDB if it knows the FedFS schema -(the definitions of FedFS record types). -.SS Filesets -FedFS groups a set of directories in a server's physical file system namespace -into a single administrative unit called a -.IR fileset . -For NFS, a whole share might be considered a fileset. -A FedFS domain consists of one or more filesets, -a domain root, -and junction information stored on an NSDB node. -.P -To function as a FedFS fileset, -a set of directories must have a name unique in a FedFS domain, -and a set of locations where the file data is stored. -.P -A FedFS -.I fileset name -is a UUID and an NSDB domainname and port. -This information is also maintained in an LDAP record on the NSDB node. -.P -A FedFS -.I fileset location -is an LDAP record that describes the location -(the fileserver where it resides, and its export path) -of a copy of a fileset's data. -These records are children of the fileset name record for this fileset. -.P -A fileset can have multiple replicas. -Such a fileset has one FedFS fileset name, -and each replica of the fileset has an individual FedFS fileset location record. -.P -A FedFS junction contains only a FedFS fileset name. -A fileserver resolves a FedFS junction by performing an LDAP -query on the NSDB node named in the junction, -using the UUID named in the junction. -The NSDB node returns location information stored -in FedFS fileset location records -for that FedFS fileset name. -The fileserver returns this location information to file-access clients -it servers via a file system referral. -.P -On Linux NFS fileservers, -.BR rpc.mountd (8) -is the gateway through which the in-kernel NFS server performs -FedFS junction resolution. -.SS Discovering domain roots -As with other FedFS filesets, -copies of a domain root can exist on multiple fileservers. -These copies are known as -.IR "domain root replicas" . -.P -Rather than using junctions and information in an NSDB node, -FedFS-enabled file-access clients locate a domain's root by looking for -DNS SRV records that advertise fileservers exporting domain root replicas. -.P -Such clients typically mount FedFS domain roots in a standard place so that -files residing in a FedFS domain appear at the same location in the -file namespace on all file-access clients. -By convention, the top of the global FedFS namespace looks like this: -.RS -.sp -.RI / fstype / domainname -.sp -.RE -where -.I fstype -specifies a network file system protocol to use, and -.I domainname -specifies a FedFS domain. -Currently, the Linux FedFS implementation recognizes only -.B nfs4 -as a valid fstype. -.SS Globally Useful Names -On FedFS-enabled Linux file-access clients, -the automounter (via a program map) or the -.BR mount.fedfs (8) -command find and mount the root of a FedFS domain. -.P -Typically, file-access clients mount the FedFS namespace so that FedFS -pathnames appear the same on all clients. -Such pathnames are referred to as -.IR "globally useful names" , -since a globally useful name refers to exactly the same file object -on every file-access client in a FedFS domain. -.P -For example, the FedFS globally useful name -.I /nfs4/example.net -would be mounted on a local directory called -.I /nfs4/example.net -on all file-access clients, so that applications have the same view of the -.I example.net -domain namespace on all FedFS-enabled file-access clients. -.P -The Linux -.BR mount.fedfs (8) -command can attach anywhere in a file-access client's local file namespace -any directory in the FedFS namespace that client -has permission to access. -This can be useful to ensure local namespace compatibility in some cases, -or hide parts of the FedFS namespace for security purposes. -.P -However, it breaks cross-platform application interoperability -by presenting applications with multiple pathnames to the same file object. -Therefore it should be avoided. -.SH SECURITY -Each host in a FedFS domain plays one or more of the following roles, -each of which have different security requirements. -.IP "\fINSDB node\fP" -LDAP server that contains FedFS domain information -.IP "\fIFedFS fileserver\fP" -stores data accessible via a FedFS domain name space -.IP "\fIFedFS file-access client\fP" -accesses data in FedFS domain name spaces -.IP "\fIFedFS admin client\fP" -manages FedFS domain information -.P -The Linux FedFS implementation provides administrative tools -to manage FedFS fileset name and location records on an NSDB node. -Junction resolution uses anonymous LDAP search requests, and -administration takes place via authenticated LDAP modification requests. -.P -Fileservers and administrative clients use plaintext or TLS-secured -transports to perform junction lookups and administrative requests. -The Linux FedFS implementation provides tools for managing x.509 -certificates required for LDAP over TLS. -.P -FedFS junction objects are created on fileservers -by a side-band RPC protocol called the -.IR "FedFS ADMIN protocol" . -This protocol is separate from network file system protocols. -This allows FedFS to operate without modification to network file system protocols. -The protocol uses RPCSEC GSS to secure administrative requests. -.P -Since two separate protocols are involved -when administering junctions and filesets, -junctions are created on fileservers and -registered with the domain's NSDB node in two separate steps. -.SH SEE ALSO -.BR nsdb-parameters (7), -.BR nsdbparams (8), -.BR fedfs-map-nfs4 (8), -.BR mount.fedfs (8), -.BR rpc.fedfsd (8), -.BR rpc.mountd (8), -.BR fedfs-create-junction (8), -.BR fedfs-create-replication (8), -.BR fedfs-delete-junction (8), -.BR fedfs-delete-replication (8), -.BR fedfs-get-limited-nsdb-params (8), -.BR fedfs-get-nsdb-params (8), -.BR fedfs-lookup-junction (8), -.BR fedfs-lookup-replication (8), -.BR fedfs-null (8), -.BR fedfs-set-nsdb-params (8), -.BR nsdb-simple-nce (8), -.BR nsdb-annotate (8), -.BR nsdb-create-fsl (8), -.BR nsdb-create-fsn (8), -.BR nsdb-update-nci (8), -.BR nsdb-delete-fsl (8), -.BR nsdb-delete-fsn (8), -.BR nsdb-remove-nci (8), -.BR nsdb-describe (8), -.BR nsdb-list (8), -.BR nsdb-nces (8), -.BR nsdb-resolve-fsn (8), -.BR nsdb-update-fsl (8) -.sp -RFC 4510 for an introduction to LDAP -.sp -RFC 5661 for a description of NFS version 4 referrals -.sp -RFC 5716 for FedFS requirements and overview -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH AUTHOR -Chuck Lever diff --git a/doc/man/fedfs.7.in b/doc/man/fedfs.7.in new file mode 100644 index 0000000..80ac1cb --- /dev/null +++ b/doc/man/fedfs.7.in @@ -0,0 +1,272 @@ +.\"@(#)fedfs.7" +.\" +.\" @file doc/man/fedfs.7 +.\" @brief Introductory material for FedFS users +.\" + +.\" +.\" Copyright 2011, 2013 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.\" +.TH FEDFS 7 "@pubdate@" +.SH NAME +fedfs \- The Linux Federated File System implementation +.SH DESCRIPTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple fileservers using +.IR "file system referrals" . +.P +A file system referral is like a symbolic link +to another file system share, +but it is not visible to applications. +It behaves like an automounted directory where a mount operation +is performed when an application first accesses that directory. +.P +Today, file system referral mechanisms exist +in several standard network file system protocols. +Because FedFS uses a mechanism already built in to standard network protocols, +using it does not require any change +to file system protocols or file-access client implementations. +.P +A sideband protocol, such as NIS, is also unnecessary. +File-access clients automatically share a common view +of the network file system namespace with no need for +individual configuration on each client. +.P +Currently, the Linux FedFS implementation supports only +NFS version 4 referrals. +More on NFS version 4 referrals can be found in RFC 5661. +FedFS may support other network file system protocols in the future. +.SH FEDFS DOMAIN OPERATION +A file system referral whose target is managed by FedFS is called a +.IR "FedFS junction" . +Junctions join separate fileserver shares into a single coherent +FedFS namespace. +On FedFS-enabled Linux fileservers, the +.BR rpc.fedfsd (8) +daemon and the +.BR nfsref (5) +command create and remove FedFS junctions. +.P +An independently administered FedFS namespace is referred to as a +.IR "FedFS domain" . +FedFS domains are file namespaces only. +They do not represent authentication or ID-mapping realms, for example. +FedFS-enabled file-access clients and fileservers are not members +of a particular FedFS domain and do not have +.I "a priori" +knowledge of what FedFS domains exist. +.P +The top-level directory of a FedFS domain is referred to as its +.IR "domain root" . +Domain roots typically contain nothing but FedFS junctions +and a few other directories. +Useful data is contained in other shares +which file-access clients discover by following FedFS junctions +in the domain root directory. +.P +Although FedFS junctions are stored on fileservers, +they are lightweight objects that contain little actual data. +The bulk of FedFS junction information in a FedFS domain +is stored on an LDAP server. +LDAP servers that store FedFS information are known as +.IR "namespace databases" , +or NSDBs, for short. +Any standard LDAP server can become an NSDB if it knows the FedFS schema +(the definitions of FedFS record types). +.SS Filesets +FedFS groups a set of directories in a server's physical file system namespace +into a single administrative unit called a +.IR fileset . +For NFS, a whole share might be considered a fileset. +A FedFS domain consists of one or more filesets, +a domain root, +and junction information stored on an NSDB node. +.P +To function as a FedFS fileset, +a set of directories must have a name unique in a FedFS domain, +and a set of locations where the file data is stored. +.P +A FedFS +.I fileset name +is a UUID and an NSDB domainname and port. +This information is also maintained in an LDAP record on the NSDB node. +.P +A FedFS +.I fileset location +is an LDAP record that describes the location +(the fileserver where it resides, and its export path) +of a copy of a fileset's data. +These records are children of the fileset name record for this fileset. +.P +A fileset can have multiple replicas. +Such a fileset has one FedFS fileset name, +and each replica of the fileset has an individual FedFS fileset location record. +.P +A FedFS junction contains only a FedFS fileset name. +A fileserver resolves a FedFS junction by performing an LDAP +query on the NSDB node named in the junction, +using the UUID named in the junction. +The NSDB node returns location information stored +in FedFS fileset location records +for that FedFS fileset name. +The fileserver returns this location information to file-access clients +it servers via a file system referral. +.P +On Linux NFS fileservers, +.BR rpc.mountd (8) +is the gateway through which the in-kernel NFS server performs +FedFS junction resolution. +.SS Discovering domain roots +As with other FedFS filesets, +copies of a domain root can exist on multiple fileservers. +These copies are known as +.IR "domain root replicas" . +.P +Rather than using junctions and information in an NSDB node, +FedFS-enabled file-access clients locate a domain's root by looking for +DNS SRV records that advertise fileservers exporting domain root replicas. +.P +Such clients typically mount FedFS domain roots in a standard place so that +files residing in a FedFS domain appear at the same location in the +file namespace on all file-access clients. +By convention, the top of the global FedFS namespace looks like this: +.RS +.sp +.RI / fstype / domainname +.sp +.RE +where +.I fstype +specifies a network file system protocol to use, and +.I domainname +specifies a FedFS domain. +Currently, the Linux FedFS implementation recognizes only +.B nfs4 +as a valid fstype. +.SS Globally Useful Names +On FedFS-enabled Linux file-access clients, +the automounter (via a program map) or the +.BR mount.fedfs (8) +command find and mount the root of a FedFS domain. +.P +Typically, file-access clients mount the FedFS namespace so that FedFS +pathnames appear the same on all clients. +Such pathnames are referred to as +.IR "globally useful names" , +since a globally useful name refers to exactly the same file object +on every file-access client in a FedFS domain. +.P +For example, the FedFS globally useful name +.I /nfs4/example.net +would be mounted on a local directory called +.I /nfs4/example.net +on all file-access clients, so that applications have the same view of the +.I example.net +domain namespace on all FedFS-enabled file-access clients. +.P +The Linux +.BR mount.fedfs (8) +command can attach anywhere in a file-access client's local file namespace +any directory in the FedFS namespace that client +has permission to access. +This can be useful to ensure local namespace compatibility in some cases, +or hide parts of the FedFS namespace for security purposes. +.P +However, it breaks cross-platform application interoperability +by presenting applications with multiple pathnames to the same file object. +Therefore it should be avoided. +.SH SECURITY +Each host in a FedFS domain plays one or more of the following roles, +each of which have different security requirements. +.IP "\fINSDB node\fP" +LDAP server that contains FedFS domain information +.IP "\fIFedFS fileserver\fP" +stores data accessible via a FedFS domain name space +.IP "\fIFedFS file-access client\fP" +accesses data in FedFS domain name spaces +.IP "\fIFedFS admin client\fP" +manages FedFS domain information +.P +The Linux FedFS implementation provides administrative tools +to manage FedFS fileset name and location records on an NSDB node. +Junction resolution uses anonymous LDAP search requests, and +administration takes place via authenticated LDAP modification requests. +.P +Fileservers and administrative clients use plaintext or TLS-secured +transports to perform junction lookups and administrative requests. +The Linux FedFS implementation provides tools for managing x.509 +certificates required for LDAP over TLS. +.P +FedFS junction objects are created on fileservers +by a side-band RPC protocol called the +.IR "FedFS ADMIN protocol" . +This protocol is separate from network file system protocols. +This allows FedFS to operate without modification to network file system protocols. +The protocol uses RPCSEC GSS to secure administrative requests. +.P +Since two separate protocols are involved +when administering junctions and filesets, +junctions are created on fileservers and +registered with the domain's NSDB node in two separate steps. +.SH SEE ALSO +.BR nsdb-parameters (7), +.BR nsdbparams (8), +.BR fedfs-map-nfs4 (8), +.BR mount.fedfs (8), +.BR rpc.fedfsd (8), +.BR rpc.mountd (8), +.BR fedfs-create-junction (8), +.BR fedfs-create-replication (8), +.BR fedfs-delete-junction (8), +.BR fedfs-delete-replication (8), +.BR fedfs-get-limited-nsdb-params (8), +.BR fedfs-get-nsdb-params (8), +.BR fedfs-lookup-junction (8), +.BR fedfs-lookup-replication (8), +.BR fedfs-null (8), +.BR fedfs-set-nsdb-params (8), +.BR nsdb-simple-nce (8), +.BR nsdb-annotate (8), +.BR nsdb-create-fsl (8), +.BR nsdb-create-fsn (8), +.BR nsdb-update-nci (8), +.BR nsdb-delete-fsl (8), +.BR nsdb-delete-fsn (8), +.BR nsdb-remove-nci (8), +.BR nsdb-describe (8), +.BR nsdb-list (8), +.BR nsdb-nces (8), +.BR nsdb-resolve-fsn (8), +.BR nsdb-update-fsl (8) +.sp +RFC 4510 for an introduction to LDAP +.sp +RFC 5661 for a description of NFS version 4 referrals +.sp +RFC 5716 for FedFS requirements and overview +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH AUTHOR +Chuck Lever diff --git a/doc/man/mount.fedfs.8 b/doc/man/mount.fedfs.8 deleted file mode 100644 index 73558a7..0000000 --- a/doc/man/mount.fedfs.8 +++ /dev/null @@ -1,218 +0,0 @@ -.\"@(#)mount.fedfs.8" -.\" -.\" @file doc/man/mount.fedfs.8 -.\" @brief man page for mount.fedfs subcommand -.\" - -.\" -.\" Copyright 2011, 2013 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH MOUNT.FEDFS 8 "@publication-date@" -.SH NAME -mount.fedfs \- mount a FedFS domain root -.SH SYNOPSIS -.B mount.fedfs -.I remotedir localdir -.RB [ \-fhnrsvVw ] -.RB [ \-o -.IR options ] -.SH DESCRIPTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -The -.BR mount.fedfs (8) -command locates FedFS domains by looking for DNS SRV records -that advertise file servers exporting FedFS domain root replicas. -The -.I remotedir -argument determines what FedFS domain is mounted and -what network file system protocol is used. -.P -The -.BR mount.fedfs (8) -command sorts the list of available domain root replicas -according to the SRV record sorting rules outlined in RFC 2782. -It attempts to contact each file server -appearing in the SRV record list -until a mount request succeeds -or the end of the SRV record list is reached. -.SS Command line arguments -The first argument, -.IR remotedir , -is the -.I globally useful name -to mount. -Globally useful names are discussed in more detail in -.BR fedfs (7). -.P -The second argument, -.IR localdir , -specifies the local directory on which to mount the requested -FedFS globally useful name. -As with other file systems, -.I localdir -must exist on the client for a mount request to succeed. -.P -The -.BR mount.fedfs (8) -command converts the specified -.I remotedir -and -.I localdir -arguments, along with information obtained via DNS SRV queries, -to arguments suitable for a local mount request. -It then forks and execs the -appropriate file system mount subcommand (such as the -.BR mount.nfs (8) -subcommand) to mount the file server where the domain root resides. -.P -Because an unmodified file system mount subcommand -is used for the actual mount operation, -the file system's equivalent umount subcommand -is all that is required to unmount this mount point when it is -finished being used. -.SS Mount option inheritance -The Linux NFS client treats an NFS referral -as a server-initiated mount request. -The referring fileserver provides only a list of server names and export paths. -The mount options for this new mount are inherited from the new mount -point's parent directory on the client. -.P -As applications proceed deeper into a domain's namespace, -they can encounter both file sets to which they have -read-only access, and file sets to which they have read-write -access. -To allow applications proper access to both types of file sets, -typically file-access clients mount domain root directories in read-write mode. -All submounts of the domain root are then mounted read-write as well. -Write access is then controlled by fileservers. -.P -For example, a domain root may contain an NFS version 4 referral to an -export containing user home directories. -The domain root may be exported read-only so file-access clients cannot update it, -but user home directories would not be very useful if they could not be -written to by their owners. -The fileserver continues to employ user credentials to limit access -as appropriate. -.P -Network file system clients follow file system referrals -as applications encounter them, -which is similar to how an automounter works. -Consider the initial mount of the domain root -as if you are mounting a single whole file system, -even though underneath, additional NFS mounts come and go as needed. -.SS Options -.IP "\fB\-f, \-\-fake" -Fake mount. This option is ignored by -.BR mount.fedfs (8) -but is passed to the underlying file system mount subcommand. -.IP "\fB\-h, \-\-help\fP" -Print the -.BR mount.fedfs (8) -usage message and exit. -.IP "\fB\-n, \-\-no\-mtab\fP" -Do not update -.IR /etc/mtab . -This option is ignored by -.BR mount.fedfs (8) -but is passed to the underlying file system mount subcommand. -.IP "\fB\-o, \-\-options \fIoptions\fP" -Specify mount options for this mount point and all submounts. -These are ignored by -.BR mount.fedfs (8) -but are passed to the underlying file system mount subcommand. -For further details, refer to -.BR mount (8). -.IP "\fB\-r, \-\-ro, \-\-read\-only\fP" -Mount the domain root and all submounts read-only. -.IP "\fB\-s, \-\-sloppy\fP" -Tolerate unrecognized mount options. This is ignored by -.BR mount.fedfs (8) -but is passed to the underlying file system mount subcommand. -.IP "\fB\-v, \-\-verbose\fP" -Report more information during the mount process. -This affects -.BR mount.fedfs (8) -and is also passed to the underlying file system mount subcommand. -.IP "\fB\-V, \-\-version\fP" -Print version information for -.BR mount.fedfs(8) -and exit. -.IP "\fB\-w, \-\-rw, \-\-read-write\fP" -Mount the domain root and all submounts read-write. This is the default behavior. -.SH EXAMPLES -To mount the domain root of the -.I example.net -FedFS domain via NFS version 4 automatically, you might add this to your -.IR /etc/fstab : -.RS -.sp -/nfs4/example.net /nfs4/example.net fedfs defaults 0 0 -.sp -.RE -A FedFS domain root can also be mounted with a stand-alone invocation of -.BR mount (8): -.RS -.sp -# mount -t fedfs /nfs4/example.net /mnt/fedfs -.sp -.RE -This mounts the FedFS domain root for the -.I example.net -domain on the client's -.I /mnt/fedfs -directory. -A simple -.RS -.sp -# umount /mnt/fedfs -.sp -.RE -unmounts it when you are finished with it. -.SH FILES -.TP 18n -.I /etc/fstab -filesystem table -.TP -.I /etc/mtab -table of mounted file systems -.SH "SEE ALSO" -.BR fedfs (7), -.BR nfs (5), -.BR mount (8), -.BR mount.nfs (8) -.sp -RFC 2782 for a discussion of DNS SRV records -.sp -RFC 5661 for a description of NFS version 4 referrals -.sp -RFC 5716 for FedFS requirements and overview -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/mount.fedfs.8.in b/doc/man/mount.fedfs.8.in new file mode 100644 index 0000000..949f90a --- /dev/null +++ b/doc/man/mount.fedfs.8.in @@ -0,0 +1,218 @@ +.\"@(#)mount.fedfs.8" +.\" +.\" @file doc/man/mount.fedfs.8 +.\" @brief man page for mount.fedfs subcommand +.\" + +.\" +.\" Copyright 2011, 2013 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH MOUNT.FEDFS 8 "@pubdate@" +.SH NAME +mount.fedfs \- mount a FedFS domain root +.SH SYNOPSIS +.B mount.fedfs +.I remotedir localdir +.RB [ \-fhnrsvVw ] +.RB [ \-o +.IR options ] +.SH DESCRIPTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +The +.BR mount.fedfs (8) +command locates FedFS domains by looking for DNS SRV records +that advertise file servers exporting FedFS domain root replicas. +The +.I remotedir +argument determines what FedFS domain is mounted and +what network file system protocol is used. +.P +The +.BR mount.fedfs (8) +command sorts the list of available domain root replicas +according to the SRV record sorting rules outlined in RFC 2782. +It attempts to contact each file server +appearing in the SRV record list +until a mount request succeeds +or the end of the SRV record list is reached. +.SS Command line arguments +The first argument, +.IR remotedir , +is the +.I globally useful name +to mount. +Globally useful names are discussed in more detail in +.BR fedfs (7). +.P +The second argument, +.IR localdir , +specifies the local directory on which to mount the requested +FedFS globally useful name. +As with other file systems, +.I localdir +must exist on the client for a mount request to succeed. +.P +The +.BR mount.fedfs (8) +command converts the specified +.I remotedir +and +.I localdir +arguments, along with information obtained via DNS SRV queries, +to arguments suitable for a local mount request. +It then forks and execs the +appropriate file system mount subcommand (such as the +.BR mount.nfs (8) +subcommand) to mount the file server where the domain root resides. +.P +Because an unmodified file system mount subcommand +is used for the actual mount operation, +the file system's equivalent umount subcommand +is all that is required to unmount this mount point when it is +finished being used. +.SS Mount option inheritance +The Linux NFS client treats an NFS referral +as a server-initiated mount request. +The referring fileserver provides only a list of server names and export paths. +The mount options for this new mount are inherited from the new mount +point's parent directory on the client. +.P +As applications proceed deeper into a domain's namespace, +they can encounter both file sets to which they have +read-only access, and file sets to which they have read-write +access. +To allow applications proper access to both types of file sets, +typically file-access clients mount domain root directories in read-write mode. +All submounts of the domain root are then mounted read-write as well. +Write access is then controlled by fileservers. +.P +For example, a domain root may contain an NFS version 4 referral to an +export containing user home directories. +The domain root may be exported read-only so file-access clients cannot update it, +but user home directories would not be very useful if they could not be +written to by their owners. +The fileserver continues to employ user credentials to limit access +as appropriate. +.P +Network file system clients follow file system referrals +as applications encounter them, +which is similar to how an automounter works. +Consider the initial mount of the domain root +as if you are mounting a single whole file system, +even though underneath, additional NFS mounts come and go as needed. +.SS Options +.IP "\fB\-f, \-\-fake" +Fake mount. This option is ignored by +.BR mount.fedfs (8) +but is passed to the underlying file system mount subcommand. +.IP "\fB\-h, \-\-help\fP" +Print the +.BR mount.fedfs (8) +usage message and exit. +.IP "\fB\-n, \-\-no\-mtab\fP" +Do not update +.IR /etc/mtab . +This option is ignored by +.BR mount.fedfs (8) +but is passed to the underlying file system mount subcommand. +.IP "\fB\-o, \-\-options \fIoptions\fP" +Specify mount options for this mount point and all submounts. +These are ignored by +.BR mount.fedfs (8) +but are passed to the underlying file system mount subcommand. +For further details, refer to +.BR mount (8). +.IP "\fB\-r, \-\-ro, \-\-read\-only\fP" +Mount the domain root and all submounts read-only. +.IP "\fB\-s, \-\-sloppy\fP" +Tolerate unrecognized mount options. This is ignored by +.BR mount.fedfs (8) +but is passed to the underlying file system mount subcommand. +.IP "\fB\-v, \-\-verbose\fP" +Report more information during the mount process. +This affects +.BR mount.fedfs (8) +and is also passed to the underlying file system mount subcommand. +.IP "\fB\-V, \-\-version\fP" +Print version information for +.BR mount.fedfs(8) +and exit. +.IP "\fB\-w, \-\-rw, \-\-read-write\fP" +Mount the domain root and all submounts read-write. This is the default behavior. +.SH EXAMPLES +To mount the domain root of the +.I example.net +FedFS domain via NFS version 4 automatically, you might add this to your +.IR /etc/fstab : +.RS +.sp +/nfs4/example.net /nfs4/example.net fedfs defaults 0 0 +.sp +.RE +A FedFS domain root can also be mounted with a stand-alone invocation of +.BR mount (8): +.RS +.sp +# mount -t fedfs /nfs4/example.net /mnt/fedfs +.sp +.RE +This mounts the FedFS domain root for the +.I example.net +domain on the client's +.I /mnt/fedfs +directory. +A simple +.RS +.sp +# umount /mnt/fedfs +.sp +.RE +unmounts it when you are finished with it. +.SH FILES +.TP 18n +.I /etc/fstab +filesystem table +.TP +.I /etc/mtab +table of mounted file systems +.SH "SEE ALSO" +.BR fedfs (7), +.BR nfs (5), +.BR mount (8), +.BR mount.nfs (8) +.sp +RFC 2782 for a discussion of DNS SRV records +.sp +RFC 5661 for a description of NFS version 4 referrals +.sp +RFC 5716 for FedFS requirements and overview +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/nfsref.8 b/doc/man/nfsref.8 deleted file mode 100644 index b3a3f25..0000000 --- a/doc/man/nfsref.8 +++ /dev/null @@ -1,273 +0,0 @@ -.\"@(#)nfsref.8" -.\" -.\" @file doc/man/nfsref.8 -.\" @brief man page for nfsref command -.\" - -.\" -.\" Copyright 2011 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH NFSREF 8 "@publication-date@" -.SH NAME -nfsref \- manage NFS referrals -.SH SYNOPSIS -.B nfsref -.RB [ \-?d ] -.RB [ \-t -.IB type ] -.B add -.I pathname server export -.RI [ " server" -.IR export " ... ]" -.P -.B nfsref -.RB [ \-?d ] -.RB [ \-t -.IB type ] -.B remove -.I pathname -.P -.B nfsref -.RB [ \-?d ] -.RB [ \-t -.IB type ] -.B lookup -.I pathname -.SH INTRODUCTION -NFS version 4 introduces the concept of -.I file system referrals -to NFS. -A file system referral is like a symbolic link on a file server -to another file system share, possibly on another file server. -On an NFS client, a referral behaves like an automounted directory. -The client, under the server's direction, mounts a new NFS export -automatically when an application first accesses that directory. -.P -Referrals are typically used to construct a single file name space -across multiple file servers. -Because file servers control the shape of the name space, -no client configuration is required, -and all clients see the same referral information. -.P -The Linux NFS server supports NFS version 4 referrals. -Administrators can specify the -.B refer= -export option in -.I /etc/exports -to configure a list of exports from which the client can choose. -See -.BR exports (5) -for details. -.P -The -.BR nfsref (8) -command provides an alternate way to configure NFS referrals. -This command stores referral information -as metadata within a leaf directory in an exported file system. -The metadata it stores can contain one of two types of information: -.IP "\fIA list of Fileset Locations\fP" -A set of server name and export path pairs which are returned -verbatim to clients during an NFS referral event. -This is known as an -.IR "NFS basic junction" . -.IP "\fIA Fileset Name\fP" -The name of an LDAP record which contains information to return -to clients during an NFS referral event. -This is known as a -.IR "FedFS junction" . -.P -A directory can hold either an NFS basic junction or a FedFS junction, -but not both. -When a directory acts as a junction, its regular contents remain, -but are no longer visible to NFS clients. -.P -By storing the location information in an LDAP directory, -FedFS junctions on multiple file servers can refer to -the same copy of location information. -This common locations metadata can be updated -via a single administrative operation, -altering the file name space consistently across all servers. -The -.BR fedfs (7) -man page has more information. -.SH DESCRIPTION -The -.BR nfsref (8) -command is a simple way to get started managing junction metadata. -Other administrative commands provide richer access to junction information. -.SS Subcommands -Valid -.BR nfsref (8) -subcommands are: -.IP "\fBadd\fP" -Adds junction information to the directory named by -.IR pathname . -The named directory must already exist, -and must not already contain junction information. -Regular directory contents are obscured to NFS clients by this operation. -.IP -A list of one or more file server and export path pairs -is also specified on the command line. -When creating an NFS basic junction, this list is -stored in an extended attribute of the directory. -.IP -When creating a FedFS junction, FedFS records containing the -file server and export path pairs are created on an LDAP server, -and a pointer to the new FedFS records is -stored in an extended attribute of the directory. -Fresh FSN and FSL UUIDs are generated during this operation. -.IP -If junction creation is successful, the -.BR nfsref (8) -command flushes the kernel's export cache -to remove previously cached junction information. -.IP "\fBremove\fP" -Removes junction information from the directory named by -.IR pathname . -The named directory must exist, -and must contain junction information. -Regular directory contents are made visible to NFS clients again by this operation. -.IP -When removing a FedFS junction, the -.BR nfsref (8) -command also removes FSN and FSL records referred to in the junction. -.IP -If junction deletion is successful, the -.BR nfsref (8) -command flushes the kernel's export cache -to remove previously cached junction information. -.IP "\fBlookup\fP" -Displays junction information stored in the directory named by -.IR pathname . -The named directory must exist, -and must contain junction information. -.IP -When looking up an NFS basic junction, the junction information -in the directory is listed on -.IR stdout . -When looking up a FedFS junction, junction information is -retrieved from the LDAP server listed in the junction -and listed on -.IR stdout . -.P -When creating a new FedFS junction, the -.BR nfsref (8) -command reads the following environment variables: -.IP "\fBFEDFS_NSDB_HOST\fP" -Specifies the hostname of the LDAP server where new FedFS records -should reside. If this variable is not set, the -.BR nfsref (8) -command fails. -The LDAP server specified by this variable -must be registered with the local NSDB connection -parameter database before the -.BR nfsref (8) -command can communicate with it. See -.BR nsdbparams (8) -for more information. -.IP "\fBFEDFS_NSDB_PORT\fP" -Specifies the IP port of the LDAP server where new FedFS records -should reside. The default value if this variable is not set is 389. -.IP "\fBFEDFS_NSDB_NCE\fP" -Specifies the distinguished name of the NSDB Container Entry -under which new FedFS records should reside. -If this variable is not set, the local NSDB connection parameter -database is searched for a default NCE for the hostname specified by -.BR FEDFS_NSDB_HOST . -If neither of these is specified, the -.BR nfsref (8) -command fails. -.IP "\fBFEDFS_NSDB_ADMIN\fP" -Specifies a distinguished name of an entity used to bind -to the LDAP server where new FedFS records should reside. -If this variable is not set, the local NSDB connection parameter -database is searched for a default bind DN for the hostname -specified by -.BR FEDFS_NSDB_HOST . -If neither of these is specified, or if this entity does not have -permission to modify the LDAP server's DIT, the -.BR nfsref (8) -command fails. -.SS Command line options -.IP "\fB\-d, \-\-debug" -Enables debugging messages during operation. -.IP "\fB\-t, \-\-type=\fIjunction-type\fP" -Specifies the junction type for the operation. Valid values for -.I junction-type -are -.B nfs-basic -or -.BR nfs-fedfs . -.IP -For the -.B add -subcommand, the default value if this option is not specified is -.BR nfs-basic . -For the -.B remove -and -.B lookup -subcommands, the -.B \-\-type -option is not required. The -.BR nfsref (8) -command operates on whatever junction contents are available. -.SH EXAMPLES -Suppose you have two file servers, -.I top.example.net -and -.IR home.example.net . -You want all your clients to mount -.I top.example.net:/ -and then see the files under -.I home.example.net:/ -automatically in -.IR top:/home . -.P -On -.IR top.example.net , -you might issue this command as root: -.RS -.sp -# mkdir /home -.br -# nfsref --type=nfs-basic add /home home.example.net / -.br -Created junction /home. -.sp -.RE -.SH FILES -.TP -.I /etc/exports -NFS server export table -.SH "SEE ALSO" -.BR fedfs (7), -.BR nsdbparams (8), -.BR exports (5) -.sp -RFC 5661 for a description of NFS version 4 referrals -.sp -RFC 5716 for FedFS requirements and overview -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/nfsref.8.in b/doc/man/nfsref.8.in new file mode 100644 index 0000000..886392f --- /dev/null +++ b/doc/man/nfsref.8.in @@ -0,0 +1,273 @@ +.\"@(#)nfsref.8" +.\" +.\" @file doc/man/nfsref.8 +.\" @brief man page for nfsref command +.\" + +.\" +.\" Copyright 2011 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH NFSREF 8 "@pubdate@" +.SH NAME +nfsref \- manage NFS referrals +.SH SYNOPSIS +.B nfsref +.RB [ \-?d ] +.RB [ \-t +.IB type ] +.B add +.I pathname server export +.RI [ " server" +.IR export " ... ]" +.P +.B nfsref +.RB [ \-?d ] +.RB [ \-t +.IB type ] +.B remove +.I pathname +.P +.B nfsref +.RB [ \-?d ] +.RB [ \-t +.IB type ] +.B lookup +.I pathname +.SH INTRODUCTION +NFS version 4 introduces the concept of +.I file system referrals +to NFS. +A file system referral is like a symbolic link on a file server +to another file system share, possibly on another file server. +On an NFS client, a referral behaves like an automounted directory. +The client, under the server's direction, mounts a new NFS export +automatically when an application first accesses that directory. +.P +Referrals are typically used to construct a single file name space +across multiple file servers. +Because file servers control the shape of the name space, +no client configuration is required, +and all clients see the same referral information. +.P +The Linux NFS server supports NFS version 4 referrals. +Administrators can specify the +.B refer= +export option in +.I /etc/exports +to configure a list of exports from which the client can choose. +See +.BR exports (5) +for details. +.P +The +.BR nfsref (8) +command provides an alternate way to configure NFS referrals. +This command stores referral information +as metadata within a leaf directory in an exported file system. +The metadata it stores can contain one of two types of information: +.IP "\fIA list of Fileset Locations\fP" +A set of server name and export path pairs which are returned +verbatim to clients during an NFS referral event. +This is known as an +.IR "NFS basic junction" . +.IP "\fIA Fileset Name\fP" +The name of an LDAP record which contains information to return +to clients during an NFS referral event. +This is known as a +.IR "FedFS junction" . +.P +A directory can hold either an NFS basic junction or a FedFS junction, +but not both. +When a directory acts as a junction, its regular contents remain, +but are no longer visible to NFS clients. +.P +By storing the location information in an LDAP directory, +FedFS junctions on multiple file servers can refer to +the same copy of location information. +This common locations metadata can be updated +via a single administrative operation, +altering the file name space consistently across all servers. +The +.BR fedfs (7) +man page has more information. +.SH DESCRIPTION +The +.BR nfsref (8) +command is a simple way to get started managing junction metadata. +Other administrative commands provide richer access to junction information. +.SS Subcommands +Valid +.BR nfsref (8) +subcommands are: +.IP "\fBadd\fP" +Adds junction information to the directory named by +.IR pathname . +The named directory must already exist, +and must not already contain junction information. +Regular directory contents are obscured to NFS clients by this operation. +.IP +A list of one or more file server and export path pairs +is also specified on the command line. +When creating an NFS basic junction, this list is +stored in an extended attribute of the directory. +.IP +When creating a FedFS junction, FedFS records containing the +file server and export path pairs are created on an LDAP server, +and a pointer to the new FedFS records is +stored in an extended attribute of the directory. +Fresh FSN and FSL UUIDs are generated during this operation. +.IP +If junction creation is successful, the +.BR nfsref (8) +command flushes the kernel's export cache +to remove previously cached junction information. +.IP "\fBremove\fP" +Removes junction information from the directory named by +.IR pathname . +The named directory must exist, +and must contain junction information. +Regular directory contents are made visible to NFS clients again by this operation. +.IP +When removing a FedFS junction, the +.BR nfsref (8) +command also removes FSN and FSL records referred to in the junction. +.IP +If junction deletion is successful, the +.BR nfsref (8) +command flushes the kernel's export cache +to remove previously cached junction information. +.IP "\fBlookup\fP" +Displays junction information stored in the directory named by +.IR pathname . +The named directory must exist, +and must contain junction information. +.IP +When looking up an NFS basic junction, the junction information +in the directory is listed on +.IR stdout . +When looking up a FedFS junction, junction information is +retrieved from the LDAP server listed in the junction +and listed on +.IR stdout . +.P +When creating a new FedFS junction, the +.BR nfsref (8) +command reads the following environment variables: +.IP "\fBFEDFS_NSDB_HOST\fP" +Specifies the hostname of the LDAP server where new FedFS records +should reside. If this variable is not set, the +.BR nfsref (8) +command fails. +The LDAP server specified by this variable +must be registered with the local NSDB connection +parameter database before the +.BR nfsref (8) +command can communicate with it. See +.BR nsdbparams (8) +for more information. +.IP "\fBFEDFS_NSDB_PORT\fP" +Specifies the IP port of the LDAP server where new FedFS records +should reside. The default value if this variable is not set is 389. +.IP "\fBFEDFS_NSDB_NCE\fP" +Specifies the distinguished name of the NSDB Container Entry +under which new FedFS records should reside. +If this variable is not set, the local NSDB connection parameter +database is searched for a default NCE for the hostname specified by +.BR FEDFS_NSDB_HOST . +If neither of these is specified, the +.BR nfsref (8) +command fails. +.IP "\fBFEDFS_NSDB_ADMIN\fP" +Specifies a distinguished name of an entity used to bind +to the LDAP server where new FedFS records should reside. +If this variable is not set, the local NSDB connection parameter +database is searched for a default bind DN for the hostname +specified by +.BR FEDFS_NSDB_HOST . +If neither of these is specified, or if this entity does not have +permission to modify the LDAP server's DIT, the +.BR nfsref (8) +command fails. +.SS Command line options +.IP "\fB\-d, \-\-debug" +Enables debugging messages during operation. +.IP "\fB\-t, \-\-type=\fIjunction-type\fP" +Specifies the junction type for the operation. Valid values for +.I junction-type +are +.B nfs-basic +or +.BR nfs-fedfs . +.IP +For the +.B add +subcommand, the default value if this option is not specified is +.BR nfs-basic . +For the +.B remove +and +.B lookup +subcommands, the +.B \-\-type +option is not required. The +.BR nfsref (8) +command operates on whatever junction contents are available. +.SH EXAMPLES +Suppose you have two file servers, +.I top.example.net +and +.IR home.example.net . +You want all your clients to mount +.I top.example.net:/ +and then see the files under +.I home.example.net:/ +automatically in +.IR top:/home . +.P +On +.IR top.example.net , +you might issue this command as root: +.RS +.sp +# mkdir /home +.br +# nfsref --type=nfs-basic add /home home.example.net / +.br +Created junction /home. +.sp +.RE +.SH FILES +.TP +.I /etc/exports +NFS server export table +.SH "SEE ALSO" +.BR fedfs (7), +.BR nsdbparams (8), +.BR exports (5) +.sp +RFC 5661 for a description of NFS version 4 referrals +.sp +RFC 5716 for FedFS requirements and overview +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/nsdb-annotate.8 b/doc/man/nsdb-annotate.8 deleted file mode 100644 index 3ad51df..0000000 --- a/doc/man/nsdb-annotate.8 +++ /dev/null @@ -1,369 +0,0 @@ -.\"@(#)nsdb-annotate.8" -.\" -.\" @file doc/man/nsdb-annotate.8 -.\" @brief man page for nsdb-annotate client command -.\" - -.\" -.\" Copyright 2011 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH NSDB-ANNOTATE 8 "@publication-date@" -.SH NAME -nsdb-annotate \- modify an fedfsAnnotation attribute -.SH SYNOPSIS -.B nsdb-annotate -.RB [ \-?dy ] -.RB [ \-a -.IR annotation ] -.RB [ \-D -.IR binddn ] -.RB [ \-k -.IR keyword ] -.RB [ \-l -.IR nsdbname ] -.RB [ \-r -.IR nsdbport ] -.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 -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -The bulk of FedFS junction information in a FedFS domain is stored -on one or more LDAP servers. -These servers are known as -.IR "namespace databases" , -or NSDBs, for short. -.P -FedFS-enabled file servers and clients access the information stored -on NSDBs via standard LDAP queries. -FedFS-enabled file servers use these queries to resolve FedFS junctions. -FedFS administrators use them to manage information -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 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 -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 -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 inserts new values or deletes or replaces existing ones -while maintaining the correct structure of each value -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 -.B fedfsAnnotation -string to process. -The form of the string is not checked by the -.BR -nsdb-annotate (8) -command. -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\-d, \-\-debug" -Enables debugging messages during operation. -.IP "\fB\-?, \-\-help" -Displays -.BR nsdb-annotate (8) -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 the LDAP server -where the NSDB resides. -If the -.B \-\-binddn -option is not specified, -the value of the FEDFS_NSDB_ADMIN environment variable is consulted. -If this variable is not set, -the NSDB connection parameter database is searched for this DN. -If none of these is specified, or -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-k, \-\-keyword=\fIannotation-keyword\fP" -Specifies the keyword part of a -.B fedfsAnnotation -string. Use either the -.B \-\-keyword -and -.B \-\-value -options or the -.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 record resides. -If the -.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 \-\-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 record resides. -If the -.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 -.B fedfsAnnotation -string. -Use either the -.B \-\-keyword -and -.B \-\-value -options or the -.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\-y, \-\-delete\fP" -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 -.B FEDFS_OK -The LDAP modify request succeeded. -.TP -.B FEDFS_ERR_ACCESS -The bound entity does not have permission to perform the requested operation. -.TP -.B FEDFS_ERR_INVAL -One of the arguments was not valid. -.TP -.B FEDFS_ERR_SVRFAULT -An unanticipated non-protocol error occurred. -.TP -.B FEDFS_ERR_NSDB_ROUTE -The -.BR nsdb-annotate (8) -command was unable to find a route to the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_DOWN -The -.BR nsdb-annotate (8) -command determined that the specified NSDB was down. -.TP -.B FEDFS_ERR_NSDB_CONN -The -.BR nsdb-annotate (8) -command was unable to establish a connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_AUTH -The -.BR nsdb-annotate (8) -command was unable to authenticate -and establish a secure connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP -A non-specific LDAP error occurred on the connection between the -.BR nsdb-annotate (8) -command and specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_VAL -An LDAP error occurred on the connection between the -.BR nsdb-annotate (8) -command and specified NSDB. -The specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_NONCE -The -.BR nsdb-annotate (8) -command was unable to locate the NCE on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_NOFSN -The -.BR nsdb-annotate (8) -command was unable to locate the specified FSN on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_NOFSL -The -.BR nsdb-annotate (8) -command was unable to locate any FSLs for the specified FSN -on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_RESPONSE -The -.BR nsdb-annotate (8) -command received a malformed response from the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_FAULT -An unanticipated error related to the specified NSDB occurred. -.TP -.B FEDFS_ERR_NSDB_PARAMS -The local NSDB connection parameter database -does not have any connection parameters on record for the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL -The -.BR nsdb-annotate (8) -command received an LDAP referral that it was unable to follow. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL -The -.BR nsdb-annotate (8) -command received an LDAP referral that it was unable to follow. -A specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED -The -.BR nsdb-annotate (8) -command received an LDAP referral that it chose not to follow, -either because the local implementation does not support -following LDAP referrals or LDAP referral following is disabled. -.TP -.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL -The -.BR nsdb-annotate (8) -command received an LDAP referral that it chose not to follow -because the local NSDB connection parameter database had no -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 record for -FSN UUID dc25a644-06e4-11e0-ae55-000c29dc7f8a on -the LDAP server -.IR nsdb.example.net . -You might use: -.RS -.sp -$ nsdb-annotate -l nsdb.example.net \\ -.br - -k readonly -v yes -D cn=Manager \\ -.br - fedfsFsnUuid=dc25a644-06e4-\\ -.br - 11e0-ae55-000c29dc7f8a,o=fedfs -.br -Enter NSDB password: -.br -Successfully updated annotation "readonly" = "yes" for -.br - fedfsFsnUuid=dc25a644-06e4-11e0-ae55-000c29dc7f8a,o=fedfs -.sp -.RE -To see the new annotation, use -.BR nsdb-resolve-fsn (8). -.SH SECURITY -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 -to perform this operation. -The -.BR nsdb-annotate (8) -command asks for a bind password on -.IR stdin . -Standard password blanking techniques are used -to obscure the password on the user's terminal. -.P -The target LDAP server must be registered in the local NSDB connection -parameter database. -The connection security mode listed -in the NSDB connection parameter database -for the target LDAP server is used during this operation. -See -.BR nsdbparams (8) -for details on how to register an NSDB -in the local NSDB connection parameter database. -.SH "SEE ALSO" -.BR fedfs (7), -.BR nsdb-resolve-fsn (8), -.BR nsdbparams (8) -.sp -RFC 5716 for FedFS requirements and overview -.sp -RFC 4510 for an introduction to LDAP -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/nsdb-annotate.8.in b/doc/man/nsdb-annotate.8.in new file mode 100644 index 0000000..f3d71cc --- /dev/null +++ b/doc/man/nsdb-annotate.8.in @@ -0,0 +1,369 @@ +.\"@(#)nsdb-annotate.8" +.\" +.\" @file doc/man/nsdb-annotate.8 +.\" @brief man page for nsdb-annotate client command +.\" + +.\" +.\" Copyright 2011 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH NSDB-ANNOTATE 8 "@pubdate@" +.SH NAME +nsdb-annotate \- modify an fedfsAnnotation attribute +.SH SYNOPSIS +.B nsdb-annotate +.RB [ \-?dy ] +.RB [ \-a +.IR annotation ] +.RB [ \-D +.IR binddn ] +.RB [ \-k +.IR keyword ] +.RB [ \-l +.IR nsdbname ] +.RB [ \-r +.IR nsdbport ] +.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 +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +The bulk of FedFS junction information in a FedFS domain is stored +on one or more LDAP servers. +These servers are known as +.IR "namespace databases" , +or NSDBs, for short. +.P +FedFS-enabled file servers and clients access the information stored +on NSDBs via standard LDAP queries. +FedFS-enabled file servers use these queries to resolve FedFS junctions. +FedFS administrators use them to manage information +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 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 +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 +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 inserts new values or deletes or replaces existing ones +while maintaining the correct structure of each value +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 +.B fedfsAnnotation +string to process. +The form of the string is not checked by the +.BR +nsdb-annotate (8) +command. +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\-d, \-\-debug" +Enables debugging messages during operation. +.IP "\fB\-?, \-\-help" +Displays +.BR nsdb-annotate (8) +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 the LDAP server +where the NSDB resides. +If the +.B \-\-binddn +option is not specified, +the value of the FEDFS_NSDB_ADMIN environment variable is consulted. +If this variable is not set, +the NSDB connection parameter database is searched for this DN. +If none of these is specified, or +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-k, \-\-keyword=\fIannotation-keyword\fP" +Specifies the keyword part of a +.B fedfsAnnotation +string. Use either the +.B \-\-keyword +and +.B \-\-value +options or the +.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 record resides. +If the +.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 \-\-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 record resides. +If the +.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 +.B fedfsAnnotation +string. +Use either the +.B \-\-keyword +and +.B \-\-value +options or the +.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\-y, \-\-delete\fP" +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 +.B FEDFS_OK +The LDAP modify request succeeded. +.TP +.B FEDFS_ERR_ACCESS +The bound entity does not have permission to perform the requested operation. +.TP +.B FEDFS_ERR_INVAL +One of the arguments was not valid. +.TP +.B FEDFS_ERR_SVRFAULT +An unanticipated non-protocol error occurred. +.TP +.B FEDFS_ERR_NSDB_ROUTE +The +.BR nsdb-annotate (8) +command was unable to find a route to the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_DOWN +The +.BR nsdb-annotate (8) +command determined that the specified NSDB was down. +.TP +.B FEDFS_ERR_NSDB_CONN +The +.BR nsdb-annotate (8) +command was unable to establish a connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_AUTH +The +.BR nsdb-annotate (8) +command was unable to authenticate +and establish a secure connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP +A non-specific LDAP error occurred on the connection between the +.BR nsdb-annotate (8) +command and specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_VAL +An LDAP error occurred on the connection between the +.BR nsdb-annotate (8) +command and specified NSDB. +The specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_NONCE +The +.BR nsdb-annotate (8) +command was unable to locate the NCE on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_NOFSN +The +.BR nsdb-annotate (8) +command was unable to locate the specified FSN on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_NOFSL +The +.BR nsdb-annotate (8) +command was unable to locate any FSLs for the specified FSN +on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_RESPONSE +The +.BR nsdb-annotate (8) +command received a malformed response from the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_FAULT +An unanticipated error related to the specified NSDB occurred. +.TP +.B FEDFS_ERR_NSDB_PARAMS +The local NSDB connection parameter database +does not have any connection parameters on record for the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL +The +.BR nsdb-annotate (8) +command received an LDAP referral that it was unable to follow. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL +The +.BR nsdb-annotate (8) +command received an LDAP referral that it was unable to follow. +A specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED +The +.BR nsdb-annotate (8) +command received an LDAP referral that it chose not to follow, +either because the local implementation does not support +following LDAP referrals or LDAP referral following is disabled. +.TP +.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL +The +.BR nsdb-annotate (8) +command received an LDAP referral that it chose not to follow +because the local NSDB connection parameter database had no +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 record for +FSN UUID dc25a644-06e4-11e0-ae55-000c29dc7f8a on +the LDAP server +.IR nsdb.example.net . +You might use: +.RS +.sp +$ nsdb-annotate -l nsdb.example.net \\ +.br + -k readonly -v yes -D cn=Manager \\ +.br + fedfsFsnUuid=dc25a644-06e4-\\ +.br + 11e0-ae55-000c29dc7f8a,o=fedfs +.br +Enter NSDB password: +.br +Successfully updated annotation "readonly" = "yes" for +.br + fedfsFsnUuid=dc25a644-06e4-11e0-ae55-000c29dc7f8a,o=fedfs +.sp +.RE +To see the new annotation, use +.BR nsdb-resolve-fsn (8). +.SH SECURITY +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 +to perform this operation. +The +.BR nsdb-annotate (8) +command asks for a bind password on +.IR stdin . +Standard password blanking techniques are used +to obscure the password on the user's terminal. +.P +The target LDAP server must be registered in the local NSDB connection +parameter database. +The connection security mode listed +in the NSDB connection parameter database +for the target LDAP server is used during this operation. +See +.BR nsdbparams (8) +for details on how to register an NSDB +in the local NSDB connection parameter database. +.SH "SEE ALSO" +.BR fedfs (7), +.BR nsdb-resolve-fsn (8), +.BR nsdbparams (8) +.sp +RFC 5716 for FedFS requirements and overview +.sp +RFC 4510 for an introduction to LDAP +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/nsdb-create-fsl.8 b/doc/man/nsdb-create-fsl.8 deleted file mode 100644 index caa8f08..0000000 --- a/doc/man/nsdb-create-fsl.8 +++ /dev/null @@ -1,360 +0,0 @@ -.\"@(#)nsdb-create-fsl.8" -.\" -.\" @file doc/man/nsdb-create-fsl.8 -.\" @brief man page for nsdb-create-fsl client command -.\" - -.\" -.\" Copyright 2011 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH NSDB-CREATE-FSL 8 "@publication-date@" -.SH NAME -nsdb-create-fsl \- create a fileset location (FSL) record on an NSDB -.SH SYNOPSIS -.B nsdb-create-fsl -.RB [ \-?d ] -.RB [ \-D -.IR binddn ] -.RB [ \-e -.IR nce ] -.RB [ \-l -.IR nsdbname ] -.RB [ \-o -.IR serverport ] -.RB [ \-r -.IR nsdbport ] -.I fsn-uuid -.I fsl-uuid -.I servername -.I serverpath -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -The bulk of FedFS junction information in a FedFS domain is stored -on one or more LDAP servers. -These servers are known as -.IR "namespace databases" , -or NSDBs, for short. -.P -FedFS-enabled file servers and clients access the information stored -on NSDBs via standard LDAP queries. -FedFS-enabled file servers use these queries to resolve FedFS junctions. -FedFS administrators use them to manage information -about file sets contained in a FedFS domain name space. -.SH DESCRIPTION -The -.BR nsdb-create-fsl (8) -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. -This command creates a FedFS -.I fileset location -(FSL) record on an NSDB. -.P -A fileset location, or FSL, uniquely identifies the location of one -replica of a fileset. -An FSL record contains two UUIDs and other information, -depending on the subtype of the FSL. -The meaning of these items is described in more detail in -.BR fedfs (7). -.P -FSLs are stored in records on an NSDB. -FSL records are stored as children of FSN records. -Replicas of these records can exist on more than one LDAP server. -.P -The -.BR nsdb-create-fsl (8) -command creates an FSL record on the named NSDB. -It does not create parent FSN records. -To create FSN records, use the -.BR nsdb-create-fsn (8) -command. -It does not create a replica of a fileset. -To create a fileset replica, -use appropriate file server administrative commands. -.P -This command has four positional parameters. The first parameter -specifies the target FSN UUID. If a record for this FSN does not -already exist, the -.BR nsdb-create-fsn (8) -command fails. -The second parameter specifies the -UUID of the new FSL record. If a record for this FSL already -exists, the -.BR nsdb-create-fsn (8) -command fails. -.P -The third parameter specifies the -hostname of the fileserver where the fileset replica resides. -The fourth parameter specifies the export path of that replica. -The -.BR nsdb-create-fsn (8) -command does not verify that a replica exists at that location. -.SH OPTIONS -.IP "\fB\-d, \-\-debug" -Enables debugging messages during operation. -.IP "\fB\-?, \-\-help" -Displays -.BR nsdb-create-fsl (8) -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 the LDAP server -where the NSDB resides. If the -.B \-\-binddn -option is not specified, -the value of the FEDFS_NSDB_ADMIN environment variable is consulted. -If this variable is not set, -the NSDB connection parameter database is searched for this DN. -If none of these is specified, or -if this entity does not have permission to modify this area -of the server's DIT, the -.BR nsdb-create-fsl (8) -command fails. -.IP "\fB-e, \-\-nce=\fINSDB-container-entry-distinguished-name\fP" -Specifies the distinguished name of the NSDB Container Entry -under which this FSL record is to be created. -If the -.B \-\-nce -option is not specified, -the value of the FEDFS_NSDB_NCE environment variable is consulted. -If this variable is not set, -then the NSDB connection parameter database is searched for this DN. -If none of these is specified, the -.BR nsdb-create-fsl (8) -command fails. -.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" -Specifies the hostname of the NSDB where the new FSL record should reside. -If the -.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 \-\-nsdbname -option is not specified, the -.BR nsdb-create-fsl (8) -command fails. -.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" -Specifies the IP port of the NSDB where the new FSL record should reside. -If the -.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\-o, \-\-serverport=\fIfile-server-port\fP" -Specifies the IP port of the file server a client should mount to access -this fileset location. -The default value if this option is not specified is 2049. -.SH EXIT CODES -The NSDB returns a value that reflects the success of the requested operation. -.TP -.B FEDFS_OK -The LDAP modify request succeeded. -.TP -.B FEDFS_ERR_ACCESS -The bound entity does not have permission to perform the requested operation. -.TP -.B FEDFS_ERR_INVAL -One of the arguments was not valid. -.TP -.B FEDFS_ERR_SVRFAULT -An unanticipated non-protocol error occurred. -.TP -.B FEDFS_ERR_NSDB_ROUTE -The -.BR nsdb-create-fsl (8) -command was unable to find a route to the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_DOWN -The -.BR nsdb-create-fsl (8) -command determined that the specified NSDB was down. -.TP -.B FEDFS_ERR_NSDB_CONN -The -.BR nsdb-create-fsl (8) -command was unable to establish a connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_AUTH -The -.BR nsdb-create-fsl (8) -command was unable to authenticate -and establish a secure connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP -A non-specific LDAP error occurred on the connection between the -.BR nsdb-create-fsl (8) -command and specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_VAL -An LDAP error occurred on the connection between the -.BR nsdb-create-fsl (8) -command and specified NSDB. -The specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_NONCE -The -.BR nsdb-create-fsl (8) -command was unable to locate the NCE on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_NOFSN -The -.BR nsdb-create-fsl (8) -command was unable to locate the specified FSN on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_NOFSL -The -.BR nsdb-create-fsl (8) -command was unable to locate the specified FSL for the specified FSN -on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_RESPONSE -The -.BR nsdb-create-fsl (8) -command received a malformed response from the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_FAULT -An unanticipated error related to the specified NSDB occurred. -.TP -.B FEDFS_ERR_NSDB_PARAMS -The local NSDB connection parameter database -does not have any connection parameters on record for the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL -The -.BR nsdb-create-fsl (8) -command received an LDAP referral that it was unable to follow. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL -The -.BR nsdb-create-fsl (8) -command received an LDAP referral that it was unable to follow. -A specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED -The -.BR nsdb-create-fsl (8) -command received an LDAP referral that it chose not to follow, -either because the local implementation does not support -following LDAP referrals or LDAP referral following is disabled. -.TP -.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL -The -.BR nsdb-create-fsl (8) -command received an LDAP referral that it chose not to follow -because the local NSDB connection parameter database had no -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 have created a new FSN for some fileset. -The new FSN looks like: -.RS -.sp - FSN UUID: 8e246ddc-7b46-11e0-8252-000c297fd679 -.br - NSDB: nsdb.example.net:389 -.sp -.RE -Further suppose the NSDB -.I nsdb.example.net:389 -has an NSDB Container Entry whose distinguished name is -.IR o=fedfs , -and that an FSN record for the above UUID already exists. -Finally, a replica of this fileset exists at -.IR fileserver.example.net:/export/path . -To create a corresponding FSL record, you might use: -.RS -.sp -$ nsdb-create-fsl -D cn=Manager -e o=fedfs \\ -.br - -l nsdb.example.net \\ -.br - 8e246ddc-7b46-11e0-8252-000c297fd679 \\ -.br - 323c5068-7c11-11e0-8d38-000c297fd679 \\ -.br - fileserver.example.net /export/path -.br -Enter NSDB password: -.br -Successfully created FSL record - fedfsFslUuid=323c5068-7c11-11e0-8d38-000c297fd679, - fedfsFsnUuid=8e246ddc-7b46-11e0-8252-000c297fd679,o=fedfs -.sp -.RE -A new unpopulated NFS FSL record is created on -.I nsdb.example.net:389 -as a child of the FSN record with a distinguished name of -.RS -.sp -.IR fedfsFsnUuid=8e246ddc-7b46-11e0-8252-000c297fd679,o=fedfs . -.sp -.RE -To see the new FSL record, use -.BR nsdb-list (8) -or -.BR nsdb-resolve-fsn (8). -To update individual attributes in the new FSL record, use -.BR nsdb-update-fsl (8). -.SH SECURITY -Permission to modify the LDAP's DIT is required to create a new FSL record. -The -.BR nsdb-create-fsl (8) -command must bind as an entity permitted to modify the DIT -to perform this operation. -The -.BR nsdb-create-fsl (8) -command asks for a password on -.IR stdin . -Standard password blanking techniques are used -to obscure the password on the user's terminal. -.P -The target LDAP server must be registered in the local NSDB connection -parameter database. -The connection security mode listed -in the NSDB connection parameter database -for the target LDAP server is used during this operation. -See -.BR nsdbparams (8) -for details on how to register an NSDB -in the local NSDB connection parameter database. -.SH "SEE ALSO" -.BR fedfs (7), -.BR nsdb-create-fsn (8), -.BR nsdb-update-fsl (8), -.BR nsdb-resolve-fsn (8), -.BR nsdb-list (8), -.BR nsdbparams (8) -.sp -RFC 5716 for FedFS requirements and overview -.sp -RFC 4510 for an introduction to LDAP -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/nsdb-create-fsl.8.in b/doc/man/nsdb-create-fsl.8.in new file mode 100644 index 0000000..fcb2054 --- /dev/null +++ b/doc/man/nsdb-create-fsl.8.in @@ -0,0 +1,360 @@ +.\"@(#)nsdb-create-fsl.8" +.\" +.\" @file doc/man/nsdb-create-fsl.8 +.\" @brief man page for nsdb-create-fsl client command +.\" + +.\" +.\" Copyright 2011 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH NSDB-CREATE-FSL 8 "@pubdate@" +.SH NAME +nsdb-create-fsl \- create a fileset location (FSL) record on an NSDB +.SH SYNOPSIS +.B nsdb-create-fsl +.RB [ \-?d ] +.RB [ \-D +.IR binddn ] +.RB [ \-e +.IR nce ] +.RB [ \-l +.IR nsdbname ] +.RB [ \-o +.IR serverport ] +.RB [ \-r +.IR nsdbport ] +.I fsn-uuid +.I fsl-uuid +.I servername +.I serverpath +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +The bulk of FedFS junction information in a FedFS domain is stored +on one or more LDAP servers. +These servers are known as +.IR "namespace databases" , +or NSDBs, for short. +.P +FedFS-enabled file servers and clients access the information stored +on NSDBs via standard LDAP queries. +FedFS-enabled file servers use these queries to resolve FedFS junctions. +FedFS administrators use them to manage information +about file sets contained in a FedFS domain name space. +.SH DESCRIPTION +The +.BR nsdb-create-fsl (8) +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. +This command creates a FedFS +.I fileset location +(FSL) record on an NSDB. +.P +A fileset location, or FSL, uniquely identifies the location of one +replica of a fileset. +An FSL record contains two UUIDs and other information, +depending on the subtype of the FSL. +The meaning of these items is described in more detail in +.BR fedfs (7). +.P +FSLs are stored in records on an NSDB. +FSL records are stored as children of FSN records. +Replicas of these records can exist on more than one LDAP server. +.P +The +.BR nsdb-create-fsl (8) +command creates an FSL record on the named NSDB. +It does not create parent FSN records. +To create FSN records, use the +.BR nsdb-create-fsn (8) +command. +It does not create a replica of a fileset. +To create a fileset replica, +use appropriate file server administrative commands. +.P +This command has four positional parameters. The first parameter +specifies the target FSN UUID. If a record for this FSN does not +already exist, the +.BR nsdb-create-fsn (8) +command fails. +The second parameter specifies the +UUID of the new FSL record. If a record for this FSL already +exists, the +.BR nsdb-create-fsn (8) +command fails. +.P +The third parameter specifies the +hostname of the fileserver where the fileset replica resides. +The fourth parameter specifies the export path of that replica. +The +.BR nsdb-create-fsn (8) +command does not verify that a replica exists at that location. +.SH OPTIONS +.IP "\fB\-d, \-\-debug" +Enables debugging messages during operation. +.IP "\fB\-?, \-\-help" +Displays +.BR nsdb-create-fsl (8) +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 the LDAP server +where the NSDB resides. If the +.B \-\-binddn +option is not specified, +the value of the FEDFS_NSDB_ADMIN environment variable is consulted. +If this variable is not set, +the NSDB connection parameter database is searched for this DN. +If none of these is specified, or +if this entity does not have permission to modify this area +of the server's DIT, the +.BR nsdb-create-fsl (8) +command fails. +.IP "\fB-e, \-\-nce=\fINSDB-container-entry-distinguished-name\fP" +Specifies the distinguished name of the NSDB Container Entry +under which this FSL record is to be created. +If the +.B \-\-nce +option is not specified, +the value of the FEDFS_NSDB_NCE environment variable is consulted. +If this variable is not set, +then the NSDB connection parameter database is searched for this DN. +If none of these is specified, the +.BR nsdb-create-fsl (8) +command fails. +.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" +Specifies the hostname of the NSDB where the new FSL record should reside. +If the +.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 \-\-nsdbname +option is not specified, the +.BR nsdb-create-fsl (8) +command fails. +.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" +Specifies the IP port of the NSDB where the new FSL record should reside. +If the +.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\-o, \-\-serverport=\fIfile-server-port\fP" +Specifies the IP port of the file server a client should mount to access +this fileset location. +The default value if this option is not specified is 2049. +.SH EXIT CODES +The NSDB returns a value that reflects the success of the requested operation. +.TP +.B FEDFS_OK +The LDAP modify request succeeded. +.TP +.B FEDFS_ERR_ACCESS +The bound entity does not have permission to perform the requested operation. +.TP +.B FEDFS_ERR_INVAL +One of the arguments was not valid. +.TP +.B FEDFS_ERR_SVRFAULT +An unanticipated non-protocol error occurred. +.TP +.B FEDFS_ERR_NSDB_ROUTE +The +.BR nsdb-create-fsl (8) +command was unable to find a route to the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_DOWN +The +.BR nsdb-create-fsl (8) +command determined that the specified NSDB was down. +.TP +.B FEDFS_ERR_NSDB_CONN +The +.BR nsdb-create-fsl (8) +command was unable to establish a connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_AUTH +The +.BR nsdb-create-fsl (8) +command was unable to authenticate +and establish a secure connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP +A non-specific LDAP error occurred on the connection between the +.BR nsdb-create-fsl (8) +command and specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_VAL +An LDAP error occurred on the connection between the +.BR nsdb-create-fsl (8) +command and specified NSDB. +The specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_NONCE +The +.BR nsdb-create-fsl (8) +command was unable to locate the NCE on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_NOFSN +The +.BR nsdb-create-fsl (8) +command was unable to locate the specified FSN on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_NOFSL +The +.BR nsdb-create-fsl (8) +command was unable to locate the specified FSL for the specified FSN +on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_RESPONSE +The +.BR nsdb-create-fsl (8) +command received a malformed response from the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_FAULT +An unanticipated error related to the specified NSDB occurred. +.TP +.B FEDFS_ERR_NSDB_PARAMS +The local NSDB connection parameter database +does not have any connection parameters on record for the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL +The +.BR nsdb-create-fsl (8) +command received an LDAP referral that it was unable to follow. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL +The +.BR nsdb-create-fsl (8) +command received an LDAP referral that it was unable to follow. +A specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED +The +.BR nsdb-create-fsl (8) +command received an LDAP referral that it chose not to follow, +either because the local implementation does not support +following LDAP referrals or LDAP referral following is disabled. +.TP +.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL +The +.BR nsdb-create-fsl (8) +command received an LDAP referral that it chose not to follow +because the local NSDB connection parameter database had no +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 have created a new FSN for some fileset. +The new FSN looks like: +.RS +.sp + FSN UUID: 8e246ddc-7b46-11e0-8252-000c297fd679 +.br + NSDB: nsdb.example.net:389 +.sp +.RE +Further suppose the NSDB +.I nsdb.example.net:389 +has an NSDB Container Entry whose distinguished name is +.IR o=fedfs , +and that an FSN record for the above UUID already exists. +Finally, a replica of this fileset exists at +.IR fileserver.example.net:/export/path . +To create a corresponding FSL record, you might use: +.RS +.sp +$ nsdb-create-fsl -D cn=Manager -e o=fedfs \\ +.br + -l nsdb.example.net \\ +.br + 8e246ddc-7b46-11e0-8252-000c297fd679 \\ +.br + 323c5068-7c11-11e0-8d38-000c297fd679 \\ +.br + fileserver.example.net /export/path +.br +Enter NSDB password: +.br +Successfully created FSL record + fedfsFslUuid=323c5068-7c11-11e0-8d38-000c297fd679, + fedfsFsnUuid=8e246ddc-7b46-11e0-8252-000c297fd679,o=fedfs +.sp +.RE +A new unpopulated NFS FSL record is created on +.I nsdb.example.net:389 +as a child of the FSN record with a distinguished name of +.RS +.sp +.IR fedfsFsnUuid=8e246ddc-7b46-11e0-8252-000c297fd679,o=fedfs . +.sp +.RE +To see the new FSL record, use +.BR nsdb-list (8) +or +.BR nsdb-resolve-fsn (8). +To update individual attributes in the new FSL record, use +.BR nsdb-update-fsl (8). +.SH SECURITY +Permission to modify the LDAP's DIT is required to create a new FSL record. +The +.BR nsdb-create-fsl (8) +command must bind as an entity permitted to modify the DIT +to perform this operation. +The +.BR nsdb-create-fsl (8) +command asks for a password on +.IR stdin . +Standard password blanking techniques are used +to obscure the password on the user's terminal. +.P +The target LDAP server must be registered in the local NSDB connection +parameter database. +The connection security mode listed +in the NSDB connection parameter database +for the target LDAP server is used during this operation. +See +.BR nsdbparams (8) +for details on how to register an NSDB +in the local NSDB connection parameter database. +.SH "SEE ALSO" +.BR fedfs (7), +.BR nsdb-create-fsn (8), +.BR nsdb-update-fsl (8), +.BR nsdb-resolve-fsn (8), +.BR nsdb-list (8), +.BR nsdbparams (8) +.sp +RFC 5716 for FedFS requirements and overview +.sp +RFC 4510 for an introduction to LDAP +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/nsdb-create-fsn.8 b/doc/man/nsdb-create-fsn.8 deleted file mode 100644 index 1aef5eb..0000000 --- a/doc/man/nsdb-create-fsn.8 +++ /dev/null @@ -1,332 +0,0 @@ -.\"@(#)nsdb-create-fsn.8" -.\" -.\" @file doc/man/nsdb-create-fsn.8 -.\" @brief man page for nsdb-create-fsn client command -.\" - -.\" -.\" Copyright 2011 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH NSDB-CREATE-FSN 8 "@publication-date@" -.SH NAME -nsdb-create-fsn \- create a fileset name (FSN) record on an NSDB -.SH SYNOPSIS -.B nsdb-create-fsn -.RB [ \-?d ] -.RB [ \-D -.IR binddn ] -.RB [ \-e -.IR nce ] -.RB [ \-l -.IR nsdbname ] -.RB [ \-r -.IR nsdbport ] -.RB [ \-t -.IR ttl ] -.I fsn-uuid -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -The bulk of FedFS junction information in a FedFS domain is stored -on one or more LDAP servers. -These servers are known as -.IR "namespace databases" , -or NSDBs, for short. -.P -FedFS-enabled file servers and clients access the information stored -on NSDBs via standard LDAP queries. -FedFS-enabled file servers use these queries to resolve FedFS junctions. -FedFS administrators use them to manage information -about file sets contained in a FedFS domain name space. -.SH DESCRIPTION -The -.BR nsdb-create-fsn (8) -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 creates a FedFS -.I fileset name -(FSN) record on an NSDB. -.P -A fileset name, or FSN, uniquely identifies a fileset in FedFS. -An FSN consists of a UUID and the hostname and port of an NSDB. -This pair is intended to be unique across all of FedFS. -The meaning of these items is described in more detail in -.BR fedfs (7). -.P -A FedFS junction contains an FSN. -There can be multiple junctions that contain a particular FSN. -There is exactly one FSN record stored on an NSDB that corresponds to this FSN. -The FSN record can have zero or more FSL records as children. -Replicas of these records can exist on more than one LDAP server. -.P -The -.BR nsdb-create-fsn (8) -command creates an FSN record on the named NSDB -in preparation for use in FedFS junctions. -It does not create FedFS junctions. -To create a junction, use the -.BR fedfs-create-junction (8) -command. -It does not create any FSL children records. -To create an FSL record, use the -.BR nsdb-create-fsl (8) -command. -.P -This command has one positional parameter which specifies -the UUID of the new FSN record. -.SH OPTIONS -.IP "\fB\-d, \-\-debug" -Enables debugging messages during operation. -.IP "\fB\-?, \-\-help" -Displays -.BR nsdb-create-fsn (8) -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 the LDAP server -where the NSDB resides. -If the -.B \-\-binddn -option is not specified, -the value of the FEDFS_NSDB_ADMIN environment variable is consulted. -If this variable is not set, -the NSDB connection parameter database is searched for this DN. -If none of these is specified, or -if this entity does not have permission to modify this area -of the server's DIT, the -.BR nsdb-create-fsn (8) -command fails. -.IP "\fB-e, \-\-nce=\fINSDB-container-entry-distinguished-name\fP" -Specifies the distinguished name of the NSDB Container Entry -under which this FSN record is to be created. -If the -.B \-\-nce -option is not specified, -the value of the FEDFS_NSDB_NCE environment variable is consulted. -If this variable is not set, -then the NSDB connection parameter database is searched for this DN. -If none of these is specified, the -.BR nsdb-create-fsn (8) -command fails. -.IP "\fB\-l, \-\-nsdbname=\fINSDB-host-name\fP" -Specifies the hostname of the NSDB where the new FSN record should reside. -If the -.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 \-\-nsdbname -option is not specified, the -.BR nsdb-create-fsn (8) -command fails. -.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" -Specifies the IP port of the NSDB where the new FSN record should reside. -If the -.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\-t, \-\-ttl=\fITTL\fP" -Specifies the number of seconds a file server may cache the information -in this record. If the -.B \-\-ttl -option is not specified, -a value of 300 seconds is used. -.SH EXIT CODES -The NSDB returns a value that reflects the success of the requested operation. -.TP -.B FEDFS_OK -The LDAP modify request succeeded. -.TP -.B FEDFS_ERR_ACCESS -The bound entity does not have permission to perform the requested operation. -.TP -.B FEDFS_ERR_INVAL -One of the arguments was not valid. -.TP -.B FEDFS_ERR_SVRFAULT -An unanticipated non-protocol error occurred. -.TP -.B FEDFS_ERR_NSDB_ROUTE -The -.BR nsdb-create-fsn (8) -command was unable to find a route to the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_DOWN -The -.BR nsdb-create-fsn (8) -command determined that the specified NSDB was down. -.TP -.B FEDFS_ERR_NSDB_CONN -The -.BR nsdb-create-fsn (8) -command was unable to establish a connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_AUTH -The -.BR nsdb-create-fsn (8) -command was unable to authenticate -and establish a secure connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP -A non-specific LDAP error occurred on the connection between the -.BR nsdb-create-fsn (8) -command and specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_VAL -An LDAP error occurred on the connection between the -.BR nsdb-create-fsn (8) -command and specified NSDB. -The specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_NONCE -The -.BR nsdb-create-fsn (8) -command was unable to locate the NCE on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_NOFSN -The -.BR nsdb-create-fsn (8) -command was unable to locate the specified FSN on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_RESPONSE -The -.BR nsdb-create-fsn (8) -command received a malformed response from the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_FAULT -An unanticipated error related to the specified NSDB occurred. -.TP -.B FEDFS_ERR_NSDB_PARAMS -The local NSDB connection parameter database -does not have any connection parameters on record for the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL -The -.BR nsdb-create-fsn (8) -command received an LDAP referral that it was unable to follow. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL -The -.BR nsdb-create-fsn (8) -command received an LDAP referral that it was unable to follow. -A specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED -The -.BR nsdb-create-fsn (8) -command received an LDAP referral that it chose not to follow, -either because the local implementation does not support -following LDAP referrals or LDAP referral following is disabled. -.TP -.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL -The -.BR nsdb-create-fsn (8) -command received an LDAP referral that it chose not to follow -because the local NSDB connection parameter database had no -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 have created a new FSN for some fileset. -The new FSN might look like: -.RS -.sp - FSN UUID: 8e246ddc-7b46-11e0-8252-000c297fd679 -.br - NSDB: nsdb.example.net:389 -.sp -.RE -Further suppose the NSDB -.I nsdb.example.net:389 -has an NSDB Container Entry whose distinguished name is -.IR o=fedfs . -To create a corresponding FSN record, you might use: -.RS -.sp -$ nsdb-create-fsn -D cn=Manager -e o=fedfs \\ -.br - -l nsdb.example.net \\ -.br - 8e246ddc-7b46-11e0-8252-000c297fd679 -.br -Enter NSDB password: -.br -Successfully created FSN record - fedfsFsnUuid=8e246ddc-7b46-11e0-8252-000c297fd679,o=fedfs -.sp -.RE -A new FSN record is created on -.I nsdb.example.net:389 -with a distinguished name of -.RS -.sp -.IR fedfsFsnUuid=8e246ddc-7b46-11e0-8252-000c297fd679,o=fedfs . -.sp -.RE -To see the new FSN record, use -.BR nsdb-list (8) -or -.BR nsdb-resolve-fsn (8). -.SH SECURITY -Permission to modify the LDAP's DIT is required to create a new FSN record. -The -.BR nsdb-create-fsn (8) -command must bind as an entity permitted to modify the DIT -to perform this operation. -The -.BR nsdb-create-fsn (8) -command asks for a password on -.IR stdin . -Standard password blanking techniques are used -to obscure the password on the user's terminal. -.P -The target LDAP server must be registered in the local NSDB connection -parameter database. -The connection security mode listed -in the NSDB connection parameter database -for the target LDAP server is used during this operation. -See -.BR nsdbparams (8) -for details on how to register an NSDB -in the local NSDB connection parameter database. -.SH "SEE ALSO" -.BR fedfs (7), -.BR fedfs-create-junction (8), -.BR nsdb-create-fsl (8), -.BR nsdb-resolve-fsn (8), -.BR nsdb-list (8), -.BR nsdbparams (8) -.sp -RFC 5716 for FedFS requirements and overview -.sp -RFC 4510 for an introduction to LDAP -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/nsdb-create-fsn.8.in b/doc/man/nsdb-create-fsn.8.in new file mode 100644 index 0000000..e6b7722 --- /dev/null +++ b/doc/man/nsdb-create-fsn.8.in @@ -0,0 +1,332 @@ +.\"@(#)nsdb-create-fsn.8" +.\" +.\" @file doc/man/nsdb-create-fsn.8 +.\" @brief man page for nsdb-create-fsn client command +.\" + +.\" +.\" Copyright 2011 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH NSDB-CREATE-FSN 8 "@pubdate@" +.SH NAME +nsdb-create-fsn \- create a fileset name (FSN) record on an NSDB +.SH SYNOPSIS +.B nsdb-create-fsn +.RB [ \-?d ] +.RB [ \-D +.IR binddn ] +.RB [ \-e +.IR nce ] +.RB [ \-l +.IR nsdbname ] +.RB [ \-r +.IR nsdbport ] +.RB [ \-t +.IR ttl ] +.I fsn-uuid +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +The bulk of FedFS junction information in a FedFS domain is stored +on one or more LDAP servers. +These servers are known as +.IR "namespace databases" , +or NSDBs, for short. +.P +FedFS-enabled file servers and clients access the information stored +on NSDBs via standard LDAP queries. +FedFS-enabled file servers use these queries to resolve FedFS junctions. +FedFS administrators use them to manage information +about file sets contained in a FedFS domain name space. +.SH DESCRIPTION +The +.BR nsdb-create-fsn (8) +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 creates a FedFS +.I fileset name +(FSN) record on an NSDB. +.P +A fileset name, or FSN, uniquely identifies a fileset in FedFS. +An FSN consists of a UUID and the hostname and port of an NSDB. +This pair is intended to be unique across all of FedFS. +The meaning of these items is described in more detail in +.BR fedfs (7). +.P +A FedFS junction contains an FSN. +There can be multiple junctions that contain a particular FSN. +There is exactly one FSN record stored on an NSDB that corresponds to this FSN. +The FSN record can have zero or more FSL records as children. +Replicas of these records can exist on more than one LDAP server. +.P +The +.BR nsdb-create-fsn (8) +command creates an FSN record on the named NSDB +in preparation for use in FedFS junctions. +It does not create FedFS junctions. +To create a junction, use the +.BR fedfs-create-junction (8) +command. +It does not create any FSL children records. +To create an FSL record, use the +.BR nsdb-create-fsl (8) +command. +.P +This command has one positional parameter which specifies +the UUID of the new FSN record. +.SH OPTIONS +.IP "\fB\-d, \-\-debug" +Enables debugging messages during operation. +.IP "\fB\-?, \-\-help" +Displays +.BR nsdb-create-fsn (8) +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 the LDAP server +where the NSDB resides. +If the +.B \-\-binddn +option is not specified, +the value of the FEDFS_NSDB_ADMIN environment variable is consulted. +If this variable is not set, +the NSDB connection parameter database is searched for this DN. +If none of these is specified, or +if this entity does not have permission to modify this area +of the server's DIT, the +.BR nsdb-create-fsn (8) +command fails. +.IP "\fB-e, \-\-nce=\fINSDB-container-entry-distinguished-name\fP" +Specifies the distinguished name of the NSDB Container Entry +under which this FSN record is to be created. +If the +.B \-\-nce +option is not specified, +the value of the FEDFS_NSDB_NCE environment variable is consulted. +If this variable is not set, +then the NSDB connection parameter database is searched for this DN. +If none of these is specified, the +.BR nsdb-create-fsn (8) +command fails. +.IP "\fB\-l, \-\-nsdbname=\fINSDB-host-name\fP" +Specifies the hostname of the NSDB where the new FSN record should reside. +If the +.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 \-\-nsdbname +option is not specified, the +.BR nsdb-create-fsn (8) +command fails. +.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" +Specifies the IP port of the NSDB where the new FSN record should reside. +If the +.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\-t, \-\-ttl=\fITTL\fP" +Specifies the number of seconds a file server may cache the information +in this record. If the +.B \-\-ttl +option is not specified, +a value of 300 seconds is used. +.SH EXIT CODES +The NSDB returns a value that reflects the success of the requested operation. +.TP +.B FEDFS_OK +The LDAP modify request succeeded. +.TP +.B FEDFS_ERR_ACCESS +The bound entity does not have permission to perform the requested operation. +.TP +.B FEDFS_ERR_INVAL +One of the arguments was not valid. +.TP +.B FEDFS_ERR_SVRFAULT +An unanticipated non-protocol error occurred. +.TP +.B FEDFS_ERR_NSDB_ROUTE +The +.BR nsdb-create-fsn (8) +command was unable to find a route to the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_DOWN +The +.BR nsdb-create-fsn (8) +command determined that the specified NSDB was down. +.TP +.B FEDFS_ERR_NSDB_CONN +The +.BR nsdb-create-fsn (8) +command was unable to establish a connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_AUTH +The +.BR nsdb-create-fsn (8) +command was unable to authenticate +and establish a secure connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP +A non-specific LDAP error occurred on the connection between the +.BR nsdb-create-fsn (8) +command and specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_VAL +An LDAP error occurred on the connection between the +.BR nsdb-create-fsn (8) +command and specified NSDB. +The specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_NONCE +The +.BR nsdb-create-fsn (8) +command was unable to locate the NCE on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_NOFSN +The +.BR nsdb-create-fsn (8) +command was unable to locate the specified FSN on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_RESPONSE +The +.BR nsdb-create-fsn (8) +command received a malformed response from the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_FAULT +An unanticipated error related to the specified NSDB occurred. +.TP +.B FEDFS_ERR_NSDB_PARAMS +The local NSDB connection parameter database +does not have any connection parameters on record for the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL +The +.BR nsdb-create-fsn (8) +command received an LDAP referral that it was unable to follow. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL +The +.BR nsdb-create-fsn (8) +command received an LDAP referral that it was unable to follow. +A specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED +The +.BR nsdb-create-fsn (8) +command received an LDAP referral that it chose not to follow, +either because the local implementation does not support +following LDAP referrals or LDAP referral following is disabled. +.TP +.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL +The +.BR nsdb-create-fsn (8) +command received an LDAP referral that it chose not to follow +because the local NSDB connection parameter database had no +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 have created a new FSN for some fileset. +The new FSN might look like: +.RS +.sp + FSN UUID: 8e246ddc-7b46-11e0-8252-000c297fd679 +.br + NSDB: nsdb.example.net:389 +.sp +.RE +Further suppose the NSDB +.I nsdb.example.net:389 +has an NSDB Container Entry whose distinguished name is +.IR o=fedfs . +To create a corresponding FSN record, you might use: +.RS +.sp +$ nsdb-create-fsn -D cn=Manager -e o=fedfs \\ +.br + -l nsdb.example.net \\ +.br + 8e246ddc-7b46-11e0-8252-000c297fd679 +.br +Enter NSDB password: +.br +Successfully created FSN record + fedfsFsnUuid=8e246ddc-7b46-11e0-8252-000c297fd679,o=fedfs +.sp +.RE +A new FSN record is created on +.I nsdb.example.net:389 +with a distinguished name of +.RS +.sp +.IR fedfsFsnUuid=8e246ddc-7b46-11e0-8252-000c297fd679,o=fedfs . +.sp +.RE +To see the new FSN record, use +.BR nsdb-list (8) +or +.BR nsdb-resolve-fsn (8). +.SH SECURITY +Permission to modify the LDAP's DIT is required to create a new FSN record. +The +.BR nsdb-create-fsn (8) +command must bind as an entity permitted to modify the DIT +to perform this operation. +The +.BR nsdb-create-fsn (8) +command asks for a password on +.IR stdin . +Standard password blanking techniques are used +to obscure the password on the user's terminal. +.P +The target LDAP server must be registered in the local NSDB connection +parameter database. +The connection security mode listed +in the NSDB connection parameter database +for the target LDAP server is used during this operation. +See +.BR nsdbparams (8) +for details on how to register an NSDB +in the local NSDB connection parameter database. +.SH "SEE ALSO" +.BR fedfs (7), +.BR fedfs-create-junction (8), +.BR nsdb-create-fsl (8), +.BR nsdb-resolve-fsn (8), +.BR nsdb-list (8), +.BR nsdbparams (8) +.sp +RFC 5716 for FedFS requirements and overview +.sp +RFC 4510 for an introduction to LDAP +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/nsdb-delete-fsl.8 b/doc/man/nsdb-delete-fsl.8 deleted file mode 100644 index cad9832..0000000 --- a/doc/man/nsdb-delete-fsl.8 +++ /dev/null @@ -1,329 +0,0 @@ -.\"@(#)nsdb-delete-fsl.8" -.\" -.\" @file doc/man/nsdb-delete-fsl.8 -.\" @brief man page for nsdb-delete-fsl client command -.\" - -.\" -.\" Copyright 2011 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH NSDB-DELETE-FSL 8 "@publication-date@" -.SH NAME -nsdb-delete-fsl \- delete a fileset location (FSL) record from an NSDB -.SH SYNOPSIS -.B nsdb-delete-fsl -.RB [ \-?d ] -.RB [ \-D -.IR binddn ] -.RB [ \-e -.IR nce ] -.RB [ \-l -.IR nsdbname ] -.RB [ \-r -.IR nsdbport ] -.I fsl-uuid -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -The bulk of FedFS junction information in a FedFS domain is stored -on one or more LDAP servers. -These servers are known as -.IR "namespace databases" , -or NSDBs, for short. -.P -FedFS-enabled file servers and clients access the information stored -on NSDBs via standard LDAP queries. -FedFS-enabled file servers use these queries to resolve FedFS junctions. -FedFS administrators use them to manage information -about file sets contained in a FedFS domain name space. -.SH DESCRIPTION -The -.BR nsdb-delete-fsl (8) -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. -This command deletes a FedFS -.I fileset location -(FSL) record from an NSDB. -.P -A fileset location, or FSL, uniquely identifies the location of one -replica of a fileset. -An FSL record contains two UUIDs and other information, -depending on the subtype of the FSL. -The meaning of these items is described in more detail in -.BR fedfs (7). -.P -FSLs are stored in records on an NSDB. -These records are stored as children of FSN records. -Replicas of these records can exist on more than one LDAP server. -.P -The -.BR nsdb-delete-fsl (8) -command removes an FSL record from the named NSDB. -It does not remove parent FSN records. -To remove FSN records, use the -.BR nsdb-delete-fsn (8) -command. -It does not remove a replica of a fileset. -To remove fileset replicas, -use appropriate file server administrative commands. -.P -This command has two positional parameters. -The first parameter specifies the target FSN UUID. -If a record for this FSN does not already exist, the -.BR nsdb-delete-fsn (8) -command fails. -The second parameter specifies the UUID of the FSL record to remove. -If a record for this FSL does not exist, the -.BR nsdb-delete-fsn (8) -command fails. -.SH OPTIONS -.IP "\fB\-d, \-\-debug" -Enables debugging messages during operation. -.IP "\fB\-?, \-\-help" -Displays -.BR nsdb-delete-fsl (8) -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 the LDAP server -where the NSDB resides. -If the -.B \-\-binddn -option is not specified, -the value of the FEDFS_NSDB_ADMIN environment variable is consulted. -If this variable is not set, -the NSDB connection parameter database is searched for this DN. -If none of these is specified, or -if this entity does not have permission to modify this area -of the server's DIT, the -.BR nsdb-delete-fsl (8) -command fails. -.IP "\fB-e, \-\-nce=\fINSDB-container-entry-distinguished-name\fP" -Specifies the distinguished name of the NSDB Container Entry -under which this FSL is to be created. -If the -.B \-\-nce -option is not specified, -the value of the FEDFS_NSDB_NCE environment variable is consulted. -If this variable is not set, -then the NSDB connection parameter database is searched for this DN. -If none of these is specified, the -.BR nsdb-delete-fsl (8) -command fails. -.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" -Specifies the hostname of the NSDB where the new FSL record should reside. -If the -.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 \-\-nsdbname -option is not specified, the -.BR nsdb-delete-fsl (8) -command fails. -.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" -Specifies the IP port of the NSDB where the new FSL record should reside. -If the -.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. -.SH EXIT CODES -The NSDB returns a value that reflects the success of the requested operation. -.TP -.B FEDFS_OK -The LDAP modify request succeeded. -.TP -.B FEDFS_ERR_ACCESS -The bound entity does not have permission to perform the requested operation. -.TP -.B FEDFS_ERR_INVAL -One of the arguments was not valid. -.TP -.B FEDFS_ERR_SVRFAULT -An unanticipated non-protocol error occurred. -.TP -.B FEDFS_ERR_NSDB_ROUTE -The -.BR nsdb-delete-fsl (8) -command was unable to find a route to the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_DOWN -The -.BR nsdb-delete-fsl (8) -command determined that the specified NSDB was down. -.TP -.B FEDFS_ERR_NSDB_CONN -The -.BR nsdb-delete-fsl (8) -command was unable to establish a connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_AUTH -The -.BR nsdb-delete-fsl (8) -command was unable to authenticate -and establish a secure connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP -A non-specific LDAP error occurred on the connection between the -.BR nsdb-delete-fsl (8) -command and specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_VAL -An LDAP error occurred on the connection between the -.BR nsdb-delete-fsl (8) -command and specified NSDB. -The specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_NONCE -The -.BR nsdb-delete-fsl (8) -command was unable to locate the NCE on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_NOFSN -The -.BR nsdb-delete-fsl (8) -command was unable to locate the specified FSN on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_NOFSL -The -.BR nsdb-delete-fsl (8) -command was unable to locate the specified FSL for the specified FSN -on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_RESPONSE -The -.BR nsdb-delete-fsl (8) -command received a malformed response from the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_FAULT -An unanticipated error related to the specified NSDB occurred. -.TP -.B FEDFS_ERR_NSDB_PARAMS -The local NSDB connection parameter database -does not have any connection parameters on record for the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL -The -.BR nsdb-delete-fsl (8) -command received an LDAP referral that it was unable to follow. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL -The -.BR nsdb-delete-fsl (8) -command received an LDAP referral that it was unable to follow. -A specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED -The -.BR nsdb-delete-fsl (8) -command received an LDAP referral that it chose not to follow, -either because the local implementation does not support -following LDAP referrals or LDAP referral following is disabled. -.TP -.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL -The -.BR nsdb-delete-fsl (8) -command received an LDAP referral that it chose not to follow -because the local NSDB connection parameter database had no -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 have an FSN that looks like: -.RS -.sp - FSN UUID: 8e246ddc-7b46-11e0-8252-000c297fd679 -.br - NSDB: nsdb.example.net:389 -.sp -.RE -Further suppose the NSDB -.I nsdb.example.net:389 -has an NSDB Container Entry whose distinguished name is -.IR o=fedfs . -The replica of this fileset that exists at -.I fileserver.example.net:/path -has just been removed, and it's FSL UUID is -.IR 323c5068-7c11-11e0-8d38-000c297fd679 . -To delete the corresponding FSL record, you might use: -.RS -.sp -$ nsdb-delete-fsl -D cn=Manager -e o=fedfs \\ -.br - -l nsdb.example.net \\ -.br - 8e246ddc-7b46-11e0-8252-000c297fd679 -.br - 323c5068-7c11-11e0-8d38-000c297fd679 -.br -Enter NSDB password: -.br -Successfully deleted FSL record - fedfsFslUuid=323c5068-7c11-11e0-8d38-000c297fd679, - fedfsFsnUuid=8e246ddc-7b46-11e0-8252-000c297fd679,o=fedfs -.sp -.RE -The FSL record for the specified replica is removed, -leaving possibly other FSL records for this fileset, -and leaving the parent FSN record intact. -.SH SECURITY -Permission to modify the LDAP's DIT is required to delete an FSL record. -The -.BR nsdb-delete-fsl (8) -command must bind as an entity permitted to modify the DIT -to perform this operation. -The -.BR nsdb-delete-fsl (8) -command asks for a password on -.IR stdin . -Standard password blanking techniques are used -to obscure the password on the user's terminal. -.P -The target LDAP server must be registered in the local NSDB connection -parameter database. -The connection security mode listed -in the NSDB connection parameter database -for the target LDAP server is used during this operation. -See -.BR nsdbparams (8) -for details on how to register an NSDB -in the local NSDB connection parameter database. -.SH "SEE ALSO" -.BR fedfs (7), -.BR nsdb-delete-fsn (8), -.BR nsdb-list (8), -.BR nsdbparams (8) -.sp -RFC 5716 for FedFS requirements and overview -.sp -RFC 4510 for an introduction to LDAP -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/nsdb-delete-fsl.8.in b/doc/man/nsdb-delete-fsl.8.in new file mode 100644 index 0000000..7d6a3cd --- /dev/null +++ b/doc/man/nsdb-delete-fsl.8.in @@ -0,0 +1,329 @@ +.\"@(#)nsdb-delete-fsl.8" +.\" +.\" @file doc/man/nsdb-delete-fsl.8 +.\" @brief man page for nsdb-delete-fsl client command +.\" + +.\" +.\" Copyright 2011 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH NSDB-DELETE-FSL 8 "@pubdate@" +.SH NAME +nsdb-delete-fsl \- delete a fileset location (FSL) record from an NSDB +.SH SYNOPSIS +.B nsdb-delete-fsl +.RB [ \-?d ] +.RB [ \-D +.IR binddn ] +.RB [ \-e +.IR nce ] +.RB [ \-l +.IR nsdbname ] +.RB [ \-r +.IR nsdbport ] +.I fsl-uuid +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +The bulk of FedFS junction information in a FedFS domain is stored +on one or more LDAP servers. +These servers are known as +.IR "namespace databases" , +or NSDBs, for short. +.P +FedFS-enabled file servers and clients access the information stored +on NSDBs via standard LDAP queries. +FedFS-enabled file servers use these queries to resolve FedFS junctions. +FedFS administrators use them to manage information +about file sets contained in a FedFS domain name space. +.SH DESCRIPTION +The +.BR nsdb-delete-fsl (8) +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. +This command deletes a FedFS +.I fileset location +(FSL) record from an NSDB. +.P +A fileset location, or FSL, uniquely identifies the location of one +replica of a fileset. +An FSL record contains two UUIDs and other information, +depending on the subtype of the FSL. +The meaning of these items is described in more detail in +.BR fedfs (7). +.P +FSLs are stored in records on an NSDB. +These records are stored as children of FSN records. +Replicas of these records can exist on more than one LDAP server. +.P +The +.BR nsdb-delete-fsl (8) +command removes an FSL record from the named NSDB. +It does not remove parent FSN records. +To remove FSN records, use the +.BR nsdb-delete-fsn (8) +command. +It does not remove a replica of a fileset. +To remove fileset replicas, +use appropriate file server administrative commands. +.P +This command has two positional parameters. +The first parameter specifies the target FSN UUID. +If a record for this FSN does not already exist, the +.BR nsdb-delete-fsn (8) +command fails. +The second parameter specifies the UUID of the FSL record to remove. +If a record for this FSL does not exist, the +.BR nsdb-delete-fsn (8) +command fails. +.SH OPTIONS +.IP "\fB\-d, \-\-debug" +Enables debugging messages during operation. +.IP "\fB\-?, \-\-help" +Displays +.BR nsdb-delete-fsl (8) +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 the LDAP server +where the NSDB resides. +If the +.B \-\-binddn +option is not specified, +the value of the FEDFS_NSDB_ADMIN environment variable is consulted. +If this variable is not set, +the NSDB connection parameter database is searched for this DN. +If none of these is specified, or +if this entity does not have permission to modify this area +of the server's DIT, the +.BR nsdb-delete-fsl (8) +command fails. +.IP "\fB-e, \-\-nce=\fINSDB-container-entry-distinguished-name\fP" +Specifies the distinguished name of the NSDB Container Entry +under which this FSL is to be created. +If the +.B \-\-nce +option is not specified, +the value of the FEDFS_NSDB_NCE environment variable is consulted. +If this variable is not set, +then the NSDB connection parameter database is searched for this DN. +If none of these is specified, the +.BR nsdb-delete-fsl (8) +command fails. +.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" +Specifies the hostname of the NSDB where the new FSL record should reside. +If the +.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 \-\-nsdbname +option is not specified, the +.BR nsdb-delete-fsl (8) +command fails. +.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" +Specifies the IP port of the NSDB where the new FSL record should reside. +If the +.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. +.SH EXIT CODES +The NSDB returns a value that reflects the success of the requested operation. +.TP +.B FEDFS_OK +The LDAP modify request succeeded. +.TP +.B FEDFS_ERR_ACCESS +The bound entity does not have permission to perform the requested operation. +.TP +.B FEDFS_ERR_INVAL +One of the arguments was not valid. +.TP +.B FEDFS_ERR_SVRFAULT +An unanticipated non-protocol error occurred. +.TP +.B FEDFS_ERR_NSDB_ROUTE +The +.BR nsdb-delete-fsl (8) +command was unable to find a route to the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_DOWN +The +.BR nsdb-delete-fsl (8) +command determined that the specified NSDB was down. +.TP +.B FEDFS_ERR_NSDB_CONN +The +.BR nsdb-delete-fsl (8) +command was unable to establish a connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_AUTH +The +.BR nsdb-delete-fsl (8) +command was unable to authenticate +and establish a secure connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP +A non-specific LDAP error occurred on the connection between the +.BR nsdb-delete-fsl (8) +command and specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_VAL +An LDAP error occurred on the connection between the +.BR nsdb-delete-fsl (8) +command and specified NSDB. +The specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_NONCE +The +.BR nsdb-delete-fsl (8) +command was unable to locate the NCE on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_NOFSN +The +.BR nsdb-delete-fsl (8) +command was unable to locate the specified FSN on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_NOFSL +The +.BR nsdb-delete-fsl (8) +command was unable to locate the specified FSL for the specified FSN +on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_RESPONSE +The +.BR nsdb-delete-fsl (8) +command received a malformed response from the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_FAULT +An unanticipated error related to the specified NSDB occurred. +.TP +.B FEDFS_ERR_NSDB_PARAMS +The local NSDB connection parameter database +does not have any connection parameters on record for the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL +The +.BR nsdb-delete-fsl (8) +command received an LDAP referral that it was unable to follow. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL +The +.BR nsdb-delete-fsl (8) +command received an LDAP referral that it was unable to follow. +A specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED +The +.BR nsdb-delete-fsl (8) +command received an LDAP referral that it chose not to follow, +either because the local implementation does not support +following LDAP referrals or LDAP referral following is disabled. +.TP +.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL +The +.BR nsdb-delete-fsl (8) +command received an LDAP referral that it chose not to follow +because the local NSDB connection parameter database had no +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 have an FSN that looks like: +.RS +.sp + FSN UUID: 8e246ddc-7b46-11e0-8252-000c297fd679 +.br + NSDB: nsdb.example.net:389 +.sp +.RE +Further suppose the NSDB +.I nsdb.example.net:389 +has an NSDB Container Entry whose distinguished name is +.IR o=fedfs . +The replica of this fileset that exists at +.I fileserver.example.net:/path +has just been removed, and it's FSL UUID is +.IR 323c5068-7c11-11e0-8d38-000c297fd679 . +To delete the corresponding FSL record, you might use: +.RS +.sp +$ nsdb-delete-fsl -D cn=Manager -e o=fedfs \\ +.br + -l nsdb.example.net \\ +.br + 8e246ddc-7b46-11e0-8252-000c297fd679 +.br + 323c5068-7c11-11e0-8d38-000c297fd679 +.br +Enter NSDB password: +.br +Successfully deleted FSL record + fedfsFslUuid=323c5068-7c11-11e0-8d38-000c297fd679, + fedfsFsnUuid=8e246ddc-7b46-11e0-8252-000c297fd679,o=fedfs +.sp +.RE +The FSL record for the specified replica is removed, +leaving possibly other FSL records for this fileset, +and leaving the parent FSN record intact. +.SH SECURITY +Permission to modify the LDAP's DIT is required to delete an FSL record. +The +.BR nsdb-delete-fsl (8) +command must bind as an entity permitted to modify the DIT +to perform this operation. +The +.BR nsdb-delete-fsl (8) +command asks for a password on +.IR stdin . +Standard password blanking techniques are used +to obscure the password on the user's terminal. +.P +The target LDAP server must be registered in the local NSDB connection +parameter database. +The connection security mode listed +in the NSDB connection parameter database +for the target LDAP server is used during this operation. +See +.BR nsdbparams (8) +for details on how to register an NSDB +in the local NSDB connection parameter database. +.SH "SEE ALSO" +.BR fedfs (7), +.BR nsdb-delete-fsn (8), +.BR nsdb-list (8), +.BR nsdbparams (8) +.sp +RFC 5716 for FedFS requirements and overview +.sp +RFC 4510 for an introduction to LDAP +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/nsdb-delete-fsn.8 b/doc/man/nsdb-delete-fsn.8 deleted file mode 100644 index dd2dd29..0000000 --- a/doc/man/nsdb-delete-fsn.8 +++ /dev/null @@ -1,320 +0,0 @@ -.\"@(#)nsdb-delete-fsn.8" -.\" -.\" @file doc/man/nsdb-delete-fsn.8 -.\" @brief man page for nsdb-delete-fsn client command -.\" - -.\" -.\" Copyright 2011 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH NSDB-DELETE-FSN 8 "@publication-date@" -.SH NAME -nsdb-delete-fsn \- delete a fileset name (FSN) record from an NSDB -.SH SYNOPSIS -.B nsdb-delete-fsn -.RB [ \-?dy ] -.RB [ \-D -.IR binddn ] -.RB [ \-e -.IR nce ] -.RB [ \-l -.IR nsdbname ] -.RB [ \-r -.IR nsdbport ] -.I fsn-uuid -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -The bulk of FedFS junction information in a FedFS domain is stored -on one or more LDAP servers. -These servers are known as -.IR "namespace databases" , -or NSDBs, for short. -.P -FedFS-enabled file servers and clients access the information stored -on NSDBs via standard LDAP queries. -FedFS-enabled file servers use these queries to resolve FedFS junctions. -FedFS administrators use them to manage information -about file sets contained in a FedFS domain name space. -.SH DESCRIPTION -The -.BR nsdb-delete-fsn (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. -This command deletes a FedFS -.I fileset name -(FSN) record from an NSDB. -.P -A fileset name, or FSN, uniquely identifies a fileset in FedFS. -An FSN consists of a UUID and the hostname and port of an NSDB. -This pair is intended to be unique across all of FedFS. -The meaning of these items is described in more detail in -.BR fedfs (7). -.P -A FedFS junction contains an FSN. -There can be multiple junctions that contain a particular FSN. -There is exactly one FSN record stored on an NSDB that corresponds to this FSN. -The FSN record can have zero or more FSL records as children. -Replicas of these records can exist on more than one LDAP server. -.P -The -.BR nsdb-delete-fsn (8) -command removes an FSN record from the named NSDB -after it is no longer used in FedFS junctions. -It does not remove FedFS junctions. -To remove a junction, use the -.BR fedfs-delete-junction (8) -command -.P -The default behavior, if the -.B \-\-delete -option is not specified, -removes the specified FSN record and all of its FSL children records. -If the -.B \-\-delete -option is specified, -all FSL child records of the specified FSN record are removed, -but the specified FSN record is left in place. -.P -This command has one positional parameter which specifies -the UUID of the FSN record to modify or remove. -.SH OPTIONS -.IP "\fB\-d, \-\-debug" -Enables debugging messages during operation. -.IP "\fB\-?, \-\-help" -Displays -.BR nsdb-delete-fsn (8) -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 the LDAP server -where the NSDB resides. -If the -.B \-\-binddn -option is not specified, -the value of the FEDFS_NSDB_ADMIN environment variable is consulted. -If this variable is not set, -the NSDB connection parameter database is searched for this DN. -If none of these is specified, or -if this entity does not have permission to modify this area -of the server's DIT, the -.BR nsdb-delete-fsn (8) -command fails. -.IP "\fB-e, \-\-nce=\fINSDB-container-entry-distinguished-name\fP" -Specifies the distinguished name of the NSDB Container Entry -under which the doomed FSN record exists. -If the -.B \-\-nce -option is not specified, -the value of the FEDFS_NSDB_NCE environment variable is consulted. -If this variable is not set, -then the NSDB connection parameter database is searched for this DN. -If none of these is specified, the -.BR nsdb-delete-fsn (8) -command fails. -.IP "\fB\-l, \-\-nsdbname=\fINSDB-host-name\fP" -Specifies the hostname of the NSDB where the doomed FSN record resides. -If the -.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 \-\-nsdbname -option is not specified, the -.BR nsdb-delete-fsn (8) -command fails. -.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" -Specifies the IP port of the NSDB where the doomed FSN record resides. -If the -.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-y, \-\-leavefsn\fP" -Specifies that the specified FSN record should remain, -but all FSL records associated with the specified FSN record should be deleted. -.SH EXIT CODES -The NSDB returns a value that reflects the success of the requested operation. -.TP -.B FEDFS_OK -The LDAP modify request succeeded. -.TP -.B FEDFS_ERR_ACCESS -The bound entity does not have permission to perform the requested operation. -.TP -.B FEDFS_ERR_INVAL -One of the arguments was not valid. -.TP -.B FEDFS_ERR_SVRFAULT -An unanticipated non-protocol error occurred. -.TP -.B FEDFS_ERR_NSDB_ROUTE -The -.BR nsdb-delete-fsn (8) -command was unable to find a route to the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_DOWN -The -.BR nsdb-delete-fsn (8) -command determined that the specified NSDB was down. -.TP -.B FEDFS_ERR_NSDB_CONN -The -.BR nsdb-delete-fsn (8) -command was unable to establish a connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_AUTH -The -.BR nsdb-delete-fsn (8) -command was unable to authenticate -and establish a secure connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP -A non-specific LDAP error occurred on the connection between the -.BR nsdb-delete-fsn (8) -command and specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_VAL -An LDAP error occurred on the connection between the -.BR nsdb-delete-fsn (8) -command and specified NSDB. -The specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_NONCE -The -.BR nsdb-delete-fsn (8) -command was unable to locate the NCE on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_NOFSN -The -.BR nsdb-delete-fsn (8) -command was unable to locate the specified FSN on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_RESPONSE -The -.BR nsdb-delete-fsn (8) -command received a malformed response from the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_FAULT -An unanticipated error related to the specified NSDB occurred. -.TP -.B FEDFS_ERR_NSDB_PARAMS -The local NSDB connection parameter database -does not have any connection parameters on record for the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL -The -.BR nsdb-delete-fsn (8) -command received an LDAP referral that it was unable to follow. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL -The -.BR nsdb-delete-fsn (8) -command received an LDAP referral that it was unable to follow. -A specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED -The -.BR nsdb-delete-fsn (8) -command received an LDAP referral that it chose not to follow, -either because the local implementation does not support -following LDAP referrals or LDAP referral following is disabled. -.TP -.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL -The -.BR nsdb-delete-fsn (8) -command received an LDAP referral that it chose not to follow -because the local NSDB connection parameter database had no -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 remove the FSN record for this FSN: -.RS -.sp - FSN UUID: 8e246ddc-7b46-11e0-8252-000c297fd679 -.br - NSDB: nsdb.example.net:389 -.sp -.RE -Further suppose the NSDB -.I nsdb.example.net:389 -has an NSDB Container Entry whose distinguished name is -.IR o=fedfs . -To delete the corresponding FSN record, you might use: -.RS -.sp -$ nsdb-delete-fsn -D cn=Manager -e o=fedfs \\ -.br - -l nsdb.example.net \\ -.br - 8e246ddc-7b46-11e0-8252-000c297fd679 -.br -Enter NSDB password: -.br -Successfully deleted FSN record - fedfsFsnUuid=8e246ddc-7b46-11e0-8252-000c297fd679,o=fedfs -.sp -.RE -In this example, -all FSL child records for this FSN record are also removed. -.SH SECURITY -Permission to modify the LDAP's DIT is required to delete an FSN record. -The -.BR nsdb-delete-fsn (8) -command must bind as an entity permitted to modify the DIT -to perform this operation. -The -.BR nsdb-delete-fsn (8) -command asks for a password on -.IR stdin . -Standard password blanking techniques are used -to obscure the password on the user's terminal. -.P -The target LDAP server must be registered in the local NSDB connection -parameter database. -The connection security mode listed -in the NSDB connection parameter database -for the target LDAP server is used during this operation. -See -.BR nsdbparams (8) -for details on how to register an NSDB -in the local NSDB connection parameter database. -.SH "SEE ALSO" -.BR fedfs (7), -.BR fedfs-delete-junction (8), -.BR nsdb-delete-fsl (8), -.BR nsdbparams (8) -.sp -RFC 5716 for FedFS requirements and overview -.sp -RFC 4510 for an introduction to LDAP -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/nsdb-delete-fsn.8.in b/doc/man/nsdb-delete-fsn.8.in new file mode 100644 index 0000000..d485da8 --- /dev/null +++ b/doc/man/nsdb-delete-fsn.8.in @@ -0,0 +1,320 @@ +.\"@(#)nsdb-delete-fsn.8" +.\" +.\" @file doc/man/nsdb-delete-fsn.8 +.\" @brief man page for nsdb-delete-fsn client command +.\" + +.\" +.\" Copyright 2011 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH NSDB-DELETE-FSN 8 "@pubdate@" +.SH NAME +nsdb-delete-fsn \- delete a fileset name (FSN) record from an NSDB +.SH SYNOPSIS +.B nsdb-delete-fsn +.RB [ \-?dy ] +.RB [ \-D +.IR binddn ] +.RB [ \-e +.IR nce ] +.RB [ \-l +.IR nsdbname ] +.RB [ \-r +.IR nsdbport ] +.I fsn-uuid +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +The bulk of FedFS junction information in a FedFS domain is stored +on one or more LDAP servers. +These servers are known as +.IR "namespace databases" , +or NSDBs, for short. +.P +FedFS-enabled file servers and clients access the information stored +on NSDBs via standard LDAP queries. +FedFS-enabled file servers use these queries to resolve FedFS junctions. +FedFS administrators use them to manage information +about file sets contained in a FedFS domain name space. +.SH DESCRIPTION +The +.BR nsdb-delete-fsn (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. +This command deletes a FedFS +.I fileset name +(FSN) record from an NSDB. +.P +A fileset name, or FSN, uniquely identifies a fileset in FedFS. +An FSN consists of a UUID and the hostname and port of an NSDB. +This pair is intended to be unique across all of FedFS. +The meaning of these items is described in more detail in +.BR fedfs (7). +.P +A FedFS junction contains an FSN. +There can be multiple junctions that contain a particular FSN. +There is exactly one FSN record stored on an NSDB that corresponds to this FSN. +The FSN record can have zero or more FSL records as children. +Replicas of these records can exist on more than one LDAP server. +.P +The +.BR nsdb-delete-fsn (8) +command removes an FSN record from the named NSDB +after it is no longer used in FedFS junctions. +It does not remove FedFS junctions. +To remove a junction, use the +.BR fedfs-delete-junction (8) +command +.P +The default behavior, if the +.B \-\-delete +option is not specified, +removes the specified FSN record and all of its FSL children records. +If the +.B \-\-delete +option is specified, +all FSL child records of the specified FSN record are removed, +but the specified FSN record is left in place. +.P +This command has one positional parameter which specifies +the UUID of the FSN record to modify or remove. +.SH OPTIONS +.IP "\fB\-d, \-\-debug" +Enables debugging messages during operation. +.IP "\fB\-?, \-\-help" +Displays +.BR nsdb-delete-fsn (8) +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 the LDAP server +where the NSDB resides. +If the +.B \-\-binddn +option is not specified, +the value of the FEDFS_NSDB_ADMIN environment variable is consulted. +If this variable is not set, +the NSDB connection parameter database is searched for this DN. +If none of these is specified, or +if this entity does not have permission to modify this area +of the server's DIT, the +.BR nsdb-delete-fsn (8) +command fails. +.IP "\fB-e, \-\-nce=\fINSDB-container-entry-distinguished-name\fP" +Specifies the distinguished name of the NSDB Container Entry +under which the doomed FSN record exists. +If the +.B \-\-nce +option is not specified, +the value of the FEDFS_NSDB_NCE environment variable is consulted. +If this variable is not set, +then the NSDB connection parameter database is searched for this DN. +If none of these is specified, the +.BR nsdb-delete-fsn (8) +command fails. +.IP "\fB\-l, \-\-nsdbname=\fINSDB-host-name\fP" +Specifies the hostname of the NSDB where the doomed FSN record resides. +If the +.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 \-\-nsdbname +option is not specified, the +.BR nsdb-delete-fsn (8) +command fails. +.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" +Specifies the IP port of the NSDB where the doomed FSN record resides. +If the +.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-y, \-\-leavefsn\fP" +Specifies that the specified FSN record should remain, +but all FSL records associated with the specified FSN record should be deleted. +.SH EXIT CODES +The NSDB returns a value that reflects the success of the requested operation. +.TP +.B FEDFS_OK +The LDAP modify request succeeded. +.TP +.B FEDFS_ERR_ACCESS +The bound entity does not have permission to perform the requested operation. +.TP +.B FEDFS_ERR_INVAL +One of the arguments was not valid. +.TP +.B FEDFS_ERR_SVRFAULT +An unanticipated non-protocol error occurred. +.TP +.B FEDFS_ERR_NSDB_ROUTE +The +.BR nsdb-delete-fsn (8) +command was unable to find a route to the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_DOWN +The +.BR nsdb-delete-fsn (8) +command determined that the specified NSDB was down. +.TP +.B FEDFS_ERR_NSDB_CONN +The +.BR nsdb-delete-fsn (8) +command was unable to establish a connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_AUTH +The +.BR nsdb-delete-fsn (8) +command was unable to authenticate +and establish a secure connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP +A non-specific LDAP error occurred on the connection between the +.BR nsdb-delete-fsn (8) +command and specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_VAL +An LDAP error occurred on the connection between the +.BR nsdb-delete-fsn (8) +command and specified NSDB. +The specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_NONCE +The +.BR nsdb-delete-fsn (8) +command was unable to locate the NCE on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_NOFSN +The +.BR nsdb-delete-fsn (8) +command was unable to locate the specified FSN on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_RESPONSE +The +.BR nsdb-delete-fsn (8) +command received a malformed response from the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_FAULT +An unanticipated error related to the specified NSDB occurred. +.TP +.B FEDFS_ERR_NSDB_PARAMS +The local NSDB connection parameter database +does not have any connection parameters on record for the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL +The +.BR nsdb-delete-fsn (8) +command received an LDAP referral that it was unable to follow. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL +The +.BR nsdb-delete-fsn (8) +command received an LDAP referral that it was unable to follow. +A specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED +The +.BR nsdb-delete-fsn (8) +command received an LDAP referral that it chose not to follow, +either because the local implementation does not support +following LDAP referrals or LDAP referral following is disabled. +.TP +.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL +The +.BR nsdb-delete-fsn (8) +command received an LDAP referral that it chose not to follow +because the local NSDB connection parameter database had no +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 remove the FSN record for this FSN: +.RS +.sp + FSN UUID: 8e246ddc-7b46-11e0-8252-000c297fd679 +.br + NSDB: nsdb.example.net:389 +.sp +.RE +Further suppose the NSDB +.I nsdb.example.net:389 +has an NSDB Container Entry whose distinguished name is +.IR o=fedfs . +To delete the corresponding FSN record, you might use: +.RS +.sp +$ nsdb-delete-fsn -D cn=Manager -e o=fedfs \\ +.br + -l nsdb.example.net \\ +.br + 8e246ddc-7b46-11e0-8252-000c297fd679 +.br +Enter NSDB password: +.br +Successfully deleted FSN record + fedfsFsnUuid=8e246ddc-7b46-11e0-8252-000c297fd679,o=fedfs +.sp +.RE +In this example, +all FSL child records for this FSN record are also removed. +.SH SECURITY +Permission to modify the LDAP's DIT is required to delete an FSN record. +The +.BR nsdb-delete-fsn (8) +command must bind as an entity permitted to modify the DIT +to perform this operation. +The +.BR nsdb-delete-fsn (8) +command asks for a password on +.IR stdin . +Standard password blanking techniques are used +to obscure the password on the user's terminal. +.P +The target LDAP server must be registered in the local NSDB connection +parameter database. +The connection security mode listed +in the NSDB connection parameter database +for the target LDAP server is used during this operation. +See +.BR nsdbparams (8) +for details on how to register an NSDB +in the local NSDB connection parameter database. +.SH "SEE ALSO" +.BR fedfs (7), +.BR fedfs-delete-junction (8), +.BR nsdb-delete-fsl (8), +.BR nsdbparams (8) +.sp +RFC 5716 for FedFS requirements and overview +.sp +RFC 4510 for an introduction to LDAP +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/nsdb-delete-nsdb.8 b/doc/man/nsdb-delete-nsdb.8 deleted file mode 100644 index eb1be8e..0000000 --- a/doc/man/nsdb-delete-nsdb.8 +++ /dev/null @@ -1,266 +0,0 @@ -.\"@(#)nsdb-delete-nsdb.8" -.\" -.\" @file doc/man/nsdb-delete-nsdb.8 -.\" @brief man page for nsdb-delete-nsdb client command -.\" - -.\" -.\" Copyright 2011 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH NSDB-REMOVE-NCI 8 "@publication-date@" -.SH NAME -nsdb-delete-nsdb \- remove all FedFS info from an NSDB -.SH SYNOPSIS -.B nsdb-delete-nsdb -.RB [ \-?d ] -.RB [ \-D -.IR binddn ] -.RB [ \-l -.IR nsdbname ] -.RB [ \-r -.IR nsdbport ] -.IR nce -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -The bulk of FedFS junction information in a FedFS domain is stored -on one or more LDAP servers. -These servers are known as -.IR "namespace databases" , -or NSDBs, for short. -.P -FedFS-enabled file servers and clients access the information stored -on NSDBs via standard LDAP queries. -FedFS-enabled file servers use these queries to resolve FedFS junctions. -FedFS administrators use them to manage information -about file sets contained in a FedFS domain name space. -.SH DESCRIPTION -The -.BR nsdb-delete-nsdb (8) -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. -This command wipes part or all of an NSDB clean by -disconnecting an -.IR "NSDB Container Entry" , -or NCE, and removing all FedFS records under it. -.P -This command has one positional parameter which specifies the -fully qualified distinguished name of the NCE to be removed. -.P -The -.BR nsdb-delete-nsdb (8) -command first removes the NSDB container information -for the specified NCE to prevent FedFS-enabled clients and servers -from accessing the FedFS records under that NCE. -Then, it removes all FSN and FSL records under the NCE. -The entry that was the NCE is left on the LDAP server. -.SH OPTIONS -.IP "\fB\-d, \-\-debug" -Enables debugging messages during operation. -.IP "\fB\-?, \-\-help" -Displays -.BR nsdb-delete-nsdb (8) -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 the LDAP server -where the NSDB resides. -If the -.B \-\-binddn -option is not specified, -the value of the FEDFS_NSDB_ADMIN environment variable is consulted. -If this variable is not set, -the NSDB connection parameter database is searched for this DN. -If none of these is specified, or -if this entity does not have permission to modify this area -of the server's DIT, the -.BR nsdb-delete-nsdb (8) -command fails. -.IP "\fB-e, \-\-nce=\fINSDB-container-entry-distinguished-name\fP" -Specifies the distinguished name of the NSDB Container Entry. -This option must be specified on the command line. -No default value is assumed or read from an environment variable. -.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" -Specifies the hostname of the NSDB where the NSDB Container Entry resides. -If the -.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 \-\-nsdbname -option is not specified, the -.BR nsdb-delete-nsdb (8) -command fails. -.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" -Specifies the IP port of the NSDB where the NSDB Container Entry resides. -If the -.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. -.SH EXIT CODES -The NSDB returns a value that reflects the success of the requested operation. -.TP -.B FEDFS_OK -The LDAP modify request succeeded. -.TP -.B FEDFS_ERR_ACCESS -The bound entity does not have permission to perform the requested operation. -.TP -.B FEDFS_ERR_INVAL -One of the arguments was not valid. -.TP -.B FEDFS_ERR_SVRFAULT -An unanticipated non-protocol error occurred. -.TP -.B FEDFS_ERR_NSDB_ROUTE -The -.BR nsdb-delete-nsdb (8) -command was unable to find a route to the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_DOWN -The -.BR nsdb-delete-nsdb (8) -command determined that the specified NSDB was down. -.TP -.B FEDFS_ERR_NSDB_CONN -The -.BR nsdb-delete-nsdb (8) -command was unable to establish a connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_AUTH -The -.BR nsdb-delete-nsdb (8) -command was unable to authenticate -and establish a secure connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP -A non-specific LDAP error occurred on the connection between the -.BR nsdb-delete-nsdb (8) -command and specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_VAL -An LDAP error occurred on the connection between the -.BR nsdb-delete-nsdb (8) -command and specified NSDB. -The specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_RESPONSE -The -.BR nsdb-delete-nsdb (8) -command received a malformed response from the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_FAULT -An unanticipated error related to the specified NSDB occurred. -.TP -.B FEDFS_ERR_NSDB_PARAMS -The local NSDB connection parameter database -does not have any connection parameters on record for the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL -The -.BR nsdb-delete-nsdb (8) -command received an LDAP referral that it was unable to follow. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL -The -.BR nsdb-delete-nsdb (8) -command received an LDAP referral that it was unable to follow. -A specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED -The -.BR nsdb-delete-nsdb (8) -command received an LDAP referral that it chose not to follow, -either because the local implementation does not support -following LDAP referrals or LDAP referral following is disabled. -.TP -.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL -The -.BR nsdb-delete-nsdb (8) -command received an LDAP referral that it chose not to follow -because the local NSDB connection parameter database had no -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 wipe the NCE -.I o=fedfs -from the LDAP server -.IR ldap.example.net . -.RS -.sp -$ nsdb-delete-nsdb -l ldap.example.net -D cn=Manager -e o=fedfs -.br -Enter NSDB password: -.br -Successfully removed NCE -.sp -.RE -This action removes all FedFS records under -.IR o=fedfs . -Compare with the action of the -.BR nsdb-remove-nci (8) -command. -.SH SECURITY -An entity with appropriate authority, such as an administrator entity, -must be used to modify LDAP entries. -The -.BR nsdb-delete-nsdb (8) -command must bind as such an entity to perform this operation. -The -.BR nsdb-delete-nsdb (8) -command asks for a password on -.IR stdin . -Standard password blanking techniques are used -to obscure the password on the user's terminal. -.P -The target LDAP server must be registered in the local NSDB connection -parameter database. -The connection security mode listed -in the NSDB connection parameter database -for the target LDAP server is used during this operation. -See -.BR nsdbparams (8) -for details on how to register an NSDB -in the local NSDB connection parameter database. -.SH "SEE ALSO" -.BR fedfs (7), -.BR nsdb-nces (8), -.BR nsdb-list (8), -.BR nsdb-update-nci (8), -.BR nsdb-remove-nci (8), -.BR nsdbparams (8) -.sp -RFC 5716 for FedFS requirements and overview -.sp -RFC 4510 for an introduction to LDAP -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/nsdb-delete-nsdb.8.in b/doc/man/nsdb-delete-nsdb.8.in new file mode 100644 index 0000000..18358db --- /dev/null +++ b/doc/man/nsdb-delete-nsdb.8.in @@ -0,0 +1,266 @@ +.\"@(#)nsdb-delete-nsdb.8" +.\" +.\" @file doc/man/nsdb-delete-nsdb.8 +.\" @brief man page for nsdb-delete-nsdb client command +.\" + +.\" +.\" Copyright 2011 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH NSDB-REMOVE-NCI 8 "@pubdate@" +.SH NAME +nsdb-delete-nsdb \- remove all FedFS info from an NSDB +.SH SYNOPSIS +.B nsdb-delete-nsdb +.RB [ \-?d ] +.RB [ \-D +.IR binddn ] +.RB [ \-l +.IR nsdbname ] +.RB [ \-r +.IR nsdbport ] +.IR nce +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +The bulk of FedFS junction information in a FedFS domain is stored +on one or more LDAP servers. +These servers are known as +.IR "namespace databases" , +or NSDBs, for short. +.P +FedFS-enabled file servers and clients access the information stored +on NSDBs via standard LDAP queries. +FedFS-enabled file servers use these queries to resolve FedFS junctions. +FedFS administrators use them to manage information +about file sets contained in a FedFS domain name space. +.SH DESCRIPTION +The +.BR nsdb-delete-nsdb (8) +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. +This command wipes part or all of an NSDB clean by +disconnecting an +.IR "NSDB Container Entry" , +or NCE, and removing all FedFS records under it. +.P +This command has one positional parameter which specifies the +fully qualified distinguished name of the NCE to be removed. +.P +The +.BR nsdb-delete-nsdb (8) +command first removes the NSDB container information +for the specified NCE to prevent FedFS-enabled clients and servers +from accessing the FedFS records under that NCE. +Then, it removes all FSN and FSL records under the NCE. +The entry that was the NCE is left on the LDAP server. +.SH OPTIONS +.IP "\fB\-d, \-\-debug" +Enables debugging messages during operation. +.IP "\fB\-?, \-\-help" +Displays +.BR nsdb-delete-nsdb (8) +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 the LDAP server +where the NSDB resides. +If the +.B \-\-binddn +option is not specified, +the value of the FEDFS_NSDB_ADMIN environment variable is consulted. +If this variable is not set, +the NSDB connection parameter database is searched for this DN. +If none of these is specified, or +if this entity does not have permission to modify this area +of the server's DIT, the +.BR nsdb-delete-nsdb (8) +command fails. +.IP "\fB-e, \-\-nce=\fINSDB-container-entry-distinguished-name\fP" +Specifies the distinguished name of the NSDB Container Entry. +This option must be specified on the command line. +No default value is assumed or read from an environment variable. +.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" +Specifies the hostname of the NSDB where the NSDB Container Entry resides. +If the +.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 \-\-nsdbname +option is not specified, the +.BR nsdb-delete-nsdb (8) +command fails. +.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" +Specifies the IP port of the NSDB where the NSDB Container Entry resides. +If the +.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. +.SH EXIT CODES +The NSDB returns a value that reflects the success of the requested operation. +.TP +.B FEDFS_OK +The LDAP modify request succeeded. +.TP +.B FEDFS_ERR_ACCESS +The bound entity does not have permission to perform the requested operation. +.TP +.B FEDFS_ERR_INVAL +One of the arguments was not valid. +.TP +.B FEDFS_ERR_SVRFAULT +An unanticipated non-protocol error occurred. +.TP +.B FEDFS_ERR_NSDB_ROUTE +The +.BR nsdb-delete-nsdb (8) +command was unable to find a route to the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_DOWN +The +.BR nsdb-delete-nsdb (8) +command determined that the specified NSDB was down. +.TP +.B FEDFS_ERR_NSDB_CONN +The +.BR nsdb-delete-nsdb (8) +command was unable to establish a connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_AUTH +The +.BR nsdb-delete-nsdb (8) +command was unable to authenticate +and establish a secure connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP +A non-specific LDAP error occurred on the connection between the +.BR nsdb-delete-nsdb (8) +command and specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_VAL +An LDAP error occurred on the connection between the +.BR nsdb-delete-nsdb (8) +command and specified NSDB. +The specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_RESPONSE +The +.BR nsdb-delete-nsdb (8) +command received a malformed response from the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_FAULT +An unanticipated error related to the specified NSDB occurred. +.TP +.B FEDFS_ERR_NSDB_PARAMS +The local NSDB connection parameter database +does not have any connection parameters on record for the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL +The +.BR nsdb-delete-nsdb (8) +command received an LDAP referral that it was unable to follow. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL +The +.BR nsdb-delete-nsdb (8) +command received an LDAP referral that it was unable to follow. +A specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED +The +.BR nsdb-delete-nsdb (8) +command received an LDAP referral that it chose not to follow, +either because the local implementation does not support +following LDAP referrals or LDAP referral following is disabled. +.TP +.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL +The +.BR nsdb-delete-nsdb (8) +command received an LDAP referral that it chose not to follow +because the local NSDB connection parameter database had no +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 wipe the NCE +.I o=fedfs +from the LDAP server +.IR ldap.example.net . +.RS +.sp +$ nsdb-delete-nsdb -l ldap.example.net -D cn=Manager -e o=fedfs +.br +Enter NSDB password: +.br +Successfully removed NCE +.sp +.RE +This action removes all FedFS records under +.IR o=fedfs . +Compare with the action of the +.BR nsdb-remove-nci (8) +command. +.SH SECURITY +An entity with appropriate authority, such as an administrator entity, +must be used to modify LDAP entries. +The +.BR nsdb-delete-nsdb (8) +command must bind as such an entity to perform this operation. +The +.BR nsdb-delete-nsdb (8) +command asks for a password on +.IR stdin . +Standard password blanking techniques are used +to obscure the password on the user's terminal. +.P +The target LDAP server must be registered in the local NSDB connection +parameter database. +The connection security mode listed +in the NSDB connection parameter database +for the target LDAP server is used during this operation. +See +.BR nsdbparams (8) +for details on how to register an NSDB +in the local NSDB connection parameter database. +.SH "SEE ALSO" +.BR fedfs (7), +.BR nsdb-nces (8), +.BR nsdb-list (8), +.BR nsdb-update-nci (8), +.BR nsdb-remove-nci (8), +.BR nsdbparams (8) +.sp +RFC 5716 for FedFS requirements and overview +.sp +RFC 4510 for an introduction to LDAP +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/nsdb-describe.8 b/doc/man/nsdb-describe.8 deleted file mode 100644 index 78028a8..0000000 --- a/doc/man/nsdb-describe.8 +++ /dev/null @@ -1,314 +0,0 @@ -.\"@(#)nsdb-describe.8" -.\" -.\" @file doc/man/nsdb-describe.8 -.\" @brief man page for nsdb-describe client command -.\" - -.\" -.\" Copyright 2011 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH NSDB-DESCRIBE 8 "@publication-date@" -.SH NAME -nsdb-describe \- modify an fedfsDescr attribute -.SH SYNOPSIS -.B nsdb-describe -.RB [ \-?dy ] -.RB [ \-a -.IR description ] -.RB [ \-D -.IR binddn ] -.RB [ \-l -.IR nsdbname ] -.RB [ \-r -.IR nsdbport ] -.I distinguished-name -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -The bulk of FedFS junction information in a FedFS domain is stored -on one or more LDAP servers. -These servers are known as -.IR "namespace databases" , -or NSDBs, for short. -.P -FedFS-enabled file servers and clients access the information stored -on NSDBs via standard LDAP queries. -FedFS-enabled file servers use these queries to resolve FedFS junctions. -FedFS administrators use them to manage information -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 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 -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 -The -.BR nsdb-describe (8) -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 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 \-\-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" -Enables debugging messages during operation. -.IP "\fB\-?, \-\-help" -Displays -.BR nsdb-describe (8) -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 the LDAP server -where the NSDB resides. -If the -.B \-\-binddn -option is not specified, -the value of the FEDFS_NSDB_ADMIN environment variable is consulted. -If this variable is not set, -the NSDB connection parameter database is searched for this DN. -If none of these is specified, or -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\-l, \-\-nsdbname=\fINSDB-hostname\fP" -Specifies the hostname of the NSDB where the target record resides. -If the -.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 \-\-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 record resides. -If the -.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\-y, \-\-delete\fP" -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 -.B FEDFS_OK -The LDAP modify request succeeded. -.TP -.B FEDFS_ERR_ACCESS -The bound entity does not have permission to perform the requested operation. -.TP -.B FEDFS_ERR_INVAL -One of the arguments was not valid. -.TP -.B FEDFS_ERR_SVRFAULT -An unanticipated non-protocol error occurred. -.TP -.B FEDFS_ERR_NSDB_ROUTE -The -.BR nsdb-describe (8) -command was unable to find a route to the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_DOWN -The -.BR nsdb-describe (8) -command determined that the specified NSDB was down. -.TP -.B FEDFS_ERR_NSDB_CONN -The -.BR nsdb-describe (8) -command was unable to establish a connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_AUTH -The -.BR nsdb-describe (8) -command was unable to authenticate -and establish a secure connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP -A non-specific LDAP error occurred on the connection between the -.BR nsdb-describe (8) -command and specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_VAL -An LDAP error occurred on the connection between the -.BR nsdb-describe (8) -command and specified NSDB. -The specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_NONCE -The -.BR nsdb-describe (8) -command was unable to locate the NCE on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_NOFSN -The -.BR nsdb-describe (8) -command was unable to locate the specified FSN on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_NOFSL -The -.BR nsdb-describe (8) -command was unable to locate any FSLs for the specified FSN -on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_RESPONSE -The -.BR nsdb-describe (8) -command received a malformed response from the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_FAULT -An unanticipated error related to the specified NSDB occurred. -.TP -.B FEDFS_ERR_NSDB_PARAMS -The local NSDB connection parameter database -does not have any connection parameters on record for the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL -The -.BR nsdb-describe (8) -command received an LDAP referral that it was unable to follow. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL -The -.BR nsdb-describe (8) -command received an LDAP referral that it was unable to follow. -A specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED -The -.BR nsdb-describe (8) -command received an LDAP referral that it chose not to follow, -either because the local implementation does not support -following LDAP referrals or LDAP referral following is disabled. -.TP -.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL -The -.BR nsdb-describe (8) -command received an LDAP referral that it chose not to follow -because the local NSDB connection parameter database had no -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 you want to modify the record for -FSN UUID dc25a644-06e4-11e0-ae55-000c29dc7f8a on -the NSDB -.IR nsdb.example.net . -You might use: -.RS -.sp -$ nsdb-describe -l nsdb.example.net \\ -.br - -a "Hello, world\\!" -D cn=Manager \\ -.br - fedfsFsnUuid=dc25a644-06e4-\\ -.br - 11e0-ae55-000c29dc7f8a,o=fedfs -.br -Enter NSDB password: -.br -Successfully updated description value for -.br - fedfsFsnUuid=dc25a644-06e4-11e0-ae55-000c29dc7f8a,o=fedfs -.sp -.RE -To see the new description, use -.BR nsdb-resolve-fsn (8). -.SH SECURITY -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 -to perform this operation. -The -.BR nsdb-describe (8) -command asks for a password on -.IR stdin . -Standard password blanking techniques are used -to obscure the password on the user's terminal. -.P -The target LDAP server must be registered in the local NSDB connection -parameter database. -The connection security mode listed -in the NSDB connection parameter database -for the target LDAP server is used during this operation. -See -.BR nsdbparams (8) -for details on how to register an NSDB -in the local NSDB connection parameter database. -.SH "SEE ALSO" -.BR fedfs (7), -.BR nsdb-resolve-fsn (8), -.BR nsdbparams (8) -.sp -RFC 5716 for FedFS requirements and overview -.sp -RFC 4510 for an introduction to LDAP -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/nsdb-describe.8.in b/doc/man/nsdb-describe.8.in new file mode 100644 index 0000000..dba5874 --- /dev/null +++ b/doc/man/nsdb-describe.8.in @@ -0,0 +1,314 @@ +.\"@(#)nsdb-describe.8" +.\" +.\" @file doc/man/nsdb-describe.8 +.\" @brief man page for nsdb-describe client command +.\" + +.\" +.\" Copyright 2011 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH NSDB-DESCRIBE 8 "@pubdate@" +.SH NAME +nsdb-describe \- modify an fedfsDescr attribute +.SH SYNOPSIS +.B nsdb-describe +.RB [ \-?dy ] +.RB [ \-a +.IR description ] +.RB [ \-D +.IR binddn ] +.RB [ \-l +.IR nsdbname ] +.RB [ \-r +.IR nsdbport ] +.I distinguished-name +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +The bulk of FedFS junction information in a FedFS domain is stored +on one or more LDAP servers. +These servers are known as +.IR "namespace databases" , +or NSDBs, for short. +.P +FedFS-enabled file servers and clients access the information stored +on NSDBs via standard LDAP queries. +FedFS-enabled file servers use these queries to resolve FedFS junctions. +FedFS administrators use them to manage information +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 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 +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 +The +.BR nsdb-describe (8) +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 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 \-\-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" +Enables debugging messages during operation. +.IP "\fB\-?, \-\-help" +Displays +.BR nsdb-describe (8) +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 the LDAP server +where the NSDB resides. +If the +.B \-\-binddn +option is not specified, +the value of the FEDFS_NSDB_ADMIN environment variable is consulted. +If this variable is not set, +the NSDB connection parameter database is searched for this DN. +If none of these is specified, or +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\-l, \-\-nsdbname=\fINSDB-hostname\fP" +Specifies the hostname of the NSDB where the target record resides. +If the +.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 \-\-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 record resides. +If the +.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\-y, \-\-delete\fP" +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 +.B FEDFS_OK +The LDAP modify request succeeded. +.TP +.B FEDFS_ERR_ACCESS +The bound entity does not have permission to perform the requested operation. +.TP +.B FEDFS_ERR_INVAL +One of the arguments was not valid. +.TP +.B FEDFS_ERR_SVRFAULT +An unanticipated non-protocol error occurred. +.TP +.B FEDFS_ERR_NSDB_ROUTE +The +.BR nsdb-describe (8) +command was unable to find a route to the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_DOWN +The +.BR nsdb-describe (8) +command determined that the specified NSDB was down. +.TP +.B FEDFS_ERR_NSDB_CONN +The +.BR nsdb-describe (8) +command was unable to establish a connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_AUTH +The +.BR nsdb-describe (8) +command was unable to authenticate +and establish a secure connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP +A non-specific LDAP error occurred on the connection between the +.BR nsdb-describe (8) +command and specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_VAL +An LDAP error occurred on the connection between the +.BR nsdb-describe (8) +command and specified NSDB. +The specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_NONCE +The +.BR nsdb-describe (8) +command was unable to locate the NCE on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_NOFSN +The +.BR nsdb-describe (8) +command was unable to locate the specified FSN on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_NOFSL +The +.BR nsdb-describe (8) +command was unable to locate any FSLs for the specified FSN +on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_RESPONSE +The +.BR nsdb-describe (8) +command received a malformed response from the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_FAULT +An unanticipated error related to the specified NSDB occurred. +.TP +.B FEDFS_ERR_NSDB_PARAMS +The local NSDB connection parameter database +does not have any connection parameters on record for the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL +The +.BR nsdb-describe (8) +command received an LDAP referral that it was unable to follow. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL +The +.BR nsdb-describe (8) +command received an LDAP referral that it was unable to follow. +A specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED +The +.BR nsdb-describe (8) +command received an LDAP referral that it chose not to follow, +either because the local implementation does not support +following LDAP referrals or LDAP referral following is disabled. +.TP +.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL +The +.BR nsdb-describe (8) +command received an LDAP referral that it chose not to follow +because the local NSDB connection parameter database had no +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 you want to modify the record for +FSN UUID dc25a644-06e4-11e0-ae55-000c29dc7f8a on +the NSDB +.IR nsdb.example.net . +You might use: +.RS +.sp +$ nsdb-describe -l nsdb.example.net \\ +.br + -a "Hello, world\\!" -D cn=Manager \\ +.br + fedfsFsnUuid=dc25a644-06e4-\\ +.br + 11e0-ae55-000c29dc7f8a,o=fedfs +.br +Enter NSDB password: +.br +Successfully updated description value for +.br + fedfsFsnUuid=dc25a644-06e4-11e0-ae55-000c29dc7f8a,o=fedfs +.sp +.RE +To see the new description, use +.BR nsdb-resolve-fsn (8). +.SH SECURITY +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 +to perform this operation. +The +.BR nsdb-describe (8) +command asks for a password on +.IR stdin . +Standard password blanking techniques are used +to obscure the password on the user's terminal. +.P +The target LDAP server must be registered in the local NSDB connection +parameter database. +The connection security mode listed +in the NSDB connection parameter database +for the target LDAP server is used during this operation. +See +.BR nsdbparams (8) +for details on how to register an NSDB +in the local NSDB connection parameter database. +.SH "SEE ALSO" +.BR fedfs (7), +.BR nsdb-resolve-fsn (8), +.BR nsdbparams (8) +.sp +RFC 5716 for FedFS requirements and overview +.sp +RFC 4510 for an introduction to LDAP +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/nsdb-jumpstart.8 b/doc/man/nsdb-jumpstart.8 deleted file mode 100644 index c6e443f..0000000 --- a/doc/man/nsdb-jumpstart.8 +++ /dev/null @@ -1,404 +0,0 @@ -.\"@(#)nsdb-jumpstart.8 -.\" -.\" @file doc/man/nsdb-jumpstart.8 -.\" @brief man page for nsdb-jumpstart tool -.\" - -.\" -.\" Copyright 2013 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH NSDB-JUMPSTART 8 "@publication-date@" -.SH NAME -nsdb-jumpstart \- Administer a basic FedFS NSDB using OpenLDAP -.SH SYNOPSIS -.B nsdb-jumpstart -.RB [ \-h , \-\-help ] -.RB [ \-\-version ] -.P -.B nsdb-jumpstart -.RB [ \-\-statedir = -.IR statedir ] -.B install -.RB [ \-\-security = -.IR mode ] -.P -.B nsdb-jumpstart -.RB [ \-\-statedir = -.IR statedir ] -.B status -.P -.B nsdb-jumpstart -.RB [ \-\-statedir = -.IR statedir ] -.B backup -.P -.B nsdb-jumpstart -.RB [ \-\-statedir = -.IR statedir ] -.B restore -.RI [ backup-name ] -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -A FedFS domain's namespace is joined together via -.IR junctions . -When a file-access client encounters a junction on a file server, -the file server provides a list of locations where that client -can access the target file set to which the juntion refers. -.P -In a FedFS domain, these location lists are stored on one or more LDAP servers, -known as -.IR "namespace databases" , -or -.IR NSDBs , -for short. -.P -FedFS-enabled file servers access the information stored -on NSDBs via standard LDAP queries. -Tools that administer a FedFS domain use ldapmodify queries -to manage information stored on an NSDB. -File-access clients have no need to access NSDBs directly. -.P -Further information about junctions and NSDBs is available in -.BR fedfs (7). -.SH DESCRIPTION -The FedFS NSDB Proposed Standard allows flexible use -of any LDAP server and its Directory Information Tree -to store and manage NSDB information. -.P -The -.BR nsdb-jumpstart (8) -command provides a simplified but fully capable stand-alone -NSDB based specifically on OpenLDAP. -Using this command, -you can install a fresh NSDB, or back up or restore your NSDB data. -It can even construct a self-signed x.509 certificate to enable -secure NSDB queries. -.SS Operation -The -.B install -subcommand sets up an empty NSDB, ready to be used in a FedFS domain. -The new NSDB replaces any OpenLDAP configuration -that may already exist on the system. -OpenLDAP must already be installed on the system. -.P -Once the new NSDB is running, -FedFS fileset location information is stored as records -in a Directory Information Tree under the NCE. -This information is managed with commands like -.BR nsdb-create-fsn (8). -.P -A handful of parameters are needed to set up the new NSDB. -These are gathered via a brief interview. -The domain name and administrator credentials are provided during -this interview. -Passwords are not checked for strength, -however blank passwords are not permitted. -.P -The baseline security requirements for the NSDB are specified -at install time using the -.B \-\-security= -option. See the -.B SECURITY -section for an in-depth discussion. -.P -Once set up with the -.B install -subcommand, OpenLDAP listens for LDAP queries on the standard LDAP port (389). -The underlying LDAP server can be configured like any other OpenLDAP server -using the new-style -.I cn=config -configuration interface. -.P -To display the current status of the NSDB service on the local host, use the -.B status -subcommand. -Information about the local NSDB service is displayed, including whether -the LDAP service is started, whether it actually is an NSDB, and -whether TLS security is required to use it. -.P -The -.BR nsdb-jumpstart (8) -command also provides backup and restore facilities. -The -.B backup -subcommand saves location information stored on the local NSDB -to a dated LDIF file. -LDIF files created by the -.B backup -command are stored in the -.I @statedir@/nsdb-backup -directory by default. -.P -The -.B restore -subcommand completely replaces the contents of the NSDB with a backup -contained in of one of the previously saved LDIF files. -The -.B restore -subcommand takes one positional argument, which is the name of -the backup to restore. -A list of backups is displayed by using the -.B restore -subcommand with no argument. -.P -The -.BR nsdb-jumpstart (8) -command must run as root. -A audit log of each -.BR nsdb-jumpstart (8) -operation is stored in -.IR @statedir@/nsdb-jumpstart.log . -.SS Subcommands -Valid -.BR nsdb-jumpstart (8) -subcommands are: -.IP "\fBinstall\fP" -Replace the OpenLDAP configuration on the local system with -a ready-built NSDB. -The user is asked to confirm before action is taken. -.IP -Specifying the -.B \-\-security= -option sets the transport security that the NSDB requires -clients to use when communicating with it. -.IP "\fBstatus\fP" -Display the status of the NSDB on the local system. -This subcommand takes no arguments. -.IP "\fBbackup\fP" -Generate an LDIF containing the NSDB information stored -on the local LDAP server. -The LDIF is stored in a dated file under -.IR @statedir@/nsdb-backup . -This subcommand takes no arguments. -.IP "\fBrestore\fP" -Replace the NSDB information on the local LDAP server -with the contents of an LDIF. -This subcommand takes a backup name as an argument. -If no backup name is given, -a list of backups that can be restored is displayed. -The user is asked to confirm before action is taken. -.SS Command line options -The following options are specified before the subcommand on the command line. -.IP "\fB\-\-help" -Displays usage and copyright information, then exit. -.IP "\fB\-\-version" -Displays fedfs-utils version information, then exit. -.IP "\fB\-\-stateidr=\fIpathname\fP" -Specifies the pathname of the local directory -under which NSDB data is maintained. -By default, this directory is -.IR @statedir . -.SS Subcommand options -.IP "\fB\-\-security=\fImode\fP" -Selects the security mode of the NSDB. -This option may be specified only on the -.B install -subcommand. -Valid -.I mode -values are -.B none -and -.BR tls . -.P -If -.B none -is specified, or the -.B \-\-security= -option is not specified, clients can connect to this NSDB in the clear. -.P -If -.B tls -is specified, the -.B install -subcommand creates a self-signed x.509 certificate, -and configures the NSDB so that clients are required to use TLS -when connecting to the NSDB. -.SH EXIT CODES -The -.BR nsdb-jumpstart (8) -command returns one of two values upon exit. -.TP -.B 0 -The subcommand succeeded. -.TP -.B 1 -The subcommand failed. -.SH EXAMPLES -Suppose you are the FedFS administrator of the -.I example.net -FedFS domain. -After you have chosen a reliable server in the -.I example.net -domain to act as your NSDB, log in on that server as root, -ensure that OpenLDAP is installed, -and that any configuration can be discarded. -.P -To create a new NSDB with a self-signed certificate for the -.I example.net -domain, use: -.RS -.sp -# ./nsdb-jumpstart install --security=tls -.br -This command is about to replace the OpenLDAP configuration on this system. -.br -Do you want to continue? [y/N] y -.br -Enter the name of the Fedfs domain this NSDB will server -.br -FedFS domain [ example.net ]: -.br -Enter the LDAP administrator DN for this NSDB -.br -Admin DN [ cn=admin,cn=config ]: -.br -Enter the LDAP administrator password for this DN -.br -New password: -.br -Re-enter new password: -.br -Enter the NSDB administrator password for this DN -.br -New password: -.br -Re-enter new password: -.br -Last chance: about to replace the OpenLDAP configuration on this system. -.br -Continue? [y/N] y -.br -Setting up a self-signed x.509 certificate. Please answer the following questions: -.br - -.br -Country (C)? US -.br -State or province (ST)? Massachusetts -.br -City (L)? Boston -.br -Organization (O)? Red Sox -.br -Organizational unit (OU)? Fans -.br - -.br -NSDB configuration was successful. -.br - -.br -Slapd is enabled and running -.br -The LDAP administrator DN is: cn=admin,cn=config -.br -The NSDB administrator DN is: cn=NSDB Manager,dc=example,dc=net -.br -The NCE is: ou=fedfs,dc=example,dc=net -.br - -.br -Distribute the NSDB's certificate in /etc/openldap/nsdb-cert.pem -.br -# -.RE -.SH SECURITY -The NSDB created by the -.BR nsdb-jumpstart (8) -command allows anonymous read access to the NCE and all entries under it. -The LDAP server's rootDSE is also readable by anyone. -An NSDB client must bind with administrator privileges -to update NSDB records for a FedFS domain. -ACLs may be adjusted after the NSDB is set up with -.BR nsdb-jumpstart (8). -.P -Before binding, however, NSDB clients must connect to the NSDB to use it. -The -.B \-\-security= -setting determines what type of transport layer security is required -to connect to the NSDB. -.P -When the -.B \-\-security=none -option is specified during NSDB setup, -or if no -.B \-\-security= -setting is specified, -NSDB clients can connect to the NSDB using an unencrypted -connection to the standard LDAP port (389). -.P -By specifying the -.B \-\-security=tls -option on the -.BR nsdb-jumpstart (8) -command, a self-signed x.509 certificate is created -that NSDB clients must use to authenticate the NSDB and its contents. -The underlying LDAP server requires the use of TLS -and the use of AES or better encryption when a client access the NSDB. -The NSDB never authenticates its clients. -.P -To use this NSDB, the new certificate material must be distributed -to NSDB clients (fileservers and administrative systems) -and installed using the -.BR nsdbparams (8) -command, or it can be transferred directly to NSDB clients that -are running the -.BR rpc.fedfsd (8) -daemon. -.P -The use of a transport encryption mechanism such as TLS is -strongly recommended to protect NSDB requests on untrusted networks. -SASL is currently not supported for the NSDB protocol. -.SH FILES -.TP -.I @statedir/nsdb-jumpstart.log -Log file created during subcommand processing -.TP -.I /etc/openldap/nsdb-cert.pem -File containing the server's x.509 certificate, in PEM format -.TP -.I /etc/openldap/nsdb-key.pem -File containing the server's private key, in PEM format -.TP -.I @statedir/nsdb-db -Directory containing back-end database for the LDAP server's -domain controller root suffix -.SH "SEE ALSO" -.BR fedfs (7), -.BR nfsref (8), -.BR nsdb-create-fsn (8), -.BR nsdbparams (8), -.BR rpc.fedfsd (8) -.sp -RFC 5716 for FedFS requirements and overview -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/nsdb-jumpstart.8.in b/doc/man/nsdb-jumpstart.8.in new file mode 100644 index 0000000..ff22815 --- /dev/null +++ b/doc/man/nsdb-jumpstart.8.in @@ -0,0 +1,404 @@ +.\"@(#)nsdb-jumpstart.8 +.\" +.\" @file doc/man/nsdb-jumpstart.8 +.\" @brief man page for nsdb-jumpstart tool +.\" + +.\" +.\" Copyright 2013 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH NSDB-JUMPSTART 8 "@pubdate@" +.SH NAME +nsdb-jumpstart \- Administer a basic FedFS NSDB using OpenLDAP +.SH SYNOPSIS +.B nsdb-jumpstart +.RB [ \-h , \-\-help ] +.RB [ \-\-version ] +.P +.B nsdb-jumpstart +.RB [ \-\-statedir = +.IR statedir ] +.B install +.RB [ \-\-security = +.IR mode ] +.P +.B nsdb-jumpstart +.RB [ \-\-statedir = +.IR statedir ] +.B status +.P +.B nsdb-jumpstart +.RB [ \-\-statedir = +.IR statedir ] +.B backup +.P +.B nsdb-jumpstart +.RB [ \-\-statedir = +.IR statedir ] +.B restore +.RI [ backup-name ] +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +A FedFS domain's namespace is joined together via +.IR junctions . +When a file-access client encounters a junction on a file server, +the file server provides a list of locations where that client +can access the target file set to which the juntion refers. +.P +In a FedFS domain, these location lists are stored on one or more LDAP servers, +known as +.IR "namespace databases" , +or +.IR NSDBs , +for short. +.P +FedFS-enabled file servers access the information stored +on NSDBs via standard LDAP queries. +Tools that administer a FedFS domain use ldapmodify queries +to manage information stored on an NSDB. +File-access clients have no need to access NSDBs directly. +.P +Further information about junctions and NSDBs is available in +.BR fedfs (7). +.SH DESCRIPTION +The FedFS NSDB Proposed Standard allows flexible use +of any LDAP server and its Directory Information Tree +to store and manage NSDB information. +.P +The +.BR nsdb-jumpstart (8) +command provides a simplified but fully capable stand-alone +NSDB based specifically on OpenLDAP. +Using this command, +you can install a fresh NSDB, or back up or restore your NSDB data. +It can even construct a self-signed x.509 certificate to enable +secure NSDB queries. +.SS Operation +The +.B install +subcommand sets up an empty NSDB, ready to be used in a FedFS domain. +The new NSDB replaces any OpenLDAP configuration +that may already exist on the system. +OpenLDAP must already be installed on the system. +.P +Once the new NSDB is running, +FedFS fileset location information is stored as records +in a Directory Information Tree under the NCE. +This information is managed with commands like +.BR nsdb-create-fsn (8). +.P +A handful of parameters are needed to set up the new NSDB. +These are gathered via a brief interview. +The domain name and administrator credentials are provided during +this interview. +Passwords are not checked for strength, +however blank passwords are not permitted. +.P +The baseline security requirements for the NSDB are specified +at install time using the +.B \-\-security= +option. See the +.B SECURITY +section for an in-depth discussion. +.P +Once set up with the +.B install +subcommand, OpenLDAP listens for LDAP queries on the standard LDAP port (389). +The underlying LDAP server can be configured like any other OpenLDAP server +using the new-style +.I cn=config +configuration interface. +.P +To display the current status of the NSDB service on the local host, use the +.B status +subcommand. +Information about the local NSDB service is displayed, including whether +the LDAP service is started, whether it actually is an NSDB, and +whether TLS security is required to use it. +.P +The +.BR nsdb-jumpstart (8) +command also provides backup and restore facilities. +The +.B backup +subcommand saves location information stored on the local NSDB +to a dated LDIF file. +LDIF files created by the +.B backup +command are stored in the +.I @statedir@/nsdb-backup +directory by default. +.P +The +.B restore +subcommand completely replaces the contents of the NSDB with a backup +contained in of one of the previously saved LDIF files. +The +.B restore +subcommand takes one positional argument, which is the name of +the backup to restore. +A list of backups is displayed by using the +.B restore +subcommand with no argument. +.P +The +.BR nsdb-jumpstart (8) +command must run as root. +A audit log of each +.BR nsdb-jumpstart (8) +operation is stored in +.IR @statedir@/nsdb-jumpstart.log . +.SS Subcommands +Valid +.BR nsdb-jumpstart (8) +subcommands are: +.IP "\fBinstall\fP" +Replace the OpenLDAP configuration on the local system with +a ready-built NSDB. +The user is asked to confirm before action is taken. +.IP +Specifying the +.B \-\-security= +option sets the transport security that the NSDB requires +clients to use when communicating with it. +.IP "\fBstatus\fP" +Display the status of the NSDB on the local system. +This subcommand takes no arguments. +.IP "\fBbackup\fP" +Generate an LDIF containing the NSDB information stored +on the local LDAP server. +The LDIF is stored in a dated file under +.IR @statedir@/nsdb-backup . +This subcommand takes no arguments. +.IP "\fBrestore\fP" +Replace the NSDB information on the local LDAP server +with the contents of an LDIF. +This subcommand takes a backup name as an argument. +If no backup name is given, +a list of backups that can be restored is displayed. +The user is asked to confirm before action is taken. +.SS Command line options +The following options are specified before the subcommand on the command line. +.IP "\fB\-\-help" +Displays usage and copyright information, then exit. +.IP "\fB\-\-version" +Displays fedfs-utils version information, then exit. +.IP "\fB\-\-stateidr=\fIpathname\fP" +Specifies the pathname of the local directory +under which NSDB data is maintained. +By default, this directory is +.IR @statedir@ . +.SS Subcommand options +.IP "\fB\-\-security=\fImode\fP" +Selects the security mode of the NSDB. +This option may be specified only on the +.B install +subcommand. +Valid +.I mode +values are +.B none +and +.BR tls . +.P +If +.B none +is specified, or the +.B \-\-security= +option is not specified, clients can connect to this NSDB in the clear. +.P +If +.B tls +is specified, the +.B install +subcommand creates a self-signed x.509 certificate, +and configures the NSDB so that clients are required to use TLS +when connecting to the NSDB. +.SH EXIT CODES +The +.BR nsdb-jumpstart (8) +command returns one of two values upon exit. +.TP +.B 0 +The subcommand succeeded. +.TP +.B 1 +The subcommand failed. +.SH EXAMPLES +Suppose you are the FedFS administrator of the +.I example.net +FedFS domain. +After you have chosen a reliable server in the +.I example.net +domain to act as your NSDB, log in on that server as root, +ensure that OpenLDAP is installed, +and that any configuration can be discarded. +.P +To create a new NSDB with a self-signed certificate for the +.I example.net +domain, use: +.RS +.sp +# ./nsdb-jumpstart install --security=tls +.br +This command is about to replace the OpenLDAP configuration on this system. +.br +Do you want to continue? [y/N] y +.br +Enter the name of the Fedfs domain this NSDB will server +.br +FedFS domain [ example.net ]: +.br +Enter the LDAP administrator DN for this NSDB +.br +Admin DN [ cn=admin,cn=config ]: +.br +Enter the LDAP administrator password for this DN +.br +New password: +.br +Re-enter new password: +.br +Enter the NSDB administrator password for this DN +.br +New password: +.br +Re-enter new password: +.br +Last chance: about to replace the OpenLDAP configuration on this system. +.br +Continue? [y/N] y +.br +Setting up a self-signed x.509 certificate. Please answer the following questions: +.br + +.br +Country (C)? US +.br +State or province (ST)? Massachusetts +.br +City (L)? Boston +.br +Organization (O)? Red Sox +.br +Organizational unit (OU)? Fans +.br + +.br +NSDB configuration was successful. +.br + +.br +Slapd is enabled and running +.br +The LDAP administrator DN is: cn=admin,cn=config +.br +The NSDB administrator DN is: cn=NSDB Manager,dc=example,dc=net +.br +The NCE is: ou=fedfs,dc=example,dc=net +.br + +.br +Distribute the NSDB's certificate in /etc/openldap/nsdb-cert.pem +.br +# +.RE +.SH SECURITY +The NSDB created by the +.BR nsdb-jumpstart (8) +command allows anonymous read access to the NCE and all entries under it. +The LDAP server's rootDSE is also readable by anyone. +An NSDB client must bind with administrator privileges +to update NSDB records for a FedFS domain. +ACLs may be adjusted after the NSDB is set up with +.BR nsdb-jumpstart (8). +.P +Before binding, however, NSDB clients must connect to the NSDB to use it. +The +.B \-\-security= +setting determines what type of transport layer security is required +to connect to the NSDB. +.P +When the +.B \-\-security=none +option is specified during NSDB setup, +or if no +.B \-\-security= +setting is specified, +NSDB clients can connect to the NSDB using an unencrypted +connection to the standard LDAP port (389). +.P +By specifying the +.B \-\-security=tls +option on the +.BR nsdb-jumpstart (8) +command, a self-signed x.509 certificate is created +that NSDB clients must use to authenticate the NSDB and its contents. +The underlying LDAP server requires the use of TLS +and the use of AES or better encryption when a client access the NSDB. +The NSDB never authenticates its clients. +.P +To use this NSDB, the new certificate material must be distributed +to NSDB clients (fileservers and administrative systems) +and installed using the +.BR nsdbparams (8) +command, or it can be transferred directly to NSDB clients that +are running the +.BR rpc.fedfsd (8) +daemon. +.P +The use of a transport encryption mechanism such as TLS is +strongly recommended to protect NSDB requests on untrusted networks. +SASL is currently not supported for the NSDB protocol. +.SH FILES +.TP +.I @statedir@/nsdb-jumpstart.log +Log file created during subcommand processing +.TP +.I /etc/openldap/nsdb-cert.pem +File containing the server's x.509 certificate, in PEM format +.TP +.I /etc/openldap/nsdb-key.pem +File containing the server's private key, in PEM format +.TP +.I @statedir@/nsdb-db +Directory containing back-end database for the LDAP server's +domain controller root suffix +.SH "SEE ALSO" +.BR fedfs (7), +.BR nfsref (8), +.BR nsdb-create-fsn (8), +.BR nsdbparams (8), +.BR rpc.fedfsd (8) +.sp +RFC 5716 for FedFS requirements and overview +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/nsdb-list.8 b/doc/man/nsdb-list.8 deleted file mode 100644 index 11f993f..0000000 --- a/doc/man/nsdb-list.8 +++ /dev/null @@ -1,251 +0,0 @@ -.\"@(#)nsdb-list.8" -.\" -.\" @file doc/man/nsdb-list.8 -.\" @brief man page for nsdb-list client command -.\" - -.\" -.\" Copyright 2011 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH NSDB-LIST 8 "@publication-date@" -.SH NAME -nsdb-list \- list file set name and location entries on an NSDB -.SH SYNOPSIS -.B nsdb-list -.RB [ \-?d ] -.RB [ \-e -.IR nce ] -.RB [ \-l -.IR nsdbname ] -.RB [ \-r -.IR nsdbport ] -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -The bulk of FedFS junction information in a FedFS domain is stored -on one or more LDAP servers. -These servers are known as -.IR "namespace databases" , -or NSDBs, for short. -.P -FedFS-enabled file servers and clients access the information stored -on NSDBs via standard LDAP queries. -FedFS-enabled file servers use these queries to resolve FedFS junctions. -FedFS administrators use them to manage information -about file sets contained in a FedFS domain name space. -.SH DESCRIPTION -The -.BR nsdb-list (8) -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 retrieves the list of file set name and location records -stored on an NSDB -under one NSDB Container Entry. -.SH OPTIONS -.IP "\fB\-d, \-\-debug" -Specifies that debugging messages be produced during operation. -.IP "\fB\-?, \-\-help" -Prints an -.BR nsdb-list (8) -version and usage message on -.IR stderr , -then exits. -.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" -Specifies the hostname of the NSDB to enumerate. -If the -.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 --nsdbname -option is not specified, the -.BR nsdb-list (8) -command fails. -.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" -Specifies the IP port of the NSDB to enumerate. -If the -.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\-e, \-\-nce=\fINSDB-container-entry\fP" -Limits the query to a particular NSDB Container Entry on the target NSDB. -If the -.B --nce -option is not specified, -the value of the FEDFS_NSDB_NCE environment variable is consulted. -If the variable is not set and the -.B --nce -option is not specified, -or the specified NCE does not exist on the target NSDB, the -.BR nsdb-list (8) -command fails. -.SH EXIT CODES -The NSDB returns a value that reflects the success of the requested operation. -.TP -.B FEDFS_OK -The LDAP query succeeded. -A list of FSN and FSL records are summarized on -.IR stdout . -.TP -.B FEDFS_ERR_ACCESS -The anonymous entity does not have permission to perform the requested operation. -.TP -.B FEDFS_ERR_INVAL -One of the arguments was not valid. -.TP -.B FEDFS_ERR_SVRFAULT -An unanticipated non-protocol error occurred. -.TP -.B FEDFS_ERR_NSDB_ROUTE -The -.BR nsdb-list (8) -command was unable to find a route to the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_DOWN -The -.BR nsdb-list (8) -command determined that the specified NSDB was down. -.TP -.B FEDFS_ERR_NSDB_CONN -The -.BR nsdb-list (8) -command was unable to establish a connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_AUTH -The -.BR nsdb-list (8) -command was unable to authenticate -and establish a secure connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP -A non-specific LDAP error occurred on the connection between the -.BR nsdb-list (8) -command and specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_VAL -An LDAP error occurred on the connection between the -.BR nsdb-list (8) -command and specified NSDB. -The specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_NONCE -The -.BR nsdb-list (8) -command was unable to locate the NCE on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_RESPONSE -The -.BR nsdb-list (8) -command received a malformed response from the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_FAULT -An unanticipated error related to the specified NSDB occurred. -.TP -.B FEDFS_ERR_NSDB_PARAMS -The local NSDB connection parameter database -does not have any connection parameters on record for the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL -The -.BR nsdb-list (8) -command received an LDAP referral that it was unable to follow. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL -The -.BR nsdb-list (8) -command received an LDAP referral that it was unable to follow. -A specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED -The -.BR nsdb-list (8) -command received an LDAP referral that it chose not to follow, -either because the local implementation does not support -following LDAP referrals or LDAP referral following is disabled. -.TP -.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL -The -.BR nsdb-list (8) -command received an LDAP referral that it chose not to follow -because the local NSDB connection parameter database had no -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 know if the LDAP server -.IR ldap.example.net -is an NSDB. Use: -.RS -.sp -$ nsdb-list -l ldap.example.net -e o=fedfs -.br -NSDB: ldap.example.net:389 -.sp - NCE: o=fedfs -.sp - FSN UUID: c1c21720-1fcd-4ad6-a837-f57af4cf2972 -.br - FSL UUID: 4c887035-ad2f-4ba8-ab75-7118df9714cd -.br - FSL UUID: 84445758-b5fb-4acc-814b-cc121b3bafe9 -.sp -.RE -There is a single file set name, with two file set location records, -registered under "o=fedfs" on this NSDB. -To resolve the listed FSN UUID, use the -.BR nsdb-resolve-junction (8) -command. -.SH SECURITY -The NSDB protocol draft standard requires that FedFS FSN and FSL -records are readable by everyone. -The -.BR nsdb-list (8) -command uses anonymous binding when performing LDAP queries. -.P -The target LDAP server must be registered in the local NSDB connection -parameter database. -The connection security mode listed -in the NSDB connection parameter database -for the target LDAP server is used during this operation. -See -.BR nsdbparams (8) -for details on how to register an NSDB -in the local NSDB connection parameter database. -.SH "SEE ALSO" -.BR fedfs (7), -.BR nsdb-resolve-junction (8), -.BR nsdbparams (8) -.sp -RFC 5716 for FedFS requirements and overview -.sp -RFC 4510 for an introduction to LDAP -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/nsdb-list.8.in b/doc/man/nsdb-list.8.in new file mode 100644 index 0000000..9f2c668 --- /dev/null +++ b/doc/man/nsdb-list.8.in @@ -0,0 +1,251 @@ +.\"@(#)nsdb-list.8" +.\" +.\" @file doc/man/nsdb-list.8 +.\" @brief man page for nsdb-list client command +.\" + +.\" +.\" Copyright 2011 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH NSDB-LIST 8 "@pubdate@" +.SH NAME +nsdb-list \- list file set name and location entries on an NSDB +.SH SYNOPSIS +.B nsdb-list +.RB [ \-?d ] +.RB [ \-e +.IR nce ] +.RB [ \-l +.IR nsdbname ] +.RB [ \-r +.IR nsdbport ] +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +The bulk of FedFS junction information in a FedFS domain is stored +on one or more LDAP servers. +These servers are known as +.IR "namespace databases" , +or NSDBs, for short. +.P +FedFS-enabled file servers and clients access the information stored +on NSDBs via standard LDAP queries. +FedFS-enabled file servers use these queries to resolve FedFS junctions. +FedFS administrators use them to manage information +about file sets contained in a FedFS domain name space. +.SH DESCRIPTION +The +.BR nsdb-list (8) +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 retrieves the list of file set name and location records +stored on an NSDB +under one NSDB Container Entry. +.SH OPTIONS +.IP "\fB\-d, \-\-debug" +Specifies that debugging messages be produced during operation. +.IP "\fB\-?, \-\-help" +Prints an +.BR nsdb-list (8) +version and usage message on +.IR stderr , +then exits. +.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" +Specifies the hostname of the NSDB to enumerate. +If the +.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 --nsdbname +option is not specified, the +.BR nsdb-list (8) +command fails. +.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" +Specifies the IP port of the NSDB to enumerate. +If the +.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\-e, \-\-nce=\fINSDB-container-entry\fP" +Limits the query to a particular NSDB Container Entry on the target NSDB. +If the +.B --nce +option is not specified, +the value of the FEDFS_NSDB_NCE environment variable is consulted. +If the variable is not set and the +.B --nce +option is not specified, +or the specified NCE does not exist on the target NSDB, the +.BR nsdb-list (8) +command fails. +.SH EXIT CODES +The NSDB returns a value that reflects the success of the requested operation. +.TP +.B FEDFS_OK +The LDAP query succeeded. +A list of FSN and FSL records are summarized on +.IR stdout . +.TP +.B FEDFS_ERR_ACCESS +The anonymous entity does not have permission to perform the requested operation. +.TP +.B FEDFS_ERR_INVAL +One of the arguments was not valid. +.TP +.B FEDFS_ERR_SVRFAULT +An unanticipated non-protocol error occurred. +.TP +.B FEDFS_ERR_NSDB_ROUTE +The +.BR nsdb-list (8) +command was unable to find a route to the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_DOWN +The +.BR nsdb-list (8) +command determined that the specified NSDB was down. +.TP +.B FEDFS_ERR_NSDB_CONN +The +.BR nsdb-list (8) +command was unable to establish a connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_AUTH +The +.BR nsdb-list (8) +command was unable to authenticate +and establish a secure connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP +A non-specific LDAP error occurred on the connection between the +.BR nsdb-list (8) +command and specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_VAL +An LDAP error occurred on the connection between the +.BR nsdb-list (8) +command and specified NSDB. +The specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_NONCE +The +.BR nsdb-list (8) +command was unable to locate the NCE on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_RESPONSE +The +.BR nsdb-list (8) +command received a malformed response from the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_FAULT +An unanticipated error related to the specified NSDB occurred. +.TP +.B FEDFS_ERR_NSDB_PARAMS +The local NSDB connection parameter database +does not have any connection parameters on record for the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL +The +.BR nsdb-list (8) +command received an LDAP referral that it was unable to follow. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL +The +.BR nsdb-list (8) +command received an LDAP referral that it was unable to follow. +A specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED +The +.BR nsdb-list (8) +command received an LDAP referral that it chose not to follow, +either because the local implementation does not support +following LDAP referrals or LDAP referral following is disabled. +.TP +.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL +The +.BR nsdb-list (8) +command received an LDAP referral that it chose not to follow +because the local NSDB connection parameter database had no +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 know if the LDAP server +.IR ldap.example.net +is an NSDB. Use: +.RS +.sp +$ nsdb-list -l ldap.example.net -e o=fedfs +.br +NSDB: ldap.example.net:389 +.sp + NCE: o=fedfs +.sp + FSN UUID: c1c21720-1fcd-4ad6-a837-f57af4cf2972 +.br + FSL UUID: 4c887035-ad2f-4ba8-ab75-7118df9714cd +.br + FSL UUID: 84445758-b5fb-4acc-814b-cc121b3bafe9 +.sp +.RE +There is a single file set name, with two file set location records, +registered under "o=fedfs" on this NSDB. +To resolve the listed FSN UUID, use the +.BR nsdb-resolve-junction (8) +command. +.SH SECURITY +The NSDB protocol draft standard requires that FedFS FSN and FSL +records are readable by everyone. +The +.BR nsdb-list (8) +command uses anonymous binding when performing LDAP queries. +.P +The target LDAP server must be registered in the local NSDB connection +parameter database. +The connection security mode listed +in the NSDB connection parameter database +for the target LDAP server is used during this operation. +See +.BR nsdbparams (8) +for details on how to register an NSDB +in the local NSDB connection parameter database. +.SH "SEE ALSO" +.BR fedfs (7), +.BR nsdb-resolve-junction (8), +.BR nsdbparams (8) +.sp +RFC 5716 for FedFS requirements and overview +.sp +RFC 4510 for an introduction to LDAP +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/nsdb-nces.8 b/doc/man/nsdb-nces.8 deleted file mode 100644 index 0c3e523..0000000 --- a/doc/man/nsdb-nces.8 +++ /dev/null @@ -1,260 +0,0 @@ -.\"@(#)nsdb-nces.8" -.\" -.\" @file doc/man/nsdb-nces.8 -.\" @brief man page for nsdb-nces client command -.\" - -.\" -.\" Copyright 2011 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH NSDB-NCES 8 "@publication-date@" -.SH NAME -nsdb-nces \- list NSDB container entries on an LDAP server -.SH SYNOPSIS -.B nsdb-nces -.RB [ \-?d ] -.RB [ \-l -.IR nsdbname ] -.RB [ \-r -.IR nsdbport ] -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -The bulk of FedFS junction information in a FedFS domain is stored -on one or more LDAP servers. -These servers are known as -.IR "namespace databases" , -or NSDBs, for short. -.P -FedFS-enabled file servers and clients access the information stored -on NSDBs via standard LDAP queries. -FedFS-enabled file servers use these queries to resolve FedFS junctions. -FedFS administrators use them to manage information -about file sets contained in a FedFS domain name space. -.SH DESCRIPTION -The -.BR nsdb-nces (8) -command is part of a collection of low-level single-use programs -that in intended for testing the NSDB protocol or for use in scripts. -It queries an LDAP server for the existance of -.IR "NSDB Container Entries" , -or -.IR NCEs , -for short. -.P -The top of the Directory Information Tree on an LDAP server has -one or more -.IR "naming contexts" . -Some LDAP server implementations call these contexts "root suffixes". -All LDAP entries on that server are contained under one of these -contexts. -.P -The LDAP object under which FedFS-related entries reside -is known as the -.I NSDB Container Entry -(or NCE). -The NCE can be a naming context object, -or it can be located somewhere below the naming context. -Both the naming context and the NCE must be world-readable -for FedFS-enabled clients and servers to access the NSDB. -.P -The -.BR nsdb-nces (8) -command displays each naming context on a target LDAP server -and indicates whether that context contains an NCE. -At its simplest, you can think of the -.BR nsdb-nces (8) -command as a form of NSDB ping. -However, it can also convey certain details about the organization -of any NCEs on an LDAP server. -Discovering NCEs on an NSDB is always the first step -FedFS-enabled file servers perform when resolving a FedFS junction. -.SH OPTIONS -.IP "\fB\-d, \-\-debug" -Specifies that debugging messages be produced during operation. -.IP "\fB\-?, \-\-help" -Prints an -.BR nsdb-nces (8) -version and usage message on -.IR stderr , -then exits. -.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" -Specifies the hostname of the NSDB to enumerate. -If the -.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 --nsdbname -option is not specified, the -.BR nsdb-nces (8) -command fails. -.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" -Specifies the IP port of the NSDB to enumerate. -If the -.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. -.SH EXIT CODES -The NSDB returns a value that reflects the success of the requested operation. -.TP -.B FEDFS_OK -The LDAP query succeeded. -One or more NSDB container entries were detected on the target LDAP server. -.TP -.B FEDFS_ERR_ACCESS -The anonymous entity does not have permission to perform the requested operation. -.TP -.B FEDFS_ERR_INVAL -One of the arguments was not valid. -.TP -.B FEDFS_ERR_SVRFAULT -An unanticipated non-protocol error occurred. -.TP -.B FEDFS_ERR_NSDB_ROUTE -The -.BR nsdb-nces (8) -command was unable to find a route to the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_DOWN -The -.BR nsdb-nces (8) -command determined that the specified NSDB was down. -.TP -.B FEDFS_ERR_NSDB_CONN -The -.BR nsdb-nces (8) -command was unable to establish a connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_AUTH -The -.BR nsdb-nces (8) -command was unable to authenticate -and establish a secure connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP -A non-specific LDAP error occurred on the connection between the -.BR nsdb-nces (8) -command and specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_VAL -An LDAP error occurred on the connection between the -.BR nsdb-nces (8) -command and specified NSDB. -The specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_NONCE -The -.BR nsdb-nces (8) -command was unable to locate any NCEs on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_RESPONSE -The -.BR nsdb-nces (8) -command received a malformed response from the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_FAULT -An unanticipated error related to the specified NSDB occurred. -.TP -.B FEDFS_ERR_NSDB_PARAMS -The local NSDB connection parameter database -does not have any connection parameters on record for the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL -The -.BR nsdb-nces (8) -command received an LDAP referral that it was unable to follow. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL -The -.BR nsdb-nces (8) -command received an LDAP referral that it was unable to follow. -A specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED -The -.BR nsdb-nces (8) -command received an LDAP referral that it chose not to follow, -either because the local implementation does not support -following LDAP referrals or LDAP referral following is disabled. -.TP -.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL -The -.BR nsdb-nces (8) -command received an LDAP referral that it chose not to follow -because the local NSDB connection parameter database had no -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 know if the LDAP server -.IR ldap.example.net -is an NSDB. Use: -.RS -.sp -$ nsdb-nces -l ldap.example.net -.br -Host: ldap.example.net:389 -.br - namingContext 'dc=example,dc=net' does not host an NCE. -.br - namingContext 'o=fedfs' hosts an NCE at 'o=fedfs'. -.br - namingContext 'o=netscaperoot' does not host an NCE. -.sp -.RE -This shows there are three LDAP naming contexts on the target LDAP server. -One of these is an NSDB Container Entry. -Thus the target LDAP server is an NSDB. -.SH SECURITY -The -.BR nsdb-nces (8) -command uses anonymous binding when performing LDAP queries. -LDAP naming contexts are typically readable by everyone. -.P -The target LDAP server must be registered in the local NSDB connection -parameter database. -The connection security mode listed -in the NSDB connection parameter database -for the target LDAP server is used during this operation. -See -.BR nsdbparams (8) -for details on how to register an NSDB -in the local NSDB connection parameter database. -.SH "SEE ALSO" -.BR fedfs (7), -.BR nsdbparams (8) -.sp -RFC 5716 for FedFS requirements and overview -.sp -RFC 4510 for an introduction to LDAP -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/nsdb-nces.8.in b/doc/man/nsdb-nces.8.in new file mode 100644 index 0000000..6381768 --- /dev/null +++ b/doc/man/nsdb-nces.8.in @@ -0,0 +1,260 @@ +.\"@(#)nsdb-nces.8" +.\" +.\" @file doc/man/nsdb-nces.8 +.\" @brief man page for nsdb-nces client command +.\" + +.\" +.\" Copyright 2011 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH NSDB-NCES 8 "@pubdate@" +.SH NAME +nsdb-nces \- list NSDB container entries on an LDAP server +.SH SYNOPSIS +.B nsdb-nces +.RB [ \-?d ] +.RB [ \-l +.IR nsdbname ] +.RB [ \-r +.IR nsdbport ] +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +The bulk of FedFS junction information in a FedFS domain is stored +on one or more LDAP servers. +These servers are known as +.IR "namespace databases" , +or NSDBs, for short. +.P +FedFS-enabled file servers and clients access the information stored +on NSDBs via standard LDAP queries. +FedFS-enabled file servers use these queries to resolve FedFS junctions. +FedFS administrators use them to manage information +about file sets contained in a FedFS domain name space. +.SH DESCRIPTION +The +.BR nsdb-nces (8) +command is part of a collection of low-level single-use programs +that in intended for testing the NSDB protocol or for use in scripts. +It queries an LDAP server for the existance of +.IR "NSDB Container Entries" , +or +.IR NCEs , +for short. +.P +The top of the Directory Information Tree on an LDAP server has +one or more +.IR "naming contexts" . +Some LDAP server implementations call these contexts "root suffixes". +All LDAP entries on that server are contained under one of these +contexts. +.P +The LDAP object under which FedFS-related entries reside +is known as the +.I NSDB Container Entry +(or NCE). +The NCE can be a naming context object, +or it can be located somewhere below the naming context. +Both the naming context and the NCE must be world-readable +for FedFS-enabled clients and servers to access the NSDB. +.P +The +.BR nsdb-nces (8) +command displays each naming context on a target LDAP server +and indicates whether that context contains an NCE. +At its simplest, you can think of the +.BR nsdb-nces (8) +command as a form of NSDB ping. +However, it can also convey certain details about the organization +of any NCEs on an LDAP server. +Discovering NCEs on an NSDB is always the first step +FedFS-enabled file servers perform when resolving a FedFS junction. +.SH OPTIONS +.IP "\fB\-d, \-\-debug" +Specifies that debugging messages be produced during operation. +.IP "\fB\-?, \-\-help" +Prints an +.BR nsdb-nces (8) +version and usage message on +.IR stderr , +then exits. +.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" +Specifies the hostname of the NSDB to enumerate. +If the +.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 --nsdbname +option is not specified, the +.BR nsdb-nces (8) +command fails. +.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" +Specifies the IP port of the NSDB to enumerate. +If the +.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. +.SH EXIT CODES +The NSDB returns a value that reflects the success of the requested operation. +.TP +.B FEDFS_OK +The LDAP query succeeded. +One or more NSDB container entries were detected on the target LDAP server. +.TP +.B FEDFS_ERR_ACCESS +The anonymous entity does not have permission to perform the requested operation. +.TP +.B FEDFS_ERR_INVAL +One of the arguments was not valid. +.TP +.B FEDFS_ERR_SVRFAULT +An unanticipated non-protocol error occurred. +.TP +.B FEDFS_ERR_NSDB_ROUTE +The +.BR nsdb-nces (8) +command was unable to find a route to the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_DOWN +The +.BR nsdb-nces (8) +command determined that the specified NSDB was down. +.TP +.B FEDFS_ERR_NSDB_CONN +The +.BR nsdb-nces (8) +command was unable to establish a connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_AUTH +The +.BR nsdb-nces (8) +command was unable to authenticate +and establish a secure connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP +A non-specific LDAP error occurred on the connection between the +.BR nsdb-nces (8) +command and specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_VAL +An LDAP error occurred on the connection between the +.BR nsdb-nces (8) +command and specified NSDB. +The specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_NONCE +The +.BR nsdb-nces (8) +command was unable to locate any NCEs on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_RESPONSE +The +.BR nsdb-nces (8) +command received a malformed response from the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_FAULT +An unanticipated error related to the specified NSDB occurred. +.TP +.B FEDFS_ERR_NSDB_PARAMS +The local NSDB connection parameter database +does not have any connection parameters on record for the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL +The +.BR nsdb-nces (8) +command received an LDAP referral that it was unable to follow. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL +The +.BR nsdb-nces (8) +command received an LDAP referral that it was unable to follow. +A specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED +The +.BR nsdb-nces (8) +command received an LDAP referral that it chose not to follow, +either because the local implementation does not support +following LDAP referrals or LDAP referral following is disabled. +.TP +.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL +The +.BR nsdb-nces (8) +command received an LDAP referral that it chose not to follow +because the local NSDB connection parameter database had no +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 know if the LDAP server +.IR ldap.example.net +is an NSDB. Use: +.RS +.sp +$ nsdb-nces -l ldap.example.net +.br +Host: ldap.example.net:389 +.br + namingContext 'dc=example,dc=net' does not host an NCE. +.br + namingContext 'o=fedfs' hosts an NCE at 'o=fedfs'. +.br + namingContext 'o=netscaperoot' does not host an NCE. +.sp +.RE +This shows there are three LDAP naming contexts on the target LDAP server. +One of these is an NSDB Container Entry. +Thus the target LDAP server is an NSDB. +.SH SECURITY +The +.BR nsdb-nces (8) +command uses anonymous binding when performing LDAP queries. +LDAP naming contexts are typically readable by everyone. +.P +The target LDAP server must be registered in the local NSDB connection +parameter database. +The connection security mode listed +in the NSDB connection parameter database +for the target LDAP server is used during this operation. +See +.BR nsdbparams (8) +for details on how to register an NSDB +in the local NSDB connection parameter database. +.SH "SEE ALSO" +.BR fedfs (7), +.BR nsdbparams (8) +.sp +RFC 5716 for FedFS requirements and overview +.sp +RFC 4510 for an introduction to LDAP +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/nsdb-parameters.7 b/doc/man/nsdb-parameters.7 deleted file mode 100644 index 2f10373..0000000 --- a/doc/man/nsdb-parameters.7 +++ /dev/null @@ -1,161 +0,0 @@ -.\"@(#)nsdb-parameters.7" -.\" -.\" @file doc/man/nsdb-parameters.7 -.\" @brief NSDB connection parameters -.\" - -.\" -.\" Copyright 2012 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH NSDB-PARAMETERS 7 "@publication-date@" -.SH NAME -nsdb-parameters \- NSDB connection parameters -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -The bulk of FedFS metadata is stored on one or more LDAP servers. -These servers are known as -.IR "namespace databases" , -or NSDBs, for short. -An -.I NSDB client -is any system that communicates with an NSDB. -This can be either a fileserver or an NSDB administrative client. -.P -On NSDB clients, -a small local database stores information about how to connect -to each NSDB node. These -.I NSDB connection parameters -are used when a fileserver contacts an NSDB node to resolve junctions, -or when executing NSDB administrative commands. -.P -The settings in this database effect only the behavior of NSDB clients -on the local system. They have no effect on the operation -of NSDB nodes or other NSDB clients. -.SH DESCRIPTION -Before an NSDB client may communicate with an NSDB node, that client -must know how to contact the NSDB. -The client's local NSDB connnection parameter database contains the -DNS hostname, IP port number, and connection security type of each -NSDB node that can be contacted. -Administrators must provide this information in advance. -.SS NSDB name equality -The local NSDB connection parameter database is indexed by each NSDB -node's DNS hostname and IP port number. Two NSDB node names -are equivalent if their respective DNS hostnames and port numbers -are an exact match. -.P -Before matching, the special port value "0" is always mapped to the -standard LDAP port "389." -Likewise, if no port is specified, "389" is assumed. -.P -Upper and lower case are considered equivalent. -The IP addresses to which hostnames are bound are not considered -when matching. -.P -For example, the NSDB "nsdb.example.net:389 would share a database -entry with "nsdb.EXAMPLE.NET:0", but not with "nsdb.example.net:636". -If "nsdb.example.com:389" maps to 10.0.0.1 and "nsdb.example.net:389" -also maps to that address, the database maintains separate entries for -each, although the same connection parameters may be set for both -entries. -.SS Connection security -One of two connection security types may be specified in an NSDB -connection parameter entry: -.IP "\fBNONE\fP" -The local system communicates with the NSDB node in plain-text. -The local system performs no authentication of the NSDB node. -.IP "\fBTLS\fP" -The local system always uses Transport Layer Security when -communicating with the NSDB node. -The local system authenticates the -NSDB node before making requests. -Integrity or encryption is used during communication. -Requests to the NSDB node fail if a TLS session cannot be established. -.P -.B NONE -is a low-overhead mode for use when the network and the NSDB are -trusted by all NSDB clients. -.B TLS -is a high-security mode for use when NSDBs operate on untrusted public -networks, but it requires the additional burden of creating and -distributing x.509 certificates for each NSDB. -.P -An NSDB node can operate in one of three security modes: -.IP "\fBBasic\fP" -NSDB clients connect to this NSDB node using only FEDFS_SEC_NONE security. -.IP "\fBTransitional\fP" -NSDB clients connect to this NSDB node using either FEDFS_SEC_NONE or -FEDFS_SEC_TLS security. -.IP "\fBSecure\fP" -NSDB clients connect to this NSDB node using only FEDFS_SEC_TLS security. -.P -An NSDB client always uses the security type specified in its local -NSDB connection parameter database for that NSDB node. -For greatest security, it is recommended that NSDB nodes be configured as -.B secure -NSDBs (see table above). -.SS x.509 certificates -Administrators provide the certificate material used to authenticate -an NSDB node in a PEM format file that contains an x.509v3 certificate -chain. -.P -This file may contain just the public certificate of the Certificate -Authority (CA) which signed the NSDB's certificate. Or it may contain -a chain of certificates that represents the full chain of trust for -the NSDB node. -A self-signed CA certificate may be used to reduce the burden -of setting up NSDBs for your FedFS domain. -.P -Either the -.BR fedfs-set-nsdb-params (8) -command is used to transfer this material to a remote fileserver running -a FedFS ADMIN service, or the -.BR nsdbparams (8) -command is used to install this material in the NSDB connection parameter -database on the local system. -For both commands, the file containing certificates for one NSDB is -specified on the command line with the -.B "\-\-certfile" -option. -.P -The certificate material provisioned via these commands is used for no -other purpose on the local system than NSDB authentication. -.SH "SEE ALSO" -.BR fedfs (7), -.BR nsdbparams (8), -.BR rpc.fedfsd (8), -.BR fedfs-set-nsdb-params (8) -.sp -RFC 5661 for a description of NFS version 4 referrals -.sp -RFC 5716 for FedFS requirements and overview -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/nsdb-parameters.7.in b/doc/man/nsdb-parameters.7.in new file mode 100644 index 0000000..7b4ef11 --- /dev/null +++ b/doc/man/nsdb-parameters.7.in @@ -0,0 +1,161 @@ +.\"@(#)nsdb-parameters.7" +.\" +.\" @file doc/man/nsdb-parameters.7 +.\" @brief NSDB connection parameters +.\" + +.\" +.\" Copyright 2012 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH NSDB-PARAMETERS 7 "@pubdate@" +.SH NAME +nsdb-parameters \- NSDB connection parameters +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +The bulk of FedFS metadata is stored on one or more LDAP servers. +These servers are known as +.IR "namespace databases" , +or NSDBs, for short. +An +.I NSDB client +is any system that communicates with an NSDB. +This can be either a fileserver or an NSDB administrative client. +.P +On NSDB clients, +a small local database stores information about how to connect +to each NSDB node. These +.I NSDB connection parameters +are used when a fileserver contacts an NSDB node to resolve junctions, +or when executing NSDB administrative commands. +.P +The settings in this database effect only the behavior of NSDB clients +on the local system. They have no effect on the operation +of NSDB nodes or other NSDB clients. +.SH DESCRIPTION +Before an NSDB client may communicate with an NSDB node, that client +must know how to contact the NSDB. +The client's local NSDB connnection parameter database contains the +DNS hostname, IP port number, and connection security type of each +NSDB node that can be contacted. +Administrators must provide this information in advance. +.SS NSDB name equality +The local NSDB connection parameter database is indexed by each NSDB +node's DNS hostname and IP port number. Two NSDB node names +are equivalent if their respective DNS hostnames and port numbers +are an exact match. +.P +Before matching, the special port value "0" is always mapped to the +standard LDAP port "389." +Likewise, if no port is specified, "389" is assumed. +.P +Upper and lower case are considered equivalent. +The IP addresses to which hostnames are bound are not considered +when matching. +.P +For example, the NSDB "nsdb.example.net:389 would share a database +entry with "nsdb.EXAMPLE.NET:0", but not with "nsdb.example.net:636". +If "nsdb.example.com:389" maps to 10.0.0.1 and "nsdb.example.net:389" +also maps to that address, the database maintains separate entries for +each, although the same connection parameters may be set for both +entries. +.SS Connection security +One of two connection security types may be specified in an NSDB +connection parameter entry: +.IP "\fBNONE\fP" +The local system communicates with the NSDB node in plain-text. +The local system performs no authentication of the NSDB node. +.IP "\fBTLS\fP" +The local system always uses Transport Layer Security when +communicating with the NSDB node. +The local system authenticates the +NSDB node before making requests. +Integrity or encryption is used during communication. +Requests to the NSDB node fail if a TLS session cannot be established. +.P +.B NONE +is a low-overhead mode for use when the network and the NSDB are +trusted by all NSDB clients. +.B TLS +is a high-security mode for use when NSDBs operate on untrusted public +networks, but it requires the additional burden of creating and +distributing x.509 certificates for each NSDB. +.P +An NSDB node can operate in one of three security modes: +.IP "\fBBasic\fP" +NSDB clients connect to this NSDB node using only FEDFS_SEC_NONE security. +.IP "\fBTransitional\fP" +NSDB clients connect to this NSDB node using either FEDFS_SEC_NONE or +FEDFS_SEC_TLS security. +.IP "\fBSecure\fP" +NSDB clients connect to this NSDB node using only FEDFS_SEC_TLS security. +.P +An NSDB client always uses the security type specified in its local +NSDB connection parameter database for that NSDB node. +For greatest security, it is recommended that NSDB nodes be configured as +.B secure +NSDBs (see table above). +.SS x.509 certificates +Administrators provide the certificate material used to authenticate +an NSDB node in a PEM format file that contains an x.509v3 certificate +chain. +.P +This file may contain just the public certificate of the Certificate +Authority (CA) which signed the NSDB's certificate. Or it may contain +a chain of certificates that represents the full chain of trust for +the NSDB node. +A self-signed CA certificate may be used to reduce the burden +of setting up NSDBs for your FedFS domain. +.P +Either the +.BR fedfs-set-nsdb-params (8) +command is used to transfer this material to a remote fileserver running +a FedFS ADMIN service, or the +.BR nsdbparams (8) +command is used to install this material in the NSDB connection parameter +database on the local system. +For both commands, the file containing certificates for one NSDB is +specified on the command line with the +.B "\-\-certfile" +option. +.P +The certificate material provisioned via these commands is used for no +other purpose on the local system than NSDB authentication. +.SH "SEE ALSO" +.BR fedfs (7), +.BR nsdbparams (8), +.BR rpc.fedfsd (8), +.BR fedfs-set-nsdb-params (8) +.sp +RFC 5661 for a description of NFS version 4 referrals +.sp +RFC 5716 for FedFS requirements and overview +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/nsdb-remove-nci.8 b/doc/man/nsdb-remove-nci.8 deleted file mode 100644 index 1c87034..0000000 --- a/doc/man/nsdb-remove-nci.8 +++ /dev/null @@ -1,284 +0,0 @@ -.\"@(#)nsdb-remove-nci.8" -.\" -.\" @file doc/man/nsdb-remove-nci.8 -.\" @brief man page for nsdb-remove-nci client command -.\" - -.\" -.\" Copyright 2011 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH NSDB-REMOVE-NCI 8 "@publication-date@" -.SH NAME -nsdb-remove-nci \- remove NSDB container information from an LDAP server -.SH SYNOPSIS -.B nsdb-remove-nci -.RB [ \-?d ] -.RB [ \-D -.IR binddn ] -.RB [ \-e -.IR nce ] -.RB [ \-l -.IR nsdbname ] -.RB [ \-r -.IR nsdbport ] -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -The bulk of FedFS junction information in a FedFS domain is stored -on one or more LDAP servers. -These servers are known as -.IR "namespace databases" , -or NSDBs, for short. -.P -FedFS-enabled file servers and clients access the information stored -on NSDBs via standard LDAP queries. -FedFS-enabled file servers use these queries to resolve FedFS junctions. -FedFS administrators use them to manage information -about file sets contained in a FedFS domain name space. -.SH DESCRIPTION -The -.BR nsdb-remove-nci (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. -This command is a convenient way to remove NSDB features -from an LDAP server by removing NSDB container information from the server's -.I Directory Information Tree -(or DIT, for short). -.P -The top of the DIT on an LDAP server has one or more -.IR "naming contexts" . -Some LDAP server implementations call these contexts -.IR "root suffixes" . -All LDAP entries on that server are contained under naming contexts. -.P -The LDAP object under which FedFS-related entries reside -is known as the -.I NSDB Container Entry -(or NCE). -The NCE can be a naming context object, -or it can be located somewhere below the naming context. -Both the naming context and the NCE must be world-readable -for FedFS-enabled clients and servers to access the NSDB. -.P -The -.BR nsdb-remove-nci (8) -command demotes an NCE to an unremarkable LDAP entry so that -NSDB clients cannot discover it. -It performs the opposite action from -.BR nsdb-update-nci (8). -The target NCE object -.I must -exist before this operation can complete successfully. -.SH OPTIONS -.IP "\fB\-d, \-\-debug" -Specifies that debugging messages be produced during operation. -.IP "\fB\-?, \-\-help" -Prints an -.BR nsdb-remove-nci (8) -version and usage message on -.IR stderr , -then exits. -.IP "\fB-D, \-\-binddn=\fIbind-distinguished-name\fP" -Specifies a distinguished name of an entity used to bind to the LDAP server -where the NSDB resides. -If the -.B \-\-binddn -option is not specified, -the value of the FEDFS_NSDB_ADMIN environment variable is consulted. -If this variable is not set, -the NSDB connection parameter database is searched for this DN. -If none of these is specified, or -if this entity does not have permission to modify this area -of the server's DIT, the -.BR nsdb-remove-nci (8) -command fails. -.IP "\fB-e, \-\-nce=\fINSDB-container-entry-distinguished-name\fP" -Specifies the distinguished name of the doomed NSDB Container Entry. -If the -.B \-\-nce -option is not specified, -the value of the FEDFS_NSDB_NCE environment variable is consulted. -If this variable is not set, -then the NSDB connection parameter database is searched for this DN. -If none of these is specified, the -.BR nsdb-remove-nci (8) -command fails. -.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" -Specifies the hostname of the NSDB where the NSDB Container Entry resides. -If the -.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 \-\-nsdbname -option is not specified, the -.BR nsdb-remove-nci (8) -command fails. -.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" -Specifies the IP port of the NSDB where the NSDB Container Entry resides. -If the -.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. -.SH EXIT CODES -The NSDB returns a value that reflects the success of the requested operation. -.TP -.B FEDFS_OK -The LDAP modify request succeeded. -.TP -.B FEDFS_ERR_ACCESS -The bound entity does not have permission to perform the requested operation. -.TP -.B FEDFS_ERR_INVAL -One of the arguments was not valid. -.TP -.B FEDFS_ERR_SVRFAULT -An unanticipated non-protocol error occurred. -.TP -.B FEDFS_ERR_NSDB_ROUTE -The -.BR nsdb-remove-nci (8) -command was unable to find a route to the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_DOWN -The -.BR nsdb-remove-nci (8) -command determined that the specified NSDB was down. -.TP -.B FEDFS_ERR_NSDB_CONN -The -.BR nsdb-remove-nci (8) -command was unable to establish a connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_AUTH -The -.BR nsdb-remove-nci (8) -command was unable to authenticate -and establish a secure connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP -A non-specific LDAP error occurred on the connection between the -.BR nsdb-remove-nci (8) -command and specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_VAL -An LDAP error occurred on the connection between the -.BR nsdb-remove-nci (8) -command and specified NSDB. -The specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_RESPONSE -The -.BR nsdb-remove-nci (8) -command received a malformed response from the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_FAULT -An unanticipated error related to the specified NSDB occurred. -.TP -.B FEDFS_ERR_NSDB_PARAMS -The local NSDB connection parameter database -does not have any connection parameters on record for the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL -The -.BR nsdb-remove-nci (8) -command received an LDAP referral that it was unable to follow. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL -The -.BR nsdb-remove-nci (8) -command received an LDAP referral that it was unable to follow. -A specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED -The -.BR nsdb-remove-nci (8) -command received an LDAP referral that it chose not to follow, -either because the local implementation does not support -following LDAP referrals or LDAP referral following is disabled. -.TP -.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL -The -.BR nsdb-remove-nci (8) -command received an LDAP referral that it chose not to follow -because the local NSDB connection parameter database had no -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 disable the NCE -.I o=fedfs -on the NSDB -.IR nsdb.example.net . -.RS -.sp -$ nsdb-remove-nci -l nsdb.example.net -D cn=Manager -e o=fedfs -.br -Enter NSDB password: -.br -Successfully removed NCI -.br -.RE -This action does not remove any FedFS records. -It simply removes the pointer to the records. -.SH SECURITY -An entity with appropriate authority, such as an administrator entity, -must be used to modify LDAP entries. -The -.BR nsdb-remove-nci (8) -command must bind as such an entity to perform this operation. -The -.BR nsdb-remove-nci (8) -command asks for a password on -.IR stdin . -Standard password blanking techniques are used -to obscure the password on the user's terminal. -.P -The target LDAP server must be registered in the local NSDB connection -parameter database. -The connection security mode listed -in the NSDB connection parameter database -for the target LDAP server is used during this operation. -See -.BR nsdbparams (8) -for details on how to register an NSDB -in the local NSDB connection parameter database. -.SH "SEE ALSO" -.BR fedfs (7), -.BR nsdb-nces (8), -.BR nsdb-update-nci (8), -.BR nsdbparams (8) -.sp -RFC 5716 for FedFS requirements and overview -.sp -RFC 4510 for an introduction to LDAP -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/nsdb-remove-nci.8.in b/doc/man/nsdb-remove-nci.8.in new file mode 100644 index 0000000..fbb66d1 --- /dev/null +++ b/doc/man/nsdb-remove-nci.8.in @@ -0,0 +1,284 @@ +.\"@(#)nsdb-remove-nci.8" +.\" +.\" @file doc/man/nsdb-remove-nci.8 +.\" @brief man page for nsdb-remove-nci client command +.\" + +.\" +.\" Copyright 2011 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH NSDB-REMOVE-NCI 8 "@pubdate@" +.SH NAME +nsdb-remove-nci \- remove NSDB container information from an LDAP server +.SH SYNOPSIS +.B nsdb-remove-nci +.RB [ \-?d ] +.RB [ \-D +.IR binddn ] +.RB [ \-e +.IR nce ] +.RB [ \-l +.IR nsdbname ] +.RB [ \-r +.IR nsdbport ] +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +The bulk of FedFS junction information in a FedFS domain is stored +on one or more LDAP servers. +These servers are known as +.IR "namespace databases" , +or NSDBs, for short. +.P +FedFS-enabled file servers and clients access the information stored +on NSDBs via standard LDAP queries. +FedFS-enabled file servers use these queries to resolve FedFS junctions. +FedFS administrators use them to manage information +about file sets contained in a FedFS domain name space. +.SH DESCRIPTION +The +.BR nsdb-remove-nci (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. +This command is a convenient way to remove NSDB features +from an LDAP server by removing NSDB container information from the server's +.I Directory Information Tree +(or DIT, for short). +.P +The top of the DIT on an LDAP server has one or more +.IR "naming contexts" . +Some LDAP server implementations call these contexts +.IR "root suffixes" . +All LDAP entries on that server are contained under naming contexts. +.P +The LDAP object under which FedFS-related entries reside +is known as the +.I NSDB Container Entry +(or NCE). +The NCE can be a naming context object, +or it can be located somewhere below the naming context. +Both the naming context and the NCE must be world-readable +for FedFS-enabled clients and servers to access the NSDB. +.P +The +.BR nsdb-remove-nci (8) +command demotes an NCE to an unremarkable LDAP entry so that +NSDB clients cannot discover it. +It performs the opposite action from +.BR nsdb-update-nci (8). +The target NCE object +.I must +exist before this operation can complete successfully. +.SH OPTIONS +.IP "\fB\-d, \-\-debug" +Specifies that debugging messages be produced during operation. +.IP "\fB\-?, \-\-help" +Prints an +.BR nsdb-remove-nci (8) +version and usage message on +.IR stderr , +then exits. +.IP "\fB-D, \-\-binddn=\fIbind-distinguished-name\fP" +Specifies a distinguished name of an entity used to bind to the LDAP server +where the NSDB resides. +If the +.B \-\-binddn +option is not specified, +the value of the FEDFS_NSDB_ADMIN environment variable is consulted. +If this variable is not set, +the NSDB connection parameter database is searched for this DN. +If none of these is specified, or +if this entity does not have permission to modify this area +of the server's DIT, the +.BR nsdb-remove-nci (8) +command fails. +.IP "\fB-e, \-\-nce=\fINSDB-container-entry-distinguished-name\fP" +Specifies the distinguished name of the doomed NSDB Container Entry. +If the +.B \-\-nce +option is not specified, +the value of the FEDFS_NSDB_NCE environment variable is consulted. +If this variable is not set, +then the NSDB connection parameter database is searched for this DN. +If none of these is specified, the +.BR nsdb-remove-nci (8) +command fails. +.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" +Specifies the hostname of the NSDB where the NSDB Container Entry resides. +If the +.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 \-\-nsdbname +option is not specified, the +.BR nsdb-remove-nci (8) +command fails. +.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" +Specifies the IP port of the NSDB where the NSDB Container Entry resides. +If the +.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. +.SH EXIT CODES +The NSDB returns a value that reflects the success of the requested operation. +.TP +.B FEDFS_OK +The LDAP modify request succeeded. +.TP +.B FEDFS_ERR_ACCESS +The bound entity does not have permission to perform the requested operation. +.TP +.B FEDFS_ERR_INVAL +One of the arguments was not valid. +.TP +.B FEDFS_ERR_SVRFAULT +An unanticipated non-protocol error occurred. +.TP +.B FEDFS_ERR_NSDB_ROUTE +The +.BR nsdb-remove-nci (8) +command was unable to find a route to the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_DOWN +The +.BR nsdb-remove-nci (8) +command determined that the specified NSDB was down. +.TP +.B FEDFS_ERR_NSDB_CONN +The +.BR nsdb-remove-nci (8) +command was unable to establish a connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_AUTH +The +.BR nsdb-remove-nci (8) +command was unable to authenticate +and establish a secure connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP +A non-specific LDAP error occurred on the connection between the +.BR nsdb-remove-nci (8) +command and specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_VAL +An LDAP error occurred on the connection between the +.BR nsdb-remove-nci (8) +command and specified NSDB. +The specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_RESPONSE +The +.BR nsdb-remove-nci (8) +command received a malformed response from the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_FAULT +An unanticipated error related to the specified NSDB occurred. +.TP +.B FEDFS_ERR_NSDB_PARAMS +The local NSDB connection parameter database +does not have any connection parameters on record for the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL +The +.BR nsdb-remove-nci (8) +command received an LDAP referral that it was unable to follow. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL +The +.BR nsdb-remove-nci (8) +command received an LDAP referral that it was unable to follow. +A specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED +The +.BR nsdb-remove-nci (8) +command received an LDAP referral that it chose not to follow, +either because the local implementation does not support +following LDAP referrals or LDAP referral following is disabled. +.TP +.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL +The +.BR nsdb-remove-nci (8) +command received an LDAP referral that it chose not to follow +because the local NSDB connection parameter database had no +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 disable the NCE +.I o=fedfs +on the NSDB +.IR nsdb.example.net . +.RS +.sp +$ nsdb-remove-nci -l nsdb.example.net -D cn=Manager -e o=fedfs +.br +Enter NSDB password: +.br +Successfully removed NCI +.br +.RE +This action does not remove any FedFS records. +It simply removes the pointer to the records. +.SH SECURITY +An entity with appropriate authority, such as an administrator entity, +must be used to modify LDAP entries. +The +.BR nsdb-remove-nci (8) +command must bind as such an entity to perform this operation. +The +.BR nsdb-remove-nci (8) +command asks for a password on +.IR stdin . +Standard password blanking techniques are used +to obscure the password on the user's terminal. +.P +The target LDAP server must be registered in the local NSDB connection +parameter database. +The connection security mode listed +in the NSDB connection parameter database +for the target LDAP server is used during this operation. +See +.BR nsdbparams (8) +for details on how to register an NSDB +in the local NSDB connection parameter database. +.SH "SEE ALSO" +.BR fedfs (7), +.BR nsdb-nces (8), +.BR nsdb-update-nci (8), +.BR nsdbparams (8) +.sp +RFC 5716 for FedFS requirements and overview +.sp +RFC 4510 for an introduction to LDAP +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/nsdb-resolve-fsn.8 b/doc/man/nsdb-resolve-fsn.8 deleted file mode 100644 index 10f7d9f..0000000 --- a/doc/man/nsdb-resolve-fsn.8 +++ /dev/null @@ -1,303 +0,0 @@ -.\"@(#)nsdb-resolve-fsn.8" -.\" -.\" @file doc/man/nsdb-resolve-fsn.8 -.\" @brief man page for nsdb-resolve-fsn client command -.\" - -.\" -.\" Copyright 2011 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH NSDB-RESOLVE-FSN 8 "@publication-date@" -.SH NAME -nsdb-resolve-fsn \- resolve a fileset name (FSN) record on an NSDB -.SH SYNOPSIS -.B nsdb-resolve-fsn -.RB [ \-?d ] -.RB [ \-e -.IR nce ] -.RB [ \-l -.IR nsdbname ] -.RB [ \-r -.IR nsdbport ] -.I fsn-uuid -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -The bulk of FedFS junction information in a FedFS domain is stored -on one or more LDAP servers. -These servers are known as -.IR "namespace databases" , -or NSDBs, for short. -.P -FedFS-enabled file servers and clients access the information stored -on NSDBs via standard LDAP queries. -FedFS-enabled file servers use these queries to resolve FedFS junctions. -FedFS administrators use them to manage information -about file sets contained in a FedFS domain name space. -.SH DESCRIPTION -The -.BR nsdb-resolve-fsn (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. -This command resolves a FedFS -.I fileset name -(FSN) record on an NSDB into a list of fileset locations. -.P -A fileset name, or FSN, uniquely identifies a fileset in FedFS. -An FSN consists of a UUID and the hostname and port of an NSDB. -This pair is intended to be unique across all of FedFS. -The meaning of these items is described in more detail in -.BR fedfs (7). -.P -A FedFS junction contains an FSN. -There can be multiple junctions that contain a particular FSN. -There is exactly one FSN record stored on an NSDB that corresponds to this FSN. -The FSN record can have zero or more FSL records as children. -Replicas of these records can exist on more than one LDAP server. -.P -The -.BR nsdb-resolve-fsn (8) -command looks up an FSN record on the named NSDB -and returns the set of FSL records that are its children. -This is the same operation that FedFS-enabled file servers perform -when resolving the FSN contained in a FedFS junction. -.P -This command has one positional parameter which specifies -the UUID of the FSN record to resolve. -.SH OPTIONS -.IP "\fB\-d, \-\-debug" -Enables debugging messages during operation. -.IP "\fB\-?, \-\-help" -Displays -.BR nsdb-resolve-fsn (8) -version information and a usage message on -.IR stderr . -.IP "\fB-e, \-\-nce=\fINSDB-container-entry-distinguished-name\fP" -Specifies the distinguished name of the NSDB Container Entry -under which this FSN record resides. -If the -.B \-\-nce -option is not specified, -the value of the FEDFS_NSDB_NCE environment variable is consulted. -If this variable is not set, -then the NSDB connection parameter database is searched for this DN. -If none of these is specified, the -.BR nsdb-resolve-fsn (8) -command searches the NSDB's naming contexts to discover its NCEs. -.IP "\fB\-l, \-\-nsdbname=\fINSDB-host-name\fP" -Specifies the NSDB hostname portion of the FSN to resolve. -If the -.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 \-\-nsdbname -option is not specified, the -.BR nsdb-resolve-fsn (8) -command fails. -.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" -Specifies the NSDB IP port portion of the FSN to resolve. -If the -.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. -.SH EXIT CODES -The NSDB returns a value that reflects the success of the requested operation. -.TP -.B FEDFS_OK -The LDAP query succeeded. -.TP -.B FEDFS_ERR_ACCESS -The anonymous entity does not have permission to perform the requested operation. -.TP -.B FEDFS_ERR_INVAL -One of the arguments was not valid. -.TP -.B FEDFS_ERR_SVRFAULT -An unanticipated non-protocol error occurred. -.TP -.B FEDFS_ERR_NSDB_ROUTE -The -.BR nsdb-resolve-fsn (8) -command was unable to find a route to the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_DOWN -The -.BR nsdb-resolve-fsn (8) -command determined that the specified NSDB was down. -.TP -.B FEDFS_ERR_NSDB_CONN -The -.BR nsdb-resolve-fsn (8) -command was unable to establish a connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_AUTH -The -.BR nsdb-resolve-fsn (8) -command was unable to authenticate -and establish a secure connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP -A non-specific LDAP error occurred on the connection between the -.BR nsdb-resolve-fsn (8) -command and specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_VAL -An LDAP error occurred on the connection between the -.BR nsdb-resolve-fsn (8) -command and specified NSDB. -The specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_NONCE -The -.BR nsdb-resolve-fsn (8) -command was unable to locate the NCE on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_NOFSN -The -.BR nsdb-resolve-fsn (8) -command was unable to locate the specified FSN on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_NOFSL -The -.BR nsdb-resolve-fsn (8) -command was unable to locate any FSLs for the specified FSN -on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_RESPONSE -The -.BR nsdb-resolve-fsn (8) -command received a malformed response from the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_FAULT -An unanticipated error related to the specified NSDB occurred. -.TP -.B FEDFS_ERR_NSDB_PARAMS -The local NSDB connection parameter database -does not have any connection parameters on record for the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL -The -.BR nsdb-resolve-fsn (8) -command received an LDAP referral that it was unable to follow. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL -The -.BR nsdb-resolve-fsn (8) -command received an LDAP referral that it was unable to follow. -A specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED -The -.BR nsdb-resolve-fsn (8) -command received an LDAP referral that it chose not to follow, -either because the local implementation does not support -following LDAP referrals or LDAP referral following is disabled. -.TP -.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL -The -.BR nsdb-resolve-fsn (8) -command received an LDAP referral that it chose not to follow -because the local NSDB connection parameter database had no -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 have created a new FSN that looks like: -.RS -.sp - FSN UUID: 8e246ddc-7b46-11e0-8252-000c297fd679 -.br - NSDB: nsdb.example.net:389 -.sp -.RE -Further suppose the NSDB -.I nsdb.example.net:389 -has an NSDB Container Entry whose distinguished name is -.IR o=fedfs , -and that the FSN has a single FSL child record. -To resolve the FSN, you might use: -.RS -.sp -$ nsdb-resolve-fsn -e o=fedfs \\ -.br - -l nsdb.example.net \\ -.br - 8e246ddc-7b46-11e0-8252-000c297fd679 -.sp -For FSN UUID 8e246ddc-7b46-11e0-8252-000c297fd679 -.br - FSN TTL 600 -.sp ------------------------------------------------------- -.br -dn: fedfsFslUuid=323c5068-7c11-11e0-8d38-000c297fd679, -.br - fedfsFsnUuid=8e246ddc-7b46-11e0-8252-000c297fd679,o=fedfs -.sp - FSN UUID: 8e246ddc-7b46-11e0-8252-000c297fd679 -.br - FSL UUID: 323c5068-7c11-11e0-8d38-000c297fd679 -.br - NFS fls_server: fileserver.example.net -.sp - NFS fli_rootpath: /path -.br - NFS fls_currency: -1 -.sp -.RE -and so on. -.SH SECURITY -The NSDB protocol draft standard requires that FedFS FSN and FSL -records are readable by everyone. -The -.BR nsdb-resolve-fsn (8) -command uses anonymous binding to perform LDAP queries. -.P -The target LDAP server must be registered in the local NSDB connection -parameter database. -The connection security mode listed -in the NSDB connection parameter database -for the target LDAP server is used during this operation. -See -.BR nsdbparams (8) -for details on how to register an NSDB -in the local NSDB connection parameter database. -.SH "SEE ALSO" -.BR fedfs (7), -.BR nsdb-list (8), -.BR nsdbparams (8) -.sp -RFC 5716 for FedFS requirements and overview -.sp -RFC 4510 for an introduction to LDAP -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/nsdb-resolve-fsn.8.in b/doc/man/nsdb-resolve-fsn.8.in new file mode 100644 index 0000000..5218e48 --- /dev/null +++ b/doc/man/nsdb-resolve-fsn.8.in @@ -0,0 +1,303 @@ +.\"@(#)nsdb-resolve-fsn.8" +.\" +.\" @file doc/man/nsdb-resolve-fsn.8 +.\" @brief man page for nsdb-resolve-fsn client command +.\" + +.\" +.\" Copyright 2011 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH NSDB-RESOLVE-FSN 8 "@pubdate@" +.SH NAME +nsdb-resolve-fsn \- resolve a fileset name (FSN) record on an NSDB +.SH SYNOPSIS +.B nsdb-resolve-fsn +.RB [ \-?d ] +.RB [ \-e +.IR nce ] +.RB [ \-l +.IR nsdbname ] +.RB [ \-r +.IR nsdbport ] +.I fsn-uuid +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +The bulk of FedFS junction information in a FedFS domain is stored +on one or more LDAP servers. +These servers are known as +.IR "namespace databases" , +or NSDBs, for short. +.P +FedFS-enabled file servers and clients access the information stored +on NSDBs via standard LDAP queries. +FedFS-enabled file servers use these queries to resolve FedFS junctions. +FedFS administrators use them to manage information +about file sets contained in a FedFS domain name space. +.SH DESCRIPTION +The +.BR nsdb-resolve-fsn (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. +This command resolves a FedFS +.I fileset name +(FSN) record on an NSDB into a list of fileset locations. +.P +A fileset name, or FSN, uniquely identifies a fileset in FedFS. +An FSN consists of a UUID and the hostname and port of an NSDB. +This pair is intended to be unique across all of FedFS. +The meaning of these items is described in more detail in +.BR fedfs (7). +.P +A FedFS junction contains an FSN. +There can be multiple junctions that contain a particular FSN. +There is exactly one FSN record stored on an NSDB that corresponds to this FSN. +The FSN record can have zero or more FSL records as children. +Replicas of these records can exist on more than one LDAP server. +.P +The +.BR nsdb-resolve-fsn (8) +command looks up an FSN record on the named NSDB +and returns the set of FSL records that are its children. +This is the same operation that FedFS-enabled file servers perform +when resolving the FSN contained in a FedFS junction. +.P +This command has one positional parameter which specifies +the UUID of the FSN record to resolve. +.SH OPTIONS +.IP "\fB\-d, \-\-debug" +Enables debugging messages during operation. +.IP "\fB\-?, \-\-help" +Displays +.BR nsdb-resolve-fsn (8) +version information and a usage message on +.IR stderr . +.IP "\fB-e, \-\-nce=\fINSDB-container-entry-distinguished-name\fP" +Specifies the distinguished name of the NSDB Container Entry +under which this FSN record resides. +If the +.B \-\-nce +option is not specified, +the value of the FEDFS_NSDB_NCE environment variable is consulted. +If this variable is not set, +then the NSDB connection parameter database is searched for this DN. +If none of these is specified, the +.BR nsdb-resolve-fsn (8) +command searches the NSDB's naming contexts to discover its NCEs. +.IP "\fB\-l, \-\-nsdbname=\fINSDB-host-name\fP" +Specifies the NSDB hostname portion of the FSN to resolve. +If the +.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 \-\-nsdbname +option is not specified, the +.BR nsdb-resolve-fsn (8) +command fails. +.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" +Specifies the NSDB IP port portion of the FSN to resolve. +If the +.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. +.SH EXIT CODES +The NSDB returns a value that reflects the success of the requested operation. +.TP +.B FEDFS_OK +The LDAP query succeeded. +.TP +.B FEDFS_ERR_ACCESS +The anonymous entity does not have permission to perform the requested operation. +.TP +.B FEDFS_ERR_INVAL +One of the arguments was not valid. +.TP +.B FEDFS_ERR_SVRFAULT +An unanticipated non-protocol error occurred. +.TP +.B FEDFS_ERR_NSDB_ROUTE +The +.BR nsdb-resolve-fsn (8) +command was unable to find a route to the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_DOWN +The +.BR nsdb-resolve-fsn (8) +command determined that the specified NSDB was down. +.TP +.B FEDFS_ERR_NSDB_CONN +The +.BR nsdb-resolve-fsn (8) +command was unable to establish a connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_AUTH +The +.BR nsdb-resolve-fsn (8) +command was unable to authenticate +and establish a secure connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP +A non-specific LDAP error occurred on the connection between the +.BR nsdb-resolve-fsn (8) +command and specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_VAL +An LDAP error occurred on the connection between the +.BR nsdb-resolve-fsn (8) +command and specified NSDB. +The specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_NONCE +The +.BR nsdb-resolve-fsn (8) +command was unable to locate the NCE on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_NOFSN +The +.BR nsdb-resolve-fsn (8) +command was unable to locate the specified FSN on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_NOFSL +The +.BR nsdb-resolve-fsn (8) +command was unable to locate any FSLs for the specified FSN +on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_RESPONSE +The +.BR nsdb-resolve-fsn (8) +command received a malformed response from the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_FAULT +An unanticipated error related to the specified NSDB occurred. +.TP +.B FEDFS_ERR_NSDB_PARAMS +The local NSDB connection parameter database +does not have any connection parameters on record for the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL +The +.BR nsdb-resolve-fsn (8) +command received an LDAP referral that it was unable to follow. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL +The +.BR nsdb-resolve-fsn (8) +command received an LDAP referral that it was unable to follow. +A specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED +The +.BR nsdb-resolve-fsn (8) +command received an LDAP referral that it chose not to follow, +either because the local implementation does not support +following LDAP referrals or LDAP referral following is disabled. +.TP +.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL +The +.BR nsdb-resolve-fsn (8) +command received an LDAP referral that it chose not to follow +because the local NSDB connection parameter database had no +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 have created a new FSN that looks like: +.RS +.sp + FSN UUID: 8e246ddc-7b46-11e0-8252-000c297fd679 +.br + NSDB: nsdb.example.net:389 +.sp +.RE +Further suppose the NSDB +.I nsdb.example.net:389 +has an NSDB Container Entry whose distinguished name is +.IR o=fedfs , +and that the FSN has a single FSL child record. +To resolve the FSN, you might use: +.RS +.sp +$ nsdb-resolve-fsn -e o=fedfs \\ +.br + -l nsdb.example.net \\ +.br + 8e246ddc-7b46-11e0-8252-000c297fd679 +.sp +For FSN UUID 8e246ddc-7b46-11e0-8252-000c297fd679 +.br + FSN TTL 600 +.sp +------------------------------------------------------ +.br +dn: fedfsFslUuid=323c5068-7c11-11e0-8d38-000c297fd679, +.br + fedfsFsnUuid=8e246ddc-7b46-11e0-8252-000c297fd679,o=fedfs +.sp + FSN UUID: 8e246ddc-7b46-11e0-8252-000c297fd679 +.br + FSL UUID: 323c5068-7c11-11e0-8d38-000c297fd679 +.br + NFS fls_server: fileserver.example.net +.sp + NFS fli_rootpath: /path +.br + NFS fls_currency: -1 +.sp +.RE +and so on. +.SH SECURITY +The NSDB protocol draft standard requires that FedFS FSN and FSL +records are readable by everyone. +The +.BR nsdb-resolve-fsn (8) +command uses anonymous binding to perform LDAP queries. +.P +The target LDAP server must be registered in the local NSDB connection +parameter database. +The connection security mode listed +in the NSDB connection parameter database +for the target LDAP server is used during this operation. +See +.BR nsdbparams (8) +for details on how to register an NSDB +in the local NSDB connection parameter database. +.SH "SEE ALSO" +.BR fedfs (7), +.BR nsdb-list (8), +.BR nsdbparams (8) +.sp +RFC 5716 for FedFS requirements and overview +.sp +RFC 4510 for an introduction to LDAP +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/nsdb-simple-nce.8 b/doc/man/nsdb-simple-nce.8 deleted file mode 100644 index 5a81997..0000000 --- a/doc/man/nsdb-simple-nce.8 +++ /dev/null @@ -1,292 +0,0 @@ -.\"@(#)nsdb-simple-nce.8" -.\" -.\" @file doc/man/nsdb-simple-nce.8 -.\" @brief man page for nsdb-simple-nce client command -.\" - -.\" -.\" Copyright 2012 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH NSDB-SIMPLE-NCE 8 "@publication-date@" -.SH NAME -nsdb-simple-nce \- Create a simple NSDB Container Entry -.SH SYNOPSIS -.B nsdb-simple-nce -.RB [ \-?d ] -.RB [ \-D -.IR binddn ] -.RB [ \-l -.IR nsdbname ] -.RB [ \-r -.IR nsdbport ] -.I parent-dn -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -The bulk of FedFS junction information in a FedFS domain is stored -on one or more LDAP servers. -These servers are known as -.IR "namespace databases" , -or NSDBs, for short. -.P -FedFS-enabled file servers and clients access the information stored -on NSDBs via standard LDAP queries. -FedFS-enabled file servers use these queries to resolve FedFS junctions. -FedFS administrators use these queries to manage information -about file sets contained in a FedFS domain name space. -.SH DESCRIPTION -The -.BR nsdb-simple-nce (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. -This command is an easy way to turn a standard LDAP server into an NSDB -by creating an NSDB Container Entry in the server's -.I Directory Information Tree -(or DIT, for short). -.P -The top of the DIT on an LDAP server has one or more -.IR "naming contexts" . -Some LDAP server implementations call these contexts -.IR "root suffixes" . -An LDAP server's naming contexts are easy for clients to locate -with a well-known search query. -All LDAP entries on that server are contained under naming contexts. -.P -The LDAP entry under which all other FedFS-related entries reside -is known as the -.I NSDB Container Entry -(or NCE). -The NCE can be a naming context entry, -or it can be located somewhere below a naming context. -The -.BR nsdb-simple-nce (8) -command adds an NSDB Container Entry -with a distinguished name that can be created without -much prior knowledge of the server's DIT. -.P -Once this entry is created, the -.BR nsdb-simple-nce (8) -command automatically adds the new entry's DN to the parent -naming context so that NSDB clients can find it. -The result is a ready-to-use NSDB. -.P -The -.BR nsdb-simple-nce (8) -command establishes an NSDB quickly and without fuss. -A more sophisticated configuration may be -established using standard LDAP tools and the -.BR nsdb-update-nci (8) -command. -This might be necessary when preparing an existing LDAP server -with a large pre-existing DIT for use as an NSDB. -.P -This command has one positional parameter which specifies -the distinguished name of the parent entry of the new -NSDB Container Entry. -.SH OPTIONS -.IP "\fB\-d, \-\-debug" -Enables debugging messages during operation. -.IP "\fB\-?, \-\-help" -Displays -.BR nsdb-simple-nce (8) -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 the LDAP server -where the NSDB resides. -If the -.B \-\-binddn -option is not specified, -the value of the FEDFS_NSDB_ADMIN environment variable is consulted. -If this variable is not set, -the NSDB connection parameter database is searched for this DN. -If none of these is specified, or -if this entity does not have permission to modify this area -of the server's DIT, the -.BR nsdb-simple-nce (8) -command fails. -.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" -Specifies the hostname of the NSDB where the target NCE should reside. -If the -.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 \-\-nsdbname -option is not specified, the -.BR nsdb-simple-nce (8) -command fails. -.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" -Specifies the IP port of the NSDB where the target NCE should reside. -If the -.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. -.SH EXIT CODES -The NSDB returns a value that reflects the success of the requested operation. -.TP -.B FEDFS_OK -The LDAP modify request succeeded. -.TP -.B FEDFS_ERR_ACCESS -The bound entity does not have permission to perform the requested operation. -.TP -.B FEDFS_ERR_INVAL -One of the arguments was not valid. -.TP -.B FEDFS_ERR_SVRFAULT -An unanticipated non-protocol error occurred. -.TP -.B FEDFS_ERR_NSDB_ROUTE -The -.BR nsdb-simple-nce (8) -command was unable to find a route to the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_DOWN -The -.BR nsdb-simple-nce (8) -command determined that the specified NSDB was down. -.TP -.B FEDFS_ERR_NSDB_CONN -The -.BR nsdb-simple-nce (8) -command was unable to establish a connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_AUTH -The -.BR nsdb-simple-nce (8) -command was unable to authenticate -and establish a secure connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP -A non-specific LDAP error occurred on the connection between the -.BR nsdb-simple-nce (8) -command and specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_VAL -An LDAP error occurred on the connection between the -.BR nsdb-simple-nce (8) -command and specified NSDB. -The specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_RESPONSE -The -.BR nsdb-simple-nce (8) -command received a malformed response from the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_FAULT -An unanticipated error related to the specified NSDB occurred. -.TP -.B FEDFS_ERR_NSDB_PARAMS -The local NSDB connection parameter database -does not have any connection parameters on record for the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL -The -.BR nsdb-simple-nce (8) -command received an LDAP referral that it was unable to follow. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL -The -.BR nsdb-simple-nce (8) -command received an LDAP referral that it was unable to follow. -A specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED -The -.BR nsdb-simple-nce (8) -command received an LDAP referral that it chose not to follow, -either because the local implementation does not support -following LDAP referrals or LDAP referral following is disabled. -.TP -.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL -The -.BR nsdb-simple-nce (8) -command received an LDAP referral that it chose not to follow -because the local NSDB connection parameter database had no -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 make the LDAP server -.IR ldap.example.net -into an NSDB. -Ensure the LDAP server has the FedFS schema installed. -The naming context "dc=example,dc=net" must exist, and -must have an entry associated with it. -Then you might use: -.RS -.sp -$ nsdb-simple-nce -l ldap.example.net -D cn=Manager dc=example,dc=net -.br -Enter NSDB password: -.br -Successfully created simple NCE -.sp -.RE -The distinguished name of the new NCE is "ou=fedfs,dc=example,dc=net". -The naming context "dc=example,dc=net" is updated to refer NSDB clients -to the "ou=fedfs,dc=example,dc=net" entry. -.P -To see the new NCE, use -.BR nsdb-nces (8). -.SH SECURITY -LDAP naming contexts are typically writable only by administrative entities. -The -.BR nsdb-simple-nce (8) -command must bind as an administrative entity to perform this operation. -The -.BR nsdb-simple-nce (8) -command asks for a password on -.IR stdin . -Standard password blanking techniques are used -to obscure the password on the user's terminal. -.P -The target LDAP server must be registered in the local NSDB connection -parameter database. -The connection security mode listed -in the NSDB connection parameter database -for the target LDAP server is used during this operation. -See -.BR nsdbparams (8) -for details on how to register an NSDB -in the local NSDB connection parameter database. -.SH "SEE ALSO" -.BR fedfs (7), -.BR nsdb-nces (8), -.BR nsdb-update-nce (8), -.BR nsdbparams (8) -.sp -RFC 5716 for FedFS requirements and overview -.sp -RFC 4510 for an introduction to LDAP -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/nsdb-simple-nce.8.in b/doc/man/nsdb-simple-nce.8.in new file mode 100644 index 0000000..297e8af --- /dev/null +++ b/doc/man/nsdb-simple-nce.8.in @@ -0,0 +1,292 @@ +.\"@(#)nsdb-simple-nce.8" +.\" +.\" @file doc/man/nsdb-simple-nce.8 +.\" @brief man page for nsdb-simple-nce client command +.\" + +.\" +.\" Copyright 2012 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH NSDB-SIMPLE-NCE 8 "@pubdate@" +.SH NAME +nsdb-simple-nce \- Create a simple NSDB Container Entry +.SH SYNOPSIS +.B nsdb-simple-nce +.RB [ \-?d ] +.RB [ \-D +.IR binddn ] +.RB [ \-l +.IR nsdbname ] +.RB [ \-r +.IR nsdbport ] +.I parent-dn +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +The bulk of FedFS junction information in a FedFS domain is stored +on one or more LDAP servers. +These servers are known as +.IR "namespace databases" , +or NSDBs, for short. +.P +FedFS-enabled file servers and clients access the information stored +on NSDBs via standard LDAP queries. +FedFS-enabled file servers use these queries to resolve FedFS junctions. +FedFS administrators use these queries to manage information +about file sets contained in a FedFS domain name space. +.SH DESCRIPTION +The +.BR nsdb-simple-nce (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. +This command is an easy way to turn a standard LDAP server into an NSDB +by creating an NSDB Container Entry in the server's +.I Directory Information Tree +(or DIT, for short). +.P +The top of the DIT on an LDAP server has one or more +.IR "naming contexts" . +Some LDAP server implementations call these contexts +.IR "root suffixes" . +An LDAP server's naming contexts are easy for clients to locate +with a well-known search query. +All LDAP entries on that server are contained under naming contexts. +.P +The LDAP entry under which all other FedFS-related entries reside +is known as the +.I NSDB Container Entry +(or NCE). +The NCE can be a naming context entry, +or it can be located somewhere below a naming context. +The +.BR nsdb-simple-nce (8) +command adds an NSDB Container Entry +with a distinguished name that can be created without +much prior knowledge of the server's DIT. +.P +Once this entry is created, the +.BR nsdb-simple-nce (8) +command automatically adds the new entry's DN to the parent +naming context so that NSDB clients can find it. +The result is a ready-to-use NSDB. +.P +The +.BR nsdb-simple-nce (8) +command establishes an NSDB quickly and without fuss. +A more sophisticated configuration may be +established using standard LDAP tools and the +.BR nsdb-update-nci (8) +command. +This might be necessary when preparing an existing LDAP server +with a large pre-existing DIT for use as an NSDB. +.P +This command has one positional parameter which specifies +the distinguished name of the parent entry of the new +NSDB Container Entry. +.SH OPTIONS +.IP "\fB\-d, \-\-debug" +Enables debugging messages during operation. +.IP "\fB\-?, \-\-help" +Displays +.BR nsdb-simple-nce (8) +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 the LDAP server +where the NSDB resides. +If the +.B \-\-binddn +option is not specified, +the value of the FEDFS_NSDB_ADMIN environment variable is consulted. +If this variable is not set, +the NSDB connection parameter database is searched for this DN. +If none of these is specified, or +if this entity does not have permission to modify this area +of the server's DIT, the +.BR nsdb-simple-nce (8) +command fails. +.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" +Specifies the hostname of the NSDB where the target NCE should reside. +If the +.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 \-\-nsdbname +option is not specified, the +.BR nsdb-simple-nce (8) +command fails. +.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" +Specifies the IP port of the NSDB where the target NCE should reside. +If the +.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. +.SH EXIT CODES +The NSDB returns a value that reflects the success of the requested operation. +.TP +.B FEDFS_OK +The LDAP modify request succeeded. +.TP +.B FEDFS_ERR_ACCESS +The bound entity does not have permission to perform the requested operation. +.TP +.B FEDFS_ERR_INVAL +One of the arguments was not valid. +.TP +.B FEDFS_ERR_SVRFAULT +An unanticipated non-protocol error occurred. +.TP +.B FEDFS_ERR_NSDB_ROUTE +The +.BR nsdb-simple-nce (8) +command was unable to find a route to the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_DOWN +The +.BR nsdb-simple-nce (8) +command determined that the specified NSDB was down. +.TP +.B FEDFS_ERR_NSDB_CONN +The +.BR nsdb-simple-nce (8) +command was unable to establish a connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_AUTH +The +.BR nsdb-simple-nce (8) +command was unable to authenticate +and establish a secure connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP +A non-specific LDAP error occurred on the connection between the +.BR nsdb-simple-nce (8) +command and specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_VAL +An LDAP error occurred on the connection between the +.BR nsdb-simple-nce (8) +command and specified NSDB. +The specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_RESPONSE +The +.BR nsdb-simple-nce (8) +command received a malformed response from the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_FAULT +An unanticipated error related to the specified NSDB occurred. +.TP +.B FEDFS_ERR_NSDB_PARAMS +The local NSDB connection parameter database +does not have any connection parameters on record for the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL +The +.BR nsdb-simple-nce (8) +command received an LDAP referral that it was unable to follow. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL +The +.BR nsdb-simple-nce (8) +command received an LDAP referral that it was unable to follow. +A specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED +The +.BR nsdb-simple-nce (8) +command received an LDAP referral that it chose not to follow, +either because the local implementation does not support +following LDAP referrals or LDAP referral following is disabled. +.TP +.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL +The +.BR nsdb-simple-nce (8) +command received an LDAP referral that it chose not to follow +because the local NSDB connection parameter database had no +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 make the LDAP server +.IR ldap.example.net +into an NSDB. +Ensure the LDAP server has the FedFS schema installed. +The naming context "dc=example,dc=net" must exist, and +must have an entry associated with it. +Then you might use: +.RS +.sp +$ nsdb-simple-nce -l ldap.example.net -D cn=Manager dc=example,dc=net +.br +Enter NSDB password: +.br +Successfully created simple NCE +.sp +.RE +The distinguished name of the new NCE is "ou=fedfs,dc=example,dc=net". +The naming context "dc=example,dc=net" is updated to refer NSDB clients +to the "ou=fedfs,dc=example,dc=net" entry. +.P +To see the new NCE, use +.BR nsdb-nces (8). +.SH SECURITY +LDAP naming contexts are typically writable only by administrative entities. +The +.BR nsdb-simple-nce (8) +command must bind as an administrative entity to perform this operation. +The +.BR nsdb-simple-nce (8) +command asks for a password on +.IR stdin . +Standard password blanking techniques are used +to obscure the password on the user's terminal. +.P +The target LDAP server must be registered in the local NSDB connection +parameter database. +The connection security mode listed +in the NSDB connection parameter database +for the target LDAP server is used during this operation. +See +.BR nsdbparams (8) +for details on how to register an NSDB +in the local NSDB connection parameter database. +.SH "SEE ALSO" +.BR fedfs (7), +.BR nsdb-nces (8), +.BR nsdb-update-nce (8), +.BR nsdbparams (8) +.sp +RFC 5716 for FedFS requirements and overview +.sp +RFC 4510 for an introduction to LDAP +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/nsdb-update-fsl.8 b/doc/man/nsdb-update-fsl.8 deleted file mode 100644 index 1478591..0000000 --- a/doc/man/nsdb-update-fsl.8 +++ /dev/null @@ -1,353 +0,0 @@ -.\"@(#)nsdb-update-fsl.8" -.\" -.\" @file doc/man/nsdb-update-fsl.8 -.\" @brief man page for nsdb-update-fsl client command -.\" - -.\" -.\" Copyright 2011 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH NSDB-UPDATE-FSL 8 "@publication-date@" -.SH NAME -nsdb-update-fsl \- update attributes of a fileset location (FSL) record -.SH SYNOPSIS -.B nsdb-update-fsl -.RB [ \-?d ] -.RB [ \-D -.IR binddn ] -.RB [ \-e -.IR nce ] -.RB [ \-l -.IR nsdbname ] -.RB [ \-r -.IR nsdbport ] -.RB [ \-v -.IR value ] -.I fsl-uuid -.I attribute -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -The bulk of FedFS junction information in a FedFS domain is stored -on one or more LDAP servers. -These servers are known as -.IR "namespace databases" , -or NSDBs, for short. -.P -FedFS-enabled file servers and clients access the information stored -on NSDBs via standard LDAP queries. -FedFS-enabled file servers use these queries to resolve FedFS junctions. -FedFS administrators use them to manage information -about file sets contained in a FedFS domain name space. -.SH DESCRIPTION -The -.BR nsdb-update-fsl (8) -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. -This command modifies attributes contained in -.I fileset location -(FSL) records on an NSDB. -.P -A fileset location, or FSL, uniquely identifies the location of one -replica of a fileset. -An FSL record contains two UUIDs and other information, -depending on the subtype of the FSL. -The meaning of these items is described in more detail in -.BR fedfs (7). -.P -FSLs are stored in records on an NSDB. -These records are stored as children of FSN records. -Replicas of these records can exist on more than one LDAP server. -.P -The -.BR nsdb-update-fsl (8) -command can modify certain attributes of an FSL record. -It does not create FSL records. -To create FSL records, use the -.BR nsdb-create-fsl (8) -command. -It does not update base FSL attributes, such as the servername. -To modify those attributes, a new FSL record must be created. -.P -The -.IR fedfsAnnotation " and" -.I fedfsDescr -attributes are multi-value attributes. -To modify them, use -.BR nsdb-annotate "(8) and" -.BR nsdb-describe "(8), respectively." -.P -This command has two positional parameters. -The first parameter specifies the UUID of the FSL record to modify. -If a record for this FSL does not already exist, the -.BR nsdb-update-fsl (8) -command fails. -The second parameter specifies the name of the attribute to update. -If that attribute does not already exist, -it is added to the target FSL record. -.SH OPTIONS -.IP "\fB\-d, \-\-debug" -Enables debugging messages during operation. -.IP "\fB\-?, \-\-help" -Displays -.BR nsdb-update-fsl (8) -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 the LDAP server -where the NSDB resides. -If the -.B \-\-binddn -option is not specified, -the value of the FEDFS_NSDB_ADMIN environment variable is consulted. -If this variable is not set, -the NSDB connection parameter database is searched for this DN. -If none of these is specified, or -if this entity does not have permission to modify this area -of the server's DIT, the -.BR nsdb-update-fsl (8) -command fails. -.IP "\fB-e, \-\-nce=\fINSDB-container-entry-distinguished-name\fP" -Specifies the distinguished name of the NSDB container entry -under which the specified FSL record resides. -If the -.B \-\-nce -option is not specified, -the value of the FEDFS_NSDB_NCE environment variable is consulted. -If this variable is not set, -then the NSDB connection parameter database is searched for this DN. -If none of these is specified, the -.BR nsdb-update-fsl (8) -command fails. -.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" -Specifies the hostname of the NSDB where the specified FSL record resides. -If the -.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 \-\-nsdbname -option is not specified, the -.BR nsdb-update-fsl (8) -command fails. -.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" -Specifies the IP port of the NSDB where the specified FSL record resides. -If the -.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=\fILDAP-value\fP" -Specifies the new value that should be stored in the specified attribute. -If the specified attribute does not exist, it is created and assigned -the specified value. -Otherwise the existing value is replaced. -If the -.B \-\-value -option is not specified, the -.BR nsdb-update-fsl (8) -command attempts to delete the specified attribute. -.SH EXIT CODES -The NSDB returns a value that reflects the success of the requested operation. -.TP -.B FEDFS_OK -The LDAP modify request succeeded. -.TP -.B FEDFS_ERR_ACCESS -The bound entity does not have permission to perform the requested operation. -.TP -.B FEDFS_ERR_INVAL -One of the arguments was not valid. -.TP -.B FEDFS_ERR_SVRFAULT -An unanticipated non-protocol error occurred. -.TP -.B FEDFS_ERR_NSDB_ROUTE -The -.BR nsdb-update-fsl (8) -command was unable to find a route to the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_DOWN -The -.BR nsdb-update-fsl (8) -command determined that the specified NSDB was down. -.TP -.B FEDFS_ERR_NSDB_CONN -The -.BR nsdb-update-fsl (8) -command was unable to establish a connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_AUTH -The -.BR nsdb-update-fsl (8) -command was unable to authenticate -and establish a secure connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP -A non-specific LDAP error occurred on the connection between the -.BR nsdb-update-fsl (8) -command and specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_VAL -An LDAP error occurred on the connection between the -.BR nsdb-update-fsl (8) -command and specified NSDB. -The specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_NONCE -The -.BR nsdb-update-fsl (8) -command was unable to locate the NCE on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_NOFSN -The -.BR nsdb-update-fsl (8) -command was unable to locate the specified FSN on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_NOFSL -The -.BR nsdb-update-fsl (8) -command was unable to locate the specified FSL for the specified FSN -on the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_RESPONSE -The -.BR nsdb-update-fsl (8) -command received a malformed response from the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_FAULT -An unanticipated error related to the specified NSDB occurred. -.TP -.B FEDFS_ERR_NSDB_PARAMS -The local NSDB connection parameter database -does not have any connection parameters on record for the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL -The -.BR nsdb-update-fsl (8) -command received an LDAP referral that it was unable to follow. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL -The -.BR nsdb-update-fsl (8) -command received an LDAP referral that it was unable to follow. -A specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED -The -.BR nsdb-update-fsl (8) -command received an LDAP referral that it chose not to follow, -either because the local implementation does not support -following LDAP referrals or LDAP referral following is disabled. -.TP -.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL -The -.BR nsdb-update-fsl (8) -command received an LDAP referral that it chose not to follow -because the local NSDB connection parameter database had no -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 have created a new FSN for some fileset. -The new FSN looks like: -.RS -.sp - FSN UUID: 8e246ddc-7b46-11e0-8252-000c297fd679 -.br - NSDB: nsdb.example.net:389 -.sp -.RE -Further suppose the NSDB -.I nsdb.example.net:389 -has an NSDB container entry whose distinguished name is -.IR o=fedfs , -and that an FSL child record with the UUID -.I 323c5068-7c11-11e0-8d38-000c297fd679 -already exists. -.P -To change the NFS minor version used when clients mount this location -from zero to one, you might use: -.RS -.sp -$ nsdb-update-fsl -D cn=Manager -e o=fedfs \\ -.br - -x 323c5068-7c11-11e0-8d38-000c297fd679 \\ -.br - -l nsdb.example.net \\ -.br - 8e246ddc-7b46-11e0-8252-000c297fd679 \\ -.br - fedfsNfsMinorVer -v 1 -.br -Enter NSDB password: -.br -Successfully updated FSL record - fedfsFslUuid=323c5068-7c11-11e0-8d38-000c297fd679, - fedfsFsnUuid=8e246ddc-7b46-11e0-8252-000c297fd679,o=fedfs -.sp -.RE -To see the contents of the updated FSL record, use -.BR nsdb-resolve-fsn (8). -.SH SECURITY -Permission to modify the LDAP's DIT is required to update an FSL record. -The -.BR nsdb-update-fsl (8) -command must bind as an entity permitted to modify the DIT -to perform this operation. -The -.BR nsdb-update-fsl (8) -command asks for a password on -.IR stdin . -Standard password blanking techniques are used -to obscure the password on the user's terminal. -.P -The target LDAP server must be registered in the local NSDB connection -parameter database. -The connection security mode listed -in the NSDB connection parameter database -for the target LDAP server is used during this operation. -See -.BR nsdbparams (8) -for details on how to register an NSDB -in the local NSDB connection parameter database. -.SH "SEE ALSO" -.BR fedfs (7), -.BR nsdb-create-fsl (8), -.BR nsdb-annotate (8), -.BR nsdb-describe (8), -.BR nsdb-resolve-fsn (8), -.BR nsdbparams (8) -.sp -RFC 5716 for FedFS requirements and overview -.sp -RFC 4510 for an introduction to LDAP -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/nsdb-update-fsl.8.in b/doc/man/nsdb-update-fsl.8.in new file mode 100644 index 0000000..e8c81f9 --- /dev/null +++ b/doc/man/nsdb-update-fsl.8.in @@ -0,0 +1,353 @@ +.\"@(#)nsdb-update-fsl.8" +.\" +.\" @file doc/man/nsdb-update-fsl.8 +.\" @brief man page for nsdb-update-fsl client command +.\" + +.\" +.\" Copyright 2011 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH NSDB-UPDATE-FSL 8 "@pubdate@" +.SH NAME +nsdb-update-fsl \- update attributes of a fileset location (FSL) record +.SH SYNOPSIS +.B nsdb-update-fsl +.RB [ \-?d ] +.RB [ \-D +.IR binddn ] +.RB [ \-e +.IR nce ] +.RB [ \-l +.IR nsdbname ] +.RB [ \-r +.IR nsdbport ] +.RB [ \-v +.IR value ] +.I fsl-uuid +.I attribute +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +The bulk of FedFS junction information in a FedFS domain is stored +on one or more LDAP servers. +These servers are known as +.IR "namespace databases" , +or NSDBs, for short. +.P +FedFS-enabled file servers and clients access the information stored +on NSDBs via standard LDAP queries. +FedFS-enabled file servers use these queries to resolve FedFS junctions. +FedFS administrators use them to manage information +about file sets contained in a FedFS domain name space. +.SH DESCRIPTION +The +.BR nsdb-update-fsl (8) +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. +This command modifies attributes contained in +.I fileset location +(FSL) records on an NSDB. +.P +A fileset location, or FSL, uniquely identifies the location of one +replica of a fileset. +An FSL record contains two UUIDs and other information, +depending on the subtype of the FSL. +The meaning of these items is described in more detail in +.BR fedfs (7). +.P +FSLs are stored in records on an NSDB. +These records are stored as children of FSN records. +Replicas of these records can exist on more than one LDAP server. +.P +The +.BR nsdb-update-fsl (8) +command can modify certain attributes of an FSL record. +It does not create FSL records. +To create FSL records, use the +.BR nsdb-create-fsl (8) +command. +It does not update base FSL attributes, such as the servername. +To modify those attributes, a new FSL record must be created. +.P +The +.IR fedfsAnnotation " and" +.I fedfsDescr +attributes are multi-value attributes. +To modify them, use +.BR nsdb-annotate "(8) and" +.BR nsdb-describe "(8), respectively." +.P +This command has two positional parameters. +The first parameter specifies the UUID of the FSL record to modify. +If a record for this FSL does not already exist, the +.BR nsdb-update-fsl (8) +command fails. +The second parameter specifies the name of the attribute to update. +If that attribute does not already exist, +it is added to the target FSL record. +.SH OPTIONS +.IP "\fB\-d, \-\-debug" +Enables debugging messages during operation. +.IP "\fB\-?, \-\-help" +Displays +.BR nsdb-update-fsl (8) +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 the LDAP server +where the NSDB resides. +If the +.B \-\-binddn +option is not specified, +the value of the FEDFS_NSDB_ADMIN environment variable is consulted. +If this variable is not set, +the NSDB connection parameter database is searched for this DN. +If none of these is specified, or +if this entity does not have permission to modify this area +of the server's DIT, the +.BR nsdb-update-fsl (8) +command fails. +.IP "\fB-e, \-\-nce=\fINSDB-container-entry-distinguished-name\fP" +Specifies the distinguished name of the NSDB container entry +under which the specified FSL record resides. +If the +.B \-\-nce +option is not specified, +the value of the FEDFS_NSDB_NCE environment variable is consulted. +If this variable is not set, +then the NSDB connection parameter database is searched for this DN. +If none of these is specified, the +.BR nsdb-update-fsl (8) +command fails. +.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" +Specifies the hostname of the NSDB where the specified FSL record resides. +If the +.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 \-\-nsdbname +option is not specified, the +.BR nsdb-update-fsl (8) +command fails. +.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" +Specifies the IP port of the NSDB where the specified FSL record resides. +If the +.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=\fILDAP-value\fP" +Specifies the new value that should be stored in the specified attribute. +If the specified attribute does not exist, it is created and assigned +the specified value. +Otherwise the existing value is replaced. +If the +.B \-\-value +option is not specified, the +.BR nsdb-update-fsl (8) +command attempts to delete the specified attribute. +.SH EXIT CODES +The NSDB returns a value that reflects the success of the requested operation. +.TP +.B FEDFS_OK +The LDAP modify request succeeded. +.TP +.B FEDFS_ERR_ACCESS +The bound entity does not have permission to perform the requested operation. +.TP +.B FEDFS_ERR_INVAL +One of the arguments was not valid. +.TP +.B FEDFS_ERR_SVRFAULT +An unanticipated non-protocol error occurred. +.TP +.B FEDFS_ERR_NSDB_ROUTE +The +.BR nsdb-update-fsl (8) +command was unable to find a route to the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_DOWN +The +.BR nsdb-update-fsl (8) +command determined that the specified NSDB was down. +.TP +.B FEDFS_ERR_NSDB_CONN +The +.BR nsdb-update-fsl (8) +command was unable to establish a connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_AUTH +The +.BR nsdb-update-fsl (8) +command was unable to authenticate +and establish a secure connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP +A non-specific LDAP error occurred on the connection between the +.BR nsdb-update-fsl (8) +command and specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_VAL +An LDAP error occurred on the connection between the +.BR nsdb-update-fsl (8) +command and specified NSDB. +The specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_NONCE +The +.BR nsdb-update-fsl (8) +command was unable to locate the NCE on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_NOFSN +The +.BR nsdb-update-fsl (8) +command was unable to locate the specified FSN on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_NOFSL +The +.BR nsdb-update-fsl (8) +command was unable to locate the specified FSL for the specified FSN +on the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_RESPONSE +The +.BR nsdb-update-fsl (8) +command received a malformed response from the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_FAULT +An unanticipated error related to the specified NSDB occurred. +.TP +.B FEDFS_ERR_NSDB_PARAMS +The local NSDB connection parameter database +does not have any connection parameters on record for the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL +The +.BR nsdb-update-fsl (8) +command received an LDAP referral that it was unable to follow. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL +The +.BR nsdb-update-fsl (8) +command received an LDAP referral that it was unable to follow. +A specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED +The +.BR nsdb-update-fsl (8) +command received an LDAP referral that it chose not to follow, +either because the local implementation does not support +following LDAP referrals or LDAP referral following is disabled. +.TP +.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL +The +.BR nsdb-update-fsl (8) +command received an LDAP referral that it chose not to follow +because the local NSDB connection parameter database had no +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 have created a new FSN for some fileset. +The new FSN looks like: +.RS +.sp + FSN UUID: 8e246ddc-7b46-11e0-8252-000c297fd679 +.br + NSDB: nsdb.example.net:389 +.sp +.RE +Further suppose the NSDB +.I nsdb.example.net:389 +has an NSDB container entry whose distinguished name is +.IR o=fedfs , +and that an FSL child record with the UUID +.I 323c5068-7c11-11e0-8d38-000c297fd679 +already exists. +.P +To change the NFS minor version used when clients mount this location +from zero to one, you might use: +.RS +.sp +$ nsdb-update-fsl -D cn=Manager -e o=fedfs \\ +.br + -x 323c5068-7c11-11e0-8d38-000c297fd679 \\ +.br + -l nsdb.example.net \\ +.br + 8e246ddc-7b46-11e0-8252-000c297fd679 \\ +.br + fedfsNfsMinorVer -v 1 +.br +Enter NSDB password: +.br +Successfully updated FSL record + fedfsFslUuid=323c5068-7c11-11e0-8d38-000c297fd679, + fedfsFsnUuid=8e246ddc-7b46-11e0-8252-000c297fd679,o=fedfs +.sp +.RE +To see the contents of the updated FSL record, use +.BR nsdb-resolve-fsn (8). +.SH SECURITY +Permission to modify the LDAP's DIT is required to update an FSL record. +The +.BR nsdb-update-fsl (8) +command must bind as an entity permitted to modify the DIT +to perform this operation. +The +.BR nsdb-update-fsl (8) +command asks for a password on +.IR stdin . +Standard password blanking techniques are used +to obscure the password on the user's terminal. +.P +The target LDAP server must be registered in the local NSDB connection +parameter database. +The connection security mode listed +in the NSDB connection parameter database +for the target LDAP server is used during this operation. +See +.BR nsdbparams (8) +for details on how to register an NSDB +in the local NSDB connection parameter database. +.SH "SEE ALSO" +.BR fedfs (7), +.BR nsdb-create-fsl (8), +.BR nsdb-annotate (8), +.BR nsdb-describe (8), +.BR nsdb-resolve-fsn (8), +.BR nsdbparams (8) +.sp +RFC 5716 for FedFS requirements and overview +.sp +RFC 4510 for an introduction to LDAP +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/nsdb-update-nci.8 b/doc/man/nsdb-update-nci.8 deleted file mode 100644 index a5f1a14..0000000 --- a/doc/man/nsdb-update-nci.8 +++ /dev/null @@ -1,322 +0,0 @@ -.\"@(#)nsdb-update-nci.8" -.\" -.\" @file doc/man/nsdb-update-nci.8 -.\" @brief man page for nsdb-update-nci client command -.\" - -.\" -.\" Copyright 2011 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH NSDB-UPDATE-NCI 8 "@publication-date@" -.SH NAME -nsdb-update-nci \- update NSDB container information on an LDAP server -.SH SYNOPSIS -.B nsdb-update-nci -.RB [ \-?dy ] -.RB [ \-D -.IR binddn ] -.RB [ \-e -.IR nce ] -.RB [ \-l -.IR nsdbname ] -.RB [ \-r -.IR nsdbport ] -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -The bulk of FedFS junction information in a FedFS domain is stored -on one or more LDAP servers. -These servers are known as -.IR "namespace databases" , -or NSDBs, for short. -.P -FedFS-enabled file servers and clients access the information stored -on NSDBs via standard LDAP queries. -FedFS-enabled file servers use these queries to resolve FedFS junctions. -FedFS administrators use them to manage information -about file sets contained in a FedFS domain name space. -.SH DESCRIPTION -The -.BR nsdb-update-nci (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. -This command is an easy way to turn a standard LDAP server into an NSDB -by adding NSDB container information to the server's -.I Directory Information Tree -(or DIT, for short). -.P -The top of the DIT on an LDAP server has one or more -.IR "naming contexts" . -Some LDAP server implementations call these contexts -.IR "root suffixes" . -An LDAP server's naming contexts are easy for clients to locate -with a well-known search query. -All LDAP entries on that server are contained under naming contexts. -.P -The root LDAP object under which FedFS-related entries reside -is known as the -.I NSDB Container Entry -(or NCE). -The NCE can be a naming context object, -or it can be located somewhere below the naming context. -Both the naming context and the NCE must be world-readable -for FedFS-enabled clients and servers to access the NSDB. -.P -The -.BR nsdb-update-nci (8) -command promotes an unremarkable LDAP entry to become an NCE. -This is the step that turns an LDAP server into an NSDB. -The target NCE object -.I must -exist before this operation can complete successfully. -.SH OPTIONS -.IP "\fB\-d, \-\-debug" -Enables debugging messages during operation. -.IP "\fB\-?, \-\-help" -Displays -.BR nsdb-update-nci (8) -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 the LDAP server -where the NSDB resides. -If the -.B \-\-binddn -option is not specified, -the value of the FEDFS_NSDB_ADMIN environment variable is consulted. -If this variable is not set, -the NSDB connection parameter database is searched for this DN. -If none of these is specified, or -if this entity does not have permission to modify this area -of the server's DIT, the -.BR nsdb-update-nci (8) -command fails. -.IP "\fB-e, \-\-nce=\fINSDB-container-entry-distinguished-name\fP" -Specifies the distinguished name of the new NSDB container entry. -If the -.B \-\-nce -option is not specified, -the value of the FEDFS_NSDB_NCE environment variable is consulted. -If this variable is not set, -then the NSDB connection parameter database is searched for this DN. -If none of these is specified, the -.BR nsdb-update-nci (8) -command fails. -.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" -Specifies the hostname of the NSDB where the target NCE should reside. -If the -.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 \-\-nsdbname -option is not specified, the -.BR nsdb-update-nci (8) -command fails. -.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" -Specifies the IP port of the NSDB where the target NCE should reside. -If the -.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\-y, \-\-delete\fP" -Specifies that NSDB Container Information for this NCE -should be removed from this LDAP server. -This operation cannot be undone. -.SH EXIT CODES -The NSDB returns a value that reflects the success of the requested operation. -.TP -.B FEDFS_OK -The LDAP modify request succeeded. -.TP -.B FEDFS_ERR_ACCESS -The bound entity does not have permission to perform the requested operation. -.TP -.B FEDFS_ERR_INVAL -One of the arguments was not valid. -.TP -.B FEDFS_ERR_SVRFAULT -An unanticipated non-protocol error occurred. -.TP -.B FEDFS_ERR_NSDB_ROUTE -The -.BR nsdb-update-nci (8) -command was unable to find a route to the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_DOWN -The -.BR nsdb-update-nci (8) -command determined that the specified NSDB was down. -.TP -.B FEDFS_ERR_NSDB_CONN -The -.BR nsdb-update-nci (8) -command was unable to establish a connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_AUTH -The -.BR nsdb-update-nci (8) -command was unable to authenticate -and establish a secure connection with the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP -A non-specific LDAP error occurred on the connection between the -.BR nsdb-update-nci (8) -command and specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_VAL -An LDAP error occurred on the connection between the -.BR nsdb-update-nci (8) -command and specified NSDB. -The specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_RESPONSE -The -.BR nsdb-update-nci (8) -command received a malformed response from the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_FAULT -An unanticipated error related to the specified NSDB occurred. -.TP -.B FEDFS_ERR_NSDB_PARAMS -The local NSDB connection parameter database -does not have any connection parameters on record for the specified NSDB. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL -The -.BR nsdb-update-nci (8) -command received an LDAP referral that it was unable to follow. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL -The -.BR nsdb-update-nci (8) -command received an LDAP referral that it was unable to follow. -A specific error may be displayed on the command line. -.TP -.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED -The -.BR nsdb-update-nci (8) -command received an LDAP referral that it chose not to follow, -either because the local implementation does not support -following LDAP referrals or LDAP referral following is disabled. -.TP -.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL -The -.BR nsdb-update-nci (8) -command received an LDAP referral that it chose not to follow -because the local NSDB connection parameter database had no -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 make the LDAP server -.IR ldap.example.net -into an NSDB. -After creating a naming context and root suffix object -with a distinguished name of -.I o=fedfs -on the LDAP server, you might use: -.RS -.sp -$ nsdb-update-nci -l ldap.example.net -D cn=Manager -e o=fedfs -.br -Enter NSDB password: -.br -Successfully updated NCI -.sp -.RE -NSDB container information is inserted into -.IR o=fedfs , -and this entry is changed to an NSDB Container Entry. -.P -To see the new container information, use -.BR nsdb-nces (8). -.P -.I o=fedfs -is a typical location for an NCE on an LDAP server. -However, suppose that instead of creating such a typical NCE, -you would prefer the entry -.I ou=fedfs,dc=example,dc=net -to contain FedFS information. -Assuming your server set-up script has already created the -.I dc=example,dc=net -naming context and root object, -and after creating a generic object with the distinguished name -.IR ou=fedfs,dc=example,dc=net , -you might use: -.RS -.sp -$ nsdb-update-nci -e "ou=fedfs,dc=example,dc=net" -D cn=Manager -.br -Enter NSDB password: -.br -Successfully updated NCI -.sp -.RE -NSDB container information is inserted into -.IR dc=example,dc=net , -and the entry at -.I ou=fedfs,dc=example,dc=net -is made into an NCE. -.P -To see the new NCE, use -.BR nsdb-nces (8). -.SH SECURITY -LDAP naming contexts are typically writable only by administrative entities. -The -.BR nsdb-update-nci (8) -command must bind as an administrative entity to perform this operation. -The -.BR nsdb-update-nci (8) -command asks for a password on -.IR stdin . -Standard password blanking techniques are used -to obscure the password on the user's terminal. -.P -The target LDAP server must be registered in the local NSDB connection -parameter database. -The connection security mode listed -in the NSDB connection parameter database -for the target LDAP server is used during this operation. -See -.BR nsdbparams (8) -for details on how to register an NSDB -in the local NSDB connection parameter database. -.SH "SEE ALSO" -.BR fedfs (7), -.BR nsdb-nces (8), -.BR nsdbparams (8) -.sp -RFC 5716 for FedFS requirements and overview -.sp -RFC 4510 for an introduction to LDAP -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/nsdb-update-nci.8.in b/doc/man/nsdb-update-nci.8.in new file mode 100644 index 0000000..a930440 --- /dev/null +++ b/doc/man/nsdb-update-nci.8.in @@ -0,0 +1,322 @@ +.\"@(#)nsdb-update-nci.8" +.\" +.\" @file doc/man/nsdb-update-nci.8 +.\" @brief man page for nsdb-update-nci client command +.\" + +.\" +.\" Copyright 2011 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH NSDB-UPDATE-NCI 8 "@pubdate@" +.SH NAME +nsdb-update-nci \- update NSDB container information on an LDAP server +.SH SYNOPSIS +.B nsdb-update-nci +.RB [ \-?dy ] +.RB [ \-D +.IR binddn ] +.RB [ \-e +.IR nce ] +.RB [ \-l +.IR nsdbname ] +.RB [ \-r +.IR nsdbport ] +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +The bulk of FedFS junction information in a FedFS domain is stored +on one or more LDAP servers. +These servers are known as +.IR "namespace databases" , +or NSDBs, for short. +.P +FedFS-enabled file servers and clients access the information stored +on NSDBs via standard LDAP queries. +FedFS-enabled file servers use these queries to resolve FedFS junctions. +FedFS administrators use them to manage information +about file sets contained in a FedFS domain name space. +.SH DESCRIPTION +The +.BR nsdb-update-nci (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. +This command is an easy way to turn a standard LDAP server into an NSDB +by adding NSDB container information to the server's +.I Directory Information Tree +(or DIT, for short). +.P +The top of the DIT on an LDAP server has one or more +.IR "naming contexts" . +Some LDAP server implementations call these contexts +.IR "root suffixes" . +An LDAP server's naming contexts are easy for clients to locate +with a well-known search query. +All LDAP entries on that server are contained under naming contexts. +.P +The root LDAP object under which FedFS-related entries reside +is known as the +.I NSDB Container Entry +(or NCE). +The NCE can be a naming context object, +or it can be located somewhere below the naming context. +Both the naming context and the NCE must be world-readable +for FedFS-enabled clients and servers to access the NSDB. +.P +The +.BR nsdb-update-nci (8) +command promotes an unremarkable LDAP entry to become an NCE. +This is the step that turns an LDAP server into an NSDB. +The target NCE object +.I must +exist before this operation can complete successfully. +.SH OPTIONS +.IP "\fB\-d, \-\-debug" +Enables debugging messages during operation. +.IP "\fB\-?, \-\-help" +Displays +.BR nsdb-update-nci (8) +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 the LDAP server +where the NSDB resides. +If the +.B \-\-binddn +option is not specified, +the value of the FEDFS_NSDB_ADMIN environment variable is consulted. +If this variable is not set, +the NSDB connection parameter database is searched for this DN. +If none of these is specified, or +if this entity does not have permission to modify this area +of the server's DIT, the +.BR nsdb-update-nci (8) +command fails. +.IP "\fB-e, \-\-nce=\fINSDB-container-entry-distinguished-name\fP" +Specifies the distinguished name of the new NSDB container entry. +If the +.B \-\-nce +option is not specified, +the value of the FEDFS_NSDB_NCE environment variable is consulted. +If this variable is not set, +then the NSDB connection parameter database is searched for this DN. +If none of these is specified, the +.BR nsdb-update-nci (8) +command fails. +.IP "\fB\-l, \-\-nsdbname=\fINSDB-hostname\fP" +Specifies the hostname of the NSDB where the target NCE should reside. +If the +.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 \-\-nsdbname +option is not specified, the +.BR nsdb-update-nci (8) +command fails. +.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" +Specifies the IP port of the NSDB where the target NCE should reside. +If the +.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\-y, \-\-delete\fP" +Specifies that NSDB Container Information for this NCE +should be removed from this LDAP server. +This operation cannot be undone. +.SH EXIT CODES +The NSDB returns a value that reflects the success of the requested operation. +.TP +.B FEDFS_OK +The LDAP modify request succeeded. +.TP +.B FEDFS_ERR_ACCESS +The bound entity does not have permission to perform the requested operation. +.TP +.B FEDFS_ERR_INVAL +One of the arguments was not valid. +.TP +.B FEDFS_ERR_SVRFAULT +An unanticipated non-protocol error occurred. +.TP +.B FEDFS_ERR_NSDB_ROUTE +The +.BR nsdb-update-nci (8) +command was unable to find a route to the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_DOWN +The +.BR nsdb-update-nci (8) +command determined that the specified NSDB was down. +.TP +.B FEDFS_ERR_NSDB_CONN +The +.BR nsdb-update-nci (8) +command was unable to establish a connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_AUTH +The +.BR nsdb-update-nci (8) +command was unable to authenticate +and establish a secure connection with the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP +A non-specific LDAP error occurred on the connection between the +.BR nsdb-update-nci (8) +command and specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_VAL +An LDAP error occurred on the connection between the +.BR nsdb-update-nci (8) +command and specified NSDB. +The specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_RESPONSE +The +.BR nsdb-update-nci (8) +command received a malformed response from the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_FAULT +An unanticipated error related to the specified NSDB occurred. +.TP +.B FEDFS_ERR_NSDB_PARAMS +The local NSDB connection parameter database +does not have any connection parameters on record for the specified NSDB. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL +The +.BR nsdb-update-nci (8) +command received an LDAP referral that it was unable to follow. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL +The +.BR nsdb-update-nci (8) +command received an LDAP referral that it was unable to follow. +A specific error may be displayed on the command line. +.TP +.B FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED +The +.BR nsdb-update-nci (8) +command received an LDAP referral that it chose not to follow, +either because the local implementation does not support +following LDAP referrals or LDAP referral following is disabled. +.TP +.B FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL +The +.BR nsdb-update-nci (8) +command received an LDAP referral that it chose not to follow +because the local NSDB connection parameter database had no +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 make the LDAP server +.IR ldap.example.net +into an NSDB. +After creating a naming context and root suffix object +with a distinguished name of +.I o=fedfs +on the LDAP server, you might use: +.RS +.sp +$ nsdb-update-nci -l ldap.example.net -D cn=Manager -e o=fedfs +.br +Enter NSDB password: +.br +Successfully updated NCI +.sp +.RE +NSDB container information is inserted into +.IR o=fedfs , +and this entry is changed to an NSDB Container Entry. +.P +To see the new container information, use +.BR nsdb-nces (8). +.P +.I o=fedfs +is a typical location for an NCE on an LDAP server. +However, suppose that instead of creating such a typical NCE, +you would prefer the entry +.I ou=fedfs,dc=example,dc=net +to contain FedFS information. +Assuming your server set-up script has already created the +.I dc=example,dc=net +naming context and root object, +and after creating a generic object with the distinguished name +.IR ou=fedfs,dc=example,dc=net , +you might use: +.RS +.sp +$ nsdb-update-nci -e "ou=fedfs,dc=example,dc=net" -D cn=Manager +.br +Enter NSDB password: +.br +Successfully updated NCI +.sp +.RE +NSDB container information is inserted into +.IR dc=example,dc=net , +and the entry at +.I ou=fedfs,dc=example,dc=net +is made into an NCE. +.P +To see the new NCE, use +.BR nsdb-nces (8). +.SH SECURITY +LDAP naming contexts are typically writable only by administrative entities. +The +.BR nsdb-update-nci (8) +command must bind as an administrative entity to perform this operation. +The +.BR nsdb-update-nci (8) +command asks for a password on +.IR stdin . +Standard password blanking techniques are used +to obscure the password on the user's terminal. +.P +The target LDAP server must be registered in the local NSDB connection +parameter database. +The connection security mode listed +in the NSDB connection parameter database +for the target LDAP server is used during this operation. +See +.BR nsdbparams (8) +for details on how to register an NSDB +in the local NSDB connection parameter database. +.SH "SEE ALSO" +.BR fedfs (7), +.BR nsdb-nces (8), +.BR nsdbparams (8) +.sp +RFC 5716 for FedFS requirements and overview +.sp +RFC 4510 for an introduction to LDAP +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/nsdbparams.8 b/doc/man/nsdbparams.8 deleted file mode 100644 index f3da318..0000000 --- a/doc/man/nsdbparams.8 +++ /dev/null @@ -1,364 +0,0 @@ -.\"@(#)nsdbparams.8" -.\" -.\" @file doc/man/nsdbparams.8 -.\" @brief man page for nsdbparams command -.\" - -.\" -.\" Copyright 2011 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH NSDBPARAMS 8 "@publication-date@" -.SH NAME -nsdbparams \- manage local NSDB connection parameter database -.SH SYNOPSIS -.B nsdbparams delete -.RB [ \-?d ] -.RB [ \-g -.IR gid ] -.RB [ \-r -.IR nsdbport ] -.RB [ \-u -.IR uid ] -.I nsdbname -.P -.B nsdbparams list -.RB [ \-?d ] -.RB [ \-u -.IR uid ] -.RB [ \-g -.IR gid ] -.P -.B nsdbparams show -.RB [ \-?d ] -.RB [ \-g -.IR gid ] -.RB [ \-r -.IR nsdbport ] -.RB [ \-u -.IR uid ] -.I nsdbname -.P -.B nsdbparams update -.RB [ \-?d ] -.RB [ \-D -.IR def-binddn ] -.RB [ \-e -.IR def-nce ] -.RB [ \-f -.IR certfile ] -.RB [ \-g -.IR gid ] -.RB [ \-R -.BR y | n ] -.RB [ \-r -.IR nsdbport ] -.RB [ \-t -.IR sectype ] -.RB [ \-u -.IR uid ] -.I nsdbname -.SH INTRODUCTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -The bulk of FedFS metadata is stored on one or more LDAP servers. -These servers are known as -.IR "namespace databases" , -or NSDBs, for short. -An -.I NSDB client -is any system that communicates with an NSDB. -This can be either a fileserver or an NSDB administrative client. -.P -On NSDB clients, -a small local database stores information about how to connect -to each NSDB node. These -.I NSDB connection parameters -are used when an NSDB client contacts an NSDB node to perform file -server operations or when executing NSDB administrative commands. -.P -The settings in this database effect only the behavior of the local -NSDB client. They have no effect on the operation of NSDBs nodes. -.SH DESCRIPTION -The -.BR nsdbparams (8) -command is one way FedFS domain administrators can manage -a system's local NSDB connection parameter database. -This database stores connection security preferences and default settings, -such as the preferred bind DN and the location of the -NSDB container entry, -for each NSDB the local system knows about. -.P -Some NSDB connection parameters are also remotely accessible via -.BR rpc.fedfsd (8). -The -.BR nsdbparams (8) -command allows complete access to the local system's NSDB database -including access to some parameters which are not accessible to clients of -.BR rpc.fedfsd (8). -.P -Typically -.BR rpc.fedfsd (8) -runs only on FedFS-enabled file servers. -FedFS administrators can manage NSDB connection parameters with -.BR nsdbparams (8) -on a system that is not running -.BR rpc.fedfsd (8), -such as a system that is acting only as a FedFS administrative client. -Connection parameters for NSDBs must be stored -in the local NSDB connection parameter database -before FedFS junction resolution and -NSDB administrative commands can work. -.SS Operation -The NSDB connection parameter database is stored -in a directory -(typically -.IR @statedir ) -that is owned by a special UID and GID. -Therefore, this command must be run as root. -During operation, -.BR nsdbparams (8) -drops its root privileges, -running as the special user and group instead. -.P -The default value of these special IDs is determined when -.BR nsdbparams (8) -is built. They can also be specified at run time using the -.B \-\-uid -or -.B \-\-gid -command line options. -.P -When executing a subcommand, -.BR nsdbparams (8) -verifies that the local NSDB connection parameter database exists -and is accessible. -If it does not exist, -.BR nsdbparams (8) -attempts to create and initialize a new connection parameter database. -If it cannot, the subcommand fails. -.SS Subcommands -Valid -.BR nsdbparams (8) -subcommands are: -.IP "\fBdelete\fP" -Remove the connection parameters for the specified NSDB -from the local NSDB connection parameter database. -If this subcommand succeeds, -subsequent attempts to access the specified NSDB on the local system fail. -.IP "\fBlist\fP" -Display a list of all NSDBs in the local NSDB connection parameter database. -An abbreviated form of the connection parameters for each known NSDB -are shown. -This subcommand does not take an NSDB domain name parameter. -.IP "\fBupdate\fP" -Update the connection parameters for the specified NSDB -in the local NSDB connection parameter database. -Use this subcommand to -add a new entry for an NSDB to the local connection parameter database, -or to modify an existing entry in the database. -.IP "\fBshow\fP" -Display the recorded connection parameters for the specified NSDB. -This subcommand displays all known settings for the specified NSDB -stored in the local NSDB connection parameter database. -.P -The NSDB domain name and IP port number pair -are used as the primary key to identify an NSDB to the NSDB -connection parameter database. -The subcommands -.BR delete , -.BR update ", and" -.B show -require that an NSDB domain name be specified as a positional parameter. -If no NSDB port number is provided on the command line, the -.BR nsdbparams (8) -command uses the default LDAP port (389). -.P -The database matches NSDB domain names and ports by exact value. -Details on NSDB connection parameters database entry matching can be -found in -.BR nsdb-parameters (7). -.SS Command line options -.IP "\fB\-d, \-\-debug" -Enables debugging messages during subcommand operation. -This option is valid for all subcommands. -.IP "\fB\-D, \-\-binddn=\fIbind-DN\fP" -Specifies the default LDAP distinguished name to use -when binding to the specified NSDB for administrative operations. -This option is valid for the -.B update -subcommand. -.IP "\fB-e, \-\-nce=\fINCE-DN\fP" -Specifies the default LDAP distinguished name of the NSDB container entry -for the specified NSDB for administrative operations. -This option is valid for the -.B update -subcommand. -.IP "\fB-f, \-\-certfile=\fIpathname\fP" -Specifies the pathname of a local file containing security data -appropriate for the -.B "\-\-sectype" -specified on the command line. -The specified file may be deleted after the command succeeds. -Details on security data can be found in -.BR nsdb-parameters (7). -This option is valid for the -.B update -subcommand. -.IP "\fB\-g, \-\-gid=\fIid\fP" -Specifies the numeric or text GID that the -.BR nsdbparams (8) -command runs as after dropping root privileges. -By default, the GID for the group -.I @fedfsuser@ -is used. -If that group doesn't exist, then the GID for -.I nobody -is used instead. -This option is valid for all subcommands. -.IP "\fB\-?, \-\-help" -Displays -.BR nsdbparams (8) -version information and a subcommand usage message on -.IR stderr . -This option is valid for all subcommands. -.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" -Specifies the IP port for the specified NSDB. -The default value if this option is not specified is 389. -This option is valid for any subcommand that requires an -NSDB domain name to be specified. -.IP "\fB\-R, \-\-referral=\fP[\fByes\fP|\fBno\fP]" -Specifies whether or not the local system should follow LDAP referrals -received from the specified NSDB. -This option is valid for the -.B update -subcommand. -.IP "\fB\-t, \-\-sectype=\fIsecurity-type\fP" -Specifies the FedFS connection security type to use when connecting -to the specified NSDB. Valid values for -.I security-type -are -.BR 0 , -.BR none , -.BR FEDFS_SEC_NONE , -.BR 1 , -.BR tls , -or -.BR FEDFS_SEC_TLS . -This option is valid for the -.B update -subcommand. -.IP "\fB\-u, \-\-uid=\fIid\fP" -Specifies the numeric or text UID that -.BR nsdbparams (8) -runs as after dropping root privileges. -By default, the UID for the user -.I @fedfsuser@ -is used. -If that user doesn't exist, then the UID for -.I nobody -is used instead. -This option is valid for all subcommands. -.SH CHANGING SECURITY TYPES -You can change connection security types used to contact an NSDB node -using the -.B update -subcommand. Simply specify the new security type with the -.B "\-\-sectype" -option. -Specifying the NONE type removes existing stored certificate material -for that NSDB node. -Specifying the TLS type replaces existing stored certificate material -with new material specified with the -.B "\-\-certfile" -option. -.SH EXAMPLES -If there is an NSDB called -.IR nsdb.example.net , -the first command you might issue on a new administrative client might be: -.RS -.sp -# nsdbparams update nsdb.example.net -.sp -.RE -You can view the new connection parameter entry with -.RS -.sp -# nsdbparams show nsdb.example.net -.sp -.RE -The result of this command would look like: -.RS -.sp -nsdb.example.net:389: -.br - connection security: FEDFS_SEC_NONE -.br - follow referrals: no -.sp -.RE -To set up TLS security, use the -.B update -subcommand and specify the -.B \-\-sectype -and -.B \-\-certfile -options. -For instance, if an x.509 certificate for -.I nsdb.example.net -were contained in a local file called -.IR /tmp/nsdb.pem , -you might use: -.RS -.sp -# nsdbparams update -t tls -f /tmp/nsdb.pem nsdb.example.net -.sp -.RE -To switch from TLS security back to no connection security for this NSDB, -you might use: -.RS -.sp -# nsdbparams update nsdb.example.net -t none -.SH FILES -.TP -.I @statedir@/nsdbparam.sqlite3 -database of NSDB connection parameters -.TP -.I @statedir@/nsdbcerts -local directory that stores x.509 certificates for NSDBs -.SH "SEE ALSO" -.BR fedfs (7), -.BR nsdb-parameters (7), -.BR rpc.fedfsd (8) -.sp -RFC 5661 for a description of NFS version 4 referrals -.sp -RFC 5716 for FedFS requirements and overview -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/nsdbparams.8.in b/doc/man/nsdbparams.8.in new file mode 100644 index 0000000..fd6e94b --- /dev/null +++ b/doc/man/nsdbparams.8.in @@ -0,0 +1,364 @@ +.\"@(#)nsdbparams.8" +.\" +.\" @file doc/man/nsdbparams.8 +.\" @brief man page for nsdbparams command +.\" + +.\" +.\" Copyright 2011 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH NSDBPARAMS 8 "@pubdate@" +.SH NAME +nsdbparams \- manage local NSDB connection parameter database +.SH SYNOPSIS +.B nsdbparams delete +.RB [ \-?d ] +.RB [ \-g +.IR gid ] +.RB [ \-r +.IR nsdbport ] +.RB [ \-u +.IR uid ] +.I nsdbname +.P +.B nsdbparams list +.RB [ \-?d ] +.RB [ \-u +.IR uid ] +.RB [ \-g +.IR gid ] +.P +.B nsdbparams show +.RB [ \-?d ] +.RB [ \-g +.IR gid ] +.RB [ \-r +.IR nsdbport ] +.RB [ \-u +.IR uid ] +.I nsdbname +.P +.B nsdbparams update +.RB [ \-?d ] +.RB [ \-D +.IR def-binddn ] +.RB [ \-e +.IR def-nce ] +.RB [ \-f +.IR certfile ] +.RB [ \-g +.IR gid ] +.RB [ \-R +.BR y | n ] +.RB [ \-r +.IR nsdbport ] +.RB [ \-t +.IR sectype ] +.RB [ \-u +.IR uid ] +.I nsdbname +.SH INTRODUCTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +The bulk of FedFS metadata is stored on one or more LDAP servers. +These servers are known as +.IR "namespace databases" , +or NSDBs, for short. +An +.I NSDB client +is any system that communicates with an NSDB. +This can be either a fileserver or an NSDB administrative client. +.P +On NSDB clients, +a small local database stores information about how to connect +to each NSDB node. These +.I NSDB connection parameters +are used when an NSDB client contacts an NSDB node to perform file +server operations or when executing NSDB administrative commands. +.P +The settings in this database effect only the behavior of the local +NSDB client. They have no effect on the operation of NSDBs nodes. +.SH DESCRIPTION +The +.BR nsdbparams (8) +command is one way FedFS domain administrators can manage +a system's local NSDB connection parameter database. +This database stores connection security preferences and default settings, +such as the preferred bind DN and the location of the +NSDB container entry, +for each NSDB the local system knows about. +.P +Some NSDB connection parameters are also remotely accessible via +.BR rpc.fedfsd (8). +The +.BR nsdbparams (8) +command allows complete access to the local system's NSDB database +including access to some parameters which are not accessible to clients of +.BR rpc.fedfsd (8). +.P +Typically +.BR rpc.fedfsd (8) +runs only on FedFS-enabled file servers. +FedFS administrators can manage NSDB connection parameters with +.BR nsdbparams (8) +on a system that is not running +.BR rpc.fedfsd (8), +such as a system that is acting only as a FedFS administrative client. +Connection parameters for NSDBs must be stored +in the local NSDB connection parameter database +before FedFS junction resolution and +NSDB administrative commands can work. +.SS Operation +The NSDB connection parameter database is stored +in a directory +(typically +.IR @statedir@ ) +that is owned by a special UID and GID. +Therefore, this command must be run as root. +During operation, +.BR nsdbparams (8) +drops its root privileges, +running as the special user and group instead. +.P +The default value of these special IDs is determined when +.BR nsdbparams (8) +is built. They can also be specified at run time using the +.B \-\-uid +or +.B \-\-gid +command line options. +.P +When executing a subcommand, +.BR nsdbparams (8) +verifies that the local NSDB connection parameter database exists +and is accessible. +If it does not exist, +.BR nsdbparams (8) +attempts to create and initialize a new connection parameter database. +If it cannot, the subcommand fails. +.SS Subcommands +Valid +.BR nsdbparams (8) +subcommands are: +.IP "\fBdelete\fP" +Remove the connection parameters for the specified NSDB +from the local NSDB connection parameter database. +If this subcommand succeeds, +subsequent attempts to access the specified NSDB on the local system fail. +.IP "\fBlist\fP" +Display a list of all NSDBs in the local NSDB connection parameter database. +An abbreviated form of the connection parameters for each known NSDB +are shown. +This subcommand does not take an NSDB domain name parameter. +.IP "\fBupdate\fP" +Update the connection parameters for the specified NSDB +in the local NSDB connection parameter database. +Use this subcommand to +add a new entry for an NSDB to the local connection parameter database, +or to modify an existing entry in the database. +.IP "\fBshow\fP" +Display the recorded connection parameters for the specified NSDB. +This subcommand displays all known settings for the specified NSDB +stored in the local NSDB connection parameter database. +.P +The NSDB domain name and IP port number pair +are used as the primary key to identify an NSDB to the NSDB +connection parameter database. +The subcommands +.BR delete , +.BR update ", and" +.B show +require that an NSDB domain name be specified as a positional parameter. +If no NSDB port number is provided on the command line, the +.BR nsdbparams (8) +command uses the default LDAP port (389). +.P +The database matches NSDB domain names and ports by exact value. +Details on NSDB connection parameters database entry matching can be +found in +.BR nsdb-parameters (7). +.SS Command line options +.IP "\fB\-d, \-\-debug" +Enables debugging messages during subcommand operation. +This option is valid for all subcommands. +.IP "\fB\-D, \-\-binddn=\fIbind-DN\fP" +Specifies the default LDAP distinguished name to use +when binding to the specified NSDB for administrative operations. +This option is valid for the +.B update +subcommand. +.IP "\fB-e, \-\-nce=\fINCE-DN\fP" +Specifies the default LDAP distinguished name of the NSDB container entry +for the specified NSDB for administrative operations. +This option is valid for the +.B update +subcommand. +.IP "\fB-f, \-\-certfile=\fIpathname\fP" +Specifies the pathname of a local file containing security data +appropriate for the +.B "\-\-sectype" +specified on the command line. +The specified file may be deleted after the command succeeds. +Details on security data can be found in +.BR nsdb-parameters (7). +This option is valid for the +.B update +subcommand. +.IP "\fB\-g, \-\-gid=\fIid\fP" +Specifies the numeric or text GID that the +.BR nsdbparams (8) +command runs as after dropping root privileges. +By default, the GID for the group +.I @fedfsuser@ +is used. +If that group doesn't exist, then the GID for +.I nobody +is used instead. +This option is valid for all subcommands. +.IP "\fB\-?, \-\-help" +Displays +.BR nsdbparams (8) +version information and a subcommand usage message on +.IR stderr . +This option is valid for all subcommands. +.IP "\fB\-r, \-\-nsdbport=\fINSDB-port\fP" +Specifies the IP port for the specified NSDB. +The default value if this option is not specified is 389. +This option is valid for any subcommand that requires an +NSDB domain name to be specified. +.IP "\fB\-R, \-\-referral=\fP[\fByes\fP|\fBno\fP]" +Specifies whether or not the local system should follow LDAP referrals +received from the specified NSDB. +This option is valid for the +.B update +subcommand. +.IP "\fB\-t, \-\-sectype=\fIsecurity-type\fP" +Specifies the FedFS connection security type to use when connecting +to the specified NSDB. Valid values for +.I security-type +are +.BR 0 , +.BR none , +.BR FEDFS_SEC_NONE , +.BR 1 , +.BR tls , +or +.BR FEDFS_SEC_TLS . +This option is valid for the +.B update +subcommand. +.IP "\fB\-u, \-\-uid=\fIid\fP" +Specifies the numeric or text UID that +.BR nsdbparams (8) +runs as after dropping root privileges. +By default, the UID for the user +.I @fedfsuser@ +is used. +If that user doesn't exist, then the UID for +.I nobody +is used instead. +This option is valid for all subcommands. +.SH CHANGING SECURITY TYPES +You can change connection security types used to contact an NSDB node +using the +.B update +subcommand. Simply specify the new security type with the +.B "\-\-sectype" +option. +Specifying the NONE type removes existing stored certificate material +for that NSDB node. +Specifying the TLS type replaces existing stored certificate material +with new material specified with the +.B "\-\-certfile" +option. +.SH EXAMPLES +If there is an NSDB called +.IR nsdb.example.net , +the first command you might issue on a new administrative client might be: +.RS +.sp +# nsdbparams update nsdb.example.net +.sp +.RE +You can view the new connection parameter entry with +.RS +.sp +# nsdbparams show nsdb.example.net +.sp +.RE +The result of this command would look like: +.RS +.sp +nsdb.example.net:389: +.br + connection security: FEDFS_SEC_NONE +.br + follow referrals: no +.sp +.RE +To set up TLS security, use the +.B update +subcommand and specify the +.B \-\-sectype +and +.B \-\-certfile +options. +For instance, if an x.509 certificate for +.I nsdb.example.net +were contained in a local file called +.IR /tmp/nsdb.pem , +you might use: +.RS +.sp +# nsdbparams update -t tls -f /tmp/nsdb.pem nsdb.example.net +.sp +.RE +To switch from TLS security back to no connection security for this NSDB, +you might use: +.RS +.sp +# nsdbparams update nsdb.example.net -t none +.SH FILES +.TP +.I @statedir@/nsdbparam.sqlite3 +database of NSDB connection parameters +.TP +.I @statedir@/nsdbcerts +local directory that stores x.509 certificates for NSDBs +.SH "SEE ALSO" +.BR fedfs (7), +.BR nsdb-parameters (7), +.BR rpc.fedfsd (8) +.sp +RFC 5661 for a description of NFS version 4 referrals +.sp +RFC 5716 for FedFS requirements and overview +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever diff --git a/doc/man/rpc.fedfsd.8 b/doc/man/rpc.fedfsd.8 deleted file mode 100644 index 1a0933f..0000000 --- a/doc/man/rpc.fedfsd.8 +++ /dev/null @@ -1,205 +0,0 @@ -.\"@(#)rpc.fedfsd.8" -.\" -.\" @file doc/man/rpc.fedfsd.8 -.\" @brief man page for FedFS Admin service daemon -.\" - -.\" -.\" Copyright 2011, 2013 Oracle. All rights reserved. -.\" -.\" This file is part of fedfs-utils. -.\" -.\" fedfs-utils is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2.0 as -.\" published by the Free Software Foundation. -.\" -.\" fedfs-utils is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License version 2.0 for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" version 2.0 along with fedfs-utils. If not, see: -.\" -.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -.\" -.TH RPC.FEDFSD 8 "@publication-date@" -.SH NAME -rpc.fedfsd \- FedFS administrative service daemon -.SH SYNOPSIS -.B rpc.fedfsd -.RB [ \-?dF ] -.RB [ \-u -.IR uid ] -.RB [ \-g -.IR gid ] -.RB [ \-o -.IR port ] -.SH DESCRIPTION -RFC 5716 introduces the Federated File System (FedFS, for short). -FedFS is an extensible standardized mechanism -by which system administrators construct -a coherent namespace across multiple file servers using -.IR "file system referrals" . -For further details, see -.BR fedfs (7). -.P -The -.BR rpc.fedfsd (8) -daemon runs on file servers participating in a FedFS domain. -It enables secure remote administration of junctions on that file server. -A remote FedFS administrative client can identify new NSDBs, update an -NSDB's connection parameters (security information and DNS name), and -create and delete FedFS junctions on that file server. -.P -Because -.BR rpc.fedfsd (8) -can operate on any object in an file server's local file systems, -FedFS administrative clients should use strong security -such as Kerberos when communicating with -.BR rpc.fedfsd (8). -.SS Command line arguments -.IP "\fB\-?, \-\-help" -Prints -.BR rpc.fedfsd (8) -version and usage message on -.IR stderr , -then exits. -.IP "\fB\-d, \-\-debug" -Enables additional debugging messages to be produced during operation. -.IP "\fB\-F, \-\-foreground" -Keeps -.BR rpc.fedfsd (8) -attached to its controlling terminal so that operation -can be monitored directly, or run under a debugger. -.BR rpc.fedfsd (8) -also writes log messages on -.I stderr -instead of to the system log. -If this option is not specified, -.BR rpc.fedfsd (8) -backgrounds itself soon after it starts. -.IP "\fB\-u, \-\-uid=\fIid\fP" -Specifies the numeric or text UID that -.BR rpc.fedfsd (8) -runs under after dropping root privileges. -By default, the UID for the user -.I @fedfsuser@ -is used. -If that user doesn't exist, then the UID for -.I nobody -is used instead. -.IP "\fB\-g, \-\-gid=\fIid\fP" -Specifies the numeric or text GID that -.BR rpc.fedfsd (8) -runs under after dropping root privileges. -By default, the GID for the group -.I @fedfsuser@ -is used. -If that group doesn't exist, then the GID for -.I nobody -is used instead. -.IP "\fB\-o, \-\-port=\fInum\fP" -Specifies the port number used for RPC listener sockets. -If this option is not specified, -.BR rpc.fedfsd (8) -chooses a random ephemeral port for each listener socket. -.SS Access control -An Access Control List stored in -.I /etc/fedfsd/access.conf -manages whom -.BR rpc.fedfsd (8) -allows to perform ADMIN operations. -The following access types are supported: -.IP "\fBnone\fP" -Enabling -.B none -allows anyone using -.B AUTH_NONE -security to perform ADMIN operations. -.B none -is for backwards compatibility only. -It is not recommended for use in production deployments. -.IP "\fBunix\fP" -This setting specifies lists of users and groups who are allowed to use -.B AUTH_SYS -security to perform ADMIN operations. -Though the -.B unix -setting -provides more security than the -.BR none -setting, -.B unix -is not recommended for use on untrusted networks. -.IP "\fBgss\fP" -This setting specifies which GSS mechanisms, services, and principals -are authorized to perform ADMIN operations. -Currently the only supported GSS mechanism is -.BR kerberos_v5 . -.P -See comments in -.I /etc/fedfsd/access.conf -for details on syntax of the Access Control List. -.P -To enable Kerberos security via GSS, a service principal for the -.B fedfs-admin -service must be created for each host running -.BR rpc.fedfsd (8). -The resulting key must be retrieved from the KDC -and stored in a keytab file (usually -.IR /etc/krb5.keytab ) -on each host running -.BR rpc.fedfsd (8). -.P -The exact procedure for creating a service principal and retrieving -and storing a secret key for it depends on the type of KDC -in use for the local Kerberos realm. -Consult your local Kerberos realm administrator for more information. -.SH NOTES -To create, resolve, or delete a junction, FedFS admin clients -specify the pathname of that junction as an argument to the -requested operation. -The FedFS admin protocol supports at least two types of these -pathnames: -.IR ADMIN , -and -.IR NFS . -At this time the Linux -.BR rpc.fedfs (8) -daemon supports only FedFS ADMIN pathnames. -This type of pathname represents a fully-qualified POSIX pathname -relative to the file server's physical root directory. -.P -During each start-up, -.BR rpc.fedfsd (8) -verifies that the local NSDB connection parameter database exists -and is accessible. -If it does not exist, -.BR rpc.fedfsd (8) -attempts to create such a database. -If it cannot, the daemon fails to start. -.SH FILES -.TP -.I @statedir@/nsdbparam.sqlite3 -database of NSDB connection parameters -.TP -.I @statedir@/nsdbcerts -local directory that stores X.509 certificates for NSDBs -.TP -.I /etc/fedfsd/access.conf -controls remote access to rpc.fedfsd -.SH "SEE ALSO" -.BR fedfs (7), -.BR nfs (5) -.sp -RFC 5661 for the NFS version 4 specification -.sp -RFC 5716 for FedFS requirements and overview -.SH COLOPHON -This page is part of the fedfs-utils package. -A description of the project and information about reporting bugs -can be found at -.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . -.SH "AUTHOR" -Chuck Lever diff --git a/doc/man/rpc.fedfsd.8.in b/doc/man/rpc.fedfsd.8.in new file mode 100644 index 0000000..3a8b42d --- /dev/null +++ b/doc/man/rpc.fedfsd.8.in @@ -0,0 +1,205 @@ +.\"@(#)rpc.fedfsd.8" +.\" +.\" @file doc/man/rpc.fedfsd.8 +.\" @brief man page for FedFS Admin service daemon +.\" + +.\" +.\" Copyright 2011, 2013 Oracle. All rights reserved. +.\" +.\" This file is part of fedfs-utils. +.\" +.\" fedfs-utils is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2.0 as +.\" published by the Free Software Foundation. +.\" +.\" fedfs-utils is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License version 2.0 for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" version 2.0 along with fedfs-utils. If not, see: +.\" +.\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt +.\" +.TH RPC.FEDFSD 8 "@pubdate@" +.SH NAME +rpc.fedfsd \- FedFS administrative service daemon +.SH SYNOPSIS +.B rpc.fedfsd +.RB [ \-?dF ] +.RB [ \-u +.IR uid ] +.RB [ \-g +.IR gid ] +.RB [ \-o +.IR port ] +.SH DESCRIPTION +RFC 5716 introduces the Federated File System (FedFS, for short). +FedFS is an extensible standardized mechanism +by which system administrators construct +a coherent namespace across multiple file servers using +.IR "file system referrals" . +For further details, see +.BR fedfs (7). +.P +The +.BR rpc.fedfsd (8) +daemon runs on file servers participating in a FedFS domain. +It enables secure remote administration of junctions on that file server. +A remote FedFS administrative client can identify new NSDBs, update an +NSDB's connection parameters (security information and DNS name), and +create and delete FedFS junctions on that file server. +.P +Because +.BR rpc.fedfsd (8) +can operate on any object in an file server's local file systems, +FedFS administrative clients should use strong security +such as Kerberos when communicating with +.BR rpc.fedfsd (8). +.SS Command line arguments +.IP "\fB\-?, \-\-help" +Prints +.BR rpc.fedfsd (8) +version and usage message on +.IR stderr , +then exits. +.IP "\fB\-d, \-\-debug" +Enables additional debugging messages to be produced during operation. +.IP "\fB\-F, \-\-foreground" +Keeps +.BR rpc.fedfsd (8) +attached to its controlling terminal so that operation +can be monitored directly, or run under a debugger. +.BR rpc.fedfsd (8) +also writes log messages on +.I stderr +instead of to the system log. +If this option is not specified, +.BR rpc.fedfsd (8) +backgrounds itself soon after it starts. +.IP "\fB\-u, \-\-uid=\fIid\fP" +Specifies the numeric or text UID that +.BR rpc.fedfsd (8) +runs under after dropping root privileges. +By default, the UID for the user +.I @fedfsuser@ +is used. +If that user doesn't exist, then the UID for +.I nobody +is used instead. +.IP "\fB\-g, \-\-gid=\fIid\fP" +Specifies the numeric or text GID that +.BR rpc.fedfsd (8) +runs under after dropping root privileges. +By default, the GID for the group +.I @fedfsuser@ +is used. +If that group doesn't exist, then the GID for +.I nobody +is used instead. +.IP "\fB\-o, \-\-port=\fInum\fP" +Specifies the port number used for RPC listener sockets. +If this option is not specified, +.BR rpc.fedfsd (8) +chooses a random ephemeral port for each listener socket. +.SS Access control +An Access Control List stored in +.I /etc/fedfsd/access.conf +manages whom +.BR rpc.fedfsd (8) +allows to perform ADMIN operations. +The following access types are supported: +.IP "\fBnone\fP" +Enabling +.B none +allows anyone using +.B AUTH_NONE +security to perform ADMIN operations. +.B none +is for backwards compatibility only. +It is not recommended for use in production deployments. +.IP "\fBunix\fP" +This setting specifies lists of users and groups who are allowed to use +.B AUTH_SYS +security to perform ADMIN operations. +Though the +.B unix +setting +provides more security than the +.BR none +setting, +.B unix +is not recommended for use on untrusted networks. +.IP "\fBgss\fP" +This setting specifies which GSS mechanisms, services, and principals +are authorized to perform ADMIN operations. +Currently the only supported GSS mechanism is +.BR kerberos_v5 . +.P +See comments in +.I /etc/fedfsd/access.conf +for details on syntax of the Access Control List. +.P +To enable Kerberos security via GSS, a service principal for the +.B fedfs-admin +service must be created for each host running +.BR rpc.fedfsd (8). +The resulting key must be retrieved from the KDC +and stored in a keytab file (usually +.IR /etc/krb5.keytab ) +on each host running +.BR rpc.fedfsd (8). +.P +The exact procedure for creating a service principal and retrieving +and storing a secret key for it depends on the type of KDC +in use for the local Kerberos realm. +Consult your local Kerberos realm administrator for more information. +.SH NOTES +To create, resolve, or delete a junction, FedFS admin clients +specify the pathname of that junction as an argument to the +requested operation. +The FedFS admin protocol supports at least two types of these +pathnames: +.IR ADMIN , +and +.IR NFS . +At this time the Linux +.BR rpc.fedfs (8) +daemon supports only FedFS ADMIN pathnames. +This type of pathname represents a fully-qualified POSIX pathname +relative to the file server's physical root directory. +.P +During each start-up, +.BR rpc.fedfsd (8) +verifies that the local NSDB connection parameter database exists +and is accessible. +If it does not exist, +.BR rpc.fedfsd (8) +attempts to create such a database. +If it cannot, the daemon fails to start. +.SH FILES +.TP +.I @statedir@/nsdbparam.sqlite3 +database of NSDB connection parameters +.TP +.I @statedir@/nsdbcerts +local directory that stores X.509 certificates for NSDBs +.TP +.I /etc/fedfsd/access.conf +controls remote access to rpc.fedfsd +.SH "SEE ALSO" +.BR fedfs (7), +.BR nfs (5) +.sp +RFC 5661 for the NFS version 4 specification +.sp +RFC 5716 for FedFS requirements and overview +.SH COLOPHON +This page is part of the fedfs-utils package. +A description of the project and information about reporting bugs +can be found at +.IR http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject . +.SH "AUTHOR" +Chuck Lever