Welcome to KatWebX!

KatWebX is an extremely fast web-server and reverse proxy for the modern web. Its features are listed below.

• Flexible config parsing
• Regex-based redirects
• Compressed regex-based reverse proxy
• Websocket reverse proxying
• HTTP basic authentication
• Fast file serving
• Brotli file compression
• Systemd/systemfd socket listening
• HSTS support
• SNI and OCSP reponse stapling
• High peformance HTTP/2 and TLS 1.3
• Multiple logging types
• Material design server-generated pages

You can download KatWebX's releases or source code from github.com/kittyhacker101/KatWebX.

Already have KatWebX? Continue reading the content on this page to learn how to configure KatWebX properly.

Folder structure

KatWebX keeps all of its data contained with its folder. The folder structure is listed below.

• /html/ - Default web server root.
  • /index.html - Root index page.
• /[domain]/ - File system root for [domain].
  • /index.html - Root index page.
• /ssl/ - Server TLS certificates.
  • /default.crt - Default TLS certificate.
  • /default.pem - Default certificate key.
  • /default.ocsp - Default OCSP reponse (optional).
  • /[domain].crt - TLS certificate for [domain].
  • /[domain].pem - Certificate key for [domain].
  • /[domain].ocsp - OCSP response for [domain] (optional).
• /src/ - Program source code.
  • /*.rs - Rust source code.
• /conf.json - Global configuration file.

Global configuration

KatWebX's global configuration is stored in the /conf.json file. Changes made to this file only take effect after KatWebX has been restarted.

• cachingTimeout (default: 4) - How long requests should be cached by the client, in hours. Setting this to zero will disable client-side caching.
• streamTimeout (default: 20) - The maximum amount of time a connection can be kept open, in seconds. If you intend to transfer large files, setting this higher is recommended.
• hsts (default: false) - Send HSTS headers, and redirect HTTP requests to HTTPS. This will enable HSTS preloading.
• proxy (array) - HTTP(S) reverse proxy.
  • location (type: host, regex: url) - The location where the proxy can be accessed.
  • host (type: absolute-url) - The URL of the location being proxied.
• redir (array) - Permanent HTTP redirects.
  • location (type, regex: url) - The location the redirect affects.
  • dest (type: absolute-url) - The URL to redirect to.
• auth (array) - HTTP basic authentication.
  • location (regex: url) - The location the password-protection affects.
  • login (type: login) - The credentials required to access the resource.
• hide (array: [type, regex: host]) - List of folders to ignore.
• advanced - Advanced KatWebX configuration
  • protect (default: true) - Increase website security using HTTP headers.
  • compressfiles (default: true) - Automatically compress resources with Brotli compression. Disaling this will not prevent pre-compressed resources from being served, or disable on-the-fly compression.
  • logformat (type: logtype, default: simple) - Logging format used.
  • httpAddr (type: listen-host, default: [::]:80) - Location to listen for HTTP requests.
  • tlsAddr (type: listen-host, default: [::]:443) - Location to listen for HTTPS requests.

Configuration types

Normal types are automatically used, regex types can be used by prefixing the configuration string with #r. When the string is set to its regex type, the string set in the configuration is parsed as regex.

• Host - An IPv4/IPv6 address or domain (ex. example.com)
• Listen-host - An IPv4/IPv6 address and port (ex. 127.0.0.1:443)
• Url - A URL without protocol (ex. example.com/page.html)
• Absolute-url - A url with protocol (ex. https://example.com/page.html)
• Login - A password and username split with : (ex. admin:passwd)
• Logtype - A logging format. Supported values: combinedvhost, combined, commonvhost, common, simpleplus, simple, minimal, none

Loading certificate and key pairs

To use a certificate and key, you must name the certificate [domain].crt, and the key [domain].pem. The certificate used is automatically detected using SNI. If no matching certificate is present, the files default.crt and default.pem will be used instead.

The keyfile must be in pkcs8 format. You can convert it into pkcs8 using the command below (requires openssl): openssl pkcs8 -topk8 -nocrypt -in oldkey.pem -out newkey.pem

Getting a TLS certificate

You can get free TLS certificates from Let's Encrypt through the use of an ACME client, like sslforfree.com.

Note: It is heavily recommended that you generate your own ECDSA key and CSR instead of letting the ACME client do it. Most ACME clients default to using RSA instead of ECDSA, which will result in reduced server peformance.

Forcing encrypted connections using HSTS

It's highly recommended that you make all internet-facing sites HTTPS only. To do so, you can enable the conf.hsts configuration option. This will automatically redirect all requests to HTTPS, and set an HSTS header, to allow for HSTS preloading. You can then request for your site to be added to the HSTS preload list here.

Note: Once you are on the preload list, it is very difficult to get off it. Make sure your site works properly over HTTPS before doing this!

OCSP stapling

KatWebX supports stapling an OCSP response, but it doesn't have a builtin OCSP client. If you split the certificate chain into two files, you can get an OCSP reponse manually using the commands below (requires openssl and bash): URI=$(openssl x509 -noout -ocsp_uri -in server.crt)
openssl ocsp -issuer ca.crt -cert server.crt -url $URI -respout output.ocsp

You can then apply it to a host by renaming the file to [domain].ocsp. Note that this file must be renewed often (usually every 7 days) to prevent it from expiring.

Socket listening

KatWebX can also listen using sockets passed to it, instead of directly binding to an address. The first socket passed to KatWebX will serve HTTP, and the second optional socket passed to KatWebX will serve HTTPS. When using sockets, KatWebX will behave the same as it would if you were binding to a TCP/IP address. You can test out the socket listening using the command below (requires systemfd and katwebx): systemfd -s http::8080 -s https::8181 -- ./katwebx

Peformance optimization

Although KatWebX is designed to be high-peformance, it may need a bit of extra tweaking when under extreme load. Here's some tips on how to improve KatWebX's peformance.

• Use the latest version of KatWebX. KatWebX is constantly being optimized, and newer versions can bring noticeable performance improvements (and even if they don't, using outdated releases can put your server's security at risk).
• Set conf.advanced.logformat to "minimal" or "none". Disabling logging heavily reduces latency and CPU load.
• Avoid using regex in the config whenever possible. Heavy use of regex can be extremely intensive.
• Try keeping files below 64kb in size. Small files can be copied directly into the response, which is ~2x faster than using streaming IO.
• If you are using RSA key sizes greater than 2048, consider switching to ECDSA instead.
• Avoid using unknown extensions. When the file extension is unknown, the server has to sniff the MIME type manually, which has a significant peformance impact.
• Make sure conf.advanced.compressfiles is enabled. This heavily reduces CPU load by pre-compressing files, instead of requiring data to be compressed in realtime.
• Make sure conf.cachingTimeout is set to a high value. More client side caching will result in fewer requests to the server.