1 10/10/88  enter_imft_request, eir
  2 
  3 Syntax as a command:  eir transfer_specs {-control_args}
  4 
  5 
  6 Function: submits requests to transfer files or subtrees to or from
  7 remote Multics systems using the Inter-Multics File Transfer (IMFT)
  8 facility.
  9 
 10 
 11 Arguments (transfer_specs):
 12    The transfer_specs specify the files or subtree to be transferred
 13    and has the following format:
 14 path {-target_pathname equal_path},
 15 path {-tpn equal_path}
 16    path specifies the relative pathname of files and/or subtrees to be
 17    transferred.  The star convention is accepted.  This is also
 18    referred to as the source pathname.  If supplied, the equal_path is
 19    the relative pathname of where the files and subtrees will be
 20    placed on the target system.  The equal convention is accepted.
 21    The target pathname is converted to an absolute pathname relative
 22    to the working directory on the local system.  If not given, the
 23    files and subtrees are given the same pathname on the target
 24    system.
 25 
 26 
 27 Control arguments (object type selection):
 28 -file, -f
 29    specifies that transfer requests should be issued only for files
 30    which match the transfer_specs.  If a transfer_spec does not use
 31    the star convention and there is no matching file, an error message
 32    is issued.  (Default -- issue requests for matching files and
 33    subtrees).
 34 -subtree, -subt
 35    specifies that transfer requests should be issued only for subtrees
 36    which match the transfer_specs.  If a transfer_spec does not use
 37    the star convention and there is no matching subtree, an error
 38    message is issued.  This is incompatible with the -extend and
 39    -update control arguments.  The default is to issue requests for
 40    matching subtrees.
 41 
 42 
 43 Control arguments (file handling):
 44 -extend
 45    appends the contents of the source pathname to the end of the
 46    contents of the target pathname.  An error occurs if the source is
 47    a nonfile.  An error occurs if the target does not already exist.
 48    It is incompatible with the -subtree option.
 49 -replace, -rpl, -rp
 50    replaces the entire target file specified by the target pathname
 51    (deletes and creates a new object), rather than modifying its
 52    contents as is done by -extend and -update.  (Default)
 53 
 54 
 55 -update, -ud
 56    replaces the contents of the file specified by the target pathname
 57    with those of the source pathname without deleting the target file
 58    or changing any of its attributes.  An error occurs if the source
 59    is a nonfile.  An error occurs if the target pathname does not
 60    already exist.  It is incompatible with the -subtree option.
 61 
 62 
 63 Control arguments (directory handling):
 64 -merge_directories, -mdr
 65    specifies that if there is a directory on the target system with
 66    the same name as one of the names on the root directory of the
 67    subtree being transferred, the contents of the source subtree will
 68    be merged with the target subtree.  If the target entry is not a
 69    directory, processing will continue as though -replace_directories
 70    had been specified.  Any directories within the subtree are treated
 71    in a similar fashion with respect to name duplications.  See the
 72    Notes for a description of the treatment of files within the
 73    subtree.  (Default)
 74 
 75 
 76 -replace_directories, -rpdr
 77    specifies that if there is an entry on the target system with the
 78    same name as one of the names on the root directory of the subtree
 79    being transferred, that name will be removed from the target entry;
 80    if the target entry has only one name, it will be deleted.
 81 
 82 
 83 Control arguments (chase):
 84 -chase
 85    specifies that transfer requests should be issued for the targets of
 86    any links which match the transfer_specs.  (Default -- chase links
 87    for any transfer_specs that do not use the star convention; do not
 88    chase links for any transfer_specs that use the star convention)
 89 -no_chase
 90    specifies that transfer requests are not issued for the targets of
 91    any links which match the transfer_specs.
 92 
 93 
 94 Control arguments (object selection):
 95 -date_time_after DT, -dtaf DT
 96    skips selected files and subtrees if their
 97    date_time_contents_modified value is older than the time selected
 98    by DT.  This option is not applied to contents of subtrees.  The DT
 99    string must be acceptable to the convert_date_to_binary_
100    subroutine.  This option facilitates selecting only modified
101    information to reduce IMFT traffic.  The -dtaf option only applies
102    to push transfers, ie, transfering objects from the local system to
103    the remote.
104 -skipped, -skpd
105    turns on the display of the objects that are skipped when the
106    -date_time_after option is used.
107 
108 
109 -no_skipped, -nskpd
110    turns off the display of the items that are skipped when the
111    date_time_after option is used.  (Default)
112 
113 
114 Control arguments (delete):
115 -delete, -dl
116    deletes the source pathname immediately after it is successfully
117    transferred.
118 -no_delete, -ndl
119    does not delete objects.  (Default)
120 
121 
122 Control arguments (direction):
123 -destination STR, -ds STR
124    identifies the remote system to which the files and subtrees are to
125    be transferred.  STR must be one of the names listed by the
126    print_imft_sites command.
127 -source STR, -sc STR
128    identifies the remote system from which the files and subtrees are
129    to be transferred. STR must be one of the names listed by the
130    print_imft_sites command. If neither -destination nor -source is
131    specified, the default is -destination imft.
132 -queue N, -q N
133    specifies that the requests be entered in priority queue N where N
134    is an integer between 1 and 4 inclusive.  (Default -- depends on the
135    destination or source specified)
136 
137 
138 Control arguments (notification):
139 -notify, -nt
140    sends notification of successful initiation and completion of each
141    transfer request.  The notifications are sent on the the local and
142    remote systems.  (Default)
143 -no_notify, -nnt
144    suppresses notifications of successful transfer on both systems.
145    Any errors detected during transmission will still cause mail to be
146    sent regardless of the use of -no_notify.
147 
148 
149 Control arguments (display):
150 -brief, -bf
151    suppresses the messages providing the request IDs of the requests
152    entered by this command.
153 -long, -lg
154    prints the messages providing the request IDs of the requests
155    entered by this command.  (Default)
156 -long_id, -lgid
157    prints the long form of the request ID in any messages.
158 -short_id, -shid
159    prints the short form of the request ID.  (Default)
160 
161 
162 -absolute_pathname, -absp
163    prints the absolute pathname of the file or subtree along with the
164    request ID for each request entered by this command.
165 -entryname, -etnm
166    prints only the entry name of the file or subtree along with the
167    request ID for each request entered by this command.  (Default)
168 
169 
170 Control arguments (misc):
171 -foreign_user Person.Project, -fu Person.Project
172    specifies the identity of the user at the remote system on whose
173    behalf the transfer requests are being entered.  Notifications on
174    the remote system are sent to this user.  See "Access required"
175    below for further information.  (Default -- the same as the user on
176    the local system)
177 
178 
179 Access required:
180 All access checking is done using explicit ACL entries.  An explicit
181 ACL entry has an access name of the form "Person.Project.*".  ACL
182 entries which have access names of "Person.*.*", "*.Project.*", or
183 "*.*.*" will not work.  In order to check the access of any object,
184 the daemon must have at least (ie, it does not have to be explicit)
185 "s" access to the containing directory.
186 
187 In order to transfer a file or subtree from the source system to the
188 target system, the following conditions must be met:
189 
190 
191 For files, the user on the source system must have explicit "r" access
192 to the file; for subtrees, the user must have explicit "s" access to
193 the root of the subtree and each directory contained therein and
194 explicit "r" access to each file in the subtree.  The user must also
195 have explicit "s" access to the containing directory of the object
196 specified by the source pathname.
197 
198 The daemon process on the source system which transfers the file or
199 subtree must also have the same type of access as described above for
200 the source system's user.  Additionally, the daemon must also have at
201 least "s" access to the directory above the containing directory of
202 the specified object in order to verify that the user and daemon have
203 the proper access.  The identity of the daemon can be determined using
204 the print_imft_sites command.
205 
206 
207 The user on the target system must have explicit "sma" access to the
208 directory into which the file or subtree is to be placed.  The source
209 system user and the target system user are the same unless the
210 -foreign_user control argument is specified.  The user also needs
211 "sma" access to the parent directory of the source and "rw" access to
212 the source object if the -delete control argument is specified.
213 
214 The daemon process on the target system which receives the file or
215 subtree must also have explicit "sma" access to the directory into
216 which the file or subtree will be placed.  If the source object is to
217 be deleted, the daemon process must also have "sma" to the containing
218 directory of the object and "rw" to the source object.  In addition,
219 this daemon must have at least "s" access to the directory containing
220 that directory in order to validate that the target user has the
221 proper access.
222 
223 
224 If the -extend or -update options are used, the target file must exist
225 and the user (for pull transfers) or foreign_user (for push transfers)
226 must have an explicit "rw" ACL entry on the target file.  The daemon
227 on the target system must also have an explicit "rw" ACL entry on the
228 target file.
229 
230 
231 Access control segment:
232 The ability of a user on the local system (LPerson.LProj) to transfer
233 files to or from the foreign system is controlled by the access
234 granted to the local user by the user on the foreign system
235 (FPerson.FProj) to the segment:
236 
237    >udd>FProj>FPerson>LSite.imft.acs
238 
239 on the foreign system where LSite is the name of the local system.  In
240 order to request that files be transferred from the foreign system,
241 LPerson.LProj.* must have explicit read access to the above-named
242 segment.  In order to transfer files to the foreign system,
243 LPerson.LProj.* must have explicit write access to the segment.
244 (Note: when setting write access on an ACS, it is advisable to set its
245 maximum length to 0, to prevent it from acquiring contents.)
246 
247 
248 In the case of remote requests (i.e., use of the -source control
249 argument), the foreign and local users must have all the same access as
250 if the request had been issued at the source system, in addition to
251 read access to the ACS as indicated above.
252 
253 
254 An example of access requirements (local to remote file tranfer):
255 This type of transfer request is also known as a push request.  Assume
256 that the user Smith.Multics on MIT wishes to send the file
257 
258    >udd>m>Smith>test>new.pl1
259 
260 to the directory
261 
262    >udd>Guest>SmithP>imft>mit
263 
264 on System-M where his user ID is SmithP.Guest.  Further, assume that
265 the daemon on both systems is IMFT.Daemon, and that the names of the
266 source and target systems (given by print_imft_sites command) are MIT
267 and System-M respectively.
268 
269 
270 On MIT (the source system), Smith.Multics must issue the following
271 set_acl commands to insure that he and the daemon have proper access;
272 
273    set_acl >udd>m>Smith>test>new.pl1 r Smith.Multics r IMFT.Daemon
274    set_acl >udd>m>Smith>test s IMFT.Daemon
275 
276 Note that the daemon must have at least "s" access to >udd>m>Smith in
277 order to check that the above explicit ACLs are present.  Only in this
278 case will any ACL term which grants appropriate access to the daemon
279 for these checks is sufficient, ie, IMFT.*.* or *.Daemon.* or *.*.*
280 will suffice.
281 
282 
283 On System-M, SmithP.Guest issues the following set_acl commands to
284 insure proper access to receive the file;
285 
286    set_acl >udd>Guest>SmithP>imft>mit sma SmithP.Guest sma IMFT.Daemon
287    set_acl >udd>Guest>SmithP>imft s IMFT.*
288    set_acl >udd>Guest>SmithP>MIT.imft.acs w Smith.Multics
289 
290 Once proper access is established, Smith.Multics issues the command
291 line;
292 
293    eir >udd>m>Smith>test>new.pl1 -tpn >udd>Guest>SmithP>imft>mit>===
294       -fu SmithP.Guest -ds System-M
295 
296 
297 An example of access requirements (remote to local file tranfer):
298 
299 For a related example, let's assume that the same user wants to
300 transfer the same file as a remote request (i.e., he wants to issue
301 the request while logged in at System-M as SmithP.Guest.) To do this,
302 he needs exactly the same access as described above, with one
303 exception.  Instead of giving himself "w" access to the ACS segment,
304 he must establish "r" access with the following command line at MIT:
305 
306    set_acl >udd>Multics>Smith>System-M.imft.acs r SmithP.Guest
307 
308 SmithP.Guest may now request the transfer by issuing the command line
309 on System-M;
310 
311    eir >udd>Multics>Smith>test>new.pl1 -tpn
312       >udd>Guest>SmithP>imft>mit>=== -fu Smith.Multics -source MIT
313 
314 
315 Notes on AIM:
316 Files and subtrees may be transferred only if their access class is
317 less than or equal to the process authorization of the user who
318 submitted the request and the common access class ceiling.  Type:
319 
320      help common_access_ceiling.gi
321 
322 for a definition of the common access class ceiling.  The sites may
323 chose to lower the common access class ceiling; check with your system
324 administrators to find out the actual common access class ceiling.
325 
326 Files and subtrees are created on the target system with the same
327 access class as they had on the source system.
328 
329 
330 When transferring a subtree, the daemon will not transfer any directory
331 in the subtree if its access class is greater than that of the
332 directory where it will be placed on the target system.  Therefore, it
333 is necessary to issue separate requests for each such upgraded
334 directory specifying a target pathname whose containing directory has
335 the same access class as the directory being transferred.
336 
337 For example, if the access class of the directory on the source system
338 is "classified, Division" and the command line:
339 
340      eir my_directory -tpn >udd>m>gmp>receiver>===
341 
342 is issued, the access class of the directory >udd>m>gmp>receiver on the
343 target system must also be "classified, Division".
344 
345 
346 Notes:
347 If conflicting control arguments (e.g., -notify and -no_notify, or
348 -destination and -source, or -extend, -replace and -update, or
349 -replace_directories and -merge_directories) are given on the command
350 line, the rightmost control argument takes effect.
351 
352 If -extend or -update control arguments are not used, and there is an
353 entry on the target system with the same name as one of the names on
354 the file being transferred, that name will be removed from the target
355 entry; if the target entry has only one name, it will be deleted.  No
356 distinction is made between files specified in a transfer_spec and
357 files contained in a subtree with respect to the handling of duplicate
358 names on the target system.
359 
360 
361 Examples of usage:
362 eir **.pl1 -tpn <x>===.new -ds MIT
363    transfers all files and subtrees in the working directory whose name
364    ends with the pl1 suffix.  If the local working directory is
365    >udd>m>gmp>w, a file named "foo.pl1" will appear on the remote
366    system as >udd>m>gmp>x>foo.pl1.new
367 
368 
369 eir my_subtree -ds System-M -mdr
370    transfers the subtree named "my_subtree" in the working directory to
371    the same point in the hierarchy on the remote system.  Assume (1)
372    that there already is a foreign directory named my_subtree, (2) that
373    the local my_subtree contains two files named file1 and file2 and a
374    directory named subdir1, and (3) that the foreign my_subtree also
375    contains two files named file1 and file3.  After the transfer is
376    completed, the foreign my_subtree will contain three files -- file1
377    and file2 from the local system and file3 from the foreign system --
378    and one directory -- subdir1 from the local system along with the
379    contents of the local subdir1.
380 
381 
382       eir >udd>sm>Kelley.profile -tpn >udd>m>PKelley.= -source MIT
383          -fu Kelley.SysMaint
384 
385    transfers the segment >udd>sm>Kelley.profile from MIT on behalf of
386    the MIT user Kelley.SysMaint, and places it in
387    >udd>m>PKelley.profile on the local system.