diff options
Diffstat (limited to 'man/cherryd.1')
| -rw-r--r-- | man/cherryd.1 | 263 |
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. +.\" |