I'm working on a project at
the moment, which has a number
of contributers. We're managing
the project gate (which is stand alone) with mercurial. We want to have an easy way
of seeing
the changelog, so we can show management what is going on.
Luckily mercurial provides a basic
web server which allows you to see
the changes, and drill in to change sets. This can be run as a daemon, but as it was running on our build server, every time it was rebooted, someone needed to remember to start
the process again. This is
of course a classic usage
of SMF.
Now I'm not an experienced person at writing SMF services, so it took me 1/2 an hour or so to figure it out
the first time. But going forward I should know what I'm doing a bit better. I did reference this doc extensively.
Taking a step back,
the command to start
the mercurial
web server is
$ hg serve -p <port number> -d
So we somehow need to get SMF to run that command for us.
In
the simplest form, SMF services are really made up
of two components.
The manifest
Usually lives in /var/svc/manifest somewhere
Can be imported from any location
The method
Usually live in /lib/svc/method
I simply put
the script straight in that directory. Not very repeatable, but it worked
Can take an argument
of start, stop, or refresh
Lets start with
the manifest. This looks pretty complex, but all it's doing is describing
the service name,
the dependencies,
the start and stop methods, and some properties.
The properties can be by instance, that is to say I could have multiple hg serve processes handling different mercurial projects, on different ports simultaneously
Here is
the manifest I wrote. I stole extensively from
the examples in
the Documentation.
So my manifest looks like this
$ cat hg-serve.xml
<?xml version="1.0"?>
<!DOCTYPE service_bundle SYSTEM "/usr/share/lib/xml/dtd/service_bundle.dtd.1">
<service_bundle type='manifest' name='hg-serve'>
<service
name='application/network/hg-serve'
type='service'
version='1'>
<dependency
name='network'
grouping='require_all'
restart_on='none'
type='service'>
<service_fmri value='svc:/milestone/network:default' />
</dependency>
<exec_method
type='method'
name='start'
exec='/lib/svc/method/hg-serve %m'
timeout_seconds='2' />
<exec_method
type='method'
name='stop'
exec=':kill'
timeout_seconds='2'>
</exec_method>
<instance name='project-gate' enabled='true'>
<method_context>
<method_credential user='root' group='root' />
</method_context>
<property_group name='hg-serve' type='application'>
<propval name='path' type='astring' value='/src/project-gate'/>
<propval name='port' type='astring' value='9998' />
</property_group>
</instance>
<stability value='Evolving' />
<template>
<common_name>
<loctext xml:lang='C'>hg-serve</loctext>
</common_name>
<documentation>
<manpage title='hg' section='1' />
</documentation>
</template>
</service>
</service_bundle>
So
the only things I had to decide on in this are
the service name "application/network/hg-serve"
the start and stop methods (more
of which later) and
the properties. This is
the information I need to pass to
the start method script. In my case
the port I want to start
the web server on "9998", and
the path to
the source gate "/src/project-gate". These can be read in to
the start method.
So now lets look at
the method scripts
$ cat /lib/svc/method/hg-serve
#!/sbin/sh
#
#
# Copyright (c) 2012, Oracle and/or its affiliates. All rights reserved.
#
# Standard prolog
#
. /lib/svc/share/smf_include.sh
if [ -z $SMF_FMRI ]; then
echo "SMF framework variables are not initialized."
exit $SMF_EXIT_ERR
fi
#
# Build
the command line flags
#
# Get
the port and directory from
the SMF properties
port=`svcprop -c -p hg-serve/port $SMF_FMRI`
dir=`svcprop -c -p hg-serve/path $SMF_FMRI`
echo "$1"
case "$1" in
'start')
cd $dir
/usr/bin/hg serve -d -p $port
;;
*)
echo "Usage: $0 {start|refresh|stop}"
exit 1
;;
esac
exit $SMF_EXIT_OK
This is all pretty self explanatory, we read
the port and directory using svcprop, and use those simply to run a command in
the start case. We don't need to implement a stop case, as
the manifest says to use "exec=':kill'for
the stop method.
Now all we need to do is import
the manifest and start
the service, but first verify
the manifest
# svccfg verify /path/to/hg-serve.xml
If that doesn't give an error try importing it
# svccfg import /path/to/hg-serve.xml
If like me you originally put
the hg-serve.xml file in /var/svc/manifest somewhere you'll get an error and told to restart
the import service
svccfg: Restarting svc:/system/manifest-import
The manifest being imported is from a standard location and should be imported with
the command : svcadm restart svc:/system/manifest-import
# svcadm restart svc:/system/manifest-import
and you're nearly done. You can look at
the service using svcs -l
# svcs -l hg-serve
fmri svc:/application/network/hg-serve:project-gate
name hg-serve
enabled false
state disabled
next_state none
state_time Thu May 31 16:11:47 2012
logfile /var/svc/log/application-network-hg-serve:project-gate.log
restarter svc:/system/svc/restarter:default
contract_id 15749
manifest /var/svc/manifest/network/hg/hg-serve.xml
dependency require_all/none svc:/milestone/network:default (online)
And look at
the interesting properties
# svcprop hg-serve
hg-serve/path astring /src/project-gate
hg-serve/port astring 9998
...stuff deleted....
Then simply enable
the service and if every things gone right, you can point your browser at http://server:9998 and get a nice graphical log
of project activity.
# svcadm enable hg-serve
# svcs -l hg-serve
fmri svc:/application/network/hg-serve:project-gate
name hg-serve
enabled true
state online
next_state none
state_time Thu May 31 16:18:11 2012
logfile /var/svc/log/application-network-hg-serve:project-gate.log
restarter svc:/system/svc/restarter:default
contract_id 15858
manifest /var/svc/manifest/network/hg/hg-serve.xml
dependency require_all/none svc:/milestone/network:default (online)
None
of this is rocket science, but a bit fiddly. Hence I thought I'd blog it. It might just be you see this in google and it clicks with you more than one
of the many other blogs or how tos about it. Plus I can always refer back to it myself in 3 weeks, when I want to add another project to
the server, and I've forgotten how to do it.
