libwebsockets
Lightweight C library for HTML5 websockets
lws-context-vhost.h
Go to the documentation of this file.
1
/*
2
* libwebsockets - small server side websockets and web server implementation
3
*
4
* Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
5
*
6
* Permission is hereby granted, free of charge, to any person obtaining a copy
7
* of this software and associated documentation files (the "Software"), to
8
* deal in the Software without restriction, including without limitation the
9
* rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10
* sell copies of the Software, and to permit persons to whom the Software is
11
* furnished to do so, subject to the following conditions:
12
*
13
* The above copyright notice and this permission notice shall be included in
14
* all copies or substantial portions of the Software.
15
*
16
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22
* IN THE SOFTWARE.
23
*/
24
25
/*! \defgroup context-and-vhost context and vhost related functions
26
* ##Context and Vhost releated functions
27
* \ingroup lwsapi
28
*
29
*
30
* LWS requires that there is one context, in which you may define multiple
31
* vhosts. Each vhost is a virtual host, with either its own listen port
32
* or sharing an existing one. Each vhost has its own SSL context that can
33
* be set up individually or left disabled.
34
*
35
* If you don't care about multiple "site" support, you can ignore it and
36
* lws will create a single default vhost at context creation time.
37
*/
38
///@{
39
40
/*
41
* NOTE: These public enums are part of the abi. If you want to add one,
42
* add it at where specified so existing users are unaffected.
43
*/
44
45
46
#
define
LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT
(
(
1ll
<<
1
)
|
47
(
1ll
<<
12
)
)
48
/**< (VH) Don't allow the connection unless the client has a
49
* client cert that we recognize; provides
50
* LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT */
51
#
define
LWS_SERVER_OPTION_SKIP_SERVER_CANONICAL_NAME
(
1ll
<<
2
)
52
/**< (CTX) Don't try to get the server's hostname */
53
#
define
LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT
(
(
1ll
<<
3
)
|
54
(
1ll
<<
12
)
)
55
/**< (VH) Allow non-SSL (plaintext) connections on the same
56
* port as SSL is listening. If combined with
57
* LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS it will try to
58
* force http connections on an https listener (eg, http://x.com:443) to
59
* redirect to an explicit https connection (eg, https://x.com)
60
*/
61
#
define
LWS_SERVER_OPTION_LIBEV
(
1ll
<<
4
)
62
/**< (CTX) Use libev event loop */
63
#
define
LWS_SERVER_OPTION_DISABLE_IPV6
(
1ll
<<
5
)
64
/**< (VH) Disable IPV6 support */
65
#
define
LWS_SERVER_OPTION_DISABLE_OS_CA_CERTS
(
1ll
<<
6
)
66
/**< (VH) Don't load OS CA certs, you will need to load your
67
* own CA cert(s) */
68
#
define
LWS_SERVER_OPTION_PEER_CERT_NOT_REQUIRED
(
1ll
<<
7
)
69
/**< (VH) Accept connections with no valid Cert (eg, selfsigned) */
70
#
define
LWS_SERVER_OPTION_VALIDATE_UTF8
(
1ll
<<
8
)
71
/**< (VH) Check UT-8 correctness */
72
#
define
LWS_SERVER_OPTION_SSL_ECDH
(
(
1ll
<<
9
)
|
73
(
1ll
<<
12
)
)
74
/**< (VH) initialize ECDH ciphers */
75
#
define
LWS_SERVER_OPTION_LIBUV
(
1ll
<<
10
)
76
/**< (CTX) Use libuv event loop */
77
#
define
LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS
(
(
1ll
<<
11
)
|
78
(
1ll
<<
12
)
)
79
/**< (VH) Use an http redirect to force the client to ask for https.
80
* Notice if your http server issues the STS header and the client has
81
* ever seen that, the client will fail the http connection before it
82
* can actually do the redirect.
83
*
84
* Combine with LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS to handle, eg,
85
* http://x.com:443 -> https://x.com
86
*
87
* (deprecated: use mount redirection) */
88
#
define
LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT
(
1ll
<<
12
)
89
/**< (CTX) Initialize the SSL library at all */
90
#
define
LWS_SERVER_OPTION_EXPLICIT_VHOSTS
(
1ll
<<
13
)
91
/**< (CTX) Only create the context when calling context
92
* create api, implies user code will create its own vhosts */
93
#
define
LWS_SERVER_OPTION_UNIX_SOCK
(
1ll
<<
14
)
94
/**< (VH) Use Unix socket */
95
#
define
LWS_SERVER_OPTION_STS
(
1ll
<<
15
)
96
/**< (VH) Send Strict Transport Security header, making
97
* clients subsequently go to https even if user asked for http */
98
#
define
LWS_SERVER_OPTION_IPV6_V6ONLY_MODIFY
(
1ll
<<
16
)
99
/**< (VH) Enable LWS_SERVER_OPTION_IPV6_V6ONLY_VALUE to take effect */
100
#
define
LWS_SERVER_OPTION_IPV6_V6ONLY_VALUE
(
1ll
<<
17
)
101
/**< (VH) if set, only ipv6 allowed on the vhost */
102
#
define
LWS_SERVER_OPTION_UV_NO_SIGSEGV_SIGFPE_SPIN
(
1ll
<<
18
)
103
/**< (CTX) Libuv only: Do not spin on SIGSEGV / SIGFPE. A segfault
104
* normally makes the lib spin so you can attach a debugger to it
105
* even if it happened without a debugger in place. You can disable
106
* that by giving this option.
107
*/
108
#
define
LWS_SERVER_OPTION_JUST_USE_RAW_ORIGIN
(
1ll
<<
19
)
109
/**< For backwards-compatibility reasons, by default
110
* lws prepends "http://" to the origin you give in the client
111
* connection info struct. If you give this flag when you create
112
* the context, only the string you give in the client connect
113
* info for .origin (if any) will be used directly.
114
*/
115
#
define
LWS_SERVER_OPTION_FALLBACK_TO_RAW
/* use below name */
(
1ll
<<
20
)
116
#
define
LWS_SERVER_OPTION_FALLBACK_TO_APPLY_LISTEN_ACCEPT_CONFIG
(
1ll
<<
20
)
117
/**< (VH) if invalid http is coming in the first line, then abandon
118
* trying to treat the connection as http, and belatedly apply the
119
* .listen_accept_role / .listen_accept_protocol info struct members to
120
* the connection. If they are NULL, for backwards-compatibility the
121
* connection is bound to "raw-skt" role, and in order of priority:
122
* 1) the vh protocol with a pvo named "raw", 2) the vh protocol with a
123
* pvo named "default", or 3) protocols[0].
124
*
125
* Must be combined with LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT
126
* to work with a socket listening with tls.
127
*/
128
129
#
define
LWS_SERVER_OPTION_LIBEVENT
(
1ll
<<
21
)
130
/**< (CTX) Use libevent event loop */
131
132
#
define
LWS_SERVER_OPTION_ONLY_RAW
/* Use below name instead */
(
1ll
<<
22
)
133
#
define
LWS_SERVER_OPTION_ADOPT_APPLY_LISTEN_ACCEPT_CONFIG
(
1ll
<<
22
)
134
/**< (VH) All connections to this vhost / port are bound to the
135
* role and protocol given in .listen_accept_role /
136
* .listen_accept_protocol.
137
*
138
* If those explicit user-controlled names are NULL, for backwards-
139
* compatibility the connection is bound to "raw-skt" role, and in order
140
* of priority: 1) the vh protocol with a pvo named "raw", 2) the vh
141
* protocol with a pvo named "default", or 3) protocols[0].
142
*
143
* It's much preferred to specify the role + protocol using the
144
* .listen_accept_role and .listen_accept_protocol in the info struct.
145
*/
146
#
define
LWS_SERVER_OPTION_ALLOW_LISTEN_SHARE
(
1ll
<<
23
)
147
/**< (VH) Set to allow multiple listen sockets on one interface +
148
* address + port. The default is to strictly allow only one
149
* listen socket at a time. This is automatically selected if you
150
* have multiple service threads. Linux only.
151
*/
152
#
define
LWS_SERVER_OPTION_CREATE_VHOST_SSL_CTX
(
1ll
<<
24
)
153
/**< (VH) Force setting up the vhost SSL_CTX, even though the user
154
* code doesn't explicitly provide a cert in the info struct. It
155
* implies the user code is going to provide a cert at the
156
* LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS callback, which
157
* provides the vhost SSL_CTX * in the user parameter.
158
*/
159
#
define
LWS_SERVER_OPTION_SKIP_PROTOCOL_INIT
(
1ll
<<
25
)
160
/**< (VH) You probably don't want this. It forces this vhost to not
161
* call LWS_CALLBACK_PROTOCOL_INIT on its protocols. It's used in the
162
* special case of a temporary vhost bound to a single protocol.
163
*/
164
#
define
LWS_SERVER_OPTION_IGNORE_MISSING_CERT
(
1ll
<<
26
)
165
/**< (VH) Don't fail if the vhost TLS cert or key are missing, just
166
* continue. The vhost won't be able to serve anything, but if for
167
* example the ACME plugin was configured to fetch a cert, this lets
168
* you bootstrap your vhost from having no cert to start with.
169
*/
170
#
define
LWS_SERVER_OPTION_VHOST_UPG_STRICT_HOST_CHECK
(
1ll
<<
27
)
171
/**< (VH) On this vhost, if the connection is being upgraded, insist
172
* that there's a Host: header and that the contents match the vhost
173
* name + port (443 / 80 are assumed if no :port given based on if the
174
* connection is using TLS).
175
*
176
* By default, without this flag, on upgrade lws just checks that the
177
* Host: header was given without checking the contents... this is to
178
* allow lax hostname mappings like localhost / 127.0.0.1, and CNAME
179
* mappings like www.mysite.com / mysite.com
180
*/
181
#
define
LWS_SERVER_OPTION_HTTP_HEADERS_SECURITY_BEST_PRACTICES_ENFORCE
(
1ll
<<
28
)
182
/**< (VH) Send lws default HTTP headers recommended by Mozilla
183
* Observatory for security. This is a helper option that sends canned
184
* headers on each http response enabling a VERY strict Content Security
185
* Policy. The policy is so strict, for example it won't let the page
186
* run its own inline JS nor show images or take CSS from a different
187
* server. In many cases your JS only comes from your server as do the
188
* image sources and CSS, so that is what you want... attackers hoping
189
* to inject JS into your DOM are completely out of luck since even if
190
* they succeed, it will be rejected for execution by the browser
191
* according to the strict CSP. In other cases you have to deviate from
192
* the complete strictness, in which case don't use this flag: use the
193
* .headers member in the vhost init described in struct
194
* lws_context_creation_info instead to send the adapted headers
195
* yourself.
196
*/
197
198
#
define
LWS_SERVER_OPTION_ALLOW_HTTP_ON_HTTPS_LISTENER
(
1ll
<<
29
)
199
/**< (VH) If you really want to allow HTTP connections on a tls
200
* listener, you can do it with this combined with
201
* LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT. But this is allowing
202
* accidental loss of the security assurances provided by tls depending
203
* on the client using http when he meant https... it's not
204
* recommended.
205
*/
206
#
define
LWS_SERVER_OPTION_FAIL_UPON_UNABLE_TO_BIND
(
1ll
<<
30
)
207
/**< (VH) When instantiating a new vhost and the specified port is
208
* already in use, a null value shall be return to signal the error.
209
*/
210
211
#
define
LWS_SERVER_OPTION_H2_JUST_FIX_WINDOW_UPDATE_OVERFLOW
(
1ll
<<
31
)
212
/**< (VH) Indicates the connections using this vhost should ignore
213
* h2 WINDOW_UPDATE from broken peers and fix them up */
214
215
#
define
LWS_SERVER_OPTION_VH_H2_HALF_CLOSED_LONG_POLL
(
1ll
<<
32
)
216
/**< (VH) Tell the vhost to treat half-closed remote clients as
217
* entered into an immortal (ie, not subject to normal timeouts) long
218
* poll mode.
219
*/
220
221
#
define
LWS_SERVER_OPTION_GLIB
(
1ll
<<
33
)
222
/**< (CTX) Use glib event loop */
223
224
#
define
LWS_SERVER_OPTION_H2_PRIOR_KNOWLEDGE
(
1ll
<<
34
)
225
/**< (VH) Tell the vhost to treat plain text http connections as
226
* H2 with prior knowledge (no upgrade request involved)
227
*/
228
229
#
define
LWS_SERVER_OPTION_NO_LWS_SYSTEM_STATES
(
1ll
<<
35
)
230
/**< (CTX) Disable lws_system state, eg, because we are a secure streams
231
* proxy client that is not trying to track system state by itself. */
232
233
#
define
LWS_SERVER_OPTION_SS_PROXY
(
1ll
<<
36
)
234
/**< (VH) We are being a SS Proxy listen socket for the vhost */
235
236
#
define
LWS_SERVER_OPTION_SDEVENT
(
1ll
<<
37
)
237
/**< (CTX) Use sd-event loop */
238
239
#
define
LWS_SERVER_OPTION_ULOOP
(
1ll
<<
38
)
240
/**< (CTX) Use libubox / uloop event loop */
241
242
#
define
LWS_SERVER_OPTION_DISABLE_TLS_SESSION_CACHE
(
1ll
<<
39
)
243
/**< (VHOST) Disallow use of client tls caching (on by default) */
244
245
246
/****** add new things just above ---^ ******/
247
248
249
#
define
lws_check_opt
(
c
,
f
)
(
(
(
(
uint64_t
)
c
)
&
(
(
uint64_t
)
f
)
)
==
(
(
uint64_t
)
f
)
)
250
251
struct
lws_plat_file_ops
;
252
struct
lws_ss_policy
;
253
struct
lws_ss_plugin;
254
struct
lws_metric_policy
;
255
struct
lws_sss_ops;
256
257
typedef
int
(*
lws_context_ready_cb_t
)(
struct
lws_context *context);
258
259
#
if
defined
(
LWS_WITH_NETWORK
)
260
typedef
int
(*lws_peer_limits_notify_t)(
struct
lws_context *ctx,
261
lws_sockfd_type sockfd,
262
lws_sockaddr46 *sa46);
263
#
endif
264
265
/** struct lws_context_creation_info - parameters to create context and /or vhost with
266
*
267
* This is also used to create vhosts.... if LWS_SERVER_OPTION_EXPLICIT_VHOSTS
268
* is not given, then for backwards compatibility one vhost is created at
269
* context-creation time using the info from this struct.
270
*
271
* If LWS_SERVER_OPTION_EXPLICIT_VHOSTS is given, then no vhosts are created
272
* at the same time as the context, they are expected to be created afterwards.
273
*/
274
struct
lws_context_creation_info
{
275
#
if
defined
(
LWS_WITH_NETWORK
)
276
const
char
*
iface
;
277
/**< VHOST: NULL to bind the listen socket to all interfaces, or the
278
* interface name, eg, "eth2"
279
* If options specifies LWS_SERVER_OPTION_UNIX_SOCK, this member is
280
* the pathname of a UNIX domain socket. you can use the UNIX domain
281
* sockets in abstract namespace, by prepending an at symbol to the
282
* socket name. */
283
const
struct
lws_protocols
*
protocols
;
284
/**< VHOST: Array of structures listing supported protocols and a
285
* protocol-specific callback for each one. The list is ended with an
286
* entry that has a NULL callback pointer. SEE ALSO .pprotocols below,
287
* which gives an alternative way to provide an array of pointers to
288
* protocol structs. */
289
#
if
defined
(
LWS_ROLE_WS
)
290
const
struct
lws_extension
*
extensions
;
291
/**< VHOST: NULL or array of lws_extension structs listing the
292
* extensions this context supports. */
293
#
endif
294
#
if
defined
(
LWS_ROLE_H1
)
||
defined
(
LWS_ROLE_H2
)
295
const
struct
lws_token_limits
*
token_limits
;
296
/**< CONTEXT: NULL or struct lws_token_limits pointer which is
297
* initialized with a token length limit for each possible WSI_TOKEN_ */
298
const
char
*
http_proxy_address
;
299
/**< VHOST: If non-NULL, attempts to proxy via the given address.
300
* If proxy auth is required, use format
301
* "username:password\@server:port" */
302
const
struct
lws_protocol_vhost_options
*
headers
;
303
/**< VHOST: pointer to optional linked list of per-vhost
304
* canned headers that are added to server responses */
305
306
const
struct
lws_protocol_vhost_options
*
reject_service_keywords
;
307
/**< CONTEXT: Optional list of keywords and rejection codes + text.
308
*
309
* The keywords are checked for existing in the user agent string.
310
*
311
* Eg, "badrobot" "404 Not Found"
312
*/
313
const
struct
lws_protocol_vhost_options
*
pvo
;
314
/**< VHOST: pointer to optional linked list of per-vhost
315
* options made accessible to protocols */
316
const
char
*
log_filepath
;
317
/**< VHOST: filepath to append logs to... this is opened before
318
* any dropping of initial privileges */
319
const
struct
lws_http_mount
*
mounts
;
320
/**< VHOST: optional linked list of mounts for this vhost */
321
const
char
*
server_string
;
322
/**< CONTEXT: string used in HTTP headers to identify server
323
* software, if NULL, "libwebsockets". */
324
325
const
char
*
error_document_404
;
326
/**< VHOST: If non-NULL, when asked to serve a non-existent file,
327
* lws attempts to server this url path instead. Eg,
328
* "/404.html" */
329
int
port
;
330
/**< VHOST: Port to listen on. Use CONTEXT_PORT_NO_LISTEN to suppress
331
* listening for a client. Use CONTEXT_PORT_NO_LISTEN_SERVER if you are
332
* writing a server but you are using \ref sock-adopt instead of the
333
* built-in listener.
334
*
335
* You can also set port to 0, in which case the kernel will pick
336
* a random port that is not already in use. You can find out what
337
* port the vhost is listening on using lws_get_vhost_listen_port() */
338
339
unsigned
int
http_proxy_port
;
340
/**< VHOST: If http_proxy_address was non-NULL, uses this port */
341
unsigned
int
max_http_header_data2
;
342
/**< CONTEXT: if max_http_header_data is 0 and this
343
* is nonzero, this will be used in place of the default. It's
344
* like this for compatibility with the original short version,
345
* this is unsigned int length. */
346
unsigned
int
max_http_header_pool2
;
347
/**< CONTEXT: if max_http_header_pool is 0 and this
348
* is nonzero, this will be used in place of the default. It's
349
* like this for compatibility with the original short version:
350
* this is unsigned int length. */
351
352
int
keepalive_timeout
;
353
/**< VHOST: (default = 0 = 5s, 31s for http/2) seconds to allow remote
354
* client to hold on to an idle HTTP/1.1 connection. Timeout lifetime
355
* applied to idle h2 network connections */
356
uint32_t
http2_settings
[7];
357
/**< VHOST: if http2_settings[0] is nonzero, the values given in
358
* http2_settings[1]..[6] are used instead of the lws
359
* platform default values.
360
* Just leave all at 0 if you don't care.
361
*/
362
363
unsigned
short
max_http_header_data
;
364
/**< CONTEXT: The max amount of header payload that can be handled
365
* in an http request (unrecognized header payload is dropped) */
366
unsigned
short
max_http_header_pool
;
367
/**< CONTEXT: The max number of connections with http headers that
368
* can be processed simultaneously (the corresponding memory is
369
* allocated and deallocated dynamically as needed). If the pool is
370
* fully busy new incoming connections must wait for accept until one
371
* becomes free. 0 = allow as many ah as number of availble fds for
372
* the process */
373
374
#
endif
375
376
#
if
defined
(
LWS_WITH_TLS
)
377
const
char
*
ssl_private_key_password
;
378
/**< VHOST: NULL or the passphrase needed for the private key. (For
379
* backwards compatibility, this can also be used to pass the client
380
* cert passphrase when setting up a vhost client SSL context, but it is
381
* preferred to use .client_ssl_private_key_password for that.) */
382
const
char
*
ssl_cert_filepath
;
383
/**< VHOST: If libwebsockets was compiled to use ssl, and you want
384
* to listen using SSL, set to the filepath to fetch the
385
* server cert from, otherwise NULL for unencrypted. (For backwards
386
* compatibility, this can also be used to pass the client certificate
387
* when setting up a vhost client SSL context, but it is preferred to
388
* use .client_ssl_cert_filepath for that.)
389
*
390
* Notice you can alternatively set a single DER or PEM from a memory
391
* buffer as the vhost tls cert using \p server_ssl_cert_mem and
392
* \p server_ssl_cert_mem_len.
393
*/
394
const
char
*
ssl_private_key_filepath
;
395
/**< VHOST: filepath to private key if wanting SSL mode;
396
* if this is set to NULL but ssl_cert_filepath is set, the
397
* OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY callback is called
398
* to allow setting of the private key directly via openSSL
399
* library calls. (For backwards compatibility, this can also be used
400
* to pass the client cert private key filepath when setting up a
401
* vhost client SSL context, but it is preferred to use
402
* .client_ssl_private_key_filepath for that.)
403
*
404
* Notice you can alternatively set a DER or PEM private key from a
405
* memory buffer as the vhost tls private key using
406
* \p server_ssl_private_key_mem and \p server_ssl_private_key_mem_len.
407
*/
408
const
char
*
ssl_ca_filepath
;
409
/**< VHOST: CA certificate filepath or NULL. (For backwards
410
* compatibility, this can also be used to pass the client CA
411
* filepath when setting up a vhost client SSL context,
412
* but it is preferred to use .client_ssl_ca_filepath for that.)
413
*
414
* Notice you can alternatively set a DER or PEM CA cert from a memory
415
* buffer using \p server_ssl_ca_mem and \p server_ssl_ca_mem_len.
416
*/
417
const
char
*
ssl_cipher_list
;
418
/**< VHOST: List of valid ciphers to use ON TLS1.2 AND LOWER ONLY (eg,
419
* "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
420
* or you can leave it as NULL to get "DEFAULT" (For backwards
421
* compatibility, this can also be used to pass the client cipher
422
* list when setting up a vhost client SSL context,
423
* but it is preferred to use .client_ssl_cipher_list for that.)
424
* SEE .tls1_3_plus_cipher_list and .client_tls_1_3_plus_cipher_list
425
* for the equivalent for tls1.3.
426
*/
427
const
char
*
ecdh_curve
;
428
/**< VHOST: if NULL, defaults to initializing server with
429
* "prime256v1" */
430
const
char
*
tls1_3_plus_cipher_list
;
431
/**< VHOST: List of valid ciphers to use for incoming server connections
432
* ON TLS1.3 AND ABOVE (eg, "TLS_CHACHA20_POLY1305_SHA256" on this vhost
433
* or you can leave it as NULL to get "DEFAULT".
434
* SEE .client_tls_1_3_plus_cipher_list to do the same on the vhost
435
* client SSL_CTX.
436
*/
437
438
const
void
*
server_ssl_cert_mem
;
439
/**< VHOST: Alternative for \p ssl_cert_filepath that allows setting
440
* from memory instead of from a file. At most one of
441
* \p ssl_cert_filepath or \p server_ssl_cert_mem should be non-NULL. */
442
const
void
*
server_ssl_private_key_mem
;
443
/**< VHOST: Alternative for \p ssl_private_key_filepath allowing
444
* init from a private key in memory instead of a file. At most one
445
* of \p ssl_private_key_filepath or \p server_ssl_private_key_mem
446
* should be non-NULL. */
447
const
void
*
server_ssl_ca_mem
;
448
/**< VHOST: Alternative for \p ssl_ca_filepath allowing
449
* init from a CA cert in memory instead of a file. At most one
450
* of \p ssl_ca_filepath or \p server_ssl_ca_mem should be non-NULL. */
451
452
long
ssl_options_set
;
453
/**< VHOST: Any bits set here will be set as server SSL options */
454
long
ssl_options_clear
;
455
/**< VHOST: Any bits set here will be cleared as server SSL options */
456
int
simultaneous_ssl_restriction
;
457
/**< CONTEXT: 0 (no limit) or limit of simultaneous SSL sessions
458
* possible.*/
459
int
simultaneous_ssl_handshake_restriction
;
460
/**< CONTEXT: 0 (no limit) or limit of simultaneous SSL handshakes ongoing */
461
int
ssl_info_event_mask
;
462
/**< VHOST: mask of ssl events to be reported on LWS_CALLBACK_SSL_INFO
463
* callback for connections on this vhost. The mask values are of
464
* the form SSL_CB_ALERT, defined in openssl/ssl.h. The default of
465
* 0 means no info events will be reported.
466
*/
467
unsigned
int
server_ssl_cert_mem_len
;
468
/**< VHOST: Server SSL context init: length of server_ssl_cert_mem in
469
* bytes */
470
unsigned
int
server_ssl_private_key_mem_len
;
471
/**< VHOST: length of \p server_ssl_private_key_mem in memory */
472
unsigned
int
server_ssl_ca_mem_len
;
473
/**< VHOST: length of \p server_ssl_ca_mem in memory */
474
475
const
char
*
alpn
;
476
/**< CONTEXT: If non-NULL, default list of advertised alpn, comma-
477
* separated
478
*
479
* VHOST: If non-NULL, per-vhost list of advertised alpn, comma-
480
* separated
481
*/
482
483
484
#
if
defined
(
LWS_WITH_CLIENT
)
485
const
char
*
client_ssl_private_key_password
;
486
/**< VHOST: Client SSL context init: NULL or the passphrase needed
487
* for the private key */
488
const
char
*
client_ssl_cert_filepath
;
489
/**< VHOST: Client SSL context init: The certificate the client
490
* should present to the peer on connection */
491
const
void
*
client_ssl_cert_mem
;
492
/**< VHOST: Client SSL context init: client certificate memory buffer or
493
* NULL... use this to load client cert from memory instead of file */
494
unsigned
int
client_ssl_cert_mem_len
;
495
/**< VHOST: Client SSL context init: length of client_ssl_cert_mem in
496
* bytes */
497
const
char
*
client_ssl_private_key_filepath
;
498
/**< VHOST: Client SSL context init: filepath to client private key
499
* if this is set to NULL but client_ssl_cert_filepath is set, you
500
* can handle the LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS
501
* callback of protocols[0] to allow setting of the private key directly
502
* via tls library calls */
503
const
void
*
client_ssl_key_mem
;
504
/**< VHOST: Client SSL context init: client key memory buffer or
505
* NULL... use this to load client key from memory instead of file */
506
const
char
*
client_ssl_ca_filepath
;
507
/**< VHOST: Client SSL context init: CA certificate filepath or NULL */
508
const
void
*
client_ssl_ca_mem
;
509
/**< VHOST: Client SSL context init: CA certificate memory buffer or
510
* NULL... use this to load CA cert from memory instead of file */
511
512
const
char
*
client_ssl_cipher_list
;
513
/**< VHOST: Client SSL context init: List of valid ciphers to use (eg,
514
* "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
515
* or you can leave it as NULL to get "DEFAULT" */
516
const
char
*
client_tls_1_3_plus_cipher_list
;
517
/**< VHOST: List of valid ciphers to use for outgoing client connections
518
* ON TLS1.3 AND ABOVE on this vhost (eg,
519
* "TLS_CHACHA20_POLY1305_SHA256") or you can leave it as NULL to get
520
* "DEFAULT".
521
*/
522
523
long
ssl_client_options_set
;
524
/**< VHOST: Any bits set here will be set as CLIENT SSL options */
525
long
ssl_client_options_clear
;
526
/**< VHOST: Any bits set here will be cleared as CLIENT SSL options */
527
528
529
unsigned
int
client_ssl_ca_mem_len
;
530
/**< VHOST: Client SSL context init: length of client_ssl_ca_mem in
531
* bytes */
532
unsigned
int
client_ssl_key_mem_len
;
533
/**< VHOST: Client SSL context init: length of client_ssl_key_mem in
534
* bytes */
535
536
#
endif
537
538
#
if
!
defined
(
LWS_WITH_MBEDTLS
)
539
SSL_CTX
*
provided_client_ssl_ctx
;
540
/**< CONTEXT: If non-null, swap out libwebsockets ssl
541
* implementation for the one provided by provided_ssl_ctx.
542
* Libwebsockets no longer is responsible for freeing the context
543
* if this option is selected. */
544
#
else
/* WITH_MBEDTLS */
545
const
char
*
mbedtls_client_preload_filepath
;
546
/**< CONTEXT: If NULL, no effect. Otherwise it should point to a
547
* filepath where every created client SSL_CTX is preloaded from the
548
* system trust bundle.
549
*
550
* This sets a processwide variable that affects all contexts.
551
*
552
* Requires that the mbedtls provides mbedtls_x509_crt_parse_file(),
553
* else disabled.
554
*/
555
#
endif
556
#
endif
557
558
int
ka_time
;
559
/**< CONTEXT: 0 for no TCP keepalive, otherwise apply this keepalive
560
* timeout to all libwebsocket sockets, client or server */
561
int
ka_probes
;
562
/**< CONTEXT: if ka_time was nonzero, after the timeout expires how many
563
* times to try to get a response from the peer before giving up
564
* and killing the connection */
565
int
ka_interval
;
566
/**< CONTEXT: if ka_time was nonzero, how long to wait before each ka_probes
567
* attempt */
568
unsigned
int
timeout_secs
;
569
/**< VHOST: various processes involving network roundtrips in the
570
* library are protected from hanging forever by timeouts. If
571
* nonzero, this member lets you set the timeout used in seconds.
572
* Otherwise a default timeout is used. */
573
unsigned
int
connect_timeout_secs
;
574
/**< VHOST: client connections have this long to find a working server
575
* from the DNS results, or the whole connection times out. If zero,
576
* a default timeout is used */
577
int
bind_iface
;
578
/**< VHOST: nonzero to strictly bind sockets to the interface name in
579
* .iface (eg, "eth2"), using SO_BIND_TO_DEVICE.
580
*
581
* Requires SO_BINDTODEVICE support from your OS and CAP_NET_RAW
582
* capability.
583
*
584
* Notice that common things like access network interface IP from
585
* your local machine use your lo / loopback interface and will be
586
* disallowed by this.
587
*/
588
unsigned
int
timeout_secs_ah_idle
;
589
/**< VHOST: seconds to allow a client to hold an ah without using it.
590
* 0 defaults to 10s. */
591
#
endif
/* WITH_NETWORK */
592
593
#
if
defined
(
LWS_WITH_TLS_SESSIONS
)
594
uint32_t
tls_session_timeout
;
595
/**< VHOST: seconds until timeout/ttl for newly created sessions.
596
* 0 means default timeout (defined per protocol, usually 300s). */
597
uint32_t
tls_session_cache_max
;
598
/**< VHOST: 0 for default limit of 10, or the maximum number of
599
* client tls sessions we are willing to cache */
600
#
endif
601
602
gid_t
gid
;
603
/**< CONTEXT: group id to change to after setting listen socket,
604
* or -1. See also .username below. */
605
uid_t
uid
;
606
/**< CONTEXT: user id to change to after setting listen socket,
607
* or -1. See also .groupname below. */
608
uint64_t
options
;
609
/**< VHOST + CONTEXT: 0, or LWS_SERVER_OPTION_... bitfields */
610
void
*
user
;
611
/**< VHOST + CONTEXT: optional user pointer that will be associated
612
* with the context when creating the context (and can be retrieved by
613
* lws_context_user(context), or with the vhost when creating the vhost
614
* (and can be retrieved by lws_vhost_user(vhost)). You will need to
615
* use LWS_SERVER_OPTION_EXPLICIT_VHOSTS and create the vhost separately
616
* if you care about giving the context and vhost different user pointer
617
* values.
618
*/
619
unsigned
int
count_threads
;
620
/**< CONTEXT: how many contexts to create in an array, 0 = 1 */
621
unsigned
int
fd_limit_per_thread
;
622
/**< CONTEXT: nonzero means restrict each service thread to this
623
* many fds, 0 means the default which is divide the process fd
624
* limit by the number of threads.
625
*
626
* Note if this is nonzero, and fd_limit_per_thread multiplied by the
627
* number of service threads is less than the process ulimit, then lws
628
* restricts internal lookup table allocation to the smaller size, and
629
* switches to a less efficient lookup scheme. You should use this to
630
* trade off speed against memory usage if you know the lws context
631
* will only use a handful of fds.
632
*
633
* Bear in mind lws may use some fds internally, for example for the
634
* cancel pipe, so you may need to allow for some extras for normal
635
* operation.
636
*/
637
const
char
*
vhost_name
;
638
/**< VHOST: name of vhost, must match external DNS name used to
639
* access the site, like "warmcat.com" as it's used to match
640
* Host: header and / or SNI name for SSL.
641
* CONTEXT: NULL, or the name to associate with the context for
642
* context-specific logging
643
*/
644
#
if
defined
(
LWS_WITH_PLUGINS
)
645
const
char
*
const
*
plugin_dirs
;
646
/**< CONTEXT: NULL, or NULL-terminated array of directories to
647
* scan for lws protocol plugins at context creation time */
648
#
endif
649
void
*
external_baggage_free_on_destroy
;
650
/**< CONTEXT: NULL, or pointer to something externally malloc'd, that
651
* should be freed when the context is destroyed. This allows you to
652
* automatically sync the freeing action to the context destruction
653
* action, so there is no need for an external free() if the context
654
* succeeded to create.
655
*/
656
657
658
unsigned
int
pt_serv_buf_size
;
659
/**< CONTEXT: 0 = default of 4096. This buffer is used by
660
* various service related features including file serving, it
661
* defines the max chunk of file that can be sent at once.
662
* At the risk of lws having to buffer failed large sends, it
663
* can be increased to, eg, 128KiB to improve throughput. */
664
#
if
defined
(
LWS_WITH_FILE_OPS
)
665
const
struct
lws_plat_file_ops
*
fops
;
666
/**< CONTEXT: NULL, or pointer to an array of fops structs, terminated
667
* by a sentinel with NULL .open.
668
*
669
* If NULL, lws provides just the platform file operations struct for
670
* backwards compatibility.
671
*/
672
#
endif
673
674
#
if
defined
(
LWS_WITH_SOCKS5
)
675
const
char
*
socks_proxy_address
;
676
/**< VHOST: If non-NULL, attempts to proxy via the given address.
677
* If proxy auth is required, use format
678
* "username:password\@server:port" */
679
unsigned
int
socks_proxy_port
;
680
/**< VHOST: If socks_proxy_address was non-NULL, uses this port
681
* if nonzero, otherwise requires "server:port" in .socks_proxy_address
682
*/
683
#
endif
684
685
#
if
defined
(
LWS_HAVE_SYS_CAPABILITY_H
)
&&
defined
(
LWS_HAVE_LIBCAP
)
686
cap_value_t
caps
[4];
687
/**< CONTEXT: array holding Linux capabilities you want to
688
* continue to be available to the server after it transitions
689
* to a noprivileged user. Usually none are needed but for, eg,
690
* .bind_iface, CAP_NET_RAW is required. This gives you a way
691
* to still have the capability but drop root.
692
*/
693
char
count_caps
;
694
/**< CONTEXT: count of Linux capabilities in .caps[]. 0 means
695
* no capabilities will be inherited from root (the default) */
696
#
endif
697
void
**
foreign_loops
;
698
/**< CONTEXT: This is ignored if the context is not being started with
699
* an event loop, ie, .options has a flag like
700
* LWS_SERVER_OPTION_LIBUV.
701
*
702
* NULL indicates lws should start its own even loop for
703
* each service thread, and deal with closing the loops
704
* when the context is destroyed.
705
*
706
* Non-NULL means it points to an array of external
707
* ("foreign") event loops that are to be used in turn for
708
* each service thread. In the default case of 1 service
709
* thread, it can just point to one foreign event loop.
710
*/
711
void
(*
signal_cb
)(
void
*event_lib_handle,
int
signum);
712
/**< CONTEXT: NULL: default signal handling. Otherwise this receives
713
* the signal handler callback. event_lib_handle is the
714
* native event library signal handle, eg uv_signal_t *
715
* for libuv.
716
*/
717
struct
lws_context **
pcontext
;
718
/**< CONTEXT: if non-NULL, at the end of context destroy processing,
719
* the pointer pointed to by pcontext is written with NULL. You can
720
* use this to let foreign event loops know that lws context destruction
721
* is fully completed.
722
*/
723
void
(*
finalize
)(
struct
lws_vhost *vh,
void
*arg);
724
/**< VHOST: NULL, or pointer to function that will be called back
725
* when the vhost is just about to be freed. The arg parameter
726
* will be set to whatever finalize_arg is below.
727
*/
728
void
*
finalize_arg
;
729
/**< VHOST: opaque pointer lws ignores but passes to the finalize
730
* callback. If you don't care, leave it NULL.
731
*/
732
const
char
*
listen_accept_role
;
733
/**< VHOST: NULL for default, or force accepted incoming connections to
734
* bind to this role. Uses the role names from their ops struct, eg,
735
* "raw-skt".
736
*/
737
const
char
*
listen_accept_protocol
;
738
/**< VHOST: NULL for default, or force accepted incoming connections to
739
* bind to this vhost protocol name.
740
*/
741
const
struct
lws_protocols
**
pprotocols
;
742
/**< VHOST: NULL: use .protocols, otherwise ignore .protocols and use
743
* this array of pointers to protocols structs. The end of the array
744
* is marked by a NULL pointer.
745
*
746
* This is preferred over .protocols, because it allows the protocol
747
* struct to be opaquely defined elsewhere, with just a pointer to it
748
* needed to create the context with it. .protocols requires also
749
* the type of the user data to be known so its size can be given.
750
*/
751
752
const
char
*
username
;
/**< CONTEXT: string username for post-init
753
* permissions. Like .uid but takes a string username. */
754
const
char
*
groupname
;
/**< CONTEXT: string groupname for post-init
755
* permissions. Like .gid but takes a string groupname. */
756
const
char
*
unix_socket_perms
;
/**< VHOST: if your vhost is listening
757
* on a unix socket, you can give a "username:groupname" string here
758
* to control the owner:group it's created with. It's always created
759
* with 0660 mode. */
760
const
lws_system_ops_t
*
system_ops
;
761
/**< CONTEXT: hook up lws_system_ apis to system-specific
762
* implementations */
763
const
lws_retry_bo_t
*
retry_and_idle_policy
;
764
/**< VHOST: optional retry and idle policy to apply to this vhost.
765
* Currently only the idle parts are applied to the connections.
766
*/
767
#
if
defined
(
LWS_WITH_SYS_STATE
)
768
lws_state_notify_link_t
*
const
*
register_notifier_list
;
769
/**< CONTEXT: NULL, or pointer to an array of notifiers that should
770
* be registered during context creation, so they can see state change
771
* events from very early on. The array should end with a NULL. */
772
#
endif
773
#
if
defined
(
LWS_WITH_SECURE_STREAMS
)
774
#
if
defined
(
LWS_WITH_SECURE_STREAMS_STATIC_POLICY_ONLY
)
775
const
struct
lws_ss_policy
*
pss_policies
;
/**< CONTEXT: point to first
776
* in a linked-list of streamtype policies prepared by user code */
777
#
else
778
const
char
*
pss_policies_json
;
/**< CONTEXT: point to a string
779
* containing a JSON description of the secure streams policies. Set
780
* to NULL if not using Secure Streams.
781
* If the platform supports files and the string does not begin with
782
* '{', lws treats the string as a filepath to open to get the JSON
783
* policy.
784
*/
785
#
endif
786
const
struct
lws_ss_plugin
**
pss_plugins
;
/**< CONTEXT: point to an array
787
* of pointers to plugin structs here, terminated with a NULL ptr.
788
* Set to NULL if not using Secure Streams. */
789
const
char
*
ss_proxy_bind
;
/**< CONTEXT: NULL, or: ss_proxy_port == 0:
790
* point to a string giving the Unix Domain Socket address to use (start
791
* with @ for abstract namespace), ss_proxy_port nonzero: set the
792
* network interface address (not name, it's ambiguous for ipv4/6) to
793
* bind the tcp connection to the proxy to */
794
const
char
*
ss_proxy_address
;
/**< CONTEXT: NULL, or if ss_proxy_port
795
* nonzero: the tcp address of the ss proxy to connect to */
796
uint16_t
ss_proxy_port
;
/* 0 = if connecting to ss proxy, do it via a
797
* Unix Domain Socket, "+@proxy.ss.lws" if ss_proxy_bind is NULL else
798
* the socket path given in ss_proxy_bind (start it with a + or +@);
799
* nonzero means connect via a tcp socket to the tcp address in
800
* ss_proxy_bind and the given port */
801
const
struct
lws_transport_proxy_ops
*
txp_ops_ssproxy
;
/**< CONTEXT: NULL, or
802
* custom sss transport ops used for ss proxy communication. NULL means
803
* to use the default wsi-based proxy server */
804
const
void
*
txp_ssproxy_info
;
/**< CONTEXT: NULL, or extra transport-
805
* specifi creation info to be used at \p txp_ops_ssproxy creation */
806
const
struct
lws_transport_client_ops
*
txp_ops_sspc
;
/**< CONTEXT: NULL, or
807
* custom sss transport ops used for ss client communication to the ss
808
* proxy. NULL means to use the default wsi-based client support */
809
#
endif
810
811
#
if
defined
(
LWS_WITH_SECURE_STREAMS_PROXY_API
)
812
#
endif
813
814
int
rlimit_nofile
;
815
/**< 0 = inherit the initial ulimit for files / sockets from the startup
816
* environment. Nonzero = try to set the limit for this process.
817
*/
818
#
if
defined
(
LWS_WITH_PEER_LIMITS
)
819
lws_peer_limits_notify_t
pl_notify_cb
;
820
/**< CONTEXT: NULL, or a callback to receive notifications each time a
821
* connection is being dropped because of peer limits.
822
*
823
* The callback provides the context, and an lws_sockaddr46 with the
824
* peer address and port.
825
*/
826
unsigned
short
ip_limit_ah
;
827
/**< CONTEXT: max number of ah a single IP may use simultaneously
828
* 0 is no limit. This is a soft limit: if the limit is
829
* reached, connections from that IP will wait in the ah
830
* waiting list and not be able to acquire an ah until
831
* a connection belonging to the IP relinquishes one it
832
* already has.
833
*/
834
unsigned
short
ip_limit_wsi
;
835
/**< CONTEXT: max number of wsi a single IP may use simultaneously.
836
* 0 is no limit. This is a hard limit, connections from
837
* the same IP will simply be dropped once it acquires the
838
* amount of simultaneous wsi / accepted connections
839
* given here.
840
*/
841
842
#
endif
/* PEER_LIMITS */
843
844
#
if
defined
(
LWS_WITH_SYS_FAULT_INJECTION
)
845
lws_fi_ctx_t
fic
;
846
/**< CONTEXT | VHOST: attach external Fault Injection context to the
847
* lws_context or vhost. If creating the context + default vhost in
848
* one step, only the context binds to \p fi. When creating a vhost
849
* otherwise this can bind to the vhost so the faults can be injected
850
* from the start.
851
*/
852
#
endif
853
854
#
if
defined
(
LWS_WITH_SYS_SMD
)
855
lws_smd_notification_cb_t
early_smd_cb
;
856
/**< CONTEXT: NULL, or an smd notification callback that will be registered
857
* immediately after the smd in the context is initialized. This ensures
858
* you can get all notifications without having to intercept the event loop
859
* creation, eg, when using an event library. Other callbacks can be
860
* registered later manually without problems.
861
*/
862
void
*
early_smd_opaque
;
863
lws_smd_class_t
early_smd_class_filter
;
864
lws_usec_t
smd_ttl_us
;
865
/**< CONTEXT: SMD messages older than this many us are removed from the
866
* queue and destroyed even if not fully delivered yet. If zero,
867
* defaults to 2 seconds (5 second for FREERTOS).
868
*/
869
uint16_t
smd_queue_depth
;
870
/**< CONTEXT: Maximum queue depth, If zero defaults to 40
871
* (20 for FREERTOS) */
872
#
endif
873
874
#
if
defined
(
LWS_WITH_SYS_METRICS
)
875
const
struct
lws_metric_policy
*
metrics_policies
;
876
/**< CONTEXT: non-SS policy metrics policies */
877
const
char
*
metrics_prefix
;
878
/**< CONTEXT: prefix for this context's metrics, used to distinguish
879
* metrics pooled from different processes / applications, so, eg what
880
* would be "cpu.svc" if this is NULL becomes "myapp.cpu.svc" is this is
881
* set to "myapp". Policies are applied using the name with the prefix,
882
* if present.
883
*/
884
#
endif
885
886
int
fo_listen_queue
;
887
/**< VHOST: 0 = no TCP_FASTOPEN, nonzero = enable TCP_FASTOPEN if the
888
* platform supports it, with the given queue length for the listen
889
* socket.
890
*/
891
892
const
struct
lws_plugin_evlib
*
event_lib_custom
;
893
/**< CONTEXT: If non-NULL, override event library selection so it uses
894
* this custom event library implementation, instead of default internal
895
* loop. Don't set any other event lib context creation flags in that
896
* case. it will be used automatically. This is useful for integration
897
* where an existing application is using its own handrolled event loop
898
* instead of an event library, it provides a way to allow lws to use
899
* the custom event loop natively as if it were an "event library".
900
*/
901
902
#
if
defined
(
LWS_WITH_TLS_JIT_TRUST
)
903
size_t
jitt_cache_max_footprint
;
904
/**< CONTEXT: 0 for no limit, else max bytes used by JIT Trust cache...
905
* LRU items are evicted to keep under this limit */
906
int
vh_idle_grace_ms
;
907
/**< CONTEXT: 0 for default of 5000ms, or number of ms JIT Trust vhosts
908
* are allowed to live without active connections using them. */
909
#
endif
910
911
lws_log_cx_t
*
log_cx
;
912
/**< CONTEXT: NULL to use the default, process-scope logging context,
913
* else a specific logging context to associate with this context */
914
915
#
if
defined
(
LWS_WITH_CACHE_NSCOOKIEJAR
)
&&
defined
(
LWS_WITH_CLIENT
)
916
const
char
*
http_nsc_filepath
;
917
/**< CONTEXT: Filepath to use for http netscape cookiejar file */
918
919
size_t
http_nsc_heap_max_footprint
;
920
/**< CONTEXT: 0, or limit in bytes for heap usage of memory cookie
921
* cache */
922
size_t
http_nsc_heap_max_items
;
923
/**< CONTEXT: 0, or the max number of items allowed in the cookie cache
924
* before destroying lru items to keep it under the limit */
925
size_t
http_nsc_heap_max_payload
;
926
/**< CONTEXT: 0, or the maximum size of a single cookie we are able to
927
* handle */
928
#
endif
929
930
#
if
defined
(
LWS_WITH_SYS_ASYNC_DNS
)
931
const
char
**
async_dns_servers
;
932
/**< CONTEXT: NULL, or a pointer to an array of strings containing the
933
* numeric IP like "8.8.8.8" or "2001:4860:4860::8888" for a list of DNS
934
* server to forcibly add. If given, the list of strings must be
935
* terminated with a NULL.
936
*/
937
#
endif
938
939
/* Add new things just above here ---^
940
* This is part of the ABI, don't needlessly break compatibility
941
*
942
* The below is to ensure later library versions with new
943
* members added above will see 0 (default) even if the app
944
* was not built against the newer headers.
945
*/
946
947
void
*
_unused
[2];
/**< dummy */
948
};
949
950
/**
951
* lws_create_context() - Create the websocket handler
952
* \param info: pointer to struct with parameters
953
*
954
* This function creates the listening socket (if serving) and takes care
955
* of all initialization in one step.
956
*
957
* If option LWS_SERVER_OPTION_EXPLICIT_VHOSTS is given, no vhost is
958
* created; you're expected to create your own vhosts afterwards using
959
* lws_create_vhost(). Otherwise a vhost named "default" is also created
960
* using the information in the vhost-related members, for compatibility.
961
*
962
* After initialization, it returns a struct lws_context * that
963
* represents this server. After calling, user code needs to take care
964
* of calling lws_service() with the context pointer to get the
965
* server's sockets serviced. This must be done in the same process
966
* context as the initialization call.
967
*
968
* The protocol callback functions are called for a handful of events
969
* including http requests coming in, websocket connections becoming
970
* established, and data arriving; it's also called periodically to allow
971
* async transmission.
972
*
973
* HTTP requests are sent always to the FIRST protocol in protocol, since
974
* at that time websocket protocol has not been negotiated. Other
975
* protocols after the first one never see any HTTP callback activity.
976
*
977
* The server created is a simple http server by default; part of the
978
* websocket standard is upgrading this http connection to a websocket one.
979
*
980
* This allows the same server to provide files like scripts and favicon /
981
* images or whatever over http and dynamic data over websockets all in
982
* one place; they're all handled in the user callback.
983
*/
984
LWS_VISIBLE LWS_EXTERN
struct
lws_context *
985
lws_create_context
(
const
struct
lws_context_creation_info
*info);
986
987
988
/**
989
* lws_context_destroy() - Destroy the websocket context
990
* \param context: Websocket context
991
*
992
* This function closes any active connections and then frees the
993
* context. After calling this, any further use of the context is
994
* undefined.
995
*/
996
LWS_VISIBLE LWS_EXTERN
void
997
lws_context_destroy
(
struct
lws_context *context);
998
999
typedef
int
(*
lws_reload_func
)(
void
);
1000
1001
/**
1002
* lws_context_deprecate() - Deprecate the websocket context
1003
*
1004
* \param context: Websocket context
1005
* \param cb: Callback notified when old context listen sockets are closed
1006
*
1007
* This function is used on an existing context before superceding it
1008
* with a new context.
1009
*
1010
* It closes any listen sockets in the context, so new connections are
1011
* not possible.
1012
*
1013
* And it marks the context to be deleted when the number of active
1014
* connections into it falls to zero.
1015
*
1016
* This is aimed at allowing seamless configuration reloads.
1017
*
1018
* The callback cb will be called after the listen sockets are actually
1019
* closed and may be reopened. In the callback the new context should be
1020
* configured and created. (With libuv, socket close happens async after
1021
* more loop events).
1022
*/
1023
LWS_VISIBLE LWS_EXTERN
void
1024
lws_context_deprecate
(
struct
lws_context *context,
lws_reload_func
cb);
1025
1026
LWS_VISIBLE LWS_EXTERN
int
1027
lws_context_is_deprecated
(
struct
lws_context *context);
1028
1029
/**
1030
* lws_set_proxy() - Setups proxy to lws_context.
1031
* \param vhost: pointer to struct lws_vhost you want set proxy for
1032
* \param proxy: pointer to c string containing proxy in format address:port
1033
*
1034
* Returns 0 if proxy string was parsed and proxy was setup.
1035
* Returns -1 if proxy is NULL or has incorrect format.
1036
*
1037
* This is only required if your OS does not provide the http_proxy
1038
* environment variable (eg, OSX)
1039
*
1040
* IMPORTANT! You should call this function right after creation of the
1041
* lws_context and before call to connect. If you call this
1042
* function after connect behavior is undefined.
1043
* This function will override proxy settings made on lws_context
1044
* creation with genenv() call.
1045
*/
1046
LWS_VISIBLE LWS_EXTERN
int
1047
lws_set_proxy
(
struct
lws_vhost *vhost,
const
char
*proxy);
1048
1049
/**
1050
* lws_set_socks() - Setup socks to lws_context.
1051
* \param vhost: pointer to struct lws_vhost you want set socks for
1052
* \param socks: pointer to c string containing socks in format address:port
1053
*
1054
* Returns 0 if socks string was parsed and socks was setup.
1055
* Returns -1 if socks is NULL or has incorrect format.
1056
*
1057
* This is only required if your OS does not provide the socks_proxy
1058
* environment variable (eg, OSX)
1059
*
1060
* IMPORTANT! You should call this function right after creation of the
1061
* lws_context and before call to connect. If you call this
1062
* function after connect behavior is undefined.
1063
* This function will override proxy settings made on lws_context
1064
* creation with genenv() call.
1065
*/
1066
LWS_VISIBLE LWS_EXTERN
int
1067
lws_set_socks
(
struct
lws_vhost *vhost,
const
char
*socks);
1068
1069
struct
lws_vhost;
1070
1071
/**
1072
* lws_create_vhost() - Create a vhost (virtual server context)
1073
* \param context: pointer to result of lws_create_context()
1074
* \param info: pointer to struct with parameters
1075
*
1076
* This function creates a virtual server (vhost) using the vhost-related
1077
* members of the info struct. You can create many vhosts inside one context
1078
* if you created the context with the option LWS_SERVER_OPTION_EXPLICIT_VHOSTS
1079
*/
1080
LWS_VISIBLE LWS_EXTERN
struct
lws_vhost *
1081
lws_create_vhost
(
struct
lws_context *context,
1082
const
struct
lws_context_creation_info
*info);
1083
1084
/**
1085
* lws_vhost_destroy() - Destroy a vhost (virtual server context)
1086
*
1087
* \param vh: pointer to result of lws_create_vhost()
1088
*
1089
* This function destroys a vhost. Normally, if you just want to exit,
1090
* then lws_destroy_context() will take care of everything. If you want
1091
* to destroy an individual vhost and all connections and allocations, you
1092
* can do it with this.
1093
*
1094
* If the vhost has a listen sockets shared by other vhosts, it will be given
1095
* to one of the vhosts sharing it rather than closed.
1096
*
1097
* The vhost close is staged according to the needs of the event loop, and if
1098
* there are multiple service threads. At the point the vhost itself if
1099
* about to be freed, if you provided a finalize callback and optional arg at
1100
* vhost creation time, it will be called just before the vhost is freed.
1101
*/
1102
LWS_VISIBLE LWS_EXTERN
void
1103
lws_vhost_destroy
(
struct
lws_vhost *vh);
1104
1105
/**
1106
* lwsws_get_config_globals() - Parse a JSON server config file
1107
* \param info: pointer to struct with parameters
1108
* \param d: filepath of the config file
1109
* \param config_strings: storage for the config strings extracted from JSON,
1110
* the pointer is incremented as strings are stored
1111
* \param len: pointer to the remaining length left in config_strings
1112
* the value is decremented as strings are stored
1113
*
1114
* This function prepares a n lws_context_creation_info struct with global
1115
* settings from a file d.
1116
*
1117
* Requires CMake option LWS_WITH_LEJP_CONF to have been enabled
1118
*/
1119
LWS_VISIBLE LWS_EXTERN
int
1120
lwsws_get_config_globals
(
struct
lws_context_creation_info
*info,
const
char
*d,
1121
char
**config_strings,
int
*len);
1122
1123
/**
1124
* lwsws_get_config_vhosts() - Create vhosts from a JSON server config file
1125
* \param context: pointer to result of lws_create_context()
1126
* \param info: pointer to struct with parameters
1127
* \param d: filepath of the config file
1128
* \param config_strings: storage for the config strings extracted from JSON,
1129
* the pointer is incremented as strings are stored
1130
* \param len: pointer to the remaining length left in config_strings
1131
* the value is decremented as strings are stored
1132
*
1133
* This function creates vhosts into a context according to the settings in
1134
*JSON files found in directory d.
1135
*
1136
* Requires CMake option LWS_WITH_LEJP_CONF to have been enabled
1137
*/
1138
LWS_VISIBLE LWS_EXTERN
int
1139
lwsws_get_config_vhosts
(
struct
lws_context *context,
1140
struct
lws_context_creation_info
*info,
const
char
*d,
1141
char
**config_strings,
int
*len);
1142
1143
/**
1144
* lws_get_vhost() - return the vhost a wsi belongs to
1145
*
1146
* \param wsi: which connection
1147
*/
1148
LWS_VISIBLE LWS_EXTERN
struct
lws_vhost *
1149
lws_get_vhost
(
struct
lws *wsi);
1150
1151
/**
1152
* lws_get_vhost_name() - returns the name of a vhost
1153
*
1154
* \param vhost: which vhost
1155
*/
1156
LWS_VISIBLE LWS_EXTERN
const
char
*
1157
lws_get_vhost_name
(
struct
lws_vhost *vhost);
1158
1159
/**
1160
* lws_get_vhost_by_name() - returns the vhost with the requested name, or NULL
1161
*
1162
* \param context: the lws_context to look in
1163
* \param name: vhost name we are looking for
1164
*
1165
* Returns NULL, or the vhost with the name \p name
1166
*/
1167
LWS_VISIBLE LWS_EXTERN
struct
lws_vhost *
1168
lws_get_vhost_by_name
(
struct
lws_context *context,
const
char
*name);
1169
1170
/**
1171
* lws_get_vhost_port() - returns the port a vhost listens on, or -1
1172
*
1173
* \param vhost: which vhost
1174
*/
1175
LWS_VISIBLE LWS_EXTERN
int
1176
lws_get_vhost_port
(
struct
lws_vhost *vhost);
1177
1178
/**
1179
* lws_get_vhost_user() - returns the user pointer for the vhost
1180
*
1181
* \param vhost: which vhost
1182
*/
1183
LWS_VISIBLE LWS_EXTERN
void
*
1184
lws_get_vhost_user
(
struct
lws_vhost *vhost);
1185
1186
/**
1187
* lws_get_vhost_iface() - returns the binding for the vhost listen socket
1188
*
1189
* \param vhost: which vhost
1190
*/
1191
LWS_VISIBLE LWS_EXTERN
const
char
*
1192
lws_get_vhost_iface
(
struct
lws_vhost *vhost);
1193
1194
/**
1195
* lws_vhost_user() - get the user data associated with the vhost
1196
* \param vhost: Websocket vhost
1197
*
1198
* This returns the optional user pointer that can be attached to
1199
* a vhost when it was created. Lws never dereferences this pointer, it only
1200
* sets it when the vhost is created, and returns it using this api.
1201
*/
1202
LWS_VISIBLE LWS_EXTERN
void
*
1203
lws_vhost_user
(
struct
lws_vhost *vhost);
1204
1205
/**
1206
* lws_context_user() - get the user data associated with the context
1207
* \param context: Websocket context
1208
*
1209
* This returns the optional user allocation that can be attached to
1210
* the context the sockets live in at context_create time. It's a way
1211
* to let all sockets serviced in the same context share data without
1212
* using globals statics in the user code.
1213
*/
1214
LWS_VISIBLE LWS_EXTERN
void
*
1215
lws_context_user
(
struct
lws_context *context);
1216
1217
LWS_VISIBLE LWS_EXTERN
const
char
*
1218
lws_vh_tag
(
struct
lws_vhost *vh);
1219
1220
LWS_VISIBLE LWS_EXTERN
void
1221
_lws_context_info_defaults
(
struct
lws_context_creation_info
*info,
1222
const
char
*sspol);
1223
1224
LWS_VISIBLE LWS_EXTERN
void
1225
lws_default_loop_exit
(
struct
lws_context *cx);
1226
1227
LWS_VISIBLE LWS_EXTERN
void
1228
lws_context_default_loop_run_destroy
(
struct
lws_context *cx);
1229
1230
LWS_VISIBLE LWS_EXTERN
int
1231
lws_cmdline_passfail
(
int
argc,
const
char
**argv,
int
actual);
1232
1233
/**
1234
* lws_context_is_being_destroyed() - find out if context is being destroyed
1235
*
1236
* \param context: the struct lws_context pointer
1237
*
1238
* Returns nonzero if the context has had lws_context_destroy() called on it...
1239
* when using event library loops the destroy process can be asynchronous. In
1240
* the special case of libuv foreign loops, the failure to create the context
1241
* may have to do work on the foreign loop to reverse the partial creation,
1242
* meaning a failed context create cannot unpick what it did and return NULL.
1243
*
1244
* In that condition, a valid context that is already started the destroy
1245
* process is returned, and this test api will return nonzero as a way to
1246
* find out the create is in the middle of failing.
1247
*/
1248
LWS_VISIBLE LWS_EXTERN
int
1249
lws_context_is_being_destroyed
(
struct
lws_context *context);
1250
1251
/*! \defgroup vhost-mounts Vhost mounts and options
1252
* \ingroup context-and-vhost-creation
1253
*
1254
* ##Vhost mounts and options
1255
*/
1256
///@{
1257
/** struct lws_protocol_vhost_options - linked list of per-vhost protocol
1258
* name=value options
1259
*
1260
* This provides a general way to attach a linked-list of name=value pairs,
1261
* which can also have an optional child link-list using the options member.
1262
*/
1263
struct
lws_protocol_vhost_options
{
1264
const
struct
lws_protocol_vhost_options
*
next
;
/**< linked list */
1265
const
struct
lws_protocol_vhost_options
*
options
;
/**< child linked-list of more options for this node */
1266
const
char
*
name
;
/**< name of name=value pair */
1267
const
char
*
value
;
/**< value of name=value pair */
1268
};
1269
1270
/** enum lws_mount_protocols
1271
* This specifies the mount protocol for a mountpoint, whether it is to be
1272
* served from a filesystem, or it is a cgi etc.
1273
*/
1274
enum
lws_mount_protocols
{
1275
LWSMPRO_HTTP
= 0,
/**< http reverse proxy */
1276
LWSMPRO_HTTPS
= 1,
/**< https reverse proxy */
1277
LWSMPRO_FILE
= 2,
/**< serve from filesystem directory */
1278
LWSMPRO_CGI
= 3,
/**< pass to CGI to handle */
1279
LWSMPRO_REDIR_HTTP
= 4,
/**< redirect to http:// url */
1280
LWSMPRO_REDIR_HTTPS
= 5,
/**< redirect to https:// url */
1281
LWSMPRO_CALLBACK
= 6,
/**< hand by named protocol's callback */
1282
};
1283
1284
/** enum lws_authentication_mode
1285
* This specifies the authentication mode of the mount. The basic_auth_login_file mount parameter
1286
* is ignored unless LWSAUTHM_DEFAULT is set.
1287
*/
1288
enum
lws_authentication_mode
{
1289
LWSAUTHM_DEFAULT
= 0,
/**< default authenticate only if basic_auth_login_file is provided */
1290
LWSAUTHM_BASIC_AUTH_CALLBACK
= 1 << 28
/**< Basic auth with a custom verifier */
1291
};
1292
1293
/** The authentication mode is stored in the top 4 bits of lws_http_mount.auth_mask */
1294
#
define
AUTH_MODE_MASK
0xF0000000
1295
1296
/** struct lws_http_mount
1297
*
1298
* arguments for mounting something in a vhost's url namespace
1299
*/
1300
struct
lws_http_mount
{
1301
const
struct
lws_http_mount
*
mount_next
;
1302
/**< pointer to next struct lws_http_mount */
1303
const
char
*
mountpoint
;
1304
/**< mountpoint in http pathspace, eg, "/" */
1305
const
char
*
origin
;
1306
/**< path to be mounted, eg, "/var/www/warmcat.com" */
1307
const
char
*
def
;
1308
/**< default target, eg, "index.html" */
1309
const
char
*
protocol
;
1310
/**<"protocol-name" to handle mount */
1311
1312
const
struct
lws_protocol_vhost_options
*
cgienv
;
1313
/**< optional linked-list of cgi options. These are created
1314
* as environment variables for the cgi process
1315
*/
1316
const
struct
lws_protocol_vhost_options
*
extra_mimetypes
;
1317
/**< optional linked-list of mimetype mappings */
1318
const
struct
lws_protocol_vhost_options
*
interpret
;
1319
/**< optional linked-list of files to be interpreted */
1320
1321
int
cgi_timeout
;
1322
/**< seconds cgi is allowed to live, if cgi://mount type */
1323
int
cache_max_age
;
1324
/**< max-age for reuse of client cache of files, seconds */
1325
unsigned
int
auth_mask
;
1326
/**< bits set here must be set for authorized client session */
1327
1328
unsigned
int
cache_reusable
:1;
/**< set if client cache may reuse this */
1329
unsigned
int
cache_revalidate
:1;
/**< set if client cache should revalidate on use */
1330
unsigned
int
cache_intermediaries
:1;
/**< set if intermediaries are allowed to cache */
1331
unsigned
int
cache_no
:1;
/**< set if client should check cache always*/
1332
1333
unsigned
char
origin_protocol
;
/**< one of enum lws_mount_protocols */
1334
unsigned
char
mountpoint_len
;
/**< length of mountpoint string */
1335
1336
const
char
*
basic_auth_login_file
;
1337
/**<NULL, or filepath to use to check basic auth logins against. (requires LWSAUTHM_DEFAULT) */
1338
1339
/* Add new things just above here ---^
1340
* This is part of the ABI, don't needlessly break compatibility
1341
*/
1342
};
1343
1344
///@}
1345
///@}
include
libwebsockets
lws-context-vhost.h
Generated on Fri Jun 17 2022 04:56:33 for libwebsockets by
1.9.1