[MacPorts] #16930: more explanation in the guide for startupitems

[MacPorts]

#16930: more explanation in the guide for startupitems
------------------------------------------------+---------------------------
 Reporter:  dweber at macports.org                 |       Owner:  markd at macports.org     
     Type:  enhancement                         |      Status:  new                    
 Priority:  Normal                              |   Milestone:  Website & Documentation
Component:  guide                               |     Version:  1.6.0                  
 Keywords:  startupitem daemondo launchd guide  |        Port:                         
------------------------------------------------+---------------------------
 I found the guide for startupitems is too terse, without adequate
 background explanation of the tools that implement the process.  Please
 include information on how to get further information, such as:

 {{{
 man launchd
 man launchctl
 daemondo --help
 }}}

 The latter is helpful, as {{{man daemondo}} doesn't exist (can we create
 it?).

 In my case, I found it useful to read through the entire thread that was
 engaged during the creation of the guide for this section (esp. comments
 therein from James Berry), ie:

 Ryan Schmidt, "daemondo defeats purpose of launchd?" at
 http://lists.macosforge.org/pipermail/macports-
 dev/2007-September/002669.html

 If I had time and an understanding of the documentation dev process, I
 would contribute directly, but it may be easier for the current dev folks
 to update this section of the guide.  I would really like to see a few
 paragraphs from James' comments adapted into the background for this
 section of the guide.  His comments are succinct and illuminating (esp. in
 the context of that thread).  For example,

 {{{
 daemondo will indeed quit when it detects that the launched process
 has quit, and thus will "keep alive" the process, since launchd will
 then restart daemondo. In this way, daemondo acts as a shim or
 adapter between the scripts supported by the startupitem command,
 and the single process expected by launchd.

 The reason that startupitem.executable is preferred is that this
 gives the best possible chance that daemondo will be able to detect
 the death of the launched process: since daemondo can launch the
 process, it can also detect when it quits, stop it, etc.

 For those cases where startupitem.executable cannot be used, daemondo
 also supports the startupitem.pidfile commands that allow the
 process' pidfile to be monitored: daemondo will read the pidfile and
 watch for the death of that process.

 So daemondo, and thus launchd, will be aware of the daemon process
 death (and be able to restart the daemon process) only under two
 circumstances:

 (1) startupitem.executable was supplied (thus daemondo starts the process)
 (2) startupitem.pidfile was supplied (thus daemondo reads the process id)

 Under all other circumstances, daemondo will not know that the daemon
 process has died, and will not exit when the process does die, and
 thus launchd won't restart the process since it doesn't  know it
 died. Put another way, if daemondo can know the process has died,
 then launchd will know too, but not otherwise.
 }}}


 {{{
 Note that for simplicity, startupitem.executable is handled by
 daemondo at present. This has two purposes:

         - It keeps the startupitem generating code a little simpler.
         - It allows the potential support for higher value services to be
 provided by daemondo. In particular, note daemondo's --restart-
 netchange option, which can be quite useful, but for which there is
 no current support by the startupitem keys.
 }}}

 Also, later in the thread, we have some comments that could be adapted for
 the guide:

 {{{
 ...

 I don't see  the incompatibility of those statements, but then I again
 I know what i meant, not necessarily what it means to others ;). The
 later sentence, btw, is missing a word on the end. It should read:
 "the pidfile keyword is likely useful only if the executable keyword
 is not specified." Does that help any?

 > Looks to me like startupitem.pidfile must be set for a deamon to be
 > tracked whether it is executable startupitem or not.

 No, daemondo will track an "executable" in an case (and it doesn't
 need to know where their pidfile is, generally, since it launches the
 code and thus knows the pid). In the case of script code (non
 "executable") daemondo doesn't know the pid, since it doesn't know
 what the script code did. In this case, it has to rely on reading a
 pidfile to get the process id, or else simply not know.

 > And the man page
 > says startupitem.pidfile is "particularly useful" for
 > startupitem.executable.  Can you explain this?

 That was either garbage to begin with, or else got messed up in
 creation of the man page. Off the top of my head I can't see any
 particular reason to use a pidfile keyword in conjunction with the
 executable keyword, unless it's to specify that it should delete a
 pidfile created by the executable, and I'm not sure that even works
 for that case.

 Hope that helps.

 James
 }}}


 Best, Darren


 PS, In the description of the startupitem.pidfile, can we remove the OR
 operator, ie:
 {{{
 Default: [none] | [${prefix}/var/run/${name}.pid]
 }}}

 It's easy to confuse this syntax as either:
 {{{
 Default: [none]
 }}}
 OR
 {{{
 Default: [${prefix}/var/run/${name}.pid]
 }}}
 However, we do need two arguments: [daemondoAction] [pidFile]

-- 
Ticket URL: <http://trac.macports.org/ticket/16930>
MacPorts <http://www.macports.org/>
Ports system for Mac OS