Permalink
Browse files

Documentation improvements and additions

git-svn-id: svn://cherokee-project.com/cherokee/trunk@6317 5dc97367-97f1-0310-9951-d761b3857238
  • Loading branch information...
taher
taher committed Feb 16, 2011
1 parent b41e159 commit 047144f3a2f3c56b3f084de25400ceba53c48e16
View
@@ -69,6 +69,7 @@ cookbook_concrete5.html \
cookbook_https_accelerator.html \
cookbook_http_to_https.html \
cookbook_global_redirects.html \
+cookbook_traffic_restriction.html \
modules.html \
modules_balancers.html \
modules_balancers_failover.html \
@@ -96,6 +97,7 @@ modules_handlers_proxy.html \
modules_handlers_secdownload.html \
modules_handlers_uwsgi.html \
modules_handlers_empty_gif.html \
+modules_handlers_drop.html \
modules_loggers.html \
modules_loggers_combined.html \
modules_loggers_ncsa.html \
@@ -183,7 +183,7 @@ This section allows to define the list of domains that the virtual
server implements.
It can accept either FQDN (Fully Qualified Domain Names), wild card
-entries, regular expressions, IPs, or a combination of methods that
+entries, regular expressions, IPs/Subnets, or a combination of methods that
will be evaluated as a logical OR. This can be useful for some rare
cases where you might need to match by IP OR wildcards simultaneously,
such as the link:cookbook_ssl.html#workaround[HTTPS-without-SNI workaround]
@@ -236,6 +236,17 @@ nicknames not matched, while *.example.com does work?"]. A careful
reinterpretation of what has just been explained in this section
should clarify any doubts.
+WARNING: Do not use the IP/Subnet host match as a security measure to
+prevent access to specific IP addresses. The purpose of the IP/Subnet
+match type was to implement the SSL certificate selection workaround
+that other web servers have been using for years. If it were to be
+attacked, it could be easily overcome by simply setting the Host
+header to the name of the virtual server. To restrict the traffic of
+one of your virtual servers based on the incoming IP, please read the
+appropriate cookbook entry,
+link:cookbook_traffic_restriction.html[restricting traffic by IP].
+
+
[[behavior]]
Behavior
~~~~~~~~
View
@@ -36,3 +36,4 @@
. link:cookbook_uwsgi.html[uWSGI]: Setting up Cherokee for uWSGI.
. link:cookbook_http_to_https.html[HTTP to HTTPS]: How to redirect all traffic from HTTP to HTTPS.
. link:cookbook_global_redirects.html[Global redirections]: How to make a global redirectection for every (sub)domain.
+ . link:cookbook_traffic_restriction.html[Restricting traffic by IP]: how to restrict traffic based on incoming IP.
@@ -0,0 +1,23 @@
+== link:index.html[Index] -> link:cookbook.html[Cookbook]
+
+Cookbook: Restricting traffic by IP
+-----------------------------------
+
+This section answers some general questions regarding the current
+behavior of several parts of Cherokee that might lead to
+missunderstandings.
+
+Some scenarios require web traffic to be restricted on a virtual
+server basd on incoming IP. Although an IP/Subnet host match type is
+present on the `Host Match` tab of virtual servers, this can't be used
+as a security measure to enforce traffic restrictions. Its main
+purpose is explained elsewhere in the documentation, and suffice it to
+say that if this method were to be used, it could be easily overcomed by
+forging the `Host` header.
+
+If you want to restrict the traffic of one of your virtual servers
+based on the incoming IP, the best way to go is setting a non-final
+rule on top of your behavior rule list of the virtual server. That
+rule should match the forbidden IPs with an `Incoming IP/Port`-type
+rule (such as `(NOT Incoming IP: 127.0.0.1/8)`), and could be handled
+by custom error handler, or an appropriate redirection.
View
@@ -72,6 +72,8 @@ link:cookbook.html[Cookbook]: Recipes for specific tasks
. link:cookbook_uwsgi.html[uWSGI]: Setting up Cherokee for uWSGI.
. link:cookbook_http_to_https.html[HTTP to HTTPS]: How to redirect all traffic from HTTP to HTTPS.
. link:cookbook_global_redirects.html[Global redirections]: How to make a global redirectection for every (sub)domain.
+ . link:cookbook_traffic_restriction.html[Restricting traffic by IP]: how to restrict traffic based on incoming IP.
+
*********************************
link:modules.html[Modules]: Information about the standard modules
@@ -96,6 +98,7 @@ link:modules.html[Modules]: Information about the standard modules
- link:modules_handlers_dbslayer.html[MySQL bridge]: MySQL over HTTP bridge.
- link:modules_handlers_admin.html[Remote Administration]: Cherokee administration handler.
- link:modules_handlers_empty_gif.html[1x1 Transparent GIF]: Returns a 1x1 pixel transparent GIF.
+ - link:modules_handlers_drop.html[Drop Connection]: Immediately drop TCP connection.
. link:modules_validators.html[Validators]: Authentication mechanisms.
- link:modules_validators_plain.html[Plain]: Plain file mechanism.
- link:modules_validators_htpasswd.html[htpasswd]: htpasswd mechanism.
View
@@ -19,6 +19,7 @@
- link:modules_handlers_dbslayer.html[MySQL bridge]: MySQL over HTTP bridge.
- link:modules_handlers_admin.html[Remote Administration]: Cherokee administration handler.
- link:modules_handlers_empty_gif.html[1x1 Transparent GIF]: Returns a 1x1 pixel transparent GIF.
+ - link:modules_handlers_drop.html[Drop Connection]: Immediately drop TCP connection.
. link:modules_validators.html[Validators]: Authentication mechanisms.
- link:modules_validators_plain.html[Plain]: Plain file mechanism.
- link:modules_validators_htpasswd.html[htpasswd]: htpasswd mechanism.
View
@@ -31,3 +31,4 @@ This is the list of standard handlers provided by Cherokee:
* link:modules_handlers_dbslayer.html[MySQL bridge]: MySQL over HTTP bridge.
* link:modules_handlers_admin.html[Remote Administration]: Cherokee administration handler.
* link:modules_handlers_empty_gif.html[1x1 Transparent GIF]: Returns a 1x1 pixel transparent GIF.
+* link:modules_handlers_drop.html[Drop Connection]: Immediately drop TCP connection.
@@ -0,0 +1,25 @@
+== link:index.html[Index] -> link:modules.html[Modules] -> link:modules_handlers.html[Handlers]
+
+Handler: Drop Connection
+------------------------
+
+This handler immediately drops the TCP connection without replying
+anything whatsoever.
+
+This handler can be used as security measure against some types of
+attack. For instance, an an error in the PHP and Java floating point
+library could be exploited to cause a denial of service against a web
+service. Under certain circumstances, attempting to convert the string
+'2.2250738585072011e-308' into a floating point value can hang the PHP
+runtime. Similarly, the Java runtime (and compiler) suffer from a
+related problem.
+
+By filtering incoming traffic and using this handler,
+requests that may seek to exploit this fault can be safely discarded.
+
+TIP: Any application code that parses input into a floating point
+could be vulnerable. More importantly, the family of 'Accept' HTTP
+headers use floating point scores that could be exploited on certain
+implementations. To prevent this problem, a solution could be to create a
+Header-type rule that matches the '2250738585072011' string and
+discards the requests.
@@ -31,7 +31,7 @@ evaluated right before writing each log entry:
|`${transport}` |https |Transport type: `http` or `https`
|`${user_remote}` |guest |Remote user (authentication)
|`${vserver_name}` |default |Virtual Server nick name
-|`${vserver_name_req}` |example.com |Requested host (Host: header)
+|`${vserver_name_req}` |example.com |Requested host (Host: header), or vserver nickname if absent
|`${http_host}` |example.com |"Host:" header of the request
|`${http_referrer}` |example.com/page |"Referrer:" header of the request
|`${http_user_agent}` |Mozilla/1.0.0 |"User-Agent:" header of the request
@@ -60,3 +60,25 @@ would generate this entry in the log:
[08/Apr/2009:12:02:11 +0200] 74.125.67.100: /file.txt (200)
----
+
+Apache's comined format
+~~~~~~~~~~~~~~~~~~~~~~~
+The following formats are all like Apache's combined format, except the second field not being the client ident but the (way more interesting) HTTP host or vserver name.
+
+* Virtual server name
++
+----
+${ip_remote} ${vserver_name} ${user_remote} [${now}] "${request_first_line}" ${status} ${response_size} "${http_referrer}" "${http_user_agent}"
+----
+
+* Host
++
+----
+${ip_remote} ${http_host} ${user_remote} [${now}] "${request_first_line}" ${status} ${response_size} "${http_referrer}" "${http_user_agent}"
+----
+
+* Host if present, otherwise virtual serven name
++
+----
+${ip_remote} ${vserver_name_req} ${user_remote} [${now}] "${request_first_line}" ${status} ${response_size} "${http_referrer}" "${http_user_agent}"
+----
@@ -23,5 +23,25 @@ course this step is not necessary when invoked with the
development purposes.
Refer to the link:other_bundle_cherokee-admin.html[cherokee-admin
-documentation ]for more in-depth explanations of all the parameters
+documentation] for more in-depth explanations of all the parameters
and options.
+
+
+*SIGNALS*::
+ You can send the SIGHUP signal to cherokee-admin-launcher to
+ make it relaunch a web browser conviniently authenticated
+ agains cherokee-admin. This is useful in case you closed the
+ web browser and wished to access cherokee-admin again without
+ restarting it, since manual access would require you to provide
+ the one-time login details that you wouldn't have.
+
+
+.Command on Solaris
+----
+# pkill -HUP cherokee-admin-launcher
+----
+
+.Command on most Unix-like systems
+----
+# killall -HUP cherokee-admin-launcher
+----
View
@@ -47,6 +47,13 @@ around, so after the mailing lists it is the second best place to look
for answers and help.
+[[forums]]
+Forums
+~~~~~~
+Multi-language forums are available at the
+link:http://forum.cherokee-project.com/[Cherokee-Project] site.
+
+
The Cherokee Planet
~~~~~~~~~~~~~~~~~~~

0 comments on commit 047144f

Please sign in to comment.