X-Cart:Installation

Procedure

You can install the X-Cart shopping cart either manually or using the Installation Wizard that will do the most of the necessary jobs for you. The recommended method is to install X-Cart through the Wizard; manual installation should be performed by advanced users when it is impossible to install the software through the Wizard. For instruction on how to install X-Cart refer to the following sections:

Installing X-Cart on Windows

FAQ

What are correct file permissions for my X-Cart installation?

See X-Cart:Setting up file permissions page.

How to manage file permissions on UNIX server?

If you use UNIX operation system, you should change permissions on some files in order to install X-Cart. During setup X-cart installation wizard needs to modify config.php file, create several directories in xcart directory and populate them with files. That is why it is neccesary to set writable permissions on config.php (chmod 0666 config.php) and xcart directory (chmod 0777 . - dot means current directory, because you may install xcart in a directory with different name, e.g. /shop or /store or in a root directory). X-cart is also using perl scripts to connect to some payment processors and shell script spam.sh to send newsletter; the last 2 commands (chmod 755 admin/spam.sh and chmod 755 payment/*.pl) make these scripts executable. You can use UNIX shell or ftp client to run chmod commands.

If you are unfamiliar with chmod comand here is some info about it:

Chmod command is used to define the users of various groups that have certain permissions to perform an action over a file. There are three basic actions you can carry out over any file: read from it, write to it, and execute it. The basic format for chmod is chmod xyz file.foo. x, y, and z are each a number between 0 and 7. Each number represents permissions given to a group: x is for the user that owns the file, y is for the group that owns the file (normally the user's group), and z is for everybody else. To determine actual values for each number, one uses the following method: start with x = 0. If you want to be able to read from the file, add four. x can be 0 or 4 at this point in time. If you want to be able to write to the file, add two. x can now be 0, 2 (a write-only file), 4 (read-only file), or 6 (read/write file). If you want to be able to execute the program, add one. You now have a full range of possible numbers:

Digit	Permissions
0	None - cannot read or write or execute
1	Can execute, but cannot read or write
2	Write-only, cannot read or execute
3	Write-able/executable
4	Read-only, cannot write to or execute
5	Read-only executable, cannot write to
6	Readable Writeable file, but not executable (ie: text file)
7	Readable Writeable Executable file - most programs are this

Note: it is insecure to keep config.php file writable for everyone. After the installation, you should change the permissions: chmod 644 config.php

How to configure access file permissions on Windows Server?

When you are installing or updating the software under Windows, the IUSR_<computername> user must be given appropriate permissions on the file system to be able to modify files in the x-cart directory and its subdirectories or to run perl and upgrades etc.

There are several ways to configure permissions:

1. Turn off simple file sharing (in the Explorer menus, under "Folder Options" -> Tab: View), then set the permissions using the normal Security tab in Windows.

2. Use a built-in 'cacls' command to allow anonymous user necessary access. This way "simple file sharing" may remain active but still user can be granted necessary privileges. This commandline allows you to change permissions on x-cart directory and all its subdirectories::

cacls c:\inetpub\wwwroot\xcart /E /G <computer>\\IUSR_<computer>:C

The <computer> string should be replaced with the name of your computer.

It is the C at the end after the colon that means setting 'Change' permission.

Here is more information on permissions on Windows

The permissions on Windows systems are all selectable with two boxes which are:

Allow - Grant the permission.
Deny - Any denied permission for a group or user will override any allow permission, even if the user is in a group that is granted that permission.

If neither box is checked, the permission is not granted for the user or group, but if the user is in another group that has the permission, it will not be denied. Normally, if a user is a member of several groups that have different levels of permissions to an object, the least restrictive permissions apply unless the user, or one of their groups have the no access box checked for that permission.

Standard File and Folder Permissions

Read(R) - View attributes, contents, and permissions. Can synchronize.
Write(W) - Can change attributes, and file contents. Can create files or folders. Can synchronize.
Read(R) and Execute(E) - Can change sub folders, perform read operations, and execute a file.
List Folder Contents - Can perform read and execute permissions on folders. Can view folder contents, attributes, permissions. Can synchronize and change to subfolders.
Modify - Perform Read, Execute, and Write permissions along with ability to delete.
Full Control - Can perform Modify functions (above), take ownership, and modify permissions.

Permissions assigned to directories are inherited (default) by all files and subdirectories that are contained in the directory. The inheritance option, selected by default, may be deselected. Each file or directory has an Access Control List (ACL). To set permissions for additional users or groups, they are added to the ACL of the file or directory. Windows Explorer or the Cacls command line utility can be used to set permissions.

Special File and Folder Permissions

On the file or folder properties dialog, click the "Security" tab and the "Advanced" button to assign special file or folder permissions.

Traverse Folder/Execute File - .
List Folder/Read Data - .
Read Attributes - The user can read the attributes (archive, compress, hidden, etc.) of the file, but not read the contents of the file.
Read Extended Attributes - .
Create Files/Write Data - .
Create Folders/Append Data - .
Write Attributes - .
Write Extended Attributes - .
Delete Subfolders and Files - .
Delete - The user can delete the file.
Read Permissions - The user can read the file.
Change Permissions - Lets the user change permissions for the file, but not view or change the contents of the file.
Take Ownership - The user can take ownership of the file, but can't give it back.

These permissions can be applied to directories, files, and subdirectories with one of the following selections:

This folder, subfolders and files
This folder only
This folder and subfolders
This folder and files
Subfolders and files only
Subfolders only
Files only

How to disable PHP safe_mode in Ensim control panel?

To disable php_safe_mode in the Ensim accounts, create a file named php in the /etc/httpd/conf/site# (replace site# accordingly) with the following lines:

<IfDefine vwh_php4_module>
php_admin_flag safe_mode off
</IfDefine>

How to disable SELinux security restrictions for httpd on Fedora Core & RedHat?

1. Edit the file '/etc/selinux/SELINUXTYPE/booleans' and add the string

httpd_disable_trans=1

2. Execute command 'setsebool httpd_disable_trans 1'

3. Restart the Apache 'service httpd restart'

How to specify socket to be used for connecting to MySQL database?

Socket filename can be entered in MySQL hostname field during installation.

Example:

localhost:/tmp/mysql-5.0.sock

or can be edited in config.php file.

Troubleshooting

500 Internal server error

Internal server errors can be usually caused by one of the issues discussed here.

Error: "Warning no such file or directory: ./COPYRIGHT".

This or similar errors occur if some of X-Cart files are missing. They could be lost during FTP upload to the server or accidentally deleted. You should re-upload X-Cart distribution to your host and try to run installation script again.

Fatal error: Can't connect to the MySQL server" on step 2 of installation

Possible causes are as follows:

a) Incorrect username/password/database name of your MySQL database. You should contact your hosting administrators and ask them to specify correct access information for MySQL database (please note, this information is case sensitive).

b) If your MySQL server and X-Cart are located on different hosts there is a possibility that connection from your host to MySQL server is disabled. You should contact your hosting administrator to ask if there are any restrictions of this kind.

Installation suddenly freezes on step 3 (importing data)

Some mis-configured MySQL servers drop connection when feeding big amount of data from PHP script (during installation X-Cart pumps several megabytes of data into the database). You may try to restart installation process from the beginning. If you still cannot succeed you can install X-Cart manually (look for details in the INSTALL file in the X-Cart distribution or in the corresponding section of X-Cart manual).

Installation error - Warning: opendir(/[xcart_root_dir]/.pgp.def): failed to open dir: No such file or directory in /[xcart_root_dir]/include/install.php on line 599

X-Cart '.pgp.def' folder wasn't extracted from the installation package. You should create this folder manually ('mkdir .pgp.def') and reinstall X-Cart.

Got error 28 from storage engine

This error appeared due to the lack of free space in the file system on the hard disc drive where MySQL is installed. The solution is rather simple - to clean up some disc space.

Lost connection to MySQL server during query

This error message means that when executing the query the conenction with MySQL server was lost

if such errors are numerous, most likely the reason is the same as described here: https://kb.x-cart.com/article/mysql-server-has-gone-away
if it is a one time error, then most likely it was caused by the MySQL server restart
also the problem may be caused by the low value of the max_allowed_packet option: https://kb.x-cart.com/article/the-size-of-the-data-package-being-transmitted-is-greater-than-maximum-allowed-by-the-server

Mysql connect(): Too many connections

The limit of simultaneous connections to MySQL server is exceeded. This limit is set by the max_connections MySQL option - see https://dev.mysql.com/doc/refman/5.0/en/too-many-connections.html. The problem can be resolved in the following ways:

Increase the max_connections option value
if the images are stored in the database(are called via image.php), move them to the file system
change the hosting company

MySQL server has gone away

When you get a number of MySQL server has gone away errors in logs, this means that the MySQl server aborted the connection to PHP script but the script is still trying to execute a certain query.

This usually occurs when:

a customer opens a store page in the browser
PHP script connects to the MySQL
for some reason the script stops for a while, during this pause MySQL server timed out and the connection was closed
the script finishes its work and tries to execute the MySQL query again
since the connection is already lost, the error message is shown

Additional info on the matter can be found here: https://dev.mysql.com/doc/refman/5.0/en/gone-away.html

A possible solutions in this case - increase the wait_timeout option value (default value is 28800). Please contact your hosting regarding the matter. More info about this option: https://dev.mysql.com/doc/refman/5.0/en/server-system-variables.html#option_mysqld_wait_timeout

As a quick workaround solution, you can apply the File:Mysql server has gone away.txt patch. After this patch is applied, X-Cart will reconnect to MySQL in case of such errors. This patch is already included to X-Cart 4.1.11 and higher.

If the error still persists and it is impossible to change the wait_timeout option value then it is recommended to change the hosting company.

SQL error when deleting products

When trying to delete a product, a SQL error appears. This problem can be reproduced on MySQL 5.x

Error message is as follows:

SQL query : SELECT IF(xcart_categories_lng.category != '', xcart_categories_lng.category, xcart_categories.category) as category FROM
xcart_categories, xcart_products_categories LEFT JOIN xcart_categories_lng ON xcart_categories.categoryid = xcart_categories_lng.categoryid AND
xcart_categories_lng.code = 'US' WHERE xcart_products_categories.productid = '16856' AND xcart_products_categories.categoryid =
xcart_categories.categoryid AND xcart_products_categories.main = 'Y'

Error code : 1054
Description : Unknown column 'xcart_categories.categoryid' in 'on clause'
Request URI: /admin/process_product.php?mode=delete&keep_https=yes
Backtrace:
/include/func/func.db.php:186
/include/func/func.db.php:112
/include/func/func.db.php:357
/include/process_product.php:202
/admin/process_product.php:43

In order to fix this issue, please apply the File:Product deletion error in 4 1 11.txt patch.

This issue is fixed in the X-Cart 4.1.12 and higher.

The size of the data package being transmitted is greater than maximum allowed by the server

The size of the data package being transmitted is greater than maximum allowed by the server

The above error is caused by the fact that there was an attempt to transmit via MySQL the data package, which size was greater than the 'max_allowed_packet' MySQL option value.

The detailed description can be found here: https://dev.mysql.com/doc/refman/5.0/en/packet-too-large.html

In order to fix this issue it is required to change the max_allowed_packet to a larger value

Unknown column 'xcart products.productid' in 'on clause'

X-Cart 4.0or above

X-Cart 4.1.1

This issue may be caused by several facts:

the hosting has mySQL 5.x installed
X-Cart 4.0.x is used, which does not support mySQL 5.x. (the issue was also found in X-Cart 4.1.1) ( MySQL 5.x is not supported since there were numerous changes in MySQL 5.0.12)
X-Cart 4.0.x had been released before the MySQL 5.0.12, that's why such errors occur.

The problem can be resolved using the File:MYSQL5 comp for 4.0.x.txt patch.

User 'mysqluser' has exceeded the 'max questions' resource (current value: 50000)

You receive the following SQL errors:

INVALID SQL: 1226 : User 'mysqluser' has exceeded the 'max_questions' resource (current value: 50000)

MySQL allows to limit any user's activity. The max_questions option contains a number of queries of 'SELECT' type which a user can execute per hour.

If such an error is received, this means that X-cart executes a lot of queries and exceeds the limit. You can find more info about this option here: https://dev.mysql.com/doc/refman/5.1/en/user-resources.html

The problem can be resolved in the following ways:

increase the max_questions value
the following workaround can be used: it is required to create a few MySQL users, realize in the config.php a random choice of user from the list. Since every user has a limit of max_questions, X-Cart will be able to fulfill the following number of queries: max_questions * the number of users in the config.php
move the images to the file system, disable the unnecessary modules, disable the statistics, which will decrease page load time
change the hosting provider

User [name] has already more than 'max_user_connections' active connections

Warning: mysql_connect(): User [name] has already more than 'max_user_connections' active connections
in /home/[path_to_xcart_dir]/include/func.php on line 43

Could not connect to SQL db

This means that your mysql user has exceeded the max_user_connections limit (mysql configurable parameter). For example, when several users browse your site, several instances of x-cart scripts are called and the scripts try to connect to the mysql database. If the number of those scripts instances is higher than the max_user_connections limit defined on your server, user will see such error message.

You should contact your hosting administrators and ask them to increase the limit number of mysql connections per mysql user, i.e. 'max_user_connections' limit.

Can't create/write to file

If you get an error of the "Can't create/write to file" type for some queries, it means that MySQL cannot create a temporary file for the result set in the temporary directory. The probable reasons are:

no writable permissions set for the temporary directory;
the temporary directory is defined incorrectly in MySQL configuration file;
problems with the storage device (not enough free disk space);
anti-virus or other software is blocking MySQL from writing to the temporary directory.

Contact your server administrators and ask them to look into and fix the problem.

For more details about the "Can't create/write to file" error please refer to: https://dev.mysql.com/doc/refman/5.0/en/cannot-create.html

If you have McAfee On-Access Scanner running on your server, add the temporary directory or the MySQL filetypes (MYD, MYI) into On-Access Scanner's exclude list. See: How to manage file and folder exclusions in VirusScan Enterprise 8.x

Table '%table_name%' is marked as crashed and should be repaired

If you get an error like:

Table '%table_name%' is marked as crashed and should be repaired

It means that the MySQL table '%table_name%' has been crashed in the database. Occasionally, under circumstances involving high load on the server, multiple INSERTs and UPDATEs, coupled with many SELECTs, or hardware failure, your database server may corrupt a table. According to the MySQL manual, you can get corrupted tables if some of the following things happens:

The mysqld process being killed in the middle of a write.
Unexpected shutdown of the computer (for example, if the computer is turned off).
A hardware error.
You are using an external program (like myisamchk) on a live table.
A software bug in the MySQL or MyISAM code.

In order to fix this issue try to connect to your store MySQL database and executed the following MySQL query:

REPAIR TABLE '%table_name%';

Opening X-Cart installation script shows a blank page

The permissions set to the X-Cart files and folders are incorrect. The correct X-Cart files and folder permissions depend on the server configuration.