platform docs: updated commands, removed config items that are no longer supported...
[leap_doc.git] / docs / platform / troubleshooting.md
1 @title = 'Troubleshooting Guide'
2 @nav_title = 'Troubleshooting'
3 @toc = true
4
5
6 General
7 =======
8
9 * Please increase verbosity when debugging / filing issues in our issue tracker. You can do this with adding i.e. `-v 5` after the `leap` cmd, i.e. `leap -v 2 deploy`.
10
11 Webapp
12 ======
13
14 Places to look for errors
15 -------------------------
16
17 * `/var/log/apache2/error.log`
18 * `/srv/leap/webapp/log/production.log`
19 * `/var/log/syslog` (watch out for stunnel issues)
20 * `/var/log/leap/*`
21
22 Is haproxy ok ?
23 ---------------
24
25
26     curl -s -X  GET "http://127.0.0.1:4096"
27
28 Is couchdb accessible through stunnel ?
29 ---------------------------------------
30
31 * Depending on how many couch nodes you have, increase the port for every test
32   (see /etc/haproxy/haproxy.cfg for the server/port mapping):
33
34
35     curl -s -X  GET "http://127.0.0.1:4000"
36     curl -s -X  GET "http://127.0.0.1:4001"
37     ...
38
39
40 Check couchdb acl as admin
41 --------------------------
42
43     mkdir /etc/couchdb
44     cat /srv/leap/webapp/config/couchdb.yml.admin  # see username and password
45     echo "machine 127.0.0.1 login admin password <PASSWORD>" > /etc/couchdb/couchdb-admin.netrc
46     chmod 600 /etc/couchdb/couchdb-admin.netrc
47
48     curl -s --netrc-file /etc/couchdb/couchdb-admin.netrc -X GET "http://127.0.0.1:4096"
49     curl -s --netrc-file /etc/couchdb/couchdb-admin.netrc -X GET "http://127.0.0.1:4096/_all_dbs"
50
51 Check couchdb acl as unpriviledged user
52 ---------------------------------------
53
54     cat /srv/leap/webapp/config/couchdb.yml  # see username and password
55     echo "machine 127.0.0.1 login webapp password <PASSWORD>" > /etc/couchdb/couchdb-webapp.netrc
56     chmod 600 /etc/couchdb/couchdb-webapp.netrc
57
58     curl -s --netrc-file /etc/couchdb/couchdb-webapp.netrc -X GET "http://127.0.0.1:4096"
59     curl -s --netrc-file /etc/couchdb/couchdb-webapp.netrc -X GET "http://127.0.0.1:4096/_all_dbs"
60
61
62 Check client config files
63 -------------------------
64
65     https://example.net/provider.json
66     https://example.net/1/config/smtp-service.json
67     https://example.net/1/config/soledad-service.json
68     https://example.net/1/config/eip-service.json
69
70
71 Soledad
72 =======
73
74     /var/log/soledad.log
75
76
77 Couchdb
78 =======
79
80 Places to look for errors
81 -------------------------
82
83 * `/opt/bigcouch/var/log/bigcouch.log`
84 * `/var/log/syslog` (watch out for stunnel issues)
85
86
87
88 Bigcouch membership
89 -------------------
90
91 * All nodes configured for the provider should appear here:
92
93 <pre>
94     curl -s --netrc-file /etc/couchdb/couchdb.netrc -X GET 'http://127.0.0.1:5986/nodes/_all_docs'
95 </pre>
96
97 * All configured nodes should show up under "cluster_nodes", and the ones online and communicating with each other should appear under "all_nodes". This example output shows the configured cluster nodes `couch1.bitmask.net` and `couch2.bitmask.net`, but `couch2.bitmask.net` is currently not accessible from `couch1.bitmask.net`
98
99
100 <pre>
101     curl -s --netrc-file /etc/couchdb/couchdb.netrc 'http://127.0.0.1:5984/_membership'
102     {"all_nodes":["bigcouch@couch1.bitmask.net"],"cluster_nodes":["bigcouch@couch1.bitmask.net","bigcouch@couch2.bitmask.net"]}
103 </pre>
104
105 * Sometimes a `/etc/init.d/bigcouch restart` on all nodes is needed, to register new nodes
106
107 Databases
108 ---------
109
110 * Following output shows all neccessary DBs that should be present. Note that the `user-0123456....` DBs are the data stores for a particular user.
111
112 <pre>
113     curl -s --netrc-file /etc/couchdb/couchdb.netrc -X GET 'http://127.0.0.1:5984/_all_dbs'
114     ["customers","identities","sessions","shared","tickets","tokens","user-0","user-9d34680b01074c75c2ec58c7321f540c","user-9d34680b01074c75c2ec58c7325fb7ff","users"]
115 </pre>
116
117
118
119
120 Design Documents
121 ----------------
122
123 * Is User `_design doc` available ?
124
125
126 <pre>
127     curl -s --netrc-file /etc/couchdb/couchdb.netrc -X  GET "http://127.0.0.1:5984/users/_design/User"
128 </pre>
129
130 Is couchdb cluster backend accessible through stunnel ?
131 -------------------------------------------------------
132
133 * Find out how many connections are set up for the couchdb cluster backend:
134
135 <pre>
136     grep "accept = 127.0.0.1" /etc/stunnel/*
137 </pre>
138
139
140 * Now connect to all of those local endpoints to see if they up. All these tests should return "localhost [127.0.0.1] 4000 (?) open"
141
142 <pre>
143     nc -v 127.0.0.1 4000
144     nc -v 127.0.0.1 4001
145     ...
146 </pre>
147
148
149 MX
150 ==
151
152 Places to look for errors
153 -------------------------
154
155 * `/var/log/mail.log`
156 * `/var/log/leap_mx.log`
157 * `/var/log/syslog` (watch out for stunnel issues)
158
159 Is couchdb accessible through stunnel ?
160 ---------------------------------------
161
162 * Depending on how many couch nodes you have, increase the port for every test
163   (see /etc/haproxy/haproxy.cfg for the server/port mapping):
164
165
166     curl -s -X  GET "http://127.0.0.1:4000"
167     curl -s -X  GET "http://127.0.0.1:4001"
168     ...
169
170 Query leap-mx
171 -------------
172
173 * for useraccount
174
175
176 <pre>
177     postmap -v -q  "joe@dev.bitmask.net" tcp:localhost:2244
178     ...
179     postmap: dict_tcp_lookup: send: get jow@dev.bitmask.net
180     postmap: dict_tcp_lookup: recv: 200
181     ...
182 </pre>
183
184 * for mailalias
185
186
187 <pre>
188     postmap -v -q  "joe@dev.bitmask.net" tcp:localhost:4242
189     ...
190     postmap: dict_tcp_lookup: send: get joe@dev.bitmask.net
191     postmap: dict_tcp_lookup: recv: 200 f01bc1c70de7d7d80bc1ad77d987e73a
192     postmap: dict_tcp_lookup: found: f01bc1c70de7d7d80bc1ad77d987e73a
193     f01bc1c70de7d7d80bc1ad77d987e73a
194     ...
195 </pre>
196
197
198 Check couchdb acl as unpriviledged user
199 ---------------------------------------
200
201
202
203     cat /etc/leap/mx.conf  # see username and password
204     echo "machine 127.0.0.1 login leap_mx password <PASSWORD>" > /etc/couchdb/couchdb-leap_mx.netrc
205     chmod 600 /etc/couchdb/couchdb-leap_mx.netrc
206
207     curl -s --netrc-file /etc/couchdb/couchdb-leap_mx.netrc -X GET "http://127.0.0.1:4096/_all_dbs"   # pick one "user-<hash>" db
208     curl -s --netrc-file /etc/couchdb/couchdb-leap_mx.netrc -X GET "http://127.0.0.1:4096/user-de9c77a3d7efbc779c6c20da88e8fb9c"
209
210
211 * you may check multiple times, cause 127.0.0.1:4096 is haproxy load-balancing the different couchdb nodes
212
213
214 Mailspool
215 ---------
216
217 * Any file in the leap_mx mailspool longer for a few seconds ?
218
219
220
221 <pre>
222     ls -la /var/mail/vmail/Maildir/cur/
223 </pre>
224
225 * Any mails in postfix mailspool longer than a few seconds ?
226
227 <pre>
228     mailq
229 </pre>
230
231
232
233 Testing mail delivery
234 ---------------------
235
236     swaks -f alice@example.org -t bob@example.net -s mx1.example.net --port 25
237     swaks -f varac@cdev.bitmask.net -t varac@cdev.bitmask.net -s chipmonk.cdev.bitmask.net --port 465 --tlsc
238     swaks -f alice@example.org -t bob@example.net -s mx1.example.net --port 587 --tls
239
240
241 VPN
242 ===
243
244 Places to look for errors
245 -------------------------
246
247 * `/var/log/syslog` (watch out for openvpn issues)
248
249