Changeset 1801

Show
Ignore:
Timestamp:
08/13/08 20:15:57 (3 months ago)
Author:
taher
Message:

--

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • cherokee/trunk/ChangeLog

    r1800 r1801  
     12008-08-13  Taher Shihadeh <taher@unixwars.com> 
     2 
     3        * doc/basics.txt, doc/basics_why_cherokee.txt, 
     4        doc/build/chunked_template.conf, doc/build/combined_template.conf, 
     5        doc/build/combined.txt, doc/build/doc.conf, doc/bundle.txt, 
     6        doc/config.txt, doc/cookbook_authentication.txt, 
     7        doc/cookbook_cross_compilation.txt, doc/cookbook_django.txt, 
     8        doc/cookbook_managing_logs.txt, doc/cookbook_optimizations.txt, 
     9        doc/cookbook_php.txt, doc/cookbook_ror.txt, doc/cookbook_ssl.txt, 
     10        doc/cookbook.txt, doc/dev_api.txt, doc/dev_cherokee.conf.txt, 
     11        doc/dev_examples.txt, doc/dev.txt, doc/index.txt, 
     12        doc/modules_handlers_fcgi.txt, doc/modules_handlers_scgi.txt, 
     13        doc/modules.txt, doc/modules_validators_htdigest.txt, 
     14        doc/modules_validators_htpasswd.txt, 
     15        doc/modules_validators_ldap.txt, doc/modules_validators_mysql.txt, 
     16        doc/modules_validators_pam.txt, doc/modules_validators_plain.txt, 
     17        doc/other_goodies.txt, doc/other.txt: almost done with 
     18        documents. Added some snapshots too. 
     19 
    1202008-08-13  Alvaro Lopez Ortega  <alvaro@alobbs.com> 
    221 

  • cherokee/trunk/doc/Makefile.am

    r1786 r1801  
    1 DOC_RELEASE=0.8.0 
    2  
    3 ASCIIDOC=python $(top_srcdir)/doc/build/asciidoc.py --unsafe -b xhtml11 --conf-file=$(top_srcdir)/doc/build/chunked_template.conf -a cherokee_version=$(DOC_RELEASE) 
    4 ASCIIDOC_TOC=python $(top_srcdir)/doc/build/asciidoc.py -b xhtml11 -s  
     1ASCIIDOC=python $(top_srcdir)/doc/build/asciidoc.py --unsafe --conf-file=$(top_srcdir)/doc/build/doc.conf 
     2ASCIIDOC_TOC=python $(top_srcdir)/doc/build/asciidoc.py -s  
    53 
    64SUFFIXES = .txt .html .inc 
    75 
    86.txt.inc: 
    9         $(ASCIIDOC_TOC) -o $@ $<  
     7        $(ASCIIDOC_TOC) -o $@ $(top_srcdir)/doc/$<  
    108 
    119.txt.html: 
    12         $(ASCIIDOC) $<  
     10        $(ASCIIDOC) -o $@ $(top_srcdir)/doc/$<  
    1311 
    1412docdir = $(datadir)/doc/cherokee 
    1513doc_DATA = \ 
    16 TOC.inc \ 
     14index.inc \ 
     15index.html \ 
    1716basics.html \ 
    1817basics_why_cherokee.html \ 
    …… 
    4241config_advanced.html \ 
    4342cookbook.html \ 
     43cookbook_managing_logs.html \ 
     44cookbook_optimizations.html \ 
    4445cookbook_cross_compilation.html \ 
     46cookbook_django.html \ 
     47cookbook_php.html \ 
     48cookbook_ror.html \ 
    4549cookbook_authentication.html \ 
    4650cookbook_ssl.html \ 
    47 cookbook_optimizations.html \ 
    48 cookbook_php.html \ 
    49 cookbook_ror.html \ 
    50 cookbook_django.html \ 
    5151modules.html \ 
    5252modules_balancers.html \ 
    …… 
    7777modules_validators_pam.html \ 
    7878modules_validators_plain.html \ 
     79other.html \ 
    7980other_goodies.html \ 
    8081dev.html \ 

  • cherokee/trunk/doc/TOC.txt

    r1786 r1801  
    4040********************************* 
    4141 
    42 ///// 
    43   Reference table     <8>      link:cookbook_reference.html[] 
    44   Optimizing Cherokee <2>      link:cookbook_optimizations.html[] <descriptors, iocache, x-sendfile, 
    45 ///// 
     42//// 
     43  . Embedding Cherokee  <9>    link:cookbook_embedding_cherokee.html[] 
     44  . Managing logs       <5>    link:cookbook_managing_logs.html[] <backends, rotations and cherokee-tweak?> 
     45//// 
    4646 
     47  . link:cookbook_optimizations.html[Optimizing Cherokee] 
    4748  . link:cookbook_cross_compilation.html[Cross compilation] 
    48  
    49 //// 
    50   Embedding Cherokee  <9>       link:cookbook_embedding_cherokee.html[] 
    51   Managing logs       <5>       link:cookbook_managing_logs.html[] <backends, rotations and cherokee-tweak?> 
    52   Authentication      [8] <3>   link:cookbook_authentication.html[Authentication] 
    53   SSL/TLS, certs      [13]<6>   link:cookbook_ssl.html[] 
    54 //// 
     49  . link:cookbook_django.html[Setting up Django] 
    5550  . link:cookbook_php.html[Setting up PHP] 
    56 ////// 
    57   Setting up Django   <4>       link:cookbook_django.html[] 
    58   Setting up RoR      <4>       link:cookbook_ror.html[] 
    59 ////// 
     51  . link:cookbook_ror.html[Setting up RoR] 
     52  . link:cookbook_ssl.html[SSL/TLS, certs] 
     53  . link:cookbook_authentication.html[Authentication] 
    6054 
    6155********************************* 
    62 Modules 
     56link:modules.html[Modules] 
    6357********************************* 
    6458 
    …… 
    9286 
    9387********************************* 
    94 Other resources 
     88link:other.html[Other information] 
    9589********************************* 
    9690 
    …… 
    10296 
    10397********************************* 
    104 Development info 
     98link:dev.html[Development info] 
    10599********************************* 
    106100 
    …… 
    111105  . Examples            link:dev_examples.html[] 
    112106//// 
     107 
     108 
     109 
     110//////////////////////////////////////////////////// 
     111Remaingin tasks: 
     112---------------- 
     113* <3> How to setup authenticated resources <cookbook_authentication.txt> 
     114* <5> How to manage logs  (make specific mention of usage of 
     115      Cherokee-Tweak and log backers). 
     116* <6> How to manage security (SSL/TLS, certs, etc) <cookbook_ssl.txt> 
     117* <7> Development documentation 
     118* <8> Reference table of functionalities to be achieved (and hopefully 
     119      a full setup example). 
     120* <9> Cherokee on exotic devices 
     121//////////////////////////////////////////////////// 

  • cherokee/trunk/doc/basics.txt

    r1765 r1801  
    1 ********************************* 
    2 Getting started 
    3 ********************************* 
    4  
    51 . link:basics_why_cherokee.html[Why Cherokee?] 
    62 . link:basics_requirements.html[Requirements] 

  • cherokee/trunk/doc/basics_why_cherokee.txt

    r1773 r1801  
    22------------- 
    33 
    4 Welcome to the Cherokee {cherokee_version} documentation. Cherokee is 
     4Welcome to the Cherokee 0.8 documentation. Cherokee is 
    55high-performance web server. It is very fast, flexible and easy to 
    66configure. It offers support for the widespread technologies nowadays: 

  • cherokee/trunk/doc/build/doc.conf

    r1765 r1801  
    2525</div> 
    2626<div id="page_nav"> 
    27 include::../TOC.inc[] 
     27include::../index.inc[] 
    2828</div> 
    2929<div id="footer"> 

  • cherokee/trunk/doc/bundle.txt

    r1765 r1801  
    1 ********************************* 
    2 Cherokee Bundle 
    3 ********************************* 
    4  
    51 . link:bundle_cherokee.html[cherokee] 
    62 . link:bundle_cherokee-admin.html[cherokee-admin] 

  • cherokee/trunk/doc/config.txt

    r1765 r1801  
    1 ********************************* 
    2 Configuration 
    3 ********************************* 
    4  
    51  . link:config_quickstart.html[Quickstart] 
    62  . link:config_general.html[General] 

  • cherokee/trunk/doc/cookbook.txt

    r1765 r1801  
    1 ********************************* 
    2 Cookbook 
    3 ********************************* 
    4  
     1  . link:cookbook_optimizations.html[Optimizing Cherokee] 
     2  . link:cookbook_cross_compilation.html[Cross compilation] 
     3  . link:cookbook_django.html[Setting up Django] 
     4  . link:cookbook_php.html[Setting up PHP] 
     5  . link:cookbook_ror.html[Setting up RoR] 
     6  . link:cookbook_ssl.html[SSL/TLS, certs] 
     7  . link:cookbook_authentication.html[Authentication] 

  • cherokee/trunk/doc/cookbook_authentication.txt

    r1740 r1801  
    1 Authentication 
    2 -------------- 
     1Cookbook: Authentication 
     2------------------------ 
     3 
     4In this section you will find information useful to set up 
     5authentication mechanisms with several of Cherokee's validators. 
     6 
     7You can find information and basic examples in each validator's 
     8documentation. This is the list of validator modules provided by 
     9Cherokee: 
     10 
     11* link:modules_validators_htdigest.html[htdigest] 
     12* link:modules_validators_htpasswd.html[htpasswd] 
     13* link:modules_validators_ldap.html[LDAP] 
     14* link:modules_validators_mysql.html[MySQL] 
     15* link:modules_validators_pam.html[PAM] 
     16* link:modules_validators_plain.html[Plain] 
     17 
     18You will also find interesting information in the 
     19link:modules_validators_plain.html["Validator Modules Overview"] and 
     20step by step examples for Plain and PAM mechanisms in the 
     21link:config_quickstart.html["Quickstart"] section. 
    322 
    423There are two types of authentication: 
    …… 
    1433    web browsers support this method. 
    1534 
    16 Cherokee comes with a number of validators: link:modules_validators_htpasswd.html[htpasswd],  
    17 link:modules_validators_htdigest.html[htdigest], link:modules_validators_pam.html[PAM],  
    18 link:modules_validators_ldap.html[LDAP], link:modules_validators_mysql.html[MySQL],  
    19 and a link:modules_validators_plain.html[plain] text file. 
    2035 
     36//// 
     37To be written 
     38 
     39Details for htdigest, htpasswd, mysql and ldap. 
     40//// 

  • cherokee/trunk/doc/cookbook_cross_compilation.txt

    r1740 r1801  
    1 How to cross compile Cherokee 
    2 ----------------------------- 
     1Cookbook: How to cross compile Cherokee 
     2--------------------------------------- 
    33 
    44Cherokee-Win32 from Linux 

  • cherokee/trunk/doc/cookbook_django.txt

    r1786 r1801  
    1 Setting up Django 
    2 ----------------- 
     1Cookbook: Setting up Django 
     2--------------------------- 
    33 
    4 To be written 
     4Django is a fantastic high-level Python Web framework that can run 
     5nicely with Cherokee and either the 
     6link:modules_handlers_scgi.html[SCGI] or 
     7link:modules_handlers_fcgi.html[FastCGI] or handlers. 
    58 
    6 [python-flup] 
     9To properly set up Cherokee to use Django you will need a working 
     10Django framework, which is not difficult at all to get ready. The 
     11details vary from system to system. You can refer to the official 
     12project's documentation for more information on 
     13link:http://www.djangoproject.com/documentation/install[how to install 
     14Django]. 
     15 
     16 
     17On Debian based systems this will be enough: 
     18---- 
     19# apt-get install python-django python-flup 
     20---- 
     21 
     22You will need Flup because it implements the standard interface 
     23between Python Web applications and Web servers, so you will be using 
     24it to run your web application either as FastCGI or SCGI. 
     25 
     26 
     27Once you are done with that, you must deploy your Django project: 
     28 
     29---- 
     30$ cd /var/www 
     31$ django-admin.py startproject example 
     32---- 
     33 
     34This will create the basic structure into a new directory called 
     35`example`. Now you are ready to configure Cherokee. You only need to 
     36know how to spawn the FastCGI or SCGI, which is done with a script 
     37provided by your project called `manage.py`. 
     38 
     39It can be run on a TCP port or on a Unix socket. In our example we 
     40will be launching it as threaded server on a TCP port with SCGI 
     41protocol. This is acomplished with the following command, which is 
     42what we will have to set up in `cherokee-admin`. 
     43 
     44---- 
     45./manage.py runfcgi method=threaded host=127.0.0.1 port=3033 protocol=scgi 
     46---- 
     47 
     48The process is fairly simple. Set up a new rule for this new path and 
     49manage it with the SCGI handler. If you wanted to use the FastCGI 
     50handler instead you would only have to omit the last parameter and 
     51FastCGI would be used by default. The configuration of the handler is 
     52exactly the same for SCGI and FastCGI. 
     53 
     54Once you have created the new rule for your `/var/www/example 
     55directory`, choose the desired handler and use the following 
     56configuration. 
     57 
     58.Common CGI options 
     59Under `Common CGI options` make sure to check the `Error handler` box and 
     60uncheck `Check file`. This is to prevent possible errors with the 
     61`INFO_PATH` generation that can happen when an application, in this 
     62case 'Rails', manages the whole subtree. This is mentioned in the 
     63link:modules_handlers_cgi.html[Common CGI] section of the 
     64documentation. 
     65 
     66image::media/images/cookbook_django_common.png[Common CGI options] 
     67 
     68.SCGI specific 
     69Under `SCGI specific` make sure to add the hosts providing the 
     70service. Note that you will have to manually launch the `spawner` if 
     71you use a `Remote host` as `Information source` instead of a `Local 
     72interpreter`. 
     73 
     74You will simply have to add as many sources as desired, for instance 
     75our example uses the port 3033. 
     76 
     77[grid="rows"] 
     78`~~~~~~~~~~~~~~`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     79Host           , Interpreter 
     80~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     81localhost:3033 , `/var/www/example/manage.py runfcgi method=threaded ` \ 
     82                 `host=127.0.0.1 port=3033 protocol=scgi` 
     83~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     84 
     85You can set up as many hosts as desired and Cherokee will balance the 
     86load among them. 
     87 
     88image::media/images/cookbook_django_scgi.png[SCGI specifics] 

  • cherokee/trunk/doc/cookbook_optimizations.txt

    r1786 r1801  
    1 Optimizing Cherokee 
    2 ------------------- 
     1Cookbook: Optimizing Cherokee 
     2----------------------------- 
    33 
    4 To be written. 
    5 Talk about. 
     4Cherokee's default parameters are suitable for most cases. However, 
     5there are a number of things that can be tweaked in order to improve 
     6the behavior of Cherokee under special circumstances. 
    67 
    7 Check: 
     8Compiled capabilities 
     9~~~~~~~~~~~~~~~~~~~~~ 
     10 
     11First of all you should check the capabilities that have been built 
     12into your specific Cherokee build. This can be done by: 
     13 
     14---- 
     15$ cherokee -i 
     16Compilation 
     17 Version: 0.8.0 
     18 
     19[...] 
     20 
     21Support 
     22 IPv6: yes 
     23 OpenSSL: no 
     24 GnuTLS: yes 
    825 Pthreads: yes 
    926 Tracing: yes 
    1027 sendfile(): yes 
     28 syslog(): yes 
    1129 Polling methods: select poll epoll 
     30---- 
    1231 
    13 IO cache & file, number of threads, increase descriptors, X-Sendfile... 
     32The last section is interesting. If you see that any siginficant 
     33capability supported by your platform is missing, you should really 
     34build another binary or check if something is wrong with your 
     35system. Note that not every single capability is present in every 
     36platform. For instance, `epoll` is a polling method specific to Linux 
     37platforms, and its abscence from any non-Linux system is perfectly 
     38normal. It is inherently more efficient than the other methods. On the 
     39other hand the second best choice is `poll` which is POSIX conformant 
     40and will only be available on systems that follow the POSIX 
     41standard. From the list above, the capabilities that have a dramatic 
     42impact in the speed of Cherokee are the polling methods, the existence 
     43of sendfile() and the Pthreads support. 
     44 
     45 
     46Tweaks 
     47~~~~~~ 
     48 
     49There is no general recomendation that is the best for everybody. In 
     50general Cherokee's default values try to offer a good compromise 
     51between resources and performance, but for specific cases you will be 
     52able to tweak somethings that may (or may not) improve the overall 
     53performance. Some of the things to keep in mind are mentioned here. 
     54 
     55Encoding:: 
     56As it is explained in the link:modules_encoders.html[Encoders'] 
     57documentation, compressing the information to be sent makes a lot of 
     58sense for specific file types. Not that much processing power is used 
     59to compress a text file, for instance, and hardware is cheaper than 
     60bandwidth, so you should encode files whenever it makes sense. 
     61 
     62Handler specific:: 
     63* *CGI, SCGI, FastCGI*: link:other_goodies.html#x-sendfile[X-Sendfile] 
     64  support can be enabled or disabled. If you know what this is, you 
     65  will know how X-Sendfile improves performance by assigning the task 
     66  of serving files to the web server while leaving the backend 
     67  application to run free without waiting for the task to end. This 
     68  gives you extra performance at no cost, but of course your 
     69  application must specifically make use of this feature. 
     70+ 
     71* *Static Content*: IO cache is a caching mechanism that dramatically 
     72 improves performance serving files. The caching algorithm is very 
     73 efficient and assures that a file will be immediately served while it 
     74 remains cached. The usage of IO cache is absolutely recommended in 
     75 all cases except when the contents of the files are changed 
     76 frequently. 
     77 
     78General:: 
     79+ 
     80* *Timeout*: The lower your timeout interval is, the faster you will 
     81  free up resources at the cost of cancelling viable but slow 
     82  connections. 
     83+ 
     84* *Keep alive*: This setting dramatically affects the speed at which 
     85  repeated connections are server to the same client. This is 
     86  especially noticeable when an asyncrhonous application is used. The 
     87  trade off is that, since connections are kept open more time, less 
     88  connections remain available for other clients in any given 
     89  moment. Cherokee does a pretty good job at reclaiming unused open 
     90  connections, especially when the number of connections approaches 
     91  the limit imposed to the system, but any way you should keep in mind 
     92  this. 
     93 
     94Advanced:: 
     95+ 
     96* System tweaking: 
     97 - Threads: The default value is chosen so that it is more than enough 
     98   to saturate the processors. You will probably not get much out of 
     99   this setting, since a higher value will not produce better results 
     100   and a lower one will simply increase the amount of unused processor 
     101   power. 
     102+ 
     103 - File descriptors: By deffinition, the higher this limit is, the 
     104   less efficient will your system be in relative terms. However, it 
     105   is understood that if you are tweaking this value is because you 
     106   need to, that is, you have a very high load site. In these cases 
     107   increasing the file descriptors' limit makes sense because the 
     108   higher this limit is, the more connections Cherokee will be able to 
     109   handle. By default Cherokee does not touch this value and it uses 
     110   the one specified by your system. 

  • cherokee/trunk/doc/cookbook_php.txt

    r1786 r1801  
    1  
    2 Setting up PHP 
    3 -------------- 
     1Cookbook: Setting up PHP 
     2------------------------ 
    43 
    54There is not much to learn to configure PHP with Cherokee. 

  • cherokee/trunk/doc/cookbook_ror.txt

    r1786 r1801  
    1 Setting up Ruby on Rails 
    2 ------------------------ 
     1Cookbook: Setting up Ruby on Rails 
     2---------------------------------- 
    33 
    4 To be written 
     4Setting up a Rails application to run with Cherokee and FastCGI is not 
     5only easy. It is also the best possible solution to manage the load 
     6among one or many Rails servers, using an extremely efficient web 
     7server to manage the web part and leaving as many free resources as 
     8possible to Rails. 
    59 
    6 sudo gem update --system 
    7 sudo gem install rails 
    8 rails example 
    9 cd example 
    10 script/process/spawner fcgi 
     10Of course you will need a working Rails installation for this to 
     11succed. You can set this up easily. If you have Ruby and Ruby Gems 
     12installed, you can directly install the 'Rails' gem like this: 
     13 
     14---- 
     15# gem update --system 
     16# gem install rails 
     17---- 
     18 
     19Note that on Debian based systems you don't even need to install 
     20Rubygems. There is already a package that will install every needed 
     21dependency: 
     22 
     23---- 
     24# apt-get install rails 
     25---- 
     26 
     27The installation of the 'Rails' gem directly would also work, but note 
     28that you cannot execute the first command because it is disabled by 
     29default. 
     30 
     31---- 
     32# gem update --system 
     33ERROR:  While executing gem ... (RuntimeError) 
     34    gem update --system is disabled on Debian. RubyGems can be updated \ 
     35    using the official Debian repositories by aptitude or apt-get. 
     36---- 
     37 
     38Once you are done with that, you must deploy your Rails project: 
     39 
     40---- 
     41$ rails example 
     42---- 
     43 
     44You can do so wherever you want, but the usal recommended way of doing 
     45this is by deploying it outside of your web root path and then 
     46creating a symbolic link. This is simply to protect from exposure all 
     47the files that do not need to be in your document root. 
     48 
     49Assuming you deployed the `example` project in `/home/foo/example`, 
     50and you have writing permissions to your web path, `/var/www`, simply 
     51type: 
     52 
     53---- 
     54$ ln -s /home/foo/example/public /var/www/example 
     55---- 
     56 
     57Now you are ready to configure Cherokee. You only need to know that 
     58you can spawn the FastCGI process using a script that is already in 
     59your deployed project. In this case, 
     60`/home/foo/example/script/process/spawner`. 
     61We will be using the default parameters (3 instances starting at port 
     628000) but you can fine tune this using the many parameters provided by 
     63the script. 
     64 
     65The process is fairly simple. Set up a new rule for this new path and 
     66manage it with the FastCGI handler. 
     67 
     68.Common CGI options 
     69Under `Common CGI options` make sure to check the `Error handler` box and 
     70uncheck `Check file`. This is to prevent possible errors with the 
     71`INFO_PATH` generation that can happen when an application, in this 
     72case 'Rails', manages the whole subtree. This is mentioned in the 
     73link:modules_handlers_cgi.html[Common CGI] section of the 
     74documentation. 
     75 
     76image::media/images/cookbook_ror_common.png[Common CGI options] 
     77 
     78.FastCGI specific 
     79Under `FastCGI specific` make sure to add the hosts providing the 
     80service. Note that you will have to manually launch the `spawner` if 
     81you use a `Remote host` as `Information source` instead of a `Local 
     82interpreter`. 
     83 
     84You will simply have to add as many sources as desired, for instance 
     85our example uses the default values to set up ports 8000 through 8002: 
     86 
     87[grid="rows"] 
     88`~~~~~~~~~~~~~~`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     89Host           , Interpreter 
     90~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     91localhost:8000 , `/home/foo/example/script/process/spawner fastcgi` 
     92localhost:8001 , `/home/foo/example/script/process/spawner fastcgi` 
     93localhost:8002 , `/home/foo/example/script/process/spawner fastcgi` 
     94~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     95 
     96If any of those ports was not reachable, the `interpreter` command 
     97would be launched and the fallen one would be reinstantiated. 
     98 
     99image::media/images/cookbook_ror_fcgi.png[FastCGI specifics] 

  • cherokee/trunk/doc/cookbook_ssl.txt

    r1740 r1801  
    1 How to generate SSL keys 
    2 ------------------------ 
     1Cookbook: SSL, TLS and certificates 
     2----------------------------------- 
    33 
    4 Locate CA.pl or CA.sh  
     4To generate SSL keys you will have to follow these steps detailed below. 
     5 
     6Locate CA.pl or CA.sh 
    57~~~~~~~~~~~~~~~~~~~~~ 
    68 
    7 In Debian GNU/Linux are located in /usr/lib/ssl/misc/  
     9In Debian GNU/Linux those are located in /usr/lib/ssl/misc/ 
    810 
    9 ``find / -iname CA.pl -print`` might help.  
     11``find / -iname CA.pl -print`` might help. 
    1012 
    1113Create a new CA 
    …… 
    9092            emailAddress              = sysop@cherokee-project.com 
    9193        X509v3 extensions: 
    92             X509v3 Basic Constraints:  
     94            X509v3 Basic Constraints: 
    9395            CA:FALSE 
    94             Netscape Comment:  
     96            Netscape Comment: 
    9597            OpenSSL Generated Certificate 
    96             X509v3 Subject Key Identifier:  
     98            X509v3 Subject Key Identifier: 
    9799            14:6A:45:66:A2:EB:73:74:5A:C5:68:80:50:D5:48:94:DD:ED:25:F7 
    98             X509v3 Authority Key Identifier:  
     100            X509v3 Authority Key Identifier: 
    99101            keyid:9E:E0:E2:6E:1B:02:17:F2:72:C9:0D:E3:DA:C9:E1:8F:CE:BC:6E:A2 
    100102            DirName:/C=ES/ST=Madrid/L=Madrid/O=Cherokee Team/CN=Cherokee Certificate Master/emailAddress=alvaro@alobbs.com 
    …… 
    114116~~~~~~~~~~~~~~~~~~~~~~~~ 
    115117 
    116 It's another way to generate certificate files. Ramon Pons sent this little script to create  
    117 self signed certificates:: 
     118It's another way to generate certificate files. Ramon Pons sent this 
     119little script to create self signed certificates:: 
    118120 
    119121---- 

  • cherokee/trunk/doc/dev.txt

    r1765 r1801  
    1 ********************************* 
    2 Development info 
    3 ********************************* 
    4  
     1  . link:dev_debug.html[Debugging] 
     2  . link:dev_cherokee.conf.html[cherokee.conf] 

  • cherokee/trunk/doc/dev_cherokee.conf.txt

    r1767 r1801  
    4040should know about. 
    4141 
    42 The following blocks will summarize the configuration keys that 
    43 Cherokee {cherokee_version} handles: 
     42The following blocks will summarize the configuration keys that the 
     43current Cherokee release handles: 
    4444 
    4545Server 
    …… 
    8484 
    8585[grid="rows"] 
    86 ``~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     86`~~~~~~~~~~~~`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
    8787Value                     , Description 
    8888~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
    …… 
    9797 
    9898[grid="rows"] 
    99 ``~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     99`~~~~~~~~~~~~`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
    100100Value                     , Description 
    101101~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
    …… 
    113113 
    114114[grid="rows"] 
    115 ``~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     115`~~~~~~~~~~~~`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
    116116Parameter                 , Description 
    117117~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
    …… 
    149149 
    150150[grid="rows"] 
    151 ```~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     151`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~`~~~~~~~~~`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
    152152**Key**                           , **Type**, **Description** 
    153153~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
    …… 
    253253 
    254254[grid="rows"] 
    255 ```~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     255`~~~~~~~~~~~~~~`~~~~~~~~~~`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
    256256**Key**                                 , **Type**, **Description** 
    257257~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
    …… 
    264264~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
    265265 
    266 The ``auth`` entry deserves a little more attention, actually. It 
    267 restricts the access to some of the objects accessed by the web 
    268 server based on a number of properties that are defined at its child 
    269 properties: 
    270  
    271 [grid="rows"] 
    272 ```~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     266The ``auth`` entry deserves a little more attention, 
     267actually. Accepted validarot modules are `htdigest, htpasswd, ldap, 
     268mysql, pam, plain`. It restricts the access to some of the objects 
     269accessed by the web server based on a number of properties that are 
     270defined at its child properties: 
     271 
     272[grid="rows"] 
     273`~~~~~~~~~~~~`~~~~~~~~~~~~`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
    273274**Key**                                 , **Type**, **Description** 
    274275~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
    …… 
    278279~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
    279280 
    280 So, here are a few examples about how this notation works: 
     281Some validators have extra configuration keys. 
     282 
     283.htdigest, htpasswd, plain 
     284[grid="rows"] 
     285`~~~~~~~~~~~~~~~~~`~~~~~~~~~`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     286**Key**           , **Type**, **Description** 
     287~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     288auth!passwdfile   , String  , Full path to the passwords' file. htdigest|htpasswd|plain 
     289~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     290 
     291.mysql 
     292[grid="rows"] 
     293`~~~~~~~~~~~~~~~~~`~~~~~~~~~`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     294**Key**           , **Type**, **Description** 
     295~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     296auth!host           , String, MySQL host. 
     297auth!database       , String, Database name. 
     298auth!user           , String, Database user. 
     299auth!passwd         , String, Database password. 
     300auth!port           , Number, Port number of the service. 
     301auth!query          , String, SQL query to match users/passwords. \ 
     302                              Replace your username for '${user}'. 
     303auth!use_md5_passwd , Bool  , Encrypt the passwords with MD5. 
     304~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     305 
     306.ldap 
     307[grid="rows"] 
     308`~~~~~~~~~~~~`~~~~~~~~~~`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     309**Key**      , **Type**, **Description** 
     310~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     311auth!server  , String  , IP or hostname of the LDAP server. 
     312auth!port    , Number  , Port number of the service. 
     313auth!base_dn , String  , Base distinguished name. 
     314auth!bind_dn , String  , User 
     315auth!bind_pw , String  , Password 
     316auth!filter  , String  , LDAP search filter. 
     317auth!tls     , Bool    , Indicates TLS based integrity 
     318auth!ca_file , String  , Cert file. Must be provided if TLS is enabled. 
     319~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     320 
     321Here are a few examples about how this notation works: 
    281322 
    282323- The default virtual server uses the "common" handler as default 
    …… 
    313354    vserver!1!rule!extensions!iso,ISO!auth!methods = digest 
    314355    vserver!1!rule!extensions!iso,ISO!auth!passwdfile = /var/passwd/isos.htdigest 
     356---- 
     357 
     358- Authenticated directory with `htpasswd` validator: 
     359+ 
     360---- 
     361vserver!10!rule!500!auth = htpasswd 
     362vserver!10!rule!500!auth!methods = basic 
     363vserver!10!rule!500!auth!passwdfile = /var/www/passwd.htpasswd 
     364vserver!10!rule!500!auth!realm = secret 
     365vserver!10!rule!500!match = directory 
     366vserver!10!rule!500!match!directory = /auth 
     367vserver!10!rule!500!match!final = 0 
     368vserver!10!rule!500!only_secure = 0 
     369---- 
     370 
     371- Same example, using `mysql` validator: 
     372+ 
     373---- 
     374vserver!10!rule!500!auth = mysql 
     375vserver!10!rule!500!auth!database = auth_users 
     376vserver!10!rule!500!auth!host = localhost 
     377vserver!10!rule!500!auth!methods = basic,digest 
     378vserver!10!rule!500!auth!passwd = db_passwd 
     379vserver!10!rule!500!auth!port = 3306 
     380vserver!10!rule!500!auth!query = SELECT password FROM auth_users WHERE username= '${user}' 
     381vserver!10!rule!500!auth!realm = secret 
     382vserver!10!rule!500!auth!use_md5_passwd = 1 
     383vserver!10!rule!500!auth!user = db_user 
     384vserver!10!rule!500!match = directory 
     385vserver!10!rule!500!match!directory = /auth 
     386vserver!10!rule!500!match!final = 0 
     387vserver!10!rule!500!only_secure = 0 
     388---- 
     389 
     390- Same thing with `ldap` validator: 
     391+ 
     392---- 
     393vserver!10!rule!500!auth = ldap 
     394vserver!10!rule!500!auth!base_dn = Example DN 
     395vserver!10!rule!500!auth!bind_dn = Directory Manager 
     396vserver!10!rule!500!auth!bind_pw = secretpassword 
     397vserver!10!rule!500!auth!methods = basic 
     398vserver!10!rule!500!auth!port = 389 
     399vserver!10!rule!500!auth!realm = secret 
     400vserver!10!rule!500!auth!server = ldap.example.com 
     401vserver!10!rule!500!auth!tls = 0 
     402vserver!10!rule!500!match = directory 
     403vserver!10!rule!500!match!directory = /auth 
     404vserver!10!rule!500!match!final = 0 
     405vserver!10!rule!500!only_secure = 0 
    315406---- 
    316407 

  • cherokee/trunk/doc/modules.txt

    r1765 r1801  
    1 ********************************* 
    2 Modules 
    3 ********************************* 
     1  . link:modules_balancers.html[Balancers] 
     2    - link:modules_balancers_round_robin.html[Round robin] 
     3  . link:modules_encoders.html[Encoders] 
     4    - link:modules_encoders_gzip.html[gzip] 
     5    - link:modules_encoders_deflate.html[deflate] 
     6  . link:modules_handlers.html[Handlers] 
     7    - link:modules_handlers_file.html[Static Content] 
     8    - link:modules_handlers_dirlist.html[Only listing] 
     9    - link:modules_handlers_common.html[List & Send] 
     10    - link:modules_handlers_redir.html[Redirection] 
     11    - link:modules_handlers_cgi.html[CGI] 
     12    - link:modules_handlers_fcgi.html[FastCGI] 
     13    - link:modules_handlers_scgi.html[SCGI] 
     14    - link:modules_handlers_server_info.html[Server Info] 
     15    - link:modules_handlers_mirror.html[Generic balancer] 
     16    - link:modules_handlers_admin.html[Remote Administration] 
     17  . link:modules_loggers.html[Loggers] 
     18    - link:modules_loggers_combined.html[Combined] 
     19    - link:modules_loggers_ncsa.html[Common (NCSA)] 
     20    - link:modules_loggers_w3c.html[w3c] 
     21  . link:modules_validators.html[Validators] 
     22    - link:modules_validators_plain.html[Plain] 
     23    - link:modules_validators_htpasswd.html[htpasswd] 
     24    - link:modules_validators_htdigest.html[htdigest] 
     25    - link:modules_validators_ldap.html[LDAP] 
     26    - link:modules_validators_mysql.html[MySQL] 
     27    - link:modules_validators_pam.html[PAM] 
    428 

  • cherokee/trunk/doc/modules_handlers_fcgi.txt

    r1786 r1801  
    3131for specifics. 
    3232 
     33 
     34Unix Sockets 
     35~~~~~~~~~~~~ 
     36 
     37Note that the FastCGI and SCGI handlers can directly use Unix 
     38sockets. You only have to specify a full path to the socket instead of 
     39the `host:port`, and everything will simply work. 
     40 
     41 
    3342Examples 
    3443~~~~~~~~ 
    …… 
    3746handler. The recipe about link:cookbook_php.html[setting up PHP] is a 
    3847good starting point. 
     48 
    3949 
    4050Note for developers 

  • cherokee/trunk/doc/modules_handlers_scgi.txt

    r1776 r1801  
    1212and manage. 
    1313 
    14 In the end SCGI offers the same performance as FastCGI (and better 
     14In the end, SCGI offers the same performance as FastCGI (and better 
    1515than other methods), offers cross platform simultaneous support and is 
    1616simple to install, run, and configure. 

  • cherokee/trunk/doc/modules_validators_htdigest.txt

    r1777 r1801  
    2121This validator is compatible with both **basic** and **digest** schemes. 
    2222 
    23 Example 
    24 ^^^^^^^ 
    25  
    26 Here is an example of what could be reflected in the 
    27 link:dev_cherokee.conf.html[cherokee.conf] configuration file after 
    28 setting up this authentication mechanism. Refer to the 
    29 link:cookbook_authentication.html[Authentication] recipe for a full 
    30 hands-on approach. 
    31  
    32 ---- 
    33 vserver!10!rule!500!auth = htdigest 
    34 vserver!10!rule!500!auth!methods = basic 
    35 vserver!10!rule!500!auth!passwdfile = /var/www/passwd.htdigest 
    36 vserver!10!rule!500!auth!realm = secret 
    37 vserver!10!rule!500!match = directory 
    38 vserver!10!rule!500!match!directory = /auth 
    39 vserver!10!rule!500!match!final = 0 
    40 vserver!10!rule!500!only_secure = 0 
    41 ---- 

  • cherokee/trunk/doc/modules_validators_htpasswd.txt

    r1777 r1801  
    3232 
    3333This validator is compatible with the **basic** scheme, it's not suitable for HTTP Digest. 
    34  
    35 Example 
    36 ^^^^^^^ 
    37  
    38 Here is an example of what could be reflected in the 
    39 link:dev_cherokee.conf.html[cherokee.conf] configuration file after 
    40 setting up this authentication mechanism. Refer to the 
    41 link:cookbook_authentication.html[Authentication] recipe for a full 
    42 hands-on approach. 
    43  
    44 ---- 
    45 vserver!10!rule!500!auth = htpasswd 
    46 vserver!10!rule!500!auth!methods = basic 
    47 vserver!10!rule!500!auth!passwdfile = /var/www/passwd.htpasswd 
    48 vserver!10!rule!500!auth!realm = secret 
    49 vserver!10!rule!500!match = directory 
    50 vserver!10!rule!500!match!directory = /auth 
    51 vserver!10!rule!500!match!final = 0 
    52 vserver!10!rule!500!only_secure = 0 
    53 ---- 

  • cherokee/trunk/doc/modules_validators_ldap.txt