Maxie: About OS/2

The IBM OS/2 Replication Facility has to be one of the best kept secrets in the life of OS/2. It is an existing component of OS/2 Warp 3 Connect and OS/2 Warp 4, and was included in ALL shipped offerings. Documentation for it is VERY hard to find. It is mentioned in the OS/2 Warp Command Reference under the title of REPLICATOR, but that is barely a summary of SOME the configuration parameters, rather than a tutorial of how to go about configuring and using it. This document attempts to explain how to set up and use this very useful service. I also strongly recommend you at least read anything marked as *** WARNING *** , otherwise you could be caught out in a deadly trap.

In brief, Replication is the automated backup of data from one machine to another machine. Be warned however, that Replication is NOT "drive mirroring", it is simply a process that runs at user specified (but in reality machine decided) intervals and checks for files that have altered since it last ran. It then copies any changed file to the other machine if it is different to what is on the server. It will also REMOVE files from the other machine if they no longer exist on the original machine.

*** WARNING *** The terms SERVER and CLIENT as found in the available documentation are not used in exactly the same way as you might expect. In the context of the Replication Facility, the SERVER machine is the machine containing all the data that you wish to "back up" somewhere else. The CLIENT is the machine offering the disk space to store the replicated data from the SERVER. Operationally, the CLIENT effectively pulls the data from the Server.

*** WARNING *** Automating the startup of this facility on a SERVER can be deadly. Consider this, if the SERVER has a hard drive failure and has lost all the files that are normally backed up elsewhere, the Replication Facility will simply REMOVE all the backed up files if the service is immediately restarted on the SERVER! My default configuration is to automaticaly restarted the CLIENT, but I have to MANUALLY restart a SERVER. You have been warned...

To have this facilty available you need one of -

With OS/2 Peer Services running (and REPLICATOR NOT running), a display of SMB status reveals something like this -

[C:\]net start (This command without a 3rd parameter displays the current status without change).
These services are started:
REQUESTER MESSENGER PEER
The command completed successfully.

[C:\]

The Replication facility is simpy an additional function to the above, and when it is running, the SMB Task list will look a bit like this -

Replication involves the copying of data from one machine to another machine on an automated basis. In my case, I had a directory structure on machine A, that I wished to duplicate or "back up", onto machine B. If any of the source directories on A were changed (files added, updated or removed), then ANY changed file (or directory) would be automatically updated to an identical state on B, such that machine B would become a useful backup for machine A.

Replication does NOT provide an immediate backup of files! It is NOT Mirroring of drives, or any such immediate redundancy provider! The Replication function runs at USER configured, but machine controlled, intervals, that could vary from 1-2 minutes, up to 30 minutes or more, after the file was originally closed, so it is not an immediate service! Also note that a file must be CLOSED before it can be replicated. A file that is continuously written by S/W that does not CLOSE the file, then it is not replicated.

You need 2 appropriately equiped OS/2 machines on a Network, with IBM OS/2 Peer Services installed and running. This means you need OS/2 Warp 3 Connect or OS/2 Warp 4 (or later), and appropriate User access set up on each machine. Although designed to work across a pure LAN environment, it can also work across a WAN environment provided you have MPTS configured correctly with NETBIOS over TCP/IP in addition to NETBIOS, however further details on this are far outside the scope of this document.

IMPORTANT - Test that simple file and directory sharing is working correctly between the 2 machines before proceeding. While the Replication facility does not actually use any Drive or Directory sharing in the conventional sense of the term, you need to confirm that the machines are able to talk to each other using the same basic form of connectivity.

The SERVER machine (I will call this machine bruce) is the machine that contains the original data, IE it is the SOURCE of the data.

The CLIENT machine (harry) is the machine that will hold the replicated data, IE it is the TARGET machine.

The SERVER (bruce) can only specify Replication from ONE DRIVE letter. Make sure that all the data you wish to Replicate is on this drive, however you can make a virtual drive letter using TVFS (Toronto Virtual File System).

The CLIENT machine (harry) can only specify ONE target drive letter. All data you wish to replicate on one machine MUST fit into the space available on the target drive letter.

NOTE 1: A Client machine can actually be set up to work with multiple Servers, and it can also be restricted to only servicing
those Servers that you wish it to service. I will only describe a single Server/Client relationship to keep things simple.

NOTE 2: ALL configuration work for the Replication Service is performed by manually editing configuration files that control the Peer Services facility, so keep in mind that you COULD break other existing components of OS/2 if you get things wrong. I always keep backups of original versions of these files so I can go back one step if things break. There is no GUI facility for this work.

The reason is simple, if you do this part FIRST, then setting up the SERVER becomes fairly logical.
Where x: is the OS/2 boot drive -
1. Look in the file x:\IBMLAN\IBMLAN.INI and find the [replicator] section. You will need to set up at least 4 lines looking something like this -

a. replicate = IMPORT
b. importpath = D:\Bruce-E
c. importlist = bruce
d. tryuser = yes

These lines say -

a. This machine is to operate as an Importer, or CLIENT machine.
b. Build all replicated data under this DIRECTORY. Note that I use a directory name the same as the Source machine name followed by the Source drive letter. This makes it easier to work out whats happening, but does not work if you have 2 servers for this client..
c. Import data only from a machine with a network name of 'bruce' (multiple Server names can be used).
d. Use the access provided by the currently logged in user on machine 'harry'.
NB - My machines have a permanently logged in user who is automatically logged in by the StartUp.Cmd file.

2. Create a 'Bruce-E' directory under D:\.

a. replicate = EXPORT
b. exportpath = E:\
c. exportlist = harry
d. tryuser = yes

These lines say -

a. This machine is to operate as an Exporter, or SERVER machine.
b. Search the named DRIVE for REPL.INI files. Note that this is a DRIVE, NOT a PATH! See details below...
c. Export data only to a machine named 'harry'.
d. Use the access provided by the currently logged in user on machine 'harry'. See Importer section for details on this user.

3. This is the critical step, think this out carefully. Create a file named REPL.INI in the TOP level directory that you wish to start replicating. This file contains 2 lines -

a. extent = tree | file
b. integrity = file | tree

These lines say -

a. If set to 'extent = TREE', then copy EVERYTHING below this point down this directory branch. If set to 'extent = FILE', it will copy ONLY files in THIS directory, and NOT any sub-directories.
b. This one is very subtle. If set to 'integrity = FILE', then if a file is updated, it will be marked for Replication AS SOON AS THE FILE IS CLOSED. Replication will only work on CLOSED files. If set to 'integrity = TREE', then Replication of updated files for this ENTIRE directory will only occur when NONE of the files in this directory are currently open. If just ONE file remains OPEN, then NOTHING in this directory will be copied! This is useful if a directory has a lot of work in progress, but once it is all finished, then and only then will the directory be replicated. By placing REPL.INI files in different directories on the drive, you can set up multiple directory structures to be exported using different criteria for each directory structure.

Everything is now ready, but nothing happens... Thats because you actually need to start the replication service on both machines by entering the command net start replicator on the command line. This should be followed by a statement that the Replicator service has been started, and some time after this, the files on the Server will be replicated onto the Client.

On the Client machine, a STATUS file is created in the Root Directory specified in the IBMLAN.INI file indicating the status of the Replication facility. That file could be -

OK.RP$                        If everything is up to date as at last run.
NO_SYNC.RP$        An update is currently in progress.
NO_MASTR.RP$    A Server for this client has not been found on the network.

Once you are happy with the Replication configuration and wish to have it permanently turned on, you can do this 2 ways. You can permanently add the 'net start replicator' line to STARTUP.CMD, or you can look in the x:\IBMLAN.IBMLAN.INI file and find -
For the SERVER, in the [peer] section find the SRVSERVICES = line and change that to read -

SRVSERVICES = REPLICATOR

For the CLIENT, in the [requestor] section find the WRKSERVICES = ???? line and ADD to the end of ???? -

WRKSERVICES = ????,REPLICATOR

You can also adjust several other Replication settings (eg timeout periods, etc), however that is beyond the scope of this "getting started" document. A search of the online OS/2 help files for 'REPLICATOR' will return the required details.

About the OS/2 Replication Facility.