987 lines
29 KiB
Perl
Executable file
987 lines
29 KiB
Perl
Executable file
#! /usr/bin/perl -w
|
|
#
|
|
# yapfaq by Thomas Hochstein
|
|
# (Original author: Marc Brockschmidt)
|
|
#
|
|
# containing some code from tinews.pl
|
|
# Copyright (c) 2002-2024 Urs Janssen <urs@tin.org>,
|
|
# Marc Brockschmidt <marc@marcbrockschmidt.de>
|
|
# containing some code from pgpverify.pl
|
|
# Written April 1996, <tale@isc.org> (David C Lawrence)
|
|
# Currently maintained by Russ Allbery <eagle@eyrie.org>
|
|
#
|
|
# This script posts articles (e.g. FAQs) to Usenet newsgroups.
|
|
# Most people will use it in combination with cron(8).
|
|
#
|
|
# Copyright (C) 2003 Marc Brockschmidt <marc@marcbrockschmidt.de>
|
|
# Copyright (c) 2010-2017, 2026 Thomas Hochstein <thh@thh.name>
|
|
#
|
|
# It can be redistributed and/or modified under the same terms under
|
|
# which Perl itself is published.
|
|
|
|
my $VERSION = "1.0.0";
|
|
(my $NAME = $0) =~ s#^.*/##;
|
|
|
|
use utf8;
|
|
use strict;
|
|
use POSIX qw(strftime);
|
|
use Net::Domain qw(hostfqdn);
|
|
use Net::NNTP;
|
|
use DateTime; # CPAN
|
|
use Path::Tiny; # CPAN
|
|
use Getopt::Long qw(GetOptions);
|
|
Getopt::Long::config ('bundling');
|
|
|
|
use Data::Dumper;
|
|
|
|
# configuration #######################
|
|
# may be overwritten via ~/.yapfaqrc or command line
|
|
my %Config;
|
|
|
|
$Config{'datadir'} = 'data/'; # path to data files (FAQs, ...)
|
|
|
|
$Config{'nntp-server'} = 'news'; # your NNTP server name, may be set via $NNTPSERVER
|
|
$Config{'nntp-port'} = 119; # NNTP-port, may be set via $NNTPPORT
|
|
$Config{'nntp-user'} = ''; # username for AUTHINFO
|
|
$Config{'nntp-pass'} = ''; # password for AUTHINFO
|
|
$Config{'force-auth'} = 0; # set to 1 to force authentication
|
|
$Config{'starttls'} = 0; # set to 1 to use STARTTLS if possible
|
|
|
|
$Config{'verbose'} = 0; # set to 1 to get status messages
|
|
$Config{'debug'} = 0; # set to 1 to get some debug output,
|
|
# set to 2 for NNTP debug output
|
|
|
|
# Main program ########################
|
|
|
|
### read configuration
|
|
# from (first match counts)
|
|
# $XDG_CONFIG_HOME/yapfaqrc
|
|
# ~/.config/yapfaqrc
|
|
# ~/.yapfaqrc
|
|
# if present
|
|
# taken and modified from tinews.pl
|
|
my $RCFILE = undef;
|
|
my (@try, %seen);
|
|
|
|
if ($ENV{'XDG_CONFIG_HOME'}) {
|
|
push(@try, (glob("$ENV{'XDG_CONFIG_HOME'}/yapfaqrc"))[0]);
|
|
}
|
|
push(@try, (glob('~/.config/yapfaqrc'))[0], (glob('~/.yapfaqrc'))[0]);
|
|
|
|
foreach (grep { ! $seen{$_}++ } @try) { # uniq @try
|
|
last if (open($RCFILE, '<', $_));
|
|
$RCFILE = undef;
|
|
}
|
|
if (defined($RCFILE)) {
|
|
while (defined($_ = <$RCFILE>)) {
|
|
if (m/^([^#\s=]+)\s*=\s*(\S[^#]+)/io) {
|
|
chomp($Config{lc($1)} = $2);
|
|
}
|
|
}
|
|
close($RCFILE);
|
|
}
|
|
|
|
# these env-vars have higher priority (order is important)
|
|
# taken from tinews.pl
|
|
$Config{'nntp-server'} = $ENV{'NEWSHOST'} if ($ENV{'NEWSHOST'});
|
|
$Config{'nntp-server'} = $ENV{'NNTPSERVER'} if ($ENV{'NNTPSERVER'});
|
|
$Config{'nntp-port'} = $ENV{'NNTPPORT'} if ($ENV{'NNTPPORT'});
|
|
|
|
### read commandline options
|
|
my ($OptProject,$OptForce,$OptTest,$OptNewsgroup,$OptOutput);
|
|
GetOptions ('p|project=s' => \$OptProject,
|
|
'f|force' => \$OptForce,
|
|
't|test' => \$OptTest,
|
|
'n|newsgroup=s' => \$OptNewsgroup,
|
|
'o|output' => \$OptOutput,
|
|
'datadir=s' => \$Config{'datadir'},
|
|
'nntp-server=s' => \$Config{'nntp-server'},
|
|
'nntp-port=s' => \$Config{'nntp-port'},
|
|
'nntp-user=s' => \$Config{'nntp-user'},
|
|
'nntp-pass=s' => \$Config{'nntp-pass'},
|
|
'starttls!' => \$Config{'starttls'},
|
|
'force-auth!' => \$Config{'force-auth'},
|
|
'v|verbose!' => \$Config{'verbose'},
|
|
'd|debug!' => \$Config{'debug'},
|
|
'c|config' => \&ShowConf,
|
|
'h|help' => \&ShowPOD,
|
|
'V|version' => \&ShowVersion) or &ShowUsage;
|
|
|
|
### create list of @Projects from $Config{'datadir'} unless -p is set
|
|
my @Projects;
|
|
if (!$OptProject) {
|
|
die "E: Data directory '" . $Config{'datadir'} . "' does not exist.\n" unless (-d $Config{'datadir'});
|
|
@Projects = glob $Config{'datadir'} . '*.hdr';
|
|
foreach (@Projects) {
|
|
$_ =~ s#^.*/##;
|
|
$_ =~ s/\.hdr$//;
|
|
}
|
|
} else {
|
|
push @Projects, $OptProject;
|
|
}
|
|
|
|
### iterate over @Projects
|
|
print "- Test mode, no status updates.\n" if $Config{'debug'};
|
|
foreach (@Projects) {
|
|
# check for existence of project
|
|
my $HeaderFile = $Config{'datadir'} . "$_.hdr";
|
|
if (not -r $HeaderFile) {
|
|
warn "W: Project '$_' does not exist ('$HeaderFile' not found).\n";
|
|
next;
|
|
}
|
|
|
|
print "Project '$_' ...\n" if $Config{'verbose'} or $Config{'debug'};
|
|
# generate posting and check for due date
|
|
# @Posting will be empty ('') if not due
|
|
my @Posting = &BuildPosting($_);
|
|
next if !$#Posting;
|
|
|
|
# save Message-ID
|
|
my $LastMID;
|
|
foreach (@Posting) {
|
|
if (/^Message-ID: /) {
|
|
($LastMID = $_) =~ s/^Message-ID:\s+//;
|
|
chomp ($LastMID);
|
|
last;
|
|
}
|
|
}
|
|
|
|
# sent to STDOUT due to --output
|
|
if ($OptOutput) {
|
|
print "- Print to STDTOUT.\n----->----->----->-----\n" if $Config{'debug'};
|
|
foreach (@Posting) {
|
|
print $_
|
|
};
|
|
print "-----<-----<-----<-----\n" if $Config{'debug'};
|
|
# otherwise: post
|
|
} else {
|
|
next if !&PostNNTP(@Posting);
|
|
}
|
|
|
|
# update status
|
|
&UpdateStatus($_, $LastMID) if !$OptTest;
|
|
}
|
|
|
|
### we're done
|
|
exit(0);
|
|
|
|
# subroutines #########################
|
|
|
|
### ------------------------------------------------------------------
|
|
### display version information and exit
|
|
sub ShowVersion {
|
|
print "$NAME v$VERSION\n";
|
|
print "Copyright (C) 2003 Marc Brockschmidt <marc\@marcbrockschmidt.de>\n";
|
|
print "Copyright (c) 2010-2017, 2026 Thomas Hochstein <thh\@thh.name>\n";
|
|
print "This program is free software; you may redistribute it ".
|
|
"and/or modify it under the same terms as Perl itself.\n";
|
|
exit(0);
|
|
};
|
|
|
|
### ------------------------------------------------------------------
|
|
### feed myself to perldoc and exit
|
|
sub ShowPOD {
|
|
exec('perldoc', $0);
|
|
exit(0);
|
|
};
|
|
|
|
### ------------------------------------------------------------------
|
|
### Show current configuration
|
|
sub ShowConf {
|
|
print "$NAME v$VERSION\n";
|
|
print "Current configuration:\n";
|
|
foreach my $config (sort keys %Config) {
|
|
printf("- %s: %s\n", $config, $Config{$config}) if $Config{$config};
|
|
}
|
|
};
|
|
|
|
### ------------------------------------------------------------------
|
|
### display short usage information
|
|
sub ShowUsage {
|
|
print "$NAME v$VERSION\n";
|
|
print "Usage: " . $NAME . " [OPTIONS]\n";
|
|
print " -p project run on project only, don't use all projects\n";
|
|
print " -f post unconditionally, even if project(s) is/are not due\n";
|
|
print " -t don't update project status (test)\n";
|
|
print " -n newsgroup post only to newsgroup (for testing)\n";
|
|
print " -o print to STDOUT (for testing or to pipe into inews)\n";
|
|
print " --datadir path override \$datadir\n";
|
|
print " --nntp-server name override \$nntp-server\n";
|
|
print " --nntp-port port override \$nntp-port\n";
|
|
print " --nntp-user user override \$nntp-user\n";
|
|
print " --nntp-pass passwd override \$nntp-pass\n";
|
|
print " --[no-]starttls override \$starttls\n";
|
|
print " --[no-]force-auth override \$force-auth\n";
|
|
print " -v | --[no-]verbose override \$verbose\n";
|
|
print " -d | --[no-]debug override \$debug\n";
|
|
print " -c show current configuration\n";
|
|
print " -h show documentation\n";
|
|
print " -V show version and copyright\n";
|
|
exit 0;
|
|
}
|
|
|
|
### ------------------------------------------------------------------
|
|
### parse a YYYY-MM-DD construct to a DateTime object
|
|
sub ParseDate {
|
|
my $Date = shift;
|
|
die "E: '$Date' is not a valid date format.\n" unless $Date =~ /^\d\d\d\d-\d\d-\d\d$/;
|
|
my ($Year, $Month, $Day) = split /-/, $Date;
|
|
return DateTime->new(year => $Year,
|
|
month => $Month,
|
|
day => $Day,
|
|
);
|
|
}
|
|
|
|
### ------------------------------------------------------------------
|
|
### add a duration (in d,w,m,y) to a DateTime object
|
|
sub AddDuration {
|
|
my($Date, $Duration) = @_;
|
|
$Duration =~ /(\d+)(.)/;
|
|
my ($Amount, $Timespan) = ($1, lc($2));
|
|
if ($Timespan eq 'd') {
|
|
$Date->add(days => $Amount);
|
|
}
|
|
elsif ($Timespan eq 'w') {
|
|
$Date->add(days => $Amount * 7);
|
|
}
|
|
elsif ($Timespan eq 'm') {
|
|
$Date->add(months => $Amount);
|
|
}
|
|
elsif ($Timespan eq 'y') {
|
|
$Date->add(years => $Amount);
|
|
}
|
|
return $Date;
|
|
}
|
|
|
|
### ------------------------------------------------------------------
|
|
### return a hash of all headers (ignoring duplicate headers)
|
|
# taken and modified from tinews.pl
|
|
sub ParseHeaders {
|
|
my @Headers = @_;
|
|
my (%Header, $Label, $Value);
|
|
foreach (@Headers) {
|
|
s/\r?\n$//;
|
|
|
|
last if /^$/;
|
|
|
|
if (/^(\S+):[ \t](.+)/) {
|
|
($Label, $Value) = ($1, $2);
|
|
# discard all duplicate headers
|
|
next if $Header{lc($Label)};
|
|
$Header{lc($Label)} = $Value;
|
|
} elsif (/^\s/) {
|
|
# continuation lines
|
|
if ($Label) {
|
|
s/^\s+/ /;
|
|
$Header{lc($Label)} .= $_;
|
|
} else {
|
|
warn (sprintf("W: Non-header line: %s\n",$_));
|
|
}
|
|
} else {
|
|
warn (sprintf("W: Non-header line: %s\n",$_));
|
|
}
|
|
}
|
|
return %Header;
|
|
};
|
|
|
|
### ------------------------------------------------------------------
|
|
### open NNTP connection, authenticate and return a Net::NNTP-Object
|
|
# taken and modified from tinews.pl
|
|
sub ConnectNNTP {
|
|
my $NNTP = Net::NNTP->new(
|
|
Host => $Config{'nntp-server'},
|
|
Reader => 1,
|
|
Debug => $Config{'debug'},
|
|
Port => $Config{'nntp-port'},
|
|
SSL_verify_mode => 0,
|
|
)
|
|
or die("E: Can't connect to ".$Config{'nntp-server'}.":".$Config{'nntp-port'}.".\n");
|
|
|
|
my $NNTPMsg = $NNTP->message();
|
|
my $NNTPCode = $NNTP->code();
|
|
|
|
if ($Config{'starttls'} && $NNTP->can_ssl()) {
|
|
$NNTP->starttls;
|
|
}
|
|
|
|
if ($Config{'debug'}) {
|
|
print '- Connected to ' . $NNTP->peerhost . ':' . $NNTP->peerport . "\n";
|
|
if ($Config{'starttls'}) {
|
|
printf(" SSL-Fingerprint: %s %s\n", split(/\$/, $NNTP->get_fingerprint));
|
|
}
|
|
}
|
|
|
|
# no read and/or write access - give up
|
|
if ($NNTPCode < 200 || $NNTPCode > 201) {
|
|
$NNTP->quit();
|
|
}
|
|
|
|
# read access - try to authenticate
|
|
if ($NNTPCode == 201 || $Config{'force-auth'}) {
|
|
# no user/password
|
|
if (!$Config{'nntp-user'} || !$Config{'nntp-pass'}) {
|
|
$NNTP->quit();
|
|
die('E: ' . $NNTPCode . ' ' . $NNTPMsg . "\n");
|
|
}
|
|
$NNTP = &AuthNNTP($NNTP);
|
|
}
|
|
|
|
# try posting; on failure, try to authenticate
|
|
$NNTP->post();
|
|
$NNTPCode = $NNTP->code();
|
|
if ($NNTPCode == 480) {
|
|
$NNTP = &AuthNNTP($NNTP);
|
|
$NNTP->post();
|
|
}
|
|
|
|
return $NNTP;
|
|
}
|
|
|
|
### ------------------------------------------------------------------
|
|
### do AUTHINFO on a Net::NNTP-Object, die on failure
|
|
# taken and modified from tinews.pl
|
|
sub AuthNNTP {
|
|
my $NNTP = shift;
|
|
|
|
$NNTP->authinfo($Config{'nntp-user'}, $Config{'nntp-pass'});
|
|
my $NNTPMsg = $NNTP->message();
|
|
my $NNTPCode = $NNTP->code();
|
|
if ($NNTPCode != 281) { # auth failed
|
|
$NNTP->quit();
|
|
die('E: ' . $NNTPCode . ' ' . $NNTPMsg . "\n");
|
|
}
|
|
|
|
return $NNTP;
|
|
}
|
|
|
|
### ------------------------------------------------------------------
|
|
### build posting
|
|
# read and parser header and body from files
|
|
# read status file, check due date
|
|
sub BuildPosting {
|
|
my $Project = shift;
|
|
my $StatusFile = $Config{'datadir'} . "$Project.cfg";
|
|
my $HeaderFile = $Config{'datadir'} . "$Project.hdr";
|
|
my $BodyFile = $Config{'datadir'} . "$Project.txt";
|
|
if (not -r $BodyFile) {
|
|
warn "W: '$BodyFile' not found.\n";
|
|
return '';
|
|
}
|
|
|
|
# read status file, if available
|
|
my($LastPosted, $LastMID);
|
|
if (-r $StatusFile) {
|
|
print "- Reading status ($Project.cfg).\n" if $Config{'debug'};
|
|
my @Status = path($StatusFile)->lines;
|
|
foreach (@Status) {
|
|
# convert Windows line-endings to Unix
|
|
s/\r//;
|
|
if (/^Last-posted: /i) {
|
|
chomp;
|
|
($LastPosted = $_) =~ s/^Last-posted:\s+//i;
|
|
} elsif (/^Last-Message-ID: /i) {
|
|
chomp;
|
|
($LastMID = $_) =~ s/^Last-Message-ID:\s+//i;
|
|
}
|
|
}
|
|
} else {
|
|
print "- No status file ($Project.cfg).\n" if $Config{'debug'};
|
|
}
|
|
|
|
print "- Reading headers ($Project.hdr) and body ($Project.txt).\n" if $Config{'debug'};
|
|
my @Headers = path($HeaderFile)->lines;
|
|
my @Body = path($BodyFile)->lines;
|
|
my %Header = &ParseHeaders(@Headers);
|
|
|
|
# check for mandatory headers
|
|
if (!$Header{'from'} or !$Header{'subject'} or !$Header{'newsgroups'}) {
|
|
warn "W: From, Subject or Newsgroups header missing from '$HeaderFile'.\n";
|
|
return '';
|
|
}
|
|
|
|
# add Date:
|
|
push @Headers, 'Date: ' . DateTime->now->strftime('%a, %d %b %Y %H:%M:%S %z') . "\n";
|
|
# add missing Message-ID:
|
|
push @Headers, 'Message-ID: <%n-%y-%m-%d@' . hostfqdn. ">\n" if (!$Header{'message-id'});
|
|
# add User-Agent
|
|
push @Headers, "User-Agent: $NAME/$VERSION\n";
|
|
|
|
# parse pseudo headers from body
|
|
my ($InRealBody,$LastModified,$PostingFrequency);
|
|
foreach (@Body) {
|
|
# convert Windows line-endings to Unix
|
|
s/\r//;
|
|
next if $InRealBody;
|
|
$InRealBody++ if /^$/;
|
|
$LastModified = $1 if /^Last-modified:\s*(\S+)\s*$/i;
|
|
$PostingFrequency = $1 if /^Posting-Frequency:\s*(\S+)\s*$/i;
|
|
}
|
|
# parse Posting-Frequency from pseudo-header
|
|
if ($PostingFrequency) {
|
|
print "- Posting-Frequency set to $PostingFrequency from pseudo-header.\n" if $Config{'debug'};
|
|
if ($PostingFrequency eq 'daily') {
|
|
$PostingFrequency = '1d';
|
|
} elsif ($PostingFrequency eq 'weekly') {
|
|
$PostingFrequency = '1w';
|
|
} elsif ($PostingFrequency =~ /bi-?weekly/) {
|
|
$PostingFrequency = '2w';
|
|
} elsif ($PostingFrequency eq 'monthly') {
|
|
$PostingFrequency = '1m';
|
|
} elsif ($PostingFrequency =~ /bi-?monthly/) {
|
|
$PostingFrequency = '2m';
|
|
}
|
|
}
|
|
|
|
# parse placeholders in headers
|
|
foreach (@Headers) {
|
|
# convert Windows line-endings to Unix
|
|
s/\r//;
|
|
# drop empty header
|
|
$_ = '' if /^$/;
|
|
# Replace %LM placeholder in Subject: with the Last-modified: pseudo-header
|
|
if (/^Subject: /) {
|
|
if ($LastModified) {
|
|
$_ =~ s/\%LM/$LastModified/g;
|
|
} else {
|
|
$_ =~ s/ ?[<\[{\(]?\%LM[>\]}\)]? ?//;
|
|
}
|
|
}
|
|
# Replace placeholders in Message-ID:
|
|
# %n project name
|
|
# %y current year
|
|
# %m current month
|
|
# %d current day
|
|
# %p PID
|
|
if (/^Message-ID: /i) {
|
|
my $TDY = DateTime->now->strftime('%Y');
|
|
my $TDM = DateTime->now->strftime('%m');
|
|
my $TDD = DateTime->now->strftime('%d');
|
|
$_ =~ s/\%n/$Project/g;
|
|
$_ =~ s/\%y/$TDY/g;
|
|
$_ =~ s/\%m/$TDM/g;
|
|
$_ =~ s/\%d/$TDD/g;
|
|
$_ =~ s/\%p/$$/g;
|
|
# add random part in test mode
|
|
if ($OptTest) {
|
|
my $random = sprintf("%08X", rand(0xFFFFFFFF));
|
|
$_ =~ s/</<test-$random-/;
|
|
}
|
|
}
|
|
# create Expires: from time period
|
|
if (/^Expires: /) {
|
|
chomp;
|
|
$_ =~ s/^Expires:\s+//;
|
|
die "E: Illegal 'Expires: $_' in '$HeaderFile'.\n" if ($_ !~ /^\d+[dwmy]$/);
|
|
$_ = 'Expires: ' . &AddDuration(DateTime->now,$_)->strftime('%a, %d %b %Y %H:%M:%S %z') . "\n";
|
|
}
|
|
# add Supersedes: if set
|
|
if (/^Supersedes: /) {
|
|
if ($LastMID && !$OptTest) {
|
|
$_= "Supersedes: $LastMID\n";
|
|
} else {
|
|
$_ = '';
|
|
}
|
|
}
|
|
# overwrite Newsgroups: if --newsgroup is set
|
|
if ($OptNewsgroup && /^Newsgroups: /) {
|
|
print "- 'Newsgroups: $OptNewsgroup' has been set.\n" if $Config{'debug'};
|
|
$_= "Newsgroups: $OptNewsgroup\n";
|
|
}
|
|
# get Posting-Frequency
|
|
if (/^Posting-Frequency: /i) {
|
|
chomp;
|
|
$_ =~ s/^Posting-Frequency:\s+//i;
|
|
$PostingFrequency = $_;
|
|
$_ = '';
|
|
print "- Posting-Frequency set to $PostingFrequency.\n" if $Config{'debug'};
|
|
}
|
|
}
|
|
|
|
# not due if Posting-Freqency is "none"
|
|
if ($PostingFrequency =~ /none/) {
|
|
print "... is disabled.\n" if $Config{'verbose'} or $Config{'debug'};
|
|
return '';
|
|
}
|
|
|
|
# default to 1 month if no (valid) Posting-Frequency is set
|
|
$PostingFrequency = '1m' if $PostingFrequency !~ /^\d+[dwmy]$/;
|
|
|
|
# check if posting is due
|
|
print "- Posting has been forced.\n" if $Config{'debug'} && $OptForce;
|
|
if ($OptForce or (!$LastPosted) or ($LastPosted && &AddDuration(&ParseDate($LastPosted),$PostingFrequency) <= DateTime->now)) {
|
|
print "... is due and will be posted.\n" if $Config{'verbose'} or $Config{'debug'};
|
|
} else {
|
|
print "... is not due.\n" if $Config{'verbose'} or $Config{'debug'};
|
|
return '';
|
|
}
|
|
|
|
# return posting
|
|
return @Headers, "\n", @Body;
|
|
}
|
|
|
|
### ------------------------------------------------------------------
|
|
### post via NNTP
|
|
# taken and modified from tinews.pl
|
|
sub PostNNTP {
|
|
my @Posting = @_;
|
|
|
|
my $NNTP = ConnectNNTP();
|
|
my $NNTPMsg = $NNTP->message();
|
|
my $NNTPCode = $NNTP->code();
|
|
print "- Post article.\n" if $Config{'debug'};
|
|
if ($NNTPCode == 340) {
|
|
$NNTP->datasend(@Posting);
|
|
## buggy Net::Cmd < 2.31
|
|
$NNTP->set_status(200, "");
|
|
$NNTP->dataend();
|
|
$NNTPMsg = $NNTP->message();
|
|
$NNTPCode = $NNTP->code();
|
|
if (! $NNTP->ok()) {
|
|
$NNTP->quit();
|
|
warn("W: Posting failed! Response from server:\n", $NNTPCode, ' ', $NNTPMsg);
|
|
return 0;
|
|
}
|
|
} else {
|
|
$NNTP->quit();
|
|
warn("W: Posting failed! Response from server:\n", $NNTPCode, ' ', $NNTPMsg);
|
|
return 0;
|
|
}
|
|
$NNTP->quit();
|
|
print "- Done.\n" if $Config{'debug'};
|
|
return 1;
|
|
}
|
|
|
|
### ------------------------------------------------------------------
|
|
### update status (last posted, last mid)
|
|
sub UpdateStatus {
|
|
my ($Project, $LastMID) = @_;
|
|
my $StatusFile = $Config{'datadir'} . "$Project.cfg";
|
|
my @Status;
|
|
|
|
push @Status, "Last-Posted: " . DateTime->now->strftime('%Y-%m-%d') . "\n";
|
|
push @Status, "Last-Message-ID: $LastMID\n";
|
|
|
|
$StatusFile = path($StatusFile);
|
|
$StatusFile->spew(@Status);
|
|
|
|
print "- Status updated.\n" if $Config{'debug'};
|
|
return;
|
|
}
|
|
|
|
__END__
|
|
|
|
################################ Documentation #################################
|
|
|
|
=head1 NAME
|
|
|
|
yapfaq - Post FAQs to Usenet I<(yet another postfaq)>
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<yapfaq> [B<-Vhcfto>] [B<-p> I<project name>[B<-n> I<newsgroup>] [OPTIONS]
|
|
|
|
=head1 REQUIREMENTS
|
|
|
|
=over 2
|
|
|
|
=item -
|
|
|
|
Perl 5.8 or later with core modules
|
|
|
|
=item -
|
|
|
|
DateTime
|
|
|
|
=item -
|
|
|
|
Path::Tiny
|
|
|
|
=back
|
|
|
|
Furthermore you need access to a news server to actually post FAQs.
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
B<yapfaq> can post (one or more) FAQs (or other texts) to Usenet every
|
|
n days, weeks, months or years. The content (article body) for each
|
|
text will be read from a project file, and headers (with some
|
|
placeholders) will be read from another project file. Posting
|
|
frequency can be defined as header, or in the body in form of a
|
|
news.answers pseudo-header.
|
|
|
|
Project status (last time posted, last used I<Message-ID>) will be
|
|
tracked in a config file for each project.
|
|
|
|
Configuration can be done by modifying the source (disapproved), by
|
|
adding a config file in your home directory or by overriding those
|
|
options on the command line.
|
|
|
|
=head2 Runtime configuration
|
|
|
|
Options for B<yapfaq> can be set by modifying the I<configuration>
|
|
section of the source or by using a config file located at
|
|
F<$XDG_CONFIG_HOME/yapfaqrc>, F<$HOME/.config/yapfaqrc> or
|
|
F<$HOME/.yapfaqrc> (in order of precedence). Options in config files
|
|
will override options in source. Both can be overridden by using
|
|
command line options.
|
|
|
|
=over 2
|
|
|
|
=item B<datadir> = I<path>
|
|
|
|
Path to the directory for all project files.
|
|
|
|
Each project needs a F<I<project>.hdr> file with all headers and a
|
|
F<I<project>.txt> file containing the content (body) to be posted.
|
|
B<yapfaq> will track the project status in a F<I<project>.cfg> file.
|
|
|
|
You can override this option on the command line by using
|
|
B<--datadir> I<path>.
|
|
|
|
=item B<verbose> = I<0|1>
|
|
|
|
Display some status messages on STDOUT if set to I<1>.
|
|
|
|
You can override this option on the command line by using
|
|
B<--verbose> (B<-v>) or B<--noverbose> accordingly.
|
|
|
|
Don't use B<verbose> if you want to pipe your text to another program!
|
|
|
|
=item B<debug> = I<0|1>
|
|
|
|
Display debug messages (and NNTP dialogue) on STDOUT if set to I<1>.
|
|
|
|
You can override this option on the command line by using
|
|
B<--debug> (B<-d>) or B<--nodebug> accordingly.
|
|
|
|
Don't use B<debug> if you want to pipe your text to another program!
|
|
|
|
=item B<nntp-server> = I<hostname>
|
|
|
|
News (NNTP) server to connect to.
|
|
|
|
Can be overridden by setting I<$NNTPSERVER> or I<$NEWSHOST> in your
|
|
environment.
|
|
|
|
You can override this option on the command line by using
|
|
B<--nntp-server> I<hostname>.
|
|
|
|
=item B<nntp-port> = I<port>
|
|
|
|
Port on B<nntp-server> to connect to. Default is 119.
|
|
|
|
B<yapfaq> can't use NNTPS on port 563, but can use STARTTLS if
|
|
available.
|
|
|
|
Can be overridden by setting I<$NNTPPORT> in your environment.
|
|
|
|
You can override this option on the command line by using
|
|
B<--nntp-port> I<port>.
|
|
|
|
=item B<nntp-user> = I<user name>
|
|
|
|
User name for AUTHINFO authentication.
|
|
|
|
You can override this option on the command line by using
|
|
B<--nntp-user> I<user name>.
|
|
|
|
=item B<nntp-pass> = I<password>
|
|
|
|
Password for AUTHINFO authentication.
|
|
|
|
You can override this option on the command line by using
|
|
B<--nntp-pass> I<password>.
|
|
|
|
=item B<force-auth> = I<0|1>
|
|
|
|
Force AUTHINFO authentication, even if the server reports that you
|
|
may post. Necessary for some servers.
|
|
|
|
You can override this option on the command line by using
|
|
B<--force-auth> or B<--noforce-auth> accordingly.
|
|
|
|
=item B<starttls> = I<0|1>
|
|
|
|
Use a TLS encrypted connection (via STARTTLS) if available.
|
|
|
|
You can override this option on the command line by using
|
|
B<--starttls> or B<--nostarttls> accordingly.
|
|
|
|
=back
|
|
|
|
=head2 Project files
|
|
|
|
Each project needs a F<I<project>.hdr> and a F<I<project>.text> file,
|
|
and will get a F<I<project>.cfg> file after the first posting. These
|
|
files need to be in B<datadir>.
|
|
|
|
=head3 Headers file
|
|
|
|
Needs to have at least I<From:>, I<Subject:> and I<Newsgroups:> and
|
|
can contain all other headers that the posting should have. Headers
|
|
must conform to RFC 5536 and RFC 5322 and use MIME encoded words for
|
|
8bit characters. B<yapfaq> won't convert headers.
|
|
|
|
I<Subject:> may contain a I<%LM> placeholder that will be replaced
|
|
with the I<Last-modified:> pseudo-header from the text file
|
|
(see below), if present. If no I<Last-modified:> pseudo-header is
|
|
found, the placeholder (and surrounding brackets, angle brackets or
|
|
curly brackets and spaces) is removed.
|
|
|
|
If a I<Message-ID:> header is present, placeholders in that header
|
|
will be replaced: I<%n> with the project name, I<%y> with the current
|
|
year (YYYY), I<%m> with the current month (MM), I<%d> with the
|
|
current day (DD) and I<%p> with the current process ID (PID) of
|
|
B<yapfaq>. If no I<Message-ID:> header is present, the I<Message-ID>
|
|
will be generated with the hostname of the system B<yapfaq> is
|
|
running on and I<%n-%y-%m-%d> as template for the left hand side. If
|
|
the I<Message-ID:> header in the headers file does not contain
|
|
placeholders, the next repost will most probably fail.
|
|
|
|
If an I<Expires:> header is present, it must contain a time period of
|
|
n days, weeks, months or years in the form of a number followed by
|
|
I<d>, I<w>, I<m> or I<y>, e.g. I<Expires: 4w> for four weeks: If no
|
|
such I<Expires:> header is present, no such header will be set.
|
|
|
|
If a I<Supersedes:> header is present (e.g. I<Supersedes: yes>, it
|
|
will be replaced with a I<Supersedes:> header containing the
|
|
I<Message-ID> of the last posted article.
|
|
|
|
If a I<Posting-Frequency:> header is present, it must contain a time
|
|
period in the same way as for I<Expires:>, e.g. I<Posting-Frequency:
|
|
1m> for a monthly posting, or the keyword B<none>. The
|
|
I<Posting-Frequency:> header will be removed after parsing.
|
|
Alternatively a I<Posting-Frequency:> pseudo-header in the text file
|
|
may be used (see below). If no I<Posting-Frequency:> is set anywhere,
|
|
the default ist one month (I<1m>). I<Posting-Frequency: none> disables
|
|
automatic postings.
|
|
|
|
B<Example headers file>
|
|
|
|
From: John Doe <john-doe@example.com>
|
|
Reply-To: <john@doe.example>
|
|
Subject: <%LM> FAQ for alt.example.discussions
|
|
Newsgroups: alt.example.discussions
|
|
Message-ID: <%n-%y-%m-%d@my-domain.example>
|
|
Posting-frequency: 1w
|
|
Expires: 1m
|
|
Supersedes: yes
|
|
Mime-Version: 1.0
|
|
Content-Type: text/plain; charset=utf-8
|
|
Content-Transfer-Encoding: 8bit
|
|
|
|
=head3 Text file
|
|
|
|
The content (body) of your FAQ or other text.
|
|
|
|
It may contain pseudo-headers, starting on the first line and
|
|
separated from the reamining content by a blank line.
|
|
|
|
I<Last-modified:> and I<Posting-frequency> will be evaluated by
|
|
B<yapfaq>.
|
|
|
|
If your content contains 8bit characters, you'll need suitable MIME
|
|
headers in your headers file.
|
|
|
|
B<Example text file with pseudo-headers>
|
|
|
|
Archive-name: alt-example/discussions-faq
|
|
Posting-frequency: weekly
|
|
Last-modified: 2025-12-15
|
|
URL: https://doe.example/faqs/alt-example-discussions-faq.txt
|
|
|
|
This is a list of frequently asked questions (FAQs) and their
|
|
answers for the alt.example.discussions newsgroup.
|
|
|
|
1. What is the topic of alt.example.discussions?
|
|
|
|
We discuss examples.
|
|
|
|
That's quite enought, isn't it?
|
|
|
|
=head1 OPTIONS
|
|
|
|
=over 4
|
|
|
|
=item B<-c>, B<--config>
|
|
|
|
Display current runtime configuration from source or config file.
|
|
|
|
=item B<-f>, B<--force>
|
|
|
|
Post text unconditionally, even if not due according to the defined
|
|
posting frequency. This refers either to all projects or just one
|
|
defined by B<--project>.
|
|
|
|
=item B<-n>, B<--newsgroup> I<newsgroup>
|
|
|
|
Override the I<Newsgroups:> header for all texts posted. Intended for
|
|
testing purposes.
|
|
|
|
Combine with B<--test> to avoid updating project status and to get a
|
|
unique I<Message-ID:> (and no I<Supersedes:> header).
|
|
|
|
=item B<-o>, B<--output>
|
|
|
|
Don't post via NNTP, but print to STDOUT.
|
|
|
|
Combine with B<--test> to avoid updating project status.
|
|
|
|
Intended for testing purposes or to pipe in another program like
|
|
I<inews> or I<tinews.pl>. If you want to pipe the output to another
|
|
program, neither B<--verbose> nor B<--debug> should be set.
|
|
|
|
=item B<-p>, B<--project> I<project name>
|
|
|
|
Run for just one project (FAQ, text). Default is running for all
|
|
projects.
|
|
|
|
=item B<-h>, B<--help>
|
|
|
|
Display this man page and exit.
|
|
|
|
=item B<-t>, B<--test>
|
|
|
|
Test mode. Don't update project status (time and Message-ID of last
|
|
posting), dont' add a I<Supersedes:> header and modify the
|
|
I<Message-ID:> with a random part.
|
|
|
|
The text(s) will still be posted if due or forced by B<--force>.
|
|
|
|
Combine with B<--output> to redirect output to STDOUT or with
|
|
B<--newsgroup> to override the I<Newsgroups:> header.
|
|
|
|
=item B<-V>, B<--version>
|
|
|
|
Display version and copyright information and exit.
|
|
|
|
=item B<OPTIONS>
|
|
|
|
You can override all runtime configuration options set in the source
|
|
or a config file from the command line, as described above.
|
|
|
|
=back
|
|
|
|
=head1 EXAMPLES
|
|
|
|
Post all FAQs that are due for posting:
|
|
|
|
yapfaq.pl
|
|
|
|
You may run this command daily from B<cron>.
|
|
|
|
Do a dry run, showing which FAQs would be posted and print them on
|
|
STDOUT:
|
|
|
|
yapfaq.pl -t -v -o
|
|
(or yapfaq.pl -tvo)
|
|
|
|
The same, with debugging output:
|
|
|
|
yapfaq.pl -tdo
|
|
|
|
Force a test post of your I<example> text to I<alt.test>, even if
|
|
the text is not due to be posted:
|
|
|
|
yapfaq.pl -t -f -n alt.test
|
|
|
|
The same, with debugging output:
|
|
|
|
yapfaq.pl -tfdn alt.test
|
|
|
|
|
|
Pipe all FAQs (that are due for posting) to I<inews> from INN:
|
|
|
|
yapfaq.pl -o | inews
|
|
|
|
You may run this command daily from B<cron>, too.
|
|
|
|
=head1 ENVIRONMENT
|
|
|
|
=over 2
|
|
|
|
=item B<$NEWSHOST>
|
|
|
|
Set to override the NNTP server configured in the source or config
|
|
file. It has lower priority than B<$NNTPSERVER> and should be
|
|
avoided. The B<--nntp-server> command line option overrides
|
|
B<$NEWSHOST>.
|
|
|
|
=item B<$NNTPSERVER>
|
|
|
|
Set to override the NNTP server configured in the source or config
|
|
file. This has higher priority than B<$NEWSHOST>. The
|
|
B<--nntp-server> command line option overrides B<$NNTPSERVER>.
|
|
|
|
=item B<$NNTPPORT>
|
|
|
|
The NNTP TCP port to connect news to. This variable only needs to be
|
|
set if the TCP port is not 119 (the default). The B<--nntp-port>
|
|
command line option overrides B<$NNTPPORT>.
|
|
|
|
=back
|
|
|
|
=head1 FILES
|
|
|
|
=over 2
|
|
|
|
=item F<bin/yapfaq.pl>
|
|
|
|
The script itself.
|
|
|
|
=item F<$XDG_CONFIG_HOME/yapfaqrc> F<$HOME/.config/yapfaqrc> F<$HOME/.yapfaqrc>
|
|
|
|
Config file (on order of precedence).
|
|
|
|
=item F<I<datadir>/I<project>.hdr>
|
|
|
|
Headers for I<project>.
|
|
|
|
=item F<I<datadir>/I<project>.txt>
|
|
|
|
Content (body) for I<project>.
|
|
|
|
=item F<I<datadir>/I<project>.cfg>
|
|
|
|
Status data of I<project>.
|
|
|
|
=back
|
|
|
|
=head1 BUGS
|
|
|
|
Please report any bugs or feature requests to the author or use the
|
|
bug tracker at L<https://code.virtcomm.de/thh/yapfaq/issues>!
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<https://th-h.de/net/software/yapfaq/> will have the current
|
|
version of this program.
|
|
|
|
This program is maintained using the Git version control system at
|
|
L<https://code.virtcomm.de/thh/yapfaq/>.
|
|
|
|
=head1 AUTHOR
|
|
|
|
Thomas Hochstein <thh@thh.name>
|
|
|
|
Original author (up to version 0.5b, dating from 2003):
|
|
Marc Brockschmidt <marc@marcbrockschmidt.de>
|
|
|
|
=head1 COPYRIGHT AND LICENSE
|
|
|
|
Copyright (c) 2003 Marc Brockschmidt <marc@marcbrockschmidt.de>
|
|
|
|
Copyright (c) 2010-2017, 2026 Thomas Hochstein <thh@thh.name>
|
|
|
|
This program is free software; you may redistribute it and/or modify it
|
|
under the same terms as Perl itself.
|
|
|
|
This program contains (modified) code from tinews.pl,
|
|
copyright (c) 2002-2024 Urs Janssen <urs@tin.org> and
|
|
Marc Brockschmidt <marc@marcbrockschmidt.de>
|
|
|
|
This program contains (modified) code from pgpverify.pl,
|
|
written April 1996, <tale@isc.org> (David C Lawrence),
|
|
currently maintained by Russ Allbery <eagle@eyrie.org>
|
|
|
|
=cut
|