Differences
This shows you the differences between two versions of the page.
Next revision | Previous revisionNext revisionBoth sides next revision | ||
server:web [2010/02/21 19:58] – created digitalman | server:web [2023/12/20 23:08] – [sbbs.ini] Re-org and beautify digital man | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== Web Server ====== | ====== Web Server ====== | ||
- | TODO | + | The Synchronet Web Server serves static (e.g. files) and dynamic content to HTTP clients (e.g. web browsers). |
+ | |||
+ | ===== Introduction ===== | ||
+ | |||
+ | The Synchronet Web Server is a mostly HTTP 1.1 compliant web server capable of | ||
+ | handing basic web servicing tasks. | ||
+ | general-purpose web server one would come to expect, including (Fast)CGI. | ||
+ | |||
+ | It also, through Server-Side JavaScript (SSJS), allows dynamic pages to be | ||
+ | created which can access BBS data directly. | ||
+ | |||
+ | |||
+ | ===== Configure ===== | ||
+ | |||
+ | The Synchronet Web Server can be configured via [[util: | ||
+ | |||
+ | < | ||
+ | ╔══════════════════════════════════════════════════════════════════════╗ | ||
+ | ║ Web Server | ||
+ | ╠══════════════════════════════════════════════════════════════════════╣ | ||
+ | ║ │Enabled | ||
+ | ║ │Log Level | ||
+ | ║ │HTTP Interfaces | ||
+ | ║ │HTTP Port | ||
+ | ║ │HTTPS Support | ||
+ | ║ │HTTPS Interfaces | ||
+ | ║ │HTTPS Port 443 ║ | ||
+ | ║ │SSJS File Extension | ||
+ | ║ │Index Filenames | ||
+ | ║ │Content Root Directory | ||
+ | ║ │Error Sub-directory | ||
+ | ║ │Strict Transport Security | ||
+ | ║ │Virtual Host Support | ||
+ | ║ │Access Logging | ||
+ | ║ │Max Clients | ||
+ | ║ │Max Inactivity | ||
+ | ║ │Filebase Index Script | ||
+ | ║ │Filebase VPath Prefix | ||
+ | ║ │Filebase VPath for VHosts | ||
+ | ║ │Authentication Methods | ||
+ | ║ │Output Buffer Drain Timeout | ||
+ | ║ │Lookup Client Hostname | ||
+ | ║ │CGI Support | ||
+ | ╚══════════════════════════════════════════════════════════════════════╝ | ||
+ | </ | ||
+ | |||
+ | ... or via [[monitor: | ||
+ | |||
+ | {{: | ||
+ | |||
+ | ... or via manual edit of the '' | ||
+ | |||
+ | ==== sbbs.ini ==== | ||
+ | |||
+ | The '' | ||
+ | |||
+ | ^ Key ^ Default | ||
+ | | AutoStart | ||
+ | | HostName | ||
+ | | LogLevel | ||
+ | | TLSErrorLevel | ||
+ | | Interface | ||
+ | | TLSInterface | ||
+ | | Port | '' | ||
+ | | TLSPort | ||
+ | | BindRetryCount | ||
+ | | BindRetryDelay | ||
+ | | MaxClients | ||
+ | | MaxInactivity | ||
+ | | MaxCgiInactivity | ||
+ | | SemFileCheckFrequency | ||
+ | | IndexFileNames | ||
+ | | RootDirectory | ||
+ | | ErrorDirectory | ||
+ | | CGIDirectory | ||
+ | | DefaultCGIContent | ||
+ | | CGIExtensions | ||
+ | | JavaScriptExtension | ||
+ | | Authentication | ||
+ | | HttpLogFile | ||
+ | | FileIndexScript | ||
+ | | FileVPathPrefix | ||
+ | | FileVPathForVHosts | ||
+ | | OutbufDrainTimeout | ||
+ | | TempDirectory | ||
+ | | Options | ||
+ | |||
+ | === Options === | ||
+ | |||
+ | The '' | ||
+ | |||
+ | Default value: **'' | ||
+ | |||
+ | In addition to the [[config: | ||
+ | |||
+ | == DEBUG_RX == | ||
+ | |||
+ | Log all received data to the console log, as well as various | ||
+ | extra bits related to receiving data. | ||
+ | |||
+ | == DEBUG_TX == | ||
+ | |||
+ | Log all transmitted data except the reply body itself, as well | ||
+ | as various extra bits of information related to transmitted | ||
+ | data. | ||
+ | |||
+ | == DEBUG_SSJS == | ||
+ | |||
+ | Log server-side JavaScript execution details. | ||
+ | |||
+ | == VIRTUAL_HOSTS == | ||
+ | |||
+ | Supports name-based virtual hosts. | ||
+ | host names, you can have each host name return unique content | ||
+ | depending on which hostname is used. ie: if | ||
+ | '' | ||
+ | system, you could have FreeBSD-specific pages on one, and | ||
+ | general *nix stuff on the other. | ||
+ | |||
+ | A virtual host is added by simply putting the desired content | ||
+ | into a sub-directory of [[# | ||
+ | ie: '' | ||
+ | the request host name (very old browsers, or some automated | ||
+ | tools) they will be served out of document root. | ||
+ | It is therefore a good idea to put links to your various | ||
+ | virtual hosts in an '' | ||
+ | like this: | ||
+ | <code html> | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | < | ||
+ | Your browser is either too old to support | ||
+ | name-based virtual hosts, or you have visited a | ||
+ | virtual hosts that is not yet configured. | ||
+ | following are hosted here:< | ||
+ | <a href=" | ||
+ | <a href=" | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | == NO_CGI == | ||
+ | |||
+ | Disable CGI/FastCGI script execution. | ||
+ | |||
+ | == HTTP_LOGGING == | ||
+ | |||
+ | Enable logging to a Common Logfile Format log as described in | ||
+ | the HttpLogFile section. | ||
+ | programs (like Webalizer: http:// | ||
+ | |||
+ | == NO_JAVASCRIPT == | ||
+ | |||
+ | Disable SSJS execution. | ||
+ | |||
+ | == ALLOW_TLS == | ||
+ | |||
+ | Enable TLS/SSL support. | ||
+ | |||
+ | == HSTS_SAFE == | ||
+ | |||
+ | Indicates that all URLs available via http are also available via https and redirects clients who want a TLS session to the https location. | ||
+ | |||
+ | ==== Reference ==== | ||
+ | |||
+ | Web Server configuration settings reference: | ||
+ | |||
+ | === RootDirectory === | ||
+ | |||
+ | Default value: '' | ||
+ | |||
+ | This is the root directory of your web server... a request to | ||
+ | '' | ||
+ | |||
+ | **NOTE**: Older versions of Synchronet had this value default to '' | ||
+ | |||
+ | === ErrorDirectory === | ||
+ | Default value: '' | ||
+ | |||
+ | The directory relative to [[# | ||
+ | message files are located. | ||
+ | numeric HTTP error code they will represent and may be either '' | ||
+ | or '' | ||
+ | same error). | ||
+ | |||
+ | === IndexFileNames === | ||
+ | |||
+ | Default value: '' | ||
+ | |||
+ | A comma-separated list of filenames in order of preference to serve as | ||
+ | the default document in a directory. | ||
+ | '' | ||
+ | Do not remove the '' | ||
+ | web pages at all. | ||
+ | |||
+ | === Authorization === | ||
+ | |||
+ | Default value: '' | ||
+ | |||
+ | A comma-separated list of authentication mechanisms in order of preference. | ||
+ | The standards say that Basic must come first, but no browser currently | ||
+ | appears to use Digest if Basic is listed first. | ||
+ | and Digest. | ||
+ | clear over the wire. | ||
+ | |||
+ | === CGIDirectory === | ||
+ | Default value: '' | ||
+ | |||
+ | A directory relative to [[# | ||
+ | considered CGI-executable. Be careful what files you put in this | ||
+ | directory. | ||
+ | |||
+ | === CGIExtensions === | ||
+ | Default value: '' | ||
+ | |||
+ | A comma-separated list of file extensions/ | ||
+ | extensions will be considered CGI-executable and the web server will | ||
+ | attempt to execute them as such. | ||
+ | |||
+ | Other probably values include: '' | ||
+ | |||
+ | === DefaultCGIContent === | ||
+ | |||
+ | Default value: '' | ||
+ | |||
+ | If the CGI program does not generate a content-type header, this value | ||
+ | will be used for the MIME content-type specified in the HTTP response. | ||
+ | |||
+ | === JavaScriptExtension === | ||
+ | |||
+ | Default value: '' | ||
+ | |||
+ | Files with this extension will be considered SSJS files. | ||
+ | systems, this will be attempted to run with the JavaScript interpreter. | ||
+ | |||
+ | === MaxInactivity === | ||
+ | |||
+ | Default value: '' | ||
+ | |||
+ | If a client holds a connection open for this many seconds without a | ||
+ | request, the web server will shut down the connection. | ||
+ | |||
+ | === MaxCgiInactivity === | ||
+ | |||
+ | Defalut value: '' | ||
+ | |||
+ | If a CGI script runs for more than this many seconds without any | ||
+ | output, it will be terminated and the connection will be shut down. | ||
+ | |||
+ | === HttpLogFile === | ||
+ | |||
+ | Default value: '' | ||
+ | |||
+ | The prefix of log files if HTTP_LOGGING is enabled (See next item) to | ||
+ | store Common Logfile Format logs in. The current virtual host | ||
+ | (if enabled, see next item), date, and '' | ||
+ | |||
+ | === FileVPathPrefix === | ||
+ | Default value: "" | ||
+ | |||
+ | Suggested value: ''/ | ||
+ | |||
+ | A virtual sub-directory of your web root to provide direct HTTP[S] access to your file bases. HTTP-AUTH is used for conditional access/ | ||
+ | |||
+ | === FileVPathForVHosts === | ||
+ | Default value: '' | ||
+ | |||
+ | By default, virtual hosts will not have the virtual file path (if enabled). Set this to '' | ||
+ | |||
+ | === FileIndexScript === | ||
+ | Default value: "" | ||
+ | |||
+ | Suggested value: '' | ||
+ | |||
+ | A Server-side JavaScript (SSJS) file to execute and provide HTML/CSS indexes to file libraries and directories accessed via virtual file paths. | ||
+ | |||
+ | ==== Other configuration files ==== | ||
+ | |||
+ | In addition to the '' | ||
+ | also uses some other configuration files: | ||
+ | |||
+ | === ctrl/ | ||
+ | Contains the file extension to mime-type mapping. | ||
+ | is in the format " | ||
+ | The extensions are case-insensitive and do not include the ' | ||
+ | |||
+ | === ctrl/ | ||
+ | Contains the URLs to the icons used by the default 404.ssjs | ||
+ | script for each file type/ | ||
+ | Example: " | ||
+ | DIRECTORY which is used for directories and DefaultIcon which | ||
+ | is used for extensions which don't exist in the list. | ||
+ | |||
+ | === ctrl/ | ||
+ | |||
+ | This file contains 2 sections where a list of file | ||
+ | extensions and their associated content-creation handlers are | ||
+ | specified: | ||
+ | |||
+ | == [CGI] == | ||
+ | |||
+ | The [CGI] section is for natively-executed CGI handlers | ||
+ | (e.g. "pl = perl" indicates " | ||
+ | |||
+ | == [JavaScript] == | ||
+ | |||
+ | The [JavaScript] section is used for JS-executed content | ||
+ | handlers (e.g. "xjs = xjs_handler.js" | ||
+ | |||
+ | === ctrl/ | ||
+ | Contains a list of system environment variables to pass to CGI | ||
+ | processes. | ||
+ | value, over-ridden value, and prepended or appended text. | ||
+ | |||
+ | |||
+ | ==== webctrl.ini ==== | ||
+ | |||
+ | Each directory under the [[# | ||
+ | the directory it's in and all child directories. | ||
+ | either globally, in a per-filename group, or, in version 3.17 or greater, a per-directory-name group. | ||
+ | Using the * and ? wildcards as the group name such as '' | ||
+ | |||
+ | === AccessRequirements === | ||
+ | Specifies an ARS string which all users must match to be able to access | ||
+ | files in this directory. | ||
+ | |||
+ | For example, to require a login, but allow **any** user to access files in a | ||
+ | directory, but only a sysop to access '' | ||
+ | <file webctrl.ini> | ||
+ | AccessRequirements=level 0 | ||
+ | [*.log] | ||
+ | AccessRequirements=level 90 | ||
+ | [*.git] | ||
+ | AccessRequirements=level 90 | ||
+ | </ | ||
+ | |||
+ | === Realm === | ||
+ | Sets the realm that is displayed to the user for the HTTP login. | ||
+ | Default is the BBS name. | ||
+ | |||
+ | === DigestRealm === | ||
+ | Sets the realm that is displayed to the user for the HTTP login when | ||
+ | Digest authentication is being used. Default is the [[#Realm]] value. | ||
+ | |||
+ | === Authorization === | ||
+ | A comma-separated list of authentication mechanisms in order of | ||
+ | preference. | ||
+ | browser currently appears to use Digest if Basic is listed first. | ||
+ | Supported values are '' | ||
+ | users password is never sent over the wire. | ||
+ | |||
+ | === ErrorDirectory === | ||
+ | Specifies a different directory to check for error pages. | ||
+ | page is not found, will still check the global error directory. | ||
+ | |||
+ | === CGIDirectory === | ||
+ | Specify an alternate CGI directory to check for CGI files. | ||
+ | |||
+ | === PathInfoIndex === | ||
+ | Specifies that the index files can be ran for unlocated pages in the | ||
+ | current directory. | ||
+ | |||
+ | === FastCGISocket === | ||
+ | Specifies the socket address of a FastCGI listener in either < | ||
+ | <file webctrl.ini> | ||
+ | [*.php] | ||
+ | FastCGISocket=127.0.0.1: | ||
+ | </ | ||
+ | |||
+ | See [[howto: | ||
+ | |||
+ | === Rewrite* === | ||
+ | Specifies a Javascript snippet which can modify the http_request.request_string. | ||
+ | |||
+ | <file webctrl.ini> | ||
+ | RewriteDetail=var n=http_request.request_string.replace(/ | ||
+ | </ | ||
+ | |||
+ | If the expression returns " | ||
+ | an internal redirect. | ||
+ | |||
+ | Added on November 3rd, 2015 to CVS (in 3.17a). ([[https:// | ||
+ | |||
+ | === JSPreExec === | ||
+ | A JavaScript snippet which is executed in the same context as Rewrite* lines, but before any Rewrites are executed. | ||
+ | |||
+ | Added on November 3rd, 2015 to CVS (in 3.17a). | ||
+ | |||
+ | ===== JavaScript Objects ===== | ||
+ | In addition to the standard JavaScript objects, the web server provides the | ||
+ | following: | ||
+ | |||
+ | ==== http_request object ==== | ||
+ | |||
+ | The http_request object contains information from the client that was included | ||
+ | during this request. | ||
+ | |||
+ | === path_info === | ||
+ | Contains extra path information that was included with the | ||
+ | request AFTER the URI which identified this script. | ||
+ | example, if the request was for | ||
+ | '' | ||
+ | would contain the string "/ | ||
+ | |||
+ | === method === | ||
+ | Contains the HTTP method used to run the script. | ||
+ | writing, the available methods are " | ||
+ | " | ||
+ | |||
+ | === virtual_path === | ||
+ | The virtual path that this URI was reached by. This is the | ||
+ | portion of the URI from the end of the host to the end of the | ||
+ | filename. | ||
+ | |||
+ | === query === | ||
+ | This object contains the values of any form data which was | ||
+ | submitted with the request. | ||
+ | name/value pairs. | ||
+ | for this is that it is legal and often useful to have multiple | ||
+ | form fields with the same name. | ||
+ | |||
+ | === query_string === | ||
+ | If a query string was included, this is the raw, unparsed query | ||
+ | string. | ||
+ | |||
+ | === post_data === | ||
+ | As with query_string but for data which was POSTed. | ||
+ | |||
+ | === header === | ||
+ | An associative array of header name/value pairs. | ||
+ | |||
+ | === cookie === | ||
+ | Much like the query object, this object contains key/value pairs | ||
+ | of set cookies. | ||
+ | multiple values for the same key can be set for cookies. | ||
+ | |||
+ | === real_path === | ||
+ | The real OS's complete path to this script. | ||
+ | |||
+ | === ars === | ||
+ | The ARS string which applies to this request. | ||
+ | |||
+ | === request_string === | ||
+ | |||
+ | The raw request string sent by the client. | ||
+ | |||
+ | === host === | ||
+ | The value of the host header for this request. | ||
+ | === vhost === | ||
+ | The virtual host serving this request. | ||
+ | === http_ver === | ||
+ | The HTTP version used for this request as a string. | ||
+ | |||
+ | === remote_ip === | ||
+ | The IP address of the client. | ||
+ | |||
+ | === remote_host === | ||
+ | |||
+ | If the web server does host lookups (disabled by default), this | ||
+ | is the remote hostname. | ||
+ | |||
+ | === scheme === | ||
+ | |||
+ | " | ||
+ | ==== http_reply object ==== | ||
+ | |||
+ | |||
+ | The http_reply object is used to pass information about the reply back to the | ||
+ | Synchronet web server. | ||
+ | |||
+ | === status === | ||
+ | |||
+ | HTTP status string. | ||
+ | |||
+ | === header === | ||
+ | An associative array of headers to include with the reply. | ||
+ | only pre-defined one is " | ||
+ | |||
+ | === fast === | ||
+ | This optional property can be set to " | ||
+ | directly to the client for HTTP/1.0 connections. | ||
+ | keep-alives from working but generally appears faster to the | ||
+ | client. | ||
+ | required for HTTP/1.1. | ||
+ | |||
+ | |||
+ | ==== Extra global methods ==== | ||
+ | |||
+ | The web server also adds a new global JavaScript method that requests that the specified cookie be set: | ||
+ | |||
+ | set_cookie(string key, | ||
+ | | ||
+ | [, time_t expires | ||
+ | [, string domain | ||
+ | [, string path | ||
+ | [, bool secure ]]]]) | ||
+ | |||
+ | |||
+ | ==== Extra global variables ==== | ||
+ | |||
+ | === web_root_dir === | ||
+ | The path to the web server' | ||
+ | |||
+ | See also: the RootDirectory key under [Web] in [[config: | ||
+ | |||
+ | ===== XJS files ===== | ||
+ | |||
+ | XJS files, handled by '' | ||
+ | an easier method of generating SSJS files. | ||
+ | commands embedded in them using special tags much like PHP. XJS files are | ||
+ | translated on-the-fly to .ssjs files using the same name with '' | ||
+ | For example, a file named test.xjs will, when ran, generate a '' | ||
+ | file. | ||
+ | |||
+ | |||
+ | ==== XJS syntax ==== | ||
+ | |||
+ | In an XJS file, everything not within a special xjs tag is send to the remote | ||
+ | host unmodified, and everything inside the xjs tag is interpreted as JS | ||
+ | statements to be executed at that point in the file. The xjs tag begins with | ||
+ | either "<? | ||
+ | |||
+ | <code html> | ||
+ | < | ||
+ | < | ||
+ | Your SysOp "<? | ||
+ | <?xjs write(system.name) ?> | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | This would send the following web page to the remote system: | ||
+ | <code html> | ||
+ | < | ||
+ | < | ||
+ | Your SysOp " | ||
+ | My Brand New BBS | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | Looping constructs are permitted, however, not using brackets can result in | ||
+ | unexpected effects. | ||
+ | brackets with looping and flow control items. | ||
+ | |||
+ | The following example displays the numbers from one to 10. | ||
+ | <code html> | ||
+ | < | ||
+ | < | ||
+ | <?xjs | ||
+ | var i; | ||
+ | for(i=1; i<=10; i++) { | ||
+ | ?> | ||
+ | <?xjs write(i) ?>< | ||
+ | <?xjs } ?> | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | ==== XJS-specific global methods and properties ==== | ||
+ | |||
+ | The following JavaScript methods and properties are available to XJS files only. | ||
+ | |||
+ | === xjs_load(filename) === | ||
+ | Runs the specified xjs file at the current position. | ||
+ | are NOT visible to '' | ||
+ | relative to the including file (or absolute.) | ||
+ | |||
+ | === cwd === | ||
+ | Contains the path that the current xjs script was loaded from and which | ||
+ | parameters to '' | ||
+ | the value of '' | ||
+ | check for files. | ||
+ | |||
+ | {{indexmenu_n> | ||