Update release date.
[aox:aox.git] / 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