add examples

diff --git a/doc/cvtsudoers.cat b/doc/cvtsudoers.cat
index 99fcc80cd928bf3176160db8d280e3a9a6387c84..0c4aae238d6267d558e0f05936ecd604e57bf5b1 100644 (file)
--- a/doc/cvtsudoers.cat
+++ b/doc/cvtsudoers.cat
@@ -24,10 +24,10 @@ D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
      -\b-b\bb _\bd_\bn, -\b--\b-b\bba\bas\bse\be=_\bd_\bn
                  The base DN (distinguished name) that will be used when
                  performing LDAP queries.  Typically this is of the form
-                 ou=SUDOers,dc=example,dc=com for the domain example.com.  If
-                 this option is not specified, the value of the SUDOERS_BASE
-                 environment variable will be used instead.  Only necessary
-                 when converting to LDIF format.
+                 ou=SUDOers,dc=-mydomain,dc=com for the domain my-domain.com.
+                 If this option is not specified, the value of the
+                 SUDOERS_BASE environment variable will be used instead.  Only
+                 necessary when converting to LDIF format.
 
      -\b-c\bc, -\b--\b-c\bco\bon\bnf\bfi\big\bg
                  Specify the path to a configuration file.  Defaults to
@@ -61,8 +61,8 @@ D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
                  default when the output _\bf_\bo_\br_\bm_\ba_\bt is JSON or sudoers.
 
      -\b-f\bf _\bo_\bu_\bt_\bp_\bu_\bt_\b__\bf_\bo_\br_\bm_\ba_\bt, -\b--\b-f\bfo\bor\brm\bma\bat\bt=_\bo_\bu_\bt_\bp_\bu_\bt_\b__\bf_\bo_\br_\bm_\ba_\bt
-                 Specify the output format.  The following formats are
-                 supported:
+                 Specify the output format (case-insensitive).  The following
+                 formats are supported:
 
                  JSON      JSON (JavaScript Object Notation) files are usually
                            easier for third-party applications to consume than
@@ -210,6 +210,32 @@ D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
 F\bFI\bIL\bLE\bES\bS
      _\b/_\be_\bt_\bc_\b/_\bc_\bv_\bt_\bs_\bu_\bd_\bo_\be_\br_\bs_\b._\bc_\bo_\bn_\bf      default configuration for cvtsudoers
 
+E\bEX\bXA\bAM\bMP\bPL\bLE\bES\bS
+     Convert _\b/_\be_\bt_\bc_\b/_\bs_\bu_\bd_\bo_\be_\br_\bs to LDIF (LDAP Data Interchange Format) where the
+     _\bl_\bd_\ba_\bp_\b._\bc_\bo_\bn_\bf file uses a _\bs_\bu_\bd_\bo_\be_\br_\bs_\b__\bb_\ba_\bs_\be of my-domain,dc=com, storing the
+     result in _\bs_\bu_\bd_\bo_\be_\br_\bs_\b._\bl_\bd_\bi_\bf:
+
+           $ cvtsudoers -b ou=SUDOers,dc=my-domain,dc=com -o sudoers.ldif \
+                        /etc/sudoers
+
+     Convert _\b/_\be_\bt_\bc_\b/_\bs_\bu_\bd_\bo_\be_\br_\bs to JSON format, storing the result in _\bs_\bu_\bd_\bo_\be_\br_\bs_\b._\bj_\bs_\bo_\bn:
+
+           $ cvtsudoers -f json -o sudoers.json /etc/sudoers
+
+     Parse _\b/_\be_\bt_\bc_\b/_\bs_\bu_\bd_\bo_\be_\br_\bs and display only rules that match user _\ba_\bm_\bb_\br_\bo_\bs_\be on host
+     _\bh_\ba_\bs_\bt_\bu_\br:
+
+           $ cvtsudoers -f sudoers -m user=ambrose,host=hastur /etc/sudoers
+
+     Same as above, but expand aliases and prune out any non-matching users
+     and hosts from the expanded entries.
+
+           $ cvtsudoers -ep -f sudoers -m user=ambrose,host=hastur /etc/sudoers
+
+     Convert _\bs_\bu_\bd_\bo_\be_\br_\bs_\b._\bl_\bd_\bi_\bf from LDIF to traditional _\bs_\bu_\bd_\bo_\be_\br_\bs format:
+
+           $ cvtsudoers -i ldif -f sudoers -o sudoers.new sudoers.ldif
+
 S\bSE\bEE\bE A\bAL\bLS\bSO\bO
      sudoers(4), sudoers.ldap(4), sudo(1m)
 

diff --git a/doc/cvtsudoers.man.in b/doc/cvtsudoers.man.in
index d1dc94f7b820e1cf5dd8fcdd7be3f9b45ee59ebb..f50a2e47817209cb83dbbfc5ab92903f7de698a7 100644 (file)
--- a/doc/cvtsudoers.man.in
+++ b/doc/cvtsudoers.man.in
@@ -61,9 +61,9 @@ The options are as follows:
 The base DN (distinguished name) that will be used when performing
 LDAP queries.
 Typically this is of the form
-\fRou=SUDOers,dc=example,dc=com\fR
+\fRou=SUDOers,dc=-mydomain,dc=com\fR
 for the domain
-\fRexample.com\fR.
+\fRmy-domain.com\fR.
 If this option is not specified, the value of the
 \fRSUDOERS_BASE\fR
 environment variable will be used instead.
@@ -128,7 +128,7 @@ Aliases are preserved by default when the output
 is JSON or sudoers.
 .TP 12n
 \fB\-f\fR \fIoutput_format\fR, \fB\--format\fR=\fIoutput_format\fR
-Specify the output format.
+Specify the output format (case-insensitive).
 The following formats are supported:
 .PP
 .RS 12n
@@ -384,6 +384,67 @@ configuration file.
 .TP 26n
 \fI@sysconfdir@/cvtsudoers.conf\fR
 default configuration for cvtsudoers
+.SH "EXAMPLES"
+Convert
+\fI/etc/sudoers\fR
+to LDIF (LDAP Data Interchange Format) where the
+\fIldap.conf\fR
+file uses a
+\fIsudoers_base\fR
+of my-domain,dc=com, storing the result in
+\fIsudoers.ldif\fR:
+.nf
+.sp
+.RS 6n
+$ cvtsudoers -b ou=SUDOers,dc=my-domain,dc=com -o sudoers.ldif \e
+             /etc/sudoers
+.RE
+.fi
+.PP
+Convert
+\fI/etc/sudoers\fR
+to JSON format, storing the result in
+\fIsudoers.json\fR:
+.nf
+.sp
+.RS 6n
+$ cvtsudoers -f json -o sudoers.json /etc/sudoers
+.RE
+.fi
+.PP
+Parse
+\fI/etc/sudoers\fR
+and display only rules that match user
+\fIambrose\fR
+on host
+\fIhastur\fR:
+.nf
+.sp
+.RS 6n
+$ cvtsudoers -f sudoers -m user=ambrose,host=hastur /etc/sudoers
+.RE
+.fi
+.PP
+Same as above, but expand aliases and prune out any non-matching
+users and hosts from the expanded entries.
+.nf
+.sp
+.RS 6n
+$ cvtsudoers -ep -f sudoers -m user=ambrose,host=hastur /etc/sudoers
+.RE
+.fi
+.PP
+Convert
+\fIsudoers.ldif\fR
+from LDIF to traditional
+\fIsudoers\fR
+format:
+.nf
+.sp
+.RS 6n
+$ cvtsudoers -i ldif -f sudoers -o sudoers.new sudoers.ldif
+.RE
+.fi
 .SH "SEE ALSO"
 sudoers(@mansectform@),
 sudoers.ldap(@mansectform@),

diff --git a/doc/cvtsudoers.mdoc.in b/doc/cvtsudoers.mdoc.in
index 867a3da6ec09433394659a8f317c452e88936960..1ab474e41115507ecf37e4aa26cd4a2bfe30b774 100644 (file)
--- a/doc/cvtsudoers.mdoc.in
+++ b/doc/cvtsudoers.mdoc.in
@@ -58,9 +58,9 @@ The options are as follows:
 The base DN (distinguished name) that will be used when performing
 LDAP queries.
 Typically this is of the form
-.Li ou=SUDOers,dc=example,dc=com
+.Li ou=SUDOers,dc=-mydomain,dc=com
 for the domain
-.Li example.com .
+.Li my-domain.com .
 If this option is not specified, the value of the
 .Ev SUDOERS_BASE
 environment variable will be used instead.
@@ -112,7 +112,7 @@ Aliases are preserved by default when the output
 .Ar format
 is JSON or sudoers.
 .It Fl f Ar output_format , Fl -format Ns = Ns Ar output_format
-Specify the output format.
+Specify the output format (case-insensitive).
 The following formats are supported:
 .Bl -tag -width 8n
 .It JSON
@@ -327,6 +327,52 @@ configuration file.
 .It Pa @sysconfdir@/cvtsudoers.conf
 default configuration for cvtsudoers
 .El
+.Sh EXAMPLES
+Convert
+.Pa /etc/sudoers
+to LDIF (LDAP Data Interchange Format) where the
+.Pa ldap.conf
+file uses a
+.Em sudoers_base
+of my-domain,dc=com, storing the result in
+.Pa sudoers.ldif :
+.Bd -literal -offset indent
+$ cvtsudoers -b ou=SUDOers,dc=my-domain,dc=com -o sudoers.ldif \e
+             /etc/sudoers
+.Ed
+.Pp
+Convert
+.Pa /etc/sudoers
+to JSON format, storing the result in
+.Pa sudoers.json :
+.Bd -literal -offset indent
+$ cvtsudoers -f json -o sudoers.json /etc/sudoers
+.Ed
+.Pp
+Parse
+.Pa /etc/sudoers
+and display only rules that match user
+.Em ambrose
+on host
+.Em hastur :
+.Bd -literal -offset indent
+$ cvtsudoers -f sudoers -m user=ambrose,host=hastur /etc/sudoers
+.Ed
+.Pp
+Same as above, but expand aliases and prune out any non-matching
+users and hosts from the expanded entries.
+.Bd -literal -offset indent
+$ cvtsudoers -ep -f sudoers -m user=ambrose,host=hastur /etc/sudoers
+.Ed
+.Pp
+Convert
+.Pa sudoers.ldif
+from LDIF to traditional
+.Em sudoers
+format:
+.Bd -literal -offset indent
+$ cvtsudoers -i ldif -f sudoers -o sudoers.new sudoers.ldif
+.Ed
 .Sh SEE ALSO
 .Xr sudoers @mansectform@ ,
 .Xr sudoers.ldap @mansectform@ ,