Ubuntu Manpage: gencancel - Generate cancel control messages

Provided by: inn2_2.7.2~20240212-1build3_amd64

NAME

       gencancel - Generate cancel control messages

SYNOPSIS

       gencancel [-adkLm] [-b body] [-c charset] [-f from] [-n newsgroups] [-s subject] message-id

DESCRIPTION

       gencancel provides the news administrator with a helpful tool to generate cancel control messages,
       writing them to standard output.  The generated cancel article can then be injected by inews (see
       examples below).

       gencancel expects the Message-ID of the article to cancel; this message-id argument should properly be
       quoted for the shell and surrounded by angle brackets.  gencancel will then try to read the original
       article in the news spool to determine the original newsgroups it was posted to, and re-use that
       information for the cancel control message.  If you want to modify that, or if the information was not
       found, you'll have to set it with the -n flag.

       If INN was built with Cancel-Lock support, gencancel will generate the right admin Cancel-Key header
       field to use in order to authenticate cancels.  If, for whatever reason, you need cancelling an article
       posted from your news server with a Cancel-Lock header field, the corresponding admin Cancel-Key hashes
       are needed to authenticate the withdrawal request.  That information is computed with the canlockadmin
       parameter set in inn-secrets.conf.

       In case you only need the admin Cancel-Key hashes, you can use the -k flag.  Only the body of the Cancel-
       Key header field will then be written to standard output.  You can then re-use it for instance in a
       supersede request or from another script.

OPTIONS

-a gencancel outputs by default an Approved header field, using the same value as the From header field
body. If -a is used, no Approved header field is output.

This header field is useful for cancelling articles originally posted to moderated newsgroups. If a
cancel control article lists a moderated newsgroup in its Newsgroups header field, and no Approved
header field is present, the cancel will be sent to the moderator first for approval. Cancel control
messages are not required to contain an Approved header field outside of moderated newsgroups, but
can, so you shouldn't generally use -a unless you really want your cancels to be approved by a
moderator, or are sure the Newsgroups header field does not list any moderated newsgroups.

-b body
gencancel writes by default "Admin cancel." in the body of cancel control messages. Using this
argument permits writing a different value, which may be empty or multi-line.

-c charset
By default, "ISO-8859-1" is specified as the used charset in the Content-Type header field. In case
you change the default body with -b, you may want to also change charset accordingly.

-d gencancel generates a Date header field in the local time of your news server. Using -d will make
use of a UTC date.

-f from
gencancel uses by default the value of complaints in inn.conf for the From header field. Using this
argument permits setting the value you want. The same value will be used for the Approved header
field (if generated, when -a is not given).

-k Instead of outputting a whole cancel control message, gencancel will just output the body of the
Cancel-Key header field with admin hashes.

This flag is only available if INN was built with Cancel-Lock support.

-L gencancel outputs by default a Cancel-Key header field to authenticate the cancel control message.
If -L is used, no Cancel-Key header field is output.

This flag is only available if INN was built with Cancel-Lock support.

-m gencancel generates by default a random Message-ID and uses it as unique identifier of the cancel
control message. If -m is used, no Message-ID header field is output.

-n newsgroups
gencancel generates by default the same Newsgroups header field as the one present in the original
article to cancel. This is done to best ensure that the cancel control message will be relayed to
the same news servers as the original message.

In case your news server does not (or no longer) locally carry the original article, you will have to
give an explicit newsgroup or list of comma-separated newsgroups with this flag, that will be used as
the Newsgroups header field of the cancel.

-s subject
gencancel uses by default "cmsg cancel <message-id>" as the subject of cancel control messages.
Using this argument permits setting a different value for the Subject header field. Make sure it is
properly MIME-encoded.

EXAMPLES

       To only retrieve the admin Cancel-Key hashes associated to the given Message-ID:

           gencancel -k '<mid@news>'

       If you're using non-ASCII characters in headers, make sure you properly MIME-encode them.  For instance,
       use the "Encode" Perl module:

           FROM=$(perl -e 'use Encode;
                           print encode("MIME-Q",
                                        decode("UTF-8", "Julien ÉLIE"));')
           gencancel -f "$FROM <admin@news.server.com>" '<mid@news>'

       You'll then see in the output a properly MIME-encoded header field:

           From: =?UTF-8?Q?Julien_=C3=89LIE?= <admin@news.server.com>

       An example of call with a custom multi-line body:

           gencancel -b "$(echo -e "Multi\nLine\nBody.")" '<mid@news>'

       (Use -c to change the default Content-Type charset for the body.)

       You can then pipe the result into "inews -h -P -D" (meaning inews expects an article with headers, does
       not add a Sender header field, and writes the result to standard output instead of actually injecting
       it):

           gencancel '<mid@news>' | inews -h -P -D

       If it all looks good, then inject it into the news system (without giving "-D" to inews):

           gencancel '<mid@news>' | inews -h -P

       Note that inews sends the message to the server specified in the server parameter in inn.conf.

HISTORY