# Configuration Guide

Contents

- Command Line Configuration

- Application.config

  - General Settings

  - Path Handling

  - Caching

  - Errors

  - Logging

- AppServer.config

# Command Line Configuration

Each of these can be set in the .config files, but they can be overridden with the command line. Run AppServer with switches in the form ClassName.SettingName=value, e.g. AppServer.AdapterPort=8087.

The value is coerced into a Python type: if it starts with one of the characters ({["' -- i.e., parenthesis (expression), dictionary, list, or string -- then the value with be eval'ed. If it can be turned into a Boolean, integer, float or None, then it will be converted, otherwise it will be left as a string. Some examples:

- None == None

- True == True (evaluates to 1 in older Python versions)

- 1 == 1

- 127.0.0.1 == "127.0.0.1"

- (10+2) == 12

- {'a': 'b'} == {'a': 'b'}

- {a: b} == error

- [1, 'c', [2, 3]] == [1, 'c', [2, 3]]

Be careful about special characters in the shell. All the characters () [] ' " are special, and need to be quoted (with \ or with single or double quotation marks).

# Application.config

Application.config covers not only the application, but a number of components that use it as a central point of configuration.

## General Settings

Contexts:

  This dictionary maps context names to the directory holding the context content. Since the default contexts all reside in WebKit, the paths are simple and relative. The context name appears as the first path component of a URL, otherwise Contexts['default'] is used when none is specified. When creating your own application, you will add a key such as "MyApp" with a value such as "/home/apps/MyApp". That directory will then contain content such as Main.py, SomeServlet.py, SomePage.psp, etc. Webware/bin/MakeAppWorkDir.py will set up a context for your use as well. Default:

      {
          'default':   'Examples',
          'Admin':     'Admin',
          'Examples':  'Examples',
          'Docs':      'Docs',
          'Testing':   'Testing',
      }

AdminPassword:

  The password that, combined with the admin id, allows access to the AppControl page of the Admin context. Set interactively when install.py is run (no default value).

PrintConfigAtStartUp:

  Print the configuration to the console when AppServer starts. Default: True (on).

## Path Handling

These configuration settings control which files are exposed to users, which files are hidden, and some of how those files get chosen.

DirectoryFile:

  The list of basic filenames that WebKit searches for when serving up a directory. Note that the extensions are absent since WebKit will look for a file with any appropriate extension (.py., .html, .psp, etc). Default: ["index", "Main"].

ExtensionsForKid:

  This is the list of extensions for files to be parsed Kid templates. Default: ['.kid'].

ExtensionsForPSP:

  This is the list of extensions for files to be parsed as PSP. Default: ['.psp'].

ExtensionsToIgnore:

  This is a list or set of extensions that WebKit will ignore when autodetecting extensions. Note that this does not prevent WebKit from serving such a file if the extension is given explicitly in a URL. Default: set(['.pyc', '.pyo', '.py~', '.bak']).

ExtensionsToServe:

  This is a list of extensions that WebKit will use exclusively when autodetecting extensions. Note that this does not prevent WebKit from serving such a file if it is named explicitly in a URL. If no extensions are given all extensions will be served (usually anything but .py and .psp will be served as a static file). Default: [].

UseCascadingExtensions:

  If False, WebKit will give a 404 Not Found result if there is more than one file that could potentially match. If True, then WebKit will use the ExtensionCascadeOrder setting to determine which option to serve. Default: True.

ExtensionCascadeOrder:

  A list of extensions that WebKit will choose, in order, when files of the same basename but different extensions are available. Note that this will have no effect if the extension is given in the URL. Default: [".psp", ".py", ".html"].

FilesToHide:

  A list or set of file patterns to protect from browsing. This affects all requests, and these files cannot be retrieved even when the extension is given explicitly. Default: set([".*", "*~", "*bak", "*.tmpl", "*.pyc", "*.pyo", "*.config"]).

FilesToServe:

  File patterns to serve from exclusively. If the file being served for a particulary request does not match one of these patterns an HTTP 403 Forbidden error will be return. This affects all requests, not just requests with autodetected extensions. If set to [] then no restrictions are placed. Default: [].

MemcachedNamespace:

  The namespace used to prefix all keys from the Webware application when accessing Memcached servers for storing sessions. You should change this if you are using the same memcache for different applications. Default: 'WebwareSession:'.

MemcachedOnIteration:

  This setting determines how Webware behaves when attempting to iterate over the sessions or clear the session store, when using Memcached. If you set it to Error, this will raise an Exception, when set to Warning, it will print a Warning, when set to None, it will be ignored (the size of the session store will be always reported as zero). Default: Warning.

MemcachedServers:

  This sets the list of Memcached servers used when setting SessionStore to Memcached. Default: ['localhost:11211'].

RedisNamespace:

  The namespace used to prefix all keys from the Webware application when accessing Redis servers for storing sessions. You should change this if you are using the same Redis instance for different applications. Default: 'WebwareSession:'.

RedisHost:

  This sets the Redis host that shall be used when setting SessionStore to Redis. Default: 'localhost'.

RedisPort:

  This sets the port for the Redis connection that shall be used when setting SessionStore to Redis. Default: 6379.

RedisDb:

  This sets the database number for the Redis connection that shall be used when setting SessionStore to Redis. Default: 0.

RedisPassword:

  This sets the password for the Redis connection that shall be used when setting SessionStore to Redis. Default: None.

SessionModule:

  Can be used to replace the standard WebKit Session module with something else. Default: Session

SessionStore:

  This setting determines which of five possible session stores is used by the application: Dynamic, File, Memcached, Memory, Redis or `Shelve. The File store always gets sessions from disk and puts them back when finished. Memory always keeps all sessions in memory, but will periodically back them up to disk. Dynamic is a good cross between the two, which pushes excessive or inactive sessions out to disk. Shelve stores the sessions in a database file using the Python shelve module, Memcached stores them on a Memcached system using the python-memcached interface, and Redis stores them on a Redis system using the redis-py client. You can use a custom session store module as well. Default: Dynamic.

SessionStoreDir:

  If SessionStore is set to File, Dynamic or Shelve, then this setting determines the directory where the files for the individual sessions or the shelve database will be stored. The path is interpreted as relative to the working directory (or WebKit path, if you're not using a working directory), or you can specify an absolute path. Default: Sessions.

SessionTimeout:

  Determines the amount of time (expressed in minutes) that passes before a user's session will timeout. When a session times out, all data associated with that session is lost. Default: 60.

AlwaysSaveSessions:

  If False, then sessions will only be saved if they have been changed. This is more efficient and avoids problems with concurrent requests made by the same user if sessions are not shared between these requests, as is the case for session stores other than Memory or Dynamic. Note that in this case the last access time is not saved either, so sessions may time out if they are not altered. You can call setDirty() on sessions to force saving unaltered sessions in this case. If True, then sessions will always be saved. Default: True.

IgnoreInvalidSession:

  If False, then an error message will be returned to the user if the user's session has timed out or doesn't exist. If True, then servlets will be processed with no session data. Default: True.

UseAutomaticPathSessions:

  If True, then the app server will include the session ID in the URL by inserting a component of the form _SID_=8098302983 into the URL, and will parse the URL to determine the session ID. This is useful for situations where you want to use sessions, but it has to work even if the users can't use cookies. If you use relative paths in your URLs, then you can ignore the presence of these sessions variables. The name of the field can be configured with the setting SessionName. Default: False.

UseCookieSessions:

  If True, then the app server will store the session ID in a cookie with the name set in SessionName, which is usually _SID_. Default: True.

SessionCookiePath:

  You can specify a path for the session cookie here. None means that the servlet path will be used, which is normally the best choice. If you rewrite the URL using different prefixes, you may have to specify a fixed prefix for all your URLs. Using the root path '/' will always work, but may have security issues if you are running less secure applications on the same server. Default: None.

SecureSessionCookie:

  If True, then the app server will use a secure cookie for the session ID if the request was using an HTTPS connection. Default: True.

MaxDynamicMemorySessions:

  The maximum number of dynamic memory sessions that will be retained in memory. When this number is exceeded, the least recently used, excess sessions will be pushed out to disk. This setting can be used to help control memory requirements, especially for busy sites. This is used only if the SessionStore is set to Dynamic. Default: 10000.

DynamicSessionTimeout:

  The number of minutes of inactivity after which a session is pushed out to disk. This setting can be used to help control memory requirements, especially for busy sites. This is used only if the SessionStore is set to Dynamic. Default: 15.

SessionPrefix:

  This setting can be used to prefix the session IDs with a string. Possible values are None (don't use a prefix), "hostname" (use the hostname as the prefix), or any other string (use that string as the prefix). You can use this for load balancing, where each Webware server uses a different prefix. You can then use mod_rewrite or other software for load-balancing to redirect each user back to the server they first accessed. This way the backend servers do not have to share session data. Default: None.

SessionName:

  This setting can be used to change the name of the field holding the session ID. When the session ID is stored in a cookie and there are applications running on different ports on the same host, you should choose different names for the session IDs, since the web browsers usually do not distinguish the ports when storing cookies (the port cookie-attribute introduced with RFC 2965 is not used). Default: _SID_.

ExtraPathInfo:

  When enabled, this setting allows a servlet to be followed by additional path components which are accessible via HTTPRequest's extraURLPath(). For subclassers of Page, this would be self.request().extraURLPath(). Default: False.

UnknownFileTypes:

  This setting controls the manner in which WebKit serves "unknown extensions" such as .html, .css, .js, .gif, .jpeg etc. The default setting specifies that the servlet matching the file is cached in memory. You may also specify that the contents of the files shall be cached in memory if they are not too large.

  If you are concerned about performance, use mod_rewrite to avoid accessing WebKit for static content.

  The Technique setting can be switched to "redirectSansAdapter", but this is an experimental setting with some known problems.

  Default:

      {
          'ReuseServlets': True,  # cache servlets in memory
          'Technique': 'serveContent',  # or 'redirectSansAdapter'
          # If serving content:
          'CacheContent': False,  # set to True for caching file content
          'MaxCacheContentSize': 128*1024,  # cache files up to this size
          'ReadBufferSize': 32*1024  # read buffer size when serving files
      }

## Caching

CacheServletClasses:

  When set to False, the AppServer will not cache the classes that are loaded for servlets. This is for development and debugging. You usually do not need this, as servlet modules are reloaded if the file is changed. Default: True (caching on).

CacheServletInstances:

  When set to False, the app server will not cache the instances that are created for servlets. This is for development and debugging. You usually do not need this, as servlet modules are reloaded and cached instances purged when the servlet file changes. Default: True (caching on).

CacheDir:

  This is the name of the directory where things like compiled PSP or Kid templates are cached. Webware creates a subdirectory for every plug-in in this directory. The path is interpreted as relative to the working directory (or WebKit path, if you're not using a working directory), or you can specify an absolute path. Default: Cache.

ClearPSPCacheOnStart:

  When set to False, the app server will allow PSP instances to persist from one AppServer run to the next. If you have PSPs that take a long time to compile, this can give a speedup. Default: False (cache will persist).

ReloadServletClasses:

  During development of an application, servlet classes will be changed very frequently. The AutoReload mechanism could be used to detect such changes and to reload modules with changed servlet classes, but it would cause an app server restart every time a servlet class is changed. So by default, modules with servlet classes are reloaded without restarting the server. This can potentially cause problems when other modules are dependent on the reloaded module because the dependent modules will not be reloaded. To allow reloading only using the AutoReload mechanism, you can set ReloadServletClasses to False in such cases. Default: True (quick and dirty reloading).

## Errors

ShowDebugInfoOnErrors:

  If True, then uncaught exceptions will not only display a message for the user, but debugging information for the developer as well. This includes the traceback, HTTP headers, form fields, environment and process ids. You will most likely want to turn this off when deploying the site for users. Default: True.

EnterDebuggerOnException:

  If True, and if the AppServer is running from an interactive terminal, an uncaught exception will cause the AppServer to enter the debugger, allowing the developer to call functions, investigate variables, etc. See python debugger (pdb) docs for more information. You will certainly want to turn this off when deploying the site. Default: False (off).

IncludeEditLink:

  If True, an "[edit]" link will be put next to each line in tracebacks. That link will point to a file of type application/x-webkit-edit-file, which you should configure your browser to run with Webware/bin/editfile.py. If you configure editfile.py correctly, then it will automatically open the respective Python module with your favorite Python editor and put the cursor on the erroneous line. Default: True.

IncludeFancyTraceback:

  If True, then display a fancy, detailed traceback at the end of the error page. It will include the values of local variables in the traceback. This makes use of a modified version of cgitb.py which is included with Webware as CGITraceback.py. The original version was written by Ka-Ping Yee. Default: False (off).

FancyTracebackContext:

  The number of lines of source code context to show if IncludeFancyTraceback is turned on. Default: 5.

UserErrorMessage:

  This is the error message that is displayed to the user when an uncaught exception escapes a servlet. Default: "The site is having technical difficulties with this page. An error has been logged, and the problem will be fixed as soon as possible. Sorry!"

ErrorLogFilename:

  The name of the file where exceptions are logged. Each entry contains the date and time, filename, pathname, exception name and data, and the HTML error message filename (assuming there is one). Default: Logs/Errors.csv.

SaveErrorMessages:

  If True, then errors (e.g., uncaught exceptions) will produce an HTML file with both the user message and debugging information. Developers/administrators can view these files after the fact, to see the details of what went wrong. These error messages can take a surprising amount of space. Default: True (do save).

ErrorMessagesDir:

  This is the name of the directory where HTML error messages get stored. The path is interpreted as relative to the working directory (or WebKit path, if you're not using a working directory), or you can specify an absolute path.Default: ErrorMsgs.

EmailErrors:

  If True, error messages are e-mailed out according to the ErrorEmailServer and ErrorEmailHeaders settings. You must also set ErrorEmailServer and ErrorEmailHeaders. Default: False (false/do not email).

EmailErrorReportAsAttachment:

  Set to True to make html error reports be emailed as text with an html attachment, or False to make the html the body of the message. Default: False (html in body).

ErrorEmailServer:

  The SMTP server to use for sending e-mail error messages, and, if required, the port, username and password, all separated by colons. For authentication via "SMTP after POP", you can furthermore append the name of a POP3 server, the port to be used and an SSL flag. Default: 'localhost'.

ErrorEmailHeaders:

  The e-mail headers used for e-mailing error messages. Be sure to configure "From", "To" and "Reply-To" before turning EmailErrors on. Default:

      {
          'From':         'webware@mydomain,
          'To':           ['webware@mydomain'],
          'Reply-To':     'webware@mydomain',
          'Content-Type': 'text/html',
          'Subject':      'Error'
      }

ErrorPage:

  You can use this to set up custom error pages for HTTP errors and any other exceptions raised in Webware servlets. Set it to the URL of a custom error page (any Webware servlet) to catch all kinds of exceptions. If you want to catch only particular errors, you can set it to a dictionary mapping the names of the corresponding exception classes to the URL to which these exceptions should be redirected. For instance:

      {
           'HTTPNotFound': '/Errors/NotFound',
           'CustomError':  '/Errors/Custom'
      }

  If you want to catch any exceptions except HTTP errors, you can set it to:

      {
          'Exception':     '/ErrorPage',
          'HTTPException': None
      }

  Whenever one of the configured exceptions is thrown in a servlet, you will be automatically forwarded to the corresponding error page servlet. More specifically defined exceptions overrule the more generally defined. You can even forward from one error page to another error page unless you are not creating loops. In an HTTPNotFound error page, the servlet needs to determine the erroneous URI with self.request().previousURI(), since the uri() method returns the URI of the current servlet, which is the error page itself. When a custom error page is displayed, the standard error handler will not be called. So if you want to generate an error email or saved error report, you must do so explicitly in your error page servlet. Default: None (no custom error page).

MaxValueLengthInExceptionReport:

  Values in exception reports are truncated to this length, to avoid excessively long exception reports. Set this to None if you don't want any truncation. Default: 500.

RPCExceptionReturn:

  Determines how much detail an RPC servlet will return when an exception occurs on the server side. Can take the values, in order of increasing detail, "occurred", "exception" and "traceback". The first reports the string "unhandled exception", the second prints the actual exception, and the third prints both the exception and accompanying traceback. All returns are always strings. Default: "traceback".

ReportRPCExceptionsInWebKit:

  True means report exceptions in RPC servlets in the same way as exceptions in other servlets, i.e. in the logfiles, the error log, and/or by email. False means don't report the exceptions on the server side at all; this is useful if your RPC servlets are raising exceptions by design and you don't want to be notified. Default: True (do report exceptions).

## Logging

LogActivity:

  If True, then the execution of each servlet is logged with useful information such as time, duration and whether or not an error occurred. Default: True.

ActivityLogFilenames:

  This is the name of the file that servlet executions are logged to. This setting has no effect if LogActivity is False. The path can be relative to the WebKit location, or an absolute path. Default: "Logs/Activity.csv".

ActivityLogColumns:

  Specifies the columns that will be stored in the activity log. Each column can refer to an object from the set: [application, transaction, request, response, servlet, session] and then refer to its attributes using "dot notation". The attributes can be methods or instance attributes and can be qualified arbitrarily deep. Default: ['request.remoteAddress', 'request.method', 'request.uri', 'response.size', 'servlet.name', 'request.timeStamp', 'transaction.duration', 'transaction.errorOccurred'].

# AppServer.config

Host:

  The IP address at which the application server will listen for requests. Use an empty string (or 0.0.0.0) to listen on all local network interfaces, or a specific address if you don't want to listen on all of them. You should consider the security implications of allowing external access. Default: localhost (127.0.0.1).

EnableAdapter:

  Whether the application server should listen for requests from the adapter. You'll want this on unless you decide to use the built-in HTTP server. Default: True.

AdapterPort:

  The port the application server listens to for requests from the adapter. You cannot point a browser to this port. You may wish to change this if you have another application running at this port, or if you are running more than one AppServer, they must each be listening at a different port. Default: 8086.

EnableMonitor:

  Whether the application server should listen for monitor service requests. Monitor is a minimal service that accepts a simple protocol and returns a value indicating the status of the server. If you enable this, a separate monitoring program such as Monitor.py can provide additional assurance that the application server continues running at all times. Default: False.

MonitorPort:

  The port for the monitor service. You cannot point a browser to this port. You may wish to change this if you have another application running at this port, or if you are running more than one AppServer. Default: 8085.

EnableSCGI:

  Whether the application server should provide an SCGI connector. This allows you to connect via SCGI instead of using the standard adapter. Default: False.

SCGIPort:

  The port the application server listens to for SCGI connections. You cannot point a browser to this port. You may wish to change this if you have another application running at this port, or if you are running more than one AppServer, they must each be listening at a different port. Default: 8084.

EnableHTTP:

  Whether the built-in HTTP server shall be activated. The server will listen on the port specified by the HTTPPort setting. Default: True.

HTTPPort:

  The port the built-in HTTP server listens on. You can point a web browser to this port. Default: 8080.

PidFile:

  When the AppServer starts up, the process ID will be written into this file. The location is relative to the working directory (or WebKit path, if you're not using a working directory), or you can specify an absolute path. Default: appserver.pid.

AddressFiles:

  When the AppServer starts up, the server address (IP address and port) of the adapter handler and other handlers will be written into files with this name, %s being replaced by the name of the respective handler. The location is relative to the working directory (or WebKit path, if you're not using a working directory), or you can specify an absolute path. Default: %s.address.

PluginDirs:

  When the application server starts up, it looks in these locations for plugins. Each plugin is a subdirectory of its own. By default WebKit looks in the Webware/ directory (..) for plugins -- several of which are shipped with Webware. Default: [".."]. See Creating Plugins for information on creating your own plug-ins.

  The advantage of a plug-in directory is that you can add new plug-ins to the app server simply by dropping them into the directory; no additional configuration is necessary.

PlugIns:

  Loads the plug-ins from the given locations when starting the AppServer. You must add a directory to the list for every plug-in you use -- PlugInDirs is usually easier. Default: [].

PrintConfigAtStartUp:

  If True, prints configuration to console at startup. Default: True.

Verbose:

  If True, then additional messages are printed while the AppServer runs, most notably information about each request such as size and response time. Default: True.

SilentURIs:

  If Verbose is set to True, then you can use this setting to specify URIs for which you don't want to print any messages in the output of the AppServer. The value is expected to be a regular expression that is compared to the request URI. For instance, if you want to suppress output for images, JavaScript and CSS files, you can set SilentURIs to '\.(gif|jpg|jpeg|png|js|css)$' (though we do not recommend serving static files with Webware; it's much more efficient to deliver them directly from the Apache server). If set to None, messages will be printed for all requests handled by Webware. Default: None

StartServerThreads:

  The number of threads in the request handler thread pool that will be created when the application server starts. Default: 10.

MinServerThreads:

  The minimum number of threads in the request handler thread pool. This makes sure that always some threads are available immediately, even when there had been no activity for a long time. Default: 5.

MaxServerThreads:

  The maximum number of threads in the request handler thread pool, and therefore, the maximum number of concurrent requests that can be served. Unless you have a serious load on a high end machine, the default is generally sufficient. Default: 20.

UseDaemonThreads:

  If True, make all worker threads daemon threads. This allows the server to finish even when some of the worker threads cannot be told to finish their work. Default: True.

MaxRequestTime:

  This setting controls automatic cancelation of long-running requests. All worker threads executing requests longer than MaxRequestTime seconds will be automatically aborted with a RequestTooLongError exception. The monitoring of long-running requests can be disabled by setting this to 0 or None. Default: 300.

CheckInterval:

  The number of virtual instructions after which Python will check for thread switches, signal handlers, etc. This is passed directly to sys.setcheckinterval(). Benchmarks have shown 100 to give a worthwhile performance boost with higher values resulting in little gain. Default: 100.

RequestQueueSize:

  The size of the queue for request handlers that is worked off by the server threads. A size of zero is interpreted as two times the maximum number of worker threads, which has proven to be a reasonable number. Default: 0 (2*MaxServerThreads).

RequestBufferSize:

  Buffer size used for reading incoming socket requests. Default: 8192.

ResponseBufferSize:

  Buffer size for the output response stream. This is only used when a servlet has set autoFlush to True using the flush() method of the Response. Otherwise, the whole response is buffered and sent in one shot when the servlet is done. Default: 8192.

AutoReload:

  Enables the AutoReloadingAppServer module. This module is designed to notice changes to source files, including servlets, PSP's templates, or changes to the Webware source files, and reload the server as necessary to pick up the changes.

  This uses the FAM (File Alteration Monitor) module specified in the setting UseFAMModules if available. You can also specify several modules to check them in the given order (the default is gamin _fam for using python-gamin or python-fam). Otherwise, if no FAM module is specified or installed, or when ImportSpy has been disabled by setting UseImportSpy to False, it resorts to polling. The polling interval in seconds can be set with the AutoReloadPollInterval setting which defaults to 1 second.

  By default, AutoReload is set to False.