| 1 | TightURL |
| 2 | Installation |
| 3 | version 0.1.3.2 |
| 4 | |
| 5 | Installing TightURL |
| 6 | ------------------- |
| 7 | |
| 8 | 1. Untar the file: tar zxvf tighturl-0.1.3.2.tar.gz or |
| 9 | unzip the file: unzip tighturl-0.1.3.2.zip |
| 10 | |
| 11 | 2. Move the files in the directory to where you want to run |
| 12 | your installation of TightURL. |
| 13 | |
| 14 | 3. Rename tighturl.php to index.php if desired. (highly desirable!) |
| 15 | |
| 16 | 4. A. New installations should move the contents of the ./local directory |
| 17 | into the main TightURL directory. |
| 18 | B. Upgrades should review the contents of ./local and adjust existing |
| 19 | config file and templates as seen fit. Things probably won't work |
| 20 | correctly unless you modify the tighturl.config.inc in ./local with |
| 21 | your desired settings and use that. |
| 22 | |
| 23 | 5. New installations should create a MySQL database and user if |
| 24 | necessary. If you don't know how, (we were all beginners once) it |
| 25 | goes something like this: |
| 26 | mysql -u root -p |
| 27 | Enter password: ********** |
| 28 | mysql> create database tighturl; |
| 29 | mysql> quit |
| 30 | |
| 31 | If you also need to add a MySQL user (you should never use "root"), |
| 32 | then before you quit MySQL, you should enter a command like this: |
| 33 | |
| 34 | mysql> grant all on dbname.* to dbuser@localhost identified by 'pass'; |
| 35 | |
| 36 | substituting the name of your database for "dbname", the name of the |
| 37 | MySQL user you want to create for "dbuser", and the desired password |
| 38 | in place of "pass". |
| 39 | |
| 40 | 6. Edit the config settings in tighturl.config.inc.php as needed. |
| 41 | New installs will need to change at least the MySQL database settings. |
| 42 | See 'Configuration Settings' below. |
| 43 | |
| 44 | 7. Run the script: tighturl-install.php |
| 45 | When this is done, you will need to remove or rename this script |
| 46 | before your TightURL installation will work. |
| 47 | |
| 48 | 8. If you can set a custom 404 page for your Web site/directory, you |
| 49 | can set it to tighturl/index.php and get shorter URLs. To take |
| 50 | advantage of this, set $FOFMethod=TRUE in tighturl.config.inc.php. |
| 51 | |
| 52 | 9. Change the $svcname in tighturl.config.inc.php if desired. |
| 53 | |
| 54 | 10. Edit the master site HTML template tighturl.tmpl if desired. |
| 55 | See 'TightURL Templates' below. |
| 56 | |
| 57 | 11. Edit the HTML sub-templates if desired. These are: |
| 58 | A. tighturl.main.tmpl : HTML shown for your TightURL homepage |
| 59 | B. tighturl.save.tmpl : HTML shown when a URL is saved |
| 60 | C. tighturl.help.tmpl : HTML shown for Help info (may not exist yet) |
| 61 | D. tighturl.faq.tmpl : HTML shown for FAQ (may not exist yet) |
| 62 | D. tighturl.blacklist.tmpl : HTML shown for blacklisted URL submissions |
| 63 | D. tighturl.policy.tmpl : HTML shown for URL submissions that violate |
| 64 | your local policy. |
| 65 | |
| 66 | See 'TightURL Templates' below for more information. |
| 67 | |
| 68 | Configuration Settings |
| 69 | ---------------------- |
| 70 | |
| 71 | These are the configuration (variables) settings that can and should |
| 72 | be changed in tighturl.config.inc.php : |
| 73 | |
| 74 | MySQL: |
| 75 | $dbhost : DNS name of your MySQL server |
| 76 | $dbuser : MySQL user name |
| 77 | $dbpass : password for MySQL user name |
| 78 | $dbname : database containing TightURL's table |
| 79 | $dbtable : name of TightURL's table |
| 80 | |
| 81 | Operating modes: |
| 82 | $FOFMethod : Use 404-Method or mod_rewrite to compress TightURLs |
| 83 | 0 (FALSE) = full URL path (not compressed) TightURLs |
| 84 | 1 = 404-Method compressed TightURLs |
| 85 | 2 = mod_rewrite compressed TightURLs |
| 86 | |
| 87 | URIBL variables: |
| 88 | $uribl : Array of URIBLs to check |
| 89 | $uriblurl : Array of Web sites corresponding to URIBLs checked |
| 90 | |
| 91 | Text strings and style variables: |
| 92 | $svcname : One-word name for your TightURL service |
| 93 | $verbtext : One-word name for the act of tightening URLs |
| 94 | $pasttext : Past-tense name for a tightended URL |
| 95 | $tagline : "tag line" for your TightURL service |
| 96 | $headcolor : Color for the TightURL <H1> HTML header |
| 97 | $tablecolor : Color for the table the URL input field appears in |
| 98 | $copystart : 4-digit year of start of your copyright on your content. |
| 99 | defaults to current year if not given. |
| 100 | |
| 101 | NEVER CHANGE SETTINGS IN tighturl.php OR YOU WILL LOSE YOUR CHANGES |
| 102 | any time you upgrade to a newer version of TightURL. Always put your |
| 103 | configuration settings in tighturl.config.inc.php where they will |
| 104 | survive upgrades. Values in tighturl.config.inc.php override the |
| 105 | defaults (garbage) in tinyurl.php . |
| 106 | |
| 107 | Reserved URLs |
| 108 | ------------- |
| 109 | |
| 110 | Because we use Base-36 numbers as TightURL IDs, as time goes on, |
| 111 | certain desirable URLs will be issued that we might want to keep |
| 112 | for ourselves. |
| 113 | |
| 114 | For instance, the letters 'faq' are well-understood around the Internet |
| 115 | to mean "Frequently Answered Questions". We might want to use the URL |
| 116 | http://example.com/faq to point to our FAQ page, rather than issue it |
| 117 | as a regular TightURL to a random visitor. Reserved URLs allow you to |
| 118 | specify Base-36 IDs that should never be issued as TightURLs. |
| 119 | |
| 120 | There are two kinds of Reserved URLs. External (implicit) and Internal |
| 121 | (explicit) Reserved URLs. |
| 122 | |
| 123 | External Reserved URLs: |
| 124 | |
| 125 | Any URL which exists in your Web space will be served up by |
| 126 | your Web server, and not TightURL. For this reason, any URL |
| 127 | reasonably within your TightURL ID space that you want to use |
| 128 | with your TightURL site itself should be reserved so that you |
| 129 | don't issue a TightURL to anyone that won't actually work. |
| 130 | |
| 131 | For example, if you have a directory named: /www/example.com/faq |
| 132 | your Web server will attempt to serve index.html from within |
| 133 | that directory, and TightURL will never even see the request. |
| 134 | This kind of reservation is implicit, and TightURL must be |
| 135 | made aware of it. |
| 136 | |
| 137 | Internal Reserved URLs: |
| 138 | |
| 139 | Any URL which does not exist in your Web space but is Reserved |
| 140 | within TightURL will cause TightURL to look for a correspondingly |
| 141 | named TightURL Template, and serve that. If the template does |
| 142 | not exist, a 404 error is generated. |
| 143 | |
| 144 | For example, if you have reserved the ID 'faq', and TightURL |
| 145 | sees a request for this reserved ID, it will attempt to open a |
| 146 | template named tighturl.faq.tmpl and return that to the browser. |
| 147 | |
| 148 | It is VERY IMPORTANT that you decide what your Reserved URLs will be |
| 149 | before your TightURL service is put into operation, or else you run |
| 150 | the risk of wanting to reserve a URL that's already been issued as |
| 151 | a TightURL to someone. For example, by the time you've issued your |
| 152 | 19826th TightURL, you will have lost the opportunity to use 'faq' as |
| 153 | a Reserved URL, because decimal (Base-10) number '19826' is number |
| 154 | 'faq' in sexigesimal (Base-36). |
| 155 | |
| 156 | Reserving URLs: |
| 157 | |
| 158 | To reserve a URL, add it to the configuration array $ReservedURL . |
| 159 | The following URLs are reserved by default: |
| 160 | |
| 161 | faq, help, code, source, docs, cvs, arch, url, |
| 162 | about, admin, setup, svn |
| 163 | |
| 164 | There is little point in reserving URLs larger than 5 charcters long. |
| 165 | The first 6 character ID is '100000' sexigesimal, which would be far |
| 166 | past your 60 millionth TightURL issued. Since each additional Reserved |
| 167 | URL adds a little more processing time, you don't want to add URLs |
| 168 | that will never be issued anyway. |
| 169 | |
| 170 | TightURL presently uses the ID "api" with the template that describes |
| 171 | how to use the TightURL API. It would be the 13878th TightURL in the |
| 172 | system, which can easily be achieved on a moderately-used corporate- |
| 173 | wide TightURL installation. |
| 174 | |
| 175 | TightURL Templates |
| 176 | ------------------ |
| 177 | TightURL supports a simple variable-substitution templating system with |
| 178 | one level of template nesting. |
| 179 | |
| 180 | The outer template is *always* the main site template, tighturl.tmpl . |
| 181 | This template controls your site design and is *always* used to generate |
| 182 | output pages to the browser. |
| 183 | |
| 184 | The inner template is *always* one of the following sub-templates |
| 185 | (or no sub-template): |
| 186 | tighturl.main.tmpl : HTML shown for your TightURL homepage |
| 187 | tighturl.save.tmpl : HTML shown when a URL is saved |
| 188 | tighturl.help.tmpl : HTML shown for Help info (may not exist yet) |
| 189 | (none) : No inner template. |
| 190 | |
| 191 | Please note that many screens are generated using only the main site |
| 192 | (outer) template. All error screens are generated this way. |
| 193 | |
| 194 | The variables supported by TightURL Templates are: |
| 195 | |
| 196 | $HTML : In the innermost or only template, replaced by a HTML |
| 197 | message from TightURL. In an outer template, it is |
| 198 | replaced by contents of the inner (sub-)template. |
| 199 | You should never remove this variable from a template. |
| 200 | $PARM : Parameter when 404-Method not used. |
| 201 | $URL : Replaced by browser submitted URL. |
| 202 | $URLLEN : Replaced by lenghth of the submitted URL. |
| 203 | $TIGHTURL : Replaced by TightURL generated by the submission. |
| 204 | $TIGHTURLLEN : Replaced by length of the generated TightURL. |
| 205 | $DIFF : Replaced by difference in length between URLs. |
| 206 | $INPUT : Replaced by submitted URL for use when there has |
| 207 | been an error detected in the input. |
| 208 | $SVCNAME : Replaced by name chosen for your TightURL service. |
| 209 | $HEADCOLOR : Replaced by color value chosen for <H1> HTML tags. |
| 210 | $TABLECOLOR : Replaced by color value chosen for the table. |
| 211 | $TAGLINE : Replaced by "tag line" for your TightURL service. |
| 212 | $CPASTTEXT : Replaced by capitalized past tense description of |
| 213 | tightened URLs. |
| 214 | $PASTTEXT : Same as $CPASTTEXT, but first letter not capitalized. |
| 215 | $CVERBTEXT : Replaced by capitalized verb description of your |
| 216 | TightURL service. |
| 217 | $VERBTEXT : Same as $CVERBTEXT, but first letter not capitalized. |
| 218 | $COPYRIGHT : Replaced by generated copyright string created from |
| 219 | $copystart config value and current year. |
| 220 | $URIBLS : Replaced by HTML showing URIBLs being checked. |
| 221 | $HOST : Replaced by hostname of Web site. |
| 222 | $SELF : Replaced by the URL path to the TightURL script. |
| 223 | $BBSTATS : Replaced by Bad Behavior stats when BB2 is enabled. |
| 224 | $TIGHTURLVER : Replaced by the TightURL running version number. |
| 225 | |
| 226 | TightURL Operating Modes |
| 227 | ------------------------ |
| 228 | |
| 229 | TightURL supports three distinct "operating modes". These are known as |
| 230 | "basic", "mod_rewrite", and "404 Method". You want to avoid changing your |
| 231 | operating mode later, as changes to or from basic mode will cause all your |
| 232 | URLs to change. Changes between mod_rewrite and the 404 Method do not |
| 233 | result in changes to your URLs, but your operating mode is something you |
| 234 | should choose carefully and then stick with. |
| 235 | |
| 236 | Using basic mode |
| 237 | ---------------- |
| 238 | |
| 239 | This operating mode produces URLs that follow this pattern: |
| 240 | http://example.com/?i=id or http://example.com/yoursite/?i=id |
| 241 | |
| 242 | No changes to httpd.conf or .htaccess are required for basic mode, but |
| 243 | this produces slightly longer and more inconvenient to type URLs. If you |
| 244 | can use mod_rewrite or the 404 Method, it is highly recommended that you |
| 245 | do so. |
| 246 | |
| 247 | |
| 248 | Using mod_rewrite with Apache |
| 249 | ----------------------------- |
| 250 | |
| 251 | PLEASE NOTE: There was a longstanding bug in Apache mod_rewrite that |
| 252 | probably makes TightURL or anything like it unable to work except with |
| 253 | what are still very recent versions of Apache. |
| 254 | https://issues.apache.org/bugzilla/show_bug.cgi?id=34602 |
| 255 | |
| 256 | Users are encouraged to use "404 Mode", and especially in the event |
| 257 | their Apache version has the bug shown above. |
| 258 | |
| 259 | |
| 260 | This operating mode produces URLs that follow this pattern: |
| 261 | http://example.com/id or http://example.com/yoursite/id |
| 262 | |
| 263 | TightURL can be used with mod_rewrite by adding the following lines to |
| 264 | httpd.conf or if you can't modify httpd.conf, you can use .htaccess : |
| 265 | |
| 266 | <IfModule mod_rewrite.c> |
| 267 | RewriteEngine On |
| 268 | RewriteRule ^view/([a-z0-9-]+)/?$ index.php?v=$1 [NC,L] |
| 269 | RewriteRule ^([a-z0-9-]+)/?$ index.php?i=$1 [NC,L] |
| 270 | </IfModule> |
| 271 | |
| 272 | If you change the parameters (form variables) from "i" for the TightURL ID |
| 273 | to look up, and "v" for the TightURL ID to preview, then you'll need to |
| 274 | adjust these lines accordingly. |
| 275 | |
| 276 | Be aware that http.conf is read once when the Web server is started or |
| 277 | reloaded, but .htaccess must be read and parsed for *every request*, so |
| 278 | you always want to use http.conf over .htaccess whenever possible. |
| 279 | |
| 280 | |
| 281 | Using "The 404-Method" with Apache |
| 282 | ---------------------------------- |
| 283 | |
| 284 | This operating mode produces URLs that follow this pattern: |
| 285 | http://example.com/id or http://example.com/yoursite/id |
| 286 | |
| 287 | The "404-Method" refers to instructing your Web server to direct all |
| 288 | requests that generate a "Not found" error (which is an HTTP error code |
| 289 | 404) to the TightURL script. By doing this, TightURL will run for URLs in |
| 290 | your TightURL site that don't exist, such as would be the case for |
| 291 | http://example.com/tighturl.php/xxyy |
| 292 | |
| 293 | The xxyy is a TightURL ID number, not an actual Web page in your site. By |
| 294 | sending non-existent page requests to the TightURL script, you can look up |
| 295 | those IDs and issue an HTTP Redirect without the need for mod_rewrite. |
| 296 | |
| 297 | To use the 404-Method, set $FOFMethod=1 in tighturl.config.inc.php. |
| 298 | |
| 299 | Using .htaccess |
| 300 | --------------- |
| 301 | |
| 302 | Then put this in your .htaccess file: |
| 303 | |
| 304 | ErrorDocument 404 /index.php |
| 305 | |
| 306 | This change should take effect immediately after saving .htaccess . |
| 307 | If it doesn't work, make sure you have AllowOverride FileInfo on in the |
| 308 | directory you're running TightURL from. |
| 309 | |
| 310 | Using httpd.conf |
| 311 | ---------------- |
| 312 | |
| 313 | Alternatively to using .htaccess (and for improved performance), put the |
| 314 | following line in your httpd.conf in the appropriate Directory section |
| 315 | (and VirtualHost if applicable): |
| 316 | |
| 317 | ErrorDocument 404 /index.php |
| 318 | |
| 319 | You will need to reload your Apache configuration for this change to take |
| 320 | effect. |
| 321 | |
| 322 | See the Apache documentation for more information. |
| 323 | http://httpd.apache.org/docs/mod/core.html#errordocument |
| 324 | http://httpd.apache.org/docs/mod/core.html#allowoverride |
| 325 | |
| 326 | |
| 327 | AntiAbuse: Generally if your web site is connected to the Internet and |
| 328 | and the TightURL library can make outbound network connections, you should |
| 329 | run with the antiabuse system turned on. When the antiabuse system is |
| 330 | turned off, virtually everything will be accepted into your database that |
| 331 | can be shortened. |
| 332 | |
| 333 | NetChecks: Generally if your web site is connected to the Internet and |
| 334 | and the TightURL library can make outbound network connections, you should |
| 335 | run with the netchecks system turned on. If your site has no connectivity |
| 336 | or ability to make outbound network connections, you should turn the |
| 337 | netchecks off. When netchecks are off, TightURL will not be able to resolve |
| 338 | URLs through redirections to their final destination, check for new versions |
| 339 | of TightURL, or check submitted URLs against URI blacklists. |
| 340 | |
| 341 | |
| 342 | Adding more URIBLs |
| 343 | ------------------ |
| 344 | |
| 345 | In the event other URIBLs beside SURBL become available, and you wish |
| 346 | to check those also, edit $uribl and $uriblurl in |
| 347 | tighturl.config.inc.php . |
| 348 | |
| 349 | To add a new URIBL named uribl.example.com whose Web site is located |
| 350 | at http://www.example.com |
| 351 | |
| 352 | Change this: |
| 353 | |
| 354 | $uribl = array("multi.surbl.org"); |
| 355 | $uriblurl = array("www.surbl.org"); |
| 356 | |
| 357 | To this: |
| 358 | |
| 359 | $uribl = array("multi.surbl.org","uribl.example.com"); |
| 360 | $uriblurl = array("www.surbl.org","www.example.com"); |
| 361 | |
| 362 | You can add as many URIBLs as you want this way. |
| 363 | |
| 364 | Squeezing Your Base URL Down to the Smallest Possible Size |
| 365 | ---------------------------------------------------------- |
| 366 | The "base URL" is the fixed portion of your TightURL URLs. This |
| 367 | would be everything up to the TightURL ID at the end of the URL. |
| 368 | The length of the TightURL ID will start out at 1 character and may |
| 369 | get up to 6 characters after tens of millions of TightURLs have been |
| 370 | created in your system. (Most TightURL installations are not |
| 371 | expected to get into the tens of thousands, let alone tens of |
| 372 | millions) Because the ID is at most 6 characters, the most |
| 373 | important thing you can do to get the shortest URL possible is to |
| 374 | "squeeze" as many characters out of the base portion of the URL |
| 375 | as possible. |
| 376 | |
| 377 | The following URL is "unfortunately long", but should still allow |
| 378 | you to create tens of millions of TightURLs that can be used without |
| 379 | wrapping in most e-mail programs. It is 72 characters long: |
| 380 | |
| 381 | http://www.a-really-quite-long-name.com/~example01/tighturl.php?i=abcdef |
| 382 | |
| 383 | This URL is not only unfortunately long, it is unnecessarily long |
| 384 | as well. The following optimizations can be attempted: |
| 385 | |
| 386 | 1. Drop the "www." |
| 387 | 2. Rename tighturl.php to something shorter. |
| 388 | 3. Rename tighturl.php to index.php and put it in a 1-character subdir. |
| 389 | |
| 390 | If optimizations 1 and 3 are successfully applied, we get a 58 |
| 391 | character URL (14 characters shorter): |
| 392 | |
| 393 | http://a-really-quite-long-name.com/~example01/t/?i=abcdef |
| 394 | |
| 395 | A more optimistic domain name (39 characters): |
| 396 | |
| 397 | http://example.com/~example/t/?i=abcdef |
| 398 | |
| 399 | Ideal scenario with own domain (29 characters): |
| 400 | |
| 401 | http://tighturl.com/?i=abcdef |
| 402 | |
| 403 | If you are able to use Mod_Rewrite or the 404-Method as shown |
| 404 | above, you can also drop the "?i=" portion of the URL, saving |
| 405 | another 3 characters. |
| 406 | |
| 407 | Mod_Rewrite or 404-Method scenario (26 characters): |
| 408 | |
| 409 | http://tighturl.com/abcdef |
| 410 | |
| 411 | This also works with the "unfortunately long" URL, bringing |
| 412 | it down to 56 characters: |
| 413 | |
| 414 | http://a-really-quite-long-name.com/~example01/t/abcdef |
| 415 | |
| 416 | ******************************************************************************** |
| 417 | |
