==============================================================================
Remote Mirrors

- For html version go to http://www.dftpd.com/mirrors.php
==============================================================================


[Overview]
Directory mirroring in Dftpd allows downloads from specified directories to be
automatically distributed among a group of mirror sites. The redirection of 
data connections is done using the same method as remote directory links 
(see distrib.txt). The remote sites specified as mirrors must have 
pre-existing directories that exactly correspond to the directory being 
mirrored. When mirroring is enabled for a directory uploads to that directory
will not be allowed if the data connection is redirected to a remote mirror 
site. In other words, an upload to a mirrored directory will only succeed if 
the selected mirror happens to be the local site -- when files need to be 
uploaded to a mirrored directory either disable mirroring before uploading or
upload the files to a non-mirrored directory and move/copy them on the server.


[Preparing Mirrors]
The first step to creating a mirrored directory is to duplicate it on all the
mirror FTP sites. The full (absolute) path, relative to the users' home 
directory, of the directory being mirrored must be identical on all the remote
(mirror) FTP sites. For example, if the directory "/stuff/" on the local site
is being mirrored, a directory with an absolute path "/stuff/" that contains 
the exact same contents of the local "/stuff/" directory should be created 
on all the FTP servers that will be used as mirrors. If different users have 
different home directories (start directories don't matter), special care must
be taken when creating directory mirrors. For example, if a user called 
"cartman" has the home directory "/home/site/cartman/" and another user 
called "kyle" has the home directory "/home/site/" and the directory 
"/home/site/cartman/stuff/" is mirrored, the directory will not be properly 
mapped on remote sites. This is because when "kyle" accesses the directory the
absolute path will be "/cartman/stuff/" and when "cartman" accesses the 
directory the absolute path will be "/stuff/". 


[Creating Mirrored Directories]
There are two main steps necessary to create a mirrored directory. The first
step is to create a mirror entry containing all the sites that will be used 
as mirrors. The second step is to associate the mirror entry with the 
directory to be mirrored.

To add mirrors to a mirror entry the "SITE REMOTE ADDMIRROR" command is used.
Each mirror is specified by an alias, which is the directory path used as a 
remote link to a FTP site. (see distrib.txt). The ADDMIRROR command takes
3 parameters: MirrorID, weight, and alias. The MirrorID is an integer 
used as an identifier for the mirror entry. If you specify an existing 
MirrorID the mirror will be added to the corresponding entry. If a 
non-existent MirrorID is used a new mirror entry will be created. Also, if
0 is used as the MirrorID, a new mirror entry will be created using the next 
available MirrorID. The weight parameter is an integer value used to assign a
priority to the mirror being added. Its value relative to other mirrors within
the same mirror entry (other mirrors with the same MirrorID) determines how
often the mirror will be used. The formula that determines the percentage of
accesses to a given mirror is: (weight / (total weight)) * 100. For example,
if mirror1 has a weight of 15 and mirror2 has a weight of 45 then mirror1 
will be accessed (15 / (15 + 45)) * 100 = 25% of the time. The alias parameter 
specified the path acting as a link to the remote site to be used as a mirror.
Alliases are added using the "SITE REMOTE ADDALIAS" command (see SITE 
commands). In the ADDMIRROR command the alias acts as an identifier for the 
FTP site to add as a mirror. Use the "SITE REMOTE MIRRORS" command to display
the list of mirrors.

To associate a mirror entry with a directory to be mirrored the 
"SITE DIRMIRROR" command is used. This command takes 2 parameters: MirrorID 
and directory. The MirrorID parameter is the identifier for the mirror entry 
to use (as described above). The directory parameter is the path of the 
directory to associate with the MirrorID. If "SITE DIRMIRROR" is used without 
specifying a MirrorID the current MirrorID for the directory will be displayed
(MirrorID = 0 -> none/default). 


[Example]
Suppose there is a directory on the local FTP site with the path, as seen by a
FTP client, "/stuff/games/". This path is to be mirrored on a FTP server 
running on 192.168.1.3 port 21. 60% of the downloads should be from the local 
site and 40% should be from the remote FTP server.

Step 1 - Duplicate the directory to be mirrored
The first step is exactly copy the "/stuff/games/" directory on the local site 
to the server running on 192.168.1.3:21. The path of the copied directory, as
seen by a FTP client, must also be "/stuff/games/".

Step 2 - Create an alias for the remote site (if necessary)
To create an alias for the remote site run:
> SITE REMOTE ADDALIAS /remote_site_3 192.168.1.3 21 user pass / 
This command links the local directory path "/remote_site_3" to the root 
directory on the remote FTP server running on 192.168.1.3 on port 21. The
login to use for the connection is "user" and the password is "pass". Use 
SITE REMOTE ALIASES to display the list of aliases.

Step 3 - Create a mirror entry
To create a mirror entry containing the local site and the site running 
on 192.168.1.3:21 run:
> SITE REMOTE ADDMIRROR 1 60 LOCAL
> SITE REMOTE ADDMIRROR 1 40 /remote_site_3
This will create a mirror entry using MirrorID = 1 where the local site 
will be accessed 60% of the time and the remote mirror site will be accessed 
40% of the time. A simple scheme for picking weights for the mirrors is to 
make them all add up to 100. That way the value of the weight will be equal 
to the percent accesses for the mirror. There is no limit on the number of 
mirrors that can be added to a mirror entry. Use SITE REMOTE MIRRORS to 
display the current mirror entries.

Step 4 - Associate the mirror entry with the directory to be mirrored
To associate the mirror entry with the "/stuff/games/" directory run:
> SITE DIRMIRROR 1 /stuff/games
This will associate the mirror entry created above, with MirrorID = 1, with 
the "/stuff/games/" directory. Once this command is run, all downloads from 
the "/stuff/games/" directory will be distributed between the local site and 
the site aliased by "/remote_site_3", with 60% using the local site and 40% 
using the remote site. The same mirror entry can be associated with multiple 
directories. Use the SITE DIRMIRROR <directory> command (leave out the 
MirrorID) to display the MirrorID associated with a directory 
(0 = None/Default). 

