Having completed these general tasks, you can now turn to the really interesting part of INN: its configuration files. All these files reside in /etc/news. Some changes to configurations files were introduced in Version 2, and it is Version 2 that we describe here. If you're running an older version, you should find this chapter useful to guide you in upgrading your configuration. During the next few sections, we will discuss them one by one, building the Virtual Brewery's configuration as an example.
If you want to find out more about the features of individual configuration files, you can also consult the manual pages; the INN distribution contains individual manual pages for each of them.
There are a number of INN parameters that are global in nature; they are relevant to all newsgroups carried.
INN's main configuration file is inn.conf. Among other things, it determines the name by which your machine is known on Usenet. Version 2 of INN allows a baffling number of parameters to be configured in this file. Fortunately, most parameters have default values that are reasonable for most sites. The inn.conf(5) file details all of the parameters, and you should read it carefully if you experience any problems.
A simple example inn.conf might look like:
# Sample inn.conf for the Virtual Brewery server: vlager.vbrew.com domain: vbrew.com fromhost: vbrew.com pathhost: news.vbrew.com organization: The Virtual Brewery mta: /usr/sbin/sendmail -oi %s moderatormailer: %[email protected] # # Paths to INN components and files. # pathnews: /usr/lib/news pathbin: /usr/lib/news/bin pathfilter: /usr/lib/news/bin/filter pathcontrol: /usr/lib/news/bin/control pathdb: /var/lib/news pathetc: /etc/news pathrun: /var/run/news pathlog: /var/log/news pathhttp: /var/log/news pathtmp: /var/tmp pathspool: /var/spool/news patharticles: /var/spool/news/articles pathoverview: /var/spool/news/overview pathoutgoing: /var/spool/news/outgoing pathincoming: /var/spool/news/incoming patharchive: /var/spool/news/archive pathuniover: /var/spool/news/uniover overviewname: .overview |
The first line tells the programs rnews and inews which host to contact when delivering articles. This entry is absolutely crucial; to pass articles to innd, they have to establish an NNTP connection with the server.
The domain keyword should specify the domain portion of the host's fully qualified domain name. A couple of programs must look up your host's fully qualified domain name; if your resolver library returns the unqualified hostname only, the name given in the domain attribute is tacked onto it. It's not a problem to configure it either way, so it's best to define domain.
The next line defines what hostname inews is going to use when adding a From: line to articles posted by local users. Most newsreaders use the From: field when composing a reply mail message to the author of an article. If you omit this field, it will default to your news host's fully qualifed domain name. This is ot always the best choice. You might, for example, have news and mail handled by two different hosts. In this case, you would supply the fully qualified domain name of your mail host after the fromhost statement.
The pathhost line defines the hostname INN is to add to the Path: header field whenever it receives an article. In most cases, you will want to use the fully qualified domain name of your news server; you can then omit this field since that is the default. Occasionally you may want to use a generic name, such as news.vbrew.com, when serving a large domain. Doing this allows you to move the news system easily to a different host, should you choose to at some time.
The next line contains the organization keyword. This statement allows you to configure what text inews will put into the Organization: line of articles posted by your local users. Formally, you would place a description of your organization or your organization's name in full here. Should you not wish to be so formal, it is fashionable for organizations with a sense of humor to exhibit it here.
The organization keyword is mandatory and specifies the pathname of the mail transport agent that will be used for posting moderator messages. %s is replaced by the moderator email address.
The moderatormailer entry defines a default address used when a user tries to post to a moderated newsgroup. The list of moderator addresses for each newsgroup is usually kept in a separate file, but you will have a hard time keeping track of all of them. The moderatormailer entry is therefore consulted as a last resort; if it is defined, inews will replace the %s string with the (slightly transformed) newsgroup name and send the entire article to this address. For instance, when posting to soc. feminism, the article is mailed to [email protected], given the above configuration. At UUNET, there should be a mail alias installed for each of these submissions addresses that automatically forwards all messages to the appropriate moderator.
Finally, each of the remaining entries specifies the location of some component file or executable belonging to INN. If you've installed INN from a package, these paths should have been configured for you. If you're installing from source, you'll need to ensure that they reflect where you've installed INN.
The news administrator on a system is able to control which newsgroups users have access to. INN provides two configuration files that allow the administrator to decide which newsgroups to support and provide descriptions for them.
The active and newsgroups files are used to store and describe the newsgroups hosted by this news server. They list which newsgroups we are interested in receiving and serving articles for, and administrative information about them. These files are found in the /var/lib/news/ directory.
The active file determines which newsgroups this server supports. Its syntax is straightforward. Each line in the active file has four fields delimited by whitespace:
name himark lomark flags |
The name field is the name of the newsgroup. The himark field is the highest number that has been used for an article in that newsgroup. The lomark field is the lowest active number in use in the newsgroup. To illustrate how this works, consider the follow scenario. Imagine that we have a newly created newsgroup: himark and lowmark are both 0 because there are no articles. If we post 5 articles, they will be numbered 1 through 5. himark will now equal 5, the highest numbered article, and lowmark will equal 1, the lowest active article. If article 5 is cancelled there will be no change; himark will remain at 5 to ensure that that article number is not reallocated and lowmark will remain at 1, the lowest active article. If we now cancel article 1, himark will remain unchanged, but lowmark will now equal 2, because 1 is no longer active. If we now post a new article, it will be assigned article number 6, so himark will now equal 6. Article 5 has been in use, so we won't reassign it. lowmark remains at 2. This mechanism allows us to easily allocate unique article numbers for new articles and to calculate approximately how many active articles there are in the group: himark–lowmark.
The field may contain one of the following:
Posting directly to this news server is allowed.
Posting directly to this news server is not allowed. This prevents newsreaders from posting directly to this news server. New articles may only be received from other news servers.
The group is moderated. Any articles posted to this newsgroup are forwarded to the newsgroup moderator for approval before they enter the newsgroup. Most newsgroups are unmoderated.
Articles in this group are not kept, but only passed on. This causes the news server to accept the article, but all it will do with it is pass it to the “up-stream” news servers. It will not make the articles available to newsreaders reading from this server.
Articles cannot be posted to this newsgroup. The only way that news articles are delivered to this server is by feeding them from another news server. Newsreaders may not directly write articles to this server.
Articles are locally filed into the ``foo.bar'' group.
control 0000000000 0000000001 y junk 0000000000 0000000001 y rec.crafts.brewing 0000000000 0000000001 y rec.crafts.brewing.ales 0000000000 0000000001 y rec.crafts.brewing.badtaste 0000000000 0000000001 y rec.crafts.brewing.brandy 0000000000 0000000001 y rec.crafts.brewing.champagne 0000000000 0000000001 y rec.crafts.brewing.private 0000000000 0000000001 y |
The newsgroups file is even simpler. It provides one-line descriptions of newsgroups. Some newsreaders are able to read and present this information to a user to help them decide whether they want to subscribe.
The format of the newsgroups file is simply:
name description |
We want to describe the newsgroups that our server supports, so we'll build our newsgroups file as follows:
rec.crafts.brewing.ales Home brewing Ales and Lagers rec.crafts.brewing.badtaste Home brewing foul tasting brews rec.crafts.brewing.brandy Home brewing your own Brandy rec.crafts.brewing.champagne Home brew your own Champagne rec.crafts.brewing.private The Virtual Brewery home brewers group |
INN provides the news administrator the ability to control which newsgroups are forwarded on to other news servers and how they will be forwarded. The most common method uses the NNTP protocol described earlier, but INN also allows newsfeeds via other protocols, such as UUCP.
The newsfeeds file determines where news articles will be sent. It normally resides in the /etc/news/ directory.
The format of the newsfeeds is a little complicated at first. We'll describe the general layout here, and the newsfeeds(5) manual page describes what we leave out. The format is as follows:
# newsfeeds file format site:pattern:flags:param site2:pattern2\ :flags2:param2 |
The site field names the site to which this feed description relates. The sitename can be coded any way you like and doesn't have to be the domain name of the site. The site name will be used later and will refer to an entry in a table that supplies the hostname to the innxmit program that transmits the news articles by NNTP to the remote server. You may have multiple entries for each site; each entry will be treated individually.
The pattern field specifies which news groups are to be sent to this site. The default is to send all groups, so if that is what you want, just make this field empty. This field is usually a comma-delimited list of pattern-matching expressions. The * character matches zero or more of any character, the . character has no special significance, the ! character (if used at the start of an expression) performs a logical NOT, and the @ character at the start of a newsgroup name means “Do not forward any articles that are posted or crossposted to this group.” The list is read and parsed from left to right, so you should ensure that you place the more specific rules first. The pattern:
rec.crafts.brewing*,!rec.crafts.brewing.poison,@rec.crafts.brewing.private |
would send all of the rec.crafts.brewing news heirarchy except the rec.crafts.brewing.poison. It would not feed any articles that were either posted or crossposted to the rec.crafts.brewing.private newsgroup; these articles will be trapped and available only to those people who use this server. If you reversed the first two patterns, the first pattern would be overridden by the second and you would end up feeding articles for the rec.crafts.brewing.poison newsgroup. The same is true of the first and last patterns; you must always place the more specific patterns before any less specific patterns for them to take effect.
flags controls and places constraints on the feed of news articles to this site. The flags field is a comma delimited list can contain any of the items from the following list, delimited by commands:
Article must be less then size bytes.
Article checks. items can be one or more of d (must have Distribution header) or p (don't check for site in Path header).
Internal buffer size before writing to output.
Article must have less then count hops; the default is 1.
Internal buffer size (for a file feed).
Only moderated groups that match the pattern.
Only unmoderated groups that match the pattern.
Start spooling if more than size bytes get queued.
Feed types: f (file), m (funnel; the param field names the entry that articles will be funneled to), p (pipe to program), c (send to stdin channel of the param field's subprocess), and x (like c, but handles commands on stdin).
What to write: b (article bytesize), f (full path), g (first newsgroup), m (Message ID), n (relative path), s (site that fed article), t (time received), * (names of funnel feed-ins or all sites that get the article), N (newsgroups header), D (distribution header), H (all headers), O (overview data), and R (replication data).
The param field has special coding that is dependent on the type of feed. In the most common configuration it is where you specify the name of the output file to which you will write the outgoing feed. In other configurations you can leave it out. In yet other configurations it takes on different meanings. If you want to do something unusual, the newsfeeds(5) manual page will explain the use of the param field in some detail.
There is a special site name that should be coded as ME and should be the first entry in the file. This entry is used to control the default settings for your news feeds. If the ME entry has a distribution list associated with it, this list will be prepended to each of the other site entries before they are sent. This allows you to, for example, declare some newsgroups to be automatically fed, or automatically blocked from feeding, without having to repeat the pattern in each site entry.
We mentioned earlier that it was possible to use some special feeds to generate thread data that makes the newsreader's job easier. We'll do this by exploiting the overchan command that is part of the INN distribution. To do this, we've created a special local feed called overview that will pass the news articles to the overchan command for processing into overview data.
Our news server will provide only one external news feed, which goes to the Groucho Marx University, and they receive articles for all newsgroups except the control and junk newsgroups, the rec.crafts.brewing.private newsgroup, which will be kept locally, and the rec.crafts.brewing.poison newsgroup, which we don't want people from our brewery seen posting to.
We'll use the nntpsend command to transport the news via NNTP to the news.groucho.edu server. nntpsend requires us to use the “file” delivery method and to write the article's pathname and article ID. Note that we've set the param field to the name of the output file. We'll talk a little more about the nntpsend command in a moment. Our resulting newsfeed's configuration is:
# /etc/news/newsfeeds file for the Virtual Brewery # # Send all newsgroups except the control and junk ones by default ME:!control,!junk:: # # Generate overview data for any newsreaders to use. overview::Tc,WO:/usr/lib/news/bin/overchan # # Feed the Groucho Marx University everything except our private newsgroup # and any articles posted to the rec.crafts.brewing.poison newsgroup. gmarxu:!rec.crafts.brewing.poison,@rec.crafts.brewing.private:\ Tf,Wnm:news.groucho.edu # |
The nntpsend program manages the transmission of news articles using the NNTP protocol by calling the innxmit command. We saw a simple use of the nntpsend command earlier, but it too has a configuration file that provides us with some flexibility in how we configure our news feeds.
The nntpsend command expects to find batch files for the sites it will feed. It expects those batch files to be named /var/spool/news/out.going/sitename. innd creates these batch files when acting on an entry in the newsfeeds, which we saw in the previous sections. We specified the sitename as the filename in the param field, and that satisfies the nntpsend command's input requirements.
The nntpsend command has a configuration file called nntpsend.ctl that is usually stored in the /etc/news/ directory.
The nntpsend.ctl file allows us to associate a fully qualified domain name, some news feed size constraints, and a number of transmission parameters with a news feed site name. The sitename is a means of uniquely identifying a logical feed of articles. The general format of the file is:
sitename:fqdn:max_size:[args] |
The following list describes the elements of this format:
The sitename as supplied in the newsfeeds file
The fully qualified domain name of the news server to which we will be feeding the news articles
The maximum volume of news to feed in any single transfer
Additional arguments to pass to the innxmit command
Our sample configuration requires a very simple nntpsend.ctl file. We have only one news feed. We'll restrict the feed to a maximum of 2 MB of traffic and we'll pass an argument to the innxmit that sets a 3-minute (180 second) timeout. If we were a larger site and had many news feeds, we'd simply create new entries for each new feed site that looked much the same as this one:
# /etc/news/nntpsend.ctl # gmarxu:news.groucho.edu:2m:-t 180 # |
Not so many years ago, it was common for organizations to provide public access to their news servers. Today it is difficult to locate public news servers; most organizations carefully control who has access to their servers, typically restricting access to users supported on their network. INN provides configuration files to control this access.
We mentioned in our introduction to INN that it achieves some of its efficiency and size by separating the news feed mechanism from the newsreading mechanism. The /etc/news/incoming.conf file is where you specify which hosts will be feeding you news using the NNTP protocol, as well as where you define some parameters that control the way articles are fed to you from these hosts. Any host not listed in this file that connects to the news socket will not be handled by the innd daemon; instead, it will be handled by the nnrpd daemon.
The /etc/news/incoming.conf file syntax is very simple, but it takes a moment to come to terms with. Three types of valid entries are allowed: key/value pairs, which are how you specify attributes and their values; peers, which is how you specify the name of a host allowed to send articles to us using NNTP; and groups, a means of applying key/value pairs to groups of peers. Key/value pairs can have three different types of scope. Global pairs apply to every peer defined in the file. Group pairs apply to all peers defined within that group. Peer pairs apply only to that one peer. Specific definitions override less specific ones: therefore, peer definitions override group definitions, which in turn override global pairs.
Curly brace characters ({}) are used to delimit the start and end of the group and peer specifications. The # character marks the rest of the line it appears on as a comment. Key/value pairs are separated by the colon character and appear one to a line.
A number of different keys may be specified. The more common and useful are:
This key specifies a comma-separated list of fully qualifed names or IP addresses of the peers that we'll allow to send us articles. If this key is not supplied, the hostname defaults to the label of the peer.
This key determines whether streaming commands are allowed from this host. It is a Boolean value that defaults to true.
This key specifies the maximum number of connections allowed from this group or peer. A value of zero means unlimited (which can also be specified using none).
This key allows you to specify the password that must be used by a peer if it is to be allowed to transfer news. The default is to not require a password.
This key specifies the newsgroups that we accept from the associated peer. This field is coded according to precisely the same rules as we used in our newsfeeds file.
In our example we have only one host that we are expecting to feed us news: our upstream news provider at Groucho Marx University. We'll have no password, but we will ensure that we don't accept any articles for our private newsgroup from outside. Our hosts.nntp looks like:
# Virtual Brewery incoming.conf file.
# Global settings
streaming: true
max-connections: 5
# Allow NNTP posting from our local host.
peer ME {
hostname: "localhost, 127.0.0.1"
}
# Allow groucho to send us all newsgroup except our local ones.
peer groucho {
hostname: news.groucho.edu
patterns: !rec.crafts.brewing.private
} |
We mentioned earlier that newsreaders, and in fact any host not listed in the hosts.nntp, that connect to the INN news server are handled by the nnrpd program. nnrpd uses the /etc/news/nnrp.access file to determine who is allowed to make use of the news server, and what permissions they should have.
The nnrp.access file has a similar structure to the other configuration files we've looked at. It comprises a set of patterns used to match against the connecting host's domain name or IP address, and fields that determine what access and permission it should be given. Each entry should appear on a line by itself, and fields are separated by colons. The last entry in this file that matches the connecting host will be the one used, so again, you should put general patterns first and follow them with more specific ones later in the file. The five fields of each entry in the order they should appear are:
This field conforms to wildmat(3) pattern-matching rules. It is a pattern that describes the connecting host's name or IP address.
This field determines what permissions the matching host should be granted. There are two permissons you may configure: R gives read permissions, and P gives posting permissions.
This field is optional and allows you to specify a username that an NNTP client must log into the server before being allowed to post news articles. This field may be left blank. No user authentication is required to read articles.
This field is optional and is the password accompanying the username field. Leaving this field blank means that no password is required to post articles.
This field is a pattern specifying which newsgroups the client is allowed to access. The pattern follows the same rules as those used in the newsfeeds file. The default for this field is no newsgroups, so you would normally have a pattern configured here.
In the virtual brewery example, we will allow any NNTP client in the Virtual Brewery domain to both read and post to all newsgroups. We will allow any NNTP client read-only access to all newsgroups except our private internal newsgroup. Our nnrp.access file will look like this:
# Virtual Brewery - nnrp.access # We will allow public reading of all newsgroups except our private one. *:R:::*,!rec.crafts.brewing.private # Any host with the Virtual Brewery domain may Read and Post to all # newsgroups *.vbrew.com:RP::* |
When news articles are received by a news server, they are stored to disk. News articles need to be available to users for some period of time to be useful, so a large operating news server can consume lots of disk space. To ensure that the disk space is used effectively, you can opt to delete news articles automatically after a period of time. This is called article expiration. Naturally, INN provides a means of automatically expiring news articles.
The INN server uses a program called expire to delete expired news articles. The expire program in turn uses a file called /etc/news/expire.ctl to configure the rules that govern article expiration.
The syntax of /etc/news/expire.ctl is fairly simple. As with most configuration files, empty lines or lines beginning with the # character are ignored. The general idea is that you specify one rule per line. Each rule defines how article expiration will be performed on newsgroups matching a supplied pattern. The rule syntax looks like this:
pattern:modflag:keep:default:purge |
The following list describes the fields:
This field is a comma-delimited list of patterns matching names of newsgroups. The wildmat (3) routine is used to match these patterns. The last rule matching a newsgroup name is the one that is applied, so if you want to specify wildcard (*) rules, they should be listed first in this file.
This flag describes how this rule applies to moderated newsgroups. It can be coded with an M to mean that this rule applies only to moderated newsgroups, a U to mean that this rule applies only to unmoderated newsgroups, or an A to mean that this rule ignores the moderated status and applies to all groups.
This field allows you to specify the minimum time an article with an “Expires” header will be kept before it is expired. The units are days, and are a floating point, so you may specify values like 7.5 for seven-and-a-half days. You may also specify never if you wish articles to stay in a newsgroup forever.
This field is the most important. This field allows you to specify the time an article without an Expires header will be kept. Most articles won't have an Expires header. This field is coded in the same way as the keep field, with never meaning that articles without Expires headers will never be expired.
This field allows you to specify the maximum time an article with an Expires header will be kept before it is expired. The coding of this field is the same as for the keep field.
Our requirements are simple. We will keep all articles in all newsgroups for 14 days by default, and between 7 and 21 days for articles that have an Expires header. The rec.crafts.brewing.private newsgroup is our internal newsgroup, so we'll make sure we don't expire any articles from it:
# expire.ctl file for the Virtual Brewery # Expire all articles in 14 days by default, 7-21 days for those with # Expires: headers *:A:7:14:21 # This is a special internal newsgroup, which we will never expire. rec.crafts.brewing.private:A:never:never:never |
We will mention one special type of entry you may have in your /etc/news/expires.ctl file. You may have exactly one line that looks like this:
/remember/:days |
Just as with C News, INN can automatically process control messages. INN provides a powerful configuration mechanism to control what action will occur for each of a variety of control messages, and an access control mechanism to control who can initiate actions against which newsgroups.
The control.ctl file is fairly simple in structure. The syntax rules for this file are much the same as for the other INN configuration files. Lines beginning with # are ignored, lines may be continued using /, and fields are delimited by :.
When a control message is received, it is tested against each rule in turn. The last rule in the file that matches the message is the rule that will be used, so you should put any generic rules at the start of the file and more specific rules at the end of the file. The general syntax of the file is:
message:from:newsgroups:action |
The meanings of each of the fields are:
This is the name of the control message. Typical control messages are described later.
This is a shell-style pattern matching the email address of the person sending the message. The email address is converted to lowercase before comparison.
If the control message is newgroup or rmgroup, this field is a shell-style pattern matching the newsgroup created or removed.
This field specifies what action to take for any message matching the rule. There are quite a number of actions we can take; they are described in the next list.
The message field of each line can have one of the following values:
This message requests that news administrators resynchonrize their active newsgroups database against the list of newsgroups supplied in the control message.
This message requests the creation of a new newsgroup. The body of the control message should contain a short description of the purpose of the newsgroup to be created.
requests that a newsgroup be removed.
This message requests that the sys file of this news server be transmitted by mail to the originator of the control message. RFC-1036 states that it is a requirement of Usenet membership that this information be publicly available because it is used to keep the map of Usenet up to date.
This message requests that the hostname and version of news server software be returned to the originator of the control message.
This is a special coding that will match any control message.
The message field may include the following actions:
The requested command is performed. In many cases, a mail message will be sent to the administrator to advise them that the action has taken place.
This is the same as the doit action except that a log message will be written to the file log file. If the specified file is mail, the log entry is sent by email. If the specified file is the null string, the log message is written to /dev/null and is equivalent to using the unqualified doit action. If the file name begins with a / character, the name is taken to be an absolute filename for the logfile; otherwise, the specified name is translated to /var/log/news/file.log.
The requested command is performed if the command has an argument. If the command has no argument, the control message is ignored.
The requested command is ignored.
A log message is sent to the stderr output of the innd process. This is normally directed out to the /var/log/news/errlog file.
This is the same as a log action, except the logfile is specified as per the rules given for the doit=file action.
An email message is sent to the news administrator containing the requested command details. No other action takes place.
If an action begins with the string “verify-”, then the control message is authenticated using PGP (or GPG).[1]
So that you can see what a control.ctl file would look like in practice, here is a very short illustrative sample:
## Sample /etc/news/control.ctl ## ## Warning: You should not use this file, it is illustrative only. ## Control Message Handling all:*:*:mail checkgroups:*:*:mail ihave:*:*:drop sendme:*:*:drop sendsys:*:*:log=sendsys senduuname:*:*:log=senduuname version:*:*:log=version newgroup:*:*:mail rmgroup:*:*:mail ## Handle control messages for the eight most important news heirarchies ## COMP, HUMANITIES, MISC, NEWS, REC, SCI, SOC, TALK checkgroups:*:comp.*|humanities.*|misc.*|news.*|rec.*|sci.*|soc.*|talk.*:drop newgroup:*:comp.*|humanities.*|misc.*|news.*|rec.*|sci.*|soc.*|talk.*:drop rmgroup:*:comp.*|humanities.*|misc.*|news.*|rec.*|sci.*|soc.*|talk.*:drop checkgroups:[email protected]:*:verify-news.announce.newgroups newgroup:[email protected]:comp.*|misc.*|news.*:verify-news.announce.newgroups newgroup:[email protected]:rec.*|sci.*|soc.*:verify-news.announce.newgroups newgroup:[email protected]:talk.*|humanities.*:verify-news.announce.newgroups rmgroup:[email protected]:comp.*|misc.*|news.*:verify-news.announce.newgroups rmgroup:[email protected]:rec.*|sci.*|soc.*:verify-news.announce.newgroups rmgroup:[email protected]:talk.*|humanities.*:verify-news.announce.newgroups ## GNU ( Free Software Foundation ) newgroup:[email protected]:gnu.*:doit newgroup:news@*ai.mit.edu:gnu.*:doit rmgroup:[email protected]:gnu.*:doit rmgroup:news@*ai.mit.edu:gnu.*:doit ## LINUX (Newsfeed from news.lameter.com) checkgroups:[email protected]:linux.*:doit newgroup:[email protected]:linux.*:doit rmgroup:[email protected]:linux.*:doit |
| [1] | PGP and GPG are tools designed to authenticate or encrypt messages using public key techniques. GPG is the GNU free version of PGP. GPG may be found at http://www.gnupg.org/, and PGP may be found at http://www.pgp.com/. |