home *** CD-ROM | disk | FTP | other *** search
/ Chip: Windows 95 / WIN95_CD.ISO / sharewar / internet / netmagic / guide.ht_ / guide.ht
Encoding:
Text File  |  1995-06-26  |  53.9 KB  |  1,333 lines

  1. <html><head><title>NetMagic Server User's Guide</title></head>
  2. <body>
  3. <h1>NetMagic Server User's Guide</h1>
  4.  
  5. <h2>Contents</h2>
  6. <ul>
  7. <li><A HREF="#Beta">Beta Notes</A>
  8. <li><A HREF="#Installation">Installation</A>
  9. <li><A HREF="#Internet">Internet Basics</A>
  10. <li><A HREF="#Objects">NetMagic Server Objects</A>
  11. <li><A HREF="#Global">Global Settings and Configuration</A>
  12. <li><A HREF="#Client">Client Usage</A>
  13. <li><A HREF="#ServCmds">NetMagic Service Command-line options</A>
  14. <li><A HREF="#ServInfo">NetMagic Service Management</A>
  15. <li><A HREF="#Uninstall">Uninstalling NetMagic</A>
  16. </ul>
  17.  
  18. <hr>
  19.  
  20. <h2><A NAME="Beta">Beta Notes</A></h2>
  21. <h3>General Beta Information</h3>
  22.  
  23. The NetMagic Server beta software can be downloaded via 
  24. <A HREF="ftp://www.aristosoft.com/NetMagic/NetMagic.zip">FTP at
  25. ftp://www.aristosoft.com/NetMagic/NetMagic.zip</A> or
  26. <A HREF="http://www.aristosoft.com/ftp/NetMagic/NetMagic.zip">HTTP at
  27. http://www.aristosoft.com/ftp/NetMagic/NetMagic.zip</A>.  After
  28. downloading this file, use PKUNZIP to decompress it into an empty directory (not
  29. the one you'll eventually want to install it into.)
  30. Setup can then be run from this directory.
  31. <P>
  32. The following platforms are supported:
  33. <ul>
  34. <li>Windows 95 (Final and later betas)
  35. <li>Windows NT 3.5 (i386) (Server or Workstation)
  36. </ul>
  37. Memory requirements depend on usage; for Windows 95, 8 MB should be fine;
  38. for Windows NT, 16-20 MB is more realistic.  Of course, more memory helps performance
  39. with many clients, as does a nice SMP system, a 5 ms hard disk, 128 Mb RAM...
  40. <P>
  41. Although we have used NetMagic on our server for several weeks without any major
  42. problems, the software is in <i>beta</i> form.  There are probably some
  43. bugs, some features may not be fully implemented, and other strange things
  44. may happen as a result of this.  You have been warned!  Please don't use this on
  45. a mission-critical system which you haven't backed up for the past 6 months.
  46. <P>
  47. For this version of the beta, due to the fact it is being incorporated on a CD
  48. with an uncertain ship date, the timeout has been extended to Oct 31, 1995.
  49. After this date, the server will not function.
  50. This is to encourage people to either purchace the commercial version or
  51. at least download and deploy the latest evaluation version.
  52. <P>
  53. For the period of the beta, support will be available primarily via 
  54. <a HREF="mailto:aaron@aristosoft.com">aaron@aristosoft.com</a>.
  55. Let us know about any bugs or desired features or enhancements.
  56.  
  57. <h3>Known Beta Problems</h3>
  58. <ul>
  59. <li>The HTTP Proxy currently ignores the Accept: header from the client.  This will
  60.     be fixed, but shouldn't cause a problem for most browsers (which Accept: */*
  61.     anyway).
  62. <li>The HTTP Proxy does not work with HTTP/0.9 servers.
  63. <li>Under Windows 95, we've observed that trying to browse the server from the
  64.     server results in a strange TCP error.  Using the server's IP address works.
  65.     Looks like a DNS bug in Windows 95...
  66. <li>Global and server-specific accounts may interact with each other in unexpected
  67.     ways if the same user or group names are used.
  68. <li>The on-line help isn't implemented--it's still evolving, like this document.
  69. <li>A few browsers cannot handle the large amounts of client state passed around
  70. by the ChatRooms.  We've had problems with Mosaic 2.0 a7, Mosaic 2.0 b4, and
  71. problems have been reported with the Prodigy browser and Air Mosaic.  The bug in Mosaic 2.0
  72. b4 has been confirmed and is being addressed.  As it is the most widely-used browser
  73. currently, Netscape is our "reference" browser platform.  We'd appreciate any browser
  74. incompatibility reports, but also let us know if the problem can be reproduced with
  75. Netscape 1.0N/1.1N.
  76. </ul>
  77.  
  78. <hr>
  79.  
  80. <h2><A NAME="Installation">Installation</A></h2>
  81. To install the software, change to the directory/diskette with the Setup files
  82. and run <code>setup</code>.  If you received the files in a ZIPped archive,
  83. you should unzip them into a separate directory first (not the desired
  84. destination directory.
  85. <p>
  86. Setup allows you to install the Personal server or the Enterprise server.
  87. In this beta they have identical features; the difference is in how they
  88. run on your server.  The Personal server is a user application that supports
  89. Windows 95 and Windows NT; the Enterprise server runs as a Windows NT
  90. service and supports Windows NT only.  The Enterprise server is also
  91. built to use a bit more memory for internal buffering than the Personal
  92. version.
  93. <P>
  94. <i>Note:</i> The feature set of the Personal server will most likely change
  95. for the final version to reflect its lower price.  Marketing hasn't decided
  96. which features, if any, will not be present in the Personal version.
  97.  
  98. <hr>
  99.  
  100. <h2><A NAME="Internet">Internet Basics</A></h2>
  101. This is by no means a comprehensive treatise on providing Internet services;
  102. rather, it's intended to point you in the right direction.
  103. <p>
  104. To provide web services to the Internet community, your server must be
  105. accessible from the Internet.  Tomes have been written on this subject,
  106. which varies widely from site to site, state to state, and country to
  107. country.  We can be of some assistance, but you're better off discussing these
  108. issues with your internet service provider or network administrator.
  109. <ul>
  110. <li>The server must have a valid, unique, and static global IP address.  Typically,
  111. this means the server is in a valid registered domain and has been assigned a
  112. static address.  If the server obtains an address dynamically (such as from a
  113. SLIP/PPP provider or via DHCP), then you should ensure that the <i>same</i>
  114. address is always provided.
  115. <li>The server's machine name and domain name should be registered with DNS.
  116. Again, typically this is handled by the service provider or the local network
  117. administrator.  It <i>is</i> possible to provide services with only a static IP
  118. address; clients will have to specify IP numbers instead of hostnames in their
  119. URLs.
  120. </ul>
  121. Many firewall installations provide "local" IP addresses to machines (such as
  122. 192.168.x.x).  Such IP numbers cannot be seen from outside the firewall (thus why
  123. they're used).  You will need a global IP address to provide service to the
  124. entire Internet.
  125. <P>
  126. Many SLIP/PPP/ISDN providers can provide you with a static IP address and even a host
  127. name.  There are really only a few limitations when using a server connected this
  128. way to the Internet: performance (okay, ISDN isn't too bad) and accessibility.  For
  129. your services to be available, your machine will need to be connected full-time,
  130. which could be expensive!  There is talk about dial-back ISDN, but for now, the
  131. best solution is really a dedicated link (i.e. 57K frame relay, T1, or a "nailed"
  132. ISDN link).
  133.  
  134. <hr>
  135.  
  136. <a name="Objects"><h2>NetMagic Server Objects</h2></a>
  137. The NetMagic server allows you to define and enable different 
  138. <i>server objects</i>.  A server object can be an HTTP server, 
  139. a ChatRoom, or the HTTP proxy.
  140. <p>
  141. <i>Note:</i> You can create multiple HTTP servers and ChatRooms, 
  142. but there can be only one HTTP proxy.
  143. <p>
  144. Each server object must be <a href="#Binding">bound</a> to a TCP 
  145. port.  In addition, each object requires several settings and preferences
  146. be set.  Certain types of settings, such as user accounts and common
  147. configuration strings, can be shared between server objects.  Most
  148. settings, however, are specific to the object, allowing a single
  149. machine to provide different types of service to different groups
  150. of clients.
  151.  
  152. <hr>
  153.  
  154. <a name="Binding"><h2>Binding Server Objects</h2></a>
  155. Each server object must be <i>bound</i> to a TCP address.  This
  156. address specifies how client machines will access the server
  157. object.  The TCP address consists of two parts: an IP address
  158. and a TCP port.
  159. <p>
  160. In most cases, a server will have a single IP address, and
  161. this will be used to bind the server object.  In some cases,
  162. however, a machine can have multiple IP addresses; such a
  163. machine is said to be "multihomed."
  164. <p>
  165. For a multihomed server, a server object can be bound to
  166. all IP addresses for the server or to one address specifically.
  167. The default for server objects is to bind to all local IP
  168. addresses (specified as address 0.0.0.0).  Binding to multiple
  169. addresses is most often used when one machine is
  170. providing multiple, independent web services as if it were two
  171. or more unrelated machines.
  172. <p>
  173. The TCP port determines numerically which TCP-based service
  174. the client is requesting at the given IP address(es).  The
  175. Internet Engineering Task Force reserves certain TCP ports
  176. for well-known services, but most port numbers are not reserved.
  177. Other than such conventions, there is no advantage or disadvantage
  178. to using a certain port number.
  179. <p>
  180. The default TCP port for HTTP service is 80.  Your default web
  181. server object should use this address, as it relieves clients
  182. from explicitly entering the port number in your URLs.  
  183. There is no well-used 
  184. default address for ChatRooms or HTTP proxies.  The NetMagic
  185. server will default to using 8000 and above for ChatRooms
  186. and will use 8080 for the HTTP proxy.
  187. <p>
  188. <i>Note:</i> To avoid conflicts with other TCP/IP-based services
  189. your server may be providing, we recommend not using TCP port
  190. numbers below 1024.
  191.  
  192. <hr>
  193.  
  194. <a name="Global"><h2>Global Settings and Configuration</h2></a>
  195. For the Enterprise Server, all server configuration is performed
  196. by using the NetMagic Control Panel icon.  For the Personal
  197. Server, all settings are accessed via the Settings... button
  198. in the NetMagic application's main window.  You may have to
  199. restore the NetMagic icon (Windows NT) or click on the NetMagic
  200. icon in the task bar (Windows 95) to see this window.
  201. <p>
  202. The NetMagic server makes extensive use of property sheets, also 
  203. called tabbed dialogs.  The main configuration dialog allows
  204. configuring several global server properties:
  205. <dl>
  206. <dt><b><a href="#Servers">Servers</a></b>
  207.     <dd>Allows creating, editing, and deleting NetMagic server
  208.     objects (HTTP servers, ChatRooms, and the HTTP proxy).
  209. <dt><b><a href="#Users">Users</a></b>
  210.     <dd>Allows creating and editing global user accounts.
  211.     Global user accounts are valid for all server objects.
  212. <dt><b><a href="#Groups">Groups</a></b>
  213.     <dd>Allows creating and editing global user groups.
  214.     Global groups are valid for all server objects.
  215. <dt><b><a href="#Strings">Strings</a></b>
  216.     <dd>Allows creating and editing global strings.  Global
  217.     strings are optional and can be used to centralize
  218.     text used in all server objects such as a site's
  219.     copyright notice.
  220. <dt><b><a href="#Remote">Remote</a></b>
  221.     <dd>Allows managing a remote NetMagic Enterprise server
  222. <dt><b>About</b>
  223.     <dd>Displays version information about the NetMagic server.
  224. <dt><b><a href="#Service">Service</a></b>
  225.     <dd>Allows starting and stopping the NetMagic service
  226.     (Enterprise server only).
  227. </dl>
  228.  
  229. <hr>
  230.  
  231. <h2><a name="Servers">Servers</a></h2>
  232. The Servers property sheet allows editing the following
  233. server object types:
  234. <dl>
  235. <dt><b><a href="#HTTP">HTTP Servers</a></b>
  236.     <dd>HTTP servers allow clients to fetch documents using
  237.     a web browser (i.e. Mosaic) and interact with forms.
  238. <dt><b><a href="#ChatRooms">ChatRooms</a></b>
  239.     <dd>ChatRooms allow clients to converse interactively
  240.     using a web browser.
  241. <dt><b><a href="#Proxy">HTTP Proxy</a></b>
  242.     <dd>The HTTP proxy can be used to improve document
  243.     retrieval time or can be used as part of a secure firewall
  244.     installation.
  245. </dl>
  246.  
  247. <hr>
  248.  
  249. <h2><a name="Service">Service Management</a></h2>
  250. The Service management property sheet allows the NetMagic service
  251. to be started, stopped, paused, or resumed.  The Windows NT
  252. Services Control Panel can be used to perform the same function.
  253. <p>
  254. <i>Note:</i> Only options that can be performed will be
  255. available.  Note that it could take several seconds to start
  256. or stop the service.  Start and Pause will be available if
  257. the NetMagic service is running.
  258. <dl>
  259. <dt><b>Start</b>
  260.     <dd>Starts the NetMagic service.  The service must
  261.     already be installed in the Server Manager's table.
  262.     Setup automaticall installs the NetMagic service.
  263. <dt><b>Stop</b>
  264.     <dd>Stops the NetMagic service.
  265. <dt><b>Pause</b>
  266.     <dd>Pauses the NetMagic service.
  267. <dt><b>Resumes</b>
  268.     <dd>Resumes the NetMagic service.
  269. </dl>
  270.  
  271. <hr>
  272.  
  273. <h2><a name="Remote">Remote Configuration</a></h2>
  274. The Remote property sheet allows a NetMagic service
  275. on a remote machine to be configured.
  276. <p>
  277. <i>Note:</i> In order for the remote NetMagic server to be
  278. configured, the machine it is on must be accessible using
  279. Windows Networking.  It is not sufficient that the server
  280. be accessible via TCP/IP.  Typically, you must either
  281. be using the Windows Internet Name Service or have the remote
  282. system's machine name in your LMHOSTS file.
  283. <p>
  284. <i>Note:</i> Your account must have sufficient access rights to
  285. modify the remote server's NetMagic registry key (HKEY_LOCAL_MACHINE\Software\NetMagic...). 
  286. <p>
  287. <i>Note:</i> The Remote property sheet will not be present if you
  288. are already configuring a remote server.
  289. <dl>
  290. <dt><b>Machine name</b>
  291.     <dd>Specifies the Windows Networking name of the remote
  292.     server.  This is not necessarily the same as its Internet
  293.     DNS name.  The name should be preceded by \\ (i.e. \\SERVER).
  294. <dt><b>Connect</b>
  295.     <dd>Attempts to connect to the remote server.  If the
  296.     connections succeeds, a dialog similar to the NetMagic
  297.     main dialog will appear.  All properties that can be
  298.     configured locally can be configured remotely.
  299. </dl>
  300.  
  301. <hr>
  302.  
  303. <h2><a name="Users">User Accounts</a></h2>
  304. The NetMagic server supports basic client authentication.
  305. Most NetMagic resources and objects can be protected by
  306. specifying an <a href="#ACLs">Access Control List</a>, or
  307. ACL, which specifies who can and cannot access the protected
  308. resource.
  309. <p>
  310. The NetMagic server uses a hierarchy of user accounts.  Each
  311. level of this hierarchy is the account's <i>context</i>.  Global
  312. accounts are valid for all NetMagic server objects, class accounts 
  313. are available for a given type of NetMagic server object (i.e.
  314. ChatRooms), and object accounts are valid for a specific
  315. server object.  When verifying usernames and passwords, local
  316. accounts are searched first, then class accounts, then global
  317. accounts.
  318. <p>
  319. The User property page lists all user accounts for the given
  320. context.  The following options are available:
  321. <dl>
  322. <dt><b>New...</b>
  323.     <dd>Create a new user account.  The user name must be unique
  324.     in the current context.  Case is ignored for the user name
  325.     <i>but not for the password.</i>
  326. <dt><b>Edit...</b>
  327.     <dd>Edit the currently selected user account.
  328. <dt><b>Delete</b>
  329.     <dd>Delete the currently selected user account.
  330. </dl>
  331. <i>Note:</i> NetMagic user and group accounts are not related to
  332. Windows user accounts.  This is a deliberate design feature;
  333. basic authentication relies on the plaintext transmission of
  334. passwords.  If an account's password were to be stolen, only
  335. the NetMagic resources themselves, and not the entire server,
  336. would be compromised.
  337.  
  338. <hr>
  339.  
  340. <h2><a name="Groups">User Groups</a></h2>
  341. User groups provide a convenient way of grouping various
  342. users together.  Instead of specifying each user separately,
  343. a new group can be created consisting of the desired users.
  344. <p>
  345. As with <a href="#Users">user</a> accounts, a hierarchy of group 
  346. accounts is implemented.  [The implementation of this feature
  347. has not been finalized, pending beta tester feedback.] 
  348. <p>
  349. The Group property page lists all groups for the given
  350. context.  The following options are available:
  351. <dl>
  352. <dt><b>New...</b>
  353.     <dd>Create a new group.  The group name must be unique
  354.     in the current context.  Case is ignored for the group name.
  355.     Note that multiple users can be chosen to be members of the
  356.     group.
  357. <dt><b>Edit...</b>
  358.     <dd>Edit the currently selected group.
  359. <dt><b>Delete</b>
  360.     <dd>Delete the currently selected group.
  361. </dl>
  362.  
  363. <hr>
  364.  
  365. <h2><a name="Strings">Configuration Strings</a></h2>
  366. The NetMagic server uses strings to form certain client
  367. responses.  For example, all the text viewed by clients in
  368. ChatRooms is constructed from a table of strings.
  369. <p>
  370. A string is nothing more than text.  Each string must be
  371. given a name, which is called its token.  For example,
  372. the string "Copyright © 1995 FooBar, Inc." can be
  373. given the token name copyright.
  374. <p>
  375. To use the copyright string, another string might contain
  376. the following text: "All contents %copyright%"  When
  377. the NetMagic server is constructing response text, any
  378. text surrounded by two % signs is considered to be the
  379. token name of a string.  If a string with this name is
  380. found, the token name and the % signs are replaced with the
  381. string.  If not, the string is not modified.
  382. <p>
  383. Certain token names are reserved.  For example, ChatRooms
  384. use join-form to specify which text is displayed when a
  385. client joins a ChatRoom.  [Not all reserved strings are
  386. currently documented.]
  387. <p>
  388. As with <a href="#Users">user</a> accounts, a hierarchy of 
  389. configuration strings is maintained.  A string specified at
  390. a lower context (i.e. for a specific object) will override
  391. a string defined at a higher context (i.e. a global string). 
  392. <p>
  393. The String property page displays all strings that have been
  394. redefined for the current context:
  395. <dl>
  396. <dt><b>New...</b>
  397.     <dd>Create a new string.  The dialog allows you to enter
  398.     the string's token name and specify its text.  You can
  399.     also choose a predefined string name, which will show
  400.     the default value for the string and a brief usage
  401.     guideline.
  402. <dt><b>Edit...</b>
  403.     <dd>Edit the currently selected string.
  404. <dt><b>Delete</b>
  405.     <dd>Delete the currently selected string.
  406. </dl>
  407.  
  408. <hr>
  409.  
  410. <a name="HTTP"><h2>Global HTTP Settings</h2></a>
  411. Zero or more HTTP server objects can be created on a single
  412. machine running the NetMagic server.  Each HTTP server
  413. provides clients with access to files, typically HTML text and
  414. Gif and JPEG pictures.  Each HTTP server can provide access to
  415. different sets of files and to different users.
  416. <dl>
  417. <dt><b><a href="#HTTPServers">HTTP</a></b>
  418.     <dd>Allows creating, editing, and deleting HTTP server 
  419.     objects.
  420. <dt><b><a href="#Users">Users</a></b>
  421.     <dd>Allows creating and editing HTTP class user accounts.
  422.     HTTP class user accounts are valid for all HTTP
  423.     server objects.
  424. <dt><b><a href="#Groups">Groups</a></b>
  425.     <dd>Allows creating and editing HTTP class group accounts.
  426. <dt><b><a href="#Strings">Strings</a></b>
  427.     <dd>Allows creating and editing HTTP class strings.
  428. <dt><b><a href="#VPaths">Virtual Paths</a></b>
  429.     <dd>Allows creating and editing HTTP class virtual paths.
  430.     Virtual paths provide access to files not in an HTTP
  431.     server object's root directory.
  432. <dt><b><a href="#MIMETypes">MIME Types</a></b>
  433.     <dd>Allows determining how filename extensions are mapped
  434.     to MIME datatypes.
  435. <dt><b><a href="#MIMEIcons">MIME Icons</a></b>
  436.     <dd>Allows specifying which GIFs are displaed in directory
  437.     listings for various MIME types.
  438. <dt><b><a href="#Redirections">Redirections</a></b>
  439.     <dd>Allows creating and editing HTTP class URL redirections.
  440.     URL redirections provide an automatic way to point clients
  441.     to a document's new location.
  442. </dl>
  443. Please see <a href="#HTTPCGI">CGI Scripts</a> and <a href="#HTTPMaps">
  444. clickable maps</a> for information on other advanced HTTP features.
  445. <hr>
  446.  
  447. <a name="HTTPServers"><h2>HTTP Servers</h2></a>
  448. Zero or more HTTP server objects can be created on a single
  449. machine running the NetMagic server.  Each HTTP server
  450. provides clients with access to files, typically HTML text and
  451. GIF and JPEG pictures.  Each HTTP server can provide access to
  452. different sets of files and to different users.
  453. <p>
  454. The HTTP Servers property page lists all HTTP servers by TCP port
  455. and bind address.  The following buttons are available:
  456. <dl>
  457. <dt><b>New...</b>
  458.     <dd>Create a new HTTP server.  The 
  459.     <a href="#HTTPSettings">HTTP
  460.     Settings</a> dialog is displayed.
  461. <dt><b>Edit...</b>
  462.     <dd>Edit the currently selected HTTP server.  The 
  463.     <a href="#HTTPSettings">HTTP
  464.     Settings</a> dialog is displayed.
  465. <dt><b>Delete</b>
  466.     <dd>Delete the currently selected HTTP server.
  467. </dl>
  468.  
  469. <hr>
  470.  
  471. <a name="Redirections"><h2>URL Redirections</h2></a>
  472. URL redirections provide an easy way to point clients to
  473. the new location of a moved document.  Each redirection
  474. consists of two parts: the old URL and the new URL.
  475. <p>
  476. URL redirections specified for individual HTTP server objects
  477. take precedence over those specified for all HTTP servers.
  478. <p>
  479. The old URL should be specified by path only; do not include
  480. the protocol (http:) or host:port (www.foo.com:80) portions.
  481. The new URL may include the protocol and host:port if the
  482. document has been moved to a new machine.
  483. <dl>
  484. <dt><b>New...</b>
  485.     <dd>Create a new URL redirection.
  486. <dt><b>Edit...</b>
  487.     <dd>Edit the currently selected URL redirection.
  488. <dt><b>Delete</b>
  489.     <dd>Delete the currently selected URL redirection.
  490. </dl>
  491. <i>Note:</i> Unneeded redirections should be removed when
  492. they are no longer needed, as there is a slight performance
  493. impact when redirections are present.  If redirections are
  494. present, they are searched using a hash table. 
  495.  
  496. <hr>
  497.  
  498. <a name="VPaths"><h2>Virtual Paths</h2></a>
  499. Typically all files made available to a given HTTP server 
  500. object must be copied to a location under its root directory.
  501. Virtual paths allow files outside the server's root directory
  502. to be accessed as if they were in a subdirectory.
  503. <p>
  504. Virtual paths specified for individual HTTP server objects
  505. take precedence over those specified for all HTTP servers.
  506. <p>
  507. A virtual path consists of a virtual directory name and
  508. the physical directory the path corresponds to.  The virtual
  509. directory name should not contain spaces, /, or \ characters.
  510. The physical directory can be any directory accessible to
  511. the server.
  512. <p>
  513. If the first component of a URL's path matches a virtual path,
  514. the virtual path's directory will be used to transform the
  515. URL into a local path instead of the HTTP server's root
  516. directory.  For example, a URL of http://www.foo.com/default.html
  517. will return c:\http\default.html if c:\http is the HTTP
  518. directory, but if cd-rom is a virtual path to physical location
  519. r:\, then http://www.foo.com/cd-rom/ will correspond to r:\.
  520. <dl>
  521. <dt><b>New...</b>
  522.     <dd>Create a new virtual path.
  523. <dt><b>Edit...</b>
  524.     <dd>Edit the currently selected virtual path.
  525. <dt><b>Delete</b>
  526.     <dd>Delete the currently selected virtual path.
  527. <dt><b><a href="#ACLs">ACL</a></b>
  528.     <dd>When creating or editing a virtual path, you can
  529.     also specify an ACL to limit which clients can access files via the
  530.     virtual path.
  531. </dl>
  532. <i>Note:</i> Unneeded virtual paths should be removed when
  533. they are no longer needed, as there is a slight performance
  534. impact when virtual paths are present.  If virtual paths are
  535. present, they are searched using a hash table. 
  536.  
  537. <hr>
  538.  
  539. <h2><A NAME="MIMETypes">MIME Types</A></h2>
  540.  
  541. HTTP servers generally return the document type with documents
  542. fetched by clients.  Since Windows does not provide any way to
  543. directly determine a file's MIME type, the determination is based on
  544. the filename's extension.
  545. <p>
  546. A list of filename extensions and the MIME types they map to is listed
  547. on this page.  The following options are available:
  548. <dl>
  549. <dt><b>New...</b>
  550.     <dd>Create a new MIME type mapping.  A single extension
  551.     can map to only one MIME type, but multiple extensions
  552.     can map to the same type.
  553. <dt><b>Edit...</b>
  554.     <dd>Edit the currently selected mapping.
  555. <dt><b>Delete</b>
  556.     <dd>Delete the currently selected mapping.
  557. <dt><b>Default</b>
  558.     <dd>Determines the MIME type that will be specified for all
  559.     files that don't otherwise have an explicit type.
  560. </dl>
  561.  
  562. <hr>
  563.  
  564. <h2><A NAME="MIMEIcons">MIME Icons</A></h2>
  565.  
  566. When generating a directory listing for clients, the
  567. NetMagic server can place a small "icon" (really an
  568. in-line Gif image) next to the files.  Which icon is used
  569. depends on the MIME type of the file.
  570. <p>
  571. A list of MIME types and the image URL to use for the icon is 
  572. displayed.  The following options are available:
  573. <dl>
  574. <dt><b>New...</b>
  575.     <dd>Create a new MIME type mapping.  A single extension
  576.     can map to only one MIME type, but multiple extensions
  577.     can map to the same type.
  578. <dt><b>Edit...</b>
  579.     <dd>Edit the currently selected mapping.
  580. <dt><b>Delete</b>
  581.     <dd>Delete the currently selected mapping.
  582. <dt><b>Default</b>
  583.     <dd>Determines the icon that will be displayed for files
  584.     of the default MIME type.
  585. <dt><b>Folder</b>
  586.     <dd>Determines the icon that will be displayed for directories.
  587. </dl>
  588.  
  589. <hr>
  590.  
  591. <a name="HTTPSettings"><h2>HTTP Server Settings</h2></a>
  592. Each HTTP server object has several settings.  For many users,
  593. only the TCP port and root directory need to be specified.  Other
  594. settings will be useful for advanced users.
  595. <p>
  596. The following property pages are available:
  597. <dl>
  598. <dt><b><a href="#HTTPGeneral">General</a></b>
  599.     <dd>General settings for the HTTP server object.
  600. <dt><b><a href="#Users">Users</a></b>
  601.     <dd>Allows creating and editing HTTP server object user
  602.     accounts.  HTTP class user accounts are valid for all HTTP
  603.     server objects.
  604. <dt><b><a href="#Groups">Groups</a></b>
  605.     <dd>Allows creating and editing HTTP server object group
  606.     accounts.
  607. <dt><b><a href="#Strings">Strings</a></b>
  608.     <dd>Allows creating and editing HTTP server object strings.
  609. <dt><b><a href="#Redirections">Redirections</a></b>
  610.     <dd>Allows creating and editing HTTP server object URL 
  611.     redirections.
  612.     URL redirections provide an automatic way to point clients
  613.     to a document's new location.
  614. <dt><b><a href="#VPaths">Virtual Paths</a></b>
  615.     <dd>Allows creating and editing HTTP server object virtual 
  616.     paths.  Virtual paths provide access to files not in an HTTP
  617.     server object's root directory.
  618. <dt><b><a href="#MIMETypes">MIME Types</a></b>
  619.     <dd>Allows determining how filename extensions are mapped
  620.     to MIME datatypes.
  621. <dt><b><a href="#MIMEIcons">MIME Icons</a></b>
  622.     <dd>Allows specifying which GIFs are displaed in directory
  623.     listings for various MIME types.
  624. <dt><b><a href="#Access">Access Control</a></b>
  625.     <dd>Controls which clients can access the HTTP server
  626.     object.  Both <a href="#ACLs">ACLs</a> and the <a
  627.     href="#Binding">binding</a> address can be specified.
  628. </dl>
  629.  
  630. <hr>
  631.  
  632. <a name="HTTPGeneral"><h2>General HTTP Settings</h2></a>
  633. The general HTTP server object settings control the most
  634. important functions of the HTTP server object.
  635. <p>
  636. The following options can be set:
  637. <dl>
  638. <dt><b>Enable HTTP server</b>
  639.     <dd>This option must be checked to enable clients to use
  640.     the server.  Turning this off is useful when you want
  641.     to temporarily turn off the server without deleting the
  642.     object.
  643. <dt><b>Port</b>
  644.     <dd>The default TCP port for an HTTP server is 80.  If
  645.     multiple HTTP servers are bound to the same address,
  646.     they will require unique addresses.
  647. <dt><b>Root directory</b>
  648.     <dd>Determines where the server will look for files specified
  649.     in clients' URLs.
  650. <dt><b><a href="#Logging">Logging</a></b>
  651.     <dd>The location of the log files and the use of DNS in
  652.     logging can be selected.
  653. <dt><b>Allow directory browsing</b>
  654.     <dd>Determines if clients can view the contents of 
  655.     directories by issuing the URL of a directory.
  656. <dt><b>Default file</b>
  657.     <dd>Determines which file is returned to the client
  658.     when a directory URL is issued.  This option takes
  659.     precedence over directory browsing if the two conflict.
  660. </dl>
  661.  
  662. <hr>
  663.  
  664. <a name="Access"><h2>Server Access Control</h2></a>
  665. The Access property page determines which clients can access
  666. resources on the server.  Two separate mechanisms are used: <a
  667. href="#ACLs">Access Control Lists</a> and <a href="#Binding>
  668. binding</a> address.
  669. <p>
  670. The following options can be set:
  671. <dl>
  672. <dt><b>Global ACL</b>
  673.     <dd>Specifies the ACL for all resources made available
  674.     by the server object.
  675. <dt><b>File ACLs (HTTP servers objects only)</b>
  676.     <dd>Spcifies which clients can access individual files.
  677. <dt><b>Binding Address</b>
  678.     <dd>Specifies which IP address the server is bound to.
  679.     Only clients connecting to the server using this address
  680.     will be able to access the server.  An address of 0.0.0.0
  681.     allows clients to access the server using any valid
  682.     IP address for the server.
  683. </dl>
  684.  
  685. <hr>
  686.  
  687. <a name="Logging"><h2>Logging</h2></a>
  688. Each HTTP server object allows all transactions to be logged.
  689. HTTP server objects and the HTTP proxy use the NCSA Common
  690. Log File format (the ChatRoom servers use a user-definable
  691. logging format due to the fact that ChatRoom URLs don't
  692. fit well into the common logfile format).
  693. <p>
  694. Each server object allows a log file name to be specified.
  695. If this field is left blank, logging will be disabled for
  696. the server.
  697. <p>
  698. Each server also allows you to specify whether or not to resolve
  699. IP addresses to DNS hostnames when logging.  Selecting this
  700. may lead to more readable logs at the expense of performance
  701. when logging.
  702. <p>
  703. The filename for the log can be a regular filename, in which
  704. case all transactions will be logged to a single file.  In
  705. addition, the following string tokens can be used: %year%,
  706. %month%, %day%, %hour%, and %minute%.  These will be expanded
  707. to match the current time (in GMT or UTC) when determining which
  708. pathname to use.  This provides an easy way to break logs into
  709. separate files.  All needed directories will be created as well,
  710. so a log file name such as the following is valid:
  711. <p>
  712. c:\logs\http\%year%\%month-%day%
  713. <p>
  714. <i>Note:</i> The :, /, and space characters are generally
  715. reserved by the file system, so - is the best bet to use as
  716. a time and date seaparator.
  717.  
  718. <hr>
  719.  
  720. <a name="HTTPOver"><h2>HTTP Server Overview</h2></a>
  721. Each HTTP server object can allow clients to access documents
  722. using HTTP-based browsers, such as Mosaic or other web
  723. browsers.
  724. <p>
  725. In the most common configuration, the files that you want to
  726. make available to clients are all copied into a directory called
  727. the HTTP server's root directory (for example, C:\HTTP).  
  728. Any files in this directory (or any subdirectories under it)
  729. will be accessible to clients.
  730. <p>
  731. The URL that the client specifies determines which document
  732. is returned.  The protocol, host, and port portions (i.e.
  733. http://www.foobar.com:8080) are replaced by the HTTP root
  734. (i.e. C:\HTTP).  Slashes in the URL are interpreted exactly
  735. as directory path dividers.
  736. <p>
  737. A few special situations modify this otherwise straightforward
  738. translation of a URL into a pathname:
  739. <ul>
  740. <li><a href="VPaths">Virtual paths</a> allow files outside the
  741.     root directory to be accessed
  742. <li><a href="Redirections">URL Redirections</a> may cause an
  743.     entirely different URL to be returned.
  744. <li>If a URL corresponds to a directory, but does not have
  745.     a trailing slash, the server will issue an automatic
  746.     redirection to the client for the same URL with the
  747.     slash.
  748. <li>If a URL corresponds to a directory and includes the
  749.     trailing slash, a file with the default file name in
  750.     the directory will be returned.  If there is no matching
  751.     file and directory browsing is enabled, then a directory
  752.     listing will be constructed and returned.
  753. </ul>
  754.  
  755. <hr>
  756.  
  757. <a name="ChatRooms"><h2>Global ChatRoom Settings</h2></a>
  758. Zero or more HTTP server objects can be created on a single
  759. machine running the NetMagic server.  Each HTTP server
  760. provides clients with access to files, typically HTML text and
  761. Gif and JPEG pictures.  Each HTTP server can provide access to
  762. different sets of files and to different users.
  763. <dl>
  764. <dt><b><a href="#ChatServers">ChatRooms</a></b>
  765.     <dd>Allows creating, editing, and deleting ChatRoom server 
  766.     objects.
  767. <dt><b><a href="#Users">Users</a></b>
  768.     <dd>Allows creating and editing ChatRoom class user accounts.
  769.     ChatRoom class user accounts are valid for all ChatRoom
  770.     server objects.
  771. <dt><b><a href="#Groups">Groups</a></b>
  772.     <dd>Allows creating and editing ChatRoom class group accounts.
  773. <dt><b><a href="#Strings">Strings</a></b>
  774.     <dd>Allows creating and editing ChatRoom class strings.
  775. </dl>
  776.  
  777. <hr>
  778.  
  779. <a name="ChatServers"><h2>ChatRoom Servers</h2></a>
  780. Zero or more ChatRoom server objects can be created on a single
  781. machine running the NetMagic server.  Each ChatRoom server
  782. object must have a unique name and TCP port number.
  783. <p>
  784. The ChatRoom Servers property page lists all ChatRoom servers by room
  785. name.  The following buttons are available:
  786. <dl>
  787. <dt><b>New...</b>
  788.     <dd>Create a new ChatRoom server.  The 
  789.     <a href="#ChatSettings">ChatRoom
  790.     Settings</a> dialog is displayed.
  791. <dt><b>Edit...</b>
  792.     <dd>Edit the currently selected ChatRoom server.  The 
  793.     <a href="#ChatSettings">ChatRoom
  794.     Settings</a> dialog is displayed.
  795. <dt><b>Delete</b>
  796.     <dd>Delete the currently selected ChatRoom server.
  797. </dl>
  798.  
  799. <hr>
  800.  
  801. <a name="ChatSettings"><h2>ChatRoom Server Settings</h2></a>
  802. Each ChatRoom server object has several settings.  For many users,
  803. only the TCP port and root directory need to be specified.  Other
  804. settings will be useful for advanced users.
  805. <p>
  806. The following property pages are available:
  807. <dl>
  808. <dt><b><a href="#ChatGeneral">General</a></b>
  809.     <dd>General settings for the ChatRoom server object.
  810. <dt><b><a href="#Users">Users</a></b>
  811.     <dd>Allows creating and editing ChatRoom server object user
  812.     accounts.  ChatRoom class user accounts are valid for all ChatRoom
  813.     server objects.
  814. <dt><b><a href="#Groups">Groups</a></b>
  815.     <dd>Allows creating and editing ChatRoom server object group
  816.     accounts.
  817. <dt><b><a href="#Strings">Strings</a></b>
  818.     <dd>Allows creating and editing ChatRoom server object strings.
  819. <dt><b><a href="#Access">Access Control</a></b>
  820.     <dd>Controls which clients can access the ChatRoom server
  821.     object.  Both <a href="#ACLs">ACLs</a> and the <a
  822.     href="#Binding">binding</a> address can be specified.
  823. </dl>
  824.  
  825. <hr>
  826.  
  827. <a name="ChatGeneral"><h2>General ChatRoom Settings</h2></a>
  828. The general HTTP server object settings control the most
  829. important functions of the HTTP server object.
  830. <p>
  831. The following options can be set:
  832. <dl>
  833. <dt><b>Enable ChatRoom</b>
  834.     <dd>This option must be checked to enable clients to use
  835.     the server.  Turning this off is useful when you want
  836.     to temporarily turn off the server without deleting the
  837.     object.
  838. <dt><b>Port</b>
  839.     <dd>The default TCP port for an ChatRoom is the first available
  840.     TCP port after 8000.  Each ChatRoom requires a unique port.
  841. <dt><b>Name</b>
  842.     <dd>Determines the name of the ChatRoom.  Each ChatRoom on 
  843.     a given server must have a unique name.
  844. <dt><b>Description</b>
  845.     <dd>Determines the description of the ChatRoom.  The description
  846.     is displayed in the room index and the room join form.
  847. <dt><b>Timeout</b>
  848.     <dd>Determines how many seconds a realtime connection will
  849.     be held open before reverting to a non-realtime connection.
  850. <dt><b>Maximum lines</b>
  851.     <dd>Determines how many lines of dialog will be maintained
  852.     in memory.  This is the largest number of lines a client
  853.     can request to view.
  854. <dt><b>Hide room</b>
  855.     <dd>A hidden room will not appear in the room index.  This can be
  856.     useful if you don't want people to know about a ChatRoom.
  857. <dt><b><a href="#Logging">Logging</a></b>
  858.     <dd>The location of the log files and the use of DNS in
  859.     logging can be selected.
  860. </dl>
  861.  
  862. <hr>
  863.  
  864. <a name="Proxy"><h2>HTTP Proxy</h2></a>
  865. The HTTP proxy provides two functions:
  866. <ul>
  867. <li>Allowing clients inside
  868. a firewall to issue HTTP requests to hosts they cannot directly
  869. connect to
  870. <li>Improving client access to documents by caching them on
  871. the server
  872. </ul>
  873. <p>
  874. The following property pages are available:
  875. <dl>
  876. <dt><b><a href="#ProxyGeneral">General</a></b>
  877.     <dd>General settings for the HTTP proxy object.
  878. <dt><b><a href="#Cache">Cache</a></b>
  879.     <dd>Configures the operation of the HTTP proxy's cache.
  880. <dt><b><a href="#Barred">Barred URLs</a></b>
  881.     <dd>Configures the list of URLs that cannot be acessed
  882.     by clients via the proxy.
  883. <dt><b><a href="#NoCache">Uncached URLs</a></b>
  884.     <dd>Configures the list of URLs that should not be cached.
  885. <dt><b><a href="#Cascade">Cascade</a></b>
  886.     <dd>Allows the proxy to be configured to request documents
  887.     from another proxy.
  888. <dt><b><a href="#Access">Access Control</a></b>
  889.     <dd>Controls which clients can access the HTTP proxy
  890.     object.  Both <a href="#ACLs">ACLs</a> and the <a
  891.     href="#Binding">binding</a> address can be specified.
  892. </dl>
  893.  
  894. <hr>
  895.  
  896. <a name="ProxyGeneral"><h2>General HTTP Proxy Settings</h2></a>
  897. The following settings determine how the HTTP proxy operates:
  898. <dl>
  899. <dt><b>Enable HTTP Proxy</b>
  900.     <dd>Allows the proxy to be enabled or disabled.
  901. <dt><b>Port</b>
  902.     <dd>Determines the HTTP proxy's TCP port.  The default
  903.     is 8080.  80 should not be used because the HTTP
  904.     proxy isn't a true HTTP server.
  905. <dt><b><a href="#Logging">Logging</a></b>
  906.     <dd>The location of the log files and the use of DNS in
  907.     logging can be selected.
  908. </dl>
  909.  
  910. <hr>
  911.  
  912. <a name="Cache"><h2>Cache Settings</h2></a>
  913. The following settings determine how the HTTP proxy cache
  914. operates:
  915. <dl>
  916. <dt><b>Cache directory</b>
  917.     <dd>Determines where cached files and database state are stored.
  918. <dt><b>Maximum cache size</b>
  919.     <dd>Determines how large the cache should be allowed to grow.
  920.     Specify 0 to disable caching.
  921. <dt><b>Purge files after...</b>
  922.     <dd>Specifies the maximum time a file will be kept in the cache.
  923.     Documents with shorter expiration times will be purged sooner.
  924. <dt><b>Save cache every...</b>
  925.     <dd>Determines how often the cache database should be saved
  926.     to disk.  
  927. <dt><b>Purge cache every...</b>
  928.     <dd>Determines how often to purge the cache.  During a purge the
  929.     cache to shrunk to the maximum size and expired files are removed. 
  930. </dl>
  931.  
  932. <hr>
  933.  
  934. <a name="Barred"><h2>Barred URLs</h2></a>
  935. A list of URLs that will not be made available to clients can
  936. be specified.  The current list of barred URLs is displayed.
  937. The URLs can include the wildcard characters * and ?
  938. to represent 0 or more characters or one character, respectively.
  939. <p>
  940. <i>Note:</i> The URLs in the URL list are compared on a textual
  941. basis.  No attempt is made to resolve various aliases for the same
  942. site (i.e. using IP numbers instead of host names, including or
  943. excluding a default port, etc.) 
  944. <dl>
  945. <dt><b>New...</b>
  946.     <dd>Allows a new barred URL specifier to be added to the list.
  947. <dt><b>Edit...</b>
  948.     <dd>Allows a URL to be edited.
  949. <dt><b>Delete</b>
  950.     <dd>Removes a URL from the list.
  951. </dl>
  952.  
  953. <hr>
  954.  
  955. <a name="NoCache"><h2>Uncached URLs</h2></a>
  956. A list of URLs that will not be cached can
  957. be specified.  The current list of uncached URLs is displayed.
  958. The URLs can include the wildcard characters * and ?
  959. to represent 0 or more characters or one character, respectively.
  960. <p>
  961. <i>Note:</i> There are other factors that determine if a URL
  962. is cached, including its expiration date, a no-cache flag, the
  963. presense of query strings, or the HTTP access method.  
  964. <dl>
  965. <dt><b>New...</b>
  966.     <dd>Allows a new uncached URL specifier to be added to the list.
  967. <dt><b>Edit...</b>
  968.     <dd>Allows a URL to be edited.
  969. <dt><b>Delete</b>
  970.     <dd>Removes a URL from the list.
  971. </dl>
  972.  
  973. <hr>
  974.  
  975. <a name="Cascade"><h2>Cascade</h2></a>
  976. By default the HTTP proxy will fetch documents directly from the
  977. Internet.  If a proxy host is specified on the Cascade page,
  978. the HTTP proxy will request documents from yet another HTTP
  979. proxy.   
  980. <dl>
  981. <dt><b>Proxy host</b>
  982.     <dd>Specifies the host name of the proxy.  Leave blank to disable
  983.     the use of another proxy.
  984. <dt><b>Port</b>
  985.     <dd>Specifies the port at which the cascaded proxy listens.
  986. </dl>
  987. <hr>
  988.  
  989. <h2><A NAME="HTTPCGI">CGI Scripts</A></h2>
  990.  
  991. The NetMagic HTTP server supports CGI/1.1 (with the exception of nph- scripts).  A
  992. CGI script provides a means for a URL to refer to a program on the server that
  993. produces the output.  CGI scripts are typically used to process forms, but can be used
  994. for much more.  Please
  995. refer to <a href="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html">NCSA's documentation</a>
  996. for a complete discussion of CGI scripts and how they are used.  This document
  997. discusses only the NetMagic implementation specific features.
  998. <p>
  999. <i>Note:</i> This beta release of NetMagic does not support WinCGI scripts.  The next
  1000. beta release will.  In a Win32 implementation, however, normal CGI scripts should
  1001. be used since they perform better than WinCGI scripts.
  1002. <p>
  1003. CGI scripts must be executable images that end with an .EXE extension, that use redirectable,
  1004. standard input and output, and can be launched by CreateProcess() under the host operating
  1005. system.  For Windows NT and Windows 95, this includes Win32 console applications and DOS
  1006. console applications.  Windows NT (on i386 systems) also supports OS/2 1.x console applications.
  1007. Note that the executable itself may be an interpreter for something like a perl script; the actual
  1008. "script" may be specified using a variety of allowable CGI methods (i.e. query string).  (I haven't
  1009. found any way of doing a non-trivial CGI script using .BAT files, although I'd be interested if you
  1010. do...)
  1011. <P>
  1012. In order for a URL to be recognized as a CGI script invocation, it must have a path component with
  1013. a .EXE extension.  For example, /scripts/regcgi.exe/foobar.dat will work, but
  1014. /scripts/regcgi/foobar.dat won't.  For a script written in an interpreted language (i.e. perl) to be
  1015. invoked, the interpreter's .EXE file must be in the URL.  <i>This also means that you should not name
  1016. directories with .EXE extensions!</i>
  1017. <p>
  1018. For POST operations, the above is sufficient; for GET operations, there must be a non-empty query
  1019. string specified for the URL as well; otherwise, the URL will be handled as a standard GET request
  1020. (to allow downloading EXE files from, say, an archive).  This can be "forced" by appending a bogus
  1021. query: /scripts/regcgi.exe/foobar.dat?bogus.  Note that the CGI specification allows the server to
  1022. pass the query string to the script on its command line if it does not contain an = character; this is
  1023. the only documented use of the command line for CGI scripts.  For CGI scripts invoked via forms
  1024. with the GET method, the form field values will be appended by the browser to the action URL, so it
  1025. will be recognized as a CGI script (but the query won't be placed on the command line because of
  1026. the ='s in the form value string.)
  1027. <p>
  1028. The path leading up to the .EXE file in the URL must identify the CGI script; the system PATH is
  1029. not searched.  This path will be the current directory for the CGI script.  The stuff after the .EXE in
  1030. the URL is passed to the script as the PATH_INFO variable.  For example:
  1031. /data/source/monkey.exe/chimp.dat would attempt to run /data/source/monkey.exe from the
  1032. directory /data/source (relative to the HTTP server root, of course); PATH_INFO would be
  1033. /chimp.dat.
  1034.  
  1035. <hr>
  1036.  
  1037. <h2><A NAME="HTTPMaps">Clickable Maps</A></h2>
  1038.  
  1039. Clickable maps provide a (relatively) easy way to create documents with "hot" images.
  1040. Typical uses are for graphical button bars and other visual menus.
  1041. <p>
  1042. The implementation of clickable maps is similar to that of NCSA HTTPD; that is, the
  1043. HTTP server implements the hit testing.  A map file
  1044. (which must have a .MAP extension) contains a text list of regions and the URLs that should
  1045. be accessed when the click falls within these regions.
  1046. <p>
  1047. First, in the HTTP document, something similar to the following markup should be used:
  1048. <p>
  1049. <code><a href="http://foobar.com/image.map">
  1050. <img src="http://foobar.com/image.gif" ismap></a></code>
  1051. <p>
  1052. The important thing is the ISMAP option; this will cause the browser to tack on the
  1053. mouse coordinates when the browser fetches the map file.
  1054. <p>
  1055. The map file is an ASCII text file that can contain the following region commands, one
  1056. per line:
  1057. <dl>
  1058. <dt><b>default <i>url</i></b>
  1059.     <dd><i>url</i> is the default URL for this image, if the click was not in any other
  1060.     region
  1061. <dt><b>circle <i>x, y r url</i></b>
  1062.     <dd><i>url</i> will be returned if the click is in a circle of radius r centered at
  1063.     (x, y).
  1064. <dt><b>rectangle <i>a, b c, d url</i></b>
  1065.     <dd><i>url</i> will be returned if the click is in a rectangle with (a, b) as the
  1066.     upper-left corner and (c, d) is the lower-right.
  1067. <dt><b>polygon <i>a0, b0 (a1, b1..) url</i></b>
  1068.     <dd><i>url</i> will be returned if the click is in the polygon enclosed by the
  1069.     specified points.  Up to 16 points can be specified.
  1070. </dl>
  1071.  
  1072. <i>Note:</i> If the URLs in the map file are local URLs (i.e. begin with /), the
  1073. server will immediately send the data in the corresponding file.  The browser will
  1074. believe that the URL for this document is that of the <i>map</i> file, however.  This
  1075. could mess up any local URLs in the document.  Supplying full URLs in the map file
  1076. will prevent this problem, but will require an additional connection to the server
  1077. to fetch the document.  Alternatively, the <BASE ...> tag can be placed in the
  1078. HTML document.
  1079.  
  1080. <hr>
  1081.  
  1082. <h2><A NAME="ACLs">Access Control Lists</A></h2>
  1083.  
  1084. The NetMagic server uses Access Control Lists determine who can and cannot access 
  1085. various resources.  Access can be based on the client's username/password, the group the client 
  1086. belongs to, or the client's machine's IP address.  Examples include limiting access to
  1087. a local domain and making resources available to only a few users.
  1088. <P>
  1089. <i>Note:</i> ACLs are an advanced feature and may be potentially confusing at first.
  1090. There is no need to use ACLs to operate a NetMagic server.
  1091. <P>
  1092. The following resources can be protected:
  1093. <ul>
  1094. <li>Access to server objects
  1095. <li>Access to individual virtual paths (HTTP servers only)
  1096. <li>Access to individual files and directory listings (HTTP servers only)
  1097. </ul>
  1098. An access control list (ACL) is a list of filters that test a client's name or group,
  1099. HTTP access method, and IP address.  The filters are evaluated in sequence, and the
  1100. first one that applies to the client is used.  If no filters apply, then access is
  1101. denied.
  1102. <p>
  1103. <b>The exception is an important one: if the ACL contains <i>no</i> filters, then access
  1104. is automatically granted to all users.</b>  This exception allows you to ignore ACLs
  1105. altogether and allow clients to access all documents.
  1106. <P>
  1107. <i>Note:</i> The ACL for the HTTP Proxy should not specify a user or group, since this
  1108. information does not pertain to the proxy.  The Proxy ACL can contain method and IP
  1109. address masks, but you should use * for the user.
  1110. <P>
  1111. <i>Note:</i> In order for an HTTP client to access a document, the client must be
  1112. granted access by the global HTTP server ACL, the virtual path ACL
  1113. (if applicable), and the file/directory ACL (if applicable), in this order.  If the client is
  1114. rejected by any applicable ACL, access will be denied.
  1115.  
  1116. <h3><A NAME="Filters">Access Control Filters</A></h3>
  1117. Each ACL filter specifies a filter type, an access method, a user or group
  1118. (depending on filter type), and an IP address.  A * can be used to indicate
  1119. any method or user/group; similarly, *s can be used for any
  1120. portions of the IP address.
  1121. <p>
  1122. Four ACL filter types are supported:
  1123. <dl>
  1124. <dt><code>Allow-user</code>
  1125.     <dd>Allows access to the given user(s)
  1126. <dt><code>Reject-user</code>
  1127.     <dd>Rejects access to the given user(s)
  1128. <dt><code>Allow-group</code>
  1129.     <dd>Allows access if the user is in the given group
  1130. <dt><code>Reject-group</code>
  1131.     <dd>Rejects access if the user is in the given group
  1132. </dl>
  1133. Three access methods are supported.  These correspond to HTTP/1.0 commands:
  1134. <dl>
  1135. <dt><code>HEAD</code>
  1136.     <dd>Allows the HTML headers of the file to be retrieved
  1137. <dt><code>GET</code>
  1138.     <dd>Allows entire documents to be retrieved
  1139. <dt><code>POST</code>
  1140.     <dd>Allows form data to be sent to the server
  1141. </dl>
  1142.  
  1143. <h3><A NAME="ACLExamples">ACL Examples</A></h3>
  1144.  
  1145. <h4>Example 1: Local ChatRoom</h4>
  1146. Consider the following ACL:
  1147. <p>
  1148. <code>
  1149. Allow-user: *,*,204.31.29.*
  1150. </code>
  1151. <p>
  1152. This ACL allows access to users in the class C domain 204.31.29 only.  All others are
  1153. rejected (the default for a non-empty ACL).
  1154.  
  1155. <h4>Example 2: Protected Document</h4>
  1156. Consider the following ACL:
  1157. <p>
  1158. <code>
  1159. Allow-group: *,netmagic,*
  1160. </code>
  1161. <p>
  1162. This ACL allows access to users who are in the netmagic group.  As above, all others are
  1163. rejected.
  1164.  
  1165. <h4>Example 3: Keeping Out the Riff-Raff</h4>
  1166. Consider the following ACL:
  1167. <p>
  1168. <code>
  1169. Allow-group: *,*,*
  1170. </code>
  1171. <p>
  1172. At first glance, this ACL seems to allow access to everyone; however, users who do not
  1173. enter a username/password that is in the user list are in no group, so they are
  1174. rejected.  Conversely, <i>every</i> user is implicitly in at least one group.
  1175.  
  1176. <h4>Example 4: Sleepless in Pleasanton</h4>
  1177. Consider the following ACL:
  1178. <p>
  1179. <code>
  1180. Allow-user: *,*,204.31.29.7<br>
  1181. Reject-user: *,ernest,*<br>
  1182. Allow-group: *,*,*
  1183. </code>
  1184. <p>
  1185. User ernest (CEO of NetMagic) cannot access the resource unless he is using his office
  1186. machine (204.31.29.7).  Note the importance of order.  All other NetMagic users can access
  1187. the resource, and no one else can.  (This ACL prevents the developers from getting late
  1188. night calls when the spec is reviewed from ernest's home machine :-) )
  1189.  
  1190. <hr>
  1191.  
  1192. <h2><A NAME="ServCmds">NetMagic Service Command-line Options</A></h2>
  1193.  
  1194. As with many other Windows NT services, the NetMagic service (NetMSvc.exe)
  1195. can be installed and removed with command-line switches.  Note that
  1196. these switches don't install and remove the executable; rather, the
  1197. NetMagic service is added to or removed from the Service Control Manager's
  1198. list of services.  <i>You should remove the service before deleting its executable.</i>
  1199. <p>
  1200. To install the NetMagic service, type:
  1201. <p>
  1202. <code>netmsvc -install</code>
  1203. <p>
  1204. from the Windows NT system directory, where Setup installed the service.
  1205. <p>
  1206. To remove the NetMagic service, type:
  1207. <p>
  1208. <code>netmsvc -remove</code>
  1209.  
  1210. <hr>
  1211.  
  1212. <h2><A NAME="Client">Client Usage</A></h2>
  1213.  
  1214. Clients can access the HTTP and ChatRoom services provided by your 
  1215. NetMagic server using almost any HTTP-based web browser.  Typically, 
  1216. you will publish the URL of the services you provide or insert them
  1217. in other web documents.
  1218. <p>
  1219. A URL has the general form:
  1220. <p>
  1221. <code>protocol://hostname:port/path</code>
  1222. <p>
  1223. where protocol will be http for the NetMagic server, the hostname
  1224. will be either the machine's DNS name or IP address, port will
  1225. be the TCP port of the service (if this is 80, it can be
  1226. omitted), and path depends on the type of service.
  1227. <p>
  1228. For HTTP server objects, what comes after the hostname and the first /
  1229. is the virtual path to the document, very similar to a Windows pathname.
  1230. The path is relative to the HTTP server object's root directory, unless
  1231. virtual paths are being used.  It is common to use default files
  1232. so that the URL http://www.machine.com/ returns the homepage.
  1233. <p>
  1234. For ChatRooms, only two URLs are supported for clients.  To retrieve
  1235. an index of all rooms on the server, use:
  1236. <p>
  1237. <code>http://www.machine.com:port/Index</code>
  1238. <p>
  1239. The port can be that of any ChatRoom; they all return the
  1240. same index.
  1241. <p>
  1242. For requesting to join a specific room, use:
  1243. <p>
  1244. <code>http://www.machine.com:port/Join</code>
  1245. <p>
  1246. The index contains the necessary joining URLs; you may need to use
  1247. the above form explicitly for hidden rooms.
  1248.  
  1249. <hr>
  1250.  
  1251. <h2><A NAME="ServInfo">NetMagic Service Management</A></h2>
  1252.  
  1253. This section pertains only to the NetMagic Enterprise server.
  1254. <p>
  1255. A <i>service</i> in Windows NT is an application that runs in the background
  1256. no matter who is logged into the console, if anyone.  This allows the NetMagic
  1257. server to be accessed no matter who is using the server.
  1258. <p>
  1259. You should be familiar with how services work under NT.  NetMagic installs itself
  1260. as an automatic service, which means it is started when the system starts.  You
  1261. can change this via the Services icon in the Control Panel.
  1262. <p>
  1263. You can start, stop, pause, and resume the NetMagic service either
  1264. from the NetMagic control panel or the Services control panel.
  1265. <p>
  1266. Services by default log in under the system account.  We recommend that you
  1267. change this for one simple reason: security.  By creating a user account
  1268. for the NetMagic service that has access only to the files you want clients
  1269. to have access to, you can prevent unintentional access to private files.
  1270. To really be effective, you should also use NTFS instead of FAT, since files
  1271. on FAT partitions are insecure.
  1272. <p>
  1273. The account for the service can be specified via the Startup... button in the
  1274. Services icon in the Control Panel.
  1275. <p>
  1276. <i>Note:</i> NT security doesn't affect NetMagic ACLs, except that if the
  1277. service's account doesn't have access to a resource, then access will always
  1278. be denied no matter what the ACL otherwise stipulates.
  1279. <p>
  1280. Windows NT administration is beyond the scope of this document, and messing
  1281. around with security can cause problems (such as locking yourself out from
  1282. your machine!)  Be careful, and make sure you know what you're doing!
  1283. <p>
  1284. One gotcha that we've encountered is that mapped network drives exist in
  1285. the context of user accounts.  That is, if the server needs access to
  1286. a drive that's on another server, you should use the UNC pathname of
  1287. the drive instead of a mapped drive letter.  If G: is mapped to
  1288. \\SERVER\GIG1, then the UNC form of G:\HTTP is \\SERVER\GIG1\HTTP.
  1289. <p>
  1290. Another gotcha that stung us is when using an alternate account for
  1291. the NetMagic service, be sure to enter the password in the Service
  1292. startup dialog--twice!
  1293.  
  1294. <hr>
  1295.  
  1296. <h2><A NAME="Uninstall">Uninstalling NetMagic</A></h2>
  1297.  
  1298. For this beta, uninstallation must be performed manually.  The release
  1299. version will include an automated uninstall feature.
  1300. <p>
  1301. For the Enterprise version, first the service must be removed from
  1302. the Service Control Manager's list.  To do this, first stop the
  1303. NetMagic service.  Then, change into the
  1304. Windows NT system directory (i.e. \WINNT\SYSTEM32) and type:
  1305. <p>
  1306. <code>netmsvc -remove</code>
  1307. <p>
  1308. Now you can remove <code>netmsvc.exe</code> and <code>netmcpl.cpl</code>.
  1309. <p>
  1310. For both versions, the directory NetMagic was installed in (i.e. C:\NETMAGIC)
  1311. and all its contents can be removed, as can the Program Manager (or
  1312. Windows 95 desktop) group.
  1313. <p>
  1314. Lastly, if you're comfortable with RegEdit32, you can remove the
  1315. <p>
  1316. <code>HKEY_LOCAL_MACHINE\Software\NetMagic</code>
  1317. <p>
  1318. key and all its subkeys from the registry.
  1319. <p>
  1320. These steps will remove all traces of NetMagic from your system.
  1321. <hr>
  1322.  
  1323. June 18, 1995
  1324. <br>
  1325. Beta documentation by <A HREF="mailto:aaron@aristosoft.com">Aaron Wallace</a>.
  1326. <br>
  1327. <i>Software and documentation Copyright © 1995 NetMagic, Inc.  All rights reserved.</i>
  1328. <br>
  1329. This documentation and software is provided as-is.  We're using it, and we make backups of
  1330. critical data.  We recommend you do the same.
  1331.  
  1332. </body></html>
  1333.