port t0019-max_header_len.sh to Perl 5
[unicorn.git] / KNOWN_ISSUES
blob0017f20deb9a81b3d2fc4cb927fc9af465d84503
1 = Known Issues
3 Occasionally odd {issues}[link:ISSUES.html] arise without a transparent or
4 acceptable solution.  Those issues are documented here.
6 * Some libraries/applications may install signal handlers which conflict
7   with signal handlers unicorn uses.  Leaving "preload_app false"
8   (the default) will allow unicorn to always override existing signal
9   handlers.
11 * Issues with FreeBSD jails can be worked around as documented by Tatsuya Ono:
12   https://yhbt.net/unicorn-public/CAHBuKRj09FdxAgzsefJWotexw-7JYZGJMtgUp_dhjPz9VbKD6Q@mail.gmail.com/
14 * PRNGs (pseudo-random number generators) loaded before forking
15   (e.g. "preload_app true") may need to have their internal state
16   reset in the after_fork hook.  Starting with unicorn 3.6.1, we
17   have builtin workarounds for Kernel#rand and OpenSSL::Random users,
18   but applications may use other PRNGs.
20 * For notes on sandboxing tools such as Bundler or Isolate,
21   see the {Sandbox}[link:Sandbox.html] page.
23 * nginx with "sendfile on" under FreeBSD 8 is broken when
24   uploads are buffered to disk.  Disabling sendfile is required to
25   work around this bug which should be fixed in newer versions of FreeBSD.
27 * When using "preload_app true", with apps using background threads
28   need to restart them in the after_fork hook because threads are never
29   shared with child processes.  Additionally, any synchronization
30   primitives (Mutexes, Monitors, ConditionVariables) should be
31   reinitialized in case they are held during fork time to avoid
32   deadlocks.  The core Ruby Logger class needlessly uses a MonitorMutex
33   which can be disabled with a {monkey patch}[link:examples/logger_mp_safe.rb]
35 == Known Issues (Old)
37 * Under some versions of Ruby 1.8, it is necessary to call +srand+ in an
38   after_fork hook to get correct random number generation.  We have a builtin
39   workaround for this starting with unicorn 3.6.1
41   See http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-core/36450
43 * On Ruby 1.8 prior to Ruby 1.8.7-p248, *BSD platforms have a broken
44   stdio that causes failure for file uploads larger than 112K.  Upgrade
45   your version of Ruby or continue using unicorn 1.x/3.4.x.
47 * Under Ruby 1.9.1, methods like Array#shuffle and Array#sample will
48   segfault if called after forking.  Upgrade to Ruby 1.9.2 or call
49   "Kernel.rand" in your after_fork hook to reinitialize the random
50   number generator.
52   See http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-core/28655
54 * Rails 2.3.2 bundles its own version of Rack.  This may cause subtle
55   bugs when simultaneously loaded with the system-wide Rack Rubygem
56   which unicorn depends on.  Upgrading to Rails 2.3.4 (or later) is
57   strongly recommended for all Rails 2.3.x users for this (and security
58   reasons).  Rails 2.2.x series (or before) did not bundle Rack and are
59   should be unnaffected.  If there is any reason which forces your
60   application to use Rails 2.3.2 and you have no other choice, then
61   you may edit your unicorn gemspec and remove the Rack dependency.
63   ref: https://yhbt.net/unicorn-public/20091014221552.GA30624@dcvr.yhbt.net/
64   Note: the workaround described in the article above only made
65   the issue more subtle and we didn't notice them immediately.
67 * WONTFIX: code reloading and restarts with Sinatra 0.3.x (and likely older
68   versions) apps is broken.  The workaround is to force production
69   mode to disable code reloading as well as disabling "run" in your
70   Sinatra application:
71     set :env, :production
72     set :run, false
73   Since this is no longer an issue with Sinatra 0.9.x apps, this will not be
74   fixed on our end.  Since unicorn is itself the application launcher, the
75   at_exit handler used in old Sinatra always caused Mongrel to be launched
76   whenever a unicorn worker was about to exit.
78   Also remember we're capable of replacing the running binary without dropping
79   any connections regardless of framework :)