Lines Matching +full:- +full:a
4 CivetWeb is a small and easy to use web server.
5 It may be embedded into C/C++ host applications or used as a stand-alone
9 The stand-alone server is self-contained, and does not require any external
11 [Visual C++ Redistributable](http://www.microsoft.com/en-us/download/details.aspx?id=30679).
15 ----
17 On Windows, UNIX and Mac, the CivetWeb stand-alone executable may be started
19 Running `CivetWeb` in a terminal, optionally followed by configuration parameters
20 (`CivetWeb [OPTIONS]`) or a configuration file name (`CivetWeb [config_file_name]`),
24 Pressing `Ctrl-C` keys will stop the server.
27 Right-clicking on the icon pops up a menu, where it is possible to stop
32 Thus, the easiest way to share a folder on Windows is to copy `CivetWeb.exe`
33 to this folder, double-click the exe, and launch a browser at
35 be changed to a machine's name if a folder is accessed from another computer.
38 If a configuration file is specified explicitly in the command line, i.e.
43 The configuration file is a sequence of lines, each line containing one
46 Here is the example of a `CivetWeb.conf` file:
52 When a configuration file is used, additional command line arguments may
54 All command line arguments must start with `-`.
57 `CivetWeb -document_root D:\web`. Then the `D:\web` directory will be served
59 configuration file. The configuration options section below provides a good
62 Note that configuration options on the command line must start with `-`,
67 $ CivetWeb -listening_ports 1234 -document_root /var/www
77 CivetWeb -A <htpasswd_file> <realm> <user> <passwd>
81 ----
83 Below is a list of configuration options understood by CivetWeb.
84 Every option is followed by it's default value. If a default value is not
89 CivetWeb uses shell-like glob patterns for several configuration options,
104 **a$|**b$ Any string that ends with a or b
110 the stand-alone executable as well as for applications embedding CivetWeb.
111 The stand-alone executable supports some additional options: see *Options from `main.c`*.
112 The options are explained in alphabetic order - for a quick start, check
116 Access-Control-Allow-Headers header field, used for cross-origin resource
117 sharing (CORS) pre-flight requests.
118 See the [Wikipedia page on CORS](http://en.wikipedia.org/wiki/Cross-origin_resource_sharing).
120 If set to an empty string, pre-flights will not allow additional headers.
121 If set to "*", the pre-flight will allow whatever headers have been requested.
122 If set to a comma separated list of valid HTTP headers, the pre-flight will return
127 Access-Control-Allow-Methods header field, used for cross-origin resource
128 sharing (CORS) pre-flight requests.
129 See the [Wikipedia page on CORS](http://en.wikipedia.org/wiki/Cross-origin_resource_sharing).
131 If set to an empty string, pre-flights will not be supported directly by the server,
132 but scripts may still support pre-flights by handling the OPTIONS method properly.
133 If set to "*", the pre-flight will allow whatever method has been requested.
134 If set to a comma separated list of valid HTTP methods, the pre-flight will return
139 Access-Control-Allow-Origin header field, used for cross-origin resource
141 See the [Wikipedia page on CORS](http://en.wikipedia.org/wiki/Cross-origin_resource_sharing).
146 web server, the ACL is a comma separated list of IP subnets, where each
147 subnet is pre-pended by either a `-` or a `+` sign. A plus sign means allow,
148 where a minus sign means deny. If a subnet mask is omitted, such as `-1.2.3.4`,
155 -0.0.0.0/0,+192.168/16 deny all accesses, only allow 192.168/16 subnet
161 Path to a file for access logs. Either full path, or relative to the current
169 `-additional_header "X-Frame-Options: SAMEORIGIN"`
194 Note: This parameter affects only index scripts. A path like /here/script.cgi/handle/this.ext
203 While using the `sendfile` call will lead to a performance boost for HTTP connections,
219 addition to standard ones. The list must be comma-separated list
225 the default), CivetWeb looks at first line of a CGI script,
230 `#!/path/to/php-cgi.exe` and `#!/path/to/perl.exe` must be first lines of the
233 server. If CivetWeb is started by mouse double-click on Windows, the current
237 more efficient to set `cgi_interpreter` to the path to `php-cgi.exe`.
239 Note that PHP scripts must use `php-cgi.exe` as executable, not `php.exe`.
243 allows CGI files be anywhere. To restrict CGIs to a certain directory,
244 use `/path/to/cgi-bin/**.cgi` as the pattern. Note that the full file path is
257 A directory to serve. By default, the current working directory is served.
277 correct Content-Length HTTP header for each request. If this is forgotten the
282 keep\_alive\_timeout\_ms to 0. Currently, this is done as a default value,
283 but this configuration is redundant. In a future version, the keep\_alive
285 a timeout > 0 is set.
288 If this configuration value is set to `yes`, the server will send a
289 websocket PING message to a websocket client, once the timeout set by
291 feature will reply with a PONG message.
300 Path to a file for error logs. Either full path, or relative to the current
304 This option may be used to specify a directory for user defined error pages.
305 To specify a directory, make sure the name ends with a backslash (Windows)
308 404 - page requested by the client not found), a group of http status codes
309 (e.g., 4xx - all client errors) or all errors. The corresponding error pages
315 Extra mime types, in the form `extension1=type1,exten-sion2=type2,...`.
317 Extension must include a leading dot. Example:
321 Path to a global passwords file, either full path or relative to the current
322 working directory. If set, per-directory `.htpasswd` files are ignored,
331 Password files may be generated using `CivetWeb -A` as explained above, or
332 online tools e.g. [this generator](http://www.askapache.com/online-tools/htpasswd-generator).
335 A pattern for the files to hide. Files that match the pattern will not
337 must be for a file name only, not including directory names. Example:
339 CivetWeb -hide_files_patterns secret.txt|**.hide
342 hide all files with a certain extension, make sure to use **.extension
346 Comma-separated list of files to be treated as directory index files.
347 If more than one matching file is present in a directory, the one listed to the left
348 is used as a directory index.
350 In case built-in Lua support has been enabled, `index.lp,index.lsp,index.lua`
354 Idle timeout between two requests in one keep-alive connection.
359 Unfortunately, browsers do not close the keep-alive connection after loading
360 all resources required to show a website.
361 The server closes a keep-alive connection, if there is no additional request
369 automatically use keep-alive if keep\_alive\_timeout\_ms is not 0.
373 The configured value is a timeout in milliseconds. Setting the value to 0
375 Setting the value to -1 will turn off linger.
376 If the value is not set (or set to -2), CivetWeb will not set the linger
381 offers a timeout in seconds, so the value should be an integer multiple
386 Run a Lua script in the background, independent from any connection.
404 This configuration option can be used to specify a Lua script file, which
413 A pattern for files that are interpreted as Lua scripts by the server.
419 In contrast to Lua scripts, the content of a Lua server pages is delivered
425 A pattern for websocket script files that are interpreted as Lua scripts by the server.
428 Comma-separated list of ports to listen on. If the port is SSL, a
430 port 80 and port 443, and connections on port 443 will be SSL-ed.
431 For non-SSL ports, it is allowed to append letter `r`, meaning 'redirect'.
437 an IP address and a colon must be pre-pended to the port number.
438 For example, to bind to a loopback interface on port 80 and to
458 `[2001:0db8::1234]:80`). To get a list of available network interface
459 addresses, use `ipconfig` (in a `cmd` window in Windows) or `ifconfig`
460 (in a Linux shell).
462 hosts file of your operating system for a proper hostname
465 local host, you could use `ip6-localhost:80`. This translates to
470 Avahi). When using a hostname, you need to test in your particular network
471 environment - in some cases, you might need to resort to a fixed IP address.
474 a port number), use `0` for the port number. This will make it necessary to
480 A buffer of the configured size is pre allocated for every worker thread.
483 The server has to read the entire header from a client or from a CGI script,
486 The configuration value is approximate, the real limit might be a few bytes off.
490 Number of worker threads. CivetWeb handles each incoming connection in a
500 Passwords file for PUT and DELETE requests. Without a password file, it will not
506 If a client intends to keep long-running connection, either increase this
507 value or (better) use keep-alive messages.
512 that, CivetWeb needs to be started as root. From a security point of view,
516 civetweb -listening_ports 80 -run_as_user webserver
521 SSI is a simple interpreted server-side scripting language which is most
522 commonly used to include the contents of another file in a web page.
523 It can be useful when it is desirable to include a common piece
524 of code throughout a website, for example, headers and footers.
526 In order for a webpage to recognize an SSI-enabled HTML file, the filename
527 should end with a special extension, by default the extension should be
532 directives are supported, `<!--#include ...>` and
533 `<!--#exec "command">`. Note that the `<!--#include ...>` directive supports
536 <!--#include virtual="path"> Path is relative to web server root
537 <!--#include abspath="path"> Path is absolute or relative to
539 <!--#include file="path">, Path is relative to current document
540 <!--#include "path">
542 The `include` directive may be used to include the contents of a file or the
543 result of running a CGI script. The `exec` directive is used to execute a
544 command on a server, and show the output that would have been printed to
547 <!--#exec "ls -l" -->
549 For more information on Server Side Includes, take a look at the Wikipedia:
553 Name of a directory containing trusted CA certificates. Each file in the
554 directory must contain only a single CA certificate. The files must be named
560 Path to a .pem file containing trusted certificates. The file may contain
568 A description how to create a certificate can be found in doc/OpenSSL.md
571 Path to an SSL certificate chain file. As a default, the ssl\_certificate file is used.
591 ------------ | -------------
607 a different filename and then to rename it to the configured pem file name to
611 on a tmpfs (linux) on a system with very high throughput.
621 Set the maximum time (in seconds) a cache may store a static files.
623 This option will set the `Cache-Control: max-age` value for static files.
624 Dynamically generated content, i.e., content created by a script or callback,
627 A value >0 corresponds to a maximum allowed caching time in seconds.
629 A value of 0 will send "do not cache" headers for all static files.
634 Set the `Strict-Transport-Security` header, and set the `max-age` value.
641 or set to -1, no `Strict-Transport-Security` header will be sent.
642 For values <-1 and values >31622400, the behaviour is undefined.
649 for a full buffer or timeout to occur.
655 Limit download speed for clients. `throttle` is a comma-separated
662 The value is a floating-point number of bytes per second, optionally
663 followed by a `k` or `m` character, meaning kilobytes and
664 megabytes respectively. A limit of 0 means unlimited rate. The
675 Comma-separated list of URL rewrites in the form of
680 `file_or_directory_path` is used, which should be a full path name or
681 a path relative to the web server's current working directory. Note that
682 `uri_pattern`, as all CivetWeb patterns, is a prefix pattern.
686 to redirect all accesses to `.doc` files to a special script, do:
688 CivetWeb -url_rewrite_patterns **.doc$=/path/to/cgi-bin/handle_doc.cgi
692 CivetWeb -url_rewrite_patterns /~joe/=/home/joe/,/~bill=/home/bill/
696 be used for websockets as well. Since websockets use a different URL scheme
698 websockets may also be served from a different directory. By default,
714 the stand-alone executable. These options are not supported by other applications
718 Use the configured string as a server name. For Windows, this will be shown as
726 For Windows, use this website as a link in the systray, replacing the default
734 A domain configuration file may have the same options as the main server, with
739 ----
742 Pre-built Windows and Mac CivetWeb binaries have built-in Lua scripting
754 insert the content of a variable by enclosing the Lua variable name in
761 <? mg.write(os.date("%A")) ?>
784 CivetWeb can be built with Lua 5.1, 5.2, 5.3, 5.4 (currently pre-release)
791 details). Lua functions working on files (e.g., `io.open`) use a path
798 is an example for a plain Lua script.
801 is an example for a Lua Server Page.
804 is a Lua Server Page showing "Kepler Syntax" in addition to traditional CivetWeb
823 mg.read() -- reads a chunk from POST data, returns it as a string
824 mg.write(str) -- writes string to the client
825 mg.include(filename, [pathtype]) -- include another Lua Page file (Lua Pages only)
826 -- pathtype can be "abs", "rel"/"file" or "virt[ual]"
827 -- like defined for SSI #include
828 mg.redirect(uri) -- internal redirect to a given URI
829 mg.onerror(msg) -- error handler, can be overridden
830 mg.version -- a string that holds CivetWeb version
831 mg.document_root -- a string that holds the document root directory
832 mg.auth_domain -- a string that holds the HTTP authentication domain
833 mg.get_var(str, varname) -- extract variable from (query) string
834 mg.get_cookie(str, cookie) -- extract cookie from a string
835 mg.get_mime_type(filename) -- get MIME type of a file
836 mg.get_info(infotype) -- get server status information
837 mg.send_file(filename) -- send a file, including all required HTTP headers
838 mg.send_file_body(filename) -- send a file, excluding HTTP headers
839 mg.url_encode(str) -- URL encode a string
840 mg.url_decode(str, [form]) -- URL decode a string. If form=true, replace + by space.
841 mg.base64_encode(str) -- BASE64 encode a string
842 mg.base64_decode(str) -- BASE64 decode a string
843 mg.md5(str) -- return the MD5 hash of a string
844 mg.keep_alive(bool) -- allow/forbid to use http keep-alive for this request
845 mg.request_info -- a table with the following request information
846 .remote_addr -- IP address of the client as string
847 .remote_port -- remote port number
848 .server_port -- server port number
849 .request_method -- HTTP method (e.g.: GET, POST)
850 .http_version -- HTTP protocol version (e.g.: 1.1)
851 .uri -- resource name
852 .query_string -- query string if present, nil otherwise
853 .script_name -- name of the Lua script
854 .https -- true if accessed by https://, false otherwise
855 .remote_user -- user name if authenticated, nil otherwise
859 -- Connect to the remote TCP server. This function is an implementation
860 -- of simple socket interface. It returns a socket object with three
861 -- methods: send, recv, close, which are synchronous (blocking).
862 -- connect() throws an exception on connection error.
863 -- use_ssl is not implemented.
866 -- Example of using connect() interface:
867 local host = 'www.example.com' -- IP address or domain name
874 -- reply now contains the web page http://www.example.com/
881 To serve a Lua Page, CivetWeb creates a Lua context. That context is used for
883 share the same context. If one block defines a variable, for example, that
891 mg.write('HTTP/1.0 200 OK\r\nContent-Type: text/html\r\n\r\n')
896 Content-Type: text/html
903 <? mg.write('HTTP/1.0 200 OK\r\nContent-Type: text/html\r\n\r\n') ?>
908 In this case, CivetWeb automatically creates a "200 OK"/"Content-Type: text/html"
914 HTML pages, while traditional CivetWeb syntax can be used to send a content-type
922 Lua websocket scripts must define a few functions:
923 open(arg) -- callback to accept or reject a connection
924 ready(arg) -- called after a connection has been established
925 data(arg) -- called when the server receives data from the client
926 close(arg) -- called when a websocket connection is closed
942 in a special directory. CGI scripts files are recognized by the file name pattern
947 Furthermore, you must either configure a `cgi\_interpreter` to be used for all
959 Every CGI request will spawn a new child process. Data sent from the
964 In case a CGI script cannot handle a particular request, it might
965 write a short error message to stderr instead of writing to stdout.
968 A script should not write to stderr after writing a reply header
970 logging/debugging), the CGI script should redirect stderr to a
975 ----
978 - PHP doesn't work - getting empty page, or 'File not found' error. The
980 the correct interpreter is `php-cgi.exe` (`php-cgi` on UNIX).
982 `CivetWeb -cgi_interpreter /full/path/to/php-cgi`
984 - `php-cgi` is unavailable, for example on Mac OS X. As long as the `php` binary is installed, you …
988 echo "Content-Type: text/html\r\n\r\n";
992 - CivetWeb fails to start. If CivetWeb exits immediately when started, this
993 usually indicates a syntax error in the configuration file
994 (named `civetweb.conf` by default) or the command-line arguments.
1000 - Embedding with OpenSSL on Windows might fail because of calling convention.