# Configuration system overview

The CherryPy configuration system provides fine-grained control over how each part of the application should react. You will use it for two reasons:

- Web server settings
- Enabling filters per path

You will be able to declare the configuration settings either from a file or from a Python dictionary.

First of all, let's see how a typical configuration file is defined.

Configuration file

                # The configuration file called myconfigfile.conf
                [global]
                server.socketPort=8080
                server.socketHost=""
                server.socketFile=""
                server.socketQueueSize=5
                server.protocolVersion="HTTP/1.0"
                server.logToScreen=True
                server.logFile=""
                server.reverseDNS=False
                server.threadPool=10
                server.environment="development"

                [/service/xmlrpc]
                xmlRpcFilter.on = True

                [/admin]
                sessionAuthenticateFilter.on=True

                [/css/default.css]
                staticFilter.on = True
                staticFilter.file = "data/css/default.css"

                # From your script...
                cherrypy.config.update(file="myconfigfile.conf")

The settings can also be defined using a python dictionary instead of a file as follows:

Configuration dictionary

          settings = {
             'global': {
                'server.socketPort' : 8080,
                'server.socketHost': "",
                'server.socketFile': "",
                'server.socketQueueSize': 5,
                'server.protocolVersion': "HTTP/1.0",
                'server.logToScreen': True,
                'server.logFile': "",
                'server.reverseDNS': False,
                'server.threadPool': 10,
                'server.environment': "development"
             },
             '/service/xmlrpc' : {
                'xmlRpcFilter.on': True
             },
             '/admin': {
                'sessionAuthenticateFilter.on' :True
             },
             '/css/default.css': {
                'staticFilter.on': True,
                'staticFilter.file': "data/css/default.css"
             }
          }
          cherrypy.config.update(settings)

Each section of the configuration refers to a URL path; each path is mapped to a published object of the tree handled by CherryPy. Therefore when the server receives a request for `/css/default.css`, the static filter will be called and the server will actually return the physical file name `data/css/default.css`.

Since the path `/service/xmlrpc` has the XML-RPC filter enabled, all the exposed methods of the object `cherrypy.root.service.xmlrpc` will be treated as XML-RPC methods.

The root entry, defined as `global`, is also responsible for defining the server settings such as the port, the protocol version to use by default, the number of threads to start with the server, etc.

All values in the configuration file must be valid Python values. Strings must be quoted, booleans must be True or False, etc.

The `server.environment` entry controls how CherryPy should run. Three values are legal:

- development
  - logDebugInfoFilter is enabled by default
  - HTTPErrors (and therefore the default _cpOnError) display tracebacks in the browser if errors occur
  - autoreload is enabled by default
- production
  - logDebugInfoFilter is disabled by default

  - tracebacks are logged, but are not displayed in the browser

  - autoreload is disabled by default
- staging (same as production for the moment)