rfa.tr

ftam等标准协议服务器和客户端的源代码。

.\"
.\" RFA - Remote File Access
.\"
.\" rfa.tr : RFA User Manual (run through "roff -ms")
.\"
.\" Contributed by Oliver Wenzel, GMD Berlin, 1990
.\"
.\"
.\" $Header: /xtel/isode/isode/others/rfa/RCS/rfa.tr,v 9.0 1992/06/16 12:47:25 isode Rel $
.\"
.\" $Log: rfa.tr,v $
.\" Revision 9.0  1992/06/16  12:47:25  isode
.\" Release 8.0
.\"
.\"
.AM
.nr LL 7i
.pl 11i
.nr li 1 1
.nr PD 50
.TL
RFA - Remote File Access

.br
A tool for managing access to files that are distributed at multiple sites
.AU
Oliver Wenzel
GMD - Fokus
Berlin - Germany

.br
Version 1.0

.sp 4
.NH
Introduction
.XS
Introduction
.XE
.LP
This software tool called \fIRemote File
Access\fP (RFA) has been designed to allow access to a set
of files in a UNIX(TM) filesystem that are shared between multiple
sites. It has been created within the VERDI 3 project as a result of our
own requirements for a distributed document and file management system.
Basis for this requirements is the VERDI 3 project which members are
located at two different sites. Both sites of the project share a common
set of documents and files which need to be accessed and modified during
the everyday-project-work. For some time we used the FTAM software to
exchange files between the two sites, but after the number of shared
files and transfer operations grew, very often questions like
.ds is \(bu
.RS
.IP \*(is 3
at which site the up-to-date (master) version of the file is
located ?
.IP \*(is 3
is the local version up-to-date ?
.IP \*(is 3
is anyone already editing this file ?
.IP \*(is 3
are there any newly created files ?
.RE
.LP
appeared. Using a distributed filesystem like NFS was discussed as
an alternative solution, but this did not seemed to be practicable
because of the very slow communication links between the sites
(9600Bps). Therefore, we tried to build a simple tool to handle theses
questions. So the RFA tool was born and because the project is working
with ISO protocols, we built the tool on top of the ISODE software
package using the remote operation compiler
\fBrosy(1)\fP. Currently the tools only
supports to share files between two sites (because this was our primary
goal), but it should be possible to extend it to support multiple
sites.
.NH
The Model
.XS
The Model
.XE

.NH 2
The Data Model
.XS
The Data Model
.XE
.LP
The Data Model is based on the hierarchical structure of the
UNIX(TM) filesystem. The RFA tools allows to share a subtree of the
hierarchical filesystem structure between (currently) two sites. The
structure of the shared subtree must be identical at both sites. The
local root of the shared subtree may be different at both sites. Subject
of the operation of the RFA tool are the files and directories within
the shared subtree. 
.NH 3
File Version-Time
.XS
File Version-Time
.XE
.LP
A file within a shared subtree exists at the different sites as
different (local) versions of the file. The version-time (state of
modification) of a file version at a site is determined by the
\fBmodification time\fP provided by the
UNIX(TM) system call \fBstat(2)\fP. To
determine which version of file is up-to-date, the youngest version-time
is chosen. This requires that the sites participating in the file
sharing use synchronized clocks. This is necessary because the
modification time is set automatically by the UNIX system using the
local operating system clock. The RFA tool provides an operation to
synchronize the clocks where one of the sites is declared to be the
\fBtime-master\fP which provides the time
to the \fBtime-slave\fP.
.NH 3
RFA File Status
.XS
RFA File Status
.XE
.LP
Each local version of a file that exists within the shared subtree
at a site has a RFA-specific status which is one of:
.IP "MASTER" 15
the file is the up-to-date version of the file and
modifications to the local version of the file are allowed.
.IP "SLAVE" 15
the file is the read-only version of the file and may be
up-to-date but it need not. For each local file with SLAVE status there
must be a MASTER version at the remote site. File version with SLAVE
status will have file write permissions cleared.
.IP "UNREGISTERED" 15
the file not shared and has only local significance. It may
be modified locally.
.LP
.LP
This file status allows to determine which site has the up-to-date
version of a file and is allowed to do modifications to the file. The
site holding a SLAVE version of the file has to request the mastership
before it is allowed to do any modifications. Further, it has to be
assured that the local version of the file at the new MASTER site is
up-to-date. Otherwise the file has to be transferred first. A local
version of a file may change its status during its lifetime (e.g. from
UNREGISTERED to MASTER) as a result of several RFA operations described
later.
.NH 3
File Locking
.XS
File Locking
.XE
.LP
To avoid that a file is modified by multiple users at the MASTER
site or that the mastership is transferred to the remote site while the
local version is under modify-access by a local user, a local version of
a file can be (soft)-locked. Locking of files is only applicable to file
versions with status MASTER or UNREGISTERED.
.LP
Setting the lock flag of a directory has the effect, that the
\fB.rfaexec\fP file is not executed during
a RFA \fBsync\fP or
\fBrsync\fP command. This can be used to
enable the execution of the \fB.rfaexec\fP
file for a period of time (e.g. while doing incomplete modifications to
the source-code when \fB.rfaexec\fP
contains commands for re-compilation).
.NH 3
Transferlevel
.XS
Transferlevel
.XE
.LP
One mode of operation of the RFA tool is to synchronize sets of
local version of files with the remote site. To determine if a file that
is mastered remote should be transferred during this synchronization, a
transferlevel can be associated with each file:
.IP "REQUEST" 15
The file is not transferred automatically during
synchronization. If a new MASTER file is detected at the remote site,
only a local dummy (empty file) is created to indicate the existence of
the file.
.IP "AUTOMATIC" 15
The file is transferred automatically during synchronization
if the local version is not up-to-date. If a new MASTER file is detected
at the remote site, it is transferred.
.NH 2
The Functional Model
.XS
The Functional Model
.XE
.LP
The RFA tools is built using the
\fBClient-Server\fP model of the ISODE
remote operations environment. There is a RFA server (called
\fBros.rfa)\fP at each site which is
started dynamically by the ISODE
\fBtsapd\fP. Most of the RFA commands are
interpreted by the RFA client (called
\fBrfa\fP) which issues a remote operation
to the remote RFA server. The RFA client does not perform a 1-to-1
mapping of its commands onto the remote operations. It uses none, one or
more remote operations to execute a RFA command. The association
establishment is done when the first remote operation is invoked. The
RFA client can operate in an interactive mode or a command mode.
.LP
One of the basic principles of RFA is that modifications to any
files are only performed locally by the RFA client. The remote RFA
server never modifies any file, so no remote file modifications are
possible. The ensure a certain autonomy of the two sites concerning
modifications of their local files.
.NH
The RFA Client
.XS
The RFA Client
.XE
.LP
The RFA client (\fBrfa\fP) provides an
interactive mode and a command mode. The rfa command has the following
syntax:

.DS I 3
rfa [ -u username -p password ] [ -h hostname] [ -q ] 
     [ -c rfa-command ]
.DE
.LP
The name of the host (as defined in the
\fBisoentities\fP database) where the
remote site is located can be specified using the
\fB-h\fP option. Because the RFA client
binds to the remote RFA server with a username that must be valid at the
remote site, the \fB-u\fP and
\fB-p\fP options can be used to specify the
username and the password for the remote site. The
\fB-q\fP option directs
\fBrfa\fP to run in quit-mode, where only
severe errors are reported and no user interaction is performed. Using
the \fB-c\fP option, a command can be
passed to rfa in command mode. This can be any command described
below.
.LP
If the rfa is called without the
\fB-c\fP option, is runs in interactive
mode. The \fBrfa\fP provides the following
commands. A command can be abbreviated with its unambiguous
prefix.
.NH 2
pwd
.XS
pwd
.XE
.LP
During interactive mode, \fBrfa\fP has
a current directory. This directory is relative to the root of the
shared subtree. The \fBpwd\fP command shows
the name of the current working directory relative to the root of the
shared subtree. Initially this is the current working directory of the
UNIX \fBsh(1)\fP where
\fBrfa\fP has been called if it is within
the shared subtree. 
.NH 2
cd
.XS
cd
.XE
.LP
The \fBcd\fP command changes the
current directory of \fBrfa\fP in
interactive mode to the directory given as the first argument. No check
is made if this directory exists. It is not possible to change the
working directory above the root of the shared subtree.
.NH 2
list
.XS
list
.XE
.LP
The \fBlist\fP command provides a
listing of the files within the directories given as the command
arguments. If no argument is given, the current working directory is
listed. The output of the \fBlist\fP
command is similar to the output of the UNIX \fBls
-lg\fP command, e.g.

.DS I 3
-rw-rw-r-- M-A ow       verdi         754 Jul 12 13:59  .sunview
drwxr-xr-x --- ow       verdi         512 Jul 12 14:01  bin
.DE
.LP
The three character field after the file permissions is used to
indicated the different rfa-specific states of the file. The first
character indicates the status of the file, with M 
for master version, S  for slave Version and
-  for unregistered version. The second character is
the lock indicator with an L  indicating that the
file is currently locked and an -  for unlocked. The
third character indicates the transfer mode of the files with
A  for automatic transfer and - 
for transfer on request.
.NH 2
rlist
.XS
rlist
.XE
.LP
The \fBrlist\fP command is similar to
the \fBlist\fP command with the difference
that the files in the directory at the remote site are listed.
.NH 2
lock
.XS
lock
.XE
.LP
The \fBlock\fP command is used to get
a locked local version of the file(s) that are provided as argument(s)
to the command. Only regular files within the shared subtree are valid.
It is not possible to lock directories, links, etc. . If the name of the
file to be locked is a symbolic link, the file referenced by the link is
locked if it is located within the shared subtree.
.LP
The \fBlock\fP command should be used
whenever a file within the shared subtree is modified to ensure that the
local version of the file is a) the master version and b) not currently
under modify-access by another local user.
.LP
If the local version of the files has a SLAVE status, the lock
command will try to get the mastership for the file. Therefore, it first
verifies that the local version is up-to-date, otherwise it transfers
the up-to-date version from the current master, similar to the
\fBgetfile\fP command. After an up-to-date
local version of the requested file exists, a
\fBRequestMaster\fP operation is issued to
the remote site to transfer the mastership. If the file is not locked at
the remote site, the mastership is granted to the local site which then
is the new master. The local lock is set the by setting the
L (ocked) flag in the local files state.
.LP
If the local version of the requested file already is the MASTER
version or is an UNREGISTERED file, it is checked if the file is already
locked by another local user, where the requested lock is rejected.
Otherwise the local lock is set the by setting the
L (ocked) flag in the local files state.
.LP
Because the lock command will be applied in the most cases to a
local version of the file that is already master, it is not necessary to
execute the whole \fBrfa\fP program to do
the local lock. Because the \fBrfa\fP
program includes the whole code needed for the execution of the remote
operations (ISODE stack, etc.), there may be a significant time delay
while loading this huge program. To optimize this, a stand-alone program
called \fBllock\fP is provided which is
able to perform the locking if the local version is the master version.
If \fBllock\fP could perform the local
lock, it exits with exit-code 0. If the file is already locked
locally or an error condition occurred it exits with exit-code 1. If the
local version of the file is not MASTER, it returns 2 which indicates
that the \fBrfa\fP command is needed to
perform the locking.
.NH 2
unlock
.XS
unlock
.XE
.LP
The \fBunlock\fP command is used to
release a lock for a local MASTER version of the file(s) provided as
command argument(s).  If the name of the file to be unlocked is a
symbolic link, the file referenced by the link is unlocked if it is
located within the shared subtree. There is are no checks made if the
file has been locked by the user that performs the unlock operation.
.LP
Similar to the \fBllock\fP command
there exists an \fBlunlock\fP command which
is capable to perform the release of the (always) local locks to avoid
the expensive use of the \fBrfa\fP
command.
.NH 2
master
.XS
master
.XE
.LP
The \fBmaster\fP command can be used
to request that the local version of the file(s) provided as argument(s)
will become the MASTER version.  If the name of the file is a symbolic
link, the file referenced by the link is target of the operation if it
is located within the shared subtree.
.LP
If the local version of the file is in UNREGISTERED status, its
status is set to MASTER if there is no version of the file with MASTER
status at the remote site. This is the way how locally created files
will be introduced into the set of shared files where the creating site
becomes the initial master.
.LP
If the local version of the file is in SLAVE status, then the
mastership for the file is requested from the remote site similar to the
\fBlock\fP command. The write access
permissions of the new local MASTER version are set.
.NH 2
slave
.XS
slave
.XE
.LP
The \fBslave\fP command can be used to
request that the local version of the file(s) provided as argument(s)
will become a SLAVE version. If the name of the file is a symbolic link,
the file referenced by the link is target of the operation if it is
located within the shared subtree.
.LP
If the local version of the file is in UNREGISTERED or MASTER
status, its status is set to SLAVE if there is version of the file with
MASTER status at the remote site. The write access permissions of the
new local SLAVE version are cleared.
.NH 2
unregister
.XS
unregister
.XE
.LP
The \fBunregister\fP command can be
used to request that the local version of the file(s) provided as
argument(s) will become an UNREGISTERED version. If the local version of
the file is locked, this results in an error. If the name of the file is
a symbolic link, the file referenced by the link is target of the
operation if it is located within the shared subtree.
.NH 2
setrequest
.XS
setrequest
.XE
.LP