doc/man/incoming.conf.5

   1 .\" $Revision: 6992 $
   2 .TH INCOMING.CONF 5
   3 .SH NAME
   4 incoming.conf \- names and addresses that feed us news
   5 .SH DESCRIPTION
   6 The file
   7 .I <pathetc in inn.conf>/incoming.conf
   8 consists of three types of entries: key/value, peer and group.
   9 Comments are from the hash character ``#'' to the end of the line.
  10 Blank lines are ignored.  All key/value entries within each type
  11 must not be duplicated.
  12 .PP
  13 Key/value entries are a keyword immediately followed by a colon, at least
  14 one blank and a value.  For example:
  15 .PP
  16 .RS
  17 .nf
  18        max-connections: 10
  19 .fi
  20 .RE
  21 .PP
  22 A legal key does not contains blanks, colons, nor ``#''.
  23 There are 3 different types of values:  integers, booleans, and strings.
  24 Integers are as to be expected. A boolean value is either ``true'' or
  25 ``false'' (case is significant). A string value is any other sequence of
  26 characters. If the string needs to contain whitespace, then it must be
  27 quoted with double quotes.
  28 .PP
  29 Peer entries look like:
  30 .PP
  31 .RS
  32 .nf
  33         peer <name> {
  34              # body
  35         }
  36 .fi
  37 .RE
  38 .PP
  39 The word ``peer'' is required. ``<name>''is a label for this peer.
  40 The ``<name>'' is any string valid as a key. The body of a peer entry
  41 contains some number of key/value entries.
  42 .PP
  43 Group entries look like:
  44 .PP
  45 .RS
  46 .nf
  47         group <name> {
  48              # body
  49         }
  50 .fi
  51 .RE
  52 .PP
  53 The word ``group'' is required. The ``<name>'' is any string valid as a
  54 key. The body of a group entry contains any number of the three types of
  55 entries. So key/value pairs can be defined inside a group, and peers can
  56 be nested inside a group, and other groups can be nested inside a group.
  57 .PP
  58 Key/value entries that are defined outside of all peer and group entries
  59 are said to be at ``global scope''. Global key/value entries act as
  60 defaults for peers. When
  61 .IR innd (8)
  62 looks for a specific value in a peer entry
  63 (for example, the maximum number of connections to allow), if the value
  64 is not defined in the peer entry, then the enclosing groups are examined
  65 for the entry (starting at the closest enclosing group). If there are no
  66 enclosing groups, or the enclosing groups don't define the key/value,
  67 then the value at global scope is used.
  68 .PP
  69 A small example could be:
  70 .PP
  71 .RS
  72 .nf
  73 # Global value applied to all peers that have
  74 # no value of their own.
  75 max-connections: 5
  76
  77 # A peer definition.
  78 peer uunet {
  79      hostname: usenet1.uu.net
  80 }
  81
  82 peer vixie {
  83      hostname: gw.home.vix.com
  84      max-connections: 10 # override global value.
  85 }
  86
  87 # A group of two peers who can open more
  88 # connections than normal
  89 group fast-sites {
  90      max-connections: 15
  91
  92      # Another peer. The ``max-connections'' value from the
  93      # ``fast-sites'' group scope is used. The ``hostname'' value
  94      # defaults to the peer's name.
  95      peer data.ramona.vix.com {
  96      }
  97
  98      peer bb.home.vix.com {
  99          hostname: bb.home.vix.com
 100          max-connections: 20 # he can really cook.
 101     }
 102 }
 103 .fi
 104 .RE
 105 .PP
 106 Given the above configuration file, the defined peers would have the
 107 following values for the ``max-connections'' key.
 108 .PP
 109 .RS
 110 .nf
 111         uunet                  5
 112         vixie                 10
 113         data.ramona.vix.com   15
 114         bb.home.vix.com       20
 115 .fi
 116 .RE
 117 .PP
 118 Ten keys are allowed:
 119 .TP
 120 .BI hostname:
 121 This key requires a string value. It is a list of hostnames separated by a
 122 comma. A hostname is the host's FQDN, or the dotted quad ip-address of the
 123 peer. If this key is not present in a peer block, the hostname defaults to
 124 the label of the peer.
 125 .TP
 126 .BI streaming:
 127 This key requires a boolean value. It defines whether streaming commands
 128 are allowed from this peer. (default=true)
 129 .TP
 130 .BI max-connections:
 131 This key requires a positive integer value. It defines the maximum number
 132 of connections allowed. A value of zero specifies an unlimited number
 133 of maximum connections (``unlimited'' or ``none'' can be used as synonym).
 134 (default=0)
 135 .TP
 136 .BI hold-time:
 137 This key requires a positive integer value. It defines the hold time before
 138 closing, if the connection is over max-connections. A value of zero
 139 specifies immediate close. (default=0)
 140 .TP
 141 .BI password:
 142 This key requires a string value. It is used if you wish to require a peer
 143 to supply a password. (default=no password)
 144 .TP
 145 .BI identd:
 146 This key requires a string value. It is used if you wish to require a peer's
 147 user name retrieved through identd match the specified string. Note that
 148 currently
 149 .IR innd (8)
 150 does not implement any timeout in identd callbacks, so enabling this
 151 option may cause innd to hang if the remote peer does not respond to ident
 152 callbacks in a reasonable timeframe (default=no identd)
 153 .TP
 154 .BI patterns:
 155 This key requires a string value. It is a list of
 156 .IR newsfeeds (5)-style
 157 list of newsgroups which are to be accepted from this host. (default="*")
 158 .TP
 159 .BI email:
 160 This key requires a string value. Reserved for future use. (default=empty)
 161 .TP
 162 .BI comment:
 163 This key requires a string value. Reserved for future use. (default=empty)
 164 .TP
 165 .BI skip:
 166 This key requires a boolean value. Setting this entry causes this peer
 167 to be skipped. (default=false)
 168 .TP
 169 .BI noresendid:
 170 This key requires a boolean value. It defines whether
 171 .IR innd (8)
 172 should send
 173 ``431 RESENDID'' responses if a message is offered that is being received
 174 from another peer. This can be useful for peers that resend messages
 175 right away, as innfeed does. (default=false)
 176 .TP
 177 .BI nolist:
 178 This key requires a boolean value. It defines whether a peer is allowed to
 179 issue list command. (default=false)
 180 .SH HISTORY
 181 Written by Fabien Tassin <fta@sofaraway.org> for InterNetNews.
 182 .de R$
 183 This is revision \\$3, dated \\$4.
 184 ..
 185 .R$ $Id: incoming.conf.5 6992 2004-10-01 05:30:17Z rra $
 186 .SH "SEE ALSO"
 187 inn.conf(5),
 188 innd(8),
 189 newsfeeds(5),
 190 uwildmat(3).