====== URL Rewriting ====== By default, DokuWiki does no URL rewriting, resulting in URLs like this: %%http://example.com/doku.php?id=page%% These URLs are considered ugly and are not indexed well by some search engines. The solution is to enable URL rewriting, which is disabled by default. DokuWiki supports two methods for URL rewriting through the [[config:userewrite]] option. One utilizes the rewriting capabilities of the webserver; the other one handles rewritten URLs inside DokuWiki. The table below summarizes these options. ^ Value ^ Info ^ Example URL ^ | 0 | No URL rewriting is used. This is the default. | %%http://example.com/dokuwiki/doku.php?id=wiki:syntax%% | | 1 | Rewriting is handled by the webserver. | %%http://example.com/dokuwiki/wiki:syntax%% | | 2 | Rewriting is done by DokuWiki. | %%http://example.com/dokuwiki/doku.php/wiki:syntax%% | 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. **Nota Bene** In all the following examples, add or modify the line in your conf/local.php file so it reads: | $conf['userewrite'] = N; | where N is the number 1 or 2. (No need to do anything if you want the option 0.) ===== Option 0: editing php code and filenames ===== This is not about URL rewrite but when you need to replace the "doku.php" for local reasons (it doesn't sound so well in all languages). I performed it with Apache server but I think it is similar or even the same with others. * If you want: Change folder name (default is 'dokuwiki' - for example: 'mywiki'). No DokuWiki setting is required. * If you want: Change default filename 'doku.php' (for example: 'start.php') - Update filename in file 'index.php' (file in dokuwiki folder)header("Location: start.php"); - Update filename in '/inc/init.php' '[[devel:preload|inc/preload.php]]' (path in dokuwiki folder). Create the file if it does not exists. ''inc/preload.php'' is not part of default dokuwiki, so it won't be overwritten by a dokuwiki upgrade. That's all! If you find one more php file to edit, note it here, please. Regards Bronek ===== Option 1: web server ===== ==== Apache ==== 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]]. The module is enabled in httpd.conf with the following line (make sure it is not commented out): LoadModule rewrite_module modules/mod_rewrite.so On many kinds of Linux (Ubuntu, Debian, etc) you may enable mod_rewrite with: sudo a2enmod rewrite The setup of module mod_rewrite is done through so called **rewrite rules**, which can be either defined directly in the server's main config or in a .htaccess file located in DokuWiki's main directory. DokuWiki comes with an .htaccess.dist file which contains the needed rewrite rules for mode 1, but commented. Just copy the file to .htaccess (in the folder that contains doku.php, caveat Debian users((In Debian 6 at least you do not have to copy anything. ''/usr/share/dokuwiki/.htaccess'' links to ''/etc/dokuwiki/.htaccess''. So there is no caveat anymore.))) and uncomment the lines to enable rewriting. RewriteEngine on RewriteBase /dokuwiki 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 On the line ''RewriteBase /dokuwiki'', you need to replace the ''/dokuwiki'' with whatever directory you use in your URL to get to the wiki. Say that your normal (Option 0) URL is http://www.whatever.com/projects/documents/doku.php . You will need to set the above line to ''RewriteBase /projects/documents''. However sometimes this line is not needed at all. === Some Notes === .htaccess files are only honored if Apache's main config allows it. Many default Apache installs don't. To enable them try adding the following to the httpd.conf: AllowOverride AuthConfig FileInfo Limit PS: The above will ''AllowOverride'' only what is needed for the default config to work. If it does not work for you, try using ''AllowOverride All'' Alternatively you may simply specify the rewrite rules mentioned above directly in the httpd.conf: RewriteEngine on ... rewrite rules here ... You may have to restart Apache for these changes to work. Some users reported getting a "403 - Forbidden" Error after enabling the rewrite support. Setting the FollowSymlinks option seems to solve the problem: Options +FollowSymlinks RewriteEngine on ...etc. The rewrite rules given above will map all non-existing files and directories to the DokuWiki main dispatcher, this may apply to virtual mappings (aliases). Some host sites map web access statistics to a virtual /stats directory. To be able to still access these virtual directories, you need to exclude them in the rewrite conditions. Example: ... RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteCond %{REQUEST_URI} !^/stats/(.*)$ ... If you're running without a RewriteBase, perhaps because you're hosting under a dedicated VirtualHost, you must modify the rewrite rules accordingly. RewriteRule ^/_media/(.*) /lib/exe/fetch.php?media=$1 [QSA,L,R] RewriteRule ^/_detail/(.*) /lib/exe/detail.php?media=$1 [QSA,L,R] RewriteRule ^/_export/([^/]+)/(.*) /doku.php?do=export_$1&id=$2 [QSA,L] RewriteRule ^/$ /doku.php [L] RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-f RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-d RewriteRule (.*) /doku.php?id=$1 [QSA,L] Each RewriteRule stanza must have a leading slash included, or Apache will return a 400 response code. You may need to change If you have a **''robots.txt''** and/or **''sitemap.xml''** file in your document root (for the Google bot) then you must exclude these files from rewriting in your ''.htaccess'' file: RewriteCond %{REQUEST_FILENAME} !robots\.txt RewriteCond %{REQUEST_FILENAME} !sitemap\.xml If the URLs are still not rewriting correctly, double-check that this setting is actually set correctly. In the config settings page, check that "Use nice URLs" is set to ".htaccess" in your config settings. Or, double-check that $conf['userewrite'] is set to '1' in conf/local.php . ==== IIS ==== === URL Rewrite Module for IIS 7 (Microsoft's official) === [[http://learn.iis.net/page.aspx/737/url-rewrite-module-2/|URL Rewrite Module]] is a Microsoft-supported rewrite module that can be installed on IIS 7 and newer. Starting from version 2.0 it has a wizard that will convert .htaccess rules to its own format (it uses standard IIS configuration mechanism which stores the site-specific settings into a ''web.config'' file in the root folder). How to configure it for DokuWiki: - Make sure you have the .htaccess file configured as described for Apache above - Install URL Rewrite Module 2.0 from Microsoft's website http://www.iis.net/expand/URLRewrite. **Make sure you install the version 2.0** - it is a Release Candidate at the time of writing (January 2010). - In IIS Manager, navigate to the site that hosts DokuWiki and double-click "URL Rewrite" - In the right pane ("action pane"), find "Import Rules..." and click it - Select the .htaccess file and click Import - It may report an error that a RewriteBase rule is not supported. If you see this error, comment out the line in htaccess rewrite rules and run the import again - If the import succeeded, click Apply in the actions pane - In your DokuWiki configuration, set [[config:userewrite]] to 1 (in the web UI, it will be seen as ".htaccess") This procedure worked on my installation where DokuWiki was installed in the website root. I don't know for sure if these steps are enough if DokuWiki is installed in a subfolder (like ''/sample/documentation'') but in principle, URL Rewrite module supports DokuWiki and for my scenario, it was able to convert .htaccess without any problems. === ISAPI Rewrite Lite == IIS doesn't come standard with a rewrite module. I used [[http://www.isapirewrite.com/|ISAPI Rewrite Lite]] (free) successful with these rewrite rules (see the file ''%%C:\Program Files\Helicon\ISAPI_Rewrite\httpd.ini%%''): # Dokuwiki rules # Fix RSS Feeds RewriteRule ^(/wiki/)feed.php $1/feed.php [I,L] RewriteRule ^(/wiki/)feed.php\?(.*) $1/feed.php\?mode=$2&$3 [I,L] RewriteRule ^(/wiki/)_media/(.*)\?(.*) $1lib/exe/fetch.php\?media=$2&$3 [I,L] RewriteRule ^(/wiki/)_detail/(.*)\?(.*) $1lib/exe/detail.php\?media=$2&$3 [I,L] RewriteRule ^(/wiki/)_detail/(.*) $1lib/exe/detail.php\?media=$2 [I,L] RewriteRule ^(/wiki/)_export/([^/]+)/(.*) $1doku.php?do=export_$2&id=$3 [I,L] RewriteRule (/wiki/) $1doku.php [I,L] RewriteRule ^(/wiki/)\?idx=(.*) $1doku.php\?idx=$2 [I,L] RewriteRule ^(/wiki/)lib/(.*) $1lib/$2 [I,L] RewriteRule ^(/wiki/)(.*)\?do=(.*) $1doku.php\?id=$2&do=$3 [I,L] RewriteRule ^(/wiki/)doku.php\?id=(.*) $1doku.php\?id=$2 [I,L] RewriteRule ^(/wiki/)(.*) $1doku.php\?id=$2 [I,L] # this rule fixes a problem to see the old revisions RewriteRule ^(/wiki/)(.*)\?(.*) $1doku.php\?id=$2&$3 [I,L] # Diff still broken unless none is selected under 'use nice URL' options. You can still enter and link to nice URLs but the DokuWiki program will use normal naming. For all lines with ''RewriteRule ^(/wiki/)'', you need to replace the ''(/wiki/)'' with whatever directory you use in your URL to get to the wiki. Say that your normal (Option 0) URL is http://www.whatever.com/projects/documents/doku.php . You will need to set the above line to ''^(/projects/documents/)''. === Ionics Isapi Rewrite Filter === It is also possible to use [[http://www.codeplex.com/IIRF|Ionics Isapi Rewrite Filter]], which is free and open-source. IterationLimit 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 [QSA,L] # infinite redirect fix RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^/(.*)/$ /doku.php?id=$1 [QSA,L] # end fix RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^/(.*) /doku.php?id=$1 [QSA,L] ==== Lighttpd ==== Assuming you have followed [[:install:lighttpd|instructions]] for how to set up dokuwiki under lighttpd. If you haven't, define var.dokudir as shown in the example. # rewrites for dokuwiki $HTTP["url"] =~ "^" + var.dokudir { index-file.names = ("doku.php") } url.rewrite = ( "^" + var.dokudir + "/lib/.*$" => "$0", "^" + var.dokudir + "/_media/(.*)?\?(.*)$" => var.dokudir + "/lib/exe/fetch.php?media=$1&$2", "^" + var.dokudir + "/_media/(.*)$" => var.dokudir + "/lib/exe/fetch.php?media=$1", "^" + var.dokudir + "/_detail/(.*)?\?(.*)$" => var.dokudir + "/lib/exe/detail.php?media=$1&$2", "^" + var.dokudir + "/_detail/(.*)?$" => var.dokudir + "/lib/exe/detail.php?media=$1", "^" + var.dokudir + "/_export/([^/]+)/(.*)\?(.*)$" => var.dokudir + "/doku.php?do=export_$1&id=$2&$3", "^" + var.dokudir + "/_export/([^/]+)/(.*)" => var.dokudir + "/doku.php?do=export_$1&id=$2", "^" + var.dokudir + "/doku.php.*" => "$0", "^" + var.dokudir + "/feed.php.*" => "$0", "^" + var.dokudir + "/(.*)\?(.*)" => var.dokudir + "/doku.php?id=$1&$2", "^" + var.dokudir + "/(.*)" => var.dokudir + "/doku.php?id=$1" ) Enable the rewrite module in lighttpd.conf by adding "mod_rewrite" in server.modules. An example config can be seen [[:install:lighttpd_config_example|here]]. ==== Nginx ==== Nginx is a very fast and stable httpd, see more about [[http://nginx.org/|nginx project]], and an English [[http://wiki.nginx.org/|wiki]]. In the following example, our server root is /var/www, and we extract dokuwiki to /var/www/dokuwiki. For NGINX 0.7.65 or later ( [[http://wiki.nginx.org/Dokuwiki|config source]] ) server { server_name wiki.domain.tld; root /var/www/dokuwiki; location / { index doku.php; 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 last; } location ~ \.php$ { include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_pass unix:/tmp/phpcgi.socket; } } For NGINX 0.6.x or later (tested up to 0.7.65) 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 index.html index.php; location / { if (-f $request_filename) { break; } if (!-f $request_filename) { #dokuwiki is installed in the root of the site rewrite ^/(.*)?(.*) /doku.php?id=$1&$2 last; rewrite ^/$ /doku.php last; break; } } #dokuwiki is installed in the root of the site 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; location ~ \.php$ { fastcgi_pass phpfcgi; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } } For nginx 0.7.27 or later (with try_files support) 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; } } === Notes === Nginx has complete support for fastcgi, please reference [[http://wiki.codemongers.com/NginxHttpFcgiModule|nginx fastcgi]] document to fit your setup. If using https the HTTPS server variable has to be set to allow propper linking in dokuwiki. This can be done in the server section like this: server { listen 443; ... location ~ .php$ { ... include fastcgi_params; ## sets $_SERVER['HTTPS'] fastcgi_param HTTPS on; } 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. ===== Option 2: DokuWiki ===== In your conf/local.php file, add or modify the line so it reads: | $conf['userewrite'] = 2; | 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((See [[#Discussion]])). IIS6 (MS Server 2003) works pretty fine, when ''basedir'' is set to ''/''. Using Apache's **Alias directive** with this option can lead to severe headaches and broken wiki! <= A patch which should solve this problem is available here: [[https://www.trg-oha.de/~sstrickroth/dokuwiki-alias.patch]] ===== Clean PHP session ID ===== Despite using "clean" URLs you may encounter a "DokuWiki" parameter in the URL looking like this: PHP session ID: http://example.com/example?DokuWiki=c81a95369a66576982119e2a60b557a5 This parameter is the PHP session ID and gets added by PHP automatically. It's completely unrelated to rewriting. To avoid it you can force PHP to always use cookies for sessions by setting the ''session.use_only_cookies'' option for PHP. This is usually done in the php.ini config file (when using a web hoster check their support page if and how you can edit these values): session.use_only_cookies=1 If session id still work try: session.use_trans_sid=0 When your PHP is used as Apache module you may be able to tweak these values using a .htaccess file using the following syntax: php_flag session.use_only_cookies on php_flag session.use_trans_sid off If you cannot use either of these solutions (many web hosts prevent editing php.ini and the use of php_flag in .htaccess), you will need to edit conf/local.php. Note that the above settings cannot be changed using ini_set() since PHP version 4.2.3, so the **only** way to do this is to use ini_set('url_rewriter.tags', ''); > My problem was that my **session.cookie_domain** was incorrectly set (I'm doing virtual hosting, and the domain name was incorrect). I added php_value session.cookie_domain www.my.domain.com to the appropriate virtualhost in my httpd.conf (though .htaccess would probably work just as well), and the polluted URLs disappeared. Also, if you can't get to your php.ini or apache config, you should be able to use **ini_set('PHP variable', 'value');** to the same effect (it seems that conf/local.php is a good place to put this, as the file is included before the session is started). > In my case, FastCGI was causing session IDs to appear. Disabling it removed them. ====== Also see ====== * [[:tips:httpslogin|Rewrite rules for secure login]] ====== Discussion ====== * I'm using IIRF under IIS6 and the search box always redirected me back to /doku.php. I'm not sure if it's just my config, but the way I fixed it was to add the rule ''RewriteRule ^/\?(.*) /doku.php?$1 [QSA,L]'' underneath the ''_export'' rule. * Please note that it took me a few hours to figure out all by myself that I needed to add $conf['userewrite'] = 1; in my conf/local.php file. I almost erased my Dokuwiki installation because of those two little missing details. --- //bstp 2010-11-26// * Even when using above configuration with Apache, often the URL becomes example.com/doku.php, no matter at what page you are. I could not find a solution to that. * It's an implementation issue, not a rewriting problem. --- //BlackFog 2007-12-19 15:42// * Option = 2 works with IIS 6 (Windows 2003) and current nightly build if ''basedir'' is set. --- //BlackFog 2007-12-19 15:42// * For Option = 2, it seems that we need to specify the value of ''basedir'' no matter which system we are using (Apache or IIS, etc); even when ''doku.php'' is just in the root dir we still need to specify ''basedir'' as ''/'' --- //[[xie@yihui.name|Yihui Xie]] 2008/05/28 20:09// * For a long time I used DokuWiki (2) rewrite option, and now there are some links like ''.../wiki/doku.php/...'' spread through the internet. If now I'll use ''.htaccess'' rewrite method (1), which is discussed here, all those old links with ''doku.php'' will become invalid. Is it possible to add some rules so that old links were still valid? If yes, please, explain how can it be done. * The solution was to add ''RewriteRule doku.php/(.*) doku.php?id=$1 [QSA,L]'' right after ''RewriteRule ^_export/([^/]+)/(.*) doku.php?do=export_$1&id=$2 [QSA,L]'' line. * Using rewrite rules for nginx that are presented breaks retrieval of images from dokuwiki. It seems to be not using the default value of root: [error] 27613#0: *1 open() "/usr/local/nginx/html/wiki/lib/tpl/arctic/images/button-firefox.png" failed My solutions is to add the following to the nginx.conf: location /wiki/lib/ { root /var/www/path/to/site.../; } --- //thedimi.net 2009-03-06 00:00// * With IIS and Helicon Isapi_Rewrite, if DokuWiki is in the root, the code for httpd.ini should be (note the absence of the subdirectory and the fact that there are 2 lines for "_media" and not just 1 as mentioned in the code above): # Dokuwiki rules # Fix RSS Feeds RewriteRule ^(/)feed.php $1/feed.php [I,L] RewriteRule ^(/)feed.php\?(.*) $1/feed.php\?mode=$2&$3 [I,L] RewriteRule ^(/)_media/(.*)\?(.*) $1lib/exe/fetch.php\?media=$2&$3 [I,L] RewriteRule ^(/)_media/(.*) $1lib/exe/fetch.php\?media=$2 [I,L] RewriteRule ^(/)_detail/(.*)\?(.*) $1lib/exe/detail.php\?media=$2&$3 [I,L] RewriteRule ^(/)_detail/(.*) $1lib/exe/detail.php\?media=$2 [I,L] RewriteRule ^(/)_export/([^/]+)/(.*) $1doku.php?do=export_$2&id=$3 [I,L] RewriteRule (/) $1doku.php [I,L] RewriteRule ^(/)\?idx=(.*) $1doku.php\?idx=$2 [I,L] RewriteRule ^(/)lib/(.*) $1lib/$2 [I,L] RewriteRule ^(/)(.*)\?do=(.*) $1doku.php\?id=$2&do=$3 [I,L] RewriteRule ^(/)doku.php\?id=(.*) $1doku.php\?id=$2 [I,L] RewriteRule ^(/)(.*) $1doku.php\?id=$2 [I,L] # this rule fixes a problem to see the old revisions RewriteRule ^(/)(.*)\?(.*) $1doku.php\?id=$2&$3 [I,L] # Diff still broken unless none is selected under 'use nice URL' options. You can still enter and link to nice URLs but the DokuWiki program will use normal naming.