config

When starting w3pi, specify configuration options to modify the default behavior of the webserver. The configuration is processed from the command line and/or configuration file. Each configuration item on the command line starts with a slash and may contain name value pairs separated by a colon. For example:

w3pi.exe /pathinfo:atlserver /h2

This tells the webserver to serve files in the atlserver directory beneath w3pi.exe. Additionally, the h2 specifies http2 is to be used.

Configfile: You may also use configuration files to lessen the command line length.

w3pi.exe /configfile:c:\temp\config.cfg

Config files must be text based (ie. Notepad) and contain carriage return line feeds at the end of each line. Each name value pair is separated by a colon. You may place comments in the config file with #. Example config file:

# serve files in the atlserver directory
pathinfo:atlserver
http2:on

Here is a list of configuration entries that modify the way w3pi serves content:

  • Host: the host portion of the url to listen on.
  • Pathinfo: The path part of the urn to listen on. Use pipe character | to specify multiple paths. To specify a default document for the path, use a remap file.
  • Port: The tcp port number to listen on. Values greater than 1024 means that w3pi does not need administrative permissions.

The preceding (3) configuration entries and their meanings are discussed in greater detail at https://msdn.microsoft.com/en-us/library/aa364698(v=vs.85).aspx

  • Ssl: Specifies the url scheme to be https. Set to ON for enabled or specify /s on the command line. Using https implies that a certificate with a private key is accessible for w3pi to access. See this page for more info.
  • Http2: Enables http2. Set to ON for enabled or specify /h2 on the command line. NOTE: Specifying Http2 configuration entry will automatically turn on Ssl.
  • Requestsizethreshold: The maximum size of headers allowed. Defaults to 65535. This only applies to all combined header fields. If a request is receieved that contains headers larger than the bytes specified by this configuration entry, the request is rejected. This value must be a number.
  • Logging : Set to ON for enabled or specify /l on the command line. Turns on logging of http activities.
  • VerboseLogging: Set to ON for enabled or specify /v on the command line. Turns on verbose logging for all http activities.
  • Logsize: The maximum size of the log file before it is truncated and a anew file is created. This value must be a number. The default value is 1048576 (1 MB).
  • Logrollover: Either Daily, Weekly, Monthly. Specifies the time period when new log files are created.
  • Logdir: The location of the log file output.

You cannot modify the preceeding configuration entries in an atl server web application (at runtime), Also changes made in an atl server web app are not saved to disk. Instead use a configuration file. The configuration file is loaded on startup, and its’ entries placed in the configuration cache. The configuration cache can be accessed in an atl server web application using atl server’s queryservice method. The following configuration entries can be modified by an atl server web application (to modify http server behaviors dynamically).

  • Maxconnections: Sets the maximum requests per connection in the http keep-alive. It must be a number. The default value is 15.
  • Keepalive: Sets the timeout (in seconds) of the http-keepalive. This value must be a number. The default value is 240.
  • Disablekeepalive: Disables http keepalives. Set ON for enabled or specify /disablekeepalive on the command line.
  • Chunkthreshold: File size for which http requests are chunked using transfer encoding. This must be a number. The default value is 1048576 (1MB).
  • Chunksize: The size of the http chunk used in chunked transfer encoding. This value must be a number. The default value is 16384.
  • Threadmultiplier: Use to configure the maximum number of simultaneous requests that can be processed by w3pi. The default value of 1 yields 4 threads on the raspberry pi 2. On a 16 core cpu, the default value of 1 would yield 32. This configuration entry is not modifiable in an atl server web application. A value of 0 will yield 2 threads (minimum required). This value must be a number.
  • Remapfile: The location of the remap file. The remap cache is used to rewrite the urn and query string based on a regular expression match. The remapfile configuration entry specifies the location on disk of a file containing url remapping entries. If the remapfile configuration entry is specified, the entries in the file are loaded on startup and applied as http requests come in. NOTE: You cannot remap the scheme or host part of the url, only the urn and query string can be remapped. To change the host or scheme, see the redir sample. NOTE: If the remap cannot be performed, an http 403 error will be returned no directory browsing allowed - for a directory browsing example web app, see the showdir sample. Here is an example remap file:
# remap all requests to articles.htm
^/?$
/atlserver/articles.htm
  • Authfile: The auth cache is used to indicate which directories require authentication. The auth cache is initialized with the entries listed in the authfile configuration file, but can also be initialized by an atl server web app. Changes made to the auth cache by an atl server web app are not persisted to disk. The webserver uses a unique connectionid generated by the web server to determine users' authentication status. Authentication is processed after any remaps have been performed. In the authfile, Anything entered after the last backslash is considered the type of permission needed: READ, WRITE or EXECUTE.
c:\test\atlserver\READ EXECUTE

In an atl server webapp, a connectionid of 0 is used to store the directory authentication requirements (will also contain any entries from the authfile). Subsequent connectionid entries in the cache service will contain the directories which the atl server web application has authorized. These entries will have either READ, EXECUTE, or WRITE after the last backslash. The entries between the authenticated connectionid and the first entry (0) in the authcache are then compared to establish users' access.

  • Authenticationtimeout: Time (seconds) before the authenticated connection ( session ) times out. This must be a number. The default value is 300.
  • Authenticationfallback: For server tls authentication, specifies whether to allow the client access to the webserver without using ssl. This can be useful, for example, if you have a .crl that needs to be downloaded in the same url namespace.
  • Idleconnectiontimeouts: specify how long (in seconds) the connection to the client is maintained by tcp when no data is transmitted. For best results, match this value to the http keepalive timeout. This value must be a number. The default value is 240.
  • Clientssl: This setting tells w3pi that you would like mutual authentication enabled using tls. Set to ON for enabled. There are 2 types of tls client authentication. The first uses pre-authentication, and is best used with certificates that support perfect forward secrecy. The second is negotiated tls client ssl authentication. Currently, w3pi only supports preauthenticated tls.

You may also use custom configuration items that will be stored in the configuration cache and available to your atl server web application. For example, if you specified

pushfile:c:\temp\pushfile.css

your atl server web app could query this configuration entry and push the file to the user’s browser via atl server’s TransmitFile method.