Subject: [nfsv4] [FedFS] fedfsNfsPath attribute format

From: James Lentini <[email-masked]>
Date: Thu, 17 Sep 2009 17:25:47 -0400 (EDT)

At last week's FedFS meeting, I took an action item to investigate 
string formats for the fedfsNfsPath attribute. We discussed some 
alternative formats at last week's meeting and here on the mailing 
list. This email is a summary of my thoughts on this topic and an 
invitation for feedback on the requirements and possible formats.

Problem Statement
=================

For review, the problem is how to represent pathnames in an LDAP FSL 
record. 

NFSv4[.1] represents pathnames using the pathname4 type. pathname4 is 
defined in XDR as a variable length array of variable length arrays of 
opaque data. The relevant definitions from 
draft-ietf-nfsv4-minorversion1-dot-x-12 are:

 typedef opaque          utf8string<>;
 typedef utf8string      utf8str_cs;
 typedef utf8str_cs      component4;
 typedef component4      pathname4<>;

As you can see, NFS path components are case sensitive (indicated by 
the _cs in utf8str_cs) UTF-8 strings. Since the path is stored in an 
array, there is no need to define pathname separators. As a result the 
protocol allows a path component to contain any UTF-8 character, 
including '\' and '/'.

Requirements
============

In our phone and email discussions, two requirements have surfaced: 

1. The fedfsNfsPath attribute must support path components 
representing an arbitrary UTF-8 string, including strings with '\', 
'/', and non-ASCII characters. By meeting this requirement, FedFS will 
be capable of expressing the same pathnames as NFS.

2. For ease of usability, standard LDAP tools must be capable of 
manipulating the fedfsNfsPath attribute.

We should discuss these further as both have a significant impact on 
the possible solutions. For example if #1 was changed to only require 
support for POSIX pathnames (although I don't think it should), the 
problem would be greatly simplified.

Alternatives
============

We've discussed two general options for the fedfsNfsPath attribute: a 
binary format and a string format. 

+ Binary Format

As a binary field, the attribute's format could be XDR encoded data 
equivalent to a pathname4. The advantage of this is that a 
fedfsNfsPath would be capable of expressing all possible NFS paths. 
Another advantage is that the NFS server does not need to parse or 
otherwise reformat the data for generating the referral. This both 
simplifies and improves the efficiency of the NFS server 
implementation.

A disadvantage of the binary format is that the field is not easily 
viewable or modifiable using a standard LDAP tool. We discussed 
manipulating the FSL records with a tool like the SNSDB project's 
cli_fedfs, a command line tool that works on entire LDAP records. 
There were objections that this was too heavy weight.

Since our discussions last week, I've realized that smaller, simpler 
tools could also address the usability concerns. For example, tools to 
convert to and from the binary XDR path format could be created. 
Suppose these tools are named path2xdr and xdr2path and have the 
following capabilities. path2xdr could take a command line argument 
representing the path in whatever format is used on the system, 
convert the path to XDR, and write the XDR to stdout or a file. 
Similarly, xdr2path could take an filename argument where the file 
contained an XDR path, and output the path in the system's standard 
format.

Given tools such as the ones above, standard LDAP command line and GUI 
tools could be used to interact with the fedfsNfsPath attribute in a 
straightforward manner. I'll give some examples using the ubiquitous 
OpenLDAP command line tools, but the workflow would be similar for a 
GUI tool such as Apache Directory Studio.

The process for adding or modifying an FSL record would be something 
like this:

 $ path2xdr /this/is/a/loca/path > /tmp/fsl_path
 $ ldapmodify -a -x -W -D "cn=admin,o=fedfs" -h nsdb.example.com -f fsl_add.ldif

where the file fsl_add.ldif might look something like this:

           dn:fedfsFslUuid=5678,fedfsFsnUuid=1234,o=fedfs
           changeType: add
           objectClass: fedfsNfsFsl
           fedfsFslUuid: 5678
           fedfsFsnUuid: 1234
           fedfsNsdbName: nsdb.example.com
           fedfsFslHost: server.example.com
           fedfsFslTTL: 300
           fedfsNfsPath:< file:///tmp/fsl_path
           fedfsNfsMajorVer: 4
           fedfsNfsMinorVer: 1
           fedfsNfsCurrency: 0
           fedfsNfsInfo:< file:///tmp/fls_info
           fedfsNfsFlags: 0
           fedfsNfsValidFor: 300
           fedfsAnnotation: "foo" = "bar"
           fedfsDescr: This is a description.

An example of viewing the path in the FSL record with UUID 1111 would 
be:

 $ ldapsearch -x -W -D "cn=admin,o=fedfs" -h nsdb.example.com -b "fedfsFsnUuid=9012,o=fedfs" -s one -t "(fedfsFslUuid=1111)" fedfsNfsPath

which would output:

 Enter LDAP Password: 
 # extended LDIF
 #
 # LDAPv3
 # base <fedfsFsnUuid=9012,o=fedfs> with scope oneLevel
 # filter: (fedfsFslUuid=1111)
 # requesting: fedfsNfsPath 
 #

 # 1111, 9012, fedfs
 dn: fedfsFslUuid=1111,fedfsFsnUuid=9012,o=fedfs
 fedfsNfsPath:< file:///tmp/ldapsearch-fedfsNfsPath-81Kb92

 # search result
 search: 2
 result: 0 Success

 # numResponses: 2
 # numEntries: 1

and then to view the FSL path

 $ xdr2path -i /tmp/ldapsearch-fedfsNfsPath-81Kb92
 /this/is/another/loca/path 

In this case, the overhead of the binary field is one extra step to 
view or modify an FSL. I'd argue that this is a small price to pay 
given the advantages. I'd also argue that path2xdr and xdr2path will 
be very simple tools to write. Of course, this is just an example of 
what might be created. The specification would not required or even 
need to described these. I've described them here only to show that 
manipulating a binary LDAP attribute can be made relatively painless.

To recap some of the pros and cons of a binary attribute:

  - Advantages:
        - Able to express all possible NFS paths
        - NFS does not need to parse

  - Disadvantages:
        - difficult to manipulate using standard LDAP tools
	  Addressed by path2xdr and xdr2path commands?

+ String Format

If we choose a string object, we have a field that is viewable and 
manipulable using standard LDAP tools. 

This is desirable from a usability perspective. A standard LDAP tool 
would be capable of viewing and manipulating the path field. However, 
note that an FSL has other binary fields, such as the fedfsNfsInfo, 
and string fields that require some amount of understanding to 
interpret, such as the fedfsNfsFlags, so even with a string pathname 
there is still a need to have special tools and/or in depth knowledge 
of the format.

On the downside any path separator character we choose may be an 
allowed path component character in some past, present or future 
system. The two most prevalent path name formats, POSIX and Windows, 
use different conventions. In order to meet requirement #1, we need to 
invent some FedFS-specific escaping sequence to support all possible 
NFS paths. We've discussed a number of these formats on the mailing 
list and at our meetings. My fear is that the usability of our 
FedFS-specific path format will be as difficult or worse than the 
binary format since it will not be a format administrators are 
familiar with.

Any string format also requires the fileserver to parse the 
attribute's value and reformat it for the referral. This will have a 
modest increase in implementation complexity and decrease in execution 
efficiency.

  - Advantages:
        - Easy to view and modify with standard LDAP tools

  - Disadvantages:
        - FedFS-specific format that will not be familiar to users
        - Difficult to choose a format that covers all cases in 
          perpetuity.
        - NFS server needs to parse path: adds modest code complexity 
          and decreases execution efficiency

---

From: Nicolas Williams <[email-masked]>
Date: Thu, 17 Sep 2009 16:46:24 -0500

Before we discuss binary encodings and the tools to go with them: what
is wrong with a textual encodign of pathnames?

Keep in mind that we considered several alternative textual encodings.

Nico
--

---

From: James Lentini <[email-masked]>
Date: Fri, 18 Sep 2009 09:48:07 -0400 (EDT)

> Keep in mind that we considered several alternative textual encodings.

Given the goal of supporting heterogeneous systems (POSIX, Windows, 
etc.), a format capable of expressing the formats on those systems is 
required.

There are a couple of disadvantages to a string encoding:

With a string encoding, FedFS would need to define its own, unique 
path format. Any format unique to FedFS will require some time for 
users to learn and understand. Furthermore, any format that looks good 
today may not work well in perpetuity (protocols live for ever).

A string format also requires additional implementation complexity 
(servers have to parse our unique format) and processing at the NFS 
server.

The FSL record already has a binary attribute, fedfsNfsInfo, so 
defining a binary path attribute wouldn't be establishing a new 
precedent.

-james

---

From: Robert Thurlow <[email-masked]>
Date: Fri, 18 Sep 2009 08:03:07 -0600

> 	  Addressed by path2xdr and xdr2path commands?

We can provide binary tools for all current, major platforms,
and we can provide source code as well, but it seems neither
will guarantee that an admin (not a developer) will be able
to get path2xdr/xdr2path when they need it on the platform
from which they need to administer something.  And even for
platforms we support, folks knowing where to get the tools
and having to do so is a hurdle.  I think it's a recipe for
frustration, unfortunately.

I think in practice that allowing either '/' or '\' for the
path separator, and adding an attribute to clearly say what
is being used, should cover us.   Adding an escape sequence
to embed this in a path component is probably wise, but I
don't know that I can produce examples where it will get used.

Rob T

---

From: James Lentini <[email-masked]>
Date: Fri, 18 Sep 2009 14:22:47 -0400 (EDT)

> frustration, unfortunately.

Administrators may need to install software to access an LDAP 
Directory. Not all Linux and Windows systems have LDAP tools built in. 
It doesn't seem like an undue burden for an administrator to install 
an additional tool for FedFS.

Such a tool is conceptually similar to the exportfs command. 
Administrators use exportfs to add a fileset to the local NFS 
namespace. It seems natural to use a tool for adding a fileset to the 
federated namespace.

Note that the LDAP Directory software doesn't need to be modified at 
all.

> I think in practice that allowing either '/' or '\' for the path 
> separator, and adding an attribute to clearly say what is being 
> used, should cover us. Adding an escape sequence to embed this in a 
> path component is probably wise, but I don't know that I can produce 
> examples where it will get used.

A problem arises in systems where the path separator can also be used 
in the filename. For example in VMS, the format is
 
 [dir1.dir2]file.extension

The '.' character is used both as a path separator and in the file 
name.

Another issue is how to deal with local conventions. It is apparently 
common to use the ¥ (Yen symbol) as a path separator in Japan and the 
₩ (Won symbol) as a path separator in Korea.

---

From: Robert Thurlow <[email-masked]>
Date: Fri, 18 Sep 2009 13:18:52 -0600

> an additional tool for FedFS.

This hold only if their first encounter with LDAP is
the need to administer a FedFS deployment.  I think
it's dramatically easier to get LDAP code than it
can ever be to get this add-on, in the absence of
vendor support in which context we're speaking.

> The '.' character is used both as a path separator and in the file 

And does VMS share any NFS or CIFS filesystems which
are presented in this way?

> ₩ (Won symbol) as a path separator in Korea.

On what operating systems would they be able to do this?
The path separator is not just a user syntax.

Rob T

---

From: James Lentini <[email-masked]>
Date: Fri, 18 Sep 2009 16:59:26 -0400 (EDT)

On Fri, 18 Sep 2009, Robert Thurlow wrote:

> James Lentini wrote:
> 
> > Administrators may need to install software to access an LDAP Directory. Not
> > all Linux and Windows systems have LDAP tools built in. It doesn't seem like
> > an undue burden for an administrator to install an additional tool for
> > FedFS.
> 

I would hope that it would be easy to obtain FedFS software, but I 
suppose time will tell.

In general, we're already assuming some amount of software upgrades 
before FedFS can be deployed. At the minimum, users will need to 
update their NFS server and (if they want to use SRV RR) their NFS 
clients. A tool to create the LDAP records seems relatively minor 
compared to those changes.

> > A problem arises in systems where the path separator can also be used in the
> > filename. For example in VMS, the format is
> > The '.' character is used both as a path separator and in the file name.
> 

I don't know about CIFS.

In NFS, the path format isn't an issue because the NFS protocol 
doesn't use path strings. As a result, an NFS server on VMS doesn't 
have a problem presenting local directories to a client.

> > Another issue is how to deal with local conventions. It is apparently common
> > to use the ¥ (Yen symbol) as a path separator in Japan and the ₩ (Won
> > symbol) as a path separator in Korea.
> 

Windows.

---

From: Trond Myklebust <[email-masked]>
Date: Fri, 18 Sep 2009 17:44:31 -0400

> > The path separator is not just a user syntax.

I seem to remember that there is actually a documented INT 10 based
system call going all the way back to the heady days of MS-DOS, that
enables the user to change the ascii value of that separator. I must
admit that I didn't know it was still in use, though...

Cheers
  Trond

---

From: Nicolas Williams <[email-masked]>
Date: Fri, 18 Sep 2009 17:12:17 -0500

> etc.), a format capable of expressing the formats on those systems is 

A string encoding can get you that.

> today may not work well in perpetuity (protocols live for ever).

One of the proposed schemes would not require that Windows or Unix users
learn a thing (they never have a need to escape the path component
separator).  Also, you can still provide additional tools, if you want.

> (servers have to parse our unique format) and processing at the NFS 

That's required no matter what.

> defining a binary path attribute wouldn't be establishing a new 

That too could be textually encoded.

Nico
--