Provided by: leafnode_1.11.10-3_i386 bug

NAME

       leafnode - NNTP server for small (dialup) sites

SYNOPSIS

       leafnode

DESCRIPTION

       Leafnode  is a USENET package intended for small sites, where there are
       few users and little disk space, but where a large number of groups  is
       desired.

       The  design  of leafnode is intended to self-repair after problems, and
       to require no manual maintenance.

       The leafnode program itself  is  the  NNTP  server.   It  is  run  from
       inetd(8),  xinetd(8) or tcpserver when someone wants to read news.  The
       other parts of the package, fetchnews and texpire, are responsible  for
       fetching new news from another server, and for deleting old news.

ACCESS CONTROL

       No authentication or access control is supported.  This is a deliberate
       omission: Implementing this is a job which should  not  be  redone  for
       each and every service.

       It  is  mandatory  that you use external access control mechanisms like
       tcpd, inetd/xinetd compiled with libwrap  support,  tcpserver  with  -x
       option and the like and that these are in effect.  tcpd and libwrap are
       components of Wietse Venema's fine tcp_wrappers package.

       As a very rough last line of defense against abuse, leafnode will  drop
       connections  from  outside  your  LANs  by  default.  You can configure
       leafnode to let go of this restriction  (look  for  the  allowstrangers
       option),  but  don't  do  that unless tight access control is in place.
       Someone will abuse your computer sooner or later. Promised.

       I recommend that either firewalling or tcpd be used for access control.

FILES

       All these files and directories must be readable by the user "news". It
       is  recommended  that, unless otherwise stated, that the user "news" be
       the only user in the group "news" and these files belong to "root:news"
       (user:group)  so  leafnode  cannot  modify your configuration or filter
       files.

       /etc/news/leafnode should not be writable by the user  "news",  but  it
       must  be  executable for at least any of the group that the user "news"
       is in.  /etc/news/leafnode/config contains the configuration parameters
       for  leafnode.  It must not be writable by the user "news". Set this to
       owner root:news and mode 640. For details, see CONFIGURATION below.

       /var/spool/news must also be readable and writable by the user  "news".
       It  contains  the  news articles; e.g.  /var/spool/news/alt/fan/agulbra
       contains the articles in the  alt.fan.agulbra  group.   Each  directory
       contains  articles  in  numbered  files (decimal numbers, monotonically
       increasing), and a special file called  .overview  which  contains  the
       "Subject",  "From",  "Date",  "Message-ID",  "References",  "Bytes" and
       "Lines" headers for each article in the group.

       Several subdirectories are special:

       /var/spool/news/leaf.node contains  the  files  that  leafnode  creates
       during  operation,  for  example  the  groupinfo  file  which  contains
       information  about  each  USENET  newsgroup.  This  file  is  built  by
       fetchnews  (8).  You can force a complete rebuild of the groupinfo file
       by calling fetchnews with the parameter -f (see fetchnews (8)).

       /var/spool/news/out.going contains local postings that fetchnews(8)  is
       to  pass  to  the  upstream  NNTP  server.  After  a  posting  has been
       successfully written to disk, its u+r permission flag is set. This flag
       is  interpreted  by  fetchnews(8)  as "you may post this article". This
       prevents fetchnews from posting articles that are still being  received
       from newsreaders. (Note: versions 1.9.23 to 1.9.32 inclusively used u+x
       instead, which caused some "stuck post" problems with articles  in  the
       spool  when  a  prior  leafnode  version was updated to one of these 10
       versions. Updating to leafnode 1.9.33 or later fixes the problem.)

       /var/spool/news/failed.postings  contains  local  postings   that   the
       upstream  server  rejected.   fetchnews(8)  will  create  files in this
       directory, but none of the leafnode programs will  delete  anything  in
       it.

       /var/spool/news/message.id contains hard links to each message; this is
       used in place of the dbz database typically used by bigger servers.  (A
       directory such as this is probably more efficient for the small servers
       leafnode is designed for but scales very badly.)

       /var/spool/news/interesting.groups contains one file for each group  an
       NNTP  client  has asked to read.  leafnode will update the ctime (ls -l
       usually shows the mtime, try  ls -lc)  of  the  relevant  file  when  a
       LISTGROUP,  XOVER, XHDR, STAT, HEAD, BODY or ARTICLE command is issued,
       when a GROUP or LIST ACTIVE command (the  latter  only  with  a  single
       group,  not with patterns) is issued for an interesting group (to avoid
       unsubscribing low-traffic groups that are still read) and  fetchnews(8)
       will  retrieve  all  new  articles  in all groups whose files have been
       either

              - touched during the past two days, or

              - touched more than once, and at  least  once  within  the  past
              week.

       The   timeout   is  configurable  through  the  config  file  variables
       timeout_short and  timeout_long.  See  also  fetchnews(8)  for  the  -n
       option.

       /etc/inetd.conf  or  /etc/xinetd.conf  contains the configuration which
       starts leafnode.  It is strongly recommended to start leafnode as  user
       news.

ENVIRONMENT

       LN_REJECT_POST_PRE
              If  this  variable exists, all POST commands are rejected with a
              400 code.  Use only for debugging clients.

       LN_REJECT_POST_POST
              If this variable exists, the POST command is rejected with a 400
              code after the article and CRLF.CRLF has been received. Use only
              for debugging clients.

CONFIGURATION

       All configuration is done  using  the  file  /etc/news/leafnode/config,
       which  may  include a filter description file, filterfile for short, as
       described below.

       For the purposes of this section, whitespace shall  be  defined  as  an
       arbitrary  sequence consisting of one or more SPACE or HTAB characters,
       ASCII positions 32 and 9, respectively.

       The configuration file is strictly line-oriented with  LF  or  CRLF  as
       line terminator.

       Empty  lines and lines consisting of only whitespace, possibly followed
       by a comment (introduced by a hash mark (#) and extending  through  the
       end of the line), are skipped.

       All  other  lines  have  exactly  three  mandatory fields, a plain text
       parameter,  an  assignment  character  (=)  optionally  surrounded   by
       whitespace  and a value.  The value is either plain text or - new since
       leafnode v1.11 - a string  in  double  quotes  with  trivial  backslash
       escape (see below).

       Plain  text  starts  at  the first non-whitespace character and extends
       through the last non-whitespace character on the line  that  is  not  a
       comment. A trailing comment on a line is skipped.

       Quoted  strings  are  enclosed  in  double  quote  characters (").  The
       backslash character (\) is  skipped,  but  it  copies  the  immediately
       following  character  verbatim,  so  that you can specify the backslash
       itself by doubling it (\\) or a double quote character as part  of  the
       string  by  preceding  it  with  a backslash (\"); the hash mark has no
       special meaning as command introducer inside quoted strings. Text after
       the  end  of  the string is silently ignored (this may change in future
       versions).  Comments after quoted strings are ignored.

       MANDATORY PARAMETERS

       These parameters must be specified for leafnode to work.

       server = news02.example.com
              "server" is used by fetchnews (8) to select what NNTP  server(s)
              to  retrieve  news  from  and  to post your articles to. You can
              specify more than one news server; in  that  case,  the  servers
              will be queried from the top down. If you want to post articles,
              at least one of your servers should allow you to post.   In  the
              example above, news02.example.com is the news server.

              This  parameter  can be given more than once. Each server starts
              with  a  fresh  set  of  default   configuration   options,   no
              inheritance  takes  place  from  the previous server definition.
              Only options explicitly marked "server-specific" can be set on a
              per  server  basis, "general" options are set for all servers at
              the same time.

       expire = 5
              "expire" is the number of days an article should be kept around.
              In  the example, five days after the article has last been read,
              it is deleted by texpire (8). This value MUST  be  at  least  1.
              This  parameter is global, see the introductory paragraph of the
              following GENERAL OPTION PARAMETERS section  to  find  out  what
              this means.

       GENERAL OPTIONAL PARAMETERS

       These  options  can  only be configured once in the configuration file,
       and take effect for leafnode as a whole. It does not matter where these
       are  specified  relative  to  server= options, but for clarity, you are
       encouraged to place these before the  first  server=  line.  Specifying
       each  of  the  global  options  more  than once lets the last copy take
       effect, but may cause errors in the future.

       hostname = host.domain.country
              By default, leafnode tries hard to figure the host name of  your
              computer, skipping inadequate (non-unique) names if possible. It
              will look up your computer's host name with  gethostname(3)  and
              then try to qualify the name with gethostbyname(3) if necessary.
              Common sources for the full name therefore are  /etc/hosts,  NIS
              and DNS, but consult your system documentation for details.

              If  leafnode fails to determine the host name, this is usually a
              hint that your system is not configured properly, or  it  has  a
              hostname that is unsuitable for the domain part of a Message-ID,
              for example, "localhost.localdomain", and  you  should  fix  the
              name service configuration. Adding a unique fully-qualified host
              name to /etc/hosts is usually sufficient. Please see README-FQDN
              for more details.

              You  can  configure the unique fully-qualified host name here as
              well, but this is not recommended and discouraged.

       create_all_links = 1
              Normally, fetchnews will store articles only in  the  newsgroups
              which  it considers interesting. With this option set, fetchnews
              will create hardlinks for  all  newsgroups  in  the  Newsgroups:
              header  that it knows about. This may be of interest if you want
              to apply a score- or killfile to the local Xref: line.

       maxfetch = 1000
              "maxfetch" specifies the maximum number  of  articles  fetchnews
              (8) should fetch from the upstream server in each group. Its use
              is not advised, because if you use it you will not see  all  the
              traffic in a group. By default there is no limit.

       initialfetch = 1
              "initialfetch" defines how many articles from a newly subscribed
              group should be  fetched.  The  default  is  to  fetch  all  old
              articles, which can get quite time-consuming when subscribing to
              a very busy group. This is equivalent to setting initialfetch to
              zero.  If  you want to get no old articles when subscribing to a
              new group, you should set initialfetch to one, as in the example
              above.

       groupexpire very.crowded.group = 1

       groupexpire very.crowded.hierarchy.* = 1
              "groupexpire"  makes  it  possible  to  adjust  expiry times for
              individual groups. Expiry times are given in days. 0 means  "use
              the  default",  negative  values  prevent the expire process for
              this group altogether (you can consider this an  archive  mode).
              This  value  is  used  by  texpire  (8). You can specify as many
              groupexpire lines as you like. It is possible  to  specify  glob
              (7)-like wildcard expressions.

       maxage = 10
              If  an  article  turns  up on your upstream news server which is
              older than "maxage" days it will not been fetched  even  if  you
              don't  have it yet.  This is useful if your upstream server gets
              occasional "hiccups". The default is set to 10. If you  want  to
              switch  this  feature  off, set maxage to some very large value,
              such as 20000 (this is equivalent to roughly 54 years).

       maxold = 10
              Is synonymous to maxage, see above.

       maxlines = 2000
              If you want to avoid receiving very large articles, you may  set
              the  "maxlines"  parameter  to  the  maximal  number of lines an
              article should have. By default, this feature is switched off.

       minlines = 2
              Sometimes newsgroups are spammed with empty postings. To  reject
              these  postings,  you  can set the "minlines" parameter. Setting
              minlines to a value larger 4 is probably not a good  idea  since
              you  will  also  start to kill "real" postings then. By default,
              this feature is switched off.

       maxbytes = 100000
              If you want to avoid receiving very large articles,  instead  of
              using  the  "maxlines" parameter you can also use the "maxbytes"
              parameter. By default, this feature is switched off.

       maxcrosspost = 5
              If you want to combat spam, you can filter out all postings that
              are  posted  to  more  than  a certain number of newsgroups. The
              number  is  defined  by  setting  "maxcrosspost".  Setting  this
              parameter  to  very  low  values  is  probably  a bad idea. This
              feature is switched off by default.

       maxgroups = 5
              Synonymous for maxcrosspost. See above.

       filterfile = /etc/news/leafnode/filters
              Leafnode can filter the  input  headers  for  arbitrary  regular
              expressions.    These   are   stored   in   a   file  designated
              "filterfile". The format of "filterfile"  is  very  simple:  one
              perl-compatible  regular  expression  per  line.  If  one of the
              regular expressions fits to a header to be downloaded, the  body
              of  that  article will be rejected. This feature is switched off
              by default. The format of the regular expressions  is  described
              in pcre(3).

       timeout_short = 2
              By  default, a group that has been accidentally touched is being
              fetched for two days. You  can  change  this  time  by  changing
              timeout_short.

       timeout_long = 7
              By  default,  a  group  that  has  not been read at all is being
              fetched for seven days before being unsubscribed. This  interval
              can be changed by setting timeout_long to a different value.

       timeout_active = 90
              By  default,  active files from the upstream servers are re-read
              every  90  days.  This  interval  can  be  changed  by   setting
              timeout_active  to  a  different value. Be aware that reading an
              active file transfers about one MB of information if the  server
              that  you are using carries a reasonable number of groups (i. e.
              around 20,000).

       timeout_client = 900 (since v1.9.23)
              By default, leafnode will drop the connection  900  seconds  (15
              minutes)  after seeing the last command from the client. You can
              change the timeout here.  Setting  it  too  low  (like  below  5
              minutes) will annoy your users and consume more system resources
              for re-reading all the files.

       timeout_fetchnews = 300 (since v1.9.52)
              Fetchnews will, since v1.9.52, assume the  upstream  server  has
              become wedged after waiting for a reply for 300 seconds. You can
              change the timeout here.

       timeout_lock = 5 (since v1.9.54)
              Configure how many seconds the leafnode  programs  (applyfilter,
              checkgroups,  fetchnews,  texpire)  will  wait for the lock file
              before aborting. Setting this to 0 means to  wait  indefinitely.
              NOTE:  you can override this by setting the environment variable
              LN_LOCK_TIMEOUT (note it is not LN_TIMEOUT_LOCK).   The  default
              is 5 seconds.

       delaybody = 1
              With  this option set, fetchnews (8) fetches only the headers of
              an article for visual inspection. Only  when  the  headers  have
              been read, the bodies of the articles will be retrieved the next
              time fetchnews (8) is called. This can save  a  huge  amount  of
              download time and disk space.

       delaybody_in_situ = 1 (since v1.9.41)
              This is only applicable with delaybody=1.

              By default, leafnode will give the full downloaded article a new
              article number so they appear as new in  your  newsreader.  This
              does  not  work  for  all  newsreaders.  With  this  option set,
              leafnode will retain the original article number. You'll have to
              figure  out  how  to  tell your newsreader to show old articles.
              This option defaults to 0. It is highly recommended to leave  it
              unset.

       debugmode = 1
              With  this  option  set, fetchnews (8), texpire (8) and leafnode
              (8) will start to log lots of debugging output via syslog (8) at
              facility  news  and  priority  debug.  Use  it for tracking down
              problems with your feed. debugmode  should  be  left  at  0  for
              regular  use  because  it  can log enormous amounts of data. The
              higher the number, the more will be logged.  Choosing  a  figure
              greater than 3 will not make a difference at the moment.

       allow_8bit_headers = 1 (since v1.9.25)
              By  default,  leafnode  rejects  local  posts  that  have  8-bit
              characters in  their  headers,  because  they  violate  relevant
              standards,  particularly  RFC-2822  (which RFC-1036 is based on)
              that demands that Usenet news headers (as mail headers) must  be
              pure  7-bit  US-ASCII,  with  only  whitespace  allowed from the
              control characters.

              However, as UTF-8 is to come,  and  some  national  hierarchies,
              particularly  the Norwegian and Danish (no.*, dk.*) seem to have
              agreed on preferring just-send-eight over RFC-2047, you can  set
              this  option  to  allow  8-bit  data  in  headers. Leafnode will
              however add a warning header if 8-bit data is  present,  stating
              that the site administrator allowed this.

              There  is  no way to make leafnode accept non-whitespace control
              characters in headers.

       allowSTRANGERS = MAGIC (since v1.9.23)
              By default, leafnode refuses connections from outside your LANs.
              Check  config.example  for  how  to  use  this  parameter to let
              strangers connect to your leafnode. Instead of MAGIC,  you  have
              to  write  a  number  as  mentioned in config.example. Note that
              capitalization matters.

       linebuffer = 1
              By default, stdout and sometimes stderr of applications are  set
              to  "fully  buffered"  unless  connected  to terminals. Use this
              option to explicitly request line buffered mode for  stdout  and
              stderr.

       clamp_maxage = 0
              By  default,  leafnode  will derive a "maxage" argument from the
              expire time that is applicable to the group (groupexpire if set,
              expire  otherwise), to prevent fetching articles again that were
              once there and then cleared by texpire(8). Set clamp_maxage=0 to
              get rid of this behaviour.

       article_despite_filter = 1 (since v1.9.33)
              By default, fetchnews will request HEAD and BODY separately if a
              filter file is defined and delaybody is off. For  high  latency,
              high  throughput  links  (such  as  interleaved DSL or satellite
              links), it may be faster to request head and body together  with
              an  ARTICLE  command  and  ignore  the body if the filters apply
              (though it may not be cheaper if you pay  per  MByte),  enabling
              this  option  will  force leafnode to use the ARTICLE command in
              spite of filters being defined. (Note that  in  delaybody  mode,
              HEAD and BODY will ALWAYS be requested separately.)

       newsadmin = news@leafnode.example.org (since v1.9.47)
              This  option sets the From: address for the placeholder article,
              it should be the news administrator's mail address.  It defaults
              to news@HOSTNAME, where HOSTNAME is leafnode's hostname.

       SERVER-SPECIFIC OPTIONAL PARAMETERS

       These  options  can only be placed after the server= line of the server
       to which you would like these to apply, and they always pertain to  the
       preceding  server=  line. Specifying them before the first server= line
       is an error.

       username = myname
              If any of your news servers  requires  authentication,  you  can
              enter  your  username  on that server here. This field may occur
              multiple times, once  after  each  server  definition.  See  the
              introduction  of  this  CONFIGURATION section for information on
              how to quote myname.

       password = mypassword
              If any of your news servers  requires  authentication,  you  can
              enter  your  password  on that server here. This field may occur
              multiple times, once after each server  definition.   Since  the
              password  is available in clear text, it is recommended that you
              set the rights on the config file as  restrictive  as  possible,
              otherwise  other users of your computer will be able to get your
              password(s)  from  that  file.  See  the  introduction  of  this
              CONFIGURATION   section   for   information   on  how  to  quote
              mypassword.

       port = 8000
              By default, fetchnews tries to  connect  to  its  upstream  news
              servers  on  the  NNTP  port  (119).  If  your  servers run on a
              different port, you can specify those here. This field may occur
              multiple times, once after each server definition.

              Note:  to  modify the port your own leafnode servers listens on,
              change the inetd.conf, xinetd.conf  configuration  file  or  the
              tcpsvd/tcpserver  command  line.  leafnode  does  not set up its
              listen port itself.

       timeout = 30
              By default, leafnode tries to connect for 10 seconds to a server
              and  then gives up. If you have a slow server, you can try for a
              longer time by setting the timeout higher (in this  example,  30
              seconds). The timeout can be tuned individually for each server.

       noactive = ANYTHING (v1.9.25 ... v1.11.4)

       noactive = 1 (since v1.11.5)
              If  this  parameter  is set, the active file is never downloaded
              from this server. Use this for very  slow  servers  unless  they
              carry  groups  that other servers don't offer. Leafnode versions
              1.9.25 to 1.11.4 would always assume that "ANYTHING" had been 1.
              "noactive = 0" is supported since v1.11.5.

       nodesc = ANYTHING (until v1.11.4)

       nodesc = 1 (since v1.11.5)
              Some  servers  do not deliver news groups descriptions correctly
              because they  cannot  parse  the  XGTITLE  and  LIST  NEWSGROUPS
              commands.  In  that case, put this line after the "server" line.
              Leafnode  versions  up  to  v1.11.4  would  always  assume  that
              "ANYTHING" had been 1. "nodesc = 0" is supported since v1.11.5.

       nopost = 1 (since v1.9.23)
              Prevent posting to this server. You can use this if the upstream
              won't let you post but still greet leafnode with 200 or  if  the
              upstream doesn't forward your postings reliably.

       noread = 1 (since v1.9.33)
              Prevent fetching news articles or active files from this server.
              You can use this if the upstream is good to post, but  too  slow
              to fetch news from.

       noxover = 1 (since v1.9.47)
              Prevent  the  use of XOVER on the current server. Fetchnews will
              use XHDR instead.

       only_groups_match_all = 1 (since v1.9.52)
              Usually, when cross-posting an article, fetchnews will post  the
              article if ANY group listed in the Newsgroups: header is matched
              by the PCRE.  With this option on,  ALL  groups  listed  in  the
              Newsgroups:  header  must  match.  This  can  be  used  to avoid
              "poison" groups when you have multiple upstream servers.

       only_groups_pcre = PCRE (since v1.9.28)
              This parameter lists the Perl-compatible regular  expression  of
              groups  that  are  fetched or posted to this server. The PCRE is
              automatically anchored at the left hand side, so  you  can  omit
              the leading ^. Remember to escape dots, as in:
              de\.comp\.|de\.comm\.

              If  this  parameter  is omitted, all groups are fetched from and
              posted to this server.

              Note: you must run fetchnews with the -f option after  changing,
              adding or removing any only_groups_pcre option.

              Hint:   you   can   use   something  like  this  to  check  your
              only_groups_pcre settings:
              cut -f1 -d" " @spooldir@/leaf.node/groupinfo \
              | pcregrep 'PATTERN'

       post_anygroup = 1 (since v1.9.37)
              This parameter  makes  leafnode  post  on  this  server  without
              checking  if  it  carries the group an article is posted to. The
              default is post_anygroup = 0, which  means  that  leafnode  will
              check with a "GROUP" command if the server carries the group the
              articles is posted into. Use  this  on  post-only  servers  that
              don't allow the "GROUP" command. Note: inconsiderate use of this
              parameter may cause articles to end up  in  the  failed.postings
              directory.

       OBSOLETE PARAMETERS

       supplement
              is synonymous to server. Don't use it on new installations.

       fqdn   is synonymous to hostname. Don't use it on new installations.

PROTOCOL

       Here are the NNTP commands supported by this server:

       ARTICLE,  BODY,  DATE, GROUP, HDR, HEAD, HELP, LAST, LIST, LIST ACTIVE,
       LIST ACTIVE.TIMES, LIST EXTENSIONS, LIST NEWSGROUPS, LIST OVERVIEW.FMT,
       LISTGROUP, MODE, NEWGROUPS, NEXT, POST, OVER, SLAVE, STAT, XHDR, XOVER.
       These commands follow RFC-977 and RFC-2980, except HDR and  OVER  which
       are recognized in anticipation of current NNTP drafts.

       Note that the syntax of HDR and OVER may change.

BUGS

       Leafnode  is  totally  unaware  of  UTF-8 and will reject a client that
       posts UTF-8 characters in the header. Current Usefor drafts  claim  all
       article  headers UTF-8 encoded Unicode. Leafnode still expects RFC-2047
       instead which may eventually be phased out in favour of UTF-8.

       Leafnode stops reading a line at the first NUL character.

       Leafnode may not cope well with crosspostings that cross hierarchies if
       you   have   multiple  upstream  feeds  and  use  the  only_groups_pcre
       configuration option.

       Leafnode will only  bother  to  determine  the  time  zone  offset  for
       generated  Date: headers for posts that lack them on systems that offer
       the tm_gmtoff member in struct tm (commonly BSD and GNU systems).

AUTHOR

       Written by Arnt Gulbrandsen <agulbra@troll.no> and copyright 1995 Troll
       Tech AS, Postboks 6133 Etterstad, 0602 Oslo, Norway, fax +47 22646949.

       Modified  by  Cornelius  Krasel  <krasel@wpxx02.toxi.uni-wuerzburg.de>,
       Randolf   Skerka   <Randolf.Skerka@gmx.de>   and   Markus   Enzenberger
       <enz@cip.physik.uni-muenchen.de>.    Copyright   of  the  modifications
       1997-1999.

       Modified by Matthias Andree <matthias.andree@gmx.de>, Copyright 1999  -
       2002.   Modified by Ralf Wildenhues <ralf.wildenhues@gmx.de>, Copyright
       2002.

       Jonathan  Larmour  <jifl@jifvik.org>  contributed  the   timeout_client
       feature.

       Andreas  Meininger  <a.meininger@gmx.net>  contributed  the code to let
       texpire ignore groupexpire = -1 groups.

       Mark Brown <broonie@debian.org> added the noactive option.

       Numerous contributions by other people.

       The initial development of leafnode has been paid  for  by  Uninett  AS
       (http://www.uninett.no/).

SEE ALSO

       applyfilter(8), checkgroups(8), fetchnews(8), newsq(1), texpire(8).

       tcpd(8), hosts_access(5), glob(7), pcre(3), RFC 977, RFC 2980.