(In reply to Norman Gray from comment #0)
> Additional info:
> 
> 
> The descriptive text at
> <https://www.vibrantbootcamp.com/Networking%20Guide/autoD.about_null.html>
> might be useful as starter text, and is copied here for convenience:
> 
> 
>     The -null built-in map is always used in association with a mount point
> and tells automount not to mount any remote filesystems to this mount point
> on the local host. This excludes any mounts to the associated mount point
> that may be specified:
> 
>     * on the automount command line.
>     * in any master or direct maps read by automount. (Indirect maps do not
> include a mount point and so are not relevant to this discussion.)
>   This map is typically used to prevent an NIS map from specifying a mount
> to a mount point that the local system does not want covered. Remember that
> a remote filesystem, when automounted, hides any existing files or
> directories under that mount point.

That's not quite how the null map works in Linux autofs.

Maybe my interpretation of what I read at the time is incorrect.
Information was scarce so that's quite likely.

One source was "Managing NFS and NIS", O'Reilly, 2001, page 185.

That description is quite vague which is why the implementation might
not be right but it has been present in autofs for quite a while so
I can't really change it now.

But a description is also missing and should be added.

Thanks for looking at this, Ian.  A couple of further thoughts:

You're right: I should have added a disclaimer saying that this text wasn't even specific about which OS it was talking about.

Now you mention it, I think I possess a copy of the O'Reilly book (though not ready to hand).  Even if I'd consulted it, though, I'd have presumed it was referring to the SunOS implementation, and so an unreliable guide to what the Linux autofs was committing itself to.

It's certainly true that the implementation would be difficult to change (though I take the position that if something's not documented, it doesn't exist, so all bets are off!).

I think it's fairly common to want to locally cancel out, or override, all or part of a shared automount map.  If any forthcoming documentation mentioned how to do that, using the `-null` map or otherwise, that would be a kindness to future sysadmins reading the manpage.

(In reply to Norman Gray from comment #2)
> Thanks for looking at this, Ian.  A couple of further thoughts:
> 
> You're right: I should have added a disclaimer saying that this text wasn't
> even specific about which OS it was talking about.

Not really needed.

Linux autofs should behave sufficiently close to other autofs
implementations to co-exist with them. It is meant to implement
the features of the Sun map format.

But info. I could find at the time appeared ambiguous so we
ended up with what we have.

> 
> Now you mention it, I think I possess a copy of the O'Reilly book (though
> not ready to hand).  Even if I'd consulted it, though, I'd have presumed it
> was referring to the SunOS implementation, and so an unreliable guide to
> what the Linux autofs was committing itself to.

That wasn't all I used but it was a long time ago now so I can't
remember.

> 
> It's certainly true that the implementation would be difficult to change
> (though I take the position that if something's not documented, it doesn't
> exist, so all bets are off!).

OTOH it should behave closely enough to what's expected to be
used.

> 
> I think it's fairly common to want to locally cancel out, or override, all
> or part of a shared automount map.  If any forthcoming documentation
> mentioned how to do that, using the `-null` map or otherwise, that would be
> a kindness to future sysadmins reading the manpage.

TBH I'm not sure it's used much.

How it should behave in Linux autofs is:

1) It's only valid in the master map.
2) It can only be used for paths that appear in the master map.
   - the indirect map top level mount point can be nulled, no mounts
     from the nulled mount are performed (essentially it isn't mounted).
   - direct map paths can be nulled since they must be present at startup,
     so direct mount map entries are (notionally) part the master map.
3) If there is a null entry for a path, once it is seen in the master
   map, if it occurs again it will be used as normal.

So I think the only functional difference is that in Linux autofs
it can be used to override remote master map entries with local
master map entries.

I'll need to come up with some man page text for this.

Created attachment 1786284 [details]
Patch - add missing desciption of null map option

Upstream patch, not yet applied to current RHEL source.

How does this description look to you?

(In reply to Ian Kent from comment #5)
> How does this description look to you?

Btw, if in fact -null entries don't behave this way then it's a
bug that needs to be fixed (from a Linux autofs POV).

That text looks good.

One glitch:

    s/entrry/entry/

Also, it might be worth adjusting the final paragraph, since I had to read it a couple of times to feel I was confident about the logic (I wasn't quite sure what the pronoun 'this' referred to in your last sentence).  How about:

    A path with a null entry, in the master map, will ignore a single subsequent matching entry in a remote master map.  Any matching paths following that will be treated as they normally would be, thus allowing local master map entries to override remote ones.

This also makes it explicit that this constitutes an exception from the implied uniqueness of indirect map mount points: it _is_ permissible to have (for example) two /opt entries in an auto.master, if the first is a -null map cancelling an entry in +auto.master.  I would, incidentally, guess that map mount points would be expected to be unique, with a first-match-wins logic for any duplicates, but I don't _think_ this is explicit anywhere (though there is a corresponding statement for indirect map entries).

Hmm: what happens if I have

    /opt -null
    +auto.master
    /opt <my local filesystem>

If there is in fact no /opt in auto.master, does the 'next entry ignored' rule cancel the <my local filesystem> entry?  The proposed text suggests it would ('ignore a subsequent master map entrry with the given path'), but that would be surprising behaviour to me as a sysadmin, and could create headaches if there were to be a /opt in +auto.master (which this /etc/auto.master is intended to ignore), which was then removed (so that <my local filesystem> suddenly became the ignored one).  If the 'next entry ignored' rule cancels only entries in included maps (good; POLA), that might be useful to spell out, for the benefit of the careful reader.



Thanks for looking at this so speedily.

(In reply to Norman Gray from comment #7)
> That text looks good.
> 
> One glitch:
> 
>     s/entrry/entry/
> 
> Also, it might be worth adjusting the final paragraph, since I had to read
> it a couple of times to feel I was confident about the logic (I wasn't quite
> sure what the pronoun 'this' referred to in your last sentence).  How about:

Yes, I had some trouble with that sentence.

> 
>     A path with a null entry, in the master map, will ignore a single
> subsequent matching entry in a remote master map.  Any matching paths
> following that will be treated as they normally would be, thus allowing
> local master map entries to override remote ones.

It doesn't need to be a remote master map, it can be any master map entry
including another entry in the same map.

So, from a common sense POV, the null map entries can't be subject to the
same uniqueness requirements as other master map entries.

The remote map override is an example, although it is likely the sort of
thing people would want to use it for.

The information available on how this should work is fairly poor IMO
so I'm open to comments from people that have used this feature in other
autofs implementations.

But without that I can only make assumptions.

> 
> This also makes it explicit that this constitutes an exception from the
> implied uniqueness of indirect map mount points: it _is_ permissible to have
> (for example) two /opt entries in an auto.master, if the first is a -null
> map cancelling an entry in +auto.master.  I would, incidentally, guess that
> map mount points would be expected to be unique, with a first-match-wins
> logic for any duplicates, but I don't _think_ this is explicit anywhere
> (though there is a corresponding statement for indirect map entries).

There can be only one entry for indirect mount map paths.
There can be multiple direct mount map entries for the special
path "/-" but paths within direct mount maps need to be unique.

It seems sensible to me that the null map necessarily can't be
expected to be subject to those requirements given it's purpose.

> 
> Hmm: what happens if I have
> 
>     /opt -null
>     +auto.master
>     /opt <my local filesystem>
> 
> If there is in fact no /opt in auto.master, does the 'next entry ignored'
> rule cancel the <my local filesystem> entry?  The proposed text suggests it
> would ('ignore a subsequent master map entrry with the given path'), but
> that would be surprising behaviour to me as a sysadmin, and could create
> headaches if there were to be a /opt in +auto.master (which this
> /etc/auto.master is intended to ignore), which was then removed (so that <my
> local filesystem> suddenly became the ignored one).  If the 'next entry
> ignored' rule cancels only entries in included maps (good; POLA), that might
> be useful to spell out, for the benefit of the careful reader.

Yes, it should.

The problem is there is nothing that I have seen that specifies what
should happen in the case you describe.

So, as far as I can gather, a null map entry is meant to null the next
entry so that's what I've tried to do.

The point is good though.

The above case amounts to saying that null map entries should only
apply to plus included maps which would be a difficult change to make
because plus included maps are meant to behave like they are part of
the map they are included into and the code has been written with
that assumption in mind.

Ian

(In reply to Ian Kent from comment #8)
> 
> The information available on how this should work is fairly poor IMO
> so I'm open to comments from people that have used this feature in other
> autofs implementations.
> 
> But without that I can only make assumptions.

An example of the ambiguity of null map behavior descriptions can
be seen in the Solaris autofs documentation at:
https://docs.oracle.com/cd/E88353_01/html/E72487/automount-8.html

From that page:
The –null map cancels a previous map for the directory indicated. This is most
useful in the /etc/auto_master for cancelling entries that would otherwise be
inherited from the +auto_master include entry. To be effective, the –null
entries must be inserted before the included map entry.

The only things that can be inferred from this is that the null entry must
appear before the entry it cancels and that the null entry will be effective
on a subsequent entry.

It doesn't specify that null map entries are only valid in the master map
so that could be a problem for me (but doesn't make much sense IMO) and it
doesn't detail what should happen once the null entry is seen, that's
something I thought made sense and could also be a compatibility problem.

And that comes from documentation of what should be the reference
implementation of autofs.

Unfortunately I can't install Solaris to check how it actually functions
any more.

Created attachment 1787065 [details]
Patch - add missing desciption of null map option

Is this revision more readable?

The update looks good.

> The information available on how this should work is fairly poor IMO
> so I'm open to comments from people that have used this feature in other
> autofs implementations.

It's been a while since I used the SunOS implementation, so can't remember much with certainty, I'm afraid.

> There can be only one entry for indirect mount map paths.
> There can be multiple direct mount map entries for the special
> path "/-" but paths within direct mount maps need to be unique.
> 
> It seems sensible to me that the null map necessarily can't be
> expected to be subject to those requirements given it's purpose.

Very true -- I was thinking of the general virtue of explicitness, but a short manpage is a good manpage.

> The above case amounts to saying that null map entries should only
> apply to plus included maps which would be a difficult change to make
> because plus included maps are meant to behave like they are part of
> the map they are included into and the code has been written with
> that assumption in mind.

If the semantics of plus-inclusion is intended to be the same as literal text-inclusion, then yes.  However I think it's equally plausible to say, for example, that plus-included maps are supplementary to the maps explicitly included in /etc/auto.master, which is a compact rule which would give a clear meaning to both

    /opt <my-mount>
    +auto.master   # including a /opt

and

    /opt -null
    +auto.master

Of course a 'first match wins' algorithm would (i) give much the same effect, (ii) have the same effect if plus-inclusion is or isn't the same as text-inclusion, (iii) make it clear what the behaviour will be if a duplicate key is found (otherwise warn?, fail?), and (iv) resolve any questions of what happens if a key disappears from a plus-included map.

As a general point, I think the underspecification of the behaviour in other implementations gives you a certain amount of licence to implement things in a 'sensible' way.  If the Linux autofs is not bug-compatible with (eg) the Solaris one, or if the Linux one is compatible with a vague Solaris specification but with different actual behaviour, then I as a user would not feel entitled to be outraged.  Such is the joy of heterogeneous OS sysadminning (and the Linux one would have the moral advantage of a clear manpage).  Short version: I don't think precise interoperability with the Solaris implementation should _necessarily_ be a goal, if it's hard or ugly to do.

Here, I'm not positively advocating you do it one way or the other (especially since one of the alternatives is actually implemented!). 

A couple of typos:

  * s/entrry/entry/
  * s/part the master/part of the master/
  * s/as they normally/as it normally/

(In reply to Norman Gray from comment #11)
> The update looks good.

Except for the changes you mention below, I'll fix those.

> 
> > The information available on how this should work is fairly poor IMO
> > so I'm open to comments from people that have used this feature in other
> > autofs implementations.
> 
> It's been a while since I used the SunOS implementation, so can't remember
> much with certainty, I'm afraid.
> 
> > There can be only one entry for indirect mount map paths.
> > There can be multiple direct mount map entries for the special
> > path "/-" but paths within direct mount maps need to be unique.
> > 
> > It seems sensible to me that the null map necessarily can't be
> > expected to be subject to those requirements given it's purpose.
> 
> Very true -- I was thinking of the general virtue of explicitness, but a
> short manpage is a good manpage.
> 
> > The above case amounts to saying that null map entries should only
> > apply to plus included maps which would be a difficult change to make
> > because plus included maps are meant to behave like they are part of
> > the map they are included into and the code has been written with
> > that assumption in mind.
> 
> If the semantics of plus-inclusion is intended to be the same as literal
> text-inclusion, then yes.  However I think it's equally plausible to say,
> for example, that plus-included maps are supplementary to the maps
> explicitly included in /etc/auto.master, which is a compact rule which would
> give a clear meaning to both

The literal text-inclusion is my interpretation based on what I have
read so that's what I've done from an implementation POV.

> 
>     /opt <my-mount>
>     +auto.master   # including a /opt
> 
> and
> 
>     /opt -null
>     +auto.master
> 
> Of course a 'first match wins' algorithm would (i) give much the same
> effect, (ii) have the same effect if plus-inclusion is or isn't the same as
> text-inclusion, (iii) make it clear what the behaviour will be if a
> duplicate key is found (otherwise warn?, fail?), and (iv) resolve any
> questions of what happens if a key disappears from a plus-included map.

It didn't make sense to me to fail reading the master map if a duplicate
path is encountered.

If a duplicate is encountered it's ignored and an info level message
is sent to the log saying so. If I find cases where that is not
happening it's a bug and would want to fix it (rather than change
behavior).

So it sounds like we are covered, with the better option behavior
already being present, or at least will be made so if shown not to
be so for some as yet unknown case.

> 
> As a general point, I think the underspecification of the behaviour in other
> implementations gives you a certain amount of licence to implement things in
> a 'sensible' way.  If the Linux autofs is not bug-compatible with (eg) the
> Solaris one, or if the Linux one is compatible with a vague Solaris
> specification but with different actual behaviour, then I as a user would
> not feel entitled to be outraged.  Such is the joy of heterogeneous OS
> sysadminning (and the Linux one would have the moral advantage of a clear
> manpage).  Short version: I don't think precise interoperability with the
> Solaris implementation should _necessarily_ be a goal, if it's hard or ugly
> to do.

The only restriction I have is that I wanted Linux autofs to be able
to co-exist in multi-arch/os environments so compatibility is, to the
extent that I can make it so, important to me.

> 
> Here, I'm not positively advocating you do it one way or the other
> (especially since one of the alternatives is actually implemented!). 
> 
> A couple of typos:
> 
>   * s/entrry/entry/
>   * s/part the master/part of the master/
>   * s/as they normally/as it normally/

Ha, yes I'll fix these.

Ian

Created attachment 1787440 [details]
Patch - add missing desciption of null map option

Another revision for your review.

That looks great.

Thanks for all your work on this, and for your patience with my quibbles.

Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory (autofs bug fix and enhancement update), and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

https://access.redhat.com/errata/RHBA-2021:4372