doc/md/Troubleshooting.md

   1 # Troubleshooting
   2
   3 First of all, ensure that both the [web server](Server-configuration.md) and [Shaarli](Shaarli-configuration.md) are correctly configured.
   4
   5
   6 ## Login
   7
   8 ### I forgot my password!
   9
  10 Delete the file `data/config.json.php` and display the page again. You will be asked for a new login/password.
  11
  12 ### I'm locked out - Login bruteforce protection
  13
  14 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 Shaares.
  15
  16 - To remove the current IP bans, delete the file `data/ipbans.php`
  17 - To list all login attempts, see `data/log.txt` (succesful/failed logins, bans/lifted bans)
  18
  19 --------------------------------------
  20
  21 ## Browser issues
  22
  23 ### Redirection issues (HTTP Referer)
  24
  25 Shaarli relies on `HTTP_REFERER` for some functions (like redirects and clicking on tags). If you have disabled or altered/spoofed [HTTP referers](https://en.wikipedia.org/wiki/HTTP_referer) in your browser, some features of Shaarli may not work as expected (depending on configuration and installed plugins), notably redirections between pages.
  26
  27 Firefox 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.
  28
  29
  30 ### Firefox, localhost and redirections
  31
  32 `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,
  33 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/.
  34
  35 -----------------------------------------
  36
  37 ## Hosting problems
  38
  39 ### Old PHP versions
  40
  41 - On hosts (such as **free.fr**) which only support PHP 5.6, Shaarli [v0.10.4](https://github.com/shaarli/Shaarli/releases/tag/v0.10.4) is the maximum supported version. At the root of your webspace create a `sessions` directory and a `.htaccess` file containing:
  42
  43 ```xml
  44 <IfDefine Free>
  45 php56 1
  46 </IfDefine>
  47 <Files ".ht*">
  48 Order allow,deny
  49 Deny from all
  50 Satisfy all
  51 </Files>
  52 Options -Indexes
  53 ```
  54
  55 - 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 PHP 4, not PHP 5. Shaarli requires PHP 5.1. Try changing the file extension to `.php5`
  56 - 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).
  57 - 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:
  58
  59 ```php
  60 //list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.
  61 // FIXME: Decode charset according to charset specified in either 1) HTTP response headers or 2) <head> in html
  62 //if (strpos($status,'200 OK')) $title=html_extract_title($data);
  63 ```
  64
  65 - On hosts (such as **free.fr**) which forbid outgoing HTTP requests, some thumbnails will not work.
  66 - On hosts (such as **free.fr**) which limit the number of FTP connections, setup your FTP client accordingly (else some files may be missing after upload).
  67 - 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`
  68
  69
  70 ### Dates are not properly formatted
  71
  72 Shaarli tries to sniff the language of the browser (using `HTTP_ACCEPT_LANGUAGE` headers)
  73 and choose a date format accordingly. But Shaarli can only use the date formats
  74 (and more generally speaking, the locales) provided by the webserver.
  75 So even if you have a browser in French, you may end up with dates in US format
  76 (it's the case on sebsauvage.net :-( )
  77
  78 ### My session expires! I can't stay logged in
  79
  80 This can be caused by several things:
  81
  82 - 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.
  83 - 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 !)
  84 - 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).
  85 - Some browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey…). Try disabling those.
  86 - You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time.
  87 - If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions.
  88
  89
  90 ### Old apache versions, Internal Server Error
  91
  92 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).
  93
  94
  95 ### Sessions do not seem to work correctly on your server
  96
  97 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)).
  98
  99 ----------------------------------------------------------
 100
 101 ## Upgrades
 102
 103 ### You must specify an integer as a key
 104
 105 In `v0.8.1` we changed how Shaare keys are handled (from timestamps to incremental integers). Take a look at `data/updates.txt` content.
 106
 107
 108 ### `updates.txt` contains `updateMethodDatastoreIds`
 109
 110 Try to delete it and refresh your page while being logged in.
 111
 112 ### `updates.txt` doesn't exist or doesn't contain `updateMethodDatastoreIds`
 113
 114 1. Create `data/updates.txt` if it doesn't exist
 115 2. Paste this string in the update file `;updateMethodRenameDashTags;`
 116 3. Login to Shaarli
 117 4. Delete the update file
 118 5. Refresh
 119
 120
 121
 122 --------------------------------------------------------
 123
 124 ## Import/export
 125
 126 ### Importing shaarli data to Firefox
 127
 128 - In Firefox, open the bookmark manager (`Bookmarks menu > Show all bookmarks` or `Ctrl+Shift+B`), select `Import and Backup > Import bookmarks in HTML format`
 129 - Make sure the `Prepend note permalinks with this Shaarli instance's URL` box is checked when exporting, so that text-only/notes Shaares still point to the Shaarli instance you exported them from.
 130 - Depending on the number of bookmarks, the import can take some time.
 131
 132 You may be interested in these Firefox addons to manage bookmarks imported from Shaarli
 133
 134 - [Bookmark Deduplicator](https://addons.mozilla.org/en-US/firefox/addon/bookmark-deduplicator/) - provides an easy way to deduplicate your bookmarks
 135 - [TagSieve](https://addons.mozilla.org/en-US/firefox/addon/tagsieve/) - browse your bookmarks by their tags
 136
 137 ### Diigo
 138
 139 If you export your bookmark from Diigo, make sure you use the Delicious export, not the Netscape export. (Their Netscape export is broken, and they don't seem to be interested in fixing it.)
 140
 141 ### Mister Wong
 142
 143 See [this issue](https://github.com/sebsauvage/Shaarli/issues/146) for import tweaks.
 144
 145 ### SemanticScuttle
 146
 147 To correctly import the tags from a [SemanticScuttle](http://semanticscuttle.sourceforge.net/) HTML export, edit the HTML file before importing and replace all occurences of `tags=` (lowercase) to `TAGS=` (uppercase).
 148
 149 ### Scuttle
 150
 151 Shaarli cannot import data directly from [Scuttle](https://github.com/scronide/scuttle).
 152
 153 However, you can use the third-party [scuttle-to-shaarli](https://github.com/q2apro/scuttle-to-shaarli)
 154 tool to export the Scuttle database to the Netscape HTML format compatible with the Shaarli importer.
 155
 156 ### Refind.com
 157
 158 You can use the third-party tool [Derefind](https://github.com/ShawnPConroy/Derefind) to convert refind.com bookmark exports to a format that can be imported into Shaarli.
 159
 160
 161 -------------------------------------------------------
 162
 163 ## Other
 164
 165 ### The bookmarklet doesn't work
 166
 167 Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunately, there is nothing Shaarli can do about it ([1](https://github.com/shaarli/Shaarli/issues/196), [2](https://bugzilla.mozilla.org/show_bug.cgi?id=866522), [3](https://code.google.com/p/chromium/issues/detail?id=233903).
 168
 169 Under Opera, you can't drag'n drop the button: You have to right-click on it and add a bookmark to your personal toolbar.
 170
 171
 172 ### Changing the timestamp for a shaare
 173
 174 - Look for `<input type="hidden" name="lf_linkdate" value="{$link.linkdate}">` in `tpl/editlink.tpl` (line 14)
 175 - Replace `type="hidden"` with `type="text"` from this line
 176 - A new date/time field becomes available in the edit/new Shaare dialog.
 177 - You can set the timestamp manually by entering it in the format `YYYMMDD_HHMMS`.
 178
 179 ### Clearing Shaarli caches
 180
 181 For debugging purposes:
 182
 183 ```bash
 184 # clear raintpl cache and temporary files
 185 find /var/www/links/cache/ /var/www/links/pagecache/ /var/www/links/tmp/ -type f -exec rm -v '{}' \;
 186 # if you have a php accelerator such as php-apcu, restart the webserver
 187 sudo systemctl restart apache2
 188 ```
 189
 190 -------------------------------------------------------
 191
 192 ## Support
 193
 194 If the solutions above did not help, please:
 195
 196 - Come and ask question on the [Gitter chat](https://gitter.im/shaarli/Shaarli) (also reachable via [IRC](https://irc.gitter.im/))
 197 - Search for [issues](https://github.com/shaarli/Shaarli/issues) and [Pull Requests](https://github.com/shaarli/Shaarli/pulls)
 198     - if you find one that is related to the issue, feel free to comment and provide additional details (host/Shaarli setup...)
 199     - check issues labeled [`feature`](https://github.com/shaarli/Shaarli/labels/feature), [`enhancement`](https://github.com/shaarli/Shaarli/labels/enhancement), and [`plugin`](https://github.com/shaarli/Shaarli/labels/plugin) if you would like a feature added to Shaarli.
 200     - else, [open a new issue](https://github.com/shaarli/Shaarli/issues/new), and provide information about the problem:
 201         - _what happens?_ - display glitches, invalid data, security flaws...
 202         - _what is your configuration?_  - OS, server version, activated extensions, web browser...
 203         - _is it reproducible?_