/ 
Apache2-Controller-v1.1.1
River stage zero No dependents
/ Apache2::Controller::Directives

NAME

Apache2::Controller::Directives - server config directives for A2C

VERSION

Version 1.001.001

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::File

Single 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/sessions

A2C_Session_Secret

# 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

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.

A2C_Session_Cookie_Opts name    myapp_sessionid
A2C_Session_Cookie_Opts expires +3M

Multiple arguments. Apache2::Controller::Session::Cookie, Apache2::Cookie

Apache2::Controller::Methods

Misc. directives that apply to most A2C objects that inherit Apache2::Controller::Methods.

A2C_Skip_Bogus_Cookies

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.

Apache2::Controller::DBI::Connector

See Apache2::Controller::DBI::Connector.

A2C_DBI_DSN

A2C_DBI_DSN        DBI:mysql:database=foobar;host=localhost

Single argument, the DSN string. DBI

A2C_DBI_User

A2C_DBI_User       heebee

Single argument, the DBI username.

A2C_DBI_Password

A2C_DBI_Password   jeebee

Single argument, the DBI password.

A2C_DBI_Options

Multiple arguments.

A2C_DBI_Options    RaiseError  1
A2C_DBI_Options    AutoCommit  0

A2C_DBI_Cleanup

Boolean.

A2C_DBI_Cleanup        1

A2C_DBI_Pnotes_Name

String value.

A2C_DBI_Pnotes_Name    reader

A2C_DBI_Class

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.

Apache2::Controller::Auth::OpenID

See Apache2::Controller::Auth::OpenID.

A2C_Auth_OpenID_Login

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.

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  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_Register

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

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_Table

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

A2C_Auth_OpenID_User_Field  uname

Name of username field in table. Default == "uname".

A2C_Auth_OpenID_URL_Field

A2C_Auth_OpenID_URL_Field  openid_url

Name of OpenID URL field in table. Default == "openid_url".

A2C_Auth_OpenID_DBI_Name

A2C_Auth_OpenID_DBI_Name  dbh

Name in $r->pnotes->{a2c} of the connected DBI handle. Default == "dbh".

A2C_Auth_OpenID_Trust_Root

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

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.

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_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.

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#*@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.

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_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.

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

Apache2::Controller

"get_directive" in Apache2::Controller::Methods

Apache2::Controller::Session

Apache2::Module

AUTHOR

Mark Hedges, hedges +(a t)- formdata.biz

COPYRIGHT AND LICENSE

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.