Apache2::Controller::Directives - server config directives for A2C
Version 1.000.111
# apache2 config file PerlLoadModule Apache2::Controller::Directives # for Apache2::Controller::Render::Template settings: A2C_Render_Template_Path /var/myapp/templates # etc.
All values are detainted using m{ \A (.*) \z }mxs, since they are assumed to be trusted because they come from the server config file. As long as you don't give your users the ability to set directives, it should be okay.
m{ \A (.*) \z }mxs
See Apache2::Controller::Dispatch
This is the path to a file compatible with YAML::Syck. If you do not provide a dispatch_map() subroutine, the hash will be loaded with this file.
dispatch_map()
Different subclasses of Apache2::Controller::Dispatch have different data structures. YMMV.
Or, if you just specify a package name, it will generate a dispatch map with one 'default' entry with that package.
See Apache2::Controller::Render::Template.
This is the base path for templates used by Apache2::Controller::Render::Template. The directive takes only one parameter and verifies that the directory exists and is readable.
(At startup time Apache2 is root... this should verify readability by www user? Hrmm how is it going to figure out what user that is? It will have to access the server config via $parms. Except that this does not appear to work? It returns an empty hash.)
<location "/where/template/is/used"> A2C_Render_Template_Opts INTERPOLATE 1 A2C_Render_Template_Opts PRE_PROCESS header meta style scripts A2C_Render_Template_Opts POST_CHOMP 1 </location>
Options for Template Toolkit. See Template.
You can also implement <get_template_opts> in your controller subclass, which simply returns the hash reference of template options. See Apache2::Controller::Render::Template.
<get_template_opts
Note the behavior is to merge values specified at multiple levels into array references. i.e. a subdirectory could specify an additional <PRE_PROCESS> template or whatever. YMMV. It should be this way, at any rate!
<PRE_PROCESS
See Apache2::Controller::Session.
A2C_Session_Class Apache::Session::File
Single argument, the class for the tied session hash. Apache::Session.
Multiple arguments
A2C_Session_Opts Directory /tmp/sessions A2C_Session_Opts LockDirectory /var/lock/sessions
# generate a random 30-character string: A2C_Session_Secret # specify your own string: A2C_Session_Secret jsd9e9j#*@JMf39kc3
This server-wide constant string will used to verify the session id. See Apache2::Controller::Session.
If you don't specify the value, it will generate a default 30-character random string, but this will regenerate on server restarts, and would not work for a cluster of servers serving the same application.
A2C_Session_Always_Save
Takes no arguments. If directed, Apache2::Controller::Session will update a top-level timestamp in $r->pnotes->{a2c}{session}{a2c_timestamp} so that Apache::Session will always save.
$r->pnotes->{a2c}{session}{a2c_timestamp}
A2C_Session_Cookie_Opts name myapp_sessionid A2C_Session_Cookie_Opts expires +3M
Multiple arguments. Apache2::Controller::Session::Cookie, Apache2::Cookie
Misc. directives that apply to most A2C objects that inherit Apache2::Controller::Methods.
A2C_Skip_Bogus_Cookies
Takes no arguments. If present, cookie jar will be constructed using eval { } that skips NOTOKEN errors. See "get_cookie_jar" in Apache2::Controller::Methods.
eval { }
See Apache2::Controller::DBI::Connector.
A2C_DBI_DSN DBI:mysql:database=foobar;host=localhost
Single argument, the DSN string. DBI
A2C_DBI_User heebee
Single argument, the DBI username.
A2C_DBI_Password jeebee
Single argument, the DBI password.
Multiple arguments.
A2C_DBI_Options RaiseError 1 A2C_DBI_Options AutoCommit 0
Boolean.
A2C_DBI_Cleanup 1
String value.
A2C_DBI_Pnotes_Name reader
If you subclass DBI, specify the name of your DBI subclass here.
A2C_DBI_Class MyApp::DBI
Note that this is connected with a string eval which is slow. If you don't use it, it uses a block eval to connect DBI.
See Apache2::Controller::Auth::OpenID.
A2C_Auth_OpenID_Login login
The URI path for your login controller page.
If you start the value with a '/', it thinks you mean an absolute URI.
If you do not start the value with a '/', it thinks you mean a uri relative to the location path where the directive was declared.
Examples:
<Location '/foo/bar'> A2C_Auth_OpenID_Login /login </Location>
The user would be redirected to absolute uri '/login'.
<Location '/loungy/vegas/entertainment'> A2C_Auth_OpenID_Login kenny_loggins </Location>
The user would be redirected to /loungy/vegas/entertainment/kenny_loggins if they are not logged in.
/loungy/vegas/entertainment/kenny_loggins
These conventions are the same for A2C_Auth_OpenID_Logout and A2C_Auth_OpenID_Register.
A2C_Auth_OpenID_Logout
A2C_Auth_OpenID_Register
Default is the path where the controller is declared, appended with '/login'. Access will be allowed.
A2C_Auth_OpenID_Logout logout
The URI path for your logout controller page.
Logout is processed automatically, resetting the flag and timestamp in the session hash. So you just need to present a page that says "Good riddance" or something.
Same conventions apply as to A2C_Auth_OpenID_Login. Default is the path where the controller is declared, appended with '/logout'. Access will be allowed.
A2C_Auth_OpenID_Login
A2C_Auth_OpenID_Register register
The path for your registration page, where you will ask the user to sign up and associate a username with the openid url.
Same conventions apply as to A2C_Auth_OpenID_Login. Default is the path where the controller is declared, appended with '/register'. Access will be allowed.
A2C_Auth_OpenID_Timeout +1h
Idle timeout in seconds, +2m, +3h, +4D, +6M, +7Y, or 'no timeout'. Default is 1 hour. A month is actually 30 days, a year 365.
If you use 'no timeout' then logins will never expire. This probably is not a good idea because OpenID url's can be revoked, and because the login process can be a transparent series of redirects if the user has something like Verisign's SeatBelt plugin.
If you're doing some sort of cluster application or load balancing and sharing the session between servers, make sure all your servers are synchronized with NTP.
A2C_Auth_OpenID_Login openid
Name of the table in your connected database containing the user name and OpenID url fields. Default == "openid".
A2C_Auth_OpenID_User_Field uname
Name of username field in table. Default == "uname".
A2C_Auth_OpenID_URL_Field openid_url
Name of OpenID URL field in table. Default == "openid_url".
A2C_Auth_OpenID_DBI_Name dbh
Name in $r->pnotes->{a2c} of the connected DBI handle. Default == "dbh".
$r->pnotes->{a2c}
A2C_Auth_OpenID_Trust_Root http://blah.tld/blah
The trust_root param to pass to the user's OpenID server. See Net::OpenID::Consumer. Default is the top of the web site with whatever scheme, host and port that is currently being requested.
A2C_Auth_OpenID_LWP_Class LWPx::ParanoidAgent
Name of the LWP class to use. By default it uses LWPx::ParanoidAgent but not LWPx::ParanoidAgent::DashT, as that one is not available as a Debian package, I was unsuccessful building it with dh-make-perl, and I want to be able to distribute to Debian.
Specify options to the LWP class.
A2C_Auth_OpenID_LWP_Opts timeout 10 A2C_Auth_OpenID_LWP_Opts agent A2C-openid A2C_Auth_OpenID_LWP_Opts whitelisted_hosts [ 127.0.0.1 foo.bar.com ]
Don't whitelist stuff for ParanoidAgent unless you know what you're doing... I was going do this for the test suite to let the module call the temporary OpenID server set up on localhost.
But that ends up not working in the test suite because of some other problem trying to connect to a port which I don't know necessarily? ("Error fetching URL: No sock from bgsend"). So the test suite just uses plain old LWP::UserAgent.
This uses hash_assign() to assign the options.
hash_assign()
Use [ ] to force an array ref for a single option that has to be an arrayref:
A2C_Auth_OpenID_LWP_Opts whitelisted_hosts [ 192.168.34.5 ]
but don't use commas, it's tricky.
A2C_Auth_OpenID_Allow_Login
Takes no arguments. If directed, Apache2::Controller::Auth::OpenID will allow all login attempts and will not attempt to authenticate with OpenID. Useful for debugging your application on your laptop when you are not connected to the Internet.
# generate a random 30-character string: A2C_Auth_OpenID_Consumer_Secret # specify your own string: A2C_Auth_OpenID_Consumer_Secret jsd9e9j#*@JMf39kc3
This server-wide constant string will be appended to the value of time() for the sha224_base64 hash provided as the consumer_secret. See "consumer_secret" in Net::OpenID::Consumer.
A2C_Auth_OpenID_NoPreserveParams
Takes no arguments. If directed, Apache2::Controller::Auth::OpenID will not preserve GET/POST params. I know a double-negative is frowned upon, but it makes the most sense here, because preserving GET/POST params should be the default behavior, and this turns off that behavior.
This is not a configuration option, but an internal routine that we use to assign ITERATE2 options in a consistent way, or so one might hope. I'm not sure I fully understand the behavior and I haven't written tests for directives.
If a single value is specified, it is assigned as a scalar.
If multiple values are specified (on the same configuration directive call or in multiple calls) they are successively
This is sort of similar the way that $r->param will get a string or an array ref depending if the var has been named more than once.
$r->param
A2C_Auth_OpenID_LWP_Opts whitelisted_hosts [ 127.0.0.1 ]
but don't use commas, it's tricky. The closing ] is actually ignored, but you should use it to make it look sensible.
As a result, you can't use '[' or ']' for the values of any of these options... but you "shouldn't need to do that."
See "ITERATE2" in Apache2::Const.
Apache2::Controller
"get_directive" in Apache2::Controller::Methods
Apache2::Controller::Session
Apache2::Module
Mark Hedges, hedges +(a t)- formdata.biz
hedges +(a t)- formdata.biz
Copyright 2008-2010 Mark Hedges. CPAN: markle
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
This software is provided as-is, with no warranty and no guarantee of fitness for any particular purpose.
To install Apache2::Controller, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Apache2::Controller
CPAN shell
perl -MCPAN -e shell install Apache2::Controller
For more information on module installation, please visit the detailed CPAN module installation guide.