Debian Codegraph @

upstream/debian-unstable/man1/suck.1

raw
1 .\" $Revision: 4.2.0 $
2 .TH SUCK 1
3 .SH NAME
4 suck - Pull a small newsfeed from an NNTP server, avoiding the NEWNEWS command.
5 .SH SYNOPSIS
6 .I suck
7 [
8 .BI
9 hostname
10 ]
11 [
12 .BI @filename
13 ]
14 [
15 .BI \-V
16 ]
17 [
18 .BI \-K
19 ]
20 [
21 .BI \-L[SL]
22 ]
23 [
24 .BI \-LF
25 filename
26 ]
27 [
28 .BI \-H
29 ]
30 [
31 .BI \-HF
32 filename
33 ]
34 [
35 .BI \-d[tmd]
36 dirname
37 ]
38 [
39 .BI \-s\ |\ \-S
40 filename
41 ]
42 [
43 .BI \-e\ |\ \-E
44 filename
45 ]
46 [
47 .BI \-a
48 ]
49 [
50 .BI \-m
51 ]
52 [
53 .BI \-b[irlf]
54 batchfile
55 ]
56 [
57 .BI \-r
58 filesize
59 ]
60 [
61 .BI \-p
62 extension
63 ]
64 [
65 .BI \-U
66 userid
67 ]
68 [
69 .BI \-P
70 password
71 ]
72 [
73 .BI \-Q
74 ]
75 [
76 .BI \-c
77 ]
78 [
79 .BI \-M
80 ]
81 [
82 .BI \-N
83 port_number
84 ]
85 [
86 .BI \-W
87 pause_time pause_nr_msgs
88 ]
89 [
90 .BI \-w
91 pause_time pause_nr_msgs
92 ]
93 [
94 .BI \-l
95 phrase_file
96 ]
97 [
98 .BI \-D
99 ]
100 [
101 .BI \-R
102 ]
103 [
104 .BI \-q
105 ]
106 [
107 .BI \-C
108 count
109 ]
110 [
111 .BI \-k
112 ]
113 [
114 .BI \-A
115 ]
116 [
117 .BI \-AL
118 activefile
119 ]
120 [
121 .BI \-hl
122 localhost
123 ]
124 [
125 .BI \-bp
126 ]
127 [
128 .BI \-T
129 timeout
130 ]
131 [
132 .BI \-n
133 ]
134 [
135 .BI \-u
136 ]
137 [
138 .BI \-z
139 ]
140 [
141 .BI \-x
142 ]
143 [
144 .BI \-B
145 ]
146 [
147 .BI \-O
148 ]
149 [
150 .BI \-G
151 ]
152 [
153 .BI \-X
154 ]
155 [
156 .BI \-f
157 ]
158 [
159 .BI \-y
160 post_filter
161 ]
162 [
163 .BI \-F
164 ]
165 [
166 .BI \-g
167 ]
168 [
169 .BI \-i
170 number_to_read
171 ]
172 [
173 .BI \-Z
174 ]
175 [
176 .BI \-rc
177 ]
178 [
179 .BI \-lr
180 ]
181 [
182 .BI \-sg
183 ]
184 [
185 .BI \-ssl
186 ]
187 [
188 .BI \-SSL
189 ]
190
191 Options valid in all modes
192
193 hostname
194
195 The hostname may optionally include the port number, in the form
196 .BI Host:Port.
197 If this option is used, any port number specified
198 via the -N option is ignored.
199
200 \@filename
201
202 This option tells suck to read other options from a file in addition to the
203 commandline.
204
205 \-a
206
207 This option forces suck to always batch up any downloaded articles,
208 even if suck aborts for any reason. Without this option, suck will
209 only batch up articles if it finishes successfully or is cancelled by
210 a signal (see below).
211
212 \-A
213
214 This option tells suck to scan the localhost (specified with the \-hl option) and use its active file
215 to build and update the sucknewsrc. If you add a group to your local server, suck will add it to
216 sucknewsrc and download articles. Or, if you delete a group from your local server, it will be deleted
217 from sucknewsrc. If posting is not allowed to a particular group, then the line in sucknewsrc is
218 just commented out. With this option, you should never have to edit your sucknewsrc. In case you have
219 newsgroups (like control and junk) that you don't want downloaded, you can put these newsgroups in a
220 file "active-ignore", one per line, and suck will ignore these newsgroups when it scans the localhost.
221 If your system supports regex(), you may use regular expressions in the active-ignore file to skip multiple groups, eg: fred\.*.
222 If you use the -p (postfix) option, suck will check for the existence of an active-ignore file with the
223 postfix. If that doesn't exist, then suck will check for the existence of the file without the postfix.
224
225 NOTE: If the localhost is on a non-standard port, the port number may be specified as part of the hostname,
226 in the form
227 .BI Host:Port.
228
229 NOTE: If you use regular expressions, suck will silently add a "^" to the beginning of the group name,
230 and a "$" to the end of the group name if they aren't already present, so that if you have "comp.os.linux",
231 it won't match "comp.os.linux.answers" or if you have "alt.test" it doesn't match "comp.alt.test".
232
233 \-AL activefile
234
235 This option is identical to the -A option, except it reads the active file from the local file specified instead of
236 reading it from the localhost. All the caveats from the -A option apply to this option as well. If both
237 options are used on the command line, suck first tries to use the -A option, then if that fails it uses
238 this option.
239
240 \-B
241
242 This option tells suck to attempt to batch up any articles in its directory
243 BEFORE starting to download messages. This can be useful if you have a
244 problem with the previous download. This option will only work if you specify
245 a batch option (see below). If there are no messages to batch up, some
246 of the batch options may produce warning messages. They may be safely ignored.
247 Also, if the batch files exist at the end of the run, in inn-batch mode, it
248 will be overwritten, since the new batch file will contain all messages. In
249 rnews mode, if the batch file exists, it will abort and not batch up any messages.
250
251 \-c
252
253 If this option is specified, suck will clean up after itself. This includes:
254 .RS
255 1. Moving sucknewsrc to sucknewsrc.old
256 .RE
257 .RS
258 2. Moving suck.newrc to sucknewsrc
259 .RE
260 .RS
261 3. rm suck.sorted and suckothermsgs.
262 .RE
263
264 \-C count
265
266 This option tells suck to drop the connection and reopen it every count number of articles.
267 This is designed to battle INN's LIKE_PULLERS=DONT option, that some folks compile in. With
268 LIKE_PULLERS=DONT, after 100 messages INN will pause between every message, dramatically
269 reducing your download speed. I don't recommend the use of this, but if you have no other choice....
270
271 \-dd dirname
272
273 \-dm dirname
274
275 \-dt dirname
276
277 Specify the location of the various files used by suck.
278
279 \-dd dirname = directory of data files used by suck (sucknewsrc suckkillfile suckothermsgs active-ignore sucknodownload)
280
281 \-dm dirname = directory for storage of articles created in Multifile mode
282 or batch mode. DO NOT make this the same as the directories used for the
283 \-dt or -\dd options, or you will lose all your configuration files.
284
285 \-dt dirname = directory of temp files created by suck (suck.newrc, suck.sort, suck.restart, suck.killlog, suck.post).
286
287 \-D
288
289 This option tells suck to log various debugging messages to "debug.suck", primarily
290 for use by the maintainer.
291
292 \-e | \-E filename
293
294 These options will send all error messages (normally displayed on stderr), to
295 an alternate file. The lower case version, -e, will send the error messages
296 to the compiled-in default defined in suck_config.h. The default is suck.errlog.
297 The upper case version, -E, requires the filename parameter. All error messages
298 will then be sent to this file.
299
300 \-f
301
302 This option tells suck to reconnect after deduping, and before downloading the articles. This is in case
303 long dedupe times cause timeouts on the remote end.
304
305 \-F
306
307 This option tells suck to reconnect after reading the local active file, and before downloading the Msg-IDs.
308 This is in case of a large active file, which causes timeouts on the remote end.
309
310 \-g
311
312 This option causes suck to only download the headers of any selected articles.
313 As a result of this, any batching of articles is skipped. This option does
314 work with killfiles, however, killfile options such as BODYSIZE> will be
315 ignored, since the body of the article will never be downloaded.
316
317 \-G
318
319 This option causes suck to display the message count and BPS status lines in a slightly different format,
320 more suitable for use by a filter program (such as a GUI).
321
322 \-H
323
324 This option will cause suck to bypass the history check.
325
326 \-HF history_file_name
327
328 This option tells suck the location of the history file. The default is at /var/lib/news/history.
329
330 \-hl localhost
331
332 This option specifies the localhost name. This option is required with both the \-A and the \-bp option.
333
334 \-i number_to_read
335
336 This option tells suck the number of articles to download if you are using the -A
337 or -AL option, and a new group is added. The default is defined in suck_config.h (ACTIVE_DEFAULT_LASTREAD, currently -100). NOTE: This must be a negative
338 number (eg -100, -50), or 0, to download all articles currently available in
339 the group.
340
341 \-k
342
343 This option tells suck to NOT attach the postfix from the \-p option to the names of the killfiles,
344 both the master killfile and any group files. This allows you to maintain one set of killfiles for
345 multiple servers.
346
347 \-K
348
349 This option will cause suck to bypass checking the killfile(s).
350
351 \-l phrase_file
352
353 This option tells suck to load in an alternate phrase file, instead of using
354 the built-in messages. This allows you to have suck print phrases in another
355 language, or to allow you to customize the messages without re-building suck.
356 See below.
357
358 \-lr
359
360 This option, is used in conjunction with the highest article option in the sucknewsrc, to
361 download the oldest articles, vice the newest articles. See that section for more details.
362
363 \-L
364
365 This option tells suck to NOT log killed articles to suck.killlog.
366
367 \-LF filename
368
369 This option allows you to override the built-in default of "suck.killlog" for the
370 file which contains the log entries for killed articles.
371
372 \-LL
373
374 This option tells suck to create long log entries for each killed article. The long
375 entry contains the short log entry and the header for the killed message.
376
377 \-LS
378
379 This option tells suck to create short log entries for each killed article. The short
380 entry contains which group and which pattern was matched, as well as the MsgID of the
381 killed article.
382
383 \-M
384
385 This option tells suck to send the "mode reader" command to the remote
386 server. If you get an invalid command message immediately
387 after the welcome announcement, then try this option.
388
389 \-n
390
391 This option tells suck to use the article number vice the MsgId to retrieve the articles. This
392 option is supposedly less harsh on the remote server. It can also eliminate problems if your
393 ISP ages off articles quickly and you frequently get "article not found" errors.
394 Also, if your ISP uses DNEWS, you might need this option so that it knows you're reading articles in a group.
395
396 \-N port_number
397
398 This option tells suck to use an alternate NNRP port number when connecting
399 to the host, instead of the default, 119.
400
401 \-O
402
403 This option tells suck to skip the first article upon restart. This is used whenever
404 there is a problem with an article on the remote server. For some reasons, some
405 NNTP servers, when they have a problem with a particular article, they time out.
406 Yet, when you restart, you're back on the same article, and you time out again.
407 This option tells suck to skip the first article upon restart, so that you can
408 get the rest of the articles.
409
410 \-p extension
411
412 This extension is added to all files so that you can have multiple site feeds.
413 For example, if you specify -p .dummy, then suck looks for sucknewsrc.dummy, suckkillfile.dummy,
414 etc, and creates its temp files with the same extension. This will allow you to keep
415 multiple sucknewsrc files, one for each site.
416
417 \-q
418
419 This option tells suck to not display the BPS and article count messages during download.
420 Handy when running suck unattended, such as from a crontab.
421
422 \-R
423
424 This option tells suck to skip a rescan of the remote newserver upon a restart. The
425 default is to rescan the newserver for any new articles whenever suck runs, including
426 restarts.
427
428 \-rc
429
430 This option tells suck to change its behavior when the remote server resets its article
431 counters. The default behavior is to reset the lastread in sucknewsrc to the current
432 high article counter. With this option, suck resets the lastread in sucknewsrc to the
433 current low article counter, causing it to suck all articles in the group, and using
434 the historydb routines to dedupe existing articles.
435
436 \-s | \-S filename
437
438 These options will send all status messages (normally displayed on stdout), to
439 an alternate file. The lower case version, -s, will send the status messages
440 to the compiled-in default defined in suck_config.h. The default is /dev/null,
441 so no status messages will be displayed. The upper case version, -S, requires
442 the filename parameter. All status messages will then be sent to this file.
443
444 \-sg
445
446 This option tells suck to add the name of the current group being downloaded, if known,
447 to the BPS display. Typically the only time suck doesn't know the group name is if
448 an article is downloaded via the suckothermsgs file.
449
450 \-ssl
451
452 This option tells suck to use SSL to talk to the remote server, if suck was compiled with
453 SSL support.
454
455 \-SSL
456
457 This option tells suck to use SSL to talk to the local server, if suck was compiled with
458 SSL support.
459
460 \-T timeout
461
462 This option overrides the compiled-in TIMEOUT value. This is how long suck waits for data from the
463 remote host before timing out and aborting. The timeout value is in seconds.
464
465 \-u
466
467 This option tells suck to send the AUTHINFO USER command immediately upon connect to the
468 remote server, rather than wait for a request for authorization. You must supply the
469 \-U and \-P options when you use this option.
470
471 \-U userid
472
473 \-P password
474
475 These two options let you specify a userid and password, if your NNTP server
476 requires them.
477
478 \-Q
479
480 This option tells suck to get the userid and password for NNTP authentication from
481 the environment variables "NNTP_USER" and "NNTP_PASS" vice the -U or -P password.
482 This prevents a potential security problem where someone doing a ps command can
483 see your userid and password.
484
485 \-V
486
487 This option will cause suck to print out the version number and then exit.
488
489 \-w pause_timer pause_nr_msgs
490
491 This option allows you to slow down suck while pulling articles. If you
492 send suck a predefined signal (default SIGUSR1, see suck_config.h),
493 suck will swap the default pause options (if specified by the -W option),
494 with the values from this option. For example, you run suck with -w 2 2,
495 and you send suck a SIGUSR1 (using kill), suck will then pause 2 seconds
496 between every other message, allowing the server to "catch its breath."
497 If you send suck another SIGUSR1, then suck will put back the default
498 pause options. If no pause options were specified on the command line
499 (you omitted -W), then suck will return to the default full speed pull.
500
501 \-W pause_time pause_nr_msgs
502
503 This option tells suck to pause between the download of articles. You need
504 to specify how long to pause (in seconds), and how often to pause (every X nr
505 of articles). Ex: \-W 10 100 would cause suck to pause for 10 seconds every
506 100 articles. Why would you want to do this? Suck can cause heavy loads on
507 a remote server, and this pause allows the server to "catch its breath."
508
509 \-x
510
511 This option tells suck to not check the Message-IDs for the ending > character. This option
512 is for brain dead NNTP servers that truncate the XHDR information at 72 characters.
513
514 \-X
515
516 This option tells suck to bypass the XOVER killfiles.
517
518 \-y post_filter
519
520 This option is only valid when using any of batch modes. It allows you to edit any or all of
521 the articles downloaded before posting to the local host. See below for more details.
522
523 \-z
524
525 This option tells suck to bypass the normal deduping process. This is primarily for
526 slow machines where the deduping takes longer than the download of messages would. Not
527 recommended.
528
529 \-Z
530
531 This option tells suck to use the XOVER command vice the XHDR command to retrieve the
532 information needed to download articles. Use this if your remote news server doesn't
533 support the XHDR command.
534
535 .SH LONG OPTION EQUIVALENTS
536 .RS
537 \-a \-\-always_batch
538 .RE
539 .RS
540 \-bi \-\-batch-inn
541 .RE
542 .RS
543 \-br \-\-batch_rnews
544 .RE
545 .RS
546 \-bl \-\-batch_lmove
547 .RE
548 .RS
549 \-bf \-\-batch_innfeed
550 .RE
551 .RS
552 \-bp \-\-batch_post
553 .RE
554 .RS
555 \-c \-\-cleanup
556 .RE
557 .RS
558 \-dt \-\-dir_temp
559 .RE
560 .RS
561 \-dd \-\-dir_data
562 .RE
563 .RS
564 \-dm \-\-dir_msgs
565 .RE
566 .RS
567 \-e \-\-def_error_log
568 .RE
569 .RS
570 \-f \-\-reconnect_dedupe
571 .RE
572 .RS
573 \-g \-\-header_only
574 .RE
575 .RS
576 \-h \-\-host
577 .RE
578 .RS
579 \-hl \-\-localhost
580 .RE
581 .RS
582 \-k \-\-kill_no_postfix
583 .RE
584 .RS
585 \-l \-\-language_file
586 .RE
587 .RS
588 \-lr \-\-low_read
589 .RE
590 .RS
591 \-m \-\-multifile
592 .RE
593 .RS
594 \-n \-\-number_mode
595 .RE
596 .RS
597 \-p \-\-postfix
598 .RE
599 .RS
600 \-q \-\-quiet
601 .RE
602 .RS
603 \-r \-\-rnews_size
604 .RE
605 .RS
606 \-rc \-\-resetcounter
607 .RE
608 .RS
609 \-s \-\-def_status_log
610 .RE
611 .RS
612 \-sg \-\-show_group
613 .RE
614 .RS
615 \-ssl \-\-use_ssl
616 .RE
617 .RS
618 \-w \-\-wait_signal
619 .RE
620 .RS
621 \-x \-\-no_chk_msgid
622 .RE
623 .RS
624 \-y \-\-post_filter
625 .RE
626 .RS
627 \-z \-\-no_dedupe
628 .RE
629 .RS
630 \-A \-\-active
631 .RE
632 .RS
633 \-AL \-\-read_active
634 .RS
635 .RE
636 \-B \-\-pre-batch
637 .RE
638 .RS
639 \-C \-\-reconnect
640 .RE
641 .RS
642 \-D \-\-debug
643 .RE
644 .RS
645 \-E \-\-error_log
646 .RE
647 .RS
648 \-G \-\-use_gui
649 .RE
650 .RS
651 \-H \-\-no_history
652 .RE
653 .RS
654 \-HF \-\-history_file
655 .RE
656 .RS
657 \-K \-\-killfile
658 .RE
659 .RS
660 \-L \-\-kill_log_none
661 .RE
662 .RS
663 \-LS \-\-kill_log_short
664 .RE
665 .RS
666 \-LL \-\-kill_log_long
667 .RE
668 .RS
669 \-M \-\-mode_reader
670 .RE
671 .RS
672 \-N \-\-portnr
673 .RE
674 .RS
675 \-O \-\-skip_on_restart
676 .RE
677 .RS
678 \-P \-\-password
679 .RE
680 .RS
681 \-Q \-\-password_env
682 .RE
683 .RS
684 \-R \-\-no_rescan
685 .RE
686 .RS
687 \-S \-\-status_log
688 .RE
689 .RS
690 \-SSL \-\-local_use_ssl
691 .RS
692 \-T \-\-timeout
693 .RE
694 .RS
695 \-U \-\-userid
696 .RE
697 .RS
698 \-V \-\-version
699 .RE
700 .RS
701 \-W \-\-wait
702 .RE
703 .RS
704 \-X \-\-no_xover
705 .RE
706 .RS
707 \-Z \-\-use_xover
708 .RE
709
710 .SH DESCRIPTION
711
712 .SH MODE 1 \- stdout mode
713 .RS
714 %suck
715 .RE
716 .RS
717 %suck myhost.com
718 .RE
719 .PP
720 Suck grabs news from an NNTP server and sends the articles to
721 stdout. Suck accepts as argument the name of an NNTP server or
722 if you don't give an argument it will take the environment variable
723 NNTPSERVER. You can redirect the articles to a file or compress them
724 on the fly like "suck server.domain | gzip \-9 > output.gz".
725 Now it's up to you what you do with the articles. Maybe
726 you have the output already on your local machine because you
727 used a slip line or you still have to transfer the output to your
728 local machine.
729 .SH MODE 2 \- Multifile mode
730 .RS
731 %suck \-m
732 .RE
733 .RS
734 %suck myhost.com \-m
735 .RE
736 .PP
737 Suck grabs news from an NNTP server and stores each article in a
738 separate file. They are stored in the directory specified in suck_config.h or
739 by the \-dm command line option.
740 .SH MODE 3 \- Batch mode
741 .RS
742 %suck myhost.com \-b[irlf] batchfile
743 .RE
744 .RS
745 or %suck myhost.com \-bp -hl localhost
746 .RE
747 .RS
748 or %suck myhost.com \-bP NR -hl localhost
749 .RE
750 .RS
751 %suck myhost.com \-b[irlf] batchfile
752 .RE
753 .PP
754 Suck will grab news articles from an NNTP server and store them
755 into files, one for each article (Multifile mode). The location of the files
756 is based on the defines in suck_config.h and the command line \-dm.
757 Once suck is done downloading the articles, it will build a batch file
758 which can be processed by either innxmit or rnews, or it will call lmove
759 to put the files directly into the news/group/number format.
760
761 \-bi \- build batch file for innxmit. The articles are left intact,
762 and a batchfile is built with a one\-up listing of the full path of each article.
763 Then innxmit can be called:
764
765 .RS
766 %innxmit localhost batchfile
767 .RE
768
769 \-bl \- suck will call lmove to put the articles into
770 news/group/number format. You must provide the name of the
771 configuration file on the command line. The following arguments from suck
772 are passed to lmove:
773
774 .RS
775 The configuration file name (the batchfile name provided with this option)
776 .RE
777 .RS
778 The directory specified for articles (-dm or built-in default).
779 .RE
780 .RS
781 The errorlog to log errors to (-e or -E), if provided on the command line.
782 .RE
783 .RS
784 The phrases file (-l), if provided on the command line.
785 .RE
786 .RS
787 The Debug option, if provided on the command line.
788 .RE
789
790 \-br \- build batch file for rnews. The articles are
791 concatenated together, with the #!rnews size
792 article separator. This can the be fed to rnews:
793
794 .RS
795 %rnews \-S localhost batchfile
796 .RE
797
798 \-r filesize specify maximum batch file size for rnews. This option
799 allows you to specify the maximum size of a batch file to be fed to rnews.
800 When this limit is reached, a new batch file is created AFTER I finish
801 writing the current article to the old batch file. The second and
802 successive batch files get a 1 up sequence number attached to the
803 file name specified with the -br. Note that since I have to finish
804 writing out the current article after reaching the limit, the
805 max file size is only approximate.
806
807 \-bf \- build a batch file for innfeed. This batchfile contains the
808 MsgID and full path of each article. The main difference between this
809 and the innxmit option is that the innfeed file is built as the articles
810 are downloaded, so that innfeed can be posting the articles, even while
811 more articles are downloaded.
812
813 \-bp \- This option tells suck to build a batch file, and post the articles
814 in that batchfile to the localhost (specified with the \-hl option). This option
815 uses the IHAVE command to post all downloaded articles to the local host.
816 The batch file is called suck.post, and is put in the temporary directory (-dt).
817 It is deleted upon completion, as are the successfully posted articles.
818 If the article is not wanted by the server (usually because it already exists on
819 the server, or it is too old), the article is also deleted. If other errors
820 occur, the article is NOT deleted.
821 With the following command line, you can download and post articles without
822 worrying if you are using INND or CNEWS.
823
824 .RS
825 %suck news.server.com -bp -hl localhost -A -c
826 .RE
827
828 \-bP NR \- This option works identically to \-bp above, except instead of
829 waiting until all articles are downloaded, it will post them to the local
830 server after downloading NR of articles.
831
832 .RS
833 %suck news.server.com -bP 100 -hl localhost -A -c
834 .RE
835
836 .SH SUCK ARGUMENT FILE
837 .PP
838 If you specify @filename on the command line, suck will read from filename and
839 parse it for any arguments that you wish to pass to suck. You specify the
840 same arguments in this file as you do on the command line. The arguments
841 can be on one line, or spread out among more than one line. You may also
842 use comments. Comments begin with '#' and go to the end of a line. All
843 command line arguments override arguments in the file.
844
845 .RS
846 # Sample Argument file
847 .RE
848 .RS
849 -bi batch # batch file option
850 .RE
851 .RS
852 -M # use mode reader option
853 .RE
854
855 .SH SUCKNEWSRC
856 .PP
857 Suck looks for a file
858 .I sucknewsrc
859 to see what articles you want and
860 which you already received. The format of sucknewsrc is very simple. It
861 consists of one line for each newsgroup. The line contains two or
862 three fields.
863
864 The first field is the name of the group.
865
866 The second field is the highest article number that was in the group
867 when that group was last downloaded.
868
869 The third field, which is optional, limits the number of articles which
870 can be downloaded at any given time. If there are more articles than this
871 number, only the newest are downloaded. If the third field is 0, then
872 no new messages are downloaded. If the command line option \-lr is specified,
873 instead of downloading the newest articles, suck will download the oldest
874 articles instead.
875
876 The fields are separated by a space.
877
878 .RS
879 comp.os.linux.announce 1 [ 100 ]
880 .RE
881 .PP
882 When suck is finished, it creates the file suck.newrc which contains the
883 new sucknewsrc with the updated article numbers.
884 .PP
885 To add a new newsgroup, just stick it in sucknewsrc, with a
886 highest article number of \-1 (or any number less than 0).
887 Suck will then get the newest X number of messages for that newsgroup.
888 For example, a -100 would cause suck to download the newest 100
889 articles for that newsgroup.
890 .PP
891 To tell suck to skip a newsgroup, put a # as the first
892 character of a line.
893
894 .SH SUCKKILLFILE and SUCKXOVER
895 There are two types of killfiles supported in suck. The first, via
896 the file suckkillfile, kills articles based on information in the
897 actual article header or body. The second, via the file suckxover,
898 kills articles based on the information retreived via the NNTP command
899 XOVER. They are implemented in two fundamentally different ways. The
900 suckkillfile killing is done as the articles are downloaded, one at a
901 time. The XOVER killing is done while suck is getting the list of articles
902 to download, and before a single article is downloaded. You may use
903 either, none or both type of killfiles.
904
905 .SH SUCKKILLFILE and GROUP KEEP/KILLFILES
906 If
907 .I suckkillfile
908 exists, the headers of all articles will be scanned and the article downloaded or not,
909 based on the parameters in the files. If no logging option is specified (see the -L options
910 above), then the long logging option is used.
911 .PP
912 Comments lines are allowed in the killfiles. A comment line has a "#" in the first position.
913 Everything on a comment line is ignored.
914 .PP
915 Here's how the whole keep/delete package works. All articles are checked against the
916 master kill file (suckkillfile). If an article is not killed by the master kill file,
917 then its group line is parsed. If a group file exists for one of the groups then the
918 article is checked against that group file. If it matches a keep file, then it is
919 kept, otherwise it is flagged for deletion. If it matches a delete file, then it is
920 flagged for deletion, otherwise it is kept. This is done for every group on the group line.
921 .PP
922 NOTES: With the exception of the USE_EXTENDED_REGEX parameter, none of these parameters are
923 passed from the master killfile to the individual group file. Each killfile is separate
924 and independant. Also, each search is case-insensitive unless specifically specified by starting the
925 search string with the QUOTE character (see below). However, the parameter part of the
926 search expression (the LOWLINE=, HILINE= part) is case sensitive.
927 .SH
928 PARAMETERS
929 .RS
930 LOWLINES=#######
931 .RE
932 .RS
933 HILINES=#######
934 .RE
935 .RS
936 NRGRPS=####
937 .RE
938 .RS
939 NRXREF=####
940 .RE
941 .RS
942 QUOTE=c
943 .RE
944 .RS
945 NON_REGEX=c
946 .RE
947 .RS
948 GROUP=keep groupname filename OR
949 GROUP=delete groupname filename
950 .RE
951 .RS
952 PROGRAM=pathname
953 .RE
954 .RS
955 PERL=pathname
956 .RE
957 .RS
958 TIEBREAKER_DELETE
959 .RE
960 .RS
961 GROUP_OVERRIDE_MASTER
962 .RE
963 .RS
964 USE_EXTENDED_REGEX
965 .RE
966 .RS
967 XOVER_LOG_LONG
968 .RE
969 .RS
970 HEADER:
971 .RE
972 .RS
973 Any Valid Header Line:
974 .RE
975 .RS
976 BODY:
977 .RE
978 .RS
979 BODYSIZE>
980 .RE
981 .RS
982 BODYSIZE<
983 .RE
984
985 .PP
986 All parameters are valid in both the master kill file and the group files, with the
987 exception of GROUP, PROGRAM, PERL, TIEBREAKER_DELETE, and GROUP_OVERRIDE_MASTER.
988 These are only valid in the master kill file.
989
990 .SH KILL/KEEP Files Parameters
991 .PP
992 .I HILINES=
993 Match any article longer than the number of lines specified.
994 .PP
995 .I LOWLINES=
996 Match any article shorter than the number of lines specified.
997 .PP
998 .I NRGRPS=
999 This line will match any article which has more groups than the number specified
1000 on the Newsgroups: line.
1001 Typically this is used in a killfile to prevent spammed articles.
1002 (A spammed article is one that is posted to many many groups, such
1003 as those get-rich quick schemes, etc.)
1004 .PP
1005 .I NRXREF=
1006 This line will match any article that has more groups than than the number specified
1007 on the Xref: line. This is another spamm stopper. WARNING: the Xref: line is not
1008 as accurate as the Newsgroups: line, as it only contains groups known to the news
1009 server. This option is most useful in an xover killfile, as in Xoverviews don't
1010 typically provide the Newsgroups: line, but do provide the Xref: line.
1011 .PP
1012 .I HEADER:
1013 .I Any Valid Header Line:
1014 Suck allows you to scan any single header line for a particular pattern/string, or
1015 you may scan the entire article header. To scan an individual line, just specify
1016 it, for example to scan the From line for [email protected], you would put
1017
1018 .RS
1019 From:[email protected]
1020 .RE
1021
1022 Note that the header line EXACTLY matches what is contained in the article. To scan
1023 the Followup-To: line, simply put \"Followup-To:\" as the parameter.
1024 To search the same header line for multiple search items, then each search
1025 item must be on a separate line, eg:
1026 .RS
1027 From:boby@xxx
1028 .RE
1029 .RS
1030 From:nerd@yyy
1031 .RE
1032 .RS
1033 Subject:suck
1034 .RE
1035 .RS
1036 Subject:help
1037 .RE
1038 The parameter HEADER: is a special case of the above. If you use the HEADER: parameter,
1039 then the entire header is searched for the item. You are allowed multiple HEADER: lines
1040 in each killfile.
1041 .PP
1042 When suck searches for the pattern, it only searches for what follows
1043 the :, and spaces following the : are significant. With the above example "Subject:suck",
1044 we will search the Subject header line for the string "suck". If the example had read "Subject: suck",
1045 suck would have searched for the string " suck". Note the extra space.
1046 .PP
1047 If your system has regex() routines on it, then the items searched for can be POSIX
1048 regular expressions, instead of just strings. Note that the QUOTE= option is still
1049 applied, even to regular expressions.
1050 .PP
1051 .I BODY:
1052 This parameter allows you to search the body of an article for text. Again,
1053 if your system has regex(), you can use regular expressions, and the QUOTE= option is
1054 also applied. You are allowed multiple BODY: lines in each killfile.
1055 WARNING: Certain regex combinations, especially with .* at the beginning,
1056 (eg BODY:.*jpg), in combination with large articles, can cause the regex code
1057 to eat massive amounts of CPU, and suck will seem like it is doing nothing.
1058 .PP
1059 .I BODYSIZE>
1060 This parameter will match an article if the size of its body (not including the
1061 header) is greater than this parameter. The size is specified in bytes.
1062 .PP
1063 .I BODYSIZE<
1064 This parameter will match an article if the size of its body, is less than this parameter.
1065 The size is specified in bytes.
1066 .PP
1067 .I QUOTE=
1068 This item specifies the character that defines a quoted string. The default
1069 for this is a ". If an item starts with the QUOTE character, then the item is
1070 checked as-is (case significant). If an item does not start with the QUOTE character,
1071 then the item is checked with out regard to case.
1072 .PP
1073 .I NON_REGEX=
1074 This items specifies the character that defines a non-regex string. The default
1075 for this is a %. If an item starts with the NON_REGEX character, then the item
1076 is never checked for regular expressions. If the item doesn't start with the QUOTE
1077 character, then suck tries to determine if it is a regular expression, and if it
1078 is, use regex() on it. This item is so that you can tell suck to treat strings
1079 like "$$$$ MONEY $$$$" as non-regex items. IF YOU USE BOTH QUOTE and NON_REGEX
1080 characters on a string, the NON_REGEX character MUST appear first.
1081 .PP
1082 .I GROUP=
1083 This line allows you to specify either keep or delete parameters on a group
1084 by group basis. There are three parts to this line. Each part of this line
1085 must be separated by exactly one space. The first part is either
1086 "keep" or "delete". If it is keep, then only articles in that group which match
1087 the parameters in the group file are downloaded. If it is delete, articles in that
1088 group which match the parameters are not downloaded. The second part, the group name
1089 is the full group name for articles to check against the group file. The group name
1090 may contain an * as the last character, to match multiple groups, eg: "comp.os.linux.*"
1091 would match comp.os.linux.announce, comp.os.linux.answers, etc.. The third part
1092 specifies the group file which contains the parameters to check the articles against.
1093 Note, that if you specified a postfix with the \-p option, then this postfix is attached
1094 to the name of the file when suck looks for it, UNLESS you use the \-k option above.
1095 .PP
1096 .I GROUP_OVERRIDE_MASTER
1097 This allows you to override the default behavior of the master kill file. If this
1098 option is in the master kill file, then even if an article is flagged for deletion
1099 by the master kill file, it is checked against the group files. If the group files
1100 says to not delete it, then the article is kept.
1101 .PP
1102 .I TIEBREAKER_DELETE
1103 This option allows you to override the built-in tie-breaker default. The potential
1104 exists for a message to be flagged by one group file as kept, and another group
1105 file as killed. The built-in default is to then keep the message. The TIEBREAKER_DELETE
1106 option will override that, and caused the article to be deleted.
1107 .PP
1108 .I USE_EXTENDED_REGEX
1109 This option tells suck to use extended regular expressions vice standard regular expressions.
1110 It may used in the master killfile, in which case it applies to all killfiles, or in an
1111 individual killfile, where it only applies to the parameters that follow it in the
1112 killfile.
1113 .PP
1114 .I XOVER_LOG_LONG
1115 This option tells suck to format the killfile generated by from an Xover killfile so that
1116 it looks like an article header. The normal output is to just print the Xover line
1117 from theserver.
1118 .PP
1119 .I PROGRAM=
1120 This line allows suck to call an external program to check each article.
1121 You may specify any arguments in addition to the program name on this line.
1122 If this line is in your suckkillfile, all other lines are ignored. Instead, the
1123 headers are passed to the external program, and the external program determines
1124 whether or not to download the article. Here's how it works. Suck will fork
1125 your program, with stdin and stdout redirected. Suck will feed the headers
1126 to your program thru stdin, and expect a reply back thru stdout. Here's the
1127 data flow for each article:
1128
1129 .RS
1130 1. suck will write a 8 byte long string, which represents the length of the
1131 header record on stdin of the external program. Then length is in ascii,
1132 is left-aligned, and ends in a newline (example: "1234 \\n").
1133 .RE
1134 .RS
1135 2. suck will then write the header on stdin of the external program.
1136 .RE
1137 .RS
1138 3. suck will wait for a 2 character response code on stdout. This response code is
1139 either "0\\n" or "1\\n" (NOT BINARY ZERO OR ONE, ASCII ZERO OR ONE). If the return
1140 code is zero, suck will download the article, if it is one, suck won't.
1141 .RE
1142 .RS
1143 4. When there are no more articles, the length written down (for step 1) will be zero
1144 (again in ascii "0 \\n"). Suck will then wait for the external program to
1145 exit before continuing on. The external program can do any clean up it needs,
1146 then exit. Note: suck will not continue processing until the external program exits.
1147 .RE
1148
1149 .PP
1150 .I PERL=
1151 This line allows suck to call a perl subroutine to check each article. In order
1152 to use this option, you must edit the Makefile, specifically the PERL* options.
1153 If the PERL=
1154 line is in your suckkillfile, all other lines are ignored. Instead, the header
1155 is sent to your perl subroutine, and your subroutine determines if the article
1156 is downloaded or not. The parameter on the PERL= line specifies the file name
1157 of the perl routine eg:
1158
1159 .RS
1160 PERL=perl_kill.pl
1161 .RE
1162
1163 .PP
1164 See the sample/perl_kill.pl for a sample perl subroutine. There are a couple of
1165 key points in this sample. The "package Embed::Persistant;" must be in the perl
1166 file. This is so that any variable names you create will not conflict with variable
1167 names in suck. In addition, the subroutine you define must be "perl_kill", unless
1168 you change the PERL_PACKAGE_SUB define in suck_config.h. Also, your subroutine must
1169 return exactly one value, an integer, either 0 or 1. If the subroutine returns
1170 0, then the article is downloaded, otherwise, the article is not downloaded.
1171
1172 .PP
1173 NOTES: The perl file is only compiled once, before any articles are downloaded.
1174 This is to prevent lengthy delays between articles while the perl routine
1175 is re-compiled. Also, you must use Perl 5.003 or newer. In addition, you
1176 are advised to run 'perl -wc filter' BEFORE using your filter, in order
1177 to check for syntax errors and avoid problems.
1178
1179 .SH SUCKXOVER
1180 If the file
1181 .I suckxover
1182 exists, then suck uses the XOVER command to get information
1183 on the articles and decide whether or not to download the article.
1184 Xover files use the same syntax as suckkillfiles, but supports a subset
1185 of the commands.
1186 .PP
1187 The following killfile commands are not supported in suckxover files:
1188 .RS
1189 NRGROUPS:
1190 .RE
1191 .RS
1192 HEADER:
1193 .RE
1194 .RS
1195 BODY:
1196 .RE
1197 .RS
1198 TIEBREAKER_DELETE:
1199 .RE
1200 .PP
1201 Only the following header lines will be checked:
1202 .RS
1203 Subject:
1204 .RE
1205 .RS
1206 From:
1207 .RE
1208 .RS
1209 Message-ID:
1210 .RE
1211 .RS
1212 References:
1213 .RE
1214 .PP
1215 The behaviour of the size commands (
1216 .I BODYSIZE>, BODYSIZE<, HILINES, and LOWLINES
1217 ) specify the total size of the article (not just the body) in
1218 bytes or lines, respectively.
1219 .PP
1220 All other parameters are allowed. However, if you use an invalid parameter,
1221 it is silently ignored.
1222 .SH SUCKXOVER and PROGRAM= or PERL= parameters
1223 These parameters are supported in a suckxover file, however they work slightly
1224 differently than described above. The key difference is that prior to sending
1225 each individual xoverview line to your program, suck will send you the
1226 overview.fmt listing that it retrieves from the server. This overview.fmt
1227 is a tab-separated line, describing the fields in each overview.fmt line.
1228 .PP
1229 For the PROGRAM= parameter, suck will first send your program an 8 byte long
1230 string, which is the length of the overview.fmt. This length is formatted
1231 as the lengths above (see nr1 under PROGRAM=). Suck will then send the overview.fmt.
1232 After that, the flow is as described above. See sample/killxover_child.c for
1233 an example.
1234 .PP
1235 For the PERL= parameter, Your program must have two subroutines. The first
1236 is perl_overview, which will recieve the overview.fmt, and not return anything.
1237 The second subroutine is perl_xover, which will recieve the xoverview line,
1238 and return 0 or 1, as described in the PERL= above. See sample/perl_xover.pl
1239 for an example.
1240
1241 .SH SUCKOTHERMSGS
1242 If
1243 .I suckothermsgs
1244 exists, it must contain lines formatted in one of three ways. The first way
1245 is a line containing a Message-ID, with the <> included, eg:
1246
1247 .RS
1248 <[email protected]>
1249 .RE
1250
1251 This will cause the article with that Message-ID to be retrieved.
1252 .PP
1253 The second way is to put a group name and article number on a line starting
1254 with an !, eg:
1255 .RS
1256 !comp.os.linux.announce 1
1257 .RE
1258
1259 This will cause that specific article to be downloaded.
1260 .PP
1261 You can also get a group of articles from a group by using the following syntax:
1262 .RS
1263 !comp.os.linux.announce 1-10
1264 .RE
1265 .PP
1266 Whichever method you use, if the article specified exists, it will be downloaded,
1267 in addition to any articles retreived via the
1268 .I sucknewsrc.
1269 These ways can be used to get a specific article in other groups,
1270 or to download an article that was killed. These articles
1271 .B ARE NOT
1272 processed through the kill articles routines.
1273
1274 .SH SUCKNODOWNLOAD
1275 If
1276 .I sucknodownload
1277 exists, it must consist of lines contaning a Message-ID, with the <> included, eg:
1278
1279 .RS
1280 <[email protected]>
1281 .RE
1282
1283 This will cause the article with that Message-ID to NEVER be downloaded. The
1284 Message-ID must begin in the first column of the line (no leading spaces). This
1285 file overrides
1286 .I suckothermsgs
1287 so if an article is in both, it will not be downloaded.
1288
1289 .SH POST FILTER
1290 if the
1291 .BI "-y post_filter"
1292 option is specified on the command line in conjunction with any of the batch modes,
1293 then suck will call the post filter specified, after downloading the articles, and
1294 before batching/posting the articles.
1295 The filter is passed the directory where the articles are stored (the -dm option).
1296 The filter program is responsible for parsing the contents of the directory. See
1297 sample/post_filter.pl for a sample post filter. This option was designed to
1298 allow you to add your own host name to the Path: header, but if you need to
1299 do anything else to the messages, you can.
1300
1301 .SH FOREIGN LANGUAGE PHRASES
1302 If the
1303 .BI "-l phrases"
1304 option is specified or the file /usr/local/lib/suck.phrases (defined in suck_config.h)
1305 exists, then suck will load an alternate language phrase file, and use
1306 it for all status & error messages, instead of the built-in defaults. The command line
1307 overrides the build in default, if both are present.
1308 The phrase file contains all messages used by suck, rpost, testhost,
1309 and lmove, each on a separate line and enclosed in quotes. To generate
1310 a sample phrase file, run
1311 .BI "make phrases"
1312 from the command line. This will create "phrases.engl", which is a list
1313 of the default phrases. Simply edit this file, changing the english
1314 phrases to the language of your choosing, being sure to keep the phrases
1315 within the quotes. These phrases may contain variables to print items
1316 provided by the program, such as hostname. Variables are designated
1317 by %vN% where N is a one-up sequence per phrase. These variables may
1318 exist in any order on the phrase line, for example,
1319 .RS
1320 "Hello, %v1%, welcome to %v2%" or
1321 .RE
1322 .RS
1323 "Welcome to %v2%, %v1%"
1324 .RE
1325 are both valid phrases. Phrases may contain, \\n, \\r, or \\t to print a newline, carriage return,
1326 or tab, respectively. Note that the first line of the phrase file is the current version
1327 number. This is checked against the version of suck running, to be sure that the phrases
1328 file is the correct version.
1329
1330 If you modify any of the source code, and add in new phrases, you will need to regenerate
1331 phrases.h, so that everything works correctly. To recreate, just run
1332 .BI "make phrases.h"
1333 from the command line.
1334 .SH SIGNAL HANDLING
1335 Suck accepts two signals, defined in
1336 .I suck_config.h.
1337 The first signal (default SIGTERM) will cause Suck to finish downloading the
1338 current article, batch up whatever articles were downloaded, and
1339 exit, without an error.
1340
1341 The second signal (default SIGUSR1) will cause suck to use the pause values defined with
1342 the -w option (see above).
1343
1344 .SH EXIT CODES
1345 Suck will exit with the following return codes:
1346 .RS
1347 0 = success
1348 .RE
1349 .RS
1350 1 = no articles available for download.
1351 .RE
1352 .RS
1353 2 = suck got an unexpected answer to a command it issued to the remote server.
1354 .RE
1355 .RS
1356 3 = the -V option was used.
1357 .RE
1358 .RS
1359 4 = suck was unable to perform NNTP authorization with the remote server.
1360 .RE
1361 .RS
1362 -1 = general error.
1363 .RE
1364 .SH HISTORY
1365 .RS
1366 Original Author - Tim Smith (unknown address)
1367 .RE
1368 .RS
1369 Maintainers -
1370 .RE
1371 .RS
1372 March 1995 - Sven Goldt ([email protected])
1373 .RE
1374 .RS
1375 July 1995 - Robert A. Yetman ([email protected])
1376 .RE
1377 .de R$
1378 Revision \\$$3, \\$$4
1379 ..
1380 .SH "SEE ALSO"
1381 testhost(1), rpost(1), lpost(1).