From 154b705f32d7e179aea1af5ed367a3d33612f294 Mon Sep 17 00:00:00 2001
From: "Richard W.M. Jones" <rjones@redhat.com>
Date: Thu, 17 Oct 2013 15:12:19 +0100
Subject: [PATCH] Add man page for /etc/libguestfs-tools.conf (RHBZ#1019889).

Add a man page to document this configuration file.  This is
required by some distros, eg. Debian and RHEL.

(cherry picked from commit 24a315507d1293a0ec097b57d15efb3dae784489)
---
 .gitignore                     |  4 +++
 fish/Makefile.am               | 15 +++++++++
 fish/guestfish.pod             |  3 +-
 fish/libguestfs-tools.conf     | 16 +---------
 fish/libguestfs-tools.conf.pod | 70 ++++++++++++++++++++++++++++++++++++++++++
 fuse/guestmount.pod            |  3 +-
 po-docs/ja/Makefile.am         | 12 +++++++-
 po-docs/podfiles               |  1 +
 po-docs/uk/Makefile.am         | 12 +++++++-
 rescue/virt-rescue.pod         |  3 +-
 10 files changed, 119 insertions(+), 20 deletions(-)
 create mode 100644 fish/libguestfs-tools.conf.pod

diff --git a/.gitignore b/.gitignore
index 6c2f580..1a94f1e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -136,11 +136,13 @@ Makefile.in
 /fish/guestfish-actions.pod
 /fish/guestfish-commands.pod
 /fish/guestfish-prepopts.pod
+/fish/libguestfs-tools.conf.5
 /fish/prepopts.c
 /fish/prepopts.h
 /fish/rc_protocol.c
 /fish/rc_protocol.h
 /fish/stamp-guestfish.pod
+/fish/stamp-libguestfs-tools.conf.pod
 /fish/stamp-virt-copy-in.pod
 /fish/stamp-virt-copy-out.pod
 /fish/stamp-virt-tar-in.pod
@@ -201,6 +203,7 @@ Makefile.in
 /html/guestunmount.1.html
 /html/libguestfs-make-fixed-appliance.1.html
 /html/libguestfs-test-tool.1.html
+/html/libguestfs-tools.conf.5.html
 /html/virt-alignment-scan.1.html
 /html/virt-cat.1.html
 /html/virt-copy-in.1.html
@@ -325,6 +328,7 @@ Makefile.in
 /pick-guests.pl
 /po-docs/*/*.1
 /po-docs/*/*.3
+/po-docs/*/*.5
 /po-docs/*/*.8
 /po-docs/*/*.pl
 /po-docs/po4a.conf
diff --git a/fish/Makefile.am b/fish/Makefile.am
index ceceb96..83a8458 100644
--- a/fish/Makefile.am
+++ b/fish/Makefile.am
@@ -19,6 +19,7 @@ include $(top_srcdir)/subdir-rules.mk
 
 CLEANFILES = \
 	stamp-guestfish.pod \
+	stamp-libguestfs-tools.conf.pod \
 	stamp-virt-copy-in.pod \
 	stamp-virt-copy-out.pod \
 	stamp-virt-tar-in.pod \
@@ -49,6 +50,7 @@ EXTRA_DIST = \
 	rc_protocol.x \
 	guestfish.pod \
 	libguestfs-tools.conf \
+	libguestfs-tools.conf.pod \
 	virt-copy-in \
 	virt-copy-out \
 	virt-tar-in \
@@ -178,12 +180,14 @@ bin_SCRIPTS = virt-copy-in virt-copy-out virt-tar-in virt-tar-out
 
 man_MANS = \
 	guestfish.1 \
+	libguestfs-tools.conf.5 \
 	virt-copy-in.1 \
 	virt-copy-out.1 \
 	virt-tar-in.1 \
 	virt-tar-out.1
 noinst_DATA = \
 	$(top_builddir)/html/guestfish.1.html \
+	$(top_builddir)/html/libguestfs-tools.conf.5.html \
 	$(top_builddir)/html/virt-copy-in.1.html \
 	$(top_builddir)/html/virt-copy-out.1.html \
 	$(top_builddir)/html/virt-tar-in.1.html \
@@ -202,6 +206,17 @@ stamp-guestfish.pod: guestfish.pod guestfish-actions.pod guestfish-commands.pod
 	  $<
 	touch $@
 
+libguestfs-tools.conf.5 $(top_builddir)/html/libguestfs-tools.conf.5.html: stamp-libguestfs-tools.conf.pod
+
+stamp-libguestfs-tools.conf.pod: libguestfs-tools.conf.pod
+	$(PODWRAPPER) \
+	  --section 5 \
+	  --man libguestfs-tools.conf.5 \
+	  --html $(top_builddir)/html/libguestfs-tools.conf.5.html \
+	  --license GPLv2+ \
+	  $<
+	touch $@
+
 virt-copy-in.1 $(top_builddir)/html/virt-copy-in.1.html: stamp-virt-copy-in.pod
 
 stamp-virt-copy-in.pod: virt-copy-in.pod
diff --git a/fish/guestfish.pod b/fish/guestfish.pod
index 2ecc058..c19fe6c 100644
--- a/fish/guestfish.pod
+++ b/fish/guestfish.pod
@@ -1495,7 +1495,7 @@ See L</LIBGUESTFS_CACHEDIR>, L</LIBGUESTFS_TMPDIR>.
 This configuration file controls the default read-only or read-write
 mode (I<--ro> or I<--rw>).
 
-See L</OPENING DISKS FOR READ AND WRITE>.
+See L<libguestfs-tools.conf(5)>.
 
 =item $HOME/.guestfish
 
@@ -1567,6 +1567,7 @@ L<virt-tar(1)>,
 L<virt-tar-in(1)>,
 L<virt-tar-out(1)>,
 L<virt-win-reg(1)>,
+L<libguestfs-tools.conf(5)>,
 L<display(1)>,
 L<hexedit(1)>,
 L<supermin-helper(8)>.
diff --git a/fish/libguestfs-tools.conf b/fish/libguestfs-tools.conf
index 7e60468..898a8de 100644
--- a/fish/libguestfs-tools.conf
+++ b/fish/libguestfs-tools.conf
@@ -1,21 +1,7 @@
 # /etc/libguestfs-tools.conf or .libguestfs-tools.rc
 #
-# This configuration file changes the defaults for the following programs:
-#   * guestfish
-#   * guestmount
-#   * virt-rescue
-# For more information on these programs, read the manual pages
-# (guestfish(1) etc).
+# See libguestfs-tools.conf(5) man page for documentation.
 #
-# /etc/libguestfs-tools.conf is the global configuration file for all
-# of the above programs.  Local users can override the global
-# configuration by copying this file into '.libguestfs-tools.rc' in
-# their home directory and modifying it accordingly.
-#
-# This file is parsed by the libconfig library.  For more information
-# about the format, see
-# http://www.hyperrealm.com/libconfig/libconfig_manual.html
-
 # Uncomment the following line to make guestfish, guestmount,
 # virt-rescue be read-only by default (as if the --ro flag was given).
 # If it is commented out then the default is read-write.  Note that
diff --git a/fish/libguestfs-tools.conf.pod b/fish/libguestfs-tools.conf.pod
new file mode 100644
index 0000000..0c1817a
--- /dev/null
+++ b/fish/libguestfs-tools.conf.pod
@@ -0,0 +1,70 @@
+=encoding utf8
+
+=head1 NAME
+
+/etc/libguestfs-tools.conf - configuration file for guestfish, guestmount, virt-rescue
+
+=head1 SYNOPSIS
+
+ /etc/libguestfs-tools.conf
+
+ $HOME/.libguestfs-tools.rc
+
+=head1 DESCRIPTION
+
+C</etc/libguestfs-tools.conf> or C<$HOME/.libguestfs-tools.rc> changes
+the defaults for the following programs only:
+
+=over 4
+
+=item *
+
+L<guestfish(1)>
+
+=item *
+
+L<guestmount(1)>
+
+=item *
+
+L<virt-rescue(1)>
+
+=back
+
+There is currently only one setting which is controlled by this
+file.  Adding (or uncommenting):
+
+ read_only = true;
+
+changes these programs so they act as if the I<--ro> flag was given on
+the command line.  You can use this to make the programs safe against
+accidental modification of a live guest (users would have to
+explicitly add the I<--rw> flag to modify guests).  This is not the
+default because it is not backwards compatible.
+See also L<guestfish(1)/OPENING DISKS FOR READ AND WRITE>.
+
+Note that B<the semicolon is required>.
+
+C</etc/libguestfs-tools.conf> is the global configuration file for all
+of the above programs.  Local users can override the global
+configuration by copying this file into C<.libguestfs-tools.rc> in
+their home directory and modifying it accordingly.
+
+This file is parsed by the libconfig library.  For more information
+about the format, see:
+L<http://www.hyperrealm.com/libconfig/libconfig_manual.html>
+
+=head1 SEE ALSO
+
+L<guestfish(1)/OPENING DISKS FOR READ AND WRITE>,
+L<guestmount(1)>,
+L<virt-rescue(1)>,
+L<http://libguestfs.org/>.
+
+=head1 AUTHORS
+
+Richard W.M. Jones (C<rjones at redhat dot com>)
+
+=head1 COPYRIGHT
+
+Copyright (C) 2011-2013 Red Hat Inc.
diff --git a/fuse/guestmount.pod b/fuse/guestmount.pod
index b9e93de..42e8579 100644
--- a/fuse/guestmount.pod
+++ b/fuse/guestmount.pod
@@ -394,7 +394,7 @@ This also stops the daemon from forking into the background
 This configuration file controls the default read-only or read-write
 mode (I<--ro> or I<--rw>).
 
-See L<guestfish(1)/OPENING DISKS FOR READ AND WRITE>.
+See L<libguestfs-tools.conf(5)>.
 
 =back
 
@@ -412,6 +412,7 @@ L<virt-inspector(1)>,
 L<virt-cat(1)>,
 L<virt-edit(1)>,
 L<virt-tar(1)>,
+L<libguestfs-tools.conf(5)>,
 L<guestfs(3)/MOUNT LOCAL>,
 L<http://libguestfs.org/>,
 L<http://fuse.sf.net/>.
diff --git a/po-docs/ja/Makefile.am b/po-docs/ja/Makefile.am
index 0b1b10f..217dcd4 100644
--- a/po-docs/ja/Makefile.am
+++ b/po-docs/ja/Makefile.am
@@ -23,7 +23,7 @@ include $(top_srcdir)/subdir-rules.mk
 
 LINGUA = $(shell basename -- `pwd`)
 
-CLEANFILES = *.1 *.3 stamp-update-po
+CLEANFILES = *.1 *.3 *.5 stamp-update-po
 
 MANPAGES = \
 	guestfish.1 \
@@ -46,6 +46,7 @@ MANPAGES = \
 	guestunmount.1 \
 	libguestfs-make-fixed-appliance.1 \
 	libguestfs-test-tool.1 \
+	libguestfs-tools.conf.5 \
 	virt-alignment-scan.1 \
 	virt-cat.1 \
 	virt-copy-in.1 \
@@ -122,6 +123,13 @@ virt-sysprep.1: virt-sysprep.pod sysprep-extra-options.pod sysprep-operations.po
 	  --section 3 \
 	  $<
 
+%.5: %.pod
+	$(PODWRAPPER) \
+	  --no-strict-checks \
+	  --man $@ \
+	  --section 5 \
+	  $<
+
 %.8: %.pod
 	$(PODWRAPPER) \
 	  --no-strict-checks \
@@ -149,3 +157,5 @@ install-data-hook:
 	$(INSTALL) -m 0644 *.1 $(DESTDIR)$(mandir)/$(LINGUA)/man1
 	$(MKDIR_P) $(DESTDIR)$(mandir)/$(LINGUA)/man3
 	$(INSTALL) -m 0644 *.3 $(DESTDIR)$(mandir)/$(LINGUA)/man3
+	$(MKDIR_P) $(DESTDIR)$(mandir)/$(LINGUA)/man5
+	$(INSTALL) -m 0644 *.5 $(DESTDIR)$(mandir)/$(LINGUA)/man5
diff --git a/po-docs/podfiles b/po-docs/podfiles
index 3347554..629a6b0 100644
--- a/po-docs/podfiles
+++ b/po-docs/podfiles
@@ -16,6 +16,7 @@
 ../fish/guestfish-commands.pod
 ../fish/guestfish-prepopts.pod
 ../fish/guestfish.pod
+../fish/libguestfs-tools.conf.pod
 ../fish/virt-copy-in.pod
 ../fish/virt-copy-out.pod
 ../fish/virt-tar-in.pod
diff --git a/po-docs/uk/Makefile.am b/po-docs/uk/Makefile.am
index 0b1b10f..217dcd4 100644
--- a/po-docs/uk/Makefile.am
+++ b/po-docs/uk/Makefile.am
@@ -23,7 +23,7 @@ include $(top_srcdir)/subdir-rules.mk
 
 LINGUA = $(shell basename -- `pwd`)
 
-CLEANFILES = *.1 *.3 stamp-update-po
+CLEANFILES = *.1 *.3 *.5 stamp-update-po
 
 MANPAGES = \
 	guestfish.1 \
@@ -46,6 +46,7 @@ MANPAGES = \
 	guestunmount.1 \
 	libguestfs-make-fixed-appliance.1 \
 	libguestfs-test-tool.1 \
+	libguestfs-tools.conf.5 \
 	virt-alignment-scan.1 \
 	virt-cat.1 \
 	virt-copy-in.1 \
@@ -122,6 +123,13 @@ virt-sysprep.1: virt-sysprep.pod sysprep-extra-options.pod sysprep-operations.po
 	  --section 3 \
 	  $<
 
+%.5: %.pod
+	$(PODWRAPPER) \
+	  --no-strict-checks \
+	  --man $@ \
+	  --section 5 \
+	  $<
+
 %.8: %.pod
 	$(PODWRAPPER) \
 	  --no-strict-checks \
@@ -149,3 +157,5 @@ install-data-hook:
 	$(INSTALL) -m 0644 *.1 $(DESTDIR)$(mandir)/$(LINGUA)/man1
 	$(MKDIR_P) $(DESTDIR)$(mandir)/$(LINGUA)/man3
 	$(INSTALL) -m 0644 *.3 $(DESTDIR)$(mandir)/$(LINGUA)/man3
+	$(MKDIR_P) $(DESTDIR)$(mandir)/$(LINGUA)/man5
+	$(INSTALL) -m 0644 *.5 $(DESTDIR)$(mandir)/$(LINGUA)/man5
diff --git a/rescue/virt-rescue.pod b/rescue/virt-rescue.pod
index 9484ad5..7b77f97 100755
--- a/rescue/virt-rescue.pod
+++ b/rescue/virt-rescue.pod
@@ -410,7 +410,7 @@ manual page L<sh(1)> for details.
 This configuration file controls the default read-only or read-write
 mode (I<--ro> or I<--rw>).
 
-See L<guestfish(1)/OPENING DISKS FOR READ AND WRITE>.
+See L<libguestfs-tools.conf(5)>.
 
 =back
 
@@ -421,6 +421,7 @@ L<guestfish(1)>,
 L<virt-cat(1)>,
 L<virt-edit(1)>,
 L<virt-filesystems(1)>,
+L<libguestfs-tools.conf(5)>,
 L<http://libguestfs.org/>.
 
 =head1 AUTHOR
-- 
1.8.3.1