Administration Protocol for Federated File Systems
RFC 7533

I have a few non-blocking comments, most of which have to do with combinations of 2119 key words.  In all of those cases, I'm not *sure* what you want to say.  If you really do want to say what's there, then my comments are wrong.  But if, as I suspect, this is *not* really what you're trying to say, then we should sort out the right text.  Please chat with me about them if that will help.

-- Section 5.2.2 --
   If the path contains an invalid UTF-8 character, then status
   FEDFS_ERR_BADCHAR MUST be returned.

What characters are valid?  When I look at the definition of FEDFS_ERR_BADCHAR, I think you mean "unsupported", rather than "invalid"... yes?  [I'm picking on this because the IDNA specs actually *do* define valid and invalid characters, and you probably don't want to try to mess with that. :-) ]

This also appears in Sections 5.3.2, 5.4.2, 5.5.2, 5.6.2, and 5.7.2.

-- Section 5.5.2 --
   The server SHOULD permit this operation even on read-only filesets,
   but MAY return FEDFS_ERR_ROFS if this is not possible.

You might mean exactly this, in which case it's fine, but this is a SHOULD/MAY construct that's often wrong, so I'm checking.  "SHOULD do X but MAY do Y" is correct if Y is *always* optional.  But more often, this is what's really intended:

   The server SHOULD permit this operation even on read-only filesets,
   but MUST return FEDFS_ERR_ROFS if this is not possible.

Is that the case here?
This also appears in Section 5.6.2.

This one is related:
   The server MAY enforce the local permissions on the path, including
   the final component.  If the path cannot be traversed because of
   insufficient permissions, or the final component is an unexecutable
   or unwritable directory, then the operation MAY fail with status
   FEDFS_ERR_ACCESS.

If you mean this, then the phrasing above is correct:
1. The server MAY enforce local permissions.
2. If it does, then it MAY use FEDFS_ERR_ACCESS to convey failures (but that's entirely optional, and it could use some other code instead).

But if you mean this, then you should re-phrase:
1. The server MAY enforce local permissions.
2. If it does, then it MUST use FEDFS_ERR_ACCESS to convey failures.

This also appears in Sections 5.2.2, 5.3.2, 5.4.2, 5.6.2, and 5.7.2.

-- Section 5.9.2 --
   On failure, an error value indicating the type of error is returned.
   This operation MAY return FEDFS_ERR_NSDB_PARAMS to indicate that
   there are no connection parameters on record for the given NSDB.  The
   operation MAY return FEDFS_ERR_ACCESS if the operation's associated
   user does not have sufficient permissions to view NSDB connection
   parameters.

This is similar to some of the others.  If you mean to say that using those error codes is entirely optional, even under the conditions specified, then this is fine.  But if you mean to say that certain error codes are definitely the ones to use in these situations, then the MAYs are wrong, and you should re-word this.

There are similar situations at the ends of Sections 5.8.2 and 5.10.2.

1.1

   Client:  Any client that accesses fileserver data using a supported
      file-access protocol.

I love circular definitions as much as the next guy, but how about at least indicating whether the client is the software, the machine, the user, or some other theoretical entity? The above is not useful.

   Fileserver:  A server exporting one or more filesystems via a file-
      access protocol.

Hmmmm....That's not a terribly helpful definition.

4.  Data Types

   The basic data types defined above MUST be formatted as follows:

The MUST is strange. I always say that you should use MUST if an implementation might accidentally choose to do otherwise and cause an interoperability problem. In this case, choosing to do otherwise is not an accident; it's just insanity. It's probably just as good to say "The basic data types defined above are formatted as follows:". That said:

   FedFsUuid:  A universally unique identifier (UUID) as described in
      [RFC4122] as a version 4 UUID.  The UUID should be formatted in
      network byte order.

There's something weird about the first sentence. The contradiction of the "MUST" above and the "should" here is glaring. Don't you want to say here that the UUID MUST be in network byte order? *That* would cause an interoperability issue, wouldn't it?

      A system (i.e.,
      fileserver or administrative host) SHOULD resolve the fully
      qualified domain name to a network address using the system's
      standard resolution mechanisms.

SHOULD do something that is implementation dependent? That doesn't look right.

      The secType field indicates the security mechanism that MUST be
      used to protect all connections to the NSDB with the connection
      parameters.

      A value of FEDFS_SEC_NONE indicates that no security mechanism is
      necessary.  In this case, the secData array will have 0 length.

There appears to be a conflict in the above. I read the first sentence as saying that whatever is in secType MUST be used; you can not use an alternative. However, the second sentence indicates that no security mechanism is "necessary", implying that you *could* use a security mechanism if you wanted to. Which is it? Do I have to respect what's in secType, or are there instances where I can choose what I like?

I'm sorry to sound like the "RFC 2119 language police" with these
comments.  In my opinion, my comments refer to text whose meaning
(and, therefore interoperability of implementations) depends on the
interpretation of the RFC 2219 language.

In section 4:

   FedFsUuid:  A universally unique identifier (UUID) as described in
      [RFC4122] as a version 4 UUID.  The UUID should be formatted in
      network byte order.

s/should/MUST/ ?

   FedFsNsdbName:  A (hostname, port) pair.
      [...]
      A value of 0 indicates that the standard LDAP port number, 389,
      SHOULD be assumed.

s/SHOULD/MUST/, or explain when 389 is not assumed and what is used
instead of 389.  Why would one set the port to 0 instead of just using
the more direct 389, anyway?  The answer to this question should be
applied in section 4.1.

      [...]Therefore, a FedFsNsdbName SHOULD NOT contain a network address,
      such as an IPv4 or IPv6 address, as this would indefinitely assign
      the network address.

s/SHOULD NOT/MUST NOT/, or explain the syntax for encoding a network
address in a FedFsNsdbName.

   FedFsPathComponent:  A case sensitive UTF-8 string containing a
      filesystem path component.  It SHOULD be prepared using the
      component4 rules defined in Chapter 12 "Internationalization" of
      [3530bis].

When would it not "be prepared using the component4 rules[...]" and
how would that case be identified?

In section 5, some error conditions are specified as "MUST be
returned", some as "SHOULD be returned", some as "MUST fail with
status [...]" and some are not specified with any RFC 2119 language.
At the risk of suggesting foolish consistency, I suggest a editing
pass for consistency, with explanations of what to do if a SHOULD is
not followed, would likely ease the mind of an implementor.  (OK, I
admit this comment is mostly stylistic, except for the clarification
of SHOULDs.)

  I think that it would be useful to encourage implementers to install
  the trust anchors so that they are scoped to a specific NSDB.  This
  would be much better than using global trust anchors.

Thanks for clearing my discusses.