@database ParNFS.guide @Master parnfs.texi @Width 72 This is the AmigaGuideŽ file ParNFS.guide, produced by Makeinfo-1.55 from the input file parnfs.texi. @Node Main "ParNFS.guide" ParNFS ****** This file documents ParNFS 1.2. Copyright (C) 1993-1995 by Olaf 'Rhialto' Seibert. Permission is granted to copy the whole package, in accordance with the @{"GNU General Public License" Link "COPYING/MAIN"}, and some additional restrictions. @{" Overview " Link "Overview"} What is in the package? @{" Requirements " Link "Requirements"} What else do you need? @{" Installation " Link "Installation"} How do you install it? @{" Usage " Link "Usage"} How do you use it? @{" Limitations " Link "Limitations"} What does it not do? @{" Implementation " Link "Implementation"} Interesting things to know. @{" Glossary " Link "Glossary"} What all the words mean. @{" License " Link "License"} What you may do with it. @{" Release Notes " Link "Release Notes"} What's the difference with previous versions. @{" Index " Link "Index"} Where to find what in this manual. @{" Simple Installation " Link "Simple Installation"} "Stand-alone" operation @{" Complex Installation " Link "Complex Installation"} Operation together with other applications using parnet.device @EndNode @Node "Overview" "ParNFS.guide/Overview" @Next "Requirements" @Prev "Main" @Toc "Main" Overview ******** ParNFS is intended to be a replacement for the well-known Parnet file system by the Software Distillery. I wrote it because it had a number of important deficiencies: @{b}*@{ub} It came without source, which is a sin bi itself, but also meant I couldn't fix the other problems. @{b}*@{ub} It would not allow you to get a directory listing with most versions of the "list" command that I used; only the AmigaDOS 1.3 version worked. @{b}*@{ub} It did not cooperate with other applications using Parnet. @{b}*@{ub} It gave annoying requesters when you attempted to use 2.0 features. @EndNode @Node "Requirements" "ParNFS.guide/Requirements" @Next "Installation" @Prev "Overview" @Toc "Main" Requirements ************ Besides what is included in this archive, you need @{b}*@{ub} Two (or possibly more) Amigas. @{b}*@{ub} A parnet cable. How to make one is described in @{"Cable.doc" Link "Cable.doc/MAIN"}. @EndNode @Node "Installation" "ParNFS.guide/Installation" @Next "Usage" @Prev "Requirements" @Toc "Main" Installation ************ There are two different kinds of installation: the easy one and the not-so-easy one. @{" Simple Installation " Link "Simple Installation"} "Stand-alone" operation @{" Complex Installation " Link "Complex Installation"} Operation together with other applications using parnet.device @EndNode @Node "Simple Installation" "ParNFS.guide/Simple Installation" @Next "Complex Installation" @Toc "Installation" Simple Installation =================== You can do the simple installation if you don't have any other application yet that uses the parnet.device. If one of the following things is not appropriate for your case, you need to do the @{"Complex Installation" Link "Complex Installation"}. @{b}*@{ub} You only have two Amigas involved as client and server (sometimes called "host") for each other. @{b}*@{ub} The parnet addresses are set to 1 for the primary server and 2 for the primary client. @{b}*@{ub} Parnet port number 604 and 605 are not yet in use. In the simple case, we assume there will be a symmetric situation: both Amigas will be both client and server, so you can access files on Amiga 1 from Amiga 2 and files on Amiga 2 on Amiga 1. However, both client-server relations are distinct from the software's point of view, and therefore I will call one the primary client-server relation, and the other the secondary one. At this point, you should grab your trusty @{b}Installer@{ub} program, and run @{b}Install-ParNFS@{ub}. Or you can install ParNFS by hand, and do the following. First, you need to copy a few files to the appropriate place. Do this on both Amigas. @{b}*@{ub} Copy @{b}NetworkFileSystem@{ub} to @{b}L:@{ub}. @{b}*@{ub} Copy @{b}NetworkFileServer@{ub} to @{b}C:@{ub}. @{b}*@{ub} Append @{b}@{"Mountlist" Link "Mountlist/MAIN"}@{ub} to @{b}@{"DEVS:Mountlist" Link "DEVS:Mountlist/MAIN"}@{ub}, or copy it to @{b}@{"DEVS:DosDrivers/NET" Link "DEVS:DosDrivers/NET/MAIN"}@{ub} and delete the lines containing "NET:" and "#". The primary client and server ----------------------------- Now you can bring up the primary server and client. All that is needed is @{b}*@{ub} @{b}Run NetworkFileServer@{ub} on the server (Amiga 1). @{b}*@{ub} @{b}Mount NET:@{ub} on the client (Amiga 2). Poof! You're done. The secondary client and server ------------------------------- This is only slightly more difficult. What you do is @{b}*@{ub} Edit the Mountlist on the secondary client (Amiga 1), so that the line with BlocksPerTrack reads BlocksPerTrack = 1. @{b}*@{ub} @{b}Run NetworkFileServer -s@{ub} on the server (Amiga 2). The @{b}-s@{ub} means "secondary". @{b}*@{ub} @{b}Mount NET:@{ub} on the client. Poof! You're done again. If you want to use the workbench over your network, drop some copies of the @{b}Node.rinfo@{ub} icon on the disks you wish to see icons for. @EndNode @Node "Complex Installation" "ParNFS.guide/Complex Installation" @Prev "Simple Installation" @Toc "Installation" Complex Installation ==================== First you have to read through the instructions for the @{"Simple Installation" Link "Simple Installation"}. Now you have to realise that any references to @{b}NetworkFileServer@{ub} only apply to an Amiga in its capacity as server (or host), and @{b}NetworkFileHandler@{ub} and @{b}Mountlist@{ub} to a client Amiga. In all applications of parnet and ParNFS, you must follow these two simple rules: @{b}*@{ub} Every Amiga must have its own parnet address. @{b}*@{ub} Every client communicates with its server using a port number unique to that server. So what you only need to do is select addresses for all Amigas (but you probably did that before), and select a unique port number for each server. Then you install each client and each server analogous to the simple procedure, with the following modifications: @{b}*@{ub} For a client, you can indicate the selected numbers in the Mountlist as follows: BlocksPerTrack = 2 Interleave = 0xppppsscc, where pppp: the port number the server is using (in hex) ss : the parnet address of the server (in hex, 0x01 .. 0xFE) cc : the parnet address of this client (in hex, 0x01 .. 0xFE) So, to do the simple installation in the complex way, you'd have BlocksPerTrack = 2 Interleave = 0x025C0102 @{b}*@{ub} For a server, you use the command @{b}Run NetworkFileServer -a -c -p @{ub} with, of course, the selected addresses and port number. You will notice the redundant specification of the Amiga's address in case it acts both as a client and a server. This is because parnet does not have a way to inquire the current address, but all programs must know it. Advanced Installation ===================== It should be possible to have more than one client using the same server. In this case they still use all the same port number. This should be safe up to about 4 clients per server (1). You can also run multiple servers on the same Amiga; they need of course their own port numbers or chaos will ensue. You can of course also run several client @{b}NET:@{ub}s on a single Amiga: just use a different name for each. But they can't talk to the same server, because that gives a port number clash on the client machine. ---------- Footnotes ---------- (1) To increase this, recompile the server code with a higher value of the #define PENDREADS. @EndNode @Node "Usage" "ParNFS.guide/Usage" @Next "Limitations" @Prev "Installation" @Toc "Main" Usage ***** Once you've installed ParNFS, you can use it almost 100% the same as the original Software Distillery Parnet system. This means that you can access, for instance, @{b}DH0:something@{ub} on the server (or host) as @{b}NET:DH0/something@{ub}. This also works for assigns and character devices (such as @{b}SER:@{ub} and @{b}CON:@{ub}). The @{b}NET:@{ub} device also creates a volume node, named @{b}Network:@{ub}. If any requesters appear, they will always refer to volume @{b}Network:@{ub}; unfortunately they are not more specific than that. Especially "Please insert volume Network:" is a bit silly. ParNFS remembers remote device, volume and assign names that you have successfully used, and if you get a directory listing of @{b}NET:@{ub} you get all those names listed as subdirectories. There are also @{b}.info@{ub} files suppled for the Workbench. The corresponding icons are actually in the files @{b}NET:dev/Node.rinfo@{ub}, so unless these exist, Workbench will not actually display an icon. Please note that, just like Parnet, these @{b}.info@{ub} files always appear, even if the corresponding @{b}Node.rinfo@{ub} file does not exist. There are a few non-obvious things. You cannot do any device-tied operations, because there is only one device with some subdirectories. (See @{"Limitations" Link "Limitations"} for which packets those are). You can, however, relabel a disk by renaming its directory. @{b}Rename NET:df0 NET:test@{ub} A side-effect is a "Please insert..." requester, when the Rename command is trying to find out if you a directory @{b}NET:test@{ub} already exists and it should rename @{b}NET:df0@{ub} to @{b}NET:test/df0@{ub} instead. You can safely abort and restart the server. However, access to files and locks obtained before is no longer possible and will be detected by the client which will give "Volume not mounted" errors. You can also stop and restart the client (by sending an ACTION_DIE packet), but it will only quit voluntarily if there are no open files or locks. In case of involuntary restart (i.e., a reboot of the client Amiga), files and locks remain open at the server and will be lost until it also reboots. An automatic recovery from this situation is currently not implemented (but certainly possible). @EndNode @Node "Limitations" "ParNFS.guide/Limitations" @Next "Implementation" @Prev "Usage" @Toc "Main" Limitations *********** @{b}*@{ub} It is desirable that everyone should upgrade from 1.3 to 2.0 (or better) as fast as possible. Therefore, the @{b}NetworkFileServer@{ub} will gladly call 2.0 functions, if any client requests so. If the server runs on 1.3 in this case, @{i}this means the server will crash!!!@{ui} I will @{i}not@{ui} be fixing this; the correct way to remedy this is to upgrade. (1) @{b}*@{ub} Having said this, ParNFS supports all 2.0 packets, with the exception of the two file notification packets, ACTION_EXAMINE_ALL, device-related operations AddBuffers(), ACTION_FLUSH, Inhibit(), ACTION_WRITE_PROTECT (the Lock command) and Format. So record locks are supported over the net, and so is ExAll(), because AmigaDOS will substitute it with ExNext() if needed. @{b}*@{ub} File and directory names are not completely parsed by ParNFS. A directory name such as @{b}/DH1@{ub} if you're in @{b}NET:DH0@{ub} will not work, even though a @{b}ParentDir()@{ub} from @{b}NET:DH0@{ub} will give you @{b}NET:@{ub}. @{b}*@{ub} There is a potential problem with @{b}Examine()@{ub} and @{b}ExNext()@{ub}. A careful reading of ExNext() and ACTION_EXAMINE_NEXT learns that for each directory scan using a series of ExNext() calls, the same FileInfoBlock should be used, and that you shouldn't copy FileInfoBlocks around. It is also implied (but not said so with so many words) that each scan should use its own FileInfoBlock (with its own unique address). Unfortunately, these restrictions are impossible for the server to adhere to. One could say that it would be possible to allocate a fresh FileInfoBlock for each call to Examine(), but when can you release it? There is no way to know if it is going to be used for ExNext() at some later time, or if the caller will call ExNext() again once it has done so a few times. Had there existed ExamineFirst() and ExamineEnd() calls, this would be possible. Fortunately, this seems to work for now, but it may break in the future. I don't know what contortions I would have to go through to make it work again in such a case... @{b}*@{ub} A similar situation exists with ExAll() and ExAllEnd(), only worse. ExAllEnd() only exists on 3.0 and above, so you can't count on it being used. And the callback hook for ExAll() would be a nightmare to implement. ---------- Footnotes ---------- (1) Be glad I didn't use any 2.0 only functions at other times; this would have been a lot easier for me! @EndNode @Node "Implementation" "ParNFS.guide/Implementation" @Next "Glossary" @Prev "Limitations" @Toc "Main" Implementation ************** The client communicates with the server with datagrams, assuming reliable delivery. For parnet, this is a reasonable assumption. In general, each DOS packet sent to the client results in a datagram sent to the server. In general the contents of the datagram are very similar to that of the DOS packet, except that file names and other data that does not fit in a longword must be copied entirely. A datagram is received in response, and its result values are put to the DOS packet. For received file handles and locks, a DOS compliant structure is built and the value from the server is hidden in there. (When a lock or file handle must be sent to the server, these values are retrieved and sent instead.) There are a few exceptions to this, however, which make the implementation a bit more complicated. For the ACTION_LOCK_RECORD, no reply is sent; because of the timeout that is required it must be handled asynchronously. A reply can be sent at any time, possibly interrupting the processing of some other operation. At any time, a RESET packet can be received; this means that the other side has restarted. A RESET-REPLY is sent in reply. The client uses these packets to detect that existing files and locks are now invalid. The server currently ignores this information as it doesn't track resources. @EndNode @Node "Glossary" "ParNFS.guide/Glossary" @Next "License" @Prev "Implementation" @Toc "Main" Glossary ******** Client A client program is a program that uses the services of a server. A client Amiga is the Amiga that the client program runs on. There may be multiple client programs per Amiga. Usually the Local Amiga. Server A server program is a program that provides services to one or more client programs. A server Amiga is the Amiga that the server program runs on. There may be multiple server programs per Amiga. Usually the Remote Amiga. Host Synonym for Server Amiga. Local Amiga The Amiga in front of you. Usually the client Amiga. Remote Amiga The Amiga not in front of you, but connected through the parnet cable. Usually the server Amiga. @EndNode @Node "License" "ParNFS.guide/License" @Next "Release Notes" @Prev "Glossary" @Toc "Main" License ******* ParNFS is Copyright (C) 1993-1995 by Olaf Seibert. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the @{"GNU General Public License" Link "COPYING/MAIN"}, as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. The Licence (see @{"the file COPYING" Link "COPYING/MAIN"}) does not specify limitations on copying fees; the specification shall be that ParNFS may not be distributed in a commercial package of any kind, including floppy disks sold by pd/freeware/shareware resellers charging more than $6 or DM 10 per disk, without my written permission. For CD-ROMs the maximum copying fee shall be the price of a Fred Fish CD-ROM. @EndNode @Node "Release Notes" "ParNFS.guide/Release Notes" @Next "Index" @Prev "License" @Toc "Main" Release Notes ************* 1.2 fixes a few small bugs and adapts to DICEs ever stricter type checking. @EndNode @Node "Index" "ParNFS.guide/Index" @Prev "Release Notes" @Toc "Main" Index ***** @Index "Index" @{" Advanced Installation " Link "Complex Installation"} Complex Installation @{" Client " Link "Glossary"} Glossary @{" Complex Installation " Link "Complex Installation"} Complex Installation @{" Copying " Link "License"} License @{" Distribution " Link "License"} License @{" General Public License " Link "License"} License @{" Glossary " Link "Glossary"} Glossary @{" GNU General Public License " Link "License"} License @{" Host " Link "Glossary"} Glossary @{" Implementation " Link "Implementation"} Implementation @{" Index " Link "Index"} Index @{" Installation " Link "Installation"} Installation @{" License " Link "License"} License @{" Limitations " Link "Limitations"} Limitations @{" Local Amiga " Link "Glossary"} Glossary @{" Modification " Link "License"} License @{" Overview " Link "Overview"} Overview @{" Release Notes " Link "Release Notes"} Release Notes @{" Remote Amiga " Link "Glossary"} Glossary @{" Requirements " Link "Requirements"} Requirements @{" Server " Link "Glossary"} Glossary @{" Simple Installation " Link "Simple Installation"} Simple Installation @{" Usage " Link "Usage"} Usage @EndNode