[Libguestfs] [libnbd PATCH] docs: Add libnbd-security(1) man page

[Richard W.M. Jones]

On Tue, Oct 01, 2019 at 02:28:39PM -0500, Eric Blake wrote:
> Copies heavily after a similar addition recently made in nbdkit.
> ---
> 
> I'm not sure if .1 or .3 fits better for the man page.  With nbdkit,
> .1 made sense because 'nbdkit' is a standalone program; but with
> libnbd, our only standalone is nbdsh, yet naming it nbdsh-security
> seems off.

So the patch is fine, thanks for adding it.  I don't think I have a
strong opinion about whether the new page should be in section 1 or 3.
I would lean towards section 3 because that's where our other man
pages have gone, and as you say it's not a command line tool.  But
it's not a strong preference, so you can decide.

Rich.

>  docs/Makefile.am         |  7 +++++++
>  docs/libnbd-security.pod | 32 ++++++++++++++++++++++++++++++++
>  docs/libnbd.pod          |  1 +
>  Makefile.am              |  1 +
>  .gitignore               |  3 ++-
>  SECURITY                 | 14 ++++++++++++++
>  6 files changed, 57 insertions(+), 1 deletion(-)
>  create mode 100644 docs/libnbd-security.pod
>  create mode 100644 SECURITY
> 
> diff --git a/docs/Makefile.am b/docs/Makefile.am
> index df58586..4c99b5d 100644
> --- a/docs/Makefile.am
> +++ b/docs/Makefile.am
> @@ -38,6 +38,7 @@ generator_built = \
>  EXTRA_DIST = \
>  	$(generator_built) \
>  	libnbd.pod \
> +	libnbd-security.pod \
>  	nbd_create.pod \
>  	nbd_close.3 \
>  	nbd_get_error.3 \
> @@ -48,6 +49,7 @@ if HAVE_POD
> 
>  man_MANS = \
>  	libnbd.3 \
> +	libnbd-security.1 \
>  	nbd_create.3 \
>  	nbd_close.3 \
>  	nbd_get_error.3 \
> @@ -73,4 +75,9 @@ libnbd.3: libnbd.pod $(top_builddir)/podwrapper.pl \
>  	    --html $(top_builddir)/html/$@.html \
>  	    $<
> 
> +libnbd-security.1: libnbd-security.pod
> +	$(PODWRAPPER) --section=1 --man $@ \
> +	    --html $(top_builddir)/html/$@.html \
> +	    $<
> +
>  endif HAVE_POD
> diff --git a/docs/libnbd-security.pod b/docs/libnbd-security.pod
> new file mode 100644
> index 0000000..5fe0926
> --- /dev/null
> +++ b/docs/libnbd-security.pod
> @@ -0,0 +1,32 @@
> +=head1 NAME
> +
> +libnbd-security - information about past security issues in libnbd
> +
> +=head1 DESCRIPTION
> +
> +This page details past security issues found in libnbd.
> +
> +For how to report new security issues, see the C<SECURITY> file in the
> +top level source directory, also available online here:
> +L<https://github.com/libguestfs/libnbd/blob/master/SECURITY>
> +
> +=head2 CVE-2019-14842
> +protocol downgrade attack when using LIBNBD_TLS_REQUIRE
> +
> +See the full announcement and links to mitigation, tests and fixes
> +here:
> +https://www.redhat.com/archives/libguestfs/2019-September/msg00128.html
> +
> +=head1 SEE ALSO
> +
> +L<libnbd(1)>.
> +
> +=head1 AUTHORS
> +
> +Eric Blake
> +
> +Richard W.M. Jones
> +
> +=head1 COPYRIGHT
> +
> +Copyright (C) 2019 Red Hat Inc.
> diff --git a/docs/libnbd.pod b/docs/libnbd.pod
> index 7bd59f5..e4810f6 100644
> --- a/docs/libnbd.pod
> +++ b/docs/libnbd.pod
> @@ -830,6 +830,7 @@ L<https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md>.
> 
>  =head2 Other
> 
> +L<libnbd-security(1),
>  L<qemu(1)>.
> 
>  =head1 AUTHORS
> diff --git a/Makefile.am b/Makefile.am
> index 59918b9..019936f 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -24,6 +24,7 @@ EXTRA_DIST = \
>  	.gitignore \
>  	html/pod.css \
>  	scripts/git.orderfile \
> +	SECURITY \
>  	$(NULL)
> 
>  SUBDIRS = \
> diff --git a/.gitignore b/.gitignore
> index 9254d1a..ae3e04f 100644
> --- a/.gitignore
> +++ b/.gitignore
> @@ -37,10 +37,11 @@ Makefile.in
>  /config.sub
>  /configure
>  /depcomp
> -/docs/*.3
> +/docs/*.[13]
>  /docs/*.pod
>  /docs/Makefile.inc
>  !/docs/libnbd.pod
> +!/docs/libnbd-security.pod
>  !/docs/nbd_close.3
>  !/docs/nbd_create.pod
>  !/docs/nbd_get_err??.3
> diff --git a/SECURITY b/SECURITY
> new file mode 100644
> index 0000000..d9a32d6
> --- /dev/null
> +++ b/SECURITY
> @@ -0,0 +1,14 @@
> +If you think you've found a serious or potential security bug that you
> +don't want to report on a public mailing list, then send email to both
> +<rjones at redhat.com> and <eblake at redhat.com>.
> +
> +Make it clear in the email Subject line that it's a serious or
> +security-related bug in libnbd.
> +
> +You can also sign and/or encrypt messages using our GPG public keys
> +available on the usual keyservers.
> +
> +For information about past security issues, see
> +docs/libnbd-security.pod, or the libnbd-security(1) man page if you
> +have installed libnbd, also available online here:
> +http://libguestfs.org/libnbd-security.1.html
> -- 
> 2.21.0
> 
> _______________________________________________
> Libguestfs mailing list
> Libguestfs at redhat.com
> https://www.redhat.com/mailman/listinfo/libguestfs

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-builder quickly builds VMs from scratch
http://libguestfs.org/virt-builder.1.html