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. Must end in a forward slash. 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. For more information, see ssl
  • 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 basic 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 the atl server 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 the 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 the user 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.

  • Browscapfile: Allows you to specify the location of a browscap.ini formatted file. The contents of this file are then available for your web-app as a per-thread service. For more information, see the CBrowsCaps class in the ATL Server documentation.

  • CacheControlFile: A text file with files and/or directory paths specifying static files to have the Cache-Control header applied to them when being served by w3pi. The right-most colon on each line of the file determines the end-of-path. Afterwards a series of commas specifies additional Cache-Control headers which can be appended. Omitting this setting means no cache-control headers will be applied. Using a -1 value in a section means that the header will not be included

    • Flags: Use a flag or add the flags up to produce a number. This is the numeric value before the first comma. Possible flags include:

      • 64: this prevents clients from refreshing the resource (Immutable)
      • 16: ensures proxyies do not cache resource (Proxy-Revalidate)
      • 8: ensures proxies and CDNs do not cache resource (Must-Revalidate)
      • 4: ensures browsers and others do not cache resource (No-Store)
      • 2: forces caches to resubmit request to origin server for validation using if-not-modified (No-Cache)
      • 1: private
      • 0: public
    • max-age: the value after the first comma is the max-age header. This must be a number (seconds)

    • s-max-age: the s-max-age header, also a number (seconds)

    • max-stale: the max-stale header, in seconds

    • retain: the retain header, in seconds

    • expires: the expiry as an http formatted date (GMT)

The following example shows how to cache the bootstrap css folder.

C:\temp\atlserver\bootstrap-4.1.1\css\:0,3600,-1,180
  • contentsecuritypolicyfile: A text file with file paths which is used to apply Content-Security-Policy headers to static file-based http responses. The right-most pipe | character on each line determines the end-of-path for the filename. After the pipe, include the Content-Security-Policy header directives. Here is an example:
c:\temp\atlserver\index.htm|script-src 'self'
  • contentsecurityreportingfile: A text file with file paths which is used to apply Content-Security-Policy-Report-Only headers to static file-based http responses. The syntax is the same as the Content-Security-Policy entry.
  • corsfile: A text file with file paths, used to apply various Cross-Origin-Resource-Sharing (CORS) headers to a resource. The left-most pipe | character on each line determines the end-of-path for the filename. After the pipe, include another pipe | to start the header enumerations:
    • Access-Control-Allow-Origin: specify a url or urls
    • Access-Control-Expose-Headers: specify the name of the header(s)
    • Access-Control-Allow-Methods: specify http method(s)
    • Access-Control-Allow-Headers: specify the name of the header(s)
    • Access-Control-Allow-Credentials: specify True or False
    • Access-Control-Max-Age: the max-age (freshness) time

he following example shows how to apply the Access-Control-Allow-Origin header to the bootstrap stylesheet so other websites cannot use your server as a miniature cdn.

c:\temp\atlserver\bootstrap-4.1.1\css\bootstrap.css| |https://yourdomain.com http://yourdomain.com
  • mimefile: A text file with file extensions and mimetype specifications. The right-most colon : on each line of the file determines the end of the extension. For example, the following is mime-type for a word document.
doc: application/msword
  • extraheadersfile: A text file with file paths, used to apply extra http headers to a resource. The left-most pipe | character on each line determines the end-of-path for the filename. After the pipe, include another pipe | to start the header enumerations. The following headers will not be processed by w3pi when serving static files (but you may set them in an ATL Server web-application):
    • Cache-Control: to set this header, use the cachecontrolfile configuration file
    • Connection: not adjustable, instead use the disablekeepalive configuration entry
    • Date: not adjustable, instead change the time on your server
    • Keep-alive: not adjustable, instead use the Keepalive and Maxconnections configuration entry
    • Trailer: not adjustable, only used with chunked responses
    • Transfer-encoding: not adjustable, instead use an ATL Server web-app
    • Upgrade: not available
    • Content-Length: not adjustable
    • Content-Type: to set this header, use the mimefile configuration file
    • Content-Range: not adjustable
    • Expires: to set this header, use the cachecontrolfile configuration file
    • Last-Modified: not adjustable, instead use the attrib dos command
    • ETag: not adjustable
    • Proxy-Authenticate: not available
    • Server: not adjustable
    • Set-Cookie: not adjustable
    • www-authenticate: not adjustable

The following example shows how to apply the Vary and Allow headers to an html file

c:\temp\atlserver\index.htm|allow:GET, HEAD|vary: Origin
  • pagecachehistory: when used with the ATL Server Page Response Cache , this enables delta-coding, which transmits only changes between versions of ATL Server generated pages in the cache. To fully exploit this functionality, the page needs to have a serviceworker linked in. See the mywebapp sample for more details

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 users browser using http2

Namespace Reservation:

Windows IoT supports reserving HTTP namespaces so other apps cannot get access to the same server url that you wish to serve requests from on the local computer. Admin permissions are required to set and remove these reservations. The netsh commands are not available on Windows IOT for setting up http namespace reservations detailed here so you may use the tools below instead to set and remove reservations. This effectively allows you to runas w3pi.exe in a low-privelege user account.

HttpSvcPerm.zip | ARM cpu | Size: 17 KB
HttpSvcPerm.zip | x86 cpu | Size: 17 KB

After specifying a request queue, then start w3pi with requestqueue:ON in a configfile or /rq command line option. Make sure that the url used the HttpSvcPerm is exactly the same as the one being built up by w3pi (ie. set the host, port and pathinfo config entries)

Hosted by: w3pi