Jexus Web Server Documentation¶
Topics¶
Getting Started¶
Install Jexus Web Server¶
By Lex Li
This page shows you how to install Jexus web server on a clean Linux machine.
In this article:
Jexus installers can be found at Jexus.org, which is usually in the following URL patterns,
For example, a stable release, such as 5.5.2, can be downloaded from http://www.linuxdot.net/down/jexus-5.5.2.tar.gz.
Install Mono Runtime¶
Xamarin maintains the installation packages. Please follow the guide to install it and then execute
mono --version
at terminal to verify that Mono has been installed properly. mono-complete
is recommended.
Mono 4.2.2 and above is recommended version for all Linux/OS X if you know how to get it installed.
Download and Unpack Jexus Files¶
wget http://www.linuxdot.net/down/jexus-x.y.z.tar.gz
tar -zxvf jexus-x.y.z.tar.gz
Jexus binary package is downloaded from its official site, and extracted to a folder named “jexus-x.y.z” after this step.
Create Default Web Site¶
sudo mkdir /var/www
sudo mkdir /var/www/default
sudo vi /var/www/default/index.html
Press i
on keyboard to enter edit mode.
Type “Hello World from Jexus” and press Esc on keyboard to exit edit mode.
Type :wq
and press Enter on keyboard to exit vi.
/var/www/default
is the default web site path for Jexus. In this step we create a test page using vi. You might use any other Linux text editor to create this test page.
Install and Start Jexus¶
cd jexus-x.y.z
sudo ./install
cd /usr/jexus
sudo ./jws start
Here we put Jexus binary to /usr/jexus
folder, grant the jws shell script file execution permission, and then use it to register Jexus modules in Mono GAC and launch
the HTTP service.
If you want to install Jexus to another location, please change the commands accordingly.
- (Optional) Add Jexus to startup commands
sudo vi /etc/rc.local
Press i
on keyboard to enter edit mode.
Add start command /usr/jexus/jws start
.
Press Esc on keyboard to exit edit mode.
Type :wq
and press Enter on keyboard to exit vi.
Now if we open Firefox and navigate to http://localhost, the test page we created is displayed correctly,
Notes¶
Jexus author has recently found a new way to distribute Jexus web server. It is called Jws.mono at this moment, which means “Jexus bundled with Mono”. By using this approach, you can install Jexus and Mono easily from a binary package, instead of installing Mono runtime via Linux distro or building from source code.
However, Jexus Manager does not yet support Jws.mono. You have to install Mono via Linux distro or build from source code still if you want to use Jexus Manager.
Upgrade Jexus Web Server¶
By Lex Li
This page shows you how to upgrade Jexus web server on a Linux machine.
In this article:
Download and Unpack Jexus Files¶
wget http://www.linuxdot.net/down/jexus-x.y.z.tar.gz
tar -zxvf jexus-x.y.z.tar.gz
Jexus binary package is downloaded from its official site, and extracted to a folder named “jexus-x.y.z” after this step.
Stop Current Jexus Server¶
cd /usr/jexus
sudo ./jws stop
Assume the previous release was installed at /usr/jexus, we stop the service. If Jexus 5.3 was there, use “sudo ./jws.stop” instead of “sudo ./jws stop”.
Copy New Files¶
cd ~/jexus-x.y.z
sudo ./upgrade
Now let’s go back to the extracted folder and upgrade necessary files to /usr/jexus.
Fix Startup Commands¶
sudo vi /etc/rc.local
Press i on keyboard to enter edit mode.
If previous start command “/usr/jexus/jws.start” exists, replace it with “/usr/jexus/jws start”.
Remove “/usr/jexus/state.start” if it presents.
Press Esc on keyboard to exit edit mode.
Type :wq and press Enter on keyboard to exit vi.
Here we remove the old entries, and use a new entry to start Jexus at startup.
Start Jexus HTTP Service¶
cd /usr/jexus
sudo ./jws start
Tutorials¶
Configuration System¶
By Lex Li
This page shows you what is the configuration system for Jexus web server.
In this article:
Server Configuration File¶
The configuration file, which contains most of Jexus settings, is located in Jexus installation folder (usually /usr/jexus) and named jws.conf.
Unlike IIS which uses XML to store settings, the Jexus settings are stored in key-value pair, for example
SiteLogDir=log
SiteConfigDir=siteconf
Note
Any change to server configuration only takes effect when Jexus is restarted.
The description of each settings is listed as below,
SiteConfigDir¶
- Mandatory
- The directory that holds web site configuration files. Relative paths to jws.exe can be used.
- No IIS equivalent
SiteLogDir¶
- Mandatory
- The directory that holds the log files. Relative paths to jws.exe can be used.
- Equal to “system.applicationHost/log” section and “system.applicationHost/sites/site/logFile”
Runtime¶
- Optional
- Application pool ASP.NET runtime version. For example,
Runtime=v4.0.30319
orRuntime=v4.0
. - Equal to “system.applicationHost/applicationPools/add/managedRuntimeVersion”
httpd.processes¶
- Optional
- Specifies the number of worker processes associated with the application pool. A value other than 1 indicates a Web garden. The default value is 1.
- Equal to “system.applicationHost/applicationPools/add/processModel/maxProcesses”
httpd.user¶
- Optional
- Application pool identity. For example,
httpd.user=www-data
. The default value is root. - Equal to “system.applicationHost/applicationPools/add/processModel/identityType” and “system.applicationHost/applicationPools/add/processModel/userName”
httpd.MaxTotalMemory¶
- Optional
- (5.5+) Specifies the maximum total physical memory (of MBytes) that all worker processes can consume before the pool starts to recycle worker processes. It ranges from 256 to 80% of maximum physical memory installed on the machine. The default is 0, where Jexus automatically adjusts the usage.
- No IIS equivalent
Note
Each worker process the minimum physical memory usage is 128-MBytes.
httpd.MaxCpuTime¶
- Optional
- (5.5+) Specifies how much CPU resources (of seconds) can be consumed by a single worker process before being recycled by the pool. It ranges from 600 to 14400. The default value is 3600.
- No IIS equivalent
LLVM¶
- Optional
- When a worker process is created, Jexus passes this flag to Mono. The default value is false.
- No IIS equivalent
certificatefile¶
- Optional
- File name of the server certificate file (in X.509 format). The default value is empty.
- No IIS equivalent
certificatekeyfile¶
- Optional
- File name of the server certificate file private key (in PEM format). The default value is empty.
- No IIS equivalent
Website Configuration File¶
Jexus supports multiple web sites running on the same server. The web sites use individual bindings to distinguish from each other.
The web site configuration files must be saved in the configuration directory set in jws.conf (aka SiteConfigDir). The configuration file name is used as site name (site name is only used in Jexus commands), which should not contain spaces. Note that all files in configuration directory are treated as web site configuration files. Thus, don’t leave anything else there.
Note that any change to web site configuration only takes effect when the web site is restarted.
In default installation, a default web site is created. Its configuration file is /usr/jexus/siteconf/default
. Just like jws.conf, the web site configuration is also
stored in key value pair, and the description of each settings is as below,
addr¶
- Optional
- The web site IP address. Default is
addr=0.0.0.0
. (no IP v6 support yet) - Equal to “system.applicationHost/sites/site/binding”
port¶
- Optional
- The port number used for this web site. Default is
port=80
. - Equal to “system.applicationHost/sites/site/binding”
hosts¶
- Optional
- The host header accepted by this web site. Default is
hosts=*
, which means any host header is accepted. Wildcard is also supported, such as*.mysite.com
. - Equal to “system.applicationHost/sites/site/binding”
root¶
- Mandatory
- The directory mapping. The default is
root=/ /var/www/default
, which maps physical directory/var/www/default
that contains the web site contents to web site root. - Equal to “system.applicationHost/sites/site/application/virtualDirectory”
indexes¶
- Optional
- Default document name list. For example, when
indexes=index.aspx,index.htm
is used, access to / will be resolved to index.aspx if it exists, and then index.htm if exists, and 404 if none of them exists. When this setting is not set, Jexus uses its built-in name list. - Equal to “system.webServer/defaultDocument”
rewrite¶
- Optional
- URL rewrite rule. For example,
rewrite=^/.+?.(asp|php|cgi)$ /404.html
means any access to classic ASP/PHP/CGI pages is rewritten to/404.html
. To use multiple rules, use multiple lines ofrewrite=
. - Equal to “system.webServer/rewrite/rules”
denyfrom¶
- Optional
- IP address restriction. For example, when
denyfrom=111.222.111.*,1.1.1.1
is used, access from the IP addreses are denied. Mask is also supported, such asdenyfrom=192.168.1.0/255.255.255.0
. - Equal to “system.webServer/security/ipSecurity”
allowfrom¶
- Optional
- IP address restriction. For example, when
allowfrom=111.222.111.*,1.1.1.1
is used, only access from the IP addresses are allowed. All other access is denied. - Equal to “system.webServer/security/ipSecurity”
DenyDirs¶
- Optional
- Hidden segments. When
DenyDirs=bin,App_code
is used, access to such URL paths is denied. - Equal to “system.webServer/security/requestFiltering/hiddenSegments”
checkquery¶
- Optional
- Query strings restriction. Jexus uses built-in logic to perform query safety check. The default is
checkquery=true
. Note that by setting this to true, there is some impact on Jexus performance. - No IIS equivalent
nofile¶
- Optional
- NOFILE is a Jexus specific feature. It is similar to IIS custom error pages for 404. When
nofile=/mvc/controller.aspx
is used, access to non-existent files is redirected to/mvc/controller.aspx
. - Equal to “system.webServer/httpErrors”
Note
The original URL is passed via X-Real-Uri server variable.
nolog¶
- Optional
- Logging flag. The default is
nolog=false
. When set to true, Jexus stops generating log files for this web site. - Equal to “system.applicationHost/sites/site/logFile”
keep_alive¶
- Optional
- HTTP keep-alive flag. The default is
keep_alive=true
. - Equal to “system.webServer/httpProtocol/allowKeepAlive”
reproxy¶
- Optional
- Reverse proxy rule. When
reproxy=/abc/ http://www.xxxx.com:890/abc/
is used, requests on/abc/
(source) will be redirected tohttp://www.xxxx.com:890/abc/
(destination). The destination can be multiple, so that Jexus randomly picks one from them, which is similar to load balancing. For example,reproxy=/abc/ http://192.168.0.3/abc/,http://192.168.0.4/abc/
. - No IIS equivalent
fastcgi.add¶
- Optional
- FastCGI rule. For TCP connections, typical setting is
fastcgi.add=php,php3
- No IIS equivalent
usegzip¶
- Optional
- GZip compression flag. The default is
usegzip=true
. - Equal to “system.webServer/urlCompression/doStaticCompression”
usehttps¶
- Optional
- SSL flag. To enable HTTPS, this setting must be set to true, and port must be set to 443 at the same time. The default is
usehttps=false
. The certificate configured at server level will be used. - Equal to “system.applicationHost/sites/site/binding”
Application Configuration File¶
Applications under websites (IIS style applications) can be configured by creating websites, whose root points to the application path. Jexus Manager simplifies such application creation a lot, and also uses its own convention to set application configuration file names.
Virtual Directory Configuration File¶
Jexus does not support IIS style virtual directories.
Management Script¶
By Lex Li
This page shows you how to use the management script.
In this article:
Starting from Jexus 5.3 the commands are merged into one Shell script, /usr/jexus/jws
.
This script provides the following functionality,
Command | Description |
---|---|
jws start | Start Jexus server. |
jws start sitename | Start a single web site. Note that sitename must match one of the configuration files under configuration directory. |
jws restart | Restart Jexus server. |
jws restart site_name | Restart a single web site. |
jws stop | Stop Jexus server. |
jws stop site_name | Stop a single web site. |
jws regsvr | Register Jexus assembly in GAC. Note that this is only required to be executed once during installation. |
jws status | Report Jexus runtime status. |
jws -v | Display Jexus version number. |
The script should be set to executable during installation.
Note
The commands can only be executed by root.
Support¶
Release Notes¶
By Lex Li
This page shows you the release notes of Jexus web server.
In this article:
Version 5.6.5¶
Released on Oct 11, 2015
- Fixed a bug that in rare cases IndexOutOfRangeException is thrown under high load.
Version 5.6.4¶
Released on May 30, 2015
- Fixed the bug that for FastCGI module port number appears in SERVER_NAME variable.
- Added log entries for reverse proxy module.
- Enhanced security protection to prevent cross site scripting via some special URL patterns.
Version 5.6.3¶
Released on Jan 4, 2015
- “X-Real-Host” header is added by Jexus when reverse proxy is enabled. This header contains HTTP host header from original requests.
- Added a feature so that Jexus automatically kills the process who listens to the ports in need.
- Optimized the strategy of web application loading. Switched from MultiDomainHost to SingleDomain.
Version 5.6.2¶
Released on Oct 12, 2014
- Fixed the bug that data lost in reverse proxy and FastCGI modules when PUT requests are being processed.
- Optimized ASP.NET thread pooling algorithm to achieve better throughput.
Version 5.6.1¶
Released on September 28, 2014
- Added OWIN support, and OWIN compliant frameworks such as NancyFX/SignalR are supported.
- Added HTTP 100 support when client side sends “Expect: 100-continue”.
- Add chunked transfer encoding support to FastCGI module.
Version 5.5.3¶
Released on July 30, 2014
- Fixed the bug that leads to incomplete log files.
- Added a dedicated thread pool for FastCGI module to boost concurrency.
Version 5.5¶
Released on Jan 12, 2014
- Fixed “ASP.NET log entry might be incomplete” bug in logging.
- Added two settings in server configuration, httpd.MaxTotalMemory and httpd.MaxCpuTime.
- Added app_offline.htm support.
Version 5.4.4¶
Released on Oct 1, 2013
- Maximum number of worker processes is increased to [number of CPU cores] + 1 (still need to be <= 8).
- Maximum connections are now dynamically adjusted to avoid file descriptor exhaustion.
- Enabled TCPDEFERACCEPT option at TCP layer.
- Fixed “cannot find all hang worker processes” bug in application pool ping.
- Fixed “Range: byte=0-x is not properly processed” bug in Range header processing.
- Fixed “ASP.NET module cannot get external port number in NAT setup where external and internal port numbers differ” bug.
Version 5.4¶
Released on July 1, 2013
- Added application pool ping support.
- Added a new option to change socket listener binding from default to a certain IP address.
- Added a new option to control IP address whitelist.
Version 5.3¶
Released on May 11, 2013
- Fixed “Chinese characters in request path or query string can not be resolved correctly” bug in reverse proxy module.
- Fixed “pathinfo is lost” bug.
- Improved HTTPS support.
- (Breaking) ASP.NET State Service is now incorporated into Jexus master service process to simplify management;
- (Breaking) Added a single command “jws” to replace individual commands like “jws.start”, “jws.stop”.
- Core thread pool is optimized.
Version 5.2¶
Released on Jan 21, 2013
- FastCGI and reverse proxy modules now support multiple cookies.
- Added chunked transfer encoding support.
- Improved support for files with Chinese names mangled on Linux after copying from Windows.
- ASP.NET module now has OPTIONS/PUT/DELETE verbs enabled to support Web API projects.
- Improved data transmission method used in application pool control and cross app domain communication. Boosted static file performance by 5% and ASP.NET by 40%.
- Other bug fixes.
Supported Platforms¶
By Lex Li
This page shows you what are the supported platforms of Jexus web server.
In this article:
Jexus is highly flexible and supports a variety of platforms.
General Information¶
It has been tested by the author and users on the following platforms with success,
- CentOS with Mono 3.2.8+
- Ubuntu with Mono 3.2.8+
- FreeBSD with Mono 3.2.8+
Other Linux distributions or UNIX variants should also be supported out of the box or with minimal customization.
Reports show that Jexus can even run fine on resource limited hardware such as Raspberry Pi.
Supported/Recommended¶
LeXtudio recommends the following system setup,
- Ubuntu Server 14.04 with Mono 4.2.2
Above is also the supported platform by LeXtudio where technical support is provided. More supported platforms will be added in the future.
Troubleshooting¶
By Lex Li
This page shows you how to troubleshoot common issues.
In this article:
What is the cause of “System.Exception: Create work process error” when starting Jexus?¶
Answer: The detailed exception message is as below,
System.Exception: Create work process error.
at A.g.A (Int32 A, System.Collections.Generic.List`1 a, System.String B, Int32 b, Boolean C, Boolean c, Int32 D, Int32 d) [0x00000] in <filename unknown>:0
at A.G.A (System.String[] A) [0x00000] in <filename unknown>:0
05-02 16:22:51: Create httpd process failed:
Normally this is caused by corrupt Mono installation. Thus, you need to use official Mono packages from the distribution package repository, or build without any error from source code.
How to use ASP.NET session service?¶
Answer: Jexus already bundles an ASP.NET session service which monitors port 42424. So simply modify your web.config to point to this port and you can get it done.
How to reset Jexus?¶
Answer: The following commands reset Jexus worker processes and web server,
sudo killall -9 mono
sudo mono jws.exe
Unfortunately other Mono processes are also closed.
Licensing Terms¶
By Lex Li
This page shows you what are the licensing terms for Jexus web server.
In this article:
Jexus web server is free but not open source. Bing Liu can be contacted in you are interested in its source code.
Copyright (C) 2008-2015 Bing Liu All rights reserved.
The license term for the binaries is similar to CC by ND 4 .