From patchwork Mon Oct 29 17:34:31 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Chuck Lever X-Patchwork-Id: 195083 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from rcsinet15.oracle.com (rcsinet15.oracle.com [148.87.113.117]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (Client CN "rcsinet15.oracle.com", Issuer "VeriSign Class 3 International Server CA - G3" (not verified)) by ozlabs.org (Postfix) with ESMTPS id 042CA2C008A for ; Tue, 30 Oct 2012 04:34:47 +1100 (EST) Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by rcsinet15.oracle.com (Sentrion-MTA-4.2.2/Sentrion-MTA-4.2.2) with ESMTP id q9THYiBe011280 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 29 Oct 2012 17:34:45 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 q9THYiA1017603 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Mon, 29 Oct 2012 17:34:44 GMT Received: from localhost ([127.0.0.1] helo=oss.oracle.com) by oss.oracle.com with esmtp (Exim 4.63) (envelope-from ) id 1TStEa-00050Y-1a; Mon, 29 Oct 2012 10:34:44 -0700 Received: from ucsinet21.oracle.com ([156.151.31.93]) by oss.oracle.com with esmtp (Exim 4.63) (envelope-from ) id 1TStEX-00050P-PZ for fedfs-utils-devel@oss.oracle.com; Mon, 29 Oct 2012 10:34:41 -0700 Received: from acsinet11.oracle.com (acsinet11.oracle.com [141.146.126.233]) by ucsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id q9THYep3019676 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Mon, 29 Oct 2012 17:34:41 GMT Received: from mail-ie0-f171.google.com (mail-ie0-f171.google.com [209.85.223.171]) by acsinet11.oracle.com (Sentrion-MTA-4.2.2/Sentrion-MTA-4.2.2) with ESMTP id q9THYONk030145 (version=TLSv1/SSLv3 cipher=RC4-SHA bits=128 verify=OK) for ; Mon, 29 Oct 2012 17:34:40 GMT Received: by mail-ie0-f171.google.com with SMTP id s9so6641109iec.2 for ; Mon, 29 Oct 2012 10:34:40 -0700 (PDT) Received: by 10.50.237.6 with SMTP id uy6mr10467480igc.31.1351532079952; Mon, 29 Oct 2012 10:34:39 -0700 (PDT) Received: from seurat.1015granger.net (adsl-99-26-161-222.dsl.sfldmi.sbcglobal.net. [99.26.161.222]) by mx.google.com with ESMTPS id rd10sm6017548igb.1.2012.10.29.10.34.31 (version=TLSv1/SSLv3 cipher=OTHER); Mon, 29 Oct 2012 10:34:32 -0700 (PDT) From: Chuck Lever To: fedfs-utils-devel@oss.oracle.com Date: Mon, 29 Oct 2012 13:34:31 -0400 Message-ID: <20121029173430.53098.12592.stgit@seurat.1015granger.net> In-Reply-To: <20121029173011.53098.41779.stgit@seurat.1015granger.net> References: <20121029173011.53098.41779.stgit@seurat.1015granger.net> User-Agent: StGIT/0.14.3 MIME-Version: 1.0 X-Flow-Control-Info: class=Default reputation=ipRepBelow100 ip=209.85.223.171 ct-class=R4 ct-vol1=-97 ct-vol2=9 ct-vol3=8 ct-risk=30 ct-spam1=37 ct-spam2=8 ct-bulk=6 rcpts=1 size=6997 X-MM-CT-Classification: not spam X-MM-CT-RefID: str=0001.0A090203.508EBE30.0077,ss=1,re=0.000,fgs=0 X-MIME-Autoconverted: from 8bit to quoted-printable by ucsinet21.oracle.com id q9THYep3019676 Subject: [fedfs-utils] [PATCH 2/9] fedfs(7): Update and clarify 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] A collection of clarifications and updates to fedfs(7). Signed-off-by: Chuck Lever --- doc/man/fedfs.7 | 55 ++++++++++++++++++++++++++----------------------------- 1 files changed, 26 insertions(+), 29 deletions(-) diff --git a/doc/man/fedfs.7 b/doc/man/fedfs.7 index d00356e..84d3099 100644 --- a/doc/man/fedfs.7 +++ b/doc/man/fedfs.7 @@ -47,8 +47,8 @@ to file system protocols or client implementations. FedFS provides its namespace features using referral mechanisms already built in to network file system protocols. .P -As a result, FedFS provides network file system namespace configuration -to file system clients via network file systems themselves, +As a result, FedFS provides a network file system namespace +via the network file system protocols themselves, rather than via side-band protocols like NIS. Clients automatically share a common view of the network file system namespace with no need for individual configuration on each client. @@ -60,30 +60,29 @@ FedFS may support other network file system protocols in the future. .SH FEDFS DOMAIN OPERATION A file system referral that is managed by FedFS is called a .IR "FedFS junction" . -Junctions join multiple file server shares into a single coherent +Junctions join separate file server shares into a single coherent FedFS namespace. On FedFS-enabled Linux file servers, the .BR rpc.fedfsd (8) -daemon creates and removes FedFS junctions. +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 name-mapping realms, for example. -.P -Thus, FedFS-enabled file system clients and servers are not members +FedFS domains are file namespaces only. +They do not represent authentication or ID-mapping realms, for example. +FedFS-enabled file system clients and servers are not members of any FedFS domain and do not have .I "a priori" knowledge of what FedFS domains exist. -FedFS-enabled clients assume their own DNS domain name is the local -FedFS domain name. .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 other directories. +and a few other directories. Useful data is contained in other shares -which clients discover by following FedFS junctions +which clients discover by following the FedFS junctions in the domain root directory. .P Although FedFS junctions are stored on file servers, @@ -93,18 +92,14 @@ is stored on an LDAP server. LDAP servers that store FedFS information are known as .IR "namespace databases" , or NSDBs, for short. -.P Any standard LDAP server can become an NSDB if it knows the FedFS schema (the definitions of FedFS record types). -The Linux FedFS implementation is designed to work with NSDBs residing -on any standard LDAP server that use the standard FedFS schema -laid out in the FedFS NSDB draft. .P 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 nothing more than one or more filesets, +A FedFS domain consists of one or more filesets, a domain root, and junction information stored on an NSDB. .P @@ -114,18 +109,20 @@ and a set of locations where the file data is stored. 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. A FedFS .I fileset location is an LDAP record that describes the location -(the server where it resides, and its export path) +(the file server 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, for example, can have multiple replicas. +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, then, contains nothing more than a FedFS fileset name. -When a file server resolves a FedFS junction, it performs an LDAP +A FedFS junction contains only a FedFS fileset name. +A file server resolves a FedFS junction by performing an LDAP query against the NSDB named in the junction using the UUID named in the junction. The NSDB returns location information stored in FedFS fileset location records for that FedFS fileset name. @@ -148,7 +145,7 @@ By default, FedFS-enabled file system clients mount read-only replicas. .P Rather than using junctions and information in an NSDB, -clients locate replicas of a domain's root by looking for +FedFS-enabled clients locate a domain's root by looking for DNS SRV records that advertise file servers exporting domain root replicas. .P Clients typically mount FedFS domain roots in a standard place so that @@ -180,16 +177,16 @@ are visible at a different point in a client's name space than are read-only replicas. .SS Globally Useful Names On FedFS-enabled Linux clients, -either the automounter, with a special program map, or the +the automounter (via a program map) or the .BR mount.fedfs (8) -command finds and mounts the root of a FedFS domain. +command find and mount the root of a FedFS domain. .P Typically, FedFS 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 client in a domain. +on every client in a FedFS domain. .P For example, the FedFS globally useful name .I /nfs4/example.net @@ -211,14 +208,14 @@ However, it breaks cross-platform application interoperability by presenting applications with multiple pathnames to the same file object. Therefore it should be avoided. .SS Mount option inheritance -When encountering a file system referral, the Linux client -treats it as a server-initiated mount request. -The referring server provides only a list of server names and export paths. +The Linux NFS client treats an NFS referral +as a server-initiated mount request. +The referring file server 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 encounter both file sets to which they have +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 the server to provide proper access to both types of file sets,