"Fossies" - the Fresh Open Source Software Archive

Member "leafnode-1.12.0/README" (28 Dec 2021, 13383 Bytes) of package /linux/misc/leafnode-1.12.0.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README": 1.11.12_vs_1.12.0.

    1 =====	IMPORTANT
    2 
    3 Make sure that you have the most current version of leafnode installed.
    4 Check http://sourceforge.net/projects/leafnode/ for updates.
    5 
    6 You are encouraged to subscribe to the leafnode-announce mailing list,
    7 available from the address above by clicking on "Lists".
    8 
    9 =====	TABLE OF CONTENTS
   10 
   11 - OVERVIEW
   12 - FILES AND DIRECTORIES
   13 - THE FILTER FILE
   14 - INSTALLATION
   15 - UPDATE FROM VERSIONS < 1.6
   16 - UPDATE FROM VERSIONS < 1.9.3
   17 - UPDATE FROM VERSIONS < 1.9.20 -- IMPORTANT! INCOMPATIBLE CHANGES HERE!
   18 - UPDATE FROM VERSIONS < 1.9.23 -- IMPORTANT! INCOMPATIBLE CHANGES HERE!
   19 - UPDATE FROM VERSIONS < 1.11.0 -- IMPORTANT! INCOMPATIBLE CHANGES HERE!
   20 - TROUBLESHOOTING (formerly called DEBUGGING)
   21 - PROBLEMS
   22 - HACKING
   23 
   24 =====	OVERVIEW
   25 
   26 Leafnode is a USENET software package designed for small sites, with a
   27 few tens of readers and only a slow link to the net.
   28 
   29 It consists of several programs, three essential ones and several add-ons.
   30 
   31  - Leafnode is the NNTP server.  It talks to the normal news clients,
   32    and stores readership data.
   33 
   34  - Fetchnews is the NNTP news-gatherer.  It looks at the readership data
   35    Leafnode stores, and selects what groups to pull news from.
   36 
   37  - Texpire is responsible for deleting old and uninteresting news.  It
   38    deletes all discussion threads that are old and not recently read.
   39 
   40 These are the add-ons that ship with leafnode:
   41 
   42  - Applyfilter lets you delete articles from your local news spool
   43    which fit a certain pattern.
   44 
   45  - Checkgroups inserts the titles of newsgroups into the newsgroup
   46    database.
   47 
   48  - Newsq shows which news are waiting to be transferred to your upstream
   49    server.
   50 
   51 There are third-party add-ons for leafnode, listed in the "ADD-ONS" file.
   52 
   53 
   54 Only groups that someone has been reading in the past week are fetched
   55 from the upstream NNTP server.  When someone stops reading a group,
   56 fetchnews will stop reading that group a week later (this is the default
   57 which can be configured), and when someone starts reading a group, fetchnews
   58 will grab all the articles it can in that group the next time it runs.
   59 
   60 Here are Leafnode's distinguishing features:
   61 
   62  - Uses very little disk space and bandwidth compared to other servers.
   63    Obviously truer for 3-user sites than for 30-user, and probably wholly
   64    untrue for 300-user sites.
   65 
   66  - Easy configuration and maintenance. Leafnode tries very hard to
   67    recover automatically from error situations.
   68 
   69  - The newsspool can be easily manipulated by small scripts. Some tiny
   70    examples are in the subdirectory tools/ .
   71 
   72 As most programs, Leafnode has also weaknesses:
   73 
   74  - Scales very badly.
   75 
   76  - Logging and screen output are inconsistent at times.
   77 
   78 
   79 The current version of leafnode is available from:
   80 
   81 	http://sourceforge.net/projects/leafnode/
   82 	http://www.leafnode.org/
   83 
   84 There is also a leafnode mailing list. Send mail to
   85 
   86 	leafnode-list-subscribe@leafnode.org
   87 
   88 to subscribe, or visit
   89 https://www.leafnode.org/mailman/listinfo/leafnode-list/
   90 
   91 The list subscription triggers a challenge email that you need to answer
   92 before the subscription becomes effective, so that nobody can subscribe you
   93 without your prior consent.
   94 
   95 The list archives are at:
   96 https://www.leafnode.org/pipermail/leafnode-list/
   97 
   98 =====	FILES AND DIRECTORIES
   99 
  100 Leafnode puts its files in three separate directories: The spool
  101 directory, the library directory, and the binaries directory. All
  102 directories can be changed at compile time.
  103 
  104 In the spool directory you find the stored news, the active file and
  105 some other short-lived configuration file. It defaults to /var/spool/news
  106 and can be changed at compilation time. There are some special
  107 directories here; see the leafnode(8) man page.
  108 
  109 The configuration directory contains long-lived configuration files. It
  110 defaults to /etc/leafnode.
  111 
  112 The binaries directory, /usr/local/sbin by default, contains the
  113 executable programs applyfilter, texpire, fetchnews and leafnode.
  114 
  115 The user directory, /usr/local/bin by default, contains the newsq
  116 and leafnode-version programs.
  117 
  118 
  119 =====	THE FILTER FILE
  120 
  121 Since version 1.8, leafnode supports filtering of incoming headers for
  122 arbitrary regular expressions. This feature is by default deactivated.
  123 To activate it, you must write a file which contains the regular
  124 expressions to be filtered (the "filter file") and in addition point
  125 leafnode to this file by entering a line of the format
  126 
  127 filterfile = /path/to/your/filterfile
  128 
  129 into your $(LIBDIR)/config.
  130 The format of the filterfile is as follows:
  131 1) One regular expression per line
  132 2) Comments start with # at the beginning of a line
  133 3) Empty lines are allowed
  134 
  135 Here is a short example which will kill everything posted to alt.flame:
  136 
  137 ^Newsgroups:.*[, ]alt.flame$
  138 ^Newsgroups:.*[, ]alt.flame,
  139 
  140 You cannot use
  141 
  142 ^Newsgroups:.*alt.flame
  143 
  144 because this will also kill postings to alt.flame.nice or comp.alt.flame.
  145 
  146 Since version 1.9.3 and up to 1.11.X, leafnode used Perl-compatible regular
  147 expressions which are implemented in the PCRE library written by Philip
  148 Hazel, University of Cambridge, UK. Perl regular expressions should be
  149 explained in any reasonable book about Perl. There is also a whole book
  150 about regular expressions published by O'Reilly. A rather technical
  151 explanation is given in the pcre2(3) manual page.
  152 
  153 Since version 1.12.0, leafnode uses the PCRE2 library by the same author,
  154 see pcre2(3) or https://www.pcre.org/current/doc/html/index.html
  155 or its home page https://github.com/PhilipHazel/pcre2
  156 
  157 =====	INSTALLATION
  158 
  159 Read the file INSTALL.
  160 
  161 
  162 
  163 =====	UPDATE FROM VERSIONS < 1.6
  164 
  165 There are some major changes from leafnode versions previous to 1.6.
  166 These include leafnode-1.6alpha.
  167 
  168 1) The format of the groupinfo file has changed.
  169 
  170 2) Some files (including the groupinfo file) have moved from
  171    /usr/lib/leafnode/ to /var/spool/news/leaf.node/
  172 
  173 3) The article information for the main upstream server has
  174    been moved from groupinfo into a separate file.
  175 
  176 To update correctly, do a "make update" as root after you have
  177 successfully completed "make install". See the file INSTALL for more
  178 details.
  179 
  180 =====	UPDATE FROM VERSIONS < 1.9.3
  181 
  182 There is one more change from leafnode versions prior to 1.9.3. These
  183 include leafnode-1.9.3beta versions up to leafnode-1.9.3b5.
  184 
  185 The change is that the groupinfo file is now sorted in a case-insensitive
  186 manner. To update correctly, do a "make update" as root after you have
  187 successfully completed "make install". See the file INSTALL for more
  188 details.
  189 
  190 =====	UPDATE FROM VERSIONS < 1.9.20
  191 
  192 Note: some things have changed in 1.9.20.
  193 
  194 1. Fetchnews now tries to send XOVER to figure which articles to
  195    download, older versions only used XHDR. Leafnode will automatically fall
  196    back to using XHDR if XOVER fails.
  197 
  198 2. Most leafnode programs enforce a fully-qualified unique domain name
  199    and exit if gethostbyname("HOSTNAME") does not yield one. (HOSTNAME
  200    is the hostname obtained from gethostname.) The important thing here
  201    is that the hostname must be globally unique: only one computer (and
  202    none else) in the world - yours - may use that name. You will lose
  203    your own posts if this is not the case. Therefore, domain names like
  204    "localhost.localdomain" do not qualify and are rejected.
  205 
  206    This hostname need not be registered in DNS if it's explicitly
  207    specified in the configuration file.
  208 
  209    See the separate README-FQDN* documentation for details, it is
  210    available (with identical contents) in plain text and HTML formats.
  211 
  212 3. The behaviour of the out.going posting queue has changed. If a post
  213    to an upstream server fails, the article is now moved straight into
  214    failed.postings. Formerly, it would be tried on other servers.
  215 
  216 4. In adverse conditions, when fetchnews cannot obtain the lock file, it
  217    may leave files like /var/spool/news/leaf.node/lock.file.XXFjkle8w3
  218    behind. You can remove these files at any time UNLESS fetchnews or
  219    texpire is running at the same time.
  220 
  221 =====	UPDATE FROM VERSIONS < 1.9.23
  222 
  223 --- REMOTE ACCESS TO LEAFNODE LISTENING ON NNTP PORT
  224 
  225 If you want to give remote users (that are not in your LANs) access to your
  226 server, you previously only needed to allow them in access in hosts.allow.
  227 
  228 Since leafnode 1.9.23, an additional parameter is required to be set to allow
  229 users outside of your LAN access to your leafnode.  The config.example file
  230 has documentation on how to set this parameter.  This is meant as additional
  231 security measure when some novice user hoses his access control
  232 configuration, there have been recurring reports of "I did not ever touch
  233 that newsgroup, but leafnode is pulling news for that group nonetheless" --
  234 these may have been caused by unauthorized access that was accidentally
  235 granted. Note: This code is somewhat stupid for IPv6, and considers link- or
  236 site local addresses "local". The IPv4 code checks the leafnode computer's
  237 addresses and netmasks instead.
  238 
  239 DISTRIBUTORS: DO _NOT_ SET THAT PARAMETER OR EVEN CHANGE THE COMMENT IN
  240 YOUR EXAMPLE CONFIG. YOU WILL BE PUBLICALLY ACCUSED ON BUGTRAQ ET AL.
  241 
  242 WE CAN SAFELY AND SOUNDLY ASSUME THAT PEOPLE WHO WANT TO RUN WORLD-WIDE
  243 ACCESSIBLE SERVERS CAN READ DOCUMENTATION.
  244 
  245 =====	UPDATE FROM VERSIONS < 1.11.0
  246 
  247 1. Configuration change:
  248 
  249 The parser for the configuration and filter files now understands quoted
  250 strings on the right hand side of the configuration or filter lines, with
  251 simple backslash (\) escapes, to allow for hash marks (#), quote marks (")
  252 and leading or trailing blanks in passwords. If such characters are used in
  253 filters or configuration options, you will need to change the lines, see the
  254 leafnode(8) manual page for details.
  255 
  256 2. IPv6 support in fetchnews:
  257 
  258 fetchnews supports IPv6 since v1.11.0. This still needs the ./configure
  259 option --with-ipv6 and, of course, an operating system with IPv6 and IPv6
  260 network connectivity - the latter is not widespread yet. No special
  261 configuration options beyond the compile-time option is required, fetchnews
  262 will transparently use IPv6 addresses if the name lookup for a server yields
  263 IPv6 addresses.
  264 
  265 =====	TROUBLESHOOTING (formerly called DEBUGGING)
  266 
  267 To get more verbose logs out of leafnode, do this:
  268 
  269 1. log in as root
  270 
  271 2. in your /etc/leafnode/config, add a line "debugmode=1" to the top of
  272    the file.
  273 
  274 3. in your /etc/syslog.conf, add this line:
  275 
  276    news.debug	/var/log/news.all
  277 
  278    There is a tab character between the columns here.
  279 
  280    Note that a line with news.=debug is fundamentally different.
  281    "news.debug" means "debug level or more severe" whereas
  282    "news.=debug" means "only debug level".
  283 
  284    DO NOT USE news.=debug, BUT CHANGE IT TO news.debug INSTEAD
  285    if you want to see what's going on.
  286 
  287 4. touch /var/log/news.all
  288 
  289 5. kill -HUP `cat /var/run/syslogd.pid`
  290 
  291 On some syslogds (Linux), you can add a - before the file name of step
  292 #2 to have syslog write asynchronously for speed, like this:
  293 
  294     news.*	-/var/log/news.all
  295 
  296 Again, there is a tab character between the columns here.
  297 
  298 Some syslogds may complain about the asterisk in news.*. If yours does,
  299 write news.debug instead of news.*.
  300 
  301 =====	PROBLEMS
  302 
  303 If you don't find information about your problem below, please see the FAQ.
  304 
  305 ----- "fatal: libpcre.so.0: open failed: No such file or directory"
  306 
  307 Add the path to your libpcre to LD_LIBRARY_PATH, for bash/ash/ksh/sh:
  308 
  309 LD_LIBRARY_PATH=/usr/local/lib ; export LD_LIBRARY_PATH
  310 
  311  (For csh/tcsh, go figure yourself. These shells are unsuitable for
  312  anything, find the "csh programming considered harmful" article for
  313  details.  csh and tcsh are not supported by leafnode.)
  314 
  315 You can make this change permanent with the crle(1) tool on some
  316 systems.
  317 
  318 ----- make distcheck fails
  319 
  320 Currently, make distcheck requires that a valid "news" user exists in
  321 the system.
  322 
  323 ----- compiler warnings
  324 
  325 Solaris 2.5 emits a lot of bogus warnings at compile time, complaining
  326 about missing prototypes, for mkstemp, gethostname and snprintf; about
  327 the scope of struct sockaddr_in. These warnings can safely be ignored.
  328 
  329 ----- portability -- other build-time problems
  330 
  331 leafnode cannot be tested on all possible systems. Report compile or
  332 run-time portability problems to the leafnode mailing list. However, of
  333 the free operating systems (FreeBSD, NetBSD, OpenBSD, Linux), only
  334 versions supported by the vendor are supported by leafnode. Hurd,
  335 Windows and Solaris 1.x (SunOS 4.x) are unsupported, meaning that no
  336 workarounds for these systems will be employed. CygWin and AmigaOS are
  337 currently unsupported, but may be supported in the future. Feedback is
  338 appreciated.
  339 
  340 Bug and portability fixes for unsupported operating systems that don't
  341 impair the performance on the supported systems will however be accepted
  342 if sent.
  343 
  344 ----- other problems
  345 
  346 You also may want to consult the Mini-Leafsite-HOWTO by Florian Kuehnert
  347 <sutok@gmx.de> which was unfortunately written for leafnode-1.4 and is
  348 therefore somewhat out of date. It is available from the usual places
  349 (sunsite and mirrors).
  350 
  351 If you want to ask on Usenet about leafnode, look in the newsgroups
  352 news.software.nntp for English language and de.comm.software.newsserver
  353 for German-language. Do not crosspost!
  354 
  355 =====   HACKING
  356 
  357 Leafnode 1.X is in maintenance mode. No new features will be added. Only
  358 major bugs will be fixed. Please file any feature requests against
  359 leafnode 2.0beta.
  360 
  361 Hackers, remember to ./configure --enable-maintainer-mode.
  362 
  363 Cornelius Krasel <krasel@wpxx02.toxi.uni-wuerzburg.de>
  364 Matthias Andree <matthias.andree@gmx.de>
  365 
  366  vim:tw=76: