1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599
|
Welcome to INN 2.5!
Please read this document thoroughly before trying to install INN.
You'll be glad you did.
If you are upgrading from a major release of INN prior to 2.3, it is
recommended that you make copies of your old configuration files and use
them as guides for doing a clean installation and configuration of 2.5.
Many config files have changed, some have been added, and some have been
removed. You'll find it much easier to start with a fresh install than
to try to update your old installation. This is particularly true if
you're upgrading from a version of INN prior to 2.0.
If you are upgrading from INN 2.3 or later, you may be able to just
update the binaries, scripts, and man pages by running:
make update
after building INN and then comparing the new sample configuration files
with your current ones to see if anything has changed. If you take this
route, the old binaries and scripts will be saved with an extension of
".OLD" so that you can easily back out. Note that if you do not want to
have such backup copies, you can deactivate this behaviour with "make
BACKUP_OPTION='' update" instead of a mere "make update". Be sure to
configure INN with the same options that you used previously if you take
this approach (in particular, INN compiled with --enable-largefiles
can't read the data structures written by INN compiled without that
flag, and vice versa). If you don't remember what options you used but
you have your old build tree, look at the comments at the beginning of
config.status.
If you made ckpasswd setuid root so that you could use system passwords,
you'll have to do that again after "make update". (It's much better to
use PAM instead if you can.)
If you use "make update" to upgrade from a previous major release of
INN, also look at the new sample configuration files in samples to see
if there are new options of interest to you.
For more information about recent changes, see NEWS.
Supported Systems
As much as possible, INN is written in portable C and should work on any
Unix platform. It does, however, make extensive use of mmap(2) and
certain other constructs that may be poorly or incompletely implemented,
particularly on very old operating systems.
INN has been confirmed to work on the following operating systems:
AIX 4.3
FreeBSD 2.2.x and up
HP-UX 10.20 and up
Linux 2.x (tested with libc 5.4, glibc 2.0 and up)
Mac OS X 10.2 and up
NetBSD 1.6 and up
OpenBSD 2.8 and up
SCO 5.0.4 (tested with gcc 2.8.1, cc)
Solaris 2.5.x and up
UnixWare 7.1
UX/4800 R11 and up
If you have gotten INN working on an operating system other than the
ones listed above, please let us know at <inn-workers@lists.isc.org>.
Before You Begin
INN requires several other packages be installed in order to be fully
functional (or in some cases, to work at all):
* In order to build INN, you will need a C compiler that understands
ANSI C. If you are trying to install INN on an operating system that
doesn't have an ANSI C compiler (such as SunOS), installing gcc is
recommended. You can get it from <ftp://ftp.gnu.org/gnu/gcc/> or its
mirrors. INN is tested with gcc more thoroughly than with any other
compiler, so even if you have another compiler available, you may wish
to use gcc instead.
* Currently, in order to build INN, you will need an implementation of
yacc. GNU bison (from <ftp://ftp.gnu.org/gnu/bison/> or its mirrors)
will work fine. We hope to remove this requirement in the future.
* INN requires at least Perl 5.8.0 to build and to run several
subsystems. In order to process control messages, controlchan needs
the "MIME::Parser" module available from CPAN ("MIME-tools" in
modules/by-module/MIME/, for instance on <ftp://ftp.perl.org/>). This
Perl module has probably already been packaged for your distribution.
INN is tested primarily with newer versions of Perl, so it's generally
recommended that you install the latest stable distribution of Perl
before compiling INN. For instructions on obtaining and installing
Perl, see <http://www.perl.org/get.html>. Note that you may need to
use the same compiler and options (particularly large file support)
for Perl and INN.
If you're using a version of Perl prior to 5.6.0, you may need to make
sure that the Perl versions of your system header files have been
generated in order for "Sys::Syslog" to work properly (used by various
utility programs, including controlchan). To do this, run the
following two commands:
# cd /usr/include
# h2ph * sys/*
An even better approach is to install Perl 5.6.1 or later, which have
a fixed version of "Sys::Syslog" that doesn't require this (as well as
many other improvements over earlier versions of Perl).
* The INN Makefiles use the syntax "include FILE", rather than the
syntax expected by some BSDish systems of ".include <FILE>". If your
system expects the latter syntax, the recommended solution is to
install GNU make from <ftp://ftp.gnu.org/gnu/make/>. You may have GNU
make already installed as gmake, in which case using gmake rather than
make to build INN should be sufficient.
* If you want to enable support for authenticated control messages (this
is not required, but is highly recommended for systems carrying public
Usenet hierarchies) then you will need to install some version of PGP.
The recommended version is GnuPG, since it's actively developed,
supports OpenPGP, is freely available from <http://www.gnupg.org/> and
free to use for any purpose (in the US and elsewhere), and (as of
version 1.0.4 at least) supports the RSA signatures used by most
current control message senders.
* If you want to use either the Python embedded hooks, you'll need to
have a suitable version of Python installed. See doc/hook-python for
more information.
* Many of INN's optional features require other packages (primarily
libraries) be installed. If you wish to use any of these optional
features, you will need to install those packages first. Here is a
table of configure options enabling optional features and the software
and versions you'll need:
--with-perl Perl 5.004_03 or higher, 5.8.0+ recommended
--with-python Python 1.5.2 or higher, 2.5.0+ recommended
--with-berkeleydb Berkeley DB 4.4 or higher, 4.7+ recommended
--with-zlib zlib 1.x or higher
--with-openssl OpenSSL 0.9.6 or higher
--with-sasl Cyrus SASL 2.x or higher
--with-kerberos MIT Kerberos v5 1.2.x or higher
If any of these libraries (other than Perl or Python) are built shared
and installed in locations where your system doesn't search for shared
libraries by default, you may need to encode the paths to those shared
libraries in the INN binaries. For more information on shared library
paths, see <http://www.eyrie.org/~eagle/notes/rpath.html>.
For most systems, setting the environment variable LD_RUN_PATH to a
colon-separated list of additional directories in which to look for
shared libraries before building INN will be sufficient.
Unpacking the Distribution
Released versions of INN are available from
<ftp://ftp.isc.org/isc/inn/>. New major releases will be announced on
<inn-announce@lists.isc.org> (see README) when they're made.
If you want a more cutting-edge version, you can obtain current
snapshots from <ftp://ftp.isc.org/isc/inn/snapshots/>. These are
snapshots of the INN Subversion tree taken daily; there are two
snapshots made each night (one of the current development branch, and
one of the stable branch consisting of bug fixes to the previous major
release). They are stored in date format; in other words the snapshots
from April 6th, 2000, would be named inn-CURRENT-20000406.tar.gz and
inn-STABLE-20000406.tar.gz. Choose the newest file of whichever branch
you prefer. (Note that the downloading, configuring, and compiling
steps can be done while logged in as any user.)
The distribution is in gzip compressed tar archive format. To extract
it, execute:
gunzip -c <inn-src-file> | tar -xf -
Extracting the source distribution will create a directory named
inn-<version> or inn-<BRANCH>-<date> where the source resides.
Installing INN
Before beginning installation, you should make sure that there is a user
on your system named "news", and that this user's primary group is set
to a group called "news". You can change these with the
--with-news-user and --with-news-group options to configure (see below).
The home directory of this user should be set to the directory under
which you wish to install INN (/usr/local/news is the default and is a
good choice). This location will be set as *pathnews* in inn.conf. INN
will install itself as this user and group. You can change these if you
want, but these are the defaults and it's easier to stick with them on a
new installation.
By default, INN sends reports to the user "usenet". This account is
used for instance by controlchan (notifying any changes as for
newsgroups) or news.daily (sending Usenet daily reports). You can
change it with the --with-news-master option to configure (see below).
There is also the *mailto* keyword which can be given to news.daily in
order to modify the mail address to which these reports are sent.
WARNING: By default, INN installs various configuration files as
group-writeable, and in general INN is not hardened from a security
standpoint against an attack by someone who is already in the "news"
group. In general, you should consider membership in the news group as
equivalent to access to the news account. You should not rely on being
able to keep anyone with access to the news GID from converting that
into access to the news UID. The recommended configuration is to have
the only member of the group "news" be the user "news".
Installing INN so that all of its files are under a single directory
tree, rather than scattering binaries, libraries, and man pages
throughout the file system, is strongly recommended. It helps keep
everything involved in the operation of INN together as a unit and will
make the installation instructions easier to follow.
As a side note, whenever doing anything with a running news server,
first log in as this user. That way, you can ensure that all files
created by any commands you run are created with the right ownership to
be readable by the server. Particularly avoid doing anything in the
news spool itself as root, and make sure you fix the ownership of any
created files if you have to. INN doesn't like files in the news spool
owned by a user other than the news user. However, since certain
binaries need to be setuid root, indiscriminate use of "chown news" is
not the solution. (If you don't like to log in to system accounts,
careful use of "chmod g+s" on directories and a umask of 002 or 007 may
suffice.)
INN uses GNU autoconf and a generated configure script to make
configuration rather painless. Unless you have a rather abnormal setup,
configure should be able to completely configure INN for your system.
If you want to change the defaults, you can invoke the configure script
with one or more command line options. Type:
./configure --help
for a full list of supported options. Some of the most commonly used
options are:
--prefix=PATH
Sets the installation prefix for INN. The default is
/usr/local/news. All of INN's programs and support files will be
installed under this directory. This should match the home
directory of your news user (it will make installation and
maintenance easier). It is not recommended to set this to /usr; if
you decide to do that anyway, make sure to point INN's temporary
directory at a directory that isn't world-writeable (see
--with-tmp-dir below).
--with-db-dir=PATH
Sets the prefix for INN database files. The default is PREFIX/db,
where PREFIX is /usr/local/news unless overridden with the option
above. The history and active files will be stored in this
directory, and writes to those files are an appreciable percentage
of INN's disk activity. The history file can also be quite large
(requiring up to 2 GB or more during nightly expire), so this is a
common portion of INN to move to a different file system.
--with-spool-dir=PATH
Sets the prefix for the news spool (when using any storage method
other than CNFS) and the overview spool. The default is
PREFIX/spool. This is another common portion of INN to move to a
different file system (often /news).
--with-tmp-dir=PATH
Sets the directory in which INN will create temporary files. This
should under no circumstances be the same as the system temporary
directory or otherwise be set to a world-writeable directory, since
INN doesn't take care to avoid symlink attacks and other security
problems possible with a world-writeable directory. This directory
should be reserved for the exclusive use of INN and only writeable
by the news user. Usage is generally light, so this is unlikely to
need a separate partition.
It's also possible to set the paths for most other sections of the
INN installation independently; see "./configure --help" and look
for the --with-*-dir=PATH options.
--enable-largefiles
Enables large file support. This is not enabled by default, even on
platforms that support it, because it changes the format of INN's
on-disk databases (making it difficult to upgrade an earlier INN
installation) and can significantly increase the size of some of the
history database files. Large file support is not necessary unless
your history database is so large that it exceeds 2 GB or you want
to use CNFS buffers larger than 2 GB.
The history, tradindexed and buffindexed overview, and timecaf
databases written by an INN built with this option are incompatible
with those written by an INN without this option. (CNFS buffers are
compatible.)
--enable-tagged-hash
Use tagged hash table for the history database. The tagged hash
format uses much less memory but is somewhat slower. This option is
recommended if you have less than 256 MB of RAM on your news server.
If you install INN without tagged hash (the default) and expire
takes an excessive amount of time, you should make sure the RAM in
your system satisfies the following formula:
ram > 10 * tablesize
ram: Amount of system RAM (in bytes)
tablesize: 3rd field on the 1st line of history.dir (bytes)
If you don't have at least that much RAM, try rebuilding INN with
tagged hash enabled.
NOTE: --enable-largefiles cannot be used with --enable-tagged-hash.
--with-perl
Enables support for embedded Perl, allowing you to install filter
scripts written in Perl. Highly recommended, because many really
good spam filters are written in Perl. See doc/hook-perl for all
the details.
Even if you do not use this option, INN still requires Perl as
mentioned above.
--with-python
Enables support for Python, allowing you to install filter and
authentication scripts written in Python. You will need
Python 1.5.2 or later installed on your system to enable this
option. See doc/hook-python for all the details. Note that there
is an incompatibility between INN and Python 2.0 when Python is
compiled with cycle garbage collection; this problem was reported
fixed in Python 2.1a1.
--with-innd-port=PORT
By default, innbind(8) refuses to bind to any port under 1024 other
than 119, 433 and 563 for security reasons (to prevent attacks on
rsh(1)-based commands and replacing standard system daemons). If
you want to run innd on a different port under 1024, you'll need to
tell configure what port you intend to use. (You'll also still need
to set the port number in inn.conf or give it to innd on the command
line.)
--with-syslog-facility=FACILITY
Specifies the syslog facility that INN programs should log to. The
default is LOG_NEWS unless configure detects that your system
doesn't understand that facility, in which case it uses LOG_LOCAL1.
This flag overrides the automatic detection. Be sure to specify a
facility not used by anything else on your system (one of LOG_LOCAL0
through LOG_LOCAL7, for example).
--enable-libtool
INN has optional support for libtool to generate shared versions of
INN's libraries. This can significantly decrease the size of the
various binaries that come with a complete INN installation. You
can also choose to use libtool even when only building static
libraries; a libtool build may be somewhat more portable on weird
systems. libtool builds aren't the default because they take
somewhat longer. See "./configure --help" for the various available
options related to libtool builds.
Please note that INN's shared library interface is not stable and
may change drastically in future releases. For this reason, it's
also not properly versioned and won't be until some degree of
stability is guaranteed, and the relevant header files are not
installed. Only INN should use INN's shared libraries, and you
should only use the shared libraries corresponding to the version of
INN that you're installing.
Also, when updating an existing version of INN, INN tries to save
backup copies of all files but man pages so that you can revert to
the previous installed version. Unfortunately, when using shared
libraries, this confuses ldconfig on some systems (such as Linux)
and the symbolic links for the libraries may point to the ".OLD"
versions. If this happens, you can either fix the links by hand or
remove the ".OLD" versions and re-run ldconfig.
--enable-uucp-rnews
If this option is given to configure, rnews will be installed setuid
"news", owned by group "uucp", and mode 4550. This will allow the
UUCP subsystem to run rnews to process UUCP batches of news
articles. Prior to INN 2.3, installing rnews setuid "news" was
standard; since most sites no longer use UUCP, it is no longer the
default as of INN 2.3 and must be requested at configure time. You
probably don't want to use this option unless your server accepts
UUCP news batches.
--enable-setgid-inews
If this option is given to configure, inews will be installed setgid
"news" and world-executable so that non-privileged users on the news
server machine can use inews to post articles locally (somewhat
faster than opening a new network connection). For standalone news
servers, by far the most common configuration now, there's no need
to use this option; even if you have regular login accounts on your
news server, INN's inews can post fine via a network connection to
your running news server and doesn't need to use the local socket
(which is what setgid enables it to do). Installing inews setgid
was the default prior to INN 2.3.
--with-berkeleydb=PATH
Enables support for Berkeley DB (4.4 or higher), which means that it
will then be possible to use the ovdb overview method if you wish.
Enabling this configure option doesn't mean you'll be required to
use ovdb, but it does require that Berkeley DB be installed on your
system (including the header files, not just the runtime libraries).
If a path is given, it sets the installed directory of Berkeley DB
(configure will search for it in some standard locations, but if you
have it installed elsewhere, you may need this option).
--with-zlib=PATH
The ovdb storage method can optionally use compression. If
--with-berkeleydb is set, and configure finds a suitable Berkeley DB
version, this option defaults to "yes", otherwise the default is
"no". If you have zlib but it is not installed under /usr or
/usr/local, you must specify the directory where it is installed.
--with-openssl=PATH
Enables support for TLS/SSL for news reading, which means it will be
possible to have TLS encrypted NNTP connections between your server
and newsreaders. This option requires OpenSSL be installed on your
system (including the header files, not just the runtime libraries).
If a path is given, it sets the installed directory of OpenSSL.
After compiling and installing INN with this option, you'll still
need to make a certificate and private key to use TLS. See below
for details on how to do that.
--enable-ipv6
Enables support for IPv6 in innd, innfeed, nnrpd, and several of the
supporting programs. This option should be considered developmental
at present. For more information see doc/IPv6-info (and if you have
any particularly good or bad news to report, please let us know at
<inn-workers@lists.isc.org>).
For the most common installation, a standalone news server, a suggested
set of options is:
./configure --with-perl
provided that you have the necessary version of Perl installed.
(Compiling with an embedded Perl interpreter will allow you to use one
of the available excellent spam filters if you so choose.)
If the configure program runs successfully, then you are ready to build
the distribution. From the root of the INN source tree, type:
make
At this point you can step away from the computer for a little while and
have a quick snack while INN compiles. On a decently fast system it
should only take five or ten minutes at the most to build.
Once the build has completed successfully, you are ready to install INN
into its final home. Type:
make install
Normally, you will need to run this command as root so that INN can
create the directories it needs, change ownerships (if you did not
compile as the news user) and install a setuid program needed to raise
resource limits and allow innd to bind to ports under 1024. This step
will install INN under the install directory (/usr/local/news, known as
*pathnews* in inn.conf, unless you specified something else to the
configure script).
Exceptionally, if you are installing INN into a directory writable by
the news user, you can run "make install" as the configured news user.
The resulting INN installation won't be able to use ports below 1024
(including the default NNTP port of 119) unless you then run "make
install-root" as root, which will install only the setuid helper
program.
If you are configuring TLS/SSL support for newsreaders, you must make a
certificate and private key at least once. Type:
make cert
as root in order to do this.
You are now ready for the really fun part: configuring your copy of
INN!
Choosing an Article Storage Format
The first thing to decide is how INN should store articles on your
system. There are four different methods for you to choose from, each
of which has its own advantages and disadvantages. INN can support all
four at the same time, so you can store certain newsgroups in one method
and other newsgroups in another method.
The supported storage formats are:
tradspool
This is the storage method used by all versions of INN previous to
2.0. Articles are stored as individual text files whose names are
the same as the article number. The articles are divided up into
directories based on the newsgroup name. For example, article 12345
in news.software.nntp would be stored as news/software/nntp/12345
relative to the root of the article spool.
Advantages: Widely used and well-understood storage mechanism, can
read article spools written by older versions of INN, compatible
with all third-party INN add-ons, provides easy and direct access to
the articles stored on your server and makes writing programs that
fiddle with the news spool very easy, and gives you fine control
over article retention times.
Disadvantages: Takes a very fast file system and I/O system to keep
up with current Usenet traffic volumes due to file system overhead.
Groups with heavy traffic tend to create a bottleneck because of
inefficiencies in storing large numbers of article files in a single
directory. Requires a nightly expire program to delete old articles
out of the news spool, a process that can slow down the server for
several hours or more.
timehash
Articles are stored as individual files as in tradspool, but are
divided into directories based on the arrival time to ensure that no
single directory contains so many files as to cause a bottleneck.
Advantages: Heavy traffic groups do not cause bottlenecks, and fine
control of article retention time is still possible.
Disadvantages: The ability to easily find all articles in a given
newsgroup and manually fiddle with the article spool is lost, and
INN still suffers from speed degradation due to file system overhead
(creating and deleting individual files is a slow operation).
timecaf
Similar to timehash, articles are stored by arrival time, but
instead of writing a separate file for each article, multiple
articles are put in the same file.
Advantages: Roughly four times faster than timehash for article
writes, since much of the file system overhead is bypassed, while
still retaining the same fine control over article retention time.
Disadvantages: Even worse than timehash, and similar to CNFS
(below), using this method means giving up all but the most careful
manually fiddling with your article spool. As one of the newer and
least widely used storage types, timecaf has not been as thoroughly
tested as the other methods.
cnfs
CNFS stores articles sequentially in pre-configured buffer files.
When the end of the buffer is reached, new articles are stored from
the beginning of the buffer, overwriting older articles.
Advantages: Blazingly fast because no file creations or deletions
are necessary to store an article. Unlike all other storage
methods, does not require manual article expiration; old articles
are deleted to make room for new ones when the buffers get too full.
Also, with CNFS your server will never throttle itself due to a full
spool disk, and groups are restricted to just the buffer files you
give them so that they can never use more than the amount of disk
space you allocate to them.
Disadvantages: Article retention times are more difficult to
control because old articles are overwritten automatically. Attacks
on Usenet, such as flooding or massive amounts of spam, can result
in wanted articles expiring much faster than you intended (with no
warning).
Some general recommendations: If you are installing a transit news
server (one that just accepts news and sends it out again to other
servers and doesn't support any readers), use CNFS exclusively and don't
worry about any of the other storage methods. Otherwise, put
high-volume groups and groups whose articles you don't need to keep
around very long (binaries groups, *.jobs*, news.lists.filters, etc.) in
CNFS buffers, and use timehash, timecaf, or tradspool (if you have a
fast I/O subsystem or need to be able to go through the spool manually)
for everything else. You'll probably find it most convenient to keep
special hierarchies like local hierarchies and hierarchies that should
never expire in tradspool.
Choosing an Overview Storage Mechanism
If your news server will be supporting readers, you'll also need to
choose an overview storage mechanism (by setting *ovmethod* in
inn.conf). There are three overview mechanisms to choose from:
tradindexed
It is very fast for readers, but it has to update two files for each
incoming article and can be quite slow to write.
buffindexed
It can keep up with a large feed more easily, since it uses large
buffers to store all overview information, but it's somewhat slower
for readers (although not as slow as the unified overview in
INN 2.2). You will need to create the buffers for it to use (very
similar to creating CNFS buffers) and list the available buffers in
buffindexed.conf. See buffindexed.conf(5) for more information.
ovdb
It stores overview data in a Berkeley DB database; it's fast and
very robust, but may require more disk space. See the ovdb(5) man
page for more information on it.
Configuring INN
All documentation from this point on assumes that you have set up the
news user on your system as suggested in "Installing INN" so that the
root of your INN installation is ~news (*pathnews* in inn.conf). If
you've moved things around by using options with "configure", you'll
need to adjust the instructions to account for that.
All of INN's configuration files are located in *pathetc in inn.conf*.
Unless noted otherwise, any files referred to below are in this
directory. When you first install INN, a sample of each file
(containing lots of comments) is installed in *pathetc*; refer to these
for concrete examples of everything discussed in this section.
All of INN's configuration files, all of the programs that come with it,
and some of its library routines have documentation in the form of man
pages. These man pages were installed in *pathnews*/share/man as part
of the INN installation process and are the most complete reference to
how INN works. You're strongly encouraged to refer to the man pages
frequently while configuring INN, and for quick reference afterwards.
Any detailed questions about individual configuration files or the
behavior of specific programs should be answered in them. You may want
to add *pathnews*/share/man to your MANPATH environment variable;
otherwise, you may have to use a command like:
man -M <pathnews in inn.conf>/share/man inn.conf
to see the inn.conf(5) man page (for example).
Before we begin, it is worth mentioning the wildmat pattern matching
syntax used in many configuration files. These are simple wildcard
matches using the asterisk ("*") as the wildcard character, much like
the simple wildcard expansion used by Unix shells.
In many cases, wildmat patterns can be specified in a comma-separated
list to indicate a list of newsgroups. When used in this fashion, each
pattern is checked in turn to see if it matches, and the last pattern in
the line that matches the group name is used. Patterns beginning with
"!" mean to exclude groups matching that pattern. For example:
*,!comp.*,comp.os.*
In this case, we're saying we match everything ("*"), except that we
don't match anything under comp ("!comp.*"), unless it is actually under
the comp.os hierarchy ("comp.os.*"). This is because non-comp groups
will match only the first pattern (so we want them), comp.os groups will
match all three patterns (so we want them too, because the third pattern
counts in this case), and all other comp groups will match the first and
second patterns and will be excluded by the second pattern.
Some uses of wildmat patterns also support "poison" patterns (patterns
starting with "@"). These patterns behave just like "!" patterns when
checked against a single newsgroup name. Where they become special is
for articles crossposted to multiple newsgroups; normally, such an
article will be considered to match a pattern if any of the newsgroups
it is posted to matches the pattern. If any newsgroup the article is
posted to matches an expression beginning with "@", however, that
article will not match the pattern even if other newsgroups to which it
was posted match other expressions. For instance, if an article is
crossposted between misc.foo and misc.bar, the pattern:
misc.*,!misc.bar
will match that article whereas the pattern:
misc.*,@misc.bar
will not match that article. An article posted only to misc.bar will
fail to match either pattern.
See uwildmat(3) for full details on wildmat patterns.
In all INN configuration files, blank lines and lines beginning with a
"#" symbol are considered comments and are ignored. Be careful, not all
files permit comments to begin in the middle of the line.
inn.conf
The first, and most important file is inn.conf. This file is organized
as a series of parameter-value pairs, one per line. The parameter is
first, followed by a colon and one or more whitespace characters, and
then the value itself. For some parameters the value is a string or a
number; for others it is true or false. (True values can be written as
"yes", "true", or "on", whichever you prefer. Similarly, false values
can be written as "no", "false", or "off".)
inn.conf contains dozens of changeable parameters (see inn.conf(5) for
full details), but only a few really need to be edited during normal
operation:
allownewnews
If set to true then INN will support the NEWNEWS command for news
readers. While this can be an expensive operation, its speed has
been improved considerably as of INN 2.3 and it's probably safe to
turn on without risking excessive server load. The default is true.
(Note that the *access* setting in readers.conf overrides this
value; see readers.conf(5) for more details.)
complaints
Used to set the value of the X-Complaints-To: header, which is added
to all articles posted locally. The usual value would be something
like "abuse@example.com" or "postmaster@example.com". If not
specified, the newsmaster e-mail address will be used.
hiscachesize
The amount of memory (in kilobytes) to allocate for a cache of
recently used history file entries. Setting this to 0 disables
history caching. History caching can greatly increase the number of
articles per second that your server is capable of processing. A
value of 256 is a good default choice.
logipaddr
If set to true (the default), INN will log the IP address (or
hostname, if the host is listed in incoming.conf with a hostname) of
the remote host from which it received an article. If set to false,
the trailing Path: header entry is logged instead. If you are using
controlchan (see below) and need to process ihave/sendme control
messages (this is very, very unlikely, so if you don't know what
this means, don't worry about it), make sure you set this to false,
since controlchan needs a site name, not an IP address.
organization
Set this to the name of your organization as you want it to appear
in the Organization: header of all articles posted locally and not
already containing that header. This will be overridden by the
value of the ORGANIZATION environment variable (if it exists). If
neither this parameter nor the environment variable is set, no
Organization: header will be added to posts which lack one.
pathhost
This is the name of your news server as you wish it to appear in the
Path: header of all postings which travel through your server (this
includes local posts and incoming posts that you forward out to
other sites). If this parameter is unspecified, the fully-qualified
domain name (FQDN) of the machine will be used instead. Please use
the FQDN of your server or an alias for your server unless you have
a very good reason not to; a future version of the news RFCs may
require this.
rlimitnofile
If set to a non-negative value (the default is -1), INN (both innd
and innfeed) will try to raise the maximum number of open file
descriptors to this value when it starts. This may be needed if you
have lots of incoming and outgoing feeds. Note that the maximum
value for this setting is very operating-system-dependent, and you
may have to reconfigure your system (possibly even recompile your
kernel) to increase it. See "File Descriptor Limits" for complete
details.
There are tons of other possible settings; you may want to read through
inn.conf(5) to get a feel for your options. Don't worry if you don't
understand the purpose of most of them right now. Some of the settings
are only needed for very obscure things, and with more experience
running your news server the rest will make more sense.
newsfeeds
newsfeeds determines how incoming articles are redistributed to your
peers and to other INN processes. newsfeeds is very versatile and
contains dozens of options; we will touch on just the basics here. The
man page contains more detailed information.
newsfeeds is organized as a series of feed entries. Each feed entry is
composed of four fields separated by colons. Entries may span multiple
lines by using a backslash ("\") to indicate that the next line is a
continuation of the current line. (Note that comments don't interact
with backslashes in the way you might expect. A commented-out line
ending in a backslash will still be considered continued on the next
line, possibly resulting in more commented out than you intended or
bizarre syntax errors. In general, it's best to avoid commenting out
lines in the middle of continuation lines.)
The first field in an entry is the name of the feed. It must be unique,
and for feeds to other news servers it is usually set to the actual
hostname of the remote server (this makes things easier). The name can
optionally be followed by a slash ("/") and a comma-separated exclude
list. If the feed name or any of the names in the exclude list appear
in the Path: header of an article, then that article will not be
forwarded to the feed as it is assumed that it has passed through that
site once already. The exclude list is useful when a news server's
hostname is not the same as what it puts in the Path: header of its
articles, or when you don't want a feed to receive articles from a
certain source.
The second field specifies a set of desired newsgroups and distribution
lists, given as newsgroup-pattern/distribution-list. The distribution
list is not described here; see newsfeeds(5) for information (it's not
used that frequently in practice). The newsgroup pattern is a
wildmat-style pattern list as described above (supporting "@").
The third field is a comma-separated list of flags that determine both
the type of feed entry and sets certain parameters for the entry. See
newsfeeds(5) for information on the flag settings; you can do a
surprising amount with them. The three most common patterns, and the
ones mainly used for outgoing news feeds to other sites, are "Tf,Wnm"
(to write out a batch file of articles to be sent, suitable for
processing by nntpsend and innxmit), "Tm" (to send the article to a
funnel feed, used with innfeed), and "Tc,Wnm*" (to collect a funnel feed
and send it via a channel feed to an external program, used to send
articles to innfeed).
The fourth field is a multi-purpose parameter whose meaning depends on
the settings of the flags in the third field. To get a feel for it
using the examples above, for file feeds ("Tf") it's the name of the
file to write, for funnel feeds ("Tm") it's the name of the feed entry
to funnel into, and for channel feeds ("Tc") it's the name of the
program to run and feed references to articles.
Now that you have a rough idea of the file layout, we'll begin to add
the actual feed entries. First, we'll set up the special "ME" entry.
This entry is required and serves two purposes: the newsgroup pattern
specified here is prepended to the newsgroup list of all other feeds,
and the distribution pattern for this entry determines what
distributions (from the Distribution: header of incoming articles) are
accepted from remote sites by your server. The example in the sample
newsfeeds file is a good starting point. If you are going to create a
local hierarchy that should not be distributed off of your system, it
may be useful to exclude it from the default subscription pattern, but
default subscription patterns are somewhat difficult to use right so you
may want to just exclude it specifically from every feed instead.
The "ME" entry tends to confuse a lot of people, so this point is worth
repeating: the newsgroup patterns set the default subscription for
*outgoing* feeds, and the distribution patterns set the acceptable
Distribution: header entries for *incoming* articles. This is confusing
enough that it may change in later versions of INN.
There are two basic ways to feed articles to remote sites. The most
common for large sites and particularly for transit news servers is
innfeed(8), which sends articles to remote sites in real time (the
article goes out to all peers that are supposed to receive it
immediately after your server accepts it). For smaller sites,
particularly sites where the only outgoing messages will be locally
posted articles, it's more common to batch outgoing articles and send
them every ten minutes or so from cron using nntpsend(8) and innxmit(8).
Batching gives you more control and tends to be extremely stable and
reliable, but it's much slower and can't handle high volume very well.
Batching outgoing posts is easy to set up; for each peer, add an entry
to newsfeeds that looks like:
remote.example.com/news.example.com\
:<newsgroups>\
:Tf,Wnm:
where <newsgroups> is the wildmat pattern for the newsgroups that site
wants. In this example, the actual name of the remote site is
"remote.example.com", but it puts "news.example.com" in the Path:
header. If the remote site puts its actual hostname in the Path:
header, you won't need the "/news.example.com" part.
This entry will cause innd to write out a file in *pathspool*/outgoing
named remote.example.com and containing the Message-ID and storage token
of each message to send to that site. (The storage token is INN's
internal pointer to where an article is stored; to retrieve an article
given its storage token, use sm(8)). innxmit knows how to read files of
this format and send those articles to the remote site. For information
on setting it up to run periodically, see "Setting Up the Cron Jobs"
below. You will also need to set up a config file for nntpsend; see the
man page for nntpsend.ctl(5) for more information.
If instead you want to use innfeed to send outgoing messages
(recommended for sites with more than a couple of peers), you need some
slightly more complex magic. You still set up a separate entry for each
of your peers, but rather than writing out batch files, they all
"funnel" into a special innfeed entry. That special entry collects all
of the separate funnel feeds and sends the data through a special sort
of feed to an external program (innfeed in this case); this is a
"channel" feed.
First, the special channel feed entry for innfeed that will collect all
the funnel feeds:
innfeed!\
:!*\
:Tc,Wnm*:<pathbin in inn.conf>/innfeed -y
(adjust the path to innfeed(8) if you installed it elsewhere). Note
that we don't feed this entry any articles directly (its newsgroup
pattern is "!*"). Note also that the name of this entry ends in an
exclamation point. This is a standard convention for all special feeds;
since the delimiter for the Path: header is "!", no site name containing
that character can ever match the name of a real site.
Next, set up entries for each remote site to which you will be feeding
articles. All of these entries should be of the form:
remote.example.com/news.example.com\
:<newsgroups>\
:Tm:innfeed!
specifying that they funnel into the "innfeed!" feed. As in the
previous example for batching, "remote.example.com" is the actual name
of the remote peer, "news.example.com" is what it puts in the Path:
header (if different than the actual name of the server), and
<newsgroups> is the wildmat pattern of newsgroups to be sent.
As an alternative to NNTP, INN may also feed news out to an IMAP server,
by using imapfeed(8), which is almost identical to innfeed. The feed
entry for this is as follows:
imapfeed!\
:!*\
:Tc,Wnm*,S16384:<pathbin in inn.conf>/imapfeed
And set up entries for each remote site like:
remote.example.com/news.example.com\
:<newsgroups>\
:Tm:imapfeed!
For more information on imapfeed, look at the innfeed/imap_connection.c
file. For more information on IMAP in general, see RFC 3501.
Finally, there is a special entry for controlchan(8), which processes
newsgroup control messages, that should always be in newsfeeds unless
you never want to honor any control messages. This entry should look
like:
controlchan!\
:!*,control,control.*,!control.cancel\
:AC,Tc,Wnsm:<pathbin in inn.conf>/controlchan
(modified for the actual path to controlchan if you put it somewhere
else). See "Processing Newsgroup Control Messages" for more details.
For those of you upgrading from earlier versions of INN, note that the
functionality of overchan(8) and crosspost is now incorporated into INN
and neither of those programs is necessary. Although crosspost is no
longer shipped with INN (and will not be working if used), you can still
use overchan if you make sure to set *useoverchan* to true in inn.conf
so that innd doesn't write overview data itself, but be careful: innd
may accept articles faster than overchan can process the data.
incoming.conf
incoming.conf file specifies which machines are permitted to connect to
your host and feed it articles. Remote servers you peer with should be
listed here. Connections from hosts not listed in this file will (if
you don't allow readers) be rejected or (if you allow readers) be handed
off to nnrpd and checked against the access restrictions in
readers.conf.
Start with the sample incoming.conf and, for each remote peer, add an
entry like:
peer remote.example.com { }
This uses the default parameters for that feed and allows incoming
connections from a machine named "remote.example.com". If that peer
could be connecting from several different machines, instead use an
entry like:
peer remote.example.com {
hostname: "remote.example.com, news.example.com"
}
This will allow either "remote.example.com" or "news.example.com" to
feed articles to you. (In general, you should add new peer lines for
each separate remote site you peer with, and list multiple host names
using the *hostname* key if one particular remote site uses multiple
servers.)
You can restrict the newsgroups a remote site is allowed to send you,
using the same sort of pattern that newsfeeds(5) uses. For example, if
you want to prevent "example.com" hosts from sending you any articles in
the "local.*" hierarchy (even if they're crossposted to other groups),
change the above to:
peer remote.example.com {
patterns: "*, @local.*"
hostname: "remote.example.com, news.example.com"
}
Note, however, that restricting what a remote side can send you will
*not* reduce your incoming bandwidth usage. The remote site will still
send you the entire article; INN will just reject it rather than saving
it to disk. To reduce bandwidth, you have to contact your peers and ask
them not to send you the traffic you don't want.
There are various other things you can set, including the maximum number
of connections the remote host will be allowed. See incoming.conf(5)
for all the details.
Note for those familiar with older versions of INN: this file replaces
the old hosts.nntp configuration file.
cycbuff.conf
cycbuff.conf is only required if CNFS is used. If you aren't using
CNFS, skip this section.
CNFS stores articles in logical objects called *metacycbuffs*. Each
metacycbuff is in turn composed of one or more physical buffers called
*cycbuffs*. As articles are written to the metacycbuff, each article is
written to the next cycbuff in the list in a round-robin fashion (unless
"sequential" mode is specified, in which case each cycbuff is filled
before moving on to the next). This is so that you can distribute the
individual cycbuffs across multiple physical disks and balance the load
between them.
There are two ways to create your cycbuffs:
1. Use a block device directly. This will probably give you the most
speed since it avoids the file system overhead of large files, but
it requires your OS support mmap(2) on a block device. Solaris
supports this, as do late Linux 2.4 kernels. FreeBSD does not at
last report. Also on many PC-based Unixes it is difficult to create
more than eight partitions, which may limit your options.
2. Use a real file on a filesystem. This will probably be a bit slower
than using a block device directly, but it should work on any Unix
system.
If you're having doubts, use option #2; it's easier to set up and should
work regardless of your operating system. More information about the
creation of these cycbuffs can be found in cycbuff.conf(5) man page.
Now you need to decide on the sizes of your cycbuffs and metacycbuffs.
You'll probably want to separate the heavy-traffic groups
("alt.binaries.*" and maybe a few other things like "*.jobs*" and
"news.lists.filters") into their own metacycbuff so that they don't
overrun the server and push out articles on the more useful groups. If
you have any local groups that you want to stay around for a while then
you should put them in their own metacycbuff as well, so that they don't
get pushed out by other traffic. (Or you might store them in one of the
other storage methods, such as tradspool.)
For each metacycbuff, you now need to determine how many cycbuffs will
make up the metacycbuff, the size of those cycbuffs, and where they will
be stored. Also, when laying out your cycbuffs, you will want to try to
arrange them across as many physical disks as possible (or use a striped
disk array and put them all on that).
In order to use any cycbuff larger than 2 GB, you need to build INN with
the --enable-largefiles option. See "Installing INN" for more
information and some caveats.
For each cycbuff you will be creating, add a line to cycbuff.conf like
the following:
cycbuff:NAME:/path/to/buffer:SIZE
NAME must be unique and must be at most seven characters long.
Something simple like "BUFF00", "BUFF01", etc. is a decent choice, or
you may want to use something that includes the SCSI target and slice
number of the partition. SIZE is the buffer size in kilobytes (if
you're trying to stay under 2 GB, keep your sizes below 2097152).
Now, you need to tell INN how to group your cycbuffs into metacycbuffs.
This is similar to creating cycbuff entries:
metacycbuff:BUFFNAME:CYCBUF1,CYCBUF2,CYCBUF3
BUFFNAME is the name of the metacycbuff and must be unique and at most
eight characters long. These should be a bit more meaningful than the
cycbuff names since they will be used in other config files as well.
Try to name them after what will be stored in them; for example, if this
metacycbuff will hold alt.binaries postings, "BINARIES" would be a good
choice. The last part of the entry is a comma-separated list of all of
the cycbuffs that should be used to build this metacycbuff. Each
cycbuff should only appear in one metacycbuff line, and all metacycbuff
lines must occur after all cycbuff lines in the file.
If you want INN to fill each cycbuff before moving on to the next one
rather than writing to them round-robin, add ":SEQUENTIAL" to the end of
the metacycbuff line. This may give noticeably better performance when
using multiple cycbuffs on the same spindle (such as partitions or
slices of a larger disk), but will probably give worse performance if
your cycbuffs are spread out across a lot of spindles.
By default, CNFS data is flushed to disk every 25 articles. If you're
running a small server with a light article load, this could mean losing
quite a few articles in a crash. You can change this interval by adding
a cycbuffupdate: line to your cycbuff.conf file; see cycbuff.conf(5) for
more details.
Finally, you have to create the cycbuffs. See "Creating the Article
Spool (CNFS only)" for more information on how to do that.
storage.conf
storage.conf determines where incoming articles will be stored (what
storage method, and in the case of CNFS, what metacycbuff). Each entry
in the file defines a storage class for articles. The first matching
storage class is used to store the article; if no storage class matches,
INN will reject that article. (This is almost never what you want, so
make sure this file ends in a catch-all entry that will match
everything.)
A storage class definition looks like this:
method <methodname> {
newsgroups: <wildmat>
class: <storage_class>
size: <minsize>[,<maxsize>]
expires: <mintime>[,<maxtime>]
options: <options>
exactmatch: <bool>
}
<methodname> is the name of the storage method to use to store articles
in this class ("cnfs", "timehash", "timecaf", "tradspool", or the
special method "trash" that accepts the article and throws it away).
The first parameter is a wildmat pattern in the same format used by the
newsfeeds(5) file, and determines what newsgroups are accepted by this
storage class.
The second parameter is a unique number identifying this storage class
and should be between 0 and 255. It can be used to control article
expiration, and for timehash and timecaf will set the top-level
directory in which articles accepted by this storage class are stored.
The easiest way to deal with this parameter is to just number all
storage classes in storage.conf sequentially. The assignment of a
particular number to a storage class is arbitrary but *permanent* (since
it is used in storage tokens).
The third parameter can be used to accept only articles in a certain
size range into this storage class. A <maxsize> of 0 (or a missing
<maxsize>) means no upper limit (and of course a <minsize> of 0 would
mean no lower limit, because all articles are more than zero bytes
long). If you don't want to limit the size of articles accepted by this
storage class, leave this parameter out entirely.
The fourth parameter you probably don't want to use lets you assign
storage classes based on the Expires: header of incoming articles. The
exact details are in storage.conf(5). It's very easy to use this
parameter incorrectly; leave it out entirely unless you've read the man
page and know what you're doing.
The fifth parameter is the options parameter. Currently only CNFS uses
this field; it should contain the name of the metacycbuff used to store
articles in this storage class.
The sixth parameter is a boolean which is false by default: any
non-zero number of matching newsgroups is sufficient, provided no
newsgroup matches a poison wildmat. If it is set to true, all the
newsgroups in the Newsgroups: header of incoming articles will be
examined to see if they match the newsgroups wildmat pattern.
If you're using CNFS exclusively, just create one storage class for each
metacycbuff that you have defined in cycbuff.conf and set the newsgroups
pattern according to what newsgroups should be stored in that buffer.
If you're using timehash or timecaf, the storage class IDs are used to
store articles in separate directory trees, which you can take advantage
of to put particular storage classes on different disks. Also,
currently storage class is the only way to specify expiration time, so
you will need to divide up your newsgroups based on how long you want to
retain articles in those groups and create a storage class for each such
collection of newsgroups. Make note of the storage class IDs you assign
as they will be needed when you edit expire.ctl a bit later.
expire.ctl
expire.ctl sets the expiration policy for articles stored on the server.
Be careful, since the default configuration will expire most articles
after 15 days; in most circumstances this deletion is *permanent*, so
read this whole section carefully if you want to keep local hierarchies
forever. (See archive(8) for a way to automate backups of important
articles.)
Only one entry is required for all storage classes; it looks like:
/remember/:11
This entry says how long to keep the message-IDs for articles that have
already expired in the history file so that the server doesn't accept
them again. Occasionally, fairly old articles will get regurgitated
somewhere and offered to you again, so even after you've expired
articles from your spool, you want to keep them around in your history
file for a little while to ensure you don't get duplicates.
INN will reject any articles more than a certain number of days old (the
*artcutoff* parameter in inn.conf, defaulting to 10); the number on the
"/remember/" line should be one more than that number in order to take
into account articles whose posting date is one day into the future.
CNFS makes no further use of expire.ctl, since articles stored in CNFS
buffers expire automatically when the buffer runs out of free space (but
see the "-N" option in expireover(8) if you really want to expire them
earlier). For other storage methods, there are two different syntaxes
of this file, depending on *groupbaseexpiry* in inn.conf. If it is set
to false, expire.ctl takes entries of the form:
<storage_class>:<keep>:<default>:<purge>
<storage_class> is the number assigned to a storage class in
storage.conf. <default> is the number of days to keep normal articles
in that storage class (decimal values are allowed). For articles that
don't have an Expires: header, those are the only two values that
matter. For articles with an Expires: header, the other two values come
into play; the date given in the Expires: header of an article will be
honored, subject to the constraints set by <keep> and <purge>. All
articles in this storage class will be kept for at least <keep> days,
regardless of their Expires: headers, and all articles in this storage
class will be expired after <purge> days, even if their Expires: headers
specify a longer life.
All three of these fields can also contain the special keyword "never".
If <default> is "never", only articles with explicit Expires: headers
will ever be expired. If <keep> is "never", articles with explicit
Expires: headers will be kept forever. Setting <purge> to "never" says
to honor Expires: headers even if they specify dates far into the
future. (Note that if <keep> is set to "never", all articles with
Expires: headers are kept forever and the value of <purge> is not used.)
If the value of *groupbaseexpiry* is true, expire.ctl takes entries of
the form:
<wildmat>:<flag>:<keep>:<default>:<purge>
<wildmat> is a wildmat expression ("!" and "@" not permitted, and only a
single expression, not a comma-separated set of them). Each expiration
line applies to groups matching the wildmat expression. <flag> is "M"
for moderated groups, "U" for unmoderated groups, and "A" for groups
with any moderation status; the line only matches groups with the
indicated expiration status. All of the other fields have the same
meaning as above.
readers.conf
Provided that *noreader* is set to false in inn.conf, any connection
from a host that doesn't match an entry in incoming.conf (as well as any
connection from a host that does match such an entry, but has issued a
MODE READER command) will be handed off to nnrpd(8), the part of INN
that supports newsreading clients. nnrpd uses readers.conf to determine
whether a given connection is allowed to read news, and if so what
newsgroups the client can read and post to.
There are a variety of fairly complicated things that one can do with
readers.conf, things like run external authentication programs that can
query RADIUS servers. See readers.conf(5) and the example file for all
the gory details. Here's an example of probably the simplest reasonable
configuration, one that only allows clients in the "example.com" domain
to read from the server and allows any host in that domain to read and
post to all groups:
auth "example.com" {
hosts: "example.com, *.example.com"
default: "<user>"
default-domain: "example.com"
}
access "all" {
users: "*@example.com"
newsgroups: "*"
}
If you're running a server for one particular domain, want to allow all
hosts within that domain to read and post to any group on the server,
and want to deny access to anyone outside that domain, just use the
above and change "example.com" in the above to your domain and you're
all set. Lots of examples of more complicated things are in the sample
file.
Creating the Article Spool (CNFS only)
If you are using actual files as your CNFS buffers, you will need to
pre-create those files, ensuring they're the right size. The easiest
way to do this is with dd. For each cycbuff in cycbuff.conf, create the
buffer with the following commands (as the news user):
dd if=/dev/zero of=/path/to/buffer bs=1k count=BUFFERSIZE
chmod 664 /path/to/buffer
Substitute the correct path to the buffer and the size of the buffer as
specified in cycbuff.conf. This will create a zero-filled file of the
correct size; it may take a while, so be prepared to wait.
Here's a command that will print out the dd(1) commands that you should
run:
awk -F: \
'/^cy/ { printf "dd if=/dev/zero of=%s bs=1k count=%s\n", $3, $4 }' \
<pathetc in inn.conf>/cycbuff.conf
If you are using block devices, you don't technically have to do
anything at all (since INN is capable of using the devices in /dev), but
you probably want to create special device files for those devices
somewhere for INN's private use. It is more convenient to keep all of
INN's stuff together, but more importantly, the device files used by INN
really should be owned by the news user and group, and you may not want
to do that with the files in /dev.
To create the device files for INN, use mknod(8) with a type of "b",
getting the major and minor device numbers from the existing devices in
/dev. There's a small shell script in cycbuff.conf(5) that may help
with this. Make sure to create the device files in the location INN
expects them (specified in cycbuff.conf).
Solaris users please note: on Solaris, do not use block devices that
include the first cylinder of the disk. Solaris doesn't protect the
superblock from being overwritten by an application writing to block
devices and includes it in the first cylinder of the disk, so unless you
use a slice that starts with cylinder 1 instead of 0, INN will
invalidate the partition table when it tries to initialize the cycbuff
and all further accesses will fail until you repartition.
Creating the Database Files
At this point, you need to set up the news database directory (in
*pathdb*). This directory will hold the active(5) file (the list of
newsgroups you carry), the active.times(5) file (the creator and
creation time of newsgroups created since the server was initialized),
the newsgroups(5) file (descriptions for all the newsgroups you carry),
and the history(5) file (a record of every article the server currently
has or has seen in the past few days, used to decide whether to accept
or refuse new incoming messages).
Before starting to work on this, make sure you're logged on as the news
user, since all of these files need to be owned by that user. This is a
good policy to always follow; if you are doing any maintenance work on
your news server, log on as the news user. Don't do maintenance work as
root. Also make sure that *pathbin* is in the default path of the news
user (and while you're at it, make sure *pathnews*/share/man is in the
default MANPATH) so that you can run INN maintenance commands without
having to type the full path.
If you already have a server set up (if you're upgrading, or setting up
a new server based on an existing server), copy active and newsgroups
from that server into *pathdb*. Otherwise, you'll need to figure out
what newsgroups you want to carry and create new active and newsgroups
files for them. If you plan to carry a full feed, or something close to
that, go to <ftp://ftp.isc.org/pub/usenet/CONFIG/> and download active
and newsgroups from there; that will start you off with reasonably
complete files. If you plan to only carry a small set of groups, the
default minimal active file installed by INN is a good place to start;
you can create additional groups after the server is running by using
"ctlinnd newgroup". (Another option is to use actsync(8) to synchronize
your newsgroup list to that of another server.)
"control", "control.cancel" and "junk" must exist as newsgroups in your
active file for INN to start, and creating pseudogroups for the major
types of control messages is strongly encouraged for all servers that
aren't standalone. If you don't want these groups to be visible to
clients, do *not* delete them; simply hide them in readers.conf. "to"
must also exist as a newsgroup if you have *mergetogroups* set in
inn.conf.
Next, you need to create an empty history database. To do this, type:
cd <pathdb in inn.conf>
touch history
makedbz -i
(Note that if you install INN with "make install", you do not need to
run these commands: the installation takes care of creating the history
database.)
When it finishes, rename the files it created to remove the ".n" in the
file names and then make sure the file permissions are correct on all
the files you've just created:
chmod 644 *
Your news database files are now ready to go.
Configuring syslog
While some logs are handled internally, INN also logs a wide variety of
information via syslog. INN's nightly report programs know how to roll
and summarize those syslog log files, but when you first install INN you
need to set them up.
If your system understands the "news" syslog facility, INN will use it;
otherwise, it will log to "local1". Nearly every modern system has a
"news" syslog facility so you can safely assume that yours does, but if
in doubt take a look at the output from running "configure". You should
see a line that looks like:
checking log level for news... LOG_NEWS
If that says LOG_LOCAL1 instead, change the below instructions to use
"local1" instead of "news".
Edit /etc/syslog.conf on your system and add lines that look like the
following:
news.crit <pathlog in inn.conf>/news.crit
news.err <pathlog in inn.conf>/news.err
news.notice <pathlog in inn.conf>/news.notice
(Change the path names as necessary in order to match *pathlog*, which
defaults to /usr/local/news/log.) These lines *must* be tab-delimited,
so don't copy and paste from these instructions. Type it in by hand and
make sure you use a tab, or you'll get mysterious failures. You'll also
want to make sure that news log messages don't fill your other log files
(INN generates a lot of log traffic); so for every entry in
/etc/syslog.conf that starts with "*", add ";news.none" to the end of
the first column. For example, if you have a line like:
*.err /dev/console
change it to:
*.err;news.none /dev/console
(You can choose not to do this for the higher priority log messages, if
you want to make sure they go to your normal high-priority log files as
well as INN's. Don't bother with anything lower priority than "crit",
though. news.err isn't interesting enough to want to see all the time.)
Now, make sure that the news log files exist; syslog generally won't
create files automatically. Enter the following commands:
touch <pathlog in inn.conf>/news.crit
touch <pathlog in inn.conf>/news.err
touch <pathlog in inn.conf>/news.notice
chown news <pathlog in inn.conf>/news.*
chgrp news <pathlog in inn.conf>/news.*
(again adjusting the paths if necessary for your installation).
Finally, send a HUP signal to syslogd to make it re-read its
configuration file.
Setting Up the Cron Jobs
INN requires a special cron job to be set up on your system to run
news.daily(8) which performs daily server maintenance tasks such as
article expiration and the processing and rotation of the server logs.
Since it will slow the server down while it is running, it should be run
during periods of low server usage, such as in the middle of the night.
To run it at 3am, for example, add the following entry to the news
user's crontab file:
0 3 * * * <pathbin in inn.conf>/news.daily expireover lowmark
or, if your system does not have per-user crontabs, put the following
line into your system crontab instead:
0 3 * * * su news -s /bin/sh -c '<pathbin in inn.conf>/news.daily expireover lowmark'
If you're using any non-CNFS storage methods, add "delayrm" to the above
option list for news.daily.
The news user obviously must be able to run cron jobs. On Solaris, this
means that it must have a valid /etc/shadow entry and must not be locked
(although it may be a non-login account). There may be similar
restrictions with other operating systems.
If you use the batching method to send news, also set up a cron job to
run nntpsend(8) every ten minutes. nntpsend will run innxmit for all
non-empty pending batch files to send pending news to your peers. That
cron entry should look something like:
0,10,20,30,40,50 * * * * <pathbin in inn.conf>/nntpsend
The pathnames and user ID used above are the installation defaults;
change them to match your installation if you used something other than
the defaults.
The parameters passed to news.daily in the above example are the most
common (and usually the most efficient) ones to use. More information
on what these parameters do can be found in the news.daily(8) man page.
You may also want to run rnews each hour to process spooled messages
created while innd is not available:
12 * * * * <pathbin in inn.conf>/rnews -U
And it is also a good practice to refresh each day INN's cached IP
addresses:
30 2 * * * <pathbin in inn.conf>/ctlinnd -t 120 -s reload incoming.conf 'flush cache'
File Descriptor Limits
INN likes to use a lot of file descriptors, particularly if you have a
lot of peers. Depending on what your system defaults are, you may need
to make sure the default limit is increased for INN (particularly for
innd and innfeed). This is vital on Solaris, which defaults (at least
as of 2.6) to an absurdly low limit of 64 file descriptors per process.
One way to increase the number of file descriptors is to set
*rlimitnofile* in inn.conf to a higher value. This will cause innd and
innfeed to try to increase the file descriptor limits when they start.
Note, however, that INN won't be able to increase the limits above the
hard limits set by your operating system; on some systems, that hard
limit is normally 256 file descriptors (Linux, for example). On others,
like Solaris, it's 1024. Increasing the limit beyond that value may
require serious system configuration work. (On some operating systems,
it requires patching and recompiling the kernel. On Solaris it can be
changed in /etc/system, but for 2.6 or earlier the limit cannot be
increased beyond 1024 without breaking select(2) and thereby breaking
all of INN. For current versions of Linux, you may be able to change
the maximum by writing to /proc/sys/fs/file-max.)
256 file descriptors will probably be enough for all but the largest
sites. There is no harm in setting the limits higher than you actually
need (provided they're set to something lower than or equal to your
system hard limit). 256 is therefore a reasonable value to try.
If you're installing INN on a Solaris system, particularly if you're
installing it on a dedicated news server machine, it may be easier to
just increase the default file descriptor limit across the board for all
processes. You can do that by putting the line:
set rlim_fd_cur = 256
in /etc/system and rebooting. You can increase it all the way to 1024
(and may need to if you have a particularly large site), but that can
cause RPC and some stdio applications to break. It therefore probably
isn't a good idea on a machine that isn't dedicated to INN.
Starting and Stopping the System
INN is started via the shell script rc.news. This must be run as the
news user and not as root. To start INN on system boot, you therefore
want to put something like:
su news -s /bin/sh -c <pathbin in inn.conf>/rc.news
in the system boot scripts. If innd is stopped or killed, you can
restart it by running rc.news by hand as the news user.
The rc.news script may also be used to shut down INN, with the "stop"
option:
su news -s /bin/sh -c '<pathbin in inn.conf>/rc.news stop'
In the contrib directory of this source tree, two sample init scripts
are provided: one for people using System V-style init.d directories,
and another for people using systemd-style init scripts.
If you wish to use TLS/SSL for your readers, you need to start a second
nnrpd to listen to these connections to NNTPS port 563 and put something
like that in your init scripts:
su news -s /bin/sh -c '<pathbin in inn.conf>/nnrpd -D -c <pathetc in inn.conf>/readers-ssl.conf -p 563 -S'
where readers-ssl.conf is the file which indicates whether a given
connection is allowed to read and post news (you can also use the
previously created readers.conf file to handle TLS/SSL connections).
Note that a news client which supports the STARTTLS command can also use
the conventional NNTP port 119 to initiate a TLS connection. However,
such clients are not widespread yet.
In the shutdown section of the init script, you can put:
start-stop-daemon --stop --name nnrpd --quiet --oknodo
or if you do not have a start-stop-daemon utility:
su news -s /bin/sh -c 'killall nnrpd'
Processing Newsgroup Control Messages
Control messages are specially-formatted messages that tell news servers
to take various actions. Cancels (commands to delete messages) are
handled internally by INN, and all other control messages are processed
by controlchan, a channel feed program which should be run out of
newsfeeds if you want your news server to process any control messages;
see "Configuring INN" for specific instructions. Note that *pgpverify*
must also be set to true in inn.conf.
The actions of controlchan are determined by control.ctl, which lists
who can perform what actions. The primary control messages to be
concerned with are "newgroup" (to create a newsgroup), "rmgroup" (to
remove a newsgroup), and "checkgroups" (to compare the list of groups
carried in a hierarchy to a canonical list). INN comes with a
control.ctl file that processes control messages in most major public
hierarchies; if you don't want to act on all those control messages, you
should remove from that file all entries for hierarchies you don't want
to carry. The last version of that file is available from
<ftp://ftp.isc.org/pub/usenet/CONFIG/control.ctl>.
You can tell INN to just authenticate control messages based on the
From: header of the message, but this is obviously perilous and control
messages are widely forged. Many hierarchies sign all of their control
messages with PGP, allowing news servers to verify their authenticity,
and checking those signatures for hierarchies that use them is highly
recommended. controlchan knows how to do this (using pgpverify) without
additional configuration, but you do have to provide it with a public
key ring containing the public keys of all of the hierarchy
administrators whose control messages you want to check.
INN expects the public key ring to either be in the default location for
a PGP public key ring for the news user (generally *pathnews*/.gnupg for
GnuPG and *pathnews*/.pgp for old PGP implementations), or in
*pathetc*/pgp (/usr/local/news/etc/pgp by default). The latter is the
recommended path. To add a key to that key ring, use:
gpg --import --homedir=<pathetc in inn.conf>/pgp <file>
where <file> is a file containing the hierarchy key. Change the homedir
setting to point to *pathetc*/pgp if you have INN installed in a
non-default location. If you're using the old-style PGP program, an
equivalent command is:
env PGPPATH=<pathetc in inn.conf>/pgp pgp <file>
You can safely answer "no" to questions about whether you want to sign,
trust, or certify keys. And you may afterwards do:
cp <pathetc in inn.conf>/pgp/pubring.gpg <pathetc in inn.conf>/pgp/trustedkeys.gpg
The URLs from which you can get hierarchy keys are noted in comments in
control.ctl. <ftp://ftp.isc.org/pub/pgpcontrol/PGPKEYS> tries to
collect the major hierarchy keys and you can just import the whole file.
If you want to make sure that the keys have been correcly imported, use:
gpg --list-keys
If you are using GnuPG, please note that the first user ID on the key
will be the one that's used by INN for verification and must match the
key listed in control.ctl. If a hierarchy key has multiple user IDs,
you may have to remove all the user IDs except the one that matches the
control.ctl entry using "gpg --edit-key" and the "delkey" command.
$Id: install.pod 9599 2014-02-08 13:56:54Z iulius $
|