(Last modified 2/19/98)
This document describes how to set up and use Apple NetFinder
software from Apple Computer. Apple NetFinder lets you build up a Web
site (or portion of a Web site) quickly and easily by sharing folders
or files much like you would using the file-sharing feature of the
Mac OS.
Apple NetFinder is a WebSTAR compatible acgi that runs on Mac OS-based servers. After you install and launch Apple NetFinder, your Web server can serve out selected directories and files from mounted volumes and display to users a graphical interface similar to that of a Finder window, regardless of a userÕs type of Web browser. The contents of one folder are displayed at a time (similar to FTP), organized as sortable columns of data. These columns are: Name, Size, Kind, and Date depending on the language of the server's operating system. The number of items in the current directory (visible to the user) are also shown.
System: You need a PowerPC Macintosh or Mac OS computer with System version 7.5.3 or later, and a Web Server that supports WebSTAR's cgi standard.
The following instructions assume you have already installed and set up your MacOS internet server.
To install the Apple NetFinder software, place the ÒNetFinderÓ folder in a folder that can be accessed from your web server. When you first launch Apple NetFinder, it creates any necessary folders and displays a software license agreement. After dismissing the license agreement screen you can either edit the preferences or continue setting up Apple NetFinder (described later in this document).
The following folders are created automatically inside the NetFinder folder:
NetFinder_Top_Level - The contents of this folder is what Apple NetFinder displays when you call the acgi from a Web browser. Place folders, files, and aliases in this root-level folder. (If you would like, you can also use an alias as the top-level folder. Remove the ÒNetFinder_Top_LevelÓ folder and drag an alias of another volume or folder in its place and rename the alias ÒNetFinder_Top_LevelÓ.) It is important that the folder has the name "NetFinder_Top_Level". If you want users to see another name for this folder, see the option for changing this in the Preferences Dialog below.
IMPORTANT You must remember to set the access privileges of this folder and its contents to those that wish your users to see if you are using the Users & Groups permissions model. If you are using an alias as the top level, you must set the privileges on both the folder containing the alias and the resolved folder.
Volumes To Search - Put in this folder an alias to any volume you want to be able to search. Apple NetFinder will ONLY search on volumes specified inside this folder and will only display items that the user in question has User and Groups access to. Searches will be done on the ENTIRE volume (not on a particular folder) as NetFinder is using a volume Catalog search like Find File.
IMPORTANT Don't allow searches over the network to remote volumes searches over the network are slow and consume a lot of processing time. In order to protect your folders/files make sure you have your file sharing privileges set properly! When running without file sharing privileges, placing a volume alias here can give the user access to your ENTIRE volume. Use with care.
Graphics - This folder should contain GIFs that Apple NetFinder needs to display certain content types (such as folder icons, GIF icons, and so forth). A few basic default GIFs are created. Apple NetFinder will generate new ones on the fly, each one inside a folder whose name is the same as the first letter of the GIF file(s). For example, a "ttxtTEXT.GIF" file would be in the folder named "T." If this folder is missing when Apple NetFinder is launched, Apple NetFinder will create it with the needed default GIFs.
NOTE If your files aren't showing up with the proper document icon, but with a generic icon instead, make sure you have the application which created it on a mounted volume at the time NetFinder is generating the folder listing. netFinder will look for the application and read out the icon at this time. Once the cached icon file has been created, it is no longer necessary to have the application available.
Log Folder - This folder is where Apple NetFinder will create log files (named as the date), with the contents of the log window appended to this file.
Item Tracker Folder - This folder is where Apple NetFinder will create Item Tracker files (named as the date), and the information that appears in the Item Tracker Window will be saved here. This basically keeps track of the number of times each folder or file is entered or downloaded.
IMPORTANT All of the above folders are created automatically when you launch Apple NetFinder. Do NOT rename these, as Apple NetFinder expects them to have these names. It will create new copies if it doesnÕt see them.
To access Apple NetFinder from a URL, type the HTTP path ending in ÒNetFinder.acgiÓ. This will start up Apple NetFinder and return the root folderÕs contents to the user.
Apple NetFinder creates unique URLs that will point it to the
folder/file the user is interested in. To create a hard html link to
a NetFinder subfolder you can use one of the following sorting
options: NFbyName:, NFbySize:, NFbyKind:, and NFbyDate:. Follow these
labels with the path using the following syntax:
<http://www.yourServer.com/NetFinder/NetFinder.acgi$NFbyDate:/NetFinder_Top_Level/BinaryFiles/MacOS/>
"$NFbyDate:" follows the acgi name (for a view sorted by date) and
then the folder name or forward slash delimited path. You may want to
utilize this feature to enable multiple entry points to your system.
The Apple NetFinder application has a default top-level folder. The site administrator places files/folders/aliases inside this folder. The user is shown the contents of this folder with the initial call to the acgi.
IMPORTANT A current limitation of WebSTAR 1.x servers (not 2.0 and greater) is that they convert name and password strings to all uppercase; while the name is not a problem, the passwords in the Users and Groups setup are case sensitive and should all be uppercase, or all lowercase!
IMPORTANT Also make sure that you set your personal FileSharing / AppleShare privileges for all the content you want your users to access. This includes the folder "NetFinder_Top_Level".
Apple NetFinder supports the Users and Groups scheme of Mac OS file sharing and AppleShare and has two levels of access restrictions:
IMPORTANT By selecting this option, you are by passing NetFinders Users and Groups security. If you have searching enabled, you allow potential access to all data on the searchable volumes!
Apple NetFinder will utilize the Users & Groups data on your server to control permissions access to your server's data. Apple NetFinder will display the contents of a folder according to the File Sharing privileges associated with that folder. Sub folders that are not accessable will be shown with a locked folder icon which if clicked on will prompt the user with a username/password dialog (if the Make locked folders invisible checkbox isn't checked). To require users to input a name and password initially, make sure that the NetFinder_Top_Level folder doesn't have everyone access to it.
IMPORTANT Even though Apple NetFinder will not allow unauthorized access to files/folders through its interface, a user can bypass Apple NetFinder by typing in a direct URL path to a file s/he wishes to view/download. Enhanced security is possible by running Apple NetFinder in conjunction with other security programs/features. Some servers have this feature built in (AppleShare IP, Apple Personal WebServer all using Users and Groups permissions, while other servers use Realms for security). You also have the option of running third party addons or cgis (like Maxum's WebLock cgi).
Making Locked Folders Invisible By default, Apple NetFinder will show unaccessible folders as locked folders to the user. By clicking on them, the user will be presented with a name/password dialog asking for authorization. If you wish to hide these inaccessible folders (either to make a folder listing less cluttured for the user, or for better security) just select the "Make Locked Folders Invisible" option in your Preferences Dialog.
Allowing Users To Change Passwords If this item is selected in your Preferences Dialog, users with the "allow user to change password" item checked in your Users and Groups file for that user, will be able to change their password on your server via the web. After a user has logged in, s/he will see a link in their NetFinder Toolbar (if you select to have it shown) that says "Change Password". As with the other Toolbar labels, you can change the text to represent your style or language.
IMPORTANT Password changes made via NetFinder are sent over the net as clear text. Anyone who is watching data stream by can see the user name and password exchange. If security is critical, do not use this feature. Regular names and passwords are munged between browsers and servers but are also viewable and breakable by someone watching the data stream by.
You can customize the look and feel of your Apple NetFinder pages by creating text files that html tags in them that Apple NetFinder will insert into its own html generation. For each of the options below (except for the Folder Listing Override and Search Listing Override) you have two ways to implement these features. The first option is to create the file and place it in the same folder as the NetFinder.acgi application. In this location, the custom file will become the default header or footer where applicable. If you place the file inside a particular folder, NetFinder will override any default file (if applicable) and use it for this folder.
By adding "folder_header.html" and/or "folder_footer.html" file(s) to the folder where your Apple NetFinder.acgi program resides, Apple NetFinder will read the contents of these files and put the text before and after the folder listing. In addition, you can create these files and have them appear on a folder by folder basis. If one of these files resides in a subfolder, Apple NetFinder will use it to override any default header or footer files you might have at the NetFinder.acgi level.
By adding "text_header.html" and/or "text_footer.html", Apple NetFinder will read the contents and add the them to the beginning and/or end of any Simple Text document that Apple NetFinder translates into html. You can use this to display graphics, provide your own tool bar, provide a link to your top level web page, or whatever else you choose to make your site better. As above, you can also put these files in particular folders.
You can override Apple NetFinder's display of a folder listing by adding your own "html.html" or "index.hmtl" file in any folder. When Apple NetFinder is asked to display a folder that contains a "html.html" or "index.html" file, it will display this file instead.
NOTE This file only works on folder by folder basis, there is no default.
This feature works the same as the Folder Listing Override option, but can only be used globally (place the file "search_header.html" and/or "search_folder.html" in the same folder as the NetFinder.acgi application. NetFinder will use the contents of these files and add them to beginning or end of the body of text it generates as appropriate.
If you wish, you can modify the way NetFinder displays its search results as follows: Place a file named "nfsearch.html" in the same folder with items you are interested in having overridden in a resulting search query. During a search, for each item that NetFinder is to return, NetFinder will look for a "nfsearch.html" file residing in the same folder. If this file exists, and NetFinder hasn't already included it in the search listing, NetFinder read the contents of this file and place it in the html it generates.
NOTE If you wish to have the contents of this file show up in the search listing order, you must add "<TD>" at the beginning and "</TD>" at the end of the file (assuming you have the Use Tables option selected in the preferences dialog).
NOTE This file only works on folder by folder basis, there is no default.
If the user wishes to override the
command (NetFinder currently defaults to ), s/he just needs to create a text file with the html text they want to use. This file must be named ".html" (or lowercase) and placed in the same folder as the NetFinder.acgi application.NOTE This file only works when placed in the folder containing the NetFinder.acgi application.
If the user wishes to override the
command (NetFinder currently creates the <Title> command automatically to represent the file/folder name), then s/he can create a file named "<HEAD>.html" with the <HEAD>...</HEAD> content (the closing </HEAD> command is neccessary in this case).NOTE This file only works when placed in the folder containing the NetFinder.acgi application.
IMPORTANT
You do NOT want to have any of the following tags in your header or
footer files:
"<html>" "<TITLE>" "</TITLE>" "<BODY>"
"</BODY>" "</html>" as NetFinder is already generating
these tags and placing your html text in the appropriate places. By
adding your own tag, you can cause unpredictable behavior for
your users as browsers don't tend to like more than one of these and
can easily get confused.
NOTE The process of converting SimpleText into html is processor intensive and can be uncomfortably long for large documents.
With this item checked, NetFinder will automatically binhex files that are not already covered by your MIME type settings, cache them in a temporary storage folder and sent to the client with the binhex suffix.. If the server doesn't support WebSTAR's apple event for delivering the MIME type settings, NetFinder will check against its own default list of file types (see below). If you are serving a lot of cross-platform items, be aware that binhex is pretty much a MacOS only format that takes both the resource and data forks of a file and converts it into text. Non MacOS browsers usually don't know what to do with binhexed files.
'TEXT': // text 'BlWd': // text 'ttro': // text - read only 'GIFf': // gif 'JPEG': // jpeg 'PICT': // pict 'MOOV': // quicktime movie 'MooV': // quicktime movie 'MPEG': // mpeg 'WDBN': // word document 'XLS3': // excel document 'XLS4': // excel document 'XCEL': // excel 'SITD': // stuffed doc 'PDF ': // pdf format 'PNRA': // real audio format 'MD93': // director 'BOBO': // clarisworks 'MWPR': // MacWritePro 'FMP3': // FileMakerPro 'dPro': // MacDrawPro 'MSWD': // msword 'MSWK': // msworks 'PDF ': // pdf 'PNst': // pn-realaudio 'TVOD': // MoviePlayer
NOTE Searches will be done on the ENTIRE volume (not on a particular folder) as NetFinder is using a volume Catalog search like Find File.
Column names are derived from the FinderÕs resource. They will be in the same language as the operating system of the server.
Icons displayed
MacOS Character Set Conversion to ISO-8859-1 The character set of MacOS computers is different than other platforms. Thus normally if you have a MacOS server and a text file has a bullet in it, a viewer on a Windows platform would see it as a Yen symbol. NetFinder has the abiltity to automatically translate non-html SimpleText files from the MacRoman script system into the ISO-8859-1 (Latin1) system. This translation will only take place for non-mac clients.
There are two different ways to access Admin data from NetFinder, from the running application itself, or via the web.
Under the "Stats" menu in NetFinder, there are three options:
The Zero Totals option allows the user to reset the Item Tracker Info Data in NetFinder to the present time and day.
The NetFinder Log Window contains a history of user connections since NetFinder was last launched. In the top section of this window is displayed the following: the time NetFinder was last launched, number of SimpleText files read (Files Read), number of files binhexed (Files Downloaded) and the current available memory.
This window only holds 32k bytes of info and will reset when it goes over this limit. All the Log Data is also stored in a log file named by the date. These files reside in the Log Folder
The NetFinder Item Tracker Window shows a listing of three types of items: folders entered, files binhexed, and SimpleText files read. These are shown with both the number of times the file/folder was hit today as well as the number of times it was hit since the last time you zeroed your Item Tracker Data
If you are logged into NetFinder as the superuser (owner) of the server, a link to the Admin Page will appear at the bottom of each page. If you aren't logged in as the owner, or you have Everyone Access enabled, you can still get to the Admin Page via the URL:
<http://your.server.com/netfinder/path/netfinder.acgi$NFAdminRequest:>
This will take you to a page that looks similar to below:
From here you can edit your Preferences, see your Item Tracker Data, see the current Log Window, or get some System Info.
The Web Based Item Tracker Data Window shows the same content as NetFinder's Item Tracker Window on the server, but with the content converted to an html table. (see below)
The Web Based Log Window also shows the same data as its server counter part, but as with the Item Tracker Data, it gets formatted into html.
The System Info Window doesn't have a server counter part and gives information about: What version of NetFinder is running, when NetFinder was last launched, available memory, number of SimpleText Documents read, and the number of binhexed files downloaded.
Shown below are screen shots from the server's Preferences Dialog. The same information can be edited via the web, but the contents will be in html and look different.
When a user accesses a folder in NetFinder, they are shown the folder name at the top of the browser window. If you would like to have the user see something other that "NetFinder_Top_Level" when they first enter NetFinder, change the Top Level Folder Title in this window.
You can also turn on/off various NetFinder functionalities that have to do with the display of information to your user.
The "Use Tables in folder listings" checkbox allows you to turn of table generation of folder listings. This can be helpful if you are displaying folders with hundreds of items and wish to display the information quicker.
By turning on the "Use Finder 'Get Info' Comment Info" option, users will be able to read any comments you have entered in a file/folder's get info dialog. If a file/folder has a comment associated with it, NetFinder will generate an info icon next to the file/folder graphic which when clicked on, will display the file/folder's comments. This can be especially helpful for a download folder where the name of the file just isn't enough information to tell the user what it is. By using the file's comment field, you don't have to create a separate readme document for each file.
You can also turn on/off the display of the toolbar at the bottom of the folder listing that NetFinder generates. This will not affect the "Change Password" or "Admin Page" labels.
If you wish to control the default sorting behavior of NetFinder by having it use the same sorting as the Finder, check the "Use Finder Default Sort Order" box. This will cause folders to be displayed in the same sorting order as in the Finder. If this option is not selected, Apple NetFinder will use as a default the last sort order the user selected.
NOTE If you change the sort order of a folder in the Finder, the change may not be seen by NetFinder right away. You can force the Finder to update by selecting "Get Info" for the folder, or by closing it.
If you wish, you can change the labels that show up in the NetFinder toolbar. This is handy if you have NetFinder running on a non-English system.
This is where you select whether you want to use Users and Groups access to control access to your server. If you select "Use File Sharing to control user access", you can choose to make locked folders invisible and allow users to change their password via the web. (See Security)
This is where you can change some of the behavior of NetFinder:
Selecting this option will make NetFinder remove all cached binhex files from the BinHexCacheFolder when NetFinder lanches and quits. Turn this option off if you wish NetFinder to keep its cached files around between launches.
Apple NetFinder uses its own file caching scheme to save the generated html from directory listings and SimpleText conversions. This caching can dramatically speed up a users viewing experience, especially with large documents or directories with many files. If you wish to disable this option, set the cache value to 0.
If you select this option, NetFinder will execute locally any AppleScript document when the script is selected through the web browser. This can be helpful if you have automated tasks that you like to perform on you server but wish you could start them remotely.
This will cause Apple NetFinder to use the server address that it receives from the server. Choose this option if you want to create a round robin mirroring scheme where each user gets passed off to a different Apple NetFinder Server. Once the user is accessing data from a particular Apple NetFinder machine, the links are created specifically for that machine (and Apple NetFinder saves state for each user during that session). If you allow users to search your site, Apple NetFinder will automatically generate these reverse links.
You can choose to have Apple NetFinder automatically quit after a certain amount of idle time. This may be useful to you if you have a number of different server applications/cgis and your traffic is low. Apple NetFinder will get automatically launched by your server if a user requests it by URL.
This options utilizes the abiltiy to explicitly use the font's in your SimpleText document. If the browser's machine doesn't have the font, the browser will substitute its own.
To increase your performance and heighten user experience, try limiting the number of items in any one folder. Having large numbers of items in a folder not only takes longer for NetFinder to process, but the html that NetFinder generates also becomes larger. This can affect user experience as they will have to wait for the extra data to download to their browser. Also, having lots of items makes it harder for a user to find what s/he is looking for. If you are finding this to be the case, break up your folder content into sub folders.
You can add helpful hints about the contents of folders and files by adding comments to them. This is done in the Finder by selecting the item and selecting "Get Info" from the "File" menu. NetFinder will display this item in the listing with an info icon next to the folder/file's icon. This can be an easy way to give small descriptions without cluttering up your folder listing with small "ReadMe" files.
NetFinder tries to utilize the icon for a particular file that is specified by the application that created it. If NetFinder can't find this information (creator application isn't available or doesn't have the small icon defined), it will use the generic document icon from the system. When NetFinder is able to locate an icon for a document, it converts it to the gif format and saves it in the "Graphics" folder. Icon file names are based on the creator and filetype and are stored in a subfolder that starts with the first letter of the creator. For example, a SimpleText document would generate an icon named 'ttxtTEXT.GIF' for a text document, and 'ttxtttro.GIF' for a ReadOnly text document. Both of these files would be stored in the sub folder named 'T'.
I'm searching a HFS+ volume using NetFinder, why do I get inconsistent results?
There seems to be a bug in doing searches on HFS+ volumes via NetFinder. Using HFS formatted volumes is recommended.
How come when I look at a folder through NetFinder, some of my documents have generic icons?
You need to make sure that you have the application that created the document on a mounted volume at the time you look at the listing of the document with NetFinder. If this isn't the case, then the application probably doesn't have a small icon version for this document type.
How can I get NetFinder to stop binhexing certain files?
One way to stop NetFinder from binhexing a file is to turn off auto binhexing from the Preferences Dialog. However, this will turn off ALL binhexing and may not be what you intended. (SeeAuto File Binhexing for more info).
When I try to download a file, I get the following message: "WebSTAR Auto binhex, Sorry. Permission to binhex this type of file is denied." How do I fix this?
There can be some conflicts between the WebSTAR AutoBinhex plugin and NetFinder's AutoBinhex feature. I recommend either removing the plugin or turning off NetFinder's Auto Binhexing (See Auto File Binhexing for more info). You also want to make sure that you have a suffix mapping for .hqx that maps to application/mac-binhex40.
In what ways can I increase performance?
There are a number of ways to speed things up:
a) Utilize the page caching scheme in NetFinder (set by default to 10 Mb)
b) Break up folders with large numbers of items into smaller folders
c) Close NetFinder windows (or put NetFinder in the background)
d) Give NetFinder more RAM via the Get Info menu in the Finder
I seem to be getting a lot of timeouts when connecting to my server via NetFinder. How can I fix this?
There are a couple of things that might help:
a) Set the timeout value for your server to a larger number
b) Give NetFinder more RAM via the Get Info menu in the Finder
My banner graphics are broken when I try to use the folder_header command. How do I fix this?
Make sure that you are either using full paths for your src tag (e.g. <http://your.server.com /folder/graphics/mygrapic.gif>) or that you are using a path relative to the same folder that your NetFinder application resides in. NetFinder can't support a relative path from a particular folder since browsers set the current folder to be where the acgi application resides.
When I type in a password that is mixed upper and lower case, NetFinder won't authenticate me. What's going on?
Some servers force the password to all uppercase or all lowercase characters when they send the information to a cgi. This is a known problem in WebSTAR 1.X and MacHTTP, but has been fixed in WebSTAR 2.X servers.
When I try to access a folder with hundreds of items in it, my machine will sometimes crash
If you are not using WebSTAR or AppleShare IP 5.0, NetFinder is forced to send all of its generated data via a single Apple Event. This data can be a couple of hundred K if you have a folder with a large number of items in it. Both WebSTAR and AppleShare IP have the ability to handle NetFinder's response in smaller chunks. You might want to either use one of these servers or break your folder content into smaller chunks.
How do I add a search form to my website like you guys did on your NetFinder server?
See the section on Searching
I've added a search form to my folder_header file, but all my search results turn up with zero hits!
Make sure you've added an alias of all the volumes you want searched to your "Volumes To Search" Folder.
I'm now getting search results, but the files won't resolve. I keep getting a file not found error!
You must make sure that you have aliases to the mounted volume you want searched and not a lower level folder.
After a search, I'm getting hits on stuff that my users shouldn't be able to see!
Make sure you are setting the sharing privileges correctly. NetFinder will show any items that match the search criteria if it is in a folder that the user has access to.
How come when I access certain folders, instead of getting a folder listing like I want, I get the contents of my "index.html" file?
Both "index.html" and "html.html" are special files. See the section on Folder Listing Overrides.
© 1996 - 1997 Apple Computer, Inc. All
rights reserved.
Mac and the Mac OS logo are trademarks of Apple Computer, Inc. used
under license.