Differences

This shows you the differences between two versions of the page.

--- server:web [2010/02/21 20:37] – digitalman
+++ server:web [2023/12/23 02:14] (current) – [Configure] Update SCFG screenshot digital man
@@ Line 1: / Line 1: @@
 ====== Web Server ======
+The Synchronet Web Server serves static (e.g. files) and dynamic content to HTTP clients (e.g. web browsers).
 ===== Introduction =====
@@ Line 5: / Line 7: @@
 The Synchronet Web Server is a mostly HTTP 1.1 compliant web server capable of
 handing basic web servicing tasks.  It has most of the basic features of a
-general-purpose web server one would come to expect (including CGI).
+general-purpose web server one would come to expect, including (Fast)CGI.
 It also, through Server-Side JavaScript (SSJS), allows dynamic pages to be
@@ Line 11: / Line 13: @@
-===== Web Server Configuration =====
+===== Configure =====
-Most of the web server configuration is in your [[Startup INI]] file (usually
-ctrl/sbbs.ini). The ''[Web]'' section contains the following unique settings:
+The Synchronet Web Server can be configured via [[util:SCFG]]:Servers->Web Server:
+<file>
+╔══════════════════════════════════════════════════════════════════╗
+║                            Web Server                            ║
+╠══════════════════════════════════════════════════════════════════╣
+║ │Enabled                       Yes                               ║
+║ │Log Level                     Informational                     ║
+║ │HTTP Interfaces               0.0.0.0, ::                       ║
+║ │HTTP Port                     80                                ║
+║ │HTTPS Support                 Yes                               ║
+║ │HTTPS Interfaces              0.0.0.0, ::                       ║
+║ │HTTPS Port                    443                               ║
+║ │SSJS File Extension           .ssjs                             ║
+║ │Index Filenames               index.html, index.ssjs, index.xjs ║
+║ │Content Root Directory        ../webv4/root                     ║
+║ │Error Sub-directory           error                             ║
+║ │Strict Transport Security     No                                ║
+║ │Virtual Host Support          No                                ║
+║ │Access Logging                <disabled>                        ║
+║ │Max Clients                   100                               ║
+║ │Max Inactivity                2 minutes                         ║
+║ │Filebase Index Script         webfileindex.ssjs                 ║
+║ │Filebase VPath Prefix         /files/                           ║
+║ │Filebase VPath for VHosts     No                                ║
+║ │Authentication Methods        Basic,Digest,TLS-PSK              ║
+║ │Output Buffer Drain Timeout   10 ms                             ║
+║ │Lookup Client Hostname        No                                ║
+║ │CGI Support                   No                                ║
+║ │CGI Directory                 cgi-bin                           ║
+║ │CGI File Extensions           .cgi                              ║
+║ │CGI Default Content-Type      text/plain                        ║
+║ │CGI Max Inactivity            2 minutes                         ║
+║ │JavaScript Settings...                                          ║
+║ │Failed Login Attempts...                                        ║
+╚══════════════════════════════════════════════════════════════════╝
+</file>
+... or via [[monitor:SBBSCTRL]]:Web->Configure:
+{{:server:sbbsctrl.3.20.web.config.png|}}
+... or via manual edit of the ''[Web]'' section of the ''[[dir:ctrl]]/[[config:sbbs.ini]]'' file.
+==== sbbs.ini ====
+The ''[Web]'' section of your [[config:sbbs.ini]] file supports the following configuration settings (keys):
+^ Key                      ^ Default          ^ Description ^
+| AutoStart                | ''true''         | Automatically start-up the server when Synchronet is started |
+| HostName	           | //none//         | Override system hostname |
+| LogLevel	           | Informational    | Default minimum severity of log messages to view or log-to-disk |
+| TLSErrorLevel	           | Emergency	      | Maximum severity of TLS-related log messages |
+| Interface                | ''0.0.0.0,::''   | Comma-separated list of IPv4 and IPv6 addresses of network interfaces and optional port numbers to listen for incoming HTTP/TCP connections |
+| TLSInterface             | //Interface//    | ... for incoming HTTPS/TLS connections |
+| Port                     | ''80''           | Default TCP port to listen for incoming HTTP connections |
+| TLSPort                  | ''443''          | Default TCP port to listen for incoming HTTPS/TLS connections |
+| BindRetryCount	   | 2	              | Default number of network interface/port bind retry attempts |
+| BindRetryDelay	   | 15	              | Default number of seconds to wait between bind attempts |
+| MaxClients               | 100              | Maximum number of simultaneous connections supported (0 = unlimited) |
+| MaxInactivity            | ''2m''           | Maximum duration of client inactivity before disconnection |
+| MaxCgiInactivity         | ''2m''           | Maximum duration of CGI application inactivity |
+| SemFileCheckFrequency    | //global// (2)   | Seconds between semaphore file checks |
+| IndexFileNames           | ''index.html,index.ssjs''    | Index filenames to search for and serve up (when no file name was requested) |
+| RootDirectory            | ''../web/root''  | Files are served out of this directory tree |
+| ErrorDirectory           | ''error''        | Sub-directory of //RootDirectory// where error files are served from |
+| CGIDirectory             | ''cgi-bin''      | Sub-directory of //RootDirectory// where CGI applications are served from |
+| DefaultCGIContent        | ''text/plain''   | Default MIME-type of CGI content |
+| CGIExtensions            | ''.cgi''         | Comma-separate list of file extensions (suffixes) used to recognize CGI application files |
+| JavaScriptExtension      | ''.ssjs''        | File extension used to recognize Server-side JavaScript content files |
+| Authentication           | ''Basic,Digest,TLS-PSK ''    | Authentication methods supported |
+| HttpLogFile              | ''[[dir:data]]/logs/http-''  | Path prefix for HTTP access log files |
+| FileIndexScript          | ""               | Server-side JavaScript to execute to provide HTML/CSS library and directory listings of virtual file paths (e.g. ''webfileindex.ssjs'') |
+| FileVPathPrefix          | ""               | Virtual path for HTTP file base access, suggested value: ''/files/'' |
+| FileVPathForVHosts       | ''false''        | If you'd like your virtual hosts to provide HTTP access to your file bases (using virtual file paths), set this to ''true'' |
+| OutbufDrainTimeout       | ''10''           | Number of milliseconds to wait for output buffer to drain |
+| TempDirectory	           | ''../temp/''     | Override default temporary file directory |
+| Options                  |                  | See below for details |
+=== Options ===
+The ''Options'' key is set to a ''|'' separated list of options to enable.
+Default value: **''NO_HOST_LOOKUP | HTTP_LOGGING | NO_CGI''**
+In addition to the [[config:sbbs.ini|standard options]], the web server also supports the following:
+== 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.  If your system has multiple
+host names, you can have each host name return unique content
+depending on which hostname is used.  ie: if
+''freebsd.synchro.net'' and ''nix.synchro.net'' both resolved to your
+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 [[#RootDirectory]] with the desired hostname
+ie: ''web/root/freebsd.synchro.net/'' if the browser doesn't send
+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 ''index.html'' page in [[#RootDirectory]] something
+like this:
+<code html>
+<html>
+  <head>
+    <title>Old Browser</title>
+  </head>
+  <body>
+    Your browser is either too old to support
+    name-based virtual hosts, or you have visited a
+    virtual hosts that is not yet configured.  The
+    following are hosted here:<br>
+    <a href="freebsd.synchro.net">freebsd.synchro.net</a><br>
+    <a href="nix.synchro.net">nix.synchro.net</a><br>
+  </body>
+</html>
+</code>
+== NO_CGI ==
+Disable CGI/FastCGI script execution.
+== HTTP_LOGGING ==
+Enable logging to a Common Logfile Format log as described in
+the HttpLogFile section.  Usefull for running log analysis
+programs (like Webalizer: http://www.mrunix.net/webalizer/)
+== 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.
-==== [Web] Section Keys ====
+==== Reference ====
+Web Server configuration settings reference:
 === RootDirectory ===
@@ Line 25: / Line 184: @@
 ''http://yourbbs.synchro.net/index.html'' will be served out of this directory.
-::!:: Older versions of Synchronet had this value default to ''../web/html''.
+**NOTE**: Older versions of Synchronet had this value default to ''../web/html''
 === ErrorDirectory ===
 Default value: ''error''
-The directory relative to [#RootDirectory]] where the various error
+The directory relative to [[#RootDirectory]] where the various error
 message files are located.  The error message files are named by the
 numeric HTTP error code they will represent and may be either ''.html''
@@ Line 48: / Line 207: @@
 === Authorization ===
-Default value: ''Basic,Default''
+Default value: ''Basic,Digest''
 A comma-separated list of authentication mechanisms in order of preference.
@@ Line 108: / Line 267: @@
 (if enabled, see next item), date, and ''.log'' are appended to this (e.g.''http-2005-03-12.log'').
-=== Options ===
+=== FileVPathPrefix ===
+Default value: ""
-Default value: ''NO_HOST_LOOKUP''
+Suggested value: ''/files/''
-The | separated list of options to enable.  In addition to the standard
+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/restrictions, when necessary. The trailing slash is important.
-options, the web server also supports the following:
-  * ''DEBUG_RX'' \\
+=== FileVPathForVHosts ===
-Log all received data to the console log, as well as various
+Default value: ''false''
-extra bits related to receiving data.
-  *  DEBUG_TX
+By default, virtual hosts will not have the virtual file path (if enabled). Set this to ''true'' if you would like your virtual hosts to support the virtual file paths as well.
-        Log all transmitted data except the reply body itself, as well
-        as various extra bits of information related to transmitted
-        data.
-    VIRTUAL_HOSTS
-        Supports name-based virtual hosts.  If your system has multiple
-        host names, you can have each host name return unique content
-        depending on which hostname is used.  ie: if
-        freebsd.synchro.net and nix.synchro.net both resolved to your
-        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 RootDirectory with the desired hostname
-        ie: web/root/freebsd.synchro.net/ if the browser doesn't send
-        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 index.html page in RootDirectory something
-        like this:
-            <html>
-              <head>
-                <title>Old Browser</title>
-              </head>
-              <body>
-                Your browser is either too old to support
-                name-based virtual hosts, or you have visited a
-                virtual hosts that is not yet configured.  The
-                following are hosted here:<br>
-                <a href="freebsd.synchro.net">freebsd.synchro.net
-                </a><br>
-                <a href="nix.synchro.net">nix.synchro.net</a><br>
-              </body>
-            </html>
-    NO_CGI
-        Disable CGI script execution.
-    HTTP_LOGGING
-        Enable logging to a Common Logfile Format log as described in
-        the HttpLogFile section.  Usefull for running log analysis
-        programs (like Webalizer: http://www.mrunix.net/webalizer/)
-    NO_JAVASCRIPT
-        Disable SSJS execution.
+=== FileIndexScript ===
+Default value: ""
-.2. Other web-related configuration files
+Suggested value: ''webfileindex.ssjs''
-------------------------------------------
-In addition to the [Web] keys in the initialization file, the web server
-also uses some other configuration files:
-    ctrl/mime_types.ini
+A Server-side JavaScript (SSJS) file to execute and provide HTML/CSS indexes to file libraries and directories accessed via virtual file paths.
-        Contains the file extension to mime-type mapping.  Each line
-        is in the format "extension = mime-type" ie: "html = text/html"
-        The extensions are case-insensitive and do not include the '.'.
-    ctrl/webicons.ini
-        Contains the URLs to the icons used by the default 404.ssjs
-        script for each file type/extension.  Format is "extension = URL".
-        Example: "html=/icons/layout.gif".  Two "magical" extensions exist:
-        DIRECTORY which is used for directories and DefaultIcon which
-        is used for extensions which don't exist in the list.
-    ctrl/web_handler.ini
-        Contains 2 sections, [CGI] and [JavaScript], where a list of file
-        extensions and their associated content-creation handlers are
-        specified. The [CGI] section is for natively-executed CGI handlers
-        (e.g. "pl = perl" indicates "perl" will be used to handle ".pl"
-        files). The [JavaScript] section is used for JS-executed content
-        handlers (e.g. "xjs = xjs_handler.js").
-    ctrl/cgi_env.ini
-        Contains a list of system environment variables to pass to CGI
-        processes.  Each variable can have an optionally specified default
-        value, over-ridden value, and prepended or appended text.
+==== Other configuration files ====
-.3. webctrl.ini per-directory configuration file
+In addition to the ''[Web]'' keys in the [[config:sbbs.ini]] file, the web server
-------------------------------------------------
+also uses some other configuration files:
-Each directory may have a webctrl.ini file which overrides certain settings for
-the directory it's in and all child directorys.  Configuration keys may be set
-either globally, or in a per-filename group.  Using the * and ? wildcards as
-the group name such as [*.html].  The following keys may be used in these files:
-AccessRequirements:
+=== ctrl/mime_types.ini ===
-	Specifices an ARS string which all users must match to be able to access
+Contains the file extension to mime-type mapping.  Each line
-	files in this directory.  Will force an HTTP login.
+is in the format "extension = mime-type" ie: "html = text/html"
-Realm:
+The extensions are case-insensitive and do not include the '.'.
-	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.  The standards say that Basic must come first, but no
-	browser currently appears to use Digest if Basic is listed first.
-	Supported values are Basic and Digest.  Digest is more secure as the
-	users password is never sent over the wire.
-ErrorDirectory:
-	Specifies a different directory to check for error pages.  If the error
-	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.  This effecively works like a custom 404 page.
-For example, to require a login, but allow *any* user to access files in a
+=== ctrl/webicons.ini ===
-directory, but only a sysop to access *.log files, the following could be used:
+Contains the URLs to the icons used by the default 404.ssjs
-AccessRequirements=level 0
+script for each file type/extension.  Format is "extension = URL".
-[*.log]
+Example: "html=/icons/layout.gif".  Two "magical" extensions exist:
-AccessRequirements=level90
+DIRECTORY which is used for directories and DefaultIcon which
+is used for extensions which don't exist in the list.
+=== ctrl/web_handler.ini ===
-.0 JavaScript Web Server Objects
+This file contains 2 sections where a list of file
----------------------------------
+extensions and their associated content-creation handlers are
-In addition to the standard JavaScript objects, the web server provides the
+specified:
-following:
+== [CGI] ==
-.1 http_request object
+The [CGI] section is for natively-executed CGI handlers
------------------------
+(e.g. "pl = perl" indicates "perl" will be used to handle ".pl" files).
-The http_request object contains information from the client that was included
-during this request.  This objects properties are as follows:
-path_info    - Contains extra path information that was included with the
+== [JavaScript] ==
-               request AFTER the URI which identified this script.  For
-               example, if the request was for
-               http://www.synchro.net/script.ssjs/test/this then path_info
-               would contain the string "/test/this"
-method       - Contains the HTTP method used to run the script.  As of this
-               writing, the available methods are "HEAD", "GET", "POST", and
-               "OPTIONS".
-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.  This is an associative "array" of
-               name/value pairs.  THE VALUES ARE ARRAYS OF STRINGS.  The reason
-               for this is that it is legal and often usefull 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.  Once again, this is an array of strings since
-               multiple values for the same key can be set for cookies.
-real_path    - The real OSs 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.
+The [JavaScript] section is used for JS-executed content
+handlers (e.g. "xjs = xjs_handler.js").
-.2 http_reply object
+=== ctrl/cgi_env.ini ===
----------------------
+Contains a list of system environment variables to pass to CGI
-The http_reply object is used to pass information about the reply back to the
+processes.  Each variable can have an optionally specified default
-Synchronet web server.  The properties are as follows:
+value, over-ridden value, and prepended or appended text.
-status       - HTTP status string.  The default is generally "200 Ok"
-header       - An associative array of headers to include with the reply.  The
-               only pre-defined one is "Content-Type" which defaults to
-               "text/html".
-fast         - This optional property can be set to "true" to make write()s go
-               directly to the client for HTTP/1.0 connections.  This prevents
-               keep-alives from working but generally appears faster to the
-               client.  Since HTTP/1.1 requests use chunked mode, this isn't
-               required for HTTP/1.1.
+==== webctrl.ini ====
-.3 Extra global methods
+Each directory under the [[#RootDirectory]] may have a ''webctrl.ini'' file which overrides certain settings for
-------------------------
+the directory it's in and all child directories.  Configuration keys may be set
-The web server also adds new global methods.  These are:
+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 ''[*.html]'' or ''[dirname/]''.  The following keys may be used in these files:
-set_cookie(string key,
+=== AccessRequirements ===
-           string value
+Specifies an ARS string which all users must match to be able to access
-		   [, time_t expires
+files in this directory.  Will force an HTTP login.
-		   [, string domain
-		   [, string path
-		   [, bool secure ]]]])
-               Requests that the specified cookie be set.
+For example, to require a login, but allow **any** user to access files in a
+directory, but only a sysop to access ''*.log'' files and .git directories, the following could be used:
+<file webctrl.ini>
+AccessRequirements=level 0
+[*.log]
+AccessRequirements=level 90
+[*.git]
+AccessRequirements=level 90
+</file>
-.0 The SSJS Template System
+=== Realm ===
-----------------------------
+Sets the realm that is displayed to the user for the HTTP login.
-The default web pages use a SSJS Template engine which also allows for Theme
+Default is the BBS name.
-support.
-[Note:  With this latest implementation of SSJS, @@ codes no longer can be
+=== DigestRealm ===
-nested.]
+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.  The standards say that Basic must come first, but no
+browser currently appears to use Digest if Basic is listed first.
+Supported values are ''Basic'' and ''Digest''.  Digest is more secure as the
+users password is never sent over the wire.
-.1 The SSJS Template Scheme
+=== ErrorDirectory ===
-----------------------------
+Specifies a different directory to check for error pages.  If the error
-Each page consists of four parts:
+page is not found, will still check the global error directory.
-    The Header (../web/templates/default/header.inc)
+=== CGIDirectory ===
-        This file contains the basic requirements for the HTML page.
+Specify an alternate CGI directory to check for CGI files.
-        The opening HTML, doctype, title, CSS file link, etc.  The
-        header file includes the open body, System Name, and User
-        greeting plus the initial page layout table start.  The rest
-        of the layout is continued in the next files.
-    Top Navigation (../web/templates/default/topnav.inc &
+=== PathInfoIndex ===
-        ../web/lib/topnav_html.ssjs)
+Specifies that the index files can be ran for unlocated pages in the
-        The topnav.inc file contains the basic design of the "breadcrumbs"
+current directory.  This effecively works like a custom 404 page.
-        The links are dynamically generated by topnav_html.ssjs so both
-        files need to be addressed when modifying or creating themes.
-        In the case of the default layout, topnav.inc has a left and right
-        graphic and a middle section that the dynamic content goes.  The
-        background image is handled by CSS.  You can change this to anything
-        you like.
-        The topnav_html.ssjs file may seem daunting at first, but it is
-        pretty straight forward.  It has a series of if statements that
-        check the current page location and sets up the breadcrumbs based
-        on what you want it to say.
-        For example:
-            You want to add a Links page called links.html in the main
-            directory.  You would add a check for the path to links.html
-            as:
-                if(http_request.virtual_path=="/links.html")
-                    template.topnav.push({html: '<span class="tlink">
-                        Some Links</span>'});
-    Left Side Navigation (../web/templates/default/leftnav.inc &
+=== FastCGISocket ===
-        ../web/lib/leftnav_nodelist.ssjs & ../web/lib/leftnav_html.ssjs)
+Specifies the socket address of a FastCGI listener in either <Address>:<Port> format (e.g. ''127.0.0.1:9000'') or ''unix:/path/to/unix/socket'' format.  Should be used with wildcard sections like this:
-        This starts the main table layout in the default layout and also
+<file webctrl.ini>
-        provides two other things -- the main navigation links and a brief
+[*.php]
-        nodelisting that displays when users are online via telnet.
+FastCGISocket=127.0.0.1:9000
-        The links are dynamically created as in the Top Navigation example
+</file>
-        above with the exception of the two static links.
-    Main Content (various files)
+See [[howto:php]] for details on using with PHP.
-        This is where the layout of the main content is created.  It is best
-        to look at the various files in ../web/templates/default &
-        ../web/templates/default/msgs to see how the code is dispayed for the
-        various functions of the Web side of Synchronet.  Some details on what
-        each of the special codes contained in those files do will follow.
-    Footer (../web/templates/default/footer.inc)
+=== Rewrite* ===
-        This file contains the closing HTML and whatever bottom information
+Specifies a Javascript snippet which can modify the http_request.request_string.  This allows internal redirects like the RewriteRule feature in Apache .htaccess files.  The key must *begin* with the string "Rewrite" which may be followed by any legal INI key characters.  The order of execution is not guaranteed.
-        you would like. In the case of the default layout, the
-        Web Server/Synchronet versions and the XHTML 1.0 logo.  Links to
-        privacy statements or anything else can be placed here and they will
-        be displayed at the bottom of each page.
+<file webctrl.ini>
+RewriteDetail=var n=http_request.request_string.replace(/_detail\/(.*)/,"lib/exe/detail.php?media=$1"); if(n != http_request.request_string) { http_request.request_string=n; true }
+</file>
-.2 SSJS Theme Support
+If the expression returns "true", reparses http_request.request_string as
-----------------------
+an internal redirect.
-Theme Layouts can be added to Synchronet by creating them and placing the
-*.inc files in their own directory under ../web/templates/
-Themes are activated by editing the ../web/templates/html_themes.ssjs file.
+Added on November 3rd, 2015 to CVS (in 3.17a). ([[https://gitlab.synchro.net/main/sbbs/-/commit/370cb673ce644a77bb94f9375cbe3463390e485a|Commit]])
-This file contains:
-    /* Set default theme name */
+=== JSPreExec ===
-    var DefaultTheme="Default";
+A JavaScript snippet which is executed in the same context as Rewrite* lines, but before any Rewrites are executed.  This allows load()ing some common code before execution... ie: ''JSPreExec=load(js.startup_dir+'/rewrite_lib.js');''.
-    /* Edit this bit to add/remove/modify theme descriptions and dirs */
+Added on November 3rd, 2015 to CVS (in 3.17a).
-    Themes["Default"]=new Object;
-    Themes["Default"].desc="Default Synchronet Theme";
-    Themes["Default"].dir="default";
-    Themes["Default"].css="/synchronet.css";
-Themes are added by editing below the Default Theme such as:
+===== JavaScript Objects =====
+In addition to the standard JavaScript objects, the web server provides the
+following:
-    Themes["CoolTheme"]=new Object;
+==== http_request object ====
-    Themes["CoolTheme"].desc="My Cool Theme";
-    Themes["CoolTheme"].dir="cooltheme";
-    Themes["CoolTheme"].css="/cooltheme.css";
-To change the Default Theme, change:
+The http_request object contains information from the client that was included
+during this request.  This objects properties are as follows:
-    var DefaultTheme="Default";
+=== path_info ===
+Contains extra path information that was included with the
+request AFTER the URI which identified this script.  For
+example, if the request was for
+''http://www.synchro.net/script.ssjs/test/this'' then path_info
+would contain the string "/test/this"
-to:
+=== method ===
+Contains the HTTP method used to run the script.  As of this
+writing, the available methods are "HEAD", "GET", "POST", and
+"OPTIONS"
-    var DefaultTheme="CoolTheme";
+=== 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.  This is an associative "array" of
+name/value pairs.  THE VALUES ARE ARRAYS OF STRINGS.  The reason
+for this is that it is legal and often useful to have multiple
+form fields with the same name.
-.3 Special Codes Used in the SSJS Template System
+=== query_string ===
---------------------------------------------------
+If a query string was included, this is the raw, unparsed query
-By looking at at the message related files located in templates/default/msgs,
+string.
-it can be seen that some special codes are used to display dynamically created
-content. It is very important to maintain the information EXACTLY as seen in
-each file or else the messaging system will fail.  While how it is displayed
-can be changed, the correct information will only be dispayed by following the
-format in the *.inc files.
-For example the groups.inc:
+=== post_data ===
+As with query_string but for data which was POSTed.
-<!-- Main Content -->
+=== header ===
+An associative array of header name/value pairs.
-    <td class="main" valign="top"><br />
-<table class="grouplist" border="0" cellpadding="2" cellspacing="2">
+=== cookie ===
-<tr>
+Much like the query object, this object contains key/value pairs
-<th class="grouplist">Message Group</th><th class="grouplist">Subs</th>
+of set cookies.  Once again, this is an array of strings since
-</tr>
+multiple values for the same key can be set for cookies.
-<<REPEAT groups>>
-<tr>
-    <td class="grouplist">
-        <a class="grouplist" href="subs.ssjs?msg_grp=^^groups:name^^">
-            %%groups:description%%</a></td>
-    <td class="grouplist" align="right">
-        @@JS:msg_area.grp_list[RepeatObj.index].sub_list.length@@</td>
-</tr>
-<<END REPEAT groups>>
-</table>
-<br />
-<!-- end Main Content -->
+=== real_path ===
+The real OS's complete path to this script.
-While the table layout can be changed or even eliminated, the information
+=== ars ===
-within the <<REPEAT groups>> and <<END REPEAT groups>> must remain intact.
+The ARS string which applies to this request.
-To remove the table yet keep the correct infomation, the resulting groups.inc
-would be changed to (while maintaining the main table layout in this case) to:
-<!-- Main Content -->
+=== request_string ===
-    <td class="main" valign="top"><br />
-<<REPEAT groups>>
+The raw request string sent by the client.
-    <a class="grouplist" href="subs.ssjs?msg_grp=^^groups:name^^">
-        %%groups:description%%</a>
-    @@JS:msg_area.grp_list[RepeatObj.index].sub_list.length@@<br />
-<<END REPEAT groups>>
-<br />
+=== 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.
-<!-- end Main Content -->
+=== remote_ip ===
+The IP address of the client.
-This principle applies to all the .inc files in msgs respectively.
+=== remote_host ===
+If the web server does host lookups (disabled by default), this
+is the remote hostname.
-.4 The SSJS Template Library
+=== scheme ===
--------------------------------
-%%name%% is replaced with the HTML encoded value of template.name
+"https" if TLS is in use, "http" otherwise.
+==== http_reply object ====
-i.e.; Spaces are replaced with: this&nbsp;is&nbsp;html
-^^name^^ is replaced with the URI encoded value of template.name
+The http_reply object is used to pass information about the reply back to the
+Synchronet web server.  The properties are as follows:
-i.e.; Spaces are replaced with:  this%20is%20URI
+=== status ===
-@@name@@ is replaced with the value if template.name
-No changes or encoding is performed.
+HTTP status string.  The default is generally "200 Ok"
-@@name:sname@@ is replaced with the value of template.name.sname
+=== header ===
-(^^ and %% are also supported)
+An associative array of headers to include with the reply.  The
+only pre-defined one is "Content-Type" which defaults to "text/html".
-@@JS:js_expression@@ is replaced with the return value of js_expression
+=== fast ===
-(^^ and %% are also supported)
+This optional property can be set to "true" to make write()s go
+directly to the client for HTTP/1.0 connections.  This prevents
+keep-alives from working but generally appears faster to the
+client.  Since HTTP/1.1 requests use chunked mode, this isn't
+required for HTTP/1.1.
-<<REPEAT name>>
-    @@name:sname@@
-<<END REPEAT name>>
-Iterates over the array/object template.name and replaces name:sname with
+==== Extra global methods ====
-the value of template.name.sname.
-(^^ and %% are also supported)
+The web server also adds a new global JavaScript method that requests that the specified cookie be set:
-.5 SSJS Message Configuration
+  set_cookie(string key,
-------------------------------
+           string value
-Configuration settings for the SSJS Messaging system is located in the
+		   [, time_t expires
-../web/lib/msgsconfig.ssjs file:
+		   [, string domain
+		   [, string path
+		   [, bool secure ]]]])
-max_messages=20;
-max_pages=30;
-next_msg_html="Next Message";
-prev_msg_html="Previous Message";
-next_page_html="NEXT";
-prev_page_html="PREV";
-showall_subs_enable_html="Show all subs";
-showall_subs_disable_html="Show subs in new scan only";
-show_messages_all_html="Show all messages";
-show_messages_yours_html="Show messages to you only";
-show_messages_your_unread_html="Show unread messages to you only";
-show_messages_spacer_html="&nbsp;<b>|</b>&nbsp;";
-anon_only_message="Message will be posted anonymously";
-anon_allowed_message='<input type="checkbox" name="anonymous" value="Yes" /> \
-Post message anonymously';
-anon_reply_message='<input type="checkbox" name="anonymous" value="Yes" checked /> \
-Post message anonymously';
-private_only_message="Message will be marked private";
-private_allowed_message='<input type="checkbox" name="private" value="Yes" /> \
-Mark message as private';
-private_reply_message='<input type="checkbox" name="private" value="Yes" checked /> \
-Mark message as private';
-Each of these are configurable.  NOTE:  Lines ending in "\" indicate the line
+==== Extra global variables ====
-below is part of the line above.  The "\" is not part of the configuration as
-it too be removed.
-See the actual file for the defaults currently in use.
+=== web_root_dir ===
+The path to the web server's document root directory.
-.6 Embedded Javascript
+See also: the RootDirectory key under [Web] in [[config:sbbs.ini]].
------------------------
-The *.inc files can (and do in the default layout) have embedded JavaScript
+===== XJS files =====
-which is parsed by the JavaScript engine.  Care should be taken as a large
-number of embedded JavaScript in the *.inc files slow down overall processing
-of pages.
-Anything contained within @@JS: @@ is processed by the Server-side JavaScript
+XJS files, handled by ''exec/xjs_handler.js'' are what many people consider to be
-engine.
-For example, it can check if the user is Guest or an actual user with this line:
-@@JS:if(user.number==0 || user.security.restrictions&UFLAG_G) \
-'<html code for Guest>'; else '<html code for registered user>';@@
-What this does is display links specific for Registered Users only to them
-and not Guest.  There are many things that can be done with @@JS: @@ code.
-Note, it also can be used to display HTML based on location as in the
-node listing stuff. In this case, it checks for whether or not a user is
-online, or if the user is anywhere but the Who's Online page before displaying
-the Left side node listing.
-IMPORTANT!  Anything contained within @@JS: @@ MUST be on one line or there
-will be errors in parsing.
-.7 global_defs.ssjs
---------------------
-This version of the Web Layout now includes a new file called
-global_defs.ssjs.  It is located in the ../web/lib directory.  This file can
-be used for creating global definitions that span all pages of a site.
-For example:
-template.user_alias=user.alias;
-Now @@user_alias@@ can be in any *.inc template files and it will display the
-user's alias.
-Care should be excersied when using this file as loading it up with hundreds
-of predefined definitions may slow down overall page rendering as the file is
-loaded on every page.  It would be better to just put a few popular
-definitions that are truly global rather many definitions.  It would be
-inefficient to have thirty of forty message definitions being loaded when a
-user is looking at the statistics page.
-.0 XJS files
--------------
-XJS files, handled by exec/xjs_handler.js are what many people consider to be
 an easier method of generating SSJS files.  XJS files are HTML files with JS
 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 .ssjs appended.
+translated on-the-fly to .ssjs files using the same name with ''.ssjs'' appended.
-For example, a file named test.xjs will, when ran, generate a test.xjs.ssjs
+For example, a file named test.xjs will, when ran, generate a ''test.xjs.ssjs''
 file.
-.1 XJS syntax
+==== 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
@@ Line 583: / Line 532: @@
 either "<?xjs" or "<?" and ends with "?>".  A simple example would be:
+<code html>
 <html><head><title><?xjs write(system.name) ?></title></head>
 <body>
@@ Line 589: / Line 539: @@
 </body>
 </html>
+</code>
 This would send the following web page to the remote system:
+<code html>
 <html><head><title>My Brand New BBS</title></head>
 <body>
@@ Line 597: / Line 549: @@
 </body>
 </html>
+</code>
 Looping constructs are permitted, however, not using brackets can result in
@@ Line 603: / Line 556: @@
 The following example displays the numbers from one to 10.
+<code html>
 <html><head><title>Counter</title></head>
 <body>
@@ Line 613: / Line 567: @@
 </body>
 </html>
+</code>
+==== 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.  Local variables
+are NOT visible to ''xjs_load()''ed pages.  The filename is assumed to be
+relative to the including file (or absolute.)
-.2 XJS-specific global methods and properties
+=== cwd ===
-----------------------------------------------
+Contains the path that the current xjs script was loaded from and which
-The following JS commands are available to XJS files only.
+parameters to ''xjs_load()'' are assumed to be relative to.  If you change
-xjs_load(filename)
+the value of ''cwd'', it will change the location where ''xjs_load()'' will
-	Runs the specified xjs file at the current position.  Local variables
+check for files.
-	are NOT visible to xjs_load()ed pages.  The filename is assumed to be
-	relative to the including file (or absolute.)
-cwd
-	Contains the path that the current xjs script was loaded from and which
-	parameters to xjs_load() are assumed to be relative to.  If you change
-	the value of cwd, it will change the location where xjs_load() will
-	check for files.
+{{indexmenu_n>4}}

Trace:

Differences

Navigation

Search

Toolbox