1. Upgrade from previous version
2. New installation
3. Configuration of config.inc.php
4. Configuration of newsgroups.lst

To upgrade PHP News Reader from the previous version, please follow the following procedure:

1. Backup config.inc.php and newsgroups.lst
2. Download the latest version of PHP News Reader
3. Unpack the latest version of PHP News Reader and over-write the existing installation
4. Restore config.inc.php and newsgroups.lst
5. Reading the release notes in latest version, and modify config.inc.php or newsgroups.lst if appliable

The installation of PHP News Reader is quite simple.
You can download the latest source of PHP News Reader from:

http://pnews.sourceforge.net/

The source is packaged in two different format, one is tar+gzip (tgz), and the other is zip.
Please download your preferred format from SourceForge.

After downloaded the source, extract the source tarball in the directory where your server want to provide News service.

Supposed the DocumentRoot of your web is /usr/local/apache/htdocs/,

# cd  /usr/local/apache/htdocs/
# tar  zxvf  pnews263.tgz

or if you prefer the zip format,

# cd  /usr/local/apache/htdocs/
# unzip  pnews263.zip

You may want to change the directory name, for example:

# mv  pnews263  pnews

The configuration of PHP News Reader contains two files, "config.inc.php" and "newsgroups.lst"
You can refer the template of both files in the subdirectory "examples/".

The config.inc.php should be put in the root directory of PHP News Reader, (such as /usr/local/apache/htdocs/pnews/)

You can copy the file from the examples/ directory as a reference.

# cd  /usr/local/apache/htdocs/pnews/
# cp  examples/config.inc.php   .

The default location of "newsgroups.lst" is the same as config.inc.php,
but this can be changed by modifying the setting in "config.inc.php".

If you use the default setting, you can also copy the file from examples/ subdirectory.

# cp  examples/newsgroups.lst   .

Now, you can begin the editing of these two files.

If you finished the editing of both files, you can then use your favorite browser to access your new born Web News,
for example:

http://your.web.server/pnews/

Note that you should have started your web server and make sure that PHP module is enabled.

If you have any problems, or find any errors in this document,
please send your comments to cdsheen@users.sourceforge.net, any suggestion is appreciated.

config.inc.php controls how PHP News Reader works.

You can find the sample of config.inc.php in the "example/" directory.

All configuration applies PHP syntax and should be in the form of:

$CFG["foo"] = "bar";

Each setting is well-documented in the example file.

The configuration contains 3 sections:

Section 1 - Authentication
Section 2 - Contents
Section 3 - Languages

Section 1 - Authetication

This section controls how you authenticate your users.

$CFG["auth_type"]

Specify the authentication type (REQUIRED)

"required" - authentication is required to access the while system
"optional" - authentication is only required for posting and forwarding
"open" - authentication is not needed

$CFG["auth_prompt"]

Specify the style of authentication prompt (default: "form") (used only if $CFG["auth_type"] is not 'open')

"http" - authenticated user via HTTP login window
"form" - authenticated user via HTML login form (default and is recommended)
"cas" - authenticated user via CAS (with version >= 2.3.0)
"other" - authenticated user via third party system (ex: phpBB), (with version >= 2.5.6)

$CFG["global_readonly"]

Prohibits the posting and forwarding of articles, even if user performs login. (default: false)

This is global setting for all categories, if you want only one or two categories to be readonly, set it in newsgroups.lst

This setting first appeared in the v2.5.0 of PHP News Reader

It is to replace $CFG["post_restriction"] in the previous version.

$CFG["auth_http_realm"]

Specify the realm used in http authentication prompt (REQUIRED if $CFG["auth_prompt"] is 'http')

This realm string will be displayed in the HTTP login window.

$CFG["auth_method"]

Specify the authentication method (REQUIRED if $CFG["auth_type"] != "open" )

"ldap" - authenticated via LDAP server,
"pop3" - authenticated via POP3 server,
"pop3s" - authenticated via POP3S (POP3 over SSL) server (with version >= 2.4.1),
"ftp" - authenticated via FTP server,
"ftps" - authenticated via FTPS (FTP over SSL) server (with version >= 2.4.1),
"mail" - authenticated via multiple POP3/POP3S server,
"mysql" - authenticated via MySQL database,
"pgsql" - authenticated via PostgreSQL database,
"nntp" - authenticated via NNTP News Server (with version >= 2.2.1),
"nntps" - authenticated via NNTPS (NNTP over SSL) News Server (with version >= 2.4.0),
"cas" - authenticated via CAS (with version >= 2.3.0),
"phpbb" - authenticated via phpBB (with version >= 2.5.6),
"user" - authenticated via your self-defined method,

Notice for CAS users:

If you use CAS to authenticate your users,
both $CFG["auth_prompt"] and $CFG["auth_method"] should set to 'cas'.
Besides this, you should first install phpCAS in your PHP include_path or CAS/ for this method to run well.
You can download phpCAS from the following place:
    http://esup-phpcas.sourceforge.net

$CFG["auth_organization"]

Specify the organization of authentication source (REQUIRED if $CFG["auth_type"] is not 'open')

This is the organization name of your authentication source.

$CFG["auth_registration_info"]

Prompt users about how to get an account (default: "")
This message will be displayed on login (FORM) or logout (HTTP) windows

$CFG["auth_user_module"]

Specify user-defined authentication module location (REQUIRED if $CFG["auth_method"] is 'user')
You should implement a function with this prototype in your module:

function check_user_password( $username, $password )

This function should verify the correctness of $username and $password,
and then return something for granting access, null otherwise.

There's a sample authentication module in auth/sample.inc.php. You can begin the work from here.

$CFG["auth_deny_users"]

Specify users (as an array) to be denied from login (defaults: empty)

$CFG["auth_deny_users"] = array( 'guest', 'baduser' );

This setting first appeared in the v2.6.2 of PHP News Reader

LDAP authentication parameters (REQUIRED if $CFG["auth_method"] is 'ldap')

$CFG["ldap_server"]

LDAP server address ( address:port ), default port is 189

$CFG["ldap_server"] = "ldap.domain.org:189";

$CFG["ldap_dn"]

LDAP distinguish name

$CFG["ldap_dn"] = "ou=members, o=root";

$CFG["ldap_bind_rdn"]

LDAP bind RDN, %u is substituted by username (default: "%u")

$CFG["ldap_bind_rdn"] = "cn=%u,ou=members,o=root";

$CFG["ldap_bind_pwd"]

LDAP bind password, %p is substituted by password (default: "%p")

$CFG["ldap_bind_pwd"] = "%p";

$CFG["ldap_filter"]

LDAP search filter (default: "(cn=%u)")

$CFG["ldap_filter"] = "(&(cn=%u)(accountStatus=1)(MailStatus=1))";

$CFG["ldap_variable"]

The attributes extract from this LDAP search for later use (default: null)
( %u can not be used here )

$CFG["ldap_variable"] = array( "%e" => "Email", "%n" => "Fullname" );

In the above setting, the ldap attribure "Email" will be extracted from this search,
and be putted in variable %e for later use

FTP authentication parameters (REQUIRED if $CFG["auth_method"] is 'ftp')

$CFG["ftp_server"]

FTP server address ( address:port ), default port is 21

$CFG["ftp_server"] = "ftp.domain.org";

$CFG["ftp_deny"]

The user list which is denied for FTP authentication
(default: array( 'anonymous', 'guest', 'ftp' ) )

$CFG["ftp_deny"] = array( 'anonymous', 'guest', 'ftp', 'root' );

FTPS (FTP over SSL) authentication parameters (REQUIRED if $CFG["auth_method"] is 'ftps')

$CFG["ftps_server"]

FTPS server address ( address:port ), default port is 990

$CFG["ftps_server"] = "ftps.domain.org";

$CFG["ftps_deny"]

The user list which is denied for FTPS authentication
(default: array( 'anonymous', 'guest', 'ftp' ) )

$CFG["ftps_deny"] = array( 'anonymous', 'guest', 'ftp', 'root' );

POP3 authentication parameters (REQUIRED if $CFG["auth_method"] is 'pop3')

$CFG["pop3_server"]

POP3 server address ( address:port ), default port is 110

$CFG["pop3_server"] = "pop3.domain.org";

This module first appeared in the v2.4.1 of PHP News Reader

You must enable OpenSSL extension in PHP, and the PHP should be v4.3.0 or greater

POP3S (POP3 over SSL) authentication parameters (REQUIRED if $CFG["auth_method"] is 'pop3s')

$CFG["pop3s_server"]

POP3S server address ( address:port ), default port is 995

$CFG["pop3s_server"] = "pop3s.domain.org";

This module first appeared in the v2.4.1 of PHP News Reader

You must enable OpenSSL extension in PHP, and the PHP should be v4.3.0 or greater

Mail authentication parameters (REQUIRED if $CFG["auth_method"] is 'mail')

$CFG["pop3_mapping"]

the mapping from E-Mail to POP3/POP3S server address

User should login with full E-Mail address, and this module will use different POP3 server to authenticated user based on the domain part of supplied E-Mail

The following example will use "pop3.foobar.com" to authenticate "xxx@foobar.com", and use "pop3.domain.org" to authenticate "yyy@mail.domain.org".

$CFG["pop3_mapping"] = array( "@foobar.com" => "pop3.foobar.com",
                                                    "@mail.domain.org" => "pop3.domain.org" );

Since v2.5.0, this module support both pop3 and pop3s.
You can assign the server in URI syntax as follows:

$CFG["pop3_mapping"] = array( "@foobar.com" => "pop3.foobar.com",
                                                    "@pop3s.domain.org" => "pop3s://pop3s.domain.org/",                                                     ".bbs@pop3s.bbs.org" => "pop3s://pop3s.bbs.org/",                                                     "@pop3.domain.org" => "pop3://pop3.domain.org:110/" );

You must enable OpenSSL extension in PHP, and the PHP should be v4.3.0 or greater

$CFG["domain_select"]

Show domain-list selector in login dialog (default: true)

Note that domain-list selector only appear if $CFG["auth_prompt"] is 'form'

This setting first appeared in the v2.5.0 of PHP News Reader

NNTP authentication parameters (REQUIRED if $CFG["auth_method"] is 'nntp')

$CFG["auth_nntp_server"]

News (NNTP) server address and port ( address:port ), default port is 119

$CFG["auth_nntp_server"] = "news.domain.org";

Note that this option only deal with the authentication of PHP News Reader, it has nothing to do with the authentication perform by news server. Add auth directive to your newsgroups.lst if your news server requires authentication.

This setting first appeared in the v2.2.0 of PHP News Reader

NNTPS (NNTP over SSL) authentication parameters (REQUIRED if $CFG["auth_method"] is 'nntps')

$CFG["auth_nntps_server"]

News (NNTPS) server address and port ( address:port ), default port is 563

$CFG["auth_nntps_server"] = "nntps.domain.org";

Note that this option only deal with the authentication of PHP News Reader, it has nothing to do with the authentication perform by news server. Add auth directive to your newsgroups.lst if your news server requires authentication.

This module first appeared in the v2.4.0 of PHP News Reader

You must enable OpenSSL extension in PHP, and the PHP should be v4.3.0 or greater

CAS authentication parameters (REQUIRED if $CFG["auth_method"] is 'cas')

$CFG["auth_cas_server"]

CAS server address and port ( address:port ), the port part should not be omitted.

$CFG["auth_cas_server"] = "cas.domain.org:1234";

$CFG["auth_cas_base_uri"]

CAS Server Base URI

$CFG["auth_cas_base_uri"] = "cas";

$CFG["auth_cas_debug"]

The filename for outputing debug log, or false to turn off debug mode (default: false)

$CFG["auth_cas_debug"] = "/tmp/phpcas.log";

The above settings first appeared in the v2.3.0 of PHP News Reader

phpBB authentication module paramenters (REQUIRED if $CFG["auth_method"] is 'phpbb')

$CFG["auth_phpbb_url_base"]

The base URL of your phpBB installation

$CFG["auth_phpbb_url_base"] = "http://phpbb.foobar.com/";

$CFG["auth_phpbb_path"]

The relative path of absolute path of your phpBB installation

$CFG["auth_phpbb_path"] = "../phpbb/";

With 'phpbb' as authentication module, you can utilize the session if you already login phpBB.

Notice: Your $CFG["auth_prompt"] must be 'other' if you want to use phpBB authtication module.

The above settings first appeared in the v2.5.6 of PHP News Reader

MySQL/PostgreSQL Database authentication parameters

(REQUIRED if $CFG["auth_method"] is 'mysql' or 'pgsql' )

These parameters are used in both MySQL and PostgreSQL database authentication module.

$CFG["db_server"]

The database server address (address:port)

$CFG["db_name"]

The database name

$CFG["db_username"]

The username used to connect database

$CFG["db_password"]

The password used to connect database

$CFG["db_table"]

The table name for user information

$CFG["db_field_username"]

The field name for username

$CFG["db_field_password"]

The field name for password

$CFG["db_password_crypt"]

The password hashing method (default: false - cleartext)
current supported hashing are: "md5", "crypt", or false

If your password does not saved as cleartext in the database,
this parameter defined the hashing method used to hash password.

The support for database authentication module make it easy to integrate with many PHP products.

For example, to enable PHP News Reader authenticating with the existing users of your phpBB 2.0, use the following settings:

$CFG["db_server"] = "database.domain.org";
$CFG["db_name"] = "phpbb";
$CFG["db_username"] = "db_user";
$CFG["db_password"] = "db_pass";
$CFG["db_table"] = "phpbb_users";
$CFG["db_field_username"] = "username";
$CFG["db_field_password"] = "user_password";
$CFG["db_password_crypt"] = "md5";
$CFG["db_variable"] = array( "%e" => "user_email" );

Since v2.5.6, you can use 'phpbb' as $CFG["auth_method"] for seamless integration with sessions of phpBB. With 'phpbb' as authentication module, you can utilize the session if you already login phpBB.

$CFG["auth_expire_time"]

After this time in seconds, authentication is expired
And login again is required. Zero means never expire (default: 3600 seconds)

$CFG["auth_user_fullname]

The full name of authenticated user (default: "%u")

The default is the username supplied for authentication

You can customize this based on the variable defined in the [db_variable] or [ldap_variable]

For example,

$CFG["auth_user_fullname"] = "%n";

$CFG["auth_user_email"]

The E-Mail of authenticated user (REQUIRED if $CFG["auth_method"] is not 'mail')

The %u will be substituted by the username enter by authentication session

Other variables are defined in the [db_variable] or [ldap_variable]

Note: if you use 'mail' as your auth_method, $CFG["auth_user_email"] will always been set to user's E-Mail.

$CFG["log"]

Enable access log (default: false - no log)

$CFG["log"] = "/var/log/pnews.log";

You need to create this file with write permission granted to the user running httpd

$CFG["log_level"]

Log verbose level (default: 3)

0 - no log
1 - log only post/reply/xpost/forward/delete actions.
2 - log all actions for authenticated users.
3 - log all actions for all users.

$CFG["log_level"] = 2;

This setting first appeared in the v2.5.0 of PHP News Reader

$CFG["debug_level"]

NNTP debug verbose level (default: 0)

0 - Turn off NNTP debug information
1 - NNTP debug information will be embeded in HTML comments
2 - NNTP debug information will be shown inline with HTML page

$CFG["debug_level"] = 1;

This setting first appeared in the v2.5.2 of PHP News Reader

 

---

Section 2 - Contents

This section configure the contents appeared in this reader

$CFG["url_base"]

Specify the base URL of your PHP News Reader installation (REQUIRED)

Prior to v2.2.1, this setting is only REQUIRED if $CFG["url_rewrite"] is true

After v2.2.2, this setting is always REQUIRED

This setting first appeared in the v2.2.0 of PHP News Reader

$CFG["url_rewrite"]

Enable or disable the URL rewrite function (default: false)

Read more about URL rewriting by clicking here.

You should enable Apache mod_rewrite module and AllowOverride for per-directory access control

And the directive AccessFileName must be .htaccess,
otherwise you should change it, or rename .htaccess to match your setting.

For more information about mod_rewrite, visit http://httpd.apache.org/docs/mod/mod_rewrite.html for details.

This setting first appeared in the v2.2.0 of PHP News Reader

$CFG["https_login"]

Whether to use SSL(HTTPS) after authentication (default: false)

This setting first appeared in the v2.2.2 of PHP News Reader

$CFG["style_sheet"]

Setting the style sheet used for all html (default: "standard.css")

This setting first appeared in the v2.2.1 of PHP News Reader

After v2.2.4, the configured style sheet should be placed in the css/ subdirectory.

$CFG["title"]

The title for this webnews, no HTML tag is allowed here. (default: "Webnews")

$CFG["banner"]

The banner text or images, HTML tags are allowed here. (default: false)

$CFG["banner"] = "<img src=banner.jpg>";

$CFG["html_header"]

The file to be included as page header (default: false)

$CFG["html_header"] = "header.htm";

If $CFG["html_header"] is a valid file which can be included,
then the $CFG["banner"] setting is ignored!

This setting first appeared in the v2.5.7 of PHP News Reader

$CFG['html_header'] can be a PHP script since v2.6.1 of PHP News Reader

$CFG["html_footer"]

The file to be included as page footer (default: false)

$CFG["html_footer"] = "footer.htm";

This setting first appeared in the v2.5.7 of PHP News Reader

$CFG['html_footer'] can be a PHP script since v2.6.1 of PHP News Reader

$CFG["group_list"]

The group definition that show on this Web News

You should get a copy from examples/newsgroups.lst (default: "newsgroups.lst")

$CFG["confirm_post"]

The message prompted to confirm the posting (post/reply/crosspost) (default: false)

$CFG["confirm_post"] = "Really post the message ?";

This setting first appeared in the v2.6.0 of PHP News Reader

$CFG["confirm_forward"]

The message prompted to confirm the forwarding (default: false)

$CFG["confirm_forward"] = "Really forward the message ?";

This setting first appeared in the v2.6.0 of PHP News Reader

$CFG["magic_tag"]

Use magic tag to indicate the visit state of newsgroup (default: false)

While magic_tag is true, the url for each newsgroup will become:

http://webnews.host/indexing.php?server=*&group=news.test&magic=23479

or while $CFG["url_rewrite"] is true,

http://webnews.host/group//news.help?23479

PHP News Reader use the above magic number in red to indicate that the group has been visited by user (with the help of browser's history).

The default is false. If you do like this feature, you can turn it on by:

$CFG["magic_tag"] = true;

This setting first appeared in the v2.2.4 of PHP News Reader

The default value of $CFG["magic_tag"] has been changed to false since v2.4.1 of PHP News Reader

$CFG["cache_dir"]

Enable cache mechanism of indexing data (default: false)

Turning on the cache mechanism will relief the loading of news server, and speed up the indexing process for large groups.

To enable caching, set this to the directory of cache data.
You should grant write permission on this directory to the user running PHP.

This function is used to cache indexing data (article number list) for each group, it does not cache the contents of articles.

Since v2.6.1, attachment is also cached if you enable $CFG["cache_dir"].

This setting first appeared in the v2.4.0 of PHP News Reader

$CFG["thread_enable"]

Enable threading (default: false)

We only support the simplest type of threading now.
Articles in the same thread will be listed in the bottum of the page when you view one of the message in the thread.

To enable threading, you must enable the cache mechanism by setting $CFG["cache_dir"] and specify the correct $CFG["thread_db_format"]. The directroy specified by $CFG["cache_dir"] will be used for storing threading data.

You must install the PHP DBA extension in PHP to use this feature.

If you enable threading, you may need to run 'clear-cache.php' regularly.

This is because that PHP News Reader store information of all articles in cache and thread database. But, PHP News Reader does not clear the expired articles from these database, which may cause these database too large after a long time. So we suggest running 'clear-cache.php' script once a week or once a month, for example:

# php clear-cache.php /usr/local/apache/htdocs/pnews/config.inc.php

Please specify the location of config.inc.php as the first command line argument.
And the process must have the permission to delete files under $CFG["cache_dir"].

You may want to put this script in your crontab for convenience.

This setting first appeared in the v2.6.0 of PHP News Reader

$CFG["thread_db_format"]

Setting the dba handler used for storing threading data

You must install the PHP DBA extension in PHP to use this feature.

The handler, depends on your DBA extension, may be dbm, ndbm, gdbm, db2, db3 or db4.
Make sure that you already enable the handler in your DBA extension.

The default value for $CFG["thread_db_format"] is :

'db3'  if  PHP < 4.3.2,
'db4'  if  PHP >= 4.3.2 .

This setting first appeared in the v2.6.0 of PHP News Reader

$CFG["image_inline"]

The uuencoded image attachment will be shown inline along with article (default: true)

This setting first appeared in the v2.5.1 of PHP News Reader

$CFG["allow_attach_file"]

Setting the allowed attachment(s) when posting article (default: 2)

This setting first appeared in the v2.5.0 of PHP News Reader

$CFG["group_sorting"]

sort newsgroups in each category (default: false)

$CFG["show_group_description"]

Show newsgroups description or not (default: true)

$CFG["hide_email"]

Enable the Anti-Spam feature, the E-Mail will be encoded by JavaScript (default: true)

For example, the E-Mail address "dada@pnews.com.tw" will be encoded as:

<script language="JavaScript">
    document.write( "dada" + "&#64;" + "pnews&#46;com&#46;tw" );
</script>

This makes it difficult for Spamlist collector to automatically obtain email addresses from PHP News Reader

This setting first appeared in the v2.5.1 of PHP News Reader

$CFG["email_editing"]

Allow editing of E-Mail address when posting article (default: true)

This setting first appeared in the v2.3.0 of PHP News Reader

$CFG["articles_per_page"]

Setting the number of articles shown per page (default: 20)

This setting first appeared in the v2.2.0 of PHP News Reader

$CFG["show_latest_top"]

Show the latest article as the top item (default: true)

This setting first appeared in the v2.5.7 of PHP News Reader
It is to replace $CFG["article_order_reverse"] in v2.2.0 - v2.3.1 and $CFG["show_newest_top"] in v2.4.0 - v2.5.6

This setting is deprecated since v2.6.0 of PHP News Reader.

$CFG["show_article_popup"]

Controlling the article to show in popup window or not (default: false)

This setting first appeared in the v2.2.0 of PHP News Reader

This setting is deprecated since v2.6.1 of PHP News Reader.

$CFG["filter_ansi_color"]

Setting this option to true will cause filtering of ANSI coloring code from article (default: true)

This setting first appeared in the v2.2.0 of PHP News Reader

$CFG["organization"]

The organization name of this site (default: "News Server")

$CFG["post_signature"]

The signature which been appended at each posted article (default: "")

Note: This is NOT a per-user setting!

$CFG["meta_description"]

The META description embeded in HTML header (default: "PHP News Server")

This setting first appeared in the v2.5.3 of PHP News Reader

$CFG["meta_keywords"]

The META keywords embeded in HTML header (default: "news,pnews,webnews,nntp")

This setting first appeared in the v2.5.3 of PHP News Reader

$CFG["show_sourceforge_logo"]

Show sourceforge logo (default: false)

$CFG["language_switch"]

Show language switch or not (default: true)

$CFG["time_format"]

The format used to displaying time (default: "%Y/%m/%d %H:%M:%S")

$CFG["time_format"] = "%Y/%m/%d %H:%M:%S";

The conversion specifiers used in the format string is the same as PHP strftime().
You can refer http://www.php.net/manual/en/function.strftime.php for details.

$CFG["links"]

The links referring to other pages. (default: null)

This is an associate array, the key is the link text and the value is the url.

$CFG["links"] = array( "Back Home" => "../index.php", "Tech News" => "http://foo.bar/technews/" );

---

Section 3 - Languages

This section controls the setting about languages and charsets

Natively supported languages and the charsets are:

Language	Locale	Charset
English	en	US-ASCII
Tranditional Chinese	zh-tw	BIG5
Simplified Chinese	zh-cn	GB2312
Unicode	Unicode	UTF-8 (default)
Français	fr	ISO-8859-1
Finnish	fi	ISO-8859-1
German	de	ISO-8859-1
Italiano	it	ISO-8859-1
Slovak	sk	ISO-8859-2

$CFG["interface_language"]

The language setting of interface ( "en", "zh-tw", "zh-cn", "unicode", "fr", "fi", "de", "it", "sk" )
(default: "en" )

This setting first appeared in the v2.3.0 of PHP News Reader
If not set in v2.3.0 or later, the default language used in interface is "en" - English

Notice: the original $CFG["charset"]["interface"] is deprecated since v2.3.0,
please use $CFG["interface_language"] instead

$CFG["charset"]["config"]

The charset setting used in this config.inc.php

$CFG["charset"]["grouplst"]

The charset setting used in newsgroups.lst

$CFG["charset"]["database"]

The charset setting used in database or LDAP.
If you do not enable database or ldap authentication module, this setting will be ignored

Notice: the original $CFG["language"] section is deprecated since v2.1.0,
please use $CFG["charset"] section instead

newsgroups.lst list the news server / news groups to access

The syntax of this file is different from that of config.inc.php

All lines begin with the # is considered as comments

The newsgroups of PHP News Reader can be grouped by several categories.

Each category is identified by a single line like this:

[Computer Science]

This defined a category named as "Computer Science"

The newsgroups defined in the same category should be pulled from the same news server, and should be with the same charset. Also note that at least one category should be defined in newsgroups.lst.

The setting consists of multiple directives where each directive is a pair of key and value, which separated by tabs or spaces. The value part ends at end of line

For example, the following line sets directive "foobar" as "value1 value2"

foobar     value1 value2

Valid directives recognized by PHP News Reader are:

'server' directive

This directive defines the news server used to retrieve newsgroups in this category.

Since v2.5.5 of PHP News Reader, the address of the news server can be configured with port number.

For example: news.pnews-test.com:12345

'group' directive

This directive defines the groups included in each category.
Multiple groups can be separated by a comma ","
Groups can be specified in three kind of syntax:

1. Full group name for inclusion, i.e: tw.bbs.comp.hardware
   
   
2. Pattern match for sub-class groups inclusion, i.e: tw.bbs.comp.*
   
   Only the last class of group name can be used in pattern match
      For example, tw.bbs.*.hardware is INVALID.
   
   Before v2.2.4, only 'all-match' patttern (a single * ) is allowed in the last class pattern of group name
      For example, tw.bbs.comp.hard* is INVALID in v2.2.4, while tw.bbs.comp.* is VALID.
   
   After v2.3.0, the last class pattern is not restricted to a single *,
      For example, tw.bbs.comp.hard* is now VALID in v2.3.0 or later.
   
   
3. Full group name for exclusion, i.e: !tw.bbs.comp.virus
   Only full group name is allowed here, it is used to nagative the previously included group.
   
   
4. Since v2.6.0 of PHP News Reader, multiple 'group' directives can be specified in one single category.

'option' directive

In each section, an optional "option" directive can be defined.

The following values are now recognized:

default

This category will become the default category when user first come in.

Only one category can be marked as "default".
If multiple categories are marked as "default", the last category will become the default.

private

The reading access for this category is restricted by authentication,
only used when the $CFG["auth_type"] is "optional"

nntps

With this option, the connection to news server will be NNTP over SSL, also known as NNTPS. This option first appeared in v2.4.0, and require PHP with v4.3.0 or greater and be compiled with OpenSSL support.

readonly

This category is readonly even if user performs a login.

This option first appeared in v2.5.0 of PHP News Reader.

hidden

This category is hidden from index page. This category can still be accessed as normal category, if you know the corresponding category number.

This option first appeared in v2.5.2 of PHP News Reader.

Multiple options can be separated by comma, for example:

option        default,private

'auth' directive

The access to the news server of this category require the authentication info (username/password) to be specified.

The username/password are separated by comma, ",", for example:

auth         myname,mypasswd

Since PHP News Reader v2.5.2, if you use 'http' as $CFG['auth_prompt'], you can use the username and password in the http authentication as the authentication info requested by Web server. For example:

auth         %http_user,%http_pw

The %http_user and %http_pw will be replaced by the username/password provided in http authentication. This replacement does not work if you use 'form' as $CFG['auth_prompt']. This is because that the password does not available in session variable for the security reason.

The replacement of %http_* is originally coded by Jochen Staerk.

'charset' directive

The charset setting for this category. All newsgroups in this category should be with the same charset.

Notice: the original 'lang' setting is deprecated since v2.1.0, please use 'charset' instead.

---

An example for newsgroups.lst:

The setting before any categories are global settings. Two global settings are valid now: charset and server

# default charset for all categories
charset        big5

# default news server for all categories
server     news1.domain.org

After these global settings, each categories are defined. For example, the following settings defined three categories,

[X1]
server     news1.domain.org
group     nopy.*,nopy.comp.network
option    default

[X2]
# use the default news server
group     nopy.test,nopy.talk.*
auth     none

[X3]
server     news2.domain.org
group     nopy.comp.*,nopy.rec.*
auth     username,password
charset        gb2312

The first category "X1" contains all newsgroups matching "nopy.*" or "nopy.comp.network" from the news server "news1.domain.org", and the default charset is used in these groups. By the way, this category does not require authentication to the news server (by default)

The second category "X2" contains all newsgroups matching "nopy.test" or "nopy.talk.*" from the default news server defined in the above global settings, and the default charset is used in these groups. By the way, this category does not require authentication to the news server

The third category "X3" contains all newsgroups matching "nopy.comp.*" or "nopy.rec.*" from the news server "news2.domain.org", and the "gb2312" charset is used in these groups. This category does require explicily authentication to the news server by the supplied username/password