[nfsv4] [FedFS] fedfsNfsPath attribute format

[James Lentini <[e-mail]>]

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