Sunfish

Blackbanded Sunfish, Enneacanthus chaetodon
A 30-60mm long fish with a very compressed, deep body, a thin pointed pectoral fin and round tail fin. Habitat: swamps, ponds and river pools.

Sunfish
An NFS client, implemented as an image filing system. Habitat: RISC OS.

Contents

License

Sunfish is copyright © 2003 Alex Waugh

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Requirements

Sunfish requires a working network connection and an NFS server to connect to. The server should be running version 2 of the NFS protocol, version 1 of the Mount protocol, version 2 of the portmapper protocol, and optionally version 2 of the pcnfsd protocol. It has currently only been tested with the Linux kernel server present in Debian Woody, but it should work with other servers. Only UDP connections are supported at present.

Sunfish should run on RISC OS 3.11 or later, but has only been tested on RISC OS 5 at present. It is 26/32bit neutral.

Setting up a mount

Sunfish is implemented as an image filing system. Currently you have to setup a mount file by hand, but in future versions a frontend may be supplied.

Ensure the Sunfish module is loaded by double clicking on !Sunfish. Then, using your favorite text editor create a file with the appropriate options as described below. Save this, then set it's filetype to Sunfish (&1b6). The double click on the mount file you have just created and the server will be mounted and you can navigate the filesystem as normal.

Example mount files

This is a very simple mount file. It will use pcnfsd to map the username and password onto a uid and gid. 

Protocol: NFS2
Server: mint.cp15.org
Export: /home/ajw498
Username: ajw498
Password: fiddlesticks

The same as above, but specifying the uid and gid explicitly. pcnfsd is not required in this case, and there is no need for the password to be stored in the file either. 

Protocol: NFS2
Server: mint.cp15.org
Export: /home/ajw498
UID: 1001
GID: 50

A more complex example. 

Protocol: NFS2
Server: mint.cp15.org
Export: /tmp
UID: 1002
GID: 51
GIDs: 52 53 105
umask: 066
MachineName: caramel
ShowHidden: 0
Timeout: 5
Retries: 0
DefaultFiletype: FFF
AddExt: 2

Options

Any line beginning with a # is treated as a comment.

Mandatory options

These options must appear in the file for a working connection to be established. Either a uid and gid must be specified or a username and password.

Protocol

Specifies the protocol to use. An error will be generated in the current version if this is not NFS2.

Server

The domain name or ip address of the NFS server.

Export

The name of the exported directory to mount. This should match one of the entries in /etc/exports or equivalent on the server.

UID

The user id to use. If this is not specified, then a username and password should be specified instead.

GID

The group id to use. If this is not specified, then a username and password should be specified instead.

Username

The username to connect as. If specified, then pcnfsd will be used to map the username and password to a uid and gid. If not specified, or pcnfsd is not available, then the uid and gid should be specified instead.

Password

The password to give to pcnfsd with the username. This password has to be stored in the file in plain text, so if that is a concern then you should specify the uid/gid instead.

Optional options

These options can be specified if needed, but if they are not then default values will be used. For most connections, the defaults will be sufficient.

MachineName

The name of the machine the client is running on. Some servers may use it to allow or deny access. If ommitted, it defaults to the value of <Inet$Hostname> which should be sufficient in most cases.

PortMapperPort

The port number to use for the portmapper service. If omitted, it defaults to the assigned number 111.

MountPort

The port number to use for the mount service. If omitted, the portmapper service will be used to find the correct port.

NFSPort

The port number to use for NFS. If omitted, the portmapper service will be used to find the correct port.

PCNFSDPort

The port number to use for PCNFSD. If omitted, the portmapper service will be used to find the correct port.

GIDs

A list of additional group ids that the user is part of. There can be up to 16 gids in the list, separated by whitespace. If pcnfsd is used then the list returned by that will override this setting.

Logging

If set to 1 then all operations will be reported to syslog. This should only be enabled for debugging, as it significantly slows things down. Note: if one connection specifies logging, then activity on all connections will be logged while that connection is mounted.

umask

The umask to use, specified in octal. All operations that modify a files attributes will have the Unix mode bits modifed according to the umask. If not specified, it defaults to 022. If pcnfsd is used then the umask returned by that will override this setting.

ShowHidden

If set to 1, all files will be shown, if set to 0 then all files beginning with a . will be hidden from filer views. If not specified, then defaults to 1.

Timeout

The time in seconds to wait for a reply from the server before retrying or giving up. Defaults to 3 seconds.

Retries

The number of times to resend a request if no reply is recieved. Defaults to 2 retries.

DefaultFiletype

The hexadecimal filetype to give a file if it doesn't have an ,xyz extension or a . extension that matches a mimemap entry. If not specified then it defaults to FFF.

AddExt

Controls adding of a ,xyz extension. When 0, no ,xyz extensions are added, and all files get the default filetype. When 1, a ,xyz extension is only added when necessary. If the file has a . extension that matches a mimemap entry then no extension is added. When 2, a ,xyz extension is always added. If not specified, the default is 1.

Reporting Bugs

If you discover a bug, please report it to me, or better still fix it yourself and send me a patch. When reporting a bug, first load syslog, then set the logging option before doing the operation that triggers the bug. If you have access to a machine that can run ethereal then it would be very useful to use that to save a dump of the network traffic along with the syslog file, a description of the problem and exactly what operation you were doing to trigger the bug. Also details of what OS and NFS version the server is running would be helpful, and the version of the Sunfish module and RISC OS version.

Known Bugs

The leafname returned from an OS_File 0 call will be in Unix format and may still have a ,xyz extension. This is only used for printing *opt 1 info so is not crucial. The PRMs state that *opt 1 may not work correctly on RISC OS 3 onwards anyway.

Wildcards in filenames are not supported. This would be a lot of hassle to implement for little benefit, and in any case I believe that it really should be fileswitch's job to sort out wildcards, not each and every filing system.

Some operations are not as fast as they could be. For the first release I have concentrated on getting a functional and stable program, and there are some places where performance could be improved in the future. In particular, file attributes and mappings between filenames and NFS file handles should be cached, as this would reduce network traffic and delay for directory listings and many other operations. Also read and write requests should be pipelined to remove the latency between blocks, which should speed up reading and writing large files.

Recompiling

Full source code is provided. To recompile the module, you will need Norcroft v5.53 or later, cmhg 5.42 or later, TCPIPLibs, and Perl. Earlier 26bit versions of Norcroft will not work because the code makes use of 64bit integers and some C99 functions.

For some unknown reason, if you use amu then it will give an error AMU: Don't know how to make 'o.pcnfsd-calls' after generating pcnfsd-calls.c, but if you rerun amu then it will work. GNU make does not give this problem.