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="jfrederic.cl...@fujitsu-siemens.con">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="d...@commons.apache.org">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:user-subscr...@commons.apache.org">Subscribe</a></td> + <td><a href="mailto:user-unsubscr...@commons.apache.org">Unsubscribe</a></td> + <td><a href="mailto:u...@commons.apache.org?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/u...@commons.apache.org/">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:dev-subscr...@commons.apache.org">Subscribe</a></td> + <td><a href="mailto:dev-unsubscr...@commons.apache.org">Unsubscribe</a></td> + <td><a href="mailto:d...@commons.apache.org?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/d...@commons.apache.org/">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:issues-subscr...@commons.apache.org">Subscribe</a></td> + <td><a href="mailto:issues-unsubscr...@commons.apache.org">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/iss...@commons.apache.org/">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:commits-subscr...@commons.apache.org">Subscribe</a></td> + <td><a href="mailto:commits-unsubscr...@commons.apache.org">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/commits@commons.apache.org/">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:announce-subscr...@apache.org">Subscribe</a></td> + <td><a class="externalLink" href="mailto:announce-unsubscr...@apache.org">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/annou...@apache.org/">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="mt...@apache.org">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