chiark / gitweb /
debugging for thing that crashed
[innduct.git] / 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).