[github/shaarli/Shaarli.git] / doc / md / Troubleshooting.md

# Troubleshooting

## Login

### I forgot my password!

Delete the file `data/config.json.php` and display the page again. You will be asked for a new login/password.

### I'm locked out - Login bruteforce protection

Login 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.

- To remove the current IP bans, delete the file `data/ipbans.php`
- To list all login attempts, see `data/log.txt` (succesful/failed logins, bans/lifted bans)

## Browser issues

### Redirection issues (HTTP Referer)

Depending 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.

### Firefox, localhost and redirections

`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,
Shaarli 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/.

## Hosting problems

### Old PHP versions

On **free.fr**: free.fr now supports php 5.6.x([link](http://les.pages.perso.chez.free.fr/migrations/php5v6.io))
and so support now the tag autocompletion but you have to do the following.

At the root of your webspace create a `sessions` directory and a `.htaccess` file containing:

```xml
<IfDefine Free>
php56 1
</IfDefine>
```

- If you have an error such as: `Parse error: syntax error, unexpected '=', expecting '(' in /links/index.php on line xxx`, it means that your host is using php4, not php5. Shaarli requires php 5.1. Try changing the file extension to `.php5`
- On **1and1** : If you add the link from the page (and not from the bookmarklet), Shaarli will no be able to get the title of the page. You will have to enter it manually. (Because they have disabled the ability to download a file through HTTP).
- If you have the error `Warning: file_get_contents() [function.file-get-contents]: URL file-access is disabled in the server configuration in /…/index.php on line xxx`, it means that your host has disabled the ability to fetch a file by HTTP in the php config (Typically in 1and1 hosting). Bad host. Change host. Or comment the following lines:

```php
//list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.
// FIXME: Decode charset according to charset specified in either 1) HTTP response headers or 2) <head> in html
//if (strpos($status,'200 OK')) $title=html_extract_title($data);
```

- On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work.
- On **lost-oasis**, RSS doesn't work correctly, because of this message at the begining of the RSS/ATOM feed : `<? // tout ce qui est charge ici (generalement des includes et require) est charge en permanence. ?>`. To fix this, remove this message from `php-include/prepend.php`

### Dates are not properly formatted

Shaarli tries to sniff the language of the browser (using `HTTP_ACCEPT_LANGUAGE` headers)
and choose a date format accordingly. But Shaarli can only use the date formats
(and more generally speaking, the locales) provided by the webserver.
So even if you have a browser in French, you may end up with dates in US format
(it's the case on sebsauvage.net :-( )

### My session expires! I can't stay logged in

This can be caused by several things:

- Your php installation may not have a proper directory setup for session files. (eg. on Free.fr you need to create a  `session` directory on the root of your website.) You may need to create the session directory of set it up.
- Most hosts regularly clean the temporary and session directories. Your host may be cleaning those directories too aggressively (eg.OVH hosts), forcing an expire of the session. You may want to set the session directory in your web root. (eg. Create the `sessions` subdirectory and add `ini_set('session.save_path', $_SERVER['DOCUMENT_ROOT'].'/../sessions');`. Make sure this directory is not browsable !)
- If your IP address changes during surfing, Shaarli will force expire your session for security reasons (to prevent session cookie hijacking). This can happen when surfing from WiFi or 3G (you may have switched WiFi/3G access point), or in some corporate/university proxies which use load balancing (and may have proxies with several external IP addresses).
- Some browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey…). Try disabling those.
- You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time.
- If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions.

### Old apache versions, Internal Server Error

If 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).

## Sessions do not seem to work correctly on your server

Follow 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)).
Commit	Line	Data
53ed6d7d	1	# Troubleshooting
53ed6d7d	2
992af0b9	3	## Login
53ed6d7d	4
992af0b9	5	### I forgot my password!
53ed6d7d	6
48679a15	7	Delete the file `data/config.json.php` and display the page again. You will be asked for a new login/password.
992af0b9 V	8
992af0b9 V	9	### I'm locked out - Login bruteforce protection
53ed6d7d	10
992af0b9 V	11	Login 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.
992af0b9 V	12
74c1d020	13	- To remove the current IP bans, delete the file `data/ipbans.php`
74c1d020	14	- To list all login attempts, see `data/log.txt` (succesful/failed logins, bans/lifted bans)
992af0b9	15
74c1d020	16	## Browser issues
53ed6d7d	17
74c1d020	18	### Redirection issues (HTTP Referer)
	19
	20	Depending 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,
	25	Shaarli 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/.
992af0b9 V	26
992af0b9 V	27	## Hosting problems
53ed6d7d	28
6335a0fc	29	### Old PHP versions
53ed6d7d	30
43ad7c8e V	31	On free.fr: free.fr now supports php 5.6.x([link](http://les.pages.perso.chez.free.fr/migrations/php5v6.io))
	32	and so support now the tag autocompletion but you have to do the following.
	33
	34	At the root of your webspace create a `sessions` directory and a `.htaccess` file containing:
992af0b9	35
43ad7c8e	36	```xml
f8b936e7 V	37	<IfDefine Free>
	38	php56 1
	39	</IfDefine>
992af0b9 V	40	```
992af0b9 V	41
43ad7c8e V	42	- If you have an error such as: `Parse error: syntax error, unexpected '=', expecting '(' in /links/index.php on line xxx`, it means that your host is using php4, not php5. Shaarli requires php 5.1. Try changing the file extension to `.php5`
	43	- On 1and1 : If you add the link from the page (and not from the bookmarklet), Shaarli will no be able to get the title of the page. You will have to enter it manually. (Because they have disabled the ability to download a file through HTTP).
	44	- If you have the error `Warning: file_get_contents() [function.file-get-contents]: URL file-access is disabled in the server configuration in /…/index.php on line xxx`, it means that your host has disabled the ability to fetch a file by HTTP in the php config (Typically in 1and1 hosting). Bad host. Change host. Or comment the following lines:
992af0b9 V	45
	46	```php
	47	//list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.
48679a15	48	// FIXME: Decode charset according to charset specified in either 1) HTTP response headers or 2) <head> in html
992af0b9 V	49	//if (strpos($status,'200 OK')) $title=html_extract_title($data);
	50	```
	51
43ad7c8e V	52	- On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work.
43ad7c8e V	53	- On lost-oasis, RSS doesn't work correctly, because of this message at the begining of the RSS/ATOM feed : `<? // tout ce qui est charge ici (generalement des includes et require) est charge en permanence. ?>`. To fix this, remove this message from `php-include/prepend.php`
992af0b9 V	54
992af0b9 V	55	### Dates are not properly formatted
53ed6d7d	56
48679a15 V	57	Shaarli tries to sniff the language of the browser (using `HTTP_ACCEPT_LANGUAGE` headers)
	58	and choose a date format accordingly. But Shaarli can only use the date formats
	59	(and more generally speaking, the locales) provided by the webserver.
	60	So even if you have a browser in French, you may end up with dates in US format
	61	(it's the case on sebsauvage.net :-( )
992af0b9	62
992af0b9	63	### My session expires! I can't stay logged in
53ed6d7d	64
992af0b9 V	65	This can be caused by several things:
992af0b9 V	66
43ad7c8e V	67	- Your php installation may not have a proper directory setup for session files. (eg. on Free.fr you need to create a `session` directory on the root of your website.) You may need to create the session directory of set it up.
	68	- Most hosts regularly clean the temporary and session directories. Your host may be cleaning those directories too aggressively (eg.OVH hosts), forcing an expire of the session. You may want to set the session directory in your web root. (eg. Create the `sessions` subdirectory and add `ini_set('session.save_path', $_SERVER['DOCUMENT_ROOT'].'/../sessions');`. Make sure this directory is not browsable !)
	69	- If your IP address changes during surfing, Shaarli will force expire your session for security reasons (to prevent session cookie hijacking). This can happen when surfing from WiFi or 3G (you may have switched WiFi/3G access point), or in some corporate/university proxies which use load balancing (and may have proxies with several external IP addresses).
	70	- Some browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey…). Try disabling those.
	71	- You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time.
	72	- If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions.
992af0b9	73
74c1d020	74	### Old apache versions, Internal Server Error
	75
	76	If 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
992af0b9	78	## Sessions do not seem to work correctly on your server
53ed6d7d	79
53ed6d7d	80	Follow 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)).
5256f83d	81