Collaboration diagram for context and vhost related functions:

Topics
	Vhost mounts and options

Data Structures
struct	lws_context_creation_info
struct	lws_lejp_conf_defs
struct	lws_protocol_vhost_options

Macros
#define	LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT
#define	LWS_SERVER_OPTION_SKIP_SERVER_CANONICAL_NAME (1ll << 2)
#define	LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT
#define	LWS_SERVER_OPTION_LIBEV (1ll << 4)
#define	LWS_SERVER_OPTION_DISABLE_IPV6 (1ll << 5)
#define	LWS_SERVER_OPTION_DISABLE_OS_CA_CERTS (1ll << 6)
#define	LWS_SERVER_OPTION_PEER_CERT_NOT_REQUIRED (1ll << 7)
#define	LWS_SERVER_OPTION_VALIDATE_UTF8 (1ll << 8)
#define	LWS_SERVER_OPTION_SSL_ECDH
#define	LWS_SERVER_OPTION_LIBUV (1ll << 10)
#define	LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS
#define	LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT (1ll << 12)
#define	LWS_SERVER_OPTION_EXPLICIT_VHOSTS (1ll << 13)
#define	LWS_SERVER_OPTION_UNIX_SOCK (1ll << 14)
#define	LWS_SERVER_OPTION_STS (1ll << 15)
#define	LWS_SERVER_OPTION_IPV6_V6ONLY_MODIFY (1ll << 16)
#define	LWS_SERVER_OPTION_IPV6_V6ONLY_VALUE (1ll << 17)
#define	LWS_SERVER_OPTION_UV_NO_SIGSEGV_SIGFPE_SPIN (1ll << 18)
#define	LWS_SERVER_OPTION_JUST_USE_RAW_ORIGIN (1ll << 19)
#define	LWS_SERVER_OPTION_FALLBACK_TO_RAW /* use below name */ (1ll << 20)
#define	LWS_SERVER_OPTION_FALLBACK_TO_APPLY_LISTEN_ACCEPT_CONFIG (1ll << 20)
#define	LWS_SERVER_OPTION_LIBEVENT (1ll << 21)
#define	LWS_SERVER_OPTION_ONLY_RAW /* Use below name instead */ (1ll << 22)
#define	LWS_SERVER_OPTION_ADOPT_APPLY_LISTEN_ACCEPT_CONFIG (1ll << 22)
#define	LWS_SERVER_OPTION_ALLOW_LISTEN_SHARE (1ll << 23)
#define	LWS_SERVER_OPTION_CREATE_VHOST_SSL_CTX (1ll << 24)
#define	LWS_SERVER_OPTION_SKIP_PROTOCOL_INIT (1ll << 25)
#define	LWS_SERVER_OPTION_IGNORE_MISSING_CERT (1ll << 26)
#define	LWS_SERVER_OPTION_VHOST_UPG_STRICT_HOST_CHECK (1ll << 27)
#define	LWS_SERVER_OPTION_HTTP_HEADERS_SECURITY_BEST_PRACTICES_ENFORCE (1ll << 28)
#define	LWS_SERVER_OPTION_ALLOW_HTTP_ON_HTTPS_LISTENER (1ll << 29)
#define	LWS_SERVER_OPTION_FAIL_UPON_UNABLE_TO_BIND (1ll << 30)
#define	LWS_SERVER_OPTION_H2_JUST_FIX_WINDOW_UPDATE_OVERFLOW (1ll << 31)
#define	LWS_SERVER_OPTION_VH_H2_HALF_CLOSED_LONG_POLL (1ll << 32)
#define	LWS_SERVER_OPTION_DISABLE_UTF8_VALIDATION (1ll << 34)
#define	LWS_SERVER_OPTION_GLIB (1ll << 33)
#define	LWS_SERVER_OPTION_QUIC_FORCE_RETRY (1ll << 52)
#define	LWS_SERVER_OPTION_H2_PRIOR_KNOWLEDGE (1ll << 34)
#define	LWS_SERVER_OPTION_NO_LWS_SYSTEM_STATES (1ll << 35)
#define	LWS_SERVER_OPTION_SS_PROXY (1ll << 36)
#define	LWS_SERVER_OPTION_SDEVENT (1ll << 37)
#define	LWS_SERVER_OPTION_ULOOP (1ll << 38)
#define	LWS_SERVER_OPTION_DISABLE_TLS_SESSION_CACHE (1ll << 39)
#define	LWS_SERVER_OPTION_OPENSSL_AUTO_DH_PARAMETERS (1ll << 40)
#define	LWS_SERVER_OPTION_MBEDTLS_VERIFY_CLIENT_CERT_POST_HANDSHAKE
#define	LWS_SERVER_OPTION_VH_INSTANTIATE_ALL_PROTOCOLS (1ll << 42)
#define	LWS_SERVER_OPTION_VH_SKIP_PRIV_DROP (1ll << 43)
#define	LWS_SERVER_OPTION_CMDLINE_FORCE_H1 (1ll << 44)
#define	LWS_SERVER_OPTION_CMDLINE_FORCE_H2 (1ll << 45)
#define	LWS_SERVER_OPTION_CMDLINE_FORCE_H3 (1ll << 46)
#define	LWS_SERVER_OPTION_ALLOW_EARLY_DATA (1ll << 47)
#define	LWS_SERVER_OPTION_CPD_BYPASS (1ll << 48)
#define	LWS_SERVER_OPTION_QUIC_PAD_CRYPTO (1ll << 49)
#define	LWS_SERVER_OPTION_QUIC_EARLY_KEY_UPDATE (1ll << 51)
#define	LWS_SERVER_OPTION_QUIC_LATEST_VERSION (1ll << 50)
#define	LWS_SERVER_OPTION_SNI_FALLBACK (1ll << 53)
#define	LWS_SERVER_OPTION_DISABLE_IPV4 (1ll << 54)
#define	LWS_SERVER_OPTION_NO_HTTP_STREAM_COMPRESSION (1ll << 55)
#define	lws_check_opt(c, f)
#define	LWS_PT_SERV_BUF_SIZE_MAX (16u * 1024u * 1024u)
#define	LWS_FD_LIMIT_INTERNAL_NETLINK 0
#define	LWS_FD_LIMIT_INTERNAL_ADNS 0
#define	LWS_FD_LIMIT_INTERNAL_NTP 0
#define	LWS_FD_LIMIT_INTERNAL_DHCP 0
#define	LWS_FD_LIMIT_INTERNAL
#define	LWS_FD_LIMIT_PER_THREAD_MIN (LWS_FD_LIMIT_INTERNAL + 8 /* overhead */)
#define	LWS_HTTP_BODY_MIN_RATE_NONE 0xffffffffu
#define	LWS_MUX_RESET_LIMIT_NONE 0xffffu

Typedefs
typedef int(*	lws_context_ready_cb_t) (struct lws_context *context)
typedef uint64_t(*	lws_quic_tx_credit_cb_t) (struct lws *wsi, uint64_t current_window, uint64_t consumed_bytes, uint64_t time_since_last_update_us)
typedef int(*	lws_reload_func) (void)

Functions
LWS_VISIBLE LWS_EXTERN struct lws_context *	lws_create_context (const struct lws_context_creation_info *info)
LWS_VISIBLE LWS_EXTERN void	lws_context_destroy (struct lws_context *context)
LWS_VISIBLE LWS_EXTERN void	lws_tls_cleanup_process (void)
LWS_VISIBLE LWS_EXTERN void	lws_context_deprecate (struct lws_context *context, lws_reload_func cb)
LWS_VISIBLE LWS_EXTERN int	lws_context_is_deprecated (struct lws_context *context)
LWS_VISIBLE LWS_EXTERN int	lws_set_proxy (struct lws_vhost vhost, const char proxy)
LWS_VISIBLE LWS_EXTERN int	lws_set_socks (struct lws_vhost vhost, const char socks)
LWS_VISIBLE LWS_EXTERN struct lws_vhost *	lws_create_vhost (struct lws_context context, const struct lws_context_creation_info info)
LWS_VISIBLE LWS_EXTERN void	lws_vhost_destroy (struct lws_vhost *vh)
LWS_VISIBLE LWS_EXTERN int	lwsws_get_config_globals (struct lws_context_creation_info info, const char d, char *config_strings, int len)
LWS_VISIBLE LWS_EXTERN int	lwsws_get_config_globals_defs (struct lws_lejp_conf_defs defs, struct lws_context_creation_info info, const char d, char config_strings, int len)
LWS_VISIBLE LWS_EXTERN int	lwsws_get_config_vhosts (struct lws_context context, struct lws_context_creation_info info, const char d, char config_strings, int len)
LWS_VISIBLE LWS_EXTERN int	lwsws_get_config_vhosts_defs (struct lws_lejp_conf_defs defs, struct lws_context context, struct lws_context_creation_info info, const char d, char *config_strings, int len)
LWS_VISIBLE LWS_EXTERN struct lws_vhost *	lws_get_vhost (struct lws *wsi)
LWS_VISIBLE LWS_EXTERN const char *	lws_get_vhost_name (struct lws_vhost *vhost)
LWS_VISIBLE LWS_EXTERN struct lws_vhost *	lws_get_vhost_by_name (struct lws_context context, const char name)
LWS_VISIBLE LWS_EXTERN struct lws_vhost *	lws_select_vhost_sni (struct lws_vhost lv, const char servername)
LWS_VISIBLE LWS_EXTERN int	lws_get_vhost_port (struct lws_vhost *vhost)
LWS_VISIBLE LWS_EXTERN void *	lws_get_vhost_user (struct lws_vhost *vhost)
LWS_VISIBLE LWS_EXTERN const char *	lws_get_vhost_iface (struct lws_vhost *vhost)
LWS_VISIBLE LWS_EXTERN void *	lws_vhost_user (struct lws_vhost *vhost)
LWS_VISIBLE LWS_EXTERN void *	lws_context_user (struct lws_context *context)
LWS_VISIBLE LWS_EXTERN const char *	lws_vh_tag (struct lws_vhost *vh)
LWS_VISIBLE LWS_EXTERN void	_lws_context_info_defaults (struct lws_context_creation_info info, const char sspol)
LWS_VISIBLE LWS_EXTERN void	lws_default_loop_exit (struct lws_context *cx)
LWS_VISIBLE LWS_EXTERN void	lws_context_default_loop_run_destroy (struct lws_context *cx)
LWS_VISIBLE LWS_EXTERN int	lws_cmdline_passfail (int argc, const char **argv, int actual)
LWS_VISIBLE LWS_EXTERN int	lws_systemd_inherited_fd (unsigned int index, struct lws_context_creation_info *info)
LWS_VISIBLE LWS_EXTERN int	lws_context_is_being_destroyed (struct lws_context *context)

Detailed Description

Context and Vhost releated functions

LWS requires that there is one context, in which you may define multiple vhosts. Each vhost is a virtual host, with either its own listen port or sharing an existing one. Each vhost has its own SSL context that can be set up individually or left disabled.

If you don't care about multiple "site" support, you can ignore it and lws will create a single default vhost at context creation time.

Data Structure Documentation

◆ lws_context_creation_info

struct lws_context_creation_info

Definition at line 441 of file lws-context-vhost.h.

Collaboration diagram for lws_context_creation_info:

Data Fields
gid_t	gid	CONTEXT: group id to change to after setting listen socket, or -1. See also .username below.
uid_t	uid	CONTEXT: user id to change to after setting listen socket, or -1. See also .groupname below.
uint64_t	options	VHOST + CONTEXT: 0, or LWS_SERVER_OPTION_... bitfields
void *	user	VHOST + CONTEXT: optional user pointer that will be associated with the context when creating the context (and can be retrieved by lws_context_user(context), or with the vhost when creating the vhost (and can be retrieved by lws_vhost_user(vhost)). You will need to use LWS_SERVER_OPTION_EXPLICIT_VHOSTS and create the vhost separately if you care about giving the context and vhost different user pointer values.
unsigned int	count_threads	CONTEXT: how many contexts to create in an array, 0 = 1
unsigned int	fd_limit_per_thread	CONTEXT: nonzero means restrict each service thread to this many fds, 0 means the default which is divide the process fd limit by the number of threads. Note if this is nonzero, and fd_limit_per_thread multiplied by the number of service threads is less than the process ulimit, then lws restricts internal lookup table allocation to the smaller size, and switches to a less efficient lookup scheme. You should use this to trade off speed against memory usage if you know the lws context will only use a handful of fds. The count is the whole table, including the fds lws holds itself (LWS_FD_LIMIT_INTERNAL, the floor a nonzero value is raised to) and the overhead connections carry: set it to LWS_FD_LIMIT_PER_THREAD_MIN plus the connections you will have open at once. A full table stops every listener accepting until a connection closes, logged once per thread at WARN.
const char *	vhost_name	VHOST: name of vhost, must match external DNS name used to access the site, like "warmcat.com" as it's used to match Host: header and / or SNI name for SSL. CONTEXT: NULL, or the name to associate with the context for context-specific logging
void *	external_baggage_free_on_destroy	CONTEXT: NULL, or pointer to something externally malloc'd, that should be freed when the context is destroyed. This allows you to automatically sync the freeing action to the context destruction action, so there is no need for an external free() if the context succeeded to create.
unsigned int	pt_serv_buf_size	CONTEXT: 0 = default of 4096. This buffer is used by various service related features including file serving, it defines the max chunk of file that can be sent at once. At the risk of lws having to buffer failed large sends, it can be increased to, eg, 128KiB to improve throughput. Values below LWS_PRE + 1024 or above LWS_PT_SERV_BUF_SIZE_MAX (16MiB) are clamped to those limits.
void **	foreign_loops	CONTEXT: This is ignored if the context is not being started with an event loop, ie, .options has a flag like LWS_SERVER_OPTION_LIBUV. NULL indicates lws should start its own even loop for each service thread, and deal with closing the loops when the context is destroyed. Non-NULL means it points to an array of external ("foreign") event loops that are to be used in turn for each service thread. In the default case of 1 service thread, it can just point to one foreign event loop.
void()(void event_lib_handle, int signum)	signal_cb	CONTEXT: NULL: default signal handling. Otherwise this receives the signal handler callback. event_lib_handle is the native event library signal handle, eg uv_signal_t * for libuv.
struct lws_context **	pcontext	CONTEXT: if non-NULL, at the end of context destroy processing, the pointer pointed to by pcontext is written with NULL. You can use this to let foreign event loops know that lws context destruction is fully completed.
void()(struct lws_vhost vh, void *arg)	finalize	VHOST: NULL, or pointer to function that will be called back when the vhost is just about to be freed. The arg parameter will be set to whatever finalize_arg is below.
void *	finalize_arg	VHOST: opaque pointer lws ignores but passes to the finalize callback. If you don't care, leave it NULL.
const char *	listen_accept_role	VHOST: NULL for default, or force accepted incoming connections to bind to this role. Uses the role names from their ops struct, eg, "raw-skt".
const char *	listen_accept_protocol	VHOST: NULL for default, or force accepted incoming connections to bind to this vhost protocol name.
const struct lws_protocols **	pprotocols	VHOST: NULL: use .protocols, otherwise ignore .protocols and use this array of pointers to protocols structs. The end of the array is marked by a NULL pointer. This is preferred over .protocols, because it allows the protocol struct to be opaquely defined elsewhere, with just a pointer to it needed to create the context with it. .protocols requires also the type of the user data to be known so its size can be given.
const char *	username	CONTEXT: string username for post-init permissions. Like .uid but takes a string username.
const char *	groupname	CONTEXT: string groupname for post-init permissions. Like .gid but takes a string groupname.
const char *	unix_socket_perms	VHOST: if your vhost is listening on a unix socket, you can give a "username:groupname" string here to control the owner:group it's created with. It's always created with 0660 mode.
const lws_system_ops_t *	system_ops	CONTEXT: hook up lws_system_ apis to system-specific implementations
const lws_retry_bo_t *	retry_and_idle_policy	VHOST: optional retry and idle policy to apply to this vhost. Currently only the idle parts are applied to the connections.
int	rlimit_nofile	0 = inherit the initial ulimit for files / sockets from the startup environment. Nonzero = try to set the limit for this process.
int	fo_listen_queue	VHOST: 0 = no TCP_FASTOPEN, nonzero = enable TCP_FASTOPEN if the platform supports it, with the given queue length for the listen socket.
const struct lws_plugin_evlib *	event_lib_custom	CONTEXT: If non-NULL, override event library selection so it uses this custom event library implementation, instead of default internal loop. Don't set any other event lib context creation flags in that case. it will be used automatically. This is useful for integration where an existing application is using its own handrolled event loop instead of an event library, it provides a way to allow lws to use the custom event loop natively as if it were an "event library".
lws_log_cx_t *	log_cx	CONTEXT: NULL to use the default, process-scope logging context, else a specific logging context to associate with this context
int	default_loglevel	CONTEXT: 0 for LLL_USER, LLL_ERR, LLL_WARN, LLL_NOTICE enabled by default when using lws_cmdline_option_handle_builtin(), else set to the LLL_ flags you want to be the default before calling lws_cmdline_option_handle_builtin(). Your selected default loglevel can then be cleanly overridden using -d 1039 etc commandline switch
lws_sockfd_type	vh_listen_sockfd	VHOST: 0 for normal vhost listen socket fd creation, if any. Nonzero to force the selection of an already-existing fd for the vhost's listen socket, which is already prepared. This is intended for an external process having chosen the fd, which cannot then be zero.
const char *	lws_stub	CONTEXT: if non-NULL, the name of the stub function requested via –lws-stub=... commandline switch. Filled in by lws_cmdline_option_handle_builtin().
int	argc	CONTEXT: optionally pass the app commandline to the context, so we can use it as part of lws_cmdline_option_cx()
const char **	argv	CONTEXT: optionally pass the app commandline to the context, so we can use it as part of lws_cmdline_option_cx()
uint8_t	client_ssl_ctx_unshared	VHOST: 0 (default) lets this vhost's client tls ctx be shared with other vhosts whose client tls configuration is identical (the OpenSSL and OpenHiTLS backends do this, to save the memory of a copy of the OS trust store per vhost). Nonzero gives the vhost a client tls ctx of its own. Set it if you will add trust to the vhost after creating it with lws_tls_client_vhost_extra_cert_mem(), which refuses to add to a ctx that another vhost is sharing: the other vhost would trust the cert too.
unsigned int	http_response_stall_secs	VHOST: 0 for default (.timeout_secs, but at least 30), or the seconds a server's response may go without any more of it being sent, eg, because the peer stopped reading it, before it is given up on. It bounds the stall, not the response: each piece sent starts it again, however long the whole response takes. A browser saving a big download to a slow device can stop reading for minutes while it drains its cache, and so can the server side of a proxy in front of us, while its own peer does that. A larger value lets those through, at the price of a peer that never reads holding its connection, and eg, an open file, for that long. Immortal streams (eg, long polls) are not limited.
uint32_t	quic_mtu	VHOST: 0 for default (1280), or the desired QUIC MTU for the vhost
lws_quic_tx_credit_cb_t	quic_tx_credit_cb	VHOST: Callback for dynamic QUIC TX credit window scaling. If NULL, defaults to 50% refill batched logic.
const struct lws_cc_ops *	quic_cc_ops	CONTEXT: QUIC congestion control algorithm ops to use. If NULL, defaults to &lws_cc_ops_newreno.
const char *	quic_preferred_addresses	VHOST: Comma-separated list of IPv4 and/or IPv6 preferred addresses (e.g., "1.2.3.4:443,[2001:db8::1]:443") to send to the client during the handshake to facilitate Connection Migration.
uint32_t	quic_initial_cwnd	CONTEXT: 0 for default (10 * MTU), or the desired initial congestion window in bytes
uint32_t	quic_0rtt_max_size	CONTEXT: 0 for default (16384), or the most early data a tls over tcp server lets a client send as 0-RTT (gnutls). A QUIC server always advertises 0xffffffff, as RFC 9001 requires: QUIC's 0-RTT is bounded by its flow control instead
uint32_t	quic_rx_window	CONTEXT: 0 for default (1MB, or 32KB on FreeRTOS), or the receive flow control window QUIC gives each stream and connection, up to 16MB. The peer may send all of it before we consume any, so on small devices it should be small
uint64_t	max_http_body_size	VHOST: 0 for default (100MB), or the desired max HTTP body size
const struct lws_io_ops *	io_ops	CONTEXT: NULL for lws's own IO half, or the requests of IO supplied by an embedder of the sansIO half (see lws-io-ops.h)
const struct lws_plugin_protocol const	plugins	CONTEXT: NULL, or a NULL-terminated array of protocol plugin exports the application composed into itself, by building the plugin's source in rather than having lws dlopen it or build it in. lws treats them as it treats the plugins it finds itself: their .init and .deinit are called once for the context, and a builtin or dlopened plugin of the same hdr.name is not used at all, the application's copy wins. Their protocols are given to vhosts as usual, in the vhost's info->pprotocols or info->protocols. The array and what it points to must outlive the context.
const char *	ss_proxy_perms	CONTEXT: for an SS proxy listening on a Unix Domain Socket (lws_ss_proxy_create() with port 0), who may connect to it and use it. NULL (the default): only the proxy's own user, a process whose primary group is the proxy's group, or root. The ids are .uid / .gid (or .username / .groupname) if given, else the process's effective ids. "user:group": only that user, a process whose primary group is that group, or root. A socket in the filesystem is also created owned by user:group with mode 0660. "*": any local process. Only use this if every process that can reach the socket may use the proxy and its policy. A socket in the Linux abstract namespace, like the default "@proxy.ss.lws", has no filesystem permissions, so the proxy checks each client's credentials (SO_PEERCRED) against the above. For a socket in the filesystem, its permissions control access instead; without "user:group" they are as for any lws Unix Domain Socket vhost (see .unix_socket_perms). A proxy listening on tcp has no peer check at all, see .ss_proxy_tcp_allow_remote.
uint32_t	tls_cert_grace_secs	VHOST: a tls server vhost whose cert and key are files (.ssl_cert_filepath, .ssl_private_key_filepath) notices them being renewed on disk, eg, by a symlink moving onto new files, and switches to the new ones without disturbing its connections. The new pair is loaded as soon as it is seen: this is how long after the new cert was issued or written, whichever is later, the vhost waits before serving it. 0 serves it at once. A cert published in DNS for DANE should wait for the new record to have replaced cached copies of the old one. Renewals handed to lws_tls_cert_updated() wait the same way. A restart serves the newest pair at once.
const char *	tls_passthrough	VHOST: NULL, or "host:port" ("[v6addr]:port" for an IPv6 literal) of a server this vhost's TLS connections are passed to as they are, without being decrypted, so the server terminates the TLS itself. The vhost is chosen as usual by the SNI name in the ClientHello, from the vhost names on the listener, and needs no certificate, mounts or protocols of its own. The connection's first bytes are only looked at, not consumed, so a connection that is not for such a vhost goes on to the listener's own TLS as if nothing had happened. Needs LWS_WITH_TLS_PASSTHROUGH.
uint8_t	tls_passthrough_proxy_v2	VHOST: with .tls_passthrough, nonzero to tell the server who the client is in a PROXY v2 header (see lws-proxy-v2.h) before its bytes, along with the SNI name it asked for. The server must then expect one from us, eg, with .proxy_v2_trusted.
const char *	proxy_v2_trusted	VHOST: NULL, or a comma-separated list of numeric addresses or CIDR netblocks of proxies, eg, a tls passthrough, that send a PROXY v2 header ahead of the connections they forward to this vhost's listener. A connection from one of them must start with exactly one valid header, or it is dropped, and the client it names is then the connection's peer address as lws reports it, eg, from lws_get_peer_simple(). A connection from anywhere else is never looked at for one, so nobody else can claim to be somebody they are not. That holds for TCP, whose handshake proves where a connection is from. A datagram's source is whatever its sender wrote, so on a QUIC listener, a header in a datagram from a trusted address is only hearsay: lws_peer_walk() shows the client as a LWS_PEER_KIND_RELAY claim above the relay, both hearsay until the client's QUIC connection validates its address through that relay, and only that proves the relay. Hearsay never moves a proven relay nor pushes it out, but it can still make the listener spend work on Initials and remember unproven clients, as anyone sending Initials can, and it can disturb a client's handshake before it is proven: prefer a path to the relay that its address cannot be spoofed on, eg, loopback or a private link. The list applies to every vhost sharing the listener. With LWS_WITH_PEER_LIMITS, ip_limit_wsi and ip_limit_ah apply to the client named too, and a LOCAL header's connection to the proxy itself; until its header has been read, a proxy's connection counts against nobody. Needs LWS_WITH_TLS_PASSTHROUGH.
uint32_t	quic_max_idle_timeout_ms	VHOST: 0 for default (30000), or the max_idle_timeout in ms this vhost's QUIC connections advertise to their peer, as servers and as clients. A connection is closed silently (RFC 9000 10.1) once it has been idle for the shorter of this and the peer's own value (but at least three PTOs): nothing arrived from the peer, and we sent it nothing it has to acknowledge, for that long. It is a property of the transport, whatever streams are open: a peer keeps a quiet connection by sending something, eg, PING.
unsigned int	max_http_header_pool_per_mux	CONTEXT: 0 for default, or how many of a thread's request header tables (ahs, see .max_http_header_pool) the streams of one h2 or h3 server connection may hold at once while they wait on the peer. A stream holds one from its HEADERS until its request is dispatched, or, for a request with a body, until all of its body has arrived. Streams the peer has finished sending on, eg, GETs waiting to be dispatched, don't count, and are never refused for it. A new stream with more to come over the limit is refused on its own, with RST_STREAM REFUSED_STREAM on h2 or H3_REQUEST_REJECTED on h3, which tell the client it may retry; the connection and its other streams go on. Without a limit, a few connections opening many streams whose bodies never finish could hold the whole pool, and nobody else's request could be read. The default is one less than the pool's ahs per fd of the thread, but at least 8, since clients (lws' own among them) commonly send several uploads on one connection at once and do not retry a refused stream. With the default pool, 4 ahs per fd, that is 8: connections then need nearly half the fds to fill the pool, each keeping 8 bodies coming at .http_body_min_rate. 3 or less makes that need every fd, as on h1, at the price of refusing a fourth concurrent upload on a connection.
uint32_t	http_body_min_rate	VHOST: 0 for default (500), the slowest a request body may arrive on average, in bytes per second, or LWS_HTTP_BODY_MIN_RATE_NONE for no limit beyond .timeout_secs between its pieces. The body has .http_body_grace_secs from its request's headers, plus a second for each .http_body_min_rate bytes of it taken so far: one falling behind that is given up on as for a timeout, which resets an h2 or h3 stream, giving back what it holds, or closes an h1 connection. Each piece still has to come within .timeout_secs of the last. Without it, a peer trickling a byte of body every few seconds holds its request, and its header table, for as long as it likes. The default, like Apache httpd's mod_reqtimeout MinRate, cuts no upload of any size going faster than 4 kbit/s. Time the server itself is not taking the body counts too, eg, while rx flow control is off, or a cgi or the onward connection of a proxy mount is slow to take it. Immortal streams (eg, long polls) are not limited.
uint16_t	http_body_grace_secs	VHOST: 0 for default (20), or the seconds a request body has before .http_body_min_rate starts to count against it
uint16_t	mux_reset_limit	VHOST: 0 for default (200), the most streams of one h2 or h3 server connection that may end before they are answered, on average per .mux_reset_window_secs, or LWS_MUX_RESET_LIMIT_NONE for no limit. What counts is the peer resetting a stream we had not finished answering (h2 RST_STREAM, h3 RESET_STREAM or STOP_SENDING on a request stream), and us resetting one for any reason but having answered it (eg, a protocol error on it, its body coming too slowly, the app abandoning it), other than refusing it for want of a header table (see .max_http_header_pool_per_mux). A burst of up to the limit is allowed, and room for more comes back at the limit per window. Going over it ends the connection, with GOAWAY ENHANCE_YOUR_CALM on h2 or H3_EXCESSIVE_LOAD on h3. The concurrent stream limit counts only live streams, so without this a peer that resets each request as soon as it is dispatched, and sends the next, has requests dispatched, and their work started, as fast as the server can read them ("rapid reset", CVE-2023-44487). Browsers reset streams too, eg, the requests of a page left before it finished loading, but nothing like 200 every 10s on one connection.
uint16_t	mux_reset_window_secs	VHOST: 0 for default (10), the seconds .mux_reset_limit is per
uint8_t	ss_proxy_tcp_allow_remote	CONTEXT: 0 (the default), or 1 to let an SS proxy listening on tcp (lws_ss_proxy_create() with a port) bind to an address that is not loopback, eg, for clients in containers or VMs. The tcp link has no client authentication: anybody who can reach the port can create any client streamtype in the proxy's policy, set its metadata and send payload, and the proxy fulfils it with whatever the policy binds to it, the system auth token, client certificates, signing keys, cookies. So by default the listener is bound to loopback (127.0.0.1, or ::1 without IPv4) when no .ss_proxy_bind is given, and a bind that is not a numeric loopback address is refused. Only set this where the network the listener is reachable from is itself trusted, eg, firewalled to the intended clients; lws warns about it when the proxy starts.
void *	_unused[1]	dummy

◆ lws_lejp_conf_defs

struct lws_lejp_conf_defs

struct lws_lejp_conf_defs - carrier for install-wide JSON conf defines

Zero the struct to initialize it, pass it to lwsws_get_config_globals_defs() and then to lwsws_get_config_vhosts_defs(), and destroy it with lwsac_free(&defs->ac) once all the config files have been walked. Defines created in the "global" section of files walked by lwsws_get_config_globals_defs() accumulate here, and stay visible (but cannot be added to) in all files walked by lwsws_get_config_vhosts_defs().

Definition at line 1765 of file lws-context-vhost.h.

Collaboration diagram for lws_lejp_conf_defs:

Data Fields
struct lwsac *	ac
lws_dll2_owner_t	owner

◆ lws_protocol_vhost_options

struct lws_protocol_vhost_options

struct lws_protocol_vhost_options - linked list of per-vhost protocol name=value options

This provides a general way to attach a linked-list of name=value pairs, which can also have an optional child link-list using the options member.

Definition at line 2092 of file lws-context-vhost.h.

Collaboration diagram for lws_protocol_vhost_options:

Data Fields
const struct lws_protocol_vhost_options *	next	linked list
const struct lws_protocol_vhost_options *	options	child linked-list of more options for this node
const char *	name	name of name=value pair
const char *	value	value of name=value pair

Macro Definition Documentation

◆ LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT

#define LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT

wsi	The stream wsi, or the network wsi for connection-level flow control
current_window	The current window size (rx_window_size)
consumed_bytes	The number of bytes the application just consumed
time_since_last_update_us	Microseconds since the window was last scaled or initialized

LWS_VISIBLE LWS_EXTERN void lws_context_deprecate	(	struct lws_context *	context,
		lws_reload_func	cb )

LWS_VISIBLE LWS_EXTERN int lws_set_proxy	(	struct lws_vhost *	vhost,
		const char *	proxy )

vhost	pointer to struct lws_vhost you want set proxy for
proxy	pointer to c string containing proxy in format address:port

LWS_VISIBLE LWS_EXTERN int lws_set_socks	(	struct lws_vhost *	vhost,
		const char *	socks )

vhost	pointer to struct lws_vhost you want set socks for
socks	pointer to c string containing socks in format address:port

context	pointer to result of lws_create_context()
info	pointer to struct with parameters

LWS_VISIBLE LWS_EXTERN int lwsws_get_config_globals	(	struct lws_context_creation_info *	info,
		const char *	d,
		char **	config_strings,
		int *	len )

info	pointer to struct with parameters
d	filepath of the config file
config_strings	storage for the config strings extracted from JSON, the pointer is incremented as strings are stored
len	pointer to the remaining length left in config_strings the value is decremented as strings are stored

LWS_VISIBLE LWS_EXTERN int lwsws_get_config_globals_defs	(	struct lws_lejp_conf_defs *	defs,
		struct lws_context_creation_info *	info,
		const char *	d,
		char **	config_strings,
		int *	len )

defs	caller's install-wide defines container, zeroed to initialize; defines created in the "global" section of the walked files accumulate into it
info	pointer to struct with parameters
d	filepath of the config file
config_strings	storage for the config strings extracted from JSON, the pointer is incremented as strings are stored
len	pointer to the remaining length left in config_strings the value is decremented as strings are stored

defs	caller's install-wide defines container previously filled by lwsws_get_config_globals_defs(); the defines in it are visible (read-only) in every walked file
context	pointer to result of lws_create_context()
info	pointer to struct with parameters
d	filepath of the config file
config_strings	storage for the config strings extracted from JSON, the pointer is incremented as strings are stored
len	pointer to the remaining length left in config_strings the value is decremented as strings are stored

context	the lws_context to look in
name	vhost name we are looking for

lv	the vhost that accepted the connection
servername	the SNI name the peer sent, NUL-terminated

LWS_VISIBLE LWS_EXTERN void _lws_context_info_defaults	(	struct lws_context_creation_info *	info,
		const char *	sspol )

info	the creation info struct to initialize
sspol	the Secure Streams JSON policy to use, or NULL

LWS_VISIBLE LWS_EXTERN int lws_cmdline_passfail	(	int	argc,
		const char **	argv,
		int	actual )

LWS_VISIBLE LWS_EXTERN int lws_systemd_inherited_fd	(	unsigned int	index,
		struct lws_context_creation_info *	info )

index	0+ index of exported fd
info	info struct to be prepared with related info, if any

Topics

Data Structures

Macros

Typedefs

Functions

Detailed Description

Context and Vhost releated functions

Data Structure Documentation

◆ lws_context_creation_info

◆ lws_lejp_conf_defs

◆ lws_protocol_vhost_options

Macro Definition Documentation

◆ LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT

◆ LWS_SERVER_OPTION_SKIP_SERVER_CANONICAL_NAME

◆ LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT

◆ LWS_SERVER_OPTION_LIBEV

◆ LWS_SERVER_OPTION_DISABLE_IPV6

◆ LWS_SERVER_OPTION_DISABLE_OS_CA_CERTS

◆ LWS_SERVER_OPTION_PEER_CERT_NOT_REQUIRED

◆ LWS_SERVER_OPTION_VALIDATE_UTF8

◆ LWS_SERVER_OPTION_SSL_ECDH

◆ LWS_SERVER_OPTION_LIBUV

◆ LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS

◆ LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT

◆ LWS_SERVER_OPTION_EXPLICIT_VHOSTS

◆ LWS_SERVER_OPTION_UNIX_SOCK

◆ LWS_SERVER_OPTION_STS

◆ LWS_SERVER_OPTION_IPV6_V6ONLY_MODIFY

◆ LWS_SERVER_OPTION_IPV6_V6ONLY_VALUE

◆ LWS_SERVER_OPTION_UV_NO_SIGSEGV_SIGFPE_SPIN

◆ LWS_SERVER_OPTION_JUST_USE_RAW_ORIGIN

◆ LWS_SERVER_OPTION_FALLBACK_TO_RAW

◆ LWS_SERVER_OPTION_FALLBACK_TO_APPLY_LISTEN_ACCEPT_CONFIG

◆ LWS_SERVER_OPTION_LIBEVENT

◆ LWS_SERVER_OPTION_ONLY_RAW

◆ LWS_SERVER_OPTION_ADOPT_APPLY_LISTEN_ACCEPT_CONFIG

◆ LWS_SERVER_OPTION_ALLOW_LISTEN_SHARE

◆ LWS_SERVER_OPTION_CREATE_VHOST_SSL_CTX

◆ LWS_SERVER_OPTION_SKIP_PROTOCOL_INIT

◆ LWS_SERVER_OPTION_IGNORE_MISSING_CERT

◆ LWS_SERVER_OPTION_VHOST_UPG_STRICT_HOST_CHECK

◆ LWS_SERVER_OPTION_HTTP_HEADERS_SECURITY_BEST_PRACTICES_ENFORCE

◆ LWS_SERVER_OPTION_ALLOW_HTTP_ON_HTTPS_LISTENER

◆ LWS_SERVER_OPTION_FAIL_UPON_UNABLE_TO_BIND

◆ LWS_SERVER_OPTION_H2_JUST_FIX_WINDOW_UPDATE_OVERFLOW

◆ LWS_SERVER_OPTION_VH_H2_HALF_CLOSED_LONG_POLL

◆ LWS_SERVER_OPTION_DISABLE_UTF8_VALIDATION

◆ LWS_SERVER_OPTION_GLIB

◆ LWS_SERVER_OPTION_QUIC_FORCE_RETRY

◆ LWS_SERVER_OPTION_H2_PRIOR_KNOWLEDGE

◆ LWS_SERVER_OPTION_NO_LWS_SYSTEM_STATES

◆ LWS_SERVER_OPTION_SS_PROXY

◆ LWS_SERVER_OPTION_SDEVENT

◆ LWS_SERVER_OPTION_ULOOP

◆ LWS_SERVER_OPTION_DISABLE_TLS_SESSION_CACHE

◆ LWS_SERVER_OPTION_OPENSSL_AUTO_DH_PARAMETERS

◆ LWS_SERVER_OPTION_MBEDTLS_VERIFY_CLIENT_CERT_POST_HANDSHAKE

◆ LWS_SERVER_OPTION_VH_INSTANTIATE_ALL_PROTOCOLS

◆ LWS_SERVER_OPTION_VH_SKIP_PRIV_DROP

◆ LWS_SERVER_OPTION_CMDLINE_FORCE_H1

◆ LWS_SERVER_OPTION_CMDLINE_FORCE_H2

◆ LWS_SERVER_OPTION_CMDLINE_FORCE_H3

◆ LWS_SERVER_OPTION_ALLOW_EARLY_DATA

◆ LWS_SERVER_OPTION_CPD_BYPASS

◆ LWS_SERVER_OPTION_QUIC_PAD_CRYPTO

◆ LWS_SERVER_OPTION_QUIC_EARLY_KEY_UPDATE

◆ LWS_SERVER_OPTION_QUIC_LATEST_VERSION

◆ LWS_SERVER_OPTION_SNI_FALLBACK

◆ LWS_SERVER_OPTION_DISABLE_IPV4

◆ LWS_SERVER_OPTION_NO_HTTP_STREAM_COMPRESSION

◆ lws_check_opt

◆ LWS_PT_SERV_BUF_SIZE_MAX

◆ LWS_FD_LIMIT_INTERNAL_NETLINK

◆ LWS_FD_LIMIT_INTERNAL_ADNS

◆ LWS_FD_LIMIT_INTERNAL_NTP

◆ LWS_FD_LIMIT_INTERNAL_DHCP

◆ LWS_FD_LIMIT_INTERNAL

◆ LWS_FD_LIMIT_PER_THREAD_MIN

◆ LWS_HTTP_BODY_MIN_RATE_NONE

◆ LWS_MUX_RESET_LIMIT_NONE