Subject: [nfsv4] Namespace terminology

From: Ted Anderson <[email-masked]>
Date: Thu, 15 Jan 2004 08:44:25 -0500

Here are some definitions for terms that have been used in this extended
discussion.  I've tried to make the terms consistent with each other,
and added some new ones, but I've borrowed text from the discussion
liberally and without attribution.  There is some meta-discussion at the
end.

fragment -- A sub-tree which is exported as an indivisible unit by a
     server.  If the server is high in the namespace, this might be a
     single directory containing nothing but referrals and hosted by an
     LDAP database.  Lower in the namespace it would likely be a file
     server's filesystem.  If the namespace supports file junctions then
     a fragment might be as small as a single file.  Fragments have names
     (possibly structured like pathnames) unique within each domain.

junction -- a link between two fragments of the namespace that are
     connected for the purposes of pathname traversal.  The fragment that
     is the target of the junction replaces the junction in its parent
     directory for purposes of file system operations; thus it operates
     somewhat like symbolic links.

LTE -- (location table entry) the conceptual mapping between a fragment
     and one or more physical locations where it is located.  Each
     location is a URL(s) describing contact information for the server
     exporting the fragment.

referral -- a combination of a junction and an LTE.  Thus a referral
     maps a pathname to a physical location(s).  An NFSv4 client sees
     referrals while the NFSv4 server sees junctions and LTEs.

map -- the representation, perhaps stored in a database or configuration
     file, of the connections between fragments.  The global map is
     composed of many individual maps that point to each other in a
     directed graph.  A map defines a domain of the namespace.  (Because
     these maps will be managed by many different entities, there is
     little hope for guaranteeing acyclicity.  Clients of the namespace
     will just have to cope.)  A domain's namespace map is supplemented
     by a location table.

location table -- tracks the location(s) of each fragment in the domain.
     The location table is a list of LTE(s) keyed by fragment name.

filesystem -- a fragment that is stored in a file system and accessed by
     a file server.

virtual directory -- directories in fragments that contain only other
     virtual directories and junctions.  Generally, a namespace server
     will render a map stored in a database (e.g. LDAP) as a tree of
     virtual directories.  The NFSv4 server's pseudo filesystem glues
     together exported filesystems using virtual directories.

/net -- The Solaris automounter (and others) has an option to mount the
     host namespace on some mountpoint (typically "/net") such that the
     next path component down is a hostname and down from there there's
     the exports or pseudo filesystem of the host in question.  Thus we
     have: "/net/somehost/someshare/somepath".  This makes "net" (stored
     in DNS) and "somehost" (stored in somehost's mtab) virtual
     directories.

DISCUSSION

Should we try to find a better name for "fragments"?  It is a pretty
generic term, but "namespace fragment" is clear enough though long.

Do we need a better name for "LTE"?

We could redefine "referral" to mean "LTE" instead of the collective
"junction" + "LTE".  But this might be confusing and lead to
misunderstandings, as it is already heavily used in this discussion
(though not in RFC3530).

The term "map" comes by extension from automounter maps.  It is very
generic and should be used as "namespace map" to disambiguate.  Should
we dispose of this term and use something like namespace domain or
namespace database depending on circumstances?  By analogy with the
automounter, perhaps "map" should be expanded to include "location
table", however, this didn't seem to be implied by the original usage
(by Julian on 21-Dec-2003).  In other words, should we say that a "map"
is "namespace table" + "location table"?

Additions, corrections, or reorganizational ideas are welcome.

Ted Anderson

_______________________________________________
nfsv4 mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/nfsv4

---

From: Nicolas Williams <[email-masked]>
Date: Fri, 16 Jan 2004 16:25:11 -0600

>     (possibly structured like pathnames) unique within each domain.

 - I've been calling this a "sub-namespace" -- I'm just as happy to use
   "namespace fragment," but "fragment" by itself seems insufficiently
   descriptive.

 - It seems to me that sub-namespaces, or namespace fragments, can have
   multiple [path]names.

   See examples given earlier in the other thread.

 - Namespace fragments could also have multiple types of names, one type
   being pathnames (relative to other junctions or relative to a
   namespace root), another being more like automount map names.  The
   latter are often easier to reference.

>     somewhat like symbolic links.

 - I'd say junctions are, conceptually and from users' perspectives,
   more like mounts than they are like symbolic links, though on the
   wire they look more like symbolic links.

>     location is a URL(s) describing contact information for the server

 - The word "entry" seems more appropriate to a concept directly linked
   to the directory.  Thus we could have "locations," "location tables"
   and "location table entries."

>     referrals while the NFSv4 server sees junctions and LTEs.

 - This seems too simplified to me because:

    - A server may issue referrals as a result of namespace junctions,
      but it may also issue referrals as a result of FS migration.

    - A server need not issue a referral to clients crossing a namespace
      junction if the server is a location for both sides of the
      junction.

>     will just have to cope.)  A domain's namespace map is supplemented

 - I think, in the end, that there wil be no such thing as a "global
   namespace" or "global map" anymore than sysadmins allow it, for which
   reason I'd rather speak as little of it as possible and instead focus
   on per-administrative domain namespaces and the mechanisms by which
   the locations of those are determined -- given which a global
   namespace can follow trivially.  The point about cross-domain
   references and cycles is very important to make, however, the one
   being necessary to make a global namespace a better experience and
   the other being a result of the first.

>     The location table is a list of LTE(s) keyed by fragment name.

 - I see the sub-namespace name as the name of the table, not the name
   of the entries in the table.

>     together exported filesystems using virtual directories.

 - I'm not sure that this is necessary.  This restriction is common to
   "indirect" automount maps, but it isn't obvious that it must remain
   in a referral-based namespace.

   I've been thinking of the schema modelling for namespace
   configuration lately and the automounter model keeps coming up as a
   reasonably straightforward one that can, with few changes, model most
   of what we've been discussing.

   I'm particularly interested in making sure that whatever model we
   choose is workable for both, smart-clients and
   dumb-clients/smart-servers.

>     in DNS) and "somehost" (stored in somehost's mtab) virtual

 - The Solaris terminology for this is "the -hosts special map."  In the
   context of a global namespace composed of per-domain namespace I can
   also imagine a "-domains special map."

> generic term, but "namespace fragment" is clear enough though long.

Yes.  See above.

> Do we need a better name for "LTE"?

Yes.  See above.

> misunderstandings, as it is already heavily used in this discussion

No.

> generic and should be used as "namespace map" to disambiguate.  Should

Fortunately the term maps nicely to the notion of namespace junctions.
See above.

> is "namespace table" + "location table"?

The term maps to a concept of a per-namespace junction sub-namespace
configuration database.

> Additions, corrections, or reorganizational ideas are welcome.

Cheers,

Nico
--

---

From: Julian Satran <[email-masked]>
Date: Mon, 19 Jan 2004 00:48:12 -0800

>       junction if the server is a location for both sides of the

A large portion of this lists bandwidth was devoted to referral use for 
load balancing (and migration).

> >     will just have to cope.)  A domain's namespace map is supplemented

I am not sure that we have to allow links outside the bounds of 
administrative domains
or alternatively severely restrict the number of domains a path can 
traverse. This leaves you with a manageable problem (acyclic only within a 
domain).
> 
>  - I think, in the end, that there will be no such thing as a "global

---

From: Ted Anderson <[email-masked]>
Date: Fri, 30 Jan 2004 10:08:02 -0500

Apologies for the delayed reply.

>    "namespace fragment," but "fragment" by itself seems insufficiently

I agree.  I'm also open to some better term as well.

>    See examples given earlier in the other thread.

Yes.

>    latter are often easier to reference.

I'm not clear exactly what automount map names are.  However, I agree
that a fragment will have multiple types of names.  I'd call them
"absolute pathnames", "relative (to another fragment) pathnames", and
"fragment names".  The latter are arbitrary names (e.g.
users.ota.backup), whose scope is local to a namespace domain.  This
namespace domain becomes a qualifier for fragment names in junction 
targets.  This qualifier might naturally default to the namespace domain 
of the parent fragment, or could be specified explicitly.  In AFS terms 
a namespace domain is a cell and junctions with an explicitly specified 
domain are called cellular mountpoints.

>    wire they look more like symbolic links.

Sure, but except for lstat() and unlink() symlinks are as invisible as 
mounts to file system API users.

>    and "location table entries."

I don't get your point here.  Are you arguing for the suitability of LTE 
as a name for this concept?

>       junction if the server is a location for both sides of the

Okay.  This is a result of the complicated (and confusing) use of the 
term "referral" on the mailing list.  Interestingly the term does not 
appear in  RFC3530.  Maybe it would be better to define the word 
explicitly to be some clear subset of its current (de facto) meaning and 
select other terms for other aspects of its meaning.  This would seem 
preferable to defining it as "that thing that NFSv4 servers do in this 
list of situations".

>    the other being a result of the first.

I agree with this.  The concept of a global map may be useful in 
explaining the namespace to users, but operationally it basically a fiction.

>    of the entries in the table.

I think we agree the definitions of sub-namespace and fragment are the 
same.  Then I mean a location table to look like this, one LTE per line:
     ...
     users.nico => mercury.acm.org
     users.ota => venus.acm.org
     software.X11r6.x86 => mars.acm.org, jupiter.acm.org
     ...
So there would be one table per server administrative domain (which 
would often be one-to-one with namespace domains).

>    in a referral-based namespace.

I don't mean it as a restriction.  I may have confused things with the 
reference to NFSv4's pseudo-fs.  Its directories are invisible to users 
and used only by clients to navigate to exported filesystems.  For 
virtual directories, I meant to describe a directory, high in the 
namespace, that contains no files but only other virtual directories and 
junctions and may be hosted by an LDAP database not a file system.  They 
are virtual in that the underlying (database) representation might not 
contain directories but only lists of junctions identified by fragment 
names and relative pathnames.  However, they would be directories in the 
sense that a user could "cd" to them and "ls" in them.

>    dumb-clients/smart-servers.

My concern about the automounter model is that it doesn't make any clear 
distinction between namespace junctions and location tables.  But I have 
no operational experience with automounter and my academic experience is 
quite limited.  My reference for the automounter is Callaghan's "NFS 
Illustrated".  I can well imagine that this isn't the best source. 
Could you recommend a guide for understanding this system, which I 
realized is not just a single system.

>    also imagine a "-domains special map."

Exactly.

>>generic term, but "namespace fragment" is clear enough though long.

You like sub-namespace better?

>>Do we need a better name for "LTE"?

I didn't get your suggested alternative for LTE.

> The term maps to a concept of a per-namespace junction sub-namespace

Ted

---

From: Nicolas Williams <[email-masked]>
Date: Fri, 30 Jan 2004 10:09:41 -0600

> >   See examples given earlier in the other thread.

[snip]

> distinction between namespace junctions and location tables.

But it does.

Here's the correspondence between automount concepts and what we've been
discussing:

 automount feature		NFSv4 namespace feature
 -----------------		-----------------------

 indirect map			sub-namespace config. DB
 master map			namespace root for a domain

 "normal" indirect map entry	junction to a filesystem
 map entry w/ -fstype=autofs	junction to another sub-namespace

["normal" -> the -fstype option is set to "nfs" or not given]

Note that an indirect automount map can be referenced from multiple
locations in the automount namespace (by using -fstype=autofs in
automount entries, for example), which permits multiple paths to
sub-namespaces, which we agree is good.

>                                                               But I have 

Check out:

http://docs.sun.com/db/doc/816-0211/6m6nc66nc?a=view#automount-1m-indx-1

[snip]
> mounts to file system API users.

Which is why namespace junctions look like mounts from users'
perspectives :)

> as a name for this concept?

Well, first off I'm confused by "... conceptual mapping between a
fragment and one or more physical locations where it is located."

Second, "entry" indicates "table" or "database" to me, so "LTE" may be
appropriate, but only in the context of a model of namespace
configuration (which may well be what you had in mind and I just
misread).

> preferable to defining it as "that thing that NFSv4 servers do in this 

https://www1.ietf.org/mail-archive/working-groups/nfsv4/current/msg00618.html

"Referral" refers to servers' use of the NFSv4 migration facility to
redirect a client in the process of crossing into a filesystem that does
not reside on the server it is talking to.

The distinction between "referral" and the rest of the NFSv4 migration
facility is about when the NFS4ERR_MOVED/GETATTR(fs_locations4) events
take place: a) "referral" -> before the client has acquired FH (much
less state) for a "migrated" resource, b) "migration" -> a resource the
client has an FH for, or even state, has actually moved.

In (a) the client doesn't know, and doesn't care, if the resource in
question ever actually did reside on the server doing the referral, and
it may not have, so one can hardly speak of migration (though referrals
are needed in order to support migration).

[snip]
> You like sub-namespace better?

Yes.  In particular it distinguishes the "root" of a domain's namespace,
which I think is useful (see the "Namespace root server authorization"
thread).

Cheers,

Nico
--

---

From: Ted Anderson <[email-masked]>
Date: Fri, 30 Jan 2004 12:13:51 -0500

">" is On 1/30/2004 11:09, Nicolas Williams wrote:
">>" is On Fri, Jan 30, 2004 at 10:08:02AM -0500, Ted Anderson wrote:
">>>" On 1/16/2004 17:25, Nicolas Williams wrote:

>  automount feature		NFSv4 namespace feature

Okay this is good.  I gather that none of these examples actually 
include location information, those are in still other (non-indirect) maps.

> http://docs.sun.com/db/doc/816-0211/6m6nc66nc?a=view#automount-1m-indx-1

Thanks, I will.

> fragment and one or more physical locations where it is located."

I used the word "conceptual" here because the mapping might not actually 
use a table with entries be have some entirely different structure. 
However, maybe the term "mapping" should be viewed abstractly by itself.

> configuration (which may well be what you had in mind and I just

I think it may be what I had in mind, but I'm not quite sure if you mean 
more by "configuration" than just a table containing mappings.  I 
introduced this concept only to distinquish between namespace 
connections between "fragments" or "sub-namespaces" which I have been 
calling junctions, and the association between fragments/sub-namespaces 
and their locations.  Following Julian's usage I tried to make "map" 
refer just to the junctions and invented the term "location table" for 
the corresponding location information.  It seems like you prefer using 
"namespace" for "map" and "configuration" for "map" + "location table".

> https://www1.ietf.org/mail-archive/working-groups/nfsv4/current/msg00618.html

This exchange made sense to me.

> are needed in order to support migration).

Okay, maybe the problem is that I've been overzealous in defining names 
for objects (even conceptual ones) and tried to force "referral" into 
this scheme.  However, I see that "referral" is the name for a process 
that a server uses in connection with the verb "refer".  I think some 
have used "referral" for (b), but perhaps we can just say that isn't 
correct and not become confused.

> which I think is useful (see the "Namespace root server authorization"

Okay.  I was thinking of a multi-level arrangement:
/gfs/ibm.com/ => the namespace for IBM's domain in Poughkeepsie
/gfs/ibm.com/research => a virtual directory within ibm.com
/gfs/ibm.com/research/almaden => another namespace hosted at Almaden
/gfs/ibm.com/research/hr => a namespace owned by HR dept in Research
/gfs/ibm.com/software => a namespace owned by Software Group
/gfs/ibm.com/hr => another virtual directory
/gfs/ibm.com/hr/us => a namespace hosted in Endicott
/gfs/ibm.com/hr/in => ditto, but in Bagalore

The part of the namespace hosted by ibm.com is a namespace fragment 
since it has authorization responsibility.  The namespace at 
/gfs/ibm.com/research/almaden is both a namespace and a sub-namespace. 
However, maybe it isn't too important to make this distinction.

Ted

---

From: Nicolas Williams <[email-masked]>
Date: Fri, 30 Jan 2004 11:59:34 -0600

> include location information, those are in still other (non-indirect) maps.

Oh no, what I called "normal" automount entries contain location
information.

Here's some examples (siplified -- not quite what you see in actual
automount entries):

map name	entry name	entry
--------	----------	-----

auto_master	/apps		-fstype=autofs auto_apps
...
auto_apps	KillerApp	-fstype=autofs auto_killerapp
auto_apps	webbrowser	server1,server2,server3:/path/to/webbrowser
auto_apps	OldApp		/ server1:/path/to/OldApp /data server1:/path/to/OldApp_data_fs
...

So the namespace root has "/apps" which is a sub-namespace with several
things in it (KillerApp, webbrowser, OldApp), one of which (KillerApp)
is itself a sub-namespace, another (webbrowser) is just an fs location
(with replicas) and another (OldApp) is an unnamed sub-namespace
consisting of two fs locations.

Visually (note: this is not the client view -- the client will mount
this somewhere on its local namespace):

/			<-- namespace root
/apps/			<-- "apps" sub-namespace
/apps/KillerApp/	<-- "KillerApp" sub-namespace
/apps/webbrowser/	<-- webbrowser fs location
/apps/OldApp/		<-- anonymous sub-namespace with two fs
			    locations, one mounted on:
/apps/OldApp/data/

> Okay.  I was thinking of a multi-level arrangement:

[This is a client-side view.]

> /gfs/ibm.com/ => the namespace for IBM's domain in Poughkeepsie
                ^^=> namespace root of ibm.com

> /gfs/ibm.com/research => a virtual directory within ibm.com
			^^=> a sub-namespace of ibm.com
...

> However, maybe it isn't too important to make this distinction.

As long as we know how to find namespace roots and how to authorize
servers to serve them we're done.  If we can do that with referrals and
just a bit more, good, if not we'll have to have smart clients
exclusively -- but I think we can do this with referrals.

Cheers,

Nico
--