=head1 NAME icfaq - Frequently Asked Questions =head1 DESCRIPTION =head1 How does Interchange work? =head2 Where are the pages? Interchange pages are not kept in normal HTML space. Look in the catalog subdirectory pages. The pages are always filtered through the Interchange daemon before being delivered. =head2 Where are the images? Interchange is a CGI program, and if relative image paths are used, IMG tags like the following will occur: Interchange, by default, uses an ImageDir for a prefix. In the demo, image specs that have no absolute path information are prefixed with /simple/images/. In an Interchange page, this tag: will become this: This tag: will become this: Absolute image paths are not affected. An image such as /other/images/whatever.gif will not be changed. =head1 INSTALLATION =head2 Configuration Problems Most Interchange configuration and setup problems are due to one of the following: =over 4 =item Wrong information given to makecat program. B To install a working demo, Interchange needs to know what the DocumentRoot is and how to run CGI programs. Details of this setup are server- and site-specific, which may require some research. Re-run the configuration again, and pay close attention to the prompts given. There are examples given which apply to most systems. If the web server is Apache or NCSA, Interchange will try and parse its httpd.conf file to help you along, but many ISPs don't allow users to read these and it may fail. =item Too-low version of Perl. If you have a Perl earlier than 5.005, Interchange will not work. Don't even try an earlier version. =item Perl compiled with USE_THREADS. Run perl -V. If you see -DUSE_THREADS in the compilation definition, you might run into problems with Interchange. B: You cannot run the Interchange software as root. =back If you are setting Interchange up for the entire machine, and not just as a virtual host user, it is usual to create a special interch user to run the daemon and the link program. This means the directory listing for your cgi-bin should be something like: -rwsr-xr-x 1 interchange users 6312 Dec 30 11:39 cgi-bin/simple and for the socket file it should be: srw------- 1 interchange users 0 Dec 30 11:41 etc/socket Once you have set up the software, you can easily install catalogs as root B. (The following assumes you have made the Interchange software owned and run by the special user interchange and that each user has a Interchange catalogs directory /home/user/catalogs). The best way to set permissions on a multi-user system is to make all files group readable and writable (660 or 664 mode). If you have a system setup that places each user in their own group, make interchange a member of each user's group and set ownership and permissions with: find /home/user/catalogs -print | xargs chown user find /home/user/catalogs -print | xargs chgrp user find /home/user/catalogs -print | xargs chmod g+rw For best results, set the user's default umask to 2, so that they will, by default, create files that have the proper permissions. If you have all users in the same group, the above is not secure. You should put interchange in a group of which no user is a member (perhaps interchange would be a good choice) and set all files owned by the group interchange and all directories to mode 2770: This will make files default to the proper group when created (on most UNIX versions, anyway). find /home/user/catalogs -print | xargs chown user find /home/user/catalogs -print | xargs chgrp interchange find /home/user/catalogs -print | xargs chmod g+rw find /home/user/catalogs -type d -print | xargs chmod g+s If you are on a virtual hosting system, the procedure varies. Making the program setuid should work for most systems. If your setup uses CGI-WRAP or another setuid scheme, it should still work. However, you may have to unset the setuid bit with chmod u-s cgi-bin/simple or the like. If you have a non-standard CGI setup, as some virtual host systems do, you will need to know something about UNIX and the web or engage a consultant to properly set up the paths. Usually switching to TLINK/INET mode is the easiest thing to do, though with Iserver and a few others it may take more than that. If you used the makecat program to build the catalog, it should have warned you if it was not able to make the link program setuid. To set the program (in the file cgi-bin/simple in this example) to be setuid, use the command: chmod u+s cgi-bin/simple =head2 Error -- the Interchange server was not running... This indicates that the link CGI is not communicating with the Interchange server. B The server should always be started by the same user ID which owns the suid vlink program. (This does not apply to TLINK/INET mode.) The server must be running, first of all. If you didn't start it, you can do so by going to the Interchange home directory and typing: bin/interchange -restart You can check to see if your server is running by typing: Linux, BSD: ps -ax | grep interchange Most other systems: ps -elf | grep interchange BSolaris and IRIX truncate the string, and don't allow setting of the $0 parameter. You may have to grep for 'perl' instead. If the server is not running, it may have failed due to another process occupying the TCP socket 7786. If using VLINK, try starting Interchange with start -u, which will not monitor the internet-domain socket. If VLINK is not communicating with the server, there are a number of possible reasons. First, if you are trying to run Interchange on an ISP, go to the section about ISP problems. It is probably one of those. If you are running Interchange on a single machine, it is probably one of: 1. Permissions problems 2. Interchange on NFS-mounted file system Check the error_log file for your HTTP server -- it will almost always tell you what the problem is, unless there is a simple permissions problem. Permissions are easy. If starting Interchange like this works: interchange -r SocketPerms=666 then you have a socket permission problem. Try restarting interchange without the above adjustment of SocketPerms=666, and then try accessing it again with each of these mode changes: chmod u+s cgi-bin/storename chmod u-s cgi-bin/storename cgi-bin/storename = path to your executable If neither of those work, either the UID the program is owned by is wrong, or your HTTP server is interfering in some fashion. If you are running Interchange on an NFS-mounted file system, it cannot run in server mode because UNIX-domain sockets don't work on NFS. You will need to change to static mode from server mode, or better yet, put Interchange on a file system that is directly mounted. You can use Interchange in INET mode along with the tlink.c program to allow running across NFS boundaries. If you have not changed the configured defaults, and still it will not communicate, you should try setting the LINK_HOST and LINK_PORT directives in tlink.c and recompiling. =head2 I get messages like 'Config.pm not found.' What does it mean? This means your Perl is not properly installed, or that Interchange is not using the proper Perl binary. On UNIX, try reinstalling Interchange and using the standard Perl installation sequence: /complete/path/to/proper/perl Makefile.PL make make test make install Otherwise, contact your system administrator. =head2 Can't locate lib.pm in @INC. BEGIN failed--compilation aborted. Again, your Perl is not properly installed. Someone has put a Perl up on your system, then either moved or removed the library directory. Contact your system administrator and request that Perl be re-installed. =head2 Segmentation fault or other core dump. If this happens when you run the Interchange test or server, it is always Perl that has a problem. Not sometimes, always. A proper Perl should never have a segmentation violation, period. And it should not dump core (unless you passed it a -u option somehow). You will need to either update Perl or report the bug to the proper personnel. Depending on your situation and technical ability, this may be your system admin, ISP, or the Perl porters. =head2 Configuring catalog whatever...Use of uninitialized value at Config.pm line 1614, chunk 322. This is a warning from Perl indicating that an empty value was found where one is expected. The warning is left in so that you know that something is missing. Whatever it is, it can be found at the specified "chunk," or line, of catalog.cfg. If you use the include capability, it would have to be factored in as well. The usual reason is that a file is specified in one of the directives (usually one of Help, SearchProfile, OrderProfile, Buttonbars, or UpsZoneFile) and does not exist. See the documentation for the directive on how the file name should be specified. =head2 Why isn't the above error more enlightening? Because Perl won't tell us what exactly went wrong. See its FAQ for why. =head2 XXXXXX.pm does not match executable version. This is a Perl which does not have the right Perl library installed. It usually results from a naive system administrator who thinks they can bypass the 'make install' for Perl and just copy the Perl binary or directories. If you installed Bundle::Interchange locally in your Interchange directory, it may mean that your system administrator updated Perl and failed to select the binary compatibility option. =head2 Can I run Interchange on the Macintosh or Windows? Interchange will not run on a MacOS 7, 8, or 9 operating system. It will run on Mac OS X and other PowerPC Unix variants. Interchange's *files* can be manipulated by any computer. As long as uploads/downloads of database source, pages, and configuration files are done in ASCII mode, there is no reason why they can't be edited on a Mac. And with MySQL or other ODBC databases on your UNIX-based ISP, you can even directly interface to the database you use with Interchange provided you have the scarce ODBC middleware needed for the Mac. Interchange can be run on Windows with the Cygwin tool set (1.3.2 or higher) available from http://www.cygwin.com/, but there are numerous anomalies and it may be difficult to get operating reliably. It is never recommended that you run a production catalog on a Windows system; if you do get it working you should only use for catalog development. =head2 Error -- 'make: command not found' The error is caused when the system you are installing on does not have the program called "make". It is recommended that you install make as well as a C compiler ("cc" or "gcc") for the installation of Interchange. If you are unsure of how to do this for your operating system, it may help to ask a mailing list related to your operating system. =head2 Templates aren't showing, only the center content of the page itself Example question: "All that's showing up is the center section of the template. This happened after ____: (moving my site to a new host, or uploading a new catalog.cfg or theme.cfg file, or restarting interchange)." This can happen if: =over 4 =item * The files were uploaded in binary instead of ASCII (when using FTP) =item * Windows-style carriage returns were put in the file by a windows editor or file transfer program =back From unix, do an octal dump on some of the files to see if you have cr chars: od -a templates/foundation/theme.cfg | grep cr od -a catalog.cfg | grep cr If something appears on the screen, then your file needs to be cleaned. Among the other 10-million ways to clean it, here is one: perl -pi -e 's/\r\n/\n/g' < old_file.cfg > new_file.cfg Also, if you are using FTP to transfer the files from a Windows machine, try using ASCII mode instead of binary mode. =head2 When I try to install the RPM, I get "failed dependencies" errors There are two easy solutions to this problem: =over 4 =item * Install the modules manually, then use the --nodeps RPM option. perl -MCPAN -e "install Bundle::Interchange" =back =over 4 =item * Install RPM modules to satisfy the dependencies. Some modules are available from L while others can be found on rpmfind.net. =back =head1 SSL problems =head2 Shopping cart is dropped when using SSL. If you are using a separate secure and non-secure domain, this is due to the cookies from the user not matching as well as the session ID not being able to be transferred due to differing source IP addresses. =over 4 =item B: Interchange does not support this configuration. You may be able to get it to work in some circumstances, but it is not supported. See the next set of questions for help on how you may be able to get it to work to some extent in your configuration. It will not work in every circumstance with every feature. =back This is sometimes due to the HostnameLookups (Stronghold/Apache parameter) not matching for the two servers, secure and non-secure. It can also be caused by the user having different web proxy addresses for HTTP and HTTPS. If it still does not work, try changing some of the appropriate configuration parameters in interchange.cfg: DomainTail No IpHead Yes If you still are having problems, try this combination in catalog.cfg, the catalog configuration file: SessionExpire 10 minutes WideOpen Yes The above setting will typically make Interchange work when it is possible to work. Sometimes when you have multiple Interchange servers sharing the same secure server, you will have problems after accessing the second one. (The first one issues a session ID cookie, and that causes problems). =head2 I have a different secure server domain. Why does the shopping cart get dropped? First of all, it is questionable business practice to not certify your secure server. Besides violating the terms of use of many certificate issuers, customers notice the changed domain and it is proven by user surveys and long experience that you will receive fewer orders as a result. Certs can be obtained for $125 US per year, less than the typical cost of one hour of a top consultant's time. Do your business a favor -- spend the money to get a cert. If you insist on doing it anyway, probably driven by the fact that you need a dedicated IP address for a secure server, you can use the solutions in the previous FAQ question and get some relief. But by far the best way is to have all orders and shopping cart calls go only to the secure domain. Your users may get a different session when browsing the non-secure catalog pages, but it will matter little. To do this on the Foundation demo, place in catalog.cfg: AlwaysSecure order ord/basket ord/checkout A more complete list might be: AlwaysSecure <Order it To make a form-based order button secure, use "[process secure=1]" as the ACTION. =head2 My images aren't there on the secure server!!! You have a different document root, or the permissions are not such that you can access them. You can set a different base URL for images with: ImageDirSecure https://your.secure.server/somewhere/images Don't try to set it to an http:// URL -- images will be broken anyway. =head2 My secure pages fail when the browser is MSIE. MSIE has several SSL bugs, particularly in V5.01. See the Apache-SSL or mod_ssl FAQ. You can sometimes fix this with an httpd.conf change: SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown =head1 ISP Problems The great majority of ISPs provide some CGI service, and more and more run systems that are compatible with Interchange. The new catalog configurator for Interchange makes setup much easier. A word of warning: if you chose your ISP mostly on price, you can expect problems. The low-cost providers typically have heavily-loaded machines and many domains. The more domains and the more load the unhappier you will be with Interchange. Interchange works best on a fast machine with plenty of memory. A few Internet Service Provider (ISP) systems still have difficulty with one or the other aspect of running Interchange. A few cannot (or will not) run Interchange at all. On top of that, many times ISP personnel are too busy to help, won't help, or don't know enough to help. Some are secretive about details of the setup of their systems. All in all, you can have a fair amount of confidence that your ISP can run Interchange. Or, you can get one who will. 8-) =head2 No shell access allowed on my ISP. Generally it is a waste of time to try to use Interchange without shell access. =head2 We're sorry, the Interchange server is unavailable... (The following assumes that you were able to start the Interchange server.) This could be almost anything, but with a properly configured Interchange it is almost undoubtedly due to your cgi-bin and/or your Interchange directory being located on a different filesystem than the actua machine that is executing the program. VLINK uses UNIX-domain sockets, which don't work on NFS-mounted filesystems. Iserver.com and other systems which use chroot HTTP servers require quite a bit of extra configuration to get going. If you have not been careful to set permissions properly when running in VLINK/UNIX mode, the link CGI will not be able to communicate with the Interchange server. Please read the documentation that covers this in detail. You can run in INET mode with the tlink link program to prevent those problems. =head2 Document contains no data or premature end of script headers (especially on BSDI or FreeBSD). This usually means that your HTTP server ran out of resources during the execution of the link program. It couldn't create more sockets, is unable to create a process, or can't open any more files. This usually happens in frames catalogs, when Interchange is sending more than one page simultaneously. And even more especially on FreeBSD and BSDI, which are often distributed with the kernel parameters SOMAXCONN and CHILD_MAX set to levels unsuitable for serving the web. Go to and try searching for MAXUSERS. This should give you plenty of pointers on how to set these parameters properly. =head2 Interchange server only runs for a while, then dies. Many ISPs don't allow your user ID to run a program unless it is logged in! The moment a watchdog program notices a daemon running with a non-logged-in UID, it terminates the program. Or, it terminates programs that haven't been active for XX minutes. Contact your ISP about this. They may be able to do something for you. =head2 My entire home directory is in HTML document space. If working with an ISP where all of the files are in HTML document space, disable all access to the Interchange catalog directory with the proper HTTP access restrictions. Normally that is done by creating a .htaccess file like this: order allow,deny deny from all If unable to do this, do not run Interchange unless file permissions can be set such that files will not be served. However, security will be a problem and customers' personal information could be placed at risk. =head1 SYSTEM CONFIGURATION =head2 Can I run multiple catalogs on one server? Yes. Interchange supports multiple independent catalogs. There are users who run more than 500 catalogs on a single machine. The capacity is usually a function of how busy the catalogs are and how much memory and processor speed your system has. =head2 How do I start Interchange when I reboot? Use the standard facility on your operating system. For BSD-style systems, the file is usually called rc.local (in the /etc directory). On SVR4 systems, it is quite a bit more complex. Look for the /etc/rc.d directory and see what other programs do. Often the file is called S99startup or something similar. B Interchange must not run as root, which is the user identity that the startup file executes. (Interchange will refuse to start if executed as root.) The technique to start up depends on the facility of your su(1) command. This should work on most operating systems: su interchange < must be the only thing on the line (no leading or trailing whitespace). If your su(1) command has a -c option (as most System 5 UNIXes do), you can just set: su -c /your/interchange/dir/bin/restart interchange Interchange supplies a restart script which tries to do the above portably. It works on many operating systems. =head2 I installed the Interchange RPM, and I can't restart. This usually means that you tried to run /usr/lib/interchange/bin/interchange, which fails to take into account the Linux Standard Base (LSB) file setup. Instead, run /etc/rc.d/init.d/interchange restart or /usr/sbin/interchange -r =head2 How do I set up a mall? Interchange can share product databases, session files, and any other databases. It has many features which support mall building. You can easily build separate and mostly identical catalogs which you link to via HTML. But building a mall is as much an exercise in data and process as in software. Consider the following questions: =over 4 =item 1. Who will be clearing payment? =item 2. What happens if everyone doesn't have the same tax rate? =item 3. How will you clear orders to multiple vendors? =item 4. How will you bring together multiple types of shipping? =item 5. How will the vendors get product data (including images) to you? =back If you cannot answer those questions and visualize how to build a mall, you probably should not try. =head1 PRODUCT OPTIONS =head2 Can I attach a size or color to a product? Interchange has product modifiers, or attributes, which can be carried around with the product. Inside an item list or the product page (flypage), the [item-options] tag will automatically place suitable widgets on an HTML form, and "remember" what should be selected. See the Interchange documentation for B. You can use the SeparateItems directive or set the mv_separate_items variable on the order form to cause ordered items to be put on separate lines in the shopping basket. (This is the default in the demo catalogs.) =head2 Can I change the price based on size or color (or other attribute)? Yes. Use the Interchange UI to set up your product options. It operates on the options database table to set up options that can effect price. Or see the next question. =head2 How are simple product options structured? Interchange has three types of options; I, I, and I. They are based on the options database table. To enable options for a product, it needs to have a master record in "options" with the SKU as the key. The only fields that matter in the master record are: code The SKU of the item o_master Indicates not a product, but an option for a product in another database o_enable Options enabled for that item o_matrix Set to 1 for all-in-one widgets, 2 for separate widgets o_modular Modular options (alpha) If o_enable is set, but neither o_matrix or o_modular are, the item is using simple options. For the option itself in simple mode, the following fields apply: code Arbitrary key sku SKU this option applies to o_group The attribute name of the option o_label The label the widget for the option will bear o_value The options, in IC option format o_widget The widget type used to display o_height The widget height (if any) o_width The widget width (if any) price Price adjustment Here are the fields for an item with a simple size option: code:os28009 o_master:1 o_enable:1 o_matrix:0 o_modular:0 # code:os28009-size sku:os28009 o_group:size o_label:Size o_value:S=Small,M=Medium,L=Large,XL=Extra Large o_widget:select o_height: o_width: price:S=-1.00,XL=1.00 # The price field accepts option modifiers based on the option value; for example, to adjust the price of an S down 1.00 and the price of an XL up 1.00, you use the values shown above. This works in conjunction with the special ==:options atom in CommonAdjust. To activate the pricing adjustment, you must have something like this for your CommonAdjust setting: CommonAdjust :sale_price, ;:price, ==:options The actual names of the fields used for these can be changed with the Variable MV_OPTION_TABLE_MAP, i.e. Variable MV_OPTION_TABLE_MAP <. If you dump the structure of the main shopping cart you would see something like: [ { mv_ip => '0', price_group => 'general', mv_ib => 'products', code => 'os28080', quantity => '1', }, { mv_ip => '1', price_group => 'general', mv_ib => 'products', code => 'os28080', size => 'L', color => 'black', quantity => '1', }, ] Each key of the hash is an attribute. There are a number of special attributes: Attribute Description code The item SKU sku The SKU of the base item (in the case of matrix options) mv_ip The line number of the shopping cart (minus 1) mv_ib The database table the product was ordered from quantity The number on order group The order group for a master item or subitem mv_si Subitem indicator mv_mi Master item code mv_mp Modular item mv_price Price of the item (to directly set pricing) mv_order_route Special order route for this item Any attribute besides the above is a product I