doc/recorder.man

   1 .\" Copyright 2009 The Archiveopteryx Developers <info@aox.org>
   2 .TH recorder 8 2009-07-13 aox.org "Archiveopteryx Documentation"
   3 .SH NAME
   4 recorder - IMAP connection recorder
   5 .SH SYNOPSIS
   6 .B $SBINDIR/recorder srcport address destport file
   7 .SH DESCRIPTION
   8 .nh
   9 .PP
  10 The
  11 .B recorder
  12 program relays data between an IMAP client and server, and records the
  13 session in a format which allows the Archiveopteryx developers to replay
  14 and analyse it later.
  15 .PP
  16 If you have problems getting
  17 .BR archiveopteryx (8)
  18 to work with a particular IMAP client, you can make the client connect
  19 to the
  20 .BR recorder ,
  21 instead of directly to
  22 .BR imapd ,
  23 and
  24 .B recorder
  25 will produce a transcript of the IMAP session. If the client opens more
  26 than one connection,
  27 .B recorder
  28 stores more than one file.
  29 .PP
  30 The file format is pure ASCII and can be edited. We suggest that you
  31 edit out your password, then send the rest to info@aox.org and we may
  32 be able to find out what's happening.
  33 .PP
  34 We have debug tools that can replay the connection, so we can fix any
  35 bugs on the server's side. In some cases, we can also add the file to
  36 our regression tests, so we can be sure that new versions of
  37 .BR archiveopteryx (8)
  38 do not have the same error.
  39 .SH EXAMPLE
  40 To intercept and record traffic to the IMAP server
  41 on 192.0.2.17 and place a record of the connections in files called
  42 .I /tmp/bugreport*
  43 you can do the following:
  44 .SS "Disable TLS"
  45 .PP
  46 .B recorder
  47 does not work when TLS is being used. (To TLS, a tool like
  48 .B recorder
  49 looks like a man-in-the-middle attack.)
  50 .PP
  51 To disable TLS, set the variable
  52 .I use-tls
  53 to
  54 .I disabled
  55 in
  56 .I $CONFIGDIR/archiveopteryx.conf
  57 (see the
  58 .BR archiveopteryx.conf (5)
  59 man page for more information.)
  60 .SS "Restart Archiveopteryx"
  61 The change to
  62 .I use-tls
  63 only takes effect when you restart Archiveopteryx, e.g. by issuing the
  64 following command:
  65 .IP
  66 $LIBDIR/archiveopteryx restart
  67 .SS "Start recorder"
  68 To make recorder listen on port 1430 and forward connections
  69 to the real server on port 143:
  70 .IP
  71 $SBINDIR/recorder 1430 192.0.2.17 143 /tmp/bugreport
  72 .SS "Connect to recorder"
  73 With the IMAP client, you connect to port 1430 on this host instead of
  74 the real server, and work as usual. Please don't do much more than is
  75 necessary to reproduce the problem, because it makes the bugreport
  76 files grow very large.
  77 .IP Stop
  78 Just hit Control-C to stop
  79 .B recorder
  80 when you're done. The files called
  81 .I /tmp/bugreport*
  82 contain the IMAP session transcripts.
  83 .IP "Remove passwords"
  84 Please edit the files to remove any passwords or other confidential
  85 data. If you can, don't change the number of words or bytes. It's best
  86 to change all the letters in passwords and confidential words to 'x'.
  87 .PP
  88 That's it. Now you can send an excellent bug report to info@aox.org.
  89 .SH AUTHOR
  90 The Archiveopteryx Developers, info@aox.org.
  91 .SH VERSION
  92 This man page covers Archiveopteryx version 3.1.2, released 2009-07-13,
  93 http://www.archiveopteryx.org/3.1.2
  94 .SH SEE ALSO
  95 .BR archiveopteryx (8),
  96 .BR archiveopteryx.conf (5),
  97 .BR deliver (8),
  98 .BR logd (8),
  99 .BR tlsproxy (8),
 100 http://www.archiveopteryx.org