top
MmPASS Description
Upon the order completion the module creates a temporary directory with cryptic name (you can define the length of the random cryptic directory name), locks it with user name/password and copies there all ordered products or documents that are set up for download (or remote access - e.g. at courses or member restricted websites). Beyond the (optional) login/password, it allows an additional security with (optional) crosschecking of cookies, IP address, browser version and several other parameters. You can also set the account expiration time after which the directory will be automatically removed. All this runs with symbolic links, it means the original files or documents are stored out of the public area, in the Miva data directory and they are not transferred or copied physically. So for example if you have a software product or a document for download of 1MB and 100 active customers, it does not take 100MB of disk space, but still just 1MB - and additionally the account creation is much faster and less resource intensive than when copying whole files.
Notifications with the download links may be sent to the customer either immediately upon the purchase with a selected payment method (e.g. a credit card) or after approving the order manually from the
Ultra Batch Report
. If you do not own the
Ultra Batch
module, you can use the
MmHTML
(Merchant Notification Email module) instead of the
MmHTMLc
(Customer Confirmation Email module) and forward the received Merchant notification e-mail to the customer after approving the purchase.
top
MmPASS Configuration Options
Symbolic Links
Keep User Directories
Source Extensions
Source Name Pattern
Target Name Pattern
Standalone Attributes
Path To WWW Root
Download Directory
Dir Name Length
Login Prompt
Password Type
Password Length
Expiration Time
Allow Directory Index
Payment Methods
Authorization Options
Verify User's IP address
Verify User's Host domain
Verify User's Browser
Verify User's Cookie
Verify User's Language
Verify User's "Accept" String
Verify Referer URL
list
Symbolic Links
MmPASS
works optimally, with the highest security and performance on systems that allow symbolic links from the public www directory to the Miva data directory. Usually it has to be explicitly enabled in the Miva Empresa configuration (
SecurityOptions=15
) and possibly also a change in the Apache configuration may be needed (
AllowOverride all
). However, MmPASS works also on systems that do not support symbolic links; the only limitation is that you can serve only files (downloadable products), but not access to directory structures (e.g. memberships).
If you have purchased installation by truXoft, we will configure the MmPASS optimally for your system and set up directories, symbolic links and if necessary and possible also the Miva Empresa and Apache configuration files. If you prefer setting up MmPASS yourself, you can find useful details in the
Miva Empresa Configuration Manual
and in the
Apache documentation
. Some additional details about Empresa configuration may be found also on the Mivo site in the
art0006.htm
.
When using
Symbolic links from Miva data directory
, the source files (or directories) are placed in the Miva data directory. See details below at
Source Name Pattern
and
Download Directory
for the location of the files.
MmPASS
tests for availability of symbolic link in Miva, and in Apache and displays only options found as available. If the Apache directory structure does not allow linking to the hidden Miva data directory, you have to select the only available option
"Symbolic links from Web directory"
. In this case your source data have to be placed in the public web directory and protected by .htaccess from accessing (Deny all). See details below at
Source Name Pattern
and
Download Directory
for the location of the files.
In the case symbolic links are not available at all on your system (e.g. Windows platforms), you have to work without them, using copying of files instead. In this case, the source files are always stored in the Miva data directory.
list
Keep User Directories
When checked, MmPASS adds all subsequent orders of the same customer to his personal folder. Individual products still keep their original expiration (time to live) and are being removed individually. When unchecked, a new cryptic directory (URL) is created for each order placed.
list
Source Extensions
Each product may be associated with a file or a directory holding multiple files, documents or an entire website. If no file or directory is assigned to the product, MmPASS ignores it and does not create any secure URL for it - it is considered as hardware product that is delivered by another shipping method.
The linking of a product to a file is made without any configuration in the Miva Merchant Admin interface. It is made through a simple copying of the source file or directory to the source destination, where you have to respect the
source name pattern
you chose.
If all of your files have the same extension (e.g.
.zip
), you can define it in the
source name pattern
, and can ignore this option (or clear it for better performance). If you offer files or documents of multiple extensions and do not want to encapsulate them into zip files, directories or other unified containers, you have to define a comma separated list of all extensions (including the dot) in this field. In this case, please do not enter any extension in the
source name pattern
. MmPASS will serve a file matching the source name pattern and the first matching extension.
list
Source Name Pattern
Please see also details above in the
Source Extensions
paragraph.
Depending on your system configuration and on the
Symbolic links
setting, the product source files or directories are located either in the Miva Data or the Miva Script (public web) directories.
-
Symbolic links from Miva Data directory:
By default, the source data should be placed in the
mmpass/source/
subdirectory of your store data folder. If the Source Name Pattern begins by a slash, the paths defined in the pattern is used to search the source file names relatively to the Miva Data root (typically
~/htsdata
,
~/mivadata
or similarly in your user account home). So for example if you use a pattern
/downloads/%name%.zip
, MmPASS looks for files named exactly as the product, with a zip extension in the subdirectory /download/ of your Miva data dir (typically
~/htsdata/download/
).
If the pattern does not start with a slash, the source files are searched in the default location (typically
~/htsdata/Merchant2/00000001/mmpass/source
)
-
Symbolic links from Web directory:
This option is used when the structure of Apache directories does not allow symbolic links from the public area to the hidden data area - usually when the user home directories are not within the Apache main document tree. When using this option, and the Source Name Pattern does not start with a slash, MmPASS looks for source files in the directory defined in the
Download Directory
parameter (
/download/
by default). If it starts with a slash, the files are to be placed into the path defined in the Source Name Pattern, relatively to the
Web Document Root
. For example if you use a pattern
/new/files/%id%
, MmPASS looks for files named exactly as the product ID (not the code!), with any extension defined in the
Source Extensions
option and in the subdirectory
/new/files/
of your Web root directory (typically
~/web/new/files/
,
~/www/new/files/
,
~/htdocs/new/files/
or similarly).
-
Copies from Miva Data directory:
This option is used when
Symbolic Links
are disabled or not available on your system. MmPASS looks for the source files in the same way as in the first case (Symbolic links from Miva Data directory), with the difference that files are being copied physically instead of just creating links.
Examples of source name patterns:
-
%code%
- default pattern. Product codes are used as source file (or directory) names. If extensions defined in the
Source Extensions
option, all of them will be tested.
-
%id%.exe
- the numeric product ID of the Miva Merchant's product.dbf is used and all source files (or directories) have to have extension '.exe'.
-
/files/abc_%name%-%opt_code%.zip
- the source file names should start with the string 'abc_', and the rest is composed from the product name, a dash, the product attribute code, an extension .zip and it is looked up in the /files/ directory instead of the default source directory in the mmpass data folder. Each product / option combination must have a separate source file.
-
affiliates/%affil_code%/%code%
- source documents or folders are looked up in a subdirectory of /Merchant2/00000001/mmpass/affiliates/. The name of the subdirectory uses the affiliate code as name and the source files or directories are named by the product code.
-
%opt_code%.pdf
- only the option code is used for source names. Use together with the option
Standalone Attributes
With the help of
%ship_zip%
,
%ship_state%
and
%ship_cntry%
tokens you can also serve different products to users from different location. If required, additional tokens may be added to MmPASS - for example time / date based tokens, user language tokens, etc.
list
Target Name Pattern
Target name patterns allow you to map the original file or directory names into the ones that are offered to the customer. They may be identical to the source file names or totally different and do not need to respect the original patterns at all. In extreme case you may set a pattern without any token, such as
file.zip
,
download_directory
or
members
- MmPASS will always use the same name, they will just be always in another customer's private directory. With other parameter you can set the
expiration time
, the
length
of the cryptic name of the private directory and choose whether each order should be placed in a separate directory or kept in a
common customer's private dir
.
In contrary to the
Source Name Pattern
, the target names are always realtive to the
Download Directory
.
list
Standalone Attributes
Depending on the Source Name Pattern, products with attributes or options may be served ignoring the attributes / options (same files for each products with different attributes) or as a different file for each product / attribute combination. When selecting this option, MmPASS serves product attributes / options as standalone products - always the same file for an attribute regardless of the mother product. For example if you sell computers you can offer same downloadable software options at different computers. Checking this option allows you to have just a single source container for each software option regardless of the computer type.
list
Path To WWW Root
It is the absolute path from the machine root to your public web directory root. MmPASS attempts to find it automatically, but if the displayed paths does not fit your real system setting, please modify it accordingly
list
Download Directory
This is a path to the directory where customers' private directories are going to be placed. If the
Symbolic links from Web directory
option is used, it is also the home of the source names. The directory is created automatically at the first purchase and a
.htaccess
file is created protecting the directory from unauthorized access and browsing the subdirectories. Please be sure to verify it or create the
.htaccess
manually if the directory already exists.
list
Dir Name Length
For each new customer (if
Keep User Dir
option selected) or for each new order, a new private directory is created. It contains symbolic links to, or copies of (if symlinks not available) the source files or directories. This parameter controls the length of the unique cryptic name of the customer's directory. Defaults to 16 characters. I recommend using long directory names especially if no other access control selected (password, IP,...).
list
Login Prompt
Prompt to be displayed on the login pop up window.
list
Password Type
MmPASS
offers several options for handling passwords. If you offer the URL automatically upon purchase and use other types of protection like IP address and other Authorization options, you may disable the password protection and make so the access easier to the customer. The directory names have to be accessed through cryptic URLs of the default
length
of 16 characters, If you use relatively short expiration time, it would be practically impossible to guess or crack the URL even if there is no password protection.
Second option of re-using Miva Merchant passwords works if the user has created an account for shopping in your store. People ho order without creating an account have no passwords and therefore a new password is created for them by MmPASS. In the same way a new password is created if you selected the third option. Passwords are random, cryptic of a
defined length
and case sensitive. Accounts with passwords created by MmPASS, the customer has to use the shipping e-mail address as login (case sensitive).
list
Password Length
If a customer did not create a user account or if you did not selected re-using of Miva Merchant passwords in
Password Mode
, a new random and cryptic password is created. Its length is controlled by this parameter. The longer it is, the higher is the security, but the more users will not be able to enter them correctly (they are case sensitive). Passwords longer than 8 characters are unnecessary (unless you just want to claim a higher security), because all characters above 8th place are ignored.
list
Expiration Time
Time in seconds after that the account expires and the files are removed from the customer's private folder. If there are no other products remaining in the folder, it is removed completely. If you use the
Keep User Dir
option, and customer has placed multiple orders, each product has own expiration time - older orders will expire before the new ones. If set to zero, files never expire and remain available unless you remove them manually. Please note, that currently the accounts are checked only upon an order submission. If you for example set the expiration time to twenty minutes, but the next order (of any customer) comes 5 hours later, the first customer can access his/her personal folder during all that time. Expired files are purged also when displaying
MmHTMLc
,
MmHTML
or
MmPSLP
reports containing MmPASS calls, in the
Ultra Batch report
.
list
Allow Directory Index
When un-checked, MmPASS adds
Options -Indexes
to the
.htaccess
in each customer (or order) directory to prevent the authorized user from viewing the directory index displaying all available files. Unauthorized user cannot access the index at all, regardless of the setting of this option. By default, indexes in customer folders are allowed, but the listing of the root directory containing the customer accounts, is denied. If you plan to disable indexes, please be sure to test this feature - in some specific cases the control of the indexes through
.htaccess
may be restricted in the global Apache configuration.
list
Payment Methods
You can control the creation of the customer's access URLs through several methods. If you add MmPASS tokens to
Additional Header
,
Footer
or
Column
in the
MmHTMLc Customer Confirmation
module, the URLs are being created in the moment of completing the order. Although the URLs are created, you have the choice of sending the Customer Email automatically and immediately or later, manually from the
Ultra Batch Report
. You can also enable the
On-Screen Invoice
option in MmHTMLc, display the URLs on the final checkout screen and allow immediate access to the products.
Alternatively, you can put the MmPASS tokens into the
Additional Footer
or
Column
in the
MmHTML Merchant Notification
module (resp. the
MmPSLP Packing Slips
module). In this case the URLs are being sent to you instead of to the customer. After approving the payment, you can forward the e-mails with access URLs to the customer.
The automated creation of the URLs in all above cases runs only at orders with payment methods fitting the selected choice (this option). Orders paid by the non-selected methods have to be processed first in the Miva Merchant Admin (Order Processing). When processed, you can re-run the invoices in the Ultra Batch Report, generate the URLs and send the invoices to the customers.
list
MmPASS Authorization Options
MmPASS adds access control directives to the .htaccess file in each individual access folder. Please note that some directives verify such users parameters that may change at the next access. If you plan to keep the user folders for long period, it is better to choose less restrictive settings. In contrary, if you wish to deny the account as soon as possible after the download, you may use all available options. The use of a password is optional and when you use strict authorisation and short expiration time, it may me redundant and only complicating the access - by experience I know that people are unable to type passwords correctly and will ask you for assistance the more often, the longer passwords you use.
NOTE:
some authorisation directives used by MmPASS are available only with Apache version 1.3 or higher. Please be sure to carefully test the authorisation, before going live. AFAIK,
.htaccess
authorisation does not work with IIS servers and may be ignored also by some other, more web servers. However, the vast majority of web servers today run Apache.
list
Verify User's IP address
Only access from the IP address used during the purchase will be permitted. Please note that the IP address changes at most Internet users usually at each new dial-up session, and in some cases (e.g. at AOL), it may change also during a single session. In such case, the AOL user can finish a started download, but might have problems if he/she has to re-start it. Also, the IP address reported to Apache and Miva is often not the real IP address of the user, but rather an address of a proxy server or a LAN router - potentially more individual users may use the same address.
See also the common notes - Authorization Options
list
Verify User's Host domain
User's host domain usually contains the domain name of user's ISP. In some cases, or if DNS lookups are not enabled in Apache or Miva Empresa, the variable may be identical to user's IP address. It may change if the user accesses your website through another Internet access provider, so it is not the best authorization choice for long term accounts or mobile customers.
See also the common notes - Authorization Options
list
Verify User's Browser
Only users with User-Agent (browser) ID string identical to the original ones are allowed in. The ID string usually contains type and version of the browser, operating system and possibly ID of some browser extensions. The string usually changes if the customer uses another computer, another browser, or if he upgrades the browser or operating system.
See also the common notes - Authorization Options
list
Verify User's Cookie
A unique identifier is set by Miva Empresa through a cookie to each customer's browser. If this option selected, Apache authorizes only the original browser for accessing the directory.
See also the common notes - Authorization Options
list
Verify User's Language
Browsers use to send user's language preferences to the server. The 'accept-language' string can serve an additional identification increasing the security slightly.
See also the common notes - Authorization Options
list
Verify User's "Accept" String
The 'Accept' string contains list of accepted MIME formats or installed applications and browser plug-ins. It may change frequently as the user installs or updates applications. This option offers a complementary security for short-term accounts.
See also the common notes - Authorization Options
list
Verify Referer URL
Use this authorization only if you show the download / access URLs directly on the check-out screen with the help of the MmHTMLc "on-screen invoice" option. It would not accept the user accessing from links sent by e-mail in the order confirmation. In
truXoft Customer Email
settings, you should disbale sending the notifications (
'Send on checkout'
) and enable the
'replace on-screen invoice'
option.
See also the common notes - Authorization Options
top
Compatibility
-
truXoft MmHTMLc or MmHTML v1.29 or higher required
MmPSLP
was succesfully
tested
with following following Miva engines:
-
Miva Empresa 3.77, 3.78
-
Miva Empresa 3.91, 3.92, 3.93
with following Miva Merchant versions:
-
Miva Merchant 2.2x, 3.xx, 4.xx
-
MMUI, OUI, any UI
Best performance and security would be achieved with
Apache 1.3+
on
Unix
platforms (e.g. Linux). Symbolic links and advanced password protection is not available on
Windows / IIS
server platforms - see the details
below
.
top
MmPASS Installation
Brief installation instructions follow. If you are unfamiliar with installing Modules, check out the Miva documentation at:
http://www.miva.com/docs/merchant/
For the case you are not familiar with Apache and Empresa configuration and have problems with installing the module, and value your time, you may consider purchasing the installation by
truXoft
. We will find the best possible setting fitting your system and needs.
-
Be sure to allow the use of
symbolic links
in the Miva Empresa configuration file (
SecurityOptions=15
in miva.conf).
-
Verify if Apache allows overriding of options in
.htaccess
files (
AllowOverride all
in httpd.conf)
-
Save the file module somewhere on your PC / Mac.
-
Launch the Miva Merchant Admin System, usually at http://www.yourdomain.com/Merchant2/admin.mv
-
Enter the administrator username and password
-
Click on the Blue Expander Triangle beside the word
"Modules"
to open this menu tree
-
Click on
Add Module
-
Click on the upload file icon to the right of the text field
-
A popup window will appear. Click BROWSE and find the Module you have just saved on your local drive.
-
Click
OPEN
-
Click
UPLOAD
-
Click
ADD
. Miva Merchant has now installed this module, but it is not yet assigned to a store
-
Click on the blue Expander triangle to the left of the store name to open its menu tree.
-
Click on
'System Extension Configuration'
-
Check the
'truXoft Software Delivery'
and click the Update button
-
Click on the
'truXoft Software Delivery'
tab, and set up the parameters as explained above in the
Configuration Options
chapter.
-
Put your software products, documents or web sites into the directories and using the
name patterns
as set up in the MmPASS configuration.
-
In
MmHTMLc
settings (Order Fulfillment configuration), add
MmPASS
function calls to the
Additional footer
and
User-Defined Column
.
Please note that the code must be in the "Additional Footer / Miva Expression field" (single line input), not in the HTML footer (multi-line textarea).
See examples and available possibilities below:
There are three available MmPASS tokens:
%MmPASS-url%
,
%MmPASS-login%
and
%MmPASS-pwd%
MmHTMLc Customer Email:
can be used to send the links by e-mail automatically upon a successful payment verification, or manually from the Ultra Batch report after approving them.
MmHTML Merchant Email:
can be used to receive the links by e-mail automatically upon a successful payment verification and manually forward the notification e-mails to customers after approving them.
MmPSLP Packing Slip:
may be used for printing the download URLs and access information on packing slips and send them to the user with the hardware part of the order physically.
You can insert MmPASS tokens in the footer and in the user-defined column expression. The %MmPASS-url% token returns a relative URL of each individual product (if used in user-defined column) or a relative URL of the users personal directory (if used in Additional footer expression) containing all individual products. %MmPASS-login% and %MmPASS-pwd% return (as you may guess) the access login and password.
Examples of use of the MmPASS tokens:
Example for
User-Defined Column
: (single line)
<A HREF="http://mydomain.com%MmPASS-url%" TARGET="_blank"><B>download</B></A>
Example for
User-Defined Column
with hidden output - for the use with
common URL entry
:
<BR %MmPASS-url%>
Note:
there
must
be the
%MmPASS-url%
token in the
user-defined column
. If you do not wish to display it in this place, please use the above example for hiding it.
Example for
Additional Miva Script footer
: (single line)
<BR><B STYLE="color:red">Your login:</B> %MmPASS-login%<BR><B STYLE="color:red">Your password:</B> %MmPASS-pwd%
Example for
Additional Miva Script footer
- with
common URL entry
: (single line)
<BR><B>Access URL:</B></A HREF="http://yourdomain.com/members/" TARGET="_blank">http://yourdomain.com/members/</A><BR><B>Your login:</B> %MmPASS-login%<BR><B>Your password:</B> %MmPASS-pwd%
Another example for
Additional Miva Script footer
- with
common URL entry
, table formatted:
<TABLE><TR><TD STYLE="color:red"><B>Access: </B></TD><TD><A HREF="http://yourdomain.com/download/" TARGET="_blank">http://yourdomain.com/download/</A></TD></TR><TR><TD STYLE="color:red"><B>Login: </B></TD><TD>%MmPASS-login%</TD></TR><TR><TD STYLE="color:red"><B>Password: </B></TD><TD>%MmPASS-pwd%</TD></TR></TABLE>
-
Perform a test order.
-
Verify the functionality and security of the Apache authorization mechanism.
Important Note:
please be sure that your Miva Empresa is configured so that it does not allow the use of the long cgi-bin formed URLs and that the parameter
validextensions
is used in your miva.conf! Some hosts use to install several Miva Empresas (e.g.
miva
,
miva-393
,
smiva
,
miva-redirect
,...) - in that case
all
of them must be set in this way. If it was not that case, a malicious user could use these imporperly configured engines to access your protected directories! Find more details in the
art001.htm
.
top
Support
We offer a
limited free suport
within 30 days after the date of the purchase for modules bought directly at
truXoft Co.
or at affiliated resellers as written above. The support is limited to platforms from our compatibility list below and does not include any help with installation or configuration of payment modules, or other general Miva Merchant problems.
Some non-standard features are not included in the free support, and they are also not included in the standard develper installation. All support requests and installation help with these unsupported question will be charged $100/hour (each started hour billable).
List of options excluded from the Limited Free Support:
-
Serving files from a
remote server
-
Importing data
from other applications
Some questions may be answered in the
FAQ
or may be solved with the help of other more experienced users on the
Miva Merchant User List
. I am monitoring all Miva lists and, if possible, will help with related problems posted to the user groups.
top
Known Limitations and Bugs
-
IIS Limitations (Windows servers)
:
-
Miva Empresa for Windows does not support symbolic links, so only copying could be used. As long as you do not plan to sell member access (directories), but rather just individual files with the MmPASS, it would not be too bad.
-
IIS on Windows does not support the
.htaccess
standard and there is no direct possibility on IIS to control the directory / file access from within a Miva application. It means that all those features like password protection, authoriztion of cookie, IP, agent,... would not be available. The only way to protect the directories on Windows/IIS would be using the cryptic directory names and if possible short expiration times.
top
Frequently Asked Questions
Please have a look also at the
FAQ
of
MmHTML / MmHTMLc
and
Ultra Batch
INSTALLATION
GENERAL
CONFIGURATION
ACCESS PROTECTION / AUTHORIZATION
NOTIFICATION / INVOICE
faq
INSTALLATION
Why
doesn't
the module
appear
in my store?
I guess you have forgotten to hit the
Add
button after uploading the file in
Modules/AddModule
faq
I don't know how to install the module and can't follow these instructions
Read the Module Installation documentation at
http://www.miva.com/docs/merchant/
faq
I want to add this module to another store, what do I do?
This module requires one license per use. You won't need to repeat the installation, but you will need a different license key to assign it to your new store.
faq
How do I update the module?
Click on the
update
link in the header of the module's control panel in Admin. Download the updated module from the upgrade center. In Admin Go to
Modules
» module name »
Files
, click the upload icon button right to the
Module
input field, check
"Overwrite"
, locate the new file on your disk, click
UPLOAD
and when you are back in the big window
do not forget
to click the
UPDATE
button! Click back to the
Information
tab and verify if the version was updated. Now enter the module's Admin screen in the
System Extensions
. The last step is necessary at updates where the settings database structure has changed - the changes are activated only upon opening the Admin screen.
Please note that if you have bought the module at other reseller than
MvCool
, usually you have to use the address of the reseller as the "
e-mail address assotiated with the license
" (for example sales@vikingcoders.com). You should have received intstructions from the reseller when purchasing the module.
faq
I cannot find the MmPASS settings screen. Where is it?
As written in the
installation guide
: Log into your Miva Merchant Admin and go to
Stores
»
'your store'
»
System Extension Configuration
»
truXoft Software Delivery
.
faq
GENERAL
What are the customer folders and where do I find them?
MmPASS
creates a separate directory for each customer (or optionally for each order). This directory contains only the purchased software products and is protected with user's password or other selected authorization options. The directory contains either directly the purchased product file(s) (their copies) or so-called
symbolic links
(shortcuts, pointers) that save space, CPU time and allow serving not only individual files, but even complex directories.
If you own also the
Ultra Batch
module, you can control (view, remove, re-initialize) customers' accounts without having to access the personal folders. In case you do not have the
Ultra Batch
and want to manually remove customer accounts before their expiration, or change authorization options in their .htaccess file (i.e. disabling cookie protection (if active) at users who cannot access their accounts anymore due using another PC), you can find them in FTP or Telnet/SSH inside of the
Download Directory
, as defined in the MmPASS settings. The download directory (by default
/download/
) is a subdirectory of your public web dir.
faq
You refer to "copying" as the only option on Windows systems but there is no explanation of what copying is.
Each customer has her/his own
private directory
containing only those products (i.e. files) that she/he purchased. On Unix machines it is best handled virtually, with symbolic links (shortcuts) to the real files instead of copying the product files to each customer's directory. Symbolic links are not available on Windows machines (Miva does not handle Windows shortcuts) and therefore the files must be copied physically to each customer's directory.
faq
CONFIGURATION
Downloadable link as in your example used in MmHTMLc does not work!
Please be sure that you put expressions from my examples into the right field(s). They have to be in the
Additional Miva Script Footer
and in the
User-Defined Column
(single-line input fields), but
not
in the
Page Header
/
Page Footer
(multi-line text-area inout fields)!
faq
I am getting "Page Not Found" erros when clicking on the download link!
Hmm, did you replace the
"yourdomain.com"
with the real name of your domain?
faq
I serve full directories. Do I need to enter all used extensions into "Source Extensions"?
If the source object is a directory, no extensions at all need to be defined in the MmPASS settings. MmPASS does not care what is inside of the source object. Only the source object (directory in your case) matters. If the source objects are files of different extensions (e.g. at some products you have
*.zip
files and at others
*.tar
, you have to puy both extensions into the
"Source Extensions"
field. If all of your files use the same extension, you may put it directly into the source name pattern (e.g.
%code%.zip
).
faq
I put absolute paths into the name patterns, but it still does not work!
When your source files or directories are in the default directory (
...Merchant2/00000001/mmpass/source/
), you do not need to use abolute paths. Absolute paths are necessary only if you want to put the files in another location within the Miva Data directory (resp. the Miva Script / public web directory if you chose the option
"Symbolic links from Web directory"
). Please note that abolute links are not really abolute in view of the server, but just within the sandbox of the respective Miva data/script firectory! In another words: relative paths (
not
beginning with a slash) in the pattern names are relative to the default source dir (
...Merchant2/00000001/mmpass/source/
), and absolute paths are relative to the Miva data root (typically ~/htsdata/, ~/mivadata/, ~/data/ or similarly - depends on your host's settings), respectively to the Miva Script root (usually identical to your public web directory).
faq
I want that customers access the files through a common URL (e.g. http://mydomain.com/members/), is it possible with MmPASS?
With the help of the attached "
index.mv
" and
.htaccess
files you may set up a common URL to facilitate the access to your customers. In this way you do not need to send the individual download/access URLs in the notification e-mail.
You simply create a directory in a public web area of your server and give your customer this simplified URL, for example
http://yourdomain.com/members/
. Edit the "index.mv" so that it containes the right
Store_Code
(you can see it in the URL of your Merchant store) and the right path to the Merchant root directory (typically
/Merchant2/
on MM2 and MM3,
/Merchant2/4.10/
,
/Merchant2/4.12/
or similar on MM4). Put both files (
index.mv
and
.htaccess
) into the directory and verify that the
.htaccess
file is readable by web user (permission
755
or
644
). The
index.mv
usually works even with permissions
700
, but on some systems you may need to use
744
or possibly even
755
.
faq
Can MmPASS serve files from another server?
Yes. All you need to do is using small shell (or Perl) scripts pointing to the original files on the remote server.
Say we have a product with product code
XYZ
and attribute code
012
. Assuming that you want to use attributes you should have chosen the following or similar source pattern:
%code%-%opt_code%
Normally, if serving files from the same server, you would put the product file into the source directory (
mivadata/Merchant2/00000001/mmpass/source/
by default) either into a zip file called using to the source pattern "XYZ-012.zip", or into a subdirectory called "
XYZ-012
" or simply a file with any extension from the list in the "
Source Extension
" option of MmPASS - for example "
XYZ-012.exe
", "
XYZ-012.pdf
", etc. Remember that file names are case sensitive on Unix, so you have to keep exactly the same case as in your product and attribute codes.
However, because the files are not available on the same machine, you will replace the real files with simple caller shell scripts. Again, depending on the extension of the real file, you create a small shell script with the following content and name it using the source pattern. So if for the product
XYZ
, attribute
012
you want to serve a zip file, with a text editor (e.g. NotePad) you'll create a file containing the following two lines and call it "
XYZ-012.zip
":
#!/bin/sh
GET -e http://fileServerDomain.com/path/XYZ-012.zip
Additionally you have to tell to Apache to process the files of this extension (or any other used extension) as a CGI script instead of serving it directly. If there is already the target directory on the system (by default
/download/
in the public dir) and there is a .htaccess file, you have to add the following lines into it (if the target (download) directory on the Merchant server does not exist yet, you have to create it an put the
.htaccess
into it):
Options +ExecCGI
AddHandler cgi-script .zip, .exe, .pdf
where you replace the extensions with those you plan to sell.
On the remote side of the file server, you should protect the files so, that they can be requested only from the Merchant server. In the directory where the files are located, add the following lines to the
.htaccess
file (or create a new one if there is not
.htaccess
):
<Files *>
Order Deny,Allow
Deny from all
Allow from merchantServerDomain.com
</Files>
Be sure to upload cgi and .htaccess files in
text mode
! Uploading them in binary mode can cause 500 Internal Server errors (in case of scripts) or 403 errors (in case of .htaccess).
Please note that support requests on this option are not included in the
limited free support
available with the purchase of
MmPASS
and are subject of support fee of $100/hour (each started hour billable). Setting up MmPASS for serving from remote server is also
not
included in the
developer installation
support option.
faq
How do I set individual expiration time for different products?
Insert the following hidden tag including the expiration time in seconds (e.g. 86400 for 24 hours) into the description of each product that should have different expiration time than the one set in MmPASS settings:
<MmPASS 86400>
faq
How can I serve free download products automatically?
Go to
MmPASS
settings in
Admin » Stores »
'your store'
» truXoft Software Delivery
and add the
--none--
option to the list of selected payment methods for automated fulfillment.
faq
ACCESS PROTECTION / AUTHORIZATION
I can access the user root directory, but access to the product subdirectories is denied!
OK, so you serve directories (websites) with MmPASS. Did you remove the
.htaccess
file you had there originally? They must be removed or accordingly modified, not to override the
.htaccess
settings in the customers private directories as set by MmPASS.
faq
I removed password protection and all verification options, but still cannot access the user directory!
For the testing, you can disable the
.htaccess
file in the public download root and in the user directories. You can do it with renaming the file (disables all) or commenting out individual lines of the file. If nothing of it helps, and you are still getting "Unauthorized Access" errors, then you may be the unlucky case when the directories are set in such a way, that Apache cannot access the source onject in the data directory through a symbolic link. You have to use the option
"Symbolic links from Web directory"
and move the data to the public download root (by default the
/download/
subdirectory in your public web dir). If you made already some tests, the directory is already there and all access to it from the web is denied. Only authorized access through symbolic links in the user subdirectoires is possible. The source files in the source root are never accessible directly (please test it).
faq
I have had to enter the username and the password twice. Any way to limit this to one time?
The answer is here:
http://httpd.apache.org/docs/howto/auth.html#passwordtwice
It happens when, for example, the link that is set in the MmHTMLc settings uses the a http://www.yourdomain.com, but when you log in it, is redirected to http://yourdomain.com (or vice versa) - for the browser it is another domain name and as such it must be authorized again (second time).
I guess it is problem somewhere in your Apache settings. Maybe use of the
UseCanonicalName
directive or the
mod_rewrite
module - I can't tell for sure without digging into it. Generally, to avoid problems with authorization and with cookies, you should always use the same form of the domain name. If your Merchant uses www., set it so in the download link too. If it was not there, you may need to remove the checking of cookies in the MmPASS settings, because the
www.yourdomain.com
Domain name sets another cookie than the
yourdomain.com
domain.
faq
I serve a website with MmPASS, and can access the index page OK, but am getting
"Forbidden"
for all other pages!
It looks like you are using abolute URLs or paths pointing to the source directory.
Nobody
is authorized to access the original source documents! Everybody has to access them through their private URL and everybody is authorized to use only own private directory - neither the common one, nor a directory of another customer! You
must not
use absolute URLs - they are different for each customer. You have to use relative paths only (unless you link to an external site or to documents in the public non-restricted area)! For example, if you want to link to a subdirectory
01
, simply use this link:
<a href="01/index.html">LESSON ONE</a>
That's all you need to do - additionally, you save a lot of typing an some bandwidth with the shorter URLs, too :)
faq
I want to offer free access to some users. How to do it?
There are several way possible. One of theme is this: Check the feature called
"Price Groups"
in Miva Merchant documentation. Set up a price group, set the prices of the downloadable products to zero for members of this group and give them the access to it. Do not forget to add the
'--none--'
option in the list of payment methods used for automated fulfillment, if you want that they recive the download/access links automatically in the notification e-mail. If you do not do it, you have to approve manually each order, and resending the Customer Invoice containing now the download links from
Ultra Batch
.
faq
NOTIFICATION / INVOICE
Can I display the login and password nicer aligned?
Sure. You can use any HTML formatting in the expression with download patterns, TABLEs including. So, for example you can put this code into the MmHTMLc
Additional Miva Script Footer
(one line):
<TABLE><TR><TD><B STYLE="color:red">Your login:</B> </TD><TD>%MmPASS-login%</TD></TR><TR><TD><B STYLE="color:red">Your password:</B> </TD><TD>%MmPASS-pwd%</TD></TR></TABLE><BR>
faq
How can I send the notifications with download links after approving them?
If you use multiple payment methods, you can define which payment methods may be used for immediate sending of the download / access links. So for example you may set payments by CC, but disable payments by check. In that case you will need the
Ultra Batch Report
module - after approving the orders you may re-send the notifications including the download links from the Ultra Batch report user interface. Approving is as simple as processing the selected orders or just marking them as processed.
top
Troubleshooting
In case of troubles, before contacting the support, please be sure to:
-
read the
FAQ
-
check the
changelog
and
update
the module to the latest version
-
read
known limitation and bugs
Fixing Installation Problems
-
No links created
-
'FORBIDDEN. You don't have permission to access ... on this server'
-
'500 Internal Server Error'
-
Binary files are being displayed in the browser window instead of downloading!
-
Passwords not accepted when using the Common URL
No links created
See below a list of possible reasons for no links appearing on the checkout invoice or in the customer order confirmation e-mail. For searching the reason, the best is viewing the Customer Invoices in
Ultra Batch
- in this way you do not need to submit any new orders. Once you fix the problem, the links appear in the invoices in Ultra Batch and you can re-send the e-mails to customers.
-
Missing / wrong expression in MmHTMLc settings
-
Private directories/URLs containing products (files, documents or access to member areas) are created only if a call to the MmPASS module is present in the MmHTMLc (truXoft Customer Email) settings. Please check the installation instructions and verify if you have added an expression containing a MmPASS token into the MmHTMLc header, footer
and
column expression fields as described in the installation manual. Please be sure to have the expression in the Additional Miva Script Footer / Header and or User-Defined Column (small input boxes) and not in the Page Header / Footer (bigger text area boxes).
-
Wrong location of source files
-
When an order is processed, MmPASS looks in the source directory for the presence of a file named using the pattern. By default it looks in the directory
/mivadata/Merchant2/00000001/mmpass/source/
(please note that the path may be beginning differently - depending on your server and Merchant setup, but the source subdirectory is in your store's data folder, not in the location where the *.mv scripts are located). Only if you use the option "
Symbolic Links from Web Directory
", MmPASS looks for the files in the "
Download Directory
" as defined in the MmPASS settings.
-
Source filename does not match the source pattern
-
During processing the order, MmPASS looks in the source directory (see
above
) for a file named using the "
Source Pattern
". By default, the source pattern is set to %code%. It means if you have a product with the product code
ABCD-XYZ-123
, and want to serve it with MmPASS, there must be a file or a subdirectory in the source directory called
ABCD-XYZ-123
. Subdirectory is necessary only if you want to offer multiple file for one product and for some reason do not want or cannot offer them in a packed archive. Another reason for using subdirectories is when you use MmPASS to sell access to member restricted areas, where the subdirectory contains for web page(s) and their elements. When MmPASS does not find any files or subdirectory as defined by the source pattern, it retries it with every extension defined in the "
Source Extensions
" list. In our case, with the default extension setting "
.zip,.exe
", it would look for the file
ABCD-XYZ-123.zip
and, if not found, for
ABCD-XYZ-123.exe
. If all products you serve have the same extension, you can add it to the source pattern (e.g.
%code%.exe
) and clear the extension list in "
Source Extensions
" to avoid unnecessary file lookups.
-
Mismatched case in the filename
-
Please note that on Unix systems, unlike under MS Windows, filenames and directory names are case sensitive. The source file has to be called using exactly the same casing as your product code in Miva Merchant!
-
File extension not defined
-
You have to define the file extension of your file (e.g. exe, zip, html, mp3,...) either in the "Source Extensions" list, directly in the source pattern (if same at all downloadable products) or in the product code (less usual solution). When selling products of different types (using different extensions), you have to put all of them into the comma separated list in the "Source Extensions" option.
-
Permission problem, data / script dirs owned by different uid
-
This is relatively rarely a problem, but I have already seen misconfigured servers or accounts at very restrictive hosts, where copying from the Miva Data directory to the Miva Script (public) directory fails because of directory ownership or permissions. Usually you will need to contact your host to fix that problem.
-
No payment method selected
-
If you did not select any payment method for automated fulfillment in
MmPASS
settings, no download links are being created in the
MmHTMLc
notifications and they appear in the Customer Invoices in Ultra Batch only after you have processed the orders (or marked them as processed). Note that you can select one or multiple payment methods for the automated fulfillment (hold the Ctrl key down when clicking multiple methods). Or none of them, of course too, if you wish to process all orders manually.
-
Zero-price product used
-
For the testing, people often set a zero price at the test product and then wonder why it is not served by
MmPASS
. As mentioned above, only products paid by a selected payment method will be process automatically. All other orders have to be approved manually (processing them or marking them as processed), before you can re-send the customer notifications (in Ultra Batch) now including the download links and login information. When you set a zero price, Miva Merchant does not run the purchase through
any
payment module and therefore (by default) MmPASS won't serve it automatically. However, the solution is easy: simply go to
MmPASS
settings and add the
--none--
listed at the top of available payment methods, to the list of payment methods selected for automated fulfillment.
'FORBIDDEN. You don't have permission to access ... on this server'
-
Too strong authorization options
-
Please read the section
"Authorization Options"
for detailed explanation of each option and their advantages and disadvantages. The more authorization options you enable, the securer the protection will be, but the more support requests from users unable to access the files you will get. For the installation I recommend clearing all authorization options (except the password protection) and add the ones you want to use, step by step after you have successfully tested the functionality of the module with plain password protection.
-
File permissions on the source file
-
When using the "Symbolic Links" method in MmPASS, the source files have to be word readable. Recommended permission setting is
604
for files and documents and
705
for source directories.
-
.htaccess in the download (target) directory
-
In some cases, especially at earlier versions of MmPASS, the
.htaccess
Apache configuration file that is automatically generated in the "Download Directory" (as defined in the MmPASS settings), can cause unability to access any subdirectory. Rename the file to disbale it, or edit it to disable individual lines to see if it helps.
-
Symlinks not allowed to the Miva Data directory
-
Depending on the Apache configuration and on the directory structure of your server, Apache may refuse serving files represented by symbolic links pointing to directories in the Miva Data space. In that case, you have to change the first option to "
Symbolic Links from Web Directory
" and move the source files to the "
Download Directory
" in the public area (
/download/
by default). I recommend creating a subdirectory
/source/
in the
"Download Directory"
(by default it would be
/download/source/
) and moving your source files, documents or directories into the new
/source/
directory. In the same time you have to change the source pattern from the default
%code%
to
/source/%code%
(or equivalent if you use another pattern). Please be sure to protect the source directory in the public area with a
.htaccess
file with the following directives. Place it directly into this directory (
/download/source/
in our case)
# base download directory - access denied
Options -Indexes
Order allow,deny
Deny from all
<Files *>
Order allow,deny
Deny from all
</Files>
You can recognize this problem (symlinks not allowed in Apache) easily: go to one of the tested cryptic directories and rename its .htaccess file (e.g.
/download/9ULAxyzAvuWOk1QA/.htaccess
) for example to .htaccess.orig. It means you are disabling the protection completely and if you have previously already disabled the .htaccess in the upper
/download/
directory, the files have to be accessible directly without any authorization. If you are still getting FORBIDDEN error, it means that you cannot serve the source files form the Miva Data directory, but rather from a public folder.
'500 Internal Server Error'
-
Old Apache version not supporting for example the SetEnvIf directive
-
MmPASS can restrict the access to the product files / directories not only with the password, but also with additional authorization options. Most of these options use the SetEnvIf Apache directive in a .htaccess file. This directive is available since Apache version 1.3.13. If you run an older version, you would get a
500 Internal Error
when using most of the MmPASS authorization options, except
Host
and
IP address
. Plain password authorization works, of course, on older Apache version without problems.
-
Wrong .htaccess permissions
-
The .htaccess file has to be world readable. MmPASS creates an individual .htaccess file in each personal directory and sets its permissions properly, but if you have modified the permissions of a .htaccess file in one of the personal directories or directories above them, be sure that they are all world readable. Directoires should be world readable and executable.
Binary files are being displayed in the browser window instead of downloading!
Most probably you do not have defined any MIME type for the file extension of your products. On Unix/Apache, by default there is usually not MIME type definition defined for the
.exe
extension and some browsers (e.g. MSIE) begin to dump the binary code on the screen when clicking on the download link. You can force most browsers to download it with adding the following directives in the main
.htaccess
file directly in the
Download Directory
as defined in the MmPASS settings:
AddType application/octet-stream .exe
ForceType application/octet-stream
If you serve mixed binary and text oriented files that you wish to be displayed in the browser window as usually, do not use the second directive, but rather just the first one with all binary extensions.
Passwords not accepted when using the Common URL
Be sure you have installed the attached index.mv and .htaccess files into the directory you use for the
Common URL
access. Also be sure that you have edited the file and entered your own correct
Store_Code
and
Merchant_Root
as defined in Miva Merchant.
When testing the Common URL, you have to be aware that it uses cookies to redirect each customer to his own private directory. Threfore, when testing you can use alway only the login and password associated with the first account you have tested. For subsequent tests, you have to use another browser, PC or close
all
browser windows and delete the cookie from your disk.
top
To-Do List / Wish List
-
Account Managment - manual account deletion, displaying expiration times,...
top
Change Log
top
