cherryd(1)

NAME
cherryd - Starts the CherryPy HTTP server as a daemon

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

DESCRIPTION
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,

BUGS
cherryd should probably accept command-line options --uid, --gid, and --umask, and handle dropping privileges itself.

AUTHOR
fumanchu

cherrypy.dev

COPYRIGHT
This man page is placed in the public domain