aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc
diff options
context:
space:
mode:
authornodiscc <nodiscc@gmail.com>2020-01-04 00:28:04 +0100
committernodiscc <nodiscc@gmail.com>2020-01-04 00:28:04 +0100
commit74c1d020793d9a7cae5f563776d6fc2f4155d627 (patch)
treeec15bbdb0e9ff27ebb433c81b710f8ed03db03f7 /doc
parent5256f83d024a3a116ab59a0554a876f064bcaa68 (diff)
downloadShaarli-74c1d020793d9a7cae5f563776d6fc2f4155d627.tar.gz
Shaarli-74c1d020793d9a7cae5f563776d6fc2f4155d627.tar.zst
Shaarli-74c1d020793d9a7cae5f563776d6fc2f4155d627.zip
doc: siplify troubleshooting, link to reference docs, reorder
Diffstat (limited to 'doc')
-rw-r--r--doc/md/Troubleshooting.md81
1 files changed, 15 insertions, 66 deletions
diff --git a/doc/md/Troubleshooting.md b/doc/md/Troubleshooting.md
index 78211809..01fd9840 100644
--- a/doc/md/Troubleshooting.md
+++ b/doc/md/Troubleshooting.md
@@ -1,64 +1,5 @@
1# Troubleshooting 1# Troubleshooting
2 2
3## Browser
4
5### Redirection issues (HTTP Referer)
6
7Depending on its configuration and installed plugins, the browser may remove or alter (spoof) HTTP referers, thus preventing Shaarli from properly redirecting between pages.
8
9See:
10
11- [HTTP referer](https://en.wikipedia.org/wiki/HTTP_referer) (Wikipedia)
12- [Improve online privacy by controlling referrer information](http://www.ghacks.net/2015/01/22/improve-online-privacy-by-controlling-referrer-information/)
13- [Better security, privacy and anonymity in Firefox](http://b.agilob.net/better-security-privacy-and-anonymity-in-firefox/)
14
15### Firefox HTTP Referer options
16
17HTTP settings are available by browsing `about:config`, here are the available settings and their values.
18
19`network.http.sendRefererHeader` - determines when to send the Referer HTTP header
20
21- `0`: Never send the referring URL
22 - not recommended, may break some sites
23- `1`: Send only on clicked links
24- `2` (default): Send for links and images
25
26`network.http.referer.XOriginPolicy` - Cross-domain origin policy
27
28- `0` (default): Always send
29- `1`: Send if base domains match
30- `2`: Send if hosts match
31
32`network.http.referer.spoofSource` - Referer spoofing (~faking)
33
34- `false` (default): real referer
35- `true`: spoof referer (use target URI as referer)
36 - known to break some functionality in Shaarli
37
38`network.http.referer.trimmingPolicy` - trim the URI not to send a full Referer
39
40- `0`: (default): send full URI
41- `1`: scheme+host+port+path
42- `2`: scheme+host+port
43
44### Firefox, localhost and redirections
45
46`localhost` is not a proper Fully Qualified Domain Name (FQDN); if Firefox has
47been set up to spoof referers, or only accept requests from the same base domain/host,
48Shaarli redirections will not work properly.
49
50To solve this, assign a local domain to your host, e.g.
51```
52127.0.0.1 localhost desktop localhost.lan
53::1 localhost desktop localhost.lan
54```
55
56and browse Shaarli at http://localhost.lan/.
57
58Related threads:
59- [What is localhost.localdomain for?](https://bbs.archlinux.org/viewtopic.php?id=156064)
60- [Stop returning to the first page after editing a bookmark from another page](https://github.com/shaarli/Shaarli/issues/311)
61
62## Login 3## Login
63 4
64### I forgot my password! 5### I forgot my password!
@@ -69,12 +10,19 @@ Delete the file `data/config.json.php` and display the page again. You will be a
69 10
70Login form is protected against brute force attacks: 4 failed logins will ban the IP address from login for 30 minutes. Banned IPs can still browse links. 11Login form is protected against brute force attacks: 4 failed logins will ban the IP address from login for 30 minutes. Banned IPs can still browse links.
71 12
72To remove the current IP bans, delete the file `data/ipbans.php` 13- To remove the current IP bans, delete the file `data/ipbans.php`
14- To list all login attempts, see `data/log.txt` (succesful/failed logins, bans/lifted bans)
73 15
74### List of all login attempts 16## Browser issues
75 17
76The file `data/log.txt` shows all logins (successful or failed) and bans/lifted bans. 18### Redirection issues (HTTP Referer)
77Search for `failed` in this file to look for unauthorized login attempts. 19
20Depending on its configuration and installed plugins, the browser may remove or alter (spoof) [HTTP referers](https://en.wikipedia.org/wiki/HTTP_referer), thus preventing Shaarli from properly redirecting between pages. Referer settings are available by browsing `about:config` and are documented [here](https://wiki.mozilla.org/Security/Referrer). `network.http.referer.spoofSource = true` in particular is known to break some functionality in Shaarli.
21
22### Firefox, localhost and redirections
23
24`localhost` is not a proper Fully Qualified Domain Name (FQDN); if Firefox has been set up to spoof referers, or only accept requests from the same base domain/host,
25Shaarli redirections will not work properly. To solve this, assign a local domain to your host, e.g. `localhost.lan` in your [hosts file](https://en.wikipedia.org/wiki/Hosts_(file)) and browse Shaarli at http://localhost.lan/.
78 26
79## Hosting problems 27## Hosting problems
80 28
@@ -123,10 +71,11 @@ This can be caused by several things:
123- You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time. 71- You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time.
124- If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions. 72- If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions.
125 73
74### Old apache versions, Internal Server Error
75
76If you hosting provider only provides apache 2.2 and no support for `mod_version`, `.htaccess` files may cause 500 errors (Internal Server Error). See [this workaround](https://github.com/shaarli/Shaarli/issues/1196#issuecomment-412271085).
77
126## Sessions do not seem to work correctly on your server 78## Sessions do not seem to work correctly on your server
127 79
128Follow the instructions in the error message. Make sure you are accessing shaarli via a direct IP address or a proper hostname. If you have **no dots** in the hostname (e.g. `localhost` or `http://my-webserver/shaarli/`), some browsers will not store cookies at all (this respects the [HTTP cookie specification](http://curl.haxx.se/rfc/cookie_spec.html)). 80Follow the instructions in the error message. Make sure you are accessing shaarli via a direct IP address or a proper hostname. If you have **no dots** in the hostname (e.g. `localhost` or `http://my-webserver/shaarli/`), some browsers will not store cookies at all (this respects the [HTTP cookie specification](http://curl.haxx.se/rfc/cookie_spec.html)).
129 81
130## Old apache versions, Internal Server Error
131
132If you hosting provider only provides apache 2.2 and no support for `mod_version`, `.htaccess` files may cause 500 errors (Internal Server Error). See [this workaround](https://github.com/shaarli/Shaarli/issues/1196#issuecomment-412271085). \ No newline at end of file