cutelystd4-qt6 is a developer friendly WSGI server for Cutelyst applications that can either be used as standalone HTTP server or as a gateway between your Cutelyst application and another webserver like Apache or nginx. It supports HTTP, HTTPS, HTTP/2 and FastCGI sockets. See Serve your application for usage instructions; this page documents the options available for cutelystd4-qt6. All options can also be set via configuration file options. See Configure your application.

Options

Generic program information

-h, --help: Output a usage message and exit.

-v, --version: Output the version number of cutelystd4-qt6 and exit.

Load application

-a, --application file: Path to the application file to load.

-r, --auto-restart: Automatically restart when the application file changes. Requires that master process (--master) and lazy mode (--lazy) are enabled.

--pidfile file: Create PID file (before privileges drop).

--pidfile2 file: Create PID file (after privileges drop).

--stop pidfile: Stop an instance identified by pidfile.

Directories and mount points

--chdir directory: Change to the specified directory before the application loads.

--chdir2 directory: Change to the specified directory after the application has been loaded.

--static-map mountpoint=path

Map mountpoint to local path to serve static files. The mountpoint will be removed from the request path and the rest will be appended to the local path to find the file to serve. Can be used multiple times.

If for example defining a static map /assets=/path/to/static and then getting a request for /assets/css/style.css, the server will remove /assets from the request path and appends the rest to the local path for that mountpoint. In the end it will try to find the requested file locally at /path/to/static/css/style.css.

Load configuration

--ini file

Load configuration from INI file. When used multiple times, content will be merged and same keys in the sections will be overwritten by content from later files.

Threads and processes

-M, --master: Enable master process.

--lazy: Enable lazy mode to load application in workers instead of master.

-p, --processes processes: Spawn the specified number of processes. If set to auto, the ideal process count is used.

-t, --threads threads: Number of threads to use. If set to auto, the ideal thread count is used.

--cpu-affinity cores: Set CPU affinity with the number of CPUs available for each worker core.

--experimental-thread-balancer: Balances new connections to threads using round‐robin.

Sockets

--h1, --http-socket <address>:port: Bind to the specified TCP socket using HTTP protocol. To bind to all interfaces, simply only provide the port. Can be used multiple times to add multiple sockets.

--upgrade-h2c: Defines if an HTTP/1 connection set with --h1 can be upgraded to H2C (HTTP 2 Clear Text).

--hs1, --https-socket <address>:port,certPath,keyPath<,algorithm>: Bind to the specified TCP socket using HTTPS protocol. This expects a comma separated list of options. address is optional, if omitted, will bind to all interfaces. certPath is the full path to the TLS certificate in PEM format. keyPath is the full path to the private TLS key in PEM. The optional last part algorithm can be either rsa or ec. If omitted, rsa will be used as defaut. Can be used multiple times to add multiple sockets.

--https-h2: Defines if HTTPS socket set with --hs1 should use ALPN to negotiate HTTP/2.

--h2, --http2-socket <address>:port: Bind to the specified TCP socket using HTTP/2 Clear Text only protocol. To bind to all interfaces, simply only provide the port. Can be used multiple times to add multiple sockets.

--http2-header-table size: Set the HTTP2 header table size. Default value: 4096.

--fastcgi-socket address: Bind to the specified UNIX/TCP socket using FastCGI protocol. Can be used multiple times to add multiple sockets.

--socket-access options: Set the LOCAL socket access, such as ’ugo’ standing for User, Group, Other access.

--chown-socket uid:gid: Chown UNIX sockets.

--reuse-port: Enable SO_REUSEPORT flag on socket (Linux 3.9+).

-z, --socket-timeout seconds: Set internal sockets timeout in seconds. Default value: 4.

-l, --listen size: Set the socket listen queue size. Default value: 100.

--using-frontend-proxy: Defines if a reverse proxy operates in front of this application server. If enabled, parses the HTTP headers X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Proto and uses this info to update Cutelyst::EngineRequest.

User and group

--uid user/uid: Setuid to the specified user/uid.

--gid group/gid: Setgid to the specified group/gid.

--no-initgroups: Disable additional groups set via initgroups().

--umask mask: Set file creation mask.

TCP settings

--tcp-nodelay: Enable TCP NODELAY on each request.

--so-keepalive: Enable TCP KEEPALIVE.

Buffer sizes

-b, --buffer-size bytes: Set internal buffer size in bytes. Default value: 4096.

--post-buffering bytes: Sets the size in bytes after which buffering takes place on the hard disk instead of in the main memory. Default value: -1.

--post-buffering-bufsize bytes: Set buffer size in bytes for read() in post buffering mode. Default value: 4096.

--socket-sndbuf bytes: Set the socket send buffer size in bytes at the OS level. This maps to the SO_SNDBUF socket option.

--socket-rcvbuf bytes: Set the socket receive buffer size in bytes at the OS level. This maps to the SO_RCVBUF socket option.

--websocket-max-size kibibytes: Maximum allowed payload size for websocket in kibibytes. Default value: 1024 KiB.

Exit status

0 on success and 1 if something failed.

Examples

Start application with HTTP socket and load INI config file:
cutelystd4-qt6 -M -a /path/to/cutelystapp.so --h1 localhost:3000 --ini /path/to/appconfig.ini

Start application with HTTPS socket on all interfaces and offer upgrade to HTTP/2:
cutelystd4-qt6 -M -a /path/to/cutelystapp.so --hs1 :3000,/path/to/cert.pem,/path/to/rsakey.pem --https-h2

Start application on local FastCGI socket and protect socket file:
cutelystd4-qt6 -M -a /path/to/cutelystapp.so --fastcgi‐socket /run/cutelystapp.sock --chown‐socket myuser:www --socket‐access ug --uid myuser

Start application on local FastCGI socket and store PID in file:
cutelystd4-qt6 -M -a /path/to/cutelystapp.so --fastcgi‐socket /run/cutelystapp.sock --pidfile /run/cutelystapp.pid

Stop application using pid file:
cutelystd4-qt6 --stop /run/cutelystapp.pid

Table of Contents