Skip to contentSkip to conversation

Suggestion for better manpage.

DISCUSSION Stef Bon 4 participants 5 messages Jun 17, 2008 – Jun 18, 2008 Kernel automounter

lore
Share & tools
lore

Stef Bon

author
#0 lore raw

Hello,

reading the manpage of automount, I would like to change the section in the manpage about how the daemon reacts on signals.

It is now:

If the automount daemon catches a USR1 signal, it will umount all currently unused autofs managed mounted file systems and continue running
(forced expire). If it catches the TERM signal it will umount all
unused autofs managed mounted file systems and exit if there are no remaining
busy file systems. If autofs has been compiled with the option to
ignore busy mounts on exit it will exit leaving any busy mounts in place other-
wise busy file systems will not be umounted and autofs will not exit.
Alternatively, if autofs has been compiled with the option to enable forced
shutdown then a USR2 signal to the daemon will cause all mounts to be
umounted and any busy mounts to be forcibly umounted, including autofs mount
point directories (summary execution). Note that the forced umount is
an unlink operation and the actual umount will not happen in the kernel un-
til active file handles are released. The daemon also responds to a
HUP signal which triggers an update of the maps for each mount point.

If any autofs mount point directories are busy when the daemon is sent
an exit signal the daemon will not exit. The exception to this is if autofs
has been built with configure options to either ignore busy mounts at
exit or force umount at exit. If the ignore busy mounts at exit option is
used the filesystems will be left in a catatonic (non-functional)
state and can be manually umounted when they become unused. If the force umount
at exit option is used the filesystems will be umounted but the mount
will not be released by the kernel until they are no longer in use by the
processes that held them busy. If automount managed filesystems are
found mounted when autofs is started they will be recoverd unless they are no
longer present in the map in which case they need to umounted manually.

I would like to suggest:

The automount daemon can react on a few signals. Some of them are standard, others are less standard and/or need compiletime options.

TERM

If it catches the TERM signal it will umount all unused autofs managed mounted filesystems, and exit if there are no remaining mounts left. It will keep on running (till??)
If compiled with the "ignore busy mounts" option, it will exit here, and leave any mountpoint in place.

USR2
This only applies when the automounter is compiled with the "enable forced shudown". When it catches the USR2, it will umount all mounts, busy or not.
Note: umounting a busy mountpoint is actually an unlink operation. The actual umount will be done later, when all active file handleds are released. (this id done by??)

USR1
With the USR1 signal it will umount all currently unused mounts, and continue running (forced expire).

HUP
This signal triggers an update of the maps for each mountpoint.

I've left out some parts, but mostly rearranged the information. I've left
out the text "summary execution" Is it important?

But what do you think. Is it better this way?

Stef Bon

maintainer
#1 lore raw
Quoted 4 lines · Stef Bon

Hello,

reading the manpage of automount, I would like to change the section in the manpage about how the daemon reacts on signals.

Send a patch.

Quoted 36 lines

It is now:

If the automount daemon catches a USR1 signal, it will umount all currently unused autofs managed mounted file systems and continue running
(forced expire). If it catches the TERM signal it will umount all
unused autofs managed mounted file systems and exit if there are no remaining
busy file systems. If autofs has been compiled with the option to
ignore busy mounts on exit it will exit leaving any busy mounts in place other-
wise busy file systems will not be umounted and autofs will not exit.
Alternatively, if autofs has been compiled with the option to enable forced
shutdown then a USR2 signal to the daemon will cause all mounts to be
umounted and any busy mounts to be forcibly umounted, including autofs mount
point directories (summary execution). Note that the forced umount is
an unlink operation and the actual umount will not happen in the kernel un-
til active file handles are released. The daemon also responds to a
HUP signal which triggers an update of the maps for each mount point.

If any autofs mount point directories are busy when the daemon is sent
an exit signal the daemon will not exit. The exception to this is if autofs
has been built with configure options to either ignore busy mounts at
exit or force umount at exit. If the ignore busy mounts at exit option is
used the filesystems will be left in a catatonic (non-functional)
state and can be manually umounted when they become unused. If the force umount
at exit option is used the filesystems will be umounted but the mount
will not be released by the kernel until they are no longer in use by the
processes that held them busy. If automount managed filesystems are
found mounted when autofs is started they will be recoverd unless they are no
longer present in the map in which case they need to umounted manually.

I would like to suggest:

Quoted 8 lines

The automount daemon can react on a few signals. Some of them are standard, others are less standard and/or need compiletime options.

TERM

If it catches the TERM signal it will umount all unused autofs managed mounted filesystems, and exit if there are no remaining mounts left. It will keep on running (till??)

You eventually send a TERM signal and no mounts are in use.

Quoted 9 lines

If compiled with the "ignore busy mounts" option, it will exit here, and leave any mountpoint in place.

USR2
This only applies when the automounter is compiled with the "enable forced shudown". When it catches the USR2, it will umount all mounts, busy or not.
Note: umounting a busy mountpoint is actually an unlink operation. The actual umount will be done later, when all active file handleds are released. (this id done by??)

Kernel.

Quoted 20 lines

USR1
With the USR1 signal it will umount all currently unused mounts, and continue running (forced expire).

HUP
This signal triggers an update of the maps for each mountpoint.

I've left out some parts, but mostly rearranged the information. I've left
out the text "summary execution" Is it important?

But what do you think. Is it better this way?

Stef Bon

_______________________________________________
autofs mailing list
[email protected]
http://linux.kernel.org/mailman/listinfo/autofs

#2 lore raw
Quoted 7 lines · Ian Kent
Quoted 4 lines · Stef Bon

Hello,

reading the manpage of automount, I would like to change the section in the manpage about how the daemon reacts on signals.

Send a patch.

Try this on for size.

Cheers,

Jeff

man/automount.8 +44 -29
index 59ad50e..4cb7384 100644
@@ -92,36 +92,51 @@ and the mount maps they will use. The default is
 \fBauto.master\fP.
 .hy
 .RE
+.SH SIGNALS
+.TP
+\fBSIGHUP\fP
+This signal triggers a re-read of the automount configuration.
+.TP
+\fBSIGTERM\fP
+This signal instructs the daemon to unmount all unused file systems
+and exit.  If any file system cannot be unmounted, then the daemon does not
+exit unless the daemon was compiled with either the ENABLE_IGNORE_BUSY_MOUNTS
+option or the ENABLE_FORCED_SHUTDOWN option set (see \fBNOTES\fP below).
+If ENABLE_IGNORE_BUSY_MOUNTS is set, the daemon will unmount unused file
+systems and exit, leaving busy file systems mounted.  If the
+ENABLE_FORCED_SHUTDOWN options is set, then the file systems will be
+unmounted and the daemon will exit, but the busy mountpoints will not be
+released by the kernel until they are no longer in use by the processes
+that held them busy.
+.TP
+\fBSIGUSR1\fP
+Sending this signal to the running automount daemon will cause a forced
+expire.  All automount-managed mount points that are not busy will be
+unmounted.
+.TP
+\fBSIGUSR2\fP
+This signal requires that the daemon is compiled with the
+ENABLE_FORCED_SHUTDOWN flag set (see \fBNOTES\fP below).  Sending this
+signal to the running automount daemon will cause a summary execution;
+all automount-managed mount points will be unmounted, whether they are busy
+or not.  Note that the forced unmount is an unlink operation (umount -l),
+and the actual umount will not happen in the kernel until active file
+handles are released.  In current incarnations of autofs (all releases of
+version 5, up to and including 5.0.3 and potentially newer releases, too),
+this can cause unwanted behaviour in applications.  Since the mount point
+is unlinked from the file system tree, and attempt to get a current working
+directory will fail.
+
 .SH NOTES
-If the \fBautomount\fP daemon catches a USR1 signal, it will umount all
-currently unused autofs managed mounted file systems and continue running
-(forced expire).  If it catches the TERM signal it will umount
-all unused autofs managed mounted file systems and exit if there are
-no remaining busy file systems. If autofs has been compiled with the
-option to ignore busy mounts on exit it will exit leaving any busy
-mounts in place otherwise busy file systems will not be umounted
-and autofs will not exit.
-Alternatively, if autofs has been compiled with the option to enable
-forced shutdown then a USR2 signal to the daemon will cause all
-mounts to be umounted and any busy mounts to be forcibly umounted,
-including autofs mount point directories (summary execution). Note
-that the forced umount is an unlink operation and the actual umount
-will not happen in the kernel until active file handles are released.
-The daemon also responds to a HUP signal which triggers an update of
-the maps for each mount point.
-.P
-If any autofs mount point directories are busy when the daemon is sent
-an exit signal the daemon will not exit. The exception to this is
-if autofs has been built with configure options to either ignore busy
-mounts at exit or force umount at exit. If the ignore busy mounts at
-exit option is used the filesystems will be left in a catatonic
-(non-functional) state and can be manually umounted when they become
-unused. If the force umount at exit option is used the filesystems
-will be umounted but the mount will not be released by the kernel
-until they are no longer in use by the processes that held them busy.
-If automount managed filesystems are found mounted when autofs is
-started they will be recoverd unless they are no longer present in
-the map in which case they need to umounted manually.
+To see which compile-time options were selected, run '/usr/sbin/automount -V'.
+The names of the selected options will be present in the "Compile options:"
+section.
+
+If automount-managed file systems are found already mounted when the automount
+daemon starts, those file systems will be recovered unless they are no longer
+present in the automounter configuration.  In that case, the file systems will
+need to be manually unmounted.
+
 .SH "SEE ALSO"
 .BR autofs (5),
 .BR autofs (8),
#3 lore raw

-- snip --

Review

Quoted 3 lines
(quoted diff) +2 -0
+applications.  Since the mount point is unlinked from the file system
 
+tree, and attempt to get a current working directory will fail.
         ^^^^^^^^^^^

s/and attempt/any attempt/

-----------------------------------------------------------------------------------
This email message is for the sole use of the intended recipient(s) and may contain confidential information. Any unauthorized review, use, disclosure or distribution is prohibited. If you are not the intended recipient, please contact the sender by reply email and destroy all copies of the original message.
-----------------------------------------------------------------------------------

author
#4 lore raw
In reply to Jeff Moyer
Quoted 4 lines · On Tuesday 17 June 2008 16:44:09 Jeff Moyer wrote:
Quoted 3 lines · Ian Kent
Quoted 2 lines · Stef Bon

Hello,

Quoted 8 lines
Quoted 4 lines
Quoted 2 lines

reading the manpage of automount, I would like to change the section in the manpage about how the daemon reacts on signals.

Send a patch.

Try this on for size.

Cheers,

OK, you've already done this. Very clever.

Stef