1 CONFIGURATION AND INSTALLATION OF NN 2 ------------------------------------ 3 4 RELEASE 6.7 5 6 7This file describes the necessary steps to configure and install nn. 8You are advised to read this file before proceeding with the installation. 9 10If you've configured/installed nn before, you can probably ignore this file 11and proceed to editing config.h. Note that there are new variables in 12config.h, so copying one from nn-6.6 won't work. (Though it can obviously 13be used as a guide). 14 15The following command line prompts are used in the examples: 16 `$' is used when no special privileges are required. 17 `#' is used when SUPER USER privileges may be required. 18 19Note that this file still assumes in many places that you will be running 20nnmaster. If you are using NOV instead, you should ignore anything dealing 21with nnmaster and its database. If you are only installing the nn client, 22you can also ignore steps 3.5, 6, and 7. 23 24 25 STEP 1 26 27 CONFIGURATION OF MAKEFILE 28 ------------------------- 29 30Check the 'Makefile' file and supply the proper values for the 31following parameters: 32 33CC The command to invoke the C compiler 34 35CPP The command to invoke the C preprocessor with the result 36 written to the standard output stream. 37 38CFLAGS Flags to the C compiler (e.g. -O or -g) 39 40LDFLAGS Additional flags to the C compiler when linking executables 41 42Notice that mandatory system specific CFLAGS and LDFLAGS are usually 43defined in the s- file (see below). 44 45 46 STEP 2 47 48 CREATE CONFIGURATION FILE config.h 49 ---------------------------------- 50 51The configuration file is distributed in the file config.h-dist. You 52must COPY this to config.h before proceeding. Keep the original -dist 53file to allow patches to be applied to it if necessary. 54 55 $ cp config.h-dist config.h 56 57 58 STEP 3 59 60 EDIT config.h TO REFLECT YOUR SYSTEM 61 ------------------------------------ 62 63For each required configuration parameter, the config.h file contains 64verbose comments explaining the meaning of each parameter in the file. 65Read and follow these instructions carefully. If you do that, nn 66should compile and run without problems. 67 68Further information about the parameters can be found below in case 69you are in doubt. Regarding the NNTP related definitions, consult the 70file named olddoc/NNTP. Note that the information there is out of date. 71 72Notice that every time you edit config.h, the file update.h is 73modified to make a new configuration level for the version in the 74source directory. The current configuration is showed in the version 75string as #number. 76 77 78 STEP 3.1: SPECIFY NOV AND NNTP CONFIGURATION 79 ------------------------------------------------ 80 81If you will be connecting to a newsserver that uses NOV (and nearly all of 82them do these days), define NOV. 83 84If you use nn on a single system with news on its local disks, you 85will not have to worry the least about networking, and you simply 86leave NNTP undefined. 87 88 89 STEP 3.2: SELECT SYSTEM FILE 90 ---------------------------- 91 92A list of systems that nn runs on and their associated include files 93is found in the file MACHINES. 94 95If none of these can be used on your system, create your own based on 96the file conf/s-template.h. 97 98 99 STEP 3.3: SELECT MACHINE FILE 100 ----------------------------- 101 102A list of machines that nn runs on and their associated include files 103is found in the file MACHINES. 104 105If you cannot use one of these machine files create your own based on 106the file conf/m-template.h. 107 108 109 STEP 3.4: LOCALIZE NN 110 --------------------- 111 112You will have to specify a number of files and directories which nn 113has to know about to work properly. If you don't specify these, nn 114will in most cases use it own alternatives which will correspond to 115common practices on most installations. 116 117The following directories and files can be defined in config.h: 118 119 120BIN_DIRECTORY (mandatory) 121 122 The directory where you want the user programs to be 123 installed. The following programs will be installed in that 124 directory: 125 126 nn The news reader program 127 nnacct Accounting, quota, and access management 128 nnadmin The administration program (link to nn) 129 nncheck Check for unread articles (link to nn) 130 nngoback Mark older articles as unread (link to nn) 131 nngrab Faster keyword search 132 nngrep Grep for news groups (link to nn) 133 nnpost Standalone posting program (link to nn). 134 nnstats Collection and expiration statistics 135 nntidy Cleans up the rc file (link to nn) 136 nnusage Show usage statistics 137 nnview Reads mail folders (link to nn) 138 139 140LIB_DIRECTORY 141 142 The directory where nn's auxiliary programs and files will 143 be installed unless another directory is specified by one of 144 the following definitions. 145 146 147MASTER_DIRECTORY (optional, default = LIB_DIRECTORY) 148 149 The directory containing the nnmaster daemon programs. It 150 should not be shared in a networked environment! 151 152 back_act 153 Program to make daily copies of the active file to 154 allow nngoback to work. 155 156 nnmaster 157 The program building and maintaining nn's database. 158 159 nnspew Program to build a tertiary subject database for 160 nngrab. 161 162 MPID Exclusive lock file created by the currently running 163 nnmaster daemon process. Accessed by nnadmin to 164 get the daemon's process id. 165 166 GATE Message file created by nnadmin and deleted by nnmaster. 167 168 169CLIENT_DIRECTORY (optional, default = LIB_DIRECTORY) 170 171 Contains the auxiliary programs and files required by the nn 172 program: 173 174 aux The shell script used in connection with replies etc. 175 It knows about common editors like vi and gnu emacs to 176 have them position the cursor appropriately. To add 177 support for your own favorite editor, you should edit 178 the file aux.sh, not the compiled `aux' script! 179 180 upgrade_rc 181 Script used by nn to convert release 6.3 rc files to .newsrc 182 format when first invoked after upgrade to 6.4 or later. 183 184 185HELP_DIRECTORY (optional, default = CLIENT_DIRECTORY/help) 186 187 The directory where the help files and online manual are 188 stored. This directory is an obvious candidate for sharing in 189 a network. 190 191 192CACHE_DIRECTORY (optional, default = each user's .nn directory) 193 194 Only used with NNTP!! Directory to be used as a common storage 195 for temporary cache files when nn is used with NNTP. Using a 196 common directory for cache files allows you to clean these out 197 on reboot with a single "rm" command in the rc file: 198 (cd CACHE_DIRECTORY; rm -f *) 199 But of course this requires that you use a separate directory 200 for the cache! 201 202 203TMP_DIRECTORY (optional, default = /usr/tmp) 204 205 The directory to be used as temporary storage for files used 206 when editing responses etc. 207 208 209LOG_FILE (optional, default = LIB_DIRECTORY/Log) 210 211 The log file used by nnmaster and nn to store reports, error 212 messages, usage statistics, etc. 213 214 215NEWS_DIRECTORY (optional, default = /usr/spool/news) 216 217 The directory containing the news spool directories and files. 218 It is not required when a remote NNTP server is used. 219 220 221NEWS_LIB_DIRECTORY (optional, default = /usr/lib/news) 222 223 The directory containing the news system's active file and 224 other related files. 225 226 227 STEP 3.5: WHERE DO YOU WANT THE DATABASE? 228 ----------------------------------------- 229 230The following definitions in config.h are used to control where the 231database maintained by nnmaster is stored. The database consists of a 232couple of files containing global information for all existing groups, 233and a pair of files for each non-empty group. The database requires 234some disk space to hold the necessary information. On average about 235100 bytes per article in the system, or about 5% of the space 236allocated to the news articles. 237 238The database is intended to be shared together with the news spool 239directory in a networked environment provided that NETWORK_DATABASE is 240defined in config.h. 241 242If DB_DIRECTORY is not defined, the global database files will be 243located in a directory named NEWS_DIRECTORY/.nn, and the per-group 244files will be located in each individual news group's directory (named 245.nnd and .nnx). Using this strategy will normally require that 246nnmaster is owned "news" (OWNER in config.h). 247 248The location of the database can be changed via the following 249definitions in config.h: 250 251DB_DIRECTORY (optional, default = see above) 252 The directory containing the global database information files. 253 If you share /usr/spool/news via NFS or RFS, you can set DB to 254 something like /usr/spool/news/.nn to share it automatically 255 with /usr/spool/news. 256 257DB_DATA_DIRECTORY (optional, default = DB_DIRECTORY/DATA) 258 When DB_DIRECTORY is defined, the per-group files will no 259 longer be stored in the group directories, but in a single 260 common directory specified by DB_DATA_DIRECTORY. The files in 261 this directory will be named either by group number or by 262 group name (if DB_LONG_NAMES is also defined). 263 264 265The files config.h and NNTP describes how to share the database 266between several machines (also when you don't use NNTP). 267 268 269 STEP 4 270 271 COMPILE THE SOFTWARE 272 -------------------- 273 274To compile the software, you just have to run one of the following 275make commands. 276 277If you are making a complete package with both master and client, do 278 279 $ make all 280 281If you want to share a database which resides on another host (through 282NFS/RFS/rdist), you don't need a master on the local system, so you 283can do the following instead: 284 285 $ make client 286 287 288 STEP 5 289 290 INSTALLING THE SOFTWARE 291 ----------------------- 292 293Installation of the nn software is handled entirely via a script 294"./inst" created during the compilation. The components of nn are 295split into five parts, which can be installed separately or in various 296combinations depending on whether you run a stand-alone system or 297networked systems sharing the database and other parts of the nn 298package. The five components are: 299 3001) Master files and programs (machine dependent) 301 Install the MASTER_DIRECTORY programs. 302 3032) User files and programs (machine dependent, shareable) 304 Install the BIN_DIRECTORY programs. 305 3063) Auxiliary programs (configuration dependent, shareable) 307 Install the CLIENT_DIRECTORY files and programs. 308 3094) Documentation (shareable) 310 Install the MAN pages in the proper directories. 311 3125) Help files (shareable) 313 Install the HELP_DIRECTORY files (except online manual). 314 3156) Online manual (shareable with 5) 316 Format and install the online manual in HELP_DIRECTORY. 317 318 319Unless you have defined yourself as the owner of the nn package and 320have write permission on all the necessary directories, you will need 321to be super-user to install nn, so start with 322 323 $ su 324 325Now run the installation script: 326 327 # ./inst 328 329The `inst' script will list a menu with the following choices: 330 331(1)-(6) Install individual parts of the package. 332 333(s) Install a complete server + client package (1-6). 334 335(c) Install a client which accesses all its support files and 336 the database via a network (2). 337 338(h) Install a client with local auxiliary files, but shared 339 documentation and help files (2-3). 340 341(n) Install a client accessing only the database via a network (2-6). 342 343(m) Install only the nnmaster (1). 344 345(c) Install only the client programs (2). 346 347(u) Update already installed parts of the package. This will 348 check for the existence of the old programs, and only update 349 programs and files already installed. You will typically use 350 this after applying patches. 351 352You can also run the `inst' script with the choices as arguments, e.g. 353 354 ./inst m c 355 356 357NOTICE: Since nnmaster runs setuid OWNER, all users can potentially 358 kill the running master, initialize the database etc. if they 359 have access to execute the master. So either restrict the 360 permissions to execute nnmaster or the access to the directory 361 containing it. The default installation puts modes -rwsr-s--- 362 on nnmaster and leaves the directory "open" which may not be 363 adequate for you. 364 365 366 STEP 6 367 368 INITIALIZE THE DATABASE 369 ----------------------- 370 371If you have installed the nnmaster on the current system, you now have 372to initialize the database: 373 374 $ su -- also as superuser 375 # ./inst INIT 376 377If something goes wrong in this step, e.g. problems with the active 378file, you must redo the initialization after fixing the other 379problems. 380 381When the INIT operation completes, a database with empty entries for 382all the currently existing groups will have been created. If you want 383some special actions to be performed for specific groups as described 384in the nnmaster manual, you must now edit the GROUPS file created by 385nnmaster in the DB_DIRECTORY. If you modify the GROUPS file, you must 386run the following command to register the changes to the GROUPS file. 387 388 $ MASTER_DIRECTORY/nnmaster -G 389 390When you are ready, you must start nnmaster to enter all the existing 391articles into the database. If you use the following command, 392nnmaster will fork and return immediately; its background child will 393continue to update the database whenever new articles arrive: 394It will ignore articles which are more than 45 days old (-O). 395 396 $ MASTER_DIRECTORY/nnmaster -r -O45 397 398It may take quite a while before all existing articles have been 399entered into the database. You can use nnadmin's (U)pdate and (S)tat 400commands to trace the progress and the (L)og command to see if it has 401finished (a C entry will occur). You will see that many groups will 402be BLOCKED, but the number should decrease as nnmaster gets through 403more and more groups. 404 405You can also use the following command to do the initial collection of 406articles from a terminal and get a nice trace of the action: 407 408 $ MASTER_DIRECTORY/nnmaster -D -O45 409 410One or two numbers will be shown while a group is being collected. 411The first number is the number of the article currently being read. 412The (optional) second number will be the number of old (or bad) 413articles which nnmaster has ignored in the group so far. 414 415 416NOTICE: If the system file you have used does not specify how to 417 detatch a process from its controlling terminal, the nnmaster 418 may die when you log out. 419 420When nnmaster has finished the initial collection the articles, you 421can nnadmin's (V)alidate command to verify that the database build by 422nnmaster is consistent (restart nnadmin before verifying). 423 424 425 STEP 7 426 427 UPDATE SYSTEM FILES 428 ------------------- 429 430You will have to edit some of the scripts and files on your system to 431get the database and other support files updates automatically, also 432following system shutdown, crashes, etc. 433 434 435 STEP 7.1: START NNMASTER WHEN SYSTEM IS BOOTED 436 ---------------------------------------------- 437 438To have the database updated at all times, the nnmaster should be 439started when the system is booted. 440 441There will be a file named /etc/rc, a directory /etc/rc.d, or 442something similar on your system which contains commands that are 443executed when the system is booted. The following commands should be 444added to the boot scripts: 445 446 rm -f MASTER_DIRECTORY/MPID 447 MASTER_DIRECTORY/nnmaster -l -r -C 448 449 450Alternatively, you can arrange for cron to run the master regularly. 451In this case, you should not use the -r and -C options. Instead, you 452should let cron execute the command 'nnadmin Z' once a day to 453validate the database. For example: 454 455 0,10,20,30,40,50 * * * * MASTER/nnmaster -LM 456 0 0 * * * BIN/nnadmin Z 457 458 459WARNING: If you share the database via NFS or RFS, nnmaster should run 460 only on the system where the database actually resides!! 461 And preferably it should run on the host where the news spool 462 directory is located as well. This will improve speed as well 463 as reliability (NFS can suffer from time out problems). 464 465 466 STEP 7.2: SETUP EXPIRE ON THE DATABASE 467 -------------------------------------- 468 469To run expire on the database, you simply have to execute the 470following command (with sufficient privileges): 471 472 BIN_DIRECTORY/nnadmin =EYW 473 474You should arrange for expire to be run on nn's database whenever you 475have run expire on the news directories. 476 477Supposing you run the expire from your crontab, you may simply add the 478above command to the crontab at an appropriate time when you are 479certain that news' expire is completed. 480 481If you run nnmaster from cron rather than in daemon mode, you can use 482the following command to run expire on the database. 483 484 nnmaster -F -k "" 485 486This form allows you to run expire on selected groups rather than on 487all groups as initiated by the above nnadmin command. See the 488nnmaster manual for further details. 489 490 491 STEP 7.3: SAVE A COPY OF THE ACTIVE FILE ONCE A DAY 492 --------------------------------------------------- 493 494The `nngoback' program requires that the program `back_act' is 495executed once (and only once) every day to maintain suitable copies of 496the active files for the last 14 days. In a network environment, it 497should execute on the same host as the nnmaster. 498 499Simply arrange for back_act to be invoked by cron once a day 500(preferably just before the batch of news for `today' arrives). For 501example, assuming the news is received just before midnight (syntax 502and location of crontab entry may vary): 503 504In /usr/spool/cron/crontabs/news (System V): 505 00 23 * * * MASTER_DIRECTORY/back_act 506or in /usr/lib/crontab (BSD): 507 00 23 * * * su - news MASTER_DIRECTORY/back_act 508 509The default setup allows you to go 14 days back with nngoback, but if 510you don't keep news that long, there is no reason to keep that many 511copies of the active file either. In that case, you can supply the 512maximum number of days as an argument to back_act. Of course, you can 513also keep more than 14 copies of the active file to allow nngoback to 514go more than 14 days back by giving back_act an argument larger than 14. 515 516 517 STEP 7.4: PREPARE FOR NNSPEW TO BE RUN REGULARLY 518 ------------------------------------------------- 519 520The nngrab program will run faster if a dedicated subject database in 521addition to the normal database is available. To maintain this 522additional database, the program nnspew must be executed regularly, 523e.g. from cron. Every 3-6 hours should be sufficient to keep the 524database reasonably up-to-date, e.g. 525 526In /usr/spool/cron/crontabs/news (System V): 527 2 6,12,18 * * * MASTER_DIRECTORY/nnspew 528or in /usr/lib/crontab (BSD): 529 2 6,12,18 * * * su - news MASTER_DIRECTORY/nnspew 530 531 532 STEP 8 533 534 INSTALL AND EDIT GLOBAL FILES 535 ----------------------------- 536 537Depending on your needs, you should create the following files on each 538host running nn (you may also just share the files if you like): 539 540CLIENT_DIRECTORY/init 541 The global init file for all users on the system. Users will 542 be able to override the definitions in this file, but you can 543 probably make some sensible decisions which will prevent 544 novice users from getting into trouble, for example set the 545 default distribution to "local" etc. 546 547 You can also specify a global presentation sequence here. 548 549 You may use init.sample as a starting point, but don't use it 550 without careful examination. Especially, the sequence part 551 is mainly an illustration of the possibilities. If you are in 552 doubt, just delete the sequence part of the file (groups will 553 then be presented in pure alphabetical order). 554 555CLIENT_DIRECTORY/motd 556 Every time you change this file, it will be shown to the nn 557 users the next time they invoke nn. This can be used to 558 inform the users about changes in the news environment or 559 local policies. (motd = message of the day) 560 561 562NNTP_SERVER 563 Must contain the host name of the NNTP-server when NNTP is 564 used. If you already run NNTP with your other news readers, 565 this file does not need to be modified. 566 567 568 STEP 9 569 570 TEST THE BASIC FUNCTIONS 571 ------------------------ 572 573If any of the following tests fails or you see other peculiar 574behavior, you should consult the PROBLEMS file. You may not be the 575only one to have seen the problems, and there might even be a solution. 576 577First you should check that nnmaster does collect the articles it is 578supposed to. Here, nnadmin is a great help, since you can peek around 579in all the database files and see what nnmaster is doing. nnadmin 580takes a snap-shot of the database when it starts up, but you can take 581a new snap-shot at any time using the (U)pdate command. 582 583Also look at the (L)og to see that there were no problems while 584collecting the articles. 585 586There are a few things you should check to ensure the proper 587functioning of nn. 588 5891) Backup your current .newsrc file if you have one. (Don't save it 590 in .newsrc.bak or .newsrc.orig since nn may use these names). 591 5922) Run `nn'. If you have upgraded from release 6.3, nn will convert 593 your release 6.3 .nn/rc file into a .newsrc file. 594 5953) Does nn find any news? If not, does nn -x find anything? 596 5974) Can you send mail to yourself? Try the sequence: 598 m (return) (return) testing (return) 599 edit the letter 600 s (return) 601 602 If not, you should check the REC_MAIL program. 603 6045) Can you post an article to the local test group? Try: 605 :post (return) 606 test (return) 607 local (return) 608 edit the article 609 s (return) 610 611 If not, you should check the INEWS program. 612 613 614 ------------------------------------------- 615 IF EVERYTHING WORKS 616 YOU HAVE COMPLETED THE INSTALLATION 617 ------------------------------------------- 618 619 620 UPDATING THE SOFTWARE 621 --------------------- 622 623Patches to this software will be distributes as context diff's which 624can be applied using Larry Wall's `patch' program. 625 626After applying the patches, you will need to redo the compilation and 627installation steps: 628 629 $ patch -p0 < PATCH_FILE (or use nn's :patch command) 630 $ make all 631 $ su 632 # ./inst u 633 634To be able to install a new nnmaster, the currently running master (if 635any) will be stopped automatically, and it has to be started manually 636when the installation is complete (unless it is setup to be run by cron). 637 638Notice that unless it is explicitly required in the patch, there is no 639need to reinitialize the database after applying the patch. 640