Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ACTSYNC(8)		  InterNetNews Documentation		    ACTSYNC(8)

NAME
       actsync,	actsyncd - Synchronize newsgroups

SYNOPSIS
       actsync [-AkmT] [-b hostid] [-d hostid] [-g max]	[-i ignore-file] [-I
       hostid] [-l hostid] [-n name] [-o format] [-p min-unchanged] [-q
       hostid] [-s size] [-t hostid] [-v verbosity] [-w	seconds] [-z seconds]
       [host] host

       actsyncd	config [debug-level [debug-format]]

DESCRIPTION
       actsync permits one to synchronize, compare, or merge two active	files.
       With this utility one may add, change, or remove	newsgroups on the
       local news server to make it similar to the list	of the newsgroups
       found on	another	system or file.	 The synchronization need not be
       exact.  Local differences in newsgroup lists may	be maintained and
       preserved.  Certain newsgroup errors may	be detected and	optionally
       corrected.

       There are several reasons to run	actsync	(or actsyncd) on a periodic
       basis.  Among the reasons are:

       o A control message to add, change or remove a newsgroup	may fail to
	 reach your site.

       o Your control.ctl may be out of	date or	incomplete.

       o News articles for a new newsgroup may arrive ahead (sometimes days
	 ahead)	of the control message.

       o Control messages may be forged, thus bypassing	the restrictions found
	 in control.ctl	unless you set up PGP authentication (and even then,
	 not all hierarchies use PGP authentication).

       o Your active file may have been	trashed.

       If either host argument begins with "." or "/", it is assumed to	be the
       name of a file containing information in	the active(5) format.  The
       getlist(1) utility may be used to obtain	a copy of a remote system's
       active file via its NNTP	server,	or an FTP client program can retrieve
       such a file from	an FTP archive (such as	ftp.isc.org available in both
       FTP and HTTPS <https://ftp.isc.org/pub/usenet/CONFIG/active>; see more
       about this below).  Newsgroup information from a	file may be treated as
       if it was obtained from a host.	In this	man page, the host arguments
       on the command line are called hosts, even though they may be file
       names.

       If a host argument does not begin with "." or "/", it is	assumed	to be
       a hostname or Internet address.	In this	case, actsync will attempt to
       use the NNTP protocol to	obtain a copy of the specified system's	active
       file.  If the host argument contains ":", the right side	will be
       considered the port to connect to on the	remote system.	If no port
       number is specified, actsync will connect to port 119.

       Regardless how the active file information is obtained, the actions of
       actsync remain the same.

       The first host specified	is taken to be the local host, the one where
       any changes would be made.  The second host specified is	the remote
       host that is being synchronized with.  If only one host is specified,
       it is assumed to	be the remote host to synchronize with,	and the	local
       host is assumed to be the default local NNTP server as specified	by the
       NNTPSERVER environment variable or by the server	value found in
       inn.conf.

       If either host is specified as "-", the default server will be used for
       that host, determined as	described above.

       The newsgroup synchronization, by default, involves all newsgroups
       found on	both hosts.  One may also synchronize a	subset of newsgroups
       by directing actsync to ignore certain newsgroups from both systems.
       Only newsgroups with valid names	will be	synchronized.  To be valid, a
       newsgroup name must consist only	of alphanumeric	characters, ".", "+",
       "-", and	"_".  One may not have two "." characters in a row.  The first
       character must be alphanumeric, as must any character following ".".
       The name	may not	end in a "." character.

       The actsyncd daemon provides a convenient interface to configure	and
       run actsync.  If	a host is not initially	reachable, the daemon will
       retry up	to 9 additional	times, waiting 6 minutes before	each retry.
       This daemon runs	in the foreground, sending output to standard output
       and standard error.  It then uses mod-active(8) to update the active
       file if there are commands for ctlinnd in its output.

       The configuration filename for the daemon is given as a command line
       argument, usually actsync.cfg in	pathetc.  The config file can contain
       the following options:

	   host=<host>
	   ftppath=<path-to-active>
	   ignore_file=<ignore-file>
	   flags=<actsync-options>

       The host=, ignore_file=,	and flags= lines are mandatory.	 Each keyword
       must start at the beginning of the line,	and there may be no whitespace
       before the "=" character.  Blank	lines are ignored, as are comment
       lines that start	with "#".  Any other lines may produce undefined
       results.

       The <host> setting refers to the	second (remote)	host parameter to
       actsync.	 If <path-to-active> is	provided, <host> is accessed as	an FTP
       server, retrieving the file named.  If the filename ends	in ".gz" or
       ".Z", it	will be	automatically uncompressed after retrieval.
       <ignore-file> names the ignore file used	by actsync (the	-i option).
       <actsync-options> contains any other flags that you wish	to pass	to
       actsync.

       Note that one should not	include	-i or -o options in the	flags= line;
       they are	automatically taken care of by actsyncd.

       One may produce a trial actsyncd	run without changing anything on the
       server by supplying the debug-level argument:

	   actsyncd <pathetc>/actsync.cfg 2

       The debug-level causes actsyncd to run actsync with a -v	debug-level
       flag (overriding	any -v flag on the flags= line), not make any changes
       to the active file, write a new active file to standard output, and
       write debug messages to standard	error.

       If the debug-format argument is also given to actsyncd, the data
       written to standard output will be in -o	debug-format instead of	in "-o
       a1" format.

       INN comes with default values of	"ftp.isc.org" for <host> and
       "/pub/usenet/CONFIG/active.gz" for <path-to-active>.  You can read
       about the policies used for maintaining that active file	at
       <https://ftp.isc.org/pub/usenet/CONFIG/README>.	Consider synchronizing
       from this file on a daily basis by using	cron.

OPTIONS
       actsync takes the following options.

       In all of the following options,	the hostid parameter takes one of the
       following values:

	   0	neither	server
	   1	local default server
	   2	remote server
	   12	both servers
	   21	both servers

       In other	words, 1 refers	to the local host (the first host argument on
       the actsync command line) and 2 refers to the remote host (the second
       host argument, or the only one if only one is given).

       -A  actsync tries to authenticate before	issuing	the LIST command.

       -b hostid
	   This	flag causes actsync to ignore for synchronization purposes
	   newsgroups with "bork.bork.bork"-style names	(newsgroups whose last
	   3 components	are identical).	 For example, the following newsgroups
	   have	bork-style names:

	       alt.helms.dork.dork.dork
	       alt.auto.accident.sue.sue.sue
	       alt.election.vote.vote.vote

	   The default is "-b 0"; no newsgroups	are ignored because of bork-
	   style names.

       -d hostid
	   This	flag causes actsync to ignore newsgroups that have all numeric
	   path	components.  For example, the following	newsgroups have
	   numeric path	components:

	       alt.prime.chongo.23209
	       391581.times.2.to_the.216193.power.-1
	       99.bottles.of.treacle.on.the.wall
	       linfield.class.envio_bio.101.d

	   The newsgroups directory of a newsgroup with	a all numeric
	   component could conflict with an article from another group if
	   stored using	the tradspool storage method; see storage.conf(5).
	   For example,	the directory for the first newsgroup listed above is
	   the same path as article number 23209 from the newsgroup:

	       alt.prime.chongo

	   The default is "-d 0"; all numeric newsgroups from both hosts will
	   be processed.

       -g max
	   Ignore any newsgroup	with more than max levels.  For	example, "-g
	   6" would ignore:

	       alt.feinstien.votes.to.trash.freedom.of.speech
	       alt.senator.exon.enemy.of.the.internet
	       alt.crypto.export.laws.dumb.dumb.dumb

	   but would not ignore:

	       alt.feinstien.acts.like.a.republican
	       alt.exon.amendment
	       alt.crypto.export.laws

	   If max is 0,	then the max level feature is disabled.

	   By default, the max level feature is	disabled.

       -i ignore-file
	   The ignore-file, usually actsync.ign	in pathetc, allows one to have
	   a fine degree of control over which newsgroups are ignored.	It
	   contains a set of rules that	specifies which	newsgroups will	be
	   checked and which will be ignored.

	   By default, these rules apply to both hosts.	 This can be modified
	   by using the	-I flag.

	   Blank lines and text	after a	"#" are	considered comments and	are
	   ignored.

	   Rule	lines consist of tokens	separated by whitespace.  Rule lines
	   may be one of two forms:

	       c <newsgroup> [<type> ...]
	       i <newsgroup> [<type> ...]

	   If the rule begins with a "c", the rule requests certain newsgroups
	   to be checked.  If the rule begins with an "i", the rule requests
	   certain newsgroups to be ignored.  The <newsgroup> field may	be a
	   specific newsgroup, or a uwildmat(3)	pattern.

	   If one or more <type>s are specified, then the rule applies to the
	   newsgroup only if it	is of the specified type.  Types refer to the
	   4th field of	the active file; that is, a type may be	one of:

	       y
	       n
	       m
	       j
	       x
	       =group.name

	   Unlike active files,	the "group.name" in an alias type may be a
	   newsgroup name or a uwildmat(3) pattern.  Also, "=" is equivalent
	   to "=*".

	   On each rule	line, no pattern type may be repeated.	For example,
	   one may not have more than one type that begins with	"=", per line.
	   However, one	may achieve an effect equivalent to using multiple "="
	   types by using multiple rule	lines affecting	the same newsgroup.

	   By default, all newsgroups are candidates to	be checked.  If	no
	   ignore-file is specified, or	if the ignore file contains no rule
	   lines, all newsgroups will be checked.  If an ignore	file is	used,
	   each	newsgroup in turn is checked against the ignore	file.  If
	   multiple lines match	a given	newsgroup, the last line in the	ignore
	   file	is used.

	   For example,	consider the following ignore file lines:

	       i *.general
	       c *.general m
	       i nsa.general

	   The newsgroups ba.general and mod.general would be synchronized if
	   moderated and ignored if not	moderated.  The	newsgroup nsa.general
	   would be ignored regardless of moderation status.  All newsgroups
	   not matching	*.general would	be synchronized	by default.

       -I hostid
	   This	flag restricts which hosts are affected	by the ignore file.
	   This	flag may be useful in conjunction with the -m flag.  For
	   example:

	       actsync -i actsync.ign -I 2 -m host1 host2

	   will	keep all newsgroups currently on host1.	 It will also only
	   compare host1 groups	with non-ignored newsgroups from host2.

	   The default is "-I 12"; newsgroups from both	hosts are ignored per
	   the file specified with -i.

       -k  By default, any newsgroup on	the local host that has	an invalid
	   name	will be	considered for removal.	 This causes actsync simply
	   ignore such newsgroups.  This flag, used in combination with	-m,
	   will	prevent	any newsgroup from being scheduled for removal.

       -l hostid
	   This	flag causes problem newsgroups of type "=" to be considered as
	   errors.  Newsgroups of type "=" are newsgroups active entries that
	   have	a fourth field that begins with	"="; i.e., newsgroups that are
	   aliased to other newsgroups.	 A problem newsgroup is	one for	which
	   one of the following	is true:

	   o Aliased to	itself.

	   o In	an alias chain that loops around to itself.

	   o In	an alias chain longer than 16 groups.

	   o Aliased to	a non-existant newsgroup.

	   o Aliased to	a newsgroup that has an	error of some kind.

	   However, a newsgroup	that is	equivalent to an ignored newsgroup is
	   not a problem.

	   The default is "-l 12":  problem newsgroups from both hosts are
	   marked as errors.

       -m  Merge newsgroups instead of sync.  By default, if a newsgroup
	   exists on the local host but	not the	remote,	it will	be scheduled
	   to be removed.  This	flag disables this process, permitting
	   newsgroups unique to	the local host to be kept.

       -n name
	   Depending on	-o, the	ctlinnd(8) command may be used to create
	   newsgroups as necessary.  When this is done,	the default creator
	   name	used is	"actsync".  This flag changes the creator name to
	   name.

       -o format
	   Determine the output	or action format of this utility.  format may
	   be one of:

	   a   Output in active(5) format.

	   a1  Output in active(5) format and output non-error ignored groups
	       from the	local host.

	   ak  Output in active(5) format, but use the high and	low (2nd and
	       3rd active fields) values from the remote host for any
	       newsgroup being created.

	   aK  Output in active(5) format, but use the high and	low (2nd and
	       3rd active fields) values from the remote host for all
	       newsgroups found	on that	host.

	   a1k Output in active(5) format, but use the high and	low (2nd and
	       3rd active fields) values from the remote host for any
	       newsgroup being created and output non-error ignored groups
	       from the	local host.

	   a1K Output in active(5) format, but use the high and	low (2nd and
	       3rd active fields) values from the remote host for all
	       newsgroups found	on that	host and output	non-error ignored
	       groups from the local host.

	   ak1 Same as "a1k".

	   aK1 Same as "a1K".

	   c   Output as commands to ctlinnd.

	   x   No output.  Instead, directly run ctlinnd commands.

	   xi  No output.  Instead, directly run ctlinnd commands in an
	       interactive mode.

	   The "a", "a1", "ak",	"aK", "a1k", "a1K", "ak1", and "aK1" style
	   formats allow one to	format new active file instead of producing
	   ctlinnd commands.  They use high and	low values of 0000000000 and
	   0000000001 respectively for newsgroups that are created unless
	   otherwise specified.	 The "ak" and "aK" variants change the high
	   and low values (2nd and 3rd active fields).	In the case of "ak",
	   newsgroups created take their high and low values from the remote
	   host.  In the case of "aK", all newsgroups found on the remote host
	   take	their high and low values from it.

	   The "c" format produces ctlinnd commands.  No actions are taken
	   because actsync simply prints ctlinnd commands on standard output.
	   This	output format is useful	to let you see how the local host will
	   be affected by the sync (or merge) with the remote host.

	   The sync (or	merge) may be accomplished directly by use of the "x"
	   or "xi" format.  With this format, actsync uses the execl(2)	system
	   call	to directly execute ctlinnd commands.  The output of such exec
	   calls may be	seen if	the verbosity level is at least	2.

	   The actsync utility will pause for 4	seconds	before each command is
	   executed if "-o x" is selected.  See	the -z flag below for
	   discussion of this delay and	how to customize it.

	   The "xi" format interactively prompts on standard output and	reads
	   directives on standard input.  One may pick and choose changes
	   using this format.

	   Care	should be taken	when producing active(5) formatted output.
	   One should check to be sure that actsync exited with	a zero status
	   prior to using such output.	Also one should	realize	that such
	   output will not contain lines ignored due to	-i even	if "-p 100" is
	   used.

	   By default, "-o c" is assumed.

       -p min-unchanged
	   By default, the actsync utility has safeguards against performing
	   massive changes.  If	fewer than min-unchanged percent of the	non-
	   ignored lines from the local	host remain unchanged, no actions
	   (output, execution, etc.) are performed and actsync exits with a
	   non-zero exit status.  The min-unchanged value may be a floating
	   point value such as 66.667.

	   A change is a local newsgroup line that was removed,	added,
	   changed, or found to	be in error.  Changing the 2nd or 3rd active
	   fields via "-o ak" or "-o aK" are not considered changes by -p.

	   To force actsync to accept any amount of change, use	the "-p	0"
	   option.  To force actsync to	reject any changes, use	the "-p	100"
	   option.

	   Care	should be taken	when producing active(5) formatted output.
	   One should check to be sure that actsync exited with	a zero status
	   prior to using such output.	Also one should	realize	that such
	   output will not contain lines ignored due to	-i even	if "-p 100" is
	   used.

	   By default, 96% of the lines	not ignored in the first host argument
	   on the actsync command line must be unchanged.  That	is, by
	   default, "-p	96" is assumed.

       -q hostid
	   By default, all newsgroup errors are	reported on standard error.
	   This	flag quiets errors from	the specified hostid.

       -s size
	   If size is greater than 0, then ignore newsgroups with names	longer
	   than	size and ignore	newsgroups aliased (by following "=" chains)
	   to names longer than	size.  Length checking is performed on both
	   the local and remote	hosts.

	   By default, size is 0 and thus no length checking is	performed.

       -t hostid
	   Ignore improper newsgroups consisting of only a top component from
	   the specified hostid.  The following	newsgroups are considered
	   proper newsgroups despite top only names and	therefore are exempt
	   from	this flag:

	       control
	       general
	       junk
	       test
	       to

	   For example,	the following newsgroup	names are improper because
	   they	only contain a top level component:

	       dole_for_pres
	       dos
	       microsoft
	       windows95

	   The default is "-t 2"; that is, all improper	top-level-only
	   newsgroups from the remote host are ignored.

       -T  This	flag causes newsgroups on the remote host in new hierarchies
	   to be ignored.  Normally a newsgroup	which only exists on the
	   remote host,	chongo.was.here	for example, is	created	on the local
	   host.  However, if this flag	is given and the local host does not
	   have	any other newsgroups in	the same hierarchy (chongo.* in	this
	   case), the newsgroup	in question will be ignored and	will not be
	   created on the local	host.

       -v verbosity
	   By default, actsync is not verbose.	This flag controls the
	   verbosity level as follows:

	   0 No	debug or status	reports	(default).

	   1 Print summary, but	only if	work was needed	or done.

	   2 Print actions, exec output, and summary, but only if work was
	     needed or done.

	   3 Print actions, exec output, and summary.

	   4 Full debug	output.

       -w seconds
	   If "-o x" or	"-o xi"	is selected, ctlinnd will wait seconds seconds
	   before timing out.  The default value is "-w	30".

       -z seconds
	   If "-o x" is	selected, actsync will pause for seconds seconds
	   before each command is executed.  This helps	prevent	innd from
	   being busied-out if a large number of ctlinnd commands are needed.
	   One can entirely disable this sleeping by using "-z 0".

	   By default, actsync will pause for 4	seconds	before each command is
	   executed if "-o x" is selected.

EXAMPLES
       Determine the difference	(but don't change anything) between your
       newsgroup set and uunet's set:

	   actsync news.uu.net

       Same as above, with full	debug and progress reports:

	   actsync -v 4	news.uu.net

       Force a site to have the	same newsgroups	as some	other site:

	   actsync -o x	master

       This may	be useful to sync a slave site to its master, or to sync
       internal	site to	a gateway.

       Compare your site with uunet, disregarding local	groups and certain
       local differences with uunet.  Produce a	report if any differences were
       encountered:

	   actsync -v 2	-i actsync.ign news.uu.net

       where actsync.ign contains:

	   # Don't compare to.*	groups as they will differ.
	   #
	   i	   to.*

	   # These are our local groups	that nobody else
	   # (should) carry.  So ignore	them for the sake
	   # of	the compare.
	   #
	   i	   nsa.*

	   # These groups are local favorites, so keep them
	   # even if uunet does	not carry them.
	   #
	   i	   ca.dump.bob.dorman
	   i	   ca.keep.bob.dorman
	   i	   alt.tv.dinosaurs.barney.die.die.die
	   i	   alt.tv.dinosaurs.barney.love.love.love
	   i	   alt.sounds.*	   =alt.binaries.sounds.*

       To interactively	sync against news.uu.net, using	the same ignore	file:

	   actsync -o xi -v 2 -i actsync.ign news.uu.net

       Based on	newsgroups that	you decided to keep, one could make changes to
       the actsync.ign file:

	   # Don't compare to.*	groups as they will differ.
	   #
	   i	   to.*

	   # These are our local groups	that nobody else
	   # (should) carry.  So ignore	them for the sake
	   # of	the compare.
	   #
	   i	   nsa.*

	   # These groups are local favorites, so keep them
	   # even if uunet does	not carry them.
	   #
	   i	   ca.dump.bob.dorman
	   i	   alt.tv.dinosaurs.barney.die.die.die
	   i	   alt.sounds.*	   =alt.binaries.sounds.*

	   # Don't sync	test groups, except for	ones that are
	   # moderated or that are under the gnu hierarchy.
	   #
	   i	   *.test
	   c	   *.test m	   # check moderated test groups
	   c	   gnu.*.test
	   c	   gnu.test	   # just in case it ever exists

       Automatic processing may	be set up by using the following actsync.cfg
       file:

	   # Host to sync off of (host2).
	   host=news.uu.net

	   # Location of the ignore file.
	   ignore_file=<pathetc	in inn.conf>/actsync.ign

	   # Where news	articles are kept.
	   spool=<patharticles in inn.conf>

	   # actsync(8)	flags
	   #
	   # Automatic execs, report if	something was done,
	   # otherwise don't say anything, don't report
	   # uunet active file problems, just ignore
	   # the affected entries.
	   flags=-o x -v 2 -q 2

       and then	by running actsyncd with the path to the config	file:

	   actsyncd <pathetc>/actsync.cfg

       The command

	   actsyncd <pathetc>/actsync.cfg 4 >cmd.log 2>dbg.log

       will operate in debug mode, not change the active file, write ctlinnd
       style commands to cmd.log, and write debug statements to	dbg.log.

       To check	only the major hierarchies against news.uu,net,	use the
       following actsync.ign file:

	   # By	default, ignore	everything.
	   #
	   i	   *

	   # Check the major groups.
	   #
	   c	   alt.*
	   c	   comp.*
	   c	   gnu.*
	   c	   humanities.*
	   c	   misc.*
	   c	   news.*
	   c	   rec.*
	   c	   sci.*
	   c	   soc.*
	   c	   talk.*

       and the command:

	   actsync -i actsync.ign news.uu.net

       To determine the	differences between your old active and	your current
       default server:

	   actsync <pathetc>/active.old	-

       To report but not fix any newsgroup problems with the current active
       file:

	   actsync - -

       To detect any newsgroup errors on your local server, and	to remove any
       *.bork.bork.bork-style silly newsgroup names:

	   actsync -b 2	- -

       The active file produced	by:

	   actsync <flags> -o x	erehwon.honey.edu

       is effectively the same as the active file produced by:

	   cd <pathdb>
	   ctlinnd pause 'running actsync'
	   rm -f active.new
	   actsync <flags> -o a1 erehwon.honey.edu > active.new
	   rm -f active.old
	   ln active active.old
	   mv active.new active
	   ctlinnd reload active 'running actsync'
	   ctlinnd go 'running actsync'

       It should be noted that the final method	above, pausing the server and
       simply replacing	the active file, may be	faster if you are making lots
       of changes.

FILES
       pathbin/actsync
	   The C program itself	used to	synchronize, compare, or merge two
	   active files.

       pathbin/actsyncd
	   The Shell daemon which provides a convenient	interface to configure
	   and run actsync.

       pathetc/actsync.cfg
	   The configuration file which	specifies the settings to use.

       pathetc/actsync.ign
	   The ignore file which contains a set	of synchronization rules that
	   specifies which newsgroups will be checked and which	will be
	   ignored.

CAUTION
       Careless	use of this tool may result in the unintended addition,
       change, or removal of newsgroups.  You should avoid using the "x"
       output format until you are sure	it will	do what	you want.

BUGS
       If a newsgroup appears multiple times, actsync will treat all copies as
       errors.	However, if the	group is marked	for removal, only one rmgroup
       will be issued.

HISTORY
       Written by Landon Curt Noll <chongo@toad.com> for InterNetNews.
       Updated to support FTP fetching by David	Lawrence <tale@isc.org>.
       Converted to POD	by Russ	Allbery	<eagle@eyrie.org>.

       $Id: actsync.pod	10097 2016-11-04 22:19:07Z iulius $

       By Landon Curt Noll <chongo@toad.com> (chongo was here /\../\).

       Copyright (c) Landon Curt Noll, 1993.  All rights reserved.

       Permission to use and modify is hereby granted so long as this notice
       remains.	 Use at	your own risk.	No warranty is implied.

SEE ALSO
       active(5), ctlinnd(8), getlist(8), inn.conf(5), mod-active(8),
       simpleftp(1).

INN 2.6.1			  2016-11-06			    ACTSYNC(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | FILES | CAUTION | BUGS | HISTORY | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=actsync&sektion=8&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help