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 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871
|
.\" $Revision: 1.26 $
.\" Uses the -ms macro package; e.g., "nroff -ms Install.ms | col >Install.out"
.\" If you have no "roff" then pick up awf from Volume 23 of your nearest
.\" comp.sources.unix archive. Groff users need -mgs not -ms.
.\" UX - UNIX macro
.nr UX 0
.de UX
.ie \\n(UX \s-1UNIX\s0\\$1
.el \{\
\s-1UNIX\s0\\$1\(dg
.FS
\(dg \s-1UNIX\s0 is a registered trademark of X/Open Company Ltd.
.FE
.nr UX 1
.\}
..
.DA "Northern Winter 1997"
.TL
Installing InterNetNews
.AU
Rich $alz
Updated by: James Brister
.AI
Internet Software Consortium
\fIplease send electronic mail to <inn@isc.org>\fP
.AB
This document discusses how to install and set up InterNetNews.
You should be familiar with Usenet and networks; the first section gives
references to documentation for these topics, and the appendix IV gives
a Usenet installation overview for novices.
.PP
This document also describes what many of the programs do and how they
should be used.
Even if you are a world-class expert at building and maintaining
public software, you should probably read this.
.PP
.AE
.NH 1
Things You Should Know Before You Do Anything
.PP
InterNetNews is abbreviated \fIINN\fP, which is pronounced
as the three letters, \fIeye en en\fP.
It is a Usenet transport and expiration system for larger
.UX
systems where NNTP is used for most Usenet traffic.
.PP
This document is not a tutorial on Usenet.
If you do not have much Usenet experience, you should read
\fIUsing UUCP and Usenet\fP, ISBN 0-937175-10-2.
You might also find it useful to read \fIManaging UUCP and Usenet\fP
(get the most recent edition available), ISBN 0-937175-48-X.
Both books are published by O'Reilly & Associates; send inquiries to
to <nuts@ora.com>.
.PP
There is a chapter on INN in \fIThe Internet Connection: A Guide to
Connectivity and Configuration\fP, ISBN 0-201-54237-4 by Smoot
Carl-Mitchell and John S. Quarterman.
It is published by Addison-Wesley.
.PP
There is a book called \fIAdministering Usenet
New Servers\fP, ISBN 0-201-41967-X, by James McDermott and John E.
Phillips. Published by Addison-Wesley. It has good INN 1.5.1 coverage.
.PP
In November 1997, there was a new version of \fIManaging Usenet\fP
(note, no UUCP) about to come out from O'Reilly & Associates. This has a
large section on INN as well as Cnews.
.PP
You should know BSD-derived TCP/IP \(em at least be comfortable with host
names and dotted-quad addresses.
If you have installation problems, you should know about
.UX -domain
stream and datagram sockets and the like.
In addition to any documentation available from your vendor, you might
find it useful to read the two IPC tutorials in \fI
.UX
Programmer's Manual: Supplementary Documents 1\fP.
Copies can be purchased from the Usenix Association; send inquiries to
<office@usenix.org>.
.PP
There are two RFCs that are important to InterNetNews.
RFC 1036 describes the format of Usenet articles.
It is incomplete and has some errors, but it is the only formal
document available.
RFC 977 defines NNTP, the Network News Transfer Protocol.
RFCs are available from several places, including anonymous FTP
to nnsc.nsf.net, where they can be found in the directory \fIrfc\fP.
RFC 977 is currently being revised.
The 1036 revision is most likely going to be a ``tightening-up''; since
INN already has a strict interpretation of the RFC, this revision will
probably not affect InterNetNews very much.
The 977 revision is formally adding new features and facilities which are
currently implemented, and while INN
will not provide all of them, they will have some impact.
.PP
InterNetNews does things differently from other news software.
Some other Usenet systems for
.UX
are B2.11 and C News.
Both of them require a separate NNTP implementation.
The one everyone uses is called ``NNTP.''
Because this is confusing (they don't call \fIsendmail\fP ``SMTP''), I will
refer to it as the ``reference implementation.''
You generally do not need to know anything about these other systems,
but if you are curious, the official sites are as follows:
.DS
.ta \w'B2.11 News 'u +\w'ftp.cs.toronto.edu 'u
Package Host Directory
C\ News ftp.cs.toronto.edu pub/c-news
B2.11 ftp.uu.net news/bnews-2.11
nntp ftp.academ.com public/nntp
.DE
You might find the files \fIdoc/biblio\fP, \fIdoc/problems\fP, and
\fIdoc/rfcerrata\fP in the C News distribution worthwhile reading.
The first is a bibliography, the second discusses known C News porting
problems (see the DBZ sections in particular, and ignore most of the shell
comments), while the third lists some technical and philosophical errors
in RFC 1036.
.PP
The commands below assume that \fI$inn\fP is an abbreviation for the
top of the InterNetNews source tree.
.PP
INN could not have been written without access to the freely-redistributable
sources of B2.11, C News, and NNTP.
In particular, I want to thank Rick Adams; Geoff Collyer and Henry Spencer;
and Stan Barber, Erik Fair, Brian Kantor, and Phil Lapsley.
The financial support of UUNET Technologies is also greatly appreciated.
The beta-test sites gave invaluable feedback.
.NH 1
If You Are Impatient
.PP
If you don't want to follow these directions, do the following:
.DS
cd $inn/config
cp config.dist config.data
chmod 644 config.data
vi config.data (or emacs, or whatever)
cd ..
make world
mkdir -p /usr/news /var/news /var/news/spool
make install
.DE
Then go read the appendixes.
If you have any problems, read the rest of this document.
.NH 1
Distribution Roadmap
.PP
The INN sources are divided into the following directories:
.IP \fIfrontends\fP 15
Programs to feed articles to the central server and control it.
.IP \fIinnd\fP 15
The central NNTP server.
It accepts incoming connections, receives articles, and arranges for
them to be sent to downstream newsfeeds.
.IP \fIbackends\fP 15
Programs to transmit articles to other sites.
.IP \fIexpire\fP 15
Programs to purge the article files and history database.
.IP \fInnrpd\fP 15
An NNTP server for on-campus clients that do newsreading (as opposed to
bulk article transfer).
.IP \fIlib\fP 15
Library routines used by all the above.
.IP \fIinclude\fP 15
Header files used by all the above.
.IP \fIdbz\fP 15
DBZ database package.
.IP \fIsyslog\fP 15
Syslog routines for the systems which don't provide proper functions needed
for INN.
.PP
The distribution also includes these directories:
.IP \fIsamples\fP 15
Prototype scripts and configuration files that might have to be edited
before they are installed.
.IP \fIsite\fP 15
A place to store edited copies of the files in the \fIsamples\fP directory.
.IP \fIdoc\fP 15
Manual pages for all the above.
.IP \fIconfig\fP 15
Tools to configure the release for your site.
.IP \fIsample-configs\fP 15
Sample configuration data for any system.
.IP \fIauthprogs\fP 15
Sample program which can be used for an authentication with nnrpd.
.IP \fIcontrib\fP 15
Contributed programs useful for INN.
.IP \fIobsolete\fP 15
.IP \fIFAQ\fP 15
Frequently Asked Questions on INN which is posted at news.software.{b,nntp}
periodically.
.PP
Finally, there are a handful of files in the top-level directory:
.IP \fIREADME\fP 15
A basic introduction.
.IP \fICOPYRIGHT\fP 15
The distribution copyright.
InterNetNews is freely redistributable, provided proper credit is given.
.IP \fIMANIFEST\fP 15
A one-line description of every file in the distribution.
.IP \fIBUILD\fP 15
An interactive script to configure, build, and install INN.
.IP \fImakedirs.sh\fP 15
A script to build INN's directories except for the top levels: /usr/news
/var/news and /var/news/spool.
As long as you have write permission to install the programs, this is
the only part of the installation that needs to be done as
root, except that inndstart needs to be installed setuid root, and so doing
the install as root will make life easier.
.IP \fIMakefile\fP 15
Rules to call the other Makefiles and make distributions.
.IP \fIInstall.ms\fP 15
This document.
It requires the ``\-ms'' nroff/troff macro package.
.IP \fIMakeLib\fP 15
Script to build a directory with a replacement of the reference
implementation's ``clientlib'' routines needed by remote \fIrn\fP.
.IP \fIMakeInews\fP 15
Script to build an \fIinews\fP distribution directory.
.IP \fIMakeRnews\fP 15
Script to build an \fIrnews\fP distribution directory.
.IP \fIsedf.xxx\fP 15
Various \fIsed\fP scripts to filter the output of \fIlint\fP.
.IP \fIREADME.perl_hook\fP 15
A description for PERL filtering.
.IP \fIREADME.tcl_hook\fP 15
A description for TCL filtering.
.IP \fICONTRIBUTORS\fP 15
Contributors to INN.
.IP \fIHISTORY\fP 15
History until INN 1.4.
.IP \fIiftrue.sh\fP 15
Script that does test(1).
.IP \fIinstallit.sh\fP 15
Script that installs programs, scripts and configuration files for INN.
.IP \fIPGPKEYS\fP 15
PGP public keys used for control message authentication.
.NH 1
Building the System
.PP
INN is built in steps.
First, the \fIsubst\fP program is built.
Next, a configuration file containing key/value pairs is created.
\fISubst\fP reads this file and uses it to edit a specific set of files
in the INN distribution.
(Most of the files that get modified are Makefiles or header files.)
The library is then built; \fIlint\fP is usually a good way to see if
some of the basic configuration parameters are set up right.
The next step is to compile (and lint) all the programs.
The programs are then installed, and the INN data files are set up.
.PP
The configuration process is deliberately not interactive.
Configure scripts like the one in \fIrn\fP are fun to watch, but they
spend too much effort on the wrong job, like whether \fIgrep\fP returns
an exit status.
It is also difficult to change one parameter and rebuild the software.
(C News has this same problem.)
.PP
INN's method also has its flaws.
Because almost all configuration data is in one header file, changing
almost anything will force everything to be recompiled.
.NH 2
Building subst
.PP
INN uses the C News \fIsubst\fP program to automate the configuration.
\fISubst\fP is a very clever way of safely editing a file under the control
of a configuration file.
For more details, see the documentation in \fIdoc/subst.1\fP.
Thanks to Henry Spencer and Geoff Collyer for their permission to use and
redistribute \fIsubst\fP.
.PP
We will use \fIconfig.dist\fP as the configuration file to test the
version of \fIsubst\fP that you build.
.\"Using this file on your INN distribution should result in no changes to
.\"any files.
.\"If, while doing the steps below, you see any ``updated'' messages, then
.\"something is wrong with your distribution.
(You can always replace your config file with the distribution file and
do another \fImake\fP to restore the original versions.)
.PP
The C News \fIsubst\fP program is a shell script that uses \fIsed\fP to
do the editing.
The INN configuration file is too large for some versions of \fIsed\fP.
The first step is to see if your \fIsed\fP will work.
To do this, type the following:
.DS
cd $inn/config
cp config.dist config.data
make sedtest
.DE
If you get any error messages from \fIsed\fP such as ``too much command
text'' (or if it dumps core) you have two choices.
(You should also complain to your vendor.)
One choice is to use another version of \fIsed\fP, such as the one
distributed by the Free Software Foundation.
If you do this, edit \fIconfig/Makefile\fP and change the line that
defines the SED variable.
If you want to use the C News script, then do the following:
.DS
cd $inn/config
make sh
.DE
.PP
The other choice is to use the C version of \fIsubst\fP.
You might want to do this anyway, since it can be much faster.
To do this, type the following:
.DS
cd $inn/config
cp config.dist config.data
make c quiet
.DE
If you get any compilation errors, you will have to edit the file
\fIconfig/subst.c\fP.
If you are using an early version of AFS, you will have edit the file
to enable the USE_RENAME macro.
If you have to make any other changes, please let me know.
.PP
Since \fIsubst\fP changes source files, you might want to make a
backup copy of all the files that will be modified.
You can do this by typing ``make backup'' in the \fIconfig\fP
directory.
This will create a local tar file that contains all the files that will
be modified into it.
Doing ``make restore'' will unpacks the tar file.
(Since \fIsubst\fP makes its changes safely, this step is optional.)
.NH 2
Editing config.data
.PP
Once you have \fIsubst\fP working, the next step is to set up your
configuration parameters.
This is the hardest part of installing INN.
\fIDon't panic!\fP
There are many configuration parameters, but it should be very easy
for you to determine the answer for most of them.
To do this, choose one of the sample config files which is suitable for your
system from \fIsample-configs\fP directory, and copy it to
\fIconfig/config.data\fP. If there is no sample for your system,
you should copy \fIconfig/config.dist\fP, the distribution
master, to \fIconfig/config.data\fP, your local copy.
INN is distributed to compile and run under BSD/OS 2.1 by default.
.PP
The configuration file is divided into the following sections:
.DS
MAKE CONFIG PARAMETERS
LOGGING LEVELS
OWNERSHIPS AND FILE MODES
C LIBRARY DIFFERENCES
C LIBRARY OMISSIONS
MISCELLANEOUS CONFIG DATA
PATHS TO COMMON PROGRAMS
PATHS RELATED TO THE SPOOL DIRECTORY
EXECUTION PATHS FOR INND AND RNEWS
SOCKETS CREATED BY INND OR CLIENTS
LOG AND CONFIG FILES
INNWATCH CONFIGURATION
TCL Configuration
PGP Configuration
Keyword Configuration
Local Configuration
Actsync Configuration
Perl Configuration
.DE
You should have a copy of \fIconfig.data\fP nearby as you read the next
few sections.
It is probably a good idea to write down your changes on paper before
you edit the file.
.PP
The format of the file is very strict.
A line starting with a poundsign is a comment line.
All other lines must be in this format:
.DS
parameter \fI<one-or-more-tabs>\fP value
.DE
If there is no ``value'' the ``<one-or-more-tabs>'' is still required.
Do not put quote marks around the values \(em if you do, you will usually
get a syntax error while compiling the system.
The discussion below uses quotes only to show where the values start and end.
.NH 3
MAKE CONFIG PARAMETERS
.PP
This section is used primarily to identify the path to your C compiler,
and what extra libraries or command-line switches are needed.
For example, you could put \fIgcc \-Wall\fP on the \fICC\fP line.
If you need extra \fI\-I\fP flags put them on the \fIDEFS\fP line.
INN uses the \fIregister\fP declaration a great deal.
If your compiler is very good, you might want to add \fI\-Dregister=\fP
to the \fIDEFS\fP line so that INN's declarations are ignored.
.PP
The DBZ package can be compiled so that the database is memory-mapped.
If you want to do this and have the \fImmap\fP system call, then add
``\-DMMAP'' to the \fIDBZCFLAGS\fP parameter.
.PP
If you need to link in other libraries (e.g., \fI\-lnet\fP) put them
on the \fILIBS\fP line.
.\".PP
.\"INN can be built with Conor Cahill's ``debug_malloc'' package.
.\"Add ``-D_DEBUG_MALLOC_INC\ -Ixxx'' to the \fIDEFS\fP line, where \fIxxx\fP
.\"is the path to the debug package.
.\"You will also have to add the appropriate ``libdbmalloc'' value to the
.\"\fILIBS\fP parameter.
.PP
The Makefiles usually filter all \fIlint\fP output through a \fIsed\fP
script.
If you are very paranoid, set \fILINTFILTER\fP to \fIcat\fP.
If your lint output is in the broken multi-line format:
.DS
value type declared inconsistently
exit llib-lc(297) :: test.c(7)
function returns value which is always ignored
printf
.DE
Then set \fILINTFILTER\fP to be the ``sedf.sysv'' line.
.PP
The \fIlib\fP directory also builds a \fIlint\fP library, so that
you can make sure the other programs are properly using the library
routines.
The \fILINTLIBSTYLE\fP parameter (used in \fIlib/Makefile\fP and
\fIlib/makellib.sh\fP) controls how the \fIlint\fP library is built.
If your \fIlint\fP understands the ``\-C'' flag, then set it to ``BSD''.
If you need the ``\-o'' flag to build a library, then set it to ``SYSV''.
If neither of these work, you can set it to ``NONE''; this will just
create an empty file so that the other Makefiles don't break.
If you come up with a fourth alternative, let me know.
.PP
Unfortunately, on some systems \fIlint\fP is all but useless, so complain
to your vendor and take the output with a grain of salt.
You might get some warnings about ``struct\ _DDHANDLE'' being undefined.
You can ignore them and ask your vendor to support the BSD ``\-z'' lint flag.
If you set \fIHAVE_UNISTD\fP to ``DO'' then you might get warnings
about prototype mismatches for various functions declared in
\fIinclude/clibrary.h\fP.
You can ignore them or remove the lines from the INN header file.
.PP
The \fIMANPAGESTYLE\fP parameter (used in \fIdoc/Makefile\fP and
\fIdoc/putman.sh\fP) controls how manual pages are installed into your
public directory while the \fIMANx\fP parameters specify the directories
where they get installed.
If you do not want to install any manpages, set \fIMANPAGESTYLE\fP to
\fINONE\fP.
.NH 3
LOGGING LEVELS
.PP
INN uses the modern \fIsyslog\fP that separates messages into both
levels and categories.
Look in your \fI<syslog.h>\fP header file for a ``LOG_NEWS'' macro,
and check your \fIsyslog\fP(3) manpage to make sure that \fIopenlog\fP
takes three arguments.
If it doesn't, then you will have to use the library routine and server
provided in the \fIsyslog\fP directory.
This is described later.
.PP
The different levels that are described in the \fIsyslog\fP(3) manpage
are confusing, so INN uses its own names for the four levels it uses:
.DS
.nf
.ta \w'L_NOTICE 'u
L_FATAL Fatal error, about to exit
L_ERROR Error that might require attention
L_NOTICE Informational notice, no action needed
L_DEBUG Protocol tracing or other debugging messages
.fi
.DE
Depending on how your \fIsyslog.conf\fP(5) file is set up, you might want
to change the \fIL_xxx\fP parameters in this section.
.PP
The \fIscanlogs\fP script assumes that the first three categories above
are each directed into separate files.
See \fIdoc/newslog.5\fP, \fIdoc/newslog.8\fP, and \fIsyslog/syslog.conf\fP
for details.
LOGGING is also described in more detail in the LOG AND CONFIG FILES section.
.NH 3
OWNERSHIPS AND FILE MODES
.PP
The NNTP server needs to open the NNTP port; it is port number 119,
which requires root access.
This is the only part of INN that needs this privilege: all other programs
can run under the distinct user and group id specified by the \fINEWSUSER\fP
and \fINEWSGROUP\fP parameters.
Most news administration tasks must be done as user \fINEWSUSER\fP (see the
explanation of SOCKETS CREATED BY INND OR CLIENTS section below).
In addition, \fIinews\fP will only let the \fINEWSUSER\fP user or members of
the \fINEWSGROUP\fP group post control messages other than cancel.
.PP
Some INN scripts (primarily the control message scripts and the
daily maintenance script) need to send email to the news maintainer.
The \fINEWSMASTER\fP parameter specifies the right address.
This is most often the login name of the account which has
\fINEWSUSER\fP as its user id; use an alias to forward it to the right people.
.PP
Some Usenet sites still use the Path header line to generate their email reply
messages.
Using the Path has never been guaranteed to work, and INN tries to help
stop this practice by refusing to generate valid Path addresses.
The \fIPATHMASTER\fP parameter specifies what \fIinews\fP should put
at the tail end of the Path line.
If your \fINEWSMASTER\fP mailbox is getting cluttered, then you might
want to change this to be an alias that rejects the message or drops it
into the bit-bucket.
The default value is ``not-for-mail'' which usually results in bounced
email.
.PP
The \fIxxx_MODE\fP parameters specify the permissions for articles and
directories created within the spool area, and the active file, all of
which are owned by user id \fINEWSUSER\fP.
.NH 3
C LIBRARY DIFFERENCES
.PP
Editing the parameters in this section will require you to look
around at the files in your \fI/usr/include\fP directory.
.PP
The \fISIZE_T\fP parameter is the datatype of the ``size'' parameters
in subroutine calls like \fImemchr\fP and \fIfread\fP.
The \fILOCK_STYLE\fP parameter specifies how file-locking should be done.
\fIInnxmit\fP is the only program that locks files; if you use the provided
scripts, this isn't even necessary, so you can set this to ``NONE'' if you
have any compile problems (expireover, overchan and filechan use either!)
.PP
The \fIDIR_STYLE\fP parameter specifies what is returned by your
\fIreaddir\fP(3) routine.
This will be either a ``struct\ direct'' or a ``struct\ dirent'';
set the parameter to ``DIRECT'' or ``DIRENT'' as appropriate.
.PP
If you do not have
.UX -domain
sockets, set \fIHAVE_UNIX_DOMAIN\fP to ``DONT.''
This means that INN will use a named pipe for the communication
between \fIinnd\fP and \fIctlinnd\fP.
It also means that there will be no local ``private'' port for \fIrnews\fP
to use; this should not cause any problems, although it makes it
easier for anyone to use \fIrnews\fP and post fake news articles.
(You might also have to modify the \fIsyslog\fP routines; see the end of
the file \fIsyslog/README\fP for details on this.)
.PP
INN needs to know how many descriptors are available to use for files
and sockets.
There are several ways to get this number; the \fIFDCOUNT_STYLE\fP
parameter specifies which method to use.
On most systems, the \fIgetdtablesize\fP routine will do this, so
leave the default of ``GETDTAB.''
On other systems you need to use the \fIgetrlimit\fP, \fIsysconf\fP or
\fIulimit\fP routine, so set the parameter to ``GETRLIMIT'', ``SYSCONF'',
or ``ULIMIT'', respectively.
If you do not have any of those calls then set the parameter to ``CONSTANT''
and edit the file \fIlib/getdtab.c\fP to return the right number.
To get this number, look for an \fIOPEN_MAX\fP constant in your system header
files, or write a program that repeatedly opens \fI/dev/null\fP until
it gets an error.
.PP
The last few parameters in this section, \fIxxxVAL\fP, are used primarily
to keep \fIlint\fP quiet.
These functions are declared in \fIinclude/clibrary.h\fP, and the return
values are pretty much always ignored.
You can usually determine what these values should be by examining
your manpages or your \fIlint\fP libraries.
.NH 3
C LIBRARY OMISSIONS
.PP
INN uses library routines that might not be present in all
.UX
systems, although they should be.
The \fIlib\fP directory provides versions of some of these routines,
including copies of the freely-redistributable BSD string routines.
The \fIMISSING_SRC\fP, \fIMISSING_OBJ\fP and \fIMISSING_MAN\fP parameters can be
set to list those routines that are missing from your C library.
If you don't have \fIstrcasecmp\fP and \fIstrncasecmp\fP then you will
need the \fIstrcasecmp\fP module built into your INN library.
Add the ``.c'' and ``.o'' names to \fIMISSING_SRC\fP and \fIMISSING_OBJ\fP,
respectively.
.PP
The following routines are all found in the file of the same name.
If they are missing from your system, add them the same way:
.DS
.ta 1.5i +1.5i
memchr strchr getopt
memcmp strrchr mkfifo
memcpy strspn strerror
memset strtok
memmove
.DE
.PP
If you are using version 1 of the GNU C compiler on a Sparc running SunOS,
you should add \fIinet_ntoa\fP as a missing function.
This is because the first version of \fIgcc\fP didn't properly pass
structures into routines compiled with the Sun C compiler.
.PP
If you have an older version of \fIsyslog\fP add \fIsyslog.c\fP and
\fIsyslog.o\fP to the appropriate parameters.
.PP
Pyramid machines running OSx have fast assembly-language versions of the
string routines in the ATT library.
To use these routines, add ``$(OSXATTOBJ)'' to the \fIMISSING_OBJS\fP
parameter.
This will cause \fIlib/Makefile\fP to extract the object files from the ATT
library, and add them to the INN library.
.NH 3
MISCELLANEOUS CONFIG DATA
.PP
All the parameters in this section become macros in the file
\fIinclude/configdata.h\fP.
You should at least look through the parameters up to \fIVERIFY_CANCELS\fP.
(If set to ``DO'', then \fIinnd\fP will ignore cancel messages unless
the From or Sender header match those of the original poster.)
In general, however, you can leave this section pretty much alone until you
have some experience running INN.
Nevertheless, here are some comments on some of the more useful parameters.
.PP
\fIInnd\fP can memory-map the \fIactive\fP file if you set
\fIACT_STYLE\fP to ``MMAP''.
On some systems, however, when a mapped file is updated its mtime is
not updated.
Apparently some versions of System V Release 4 have this problem.
This causes problems for programs like \fInnmaster\fP which look at the
\fIst_mtime\fP field of the \fIstat\fP structure in order to determine if
any new news has come in.
The best work-around is probably an hourly \fIcron\fP job that touches the
\fIactive\fP file.
.PP
There are a number of parameters that control the behavior of \fIrnews\fP.
If you set \fIRNEWS_SAVE_BAD\fP to ``DO'' then articles that \fIinnd\fP
rejects for reasons like bad headers will be saved in the \fI_PATH_BADNEWS\fP
directory; you will have to periodically scan this directory and clean
it up.
You can also control how \fIrnews\fP logs duplicates (those aren't saved
regardless of the value of \fIRNEWS_SAVE_BAD\fP), logging them through
\fIsyslog\fP, to a file, or not.
Note that if you set \fIRNEWS_LOG_DUPS\fP to ``FILE'', then you will want
to change \fI_PATH_RNEWS_DUP_LOG\fP, which appears later in the file.
If you receive news from several UUCP feeds, you might want to log duplicates
so that you can cut down your phone bills by optimizing your feeds.
The \fIRNEWSPROGS\fP parameter says whether or not to look in
\fI_PATH_NEWSPROGS\fP for commands named on the incoming ``#!'' line of
news batches.
You probably want to set this to ``DO''.
Make sure that the full pathname of \fIrnews\fP, \fI_PATH_RNEWS\fP,
does not conflict with the directory where your unpackers are put,
\fI_PATH_NEWSPROGS\fP.
.PP
If \fIIPADDR_LOG\fP is set to ``DO'' then the news log will report the IP
address of hosts that send articles, rather then what they put in the Path
line.
This can be useful if you run \fIinnd\fP with the ``\-a'' flag.
(If you do this, you might want to pick up ``hf.tar.Z'' via anonymous
FTP to ee.lbl.gov; it is a filter that turns IP addresses into host names.)
.PP
The \fIxxx_TIMEOUT\fP parameters control various timers within INN;
you might want to change some of these depending on your system load.
.PP
The \fILIKE_PULLERS\fP parameter controls how to handle clients that appear
to be doing a sucking feed from your machine (many admins don't like such
clients). If the value is ``DO'' (the default), then nothing different
happens. If the value is ``DONT'', then after 100 articles have been sent,
each article transfer will be followed by a short (1 second) sleep. For
most readers this isn't a problem, but some clients doe article scoring
based on the entire body of the article. Such clients will be penalized
when \fILIKE_PULLERS\fP is set to ``DONT''.
.NH 3
PATHS TO COMMON PROGRAMS
.PP
INN uses a few standard programs like \fI/bin/sh\fP and \fIsendmail\fP.
If you don't have \fIsendmail\fP then you must have a program that
accepts a full message \(em including headers \(em on its standard input,
and delivers it.
This program is specified by the \fI_PATH_SENDMAIL\fP parameter, and
is normally ``/usr/lib/sendmail\ -t''.
The parameter is actually a \fIsprintf\fP format string that will be
given the destination address as its only argument.
On some sites (e.g., those running MMDF) the ``\-t'' could be replaced
with a ``%s''.
.PP
INN puts most of its executables in the directory specified by the
\fI_PATH_NEWSBIN\fP parameter.
Some programs expect \fIinews\fP and \fIrnews\fP to be in certain places;
for example, UUCP usually wants \fIrnews\fP in \fI/bin\fP.
The default configuration puts these programs in only one spot; if you
need to have multiple links to the same file, you will have to do it
yourself after INN is installed.
If you have additional scripts and programs that you use to maintain your
system, you can put them in whatever directory you want.
You will probably need to add \fI_PATH_NEWSBIN\fP to the PATH of any
such scripts.
.PP
If you have an \fI/etc/rc.local\fP file you should make sure that
it invokes the script named by the \fI_PATH_NEWSBOOT\fP parameter.
On other systems (mostly System V derivatives), the system boot procedure
automatically runs all the scripts in a particular directory, such as
\fI/etc/init.2\fP.
In that case, you should pick a name like \fI/etc/init.2/S99news\fP and
have the news boot script installed there, or install it in the default
\fI/etc/rc.news\fP and make the link yourself.
.PP
The daily maintenance script, \fInews.daily\fP calls \fIscanlogs\fP
to rotate and trim log files, as well as generating summaries using
\fIegrep\fP and \fIawk\fP.
On some systems the log files are too big for these programs so you
might have to complain to your vendor and install the versions from
the Free Software Foundation.
The \fIscanlogs\fP script has a short test you can run to see if your
\fIegrep\fP will work.
.NH 3
PATHS RELATED TO THE SPOOL DIRECTORY
.PP
By default, all news articles are stored in directories under
\fI/usr/spool/news\fP.
Be careful if you pick a different value \(em many newsreaders know
about this directory name.
.PP
INN uses a trick (which I first saw in C News) that lets it use this same
directory to store its incoming news (spooled by \fIrnews\fP when
\fIinnd\fP is not available), and its outgoing batch files.
Since no newsgroup can ever have a dot in its name, a directory like
\fIout.going\fP can never be a newsgroup name, and it is safe to
put the news batchfiles in there.
This is used by the \fI_PATH_SPOOLNEWS\fP parameter, and the
\fI_PATH_BATCHDIR\fP parameter.
.PP
Do not make \fI_PATH_LOCKS\fP be in the same filesystem as
\fI_PATH_SPOOLNEWS\fP.
If you do this, then INN will not be able to create any lock files when
your spool directory is full.
This will probably mean that \fInews.daily\fP will not be able to run
and that it won't call \fIexpire\fP to free up disk space.
You should also put \fI_PATH_NEWSLIB\fP on a separate partition if you
can, but that is not as important because it tends to fill up less often.
.PP
If you change parameters in this section a great deal, then there is a chance
that the \fImakedirs.sh\fP script will fail because some needed
intermediate directories will not exist.
This should not be a problem, as you can just create the directories
yourself \(em make sure to set the ownership and modes right \(em and
re-run the script.
.NH 3
EXECUTION PATHS FOR INND AND RNEWS
.PP
All control messages (other then ``cancel'') are carried out by scripts.
Your system must be able to \fIexec\fP shell scripts directly.
All the scripts distributed with INN start with ``#!\ /bin/sh.''
.PP
The \fI_PATH_CONTROLPROGS\fP parameter specifies the directory where
these scripts exist.
Do not set this to a public directory like \fI/bin\fP because some bozo
might send out an ``rm'' control message.
.PP
The \fI_PATH_RNEWSPROGS\fP directory serves the same purpose for \fIrnews\fP
when it needs to unpack batches.
The \fIRNEWSPROGS\fP parameter specifies if the directory is really used.
.NH 3
SOCKETS CREATED BY INND OR CLIENTS
.PP
The \fIinnd\fP server and its clients (most notably \fIctlinnd\fP)
create
.UX -domain
sockets or named pipes.
They are created inside a ``firewall'' directory that gives access permission
to a limited set of users.
For example, assume the directory is \fI/usr/local/news/innd\fP and that it
is owned by user news in group news and has mode 0770.
Using these permissions, then only members of the news group can use
\fIctlinnd\fP to create new groups because only they will be able to
send a message to the \fIinnd\fP socket.
.PP
This directory (which is specified by the \fI_PATH_INNDDIR\fP parameter)
is also used to determine the user and group id of all sub-processes spawned
by \fIinnd\fP, as well as the owner of all news articles and files.
The owner of this directory is set at installation time and specified in
the ``Ownerships and file modes'' section, above.
.NH 3
LOG AND CONFIG FILES
.PP
INN keeps its databases, and some control files their own directory,
typically named \fI/usr/local/news\fP.
Log files are kept in \fI/var/log/news\fP.
There are many parameters in this section that refer to files within
this directory.
Some sites will want to globally replace ``/usr/local/news'' with something
like ``/var/news'', and ``/usr/lib/newsbin'' with ``/var/newsbin.''
.PP
There are two files that contain access passwords,
\fI_PATH_NNTPPASS\fP and \fI_PATH_NNRPACCESS\fP.
The default location for these files is in \fI/var/news/etc\fP, so that it is
generally safe to export \fI/usr/news\fP (read\-only is probably best).
.PP
INN programs do extensive logging, and the daily maintenance scripts
do extensive summary reports and analysis of them.
It might take you some time to learn your way around the INN logging system;
start by reading the newslog manpages in the \fIdoc\fP directory.
.NH 3
INNWATCH CONFIGURATION
.PP
The INN server, \fIinnd\fP, does not contain any checks to see if there
is enough free space on the disk or if the system load average is low enough
to allow article reception.
There are two reasons for this.
The first reason is philosophical: it is a mistake to bury this kind of policy
information inside a program.
For example, you don't want to have to recompile the program just
because you moved to a different filesystem.
(Yes, this could be partially answered by moving the information to an
external config file, but any compiled rules are still likely to be
incomplete.)
The second reason is pragmatic: there is no portable way to get standard
measurements for the information needed.
For example, C News provides three different routines to get the filesystem
statistics (with conditional compilation) while the ``get load average''
file in IDA sendmail has over 700 lines.
.PP
Rather than get tangled up in such a mess of #ifdef's, INN uses an
external program (shell script) that invokes \fIctlinnd\fP to stop and start the
server as necessary.
The program, \fIinnwatch\fP, reads the control file \fIinnwatch.ctl\fP.
\fIInnwatch\fP is documented in \fIdoc/innwatch.8\fP, while \fIinnwatch.ctl\fP
is documented in \fIdoc/innwatch.ctl.5\fP.
.PP
The parameters in this section control when the server should stop accepting
articles, and when it should start again.
You will have to examine \fIsite/innwatch.ctl\fP and probably modify it,
usually to check the amount of free space on the disks.
For example, there is a line in the file that has this fragment in it:
.DS
!!! df . | awk 'NR == 2 { print $4 }' ! ...
.DE
This is looking at the fourth field of the second line to get the amount
of freespace.
You will have to change the ``2'' and ``4'' here (both can be changed by
setting \fIINNWATCH_INODES\fP and \fIINNWATCH_BLOCKS\fP respectively),
and on other lines, as appropriate for your system.
.PP
The parameter \fIINNWATCH_SLEEPTIME\fP specifies how frequently
\fIinnwatch\fP should check the system \(em the other parameters should
be set with this in mind, eg: there needs to be enough free space on the
filesystem to last the next \fIINNWATCH_SLEEPTIME\fP seconds.
.PP
The \fIINNWATCH_xxxLOAD\fP parameters specify the load average at
which different actions should be taken.
They are integers, representing the load average multipled by 100.
For example, if you want to throttle the server when your load reaches
7.5, set \fIINNWATCH_HILOAD\fP to ``750.''
.PP
The \fIINNWATCH_xxxSPACE\fP parameters specify the minimum amount of disk
space needed for each of INN's three major filesystems.
The numbers are in ``local units,'' equivalent to whatever your \fIdf\fP
uses (512-byte units, 1K blocks, etc).
.PP
The \fIINNWATCH_SPOOLNODES\fP parameter specifies how many inodes must
be available in your spool directory.
.NH 3
TCL Configuration
.PP
The innd server can be configured to include TCL hooks to be run whenever a
new article is received and when certain other actions occur. See the file
README.tcl_hook for more details.
.PP
The \fITCL_SUPPORT\fP parameter specifies whether you want to compile in the
Tcl support code. Select DO or DONT.
.PP
The \fITCL_LIB\fP parameter specifies the extra libraries you need to link
against to include tcl support. Typically ``-ltcl -lm'' are required. If
you defined \fITCL_SUPPORT\fP to DONT, then this should be blank.
.PP
The \fI_PATH_TCL_STARTUP\fP parameter specifies the path of the tcl script
that is to be loaded at process startup time. A sample version is included
in samples/startup.tcl which will be installed in the location you define
here.
.PP
The \fI_PATH_TCL_FILTER\fP parameter specifies the path of the tcl script
that is to be loaded upon command by ctlinnd. See the ctlinnd.8 manpage
for more details (the ``filter'' and ``reload'' commands). A sample is
included in samples/filter.tcl which will be installed in the location
defined by this parameter.
.NH 3
PGP Configuration
.PP
Inn now has mechanisms in place that will do PGP verification of control
messages (except for cancels). It is \fIhighly\fP recommended that you use
PGP if you can. Forged control messages are a serious problem in USENET.
You can get PGP from \fBhttp://web.mit.edu/network/pgp.html\fP.
.PP
The \fIWANT_PGPVERIFY\fP parameter defines whether PGP verification of
control messages should be done. Select ``DO'' or ``DONT''.
.PP
To verify messages, you must have a PGP public key for each signer
that you wish to trust. It should be entered in a key ring that is
accessible to the user-id that runs the news system by running
pgp -ka on a file containing the key to add. For example, at a
site that runs the news server software as news, the following
command run by the news user-id should add the key bounded by
BEGIN and END "PGP PUBLIC KEY BLOCK" lines in the file /tmp/key
to the default key ring that would be used for authentication:
.PP
.RS
pgp -ka /tmp/key
.RE
.PP
As a general policy rule, control message signers will not use their
control message keys to introduce other keys, so when PGP asks you
a question similar to, "Would you trust this user to act as an
introducer and certify other people's public keys to you?" answer
that you would not.
.PP
After you have added the appropriate key to your key ring, you
need to tell the news software to validate the control messages
received. As implemented, the system will perform the requested
action if the message can be authenticated and it will mail the
message to the news system administrator if it cannot.
.PP
Automatic processing of control messages is handled by control.ctl,
\fIControl.ctl\fP has several lines at the beginning of it that describe
the format of the file, and there is an even longer \fIcontrol.ctl\fP(5)
manual page. PGP verification for many large heirarchies is already enabled
in \fIcontrol.ctl\fP(5). To enable PGP verification for another heirachy,
in addition to the normal authorization done by control.ctl, use the action
"verify-PGP_USERID" in the fourth field. The supplied \fIcontrol.ctl\fP
file has samples that should be clear.
.PP
To test the PGP setup a signed sample control message is in the file
CONTROLPROGS/sample.control (where CONTROLPROGS is as defined in
config.data). Copy this to /tmp/sample.control. The file name
/tmp/sample.control will be used for this example.
.PP
To verify the control message, you will need the key for
news.announce.newgroups and authorization in your news system for
tale@uunet.uu.net to automatically perform "newgroup". Go ahead
and enable it for the test even if you don't want to really allow
this, because it is easy enough to rescind after the test by
editing the control message authorization file and removing the
key with pgp -kr news.announce.newgroups.
.PP
You can check that the pgpverify part of the system will work
properly simply by feeding it the sample control message on stdin:
.PP
.RS
pgpverify < /tmp/sample.control
.RE
.PP
If it could run pgp and find the correct key in the default key ring,
the string "news.announce.newgroups" should be printed. The exit
status of the script, found in most shells with the command
.PP
echo $?
.LP
as the next command after pgpverify, should be 0 (zero).
.PP
When pgpverify passes its test, use the procedure below to verify
the authorization system.
.PP
First, cd to the directory where parsecontrol is installed.
Then execute the following four lines, in order, as the user
who owns the news system:
.PP
.RS
.nf
/bin/sh
PROG=newgroup
set -- tale@uunet.uu.net "" /tmp/sample.control
(. ./parsecontrol "$@"; echo $ACTION)
.fi
.RE
.PP
If the message verified correctly, the echo command should
output doit; otherwise, verification failed and the output
should be mail.
.PP
Edit /tmp/sample.control and change all occurences of
newusers to newgroups. Then repeat the parsecontrol
and echo lines. This time verification should fail.
.NH 3
Keyword Configuration
.PP
The keyword generating code, that has been added by Karl Kleinpaste, is off
by default, as it's a real CPU sucker (does a lot of regexp matching). To
enable it you must:
.IP 1.
Set KEYWORDS to DO in config.data (and possibly change KEYLIMIT
ABSURD and MAX_WORDS) and rebuild innd.
.IP 2.
Uncomment the last line of the overview.fmt file so that it
looks like:
.RS
.nf
Keywords:full
.fi
.RE
.IP 3.
Install and start the new innd.
.PP
Of course you need overview generation enabled -- see elsewhere
in this document for that.
.NH 3
Local Configuration
.PP
At this section local definitions like home directory of \fINEWSUSER\fP are
specified.
This parameter is used for setting environment variable handed to innd when
invoked by inndstart.
.NH 3
Actsync configuration
.PP
Landon Curt Noll's actsync(8) program has been merged into INN. This section
defines some variables for the default config file for actsync. See the
man page for more details on actsync.
.PP
The \fIACTSYNC_HOST\fP variable defines which remote host you'll be using
to synchronize your active file. If you don't have a good host to sync to,
you can get (via anon ftp) ftp://ftp.isc.org/pub/usenet/CONFIG/active.gz
and have actsync use that.
.NH 3
Perl Configuration
.PP
The innd server can be configured to include perl hooks to be run the way
TCL does whenever a new article is received and when certain other actions
occur.
Further more, nnrpd can be also configured to include perl hooks to be run
whenever a new article is posted. This is not supported in TCL.
See the file README.perl_hook for more details.
.PP
The \fIPERL_SUPPORT\fP parameter specifies whether you want to compile in the
perl support code. Select DO or DONT.
.PP
The \fIPERL_LIB\fP parameter specifies the extra libraries you need to link
against to include perl support. Typically ``-lperl -lm'' are required. If
you defined \fIPERL_SUPPORT\fP to DONT, then this should be blank.
.PP
The \fI_PATH_PERL_STARTUP_INND\fP parameter specifies the path of the perl
script that is to be loaded at process startup time. A sample version is
included in samples/startup_innd.pl which will be installed in the location you
define here.
.PP
The \fI_PATH_PERL_FILTER_INND\fP parameter specifies the path of the perl script
that is to be loaded upon command by ctlinnd. See the ctlinnd.8 manpage
for more details (the ``filter'' and ``reload'' commands). A sample is
included in samples/filter_innd.pl which will be installed in the location
defined by this parameter.
.PP
The \fI_PATH_PERL_FILTER_NNRPD\fP parameter specifies the path of the perl
script that is to be loaded at process startup time. A sample version is
included in samples/filter_nnrpd.pl which will be installed in the location you
define here.
.PP
.NH 2
Typical config.data changes
.PP
The following sections show some of the changes that need to be made to
\fIconfig.data\fP so that INN will compile.
They are only samples; ``your mileage may vary.''
.PP
Note that if you are using the first release of \fIgcc2\fP, set
\fIUSE_CHAR_CONST\fP to ``DONT''.
.PP
.DS
.UL "SunOS 4.x"
MISSING_SRC memmove.c
MISSONG_OBJ memmove.o
.DE
.PP
.DS
.UL "AIX"
.ta \w'HAVE_ST_BLKSIZE 'u
DEFS -I../include -D_NO_PROTO -U__STR__
FORK fork
FREEVAL void
FUNCTYPE int
HAVE_ST_BLKSIZE DONT
HAVE_TM_GMTOFF DONT
LDFLAGS
LINTFILTER | sed -n -f ../sedf.aix
LINTFLAGS -wkD -b -h $(DEFS)
LINTLIBSTYLE SYSV
LOCK_STYLE FCNTL
MISSING_MAN
MISSING_SRC
NEED_TIME DO
POINTER void
USE_UNION_WAIT DONT
.DE
Under AIX 3.1, you must also use the \fIsyslog\fP that comes with INN.
This is not necessary for 3.2.
Some versions also need \fIUSE_UNION_WAIT\fP set to ``DONT''.
You should also run \fIrc.news\fP from \fIinit\fP not \fI/etc/rc\fP;
add a line like the following near the end of the \fIinittab\fP file,
just before the ``cons'' line:
.DS
rcnews:wait:2:/usr/local/etc/rc.news >/dev/console 2>&1
.DE
.PP
.DS
.UL "A/UX"
.ta \w'HAVE_ST_BLKSIZE 'u
LIBS -lbsd
.DE
Make sure you don't use \fIgcc\fP version 1; it miscompiles the socket calls
in \fIinnd/cc.c\fP.
.PP
.DS
.UL "BSDI"
ABORTVAL void
ALARMVAL u_int
EXITVAL volatile void
_EXITVAL volatile void
FREEVAL void
GETPIDVAL pid_t
GID_T gid_t
HAVE_UNISTD DO
HAVE_VFORK DONT
HAVE_WAITPID DO
LSEEKVAL off_t
MISSING_OBJ
MISSING_SRC
_PATH_COMPRESS /usr/bin/compress
_PATH_EGREP /usr/bin/egrep
_PATH_MAILCMD /usr/bin/Mail
_PATH_SENDMAIL /usr/sbin/sendmail -t
PID_T pid_t
POINTER void
QSORTVAL void
SIZE_T size_t
SLEEPVAL u_int
UID_T uid_t
USE_UNION_WAIT DONT
VAR_STYLE STDARGS
.DE
Change the \fISHELL\fP variable in \fIconfig/Makefile\fP and
\fIsite/Makefile\fP to point to \fI/usr/contrib/bin/bash\fP.
Edit \fIlib/Makefile\fP so that the \fIinstall\fP target does not
try to make \fI../llib-linn.ln\fP.
You must also use the GNU \fIsed\fP; the version distributed with
BSDI 0.9.4.1 enters an infinite loop processing newgroup messages.
.PP
.DS
.UL "HP-UX 8.0"
.ta \w'HAVE_ST_BLKSIZE 'u
ABORTVAL void
ALARMVAL unsigned int
CLX_STYLE FCNTL
CTYPE isXXXXX((c))
DEFS -I../include -DHPUX
FDCOUNT_STYLE SYSCONF
FREEVAL void
GETPIDVAL pid_t
GID_T gid_t
HAVE_SETBUFFER DONT
HAVE_ST_BLKSIZE DONT
HAVE_TM_GMTOFF DONT
HAVE_UNISTD DO
HAVE_WAITPID DO
LINTFILTER | sed -n -f ../sedf.sysv
LINTFLAGS -b -h $(DEFS)
LINTLIBSTYLE SYSV
LOCK_STYLE LOCKF
LOG_INN_PROG LOG_LOCAL7
LOG_INN_SERVER LOG_LOCAL7
LSEEKVAL off_t
_PATH_MAILCMD /usr/bin/mailx
NOFILE_LIMIT 200
PID_T pid_t
POINTER void
PROF
QSORTVAL void
RANLIB echo
RES_STYLE TIMES
SIZE_T size_t
SLEEPVAL unsigned int
UID_T uid_t
USE_UNION_WAIT DONT
_EXITVAL void
.DE
You will probably also need to use the \fIbdf\fP command instead of \fIdf\fP.
.PP
.DS
.UL "SGI Indigo with IRIX 4.0.1"
.ta \w'HAVE_ST_BLKSIZE 'u
ABORTVAL void
ALARMVAL uint
ACT_STYLE MMAP
CFLAGS $(DEFS) -g -w
CLX_STYLE FCNTL
_EXITVAL void
FORK fork
FREEVAL void
GID_T gid_t
HAVE_ST_BLKSIZE DONT
HAVE_TM_GMTOFF DONT
HAVE_UNISTD DO
LDFLAGS
LIBS -lmld
LINTFILTER | sed -n -f ../sedf.sysv
LINTFLAGS $(DEFS)
LINTLIBSTYLE SYSV
LSEEKVAL off_t
POINTER void
QSORTVAL void
RANLIB echo
SIZE_T size_t
SLEEPVAL uint
UID_T uid_t
_PATH_COMPRESS /usr/bsd/compress
.DE
Also, the \fIMISSING_xxx\fP parameters should be empty.
.PP
.DS
.UL "Solaris 2.X/SunOS 5.X, using SPARCompiler C 2.X"
.ta \w'HAVE_ST_BLKSIZE 'u
DEFS -I../include -DSUNOS5 -DPOLL_BUG
USE_CHAR_CONST DO
CFLAGS -O -Xa $(DEFS)
LDFLAGS
LIBS -lnsl -lsocket -lelf
LINTLIBSTYLE SYSV
LINTFLAGS -b -h $(DEFS)
LINTFILTER | sed -n -f ../sedf.sysv
RANLIB echo
VAR_STYLE STDARGS
SIZE_T size_t
UID_T uid_t
GID_T gid_t
PID_T pid_t
POINTER void
ALIGNPTR long
LOCK_STYLE LOCKF
HAVE_UNISTD DO
HAVE_SETSID DO
HAVE_TM_GMTOFF DONT
HAVE_WAITPID DO
USE_UNION_WAIT DONT
HAVE_VFORK DONT
HAVE_UNIX_DOMAIN DO
CLX_STYLE FCNTL
RES_STYLE TIMES
FDCOUNT_STYLE SYSCONF
ABORTVAL void
ALARMVAL unsigned
GETPIDVAL pid_t
SLEEPVAL unsigned
QSORTVAL void
LSEEKVAL off_t
FREEVAL void
_EXITVAL void
MISSING_SRC
MISSING_OBJ
PATH_COMPRESS /bin/compress
.DE
Make sure you use the C version of subst.
.PP
.DS
.UL "System V Release 4"
.ta \w'HAVE_ST_BLKSIZE 'u
FREEVAL void
GETPIDVAL long
HAVE_TM_GMTOFF DONT
HAVE_WAITPID DO
LDFLAGS
LIBS -lnsl -lsocket
LINTFILTER | sed -n -f ../sedf.sysv
LINTFLAGS -b -h $(DEFS)
LINTLIBSTYLE NONE
LOCK_STYLE FCNTL
MANPAGESTYLE NONE
MISSING_MAN strcasecmp.3
MISSING_OBJ strerror.o strcasecmp.o
MISSING_SRC strerror.c strcasecmp.c
_PATH_MAILCMD /usr/bin/mailx
POINTER void
QSORTVAL void
RANLIB
RES_STYLE TIMES
SIZE_T unsigned int
USE_CHAR_CONST DONT
USE_UNION_WAIT DONT
.DE
I was never able to get \fIlint\fP to be useful on the machine I used.
Some versions of System V (for example, Esix 4.0.3) need the following
LIBS value:
.DS
.ta \w'HAVE_ST_BLKSIZE 'u
LIBS -lresolv -lsocket -lnsl -L/usr/ccs/lib -lelf
.DE
On a Dell System V machine, you have to set \fIHAVE_UNIX_DOMAIN\fP to ``DONT.''
.PP
.DS
.UL "Ultrix 4.x (RISC)"
.ta \w'HAVE_ST_BLKSIZE 'u
ALARMVAL unsigned int
FREEVAL void
LDFLAGS
LINTFILTER | sed -n -f ../sedf.sysv
LINTFLAGS -b -u -x $(DEFS)
LSEEKVAL off_t
MISSING_MAN
MISSING_OBJ syslog.o strerror.o
MISSING_SRC syslog.c strerror.c
POINTER void
PROF -p
QSORTVAL void
SIZE_T unsigned int
SLEEPVAL unsigned int
_EXITVAL void
.DE
Ultrix also requires the new \fIsyslog\fP.
You cannot use \fImmap\fP; the Ultrix version of the system call is
for devices, not files.
Some sites have reported problems with using the \fIsyslog\fP that INN includes
(output doesn't show up, or floating point numbers are garbled, etc.).
The file \fIjtkohl-syslog-complete.tar.Z\fP in the \fI/pub/DEC\fP
directory on gatekeeper.dec.com has a ``for-Ultrix'' package that handles
both old and new \fIsyslog\fP calls.
While Ultrix has symlinks, it does not have the ``\-follow'' option in
its \fIfind\fP command.
This is used in \fIexpire/makeactive.c\fP; you will have to either install
the GNU \fIfind\fP or edit the source file.
.NH 1
Other Source Preparations
.PP
In addition to setting up the configuration file, it might be necessary
to do some other setups.
.NH 2
Systems with old syslogs
.PP
If you need to install the \fIsyslog\fP that is distributed with INN, go to
the top of the distribution and type ``make syslogfix''.
This will also compile \fIsyslogd\fP, the logging daemon.
You should install this to replace your existing daemon, usually in
\fI/etc/syslog\fP.
You will also need to install the new-style \fIsyslog.conf\fP file.
.PP
If you cannot replace \fIsyslogd\fP on your machine, then see the file
\fIsyslog/README\fP for information on how to set it up as an alternate
daemon.
.PP
Ignore any complaints from \fIlint\fP about the INN sources calling
\fIopenlog\fP with the wrong argument count.
In fact, if you \fBdon't\fP get any complaints, then something is wrong
with the way \fIsyslog\fP, \fI<syslog.h>\fP, or the \fIlint\fP libraries
are set up on your system.
.NH 2
The DBZ package
.PP
INN uses the DBZ database package.
Thanks to Jon Zeeff for his permission to use and redistribute DBZ,
as modified by Henry Spencer.
INN has its own set of modifications to DBZ.
The changes are made with the \fIpatch\fP program and the context diff
in \fIlib/dbz.pch\fP.
If you don't have \fIpatch\fP installed, then you can make the changes
manually.
(If you don't have Larry Wall's \fIpatch\fP program get it from any
\fIcomp.sources.unix\fP archive as well as many FSF archives and other
places \(em you'll be glad you did.)
.PP
Both \fIinnd\fP and \fInnrpd\fP have the option of keeping the DBZ
hash table in memory, under the control of the INND_DBZINCORE and
NNRP_DBZINCORE_DELAY parameters, respectively.
This can consume lots of RAM proportional to the size of your history
database, but it can also avoid a great deal of disk I/O.
You should probably see the DBZ manpage in the \fIdoc\fP directory
for some (brief) additional discussion of this issue.
.PP
Apparently the System V 386 compiler can't optimize \fIdbz.c\fP (the
GNU C compiler doesn't have this problem).
If you have ``\-O'' in your \fIDBZCFLAGS\fP configuration parameter, then
take it out.
.NH 2
Using writev
.PP
INN makes extensive use the \fIwritev\fP system call to write several
I/O buffers in a single call.
If you do not have \fIwritev\fP then you must copy \fIinclude/uio.h\fP to
your \fI/usr/include/sys\fP directory.
You must also add ``writev.c'' and ``writev.o'' to the MISSING_SRC and
MISSING_OBJ parameters.
.PP
The ``fake'' \fIwritev\fP found in the \fIlib\fP directory is not highly
efficient.
You might want to write a better one that tries to \fImalloc\fP a new
buffer and join all the elements.
Be careful about doing this because \fIinnd\fP can use very big buffers.
.NH 1
Compiling the System
.PP
Once the INN sources have been configured, they are ready to be compiled.
If you are very confident of your changes, type the following:
.DS
cd $inn
make all
.DE
If you do not get any errors, skip to the section titled ``Installing the
System.''
.PP
If you are confident, but careful, type:
.DS
cd $inn
make world
cat */lint
.DE
This will compile everything, then run \fIlint\fP in all directories.
.PP
Another option is to run the \fIBUILD\fP script found at the top of
the source tree.
This will interactively configure, compile, and install the system.
After running that script, skip to the section titled ``Installing the
System.''
.PP
If you are more cautious, you should type the following:
.DS
cd $inn/config
make quiet
cd ..
.DE
This will use your already-tested \fIsubst\fP program with your new
\fIconfig.data\fP file.
You should then follow the steps in the following sections.
.NH 2
Building the Library
.PP
The next step is to build the INN library.
Do the following
.DS
cd $inn/lib
make libinn.a lint
.DE
.PP
This will build the library and run \fIlint\fP on the sources, putting
the output into a file named \fIlint\fP.
If anything fails to compile, you probably made a configuration error,
most likely in the ``C library differences'' section.
In particular, double-check the \fISIGHANDLER\fP and \fIxxx_STYLE\fP
parameters.
.PP
The \fIlint\fP output should be almost empty, except for a couple of
\&``possible pointer alignment problem'' warnings in \fIdbz.c\fP.
If you get much more than this, then you probably did not define
the \fIPOINTER\fP or \fISIZE_T\fP parameters properly.
The \fINEW\fP and \fIRENEW\fP macros in \fIinclude/macros.h\fP try to
capture all the alignment problems associated with dynamic memory allocation.
Also double-check the \fIALIGNPTR\fP parameter and the \fICAST\fP macro in
\fIinclude/macros.h\fP.
.PP
If \fIlint\fP reports any other problems, you should take the time to
investigate them.
Note that many \fIlint\fP libraries have errors.
Also, you may get some problems in \fIyaccpar\fP in \fIparsedate.y\fP; these
are most likely in the \fIyacc\fP-generated C code.
If you get any of these, complain to your vendor.
.PP
If you find a portability issue that I missed, please let me know.
.PP
Once the library is built, you should install it in the top-level INN
directory.
To do this type ``make\ install'' while still in the \fIlib\fP directory.
This will also compile a \fIlint\fP library for use in linting the programs
in the other directories.
.PP
Note that any time a change is made to the library you must do
\&``make\ install''; it is not enough to type ``make\ libinn.a''.
This is a deliberate decision \(em like a program, compiling a library
is different from making it available for others to use, and installing
a library should make it possible to run \fIlint\fP against it.
.NH 2
Compiling the Programs
.PP
INN's programs are separated into six areas, as detailed in the roadmap.
You'll need to build each one before you can install and use INN.
.NH 3
The Frontend Programs
.PP
Frontends are those programs that talk to the main news server, either
offering it articles or controlling its action.
This includes the following programs:
.IP \fIinews\fP 15
The program that validates and prepares news articles and gives them to
\fIinnd\fP.
This is mostly used by users (usually indirectly, through programs like
\fIPnews\fP), but also through special facilities such as news/mail
gateways.
.IP \fIrnews\fP 15
Unpacks news batches from UUCP sites and offers them to \fIinnd\fP.
.IP \fIctlinnd\fP 15
This program controls \fIinnd\fP, directing it to do most of the
tasks a news administrator will have to do: create newsgroups,
update newsfeeds, and the like.
.IP \fIsys2nf\fP 15
A program to turn a B or C News \fIsys\fP file into an INN \fInewsfeeds\fP
file.
This is a transition aide that is only documented in the source.
.PP
To build these programs, type the following:
.DS
cd $inn/frontends
make all
.DE
.NH 3
Innd
.PP
The next program is the main news server, which includes the following
programs:
.IP \fIinnd\fP 15
\fIInnd\fP accepts all incoming NNTP connections and either processes
their traffic or hands them off to the NNTP ``newsreader'' server.
It accepts articles, files them, and queues them so that they can be
sent to downstream feeds.
\fIInnd\fP listens on the official NNTP port.
On most systems only root can do this.
\fIInnd\fP is careful to set the modes of any files it creates, as well as
the privileges of any processes it spawns.
.IP \fIinndstart\fP 15
Sites that are concerned about large root-access programs may wish
to install \fIinndstart\fP.
This program opens the port, changes its user and group ID to be that
of the news administrator, and then \fIexec\fP's \fIinnd\fP with the
open port.
It also sets up a secure execution environment.
It is a small program (about 100 lines) that is easily understood.
You should use it because \fIinnd\fP will run faster because it won't
have to make any \fIchown\fP system calls.
If you make \fIinndstart\fP setuid root then no news maintenance has to
be done as root.
.PP
To build these, type the following:
.DS
cd $inn/innd
make all
.DE
.PP
Note that \fIinnd\fP handles the filing and distribution of certain messages
differently from other systems.
For example, you can have newsgroups within ``control'' for the
different types of control messages.
See \fIinnd.8\fP, \fInewsfeeds.5\fP, and \fIactive.5\fP in the \fIdoc\fP
directory for details.
.NH 3
Nnrpd
.PP
\fIInnd\fP implements a subset of the NNTP protocol \(em only those commands
that are needed for peer sites to feed news articles.
You must install \fInnrpd\fP to allow users to read news.
If a connection comes in from a host that is not a specified feed,
then an \fInnrpd\fP process is spawned to handle it.
(You can debug \fInnrpd\fP by running it interactively; put an entry for
the host named ``stdin'' in your \fInnrp.access\fP file.)
.PP
Build the newsreader server by doing the following:
.DS
cd $inn/nnrpd
make all
.DE
Note that if users on a peer machine (one that feeds you news) want to
read news from your server, then you have two choices.
You can use \fInntpd\fP from the reference platform (See Appendix II)
and make sure not to list the peer in your \fInntp.access\fP file.
The other choice is to relink the reading software on the other machine
with the INN library so that it uses the ``mode reader'' NNTP command
extension.
.NH 3
The Backend Programs
.PP
The backend programs take articles that \fIinnd\fP received and offer them
to your news neighbors.
This includes the following programs:
.IP \fIarchive\fP 15
A simple program to archive news articles.
.IP \fIactsync\fP 15
A program to synchronize active file with remote site.
.IP \fIbatcher\fP 15
Collects articles into batches for UUCP delivery.
.IP \fIbuffchan\fP 15
A program to split a single \fIinnd\fP stream into separate files.
It can buffer data, flushing files based on command-line switches.
.IP \fIcrosspost\fP 15
A program that does link creation for cross-posted articles. Runs as a
channel feed and lets innd hand off some of its i/o activity.
.IP \fIcvtbatch\fP 15
A program to turn a file list into an INN batchfile.
This is a transition aide.
.IP \fIfilechan\fP 15
Another program to split a single \fIinnd\fP stream into separate files.
It is system-call intensive, but requires no locking protocol.
.IP \fIinnxbatch\fP 15
A program to send articles with ``XBATCH'' NNTP command extension.
.IP \fIinnxmit\fP 15
A replacement for \fInntpxmit\fP from the reference implementation.
It reads a file containing a list of articles, and sends them to a host.
.IP \fInntpget\fP 15
A program to retrieve articles from a remote site.
.IP \fIshlock\fP 15
A program to provide a locking protocol for shell scripts.
.IP \fIshrinkfile\fP 15
A program to shrink a file by removing lines from the beginning.
It is useful for purging backlogged batchfiles.
.PP
To build this set of programs, type the following:
.DS
cd $inn/backends
make all
.DE
.NH 3
Expire
.PP
This directory includes programs to modify the history database
as well as some utilities that might be useful in this task.
The database is called the \fIhistory\fP file, and it contains one
line for every article on the system, specifying when it was received
and where it was filed.
This file is indexed by the Message-ID, and the DBZ package provides fast
retrieval from it.
.IP \fIconvdate\fP 15
Converts between user-readable dates and the format used in the history file.
.IP \fIexpire\fP 15
Scans the history database to purge old entries, and remove old articles
from the spool area.
You can specify how long to keep sets of newsgroups.
.IP \fImakeactive\fP 15
This program can be used to rebuild the \fIactive\fP file if it is
lost in a crash.
.IP \fImakehistory\fP 15
This program scans through the spool area and rebuilds the history files.
.IP \fInewsrequeue\fP 15
This program can be used after a crash to resend articles to your neighbors.
.IP \fIprunehistory\fP 15
This is a tool for other programs that expire news.
It reads a list of Message-ID's and filenames, and updates the history
file to mark that the files have been deleted.
.PP
This directory also includes \fIexpire.pch\fP and \fIreap.pch\fP.
The first is a patch to the C News expire program that lets it cooperate
better with \fIinnd\fP, sending it messages when articles have been removed.
The second is a set of patches to the \fIreap\fP program that lets it
cooperate with \fIprunehistory\fP; it also adds some other useful features.
Both patch files have additional information in them.
Both programs are unsupported, provided by members of the beta-test group.
.PP
To build these programs, type the following:
.DS
cd $inn/expire
make all
.DE
.PP
If you are currently running C News, note that it has a directory named
\fIexpire\fP that is often the same pathname as INN's \fIexpire\fP program.
You will have to move, or remove, the directory before you can intall
the INN program.
.NH 3
Script and data files
.PP
In addition to the programs, INN requires several scripts.
For example, one script starts the server when the machine boots
while another prunes the log files and runs \fIexpire\fP every night.
Many of these scripts can be used as-is until you get a feel for
how INN works.
.PP
INN also requires several data files.
One specifies what sites feed you news, another what sites you feed, and
so on.
INN cannot provide these, other than giving sample entries.
You'll probably find that writing these files will be the hardest part of
your installation.
.PP
Prototypes for all these files are provided in the \fIsamples\fP directory.
Your modified copies should be maintained in the \fIsite\fP directory.
By splitting things up this way, official updates will never wipe out
any changes you have made.
.PP
To create the initial set of files, do the following:
.DS
cd $inn/site
make all
.DE
.PP
See below for an explanation of each file.
.NH 2
Manual pages
.PP
INN comes with an extensive set of manual pages.
You might want to edit the Makefile to set up the right ownership of
the installed manual pages.
Or you might want to not bother installing them at all.
.PP
When it comes to reading them, you should start with \fIinnd.8\fP
and \fIctlinnd.8\fP.
From there follow the cross-references as you want.
.NH 1
Installing the System
.PP
Although either \fIinnd\fP or \fIinndstart\fP must be run with root
privileges, the build and most of the installation does not have to be done
as root \(em only the installation of the inndstart executable requires
root priviledges, as it is installed as owned by root and setuid.
The \fI$inn/makedirs.sh\fP script creates all the necessary directories used
by INN, and sets up the right ownerships and modes: owned by \fINEWSUSER\fP
in group \fINEWSGROUP\fP with 0775 permissions (the ``firewall'' directory,
\fI_PATH_INDDDIR\fP, has mode 0770).
You should review this script, then run it.
.PP
The rest of the installation should be done as the news administrator
or as root.
The Makefiles are very strict about setting the modes on the files that
get installed.
To install the programs, do the following:
.DS
cd $inn
make update
.DE
This target does a ``make\ install'' in all program directories.
It installs the programs and manpages, but does not update or install
any configuration files or scripts.
This is important: in any directory (including the top-level one), a
\&``make\ install'' will install everything in that directory into
the right place.
A ``make\ update'' can only be done in the top-level directory or in the
\fIsite\fP directory. The former only replaces executables, not
configuration files.
When updating to a new INN release, you will probably want to do an ``update''
first, and then review the changed files by doing ``make\ diff'' in the
\fIsite\fP directory, and integrate your local changes as appropriate.
The Makefile also has other targets that you might find useful, so the
comments for entries like ``most'' and ``installed-diff'', for example.
.PP
The next, and last, step is to build your INN configuration files and utility
scripts.
If you have not already done so, type the following:
.DS
cd $inn/site
make all
.DE
This will get copies of the scripts and files from the
\fIsamples\fP directories and run \fIsubst\fP over them.
Whenever patches are issued, doing a \fImake\fP in this directory will let
you know what files have been updated, without destroying your local changes.
The \fIgetsafe.sh\fP script does this.
If you have either an \fISCCS\fP or an \fIRCS\fP directory then
\fIgetsafe.sh\fP will use the appropriate source control system for the
files in this directory.
.PP
The first set of files are used to carry out the control messages.
You might want to look them over; in particular, look at the table in
\fIcontrol.ctl\fP and the newslog manpages in \fIdoc\fP.
The control files are:
.DS
.ta 1.5i
checkgroups rmgroup
control.ctl sendme
default sendsys
docheckgroups senduuname
ihave version
newgroup writelog
parsecontrol pgpverify
.DE
.PP
The following scripts are normally invoked by \fIcron\fP or at
system boot time, and should not require many changes:
.DS
.ta 1.5i
innlog.pl scanlogs
innstat tally.control
news.daily tally.unwanted
rc.news
.DE
\fIRc.news\fP starts the server. In versions 1.4 and earlier, this script
was run by user root. In this version, \fIrc.news\fP must be run by the user
defined as the \fINEWSUSER\fP in the config.data file.
\fINews.daily\fP invokes \fIexpire\fP and \fIscanlogs\fP.
\fIScanlogs\fP calls the other scripts to process the logs.
You might want to review these scripts just to see what they do.
Do not get bogged down in the details, just read the comments.
They are documented in the manpages news.daily(8), newslog(5), and newslog(8).
.PP
There are some utility scripts to send news to your news feeds:
.DS
.ta 1.5i
nntpsend send-nntp
nntpsend.ctl send-uucp
send-ihave sendbatch
.DE
They flush and lock the batch file for the specified site(s) and then call
\fIinnxmit\fP to send the articles to your downstream feeds.
\fISend-ihave\fP is used for ``ihave/sendme'' feeds and is described
in an appendix.
\fISendbatch\fP and \fIsend-uucp\fP flush and lock batchfiles and call
\fIbatcher\fP to queue up UUCP jobs.
You might want to modify these files to change the flags given to \fIuux\fP;
the default is to queue jobs up as grade ``d.''
You will almost definitely have to edit them to make sure that they properly
parse the output of \fIdf\fP so that your spool area is not overrun!
\fINntpsend\fP and \fIsend-nntp\fP do the same thing for NNTP feeds.
You must determine how you want to propagate your articles \(em the scripts
give common ways of getting the job done.
.PP
The following files will have to be edited to contain your local information.
They all have manual pages in the \fIdoc\fP directory that describe them:
.DS
.ta 1.5i
expire.ctl newsfeeds
hosts.nntp nnrp.access
inn.conf passwd.nntp
moderators
.DE
.PP
The last group of files are utility scripts you might find useful:
.DS
.ta 1.5i
inncheck innwatch
scanspool
.DE
\fIInncheck\fP is a Perl script to check the syntax and permissions of
an installed INN system.
\fIInnreport\fP is an alternate way of summarizing the server's log file.
It is a Perl script. It will become the standard log reporting mechanism in
a future release.
\fIInnwatch\fP is a shell script to monitor the system and stop the server
when you are running low on disk space or inodes; it could be run out of your
\fI_PATH_NEWSBOOT\fP script \(em it is set to be run by default.
\fIScanspool\fP is a Perl script to make sure that the active file
and the contents of your spool tree agree.
.PP
Once you have made the necessary modifications (and I admit that some of
this \(em especially the \fInewsfeeds\fP file \(em will be difficult), you
should type the following:
.DS
make install
.DE
Make sure you have \fIrc.news\fP installed in the right place, as explained
in the ``Paths to common programs'' section, above.
You might find it useful to read the ``First-Time Usenet or NNTP Installation''
appendix for help on navigating through the INN configuration files.
.PP
There are now only a couple more things to check.
First, make sure you have an \fIactive\fP file and a \fIhistory\fP database!
The appendices explain how to convert your existing files; the \fIBUILD\fP
script will create new ones for you.
If you have Perl, run \fIinncheck\fP to make sure that you have the
datafiles configured correctly.
The second is make sure that you have correctly updated your \fIsyslog.conf\fP
file to match the filenames and logging levels required by INN.
See \fIsyslog/syslog.conf\fP for an example of what to do.
.PP
Once you have done all of this, InterNetNews is now installed, and ready
to run \(em have fun!
.NH 1
Heterogeneous Client Installations
.PP
The \fIinews\fP program is used by user newsreaders.
Programs such as \fIrn\fP (which call \fIPnews\fP) prepare a news article
and feed it into \fIinews\fP.
\fIInews\fP validates the news headers, adds its own, and feeds the article
to the campus \fIinnd\fP server.
The \fIinews\fP that comes with INN is more useful than the ``mini-inews''
that comes with the reference implementation.
You cannot run the standard B2.11 \fIinews\fP.
You can run the C News \fIinews\fP, but only on client machines (i.e.,
those with a \fI$NEWSCTL/server\fP file).
I recommend that you install INN's \fIinews\fP on all the clients in your
campus.
.PP
INN comes with a \fIMakeInews\fP script to make it easier to build and
install \fIinews\fP on a wide variety of hosts.
This script creates a directory and copies all the necessary files (headers,
sources, configuration files) into it.
The script takes an optional argument, which should name the client machine's
architecture.
For example:
.DS
cd $inn
\&./MakeInews sun3
.DE
will create an \fIinews.sun3\fP directory.
You can then examine the Makefile in that directory, and build and install
\fIinews\fP on your Sun-3 clients.
This is easiest if the client NFS-mounts the source directory \(em that
way you can keep all your \fIinews\fP sources in one place.
.PP
\fIRnews\fP only has to be available on the machine where you run UUCP
(and perhaps a mail-news gateway).
If this is not the same machine as where \fIinnd\fP is running, then the
\fIMakeRnews\fP script can be used in the same manner as the \fIMakeInews\fP
script.
|