Synchronet v3.21e-Win32 (install) has been released (Mar-2026).

You can donate to the Synchronet project using PayPal.

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
server:web [2023/11/14 19:04] – [webctrl.ini per-directory configuration file] Added snippet example and additional detail from original commit message re: Rewrite* ecbbsserver:web [2026/03/04 13:51] (current) – [Reference] mention letsyncrypt nelgin
Line 7: Line 7:
 The Synchronet Web Server is a mostly HTTP 1.1 compliant web server capable of 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 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 It also, through Server-Side JavaScript (SSJS), allows dynamic pages to be
Line 13: Line 13:
  
  
-===== Configuration =====+===== Configure =====
  
-==== Startup INI [Web] Section Keys ====+The Synchronet Web Server can be configured via [[util:SCFG]]:Servers->Web Server:
  
-The ''[Web]'' section of your [[config:sbbs.ini]] file contains the following settings (keys):+ 
 +  ╔══════════════════════════════════════════════════════════════════╗ 
 +  ║                        Web Server Settings                       ║ 
 +  ╠══════════════════════════════════════════════════════════════════╣ 
 +  ║ │Enabled                       Yes                               ║ 
 +  ║ │Log Level                     Info                              ║ 
 +  ║ │HTTP Support...               Port 80                           ║ 
 +  ║ │HTTPS Support...              Port 443                          ║ 
 +  ║ │SSJS File Extension           .ssjs                             ║ 
 +  ║ │Index Filenames               index.html, index.ssjs, index.xjs ║ 
 +  ║ │Content Root Directory        ../webv4/root                     ║ 
 +  ║ │Error Sub-directory           error                             ║ 
 +  ║ │Virtual Host Support          No                                ║ 
 +  ║ │Access Logging                <disabled>                        ║ 
 +  ║ │Access Log Format             N/A                               ║ 
 +  ║ │Max Clients                   100                               ║ 
 +  ║ │Max Inactivity                2 minutes                         ║ 
 +  ║ │Max Concurrent Connections    10                                ║ 
 +  ║ │Limit Rate of Requests        <disabled>                        ║ 
 +  ║ │Authentication Methods        Basic,Digest,TLS-PSK              ║ 
 +  ║ │Output Buffer Drain Timeout   10 ms                             ║ 
 +  ║ │Lookup Client Hostname        No                                ║ 
 +  ║ │CGI Support...                <disabled>                        ║ 
 +  ║ │Filebase Support...           /files/                           ║ 
 +  ║ │Login Requirements                                              ║ 
 +  ║ │JavaScript Settings...                                          ║ 
 +  ║ │Failed Login Attempts...                                        ║ 
 +  ╚══════════════════════════════════════════════════════════════════╝ 
 + 
 +... 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) | 
 +| MaxConcurrentConnections | 10               | Maximum number of simultaneous connections allowed from a single client IP address | 
 +| MaxInactivity            | ''2m''           | Maximum duration of client inactivity before disconnection | 
 +| MaxCgiInactivity         | ''2m''           | Maximum duration of CGI application inactivity | 
 +| MaxRequestsPerPeriod     | 0                | Maximum number of requests from a single IP address over the specified time period | 
 +| RequestRateLimitPeriod   | 0                | Time period (in seconds) over which client requests are to be rate calculated and limited | 
 +| 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 | 
 +| CustomLogFormat          | ""               | [[https://httpd.apache.org/docs/current/mod/mod_log_config.html|Apache-style]] custom HTTP access log line format | 
 +| FileIndexScript          | ""               | Server-side JavaScript to execute to provide HTML/CSS library and directory listings of virtual file paths (e.g. ''[[module:webfileindex|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 | 
 +| LoginRequirements        | [global]         | [[:Access:]] [[:access:requirements]] (in ARS format) for users to be allowed login | 
 +| LoginAttempt*            | [global]         | Failed login attempt throttling / filtering / banning | 
 +| LoginInfoSave            |                  | An optional [[access:requirements|ARS]] that can be used to limit which users will have their login details saved to the userbase | 
 +| RemoteIPHeader           | ""               | Name of an HTTP header that contains the real IP address of the proxied client | 
 +| 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: 
 + 
 +^ Option        ^ Description ^ 
 +| VIRTUAL_HOSTS | Supports name-based virtual hosts. | 
 +| NO_JAVASCRIPT | Disable SSJS execution. | 
 +| NO_CGI        | Disable CGI/FastCGI script execution. | 
 +| NO_HTTP       | Disable plain-text HTTP support | 
 +| NO_FILEBASE   | Disable FileBase support | 
 +| HTTP_LOGGING  | Enable logging to a Combined Log Format or Custom Log Format http access log.  Useful for running log analysis programs (like Webalizer: http://www.mrunix.net/webalizer/). | 
 +| ONE_HTTP_LOG  | When enabled along with VIRTUAL_HOSTS, client requests will be logged to a single file instead of a separate file per requested virtual host or IP address. | 
 +| ALLOW_TLS     | Enable TLS/SSL support (required for HTTPS) | 
 +| 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. | 
 +| HAPROXY_PROTO | Indicate that incoming requests are via HAproxy | 
 +| 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. | 
 + 
 +==== Reference ==== 
 + 
 +Web Server configuration settings reference: 
 +  
 +=== 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>
  
 === RootDirectory === === RootDirectory ===
Line 27: Line 154:
  
 **NOTE**: Older versions of Synchronet had this value default to ''../web/html'' **NOTE**: Older versions of Synchronet had this value default to ''../web/html''
 +
 +**NOTE**: If you change the root directory and use letsyncrypt for your certificate management, you will want to update the Domains section of letsyncrypt.ini in the ctrl directory. You will also need to do that if you have a virtual host so Let's Encrypt can find the correct document root.
 +
  
 === ErrorDirectory === === ErrorDirectory ===
Line 105: Line 235:
 Default value: ''../data/logs/http-'' Default value: ''../data/logs/http-''
  
-The prefix of log files if HTTP_LOGGING is enabled (See next item) to +The prefix of HTTP access log filenames, used when HTTP_LOGGING is enabled.  By default (when the ''ONE_HTTP_LOG'' option is **not** enabled), the current virtual host, date, and ''.log'' are appended to this string (e.g.''http-2005-03-12.log'').
-store Common Logfile Format logs in.  The current virtual host +
-(if enabled, see next item), date, and ''.log'' are appended to this (e.g.''http-2005-03-12.log'').+
  
-=== Options ===+=== CustomLogFormat ===
  
-Default value: ''NO_HOST_LOOKUP''+When the ''CustomLogFormat'' setting is not used, the default format is the Apache "Combined Log Format".
  
-The ''Options'' key is set to a ''|'' separated list of options to enable.  In addition to the [[config:sbbs.ini|standard options]], the web server also supports the following:+When the ''CustomLogFormat'' setting is used, the supported [[https://httpd.apache.org/docs/current/mod/mod_log_config.html|Apache Custom Log Format directives]] are:
  
-''DEBUG_RX''+| %% | The percent sign |  
 +| %a | Client IP address of the request |  
 +| %B | Size of response in bytes, excluding HTTP headers. |  
 +| %b | Size of response in bytes, excluding HTTP headers. In CLF format |   
 +| %h | Remote hostname or IP address |  
 +| %H | The request protocol |  
 +| %l | Remote logname (from identd, if supplied) |  
 +| %p | Server TCP port number | 
 +| %r | First line of request |  
 +| %s | Status |  
 +| %t | Time the request was received, in the format [18/Sep/2011:19:18:28 -0400] |  
 +| %u | Remote user if the request was authenticated |  
 +| %v | The canonical ServerName of the server serving the request. (the vhost) |  
 +| %{remote}p | the client's actual port |  
 +| %{Referer}i | the HTTP Referer [sic] header line |  
 +| %{User-agent}i | the HTTP User-agent header line |
  
-Log all received data to the console log, as well as various +Note: Double-quote characters used in the format string do **not** need to be escaped (i.e. with a backslash)
-extra bits related to receiving data.+
  
-''DEBUG_TX''+Example:
  
-Log all transmitted data except the reply body itself, as well +This is the equivalent of Apache's combined log format which is used by default.
-as various extra bits of information related to transmitted +
-data.+
  
-''VIRTUAL_HOSTS''+    CustomLogFormat = %h %l %u %t "%r" %s - "%{Referer}i" "%{User-agent}i"
  
-Supports name-based virtual hosts.  If your system has multiple +This is the equivalent of Apache's vhost_combined log format. 
-host names, you can have each host name return unique content +     
-depending on which hostname is used.  ie: if +    CustomLogFormat = %v:%p %h %l %u %t "%r" %s - "%{Referer}i" "%{User-agent}i"
-''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''+=== FileVPathPrefix === 
 +Default value: ""
  
-Disable CGI script execution.+Suggested value: ''/files/''
  
-''HTTP_LOGGING''+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.
  
-Enable logging to a Common Logfile Format log as described in +=== FileVPathForVHosts === 
-the HttpLogFile section.  Usefull for running log analysis +Default value: ''false''
-programs (like Webalizer: http://www.mrunix.net/webalizer/)+
  
-''NO_JAVASCRIPT''+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.
  
-Disable SSJS execution.+=== FileIndexScript === 
 +Default value: ""
  
-''ALLOW_TLS''+Suggested value: ''[[module:webfileindex|webfileindex.ssjs]]''
  
-Enable TLS support. +A Server-side JavaScript (SSJS) file to execute and provide HTML/CSS indexes to file libraries and directories accessed via virtual file paths.
- +
-''HSTS_SAFE'' +
- +
-Indicates that all URLs availabe via http are also available via https and redirects clients who want a TLS session to the https location.+
  
 ==== Other configuration files ==== ==== Other configuration files ====
Line 220: Line 331:
  
  
-==== webctrl.ini per-directory configuration file ====+==== webctrl.ini ==== 
 Each directory under the [[#RootDirectory]] may have a ''webctrl.ini'' file which overrides certain settings for 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 directory it's in and all child directories.  Configuration keys may be set
Line 227: Line 339:
  
 === AccessRequirements === === AccessRequirements ===
-Specifices an ARS string which all users must match to be able to access+Specifies an ARS string which all users must match to be able to access
 files in this directory.  Will force an HTTP login. files in this directory.  Will force an HTTP login.
  

Trace: