Added:
commons/proper/daemon/tags/COMMONS_DAEMON_1_0_3_RC3/src/site/xdoc/jsvc.xml
URL:
http://svn.apache.org/viewvc/commons/proper/daemon/tags/COMMONS_DAEMON_1_0_3_RC3/src/site/xdoc/jsvc.xml?rev=980662&view=auto
==============================================================================
--- commons/proper/daemon/tags/COMMONS_DAEMON_1_0_3_RC3/src/site/xdoc/jsvc.xml
(added)
+++ commons/proper/daemon/tags/COMMONS_DAEMON_1_0_3_RC3/src/site/xdoc/jsvc.xml
Fri Jul 30 06:50:12 2010
@@ -0,0 +1,294 @@
+<?xml version="1.0"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<document>
+
+ <properties>
+ <title>Daemon : Java Service</title>
+ <author email="[email protected]">Jean-Frederic
Clere</author>
+ </properties>
+
+<body>
+<section name="Introduction">
+<p>
+ Jsvc is a set of libraries and applications for making Java
+ applications run on UNIX more easily.
+ <br/>
+ Jsvc allows the application (e.g. Tomcat) to perform some privileged
operations as root
+ (e.g. bind to a port < 1024), and then switch identity to a
non-privileged user.
+ <br/>
+ It can run on Win32 via the Cygwin emulation layer (see
+ <a href="http://www.cygwin.com/";> Cygwin</a> for more information),
+ however Win32 users may prefer to use <a href="procrun.html"> procrun</a>
+ instead, which allows the application to run as a Windows Service.
+</p>
+<p>
+ The sources are located in the src/native/unix subdirectory.
+</p>
+<p>
+ In the future <a href="http://apr.apache.org/";> APR </a> may be used
+ to provide more portable platform support.
+</p>
+</section>
+
+<section name="Building from source">
+<p>
+To build under a UNIX operating system you will need:
+<ul>
+ <li>GNU AutoConf (at least version 2.53)</li>
+ <li>An ANSI-C compliant compiler (GCC is good)</li>
+ <li>GNU Make</li>
+ <li>A Java Platform 2 compliant SDK</li>
+</ul>
+
+
+You need to build the "configure" program with:
+
+<source>
+sh support/buildconf.sh
+</source>
+
+(Note it is possible to replace sh by any compatible shell like bash, ksh).
+
+The result should be something like:
+<source>
+support/buildconf.sh
+support/buildconf.sh: configure script generated successfully
+</source>
+Once the configure script is generated, follow the next section.
+</p>
+</section>
+
+<section name="Building from a release tarball">
+<p>
+To build the binary under a UNIX operating system you will need:
+<ul>
+ <li>An ANSI-C compliant compiler (GCC is good)</li>
+ <li>GNU Make</li>
+ <li>A Java Platform 2 compliant SDK</li>
+</ul>
+
+You have to specify the <code>JAVA_HOME</code> of the SDK
+either with the <code>--with-java=<dir></code> parameter or set the
<code>JAVA_HOME</code> environment
+to point to your SDK installation. For example:
+<source>
+./configure --with-java=/usr/java
+</source>
+or
+<source>
+export JAVA_HOME
+./configure
+</source>
+
+If your operating system is supported, configure will go through cleanly,
+otherwise it will report an error (please send us the details of your
+OS/JDK, or a patch against the sources). To build the binaries and
+libraries simply do:
+<source>
+make
+</source>
+This will generate the executable file <code>jsvc</code>.
+</p>
+</section>
+
+<section name="Starting jsvc">
+<p>
+To check the allowed parameters for the jsvc binary simply do:
+<source>
+./jsvc -help
+Usage: jsvc [-options] class [args...]
+
+Where options include:
+
+ -help | --help | -?
+ show this help page (implies -nodetach)
+ -jvm <JVM name>
+ use a specific Java Virtual Machine. Available JVMs:
+ 'client' 'server'
+ -cp / -classpath <directories and zip/jar files>
+ set search path for service classes and resouces
+ -home <directory>
+ set the path of your JDK or JRE installation (or set
+ the JAVA_HOME environment variable)
+ -version
+ show the current Java environment version (to check
+ correctness of -home and -jvm. Implies -nodetach)
+ -showversion
+ show the current Java environment version (to check
+ correctness of -home and -jvm) and continue execution.
+ -nodetach
+ don't detach from parent process and become a daemon
+ -debug
+ verbosely print debugging information
+ -check
+ only check service (implies -nodetach)
+ -user <user>
+ user used to run the daemon (defaults to current user)
+ -verbose[:class|gc|jni]
+ enable verbose output
+ -outfile </full/path/to/file>
+ Location for output from stdout (defaults to /dev/null)
+ Use the value '&2' to simulate '1>&2'
+ -errfile </full/path/to/file>
+ Location for output from stderr (defaults to /dev/null)
+ Use the value '&1' to simulate '2>&1'
+ -pidfile </full/path/to/file>
+ Location for output from the file containing the pid of jsvc
+ (defaults to /var/run/jsvc.pid)
+ -D<name>=<value>
+ set a Java system property
+ -X<option>
+ set Virtual Machine specific option
+ -ea[:<packagename>...|:<classname>]
+ -enableassertions[:<packagename>...|:<classname>]
+ enable assertions
+ -da[:<packagename>...|:<classname>]
+ -disableassertions[:<packagename>...|:<classname>]
+ disable assertions
+ -esa | -enablesystemassertions
+ enable system assertions
+ -dsa | -disablesystemassertions
+ disable system assertions
+ -agentlib:<libname>[=<options>]
+ load native agent library <libname>, e.g. -agentlib:hprof
+ -agentpath:<pathname>[=<options>]
+ load native agent library by full pathname
+ -javaagent:<jarpath>[=<options>]
+ load Java programming language agent, see java.lang.instrument
+ -procname <procname>
+ use the specified process name (works only for Linux)
+ -wait <waittime>
+ wait waittime seconds for the service to start
+ waittime should multiple of 10 (min=10)
+ -stop
+ stop the service using the file given in the -pidfile option
+ -keepstdin
+ does not redirect stdin to /dev/null
+
+</source>
+</p>
+
+</section>
+<section name="Using jsvc">
+<p>
+There two ways to use jsvc: via a Class that implements the Daemon interface or
+via calling a Class that has the required methods.
+For example Tomcat-4.1.x uses the Daemon interface
+whereas Tomcat-5.0.x provides a Class whose methods are called by jsvc
directly.
+</p>
+<subsection name="Via Daemon interface">
+<p>
+Do the following:
+<ul>
+ <li>Write a Class that implements the Daemon interface (MyClass).</li>
+ <li>Put it in a jarfile (my.jar).</li>
+ <li>Call jsvc like:
+ <source>
+./jsvc -cp commons-daemon.jar:my.jar MyClass
+ </source>
+ </li>
+</ul>
+</p>
+</subsection>
+<subsection name="Directly">
+<p>
+Write a Class (MyClass) that implements the following methods:
+<ul>
+ <li>void init(String[] arguments): Here open configuration files, create a
trace file, create
+ ServerSockets, Threads</li>
+ <li>void start(): Start the Thread, accept incoming connections</li>
+ <li>void stop(): Inform the Thread to terminate the run(), close the
ServerSockets</li>
+ <li><code>void destroy()</code>: Destroy any object created in init()</li>
+</ul>
+Store it in a jarfile and use as above:
+<source>
+./jsvc -cp my.jar MyClass
+</source>
+</p>
+</subsection>
+</section>
+<section name="How jsvc works">
+<p>
+Jsvc uses 3 processes: a launcher process, a controller process and a
controlled process.
+The controlled process is also the main java thread, if the JVM crashes
+the controller will restart it in the next minute.
+Jsvc is a daemon process so it should be started as root and the
<code>-user</code> parameter
+allows to downgrade to an unprivilegded user.
+When the <code>-wait</code> parameter is used, the launcher process waits
until the controller says
+"I am ready", otherwise it returns after creating the controller process.
+</p>
+
+<subsection name="Forks in commons-daemon">
+<p>
+Launcher process:
+<source>
+main()
+{
+ fork()
+ parent: wait_child(), wait until JAVA service started when the child says "I
am ready".
+ child: controller process.
+}
+</source>
+
+Controller process:
+<source>
+ while (fork()) {
+ parent: wait_for_child.
+ if exited and restart needed continue
+ else exit.
+ child: exit(child()). controlled process.
+ }
+</source>
+
+Controlled process:
+<source>
+In child(): controlled process.
+ init_JVM().
+ load_service().
+ start_service().
+ say "I am ready"
+ wait for signal or poll for stop
+ stop_service().
+ destroy_service().
+ destroy_JVM().
+ exit (with different codes so that parent knows if it has to restart us).
+</source>
+Note: The controller process uses signals to stop the controlled process.
+</p>
+</subsection>
+
+<subsection name="Downgrading user">
+<p>
+On Linux <code>setuid()</code>/<code>setgid()</code> + capabilities are used.
On other unix <code>setgid</code>/<code>initgroups</code> are used.
+
+We have something like:
+<source>
+/* as root */
+init_JVM().
+load_service. /* java_load() calls the load method */
+downgrade user (set_caps() or set_user_group())
+/* as the user $USER (from -user $USER parameter) */
+umask()
+start_service. /* java_start() calls the start method */
+</source>
+</p>
+</subsection>
+</section>
+
+</body>
+</document>
Propchange:
commons/proper/daemon/tags/COMMONS_DAEMON_1_0_3_RC3/src/site/xdoc/jsvc.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added:
commons/proper/daemon/tags/COMMONS_DAEMON_1_0_3_RC3/src/site/xdoc/mail-lists.xml
URL:
http://svn.apache.org/viewvc/commons/proper/daemon/tags/COMMONS_DAEMON_1_0_3_RC3/src/site/xdoc/mail-lists.xml?rev=980662&view=auto
==============================================================================
---
commons/proper/daemon/tags/COMMONS_DAEMON_1_0_3_RC3/src/site/xdoc/mail-lists.xml
(added)
+++
commons/proper/daemon/tags/COMMONS_DAEMON_1_0_3_RC3/src/site/xdoc/mail-lists.xml
Fri Jul 30 06:50:12 2010
@@ -0,0 +1,202 @@
+<?xml version="1.0"?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<!--
+ +======================================================================+
+ |**** ****|
+ |**** THIS FILE IS GENERATED BY THE COMMONS BUILD PLUGIN ****|
+ |**** DO NOT EDIT DIRECTLY ****|
+ |**** ****|
+ +======================================================================+
+ | TEMPLATE FILE: mail-lists-template.xml |
+ | commons-build-plugin/trunk/src/main/resources/commons-xdoc-templates |
+ +======================================================================+
+ | |
+ | 1) Re-generate using: mvn commons:mail-page |
+ | |
+ | 2) Set the following properties in the component's pom: |
+ | - commons.componentid (required, alphabetic, lower case) |
+ | |
+ | 3) Example Properties |
+ | |
+ | <properties> |
+ | <commons.componentid>math</commons.componentid> |
+ | </properties> |
+ | |
+ +======================================================================+
+-->
+<document>
+ <properties>
+ <title>Commons Daemon Mailing Lists</title>
+ <author email="[email protected]">Commons Documentation Team</author>
+ </properties>
+ <body>
+
+ <section name="Overview">
+ <p>
+ <a href="index.html">Commons Daemon</a> shares mailing lists with all
the other
+ <a href="http://commons.apache.org/components.html";>Commons
Components</a>.
+ To make it easier for people to only read messages related to
components they are interested in,
+ the convention in Commons is to prefix the subject line of messages
with the component's name,
+ for example:
+ <ul>
+ <li>[daemon] Problem with the ...</li>
+ </ul>
+ </p>
+ <p>
+ Questions related to the usage of Commons Daemon should be posted to
the
+ <a href="http://mail-archives.apache.org/mod_mbox/commons-user/";>User
List</a>.
+ <br />
+ The <a
href="http://mail-archives.apache.org/mod_mbox/commons-dev/";>Developer List</a>
+ is for questions and discussion related to the development of Commons
Daemon.
+ <br />
+ Please do not cross-post; developers are also subscribed to the user
list.
+ </p>
+ <p>
+ <strong>Note:</strong> please don't send patches or attachments to any
of the mailing lists.
+ Patches are best handled via the <a href="issue-tracking.html">Issue
Tracking</a> system.
+ Otherwise, please upload the file to a public server and include the
URL in the mail.
+ </p>
+ </section>
+
+ <section name="Commons Daemon Mailing Lists">
+ <p>
+ <strong>Please prefix the subject line of any messages for <a
href="index.html">Commons Daemon</a>
+ with <i>[daemon]</i></strong> - <i>thanks!</i>
+ <br />
+ <br />
+ </p>
+
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Subscribe</th>
+ <th>Unsubscribe</th>
+ <th>Post</th>
+ <th>Archive</th>
+ <th>Other Archives</th>
+ </tr>
+
+
+ <tr>
+ <td>
+ <strong>Commons User List</strong>
+ <br /><br />
+ Questions on using Commons Daemon.
+ <br /><br />
+ </td>
+ <td><a
href="mailto:[email protected]";>Subscribe</a></td>
+ <td><a
href="mailto:[email protected]";>Unsubscribe</a></td>
+ <td><a
href="mailto:[email protected]?subject=[daemon]";>Post</a></td>
+ <td><a
href="http://mail-archives.apache.org/mod_mbox/commons-user/";>mail-archives.apache.org</a></td>
+ <td><a
href="http://markmail.org/list/org.apache.commons.users/";>markmail.org</a><br />
+ <a
href="http://www.mail-archive.com/[email protected]/";>www.mail-archive.com</a><br
/>
+ <a
href="http://news.gmane.org/gmane.comp.jakarta.commons.devel";>news.gmane.org</a>
+ </td>
+ </tr>
+
+
+ <tr>
+ <td>
+ <strong>Commons Developer List</strong>
+ <br /><br />
+ Discussion of development of Commons Daemon.
+ <br /><br />
+ </td>
+ <td><a
href="mailto:[email protected]";>Subscribe</a></td>
+ <td><a
href="mailto:[email protected]";>Unsubscribe</a></td>
+ <td><a
href="mailto:[email protected]?subject=[daemon]";>Post</a></td>
+ <td><a
href="http://mail-archives.apache.org/mod_mbox/commons-dev/";>mail-archives.apache.org</a></td>
+ <td><a
href="http://markmail.org/list/org.apache.commons.dev/";>markmail.org</a><br />
+ <a
href="http://www.mail-archive.com/[email protected]/";>www.mail-archive.com</a><br
/>
+ <a
href="http://news.gmane.org/gmane.comp.jakarta.commons.devel";>news.gmane.org</a>
+ </td>
+ </tr>
+
+
+ <tr>
+ <td>
+ <strong>Commons Issues List</strong>
+ <br /><br />
+ Only for e-mails automatically generated by the <a
href="issue-tracking.html">issue tracking</a> system.
+ <br /><br />
+ </td>
+ <td><a
href="mailto:[email protected]";>Subscribe</a></td>
+ <td><a
href="mailto:[email protected]";>Unsubscribe</a></td>
+ <td><i>read only</i></td>
+ <td><a
href="http://mail-archives.apache.org/mod_mbox/commons-issues/";>mail-archives.apache.org</a></td>
+ <td><a
href="http://markmail.org/list/org.apache.commons.issues/";>markmail.org</a><br
/>
+ <a
href="http://www.mail-archive.com/[email protected]/";>www.mail-archive.com</a>
+ </td>
+ </tr>
+
+
+ <tr>
+ <td>
+ <strong>Commons Commits List</strong>
+ <br /><br />
+ Only for e-mails automatically generated by the <a
href="source-repository.html">source control</a> sytem.
+ <br /><br />
+ </td>
+ <td><a
href="mailto:[email protected]";>Subscribe</a></td>
+ <td><a
href="mailto:[email protected]";>Unsubscribe</a></td>
+ <td><i>read only</i></td>
+ <td><a
href="http://mail-archives.apache.org/mod_mbox/commons-commits/";>mail-archives.apache.org</a></td>
+ <td><a
href="http://markmail.org/list/org.apache.commons.commits/";>markmail.org</a><br
/>
+ <a
href="http://www.mail-archive.com/[email protected]/";>www.mail-archive.com</a>
+ </td>
+ </tr>
+
+ </table>
+
+ </section>
+ <section name="Apache Mailing Lists">
+ <p>
+ Other mailing lists which you may find useful include:
+ </p>
+
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Subscribe</th>
+ <th>Unsubscribe</th>
+ <th>Post</th>
+ <th>Archive</th>
+ <th>Other Archives</th>
+ </tr>
+ <tr>
+ <td>
+ <strong>Apache Announce List</strong>
+ <br /><br />
+ General announcements of Apache project releases.
+ <br /><br />
+ </td>
+ <td><a class="externalLink"
href="mailto:[email protected]";>Subscribe</a></td>
+ <td><a class="externalLink"
href="mailto:[email protected]";>Unsubscribe</a></td>
+ <td><i>read only</i></td>
+ <td><a class="externalLink"
href="http://mail-archives.apache.org/mod_mbox/announce/";>mail-archives.apache.org</a></td>
+ <td><a class="externalLink"
href="http://markmail.org/list/org.apache.announce/";>markmail.org</a><br />
+ <a class="externalLink"
href="http://old.nabble.com/Apache-News-and-Announce-f109.html";>old.nabble.com</a><br
/>
+ <a class="externalLink"
href="http://www.mail-archive.com/[email protected]/";>www.mail-archive.com</a><br
/>
+ <a class="externalLink"
href="http://news.gmane.org/gmane.comp.apache.announce";>news.gmane.org</a>
+ </td>
+ </tr>
+ </table>
+
+ </section>
+ </body>
+</document>
Propchange:
commons/proper/daemon/tags/COMMONS_DAEMON_1_0_3_RC3/src/site/xdoc/mail-lists.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added:
commons/proper/daemon/tags/COMMONS_DAEMON_1_0_3_RC3/src/site/xdoc/procrun.xml
URL:
http://svn.apache.org/viewvc/commons/proper/daemon/tags/COMMONS_DAEMON_1_0_3_RC3/src/site/xdoc/procrun.xml?rev=980662&view=auto
==============================================================================
---
commons/proper/daemon/tags/COMMONS_DAEMON_1_0_3_RC3/src/site/xdoc/procrun.xml
(added)
+++
commons/proper/daemon/tags/COMMONS_DAEMON_1_0_3_RC3/src/site/xdoc/procrun.xml
Fri Jul 30 06:50:12 2010
@@ -0,0 +1,562 @@
+<?xml version="1.0"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<document>
+ <properties>
+ <title>Daemon : Procrun</title>
+ <author email="[email protected]">Mladen Turk</author>
+ </properties>
+
+<body>
+<section name="Introduction">
+<p>
+ Procrun is a set of applications that allow Windows users to wrap
+ (mostly) Java applications (e.g. Tomcat) as a Windows service.
+ <br></br>
+ The service can be set to automatically start when the machine boots
+ and will continue to run with no user logged onto the machine.
+</p>
+</section>
+
+<section name="Procrun monitor application">
+<p>
+ <b>Prunmgr</b> is a GUI application for monitoring and configuring procrun
+ services.
+</p>
+<p>
+ Each command line directive is in the form of <b>//XX[//ServiceName]</b>
+</p>
+<p>
+ If the <code>//ServiceName</code> parameter is omitted, then the service
name is
+ assumed to be the name of the file.
+ <br/>
+ The Prunsrv application behaves in the same way,
+ so to allow both applications to reside in the same directory, the Prunmgr
application
+ will remove a trailing <b>w</b> (lower-case w) from the name.
+ <br/>
+ For example if the Prunmgr application is renamed as
<code>TestService.exe</code>
+ - or as <code>TestServicew.exe</code> -
+ then the default service name is <code>TestService</code>.
+</p>
+ <p>The available command line options are:</p>
+<p>
+ <table>
+ <tr><th>//ES</th>
+ <td>Edit service configuration</td>
+ <td>This is the default operation. It is called if the no option is
+ provided.
+ Starts the GUI application which allows the service configuration
+ to be modified, started and stopped.
+ </td>
+ </tr>
+ <tr><th>//MS</th>
+ <td>Monitor service</td>
+ <td>Starts the GUI application and minimizes it to the system tray.
+ </td>
+ </tr>
+ <tr><th>//MR</th>
+ <td>Monitor & run service</td>
+ <td>Starts the GUI application and minimizes it to the system tray.
+ Start the service if it is not currently running.
+ </td>
+ </tr>
+ <tr><th>//MQ</th>
+ <td>Monitor Quit</td>
+ <td>Stop any running monitor for the service.
+ </td>
+ </tr>
+ </table>
+</p>
+</section>
+
+<section name="Procrun service application">
+<p>
+ <b>Prunsrv</b> is a service application for running applications as
services.
+ It can convert any application (not just Java applications) to run as a
service.
+</p>
+
+<subsection name="Command line arguments">
+<p>
+ Each command line directive is in the form of <b>//XX[//ServiceName]</b>
+</p>
+<p>
+ If the <code>//ServiceName</code> parameter is omitted, then the service
name is
+ assumed to be the name of the file.
+ <br/>
+ For example if the application is renamed as <code>TestService.exe</code>,
+ then the default service name is <code>TestService</code>.
+</p>
+ <p>The available command line options are:</p>
+<p>
+ <table>
+ <tr><th>//TS</th>
+ <td>Run the service as a console application</td>
+ <td>This is the default operation. It is called if the no option is
provided.
+ </td>
+ </tr>
+ <tr><th>//RS</th>
+ <td>Run the service</td>
+ <td>Called only from ServiceManager</td>
+ </tr>
+ <tr><th>//SS</th>
+ <td>Stop the service</td>
+ <td></td>
+ </tr>
+ <tr><th>//US</th>
+ <td>Update service parameters</td>
+ <td></td>
+ </tr>
+ <tr><th>//IS</th>
+ <td>Install service</td>
+ <td></td>
+ </tr>
+ <tr><th>//DS</th>
+ <td>Delete service</td>
+ <td>Stops the service first if it is currently running</td>
+ </tr>
+ <tr><th>//PP[//seconds]</th>
+ <td>Pause</td>
+ <td>Default is 60 seconds</td>
+ </tr>
+ <tr><th>//VS</th>
+ <td>Version</td>
+ <td>Print version and exit (since version 1.0.3)</td>
+ </tr>
+ <tr><th>//?</th>
+ <td>Help</td>
+ <td>Print usage and exit (since version 1.0.3)</td>
+ </tr>
+ </table>
+</p>
+</subsection>
+<subsection name="Command line parameters">
+<p>
+ Each command parameter is prefixed with <b>--</b>.
+ If an environment variable exists with the same name as command line
parameter but
+ prefixed with <code>PR_</code> it will take precedence.
+ For example:
+<source>set PR_CLASSPATH=xx.jar</source>
+</p>
+<p>is equivalent to providing
+<source>--Classpath=xx.jar</source>
+</p>
+<p> as a command line parameter.</p>
+<p>
+If a parameter is repeated, then normally the last value takes precedence.
+However some parameters can take multiple values - for example StartParams and
JvmOption.
+If these parameters are prefixed with <b>++</b>, then the value will be
appended to the existing value.
+For example:
+<source>
+--Startup=manual --Startup=auto --JvmOption=-Done=1 ++JvmOption=-Dtwo=2
+</source>
+will result in the following values being used:
+<source>
+Startup:
+auto
+
+JvmOption:
+-Done=1
+-Dtwo=2
+</source>
+<br/>
+Only multi-valued parameters support this; they are indicated in the table
below by <b><code>++</code></b>.
+<br></br>
+If <b><code>++</code></b> is used for a parameter that does not support
multiple values,
+then it is treated the same as <b>--</b>. No error is reported.
+</p>
+<p>
+ <table>
+ <tr>
+ <th>ParameterName</th>
+ <th>Default</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>--Description</td>
+ <td></td>
+ <td>Service name description (maximum 1024 characters)</td>
+ </tr>
+ <tr>
+ <td>--DisplayName</td>
+ <td>ServiceName</td>
+ <td>Service display name</td>
+ </tr>
+ <tr>
+ <td>--Install</td>
+ <td>procrun.exe //RS//ServiceName</td>
+ <td>Install image</td>
+ </tr>
+ <tr>
+ <td>--Startup</td>
+ <td>manual</td>
+ <td>Service startup mode can be either <b>auto</b> or <b>manual</b></td>
+ </tr>
+ <tr>
+ <td>--Type</td>
+ <td></td>
+ <td>Service type can be <b>interactive</b> to allow the service to
interact with the desktop.
+ Use this option only with Local system accounts.</td>
+ </tr>
+ <tr>
+ <td>++DependsOn</td>
+ <td></td>
+ <td>List of services that this service depends on. Dependent services
+ are separated using either <b>#</b> or <b>;</b> characters</td>
+ </tr>
+ <tr>
+ <td>++Environment</td>
+ <td></td>
+ <td>List of environment variables that will be provided to the service
+ in the form <b>key=value</b>. They are separated using either
+ <b>#</b> or <b>;</b> characters</td>
+ </tr>
+ <tr>
+ <td>--User</td>
+ <td></td>
+ <td>User account used for running executable. It is used only for
+ StartMode <b>Java</b> or <b>exe</b> and enables running applications
+ as a service under an account without the LogonAsService
privilege.</td>
+ </tr>
+ <tr>
+ <td>--Password</td>
+ <td></td>
+ <td>Password for user account set by --User parameter</td>
+ </tr>
+ <tr>
+ <td>--ServiceUser</td>
+ <td></td>
+ <td>Specifies the name of the account under which the service should run.
+ Use an account name in the form <i>DomainName\UserName</i>.
+ The service process will be logged on as this user.
+ if the account belongs to the built-in domain, you can specify
<i>.\UserName</i>
+ </td>
+ </tr>
+ <tr>
+ <td>--ServicePassword</td>
+ <td></td>
+ <td>Password for user account set by --ServiceUser parameter</td>
+ </tr>
+ <tr>
+ <td>--JavaHome</td>
+ <td>JAVA_HOME</td>
+ <td>Set a different JAVA_HOME than defined by JAVA_HOME environment
+ variable</td>
+ </tr>
+ <tr>
+ <td>--Jvm</td>
+ <td>auto</td>
+ <td>Use either <b>auto</b> or specify the full path to the <b>jvm.dll</b>.
+ You can use environment variable expansion here.</td>
+ </tr>
+ <tr>
+ <td>++JvmOptions</td>
+ <td>-Xrs</td>
+ <td>List of options in the form of <b>-D</b> or <b>-X</b> that will be
+ passed to the JVM. The options are separated using either
+ <b>#</b> or <b>;</b> characters. if you need to embed either # or ;
+ character put them inside single quotes. (Not used in <b>exe</b>
mode.)</td>
+ </tr>
+ <tr>
+ <td>--Classpath</td>
+ <td></td>
+ <td>Set the Java classpath. (Not used in <b>exe</b> mode.)</td>
+ </tr>
+ <tr>
+ <td>--JvmMs</td>
+ <td></td>
+ <td>Initial memory pool size in MB. (Not used in <b>exe</b> mode.)</td>
+ </tr>
+ <tr>
+ <td>--JvmMx</td>
+ <td></td>
+ <td>Maximum memory pool size in MB. (Not used in <b>exe</b> mode.)</td>
+ </tr>
+ <tr>
+ <td>--JvmSs</td>
+ <td></td>
+ <td>Thread stack size in KB. (Not used in <b>exe</b> mode.)</td>
+ </tr>
+ <tr>
+ <td>--StartMode</td>
+ <td></td>
+ <td>One of <b>jvm</b>, <b>Java</b> or <b>exe</b>.
+ The modes are:
+ <ul>
+ <li>jvm - start Java in-process. Depends on jvm.dll, see <b>--Jvm</b>.</li>
+ <li>Java - same as exe, but automatically uses the default Java
executable</li>
+ <li>exe - run the image as a separate process</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <tr>
+ <td>--StartImage</td>
+ <td></td>
+ <td>Executable that will be run. Only applies to <b>exe</b> mode.</td>
+ </tr>
+ <tr>
+ <td>--StartPath</td>
+ <td></td>
+ <td>Working path for the start image executable. Does not apply to
<b>jvm</b> mode.</td>
+ </tr>
+ <tr>
+ <td>--StartClass</td>
+ <td></td>
+ <td>Class that contains the startup method.
+ Applies to the <b>jvm</b> and <b>Java</b> modes. (Not used in <b>exe</b>
mode.)
+ </td>
+ </tr>
+ <tr>
+ <td>--StartMethod</td>
+ <td>main</td>
+ <td>Name of method to be called when service is started.
+ It must be <code>static void</code> and have argument <code>(String
args[])</code>.
+ Only applies to <b>jvm</b> mode - in <b>Java</b> mode, the <b>main</b>
method is always used.
+ <br />
+ <b>Note:</b> in <code>jvm</code> mode, the start method should not return
until the stop method
+ has been called.
+ </td>
+ </tr>
+ <tr>
+ <td>++StartParams</td>
+ <td></td>
+ <td>List of parameters that will be passed to either StartImage or
+ StartClass. Parameters are separated using either <b>#</b> or
+ <b>;</b> character.</td>
+ </tr>
+ <tr>
+ <td>--StopMode</td>
+ <td></td>
+ <td>One of <b>jvm</b>, <b>Java</b> or <b>exe</b>.
+ See <b>--StartMode</b> for further details.
+ </td>
+ </tr>
+ <td>--StopImage</td>
+ <td></td>
+ <td>Executable that will be run on Stop service signal. Only applies to
<b>exe</b> mode.</td>
+ </tr>
+ <tr>
+ <td>--StopPath</td>
+ <td></td>
+ <td>Working path for the stop image executable. Does not apply to
<b>jvm</b> mode.</td>
+ </tr>
+ <tr>
+ <td>--StopClass</td>
+ <td></td>
+ <td>Class that will be used on Stop service signal.
+ Applies to the <b>jvm</b> and <b>Java</b> modes.
+ </td>
+ </tr>
+ <tr>
+ <td>--StopMethod</td>
+ <td>main</td>
+ <td>Name of method to be called when service is stopped.
+ It must be <code>static void</code> and have argument <code>(String
args[])</code>.
+ Only applies to <b>jvm</b> mode.
+ In <b>Java</b> mode, the <b>main</b> method is always used.
+ </td>
+ </tr>
+ <tr>
+ <td>++StopParams</td>
+ <td></td>
+ <td>List of parameters that will be passed to either StopImage or
+ StopClass. Parameters are separated using either <b>#</b> or
+ <b>;</b> character.</td>
+ </tr>
+ <tr>
+ <td>--StopTimeout</td>
+ <td>No Timeout</td>
+ <td>Defines the timeout in seconds that procrun waits for service to
+ exit gracefully.</td>
+ </tr>
+ <tr>
+ <td>--LogPath</td>
+ <td>%SystemRoot%\System32\LogFiles\Apache</td>
+ <td>Defines the path for logging. Creates the directory if necessary.</td>
+ </tr>
+ <tr>
+ <td>--LogPrefix</td>
+ <td>commons-daemon</td>
+ <td>Defines the service log filename prefix. The log file is created in
the LogPath directory with
+ <code>.YEAR-MONTH-DAY.log</code> suffix</td>
+ </tr>
+ <tr>
+ <td>--LogLevel</td>
+ <td>Info</td>
+ <td>Defines the logging level and can be either <b>Error</b>,
+ <b>Info</b>, <b>Warn</b> or <b>Debug</b></td>. (Case insensitive).
+ </tr>
+ <tr>
+ <td>--LogJniMessages</td>
+ <td>0</td>
+ <td>Set this non-zero (e.g. 1) to capture JVM jni debug messages in the
procrun log file.
+ Is not needed if stdout/stderr redirection is being used.
+ <!-- TODO: what if only one of stdout/stderr is being redirected? -->
+ Only applies to <b>jvm</b> mode.
+ </td>
+ </tr>
+ <tr>
+ <td>--StdOutput</td>
+ <td></td>
+ <td>Redirected stdout filename. If named <b>auto</b> file is created
+ inside <b>LogPath</b> with the name
<b>service-stdout.YEAR-MONTH-DAY.log</b>.</td>
+ </tr>
+ <tr>
+ <td>--StdError</td>
+ <td></td>
+ <td>Redirected stderr filename. If named <b>auto</b> file is created
+ in the <b>LogPath</b> directory with the name
<b>service-stderr.YEAR-MONTH-DAY.log</b>.</td>
+ </tr>
+ <tr>
+ <td>--PidFile</td>
+ <td></td>
+ <td>Defines the file name for storing the running process id.
+ Actual file is created in the <b>LogPath</b> directory</td>
+ </tr>
+ </table>
+</p>
+</subsection>
+<subsection name="Installing services">
+<p>
+To install the service, you need to use the <b>//IS</b> parameter.
+</p>
+<p>
+<screen>
+<h4>Install the service named 'TestService'</h4>
+<source>
+prunsrv //IS//TestService --DisplayName="Test Service" \
+ --Install=prunsrv.exe --Jvm=auto --StartMode=jvm --StopMode=jvm \
+ --StartClass=org.apache.SomeStartClass --StartParams=arg1;arg2;arg3 \
+ --StopClass=org.apache.SomeStopClass --StopParams=arg1#arg2
+</source>
+</screen>
+</p>
+</subsection>
+<subsection name="Updating services">
+<p>
+To update the service parameters, you need to use the <b>//US</b> parameter.
+</p>
+<p>
+<screen>
+<h4>Update the service named 'TestService'</h4>
+<source>
+prunsrv //US//TestService --Description="Some Dummy Test Service" \
+ --Startup=auto --Classpath=%CLASSPATH%;test.jar
+</source>
+</screen>
+</p>
+</subsection>
+<subsection name="Removing services">
+<p>
+To remove the service, you need to use the <b>//DS</b> parameter.
+If the service is running it will be stopped and then deleted.
+</p>
+<p>
+<screen>
+<h4>Remove the service named 'TestService'</h4>
+<source>prunsrv //DS//TestService</source>
+</screen>
+</p>
+</subsection>
+
+<subsection name="Debugging services">
+<p>
+To run the service in console mode, you need to use the <b>//TS</b> parameter.
+The service shutdown can be initiated by pressing <b>CTRL+C</b> or
+<b>CTRL+BREAK</b>.
+If you rename the prunsrv.exe to testservice.exe then you can just execute the
+testservice.exe and this command mode will be executed by default.
+</p>
+<p>
+<screen>
+<h4>Run the service named 'TestService' in console mode</h4>
+<source>prunsrv //TS//TestService [additional arguments]</source>
+</screen>
+</p>
+</subsection>
+
+</section>
+
+<section name="Using Procrun in jvm mode">
+<p>
+To interface with the Procrun service application (prunsrv) using the
<b>jvm</b> mode,
+you need to create a class with the appropriate method(s).
+For example:
+<source>
+class MyClass;
+// N.B. error handling not shown
+static void main(String [] args){
+ String mode = args[0];
+ if ("start".equals(mode){
+ // process service start function
+ }
+ etc.
+}
+</source>
+This should be configured as follows:
+<source>
+--Classpath MyClass.jar
+--StartMode jvm --StartClass MyClass --StartParams start
+--StopMode jvm --StopClass MyClass --StopParams stop
+</source>
+The above example uses a single 'main' method, and uses a string parameter to
specify whether the service function
+is start or stop.
+<br></br>
+Alternatively, you can use different method names for the service start and
stop functions:
+<source>
+class MyClass;
+// N.B. error handling not shown
+static void start(String [] args){
+ // process service start function
+ }
+static void stop(String [] args){
+ // process service stop function
+ }
+}
+</source>
+This should be configured as follows:
+<source>
+--Classpath MyClass.jar
+--StartMode jvm --StartClass MyClass --StartMethod start
+--StopMode jvm --StopClass MyClass --StopMethod stop
+</source>
+Note that the method handling service start should create and start a separate
thread
+to carry out the processing, and then return.
+The start and stop methods are called from different threads.
+</p>
+</section>
+
+<section name="Using Procrun in Java or exe mode">
+<p>
+When using the <b>Java</b> or <b>exe</b> modes, the Procrun service
application (prunsrv)
+launches the target application in a separate process.
+The "stop" application needs to communicate somehow with the "start"
application to tell it to stop.
+For example, using RPC.
+</p>
+</section>
+
+<section name="Windows Registry Usage">
+<p>
+The basic Service definitions are maintained under the registry key:
+<source>HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\<ServiceName></source>
+Additional parameters are stored in the registry at:
+<source>HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\ProcRun
2.0\<ServiceName>\Parameters</source>
+</p>
+</section>
+</body>
+</document>
Propchange:
commons/proper/daemon/tags/COMMONS_DAEMON_1_0_3_RC3/src/site/xdoc/procrun.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added:
commons/proper/daemon/tags/COMMONS_DAEMON_1_0_3_RC3/src/test/org/apache/commons/daemon/SimpleDaemon.java
URL:
http://svn.apache.org/viewvc/commons/proper/daemon/tags/COMMONS_DAEMON_1_0_3_RC3/src/test/org/apache/commons/daemon/SimpleDaemon.java?rev=980662&view=auto
==============================================================================
---
commons/proper/daemon/tags/COMMONS_DAEMON_1_0_3_RC3/src/test/org/apache/commons/daemon/SimpleDaemon.java
(added)
+++
commons/proper/daemon/tags/COMMONS_DAEMON_1_0_3_RC3/src/test/org/apache/commons/daemon/SimpleDaemon.java
Fri Jul 30 06:50:12 2010
@@ -0,0 +1,304 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/* @version $Id: SimpleDaemon.java 914997 2010-02-22 18:08:51Z sebb $ */
+
+package org.apache.commons.daemon;
+
+import java.io.*;
+import java.net.*;
+import java.text.SimpleDateFormat;
+import java.util.Date;
+import java.util.Enumeration;
+import java.util.Vector;
+import org.apache.commons.daemon.Daemon;
+import org.apache.commons.daemon.DaemonController;
+import org.apache.commons.daemon.DaemonContext;
+
+public class SimpleDaemon implements Daemon, Runnable {
+
+ private ServerSocket server=null;
+ private Thread thread=null;
+ private DaemonController controller=null;
+ private volatile boolean stopping=false;
+ private String directory=null;
+ private Vector handlers=null;
+
+ public SimpleDaemon() {
+ super();
+ System.err.println("SimpleDaemon: instance "+this.hashCode()+
+ " created");
+ this.handlers=new Vector();
+ }
+
+ protected void finalize() {
+ System.err.println("SimpleDaemon: instance "+this.hashCode()+
+ " garbage collected");
+ }
+
+ /**
+ * init and destroy were added in jakarta-tomcat-daemon.
+ */
+ public void init(DaemonContext context)
+ throws Exception {
+ System.err.println("SimpleDaemon: instance "+this.hashCode()+
+ " init");
+
+ int port=1200;
+
+ String[] a = context.getArguments();
+
+ if (a.length>0) port=Integer.parseInt(a[0]);
+ if (a.length>1) this.directory=a[1];
+ else this.directory="/tmp";
+
+ /* Dump a message */
+ System.err.println("SimpleDaemon: loading on port "+port);
+
+ /* Set up this simple daemon */
+ this.controller=context.getController();
+ this.server=new ServerSocket(port);
+ this.thread=new Thread(this);
+ }
+
+ public void start() {
+ /* Dump a message */
+ System.err.println("SimpleDaemon: starting");
+
+ /* Start */
+ this.thread.start();
+ }
+
+ public void stop()
+ throws IOException, InterruptedException {
+ /* Dump a message */
+ System.err.println("SimpleDaemon: stopping");
+
+ /* Close the ServerSocket. This will make our thread to terminate */
+ this.stopping=true;
+ this.server.close();
+
+ /* Wait for the main thread to exit and dump a message */
+ this.thread.join(5000);
+ System.err.println("SimpleDaemon: stopped");
+ }
+
+ public void destroy() {
+ System.err.println("SimpleDaemon: instance "+this.hashCode()+
+ " destroy");
+ }
+
+ public void run() {
+ int number=0;
+
+ System.err.println("SimpleDaemon: started acceptor loop");
+ try {
+ while(!this.stopping) {
+ Socket socket=this.server.accept();
+ Handler handler=new Handler(socket,this,this.controller);
+ handler.setConnectionNumber(number++);
+ handler.setDirectoryName(this.directory);
+ new Thread(handler).start();
+ }
+ } catch (IOException e) {
+ /* Don't dump any error message if we are stopping. A IOException
+ is generated when the ServerSocket is closed in stop() */
+ if (!this.stopping) e.printStackTrace(System.err);
+ }
+
+ /* Terminate all handlers that at this point are still open */
+ Enumeration openhandlers=this.handlers.elements();
+ while (openhandlers.hasMoreElements()) {
+ Handler handler=(Handler)openhandlers.nextElement();
+ System.err.println("SimpleDaemon: dropping connection "+
+ handler.getConnectionNumber());
+ handler.close();
+ }
+
+ System.err.println("SimpleDaemon: exiting acceptor loop");
+ }
+
+ protected void addHandler(Handler handler) {
+ synchronized (handler) {
+ this.handlers.add(handler);
+ }
+ }
+
+ protected void removeHandler(Handler handler) {
+ synchronized (handler) {
+ this.handlers.remove(handler);
+ }
+ }
+
+ public static class Handler implements Runnable {
+
+ private DaemonController controller=null;
+ private SimpleDaemon parent=null;
+ private String directory=null;
+ private Socket socket=null;
+ private int number=0;
+
+ public Handler(Socket s, SimpleDaemon p, DaemonController c) {
+ super();
+ this.socket=s;
+ this.parent=p;
+ this.controller=c;
+ }
+
+ public void run() {
+ this.parent.addHandler(this);
+ System.err.println("SimpleDaemon: connection "+this.number+
+ " opened from "+this.socket.getInetAddress());
+ try {
+ InputStream in=this.socket.getInputStream();
+ OutputStream out=this.socket.getOutputStream();
+ handle(in,out);
+ this.socket.close();
+ } catch (IOException e) {
+ e.printStackTrace(System.err);
+ }
+ System.err.println("SimpleDaemon: connection "+this.number+
+ " closed");
+ this.parent.removeHandler(this);
+ }
+
+ public void close() {
+ try {
+ this.socket.close();
+ } catch (IOException e) {
+ e.printStackTrace(System.err);
+ }
+ }
+
+ public void setConnectionNumber(int number) {
+ this.number=number;
+ }
+
+ public int getConnectionNumber() {
+ return(this.number);
+ }
+
+ public void setDirectoryName(String directory) {
+ this.directory=directory;
+ }
+
+ public String getDirectoryName() {
+ return(this.directory);
+ }
+
+ public void log(String name)
+ throws IOException {
+ OutputStream file=new FileOutputStream(name,true);
+ PrintStream out=new PrintStream(file);
+ SimpleDateFormat fmt=new SimpleDateFormat();
+
+ out.println(fmt.format(new Date()));
+ out.close();
+ file.close();
+ }
+
+ public void handle(InputStream in, OutputStream os) {
+ PrintStream out=new PrintStream(os);
+
+ while(true) {
+ try {
+ /* If we don't have data in the System InputStream, we want
+ to ask to the user for an option. */
+ if (in.available()==0) {
+ out.println();
+ out.println("Please select one of the following:");
+ out.println(" 1) Shutdown");
+ out.println(" 2) Reload");
+ out.println(" 3) Create a file");
+ out.println(" 4) Disconnect");
+ out.print("Your choiche: ");
+ }
+
+ /* Read an option from the client */
+ int x=in.read();
+
+ switch (x) {
+ /* If the socket was closed, we simply return */
+ case -1:
+ return;
+
+ /* Attempt to shutdown */
+ case '1':
+ out.println("Attempting a shutdown...");
+ try {
+ this.controller.shutdown();
+ } catch (IllegalStateException e) {
+ out.println();
+ out.println("Can't shutdown now");
+ e.printStackTrace(out);
+ }
+ break;
+
+ /* Attempt to reload */
+ case '2':
+ out.println("Attempting a reload...");
+ try {
+ this.controller.reload();
+ } catch (IllegalStateException e) {
+ out.println();
+ out.println("Can't reload now");
+ e.printStackTrace(out);
+ }
+ break;
+
+ /* Disconnect */
+ case '3':
+ String name=this.getDirectoryName()+
+ "/SimpleDaemon."+
+ this.getConnectionNumber()+
+ ".tmp";
+ try {
+ this.log(name);
+ out.println("File '"+name+"' created");
+ } catch (IOException e) {
+ e.printStackTrace(out);
+ }
+ break;
+
+ /* Disconnect */
+ case '4':
+ out.println("Disconnecting...");
+ return;
+
+ /* Discard any carriage return / newline characters */
+ case '\r':
+ case '\n':
+ break;
+
+ /* We got something that we weren't supposed to get */
+ default:
+ out.println("Unknown option '"+(char)x+"'");
+ break;
+
+ }
+
+ /* If we get an IOException we return (disconnect) */
+ } catch (IOException e) {
+ System.err.println("SimpleDaemon: IOException in "+
+ "connection "+
+ this.getConnectionNumber());
+ return;
+ }
+ }
+ }
+ }
+}
Propchange:
commons/proper/daemon/tags/COMMONS_DAEMON_1_0_3_RC3/src/test/org/apache/commons/daemon/SimpleDaemon.java
------------------------------------------------------------------------------
svn:eol-style = native
