[PATCH] windows.html

[Ben Hyde <bh...@gensym.com>]

This superceeds the pervious patch and attempts 
responds to the input received to date.

Brian wrote: "Good start"
Paul wrote: "Not to put a downer on this good work, but..."

Thank you, who says writting doc is a thankless task!

Brian writes:
>Good start, I've committed what you sent, but what's all this @@whatever?@@
>about?

Oh - that shouldn't have gone in, the patch below removes that and
attempts to fold in Paul's input.

Later Brian writes:
>Looks good... there's a typo ("Apache on Windows NT", not "Window's
>Apache"), but other than that I'd commit it, though it seems like you'll be
>working on windows.html some more.  Should I commit this now or wait for
>more edits and commit in bulk?

I have to stop working on this.
  "End of the quarter time to herd the lemmings over the cliff."

I don't see the typo mentioned, hope it's not there.

Paul writes:
> Not to put a downer on this good work, but the -Z and signalling stuff
> isn't in Apache.

Thanks for clarifying the situtation. I've updated the doc
to reflect that situation, if it doesn't get fixed in the
next rev then the doc will need another edit instead.

From: "David D'Antonio" <dd...@newsedge.com>
> net start (or stop) Apache

I've not tried this yet.  Currently -i switch is a bit of a tease
since you have to have had the InstallShield mechinism put the
entry in the registry first.  I dream of a wrapper around the
install install.c functionality so it can invoke it from the
command line.

Dale Couch wrote about "net start (or stop) Apache"
> Not to contradict, at least for me as a Windows User, this does not work.

That may be since your account lacks the rights for such heady
operations.  I'm having a hell of time figuring out exactly what
rights the user needs for each part of the lifecycle: install,
boot, service start/stop, etc.

Dale Couch continues
>It appears that when Apache starts it warms up, and then spans 1 new child.
>The parent then exits.

Running -s I see two processes.  Killing the one recorded in PIDFile works,
as long as I've the rights to do so.

...
Oh my!  The lemmings are breeding, got a go.  - ben hyde

---
> cvs -q diff -u
Index: windows.html
===================================================================
RCS file: /cvs/apache-1.3/htdocs/manual/windows.html,v
retrieving revision 1.17
diff -u -r1.17 windows.html
--- windows.html	1998/06/16 02:40:32	1.17
+++ windows.html	1998/06/17 13:48:07
@@ -49,6 +49,7 @@
   <LI><A HREF="#cmdline">Running Apache for Windows from the Command Line</A>
   <LI><A HREF="#signal">Signalling Apache when running</A>
   <LI><A HREF="#comp">Compiling Apache for Windows</A>
+  <LI><A HREF="#user">The User Running Apache for Windows</a>
 </UL>
 
 <HR>
@@ -367,27 +368,28 @@
 configuration files as follows:
 
 <PRE>
-    apache -Z @@whatever?@@>
+    apache -Z restart
 </PRE>
 
-and to request that it shutdown gracefully, via:
+or request that it shutdown gracefully, via:
 
 <PRE>
-    apache -Z @@whatever?@@>
+    apache -Z shutdown
 </PRE>
 
-and you can force it to stop via:
+The -Z switch is available only on Windows.  These two signals
+(<code>restart</code>, <code>shutdown</code>) do not work in release 1.3.0 of
+Apache.
 
-<PRE>
-    apache -Z @@whatever?@@
-</PRE>
+As a last resort you can force it to stop by killing the process
+who's process id found in the server's 
+<A href="mod/core.html#pidfile">PidFile</A>.
 
-
-<P>
-Other techinques of shutting down the server (e.g. using the
-task manager to "End Process", distroying the command 
-window containing the server, or using control-C to interupt
-it) all have the downside of @@whatever@@.
+<p>
+Apache starts two processes under Windows, a parent and one
+child.  The child services requests and the parent exists
+only to create a new child if the child terminates.  This
+makes the server more resilient.
 
 <H2><A NAME="comp">Compiling Apache for Windows</A></H2>
 
@@ -462,6 +464,43 @@
 actual server root (for example "C:\apache").  Copy over
 the conf/magic and conf/mime.types files as well.
 
+<H2><A NAME="user">The User Running Apache for Windows</a></H2>
+
+<P>
+Generally it is best to arrange to have Apache run as a user
+with as few "rights" or privileges as possible.  That can help
+limit damage caused by a security breach.
+
+<P>
+
+If you are running Apache as a service then by default it will run as the unique
+user known as <CODE>SystemLocal</Code>, otherwise it will run as the user in
+force when you invoked it.
+
+<P>
+
+<CODE>SystemLocal</code> is uniquely powerful on the local machine, but it has
+absolutely no access to the Microsoft networking, for example it can not usually
+access UNC files beyond the local machine.  Both because it is weak, and because
+it is powerful make it a poor choice for the user running a Web Server.  You can
+change the user that any service runs as in the Services Control Panel, if you
+have the "rights" to do so.
+
+<P>
+
+Avoiding dependencies on resources outside the local machine is also a good
+idea.  Currently Window's Apache can not serve files outside the local machine
+(i.e. those whose canonical UNC names are of the form
+//SharedMachine/dir/dir2/file.ext).  A local user is preferable since the
+service manager will have to check with your site's for configuration server when
+starting up and that in turn can cause startup to hang.
+
+<P> 
+
+Obviously the user you run Apache under must have read access to the
+configuration files, write access to the logs, read access to the content being
+served, execute access to any CGI facilities, read/write access to any cache
+files, etc.
 <!--#include virtual="footer.html" -->
 </BODY>
 </HTML>
Index: mod/core.html
===================================================================
RCS file: /cvs/apache-1.3/htdocs/manual/mod/core.html,v
retrieving revision 1.125
diff -u -r1.125 core.html
--- core.html	1998/06/16 03:37:15	1.125
+++ core.html	1998/06/17 13:48:08
@@ -2857,6 +2857,10 @@
 <DD>Refers to a user by their number.
 </DL>
 
+This directive has no effect on Windows
+(see "The <A href=../windows.html#user">User</a>
+Running Apache for Windows" section in the "Using Apache with Microsoft Windows").<P>
+
 The user should have no privileges which result in it being able to access
 files which are not intended to be visible to the outside world, and
 similarly, the user should not be able to execute code which is not