Add doc/revdep-pax.pod and remove EI_PAX docs from doc/paxctl*

9 files changed, 379 insertions, 92 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index f599022..aa24304 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1 +1 @@
-dist_man_MANS = fix-gnustack.1 paxctl-ng.1
+dist_man_MANS = fix-gnustack.1 paxctl-ng.1 revdep-pax.1
diff --git a/doc/fix-gnustack.1 b/doc/fix-gnustack.1
index 7602e19..2c813c6 100644
--- a/doc/fix-gnustack.1
+++ b/doc/fix-gnustack.1
@@ -135,16 +135,16 @@ fix\-gnustack \- query or clear any ELF GNU_STACK executable flag
 .IX Header "SYNOPSIS"
 \&\fBfix-gnustack\fR \-h
 .PP
-\&\fBfix-gnustack\fR [\-f] ELFfile
+\&\fBfix-gnustack\fR [\-f] \s-1ELF\s0
 .SH "DESCRIPTION"
 .IX Header "DESCRIPTION"
 \&\fBfix-gnustack\fR scans the program headers of an \s-1ELF\s0 binary or shared
-object library and reports if it has a \s-1GNU_STACK\s0 entry and if it is
+object library, reports if it has a \s-1GNU_STACK\s0 entry and if it is
 marked both writeable and executable.  On PaX hardened kernels where
 memory protection (\s-1MPROTECT\s0) is enforced, execution of binaries with
-\&\s-1WX\s0 marked \s-1GNU_STACKS\s0, or of binaries linking against libraries with
-\&\s-1WX\s0 makred \s-1GNU_STACKS\s0, is terminated by the kernel.  When \fBfix-gnustack\fR
-is called without the \fB\-f\fR option on an ELFfile, it simply reports the
+\&\s-1GNU_STACKS\s0 marked \s-1WX\s0, or execution of binaries linking against libraries
+with \s-1GNU_STACKS\s0 marked \s-1WX\s0, is terminated by the kernel.  When \fBfix-gnustack\fR
+is called without the \fB\-f\fR option on an \s-1ELF\s0, it simply reports the
 \&\s-1RWX\s0 (read/write/execute) flags on any \s-1GNU_STACK\s0 entry found.  When called
 with \fB\-f\fR, it clears the X flag if a \s-1GNU_STACK\s0 entry is found and it
 has both W and X flags.
@@ -153,9 +153,9 @@ has both W and X flags.
 .IP "\fB\-h\fR" 4
 .IX Item "-h"
 Print out a short help message and exit.
-.IP "[\fB\-f\fR] ELFfile" 4
-.IX Item "[-f] ELFfile"
-\&\*(L"Fix\*(R" the ELFfile, ie, remove the X flag from any \s-1GNU_STACK\s0 entry found
+.IP "[\fB\-f\fR] \s-1ELF\s0" 4
+.IX Item "[-f] ELF"
+\&\*(L"Fix\*(R" the \s-1ELF\s0, ie, remove the X flag from any \s-1GNU_STACK\s0 entry found
 if it has both W and X flags.  When called without, it simply reports
 what flags it found.
 .SH "HOMEPAGE"
diff --git a/doc/fix-gnustack.pod b/doc/fix-gnustack.pod
index 0a715f6..1f01bcc 100644
--- a/doc/fix-gnustack.pod
+++ b/doc/fix-gnustack.pod
@@ -6,17 +6,17 @@ B<fix-gnustack> - query or clear any ELF GNU_STACK executable flag
 
 B<fix-gnustack> -h
 
-B<fix-gnustack> [-f] ELFfile
+B<fix-gnustack> [-f] ELF
 
 =head1 DESCRIPTION
 
 B<fix-gnustack> scans the program headers of an ELF binary or shared
-object library and reports if it has a GNU_STACK entry and if it is
+object library, reports if it has a GNU_STACK entry and if it is
 marked both writeable and executable.  On PaX hardened kernels where
 memory protection (MPROTECT) is enforced, execution of binaries with
-WX marked GNU_STACKS, or of binaries linking against libraries with
-WX makred GNU_STACKS, is terminated by the kernel.  When B<fix-gnustack>
-is called without the B<-f> option on an ELFfile, it simply reports the
+GNU_STACKS marked WX, or execution of binaries linking against libraries
+with GNU_STACKS marked WX, is terminated by the kernel.  When B<fix-gnustack>
+is called without the B<-f> option on an ELF, it simply reports the
 RWX (read/write/execute) flags on any GNU_STACK entry found.  When called
 with B<-f>, it clears the X flag if a GNU_STACK entry is found and it
 has both W and X flags.
@@ -29,9 +29,9 @@ has both W and X flags.
 
 Print out a short help message and exit.
 
-=item [B<-f>] ELFfile
+=item [B<-f>] ELF
 
-"Fix" the ELFfile, ie, remove the X flag from any GNU_STACK entry found
+"Fix" the ELF, ie, remove the X flag from any GNU_STACK entry found
 if it has both W and X flags.  When called without, it simply reports
 what flags it found.
 
diff --git a/doc/make.sh b/doc/make.sh
index a42e166..78bca35 100755
--- a/doc/make.sh
+++ b/doc/make.sh
@@ -20,3 +20,11 @@ pod2man \
  --center="Documentation for elfix" \
  --date="2011-08-18" \
  paxctl-ng.pod > paxctl-ng.1
+
+pod2man \
+ --official \
+ --section="1" \
+ --release="elfix 0.2" \
+ --center="Documentation for elfix" \
+ --date="2011-10-19" \
+ revdep-pax.pod > revdep-pax.1
diff --git a/doc/paxctl-ng-design.txt b/doc/paxctl-ng-design.txt
index 9de06a0..549b38a 100644
--- a/doc/paxctl-ng-design.txt
+++ b/doc/paxctl-ng-design.txt
@@ -3,27 +3,28 @@ INTRODUCTION
 
 Currently there are two ways to perform pax markings, one is by EI_PAX and
 the other by PT_PAX.  The former is a legacy marking which uses bytes 14
-and 15 of the ehdr.e_ident[] field.  These are in a reserved area of the ELF
-header and could be allocated to a different official use by some future
-standard [1].  For this reason, it is undesireable to continue using this
-marking scheme.  The second method introduces a new program header called
-PAX_FLAGS which hosts the markings.  While this avoids hijacking a reserved
-area of an ELF binary, it introduces the problem of pre-compiled binaries
-which do not have a PT_PAX program header.  Binaries compiled on a Gentoo
-system automatically have a PT_PAX header because of patched binutils.  However
-binaries compiled on other systems do not necessarily have such a section.
-This can be remedied by either adding a PT_PAX header or converting a GNU_STACK
-header.  However both of these are problematic.  In the case of self-checking
-elf binaries, adding a PT_PAX header will cause a failure of the check.
-Alternatively, converting a GNU_STACK header can cause the binary to fail
-to execute correctly.
-
-A third possibility is being consider, but it is in its infancy as of this
-writing.  The pax markings can be put in the Extended File Attributes, much
-like selinux labels.  This is not without its difficulties because not all
-filesystems are capable of supporting xattrs.  However, work on making
-filesystems, like tmpfs, and archiving tools, like tar, aware of xattrs
-is maturing and migrating pax markings to xattrs is now a design possibility.
+and 15 of the ehdr.e_ident[] field of an ELF binary.  These are in a reserved
+area of the ELF header and could be allocated to a different official use by some
+future standard [1].   As of glibc commit 04f2902d9fadb2b8221162247412fb2c4667d95e
+on Mar 18 2010, this way of marking  is broken [2] and needs to be deprecated.
+
+The second method introduces a new program header called PAX_FLAGS which hosts
+the markings.  While this avoids hijacking a reserved area of an ELF binary,
+it introduces the problem of pre-compiled binaries which do not have a PT_PAX
+program header.  Binaries compiled on a Gentoo system automatically have a
+PT_PAX header because of patched binutils [3].  However binaries compiled on
+other systems do not necessarily have such a section.  This can be remedied by
+either adding a PT_PAX header or converting a GNU_STACK header.  However both
+of these are problematic.  In the case of self-checking elf binaries, adding
+a PT_PAX header will cause a failure of the check.  Alternatively, converting
+a GNU_STACK header can cause the binary to fail to execute correctly.
+
+Here, we propose a third possibility is being proposed.  The pax markings can
+be put in the Extended File Attributes, much like selinux labels.  This is not
+without its difficulties because not all filesystems are capable of supporting
+xattrs.  However, work on making filesystems, like tmpfs, and archiving tools,
+like tar, aware of xattrs is maturing and migrating pax markings to xattrs is
+now a design possibility [4].  We will call these markings XT_PAX.
 
 
 PURPOSAL
@@ -31,9 +32,11 @@ PURPOSAL
 To avoid ambiguity in Hardened Gentoo and to smooth the transition to a
 future, we propose the following standards to how pax markings are treated:
 
-1) The kernel.  The kernel will be patched to force respect of PT_PAX markings
-first, and only if these are missing, revert to EI_PAX.  If both markings are
-missing, then the kernel will revert to enforcing maximum protection, meaning
+1) The kernel.  All legacy EI_PAX refrences will be removed from the kernel,
+and ehdr.e_ident[] bytes 14 and 15 will not be considered for any PaX decisions.
+The kernel will be patched to force respect of XT_PAX markings first, and only
+if these are missing, revert to PT_PAX.  If both markings are missing, then the
+kernel will revert to enforcing maximum protection, meaning
 
 	PAGEEXEC enabled
 	SEGMEXEC enabled
@@ -41,40 +44,25 @@ missing, then the kernel will revert to enforcing maximum protection, meaning
 	EMUTRAMP disabled
 	RANDMMAP enabled
 
-Once xattr pax markings are introduced, then the kernel will be patched to
-force respect of xattr markings first.  If these are missing, either because
-the file has not been pax marked in their xattr fields, or because the
-filesystem doesn't support xattrs, then the kernel will revert to using
-PT_PAX.  If the PT_PAX header is missing, the kernel will then revert to
-EI_PAX markings, and if even these are missing, it will finaly revert to
-enforcing maximum protection.
-
+Setting the kernel options for PaX will automatically set XATTR support
+on whatever filesystems are configured and support them.
 
 2) Userland utility.  A new userland utility will be required to ensure
-consistency between the two (eventually three) types of pax markings.
-
-If an ELF binary has a PT_PAX header, it will use that for pax markings.
-For consistency, and until standards say otherwise, it will also mark
-the EI_PAX field with the same flags.
-
-If the binary does not have a PT_PAX header, it will not attempt to add
-such a header, nor convert a GNU_STACK header.  Rather, it will only mark
-the EI_PAX fields.
-
-When xattr pax markings are introduced, then the utility will try to add
-the same markings to all three: xattrs, PT_PAX and EI_PAX.  It may fail
-to add the markings to either xattrs and/or PT_PAX for the reasons stated
-above, but at least the markings will be in EI_PAX.
-
+consistency between the two types of pax markings.  It will return the
+XT_PAX markings if found, and only if these are missing, revert to PT_PAX.
 
-3) It is hoped that by the time EI_PAX markings must be deprecated because
-ehdr.e_ident[14] and ehdr.e_ident[15] are allocated to some other official
-purpose, xattr marking will be fully supported and EI_PAX can be dropped
-from both the kernel and the userland utility.
+This utility will not attempt to convert or add any program header to the
+ELF binary.
 
 
 
 REFERENCE
 
 [1] http://refspecs.freestandards.org/elf/
+[2] https://bugs.gentoo.org/show_bug.cgi?id=387459
+[3] As of this writing, PT_PAX support is provided by 
+    patch 63_all_binutils-2.21.1-pt-pax-flags-20110918.patch
+    which can be obtained from the patch bundles found at
+    http://dev.gentoo.org/~vapier/dist/
+[4] https://bugs.gentoo.org/show_bug.cgi?id=382067
 
diff --git a/doc/paxctl-ng.1 b/doc/paxctl-ng.1
index d924e1f..218dde3 100644
--- a/doc/paxctl-ng.1
+++ b/doc/paxctl-ng.1
@@ -130,27 +130,24 @@
 .if n .ad l
 .nh
 .SH "NAME"
-paxctl\-ng \- get or consistently set the pax flags for both EI_PAX and PT_PAX
+paxctl\-ng \- get or set the PaX flags for both PT_PAX and XT_PAX
 .SH "SYNOPSIS"
 .IX Header "SYNOPSIS"
-\&\fBpaxctl-ng\fR [\-h]
-.PP
 \&\fBpaxctl-ng\fR [\-PpEeMmRrXxSs] [\-v] \s-1ELF\s0
 .PP
 \&\fBpaxctl-ng\fR \-Z [\-v] \s-1ELF\s0
 .PP
 \&\fBpaxctl-ng\fR \-z [\-v] \s-1ELF\s0
+.PP
+\&\fBpaxctl-ng\fR [\-h]
 .SH "DESCRIPTION"
 .IX Header "DESCRIPTION"
 \&\fBpaxctl-ng\fR scans the program headers of \s-1ELF\s0 binaries or shared
 .SH "OPTIONS"
 .IX Header "OPTIONS"
-.IP "\fB\-h\fR   Print out a short help message and exit." 4
-.IX Item "-h   Print out a short help message and exit."
-.PD 0
-.IP "" 4
 .IP "\fB\-P\fR or \fB\-p\fR   Enable or disable \s-1PAGEEXEC\s0" 4
 .IX Item "-P or -p   Enable or disable PAGEEXEC"
+.PD 0
 .IP "\fB\-S\fR or \fB\-s\fR   Enable or disable \s-1SEGMEXEC\s0" 4
 .IX Item "-S or -s   Enable or disable SEGMEXEC"
 .IP "\fB\-M\fR or \fB\-m\fR   Enable or disable \s-1MPROTECT\s0" 4
@@ -161,17 +158,19 @@ paxctl\-ng \- get or consistently set the pax flags for both EI_PAX and PT_PAX
 .IX Item "-R or -r   Enable or disable RANDMMAP"
 .IP "\fB\-X\fR or \fB\-x\fR   Enable or disable \s-1RANDEXEC\s0" 4
 .IX Item "-X or -x   Enable or disable RANDEXEC"
+.IP "" 4
 .PD
 If both enabling and disabling flags are set for one item, 
-eg. \-Pp for \s-1PAGEEXEC\s0, then the default setting \- is used is
-for \s-1PT_PAX\s0, while the most secure setting is used for \s-1EI_PAX\s0.
-.IP "\fB\-Z\fR Enable most secure settings (PSMeRX)" 4
-.IX Item "-Z Enable most secure settings (PSMeRX)"
+eg. \-Pp for \s-1PAGEEXEC\s0, then the default setting \- is used.
+.IP "\fB\-Z\fR Set most secure settings (PSMeRX)" 4
+.IX Item "-Z Set most secure settings (PSMeRX)"
 .PD 0
-.IP "\fB\-z\fR Enable default setting (\s-1PT_PAX\s0) or most secure setting (\s-1EI_PAX\s0)" 4
-.IX Item "-z Enable default setting (PT_PAX) or most secure setting (EI_PAX)"
+.IP "\fB\-z\fR Set default setting (\-\-\-\-\-\-)" 4
+.IX Item "-z Set default setting (------)"
 .IP "\fB\-v\fR View the flags" 4
 .IX Item "-v View the flags"
+.IP "\fB\-h\fR Print out a short help message and exit." 4
+.IX Item "-h Print out a short help message and exit."
 .PD
 .SH "HOMEPAGE"
 .IX Header "HOMEPAGE"
diff --git a/doc/paxctl-ng.pod b/doc/paxctl-ng.pod
index db809ab..3dcd7f7 100644
--- a/doc/paxctl-ng.pod
+++ b/doc/paxctl-ng.pod
@@ -1,17 +1,17 @@
 =head1 NAME
 
-B<paxctl-ng> - get or consistently set the pax flags for both EI_PAX and PT_PAX
+B<paxctl-ng> - get or set the PaX flags for both PT_PAX and XT_PAX
 
 =head1 SYNOPSIS
 
-B<paxctl-ng> [-h]
-
 B<paxctl-ng> [-PpEeMmRrXxSs] [-v] ELF
 
 B<paxctl-ng> -Z [-v] ELF
 
 B<paxctl-ng> -z [-v] ELF
 
+B<paxctl-ng> [-h]
+
 =head1 DESCRIPTION
 
 B<paxctl-ng> scans the program headers of ELF binaries or shared
@@ -20,10 +20,6 @@ B<paxctl-ng> scans the program headers of ELF binaries or shared
 
 =over
 
-=item B<-h>   Print out a short help message and exit.
-
-=item
-
 =item B<-P> or B<-p>   Enable or disable PAGEEXEC
 
 =item B<-S> or B<-s>   Enable or disable SEGMEXEC
@@ -36,17 +32,18 @@ B<paxctl-ng> scans the program headers of ELF binaries or shared
 
 =item B<-X> or B<-x>   Enable or disable RANDEXEC
 
+=item
+
 If both enabling and disabling flags are set for one item, 
-eg. -Pp for PAGEEXEC, then the default setting - is used is
-for PT_PAX, while the most secure setting is used for EI_PAX. 
+eg. -Pp for PAGEEXEC, then the default setting - is used.
 
-=item B<-Z> Enable most secure settings (PSMeRX)
+=item B<-Z> Set most secure settings (PSMeRX)
 
-=item B<-z> Enable default setting (PT_PAX) or most secure setting (EI_PAX)
+=item B<-z> Set default setting (------)
 
 =item B<-v> View the flags
 
-
+=item B<-h> Print out a short help message and exit.
 
 =back
 
diff --git a/doc/revdep-pax.1 b/doc/revdep-pax.1
new file mode 100644
index 0000000..944a57b
--- /dev/null
+++ b/doc/revdep-pax.1
@@ -0,0 +1,205 @@
+.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.el \{\
+.    de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "REVDEP-PAX 1"
+.TH REVDEP-PAX 1 "2011-10-19" "elfix 0.2" "Documentation for elfix"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+revdep\-pax \- find mismatching PaX markings between ELF objects and their libraries
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+\&\fBrevdep-pax\fR \-f [\-v]
+.PP
+\&\fBrevdep-pax\fR \-r [\-v]
+.PP
+\&\fBrevdep-pax\fR \-b \s-1OBJECT\s0 [\-mv]
+.PP
+\&\fBrevdep-pax\fR \-s \s-1SONAME\s0 [\-mv]
+.PP
+\&\fBrevdep-pax\fR \-l \s-1LIBRARY\s0 [\-mv]
+.PP
+\&\fBrevdep-pax\fR [\-h]
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\fBrevdep-pax\fR finds mismatching PaX markings between an \s-1ELF\s0 object and the
+libraries that object dynamically links against.  When executing an \s-1ELF\s0 binary
+that links against libraries, the PaX hardened kernel ignores the library
+markings and uses the executable markings for enforcing PaX restrictions.
+It is desireable in some circumstances to migrate back the library markings
+to the binaries.
+.PP
+revdep-pax can do its work by either starting from the object and mapping
+forwards to its libraries, or by starting from a library and mapping
+backwards to all the objects that link against it.  The library can either
+be specified by the \s-1SONAME\s0 as it is reported by \fBldd\fR(1), or by the full
+path to the \s-1LIBRARY\s0 file.  Symbolic links are dereferenced.  The user can
+optionally scan for all forward mappings on the system (\-f), for all reverse
+mappings (\-r), for forward mappings of just one \s-1OBJECT\s0 (\-b), for reverse
+mappings of just one \s-1SONAME\s0 (\-s) or one \s-1LIBRARY\s0 (\-l).  In verbose mode (\-v),
+all mappings are reported, not just mismatching ones, and in mark mode (\-m),
+the user is prompted whether to proceed with marking the found object so
+its PaX flags match its source.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.IP "\fB\-f\fR   Scan the system for all forward mappings" 4
+.IX Item "-f   Scan the system for all forward mappings"
+.PD 0
+.IP "" 4
+.IP "\fB\-r\fR   Scan the system for all reverse mappings" 4
+.IX Item "-r   Scan the system for all reverse mappings"
+.IP "" 4
+.IP "\fB\-b\fR   \s-1OBJECT\s0  Retrieve only the forward mappings for this \s-1ELF\s0 \s-1OBJECT\s0" 4
+.IX Item "-b   OBJECT  Retrieve only the forward mappings for this ELF OBJECT"
+.IP "" 4
+.IP "\fB\-s\fR   \s-1SONAME\s0  Retrieve only the reverse mappings for this \s-1SONAME\s0" 4
+.IX Item "-s   SONAME  Retrieve only the reverse mappings for this SONAME"
+.IP "" 4
+.IP "\fB\-l\fR   \s-1LIBRARY\s0 Retrieve only the reverse mappings for this \s-1LIBRARY\s0" 4
+.IX Item "-l   LIBRARY Retrieve only the reverse mappings for this LIBRARY"
+.IP "" 4
+.IP "\fB\-v\fR   Report all mappings, not just the mismatched ones" 4
+.IX Item "-v   Report all mappings, not just the mismatched ones"
+.IP "" 4
+.IP "\fB\-m\fR   Prompt the user to mark the found object with the PaX flags of the source" 4
+.IX Item "-m   Prompt the user to mark the found object with the PaX flags of the source"
+.IP "" 4
+.IP "\fB\-h\fR   Print out a short help message and exit." 4
+.IX Item "-h   Print out a short help message and exit."
+.PD
+.SH "HOMEPAGE"
+.IX Header "HOMEPAGE"
+http://dev.gentoo.org/~blueness/elfix
+.SH "REPORTING BUGS"
+.IX Header "REPORTING BUGS"
+Please report bugs at http://bugs.gentoo.org.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBscanelf\fR(1), \fBdumpelf\fR(1), \fBpaxctl\fR(1), \fBpspax\fR(1), \fBfix-gnustack\fR(1), \fBldd\fR(1)
+.SH "AUTHORS"
+.IX Header "AUTHORS"
+\&\fBAnthony G. Basile\fR <blueness@gentoo.org>
diff --git a/doc/revdep-pax.pod b/doc/revdep-pax.pod
new file mode 100644
index 0000000..6bb08e8
--- /dev/null
+++ b/doc/revdep-pax.pod
@@ -0,0 +1,90 @@
+=head1 NAME
+
+B<revdep-pax> - find mismatching PaX markings between ELF objects and their libraries
+
+=head1 SYNOPSIS
+
+B<revdep-pax> -f [-v]
+
+B<revdep-pax> -r [-v]
+
+B<revdep-pax> -b OBJECT [-mv]
+
+B<revdep-pax> -s SONAME [-mv]
+
+B<revdep-pax> -l LIBRARY [-mv]
+
+B<revdep-pax> [-h]
+
+=head1 DESCRIPTION
+
+B<revdep-pax> finds mismatching PaX markings between an ELF object and the
+libraries that object dynamically links against.  When executing an ELF binary
+that links against libraries, the PaX hardened kernel ignores the library
+markings and uses the executable markings for enforcing PaX restrictions.
+It is desireable in some circumstances to migrate back the library markings
+to the binaries.  
+
+revdep-pax can do its work by either starting from the object and mapping
+forwards to its libraries, or by starting from a library and mapping
+backwards to all the objects that link against it.  The library can either
+be specified by the SONAME as it is reported by B<ldd>(1), or by the full
+path to the LIBRARY file.  Symbolic links are dereferenced.  The user can
+optionally scan for all forward mappings on the system (-f), for all reverse
+mappings (-r), for forward mappings of just one OBJECT (-b), for reverse
+mappings of just one SONAME (-s) or one LIBRARY (-l).  In verbose mode (-v),
+all mappings are reported, not just mismatching ones, and in mark mode (-m),
+the user is prompted whether to proceed with marking the found object so
+its PaX flags match its source.
+
+=head1 OPTIONS
+
+=over
+
+=item B<-f>   Scan the system for all forward mappings
+
+=item
+
+=item B<-r>   Scan the system for all reverse mappings
+
+=item
+
+=item B<-b>   OBJECT  Retrieve only the forward mappings for this ELF OBJECT
+
+=item
+
+=item B<-s>   SONAME  Retrieve only the reverse mappings for this SONAME
+
+=item
+
+=item B<-l>   LIBRARY Retrieve only the reverse mappings for this LIBRARY
+
+=item
+
+=item B<-v>   Report all mappings, not just the mismatched ones
+
+=item
+
+=item B<-m>   Prompt the user to mark the found object with the PaX flags of the source
+
+=item
+
+=item B<-h>   Print out a short help message and exit.
+
+=back
+
+=head1 HOMEPAGE
+
+http://dev.gentoo.org/~blueness/elfix
+
+=head1 REPORTING BUGS
+
+Please report bugs at http://bugs.gentoo.org.
+
+=head1 SEE ALSO
+
+B<scanelf>(1), B<dumpelf>(1), B<paxctl>(1), B<pspax>(1), B<fix-gnustack>(1), B<ldd>(1)
+
+=head1 AUTHORS
+
+B<Anthony G. Basile> <blueness@gentoo.org>