The sh404 guide

1 - What sh404SEF for Joomla does
How the URL rewrite works
sh404 on a Windows IIS server
sh404 installation
Download the plugin
If sh404 doesn't work

Intro
This install guide for sh404 is an attempt to answer questions that people sometimes have when installing sh404 in Joomla, and also with upgrade issues. The more material available on these subjects the better, as users can more easily find what they need.

In many peoples' opinion the sh404SEF (search engine friendly) URL / Meta / Security solution is the best of many available for Joomla. It reconstructs URLs in a choice of formats, solves all sorts of problems inherent in dynamic URLs, allows custom per-page metadata, and adds some important security functions. It also handles many of the complex Joomla components faultlessly, with built-in plugins specially for them. The developer is one of the most active in the entire project, and his support is without equal.

Usually, the install will go without fault; but occasionally there are glitches. Here is a basic installation, upgrade and troubleshooting guide for the sh404 Joomla plugin.

Jooma 1.0 v Joomla 1.5

This guide is for both series. The troubleshooting and error solving sections here were written for the 1.0 series, and now that Joomla 1.5 has matured and become stable, will be expanded to cover both versions. In October '09 the 1.5 version will at last be 2 years old and the security issues should subside.

The sh404SEF version for Joomla 1.5 is still in beta but appears stable. By Oct. '09 both the CMS 1.5 series and the plugin should be fully stable. Read more about Joomla 1.0 vs Joomla 1.5 here.

News - sh404 goes commercial

September 8th 2009: Yannick finally ran out of time to run the sh404 project as a non-commercial extension, and it has been taken on by a commercial developer, although he will stay on as lead dev. Hopefully this will ensure the future of one of the most important Joomla plugins.  

The sh404 Guide

We have provided this simple and basic user guide for sh404SEF in order to help those with basic questions to find the answers quicker. The developer's website (see links at foot) is in the process of changing URLs, at 2009-09, so the situation there is a liitle fluid at present.   

1 - What sh404SEF for Joomla does

The plugin consists of two parts, a component and a module. The component provides the SEF URL rewrites, and the module does the new, unique meta - if you want this. Both parts have to be configured correctly or they won't work.

Note carefully that there is no default working arrangement directly after install.

Here are the 5 main function groups of sh404 :-

1. URL rewrites
Firstly, the most important thing this plugin does is to rewrite the long, raw dynamic URLs (page addresses) that the CMS produces. It changes them to people-friendly and search engine friendly alternatives that are much shorter, and also relevant to the page content. 

2. URL manager
It acts as an URL manager: multiple URLs are deleted; custom one-off URLs can be created; the default index page URL can be set; and so on. This is an important function.

3. Custom meta
The plugin also creates custom metadata. You can control several meta fields and input your own values on a per-page basis. That might of course be a major task on a big site - but the option is there if you need it. The sensible thing to do in such cases would be to at least give the main section and category pages - or whatever you call them - the full treatment, and fill the metatags.

4. Extra security layer
An extra security layer is provided, since the component has an excellent level of self-protection that extends to protecting the site as well. It rejects many forms of bot probes and worm attacks. For example it automatically 403s anything with script, html, or mosConfig in the URL request. A flooding defence is also built-in (see later).

5. Subsidiary functions
(a) H-level tags can be inserted as appropriate: headings can be given custom levels.
(b) Custom meta tags (or other text in fact) can be inserted into page meta headers.
(c) Unwanted standard CMS meta can be removed.

How the sh404 URL rewrite works

The rewrite component does this by using one of the following two methods:

1. It rewrites the URLs entirely within the application, without recourse to an htaccess file. No htaccess is needed but the URLs produced may not suit everyone. This is called the 'No htaccess Option'. This option can also be used successfully on IIS servers.

2. It works with the htaccess file to rewrite the URLs for best effect. This requires a custom htaccess file, different from the standard Joomla one. This is called the 'With htaccess Option'. This option cannot be used on IIS (Windows) servers, as there is no such facility.

Format 1: with /index.php/
In format (1), the URLs include an /index.php/ parameter in the middle of the filepath. Many don't like this, although it has absolutely no effect whatsoever on search results. For example we use the default URL format on this site and we have around 50 #1 or #2 global results on the largest search engine, and an uncounted number of #1 to #4 SERPs positions on all the search engines combined. The default URL format does not affect search results.

We use that version of the solution on this website because in theory it is a purer solution - working, as it should, entirely within the application and not using server resources (the server does not have to parse an entire htaccess file for every single request); and because it just allows us to forget that side of things and let it do its stuff. There's no htaccess file in the webroot with this method. As stated, it doesn't affect the search results or the usability of the site in any way - so as far as we are concerned it is perfectly acceptable. It's true that people tend to prefer the URLs without the extraneous index.php in the middle, so on clients' sites we tend to use the With htaccess Option.

Format 2: without /index.php/
In format (2) the URLs are of perfect form, and can be structured to suit your requirements: with or without a Section or Category parameter within the filepath, and with an html or htm extension. This requires the Joomla 3PD htaccess file, as supplied with the CMS for alternate use.

The supplied htaccess file contains sections for both situations. You 'comment-out' the section you don't want to operate.

You should delete or comment out the core SEF section and uncomment the 3PD section to enable the sh404 functionality.

sh404 on a Windows IIS server

The plugin is not supported when Joomla is running on an IIS server. That's for several reasons, one of which is that ultimate configuration of any URL setting is best done with an htaccess file - and there isn't one on Windows servers. Windows servers are a lost cause as far as management goes unless you have your own dedicated server, with full access to the IIS Manager. As that might apply to perhaps 0.001% of website owners, it's hardly a priority here. All problems can be resolved by changing to a normal server.

Nevertheless, there is now an sh404 setting that allows it to run on an IIS server: the 'No Htaccess Option'. If you select this in the master configs for sh404 then it will usually run OK. If it doesn't, then the developer cannot support Windows options but you'll find a board for this within the forum on the dev's site (see links at foot of page); other IIS server users will probably help you out.

iis joomla sh404sef mod_rewrite
This is a common query we get on the site so it has been included here verbatim (as normally written). There are many people who are looking for the answer to this. The question in plain language is, "How can I use mod_rewrite / htaccess with sh404 on a Windows server?".

The quick answer is that you can't use it: mod_rewrite is an Apache server tool, used in conjunction with the htaccess file. It is therefore part of a normal, standard server. An IIS server is a Windows server and not a normal, standard server. You are trying to run a PHP - MySQL CMS on a non-standard server (on which the software uses ASP not PHP) so there will be major problems. It will work - but only just. The best solution would be to change to a normal server (a LAMP server, aka Linux / Apache server).

Joomla with the sh404SEF component will run on a Windows server in basic, default mode. It cannot use any server tools or resources because a Windows server does not have any (that can be accessed by the webmaster). You will have an /index.php/ in the middle of the URL. There is nothing you can do about this.

ASP CMS are built and designed to run on a Windows server. They can use use the IIS Manager to rewrite the URLs. A PHP-MySQL CMS cannot do this is there is no way it can interact with the server. If you have a Windows server and for some reason cannot change - then get an ASP CMS like Umbraco. It is designed to run on a Windows server. Joomla is designed to run on a LAMP server.

sh404 Installation

Joomla has an SEF URL solution built in, and it's OK - but it's not precisely right, and so sh404 can be used to perfect the results.

The first thing to realise is that the sh404 plugin WILL NOT WORK unless:

1. SEF URLs are enabled in Joomla Global Config. 
2. "ON" is enabled within the sh404 component configuration.

This will enable default mode working, and the URLs will look like those on this site. If you want perfect-format URLs without the /index.php/ in the middle then you must:
 
1. Switch off sh404 if it is on.
2. Switch on SEF URLs in Joomla Global Config.
3. Change 'htaccess.txt' to '.htaccess' on the server, via FTP. Note the filename is DOT-htaccess.
4. Using this standard htaccess file with no alterations, check now that the Joomla core SEF URLs (ie without the sh404 plugin) ARE WORKING 100% - before you go any further.
5. If OK, then you can enable "ON" within the sh404 component configuration.
6. The htaccess file is then changed, for the 3PD SEF version.
7. Now you will see full SEF URLs.
8. They will still have some default parameters though. To get them perfect, you will need to enable the sh404 meta module (see later).

So from this we can clearly see that first we have to get Joomla working fine with the core SEF solution. It's pointless trying to troubleshoot the sh404 component if SEF URLs aren't working anyway!!

>> THIS IS THE PRIME CAUSE OF THE PROBLEM IN SH404 NO-GO SITUATIONS <<

So, if you like, you can go ahead and install sh404, then enable it and get it running. But if the htaccess format mode doesn't work for some reason - then your first task must be to...

### GET THE JOOMLA CORE SEF URL SOLUTION WORKING FIRST ###

sh404 SEF URL options

Again - a simplified explanation of the options:

• Option 1 - no htaccess
  The simplest option: install sh404SEF. In Joomla admin, turn on SEF URLs. In sh404 admin, turn on the component. URLs are now full-SEF, but with an /index.php/ in the middle - as on this site for example. Look up at the address bar above, at the top of the page on your browser, on this website.
  
  
• Option 2 - core SEF
  Next: ignore sh404 completely, just use the core CMS short-URL solution, with an htaccess file. Rename the file [htaccess.txt] to [.htaccess]. Check the core SEF script (the lines that make the basic 'within-Joomla' SEF URLs work) is uncommented and therefore operational, in the htaccess file in the webroot on the server. In the Joomla backend, turn on SEF URLs. URLs are now basic core SEF - this means they're better than the raw URLs, but hardly perfect. If this doesn't work you need help with your htaccess configs for the server your site is on.
  
  
• Option 3 - full SEF
  Finally: as above. Then, comment out the core SEF scripting in the htaccess file. Uncomment the 3PD scripting in the htaccess file. FTP it back up to the webroot. In sh404 admin, change the main functionality selector from 'no htaccess' to 'with htaccess'. (This selector is fairly well hidden or at least is not as prominent as it should be - since it is by far the most important config in the component.) Now, full SEF URLs are working - and you can have URLs of any shape, type, wording, or whatever else you want. It's probably the best SEF URL add-on solution anywhere in the world of CMS, since not only are the URLs perfect, but you can have any URL you like for any page.
  
  

How to install the sh404SEF plugin

Make sure you get the latest release for either the 1.0x series of Joomla, or the 1.5x series. See foot of page for links. 

Go into your admin backend and set files to CHMOD - that means, ensure the files and directories on the server can be written to, by setting the correct file permissions. Go here:
Admin backend - text menu list at top - Site - Global Config - the Server tab - File Permissions - and set up as follows.
Check the --Apply to existing files-- button on right.
Check the --Make unwriteable after saving-- button at top.
You can set the file permissions to whatever you want or find advised elsewhere. There is a conflict between 'opening them up' so they are easy to write to, and so that installs go without problem; and 'locking them down' so that script kiddies can't get into them.
You can try this version but if a plugin installation won't run correctly you'll need to open them more. On the other hand you could lock them down a bit more than this, after any install.
Don't forget to apply this to existing files.
Don't forget to make the main config file Unwriteable.
File permissions: 0754 (you'll have to tick / untick the boxes till you get this).
Directory (folder) permissions: 0754
You'll see plenty of contradictory advice on these, so go with whatever you want. If you can't install something, open it up more. After an install, close them up.
(And Register Globals, just below this, must be OFF).

Then go to: Installers - Components,
In the text box below, to the right, click the Browse button.
Locate the sh404SEF zip file you downloaded from the web (you don't unzip it first - it's unzipped up on the server).
Click Upload & Install.

All being well, after a minute or two you'll see a Success notice.
Hit Continue.

That's it for the basic install - if it fails, see the section below.

Troubleshooting sh404 if it doesn't work

sh404 install fails
If the installation fails, then we need to look at these options:

1. Did you install via the admin backend, using the correct zip file?
2. Is there an older version of sh404 (or any SEF) already there?
3. Are the server file permissions correct?
4. Are the Apache file ownership settings correct? **

** On Apache server there are two distinct sets of  'permissions': the file permissions and the file ownerships. On a dedicated server it is common to find the file ownership is wrong. This is a sign of an unmanaged server or one that has not been fully set up, since the owner is expected to do some of these tasks - or ask for them to be done. You can check file ownerships by using the FileZilla FTP client, which reports on this. If file ownerships are wrongly set then all sorts of issues occur. It is much less common to find this incorrect setting on a shared server since many CMS won't work correctly (especially their plugins). It may happen on a new server.

sh404 installs OK but doesn't work

If you find that the sh404 installation installs OK but doesn't work, here are your options.
 
1. Check all the configs are right:

• Joomla global

• sh404 main config

2. If still no luck, then get the core SEF working. If this runs OK we know that the problem is not with the server, or with the basic htaccess file. Then we can look at the 3PD htaccess file situation; a server issue maybe; then, possibly a compatibility issue with another plugin. Plugin issues are a big player here, and if you have got 20 big plugins like Community Builder and Remository, then things can get complicated.

The correct way to implement a large install like this is to do the SEF URL solution FIRST and the plugins AFTER.

However there is one important exception to this, as it won't work correctly: the Joomfish pre-translated content plugin needs installing before sh404.

Then, make sure to:

      >> GET THE JOOMLA CORE SEF SOLUTION WORKING FIRST <<
 


Part 2: >>> Install sh404Guide - 2   - The Guide, continued

Part 3:    Visual Guide to sh404 Metadata   - A step-by-step guide to enabling the metadata in sh404


We hope this tute helped you out - more info will be included as and when!
Tell us what you need to know and we'll include it. Use the forum.
sh404 has helped us a lot in our work - so we try to put something back.

sh404 related links

Note: at 2009-09-08 these URLs are dead or redirected. When the situation clarifies they will be corrected.

Developer's website:
http://extensions.siliana.com/forums/

Windows server forum:
http://extensions.siliana.com/forums/index.php?board=23.0

Download link for new sh404 versions:
http://joomlacode.org/gf/project/sh404sef/frs/