Apache::NNTPGateway

- NAME
- SYNOPSIS
- DESCRIPTION

- ACTIONS

- CONFIGURATION

- Directives

- SECURITY
- BUGS
- Changes

# 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 would 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		NTTPGatewayNewsGroup "newsgroup"
        PerlSetVar		NTTPGateway... (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 allready 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 adjustements 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.

NNTPGatewayStop

       (boolean, I<optional>)

       Tell to completely disable NNTPGateway, useful for temporary maintainance.

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 Disoganized 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).

      =item 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.

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
         acheive the same fonctionnality.
       * 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.

      =item v0.6

       First public release

  # TODO

  * Safe sharing of the NNTP global.

  -      Using an HTML Template system (maybe HTML::Template) instead of hard coded html.

  -      Improving the LANG selection stuff (maybe adding a new configuration directive?)

  -      Improving the C<check_user()> stuff for more security.

  -      more stuff ...

  # 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