Permalink
Browse files

Documentation needed a brush up

git-svn-id: svn://cherokee-project.com/cherokee/trunk@5399 5dc97367-97f1-0310-9951-d761b3857238
  • Loading branch information...
1 parent 267be32 commit 90f3e2a0aec07faa7b91f350cd3f72062db875fd taher committed Aug 17, 2010
View
@@ -1,52 +1,73 @@
.TH cherokee-tweak 1
.SH NAME
-cherokee-tweak - Command-line interface to the Cherokee administrative interface
+cherokee-tweak - Command-line interface to the administration interface of Cherokee
.SH SYNOPSIS
.B cherokee-tweak
-\-c command \-a url [options]
+[options] URL info
+.PP
+.B cherokee-tweak
+[options] URL sources
+.PP
+.B cherokee-tweak
+[options] URL kill-source ID
+.PP
+.B cherokee-tweak
+[options] URL logrotate PATH
+.PP
+.B cherokee-tweak
+[options] URL trace TRACE
.SH DESCRIPTION
-\fIcherokee-tweak\fP connects to running cherokee instance, either local or remote,
+\fIcherokee-tweak\fP connects to a running cherokee instance, either local or remote,
and requests it to perform one of several actions.
-.SH OPTIONS
-\fIcherokee-tweak\fP accepts the following options:
+.SH COMMANDS
+.TP 8
+.B info
+Prints info about the server status
+.TP 8
+.B sources
+Prints a list of the information sources
+.TP 8
+.B kill-source
+Kill a remote information source, specified by its reported ID
+.TP 8
+.B logrotate
+Rotates a local (*and only local*) log file specified by PATH.
+.TP 8
+.B trace
+Manipulates the tracing mechanism. TRACE should be the
+string that specifies the modules to be traced, and
+Cherokee must have been compiled with the
+\--enable-trace option for this to work. Everything
+traceable with CHEROKEE_TRACE can also be traced this
+way.
+.SH PARAMETERS
+.TP 8
+.B URL
+Required before any command. This is the URL where the administration
+interface can be found. This target must be defined previously in
+\fcherokee-admin\f, enabling a "Remote Administration" type handler
+(Virtual Servers->Behaviour->Add new rule, and then Handler->"Remote
+Administration"). The deffinition of a security mechanism is highly
+encouraged.
.TP 8
.B \-h, --help
Shows brief usage information
.TP 8
.B \-V, --version
Prints version and exits
+.SH OPTIONS
.TP 8
-.B \-u, --user= STRING
+\fIcherokee-tweak\fP accepts the following options:
+.TP 8
+.B \-u, --user=STRING
Specifies the user name with which to identify to the server
.TP 8
-.B \-p, --password= STRING
+.B \-p, --password=STRING
Specifies the password with which to identify to the server
-.TP 8
-.B \-c, --command=STRING
-Required option. Command to execute: logrotate, trace or info
-.TP 8
-.B \-a, --url=URL
-Required option. URL where the administration interface can be found.
-This target must be defined previously in cherokee-admin, enabling
-a "Remote Administration" type handler (Virtual Servers->Behaviour->Add new rule,
-and then Handler->"Remote Administration"). The deffinition of a security mechanism
-is highly encouraged.
-.TP 8
-.B \-l, --log=PATH
-Log file to be rotated (Only to be used when -c is logrotate)
-.TP 8
-.B \-t, --trace=STRING
-Modules to be traced (Only to be used when -c is trace). Cherokee must have
-been compiled with the --enable-trace for this to work. Everything traceable
-with CHEROKEE_TRACE can also be traced this way.
.SH SEE ALSO
\&\fIcherokee-admin\fR\|(8)
.PP
This program is a part of the Cherokee web server, \&\fIcherokee\fR\|(1)
.SH AUTHOR
-This manual page was written by Gunnar Wolf <gwolf@debian.org>, for
-the Debian GNU/linux system (but may be used by others). Maintained by Taher
-Shihadeh <taher@unixwars.com>.
.PP
-Cherokee itself was written by Álvaro López Ortega
-<alvaro@alobbs.com>.
+Cherokee was written by Alvaro Lopez Ortega<alvaro@alobbs.com>. This manual page was written by Taher Shihadeh <taher@unixwars.com>.
View
@@ -191,6 +191,7 @@ media/images/cookbook_maintenance_advanced_domains.png \
media/images/cookbook_redir_behavior.png \
media/images/cookbook_redir_domains.png \
media/images/cookbook_redir_handler.png \
+media/images/cookbook_redir_https.png \
media/images/cookbook_dbslayer1.png \
media/images/cookbook_dbslayer2.png \
media/images/cookbook_dbslayer3.png \
@@ -1,6 +1,6 @@
== link:index.html[Index] -> link:config.html[Configuration] -> link:config_virtual_servers.html[Virtual servers]
////
-Last checked: 2010/05/06 Cherokee 0.99.50b
+Last checked: 2010/08/17 Cherokee 1.0.9b
////
Virtual Server: Rules
@@ -174,6 +174,21 @@ on the values you have configured. The available options are:
. 2038: Maximum date value representable in POSIX time.
. Custom Value: set a value by hand.
+Additionaly, if a content expiration option is set, it is possible to
+specify the way in which an intermediate cache should treat the
+content, for situations such as when the content is requested to
+Cherokee through an HTTP proxy. This is done through the `Management
+by caches` setting, that can be specified to any of the following
+values: `Not set`, `Private`, `Public`, `No Cache`.
+
+If the setting is enabled, four additional parameters can be
+individually turned on and off to fine tune the behavior:
+
+ . No Store: Prevents the retention of sensitive information. Caches must not store this content.
+ . No Transform: Forbid intermediate caches from transforming the content.
+ . Must Revalidate: The client must contact the server to revalidate the object.
+ . Proxies Revalidate: Proxy servers must contact the server to revalidate the object.
+
[[security]]
Security
View
@@ -1,4 +1,7 @@
== link:index.html[Index] -> link:cookbook.html[Cookbook]
+////
+Last checked: 2010/08/17 Cherokee 1.0.9b
+////
Cookbook: Redirections
----------------------
@@ -42,3 +45,21 @@ image::media/images/cookbook_redir_handler.png[Handler configuration]
Keep in mind the redirection has to be external in order for Cherokee
to rewrite the the URL. If it wasn't, the redirection would be applied
but no change would be displayed to the users while browsing the site.
+
+
+Redirecting to HTTPS
+~~~~~~~~~~~~~~~~~~~~
+
+Now lets imagine a scenario where the name of the virtual server
+matched is of importance for the substitution. For instance, supose
+you want all the traffic to the `/secure_dir` directory of a regular
+HTTP channel to be redirected to an HTTPS channel through a server
+whose name depends on that of the matching host.
+
+In this case you need to resort to the macros supported by the
+handler. First you'll have to create a `Directory` type rule managed
+by the `Redirection` handler. And second, define an _external
+redirection_ with a _Regular Expression_ like __^/(.*)$__ and the
+appropriate _Substitution_: https://${host}/secure_dir/$1
+
+image::media/images/cookbook_redir_https.png[HTTPS redirections]
@@ -1,4 +1,8 @@
== link:index.html[Index] -> link:dev.html[Development info]
+////
+Outdated. Most changes since January 2009 are trivial, and not much
+content has been added since.
+////
Development: cherokee.conf
--------------------------
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
@@ -15,7 +15,7 @@ valuable tool for system administration *and* a severe security risk
if no precautions are taken. You are strongly encouraged to both
encrypt the channel and disable public access.
-There are no parameter to be configured for this handle.
+There are no parameters to be configured for this handle.
The information provided covers a wide spectrum: ports (secured and
non-secured), TX/RX status, connections, threads, backup mode and
@@ -26,3 +26,18 @@ this, and the section about
link:other_bundle_cherokee-tweak.html[cherokee-tweak] for specific usage
information.
+Also, you should think of this handler as a web-service. In fact,
+cherokee-tweak is just a client application using consuming
+it. Writing custom client-apps that make use of this handler is almost
+trivial, since commands can be issued from the command line using
+`curl`.
+
+.Command line examples:
+------------------------------------------------------------------------
+echo 'set server.trace time,thread,all' | curl -v http://localhost/admin/ -u myuser:mypassword --data-binary @-
+echo 'set server.trace none' | curl -v http://localhost/admin/ -u myuser:mypassword --data-binary @-
+echo 'get server.connections' | curl -v http://localhost/admin/ -u myuser:mypassword --data-binary @-
+echo 'close server.connection 100' | curl -v http://localhost/admin/ -u myuser:mypassword --data-binary @-
+echo 'get server.sources' | curl -v http://localhost/admin/ -u myuser:mypassword --data-binary @-
+echo 'kill server.source 3' | curl -v http://localhost/admin/ -u myuser:mypassword --data-binary @-
+------------------------------------------------------------------------
@@ -1,4 +1,7 @@
== link:index.html[Index] -> link:modules.html[Modules] -> link:modules_handlers.html[Handlers]
+////
+Last checked: 2010/08/17 Cherokee 1.0.9b
+////
Handler: Redirection
--------------------
@@ -48,7 +51,17 @@ the substitution.
the intended target of such petition. Getting into details of
regular expressions is out of the scope of this document. Besides,
there are many link:http://perldoc.perl.org/perlre.html[Perl
- regular expressions] references.
+ regular expressions] references. Macros can be used for these
+ substitutions, which is specially handy for some cases that cannot
+ be covered any other way, such as uniformly managing virtual
+ servers with multiple matches. Take a look at the examples at the
+ end of this section for further clarification.
++
+[options="header"]
+|=========================================================================
+|Variable |Example |Description
+|`${host}` |example.com |Host of the matching virtual server
+|=========================================================================
[[vhosts]]
@@ -94,10 +107,11 @@ This example will perform internal redirections:
[cols="30%,70%",options="header"]
|=======================================================================================
-|Regular Expression |Substitution
-|__/(\d+)$__ |http://example.com/inst/photogallery/viewphoto?photoid=$1
-|__/(\d+)/cmts__ |http://example.com/viewcomments?photoid=$1
-|__/(\d+)/delete__ |http://example.com/inst/photogallery/admin?photoid=$1&method=delete
+|Regular Expression |Substitution
+|__/(\d+)$__ |http://example.com/inst/photogallery/viewphoto?photoid=$1
+|__/(\d+)/cmts__ |http://example.com/viewcomments?photoid=$1
+|__/(\d+)/delete__ |http://example.com/inst/photogallery/admin?photoid=$1&method=delete
+|__/https_redir/(\d+)__|https://${host}/secure?photoid=$1
|=======================================================================================
Which would translate into the following redirections for the listed
@@ -109,4 +123,5 @@ matching requests:
|__/photo/123__ |http://example.com/inst/photogallery/viewphoto?photoid=123
|__/photo/213/cmts__ |http://example.com/viewcomments?photoid=213
|__/photo/501/delete__ |http://example.com/inst/photogallery/admin?photoid=501&method=delete
+|__/https_redir/555__ |https://example.com/secure?photoid=555
|===========================================================================================
@@ -1,12 +1,12 @@
== link:index.html[Index] -> link:other.html[Other information] -> link:other_bundle.html[Man pages]
-///////////////////////////////////////////////////////////////////
-Last checked: Cherokee 1.0.5b
-///////////////////////////////////////////////////////////////////
+////
+Last checked: 2010/08/17 Cherokee 1.0.9b
+////
Man pages: cherokee-tweak
-------------------------
-This command-line tool is also not as well known as it would. Again
+This command-line tool is also not as well known as it should. Again
this is not by lack of merits, which in fact are considerable. Its
intended audience are also system administrators and developers.
@@ -23,55 +23,73 @@ These actions are:
* Provide information: `info`.
+ * Report the list of Information Sources of a running server and
+ their individual statuses.
+
+ * Kill remotely any information source.
This is the full information provided by the manpage.
**********************************************************************
*NAME*::
- cherokee-tweak - Command-line interface to the Cherokee administrative
- interface
+ cherokee-tweak - Command-line interface to the administration interface of Cherokee
*SYNOPSIS*::
- cherokee-tweak -c command -a url [options]
+ cherokee-tweak [options] URL info
+ cherokee-tweak [options] URL sources
+ cherokee-tweak [options] URL kill-source ID
+ cherokee-tweak [options] URL logrotate PATH
+ cherokee-tweak [options] URL trace TRACE
*DESCRIPTION*::
- cherokee-tweak connects to running cherokee instance, either local or
+ cherokee-tweak connects to a running cherokee instance, either local or
remote, and requests it to perform one of several actions.
-*OPTIONS*::
- cherokee-tweak accepts the following options:
-
- -h, --help;;
+*COMMANDS*::
+ info;;
+ Prints info about the server status
+
+ sources;;
+ Prints a list of the information sources
+
+ kill-source;;
+ Kill a remote information source, specified by its reported ID
+
+ logrotate;;
+ Rotates a local (*and only local*) log file specified by PATH.
+
+ trace;;
+ Manipulates the tracing mechanism. TRACE should be the
+ string that specifies the modules to be traced, and
+ Cherokee must have been compiled with the
+ --enable-trace option for this to work. Everything
+ traceable with CHEROKEE_TRACE can also be traced this
+ way.
+
+*PARAMETERS*::
+ URL;;
+ Required before any command. This is the URL where the
+ administrative interface can be found. This target
+ must be defined previously in cherokee-admin, enabling
+ a "Remote Administration" type handler (Virtual
+ Servers->Behavior->Rule Management->Add new rule, and
+ then Handler->"Remote Administration"). The definition
+ of a security mechanism is highly encouraged.
+
+ -h, --help;;
Shows brief usage information
- -V, --version;;
- Prints version and exits
+ -V, --version;;
+ Print version and exit
+
+*OPTIONS*::
+ cherokee-tweak accepts the following options:
- -u, --user= STRING;;
+ -u, --user=STRING;;
Specifies the user name with which to identify to the server
- -p, --password=STRING;;
+ -p, --password=STRING;;
Specifies the password with which to identify to the server
- -c, --command=STRING;;
- Required option. Command to execute: logrotate, trace or info
-
- -a, --url=URL;;
- Required option. URL where the administrative interface
- can be found. This target must be defined previously
- in cherokee- admin, enabling a "Remote Administration"
- type handler (Virtual Servers->Behavior->Rule
- Management->Add new rule, and then Handler->"Remote
- Administration"). The definition of a security
- mechanism is highly encouraged.
-
- -l, --log=PATH;;
- Log file to be rotated (Only to be used when -c is logrotate)
-
- -t, --trace=STRING;;
- Modules to be traced (Only to be used when -c is trace). Chero‐
- kee must have been compiled with the --enable-trace for this to
- work. Everything traceable with CHEROKEE_TRACE can also be
- traced this way.
**********************************************************************
To use `cherokee-tweak`, an administrative interface must be defined
@@ -97,9 +115,9 @@ Every module traceable with CHEROKEE_TRACE can also be traced this
way. Refer to the link:dev_debug.html["Debugging"] section of the
documentation for more information on this matter.
-Keep in mind one important thing: when the `-t` option is specified,
-`cherokee-tweak` activates the tracing functionality within the
-`cherokee` instance. It does not provide tracing of its own. This
+Keep in mind one important thing: when the `trace` command is
+specified, `cherokee-tweak` activates the tracing functionality within
+the `cherokee` instance. It does not provide tracing of its own. This
means the debugging information will appear in the machine that is
actually running the `cherokee` instance. This may or may not be the
same that is running the `cherokee-tweak` process.

0 comments on commit 90f3e2a

Please sign in to comment.