Move 'docs' to 'man'. In Python projects, 'docs' typically are for Sphinx docs.

1 files changed, 263 insertions, 0 deletions

diff --git a/man/cherryd.1 b/man/cherryd.1
new file mode 100644
index 00000000..cf27a360
--- /dev/null
+++ b/man/cherryd.1
@@ -0,0 +1,263 @@
+.\" Man page generated from reStructuredText.
+.TH cherryd 1 "2009-06-15" "3.2.0" "web"
+.SH NAME
+cherryd \- Starts the CherryPy HTTP server as a daemon
+
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level magin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+
+.SH SYNOPSIS
+\fBcherryd\fP [\-d] [\-f | \-s] [\-e ENV_NAME] [\-p PIDFILE_PATH] [\-P DIRPATH] [\-c CONFIG_FILE] \-i MODULE_NAME
+
+
+.SH DESCRIPTION
+\fBcherryd\fP is a Python script which starts the CherryPy webserver as a daemon.
+
+
+.SH OPTIONS
+.INDENT 0.0
+
+.TP
+.BI \-c\  CONFIG_FILE ,\ \-\-config\fn= CONFIG_FILE
+Specifies a config file which is to be read and merged into the
+CherryPy site\-wide config dict.  This option may be specified
+multiple times.  For each CONFIG_FILE specified, \fBcherryd\fP will perform
+\fBcherrypy.config.update()\fP.
+
+
+.TP
+.B \-d
+Run the server as a daemon.
+
+
+.TP
+.BI \-e\  ENV_NAME ,\ \-\-environment\fn= ENV_NAME
+Specifies the name of an environment to be applied.  An environment is a
+canned set of configuration entries.  See \fI\%ENVIRONMENTS\fP below for a
+list of the built\-in environments.
+
+
+.TP
+.B \-f
+Start a fastcgi server instead of the default HTTP server.
+
+
+.TP
+.B \-s
+Start a scgi server instead of the default HTTP server.
+
+
+.TP
+.BI \-i\  MODULE_NAME ,\ \-\-import\fn= MODULE_NAME
+Specifies a module to import.  This option may be specified multiple times.
+For each MODULE_NAME specified, \fBcherryd\fP will import the module.  This
+is how you tell \fBcherryd\fP to run your application\'s startup code.
+For all practical purposes, \fB\-i\fP is not optional; you will always need to
+specify at least one module.
+
+
+.TP
+.BI \-p\  PIDFILE_PATH ,\ \-\-pidfile\fn= PIDFILE_PATH
+Store the process id in PIDFILE_PATH.
+
+
+.TP
+.BI \-P\  DIRPATH ,\ \-\-Path\  DIRPATH
+Specifies a directory to be inserted at the head of \fBsys.path\fP.  DIRPATH
+should be an absolute path.  This option may be specified multiple times.
+\fBcherryd\fP inserts all the specified DIRPATHs into \fBsys.path\fP before it
+attempts to import modules specified with \fB\-i\fP.
+
+.UNINDENT
+For a terse summary of the options, run \fBcherryd \-\-help\fP.
+
+
+.SH EXAMPLES
+A site\-wide configuration file \fBsite.conf\fP:
+
+.INDENT 0.0
+.INDENT 3.5
+
+[global]
+.br
+server.socket_host = "0.0.0.0"
+.br
+server.socket_port = 8008
+.br
+engine.autoreload_on = False
+.br
+
+.UNINDENT
+.UNINDENT
+The application startup code in \fBstartup.py\fP:
+
+.INDENT 0.0
+.INDENT 3.5
+
+import cherrypy
+.br
+import my_controller
+.br
+cherrypy.log.error_file = \'/var/tmp/myapp\-error.log\'
+.br
+cherrypy.log.access_file = \'/var/tmp/myapp\-access.log\'
+.br
+config_root = { \'tools.encode.encoding\' : \'utf\-8\', }
+.br
+app_conf = { \'/\' : config_root }
+.br
+cherrypy.tree.mount(my_controller.Root(), script_name=\'\', config=app_conf)
+.br
+
+.UNINDENT
+.UNINDENT
+A corresponding \fBcherryd\fP command line:
+
+.INDENT 0.0
+.INDENT 3.5
+
+cherryd \-d \-c site.conf \-i startup \-p /var/log/cherrypy/my_app.pid
+.br
+
+.UNINDENT
+.UNINDENT
+
+.SH DROPPING PRIVILEGES
+If you want to serve your web application on TCP port 80 (or any port lower than
+1024), the CherryPy HTTP server needs to start as root in order to bind to the
+port.  Running a web application as root is reckless, so the application should
+drop privileges from root to some other user and group.  The application must do
+this itself, as \fBcherryd\fP does not do it for you.
+
+To drop privileges, put the following lines into your startup code,
+substituting appropriate values for \fBumask\fP, \fBuid\fP and \fBgid\fP:
+
+.INDENT 0.0
+.INDENT 3.5
+
+from cherrypy.process.plugins import DropPrivileges
+.br
+DropPrivileges(cherrypy.engine, umask=022, uid=\'nobody\', gid=\'nogroup\').subscribe()
+.br
+
+.UNINDENT
+.UNINDENT
+Note that the values for \fBuid\fP and \fBgid\fP may be either user and group
+names, or uid and gid integers.
+
+Note that you must disable the engine Autoreload plugin, because the way
+Autoreload works is by \fBexec()\fPing a new instance of the running process,
+replacing the current instance.  Since root privileges are already dropped, the
+new process instance will fail when it tries to perform a privileged operation
+such as binding to a low\-numbered TCP port.
+
+
+.SH ENVIRONMENTS
+These are the built\-in environment configurations:
+
+
+.SS staging
+.INDENT 0.0
+.INDENT 3.5
+
+\'engine.autoreload_on\': False,
+.br
+\'checker.on\': False,
+.br
+\'tools.log_headers.on\': False,
+.br
+\'request.show_tracebacks\': False,
+.br
+\'request.show_mismatched_params\': False,
+.br
+
+.UNINDENT
+.UNINDENT
+
+.SS production
+.INDENT 0.0
+.INDENT 3.5
+
+\'engine.autoreload_on\': False,
+.br
+\'checker.on\': False,
+.br
+\'tools.log_headers.on\': False,
+.br
+\'request.show_tracebacks\': False,
+.br
+\'request.show_mismatched_params\': False,
+.br
+\'log.screen\': False,
+.br
+
+.UNINDENT
+.UNINDENT
+
+.SS embedded
+.INDENT 0.0
+.INDENT 3.5
+
+# For use with CherryPy embedded in another deployment stack, e.g. Apache mod_wsgi.
+.br
+\'engine.autoreload_on\': False,
+.br
+\'checker.on\': False,
+.br
+\'tools.log_headers.on\': False,
+.br
+\'request.show_tracebacks\': False,
+.br
+\'request.show_mismatched_params\': False,
+.br
+\'log.screen\': False,
+.br
+\'engine.SIGHUP\': None,
+.br
+\'engine.SIGTERM\': None,
+.br
+
+.UNINDENT
+.UNINDENT
+
+.SH BUGS
+\fBcherryd\fP should probably accept command\-line options \fB\-\-uid\fP, \fB\-\-gid\fP, and
+\fB\-\-umask\fP, and handle dropping privileges itself.
+
+
+.SH AUTHOR
+fumanchu
+
+.nf
+cherrypy.org
+.fi
+
+.SH COPYRIGHT
+This man page is placed in the public domain
+
+.\" Generated by docutils manpage writer on 2009-06-15 15:07.
+.\"