doc/html/Troubleshooting/index.html

   1 <!DOCTYPE html>
   2 <!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
   3 <!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
   4 <head>
   5   <meta charset="utf-8">
   6   <meta http-equiv="X-UA-Compatible" content="IE=edge">
   7   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   8
   9
  10   <link rel="shortcut icon" href="../img/favicon.ico">
  11   <title>Troubleshooting - Shaarli Documentation</title>
  12   <link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>
  13
  14   <link rel="stylesheet" href="../css/theme.css" type="text/css" />
  15   <link rel="stylesheet" href="../css/theme_extra.css" type="text/css" />
  16   <link rel="stylesheet" href="../css/highlight.css">
  17   <link href="../github-markdown.css" rel="stylesheet">
  18
  19   <script>
  20     // Current page data
  21     var mkdocs_page_name = "Troubleshooting";
  22     var mkdocs_page_input_path = "Troubleshooting.md";
  23     var mkdocs_page_url = "/Troubleshooting/";
  24   </script>
  25
  26   <script src="../js/jquery-2.1.1.min.js"></script>
  27   <script src="../js/modernizr-2.8.3.min.js"></script>
  28   <script type="text/javascript" src="../js/highlight.pack.js"></script>
  29
  30 </head>
  31
  32 <body class="wy-body-for-nav" role="document">
  33
  34   <div class="wy-grid-for-nav">
  35
  36
  37     <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
  38       <div class="wy-side-nav-search">
  39         <a href=".." class="icon icon-home"> Shaarli Documentation</a>
  40         <div role="search">
  41   <form id ="rtd-search-form" class="wy-form" action="../search.html" method="get">
  42     <input type="text" name="q" placeholder="Search docs" />
  43   </form>
  44 </div>
  45       </div>
  46
  47       <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
  48         <ul class="current">
  49
  50
  51             <li class="toctree-l1">
  52
  53     <a class="" href="..">Home</a>
  54             </li>
  55
  56             <li class="toctree-l1">
  57
  58     <span class="caption-text">Setup</span>
  59     <ul class="subnav">
  60                 <li class="">
  61
  62     <a class="" href="../Download-and-Installation/">Download and Installation</a>
  63                 </li>
  64                 <li class="">
  65
  66     <a class="" href="../Upgrade-and-migration/">Upgrade and migration</a>
  67                 </li>
  68                 <li class="">
  69
  70     <a class="" href="../Server-requirements/">Server requirements</a>
  71                 </li>
  72                 <li class="">
  73
  74     <a class="" href="../Server-configuration/">Server configuration</a>
  75                 </li>
  76                 <li class="">
  77
  78     <a class="" href="../Server-security/">Server security</a>
  79                 </li>
  80                 <li class="">
  81
  82     <a class="" href="../Shaarli-configuration/">Shaarli configuration</a>
  83                 </li>
  84                 <li class="">
  85
  86     <a class="" href="../Plugins/">Plugins</a>
  87                 </li>
  88     </ul>
  89             </li>
  90
  91             <li class="toctree-l1">
  92
  93     <span class="caption-text">Docker</span>
  94     <ul class="subnav">
  95                 <li class="">
  96
  97     <a class="" href="../Docker-101/">Docker 101</a>
  98                 </li>
  99                 <li class="">
 100
 101     <a class="" href="../Shaarli-images/">Shaarli images</a>
 102                 </li>
 103                 <li class="">
 104
 105     <a class="" href="../Reverse-proxy-configuration/">Reverse proxy configuration</a>
 106                 </li>
 107                 <li class="">
 108
 109     <a class="" href="../Docker-resources/">Docker resources</a>
 110                 </li>
 111     </ul>
 112             </li>
 113
 114             <li class="toctree-l1">
 115
 116     <span class="caption-text">Usage</span>
 117     <ul class="subnav">
 118                 <li class="">
 119
 120     <a class="" href="../Features/">Features</a>
 121                 </li>
 122                 <li class="">
 123
 124     <a class="" href="../Bookmarklet/">Bookmarklet</a>
 125                 </li>
 126                 <li class="">
 127
 128     <a class="" href="../Browsing-and-searching/">Browsing and searching</a>
 129                 </li>
 130                 <li class="">
 131
 132     <a class="" href="../Firefox-share/">Firefox share</a>
 133                 </li>
 134                 <li class="">
 135
 136     <a class="" href="../RSS-feeds/">RSS feeds</a>
 137                 </li>
 138                 <li class="">
 139
 140     <a class="" href="../REST-API/">REST API</a>
 141                 </li>
 142     </ul>
 143             </li>
 144
 145             <li class="toctree-l1">
 146
 147     <span class="caption-text">How To</span>
 148     <ul class="subnav">
 149                 <li class="">
 150
 151     <a class="" href="../Backup,-restore,-import-and-export/">Backup, restore, import and export</a>
 152                 </li>
 153                 <li class="">
 154
 155     <a class="" href="../Various-hacks/">Various hacks</a>
 156                 </li>
 157     </ul>
 158             </li>
 159
 160             <li class="toctree-l1 current">
 161
 162     <a class="current" href="./">Troubleshooting</a>
 163     <ul class="subnav">
 164
 165     <li class="toctree-l2"><a href="#troubleshooting">Troubleshooting</a></li>
 166
 167         <ul>
 168
 169             <li><a class="toctree-l3" href="#browser">Browser</a></li>
 170
 171             <li><a class="toctree-l3" href="#login">Login</a></li>
 172
 173             <li><a class="toctree-l3" href="#hosting-problems">Hosting problems</a></li>
 174
 175             <li><a class="toctree-l3" href="#sessions-do-not-seem-to-work-correctly-on-your-server">Sessions do not seem to work correctly on your server</a></li>
 176
 177         </ul>
 178
 179
 180     </ul>
 181             </li>
 182
 183             <li class="toctree-l1">
 184
 185     <span class="caption-text">Development</span>
 186     <ul class="subnav">
 187                 <li class="">
 188
 189     <a class="" href="../Development-guidelines/">Development guidelines</a>
 190                 </li>
 191                 <li class="">
 192
 193     <a class="" href="../Continuous-integration-tools/">Continuous integration tools</a>
 194                 </li>
 195                 <li class="">
 196
 197     <a class="" href="../GnuPG-signature/">GnuPG signature</a>
 198                 </li>
 199                 <li class="">
 200
 201     <a class="" href="../Coding-guidelines/">Coding guidelines</a>
 202                 </li>
 203                 <li class="">
 204
 205     <a class="" href="../Directory-structure/">Directory structure</a>
 206                 </li>
 207                 <li class="">
 208
 209     <a class="" href="../3rd-party-libraries/">3rd party libraries</a>
 210                 </li>
 211                 <li class="">
 212
 213     <a class="" href="../Plugin-System/">Plugin System</a>
 214                 </li>
 215                 <li class="">
 216
 217     <a class="" href="../Release-Shaarli/">Release Shaarli</a>
 218                 </li>
 219                 <li class="">
 220
 221     <a class="" href="../Versioning-and-Branches/">Versioning and Branches</a>
 222                 </li>
 223                 <li class="">
 224
 225     <a class="" href="../Security/">Security</a>
 226                 </li>
 227                 <li class="">
 228
 229     <a class="" href="../Static-analysis/">Static analysis</a>
 230                 </li>
 231                 <li class="">
 232
 233     <a class="" href="../Theming/">Theming</a>
 234                 </li>
 235                 <li class="">
 236
 237     <a class="" href="../Unit-tests/">Unit tests</a>
 238                 </li>
 239     </ul>
 240             </li>
 241
 242             <li class="toctree-l1">
 243
 244     <span class="caption-text">About</span>
 245     <ul class="subnav">
 246                 <li class="">
 247
 248     <a class="" href="../FAQ/">FAQ</a>
 249                 </li>
 250                 <li class="">
 251
 252     <a class="" href="../Community-&-Related-software/">Community & Related software</a>
 253                 </li>
 254     </ul>
 255             </li>
 256
 257         </ul>
 258       </div>
 259       &nbsp;
 260     </nav>
 261
 262     <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
 263
 264
 265       <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
 266         <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
 267         <a href="..">Shaarli Documentation</a>
 268       </nav>
 269
 270
 271       <div class="wy-nav-content">
 272         <div class="rst-content">
 273           <div role="navigation" aria-label="breadcrumbs navigation">
 274   <ul class="wy-breadcrumbs">
 275     <li><a href="..">Docs</a> &raquo;</li>
 276
 277
 278
 279     <li>Troubleshooting</li>
 280     <li class="wy-breadcrumbs-aside">
 281
 282         <a href="https://github.com/shaarli/Shaarli/edit/master/docs/Troubleshooting.md"
 283           class="icon icon-github"> Edit on GitHub</a>
 284
 285     </li>
 286   </ul>
 287   <hr/>
 288 </div>
 289           <div role="main">
 290             <div class="section">
 291
 292                 <h1 id="troubleshooting">Troubleshooting</h1>
 293 <h2 id="browser">Browser</h2>
 294 <h3 id="redirection-issues-http-referer">Redirection issues (HTTP Referer)</h3>
 295 <p>Depending on its configuration and installed plugins, the browser may remove or alter (spoof) HTTP referers, thus preventing Shaarli from properly redirecting between pages.</p>
 296 <p>See:
 297 - <a href="https://en.wikipedia.org/wiki/HTTP_referer">HTTP referer</a> (Wikipedia)
 298 - <a href="http://www.ghacks.net/2015/01/22/improve-online-privacy-by-controlling-referrer-information/">Improve online privacy by controlling referrer information</a>
 299 - <a href="http://b.agilob.net/better-security-privacy-and-anonymity-in-firefox/">Better security, privacy and anonymity in Firefox</a></p>
 300 <h3 id="firefox-http-referer-options">Firefox HTTP Referer options</h3>
 301 <p>HTTP settings are available by browsing <code>about:config</code>, here are the available settings and their values.</p>
 302 <p><code>network.http.sendRefererHeader</code> - determines when to send the Referer HTTP header
 303 - 0: Never send the referring URL
 304     - not recommended, may break some sites
 305 - 1: Send only on clicked links
 306 - 2 (default): Send for links and images</p>
 307 <p><code>network.http.referer.XOriginPolicy</code> - Cross-domain origin policy
 308 - 0 (default): Always send
 309 - 1: Send if base domains match
 310 - 2: Send if hosts match</p>
 311 <p><code>network.http.referer.spoofSource</code> - Referer spoofing (~faking)
 312 - false (default): real referer
 313 - true: spoof referer (use target URI as referer)
 314   - known to break some functionality in Shaarli</p>
 315 <p><code>network.http.referer.trimmingPolicy</code> - trim the URI not to send a full Referer
 316 - 0 (default): send full URI
 317 - 1: scheme+host+port+path
 318 - 2: scheme+host+port</p>
 319 <h3 id="firefox-localhost-and-redirections">Firefox, localhost and redirections</h3>
 320 <p><code>localhost</code> 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.</p>
 321 <p>To solve this, assign a local domain to your host, e.g.</p>
 322 <pre><code>127.0.0.1 localhost desktop localhost.lan
 323 ::1       localhost desktop localhost.lan
 324 </code></pre>
 325
 326 <p>and browse Shaarli at http://localhost.lan/.</p>
 327 <p>Related threads:
 328 - <a href="https://bbs.archlinux.org/viewtopic.php?id=156064">What is localhost.localdomain for?</a>
 329 - <a href="https://github.com/shaarli/Shaarli/issues/311">Stop returning to the first page after editing a bookmark from another page</a></p>
 330 <h2 id="login">Login</h2>
 331 <h3 id="i-forgot-my-password">I forgot my password!</h3>
 332 <p>Delete the file <code>data/config.php</code> and display the page again. You will be asked for a new login/password.</p>
 333 <h3 id="im-locked-out-login-bruteforce-protection">I'm locked out - Login bruteforce protection</h3>
 334 <p>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.</p>
 335 <p>To remove the current IP bans, delete the file <code>data/ipbans.php</code></p>
 336 <h3 id="list-of-all-login-attempts">List of all login attempts</h3>
 337 <p>The file <code>data/log.txt</code> shows all logins (successful or failed) and bans/lifted bans.
 338 Search for <code>failed</code> in this file to look for unauthorized login attempts.</p>
 339 <h2 id="hosting-problems">Hosting problems</h2>
 340 <h3 id="old-php-versions">Old PHP versions</h3>
 341 <ul>
 342 <li>On <strong>free.fr</strong> : free.fr now support php 5.6.x(<a href="http://les.pages.perso.chez.free.fr/migrations/php5v6.io">link</a>)and so support now the tag autocompletion but you have to do the following : At the root of your webspace create a <code>sessions</code> directory and a <code>.htaccess</code> file containing:</li>
 343 </ul>
 344 <pre><code class="ini">&lt;IfDefine Free&gt;
 345 php56 1
 346 &lt;/IfDefine&gt;
 347 </code></pre>
 348
 349 <ul>
 350 <li>If you have an error such as: <code>Parse error: syntax error, unexpected '=', expecting '(' in /links/index.php on line xxx</code>, it means that your host is using php4, not php5. Shaarli requires php 5.1. Try changing the file extension to <code>.php5</code></li>
 351 <li>On <strong>1and1</strong> : 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).</li>
 352 <li>If you have the error <code>Warning: file_get_contents() [function.file-get-contents]: URL file-access is disabled in the server configuration in /…/index.php on line xxx</code>, 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:</li>
 353 </ul>
 354 <pre><code class="php">//list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.
 355 // FIXME: Decode charset according to charset specified in either 1) HTTP response headers or 2) &lt;head&gt; in html
 356 //if (strpos($status,'200 OK')) $title=html_extract_title($data);
 357 </code></pre>
 358
 359 <ul>
 360 <li>On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work.</li>
 361 <li>On <strong>lost-oasis</strong>, RSS doesn't work correctly, because of this message at the begining of the RSS/ATOM feed : <code>&lt;? // tout ce qui est charge ici (generalement des includes et require) est charge en permanence. ?&gt;</code>. To fix this, remove this message from <code>php-include/prepend.php</code></li>
 362 </ul>
 363 <h3 id="dates-are-not-properly-formatted">Dates are not properly formatted</h3>
 364 <p>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 generaly 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 :-( )</p>
 365 <h3 id="problems-on-centos-servers">Problems on CentOS servers</h3>
 366 <p>On <strong>CentOS</strong>/RedHat derivatives, you may need to install the <code>php-mbstring</code> package.</p>
 367 <h3 id="my-session-expires-i-cant-stay-logged-in">My session expires! I can't stay logged in</h3>
 368 <p>This can be caused by several things:</p>
 369 <ul>
 370 <li>Your php installation may not have a proper directory setup for session files. (eg. on Free.fr you need to create a  <code>session</code> directory on the root of your website.) You may need to create the session directory of set it up.</li>
 371 <li>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 <code>sessions</code> subdirectory and add <code>ini_set('session.save_path', $_SERVER['DOCUMENT_ROOT'].'/../sessions');</code>. Make sure this directory is not browsable !)</li>
 372 <li>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).</li>
 373 <li>Some browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey…). Try disabling those.</li>
 374 <li>You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time.</li>
 375 <li>If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions.</li>
 376 </ul>
 377 <h2 id="sessions-do-not-seem-to-work-correctly-on-your-server">Sessions do not seem to work correctly on your server</h2>
 378 <p>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 <strong>no dots</strong> in the hostname (e.g. <code>localhost</code> or <code>http://my-webserver/shaarli/</code>), some browsers will not store cookies at all (this respects the <a href="http://curl.haxx.se/rfc/cookie_spec.html">HTTP cookie specification</a>).</p>
 379 <h3 id="pubsubhubbub-support">pubsubhubbub support</h3>
 380 <p>Download <a href="https://pubsubhubbub.googlecode.com/git/publisher_clients/php/library/publisher.php">publisher.php</a> at the root of your Shaarli installation and set <code>$GLOBALS['config']['PUBSUBHUB_URL']</code> in your <code>config.php</code></p>
 381
 382             </div>
 383           </div>
 384           <footer>
 385
 386     <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
 387
 388         <a href="../Development-guidelines/" class="btn btn-neutral float-right" title="Development guidelines">Next <span class="icon icon-circle-arrow-right"></span></a>
 389
 390
 391         <a href="../Various-hacks/" class="btn btn-neutral" title="Various hacks"><span class="icon icon-circle-arrow-left"></span> Previous</a>
 392
 393     </div>
 394
 395
 396   <hr/>
 397
 398   <div role="contentinfo">
 399     <!-- Copyright etc -->
 400
 401   </div>
 402
 403   Built with <a href="http://www.mkdocs.org">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
 404 </footer>
 405
 406         </div>
 407       </div>
 408
 409     </section>
 410
 411   </div>
 412
 413   <div class="rst-versions" role="note" style="cursor: pointer">
 414     <span class="rst-current-version" data-toggle="rst-current-version">
 415
 416           <a href="https://github.com/shaarli/Shaarli" class="fa fa-github" style="float: left; color: #fcfcfc"> GitHub</a>
 417
 418
 419         <span><a href="../Various-hacks/" style="color: #fcfcfc;">&laquo; Previous</a></span>
 420
 421
 422         <span style="margin-left: 15px"><a href="../Development-guidelines/" style="color: #fcfcfc">Next &raquo;</a></span>
 423
 424     </span>
 425 </div>
 426     <script src="../js/theme.js"></script>
 427
 428 </body>
 429 </html>