Amiga Developer CD 1.2

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Developer CD 1.2 / amidev_cd_12.iso / contrib / iam / networking / envoy-2.0 / obs / project_overview < prev next >

Wrap

Text File | 1994-12-22 | 25.1 KB | 600 lines

Envoy DO NOT REDISTRIBUTE Developer's Overview 8/21/92 Amiga Networking Group Developer's Overview This document is a collection of select pages from the Commodore internal product description for Envoy. It is provided as a background text for development to Envoy, as well as an indication of the directions Commodore intends to take with Envoy. This text is included only as a courtesy to developers. Any and all details within are subject to change. Summary Features The Envoy software package will enable all Amiga computers (including the A500 and A600) to transparently share filesystems and printers with each other. It will support third-party networking applications. Easy configuration for simple networks, and operation in complex network environments will both be part of the initial package. Security features will unobtrusively discourage unauthorized use of network resources. The Amiga GUI will be used extensively to make the package easy to configure and to use. Hardware Requirements Envoy makes use of the SANA-II Network Device Driver Specification, allowing the package to be used with any networking hardware that has a compliant device driver. Envoy can be used on any 512k Amiga running 2.0 or better. Availability & Distribution Information on the future availability of Envoy, including plans for distribution is not available at this time. The diagram below gives an overview of the Envoy project architecture. The sections which follow provide some additional details. +----------------+ +-----------------+ +--------------+ | | | | | | | Applications | | Printer Svcs. | | Network FS | | | | | | | +----------------+ +-----------------+ +--------------+ | | | | | | | | | +------+ | | | | | | | | | +---------------------------------------+ | | | | | | | | | Services Manager & services.library | | | | | | | | | +---------------------------------------+ | | | | | | | | | | | | | | | | | | | +-----------------+ | | | | | | | | | User Accounts | | | | | | | | | +-----------------+ | | | | | | | | | | | | | +--------------------------------------------------------------+ | | | nipc.library | | | +--------------------------------------------------------------+ | | | +--------------------+ | | | SANA-II Drivers | | | +--------------------+ nipc.library Architecture The nipc.library is the communications workhorse and largest piece of Envoy. It provides a Transaction-based reliable communications path between multiple Amigas, above any compliant SANA II device. To understand exactly where the nipc.library fits into the broad APPN picture, one needs to have a general understanding of the different layers that define the nipc.library and it's interactions with others. As a reference, please note figure A. As figure A shows, the nipc.library sits directly +--------------+ +------------+ above the device drivers | Envoy | | Stand | for each piece of | Applications | | Alone Apps.| networking hardware in +--------------+ +------------+ use, and directly below NIPC API-----> \ / either applications or +------------------------------+ another library. Some | nipc.library | applications may only +------------------------------+ require the ability to S-II Std Interface--> | transmit and receive data +------------------------------+ reliably - and not require | SANA-II Device Drivers | some of the more complex +------------------------------+ features that higher levels | of Envoy provide. Thus, +------------------------------+ these programs | Networking Hardware | communicate directly +------------------------------+ with the nipc.library. Figure A. Figure B. provides a more detailed diagram of exactly what levels make up the nipc.library, as well as the interfaces between levels. The lowest level is the specific networking hardware. This could be anything from an A2065 ethernet board to a low-speed serial link. The only requirement on the hardware is that a SANA II device driver must exist for it. The hardware communicates with the next layer up (the SANA II device drivers) through an arbitrary hardware specific interface. This is dependant on the exact hardware used, and may vary from implementation to implementation (for example, two differently designed ethernet boards will communicate with their device drivers differently - as they +----------------------------+ may have been designed around | 5 Applications | different chipsets). +----------------------------+ / | | +----------------------------+ The second level consists of one or | | 4 NIPC "Presentation" | more SANA II device drivers. Please | +----------------------------+ reference the document "SANA-II Network N | | Device Specification", 5/5/92 for I \ +----------------------------+ more specific information. The SANA II P < | 3 RDP & UDP | device drivers provide a standard C / +----------------------------+ interface between wildly different | | networking software and networking | +----------------------------+ hardware. | | 2 IP, ICMP, ARP | | +----------------------------+ \ | The third leve marks the beginning +----------------------------+ of a set of two levels of the proposed | 1 SANA-II Driver | design which are intentionally insulated +----------------------------+ from the rest of the design. (These can | be seen in figure B, as levels 3 and 4, +----------------------------+ as well as the interfaces between 3, 4, and | 0 Networking Hardware | 5.) The goal in doing this is to prevent the +----------------------------+ nipc.library from being necessarily tied to a specific networking protocol. Figure B. For instance, it's entirely possible to create an nipc.library which is based on Novell NetWare instead of the protocol stack shown in figure A. Level two in figure B is similar to the ISO 'Network' layer in most functions. It's function is to packetize and route data from one site to another. This level is made up of implementations of the internet protocol (IP), the internet control message protocol (ICMP), and the address resolution protocol (ARP). Above the Internet Protocol is the Reliable Datagram Protocol - which makes up level three. RDP provides reliability and sequencing, among other features, to the datagram service. Level four contains the NIPC Presentation layer. Specifically, this level provides the services specified in the nipc.library Autodocs, based on the services provided to it by lower levels (RDP and level four, in this instance). Communication to the next higher level is provided through the interface defined in the previously mentioned standard. While a layered model is an excellent method by which one may understand networking protocols, it's a decidedly poor way to implement a protocol stack. In light of this, levels two, three, and four are not entirely distinct. Communication between these levels is done with a buffering scheme that's designed to minimize data copying. The library itself contains everything from the SANA II interface up through the NIPC API (this is shown bracketed on figure B). nipc.library Overview Definition The nipc.library provides reliable, transaction-oriented networking abilities to an Amiga, with a familiar API. Concepts To fully understand the library, a knowledge of a few essential NIPC concepts is required: Entity: A communications endpoint. A single Entity can be part of a number of different communications paths - meaning that one Entity may be communicating with many other Entities at the same time. While it's useful for the purposes of descriptions to illustrate a pair of Entities communicating, it's important to understand that this isn't a limitation. An Entity is identified by both it's name, and the name of the machine on which it exists. Communications Path: An imaginary line drawn between two Entities defining a line of data transfer. Transaction: The process used to transfer data in NIPC. A Transaction is made up of two distinct phases - the time in which a Transaction is a request and the time in which it is a response. A Transaction always takes place on a communications path between two Entities. See Figure A. as a reference. Request +-------------+ -------------------> +-------------+ | | | | | Entity A | | Entity B | | | | | +-------------+ <------------------- +-------------+ (source) Response (dest) Figure A. The flow of a Transaction between Entities. Request: The first phase of a Transaction, where a source Entity (Entity A, above) sends a request packet to a destination Entity (Entity B, above). A Request can be identified by a single-byte command and a variable length data section. Response: The second phase of a Transaction, where a destination Entity processes a request packet, provides an Error code, and (if required) provides a variable length data section. Operation The nipc.library provides operations for communicating between Entities, regardless of whether the communications path involves transferring data from one machine to another, or merely transferring data between two Entities on a single machine. The operations as seen by the application program are identical, though the library obviously processes the data in different ways. Figure B. shows the modelling of how a Transaction appears when operated through a networked device. Network \ \ +-------------+ ------->/ /--------> +-------------+ | | \ \ | | | Entity A | / / | Entity B | | | \ \ | | +-------------+ <-------/ /<-------- +-------------+ \ \ Figure B. A Transaction's conceptual flow over a network. When refer encing the diagram above, keep in mind that this is only a model -- the transfer of data only appears to work in this way. Knowledge of this model is all that is necessary for using the library. While this model is straightfoward and simple enough to expect developers to understand thoroughly, it's too simplistic to use for the actual library implementation - which presents a more complex situation. However, the model serves an important role by insulating the developer from the complexities of networking. In our implementation, for each communications path in use there exists something called a Link Entity. It is between these Link Entities that networked communications actually occur. Each Entity may have several Link Entities -- one for the local side of each communications path. This scheme is shown in Figure C. This scheme lends itself quite well to NIPC. Each Link Entity might be considered a local extension of the Entity on the other side of the communications path. For instance, the leftmost Link (shorthand for "Link Entity") in Figure C. might be considered the local extension of Entity B. Thus, for library function calls, when a program attempts to reference a remote Entity (one on another machine), it actually references the Link that symbolizes the remote Entity. The networking portion of nipc.library fills in the rest. Network +----+\ \+----+ +-------------+ ->| |/ /| |--> +-------------+ | | | |\ \| | | | | Entity A | |LINK|/ /|LINK| | Entity B | | | | |\ \| | | | +-------------+ <-| |/ /| |<-- +-------------+ +----+\ \+----+ Figure C. A Transaction's actual flow over a network. For a local transaction (where the source and destination Entities are on the same machine), there's very little overhead; the Transaction structure is simply passed to the destination Entity. Envoy Services Introduction One of the problems when writing client-server applications is determining exactly how the client is supposed to initiate a connection with a server. Another problem is deciding how and when the server's process is to be started. It would seem desirable to have a system that provided a standard way to handle both problems. This is where the Envoy Services system comes into play. The Envoy Services system is designed to standardize the way in which nipc client applications initiate connections with nipc servers. This is done by providing a services.library that deals with locating the requested service on the remote machine and making the connection to the server. The other problem, that of how and when to start servers, is handled on the "server side" of the connection via the Envoy Services Manager. The Envoy Services Manager receives requests for services from the client machine and then passes this information on to an Envoy Service which then takes any actions that are required to activate the server. The Envoy Services themselves are implemented as Amiga shared libraries. By using this model, Services may be dynamically loaded from disk, and may also be flushed if they are inactive. Services also make use of special library LVO's that are used to start services, query the service, etc. Connection to a Service The first step in connecting to a service is to open nipc.library and the services.library. You must use nipc.library to create the Entity that you will be using for your side of the communications path. Then, you call the services.library function FindService() which will make an attempt to connect to the service you are requesting to use. Example: ... if(svc_entity = FindService("Cruncher","Printer Service",my_entity, FSVC_UserName,"Joe", FSVC_Password,"Joe's Password", FSVC_Error, &error_code, TAG_DONE) { ... FindService() requires that you specify the name of the host that the service you want to use is located on (in the above case, "Cruncher") , the name of the service ("Printer Service"), and the Entity that you will use for your side of the connection. You may also optionally specify a user's name, a user's password or a pointer to a ULONG that will be filled in with an error code (if any) if the connection failed. For more information, please see the services.library/FindServce() autodoc. Disconnection from a Service To disconnect from a Service you simply call the services.library function LoseService() with a pointer to the Entity returned by FindService(). Example: ... LoseService(svc_entity); ... Writing a new Service Before you write a service, you should have a good grasp on writing Amiga shared libraries. An example shared library can be found in the Amiga Libraries RKM. Each Service must implement at least two LVO's that are used by the Envoy Services Manager and it's configuration tool. These two LVO's are StartService() and GetServiceAttrs(). StartService() is called by Services Manager when there is a new request for a service from a client. The second call, GetServiceAttrs() is used by the Services Manager configuration tool to determine the name of your service (not to be confused with your Service's filename). When the Services Manager calls your StartService() function, you must take whatever steps are required to start providing your service to the requesting client. You will be passed information such as the name of the user and his password. You will also be passed a pointer to string that you are to fill in with the name of the Entity that the client should connect to. Depending on how you are designing your service, you may or may not need to start a new task for each client that connects to you. You will need at least one task, however. There currently is no way to have a task-less service. When your StartService() function returns, the Services Manager will reply to the client's request for service with the name of the Entity it should connect to or will return an error code if you could not start the service for some reason. The best way to see how all of this works is to examine the source code for the print spooler service and it's client. These two pieces of code detail some of the finer points with writing a service that haven't been covered in this section. Installing a Service All you have to do to make the Services Manager start accepting requests for your service is to run the Services Manage configuration tool and add your service. NIPC Network Realms Nipc.library is designed to work well in both a single physical network and in internets. In a situation where there is only one physical networks with a small number of machines, NIPC will work without setting up a Realm. However, when there are many machines on a single network, or when there are many different physical networks, it is desirable to logically divide the entire network into Realms. An Realm is a logical grouping of hosts that may exists on a single network or separate physical networks. Because of this, Realms are independent of network topology. A Realm name can always be optionally provided before a host name, by preceding the hostname with the Realm name and and a colon character. For instance, "siberia:scratchy" references the Amiga named 'scratchy' in the Realm "siberia". If a reference is made to a host without a Realm name, the Realm that the referencer is in is defaulted to. If you reference "scratchy", and are in the Realm "siberia" yourself, NIPC will assume you mean "siberia:scratchy". However, if you're in a different Realm -- say "Software Engineering", -- and wish to reference machine "scratchy", you must specify "siberia:scratchy" -- as providing only "scratchy" will resolve to "Software Engineering:scratchy", which at best will fail, and at worst will resolve a different machine (another one named "scratchy") than you intended. Each Realm must have one host that is acting as a "Realm Server". This host is responsible for propagating all Realm queries to all of the physical networks within a realm. Because each host in a realm is configured to know what Realm it is in and its Realm Server's network address is, a Realm Server does not need to be physically connected to each network in the realm. Network queries are initiated by calling the nipc.library function NIPCInquiryA(). This function allows applications to send many different types of queries. These range from just determining the names of all machines in a realm, to doing complex queries that can find all machines with exported filesystems, 68040's, and eight megabytes of ram. For more information, please read the autodoc for NIPCInquiryA(). If a query sent by a host is for that hosts local network, the query packet is broadcasted to every machine on that network. Each machine on that network will respond to the packet if necessary. If a query is for a specific Realm, the query is sent to the querying host's Realm Server. The Realm Server then consults its Realm database to see if it knows anything about the Realm specified in the query. If the Server determines that the Realm is one of those that it controls, it sends broadcasts to all of the physical networks that are in the specified realm. Otherwise, if the Realm specified in the query is controlled by another Realm Server, the query packet is forwarded to that machine for further processing. An NIPC Realm is configured by starting the NIPC configuration editor. On the Realms panel, there are two listview gadgets. The one on the left is for setting up realms that the Realm Server is in control of. The listview on the right is for telling the Realm Server about other Realm Servers. Each physical network in a Realm must have a separate entry in the lefthand listview gadget. Envoy Network Filesystems The initial Envoy network filesystem is broken into two halves -- a client, to access files on remote machines; and a server, to allow remote machines to access local files. The client and server portions of the filesystem may be run separately or together, allowing for true peer-to-peer filesystem access. Both the client and server include security -- a server will not allow a remote client to create a remote mount unless the username and password pair passed from the client is authenticated. Client The client portion of the filesystem is implemented as a standard AmigaDOS filesystem, and will be designed to translate DOS packets into Transactions. Each remote filesystem to be accessed will be a volume on the client filesystem. Each mount specifies the machine on which to access files, as well as the directory path to mount on that machine. Each mounted volume will create a Workbench icon -- allowing simple Amiga point-and-click access to remote files and directories. The user will not see any difference between a network-mounted filesystem and, say, a hard disk (other than access speed, depending on the CPU and network hardware being used). Each remote mount can automatically be created on system bootup - with no action required of the user other than initial configuration. Server The server portion of the filesystem will translate Transactions initiated by a remote client into actions taken on a local filesystem. When a client attempts to mount a filesystem, a client-provided username and password pair must be authenticated to allow access. When any individual file or directory is accessed, that user's user-id and any group-ids will be checked against bits in the multi-user filesystem to determine what access, if any, will be allowed to the specific file or directory. The fileserver will be able to successfully recover from most reboots by automatically re-establishing any mounts, locks, open files, etc.