NAME
Apache2::Controller::Directives - server config directives for A2C
VERSION
Version 1.000.100
SYNOPSIS
# 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.
Apache2::Controller::Dispatch
See Apache2::Controller::Dispatch
A2C_Dispatch_Map
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.
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.
Apache2::Controller::Render::Template
See Apache2::Controller::Render::Template.
A2C_Render_Template_Path
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.)
A2C_Render_Template_Opts
<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.
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!
Apache2::Controller::Session
See Apache2::Controller::Session.
A2C_Session_Class
A2C_Session_Class Apache::Session::FileSingle argument, the class for the tied session hash. Apache::Session.
A2C_Session_Opts
Multiple arguments
A2C_Session_Opts Directory /tmp/sessions
A2C_Session_Opts LockDirectory /var/lock/sessionsA2C_Session_Secret
# generate a random 30-character string:
A2C_Session_Secret
# specify your own string:
A2C_Session_Secret jsd9e9j#*@JMf39kc3This 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
A2C_Session_Always_SaveTakes 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.
A2C_Session_Cookie_Opts
A2C_Session_Cookie_Opts name myapp_sessionid
A2C_Session_Cookie_Opts expires +3MMultiple arguments. Apache2::Controller::Session::Cookie, Apache2::Cookie
Apache2::Controller::DBI::Connector
See Apache2::Controller::DBI::Connector.
A2C_DBI_DSN
A2C_DBI_DSN DBI:mysql:database=foobar;host=localhostSingle argument, the DSN string. DBI
A2C_DBI_User
A2C_DBI_User heebeeSingle argument, the DBI username.
A2C_DBI_Password
A2C_DBI_Password jeebeeSingle argument, the DBI password.
A2C_DBI_Options
Multiple arguments.
A2C_DBI_Options RaiseError 1
A2C_DBI_Options AutoCommit 0A2C_DBI_Cleanup
Boolean.
A2C_DBI_Cleanup 1A2C_DBI_Pnotes_Name
String value.
A2C_DBI_Pnotes_Name readerA2C_DBI_Class
If you subclass DBI, specify the name of your DBI subclass here.
A2C_DBI_Class MyApp::DBINote 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.
Apache2::Controller::Auth::OpenID
See Apache2::Controller::Auth::OpenID.
A2C_Auth_OpenID_Login
A2C_Auth_OpenID_Login loginThe 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.
These conventions are the same for A2C_Auth_OpenID_Logout and A2C_Auth_OpenID_Register.
Default is the path where the controller is declared, appended with '/login'. Access will be allowed.
A2C_Auth_OpenID_Logout
A2C_Auth_OpenID_Logout logoutThe 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_Register
A2C_Auth_OpenID_Register registerThe 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
A2C_Auth_OpenID_Timeout +1hIdle 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_Table
A2C_Auth_OpenID_Login openidName of the table in your connected database containing the user name and OpenID url fields. Default == "openid".
A2C_Auth_OpenID_User_Field
A2C_Auth_OpenID_User_Field unameName of username field in table. Default == "uname".
A2C_Auth_OpenID_URL_Field
A2C_Auth_OpenID_URL_Field openid_urlName of OpenID URL field in table. Default == "openid_url".
A2C_Auth_OpenID_DBI_Name
A2C_Auth_OpenID_DBI_Name dbhName in $r->pnotes->{a2c} of the connected DBI handle. Default == "dbh".
A2C_Auth_OpenID_Trust_Root
A2C_Auth_OpenID_Trust_Root http://blah.tld/blahThe 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
A2C_Auth_OpenID_LWP_Class LWPx::ParanoidAgentName 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.
A2C_Auth_OpenID_LWP_Opts
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.
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
A2C_Auth_OpenID_Allow_LoginTakes 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.
A2C_Auth_OpenID_Consumer_Secret
# generate a random 30-character string:
A2C_Auth_OpenID_Consumer_Secret
# specify your own string:
A2C_Auth_OpenID_Consumer_Secret jsd9e9j#*@JMf39kc3This 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.
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_Auth_OpenID_NoPreserveParams
A2C_Auth_OpenID_NoPreserveParamsTakes 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.
hash_assign
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.
Use [ ] to force an array ref for a single option that has to be an arrayref:
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.
SEE ALSO
"get_directive" in Apache2::Controller::Methods
AUTHOR
Mark Hedges, hedges +(a t)- scriptdolphin.org
COPYRIGHT AND LICENSE
Copyright 2008 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.