1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2 <html xmlns="http://www.w3.org/1999/xhtml">
4 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
5 <meta http-equiv="X-UA-Compatible" content="IE=9"/>
6 <meta name="generator" content="Doxygen 1.8.11"/>
7 <title>libwebsockets: Notes about lwsws</title>
8 <link href="tabs.css" rel="stylesheet" type="text/css"/>
9 <script type="text/javascript" src="jquery.js"></script>
10 <script type="text/javascript" src="dynsections.js"></script>
11 <link href="navtree.css" rel="stylesheet" type="text/css"/>
12 <script type="text/javascript" src="resize.js"></script>
13 <script type="text/javascript" src="navtreedata.js"></script>
14 <script type="text/javascript" src="navtree.js"></script>
15 <script type="text/javascript">
16 $(document).ready(initResizable);
17 $(window).load(resizeHeight);
19 <link href="doxygen.css" rel="stylesheet" type="text/css" />
22 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
24 <table cellspacing="0" cellpadding="0">
26 <tr style="height: 56px;">
27 <td id="projectlogo"><img alt="Logo" src="libwebsockets.org-logo.png"/></td>
28 <td id="projectalign" style="padding-left: 0.5em;">
29 <div id="projectname">libwebsockets
31 <div id="projectbrief">Lightweight C library for HTML5 websockets</div>
37 <!-- end header part -->
38 <!-- Generated by Doxygen 1.8.11 -->
39 <div id="navrow1" class="tabs">
41 <li><a href="index.html"><span>Main Page</span></a></li>
42 <li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
43 <li><a href="modules.html"><span>Modules</span></a></li>
44 <li><a href="annotated.html"><span>Data Structures</span></a></li>
45 <li><a href="files.html"><span>Files</span></a></li>
49 <div id="side-nav" class="ui-resizable side-nav-resizable">
51 <div id="nav-tree-contents">
52 <div id="nav-sync" class="sync"></div>
55 <div id="splitbar" style="-moz-user-select:none;"
56 class="ui-resizable-handle">
59 <script type="text/javascript">
60 $(document).ready(function(){initNavTree('md_README.lwsws.html','');});
62 <div id="doc-content">
64 <div class="headertitle">
65 <div class="title">Notes about lwsws </div> </div>
67 <div class="contents">
68 <div class="textblock"><h2>Libwebsockets Web Server </h2>
69 <p>lwsws is an implementation of a very lightweight, ws-capable generic web server, which uses libwebsockets to implement everything underneath.</p>
71 <p>Just enable -DLWS_WITH_LWSWS=1 at cmake-time.</p>
72 <p>It enables libuv and plugin support automatically.</p>
73 <h2>Configuration </h2>
74 <p>lwsws uses JSON config files, they're pure JSON but # may be used to turn the rest of the line into a comment.</p>
75 <p>There's also a single substitution, if a string contains "_lws_ddir_", then that is replaced with the LWS install data directory path, eg, "/usr/share" or whatever was set when LWS was built + installed. That lets you refer to installed paths without having to change the config if your install path was different.</p>
76 <p>There is a single file intended for global settings</p>
77 <p>/etc/lwsws/conf </p><div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> # these are the server global settings</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span> # stuff related to vhosts should go in one</div><div class="line"><a name="l00003"></a><span class="lineno"> 3</span> # file per vhost in ../conf.d/</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span> </div><div class="line"><a name="l00005"></a><span class="lineno"> 5</span> {</div><div class="line"><a name="l00006"></a><span class="lineno"> 6</span>  "global": {</div><div class="line"><a name="l00007"></a><span class="lineno"> 7</span>  "uid": "48", # apache user</div><div class="line"><a name="l00008"></a><span class="lineno"> 8</span>  "gid": "48", # apache user</div><div class="line"><a name="l00009"></a><span class="lineno"> 9</span>  "count-threads": "1",</div><div class="line"><a name="l00010"></a><span class="lineno"> 10</span>  "server-string": "myserver v1", # returned in http headers</div><div class="line"><a name="l00011"></a><span class="lineno"> 11</span>  "init-ssl": "yes"</div><div class="line"><a name="l00012"></a><span class="lineno"> 12</span>  }</div><div class="line"><a name="l00013"></a><span class="lineno"> 13</span> }</div></div><!-- fragment --><p> and a config directory intended to take one file per vhost</p>
78 <p>/etc/lwsws/conf.d/warmcat.com </p><div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> {</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span>  "vhosts": [{</div><div class="line"><a name="l00003"></a><span class="lineno"> 3</span>  "name": "warmcat.com",</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span>  "port": "443",</div><div class="line"><a name="l00005"></a><span class="lineno"> 5</span>  "interface": "eth0", # optional</div><div class="line"><a name="l00006"></a><span class="lineno"> 6</span>  "host-ssl-key": "/etc/pki/tls/private/warmcat.com.key", # if given enable ssl</div><div class="line"><a name="l00007"></a><span class="lineno"> 7</span>  "host-ssl-cert": "/etc/pki/tls/certs/warmcat.com.crt",</div><div class="line"><a name="l00008"></a><span class="lineno"> 8</span>  "host-ssl-ca": "/etc/pki/tls/certs/warmcat.com.cer",</div><div class="line"><a name="l00009"></a><span class="lineno"> 9</span>  "mounts": [{ # autoserve</div><div class="line"><a name="l00010"></a><span class="lineno"> 10</span>  "mountpoint": "/",</div><div class="line"><a name="l00011"></a><span class="lineno"> 11</span>  "origin": "file:///var/www/warmcat.com",</div><div class="line"><a name="l00012"></a><span class="lineno"> 12</span>  "default": "index.html"</div><div class="line"><a name="l00013"></a><span class="lineno"> 13</span>  }]</div><div class="line"><a name="l00014"></a><span class="lineno"> 14</span>  }]</div><div class="line"><a name="l00015"></a><span class="lineno"> 15</span> }</div></div><!-- fragment --><p> To get started quickly, an example config reproducing the old test server on port 7681, non-SSL is provided. To set it up </p><div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> # mkdir -p /etc/lwsws/conf.d /var/log/lwsws</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span> # cp ./lwsws/etc-lwsws-conf-EXAMPLE /etc/lwsws/conf</div><div class="line"><a name="l00003"></a><span class="lineno"> 3</span> # cp ./lwsws/etc-lwsws-conf.d-localhost-EXAMPLE /etc/lwsws/conf.d/test-server</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span> # sudo lwsws</div></div><!-- fragment --> <h2>Vhosts </h2>
79 <p>One server can run many vhosts, where SSL is in use SNI is used to match the connection to a vhost and its vhost-specific SSL keys during SSL negotiation.</p>
80 <p>Listing multiple vhosts looks something like this </p><div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> {</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span>  "vhosts": [ {</div><div class="line"><a name="l00003"></a><span class="lineno"> 3</span>  "name": "localhost",</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span>  "port": "443",</div><div class="line"><a name="l00005"></a><span class="lineno"> 5</span>  "host-ssl-key": "/etc/pki/tls/private/libwebsockets.org.key",</div><div class="line"><a name="l00006"></a><span class="lineno"> 6</span>  "host-ssl-cert": "/etc/pki/tls/certs/libwebsockets.org.crt",</div><div class="line"><a name="l00007"></a><span class="lineno"> 7</span>  "host-ssl-ca": "/etc/pki/tls/certs/libwebsockets.org.cer",</div><div class="line"><a name="l00008"></a><span class="lineno"> 8</span>  "mounts": [{</div><div class="line"><a name="l00009"></a><span class="lineno"> 9</span>  "mountpoint": "/",</div><div class="line"><a name="l00010"></a><span class="lineno"> 10</span>  "origin": "file:///var/www/libwebsockets.org",</div><div class="line"><a name="l00011"></a><span class="lineno"> 11</span>  "default": "index.html"</div><div class="line"><a name="l00012"></a><span class="lineno"> 12</span>  }, {</div><div class="line"><a name="l00013"></a><span class="lineno"> 13</span>  "mountpoint": "/testserver",</div><div class="line"><a name="l00014"></a><span class="lineno"> 14</span>  "origin": "file:///usr/local/share/libwebsockets-test-server",</div><div class="line"><a name="l00015"></a><span class="lineno"> 15</span>  "default": "test.html"</div><div class="line"><a name="l00016"></a><span class="lineno"> 16</span>  }],</div><div class="line"><a name="l00017"></a><span class="lineno"> 17</span>  # which protocols are enabled for this vhost, and optional</div><div class="line"><a name="l00018"></a><span class="lineno"> 18</span>  # vhost-specific config options for the protocol</div><div class="line"><a name="l00019"></a><span class="lineno"> 19</span>  #</div><div class="line"><a name="l00020"></a><span class="lineno"> 20</span>  "ws-protocols": [{</div><div class="line"><a name="l00021"></a><span class="lineno"> 21</span>  "warmcat,timezoom": {</div><div class="line"><a name="l00022"></a><span class="lineno"> 22</span>  "status": "ok"</div><div class="line"><a name="l00023"></a><span class="lineno"> 23</span>  }</div><div class="line"><a name="l00024"></a><span class="lineno"> 24</span>  }]</div><div class="line"><a name="l00025"></a><span class="lineno"> 25</span>  },</div><div class="line"><a name="l00026"></a><span class="lineno"> 26</span>  {</div><div class="line"><a name="l00027"></a><span class="lineno"> 27</span>  "name": "localhost",</div><div class="line"><a name="l00028"></a><span class="lineno"> 28</span>  "port": "7681",</div><div class="line"><a name="l00029"></a><span class="lineno"> 29</span>  "host-ssl-key": "/etc/pki/tls/private/libwebsockets.org.key",</div><div class="line"><a name="l00030"></a><span class="lineno"> 30</span>  "host-ssl-cert": "/etc/pki/tls/certs/libwebsockets.org.crt",</div><div class="line"><a name="l00031"></a><span class="lineno"> 31</span>  "host-ssl-ca": "/etc/pki/tls/certs/libwebsockets.org.cer",</div><div class="line"><a name="l00032"></a><span class="lineno"> 32</span>  "mounts": [{</div><div class="line"><a name="l00033"></a><span class="lineno"> 33</span>  "mountpoint": "/",</div><div class="line"><a name="l00034"></a><span class="lineno"> 34</span>  "origin": ">https://localhost"</div><div class="line"><a name="l00035"></a><span class="lineno"> 35</span>  }]</div><div class="line"><a name="l00036"></a><span class="lineno"> 36</span>  },</div><div class="line"><a name="l00037"></a><span class="lineno"> 37</span>  {</div><div class="line"><a name="l00038"></a><span class="lineno"> 38</span>  "name": "localhost",</div><div class="line"><a name="l00039"></a><span class="lineno"> 39</span>  "port": "80",</div><div class="line"><a name="l00040"></a><span class="lineno"> 40</span>  "mounts": [{</div><div class="line"><a name="l00041"></a><span class="lineno"> 41</span>  "mountpoint": "/",</div><div class="line"><a name="l00042"></a><span class="lineno"> 42</span>  "origin": ">https://localhost"</div><div class="line"><a name="l00043"></a><span class="lineno"> 43</span>  }]</div><div class="line"><a name="l00044"></a><span class="lineno"> 44</span>  }</div><div class="line"><a name="l00045"></a><span class="lineno"> 45</span> </div><div class="line"><a name="l00046"></a><span class="lineno"> 46</span>  ]</div><div class="line"><a name="l00047"></a><span class="lineno"> 47</span> }</div></div><!-- fragment --><p>That sets up three vhosts all called "localhost" on ports 443 and 7681 with SSL, and port 80 without SSL but with a forced redirect to <a href="https://localhost">https://localhost</a></p>
81 <h2>Vhost name and port </h2>
82 <p>The vhost name field is used to match on incoming SNI or Host: header, so it must always be the host name used to reach the vhost externally.</p>
84 <li>Vhosts may have the same name and different ports, these will each create a listening socket on the appropriate port.</li>
85 <li>Vhosts may also have the same port and different name: these will be treated as true vhosts on one listening socket and the active vhost decided at SSL negotiation time (via SNI) or if no SSL, then after the Host: header from the client has been parsed.</li>
88 <p>Vhosts by default have available the union of any initial protocols from context creation time, and any protocols exposed by plugins.</p>
89 <p>Vhosts can select which plugins they want to offer and give them per-vhost settings using this syntax </p><div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> "ws-protocols": [{</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span>  "warmcat-timezoom": {</div><div class="line"><a name="l00003"></a><span class="lineno"> 3</span>  "status": "ok"</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span>  }</div><div class="line"><a name="l00005"></a><span class="lineno"> 5</span> }]</div></div><!-- fragment --><p>The "x":"y" parameters like "status":"ok" are made available to the protocol during its per-vhost LWS_CALLBACK_PROTOCOL_INIT ( is a pointer to a linked list of struct <a class="el" href="structlws__protocol__vhost__options.html">lws_protocol_vhost_options</a> containing the name and value pointers).</p>
90 <p>To indicate that a protocol should be used when no Protocol: header is sent by the client, you can use "default": "1" </p><div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> "ws-protocols": [{</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span>  "warmcat-timezoom": {</div><div class="line"><a name="l00003"></a><span class="lineno"> 3</span>  "status": "ok",</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span>  "default": "1"</div><div class="line"><a name="l00005"></a><span class="lineno"> 5</span>  }</div><div class="line"><a name="l00006"></a><span class="lineno"> 6</span> }]</div></div><!-- fragment --><h2>Other vhost options </h2>
92 <li>If the three options <code>host-ssl-cert</code>, <code>host-ssl-ca</code> and <code>host-ssl-key</code> are given, then the vhost supports SSL.</li>
94 <p>Each vhost may have its own certs, SNI is used during the initial connection negotiation to figure out which certs to use by the server name it's asking for from the request DNS name.</p>
96 <li><code>keeplive-timeout</code> (in secs) defaults to 60 for lwsws, it may be set as a vhost option</li>
97 <li><code>interface</code> lets you specify which network interface to listen on, if not given listens on all</li>
98 <li>"`unix-socket`": "1" causes the unix socket specified in the interface option to be used instead of an INET socket</li>
99 <li>"`sts`": "1" causes lwsws to send a Strict Transport Security header with responses that informs the client he should never accept to connect to this address using http. This is needed to get the A+ security rating from SSL Labs for your server.</li>
100 <li>"`access-log`": "filepath" sets where apache-compatible access logs will be written</li>
101 <li><code>"enable-client-ssl"</code>: <code>"1"</code> enables the vhost's client SSL context, you will need this if you plan to create client conections on the vhost that will use SSL. You don't need it if you only want http / ws client connections.</li>
102 <li>"`ciphers`": "<cipher list>" sets the allowed list of ciphers and key exchange protocols for the vhost. The default list is restricted to only those providing PFS (Perfect Forward Secrecy) on the author's Fedora system.</li>
104 <p>If you need to allow weaker ciphers,you can provide an alternative list here per-vhost.</p>
106 <li>"`ecdh-curve`": "<curve name>" The default ecdh curve is "prime256v1", but you can override it here, per-vhost</li>
107 <li>"`noipv6`": "on" Disable ipv6 completely for this vhost</li>
108 <li>"`ipv6only`": "on" Only allow ipv6 on this vhost / "off" only allow ipv4 on this vhost</li>
109 <li>"`ssl-option-set`": "<decimal>" Sets the SSL option flag value for the vhost. It may be used multiple times and OR's the flags together.</li>
111 <p>The values are derived from /usr/include/openssl/ssl.h </p><div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> # define SSL_OP_NO_TLSv1_1 0x10000000L</div></div><!-- fragment --><p>would equate to</p>
112 <div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> "`ssl-option-set`": "268435456"</div></div><!-- fragment --><ul>
113 <li>"`ssl-option-clear'": "<decimal>" Clears the SSL option flag value for the vhost. It may be used multiple times and OR's the flags together.</li>
116 <p>Where mounts are given in the vhost definition, then directory contents may be auto-served if it matches the mountpoint.</p>
117 <p>Mount protocols are used to control what kind of translation happens</p>
119 <li><a href="file://">file://</a> serve the uri using the remainder of the url past the mountpoint based on the origin directory.</li>
121 <p>Eg, with this mountpoint </p><div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> {</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span>  "mountpoint": "/",</div><div class="line"><a name="l00003"></a><span class="lineno"> 3</span>  "origin": "file:///var/www/mysite.com",</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span>  "default": "/"</div><div class="line"><a name="l00005"></a><span class="lineno"> 5</span> }</div></div><!-- fragment --><p> The uri /file.jpg would serve /var/www/mysite.com/file.jpg, since / matched.</p>
123 <li>^http:// or ^https:// these cause any url matching the mountpoint to issue a redirect to the origin url</li>
124 <li>cgi:// this causes any matching url to be given to the named cgi, eg <div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> {</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span>  "mountpoint": "/git",</div><div class="line"><a name="l00003"></a><span class="lineno"> 3</span>  "origin": "cgi:///var/www/cgi-bin/cgit",</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span>  "default": "/"</div><div class="line"><a name="l00005"></a><span class="lineno"> 5</span> }, {</div><div class="line"><a name="l00006"></a><span class="lineno"> 6</span>  "mountpoint": "/cgit-data",</div><div class="line"><a name="l00007"></a><span class="lineno"> 7</span>  "origin": "file:///usr/share/cgit",</div><div class="line"><a name="l00008"></a><span class="lineno"> 8</span>  "default": "/"</div><div class="line"><a name="l00009"></a><span class="lineno"> 9</span> },</div></div><!-- fragment --> would cause the url /git/myrepo to pass "myrepo" to the cgi /var/www/cgi-bin/cgit and send the results to the client.</li>
126 <h2>Other mount options </h2>
127 <p>1) Some protocols may want "per-mount options" in name:value format. You can provide them using "pmo" </p><pre class="fragment"> {
128 "mountpoint": "/stuff",
129 "origin": "callback://myprotocol",
134 </pre><p>2) When using a cgi:// protcol origin at a mountpoint, you may also give cgi environment variables specific to the mountpoint like this </p><div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> {</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span>  "mountpoint": "/git",</div><div class="line"><a name="l00003"></a><span class="lineno"> 3</span>  "origin": "cgi:///var/www/cgi-bin/cgit",</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span>  "default": "/",</div><div class="line"><a name="l00005"></a><span class="lineno"> 5</span>  "cgi-env": [{</div><div class="line"><a name="l00006"></a><span class="lineno"> 6</span>  "CGIT_CONFIG": "/etc/cgitrc/libwebsockets.org"</div><div class="line"><a name="l00007"></a><span class="lineno"> 7</span>  }]</div><div class="line"><a name="l00008"></a><span class="lineno"> 8</span> }</div></div><!-- fragment --><p> This allows you to customize one cgi depending on the mountpoint (and / or vhost).</p>
135 <p>3) It's also possible to set the cgi timeout (in secs) per cgi:// mount, like this </p><div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> "cgi-timeout": "30"</div></div><!-- fragment --><p> 4) <code>callback://</code> protocol may be used when defining a mount to associate a named protocol callback with the URL namespace area. For example </p><div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> {</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span>  "mountpoint": "/formtest",</div><div class="line"><a name="l00003"></a><span class="lineno"> 3</span>  "origin": "callback://protocol-post-demo"</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span> }</div></div><!-- fragment --><p> All handling of client access to /formtest[anything] will be passed to the callback registered to the protocol "protocol-post-demo".</p>
136 <p>This is useful for handling POST http body content or general non-cgi http payload generation inside a plugin.</p>
137 <p>See the related notes in README.coding.md</p>
138 <p>5) Cache policy of the files in the mount can also be set. If no options are given, the content is marked uncacheable. </p><div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> {</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span>  "mountpoint": "/",</div><div class="line"><a name="l00003"></a><span class="lineno"> 3</span>  "origin": "file:///var/www/mysite.com",</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span>  "cache-max-age": "60", # seconds</div><div class="line"><a name="l00005"></a><span class="lineno"> 5</span>  "cache-reuse": "1", # allow reuse at client at all</div><div class="line"><a name="l00006"></a><span class="lineno"> 6</span>  "cache-revalidate": "1", # check it with server each time</div><div class="line"><a name="l00007"></a><span class="lineno"> 7</span>  "cache-intermediaries": "1" # allow intermediary caches to hold</div><div class="line"><a name="l00008"></a><span class="lineno"> 8</span> }</div></div><!-- fragment --><p>6) You can also define a list of additional mimetypes per-mount </p><div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> "extra-mimetypes": {</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span>  ".zip": "application/zip",</div><div class="line"><a name="l00003"></a><span class="lineno"> 3</span>  ".doc": "text/evil"</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span>  }</div></div><!-- fragment --><h2>Plugins </h2>
139 <p>Protcols and extensions may also be provided from "plugins", these are lightweight dynamic libraries. They are scanned for at init time, and any protocols and extensions found are added to the list given at context creation time.</p>
140 <p>Protocols receive init (LWS_CALLBACK_PROTOCOL_INIT) and destruction (LWS_CALLBACK_PROTOCOL_DESTROY) callbacks per-vhost, and there are arrangements they can make per-vhost allocations and get hold of the correct pointer from the wsi at the callback.</p>
141 <p>This allows a protocol to choose to strictly segregate data on a per-vhost basis, and also allows the plugin to handle its own initialization and context storage.</p>
142 <p>To help that happen conveniently, there are some new apis</p>
144 <li>lws_vhost_get(wsi)</li>
145 <li>lws_protocol_get(wsi)</li>
146 <li>lws_callback_on_writable_all_protocol_vhost(vhost, protocol)</li>
147 <li>lws_protocol_vh_priv_zalloc(vhost, protocol, size)</li>
148 <li>lws_protocol_vh_priv_get(vhost, protocol)</li>
150 <p>dumb increment, mirror and status protocol plugins are provided as examples.</p>
151 <h2>Additional plugin search paths </h2>
152 <p>Packages that have their own lws plugins can install them in their own preferred dir and ask lwsws to scan there by using a config fragment like this, in its own conf.d/ file managed by the other package </p><div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> {</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span>  "global": {</div><div class="line"><a name="l00003"></a><span class="lineno"> 3</span>  "plugin-dir": "/usr/local/share/coherent-timeline/plugins"</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span>  }</div><div class="line"><a name="l00005"></a><span class="lineno"> 5</span> }</div></div><!-- fragment --><h2>lws-server-status plugin </h2>
153 <p>One provided protocol can be used to monitor the server status.</p>
154 <p>Enable the protocol like this on a vhost's ws-protocols section </p><div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> "lws-server-status": {</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span>  "status": "ok",</div><div class="line"><a name="l00003"></a><span class="lineno"> 3</span>  "update-ms": "5000"</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span> }</div></div><!-- fragment --><p> "update-ms" is used to control how often updated JSON is sent on a ws link.</p>
155 <p>And map the provided HTML into the vhost in the mounts section </p><div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> {</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span>  "mountpoint": "/server-status",</div><div class="line"><a name="l00003"></a><span class="lineno"> 3</span>  "origin": "file:///usr/local/share/libwebsockets-test-server/server-status",</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span>  "default": "server-status.html"</div><div class="line"><a name="l00005"></a><span class="lineno"> 5</span> }</div></div><!-- fragment --><p> You might choose to put it on its own vhost which has "interface": "lo", so it's not externally visible.</p>
156 <h2>Integration with Systemd </h2>
157 <p>lwsws needs a service file like this as <code>/usr/lib/systemd/system/lwsws.service</code> </p><div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> [Unit]</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span> Description=Libwebsockets Web Server</div><div class="line"><a name="l00003"></a><span class="lineno"> 3</span> After=syslog.target</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span> </div><div class="line"><a name="l00005"></a><span class="lineno"> 5</span> [Service]</div><div class="line"><a name="l00006"></a><span class="lineno"> 6</span> ExecStart=/usr/local/bin/lwsws</div><div class="line"><a name="l00007"></a><span class="lineno"> 7</span> StandardError=null</div><div class="line"><a name="l00008"></a><span class="lineno"> 8</span> </div><div class="line"><a name="l00009"></a><span class="lineno"> 9</span> [Install]</div><div class="line"><a name="l00010"></a><span class="lineno"> 10</span> WantedBy=multi-user.target</div></div><!-- fragment --><p>You can find this prepared in <code>./lwsws/usr-lib-systemd-system-lwsws.service</code></p>
158 <h2>Integration with logrotate </h2>
159 <p>For correct operation with logrotate, <code>/etc/logrotate.d/lwsws</code> (if that's where we're putting the logs) should contain </p><div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> /var/log/lwsws/*log {</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span>  copytruncate</div><div class="line"><a name="l00003"></a><span class="lineno"> 3</span>  missingok</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span>  notifempty</div><div class="line"><a name="l00005"></a><span class="lineno"> 5</span>  delaycompress</div><div class="line"><a name="l00006"></a><span class="lineno"> 6</span> }</div></div><!-- fragment --><p> You can find this prepared in <code>/lwsws/etc-logrotate.d-lwsws</code></p>
160 <p>Prepare the log directory like this</p>
161 <div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> sudo mkdir /var/log/lwsws</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span> sudo chmod 700 /var/log/lwsws</div></div><!-- fragment --> </div></div><!-- contents -->
162 </div><!-- doc-content -->
163 <!-- start footer part -->
164 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
166 <li class="footer">Generated by
167 <a href="http://www.doxygen.org/index.html">
168 <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.11 </li>
projects / platform / upstream / libwebsockets.git / blob