INN commit: branches/2.5 (8 files)
INN Commit
rra at isc.org
Tue Sep 29 20:13:55 UTC 2009
Date: Tuesday, September 29, 2009 @ 13:13:55
Author: iulius
Revision: 8640
Mention in Perl and Python hooks that UTF-8 should be used
for reject messages.
Modified:
branches/2.5/doc/pod/hook-perl.pod
branches/2.5/doc/pod/hook-python.pod
branches/2.5/doc/pod/news.pod
branches/2.5/samples/filter_innd.pl
branches/2.5/samples/filter_innd.py
branches/2.5/samples/filter_nnrpd.pl
branches/2.5/samples/nnrpd_auth.pl.in
branches/2.5/samples/nnrpd_auth.py
--------------------------+
doc/pod/hook-perl.pod | 56 ++++++++++++++++++++++++---------------------
doc/pod/hook-python.pod | 18 ++++++++------
doc/pod/news.pod | 3 +-
samples/filter_innd.pl | 10 +++++---
samples/filter_innd.py | 13 ++++++----
samples/filter_nnrpd.pl | 3 +-
samples/nnrpd_auth.pl.in | 4 ++-
samples/nnrpd_auth.py | 5 +++-
8 files changed, 67 insertions(+), 45 deletions(-)
Modified: doc/pod/hook-perl.pod
===================================================================
--- doc/pod/hook-perl.pod 2009-09-29 20:12:25 UTC (rev 8639)
+++ doc/pod/hook-perl.pod 2009-09-29 20:13:55 UTC (rev 8640)
@@ -19,8 +19,7 @@
For Perl filtering support, you need to have Perl S<version 5.004> or newer.
Earlier versions of Perl will fail with a link error at compilation time.
-http://language.perl.com/info/software.html should have the latest Perl
-version.
+L<http://www.perl.com/download.csp> should have the latest Perl version.
To enable Perl support, you have to specify B<--with-perl> when you run
configure. See F<INSTALL> for more information.
@@ -74,7 +73,9 @@
filter_art() is called if Perl filtering is turned on. It receives no
arguments, and should return a single scalar value. That value should be
the empty string to indicate that INN should accept the article, or some
-rejection message to indicate that the article should be rejected.
+rejection message to indicate that the article should be rejected (make sure
+that such a message is properly encoded in UTF-8 so as to comply with the
+NNTP protocol).
filter_art() has access to a global hash named %hdr, which contains all of
the standard headers present in the article and their values. The
@@ -142,26 +143,29 @@
article is accepted. Note that this must be the empty string, not 0 or
undef. Otherwise, the article is rejected, and whatever scalar
filter_art() returns (typically a string) will be taken as the reason why
-the article was rejected. This reason will be returned to the remote peer
-as well as logged to the news logs. (innreport, in its nightly report,
-will summarize the number of articles rejected by the Perl filter and
-include a count of how many articles were rejected with each reason
-string.)
+the article was rejected (make sure that such a message is properly encoded
+in UTF-8 so as to comply with the NNTP protocol). This reason will be
+returned to the remote peer as well as logged to the news logs. (innreport,
+in its nightly report, will summarize the number of articles rejected
+by the Perl filter and include a count of how many articles were rejected
+with each reason string.)
One other type of filtering is also supported. If Perl filtering is
turned on and the Perl function filter_messageid() is defined, that
function will be called for each message ID received from a peer (via
either CHECK or IHAVE). The function receives a single argument, the
message ID, and like filter_art() should return an empty string to accept
-the article or an error string to refuse the article. This function is
-called before any history lookups and for every article offered to innd
-with CHECK or IHAVE (before the actual article is sent). Accordingly, the
-message ID is the only information it has about the article (the %hdr hash
-will be empty). This code would sit in a performance-critical hot path in
-a typical server, and therefore should be as fast as possible, but it can
-do things like refuse articles from certain hosts or cancels for already
-rejected articles (if they follow the $alz convention) without having to
-take the network bandwidth hit of accepting the entire article first.
+the article or an error string to refuse the article (make sure that
+such a message is properly encoded in UTF-8 so as to comply with the
+NNTP protocol). This function is called before any history lookups and
+for every article offered to innd with CHECK or IHAVE (before the actual
+article is sent). Accordingly, the message ID is the only information
+it has about the article (the %hdr hash will be empty). This code would
+sit in a performance-critical hot path in a typical server, and therefore
+should be as fast as possible, but it can do things like refuse articles
+from certain hosts or cancels for already rejected articles (if they
+follow the $alz convention) without having to take the network bandwidth
+hit of accepting the entire article first.
Note that you cannot rely on filter_messageid() being called for every
incoming article; articles sent via TAKETHIS without an earlier CHECK will
@@ -355,8 +359,9 @@
$modify_headers = 1;
If filter_post() returns something other than the empty string, this
-message is normally returned to the client as an error. There are three
-exceptions:
+message is normally returned to the client as an error (make sure that
+such a message is properly encoded in UTF-8 so as to comply with the
+NNTP protocol). There are three exceptions:
=over 4
@@ -477,12 +482,13 @@
authenticate() should return a two or three element array. The first
element is the NNTP response code to return to the client, the second
element is an error string which is passed to the client if the
-response code indicates that the authentication attempt has failed. An
-optional third return element if present will be used to match the
-connection with the users: parameter in access groups and will also be
-the username logged. If this element is absent, the username supplied
-by the client during authentication will be used for matching and
-logging.
+response code indicates that the authentication attempt has failed (make
+sure that such a message is properly encoded in UTF-8 so as to comply
+with the NNTP protocol). An optional third return element if present
+will be used to match the connection with the users: parameter in access
+groups and will also be the username logged. If this element is absent,
+the username supplied by the client during authentication will be used
+for matching and logging.
The NNTP response code should be 281 (authentication successful),
481 (authentication unsuccessful), or 403 (server failure). If the
Modified: doc/pod/hook-python.pod
===================================================================
--- doc/pod/hook-python.pod 2009-09-29 20:12:25 UTC (rev 8639)
+++ doc/pod/hook-python.pod 2009-09-29 20:13:55 UTC (rev 8640)
@@ -120,7 +120,8 @@
If you want to accept an article, return C<None> or an empty string. To
reject, return a non-empty string. The rejection strings will be shown to
local clients and your peers, so keep that in mind when phrasing your
-rejection responses.
+rejection responses and make sure that such a message is properly encoded
+in UTF-8 so as to comply with the NNTP protocol.
=item filter_messageid(I<self>, I<msgid>)
@@ -366,13 +367,14 @@
contains either two or three elements, the first of which is the NNTP
response code. The second is an error string which is passed to the
client if the response code indicates that the authentication attempt
-has failed. This allows a specific error message to be generated by
-the Python script in place of the generic message C<Authentication
-failed>. An optional third return element, if present, will be used to
-match the connection with the I<user> parameter in access groups and
-will also be the username logged. If this element is absent, the
-username supplied by the client during authentication will be used, as
-was the previous behaviour.
+has failed (make sure that such a message is properly encoded in UTF-8
+so as to comply with the NNTP protocol). This allows a specific error
+message to be generated by the Python script in place of the generic
+message C<Authentication failed>. An optional third return element,
+if present, will be used to match the connection with the I<user>
+parameter in access groups and will also be the username logged. If
+this element is absent, the username supplied by the client during
+authentication will be used, as was the previous behaviour.
The I<python_access> parameter (described below) is new; it allows the
dynamic generation of an access group of an incoming connection using
Modified: doc/pod/news.pod
===================================================================
--- doc/pod/news.pod 2009-09-29 20:12:25 UTC (rev 8639)
+++ doc/pod/news.pod 2009-09-29 20:13:55 UTC (rev 8640)
@@ -133,7 +133,8 @@
As UTF-8 is the default character set in S<RFC 3977>, C<ctlinnd pause>,
C<ctlinnd readers>, C<ctlinnd reject>, C<ctlinnd reserve>, C<ctlinnd throttle>
and C<nnrpd -r> commands now require the given reason to be encoded in UTF-8,
-so that it can be properly sent to news readers.
+so that it can be properly sent to news readers. The creator's name given
+to C<ctlinnd newgroup> is also expected to be encoded in UTF-8.
=item *
Modified: samples/filter_innd.pl
===================================================================
--- samples/filter_innd.pl 2009-09-29 20:12:25 UTC (rev 8639)
+++ samples/filter_innd.pl 2009-09-29 20:13:55 UTC (rev 8640)
@@ -22,7 +22,9 @@
# global associative array `%hdr.' If it returns the empty
# string ("") then the article is accepted. If it returns any
# non-null string value, then the article is rejected and the
-# returned string value is logged as the reason why.
+# returned string value is logged as the reason why (make sure
+# that such a message is properly encoded in UTF-8 so as to comply
+# with the NNTP protocol).
#
# The standard headers are:
#
@@ -56,8 +58,10 @@
# This routine is called when each article (in streaming
# mode only) is checked to see if INN wants to accept the
# article. If it returns the empty string, the article
-# is accepted. If it returns a non-empty value, the
-# article is refused. It is called with one argument,
+# is accepted. If it returns a non-empty value, the
+# article is refused (make sure that such a message is
+# properly encoded in UTF-8 so as to comply with the
+# NNTP protocol). It is called with one argument,
# the message-id to check.
Modified: samples/filter_innd.py
===================================================================
--- samples/filter_innd.py 2009-09-29 20:12:25 UTC (rev 8639)
+++ samples/filter_innd.py 2009-09-29 20:13:55 UTC (rev 8640)
@@ -145,10 +145,12 @@
This method interacts with the IHAVE and CHECK NNTP commands.
If you return a non-empty string here, the offered article
will be refused before you ever have to waste any bandwidth
- looking at it. This is not foolproof, so you should do your
- ID checks both here and in filter_art. (TAKETHIS does not
- offer the ID for examination, and a TAKETHIS isn't always
- preceded by a CHECK.)
+ looking at it (make sure that such a message is properly
+ encoded in UTF-8 so as to comply with the NNTP protocol).
+ This is not foolproof, so you should do your ID checks both
+ here and in filter_art. (TAKETHIS does not offer the ID
+ for examination, and a TAKETHIS isn't always preceded
+ by a CHECK.)
"""
return "" # Deactivate the samples.
@@ -192,7 +194,8 @@
want to reject, return a non-empty string. The rejection
string will appear in transfer and posting response banners,
and local posters will see them if their messages are
- rejected.
+ rejected (make sure that such a response is properly encoded
+ in UTF-8 so as to comply with the NNTP protocol).
"""
return "" # Deactivate the samples.
Modified: samples/filter_nnrpd.pl
===================================================================
--- samples/filter_nnrpd.pl 2009-09-29 20:12:25 UTC (rev 8639)
+++ samples/filter_nnrpd.pl 2009-09-29 20:13:55 UTC (rev 8640)
@@ -10,7 +10,8 @@
# posting. It has access to the headers of the article via the associative
# array `%hdr'. If it returns a null string then the article is accepted
# for posting. A non-null string rejects it, and the value returned is used
-# in the rejection message.
+# in the rejection message (make sure that such a message is properly encoded
+# in UTF-8 so as to comply with the NNTP protocol).
#
#
Modified: samples/nnrpd_auth.pl.in
===================================================================
--- samples/nnrpd_auth.pl.in 2009-09-29 20:12:25 UTC (rev 8639)
+++ samples/nnrpd_auth.pl.in 2009-09-29 20:13:55 UTC (rev 8640)
@@ -13,7 +13,9 @@
##
## 1) NNTP response code. Should be one of the codes from %authcodes
## below to not risk violating the protocol.
-## 2) An error string to be passed to the client.
+## 2) An error string to be passed to the client (make sure that
+## such a message is properly encoded in UTF-8 so as to comply with the
+## NNTP protocol).
## Both elements are required. If there is a problem, nnrpd will die
## and syslog the exact error.
Modified: samples/nnrpd_auth.py
===================================================================
--- samples/nnrpd_auth.py 2009-09-29 20:12:25 UTC (rev 8639)
+++ samples/nnrpd_auth.py 2009-09-29 20:13:55 UTC (rev 8640)
@@ -20,7 +20,10 @@
## readers.conf. Returns a response
## code, an error string and an
## optional string to appear in the
-## logs as the username.
+## logs as the username (make sure that
+## such a message is properly encoded
+## in UTF-8 so as to comply with the
+## NNTP protocol).
## authen_close() - Called on nnrpd termination. Save
## your state variables or close a database
## connection. May be omitted.
More information about the inn-committers
mailing list