cherryd(1) · carta

Usage

cherryd [-d] [{-f | -s}] [-e ENV_NAME] [-p PIDFILE_PATH] [-P DIRPATH] [-c CONFIG_FILE] -i MODULE_NAME

Overview

cherryd is a Python script which starts the CherryPy webserver as a daemon.

Options

-c CONFIG_FILE, --config=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, cherryd will perform cherrypy.config.update().

-d: Run the server as a daemon.

-e ENV_NAME, --environment=ENV_NAME: Specifies the name of an environment to be applied. An environment is a canned set of configuration entries. See ENVIRONMENTS below for a list of the built-in environments.

-f: Start a fastcgi server instead of the default HTTP server.

-s: Start a scgi server instead of the default HTTP server.

-i MODULE_NAME, --import=MODULE_NAME: Specifies a module to import. This option may be specified multiple times. For each MODULE_NAME specified, cherryd will import the module. This is how you tell cherryd to run your application´s startup code. For all practical purposes, -i is not optional; you will always need to specify at least one module.

-p PIDFILE_PATH, --pidfile=PIDFILE_PATH: Store the process id in PIDFILE_PATH.

-P DIRPATH, --Path DIRPATH: Specifies a directory to be inserted at the head of sys.path. DIRPATH should be an absolute path. This option may be specified multiple times. cherryd inserts all the specified DIRPATHs into sys.path before it attempts to import modules specified with -i.

For a terse summary of the options, run cherryd --help.

Examples

A site-wide configuration file site.conf:

[global]
server.socket_host = "0.0.0.0"
server.socket_port = 8008
engine.autoreload.on = False

The application startup code in startup.py:

import cherrypy
import my_controller
cherrypy.log.error_file = ´/var/tmp/myapp-error.log´
cherrypy.log.access_file = ´/var/tmp/myapp-access.log´
config_root = { ´tools.encode.encoding´ : ´utf-8´, }
app_conf = { ´/´ : config_root }
cherrypy.tree.mount(my_controller.Root(), script_name=´´, config=app_conf)

A corresponding cherryd command line:

cherryd -d -c site.conf -i startup -p /var/log/cherrypy/my_app.pid

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 cherryd does not do it for you.

To drop privileges, put the following lines into your startup code, substituting appropriate values for umask, uid and gid:

from cherrypy.process.plugins import DropPrivileges
DropPrivileges(cherrypy.engine, umask=022, uid=´nobody´, gid=´nogroup´).subscribe()

Note that the values for uid and gid 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 exec()ing 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.

Environments

These are the built-in environment configurations:

staging

´engine.autoreload.on´: False,
´checker.on´: False,
´tools.log_headers.on´: False,
´request.show_tracebacks´: False,
´request.show_mismatched_params´: False,

production

´engine.autoreload_on´: False,
´checker.on´: False,
´tools.log_headers.on´: False,
´request.show_tracebacks´: False,
´request.show_mismatched_params´: False,
´log.screen´: False,

embedded

# For use with CherryPy embedded in another deployment stack, e.g. Apache mod_wsgi.
´engine.autoreload_on´: False,
´checker.on´: False,
´tools.log_headers.on´: False,
´request.show_tracebacks´: False,
´request.show_mismatched_params´: False,
´log.screen´: False,
´engine.SIGHUP´: None,
´engine.SIGTERM´: None,

History

Debian 10 (Buster): the text shown here
Debian 9 (Stretch)
Debian 8 (Jessie)
Debian 7 (Wheezy)

--help until Debian 9 (Stretch); -h until Debian 9 (Stretch); -x until Debian 9 (Stretch).