Correct [log type=error|debug] final newline behavior
[interchange.git] / UPGRADE
1 -----------------------------------------------------------------------------
2
3                 U P G R A D I N G     I N T E R C H A N G E
4
5
6 Interchange is designed to be drop-in compatible in its major version.
7 Briefly summarized, here's what you can expect when upgrading from the
8 following versions:
9
10  5.6.x -- Perl 5.8.8 or newer is now generally required to run Interchange.
11           See "Known Issues" below.
12
13  5.4.x -- A number of incompatible changes were made. Most of them will be
14           simple to deal with, but please consult the list below in the
15           "Known Issues" section. Your code will almost certainly fail to
16           work properly until you make the necessary changes described!
17
18  5.2.x -- There should be few to no compatibility issues in
19           upgrading from Interchange 5.2.x.
20
21  5.0.x -- There should be few to no compatibility issues in
22           upgrading from Interchange 5.0.x.
23
24  4.8.x -- There should be only a few issues in upgrading from 4.8.x; known
25           issues are shown below. The major change is in the admin UI,
26           and you will have a distinctly different look and feel 
27           in that area. Most people find it an improvement.
28           
29  4.6.x -- Upgrading from 4.6.x and before is problematic if you rely on
30           the admin UI -- particularly if you have customized it. The public-
31           facing side should be fairly straightforward to port. See
32           "UPGRADING FROM 4.6.x" below.
33
34  BEFORE 5.7.2 -- A security vulnerability has been found that allows
35           remote searching of any table in your database configured in
36           Interchange.  To fix this vulnerability, you may need to 
37           make some adjustments to your catalog.  See "REMOTE SEARCHING"
38           below.
39
40 INSTALLING INTERCHANGE IN THE SAME LOCATION
41 --------------------------------------------
42
43 NOTE:    All below procedures assume you have installed in
44          /usr/local/interchange -- substitute paths as appropriate.
45
46 WARNING: BACK UP EVERYTHING BEFORE YOU START!
47
48     1. Make a tar backup of your Interchange software directory, e.g.
49
50         tar czvf ~/ic_backup.tar.gz /usr/local/interchange 
51
52     2. Unpack the new version of the software to a temporary directory,
53        and change to that directory.
54
55         tar xzf interchange-5.x.x.tar.gz
56         cd interchange-5.x.x
57
58     3. You can see the section below, "TO TEST BEFORE YOU UPGRADE", if
59        you want to try it out before you switch your running catalog.
60
61     4. Install it to the same location as your current software:
62
63         ## Create the makefile
64         perl Makefile.PL
65
66         ## Make the software
67         make
68
69         ## Test -- if this fails, don't worry too much.
70         make test
71
72         ## Install the software
73         make install
74
75     5. You don't need to run makecat again!!!
76
77     6. Restart Interchange.
78
79 That's it. Verify your catalog's operation, and you are live.
80
81 ---------------------------------------------------------------------------
82
83                          K N O W N   I S S U E S
84
85
86 KNOWN ISSUES UPGRADING FROM 5.6.x
87
88 1. Perl 5.8.5 (unthreaded) or Perl 5.8.8 (threaded) or newer is now required.
89
90 2. The AdminUser configuration directive has been removed.
91
92 3. In PostgreSQL 8.3 many implicit type casts were removed, some of
93 which Interchange or your code may have relied on. You may find that some
94 features in the Standard demo and some Interchange core SQL may not work
95 with PostgreSQL 8.3 or newer, though recent testing with PostgreSQL 9.2
96 did not reveal any problems.
97
98 If you run into problems, the easiest way to get things working is
99 to manually put back any removed casts that you need. The included
100 eg/pg83-implicit-casts.sql script fixes the known problems with the
101 Standard demo.
102
103 4. Digest::SHA from CPAN is now a recommended module. If it is not
104 available, Digest::SHA1 will still be used as a fallback.
105
106 5. IPv6 incompatibility: Some of the session IP address verification
107 functions do not work correctly for traffic coming from IPv6 sources,
108 resulting in lost sessions. You can use catalog directive "WideOpen Yes"
109 as a workaround but see the documentation to be aware of tradeoffs:
110
111 http://docs.icdevgroup.org/cgi-bin/online/confs/WideOpen.html
112
113
114 KNOWN ISSUES UPGRADING FROM 5.5.2
115
116 1. Several old versions of CPAN modules were distributed in the extra/
117 directory but have been removed:
118
119     Business::UPS - part of Bundle::InterchangeKitchenSink
120     File::Spec - now distributed with Perl itself
121     Tie::ShadowHash - part of Bundle::Interchange
122     URI::URL - part of Bundle::Interchange
123
124 If you find Interchange won't start up, check to make sure you have all the
125 necessary Perl modules.
126
127 2. We have removed the option available in some polymorphs of the
128 database abstraction layer's set_slice() routine that allowed key/value
129 pairs to be passed in as a simple array. For example, this will no longer
130 work:
131
132     $db->set_slice($key, $field1, $value1)
133
134 But it can be rewritten as this, which has long worked:
135
136     $db->set_slice($key, [$field1], [$value1])
137
138 3. The syntax of the custom SQL function for counters has changed. At the time
139 of the feature's introduction on 2007-11-17, the syntax was e.g.:
140
141     UserDB  default   sql_counter  "userdb:custom_counter('userdb_username_seq')"
142
143 That conflicted with MySQL pseudo-sequence functionality that used the same
144 syntax. The new syntax does not conflict and has the benefit of being more
145 generic, allowing any SELECT statement:
146
147     UserDB  default   sql_counter  "userdb:SELECT custom_counter('userdb_username_seq')"
148
149
150 KNOWN ISSUES UPGRADING FROM 5.5.1
151
152 SpecialSub catalog_init has been renamed to request_init.
153
154 UserTrack now defaults to "no", so if you want the X-Track HTTP response header
155 to be output, add "UserTrack yes" to your catalog.cfg.
156
157 UserTrack also no longer affects TrackFile, so if you don't want TrackFile
158 output, you should not have a TrackFile directive in catalog.cfg.
159
160
161 KNOWN ISSUES UPGRADING FROM 5.4.x
162
163 Check the "special_pages/missing.html" file, in all of your Interchange-driven
164 websites, for a line that looks like the following:
165
166     [if type=explicit compare="q{[subject]} =~ m{^admin/}"]
167
168 If found then replace with the following two lines:
169
170     [tmpn missing_subject][subject][/tmpn]
171     [if scratch missing_subject =~ /^admin/]
172
173 Perl 5.8.0 or newer is now required. Running with threads is still not
174 recommended for production installations, but is allowed under Perl 5.8.5
175 or newer.
176
177 The long-deprecated [sql] tag has been removed. You'll likely want to
178 rewrite queries to use the [query] tag.
179
180 The ConfigParseComments directive has been removed, and Interchange now
181 behaves as if "ConfigParseComments No" has been specified. That means that
182 no configuration file line beginning with # will be parsed, including
183 #ifdef, #include, etc., as was done in the past. Bare ifdef, include, etc.
184 must now be used.
185
186 Global ActionMaps: Previously, the path passed to a global ActionMap
187 did not include the action itself, but the path passed to a catalog
188 ActionMap did include the action. This discrepancy was annoying to keep
189 track of. Now both kinds of ActionMaps receive a path that includes
190 the action. This means that all global ActionMap code will need to be
191 updated to deal with the action. Most simply, you can strip off the
192 action at the beginning of the sub something like this:
193
194     ActionMap your_action <<EOR
195     sub {
196         my ($path) = @_;
197         # remove action
198         $path =~ s:^[^/]+/::;
199         # your code here
200     }
201     EOR
202
203 Removed SOAP_Host, RequiredFields, HTMLmirror and UseCode directives.
204
205 All previously deprecated configuration directives have been removed.
206
207 Deprecated-feature pragmas and associated code have been removed:
208 * compatible_5_2 - used to keep table editor error text (mistakenly)
209   hidden, as it was the case up to Interchange 5.2.
210 * no_html_parse - used to disable parsing of MV= arguments inside HTML tags.
211
212 If MV_COUNTRY_FIELD was in use to determine the country for tax
213 purposes, then that setting needs to be changed to MV_COUNTRY_TAX_VAR.
214
215 The [either] tag historically reparsed its output. This has been changed
216 so that while the tag body parts are interpolated, the tag output is not
217 reparsed.
218
219 Removed the [fedex-query] tag, which hasn't been useful for some time
220 because FedEx discontinued their web API that the tag interfaced with.
221
222 Removed the [/page] and [/order] macros. The [page] and [order] tags have
223 never been container tags; [/page] and [/order] were macros that were
224 replaced with </a>. You should now just use </a> in HTML instead.
225
226 The various *Robot* directives have been split from the interchange.cfg
227 file into a new robots.cfg file.  If you are upgrading then you will
228 need to remove any existing *Robot* directives from your interchange.cfg
229 file and add "include robots.cfg" in their place.
230
231 A new subdomains.cfg file has been created, and should be included into
232 your interchange.cfg file with "include subdomains.cfg".  This file defines
233 a list of country-specific standardised subdomains that should be taken
234 into account when the DomainTail directive is in effect.
235
236 The session per IP counters have been changed to the new "timecard" round-robin
237 style counters.  You will need to delete the old counter files from the
238 tmp/addr_ctr directory with a command similar to the following:
239
240     rm -rf catroot/tmp/addr_ctr/*
241
242 ...be careful with the above command. If mistyped it can seriously mess up
243 your filesystem.
244
245 The [error] and [formel] tags now make use of the following CSS class,
246 that will need to be added to your CSS file:
247
248     .mv_contrast {
249         color: #FF0000;
250     }
251
252 The name of the class can be specified using the CSS_CONTRAST Variable,
253 or will default to "mv_contrast".
254
255
256 KNOWN ISSUES UPGRADING FROM 5.2.x
257
258     None.
259
260
261 KNOWN ISSUES UPGRADING FROM 5.0.x
262
263     None.
264
265
266 KNOWN ISSUES UPGRADING FROM 4.8.x
267
268 Interchange is designed to be compatible between major versions, and
269 for the most part a catalog designed under Interchange 4.8 should
270 be compatible with 5.0.
271
272 More information on upgrades is available in the document icupgrade, part
273 of the Interchange documentation package.
274
275 UPGRADE NOTES FOR FOUNDATION-STYLE CATALOGS
276 -------------------------------------------
277
278 * Add a new column "extended" to products/mv_metadata.asc. This just involves
279   adding a TAB and "extended" to the end of the first line of the file.
280
281 * If MV_COUNTRY_FIELD was in use to determine the country for
282   tax purposes, then that setting needs to be changed to
283   MV_COUNTRY_TAX_VAR.
284
285 * Remove variables UI_IMAGE_DIR and UI_IMAGE_DIR_SECURE or point
286   them to the new location, e.g. replace /interchange/
287   with /interchange-5/.
288
289 * If you didn't follow Interchange's SKU naming convention for Matrix
290   options, and assigned them arbitrary part numbers, or you hand-edited
291   the options table, you may find that your product options don't work. 
292   You should post the question to the user mail list or contact a
293   competent Interchange consultant at interchange-biz@icdevgroup.org.
294
295 * You will probably receive a message about "history-scan tag overrides global
296   definition". See the section "PROBLEMS WITH USERTAGS" below.
297
298 * The static-page build capability is no longer supported in
299   Interchange 5. You will receive warnings about "Directive StaticPath
300   no longer supported at line XXX". 
301
302   To stop these warnings, remove the NoCache directive and any
303   directive beginning with "Static" from your catalog.cfg file.
304   In the standard-style catalog, these are all located near
305   each other.
306
307   If you use the static page build facility, there are other means of
308   accomplishing the same thing with scripts. Contact a competent
309   Interchange consultant at interchange-biz@icdevgroup.org to get help.
310
311 * See the section "PROBLEMS WITH USERTAGS" below.
312
313 ---------------------------------------------------------------------------
314
315 TO TEST BEFORE YOU UPGRADE
316 --------------------------
317
318 YOU SHOULD STILL BACK UP, and in addition it is recommended you back
319 up your catalog. While the new server should not impact your running
320 catalog beyond normal catalog interaction for orders, statistics,
321 userdb, and such, it is not outside of the realm of possiblity that
322 something could happen. It should not happen in a catalog that is
323 based on Foundation and not heavily customized (i.e. using global UserTag
324 routines).
325
326 1. Install the new Interchange 5.x.x in /usr/lib/interchange-5.x.x
327 using the procedure from the README file.
328
329 2. Make /usr/lib/interchange-5.x.x/interchange.cfg match your
330 /usr/lib/interchange.cfg. Note that there may be new options; but the
331 existing one should work if you just copy it.
332
333 3. Run bin/compile_link:
334
335     cd /usr/lib/interchange-5
336     bin/compile_link -p 7787
337
338 NOTE: If you use the INET mode linking method, you have to run the
339       test server on a different port. Assuming you use the standard
340       7786 on your live catalog, you would add to interchange.cfg:
341
342          TcpMap  localhost:7787
343
344 After running compile_link, you should see four new files in the
345 /usr/lib/interchange-5.x.x/src:
346
347 -rwxr-xr-x  1 root  root  8088 Oct  3 09:59 tlink
348 -rwxr-xr-x  1 root  root  8088 Oct  3 09:59 tlink.localhost.7787
349 -rwxr-xr-x  1 root  root  7704 Oct  3 09:59 vlink
350 -rwxr-xr-x  1 root  root  7704 Oct  3 09:59 vlink._usr_lib_interchange_5_etc_socket
351
352 4. Note the Catalog lines in your interchange.cfg:
353
354   EXAMPLE:
355
356     Catalog standard /var/lib/interchange/standard /cgi-bin/standard
357
358 You should comment out all but the one you want to test.
359
360 5. Change the /cgi-bin/standard script link name to /cgi-bin/test5.
361
362   EXAMPLE:
363
364     Catalog standard /var/lib/interchange/standard /cgi-bin/test5
365
366 6. Copy the src/vlink (UNIX mode) or src/tlink (INET mode) link executable
367 to your CGI directory and name it "test5", i.e.
368
369   EXAMPLE:
370
371     cp -p src/vlink /var/www/cgi-bin/test5
372
373 7. IMPORTANT: Make sure its permissions match the permissions on your
374 running 4.x catalog! You may have to make it SUID, i.e.:
375
376   EXAMPLE:
377
378     chmod u+s /var/www/cgi-bin/test5
379
380 That should only be done if you are in UNIX mode and your current 
381 link program is SUID.
382
383 8. Add this line to the /usr/lib/interchange-5/interchange.cfg file:
384
385     Variable TEST_SERVER 1
386
387 9. Copy any *custom* global UserTag files to the usertag/ directory. Do not
388 copy any that were distributed with Interchange if you did not modify them.
389
390 10. Copy the new Interchange image and CSS files to the interchange-5
391 subdirectory in your document root, i.e.:
392
393         EXAMPLE:
394
395                 cp -r /usr/lib/interchange-5/share/interchange \
396                           /var/www/html/interchange-5
397
398 11. Modify your /var/lib/interchange/standard/catalog.cfg file to
399 point the URLs to the test server if appropriate by placing at the
400 end:
401
402    ifdef @TEST_SERVER
403    Variable  CGI_URL             /cgi-bin/test5
404    Variable  UI_IMAGE_DIR        /interchange-5/
405    Variable  UI_IMAGE_DIR_SECURE /interchange-5/
406    ## This ensures the UI image directory will be set properly
407    Pragma    dynamic_variables_file_only
408    VendURL   http://__SERVER_NAME____CGI_URL__
409    SecureURL   https://__SERVER_NAME____CGI_URL__
410    endif
411
412 12. Start the new interchange server:
413
414     /usr/lib/interchange-5/bin/restart
415
416 At that point, your catalog should be running on both Interchange 5 and
417 Interchange 4. Test thoroughly and then upgrade. Note that the UI will
418 be significantly changed, and that all features of the UI may not be
419 supported by your old catalog. The customer-facing side should function
420 in much the same way.
421
422 ------------------------------------------------------------------------
423
424 UPGRADING FROM 4.6.x
425
426 The public-facing side of a 4.6.x catalog is fairly straightforward to
427 port. The Admin UI is problematic, particularly if you have customized
428 it.
429
430 You should be able to update a catalog from 4.6.x if you are reasonably
431 proficient in Perl and/or Interchange. If you expect to rely on the
432 backend admin UI, it is sometimes better to build a new catalog from
433 scratch, and integrate your look and feel with that. Contact a competent
434 Interchange consultant to help (interchange-biz@icdevgroup.org).
435
436 That being said, here are some of the issues.
437
438 If you have this line in interchange.cfg:
439
440         #include usertag/*
441
442        You should change it to:
443
444         include usertag/*.tag
445
446        (The leading # sign is no longer needed).
447
448        If you have created any other UserTag definitions you will need
449        to either rename the file to add a .tag extension, or include
450        them explicitly like:
451
452           include usertag/my_tag
453
454        See the "problems with UserTags" section, below.
455
456 If you use CyberCash, you should replace these lines in catalog.cfg
457
458         Variable CYBER_MODE       mauthonly
459         Variable CYBER_CONFIGFILE /path/to/your/merchant_conf
460
461     with
462
463         Variable MV_PAYMENT_MODE        cybercash
464         Variable MV_PAYMENT_CONFIGFILE  /path/to/your/merchant_conf
465
466 There is one security change that can break constructs that ran under 4.6.x.
467
468     safe_data=1
469
470         If you had a database object which contained ITL tags and
471         they now show up as [itl-tag arg=val], then you probably
472         need to add the safe-data=1 parameter around your [loop ...]
473         or [query ...] construct.
474
475         The reason this change was made was the capability of Interchange
476         to directly enter user submissions into a database. If the
477         user put in something in [square brackets], knowingly or even
478         unknowingly, it could cause anomalous or insecure behavior. 
479         (There were no known exploits in the demo, but they could
480         easily be constructed.)
481
482
483 PROBLEMS WITH USERTAGS
484 ----------------------
485
486 You may see the following error/warning messages when you (re)start
487 Interchange:
488
489 1. Duplicate usertag xxxx found.
490
491     This message is most likely to mean that you have a global "usertags"
492     directory included from your interchange.cfg file.  Interchange 4.9 has a
493     new location (code/UserTag) for global UserTags.  Your old globals may
494     "clash" with the new ones.  Delete the old usertags that are named in the
495     error messages.  As always, it is recommended that you back up everything
496     before you start.
497
498     This message will also be raised if Interchange notices two local UserTags
499     with the same name.  If this is detected then rename or delete one of the
500     two UserTags.
501
502 2. Local usertag xxxx overrides global definition.
503
504     This message is most likely to refer to your local history_scan UserTag.
505     If you have this tag definition in your catalog.cfg file then you may
506     safely delete it;  Interchange 4.9 includes this as a global UserTag.
507
508     This message will also be raised if you have created a local UserTag
509     and have given it a name identical to one of the global tags (SystemTag,
510     UserTags, UI_Tag etc.)  The message is only a warning as your local UserTag
511     will override the global one.  If you didn't mean to override the global
512     tag of the same name then simply rename your tag and restart Interchange.
513
514
515 REMOTE SEARCHING
516 ----------------
517
518 A security vulnerability was recently discovered where any table configured
519 in your Interchange installation could be viewed remotely by an unauthenticated
520 user via a specially crafted search request.
521
522 This is a serious vulnerability, and all previous versions of Interchange are
523 affected. Even if you do not use the default search structure, your catalog
524 is likely to still be vulnerable.
525
526 To resolve this, a new configuration option, AllowRemoteSearch has been
527 introduced. It should be specified in each catalog configuration, and defaults
528 to:
529
530      AllowRemoteSearch products variants options
531
532 Any table specified in this option will be remotely searchable, and you should
533 not permit any table with sensitive information to be searched in this way. You
534 should carefully consider the implications of adding any further tables to this
535 configuration option.
536
537 Remote searches may be used by your existing catalog. These should continue
538 working without any changes as long as they only search tables that are permitted
539 by the AllowRemoteSearch configuration. You should carefully examine your
540 catalog for uses of the "search" form action, or pages which submit a form to
541 a page called "search" or "scan". If they specify a search file other than
542 products, variants or options, you should consider rewriting that page to just
543 accept the search terms via CGI parameters, and not the entire search. Please
544 consult the documentation on in page searches at:
545
546      http://www.icdevgroup.org/doc/icdatabase.html#In-Page%20Searches
547
548 If your catalog makes use of ActionMaps that perform searches, these should
549 continue to work as intended as long as they search a table allowed by 
550 AllowRemoteSearch. However, you should consider updating them to use the 
551 new "search" tag.  For example, an existing ActionMap that performs a search
552 like this:
553
554    ActionMap old_cat <<EOR
555    sub {
556         my ($action, $class) = split('/', shift);
557
558         $class =~ s/_/ /g;
559
560         # Originally, search parameters were placed in the CGI hash.
561         $CGI->{co} = 1;
562         $CGI->{fi} = 'products';
563         $CGI->{st} = 'db';
564         $CGI->{sf} = 'category';
565         $CGI->{se} = "$class";
566         $CGI->{sp} = 'results';
567         $CGI->{tf} = 'category,description:f';
568         $CGI->{op} = 'eq';
569
570         $CGI->{mv_todo} = 'search';
571         $CGI->{mv_nextpage} = 'results';
572         # And the "update" tag was called to re-evaluate the page with
573         # the provided search parameters.
574         $Tag->update('process');
575         return 1;
576    }
577    EOR
578
579 Would be updated to instead look like this:
580
581    ActionMap new_cat <<EOR
582    sub {
583         my ($action, $class) = split('/', shift);
584
585         $class =~ s/_/ /g;
586
587         # Now, you must create a hash to hold the search
588         # parameters.
589         my $search;
590         $search->{co} = 1;
591         $search->{fi} = 'products';
592         $search->{st} = 'db';
593         $search->{sf} = 'category';
594         $search->{se} = "$class";
595         $search->{sp} = 'results';
596         $search->{tf} = 'category,description:f';
597         $search->{op} = "eq";
598
599         $CGI->{mv_nextpage} = 'results';
600         # And call the new search tag, which isn't subject to the
601         # AllowRemoteSearch restrictions.
602         $Tag->search({ search => $search });
603
604         return 1;
605    }
606    EOR
607
608 If you are using a modern version of the standard catalog as the basis
609 for your catalog, there is a special subroutine that provides friendly
610 URLs for product categories, but is not a traditional ActionMap.  Similar
611 to the example above, you will need to alter your catalog.cfg, replacing
612 the entire Sub ncheck_category with:
613
614 Sub ncheck_category <<EOS
615 sub {
616     my ($name) = @_;
617     return unless $name =~ m{^[A-Z]};
618     $name =~ s,_, ,g;
619     my ($prod_group, $category) = split m{/}, $name;
620
621     my $search;
622     $search->{co} = 1;
623     $search->{fi} = 'products';
624     $search->{st} = 'db';
625     $search->{sf} = join "\0", 'prod_group', 'category';
626     $search->{op} = join "\0", 'eq', 'eq';
627     $search->{se} = join "\0", $prod_group, $category;
628     $search->{sp} = 'results';
629     $search->{mv_todo} = 'search';
630     $Tag->search({ search => $search });
631     if (($o = $Search->{''}) && @{$o->{mv_results}}) {
632         return (1,  $Config->{Special}->{results});
633     }
634
635     return;
636 }
637 EOS
638
639 In the standard and foundation catalogs, the "lost password" feature makes use
640 of the remote search feature to be able to retrieve lost passwords. We recommend
641 that you remove catalog/pages/query/get_password.html from your catalog, and
642 replace catalog/pages/query/lost_password.html with an updated version from this
643 distribution. As an alternative, you may apply the following patch to your
644 existing catalog/pages/query/get_password.html:
645
646 diff --git a/dist/standard/pages/query/get_password.html
647 b/dist/standard/pages/query/get_password.html
648 index 2d70c84..5aa51f1 100644
649 --- a/dist/standard/pages/query/get_password.html
650 +++ b/dist/standard/pages/query/get_password.html
651 @@ -32,8 +32,10 @@ ui_template_name: leftonly
652         if( $Scratch->{tried_pw_retrieve}++ > 10 ) {
653                 return "No way, Jos&eacute;. Too many times.";
654         }
655      $CGI->{mv_todo} = 'search';
656         $Config->{NoSearch} = '';
657 +       push(@{$Config->{AllowRemoteSearch}},'userdb');
658 +       return;
659  [/perl]
660  [update process]
661  [search-region]
662
663 This is not a recommended solution, and is only a workaround until you can
664 consider the changes in the updated lost password page.
665
666 If you do not wish to upgrade your Interchange installation to fix this
667 vulnerability, patches for all currently supported Interchange versions are
668 also available from http://www.icdevgroup.org/. You will still need to
669 follow the upgrade advice contained here.