Heddy Boubaker > Apache-NNTPGateway > Apache::NNTPGateway

Download:
Apache-NNTPGateway-0.9.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.9   Source  

NAME ^

Apache::NNTPGateway - A NNTP interface (Usenet newsgroups) for mod_perl enabled Apache web server.

SYNOPSIS ^

 You must be using mod_perl, see http://perl.apache.org/ for details.

 For  the  correct work   your  apache configuration  should  contain   apache
 directives look like these:

 In httpd.conf (or any other apache configuration file):

 <Location "/path/to/newsgroup">
    SetHandler          perl-script
    PerlHandler         Apache::NNTPGateway
    PerlSetVar          NNTPGatewayNewsGroup "newsgroup"
    PerlSetVar          NNTPGateway... (see L<CONFIGURATION> Directives)
 </Location>

DESCRIPTION ^

 This module implements a per group interface to NNTP (Usenet) News-Groups, it
 allow users to   list,    read, post, followup   ...  articles   in a   given
 newsgroup/newsserver  depending of configuration.  This  is not a replacement
 for a real powerful newsreader client but just pretend to be a simple, useful
 mapping of some news articles into a web space.

ACTIONS

 Here is the list of all actions that can be performed on the current newsgroup.
list
  List articles,   all  articles from   the current newsgroup  or  only unread
  articles if the user/client already did a B<catchup>.
catchup
  Mark all current articles as read. This use a Cookie.
last
  Read the last article available from the newsserver.
read
  Read article by ID.
followup
  Post a followup to an article.
post
  Post an new article to the current newsgroup.

CONFIGURATION ^

  Except some very few  optional adjustments in  the module source itself all
  configuration is done with B<PerlSetVar> directives in Apache configurations
  files.

Directives

 All  following features of    this PerlHandler, will   be  set in the  apache
 configuration files. For this you can use PerlSetVar apache directive.
NNTPGatewayNewsGroup
 (string, B<mandatory>)

 The newsgroup used  for  the current NNTPGateway  location. Not  setting this
 will make NNTPGateway fail.
NNTPGatewayGroupDescription
 (string, I<optional>)

 Short description (1 or 2 lines) of what this newsgroup is for/contain.
NNTPGatewayStop
 (boolean, I<optional>)

 Tell to completely disable NNTPGateway, useful for temporary maintenance.
NNTPGatewayDefaultAction
 (ACTION name, I<optional>) Default value: B<last>

 Default action used when nothing specified. (see L<ACTIONS>).
NNTPGatewayNewsServer
 (string, I<optional>)

  When using correctly  configured perl modules B<Net::Domain>, B<Net::Config>
  on  a correctly  configured  system this should   not be changed, in  theory
  NNTPGateway could   be able to  handle  multiples  news server   but this is
  greatly nor  recommended (see L<BUGS>) unless  you really  know what you are
  doing.
NNTPGatewayOrganization
  (string, B<recommended>) Default value: B<The Disorganized Corp>

  Set the Organization header when posting articles.
NNTPGatewayTitle
  (string, I<optional>)

  Title displayed in NNTPGateway pages.
NNTPGatewayStyleSheet
  (string, I<optional>)

  Set the style sheet used  in NNTPGateway pages,  or none. There are some few
  classes in the  generated HTML, check  the source to use  them in your style
  sheet.
NNTPGatewayAnonymousPostAllowed
  (boolean, I<optional>) Default value: B<off>

  Allow anonymous posting in the current group.
NNTPGatewayAnonymousPosters
  (list, I<optional>) Default value: B<anonymous=Anonymous>

  A list of pair email=Name that could be used for anonymous
  posts. I'm B<Absolutely> not responsible for any abuse of this
  feature, this is up to the webmaster to control it's usage.

  Ex:
  C<PerlSetVar NNTPGatewayAnonymousPosters "anon=The Unknown Soldier,president=The Big Boss"> 
NNTPGatewayNonLocalPostOk
  (boolean, I<optional>) Default value: B<off>

  Allow user who do not have local (to the same web server machine -
  checked with getpwnam) login account to post articles, in B<non>
  anonymous post mode the users should have been identified themselves
  anyway (with identd or server auth).
NNTPGatewayUsersNamesCaseInsensitive
  (boolean, I<optional>) Default value: B<off>

  Check users names in a case insensitive manner.
NNTPGatewayDisabledActions
  (ACTIONS list, I<optional>) Default value: B<none> 

  List of L<ACTIONS> that are B<not> allowed to be performed by users for
  the current config. (see L<ACTIONS>).
NNTPGatewayTemplatesDir
  (string, L<optional>) Default value: B<lib/templates/NNTPGateway/>

  ServerRoot relative Directory where to find HTML templates files (not yet Implemented). 
NNTPGatewayDebug
  (boolean, I<optional>) Default value: B<off>

  Set this to debug NNTPGateway. 

SECURITY ^

  If   you  B<allow>  Anonymous posting  absolutely   no  security  checks are
  performed unless you protect access to the  Location this handler is located
  on, but that is not the job of this module.

  If  you B<deny>  Anonymous posting, the   handler will check B<remote_ident>
  (via Identd) or B<remote_user> and will check  if they are valid username by
  checking C<getpwnam()> (a list   of some generic  usernames such   as: root,
  anonymous  ...  are not   considered  as valid  too, even  if  they are), if
  directive B<NNTPGatewayNonLocalPostOk>  had not  been  set, if they are  not
  they are rejected, if they  are they could post and  the From header will be
  set to that username.  That is the only security  check the handler will do,
  it is up to other apaches modules to correctly protect  the Location and set
  valid usernames (enable identd or loggin via AuthNIS or anything else).

  Furthermore the webmaster could   disable the use   of some actions such  as
  post, followup ...

BUGS ^

 The connection to the nntp server is handled in a global variable so that the
 connection is common to all requests in the current apache child process. Due
 to that,  when the module is  used with 2  differents configs (in 2 <Location
 xxx>) setting  2 differents newsservers  and that 2 requests  are made in the
 same child with these 2 configs (or more) ... the second request could re-use
 a NNTP connection (open during the 1st request)  already open to the B<first>
 server. I do not  want to make the nntp  object a local variable, because the
 connection is a long process ... But anyway, I have some  few ideas of how to
 solve the  problem, but as  I am lazy and  my configuration do not  have this
 problem I am waiting for pressure from eventual module users ...;-)

Changes ^

v0.9
 * Article id or subject added to title in read.
 * More CSS classes everywhere... read the sources.
 * use Apache::Log qw(); to access to log functions.
 * Makefile.PL improved to really check used modules versions.
 * Call  Net::Cmd functions in a  clean manner to make perl  5.6 happy (end of
   that Bareword "CMD_ERROR" install bug).
v0.8
 * Cookie domain better handled for catchup.
 * NNTPGatewayNewsGroupTest   removed.  Set  up    a  new  Location  and   set
   NNTPGatewayNewsGroup to  the test group and  NNTPGatewayDebug on to achieve
   the same functionality.
 * Some       more       directives   to       control        users   checking
   (NNTPGatewayUsersNamesCaseInsensitive, NNTPGatewayNonLocalPostOk).
 * Some handling of Cache-Control.
 * Made this module ready for my first CPAN contribution ;-)
 ** Cleaning source code.
 ** Cleaning Documentation.
 ** CPAN  Enabled distrib (Makefile.PL,   .tar.gz dist,  README file, CPAN  ID
    ...).
v0.7
 * The configuration directive B<NNTPGatewayCatchupCookieName> do not exists anymore.
 * Disconnections to news server start to be better handled.
v0.6
 First public release

TODO ^

THANKS ^

 Thanks a lot to these people for they help:

SEE ALSO ^

 perl(1), mod_perl(3), Apache(3), Net::NNTP(3), Net::Domain(3),
 Net::Config(3), rfc9771, getpwnam(3)

COPYRIGHT ^

 The application and accompanying modules are Copyright  CENA Toulouse.  It is
 free software and can be used, copied and  redistributed at the same terms as
 perl itself.

AUTHOR ^

 heddy Boubaker <boubaker@cpan.org>

 Home page:
 http://www.tls.cena.fr/~boubaker/WWW/Apache-NNTPGateway.shtml
syntax highlighting: