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 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 file 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 (b-f) 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

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 via atl servers TransmitFile method.

Pre-Deployment Configuration:??

The netsh commands are not available on Windows IOT for setting up http namespace reservations detailed here

ARM cpu | HttpSvcPerm.zip | Size: 18 KB
x86 cpu | HttpSvcPerm.zip | Size: 18 KB
- sets (or removes) the urlacl on an HTTP API namespace reservation, so w3pi can be enabled to run without admin priveleges
- this program is required if you choose the appx deployment method

Hosted by: w3pi