-
Notifications
You must be signed in to change notification settings - Fork 23
/
issues.html
140 lines (128 loc) · 7.22 KB
/
issues.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
<!DOCTYPE html>
<html>
<head>
<title>Profanity, a console based XMPP client - Reporting issues</title>
<meta charset="utf-8">
<meta http-equiv="Expires" content="-1">
<meta http-equiv="Pragma" content="no-cache">
<meta http-equiv="Cache-Control" content="no-cache">
<link href="css/profanity.css" type="text/css" rel="stylesheet">
</head>
<body id="article">
<img class="overlay" src="images/profanity_mouth-only.png" alt="Profanity Illustration">
<header>
<h1>
<a href="index.html">
Profani<span class="kern-ty">ty</span>
</a>
</h1>
<h2>Reporting Issues</h2>
</header>
<article id="manual">
<section>
<h3>Contents</h3>
<ul>
<li><a href="#where">Where to report issues</a>
<li><a href="#proflogs">Attaching logs</a>
<li><a href="#config">Attaching configuration files</a>
<li><a href="#backtrace">Getting a backtrace</a>
<ul>
<li><a href="#ulimit">Enabling coredumps</a></li>
<li><a href="#configuredebug">Rebuild in debug mode</a></li>
<li><a href="#viewingbacktrace">Viewing the backtrace</a></li>
<ul>
</ul>
</section>
<section>
<a name="where"></a>
<h3>Where to report issues</h3>
<p>The best place to report issues is at the <a target="_blank"
href="https://github.com/boothj5/profanity/issues">github issue tracker</a>.</p>
<p>Other options are the <a target="_blank"
href="https://lists.posteo.de/listinfo/profanity">mailing list</a>,
<p>The following would be helpful in diagnosing/reproducing the issue if you can possibly supply it:
environment (OS, OS version, window manager, terminal type), profanity release version or commit hash if
from development, XMPP server and/or recipient's XMPP client if the issue only occurs with certain
servers/clients, finally any information about the build configuration and enabled features.</p>
<p>If you cant supply the above information, a simple description will do.</p>
</section>
<section>
<a name="proflogs"></a>
<h3>Attaching logs</h3>
<p>The logs can often help to diagnose an issue. Firstly run Profanity in debug mode to enable full debug
logging:</p>
<pre><code>profanity -l DEBUG</code></pre>
<p>Then recreate the issue and attach the log (or a useful section of it) found in:</p>
<pre><code>$XDG_DATA_HOME/profanity/logs/profanity.log</code></pre>
<p>Which on most systems is:</p>
<pre><code>~/.local/share/profanity/logs/profanity.log</pre></code>
<p>Remember to remove or obfuscate any private information in the logs. In particular check for credentials
in connection logging. For example the auth mechanism PLAIN sends the credentials as a base64 string
which can be easily reversed to get your username and password, e.g.:</p>
<pre><code>12/12/2014 14:22:01: conn: DBG: SENT: <auth mechanism="PLAIN" xmlns="urn:ietf:params:xml:ns:xmpp-sasl"><b>AG9saXZlci5tdWVoc2FtAE5oYTEyMDhnIw==</b></auth></code></pre>
</section>
<section>
<a name="config"></a>
<h3>Attaching configuration files</h3>
<p>Some issues are only reproducible using certain configuration options, so attaching your config can also
help. Profanity stores its core config in:</p>
<pre><code>$XDG_CONFIG_HOME/profanity/profrc</code></pre>
<p>Which on most systems is:</p>
<pre><code>~/.config/profanity/profrc</pre></code>
<p>Account specific configuration is specified in:</p>
<pre><code>$XDG_DATA_HOME/profanity/accounts</code></pre>
<p>Which on most systems is:</p>
<pre><code>~/.local/share/profanity/accounts</pre></code>
<p>Remember to remove or obfuscate any usernames/passwords from the configuration before sending, for
example, account configuration will include your password if you have set one using the <a
href="reference.html#account">/account</a> command.</p>
</section>
<section>
<a name="backtrace"></a>
<h3>Getting a backtrace</h3>
<p>Segfaults and crashes usually result in a coredump which can be useful in debugging the problem. If you
have the time, the following instructions should help when attaching a backtrace from a crash.</p>
<a name="ulimit"></a>
<h4>Enabling coredumps</h4>
<p>The following command will enable coredumps of unlimited size to be generated in the current terminal
session:</p>
<pre><code>ulimit -c unlimited</code></pre>
<p>If you prefer to set a limit, the argument is in Kilobytes, for example to allow coredumps of up to
100MB:</p>
<pre><code>ulimit -c 102400</code></pre>
<p>Add the command to your <code>~/.bashrc</code> or equivalent to enable coredumps for all terminal
sessions.</p>
<hr>
<a name="configuredebug"></a>
<h4>Rebuild in debug mode</h4>
<p>Profanity needs to be rebuilt from source to enable more useful information in the coredump.</p>
<p>In the source folder (where you extracted the download, or checked out from git) run the following:</p>
<pre><code>./bootstrap.sh
./configure-debug # calls ./configure with debug options
make clean
make</code></pre>
<p>This will only build an executable in the source folder and will not overwrite your system installed
version. To run the newly built version, in the source folder run:</p>
<pre><code>./profanity</code></pre>
<p>Note, if you installed from Homebrew on OSX it is recommended to clone and build from github (checking
out the relevant release tag) using the above steps, unless you are happy with editing and reinstalling
brew formula.</p>
<hr>
<a name="viewingbacktrace"></a>
<h4>Viewing the backtrace</h4>
<p>On Linux, you will need the GDB debugger installed for your distribution.</p>
<p>The coredump will be created in the folder in which you built and ran profanity, firstly start GDB
pointing to profanity and the coredump:</p>
<pre><code>gdb ./profanity core</code></pre>
<p>To view the backtrace in GDB:</p>
<pre><code>bt</code></pre>
<p>On OSX, the coredump can be found somewhere in the system console (usually in
Applications->Utilities->Console in the finder). It should be named with "profanity" and the date and
time of the crash.</p>
</section>
</article>
<footer>
<p class="matty">site designed by <a href="http://www.matthewbalaam.co.uk">Matthew Balaam</a></p>
</footer>
</body>
</html>