isakmpd(8) man page: clarify IKE packet capture file

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

isakmpd(8) man page: clarify IKE packet capture file

Lawrence Teo-5
isakmpd(8)'s -L command-line option enables IKE packet capture. It is
documented on the isakmpd(8) man page as follows:

  -L   Enable IKE packet capture.  When this option is given, isakmpd
       will capture to file an unencrypted copy of the negotiation
       packets it is sending and receiving. This file can later be read
       by tcpdump(8) and other utilities using pcap(3).

The documentation is currently not clear exactly which file isakmpd
will use to log the packet captures. The correct file *is* listed in
the FILES section (it is /var/run/isakmpd.pcap); however, I think it
would be helpful to mention that file in the description of -L itself,
so that the reader would not have to hunt for it throughout the entire
man page.

Similarly, the "p on/off" FIFO commands to enable IKE packet capture
are documented as follows:

  p on[=<path>]
  p off   Enable or disable cleartext IKE packet capture.
          When enabling, optionally specify which file isakmpd should
          capture the packets to.

Again, the default file is not mentioned. What is also not documented
is, if an alternate file is specified via "p on=/path/to/altfile", its
path must begin with /var/run (I found out the hard way :)).

The following diff improves the documentation by specifying the default
packet capture file in the text for -L itself, and also documents the
restriction about the alternate file path for the "p on" FIFO command
(borrowing some text from the -l option).

Any thoughts or comments?

Lawrence


Index: isakmpd.8
===================================================================
RCS file: /cvs/src/sbin/isakmpd/isakmpd.8,v
retrieving revision 1.107
diff -u -p -r1.107 isakmpd.8
--- isakmpd.8 7 Jun 2010 08:38:09 -0000 1.107
+++ isakmpd.8 5 Jun 2011 02:09:21 -0000
@@ -249,7 +249,9 @@ or
 Enable IKE packet capture.
 When this option is given,
 .Nm
-will capture to file an unencrypted copy of the negotiation packets it
+will capture to
+.Pa /var/run/isakmpd.pcap
+an unencrypted copy of the negotiation packets it
 is sending and receiving.
 This file can later be read by
 .Xr tcpdump 8
@@ -469,9 +471,12 @@ In passive mode no packets are sent to p
 .Xc
 .It Ic p off
 Enable or disable cleartext IKE packet capture.
-When enabling, optionally specify which file
-.Nm
-should capture the packets to.
+When enabling, packets are captured to
+.Pa /var/run/isakmpd.pcap ;
+optionally, an alternate file can be specified but
+note that only paths beginning with
+.Pa /var/run
+are allowed.
 .Pp
 .It Ic Q
 Cleanly shutdown the daemon, as when sent a

Reply | Threaded
Open this post in threaded view
|

Re: isakmpd(8) man page: clarify IKE packet capture file

Mitja Muženič
For what it's worth, I'd like to see this mentioned, not necessarly in those
exact words though.

How about " optionally, an alternate file inside /var/run/ can be
specified." ?


Mitja

> -----Original Message-----
> From: [hidden email] [mailto:[hidden email]] On Behalf Of
> Lawrence Teo
> Sent: Sunday, June 05, 2011 4:20 AM
> To: [hidden email]
> Subject: isakmpd(8) man page: clarify IKE packet capture file
>
> isakmpd(8)'s -L command-line option enables IKE packet capture. It is
> documented on the isakmpd(8) man page as follows:
>
>   -L   Enable IKE packet capture.  When this option is given, isakmpd
>        will capture to file an unencrypted copy of the negotiation
>        packets it is sending and receiving. This file can later be read
>        by tcpdump(8) and other utilities using pcap(3).
>
> The documentation is currently not clear exactly which file isakmpd
> will use to log the packet captures. The correct file *is* listed in
> the FILES section (it is /var/run/isakmpd.pcap); however, I think it
> would be helpful to mention that file in the description of -L itself,
> so that the reader would not have to hunt for it throughout the entire
> man page.
>
> Similarly, the "p on/off" FIFO commands to enable IKE packet capture
> are documented as follows:
>
>   p on[=<path>]
>   p off   Enable or disable cleartext IKE packet capture.
>           When enabling, optionally specify which file isakmpd should
>           capture the packets to.
>
> Again, the default file is not mentioned. What is also not documented
> is, if an alternate file is specified via "p on=/path/to/altfile", its
> path must begin with /var/run (I found out the hard way :)).
>
> The following diff improves the documentation by specifying the default
> packet capture file in the text for -L itself, and also documents the
> restriction about the alternate file path for the "p on" FIFO command
> (borrowing some text from the -l option).
>
> Any thoughts or comments?
>
> Lawrence
>
>
> Index: isakmpd.8
> ===================================================================
> RCS file: /cvs/src/sbin/isakmpd/isakmpd.8,v
> retrieving revision 1.107
> diff -u -p -r1.107 isakmpd.8
> --- isakmpd.8 7 Jun 2010 08:38:09 -0000 1.107
> +++ isakmpd.8 5 Jun 2011 02:09:21 -0000
> @@ -249,7 +249,9 @@ or
>  Enable IKE packet capture.
>  When this option is given,
>  .Nm
> -will capture to file an unencrypted copy of the negotiation packets it
> +will capture to
> +.Pa /var/run/isakmpd.pcap
> +an unencrypted copy of the negotiation packets it
>  is sending and receiving.
>  This file can later be read by
>  .Xr tcpdump 8
> @@ -469,9 +471,12 @@ In passive mode no packets are sent to p
>  .Xc
>  .It Ic p off
>  Enable or disable cleartext IKE packet capture.
> -When enabling, optionally specify which file
> -.Nm
> -should capture the packets to.
> +When enabling, packets are captured to
> +.Pa /var/run/isakmpd.pcap ;
> +optionally, an alternate file can be specified but
> +note that only paths beginning with
> +.Pa /var/run
> +are allowed.
>  .Pp
>  .It Ic Q
>  Cleanly shutdown the daemon, as when sent a

Reply | Threaded
Open this post in threaded view
|

Re: isakmpd(8) man page: clarify IKE packet capture file

Jason McIntyre
In reply to this post by Lawrence Teo-5
On Sat, Jun 04, 2011 at 10:19:49PM -0400, Lawrence Teo wrote:

> isakmpd(8)'s -L command-line option enables IKE packet capture. It is
> documented on the isakmpd(8) man page as follows:
>
>   -L   Enable IKE packet capture.  When this option is given, isakmpd
>        will capture to file an unencrypted copy of the negotiation
>        packets it is sending and receiving. This file can later be read
>        by tcpdump(8) and other utilities using pcap(3).
>
> The documentation is currently not clear exactly which file isakmpd
> will use to log the packet captures. The correct file *is* listed in
> the FILES section (it is /var/run/isakmpd.pcap); however, I think it
> would be helpful to mention that file in the description of -L itself,
> so that the reader would not have to hunt for it throughout the entire
> man page.
>
> Similarly, the "p on/off" FIFO commands to enable IKE packet capture
> are documented as follows:
>
>   p on[=<path>]
>   p off   Enable or disable cleartext IKE packet capture.
>           When enabling, optionally specify which file isakmpd should
>           capture the packets to.
>
> Again, the default file is not mentioned. What is also not documented
> is, if an alternate file is specified via "p on=/path/to/altfile", its
> path must begin with /var/run (I found out the hard way :)).
>
> The following diff improves the documentation by specifying the default
> packet capture file in the text for -L itself, and also documents the
> restriction about the alternate file path for the "p on" FIFO command
> (borrowing some text from the -l option).
>
> Any thoughts or comments?
>
> Lawrence
>

how very trendy to have two options do the same thing (-L/-l). note also
the irony in being able to issue a "p off" to isakmpd.

anyway, i'd like to offer the following tweaked version of your diff.
it's a little simpler.

jmc

Index: isakmpd.8
===================================================================
RCS file: /cvs/src/sbin/isakmpd/isakmpd.8,v
retrieving revision 1.107
diff -u -r1.107 isakmpd.8
--- isakmpd.8 7 Jun 2010 08:38:09 -0000 1.107
+++ isakmpd.8 5 Jun 2011 07:42:39 -0000
@@ -249,9 +249,10 @@
 Enable IKE packet capture.
 When this option is given,
 .Nm
-will capture to file an unencrypted copy of the negotiation packets it
-is sending and receiving.
-This file can later be read by
+will write an unencrypted copy of the negotiation packets it
+is sending and receiving to the file
+.Pa /var/run/isakmpd.pcap ,
+which can later be read by
 .Xr tcpdump 8
 and other utilities using
 .Xr pcap 3 .
@@ -471,7 +472,12 @@
 Enable or disable cleartext IKE packet capture.
 When enabling, optionally specify which file
 .Nm
-should capture the packets to.
+should capture the packets to
+(the default is
+.Pa /var/run/isakmpd.pcap ) .
+Note that only paths beginning with
+.Pa /var/run
+are allowed.
 .Pp
 .It Ic Q
 Cleanly shutdown the daemon, as when sent a

Reply | Threaded
Open this post in threaded view
|

Re: isakmpd(8) man page: clarify IKE packet capture file

Lawrence Teo-5
On Sun, Jun 05, 2011 at 08:45:33AM +0100, Jason McIntyre wrote:

> On Sat, Jun 04, 2011 at 10:19:49PM -0400, Lawrence Teo wrote:
> > isakmpd(8)'s -L command-line option enables IKE packet capture. It is
> > documented on the isakmpd(8) man page as follows:
> >
> >   -L   Enable IKE packet capture.  When this option is given, isakmpd
> >        will capture to file an unencrypted copy of the negotiation
> >        packets it is sending and receiving. This file can later be read
> >        by tcpdump(8) and other utilities using pcap(3).
> >
> > The documentation is currently not clear exactly which file isakmpd
> > will use to log the packet captures. The correct file *is* listed in
> > the FILES section (it is /var/run/isakmpd.pcap); however, I think it
> > would be helpful to mention that file in the description of -L itself,
> > so that the reader would not have to hunt for it throughout the entire
> > man page.
> >
> > Similarly, the "p on/off" FIFO commands to enable IKE packet capture
> > are documented as follows:
> >
> >   p on[=<path>]
> >   p off   Enable or disable cleartext IKE packet capture.
> >           When enabling, optionally specify which file isakmpd should
> >           capture the packets to.
> >
> > Again, the default file is not mentioned. What is also not documented
> > is, if an alternate file is specified via "p on=/path/to/altfile", its
> > path must begin with /var/run (I found out the hard way :)).
> >
> > The following diff improves the documentation by specifying the default
> > packet capture file in the text for -L itself, and also documents the
> > restriction about the alternate file path for the "p on" FIFO command
> > (borrowing some text from the -l option).
> >
> > Any thoughts or comments?
> >
> > Lawrence
> >
>
> how very trendy to have two options do the same thing (-L/-l). note also
> the irony in being able to issue a "p off" to isakmpd.
>
> anyway, i'd like to offer the following tweaked version of your diff.
> it's a little simpler.

Jason,

Thank you for your feedback. I think your tweak looks great, where it
definitely makes the text simpler and more readable.

Thanks,
Lawrence

Reply | Threaded
Open this post in threaded view
|

Re: isakmpd(8) man page: clarify IKE packet capture file

Jason McIntyre
On Sun, Jun 05, 2011 at 02:23:21PM -0400, Lawrence Teo wrote:
>
> Thank you for your feedback. I think your tweak looks great, where it
> definitely makes the text simpler and more readable.
>

ok, now committed. thanks for the diff.
jmc