Differences

This shows you the differences between two versions of the page.

--- rewrite [2020-10-05 16:56] – Changed "Configuration Manager" to "Configuration Settings" - the proper name. ben@oueb.ca
+++ rewrite [2024-03-13 11:51] (current) – link to up2date apache2 doc 185.177.84.1
@@ Line 3: / Line 3: @@
 By default, DokuWiki does no URL rewriting, resulting in URLs like this:
-  http://example.com/doku.php?id=page
+  http://example.com/doku.php?id=wiki:syntax
-These URLs are considered ugly and are not indexed well by some search engines.
+These URLs are somewhat ugly and might not be indexed well by some search engines. URL rewriting offers a solution to this, resulting in nicer URLs.
-The solution is to enable URL rewriting, which is disabled by default.
+===== Rewriting options =====
-===== Instructions in plain English =====
-==== Steps ====
-  - Go to Admin
-  - Open Configuration Settings
-  - Change Nice URLs option to .htaccess (use find, it's far down)
-  - Underneath it, check the option to "Use slash as namespace separator in URLs"
-  - Save
-  - Next, using an ftp or file manager, you need access to your /wiki/ folder that you created when creating your wiki.
-  - Inside, you'll find a file called .htaccess and .htaccess.dist. (if you don't see it, make sure you have hidden files visible. It may be an option you have while logging on depending on your hosting provider, or, simply create a file called .htaccess and upload it)
-  - inside the .htaccess file, paste the following (alternatively uncomment section in .htaccess.dist then rename to .htaccess):
-<code apache>
-RewriteEngine on
-RewriteRule ^_media/(.*)              lib/exe/fetch.php?media=$1  [QSA,L]
-RewriteRule ^_detail/(.*)             lib/exe/detail.php?media=$1  [QSA,L]
-RewriteRule ^_export/([^/]+)/(.*)     doku.php?do=export_$1&id=$2  [QSA,L]
-RewriteRule ^$                        doku.php  [L]
-RewriteCond %{REQUEST_FILENAME}       !-f
-RewriteCond %{REQUEST_FILENAME}       !-d
-RewriteRule (.*)                      doku.php?id=$1  [QSA,L]
-RewriteRule ^index.php$               doku.php
-</code>
-This will give you a format like www.myexample.com/wiki-article. If you have a different format for your address, like www.myexample.com/dokuwiki/wiki-article, then place this line right after **RewriteEngine on**
-<code apache>
-RewriteBase /dokuwiki
-</code>
-where /dokuwiki should be changed to the actual name of the folder you are using.
-===== Further Details for the Technically Savvy =====
 DokuWiki supports two methods for URL rewriting, enabled through the [[config:userewrite]] option. One relies on the rewriting capabilities of the webserver; the other one handles rewritten URLs inside DokuWiki. The table below summarizes these options.
@@ Line 55: / Line 18: @@
 URL-Rewriting is disabled by default because it requires some additional configuration besides setting the appropriate [[config:userewrite|config option]] - these configs are discussed below.
-URL-Rewriting can be enabled at ''?do=admin&page=config#_advanced'' or in the local conf/local.php file line that reads ''$conf['userewrite'] = N;''. N is the number 0, 1, or 2. The default is zero without this line present. Follow the configuration instructions below for whichever option is chosen.
+==== Option 1: web server ====
-====== Option 1: web server ======
-:!: Remember to set following in the Configuration Manager ''/start?do=admin&page=config''
-  * Use nice URLs: **.htaccess**
-  * Use slash as namespace separator in URLs [**x**]
-Otherwise rewrite rules will not be useful.
+This option requires some setup in the webserver first. How to enable it, depends on the webserver used. Please refer to the linked pages below for additional info.
-==== Apache ====
+  * [[install:Apache]] -- uses the [[http://httpd.apache.org/docs/2.4/mod/mod_rewrite.html|mod_rewrite]] module. It can be enabled using a ''.htaccess'' file.
+  * [[install:IIS]] -- uses custom rewrite rules or the rewrite module
+  * [[install:nginx]] -- has built in rewriting support
+  * [[install:php-webserver|PHP's built-in web server]] -- needs no configuration, rewrite will work using DokuWiki's index.php router
-Rewriting URLs in Apache is done through the **mod_rewrite** module of [[http://httpd.apache.org/docs/1.3/mod/mod_rewrite.html|Apache 1]] or [[http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html|Apache 2]].
-DokuWiki comes with an ''.htaccess.dist'' file which contains the needed rewrite rules for mode 1.
+Once the rewriting support has been enabled in the web server, this option can be enabled in the DokuWiki configuration.
-Here is an example
+Select the ''.htaccess'' option in the [[config:userewrite]] config dropdown. Alternatively, in your ''conf/local.php'' file, add or modify the line so it reads:
-<code apache>
-RewriteEngine on
-RewriteBase /dokuwiki
+<code php>
+$conf['userewrite'] = 1;
-RewriteRule ^_media/(.*)              lib/exe/fetch.php?media=$1  [QSA,L]
-RewriteRule ^_detail/(.*)             lib/exe/detail.php?media=$1  [QSA,L]
-RewriteRule ^_export/([^/]+)/(.*)     doku.php?do=export_$1&id=$2  [QSA,L]
-RewriteRule ^$                        doku.php  [L]
-RewriteCond %{REQUEST_FILENAME}       !-f
-RewriteCond %{REQUEST_FILENAME}       !-d
-RewriteRule (.*)                      doku.php?id=$1  [QSA,L]
-RewriteRule ^index.php$               doku.php
 </code>
-On the line ''RewriteBase /dokuwiki'', you may need to replace the ''/dokuwiki'' with whatever directory you use in your URL to get to the wiki.  If your wiki appears at the top level of the domain (e.g. http://example.com points to the start page of the wiki then use the following line: ''RewriteBase /''.
+In DokuWiki root folder, find the file ''.htaccess.dist'' and copy it as ''.htaccess''. Edit it and uncomment lines referring to userwrite. It's a short file and easy to understand.
+==== Option 2: DokuWiki ====
-You may also need to rename the file from ''.htaccess.dist'' to ''.htaccess''.
-== Apachectl status broken ==
+This option won't need any webserver setup. However it relies on the PATH_INFO feature of the CGI standard as implemented by Apache. Some webserver configurations might not support it.
-Dokuwiki rewrite rule affect //apachectl status// command and make it return dokuwiki 404 page instead of the server-status page. You can fix that by either putting this in dokuwiki rewrite rules
+To enable this option, select the ''DokuWiki internal'' option in the [[config:userewrite]] config dropdown. Alternatively, in your ''conf/local.php'' file, add or modify the line so it reads:
-<code apache>
+<code php>
-RewriteCond %{REQUEST_URI} !^/server-status$
+$conf['userewrite'] = 2;
 </code>
-or creating an empty server-status file in dokuwiki root folder where doku.php is located. See forum post [[http://forum.dokuwiki.org/post/32858 | Apachectl status is broken with dokuwiki]]
-== 404 not found error ==
-You may need to do [[https://stackoverflow.com/questions/8551740/centos-htaccess-not-being-read | this]].
-==== IIS (or Microsoft Azure Web App) ====
-Enable url rewriting and insert appropriate set of rules:
-<code xml>
-<rewrite>
-<rules>
-<rule name="rule 1C" stopProcessing="true">
-	<match url="^_media/(.*)" />
-	<action type="Rewrite" url="/lib/exe/fetch.php?media={R:1}" appendQueryString="true" />
-</rule>
-<rule name="rule 2C" stopProcessing="true">
-	<match url="^_detail/(.*)" />
-	<action type="Rewrite" url="/lib/exe/detail.php?media={R:1}" appendQueryString="true" />
-</rule>
-<rule name="rule 3C" stopProcessing="true">
-	<match url="^_export/([^/]+)/(.*)" />
-	<action type="Rewrite" url="/doku.php?do=export_{R:1}&amp;id={R:2}" appendQueryString="true" />
-</rule>
-<rule name="rule 4C" stopProcessing="true">
-	<match url="^$" />
-	<action type="Rewrite" url="/doku.php" />
-          <conditions>
-            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
-            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
-           </conditions>
-</rule>
-<rule name="rule 5C" stopProcessing="true">
-	<match url="(.*)" />
-	<action type="Rewrite" url="/doku.php?id={R:1}" appendQueryString="true" />
-          <conditions>
-            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
-            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
-          </conditions>
-</rule>
-<rule name="rule 6C">
-	<match url="^index.php$" />
-	<action type="Rewrite" url="/doku.php" />
-</rule>
-</rules>
-</rewrite>
-</code>
-**If you are using Azure Web App**, just put these lines under the <system.webServer> tags in web.config file (situated in wwwroot of your App).
-=== IIS 7.0 or greater ===
-IIS 7.0 and above can be extended with a the URL Rewrite module 2.0 available from Microsoft for both [[http://go.microsoft.com/?linkid=9722533|x86]] and [[http://go.microsoft.com/?linkid=9722532|x64]]
-Save the Apache rules above to a .htaccess file removing the "RewriteBase /dokuwiki" line. This will not be required as we will be adding the rules directly to the root of the wiki.
-In IIS Manager select your Wiki folder, and under IIS select "URL Rewrite" (if you had Manager open before installing, a refresh will be required)
-In the actions pane on the right hand side, choose "Import Rules"
-For your configuration file, select the .htaccess file and Import, this should give you 6 converted rules.
-Finally hit Apply in the Actions panel on the right hand side.
-Configure your Wiki to use .htaccess rules for rewrite and you should now be seeing your URLs rewritten.
-==== Nginx ====
-See [[http://nginx.org/|nginx]] [[http://wiki.nginx.org/|documentation]]. In the following example, our server root is /var/www, and we extract dokuwiki to /var/www/wiki.
-<code nginx>
-server {
-    listen 80;
-    server_name example.com www.example.com;
-    #maximum file upload size is 4MB - change accordingly if needed
-    client_max_body_size 4M;
-    client_body_buffer_size 128k;
-    root /var/www/wiki;
-    index doku.php;
-    location / { try_files $uri $uri/ @dokuwiki; }
-    location @dokuwiki {
-        rewrite ^/_media/(.*) /lib/exe/fetch.php?media=$1 last;
-        rewrite ^/_detail/(.*) /lib/exe/detail.php?media=$1 last;
-        rewrite ^/_export/([^/]+)/(.*) /doku.php?do=export_$1&id=$2 last;
-        rewrite ^/(.*) /doku.php?id=$1&$args last;
-    }
-    location ~ \.php$ {
-        if (!-f $request_filename) { return 404; }
-        include fastcgi_params;
-        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
-        fastcgi_param REDIRECT_STATUS 200;
-        fastcgi_pass 127.0.0.1:9000;
-    }
-}
-</code>
-=== Notes ===
-If using https the HTTPS server variable has to be set to allow proper linking in dokuwiki. This can be done
-in the server section with:
-<code nginx>
-fastcgi_param HTTPS on;
-</code>
-The ''last'' keyword of rewrite rules before location setup make sure that rewrite only happens once. You should replace all /dokuwiki/ appeared above to you wiki directory relative to web server root directory.
-If you are copy-pasting these configs, make sure you are adding locations to secure some of the directories as described on [[security|Security]] page.
-==== httpd (OpenBSD) ====
-See also [[https://man.openbsd.org/httpd.conf.5|httpd documentation]]. By default the server root is /var/www and dokuwiki is in /var/www/dokuwiki
-<code autoconf>
-server "default" {
-  listen on egress port 443
-  root "/dokuwiki"
-  directory index doku.php
-  # Set according to upload_max_filesize and post_max_size in php.ini
-  connection max request body 20971520
-  location "*.php"     { fastcgi socket "/run/php-fpm.sock" }
-  # Block access to non-public dirs
-  location "/data/*"   { block }
-  location "/conf/*"   { block }
-  location "/bin/*"    { block }
-  location "/inc/*"    { block }
-  location "/vendor/*" { block }
-  # URL rewrite rules
-  location match "/media/(.*)" {
-    request rewrite "/lib/exe/fetch.php?media=%1"
-  }
-  location match "/detail/(.*)" {
-    request rewrite "/lib/exe/detail.php?media=%1"
-  }
-  location match "/export/([^/]+)/(.*)" {
-    request rewrite "/doku.php?do=export_%1&id=%2"
-  }
-  location match "/(lib/.*)" {
-    request rewrite "/%1"
-  }
-  location match "/([^lib])" {
-    request rewrite "/doku.php?id=$DOCUMENT_URI&$QUERY_STRING"
-  }
-}
-</code>
-====== Option 2: DokuWiki ======
-In your conf/local.php file, add or modify the line so it reads:
-<code php>
-$conf['userewrite'] = 2;
-</code>
-This option won't need any webserver setup. However it relies on the PATH_INFO feature of the CGI standard as implemented by Apache. IIS is [[bug>718|known not to work]] with this setting. However, new IIS versions seem to work with this.
 ===== Clean PHP session ID =====
@@ Line 289: / Line 74: @@
 </code>
-====== Also see ======
+====== See Also ======
   * [[:tips:httpslogin|Rewrite rules for secure login]]
+  * [[https://stackoverflow.com/questions/9153262/tips-for-debugging-htaccess-rewrite-rules | Tips for debugging .htaccess rewrite rules]]