|Version 406 (modified by unbit, 2 years ago) (diff)|
uWSGI is a fast, self-healing and developer/sysadmin-friendly application container server coded in pure C.
It uses the uwsgi (all lowercase, already included by default in the Nginx and Cherokee releases) protocol for all the networking/interprocess communications, but it can speak other protocols as well (http, fastcgi, mongrel2...)
On top of all this, it is designed to be fully modular. This means that different plugins can be used in order to add compatibility with tons of different technology on top of the same core.
See the following table for a list of current language plugins:
|Technology||Available from version||Notes||Status|
|Python||0.9.1||The first available plugin, supports WSGI (PEP333, PEP3333), Web3 from version 0.9.7-dev, Pump (from 0.9.8.4), and FastFuncs. Works with VirtualEnv, Multiple Python interpreters, Python3k and has unique features like module aliasing, DynamicVirtualenv and uGreen. A module exporting handy Decorators for the uWSGI api is available in the source distribution.||Stable (100% uwsgi api support)|
|Lua||0.9.5||Support wsapi, coroutine and threads||Stable (60% uwsgi api support)|
|Perl||0.9.5||PSGI support. threading and async modes supported||Stable (60% uwsgi api support)|
|Ruby||0.9.7-dev||Rack and RubyOnRails support. A loop engine for Ruby 1.9 fibers is available||stable (20% uwsgi api support)|
|Erlang||0.9.5||allows message exchanging between uWSGI and Erlang nodes. ErlangIntegration||Stable (no uwsgi api support)|
|JVM||0.9.7-dev||allows integration between uWSGI and the JVM. An example WSGI-like (jwsgi) handler is available||Alpha|
|mono||0.9.7-dev||still at early stage of development allows integration between uWSGI and Mono||Unusable|
Current Core Features
- Written totally in C
- Very fast (and simple) communication protocol for webservers integration (apache2, nginx, cherokee and lighttpd modules available)
- Low memory footprint (thanks to the evil premature optimizations)
- Support for multiple application in the same process/domain
- A master process manager that will allows you to automatically respawn processes and monitor the stack status
- multiprotocol support (uwsgi, http, fastcgi and mongrel2 available out of the box)
- Preforking mode to improve concurrency
- Address space and rss usage reports
- Advanced logging (even networked, see UdpLogging, SocketLogging and ZeroMQLogging)
- Static file serving via sendfile() (where available)
- Portability (tested on Linux 2.6/3.0, Solaris/OpenSolaris/OpenIndiana, OpenBSD, NetBSD, DragonflyBSD, FreeBSD >= 8.0, MacOSX, Nexenta, and Haiku)
- Support for funny architectures like SPARC64 or ARM
- Support for threads (configurable, available from 0.9.7-dev)
- CGI mode for lazy users or ugly webservers (example CGI included here and here)
- 'Harakiri mode' for self-healing
- Vector based I/O to minimize syscall usage
- Hot-add of applications. See DynamicApps and uwsgi protocol variables
- On the-fly configuration parameters. See ManagementFlag
- Big (professional) user-base (hundreds of production ready wsgi/psgi/rack apps) thanks to its main development managed by the Italian ISP Unbit
- Commercial support available (contact Unbit for informations)
- All code is under GPL2 (but you can buy a commercial license if you want to modify it without releasing source code)
- Configurable buffer size for low-memory system or to manage big requests
- Customizable builds (you can remove unneeded functionality)
- Intelligent worker respawner with a no-fork-bombing policy
- Limit requests per worker
- Process reaper for external process managers (as daemontools). Avoids zombie workers.
- Per-request modifier for advanced users (See RunOnNginx for an example usage, and uwsgiProtocol for the modifiers list)
- UNIX and TCP socket support
- Graceful restart of worker processes and hot-plug substitution/upgrade of the uWSGI server using Signals. See uWSGIReload
- A shared memory area to share data between workers/processes. See SharedArea
- An integrated Spooler for managing long running task.
- Message exchanging (via uwsgi protocol) for easy-implementation of distributed applications (look at ClusteredExamples)
- Get statistics of all the workers using the EmbeddedModule
- Integrated Async/Evented proxy/load-balancer/router
- Address space usage limiting (from version 0.9.5)
- Automatically reload workers when a specific memory usage is reached
- integrated SNMP agent and nagios-friendly output (from version 0.9.5) See UseSnmp
- VirtualHosting mode (from version 0.9.6)
- Embedded async/evented HTTP server for easy development/testing and load balancing (from version 0.9.6)
- Emperor mode for massive hosting (from version 0.9.7)
- Linux Cgroups, POSIX Capabilities and Namespaces support (from version 0.9.7)
- A Signal Framework for managing external events (file system modifications, timers...) SignalFramework and CronInterface
- Shared Cache/Hashtable/Dictionary see CachingFramework
- Shared (circular) Queue (usable as a stack, fifo or simple array) see QueueFramework
- cheap and lazy modes, to automatically shutdown inactive instances
- ZergMode to automatically add workers to already running instances
- Snapshotting of running workers to allows emergency resume of apps
- Systemd support. See SystemdIntegration
Planned Features / TODO
|Planned Feature||Notes||Target Release Version|
|Integrated support for wsgi middleware||Is this really useful?||Unknown|
|SSL support w/ certificate client authentication||Allows remote management of the uWSGI stack.||Unknown|
|SCTP support||Experimental support is in 0.9.5, but needs performance improvements.||Unknown|
|AIX, Hurd and MorphOS support||N/A||0.9.9|
|Add a message queuing system on top of the Spooler||Message queuing system should support publish/subscribe. Should be able to export via the STOMP protocol||Unknown|
|Investigate support for Linux KSM to share code objects between processes||Unknown|
The current (stable) release can be downloaded from:
(Released on 20110911)
The old stable (long-term-support) release can be downloaded from:
(Released on 20110911)
Mercurial repository (trunk, unstable, may not be easily compiled)
hg clone http://projects.unbit.it/hg/uwsgi
To get started with uWSGI, take a look at the Install section of this wiki. When you are finished installing, have a look at the Doc page in order to learn about the options available. You can also view some example configurations at the Example page.
Developers/Users mailing list
Please note that with a large open source project such as uWSGI, the code and the documentation may not always be in sync. This mailing list is the best source for help regarding uWSGI.
Official IRC channel (freenode)
The owner of the channel is "unbit"
Frequently Asked Questions (FAQ)
Why ? Is this faster or simpler to configure ?
Because we can :) uWSGI wants to be a complete deploy solution with batteries (and steroids) included:
- Process management,
- Long running task handling,
- Cluster communication,
- Load balancing,
- Resource limiting
...and all of those other annoying tasks that you delegate to tons of ugly/inefficient external scripts and sysadmin tasks to.
If you are searching for a simple (wsgi/psgi/rack)-only server, uWSGI may not be for you. Though, if you are building a real (production-ready) app that needs to be rock-solid, fast and easy to distribute/optimize for various loads, you will find yourself pathetically and morbidly in love (we hope) with uWSGI.
What about the protocol?
The uwsgi (all lowercase) protocol is derived from scgi but with binary string length representation and a 4 byte header that includes the size of the var block (16 bit length) and a couple of general-purpose bytes. A typical WSGI request translate to:
header (4 bytes, size is in little endian) :
WSGI env vars follow (this is a block of the size specified in the header, string size is 16 bit little endian):
And no, we are not reinventing the wheel. Binary management is much easier and cheaper than string parsing, and we need every bit of power for our projects. If you need proof, look at the official protocol documentation and you will understand why a new protocol was needed. By the way, you can use others protocols too at the price of losing some kick-ass feature.
Can I use it in cluster environments?
Yes, this is one of the main features of the uWSGI stack. For example, using the uwsgi Cherokee handler you can specify different uWSGI servers running on different systems, or you can use the integrated upstream load balancer of Nginx.
On webserver handlers without load balancing (as Apache) you can use the integrated proxy.
Remember that the uWSGI server can pass string messages, dictionaries and even marshaled/serialized objects via its network protocol, so you can use it to build a complete clustered/distributed Python application. See Clustering and ClusteredExamples.
Why all those timeout configuration flags?
Good timeout choosing is the key for high-availability. Do not trust network applications that do not permit you to choose a timeout.
I need help !!! What i have to do ?
Post a message in the mailing-list including your operating system version, cpu architecture, webserver used (if any), uWSGI version and its command line (or config files). You should add the --show-config option and post the output in the message. It will be a lot useful. If you want, you can rebuild uWSGI with debug symbols and run it under a debugger (like gdb). Remember, uWSGI is an enormous project with hundreds of options, you cannot hope all of the things will go right at the first shot. Ask for help, ask for help and ask for help. If you are frustrated do not waste time blaming or ranting, simply join the list and ask for help. This is open source, if you only rant you are doing nothing useful.
I am not a sysadmin, nor a UNIX guru, can i use it ?
Good question :) But sadly, no answer. uWSGI is not developed with simplicity in mind, but with versatility. You can try it for sure (start with the Quickstart) and if you have problems, simply ask for help in the list or on the irc channel ;)
Why are most of the advanced features disabled on UNBIT systems?
Because most of the self-healing functions and resource management are integrated in the platform.
How can I buy commercial support for my company?
Write an email to info at unbit.it with the word 'uWSGI' in the subject. The email you send should include company information and your specific request. We will reply as soon as possible.
Will this allow me to run Python/Ruby apps on my ancient close-minded isp?
Probably not. The uWSGI server requires a serious platform/environment.
Where are the benchmarks?
Sorry, we only do "official" benchmarks for regression testing. If benchmarks are very important to you, you can search on the mailing list (for example on the cherokee list we posted a simple benchmark with flup), make your own benchmarks or search on Google.
uWSGI gives precedence to machine health, so do not expect that your ab test with huge/unreal number of concurrent connection will be managed flawlessly without tuning (under your responsibility). A bit of socket/networking knowledge is required if you want to make a valid benchmark (and avoid rage in your blog comments ;) Remember that uWSGI can be run in various modes, so avoid comparing it configured in preforking mode with another server in non-blocking/async mode if you do not want to look ridiculous :)
If you see your tests failing at higher concurrency rates you are probably hitting your OS socket backlog queue limit (maximum of 128 slot on Linux, tunable via /proc/sys/net/somaxconn and /proc/sys/net/ipv4/tcp_max_syn_backlog for TCP sockets).
You can set this value in uWSGI with the -l/--listen option (default 100)
Yeah, i have found server XXX being faster than uWSGI !!! You are no more the winner !!!
...and you have got nothing about uWSGI... Its advantage is in the huge amount of production-vital features. If you care only about speed you are seeing at the wrong project. Yes, uWSGI is probably one of the fastest application container out there, but it will always gives precedence to reliability and low-resource consumption in addition to an API aimed at allowing developers writing better apps.
What is 'Harakiri mode'?
We host hundreds of unreliable web apps on our servers. All of them run on hardly (at kernel level) constrained environments where having processes blocked for an implementation error will result on taking down an entire site. The harakiri mode has two operational modes (from version 0.9.4): one that we define as 'raw and a bit unreliable' (used for simple setup without a process manager) and another one that we define as 'reliable' that depends on the presence of the uWSGI process manager.
The first one sets a simple alarm at the start of every request. If the process gets a SIGALRM, it terminates itself. We call this 'a bit unreliable' because your app or some module you use could overwrite (or simply cancel) the alarm with a simple call to alarm().
The second one uses a master process shared memory area (via mmap) that maintains statistics on every worker on the pool. At the start of every request, the worker sets in its dedicated area a timestamp representing the time after the process will be killed. After every successful request this timestamp is zeroed. If the master process finds a worker with a timestamp in the past it will kill it.
Will my app run faster with uWSGI?
Probably not. The biggest bottleneck in web app deployment is the web app itself. If you want a faster environment, optimize your code or use techniques such as clustering or caching. We say that uWSGI is fast because it introduces a very little overhead in the deployment structure.
What are the most important options for performance and robustness in the uWSGI environment?
By default uWSGI is configured with almost-good-for-all values. But when things start going wild, tuning is a must.
Increasing (or decreasing) timeout is important, as is modifying the socket listen queue size.
Think about threading. If you do not need threads, do not enable them.
If you are running only a single application you can disable multiple interpreters (-i option).
Always remember to enable the master process in production environments.
Adding workers does not mean "increasing performance", so choose a good value based on the kind of your app (IO-Bound, Cpu_Bound, IO-waiting...)
Why not simply use HTTP as the protocol?
HTTP parsing is slow, really slow.
Why should we do a complex task twice? The web server has already done it!
The uwsgi protocol is very simple to parse for a machine. HTTP is very easy to parse for a human.
When humans are being used as servers, we will abandon the uwsgi protocol in favour of the HTTP protocol.
Why do you support multiple methods of configuration?
System administration is all about skills and taste. uWSGI tries to give sysadmins as much choice as possible based on personal-taste and integration with already available infrastructure. Having multiple methods of configuration is just one way we achieve this.
What is the best webserver handler?
It is very hard to give an answer on this topic. We will try to give you information on every one:
uWSGI support is officially included in the Cherokee webserver. Cherokee is fast and lightweight, has a beautiful admin interface and a great community. Their support for uWSGI has been awesome since the beginning and we recommend its use in most situations. The userbase of the Cherokee uWSGI handler is probably the biggest of all. It is commercially supported by Unbit.
The module is included in the official Nginx distribution from the 0.8.40 release. A 0.7.x version is maintained in the uWSGI package. This is a stable handler commercially supported by Unbit.
This is the first module developed, it is stable but could be better integrated with the Apache API. It is commercially supported by Unbit.
From the 0.9.6-dev version a second Apache2 module is included (mod_Ruwsgi) that is more apache-api friendly. mod_Ruwsgi is not commercially supported by Unbit.
Available from 0.9.8-dev via zeromq protocol plugin. In our tests Mongrel2 survived to pratically all of the loads we sent. Very good and solid project. Try it :)
This module is the last developed but its inclusion in the official lighttpd distribution has been rejected, as the main author consider the uwsgi protocol a "reinventing the wheel" technology while suggesting a FastCGI approach. We respect this position and we will continue to maintain the module as a third party one. There is currently no commercial support for this handler. We consider this module "experimental".
This is a "commodity" handler, useful mainly for testing applications without installing a full webserver. If you want to develop an uwsgi server, look at this module. RunOnTwisted
The included servlet can be used to forward requests from tomcat to the uWSGI server. It is stable, but currently lacks documentation. There is currently no commercial support for this handler.
The CGI handlers are for "lazy" installations. Their use in production environments is discouraged.
The uwsgi IIS handler is a commercial product. You can get information by emailing us at: info at unbit dot it