[OpenIndiana-discuss] How to document SMF facilities for an upstream package

[Gary Mills]

On Thu, Jan 27, 2011 at 10:04:52PM -0500, Gordon Ross wrote:
> On Thu, Jan 27, 2011 at 7:45 PM, Gary Mills <mills at cc.umanitoba.ca> wrote:
> > I've just completed writing a spec file to build an IPS package for
> > the ISC DHCP server.  I haven't made any changes to the source for
> > this product, and don't want to.  That should all be done upstream.
> 
> Sometimes it's not that simple though. There's a lot of magic in SMF
> (and even more in "ctfs" - contracts) so you can't necessarily just take
> some open-source server program and run it as an SMF service.
> As an example, I saw a problem with Samba where it did fork/exec of
> some helper process (printing? I forget what) where that process died
> with a fatal signal, and SMF took the whole service "offline".  The issue
> here is that there are rules for running as an SMF service, which you
> sometimes can't just ignore.  Something to watch out for.

It must be an uncommon problem.  I've written many SMF manifests and
method scripts without encountering that one.  They do need to be
tested, of course.

> > [...]  How should I document the SMF facilities?
> [... service FMRI, properties, RBAC privileges...]
> 
> In a case like this, I think it's practical to handle the illumos-specific
> parts like this as a local patch. Unless the upstream wants to carry
> system specific stuff like that and pre-process it away somehow on
> other systems were it does not apply.

Okay, I decided to go with a patch for the man pages.  It's actually a
pretty straightforward addition to the spec file.  What I did was to
add a new subheading called `SERVICE MANAGEMENT FACILITY' before the
`COMMAND LINE' subheading.  I put all of the SMF information in that
new subsection.

-- 
-Gary Mills-        -Unix Group-        -Computer and Network Services-