X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?a=blobdiff_plain;f=doc%2Fpod%2Finn.conf.pod;fp=doc%2Fpod%2Finn.conf.pod;h=0000000000000000000000000000000000000000;hb=b7a32e2d73e3ab1add8208d3e157f7269a31ef4d;hp=31455951ade4a5f2dc9cea2e62e92442b30326fe;hpb=ac902a8299ff4469b356836f431ead31c3377377;p=innduct.git diff --git a/doc/pod/inn.conf.pod b/doc/pod/inn.conf.pod deleted file mode 100644 index 3145595..0000000 --- a/doc/pod/inn.conf.pod +++ /dev/null @@ -1,1273 +0,0 @@ -=head1 NAME - -inn.conf - Configuration data for InterNetNews programs - -=head1 DESCRIPTION - -F in I is the primary general configuration file for -all InterNetNews programs. Settings which control the general operation -of various programs, as well as the paths to all portions of the news -installation, are found here. The INNCONF environment variable, if set, -specifies an alternate path to F. - -This file is intended to be fairly static. Any changes made to it will -generally not affect any running programs until they restart. Unlike -nearly every other configuration file, F cannot be reloaded -dynamically using ctlinnd(8); innd(8) must be stopped and restarted for -relevant changes to F to take effect (C is -the fastest way to do this.) - -Blank lines and lines starting with a number sign (C<#>) are ignored. All -other lines specify parameters, and should be of the following form: - - : - -(Any amount of whitespace can be put after the colon and is optional.) If -the value contains embedded whitespace or any of the characers C<[]<>"\:>, -it must be enclosed in double quotes (""). A backslash (C<\>) can be used -to escape quotes and backslashes inside double quotes. is -case-sensitive; C is not the same as C or C. -(F parameters are generally all in lowercase.) - -If occurs more than once in the file, the first value is used. -Some parameters specified in the file may be overridden by environment -variables. Most parameters have default values if not specified in -F; those defaults are noted in the description of each -parameter. - -Many parameters take a boolean value. For all such parameters, the value -may be specified as C, C, or C to turn it on and may be any -of C, C, or C to turn it off. The case of these values is -significant. - -This documentation is extremely long and organized as a reference manual -rather than as a tutorial. If this is your first exposure to INN and -these parameters, it would be better to start by reading other man pages -and referring to this one only when an F parameter is explicitly -mentioned. Those parameters which need to be changed when setting up a -new server are discussed in F. - -=head1 PARAMETERS - -=head2 General Settings - -These parameters are used by a wide variety of different components of -INN. - -=over 4 - -=item I - -This should be the domain name of the local host. It should not have a -leading period, and it should not be a full host address. It is used only -if the GetFQDN() routine in libinn(3) cannot get the fully-qualified -domain name by using either the gethostname(3) or gethostbyname(3) calls. -The check is very simple; if either routine returns a name with a period -in it, then it is assumed to have the full domain name. As this parameter -is rarely used, do not use it to affect the righthand side of -autogenerated Message-IDs; see instead I and I in -L. The default value is unset. - -=item I - -The flags to pass to innd on startup. See innd(8) for details on the -possible flags. The default value is unset. - -=item I - -The path to the program to be used for mailing reports and control -messages. The default is I/innmail. This should not normally -need to be changed. - -=item I - -The command to use when mailing postings to moderators and for the use of -innmail(1). The message, with headers and an added To: header, will be -piped into this program. The string C<%s>, if present, will be replaced -by the e-mail address of the moderator. It's strongly recommended for -this command to include C<%s> on the command line rather than use the -addresses in the To: and Cc: headers of the message, since the latter -approach allows the news server to be abused as a mechanism to send mail -to arbitrary addresses and will result in unexpected behavior. There is -no default value for this parameter; it must be set in F or a -fatal error message will be logged via syslog. - -For most systems, C (adjusted for the -correct path to sendmail) is a good choice. - -=item I - -What to put into the Path: header to represent the local site. This is -added to the Path: header of all articles that pass through the system, -including locally posted articles, and is also used when processing some -control messages and when naming the server in status reports. There is -no default value; this parameter must be set in F or INN will -not start. A good value to use is the fully-qualified hostname of the -system. - -=item I - -The name of the default NNTP server. If I is not set and -UNIX domain sockets are not supported, nnrpd(8) tries to hand off -locally-posted articles through an INET domain socket to this server. -actsync(8), nntpget(8), and getlist(8) also use this value as the default -server to connect to. In the latter cases, the value of the NNTPSERVER -environment variable, if it exists, overrides this. The default value is -unset. - -=back - -=head2 Feed Configuration - -These parameters govern incoming and outgoing feeds: what size of -articles are accepted, what filtering and verification is performed on -them, whether articles in groups not carried by the server are still -stored and propagated, and other similar settings. - -=over 4 - -=item I - -Articles older than this number of days are dropped. This setting should -probably match the setting on the C line in F. -The default value is C<10>. - -=item I - -Which IP address innd(8) should bind itself to. This must be in -dotted-quad format (nnn.nnn.nnn.nnn). If set to C or not set, innd -defaults to listening on all interfaces. The value of the -INND_BIND_ADDRESS environment variable, if set, overrides this setting. -The default value is unset. - -=item I - -Like I but for IPv6 sockets. If only one of the I -and I parameters is used, then only the socket for the -corresponding address family is created. If both parameters are used -then two sockets are created. If neither of them is used, the list of -sockets to listen on will be determined by the system library -I function. The value of the INND_BIND_ADDRESS6, if set, -overrides this setting. The default value is unset. - -Note that you will generally need to put double quotes ("") around this -value if you set it, since IPv6 addresses contain colons. - -=item I - -If set to a value other than C<0>, a hash of recently received message IDs -is kept in memory to speed history lookups. The value is the amount of -memory to devote to the cache in kilobytes. The cache is only used for -incoming feeds and a small cache can hold quite a few message IDs, so -large values aren't necessarily useful unless you have incoming feeds that -are badly delayed. A good value for a system with more than one incoming -feed is C<256>; systems with only one incoming feed should probably leave -this at C<0>. The default value is C<0>. - -=item I - -Whether newsgroup creation control messages (newgroup and rmgroup) should -be fed as if they were posted to the newsgroup they are creating or -deleting rather than to the newsgroups listed in the Newsgroups: header. -If this parameter is set, the newsgroup affected by the control message -will be extracted from the Control: header and the article will be fed as -if its Newsgroups: header contained solely that newsgroup. This is useful -for routing control messages to peers when they are posted to irrelevant -newsgroups that shouldn't be matched against the peer's desired newsgroups -in F. This is a boolean value and the default is false. - -=item I - -When using the timecaf storage method, article cancels are normally just -cached to be cancelled, not cancelled immediately. If this is set to -true, they will instead by cancelled as soon as the cancel is processed. -This is a boolean value and the default is false. - -This setting is ignored unless the timecaf storage method is used. - -=item I - -If set to something other than C<0>, the line count of the article is -checked against the Lines: header of the article (if present) and the -artice is rejected if the values differ by more than this amount. A -reasonable setting is C<5>, which is the standard maximum signature length -plus one (some injection software calculates the Lines: header before -adding the signature). The default value is C<0>, which tells INN not to -check the Lines: header of incoming articles. - -=item I - -The maximum size of article (headers and body) that will be accepted by -the server, in bytes. A value of C<0> allows any size of article, but -note that B will crash if system memory is exceeded. The default -value is C<1000000> (approximately 1 MB). See also I. - -=item I - -The maximum number of incoming NNTP connections innd(8) will accept. The -default value is C<50>. - -=item I - -If set, this value is prepended to the Path: header of accepted posts -(before I) if it doesn't already appear in the Path: header. -The main purpose of this parameter is to configure all news servers within -a particular organization to add a common identity string to the -Path: header. The default value is unset. - -=item I - -If set, this value is appended to the Path: header of accepted posts -(after I) if it isn't already present as the last element -of the Path: header. The main purpose of this parameter is to make -several news servers appear as one server. The default value is unset. - -Note that the Path: header reads right to left, so appended means inserted -at the leftmost side of the Path: header. - -=item I - -Whether to enable PGP verification of control messages other than cancel. -This is a boolean value and the default is based on whether configure found -pgp, pgpv, or gpgv. - -=item I - -What TCP port innd(8) should listen on. The default value is C<119>, the -standard NNTP port. - -=item I - -Whether to refuse all articles whose message IDs start with -Ccancel.>. This message ID convention is widely followed by spam -cancellers, so the vast majority of such articles will be cancels of spam. -This check, if enabled, is done before the history check and the message -ID is not written to the history file. This is a boolean value and the -default is false. - -This is a somewhat messy, inefficient, and inexact way of refusing spam -cancels. A much better way is to ask all of your upstream peers to not -send to you any articles with C in the Path: header (usually -accomplished by having them mark C as an alias for your machine -in their feed configuration). The filtering enabled by this parameter is -hard-coded; general filtering of message IDs can be done via the embedded -filtering support. - -=item I - -By default, innd(8) records rejected articles in history so that, if -offered the same article again, it can be refused before it is sent. If -you wish to disable this behavior, set this to false. This can cause a -substantial increase in the amount of bandwidth consumed by incoming news -if you have several peers and reject a lot of articles, so be careful with -it. Even if this is set to true, INN won't log some rejected articles to -history if there's reason to believe the article might be accepted if -offered by a different peer, so there is usually no reason to set this to -false (although doing so can decrease the size of the history file). This -is a boolean value and the default is true. - -=item I - -Which local IP address to bind to for outgoing NNTP sockets (used by -innxmit(8) among other programs, but I innfeed(8) -- see -I in innfeed.conf(5) for that). This must be in dotted-quad -format (nnn.nnn.nnn.nnn). If set to C or not set, the operating -system will choose the source IP address for outgoing connections. The -default value is unset. - -=item I - -Like I but for IPv6 sockets. - -=item I - -Set this to true to enable a simplistic check on all cancel messages, -attempting to verify (by simple header comparison) that the cancel message -is from the same person as the original post. This can't be done if the -cancel arrives before the article does, and is extremely easy to spoof. -While this check may once have served a purpose, it's now essentially -security via obscurity, commonly avoided by abusers, and probably not -useful. This is a boolean value, and the default is false. - -=item I - -Set this to true if you want to file articles posted to unknown newsgroups -(newsgroups not in the F file) into the C newsgroup rather -than rejecting them. This is sometimes useful for a transit news server -that needs to propagate articles in all newsgroups regardless if they're -carried locally. This is a boolean value and the default is false. - -=item I - -If INN is offered an article by a peer on one channel, it will return -deferral responses (code 436) to all other offers of that article for this -many seconds. (After this long, if the peer that offered the article -still hasn't sent it, it will be accepted from other channels.) The -default value is C<5> and probably doesn't need to be changed. - -=item I - -How long, in seconds, to keep track of message IDs offered on a channel -before expiring articles that still haven't been sent. The default value -is C<10> and probably doesn't need to be changed. - -=item I - -Normally innd(8) rejects incoming articles when directed to do so by any -enabled article filters (Perl, Python, and TCL). However, this parameter -causes such articles I to be rejected; instead filtering can be -applied on outbound articles. If this parameter is set, all articles will -be accepted on the local machine, but articles rejected by the filter will -I be fed to any peers specified in F with the C flag. - -=back - -=head2 Article Storage - -These parameters affect how articles are stored on disk. - -=over 4 - -=item I - -If set to a value other than C<0>, the claimed size of articles in CNFS -cycbuffs is checked against I plus this value, and if larger, -the CNFS cycbuff is considered corrupt. This can be useful as a sanity -check after a system crash, but be careful using this parameter if you -have changed I recently. The default value is C<0>. - -=item I - -Whether to write out overview data for articles. If set to false, INN -will run much faster, but reading news from the system will be impossible -(the server will be for news transit only). If this option is set to -true, I must also be set. This is a boolean value and the -default is true. - -=item I - -Whether to enable newsgroup-based expiry. If set to false, article expiry -is done based on storage class of storing method. If set to true (and -overview information is available), expiry is done by newsgroup name. -This affects the format of F. This is a boolean value and the -default is true. - -=item I - -Whether to file all postings to C groups in the pseudonewsgroup -C. If this is set to true, the newsgroup C must exist in the -F file or INN will not start. (See the discussion of C -groups in innd(8) under CONTROL MESSAGES.) This is a boolean value and -the default is false. - -=item I - -How many cache slots to reserve for open overview files. If INN is -writing overview files (see I), I is set to -C, and this is set to a value other than C<0>, INN will keep -around and open that many recently written-to overview files in case more -articles come in for those newsgroups. Every overview cache slot consumes -two file descriptors, so be careful not to set this value too high. You -may be able to use the C command to see how many open file -descriptors your operating system allows. innd(8) also uses an open file -descriptor for each incoming feed and outgoing channel or batch file, and -if it runs out of open file descriptors it may throttle and stop accepting -new news. The default value is C<15> (which is probably way too low if -you have a large number of file descriptors available). - -This setting is ignored unless I is set to C. - -=item I - -If set, restricts the overview data stored by INN to only the newsgroups -matching this comma-separated list of wildmat expressions. Newsgroups not -matching this setting may not be readable, and if I is -set to true and the storage method for these newsgroups does not have -self-expire functionality, storing overview data will fail. -The default is unset. - -=item I - -Which overview storage method to use. Currently supported values are -C, C, and C. There is no default value; -this parameter must be set if I is true (the default). - -=over 4 - -=item C - -Stores overview data and index information into buffers, which are -preconfigured files defined in F. C never -consumes additional disk space beyond that allocated to these buffers. - -=item C - -Uses two files per newsgroup, one containing the overview data and one -containing the index. Fast for readers, but slow to write to. - -=item C - -Stores data into a Berkeley DB database. See the ovdb(5) man page. - -=back - -=item I - -Which history storage method to use. The only currently supported -value is C. There is no default value; this parameter must -be set. - -=over 4 - -=item C - -Stores history data in the INN history v6 format: history(5) text -file and a number of dbz(3) database files; this may be in true history -v6 format, or tagged hash format, depending on the build -options. Separation of these two is a project which has not yet been -undertaken. - -=back - -=item I - -If set to true, articles will be stored based on the newsgroup names in -the Xref: header rather than in the Newsgroups: header. This affects what -the patterns in F apply to. The primary interesting effect -of setting this to true is to enable filing of all control messages -according to what storage class the control pseudogroups are filed in -rather than according to the newsgroups the control messages are posted -to. This is a boolean value and the default is true. - -=item I - -Whether to innd(8) should create overview data internally through -libstorage(3). If set to false, innd creates overview data by itself. If -set to true, innd does not create; instead overview data must be created -by overchan(8) from an appropriate entry in F. Setting to true -may be useful, if innd cannot keep up with incoming feed and the -bottleneck is creation of overview data within innd. This is a boolean -value and the default is false. - -=item I - -Only used with the tradspool storage method, this says whether to write -articles in wire format. Wire format means storing articles with C<\r\n> at -the end of each line and with periods at the beginning of lines doubled, -the article format required by the NNTP protocol. Articles stored in this -format are suitable for sending directly to a network connection without -requiring conversion, and therefore setting this to true can make the -server more efficient. The primary reason not to set this is if you have -old existing software that looks around in the spool and doesn't -understand how to read wire format. Storage methods other than tradspool -always store articles in wire format. This is a boolean value and the -default is false. - -=item I - -Whether to act as the slave of another server. If set, INN attempts to -duplicate exactly the article numbering of the server feeding it by -looking at the Xref: header of incoming articles and assigning the same -article numbers to articles as was noted in the Xref: header from the -upstream server. The result is that clients should be able to point at -either server interchangeably (using some load balancing scheme, for -example) and see the same internal article numbering. Servers with this -parameter set should generally only have one upstream feed, and should -always have I set to hand locally posted articles off to -the master server. The upstream should be careful to always feed articles -in order (innfeed(8) can have problems with this in the event of a -backlog). This is a boolean value and the default is false. - -=item I - -For servers writing articles, determine whether the article spool is -on NFS storage. If set, INN attempts to flush articles to the spool -in a more timely manner, rather than relying on the operating system -to flush things such as the CNFS article bitmaps. You should only set -this parameter if you are attempting to use a shared NFS spool on a -machine acting as a single writer within a cluster. This is a boolean -value and the default is false. - -=item I - -For servers reading articles, determine whether the article spool is -on NFS storage. If set, INN will attempt to force articles and -overviews to be read directly from the NFS spool rather than from -cached copies. You should only set this parameter if you are -attempting to use a shared NFS spool on a machine acting a reader a -cluster. This is a boolean value and the default is false. - -=item I - -For servers reading articles, determine whether the article spool is -on NFS storage. If I is set, INN will use the value of -I to delay the apparent arrival time of articles to -clients by this amount; this value should be tuned based on the NFS -cache timeouts locally. This default is 60 (1 minute). - -=item I - -How many cache slots to reserve for Message ID to storage token -translations. When serving overview data to clients (NEWNEWS, XOVER -etc.), nnrpd(8) can cache the storage token associated with a Message -ID and save the cost of looking it up in the history file; for some -configurations setting this parameter can save more than 90% of the -wall clock time for a session. The default value is 10000. - -=item I - -Whether to attempt to mmap() tradindexed overviews articles. Setting -this to true will give better performance on most systems, but some -systems have problems with mmap(). If this is set to false, overviews -will be read into memory before being sent to readers. This is a -boolean value and the default is true. - -=back - -=head2 Reading - -These parameters affect the behavior of INN for readers. Most of them are -used by nnrpd(8). There are some special sets of settings that are broken -out separately after the initial alphabetized list. - -=over 4 - -=item I - -Whether to allow use of the NEWNEWS command by clients. This command used -to put a heavy load on the server in older versions of INN, but is now -reasonably efficient, at least if only one newsgroup is specified by the -client. This is a boolean value and the default is true. If you use the -I parameter in F, be sure to read about the way it -overrides I. - -=item I - -Whether to attempt to mmap() articles. Setting this to true will give -better performance on most systems, but some systems have problems with -mmap(). If this is set to false, articles will be read into memory before -being sent to readers. This is a boolean value and the default is false. - -=item I - -How long (in seconds) a client connection can be idle before it exits. -When setting this parameter, be aware that some newsreaders use the same -connection for reading and posting and don't deal well with the connection -timing out while a post is being composed. If the system isn't having a -problem with too many long-lived connections, it may be a good idea to -increase this value to C<3600> (an hour). The default value is C<600> -(ten minutes). - -=item I - -How long (in seconds) B will wait for the first command from a -reader connection before dropping the connection. This is a defensive -timeout intended to protect the news server from badly behaved reader -clients that open and abandon a multitude of connections without every -closing them. The default value is C<10> (ten seconds), which may need to -be increased if many clients connect via slow network links. - -=item I - -Whether B should check the existence of an article before listing -it as present in response to an NNTP command. The primary use of this -setting is to prevent nnrpd from returning information about articles -which are no longer present on the server but which still have overview -data available. Checking the existence of articles before returning -overview information slows down the overview commands, but reduces the -number of "article is missing" errors seen by the client. This is a -boolean value and the default is true. - -=item I - -This parameter is now obsolete; see "Changes to Perl Authentication -Support for nnrpd" in F. - -=item I - -This parameter is now obsolete; see "Changes to Python Authentication and -Access Control Support for nnrpd" in F. - -=item I - -Normally, innd(8) will fork a copy of nnrpd(8) for all incoming -connections from hosts not listed in F. If this parameter -is set to true, those connections will instead be rejected with a 502 -error code. This should be set to true for a transit-only server that -doesn't support readers, or if nnrpd is running in daemon mode or being -started out of inetd. This is a boolean value and the default is false. - -=item I - -Whether to allow readers to connect even if the server is paused or -throttled. This is only applicable if nnrpd(8) is spawned from innd(8) -rather than run out of inetd or in daemon mode. This is a boolean value -and the default is false. - -=item I - -Whether to enable the tracking system for client behavior. Tracked -information is recorded to I/tracklogs/log-ID, where ID is -determined by nnrpd's PID and launch time.) Currently the information -recorded includes initial connection and posting; only information about -clients listed in F is recorded. This is a boolean value and -the default is false. - -=item I - -When nnrpd(8) is spawned from innd(8), these flags are passed as -arguments to the nnrpd process. This setting does not affect instances -of nnrpd that are started in daemon mode, or instances that are started -via another listener process such as inetd(8) or xinetd(8). Shell -quoting and metacharacters are not supported. This is a string value -and the default is unset. - -=item I - -If set to a value other than C<0>, connections to nnrpd will be refused -if the system load average is higher than this value. The default value -is C<16>. - -=back - -INN has optional support for generating keyword information automatically -from article body text and putting that information in overview for the -use of clients that know to look for it. The following parameters control -that feature. - -This may be too slow if you're taking a substantial feed, and probably -will not be useful for the average news reader; enabling this is not -recommended unless you have some specific intention to take advantage of -it. - -=over 4 - -=item I - -Whether the keyword generation support should be enabled. This is a -boolean value and the default is false. - -FIXME: Currently, support for keyword generation is configured into INN -semi-randomly (based on whether configure found the regex library); it -should be an option to configure and that option should be mentioned here. - -=item I - -Articles larger than this value in bytes will not have keywords generated -for them (since it would take too long to do so). The default value is -C<100000> (approximately 100 KB). - -=item I - -Maximum number of bytes allocated for keyword data. If there are more -keywords than will fit into this many bytes when separated by commas, the -rest are discarded. The default value is C<512>. - -=item I - -Maximum number of keywords that will be generated for an article. (The -keyword generation code will attempt to discard "noise" words, so the -number of keywords actually writen into the overview will usually be -smaller than this even if the maximum number of keywords is found.) The -default value is C<250>. - -=back - -=head2 Posting - -These parameters are only used by nnrpd(8), inews(1), and other programs -that accept or generate postings. There are some special sets of settings -that are broken out separately after the initial alphabetized list. - -=over 4 - -=item I - -Whether to add an NNTP-Posting-Date: header to all local posts. This is a -boolean value and the default is true. Note that INN either does not add -this header or adds the name or IP address of the client. There is no -intrinsic support for obfuscating the name of the client. That has to be -done with a user-written Perl filter, if desired. - -=item I - -Whether to add an NNTP-Posting-Host: header to all local posts giving the -FQDN or IP address of the system from which the post was received. This -is a boolean value and the default is true. - -=item I - -Whether to check local postings for the ratio of new to quoted text and -reject them if that ratio is under 50%. Included text is recognized by -looking for lines beginning with C>, C<|>, or C<:>. This is a -boolean value and the default is false. - -=item I - -The value of the X-Complaints-To: header added to all local posts. The -default is the newsmaster's e-mail address. (If the newsmaster, selected -at configure time and defaulting to C, doesn't contain C<@>, the -address will consist of the newsmaster, a C<@>, and the value of -I.) - -=item I - -Contains a domain used to construct e-mail addresses. The address of the -local news administrator will be given as @I, where -is the newsmaster user set at compile time (C by default). This -setting will also be used by mailpost(8) to fully qualify addresses and by -inews(1) to generate the Sender: header (and From: header if missing). -The value of the FROMHOST environment variable, if set, overrides this -setting. The default is the fully-qualified domain name of the local -host. - -=item I - -The maximum article size (in bytes) for locally posted articles. Articles -larger than this will be rejected. A value of C<0> allows any size of -article, but note that B and B will crash if system memory is -exceeded. See also I, which applies to all articles including -those posted locally. The default value is C<1000000> (approximately 1 -MB). - -=item I - -The address to which to send submissions for moderated groups. It is only -used if the F file doesn't exist, or if the moderated group to -which an article is posted is not matched by any entry in that file, and -takes the same form as an entry in the F file. In most cases, -C<%s@moderators.isc.org> is a good value for this parameter (C<%s> is -expanded into a form of the newsgroup name). See moderators(5) for more -details about the syntax. The default is unset. If this parameter isn't -set and an article is posted to a moderated group that does not have a -matching entry in the F file, the posting will be rejected -with an error. - -=item I - -Whether to generate a Sender: header based on reader authentication. If -this parameter is set, a Sender: header will be added to local posts -containing the identity assigned by F. If the assigned -identity does not include an C<@>, the reader's hostname is used. If this -parameter is set but no identity is be assigned, the Sender: header will -be removed from all posts even if the poster includes one. This is a -boolean value and the default is false. - -=item I - -If set, nnrpd(8) and rnews(1) will pass all locally posted articles to the -specified host rather than trying to inject them locally. See also -I. This should always be set if I is true. The -default value is unset. - -=item I - -The port on the remote server to connect to to post when I -is used. The default value is C<119>. - -=item I - -What to put in the Organization: header if it is left blank by the poster. -The value of the ORGANIZATION environment variable, if set, overrides this -setting. The default is unset, which tells INN not to insert an -Organization: header. - -=item I - -If true, nnrpd(8) will spool new articles rather than attempting to send -them to innd(8). If false, nnrpd will spool articles only if it receives -an error trying to send them to innd. Setting this to true can be useful -if nnrpd must respond as fast as possible to the client; however, when -set, articles will not appear to readers until they are given to innd. -nnrpd won't do this; C must be run periodically to take the -spooled articles and post them. This is a boolean value and the default -is false. - -=item I - -Whether to strip To:, Cc:, and Bcc: headers out of all local posts via -nnrpd(8). The primary purpose of this setting is to prevent abuse of the -news server by posting to a moderated group and including To: or Cc: -headers in the post so that the news server will send the article to -arbitrary addresses. INN now protects against this abuse in other ways -provided I is set to a command that includes C<%s> and honors it, so -this is generally no longer needed. This is a boolean value and the -default is false. - -=back - -nnrpd(8) has support for controlling high-volume posters via an -exponential backoff algorithm, as configured by the following parameters. - -Exponential posting backoff works as follows: News clients are indexed by -IP address (or username, see I below). Each time a post is -received from an IP address, the time of posting is stored (along with the -previous sleep time, see below). After a configurable number of posts in -a configurable period of time, nnrpd(8) will activate posting backoff and -begin to sleep for increasing periods of time before actually posting -anything. Posts will still be accepted, but at an increasingly reduced -rate. - -After backoff has been activated, the length of time to sleep is computed -based on the difference in time between the last posting and the current -posting. If this difference is less than I, the new -sleep time will be 1 + (previous sleep time * I). If this -difference is less than I but greater than -I, then the new sleep time will equal the previous sleep -time. If this difference is greater than I, the new -sleep time is zero and posting backoff is deactivated for this poster. - -Exponential posting backoff will not be enabled unless I is set -and I and I are set to something other -than their default values. - -Here are the parameters that control exponential posting backoff: - -=over 4 - -=item I - -Whether to index posting backoffs by user rather than by source IP -address. You must be using authentication in nnrpd(8) for a value of true -to have any meaning. This is a boolean value and the default is false. - -=item I - -The path to a directory, writeable by the news user, that will contain the -backoff database. There is no default for this parameter; you must -provide a path to a creatable or writeable directory to enable exponential -backoff. - -=item I - -The amount to multiply the previous sleep time by if the user is still -posting too quickly. A value of C<2> will double the sleep time for each -excessive post. The default value is C<1>. - -=item I - -Postings from the same identity that arrive in less than this amount of -time (in seconds) will trigger increasing sleep time in the backoff -algorithm. The default value is C<0>. - -=item I - -Postings from the same identity that arrive in greater than this amount of -time (in seconds) will reset the backoff algorithm. Another way to look -at this constant is to realize that posters will be allowed to generate at -most 86400/I posts per day. The default value is C<1>. - -=item I - -This many postings are allowed before the backoff algorithm is triggered. -The default value is C<10000>. - -=back - -=head2 Monitoring - -These parameters control the behavior of innwatch(8), the program that -monitors INN and informs the news administrator if anything goes wrong -with it. - -=over 4 - -=item I - -Whether to start innwatch(8) from rc.news. This is a boolean value, and -the default is true. - -=item I - -Free space in I, in inndf(8) output units (normally -kilobytes), at which innd(8) will be throttled by innwatch(8), assuming a -default F. The default value is C<800>. - -=item I - -Free space in I, in inndf(8) output units (normally kilobytes), at -which innd(8) will be throttled by innwatch(8), assuming a default -F. The default value is C<25000>. - -=item I - -Load average times 100 at which innd(8) will be restarted by innwatch(8) -(undoing a previous pause or throttle), assuming a default -F. The default value is C<1000> (that is, a load average of -10.00). - -=item I - -Load average times 100 at which innd(8) will be throttled by innwatch(8), -assuming a default F. The default value is C<2000> (that -is, a load average of 20.00). - -=item I - -Load average times 100 at which innd(8) will be paused by innwatch(8), -assuming a default F. The default value is C<1500> (that -is, a load average of 15.00). - -=item I - -How long (in seconds) innwatch(8) will sleep between each check of INN. -The default value is C<600>. - -=item I - -Free inodes in I at which innd(8) will be throttled by -innwatch(8), assuming a default F. The default value is -C<200>. - -=item I - -Free space in I and I, in inndf(8) output -units (normally kilobytes), at which innd(8) will be throttled by -innwatch(8), assuming a default F. The default value is -C<8000>. - -=back - -=head2 Logging - -These parameters control what information INN logs. - -=over 4 - -=item I - -Whether to start cnfsstat(8) when innd(8) is started. cnfsstat will log -the status of all CNFS cycbuffs to syslog on a periodic basis (frequency -is the default for C, currently 600 seconds). This is a -boolean value and the default is false. - -=item I - -Whether the size of accepted articles (in bytes) should be written to the -article log file. This is useful for flow rate statistics and is -recommended. This is a boolean value and the default is true. - -=item I - -Set this to true to log C commands to syslog. This is a -boolean value and the default is false. - -=item I - -How many old logs scanlogs(8) keeps. scanlogs(8) is generally run by -news.daily(8) and will archive compressed copies of this many days worth -of old logs. The default value is C<3>. - -=item I - -Whether the verified name of the remote feeding host should be logged to -the article log for incoming articles rather than the last entry in the -Path: header. The only reason to ever set this to false is due to some -interactions with F flags; see newsfeeds(5) for more -information. This is a boolean value and the default is true. - -=item I - -Whether the names of the sites to which accepted articles will be sent -should be put into the article log file. This is useful for debugging and -statistics and can be used by newsrequeue(8). This is a boolean value and -the default is true. - -=item I - -Whether nnrpd overview statistics should be logged via syslog. This can -be useful for measuring overview performance. This is a boolean value and -the default is false. - -=item I - -How many articles to process on an incoming channel before logging the -activity. The default value is C<200>. - -FIXME: This is a rather unintuitive name for this parameter. - -=item I - -Whether to put the storage API token for accepted articles (used by -nntplink) in the article log. This is a boolean value and the default is -false. - -=item I - -Where to write history statistics for analysis with -F; this can be modified with ctlinnd(8) while innd is -running. Logging does not occur unless a path is given, and there is no -default value. - -=item I - -How frequently (in seconds) innd(8) should write out a status report. The -report is written to I/inn_status.html. If this is set to C<0> or -C, status reporting is disabled. The default value is C<0>. - -=item I - -How frequently (in seconds) innd(8) should report performance timings to -syslog. If this is set to C<0>, performance timing is disabled. Enabling -this is highly recommended, and innreport(8) can produce a nice summary of -the timings. If set to C<0>, performance timings in nnrpd(8) are also -disabled, although nnrpd always reports statistics on exit and therefore -any non-zero value is equivalent for it. The default value is C<0>. - -=back - -=head2 System Tuning - -The following parameters can be modified to tune the low-level operation -of INN. In general, you shouldn't need to modify any of them except -possibly I unless the server is having difficulty. - -=over 4 - -=item I - -How many read or write failures until a channel is put to sleep or -closed. The default value is C<5>. - -=item I - -Each time an attempted write returns EAGAIN or EWOULDBLOCK, innd(8) will -wait for an increasing number of seconds before trying it again. This is -the multiplier for the sleep time. If you're having trouble with channel -feeds not keeping up, it may be good to change this value to C<2> or C<3>, -since then when the channel fills INN will try again in a couple of -seconds rather than waiting two minutes. The default value is C<120>. - -=item I - -The time (in seconds) to wait between noticing inactive channels. The -default value is C<600>. - -=item I - -How many seconds to wait before a channel restarts. The default value is -C<300>. - -=item I - -The threshold for deciding whether to move already-read data to the top of -buffer or extend the buffer. The buffer described here is used for reading -NNTP data. Increasing this value may improve performance, but it should -not be increased on Systems with insufficient memory. Permitted values -are between C<0> and C<1048576> (out of range values are treated as -C<1048576>) and the default value is C<8192>. - -=item I - -How many article writes between updating the active and history files. -The default value is C<10>. - -=item I - -When using buffindexed, retrieving overview data (that is, responding to -XOVER or running expireover) causes mmapping of all overview data blocks -which include requested overview data for newsgroup. But for high volume -newsgroups like control.cancel, this may cause too much mmapping at once -leading to system resource problems. To avoid this, if the amount to be -mmapped exceeds I (in KB), buffindexed mmap's just -one overview block (8 KB). This parameter is specific to buffindexed -overview storage method. The default value is C<1024> (1 MB). - -=item I - -If set to anything other than C<0>, maximum buffer size (in bytes) for -reading NNTP command will have this value. It should not be large on -systems which are slow to process and store articles, as that would lead -to innd(8) spending a long time on each channel and keeping other channels -waiting. The default value is BUFSIZ defined in stdio.h (C<1024> in most -environments, see setbuf(3)). - -=item I - -How many times to attempt a fork(2) before giving up. The default value -is C<10>. - -=item I - -If set to anything other than C<0>, all child processes of innd(8) will -have this nice(2) value. This is usually used to give all child processes -of innd(8) a lower priority (higher nice value) so that innd(8) can get -the lion's share of the CPU when it needs it. The default value is C<4>. - -=item I - -If set to anything greater than C<0>, all nnrpd(8) processes that receive -and process a NEWNEWS command will nice(2) themselves to this value -(giving other nnrpd processes a higher priority). The default value is -C<0>. Note that this value will be ignored if set to a lower value than -I (or I if nnrpd(8) is spawned from innd(8)). - -=item I - -If set to anything greater than C<0>, all nnrpd(8) processes will nice(1) -themselves to this value. This gives other news processes a higher -priority and can help overchan(8) keep up with incoming news (if that's -the object, be sure overchan(8) isn't also set to a lower priority via -I). The default value is C<0>, which will cause nnrpd(8) -processes spawned from innd(8) to use the value of I, while -nnrpd(8) run as a daemon will use the system default priority. Note that -for nnrpd(8) processes spawned from innd(8), this value will be ignored if -set to a value lower than I. - -=item I - -Wait for this many seconds before noticing inactive channels. -Wait for this many seconds before innd processes articles when it's paused -or the number of channel write failures exceeds I. The -default value is C<300>. - -=item I - -How long (in seconds) an innd(8) incoming channel may be inactive before -innd closes it. The default value is C<3600> (an hour). - -=item I - -The maximum number of file descriptors that innd(8) or innfeed(8) can have -open at once. If innd(8) or innfeed(8) attempts to open more file -descriptors than this value, it is possible the program may throttle or -otherwise suffer reduced functionality. The number of open file -descriptors is roughly the maximum number of incoming feeds and outgoing -batches for innd(8) and the number of outgoing streams for innfeed(8). If -this parameter is set to a negative value, the default limit of the -operating system will be used; this will normally be adequate on systems -other than Solaris. Nearly all operating systems have some hard maximum -limit beyond which this value cannot be raised, usually either 128, 256, -or 1024. The default value of this parameter is C<-1>. Setting it to -C<256> on Solaris systems is highly recommended. - -=back - -=head2 Paths and File Names - -=over 4 - -=item I - -Where to store archived news. The default value is I/archive. - -=item I - -The path to where the news articles are stored (for storage methods other -than CNFS). The default value is I/articles. - -=item I - -The path to the news binaries. The default value is I/bin. - -=item I - -The path to the files that handle control messages. The code for handling -each separate type of control message is located here. Be very careful -what you put in this directory with a name ending in C<.pl>, as it can -potentially be a severe security risk. The default value is -I/control. - -=item I - -The path to the database files used and updated by the server (currently, -F, F, F and its indices, and -F). The default value is I/db. - -=item I - -The path to the news configuration files. The default value is -I/etc. - -=item I - -The path to the Perl, Tcl, and Python filters. The default value is -I/filter. - -=item I - -Where any HTML files (such as periodic status reports) are placed. If the -news reports should be available in real-time on the web, the files in -this directory should be served by a web server. The default value is -the value of I. - -=item I - -Location where incoming batched news is stored. The default value is -I/incoming. - -=item I - -Where the news log files are written. The default value is -I/log. - -=item I - -The home directory of the news user and usually the root of the news -hierarchy. There is no default; this parameter must be set in F -or INN will refuse to start. - -=item I - -Default location for outgoing feed files. The default value is -I/outgoing. - -=item I - -The path to news overview files. The default value is -I/overview. - -=item I - -The path to files required while the server is running and run-time state -information. This includes lock files and the sockets for communicating -with innd(8). This directory and the control sockets in it should be -protected from unprivileged users other than the news user. The default -value is I/run. - -=item I - -The root of the news spool hierarchy. This used mostly to set the -defaults for other parameters, and to determine the path to the backlog -directory for innfeed(8). The default value is I/spool. - -=item I - -Where INN puts temporary files. For security reasons, this is not the -same as the system temporary files directory (INN creates a lot of -temporary files with predictable names and does not go to particularly -great lengths to protect against symlink attacks and the like; this -is safe provided that normal users can't write into its temporary -directory). The default value is set at configure time and defaults to -I/tmp. - -=back - -=head1 EXAMPLE - -Here is a very minimalist example that only sets those parameters that are -required. - - mta: /usr/lib/sendmail -oi -oem %s - ovmethod: tradindexed - pathhost: news.example.com - pathnews: /usr/local/news - hismethod: hisv6 - -For a more comprehensive example, see the sample F distributed -with INN and installed as a starting point; it contains all of the default -values for reference. - -=head1 HISTORY - -Written by Rich $alz for InterNetNews and since -modified, updated, and reorganized by innumerable other people. - -$Id: inn.conf.pod 7751 2008-04-06 14:35:40Z iulius $ - -=head1 SEE ALSO - -inews(1), innd(8), innwatch(8), nnrpd(8), rnews(1). - -Nearly every program in INN uses this file to one degree or another. The -above are just the major and most frequently mentioned ones.