NAME
    tinews.pl - Post and sign an article via NNTP

SYNOPSIS
    tinews.pl [OPTIONS] < *input*

DESCRIPTION
    tinews.pl reads an article on STDIN, signs it via pgp(1) or gpg(1) and
    posts it to a news server.

    The article shall not contain any raw 8-bit data or it needs to already
    have the relevant MIME-headers as tinews.pl will not add any
    MIME-headers nor encode its input.

    If the article contains To:, Cc: or Bcc: headers and mail-actions are
    configured it will automatically add a "Posted-And-Mailed: yes" header
    to the article and send out the mail-copies.

    If a Cancel-Lock secret file is defined it will automatically add a
    Cancel-Lock: (and Cancel-Key: if required) header.

    The input should have unix line endings (<LF>, '\n'). Use --transform to
    convert from <CR><LF> to just <LF>.

OPTIONS
    -4 | --ipv4
        Force connecting via IPv4 to the remote NNTP server.

    -a "Approved" | --approved "Approved"
        Set the article header field Approved: to the given value.

    -c "Control" | --control "Control"
        Set the article header field Control: to the given value.

    -d "Distribution" | --distribution "Distribution"
        Set the article header field Distribution: to the given value.

    -e "Expires" | --expires "Expires"
        Set the article header field Expires: to the given value.

    -f "From" | --from "From"
        Set the article header field From: to the given value.

    -i header | --ignore-headers header
        Comma separated list of headers that will be ignored during signing.
        Usually the following headers will be signed if present:

        From, Newsgroups, Subject, Control, Supersedes, Followup-To, Date,
        Injection-Date, Sender, Approved, Message-ID, Reply-To, Cancel-Key,
        Also-Control and Distribution.

        Some of them may be altered on the Server (i.e. Cancel-Key) which
        would invalid the signature, this option can be used the exclude
        such headers if required.

    -m "Message-ID" | --message-id "Message-ID"
        Set the article header field Message-ID: to the given value.

    -n "Newsgroups" | --newsgroups "Newsgroups"
        Set the article header field Newsgroups: to the given value.

    -o "Organization" | --organization "Organization"
        Set the article header field Organization: to the given value.

    -p "port" | --port "port"
        use "port" as NNTP-port

    -r "Reply-To" | --reply-to "Reply-To"
        Set the article header field Reply-To: to the given value.

    -s directory | --savedir directory
        Save signed article to directory directory instead of posting.

    -t "Subject" | --subject "Subject"
        Set the article header field Subject: to the given value.

    -v | --verbose
        Warn about disabled options due to lacking perl-modules or
        executables and unreadable files and enable warnings about raw 8-bit
        data.

    -w "Followup-To" | --followup-to "Followup-To"
        Set the article header field Followup-To: to the given value.

    -x "Path" | --path "Path"
        Prepend the article header field Path: with the given value.

    -D | -N | --debug
        Set Net::NNTP(3pm) to debug mode, enable warnings about raw 8-bit
        data, warn about disabled options due to lacking perl-modules or
        executables and unreadable files.

    -E | --discard-empty
        Silently discard an empty article.

    -F | --references
        Set the article header field References: to the given value.

    -H | --help
        Show help-page.

    -I | --no-injection-date
        Do not add Injection-Date: header.

    -L | --no-canlock
        Do not add Cancel-Lock: / Cancel-Key: headers.

    -O | --no-organization
        Do not add Organization: header.

    -R | --no-control
        Restricted mode, disallow control-messages.

    -S | --no-signature
        Do not append $HOME/.signature.

    -T "seconds" | --timeout "seconds"
        Override the connection timeout setting. Default is 120 seconds.

    -X | --no-sign
        Do not sign the article.

    -Y | --force-auth
        Force authentication on connect even if not required by the server.

    --canlock-algorithm "Algorithm"
        Digest algorithm used for Cancel-Lock: / Cancel-Key: headers.
        Supported algorithms are sha1, sha256 and sha512. Default is sha1.

    --ssl | --nntps
        Use NNTPS (via port 563) if available. This requires a recent
        version of Net::NNTP(3pm) and IO::Socket::SSL(3pm). Be aware that no
        SSL verification will be done.

    --transform
        Convert network line endings (<CR><LF>) to unix line endings (<LF>).

    --version
        Show version.

    -A -V -W
        These options are accepted for compatibility reasons but ignored.

    -h | --headers
        These options are accepted for compatibility reasons but ignored.

EXIT STATUS
    The following exit values are returned:

     0  Successful completion.

    !=0 An error occurred.

ENVIRONMENT
    $NEWSHOST
        Set to override the NNTP server configured in the source or
        config-file. It has lower priority than $NNTPSERVER and should be
        avoided.

    $NNTPSERVER
        Set to override the NNTP server configured in the source or
        config-file. This has higher priority than $NEWSHOST.

    $NNTPPORT
        The NNTP TCP-port to post news to. This variable only needs to be
        set if the TCP-port is not 119 (the default). The '-p' command-line
        option overrides $NNTPPORT.

    $PGPPASS
        Set to override the passphrase configured in the source (used for
        pgp(1)-2.6.3).

    $PGPPASSFILE
        Passphrase file used for pgp(1) or gpg(1).

    $SIGNER
        Set to override the user-id for signing configured in the source. If
        you neither set $SIGNER nor configure it in the source the contents
        of the From:-field will be used.

    $REPLYTO
        Set the article header field Reply-To: to the return address
        specified by the variable if there isn't already a Reply-To: header
        in the article. The '-r' command-line option overrides $REPLYTO.

    $ORGANIZATION
        Set the article header field Organization: to the contents of the
        variable if there isn't already an Organization: header in the
        article. The '-o' command-line option overrides $ORGANIZATION, The
        '-O' command-line option disables it.

    $DISTRIBUTION
        Set the article header field Distribution: to the contents of the
        variable if there isn't already a Distribution: header in the
        article. The '-d' command-line option overrides $DISTRIBUTION.

FILES
    pgptmp.txt
        Temporary file used to store the reformatted article.

    pgptmp.txt.asc
        Temporary file used to store the reformatted and signed article.

    $PGPPASSFILE
        The passphrase file to be used for pgp(1) or gpg(1).

    $HOME/.signature
        Signature file which will be automatically included.

    $HOME/.cancelsecret
        The passphrase file to be used for Cancel-Locks. This feature is
        turned off by default.

    $HOME/.newsauth
        "nntpserver password [user]" pairs or triples for NNTP servers that
        require authorization. First match counts. Any line that starts with
        "#" is a comment. Blank lines are ignored. This file should be
        readable only for the user as it contains the user's unencrypted
        password for reading news. If no matching entry is found
        $HOME/.nntpauth is checked.

    $HOME/.nntpauth
        "nntpserver user password" triples for NNTP servers that require
        authorization. First match counts. Lines starting with "#" are
        skipped and blank lines are ignored. This file should be readable
        only for the user as it contains the user's unencrypted password for
        reading news. $HOME/.newsauth is checked first.

    $XDG_CONFIG_HOME/tinewsrc $HOME/.config/tinewsrc $HOME/.tinewsrc
        "option=value" configuration pairs, last match counts and only
        "value" is case sensitive. Lines that start with "#" are ignored. If
        the file contains unencrypted passwords (e.g. nntp-pass or
        pgp-pass), it should be readable for the user only. Use -vH to get a
        full list of all available configuration options.

SECURITY
    If you've configured or entered a password, even if the variable that
    contained that password has been erased, it may be possible for someone
    to find that password, in plaintext, in a core dump. In short, if
    serious security is an issue, don't use this script.

    Be aware that even if NNTPS is used still no SSL verification will be
    done.

NOTES
    tinews.pl is designed to be used with pgp(1)-2.6.3, pgp(1)-5, pgp(1)-6,
    gpg(1) and gpg2(1).

    tinews.pl requires the following standard modules to be installed:
    Getopt::Long(3pm), Net::NNTP(3pm), Time::Local(3pm) and
    Term::Readline(3pm).

    NNTPS (NNTP with implicit TLS; RFC 4642 and RFC 8143) may be unavailable
    if Net::NNTP(3pm) is too old or IO::Socket::SSL(3pm) is missing on the
    system. tinews.pl will fallback to unencrypted NNTP in that case.

    If the Cancel-Lock feature (RFC 8315) is enabled the following
    additional modules must be installed: MIME::Base64(3pm),
    Digest::SHA(3pm) or Digest::SHA1(3pm) and Digest::HMAC_SHA1(3pm). sha256
    and sha512 as algorithms for canlock-algorithm are only available with
    Digest::SHA(3pm).

    gpg2(1) users may need to set $GPG_TTY, i.e.

     GPG_TTY=$(tty)
     export GPG_TTY

    before using tinews.pl. See <https://www.gnupg.org/> for details.

    tinews.pl does not do any MIME encoding, its input should be already
    properly encoded and have all relevant headers set.

AUTHOR
    Urs Janssen <urs@tin.org>, Marc Brockschmidt <marc@marcbrockschmidt.de>

SEE ALSO
    pgp(1), gpg(1), gpg2(1), pgps(1), Digest::HMAC_SHA1(3pm),
    Digest::SHA(3pm), Digest::SHA1(3pm), Getopt::Long(3pm),
    IO::Socket::SSL(3pm), MIME::Base64(3pm), Net::NNTP(3pm),
    Time::Local(3pm), Term::Readline(3pm)

