OS/2 Shareware BBS: 35 Internet/35-Internet.zip/rxmir13.zip/rxMirror.doc

Text File | 1999-02-26 | 11KB | 255 lines

ABOUT

    This program is aimed to serve to two rather distinct purposes. First,
    it is native OS/2 replacement for mirroring programs available under
    UNIX. So if you're wishing to set up a mirror site under OS/2, you're
    on the right way. Second, it is handy when you need to copy entire
    directory tree from remote machine but can't do it via NFS and have to
    use FTP.

    If you're familiar to concept of mirroring, read:
       QUICK START sections,
          try to use rxMirror, then read
       USAGE, BUGS.

    If you're new to mirroring, read:
       MIRRORING CONCEPT, REQUIREMENTS, INSTALLATION, QUICK START sections,
          try to use rxMirror, then read
       USAGE, BUGS.

    If you have troubles, read:
       REQUIREMENTS, BUGS, USAGE.

REQUIREMENTS

    As one might expect, TCP/IP protocol stack is required. IBM includes
    its TCP/IP stack with TCP/IP for OS/2 2.0, OS/2 3.0 Warp (in IAK),
    OS/2 Warp CONNECT, OS/2 Warp 4.0.

    rxMirror uses REXX rxFtp interface. rxFtp in turn uses FTPAPI calls to
    do its job. So you need ftpapi.dll and rxftp.dll in your LIBPATH. If
    you have installed one of the above TCP/IP products, you already have
    these DLLs.

    REXX is required also, of course. You need HPFS-formatted drive to do
    mirroring. rxMirror doesn't apply any conversions to filenames.
    Moreover, it uses HPFS-style names for its logfiles etc. If you're
    copying files which are all 8.3-compliant, you may try to use it on
    FAT drive. It is neither recommended nor supported. Go HPFS!

    The summary of requirements is:

    - REXX support;
    - TCP/IP stack: TCP/IP for OS/2 2.0, Warp IAK, Warp CONNECT, Warp 4;
    - HPFS drive to do mirroring.

INSTALLATION

    It's very simple. Unpack rxMirror distribution archive to any
    directory. If you like to start rxMirror.cmd from the command line,
    this directory must be in your PATH. Copy rx2Util.dll into any
    directory listed in yout LIBPATH.

    You should place configuration files into mirror current directory
    (the current directory when rxMirror.cmd is runned) and to directories
    under mirror root (specified with 'localdir' configuration tag).

    NOTE: Configuration file ".mirror.options" and others are NOT global
    customization file for rxMirror. They are supplied only as an example.
    You should NOT modify them but rather copy them to you're mirror
    current directory.

MIRRORING CONCEPT

    When I started to modify this program, I only had an idea about
    mirroring. I haven't read anything about it (even docs for other
    mirroring programs), so my vision of mirroring may be different from
    common. You might miss some features that are obligatory for mirroring
    software and encounter features that cannot be found in any other
    mirroring program.

    The principle of mirroring is very simple: to create a copy of remote
    directory tree on local machine using FTP. To do this, rxMirror
    traverses recursively remote tree, does "DIR" for each subdir and
    compares its output to local list of files. Comparison is done based
    on file name, length and time stamp. Note that name comparison is case
    insensitive. If there is a difference, rxMirror retrieves remote files
    missing in local dir and removes local files missing on remote. In
    fact, rxMirror does not REMOVE them but places into subdirectory
    ".removed" (configurable).

    After syncronising all directories, the subtree on the local drive is
    a complete mirror of remote subtree, excluding ".removed" subdirs,
    rxMirror logs/configuration (if defined) and really any file/directory
    starting with a dot (.).

QUICK START: COPYING REMOTE DIRECTORY TREE

    1) chdir to directory where you want files to be placed, for example:
          "mkdir \temp"
          "cd \temp"
       please remember, it should reside on HPFS drive!

    2) invoke rxmirror with the following arguments: a) remote machine
    hostname, b) remote directory, c) your login on remote, d) your
    password, for example "rxmirror lnfm1.sai.msu.su /home/solar/asv asv
    Sethanon" NOTE: the password in the above line is obsolete :)

    3) watch copying progress; if it fails, read this doc again :(

QUICK START: SETTING UP A MIRROR

    1) create a directory where your mirror will reside;

    2) copy file ".mirror.options" into it and edit it; warning - if
    you're using real password (not e-mail address) for mirroring, do not
    set it in ".mirror.options" file - you will risk by exposing it to
    others;

    3) start rxmirror having this directory current. if you have filled
    all four necessary fields in .mirror.options file, you don't need to
    supply any command-line parameters; otherwise, you have to enter them
    in the following order: a) remote machine hostname, b) remote
    directory, c) your login, d) your password.

    4) create batch file consisting of "d: & cd dir & rxmirror" and add it
    to crontab if you like

USAGE: COMMAND-LINE ARGUMENTS, CUSTOMIZATION, ERROR MESSAGES

    a) Command-line parameters

-!-
Usage: rxMirror [-?h] [[-s] hostname] [[-d] startdir] [[-u] userid]
                [[-p] passwd] [-l [scrlog]]

 ? or h     - display this help and exit
 s hostname - hostname or IP number of the FTP server, no default
 d startdir - directory from which mirroring starts;
              rxMirror will recurse into subdirs, no default
 u userid   - login id on the remote server, default is anonymous
 p passwd   - password on the ftp server, default is * (for prompt)
 l scrlog   - screen output log. By default logging is disabled.
              Default logname is '.mirror.scrlog' in current dir.

NOTE: For backward compatibility, some option tags are optional.
-!-

    For example:

    "rxmirror -l -s lnfm1.sai.msu.su -d /home/solar/asv -u asv -p Sethanon"

    This example will open FTP connection server lnfm1.sai.msu.su with
    user id asv and password Sethanon and then change to directory
    /home/solar/asv, which is then mirrored (including it's
    subdirectories). Screen output is logged to '.mirror.scrlog' file in
    current directory.

    It is recommended that remote directory should start with "/" to
    ensure that you always mirror right dir. If you mirror anonymous site,
    your login will be "anonymous" and password will be e-mail address.

    Please note that you have to run rxMirror from the directory where
    ".mirror.options" configuration file is located. This is the mirror
    current directory but not necessarily the mirror root (where mirrored
    files are written).

    b) ".mirror.options" file

    If you mirror anonymous site on a regular basis, you may place all
    necessary information into ".mirror.options". Besides that, this file
    may be used to set lots of handy customization parameters. They are
    described in details in ".mirror.options" file as comments, so please
    read it. To use customized values, place ".mirror.options" into mirror
    current directory (current directory when rxmirror is runned).

    c) Error messages

    Sometimes rxMirror exits with a message, and quotes an FTP error code.
    This is the value returned by rxftp call; most common error codes are:

    FTPHOST - cannot resolve hostname; check parameters.

    FTPCONNECT - cannot connect to server; probably network problems.

    FTPLOGIN - incorrect login/password or number of allowed users
    exceeded; check parameters and try later.

    FTPLOCALFILE - cannot create local file. There may be a directory with
    the same name exists, or local file is read-only and cannot be
    removed.

    There may be other error messages; usually they are self-explanatory.
    Unfortunately, broken connection during transfer will hang rxFtp. If
    you see that rxMirror waits too long, terminate it with Ctrl-C.

    NOTE: Termination might sometimes take time. Again, if nothing happens
    (rxMirror say when it's terminating due to Ctrl-C) in long time press
    Ctrl-C again or kill the session abnormally.

BUGS, INCOMPLETENESSES AND UNDESIRED FEATURES

    Most of them come from the different file naming conventions under
    OS/2 and UNIX. I will call the situation when two different UNIX names
    correspond to one OS/2 name "name clash". Examples: two names which
    differ only by case of letters; one of UNIX names has a period at the
    end of the name. However, there are some other things which can be
    implemented but haven't done yet.

    a) When there is a name clash between files in directory, only one
    file will present in the mirror.

    b) Name clash between remote directory names will be handled in a
    rather poor manner.

    c) rxMirror cannot utilize "ls-lR" files, thus it's pretty slow with
    heavy nested directory structures.

    d) rxFtp interface isn't very good constructed. It often hangs on
    transfers, fails to connect etc. I noticed that after rxFtp failed in
    some command-line session, rxFtp in this session will no longer
    function.

    e) obsolete directories (removed from server) do not get removed from
    local disk.

    f) when the remote directory get removed and a file arise with the
    same name, rxMirror will crash (unable to create a local file with the
    same name as existing directory).

    g) some servers have really ugly output and messages which prevent
    rxMirror from operation. Currently, only Unix servers and IBM OS/2
    ftpd are supported.

CONTACTING THE AUTHOR

    Author of the modifications for version 1.3 of rxMirror is
    Teemu Mannermaa <[e-mail]>. Original author of rxMirror is
    Sergey Ayukov <[e-mail]>. Feel free to ask questions; it will
    help me to improve this manual and/or rxMirror.

    NOTE: I would like to thank the original author of rxMirror, Sergey
    Ayukov, because without him version 1.3 would never have been
    possible. THANKS!

    Where to find new versions:

    1) ftp-os2.cdrom.com, hobbes.nmsu.edu, ftp.leo.org

    2) WWW: http://www.pp.clinet.fi/%7Ewicked/prj/rxmirror.html

    3) E-mail to [e-mail] and ask for the latest version.

    4) If you're in Finland (or really want to make an international
    phone call) you can find rxMirror from my Bulletin Board System (BBS):
    Eternal Light, [phone], 24h/day (V.34 and 8N1)

    Sorry for my English. I will gladly accept any corrections to this
    short manual and/or to rxMirror program itself.

-------------------------------------------------------------------------------

Teemu Mannermaa <[e-mail]>

21. February 1999