Return to unixftam.tex CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual

Annotation of 43BSDReno/contrib/isode-beta/doc/manual/unixftam.tex, revision 1.1

1.1     ! root        1: % run this through LaTeX with the appropriate wrapper
        !             2: 
        !             3: \chapter      {UNIX Implementation}\label{unixftam}
        !             4: The File Transfer, Access, and Management (FTAM) standard is the OSI file
        !             5: service.
        !             6: Included in the release is a fairly complete FTAM implementation in the
        !             7: context of the particular file services it offers.
        !             8: It is a minimal implementation in as much as it offers only four core
        !             9: services: transfer of binary files,
        !            10: transfer of text files,
        !            11: directory listings,
        !            12: and file management.
        !            13: The implementation included has been tested on both Berkeley and AT\&T
        !            14: SVR2 and SVR3~\unix/.
        !            15: Both the FTAM initiator and responder programs have \unix/ manual entries.
        !            16: 
        !            17: \section      {Implementation}\label{unixftam:code}
        !            18: If you have access to the source tree for this release,
        !            19: the directory \file{ftam2/} contains the code for the responder and initiator.
        !            20: 
        !            21: \subsection    {The Initiator}
        !            22: There is currently one initiator which uses FTAM: \man ftam(1c).
        !            23: Supported are:
        !            24: the no-recovery FTAM-QoS;
        !            25: any of 
        !            26: the transfer, management, and transfer and management service classes;
        !            27: the kernel, read, write, limited file management, enhanced file management, and
        !            28: grouping functional units;
        !            29: and, the kernel and storage attribute groups.
        !            30: Only three document types are supported as of this writing:
        !            31: unstructured text files (FTAM-1),
        !            32: unstructured binary files (FTAM-3),
        !            33: and filedirectory files (NBS-9).
        !            34: 
        !            35: The \pgm{ftam} program is an interactive FTAM initiator
        !            36: which prompts the user for commands.
        !            37: Generating an interrupt,
        !            38: usually by typing control-C (`\verb"^C"'),
        !            39: at the top-level does nothing,
        !            40: but generating an interrupt twice in a row at the top-level terminates
        !            41: \pgm{ftam};
        !            42: generating an interrupt during additional prompting causes \pgm{ftam} to abort
        !            43: the command;
        !            44: typing generating an interrupt during file transfer causes the transfer to be
        !            45: aborted.
        !            46: 
        !            47: \subsubsection {Commands}
        !            48: Here are the commands to \pgm{ftam}:
        !            49: \begin{describe}
        !            50: \item[append {\tt source destination}]
        !            51: Appends to a file in the filestore.
        !            52: 
        !            53: \item[cd {\tt [dir]}]
        !            54: Changes the working directory on the virtual filestore.
        !            55: This requires the {\bf realstore\/} variable to be set appropriately.
        !            56: 
        !            57: \item[chgrp {\tt group file $\ldots$}]
        !            58: Changes the account attribute of the named files.
        !            59: 
        !            60: \item[close]
        !            61: Terminates the association with the virtual filestore.
        !            62: 
        !            63: \item[dir {\tt [file]}]
        !            64: Prints a long directory listing.
        !            65: 
        !            66: \item[echo {\tt file $\ldots$}]
        !            67: Simply echoes any arguments.
        !            68: Useful for seeing how glob\-bed expressions will evaluate.
        !            69: 
        !            70: \item[fdir {\tt stream [file]}]
        !            71: Prints a long directory listing to a file or program.
        !            72: If \verb"stream" starts with a vertical bar (`\verb"|"')
        !            73: then the named program is invoked;
        !            74: otherwise the named file is written.
        !            75: 
        !            76: \item[fls {\tt stream [file]}]
        !            77: Prints a directory listing to a file or program.
        !            78: If \verb"stream" starts with a vertical bar (`\verb"|"')
        !            79: then the named program is invoked;
        !            80: otherwise the named file is written.
        !            81: 
        !            82: \item[get {\tt source destination}]
        !            83: Retrieves a file.
        !            84: 
        !            85: \item[help {\tt [command]}]
        !            86: Prints help information.
        !            87: For detailed information, try ``\verb*"help ?"''.
        !            88: 
        !            89: \item[lcd {\tt [file]}]
        !            90: Changes the working directory on the local system.
        !            91: 
        !            92: \item[ls {\tt [file]}]
        !            93: Prints a directory listing.
        !            94: 
        !            95: \item[mkdir {\tt dir $\ldots$}]
        !            96: Creates a directory.
        !            97: 
        !            98: \item[mv {\tt source destination}]
        !            99: Renames a file.
        !           100: 
        !           101: \item[open {\tt host user [account]}]
        !           102: Associates with the virtual filestore.
        !           103: 
        !           104: \item[put {\tt source destination}]
        !           105: Stores a file.
        !           106: 
        !           107: \item[pwd]
        !           108: Prints the working directories.
        !           109: 
        !           110: \item[quit]
        !           111: Terminates the association with the virtual filestore and exits.
        !           112: 
        !           113: \item[rm {\tt file $\ldots$}]
        !           114: Deletes a file.
        !           115: 
        !           116: \item[set {\tt variable value}]
        !           117: Displays or changes variables.
        !           118: For detailed information, try ``\verb*"set ?"''.
        !           119: 
        !           120: \item[status]
        !           121: Shows the current status.
        !           122: \end{describe}
        !           123: 
        !           124: \subsubsection {Variables}
        !           125: Here are the variables which effect \pgm{ftam}'s behavior.
        !           126: \begin{describe}
        !           127: \item[bell]
        !           128: Rings the bell after each command terminates.
        !           129: Useful for long file transfers when you want to attend to other matters and
        !           130: be notified when you can type another command.
        !           131: Boolean (values: {\bf on\/} or {\bf off\/}).
        !           132: 
        !           133: \item[debug]
        !           134: This enables voluminous output during file transfers,
        !           135: among other things.  Boolean.
        !           136: 
        !           137: \item[glob]
        !           138: This enables the expansion of shell meta-characters.
        !           139: Operations which perform globbing
        !           140: require the {\bf realstore\/} variable to be set appropriately.
        !           141: Boolean.
        !           142: 
        !           143: \item[hash]
        !           144: This enables the printing of hash marks during file transfers.
        !           145: Values:
        !           146: \verb"off", \verb"on", \verb"total".
        !           147: 
        !           148: \item[override]
        !           149: This sets the creation override mode for files being written to the virtual
        !           150: filestore.
        !           151: If the file being created already exists,
        !           152: then one of four alternatives is taken.
        !           153: Values:
        !           154: \begin{describe}
        !           155: \item[\verb"fail":]
        !           156: the creation operation;
        !           157: \item[\verb"select":]
        !           158: use the existing file with its old contents and attributes;
        !           159: \item[\verb"write":]
        !           160: zero-truncate if it already exists, and use the existing file with its old
        !           161: attributes;
        !           162: and,
        !           163: \item[\verb"delete":]
        !           164: if it already exists, then create a new file with new attributes.
        !           165: \end{describe}
        !           166: This defaults to \verb"write".
        !           167: 
        !           168: \item[qualifier]
        !           169: This sets the ``qualifier'' portion of the srevice which \pgm{ftam} will
        !           170: associate with.
        !           171: It is needed when using the current implementation of the MITRE FTAM/FTP
        !           172: gateway. 
        !           173: This defaults to \verb"filestore".
        !           174: 
        !           175: \item[query]
        !           176: This determines if \pgm{ftam} should ask the user to confirm operations
        !           177: involving globbing that expand to more than one filename.
        !           178: Boolean.
        !           179: This defaults to \verb"on".
        !           180: 
        !           181: \item[realstore]
        !           182: Sets the type of remote realstore associated with the virtual filestore.
        !           183: This is used to help \pgm{ftam} act friendlier to the user!
        !           184: Values: \verb"unix", \verb"unknown".
        !           185: \[\fbox{\begin{tabular}{lp{0.67\textwidth}}
        !           186: \bf NOTE:&     The concept of a {\bf realstore\/} is contrary to the notion of
        !           187:                open systems as it is an $N*M$ (not $N+M\/$) method.
        !           188: \end{tabular}}\]
        !           189: 
        !           190: \item[trace]
        !           191: This enables the tracing of FTAM PDUs.  Boolean.
        !           192: 
        !           193: \item[tracefile]
        !           194: This defines the file where tracing information is appended.
        !           195: 
        !           196: \item[type]
        !           197: This defines the file transfer mode to use.
        !           198: Values: \verb"default", \verb"binary", and \verb"text".
        !           199: 
        !           200: \item[verbose]
        !           201: This enables printing of informative diagnostics during operation.  Boolean.
        !           202: 
        !           203: \item[watch]
        !           204: This enables watch mode,
        !           205: something in between debug mode (too voluminous),
        !           206: and verbose mode (not informative enough).  Boolean.
        !           207: 
        !           208: \item[{\em xyz\/}sapfile]
        !           209: This defines the file where {\em xyz\/}PDU tracing information is appended.
        !           210: Values: any filename, or \verb"-" for the diagnostic output.
        !           211: 
        !           212: \item[{\em xyz\/}saplevel]
        !           213: This enables tracing of the {\em xyz\/} module.\\
        !           214: Values: \verb"none", \verb"exceptions", \verb"notice", \verb"pdus",
        !           215: \verb"trace", and \verb"debug".
        !           216: \end{describe}
        !           217: 
        !           218: \subsubsection {Options}
        !           219: Here are the command line options:
        !           220: \begin{describe}
        !           221: \item[-a {\em acct}]
        !           222: Sets the account to be used on the virtual filestore.
        !           223: 
        !           224: \item[-d]
        !           225: Sets {\bf debug}.
        !           226: 
        !           227: \item[-f]
        !           228: Inhibits reading of the user's \file{\$HOME/.ftamrc} file on startup.
        !           229: 
        !           230: \item[-h]
        !           231: Sets {\bf hash}.
        !           232: 
        !           233: \item[-o  {\em mode}]
        !           234: Sets {\bf override}.
        !           235: 
        !           236: \item[-t]
        !           237: Sets {\bf trace}.
        !           238: 
        !           239: \item[-u  {\em user}]
        !           240: Sets the initiator identity to be used on the virtual filestore.
        !           241: 
        !           242: \item[-v]
        !           243: Sets {\bf verbose\/} (default for interactive use).
        !           244: 
        !           245: \item[-w]
        !           246: Sets {\bf watch}.
        !           247: \end{describe}
        !           248: 
        !           249: \subsection    {The Responder}
        !           250: The \man ftamd(8c) program implements the file service.
        !           251: It implements {\em filestore\/} abstractions directly on the \unix/ filesystem.
        !           252: Supported are:
        !           253: the no-recovery FTAM-QoS;
        !           254: any of
        !           255: the transfer, management, and transfer and management service classes;
        !           256: the kernel, read, write, limited file management, enhanced file management, and
        !           257: grouping functional units;
        !           258: and, the kernel and storage attribute groups.
        !           259: Only three document types are supported as of this writing:
        !           260: unstructured text files (FTAM-1),
        !           261: unstructured binary files (FTAM-3),
        !           262: and filedirectory files (NBS-9).
        !           263: 
        !           264: \subsubsection {Authentication}
        !           265: An FTAM initiator must be listed in the \man passwd(5) file and have a
        !           266: non-empty password.
        !           267: Further, as with the \man ftpd(8c) daemon,
        !           268: the username must not appear in the \file{ftamusers} file in the ISODE
        !           269: \verb"ETCDIR" directory or in the \file{/etc/ftpusers} file.
        !           270: (In fact, many of the mechanisms in \pgm{ftamd} are based on the \pgm{ftpd}
        !           271: program supplied with Berkeley \unix/.)
        !           272: 
        !           273: If the username \verb"ANON" or \verb"ftp" is given,
        !           274: then \pgm{ftamd} treats this as a guest access,
        !           275: similar to the ``anonymous'' facility supported by the \pgm{ftpd} daemon.
        !           276: An entry in the \file{/etc/passwd} file for user
        !           277: \verb"ftp" must be present with a non-zero UID.
        !           278: For guest access,
        !           279: a \man chroot(2) to the guest home directory
        !           280: is executed to restrict access to the system.
        !           281: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
        !           282: \bf NOTE:&     The anonymous account is inherently dangerous and should be
        !           283:                avoided when possible.
        !           284:                It is also inherently useful.
        !           285: \end{tabular}}\]
        !           286: 
        !           287: The Berkeley UNIX version of this program runs with the effective UID of the
        !           288: FTAM initiator,
        !           289: but also with the real UID of the super-user.
        !           290: This is necessary to change the account attribute on files
        !           291: using \man chown(2).
        !           292: The possible security holes have been extensively considered,
        !           293: but may be incomplete.
        !           294: 
        !           295: The AT\&T UNIX version,
        !           296: which lacks kernel support for this technique, acts differently.
        !           297: Immediately upon association establishment,
        !           298: it changes both the real and effective UID to that of the FTAM initiator.
        !           299: To change the account attribute on files,
        !           300: it invokes the \man chgrp(1) program.
        !           301: Similarly, to create or delete directories,
        !           302: it invokes either the \man mkdir(1) program or the \man rmdir(1) program.
        !           303: Finally,
        !           304: it is unable to change the filesize attribute to a non-zero value
        !           305: if this value is smaller than the current filesize.
        !           306: 
        !           307: Finally,
        !           308: on Berkeley \unix/ systems,
        !           309: the \man wtmp(5) file is updated as appropriate.
        !           310: (We couldn't figure out how to update \file{wtmp} under AT\&T \unix/
        !           311: using the description in the SVID!)
        !           312: 
        !           313: \subsubsection {Virtual Filestore}
        !           314: Here are the file attribute mappings.
        !           315: Most attributes are derived by doing a \man stat(2) on the file and then
        !           316: examining the indicated field in the resulting structure.
        !           317: \begin{describe}
        !           318: \item[filename]
        !           319: A single component, relative to the user's \file{\$HOME}.
        !           320: Changing this attribute is equivalent to a \man rename(2).
        !           321: 
        !           322: \item[contents-type]
        !           323: Based on the \verb"st_mode" field:
        !           324: \begin{describe}
        !           325: \item[NBS-9]   for directories;
        !           326: 
        !           327: \item[FTAM-1]  for regular files appearing to be textual;
        !           328: and,
        !           329: 
        !           330: \item[FTAM-3]  for all other regular files.
        !           331: \end{describe}
        !           332: Files that are neither regular nor directories are inaccessible via this
        !           333: implementation of the VFS (i.e., special files).
        !           334: 
        !           335: \item[account]
        !           336: The \verb"st_gid" field according to \man group(5).
        !           337: Changing this attribute is equivalent to a \man chgrp(1).
        !           338: 
        !           339: \item[date-and-time-of-creation]
        !           340: The \verb"st_mtime" field.
        !           341: 
        !           342: \item[date-and-time-of-last-modification]
        !           343: The \verb"st_mtime" field.
        !           344: 
        !           345: \item[date-and-time-of-last-read-access]
        !           346: The \verb"st_atime" field.
        !           347: 
        !           348: \item[date-and-time-of-last-attribute-modification]
        !           349: \ \\   %%% hack
        !           350: The \verb"st_ctime" field.
        !           351: 
        !           352: \item[identity-of-creator]
        !           353: The \verb"st_uid" field according to \man passwd(5).
        !           354: 
        !           355: \item[identity-of-last-modifier]
        !           356: The \verb"st_uid" field according to \man passwd(5)
        !           357: (if the value of the \verb"st_mode" field guarantees uniqueness).
        !           358: 
        !           359: \item[identity-of-last-reader]
        !           360: The \verb"st_uid" field according to \man passwd(5)
        !           361: (if the value of the \verb"st_mode" field guarantees uniqueness).
        !           362: 
        !           363: \item[identity-of-last-attribute-modifier]
        !           364: The \verb"st_uid" field according to \man passwd(5)
        !           365: (if the value of the \verb"st_mode" field guarantees uniqueness).
        !           366: 
        !           367: \item[file-availability]
        !           368: Immediate.
        !           369: 
        !           370: \item[permitted-actions]
        !           371: Depends on the \verb"st_mode" the as interpreted by \man access(2):
        !           372: \verb"R_OK" for permission to read;
        !           373: \verb"W_OK" for permission to write;
        !           374: permission is always granted to read attributes;
        !           375: permission is granted to change attributes if the initiator has uid equal to
        !           376: the \verb"st_uid" field;
        !           377: and,
        !           378: permission to delete is based on writability of parent directory.
        !           379: 
        !           380: \item[filesize]
        !           381: The \verb"st_size" field.
        !           382: 
        !           383: \item[future-filesize]
        !           384: Not available.
        !           385: 
        !           386: \item[access-control]
        !           387: Not available.
        !           388: 
        !           389: \item[encryption-name]
        !           390: Not available.
        !           391: 
        !           392: \item[legal-qualifications]
        !           393: Not available.
        !           394: 
        !           395: \item[private-use]
        !           396: Not available.
        !           397: \end{describe}
        !           398: 
        !           399: The activity attribute mappings are straight-forward.
        !           400: The read action corresponds to reading UNIX files.
        !           401: The insert, replace, extend, and erase actions correspond to writing
        !           402: UNIX files.
        !           403: Concurrency control is supported for reading and writing,
        !           404: but not for reading or changing attributes, or for deleting files.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.