1. About
-------------------------------------------------------------------------
Fitz is a lightweight, cross-platform, symmetric network file server and
mounter for Amiga and Unix-like systems (Linux, FreeBSD, macOS, ...).
No configuration files, no daemons, no hassle - just a single command
line program for sharing and mounting directories ad-hoc style. For
Amiga, a GUI prefs program is included.
Fitz goes both ways: You can share and mount - on all platforms, both
directions are supported. You can share Amiga directories with other
Amigas, or mount them under Unix. You can run as many instances as you
like. There is no central server.
Fitz supports Amiga case-insensitive filenames, permission bits and
comments, not only when serving from an Amiga, but from Unix servers as
well. Support is provided through xattrs, and the required capabilities
are detected and negotiated with clients at runtime.
Fitz is MIT licensed, full source code included.
More recent versions may be found at http://home.sm41.de/projects/fitz
Check it out with: $ hg clone http://home.sm41.de/projects/fitz
2. Example use
-------------------------------------------------------------------------
Assume you have three computers in your network, the Amigas named atze
and keule, and the Linux machine lotte:
keule # fitz serve RAM:
atze # fitz mount keule KEULE:
lotte $ mkdir ~/keule
lotte $ fitz mount keule ~/keule
lotte $ mkdir ~/shared
lotte $ fitz serve ~/shared
atze # fitz mount lotte LOTTE:
keule # fitz mount lotte LOTTE:
You can also share and mount based on symbolic service names, which are
automatically promoted inside your local network. In the following
example, not a single hostname or IP address is needed:
keule # fitz serve RAM:T service temp
lotte $ fitz serve ~/data service data
atze # fitz mount :/temp TEMP:
atze # fitz mount :/data DATA:
You may give the FitzCtrl utility a try, which allows you to administer
Fitz shares and mounts with a graphical user interface on the Amiga. For
getting started, you would just click 'Add Server' on one Amiga, start
FitzCtrl on another, double click on the listed share, and be connected.
3. Requirements
-------------------------------------------------------------------------
Amiga: OS >= v37, bsdsocket.library v3, 68000 CPU, system locale (v38)
supported.
Recommended: Proper network setup including fully qualified hostname,
name resolution, and system time. See also notes on system time, which
explains how to acquire system time via network, accounting for Daylight
Saving Time (DST) on an Amiga.
POSIX/FUSE, build requirements:
gcc or clang, FUSE3 library and headers (libfuse3-dev/fuse3-devel),
pthreads. Use macFUSE on macOS. If your OS does not support FUSE for
mounting, you may still try running the server, as it is largely POSIX
compliant. If your OS or filesystem does not provide xattrs, then the
server can still run and just deny clients certain capabilities.
4. Build and install
-------------------------------------------------------------------------
On Amiga:
# copy fitz C:
Fitz is reentrant and can be made resident:
# protect C:fitz p add
# resident C:fitz
On macOS install macFUSE:
$ brew install macfuse
On Unixoid Fitz goes to /usr/local/bin:
$ make all
$ sudo make install
Building for Amiga requires vbcc or gcc13 (bebbo):
$ make amiga
Use 'make help' to see a list of targets.
5. Getting started
-------------------------------------------------------------------------
WARNING: If you invoke 'fitz serve', Fitz simply starts serving the
current directory - without authentication.
Make sure you don't expose a share on a host or network interface that
is reachable from untrusted networks, such as the internet. Typically it
is safe to use behind a home router which is also a NAT gateway.
1. Start by sharing an empty directory.
2. Copy the things to share into the shared directory. By default,
clients have no means to create links inside a share, and if you place
symbolic (or "soft") links in a share, the server follows them when they
are part of a path. (For full symlink support see 5. below.)
3. When there is no need for clients to write to a share, use the RO (or
READONLY) option, so data can't be devastated, not even by accident.
4. You can enable a thin layer of security by specifying ASKPASS in the
server command line. This will prompt you for a password, and clients
will be prompted for that password as well. Authentication by default
implies encryption. You can also specify ENCRYPT in the command lines of
either server or client, which will require encryption from the other
side - even without authentication. See also Encryption for more
details.
5. To allow clients to create and resolve links, start the server with
the LINKS option keyword. See Soft links for all details.
6. Share a directory
-------------------------------------------------------------------------
$ fitz serve [rootdir] [PORT num] [RO] [IFACE addr[:port]] [ASKPASS]
[SERVICE name] [ENCRYPT] [LINKS] ( [TZOFFS sec] )
rootdir defaults to the current directory.
PORT num defaults to 17711.
Keyword RO (or READONLY) rejects all write operations.
IFACE (or INTERFACE) binds to a specific address (e.g. 127.0.0.1), and
optionally a port number. If not specified, the server binds to all of
the machine's interfaces.
ASKPASS will prompt for a password that clients will be required to
specify as well. Successful authentication usually implies encryption.
SERVICE will give the service a name. With this option, several named
services can coexist without you to remember where they are located.
ENCRYPT will require encryption from clients.
LINKS offers symbolic links to clients. See Capability management for
more information.
TZOFFS (Amiga only) specifies a time zone offset in seconds. See also
notes on system time.
Examples:
$ fitz serve help get help on the serve command
$ fitz serve share current directory
$ fitz serve /home/shared share a specific directory
# fitz serve RAM: service ramdisk share RAM:, service name "ramdisk"
$ fitz serve /srv/pub port 8888 share on a different port
# fitz serve SYS:T RO TZOFFS 7200 read-only share, CEST (Amiga)
$ fitz serve iface 127.0.0.1:6666 localhost only, port 6666
# fitz serve df0: askpass serve df0:, with password
$ fitz serve encrypt require encryption from clients
7. Mount a share
-------------------------------------------------------------------------
# fitz mount service [VOLUME] [RO] [OH] [ENCRYPT] [TZOFFS sec] (Amiga)
$ fitz mount service mountpoint [RO] [OH] [ENCRYPT] [fuse-args] (Unix)
service can be hostname, host:port, hostname:/servicename, or just
:/servicename.
mountpoint (Unix only) must exist and should be an empty directory.
OH (or OMITHIDDEN) hides dot-files from listings (still accessible).
fuse-args are additional arguments passed to FUSE (Unix only).
ENCRYPT will require encryption - with or without password.
Examples:
# fitz mount hostname:/service RO mount to FITZ: read-only (Amiga)
# fitz mount :/data DATA: mount service :/data to DATA:
# fitz mount klappstulle NETZ: mount klappstulle to NETZ: (Amiga)
$ fitz mount 10.168.1.5:8888 ~/net mount 10.168.1.5:8888 to ~/net
$ fitz mount a1200 ~/net -f mount a1200, running in foreground
$ fitz mount NEED=unix server require the "unix" capability
# fitz mount someshare encrypt require encryption from the server
The client reconnects automatically if the server restarts; operations
block during reconnect and resume transparently (open files excepted).
Unmount on Unixoid:
$ umount ~/net
$ fusermount3 -u ~/net (if needed)
Unmount on Amiga:
press CTRL-C, or send the CTRL-C signal with the 'break' command. Use
'fitz query' to display the task numbers of named services.
See also System time, Amiga and general notes for more Amiga-specific
notes and options.
8. Service names and discovery
-------------------------------------------------------------------------
Fitz supports named services and a port-mapping facility. Instead of
running shares on distinct port numbers, you can give them names:
$ fitz serve dirname SERVICE homedir
# fitz serve RAM: SERVICE ramdisk
which will allow a client to mount by name instead of a port number:
# fitz mount hostname:/homedir
# fitz mount hostname:/ramdisk
In addition to that, you can mount services inside a LAN even without
knowing the hosts on which they are located - so you don't have to
specify their IP addresses or hostnames. When mounting, you can use the
notation :/servicename, which stands for 'on the local network':
# fitz mount :/homedir
# fitz mount :/ramdisk
Note, however, that automatic service discovery will only work inside
the same LAN segment, i.e. computers which are on the same switch or
bridge. If services are separated by a router (or VPN, etc.) then
automatic service discovery will probably not work; in that case however
you can still mount by hostname:/servicename.
With the 'query' command you can get a list of services currently
available in your local network, including their port numbers and the
process IDs (or task numbers) on the respective machine. For example:
$ fitz query
platin.intra.sm41.de (10.168.1.4):
tek 17721 10155
tmueller 17718 10147
data 17722 10151
netsys-a3000 17723 10159
a500.intra.sm41.de (10.168.1.36):
a500 17711 11
a500-ram 17712 12
NOTE: Fitz will not use the UDP broadcast mechanism if not told to do
so. If you are paranoid about 'flooding' your network with a UDP
broadcast per user session, just don't use the broadcast notation.
Instead, address a service with host:/service.
9. System time, Amiga and general notes
-------------------------------------------------------------------------
Amiga:
- Servers are usually carrying timestamps not in local time, but in UTC,
so Amiga system time needs to be normalised towards UTC when talking to
a Unix server.
Keep a correct Amiga system time by syncing with a NTP server in your
network startup script. If you are in a region without daylight saving,
Fitz will fall back to the Amiga system locale, and you are done.
To account for daylight saving time (DST), it's easiest and most
reliable to provide a 'TZ' env variable containing a POSIX time zone
format. Get this format string on most Unixoids with e.g.
strings /usr/share/zoneinfo/Europe/Berlin | tail -n 1
You would set this as the TZ variable on the Amiga like this:
setenv TZ "CET-1CEST,M3.5.0,M10.5.0/3"
copy ENV:TZ ENVARC:
And, after syncing towards UTC (or the realtime clock running in UTC),
run TZUtil (from Aminet) to change the system time according to TZ. Fitz
will use the TZ variable as well, and calculate the required offset
towards UTC when talking to a Unix server. See also the example below.
Alternatively, you can specify the offset towards UTC in seconds with
the 'TZOFFS' env variable (or command line argument), but you would have
to account for DST and calculate the offset yourself. For example,
TZOFFS for Berlin would be +2 hours in summer, that is 7200 seconds.
- A good place for setting up shares on an Amiga is your network startup
script. The following example uses FitzCtrl, assumes you have the TZ
variable set, and accounts for NTP and DST:
ntpsync -t10 -d0 pool.ntp.org ; sync towards UTC
wait 2 sec
tzutil
resident c:fitz ; requires the P bit set
SYS:Prefs/FitzCtrl start
- The FitzCtrl utility allows you to configure Fitz mounts and shares
with a graphical user interface, and it can launch them all at once in
your network startup script, or from WBStartup. See section FitzCtrl.
- Amiga clients can use the NOLEFTOUT/S option to completely hide the
.backdrop file, for hiding and rejecting left-out Workbench icons on
mounted shares.
General:
- Clients can use the TIMEOUT/N/K argument to specify the number of
seconds until a non-responsive server is considered gone and the mount
is getting dropped. Fitz features an elaborate timeout and reconnect
logic, with a conservative default of 60 seconds to help the chances of
reconnecting.
However this can be too long for shares whose drawers and icons are in
use by a desktop, especially with a server that - shall we say - may be
a bit prone to crashing. For instance, an unresponsive server can freeze
an Amiga Workbench until the mount in question terminates. For cases
such as this, use a shorter timeout period.
- OH (OMITHIDDEN) can give confusing results when recursively deleting
directories which are not empty due to invisible dot-files.
- Remember that on a Unix server, you will probably want to include
xattrs for backups and copies of directories shared with Amigas (e.g.
with cp, rsync, tar.)
10. Capability management
-------------------------------------------------------------------------
The protocols and defaults are adjusted in such way that things can be
expected to just work. For more insight and control over your mounted
filesystems, show a server's protocol and capabilities:
# fitz query host[:port]
# fitz query [host]:/service
With the arguments USE and NEED you can request server capabilities
opportunistically or strictly. For example, USE=amiga-case would use a
server's offer of Amiga-style case insensitive file names; the same with
NEED=amiga-case, but mounting would fail if the server cannot provide
the requested feature.
Amiga servers offer (and Amiga clients by default use)
"iso-8859-1,amiga-case,amiga-comment,amiga-flags". Unix servers offer
"unix,case,amiga-case" (and possibly a few more), and additionally
"amiga-comment,amiga-flags" (given the required support). Unix clients
by default use the capabilities "unix,case".
So by default Amiga clients get case-insensitive names, Amiga comments
and file flags even from Unix servers, provided that the server and
filesystem can support them - and fall back to 'Unix-like' verbatim
filenames and no support for comments and special Amiga flags. If you
strictly require them, you would specify
NEED=amiga-case,amiga-comment,amiga-flags.
Unix servers and clients talk to each other in a pretty standard way,
except for that chown and chgrp are not supported by the protocol.
Symbolic or "soft" links
A server started with the LINKS option additionally offers the
capabilities "symlink,nofollow". Amiga clients use them by default, and
then see the server's links as AmigaDOS soft links. They are listed as
links, resolved on the Amiga, and can be created with MakeLink(). With
"nofollow", the server never follows links on its own, so nothing can be
created or overwritten through a dangling link.
Links to other volumes, like SYS:C, are kept verbatim. They resolve on
each Amiga individually, and are dangling for Unix. Links to the mounted
volume itself are stored relative. Normally, relative links should be
preferred, as they work on all sides.
Unix clients see symlinks as such if the "symlink" capability is
negotiated. Absolute Unix links and links leading out of the share are
dangling for Amiga clients.
An Amiga server stores links as AmigaDOS soft links. It requires a
filesystem that supports them, e.g. PFS3. (Amiga FastFileSystem is said
to support them reliably in later versions.) Absolute links into the
share are presented to clients as relative links; absolute links to
anywhere else are presented verbatim, i.e. they resolve on the client.
Absolute Unix links cannot be created on an Amiga server.
A prominent Amiga use case is to allow for icons representing network
drawers on the Workbench, with individual looks and placement on every
Amiga mounting them. To create such a link to an Amiga icon on Unix, you
can write e.g. $ ln -s SYS:Prefs/presets/def_home.info Disk.info
11. Encryption
-------------------------------------------------------------------------
1. By default, connections are NOT authenticated and NOT encrypted.
2. Authentication by default implies encryption of the data stream.
3. The data stream can also be encrypted opportunistically, without
prior authentication.
4. Default encryption is rather solid - but it can be prohibitively slow
on a 7MHz 68000.
5. You can request a weaker than the default cipher - which might be
sufficient to obfuscate the data on the network for casual attackers.
The strongest cipher is speck64-27, the weakest is speck64-5.
6. Weaker ciphers do not mean weaker authentication.
7. You can also specify NOCRYPT (or cipher=none), in which case the data
stream is unencrypted even with prior authentication.
Authentication is BLAKE2-MAC, and stream cipher is SPECK64 big endian.
Of course this unusual combination is geared towards slow Amigas. "So
the NSA will be able to read my traffic?", you may ask. The answer is:
Yes, most probably, and SPECK64 is but one of the many reasons.
Weren't it for its shady origins, SPECK encryption would look pretty
solid. But if you mistrust it - and you have every reason to - then
don't use it, as it also degrades performance. Ensure security by not
exposing Fitz to untrusted networks. The original idea was to obfuscate
the traffic rather than to encrypt it by modern standards - so it won't
get picked up with packet sniffing too easily.
Use the ENCRYPT keyword to make sure that the traffic will be encrypted.
Clients, if required to encrypt, will pick the first from the server's
list of possible ciphers. Use CIPHER=name to choose another.
Here are some examples:
$ fitz serve nocrypt deny clients encryption
$ fitz serve askpass prompt server (and clients) for password
$ fitz serve encrypt require encryption from clients
# fitz mount encrypt require encryption from server
$ fitz serve password xxx use the given password as the secret
# fitz mount pw xxx use the given password as the secret
$ fitz serve secret filename use secret from file (max. 1024 bytes)
# fitz mount secret filename use secret from file (max. 1024 bytes)
Get a list of ciphers offered by a server with the 'query' command. You
can change the list of ciphers offered to clients:
$ fitz serve cipher=speck64-27,speck64-11 ...
Clients are still free to use no encryption at all - use the 'encrypt'
keyword at the server to enforce it:
$ fitz serve encrypt cipher=speck64-27,...
Clients can also choose one from the offered ciphers:
$ fitz mount cipher=speck64-11 ...
12. FitzCtrl
-------------------------------------------------------------------------
FitzCtrl is a combined GUI and command line program to comfortably
administer Fitz network mounts and shares on an Amiga. FitzCtrl depends
on Fitz and is an optional front-end.
FitzCtrl should be used only when the network is configured properly,
otherwise it can give confusing results. See also requirements and
installation.
Copy FitzCtrl (with icon) wherever you want. SYS:Prefs is a good
default.
If you want FitzCtrl to bring up your network shares according to your
configuration, add the following lines to your network startup script:
resident c:fitz
sys:prefs/fitzctrl start
See also full network startup example.
Alternatively, you can drag FitzCtrl to the WBStartup drawer for the
same purpose. In the icon tooltypes, set STARTGROUP to the group of
shares you want to bring up at start: auto, user, all, or none. Set
CX_POPUP=NO to start it in the background, without opening the main
window. When hidden, you can also find FitzCtrl in the Workbench tool
menu.
When FitzCtrl is started without arguments, you will be shown a list of
network shares found in your local network.
Click 'Add Server' to share a directory on your Amiga, so that it can be
found and mounted on other computers on your LAN.
With a double-click on a list entry or by clicking 'Start' you can mount
or start serving a share.
With the 'Edit' button you can configure mounts persistently. In the
configuration window you can control the volume name, encryption and
ciphers, as well as the options 'Readonly', 'Hide Dot Files', 'No
Left-out Icons' and timeout.
With the 'Add Mount' button you can create new entries for shares which
do not have a service name, and so are not broadcasted and cannot be
detected automatically - these have the notation hostname:portnumber. Or
you can add shares which are not found because they are behind a router
in a different network, with the notation hostname:/servicename.
Finally, you can put mounts and shares into a 'Start group', so entries
in the respective group can be brought up all at once. With
# fitzctrl start
# fitzctrl start user
# fitzctrl start all
you would bring up all mounts in the 'auto', 'user', or both groups. The
same works with the command 'stop'.
In the command line, you can also specify these options:
- GUI/S if you want to start/stop services, and then open the GUI
anyway.
- NOASKPASS/S to make sure that FitzCtrl won't prompt for a password in
scripts, and so stays non-interactive.
- NOREQ/S to make sure that no requester will be opened to prompt for a
password. If a password is required, it will be prompted in the
terminal.
If you don't want to be bothered with entering passwords, you can save
them in the configuration. However, passwords in the FitzCtrl
configuration file, ENVARC:fitzctrl.conf, are plain text, unencrypted.
So if you don't want to expose them, leave the password field empty. In
that case you will be prompted for the password if one is required.
13. Rationale
-------------------------------------------------------------------------
Created for lack of a better tool.
Samba: The smbfs mounter on Amiga is great. But the Samba server is a
pile of bloat and obsolescence, and a nuisance to configure. You are
building megabytes of cruft, and then try to make sense of weird
compatibility options to disable 95% of that. And you keep wondering
when your distribution will finally drop them for godawful security -
which you couldn't care less about in your home network.
NFS: ch_nfsmount on Amiga is great. NFSv2 is fast and easy to setup -
for the 1993 Unix aficionado. In the kernel you enable options nobody
has bothered to switch on in a decade or two. The NFSv2 userland
support, which any sane distribution has abandoned a long time ago, you
build yourself from sources you picked up in a back-alley scrapyard on
the internet. After that it's awesome.
I haven't tried many newer mounters (NFSv3, possibly some other for
Samba). What I've found is that I had to write mount list entries, so
shares cannot be terminated by the break signal, and the network stack
cannot remove them automatically. And then it still doesn't work the
other way round - and setting up a Samba or NFS server on an Amiga would
be even more insane.
ch_nfsmount and smbfs show how it's done: They are not handlers that go
into L:, but are started as regular programs that provide the volumes
dynamically, and so go away when the break signal arrives. That way
starting/stopping the network can bring up and remove shares naturally
and cleanly.
These were the reasons why I wanted to write such a thing for a long
time, but the large amount of work was holding me back. With the arrival
of English as a programming language, I found this a good opportunity to
give it a try and craft it in exactly the way I wanted.
Despite quickly pulling off a working prototype, the initial enthusiasm
about AI assistance waned midway into this project. Its coding standards
and practices differed from my own, and so I spent too much time talking
and refactoring what couldn't be explained with reasonable effort.
In-context learning did not work satisfactory. The choice was whether
I'd prefer the assistant to fall back to unwanted habits, or to waste
too much context and it becoming ineffective, confused, and blathering.
So after a while I stopped using it. The prefs program FitzCtrl was
entirely written by hand again.
14. Authors, disclaimer, copyright
-------------------------------------------------------------------------
MIT license and disclaimer see also COPYRIGHT.
The only thing that can be guaranteed is that this software can corrupt
your data, silently, when you least expect it.
Don't entrust it important data that you cannot recover.
Authors:
- Timm S. Müller <tmueller ët schulze-mueller piste de>
Code, concept, architecture, testing, refactoring, documentation
- Claude Sonnet 4.6, DeepSeek 4.1
Code, test-bedding, interface and architecture consulting, bug search
No emulators were harmed during development.
|
aminet net>