rpi/domo
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Import civetweb ans jsoncpp

Browse Source
This commit is contained in:
NADAL Jean-Baptiste
2016-02-27 00:07:26 +01:00
parent 5ed9eb9715
commit 3bc376da33
1153 changed files with 554633 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

176
3P/civetweb/docs/Building.md Normal file
View File

@@ -0,0 +1,176 @@
Building Civetweb
=========
This guide covers the build instructions for stand-alone web server.
See [Embedding.md](https://github.com/civetweb/civetweb/blob/master/docs/Embedding.md) for information on extending an application.
#### Where to get the source code?
https://github.com/civetweb/civetweb
Building for Windows
---------
#### Using Visual Studio
Open the *VS2012/civetweb.sln* in Visual Studio.
To include SSL support, you may have to use yaSSL. However, it is GPL licensed.
See [yaSSL.md](https://github.com/civetweb/civetweb/blob/master/docs/yaSSL.md) for more information.
#### Using MinGW-w64 or TDM-GCC
In the start menu locate and run the "Run terminal" batch file. For TDM-GCC this is named "MinGW Command Prompt".
Navigate to the civetweb sources directory and run:
```
mingw32-make CC=gcc
```
Building for Linux, BSD, and OSX
---------
## Using Make
```
make help
```
Get help
```
make build
```
compile the code
```
make install
```
Install on the system, Linux only.
```
make lib WITH_CPP=1 WITH_IPV6=1
make clean slib WITH_CPP=1 WITH_LUA=1 WITH_WEBSOCKET=1
```
Build the static and shared libraries.
The *WITH_CPP* make option is to include the CivetServer class.
The additional make options configure the library just as it would the application.
The *slib* option should be done on a separate clean build as position
independent code (PIC) is required for it. Trying to run it after
building the static library or the server will result in a link error.
```
make clean
```
Clean up the mess
## Setting build options
Make options can be set on the command line with the make command like so.
```
make build WITH_LUA=1
```
| Make Options | Description |
| ------------------------- | ---------------------------------------- |
| WITH_LUA=1 | build with Lua support |
| WITH_DEBUG=1 | build with GDB debug support |
| WITH_IPV6=1 | with IPV6 support |
| WITH_WEBSOCKET=1 | build with web socket support |
| WITH_CPP=1 | build libraries with c++ classes |
| CONFIG_FILE=file | use 'file' as the config file |
| CONFIG_FILE2=file | use 'file' as the backup config file |
| HTMLDIR=/path | place to install initial web pages |
| DOCUMENT_ROOT=/path | HTMLDIR override, config option, install |
| | nothing is installed here. |
| PORTS=8080 | listening ports override when installing |
| SSL_LIB=libssl.so.0 | use versioned SSL library |
| CRYPTO_LIB=libcrypto.so.0 | system versioned CRYPTO library |
| PREFIX=/usr/local | sets the install directory |
| COPT='-DNO_SSL' | method to insert compile flags |
Note that the WITH_* options used for *make* are not identical to the
preprocessor defines in the source code - usually USE_* is used there.
## Setting compile flags
Compile flags can be set using the *COPT* make option like so.
```
make build COPT="-DNDEBUG -DNO_CGI"
```
| Compile Flags | Description |
| ------------------------- | ------------------------------------ |
| NDEBUG | strip off all debug code |
| DEBUG | build debug version (very noisy) |
| NO_CGI | disable CGI support |
| NO_SSL | disable SSL functionality |
| NO_SSL_DL | link against system libssl library |
| NO_FILES | do not serve files from a directory |
| SQLITE_DISABLE_LFS | disables large files (Lua only) |
| SSL_ALREADY_INITIALIZED | do not initialize libcrypto |
## Cross Compiling
Take total control with *CC*, *COPT* and *TARGET_OS* as make options.
TARGET_OS is used to determine some compile details as will as code function.
TARGET_OS values should be be one found in *resources/Makefile.in-os*.
```
make CC=arm-none-linux-gnueabi-gcc COPT="-march=armv7-a -mfpu=vfp -mfloat-abi=softfp" TARGET_OS=FROG
```
## Cocoa DMG Packaging (OSX Only)
Use the alternate *Makefile.osx* to do the build. The entire build has
to be done using *Makefile.osx* because additional compile and link options
are required. This Makefile has all the same options as the other one plus
one additional *package* rule.
```
make -f Makefile.osx package
```
Building with Buildroot
---------
[Buildroot](http://buildroot.uclibc.org/) is a tool for creating cross compiled file systems. Including Civetweb in buildroot is fairly easy. There is even support for various build options.
1. First, check if it already there.
- In buildroot, make menuconfig
- Package Selection for the target --->
- Networking applications --->
- civetweb
2. If not there, just add it
- copy *Config.in* and *civetweb.mk* from Civetweb's *contrib/buildroot/* to Buildroot's *package/civetweb/* directory.
- In Buildroot's *package/Config.in, insert the following line in were you will know how to find it in the menu.
> ``` source "package/civetweb/Config.in" ```
Building on Android
---------
This is a small guide to help you run civetweb on Android. Currently it is
tested on the HTC Wildfire. If you have managed to run it on other devices
as well, please comment or drop an email in the mailing list.
Note : You dont need root access to run civetweb on Android.
- Download the source from the Downloads page.
- Download the Android NDK from [http://developer.android.com/tools/sdk/ndk/index.html](http://developer.android.com/tools/sdk/ndk/index.html)
- Run `/path-to-ndk/ndk-build -C /path-to-civetweb/resources`
That should generate civetweb/lib/armeabi/civetweb
- Using the adb tool (you need to have Android SDK installed for that),
push the generated civetweb binary to `/data/local` folder on device.
- From adb shell, navigate to `/data/local` and execute `./civetweb`.
- To test if the server is running fine, visit your web-browser and
navigate to `http://127.0.0.1:8080` You should see the `Index of /` page.
![screenshot](https://a248.e.akamai.net/camo.github.com/b88428bf009a2b6141000937ab684e04cc8586af/687474703a2f2f692e696d6775722e636f6d2f62676f6b702e706e67)
Notes:
- `jni` stands for Java Native Interface. Read up on Android NDK if you want
to know how to interact with the native C functions of civetweb in Android
Java applications.
- TODO: A Java application that interacts with the native binary or a
shared library.

168
3P/civetweb/docs/Embedding.md Normal file
View File

@@ -0,0 +1,168 @@
Embedding Civetweb
=========
Civetweb is primarily designed so applications can easily add HTTP server functionality. For example, an application server could use Civetweb to enable a web service interface for automation or remote control.
Files
------
There is just a small set of files to compile in to the application,
but if a library is desired, see [Building.md](https://github.com/civetweb/civetweb/blob/master/docs/Building.md)
#### Regarding the INL file extension
The *INL* file extension represents code that is statically included inline in a source file. Slightly different from C++ where it means "inline" code which is technically not the same as static code. Civetweb overloads this extension for the sake of clarity as opposed to having .c extensions on files that should not be directly compiled.
#### Required Files
1. HTTP Server API
- src/civetweb.c
- include/civetweb.h
2. MD5 API
- src/md5.inl
3. C++ Wrapper (Optional)
- src/CivetServer.cpp
- include/CivetServer.h
#### Other Files
1. Reference C Server
- src/main.c
2. Reference C++ Server
- examples/embedded_cpp/embedded_cpp.cpp
Quick Start
------
By default, the server will automatically serve up files like a normal HTTP server. An embedded server is most likely going to overload this functionality.
### C
- Use ```mg_start()``` to start the server.
- Use *options* to select the port and document root among other things.
- Use *callbacks* to add your own hooks.
- Use ```mg_set_request_handler()``` to easily add your own request handlers.
- Use ```mg_stop()``` to stop the server.
### C++
- Create CivetHandlers for each URI.
- Register the handlers with ```CivetServer::addHandler()```
- ```CivetServer``` starts on contruction and stops on destruction.
- Use contructor *options* to select the port and document root among other things.
- Use constructor *callbacks* to add your own hooks.
Lua Support
------
Lua is a server side include functionality. Files ending in .lua will be processed with Lua.
##### Add the following CFLAGS
- -DLUA_COMPAT_ALL
- -DUSE_LUA
- -DUSE_LUA_SQLITE3
- -DUSE_LUA_FILE_SYSTEM
##### Add the following sources
- src/mod_lua.inl
- src/third_party/lua-5.2.4/src
+ lapi.c
+ lauxlib.c
+ lbaselib.c
+ lbitlib.c
+ lcode.c
+ lcorolib.c
+ lctype.c
+ ldblib.c
+ ldebug.c
+ ldo.c
+ ldump.c
+ lfunc.c
+ lgc.c
+ linit.c
+ liolib.c
+ llex.c
+ lmathlib.c
+ lmem.c
+ loadlib.c
+ lobject.c
+ lopcodes.c
+ loslib.c
+ lparser.c
+ lstate.c
+ lstring.c
+ lstrlib.c
+ ltable.c
+ ltablib.c
+ ltm.c
+ lundump.c
+ lvm.c
+ lzio.c
- src/third_party/sqlite3.c
- src/third_party/sqlite3.h
- src/third_party/lsqlite3.c
- src/third_party/lfs.c
- src/third_party/lfs.h
Civetweb internals
------
Civetweb is multithreaded web server. `mg_start()` function allocates
web server context (`struct mg_context`), which holds all information
about web server instance:
- configuration options. Note that civetweb makes internal copies of
passed options.
- SSL context, if any
- user-defined callbacks
- opened listening sockets
- a queue for accepted sockets
- mutexes and condition variables for inter-thread synchronization
When `mg_start()` returns, all initialization is quaranteed to be complete
(e.g. listening ports are opened, SSL is initialized, etc). `mg_start()` starts
two threads: a master thread, that accepts new connections, and several
worker threads, that process accepted connections. The number of worker threads
is configurable via `num_threads` configuration option. That number puts a
limit on number of simultaneous requests that can be handled by civetweb.
If you embed civetweb into a program that uses SSL outside civetweb as well,
you may need to initialize SSL before calling `mg_start()`, and set the pre-
processor define SSL_ALREADY_INITIALIZED. This is not required if SSL is used
only within civetweb.
When master thread accepts new connection, a new accepted socket (described by
`struct socket`) it placed into the accepted sockets queue,
which has size of 20 (see [code](https://github.com/civetweb/civetweb/blob/3892e0199e6ca9613b160535d9d107ede09daa43/civetweb.c#L486)). Any idle worker thread
can grab accepted sockets from that queue. If all worker threads are busy,
master thread can accept and queue up to 20 more TCP connections,
filling up the queue.
In the attempt to queue next accepted connection, master thread blocks
until there is space in a queue. When master thread is blocked on a
full queue, TCP layer in OS can also queue incoming connection.
The number is limited by the `listen()` call parameter on listening socket,
which is `SOMAXCONN` in case of Civetweb, and depends on a platform.
Worker threads are running in an infinite loop, which in simplified form
looks something like this:
static void *worker_thread() {
while (consume_socket()) {
process_new_connection();
}
}
Function `consume_socket()` gets new accepted socket from the civetweb socket
queue, atomically removing it from the queue. If the queue is empty,
`consume_socket()` blocks and waits until new sockets are placed in a queue
by the master thread. `process_new_connection()` actually processes the
connection, i.e. reads the request, parses it, and performs appropriate action
depending on a parsed request.
Master thread uses `poll()` and `accept()` to accept new connections on
listening sockets. `poll()` is used to avoid `FD_SETSIZE` limitation of
`select()`. Since there are only a few listening sockets, there is no reason
to use hi-performance alternatives like `epoll()` or `kqueue()`. Worker
threads use blocking IO on accepted sockets for reading and writing data.
All accepted sockets have `SO_RCVTIMEO` and `SO_SNDTIMEO` socket options set
(controlled by `request_timeout_ms` civetweb option, 30 seconds default) which
specify read/write timeout on client connection.

36
3P/civetweb/docs/Installing.md Normal file
View File

@@ -0,0 +1,36 @@
Civetweb Install Guide
====
This guide covers the distributions for CivetWeb. The latest source code is available at [https://github.com/civetweb/civetweb](https://github.com/civetweb/civetweb).
Windows
---
This pre-built version comes pre-built wit Lua support. Libraries for SSL support are not included due to licensing restrictions;
however, users may add an SSL library themselves.
Instructions for adding SSL support can be found in [https://github.com/civetweb/civetweb/tree/master/docs](https://github.com/civetweb/civetweb/tree/master/docs)
1a. 32 Bit: Install the [Visual C++ Redistributable for Visual Studio 2010](http://www.microsoft.com/en-us/download/details.aspx?id=8328)
1b. 64 Bit: Install the [Visual C++ Redistributable for Visual Studio 2013](http://www.microsoft.com/en-us/download/details.aspx?id=40784)
2. Download latest *civetweb-win.zip* from [SourceForge](https://sourceforge.net/projects/civetweb/files/)
3. When started, Civetweb puts itself into the tray.
OS X
---
This pre-built version comes with Lua, IPV6 and SSL support.
1. Download the latest *Civetweb.dmg* from [SourceForge](https://sourceforge.net/projects/civetweb/files/)
2. Click on the it and look for the attachment in the finder.
4. Drag Civetweb to the Applications folder.
5. When started, Civetweb puts itself into top menu.
Linux
---
1. Download the latest *civetweb.tar.gz* from [SourceForge](https://sourceforge.net/projects/civetweb/files/)
2. Open archive and change to the new directory.
3. make help
4. make
5. make install
6. Run the program ```/usr/local/bin/civetweb```, it will use the configuration file */usr/local/etc/civetweb.conf*.

132
3P/civetweb/docs/OpenSSL.md Normal file
View File

@@ -0,0 +1,132 @@
Adding OpenSSL Support
=====
Civetweb supports *HTTPS* connections using the OpenSSL transport layer
security (TLS) library. OpenSSL is a free, open source library (see
http://www.openssl.org/).
Getting Started
----
- Install OpenSSL on your system. There are OpenSSL install packages for all
major Linux distributions as well as a setup for Windows.
- The default build configuration of the civetweb web server will load the
required OpenSSL libraries, if a HTTPS certificate has been configured.
Civetweb Configuration
----
The configuration file must contain an https port, identified by a letter 's'
attached to the port number.
To serve http and https from their standard ports use the following line in
the configuration file 'civetweb.conf':
<pre>
listening_ports 80, 443s
</pre>
To serve only https use:
<pre>
listening_ports 443s
</pre>
Furthermore the SSL certificate file must be set:
<pre>
ssl_certificate d:\civetweb\certificate\server.pem
</pre>
Creating a self signed certificate
----
OpenSSL provides a command line interface, that can be used to create the
certificate file required by civetweb (server.pem).
One can use the following steps in Windows (in Linux replace "copy" by "cp"
and "type" by "cat"):
<pre>
openssl genrsa -des3 -out server.key 1024
openssl req -new -key server.key -out server.csr
copy server.key server.key.orig
openssl rsa -in server.key.orig -out server.key
openssl x509 -req -days 3650 -in server.csr -signkey server.key -out server.crt
copy server.crt server.pem
type server.key >> server.pem
</pre>
The server.pem file created must contain a 'certificate' section as well as a
'rsa private key' section. It should look like this (x represents BASE64
encoded data):
<pre>
-----BEGIN CERTIFICATE-----
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxx
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-----END RSA PRIVATE KEY-----
</pre>
Common Problems
----
In case the OpenSSL configuration is not set up correctly, the server will not
start. Configure an error log file in 'civetweb.conf' to get more information:
<pre>
error_log_file error.log
</pre>
Check the content of 'error.log':
<pre>
load_dll: cannot load libeay32.*/libcrypto.*/ssleay32.*/libssl.*
</pre>
This error message means, the SSL library has not been installed (correctly).
For Windows you might use the pre-built binaries. A link is available at the
OpenSSL project home page (http://www.openssl.org/related/binaries.html).
Choose the windows system folder as installation directory - this is the
default location.
<pre>
set_ssl_option: cannot open server.pem: error:PEM routines:*:PEM_read_bio:no start line
set_ssl_option: cannot open server.pem: error:PEM routines:*:PEM_read_bio:bad end line
</pre>
These error messages indicate, that the format of the ssl_certificate file does
not match the expectations of the SSL library. The PEM file must contain both,
a 'CERTIFICATE' and a 'RSA PRIVATE KEY' section. It should be a strict ASCII
file without byte-order marks.
The instructions above may be used to create a valid ssl_certificate file.

575
3P/civetweb/docs/UserManual.md Normal file
View File

@@ -0,0 +1,575 @@
Overview
=====
Civetweb is small and easy to use web server.
It may be embedded into C/C++ host applications or used as a stand-alone
server. See `Embedding.md` for information on embedding civetweb into
host applications.
The stand-alone server is self-contained, and does not require any external
software to run. Some Windows users may need to install the
[Visual C++ Redistributable](http://www.microsoft.com/en-us/download/details.aspx?id=30679).
Installation
----
On Windows, UNIX and Mac, the civetweb stand-alone executable may be started
from the command line.
Running `civetweb` in a terminal, optionally followed by configuration parameters
(`civetweb [OPTIONS]`) or a configuration file name (`civetweb [config_file_name]`),
starts the web server.
For UNIX and Mac, civetweb does not detach from the terminal.
Pressing `Ctrl-C` keys will stop the server.
On Windows, civetweb iconifies itself to the system tray icon when started.
Right-click on the icon pops up a menu, where it is possible to stop
civetweb, or configure it, or install it as Windows service.
When started without options, the server exposes the local directory at
[http](http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol) port 8080.
Thus, the easiest way to share a folder on Windows is to copy `civetweb.exe`
to this folder, double-click the exe, and launch a browser at
[http://localhost:8080](http://localhost:8080). Note that 'localhost' should
be changed to a machine's name if a folder is accessed from other computer.
When started, civetweb first searches for the configuration file.
If configuration file is specified explicitly in the command line, i.e.
`civetweb path_to_config_file`, then specified configuration file is used.
Otherwise, civetweb would search for file `civetweb.conf` in the same directory
the executable is located, and use it. This configuration file is optional.
The configuration file is a sequence of lines, each line containing one
command line argument name and the corresponding value.
Empty lines, and lines beginning with `#`, are ignored.
Here is the example of `civetweb.conf` file:
document_root c:\www
listening_ports 80,443s
ssl_certificate c:\civetweb\ssl_cert.pem
When a configuration file is used, additional command line arguments may
override the configuration file settings.
All command line arguments must start with `-`.
For example: The above `civetweb.conf` file is used, and civetweb started as
`civetweb -document_root D:\web`. Then the `D:\web` directory will be served
as document root, because command line options take priority over the
configuration file. The configuration options section below provides a good
overview of the Civetweb features.
Note that configuration options on the command line must start with `-`,
but their names are the same as in the config file. All option names are
listed in the next section. Thus, the following two setups are equivalent:
# Using command line arguments
$ civetweb -listening_ports 1234 -document_root /var/www
# Using config file
$ cat civetweb.conf
listening_ports 1234
document_root /var/www
$ civetweb
Civetweb can also be used to modify `.htpasswd` passwords files:
civetweb -A <htpasswd_file> <realm> <user> <passwd>
Unlike other web servers, civetweb does not require CGI scripts to be located
in a special directory. CGI scripts can be anywhere. CGI (and SSI) files are
recognized by the file name pattern. Civetweb uses shell-like glob
patterns. Pattern match starts at the beginning of the string, so essentially
patterns are prefix patterns. Syntax is as follows:
** Matches everything
* Matches everything but slash character, '/'
? Matches any character
$ Matches the end of the string
| Matches if pattern on the left side or the right side matches.
All other characters in the pattern match themselves. Examples:
**.cgi$ Any string that ends with .cgi
/foo Any string that begins with /foo
**a$|**b$ Any string that ends with a or b
# Configuration Options
Below is a list of configuration options understood by Civetweb.
Every option is followed by it's default value. If a default value is not
present, then the default is empty.
### cgi\_pattern `**.cgi$|**.pl$|**.php$`
All files that match `cgi_pattern` are treated as CGI files. Default pattern
allows CGI files be anywhere. To restrict CGIs to a certain directory,
use `/path/to/cgi-bin/**.cgi` as pattern. Note that the full file path is
matched against the pattern, not the URI.
### cgi\_environment
Extra environment variables to be passed to the CGI script in
addition to standard ones. The list must be comma-separated list
of name=value pairs, like this: `VARIABLE1=VALUE1,VARIABLE2=VALUE2`.
### put\_delete\_auth\_file
Passwords file for PUT and DELETE requests. Without password file, it will not
be possible to, PUT new files to the server or DELETE existing ones. PUT and
DELETE requests might still be handled by Lua scripts and CGI paged.
### cgi\_interpreter
Path to an executable to use as CGI interpreter for __all__ CGI scripts
regardless of the script file extension. If this option is not set (which is
the default), Civetweb looks at first line of a CGI script,
[shebang line](http://en.wikipedia.org/wiki/Shebang_(Unix\)), for an
interpreter (not only on Linux and Mac but also for Windows).
For example, if both PHP and Perl CGIs are used, then
`#!/path/to/php-cgi.exe` and `#!/path/to/perl.exe` must be first lines of the
respective CGI scripts. Note that paths should be either full file paths,
or file paths relative to the current working directory of the civetweb
server. If civetweb is started by mouse double-click on Windows, the current
working directory is the directory where the civetweb executable is located.
If all CGIs use the same interpreter, for example they are all PHP, it is
more efficient to set `cgi_interpreter` to the path to `php-cgi.exe`.
The shebang line in the CGI scripts can be omitted in this case.
Note that PHP scripts must use `php-cgi.exe` as executable, not `php.exe`.
### protect\_uri
Comma separated list of URI=PATH pairs, specifying that given
URIs must be protected with password files specified by PATH.
All Paths must be full file paths.
### authentication_domain `mydomain.com`
Authorization realm used for HTTP digest authentication. This domain is
used in the encoding of the `.htpasswd` authorization files as well.
Changing the domain retroactively will render the existing passwords useless.
### ssi\_pattern `**.shtml$|**.shtm$`
All files that match `ssi_pattern` are treated as Server Side Includes (SSI).
SSI is a simple interpreted server-side scripting language which is most
commonly used to include the contents of another file into a web page.
It can be useful when it is desirable to include a common piece
of code throughout a website, for example, headers and footers.
In order for a webpage to recognize an SSI-enabled HTML file, the filename
should end with a special extension, by default the extension should be
either `.shtml` or `.shtm`. These extentions may be changed using the
`ssi_pattern` option.
Unknown SSI directives are silently ignored by civetweb. Currently, two SSI
directives are supported, `<!--#include ...>` and
`<!--#exec "command">`. Note that the `<!--#include ...>` directive supports
three path specifications:
<!--#include virtual="path"> Path is relative to web server root
<!--#include abspath="path"> Path is absolute or relative to
web server working dir
<!--#include file="path">, Path is relative to current document
<!--#include "path">
The `include` directive may be used to include the contents of a file or the
result of running a CGI script. The `exec` directive is used to execute a
command on a server, and show the output that would have been printed to
stdout (the terminal window) otherwise. Example:
<!--#exec "ls -l" -->
For more information on Server Side Includes, take a look at the Wikipedia:
[Server Side Includes](http://en.wikipedia.org/wiki/Server_Side_Includes)
### throttle
Limit download speed for clients. `throttle` is a comma-separated
list of key=value pairs, where key could be:
* limit speed for all connections
x.x.x.x/mask limit speed for specified subnet
uri_prefix_pattern limit speed for given URIs
The value is a floating-point number of bytes per second, optionally
followed by a `k` or `m` character, meaning kilobytes and
megabytes respectively. A limit of 0 means unlimited rate. The
last matching rule wins. Examples:
*=1k,10.0.0.0/8=0 limit all accesses to 1 kilobyte per second,
but give connections the from 10.0.0.0/8 subnet
unlimited speed
/downloads/=5k limit accesses to all URIs in `/downloads/` to
5 kilobytes per second. All other accesses are unlimited
### access\_log\_file
Path to a file for access logs. Either full path, or relative to the current
working directory. If absent (default), then accesses are not logged.
### enable\_directory\_listing `yes`
Enable directory listing, either `yes` or `no`.
### error\_log\_file
Path to a file for error logs. Either full path, or relative to the current
working directory. If absent (default), then errors are not logged.
### global\_auth\_file
Path to a global passwords file, either full path or relative to the current
working directory. If set, per-directory `.htpasswd` files are ignored,
and all requests are authorized against that file.
The file has to include the realm set through `authentication_domain` and the
password in digest format:
user:realm:digest
test:test.com:ce0220efc2dd2fad6185e1f1af5a4327
Password files may be generated using `civetweb -A` as explained above, or
online tools e.g. [this generator](http://www.askapache.com/online-tools/htpasswd-generator).
### index\_files `index.xhtml,index.html,index.htm,index.cgi,index.shtml,index.php`
Comma-separated list of files to be treated as directory index files.
If more than one matching file is present in a directory, the one listed to the left
is used as a directory index.
In case built-in Lua support has been enabled, `index.lp,index.lsp,index.lua`
are additional default index files, ordered before `index.cgi`.
### enable\_keep\_alive `no`
Enable connection keep alive, either `yes` or `no`.
Experimental feature. Allows clients to reuse TCP connection for subsequent
HTTP requests, which improves performance.
For this to work when using request handlers it is important to add the
correct Content-Length HTTP header for each request. If this is forgotten the
client will time out.
### access\_control\_list
An Access Control List (ACL) allows restrictions to be put on the list of IP
addresses which have access to the web server. In the case of the Civetweb
web server, the ACL is a comma separated list of IP subnets, where each
subnet is pre-pended by either a `-` or a `+` sign. A plus sign means allow,
where a minus sign means deny. If a subnet mask is omitted, such as `-1.2.3.4`,
this means to deny only that single IP address.
Subnet masks may vary from 0 to 32, inclusive. The default setting is to allow
all accesses. On each request the full list is traversed, and
the last match wins. Examples:
-0.0.0.0/0,+192.168/16 deny all accesses, only allow 192.168/16 subnet
To learn more about subnet masks, see the
[Wikipedia page on Subnetwork](http://en.wikipedia.org/wiki/Subnetwork).
### extra\_mime\_types
Extra mime types, in tha form `extension1=type1,exten-sion2=type2,...`.
See the [Wikipedia page on Internet media types](http://en.wikipedia.org/wiki/Internet_media_type).
Extension must include a leading dot. Example:
`.cpp=plain/text,.java=plain/text`
### listening\_ports `8080`
Comma-separated list of ports to listen on. If the port is SSL, a
letter `s` must be appended, for example, `80,443s` will open
port 80 and port 443, and connections on port 443 will be SSL-ed.
For non-SSL ports, it is allowed to append letter `r`, meaning 'redirect'.
Redirect ports will redirect all their traffic to the first configured
SSL port. For example, if `listening_ports` is `80r,443s`, then all
HTTP traffic coming at port 80 will be redirected to HTTPS port 443.
It is possible to specify an IP address to bind to. In this case,
an IP address and a colon must be pre-pended to the port number.
For example, to bind to a loopback interface on port 80 and to
all interfaces on HTTPS port 443, use `127.0.0.1:80,443s`.
If the server is built with IPv6 support, `[::]:8080` can be used to
listen to connections to port 8080 from both, IPv4 and IPv6.
IPv6 addresses of network interfaces can be specified as well,
e.g. `[::1]:8080` for the IPv6 loopback interface.
### document\_root `.`
A directory to serve. By default, the current working directory is served.
The current directory is commonly referenced as dot (`.`).
### ssl\_certificate
Path to the SSL certificate file. This option is only required when at least
one of the `listening\_ports` is SSL. The file must be in PEM format,
and it must have both, private key and certificate, see for example
[ssl_cert.pem](https://github.com/civetweb/civetweb/blob/master/resources/ssl_cert.pem)
A description how to create a certificate can be found in doc/OpenSSL.md
### num\_threads `50`
Number of worker threads. Civetweb handles each incoming connection in a
separate thread. Therefore, the value of this option is effectively the number
of concurrent HTTP connections Civetweb can handle.
### run\_as\_user
Switch to given user credentials after startup. Usually, this option is
required when civetweb needs to bind on privileged ports on UNIX. To do
that, civetweb needs to be started as root. From a security point of view,
running as root is not advisable, therefore this option can be used to drop
privileges. Example:
civetweb -listening_ports 80 -run_as_user webserver
### url\_rewrite\_patterns
Comma-separated list of URL rewrites in the form of
`uri_pattern=file_or_directory_path`. When Civetweb receives any request,
it constructs the file name to show by combining `document_root` and the URI.
However, if the rewrite option is used and `uri_pattern` matches the
requested URI, then `document_root` is ignored. Instead,
`file_or_directory_path` is used, which should be a full path name or
a path relative to the web server's current working directory. Note that
`uri_pattern`, as all civetweb patterns, is a prefix pattern.
This makes it possible to serve many directories outside from `document_root`,
redirect all requests to scripts, and do other tricky things. For example,
to redirect all accesses to `.doc` files to a special script, do:
civetweb -url_rewrite_patterns **.doc$=/path/to/cgi-bin/handle_doc.cgi
Or, to imitate support for user home directories, do:
civetweb -url_rewrite_patterns /~joe/=/home/joe/,/~bill=/home/bill/
### hide\_files\_patterns
A pattern for the files to hide. Files that match the pattern will not
show up in directory listing and return `404 Not Found` if requested. Pattern
must be for a file name only, not including directory names. Example:
civetweb -hide_files_patterns secret.txt|*.hide
### request\_timeout\_ms `30000`
Timeout for network read and network write operations, in milliseconds.
If a client intends to keep long-running connection, either increase this
value or (better) use keep-alive messages.
### lua\_preload\_file
This configuration option can be used to specify a Lua script file, which
is executed before the actual web page script (Lua script, Lua server page
or Lua websocket). It can be used to modify the Lua environment of all web
page scripts, e.g., by loading additional libraries or defining functions
required by all scripts.
It may be used to achieve backward compatibility by defining obsolete
functions as well.
### lua\_script\_pattern `"**.lua$`
A pattern for files that are interpreted as Lua scripts by the server.
In contrast to Lua server pages, Lua scripts use plain Lua syntax.
An example can be found in the test directory.
### lua\_server\_page\_pattern `**.lp$|**.lsp$`
Files matching this pattern are treated as Lua server pages.
In contrast to Lua scripts, the content of a Lua server pages is delivered
directly to the client. Lua script parts are delimited from the standard
content by including them between <? and ?> tags.
An example can be found in the test directory.
### websocket\_root
In case civetweb is built with Lua and websocket support, Lua scripts may
be used for websockets as well. Since websockets use a different URL scheme
(ws, wss) than other http pages (http, https), the Lua scripts used for
websockets may also be served from a different directory. By default,
the document_root is used as websocket_root as well.
### access\_control\_allow\_origin
Access-Control-Allow-Origin header field, used for cross-origin resource
sharing (CORS).
See the [Wikipedia page on CORS](http://en.wikipedia.org/wiki/Cross-origin_resource_sharing).
### error\_pages
This option may be used to specify a directory for user defined error pages.
The error pages may be specified for an individual http status code (e.g.,
404 - page requested by the client not found), a group of http status codes
(e.g., 4xx - all client errors) or all errors. The corresponding error pages
must be called error404.ext, error4xx.ext or error.ext, whereas the file
extention may be one of the extentions specified for the index_files option.
See the [Wikipedia page on HTTP status codes](http://en.wikipedia.org/wiki/HTTP_status_code).
### decode\_url `yes`
URL encoded request strings are decoded in the server, unless it is disabled
by setting this option to `no`.
### ssl_verify_peer `no`
Enable client's certificate verification by the server.
### ssl_ca_path
Name of a directory containing trusted CA certificates. Each file in the
directory must contain only a single CA certificate. The files must be named
by the subject name’s hash and an extension of “.0”. If there is more than one
certificate with the same subject name they should have extensions ".0", ".1",
".2" and so on respectively.
### ssl_ca_file
Path to a .pem file containing trusted certificates. The file may contain
more than one certificate.
### ssl_verify_depth `9`
Sets maximum depth of certificate chain. If client's certificate chain is longer
than the depth set here connection is refused.
### ssl_default_verify_paths `yes`
Loads default trusted certificates locations set at openssl compile time.
### ssl_forward_secrecy `yes`
Enable [forward secrecy](https://en.wikipedia.org/wiki/Forward_secrecy).
# Lua Scripts and Lua Server Pages
Pre-built Windows and Mac civetweb binaries have built-in Lua scripting
support as well as support for Lua Server Pages.
Lua scripts (default extension: *.lua) use plain Lua syntax.
The body of the script file is not sent directly to the client,
the Lua script must send header and content of the web page by calling
the function mg.write(text).
Lua Server Pages (default extensions: *.lsp, *.lp) are html pages containing
script elements similar to PHP, using the Lua programming language instead of
PHP. Lua script elements must be enclosed in `<? ?>` blocks, and can appear
anywhere on the page. Furthermore, Lua Server Pages offer the opportunity to
insert the content of a variable by enclosing the Lua variable name in
`<?= ?>` blocks, similar to PHP.
For example, to print the current weekday name and the URI of the current
page, one can write:
<p>
<span>Today is:</span>
<? mg.write(os.date("%A")) ?>
</p>
<p>
URI is <?=mg.request_info.uri?>
</p>
Lua is known for it's speed and small size. Civetweb currently uses Lua
version 5.2.4. The documentation for it can be found in the
[Lua 5.2 reference manual](http://www.lua.org/manual/5.2/).
Note that this example uses function `mg.write()`, which sends data to the
web client. Using `mg.write()` is the way to generate web content from inside
Lua code. In addition to `mg.write()`, all standard Lua library functions
are accessible from the Lua code (please check the reference manual for
details). Lua functions working on files (e.g., `io.open`) use a path
relative to the working path of the civetweb process. The web server content
is located in the path `mg.document_root`.
Information on the request is available in the `mg.request_info`
object, like the request method, all HTTP headers, etcetera.
[page2.lua](https://github.com/civetweb/civetweb/blob/master/test/page2.lua)
is an example for a plain Lua script.
[page2.lp](https://github.com/civetweb/civetweb/blob/master/test/page2.lp)
is an example for a Lua Server Page.
Both examples show the content of the `mg.request_info` object as the page
content. Please refer to `struct mg_request_info` definition in
[civetweb.h](https://github.com/civetweb/civetweb/blob/master/include/civetweb.h)
to see additional information on the elements of the `mg.request_info` object.
Civetweb also provides access to the [SQlite3 database](http://www.sqlite.org/)
through the [LuaSQLite3 interface](http://lua.sqlite.org/index.cgi/doc/tip/doc/lsqlite3.wiki)
in Lua. Examples are given in
[page.lua](https://github.com/civetweb/civetweb/blob/master/test/page.lua) and
[page.lp](https://github.com/civetweb/civetweb/blob/master/test/page.lp).
Civetweb exports the following functions to Lua:
mg (table):
mg.read() -- reads a chunk from POST data, returns it as a string
mg.write(str) -- writes string to the client
mg.include(path) -- sources another Lua file
mg.redirect(uri) -- internal redirect to a given URI
mg.onerror(msg) -- error handler, can be overridden
mg.version -- a string that holds Civetweb version
mg.document_root -- a string that holds the document root directory
mg.auth_domain -- a string that holds the HTTP authentication domain
mg.get_var(str, varname) -- extract variable from (query) string
mg.get_cookie(str, cookie) -- extract cookie from a string
mg.get_mime_type(filename) -- get MIME type of a file
mg.send_file(filename) -- send a file, including MIME type
mg.url_encode(str) -- URL encode a string
mg.url_decode(str, [form]) -- URL decode a string. If form=true, replace + by space.
mg.base64_encode(str) -- BASE64 encode a string
mg.base64_decode(str) -- BASE64 decode a string
mg.md5(str) -- return the MD5 hash of a string
mg.keep_alive(bool) -- allow/forbid to use http keep-alive for this request
mg.request_info -- a table with the following request information
.remote_addr -- IP address of the client as string
.remote_port -- remote port number
.server_port -- server port number
.request_method -- HTTP method (e.g.: GET, POST)
.http_version -- HTTP protocol version (e.g.: 1.1)
.uri -- resource name
.query_string -- query string if present, nil otherwise
.script_name -- name of the Lua script
.https -- true if accessed by https://, false otherwise
.remote_user -- user name if authenticated, nil otherwise
connect (function):
-- Connect to the remote TCP server. This function is an implementation
-- of simple socket interface. It returns a socket object with three
-- methods: send, recv, close, which are synchronous (blocking).
-- connect() throws an exception on connection error.
connect(host, port, use_ssl)
-- Example of using connect() interface:
local host = 'code.google.com' -- IP address or domain name
local ok, sock = pcall(connect, host, 80, 1)
if ok then
sock:send('GET /p/civetweb/ HTTP/1.0\r\n' ..
'Host: ' .. host .. '\r\n\r\n')
local reply = sock:recv()
sock:close()
-- reply now contains the web page https://code.google.com/p/civetweb
end
**IMPORTANT: Civetweb does not send HTTP headers for Lua pages. Therefore,
every Lua Page must begin with a HTTP reply line and headers**, like this:
<? print('HTTP/1.0 200 OK\r\nContent-Type: text/html\r\n\r\n') ?>
<html><body>
... the rest of the web page ...
To serve a Lua Page, civetweb creates a Lua context. That context is used for
all Lua blocks within the page. That means, all Lua blocks on the same page
share the same context. If one block defines a variable, for example, that
variable is visible in all block that follow.
## Websockets for Lua
Civetweb offers support for websockets in Lua as well. In contrast to plain
Lua scripts and Lua server pages, Lua websocket scripts are shared by all clients.
Lua websocket scripts must define a few functions:
open(arg) -- callback to accept or reject a connection
ready(arg) -- called after a connection has been established
data(arg) -- called when the server receives data from the client
close(arg) -- called when a websocket connection is closed
All function are called with one argument of type table with at least one field
"client" to identify the client. When "open" is called, the argument table additionally
contains the "request_info" table as defined above. For the "data" handler, an
additional field "data" is available. The functions "open", "ready" and "data"
must return true in order to keep the connetion open.
Lua websocket pages do support single shot (timeout) and interval timers.
An example is shown in
[websocket.lua](https://github.com/civetweb/civetweb/blob/master/test/websocket.lua).
# Common Problems
- PHP doesn't work - getting empty page, or 'File not found' error. The
reason for that is wrong paths to the interpreter. Remember that with PHP,
the correct interpreter is `php-cgi.exe` (`php-cgi` on UNIX).
Solution: specify the full path to the PHP interpreter, e.g.:
`civetweb -cgi_interpreter /full/path/to/php-cgi`
- Civetweb fails to start. If Civetweb exits immediately when started, this
usually indicates a syntax error in the configuration file
(named `civetweb.conf` by default) or the command-line arguments.
Syntax checking is omitted from Civetweb to keep its size low. However,
the Manual should be of help. Note: the syntax changes from time to time,
so updating the config file might be necessary after executable update.
- Embedding with OpenSSL on Windows might fail because of calling convention.
To force Civetweb to use `__stdcall` convention, add `/Gz` compilation
flag in Visual Studio compiler.

86
3P/civetweb/docs/yaSSL.md Normal file
View File

@@ -0,0 +1,86 @@
Adding CyaSSL Support
=====
### Only required for Windows!
In order to support SSL *HTTPS* connections in Civetweb on Windows,
you may wish to use the GPLv2 licensed CyaSSL library. By using this
library, the resulting binary may have to have the GPL license unless
you buy a commercial license from [wolfSSL](http://www.yassl.com/).
Getting Started
----
- Download Cayssl at http://www.yassl.com/
- Extract the zip file
- To make this seemless, extract to a directory parallel to with Civetweb is
### Example Project
If you download to cyaSSL to cyassl-2.7.0 in a directory parallel to with Civetweb, you can open the *VS2012/civetweb_yassl* solution in Visual Studio.
Build Configuration
----
#### Required include paths for both civetweb and cyassl
- *cyassl_directory*\
- *cyassl_directory*\cyassl\
#### Required civetweb preprocessor defines
- USE_YASSL
- NO_SSL_DL
#### Required cySSL preprocessor defines
- OPENSSL_EXTRA
- HAVE_ERRNO_H
- HAVE_GETHOSTBYNAME
- HAVE_INET_NTOA
- HAVE_LIMITS_H
- HAVE_MEMSET
- HAVE_SOCKET
- HAVE_STDDEF_H
- HAVE_STDLIB_H
- HAVE_STRING_H
- HAVE_SYS_STAT_H
- HAVE_SYS_TYPES_H
#### Required CyaSSL source files
- ctaocrypt/src/aes.c
- ctaocrypt/src/arc4.c
- ctaocrypt/src/asn.c
- ctaocrypt/src/coding.c
- ctaocrypt/src/des3.c
- ctaocrypt/src/dh.c
- ctaocrypt/src/dsa.c
- ctaocrypt/src/ecc.c
- ctaocrypt/src/error.c
- ctaocrypt/src/hc128.c
- ctaocrypt/src/hmac.c
- ctaocrypt/src/integer.c
- ctaocrypt/src/logging.c
- ctaocrypt/src/md2.c
- ctaocrypt/src/md4.c
- ctaocrypt/src/md5.c
- ctaocrypt/src/memory.c
- ctaocrypt/src/misc.c
- ctaocrypt/src/pwdbased.c
- ctaocrypt/src/rabbit.c
- ctaocrypt/src/random.c
- ctaocrypt/src/ripemd.c
- ctaocrypt/src/rsa.c
- ctaocrypt/src/sha.c
- ctaocrypt/src/sha256.c
- ctaocrypt/src/sha512.c
- ctaocrypt/src/tfm.c
- src/crl.c
- src/internal.c
- src/io.c
- src/keys.c
- src/ocsp.c
- src/sniffer.c
- src/ssl.c
- src/tls.c