//Short: Light TCP/IP file server and mounter
//Author: Timm S. Mueller, Claude Sonnet
//Uploader: tmueller@schulze-mueller.de
//Type: comm/tcp
//Version: 1.12
//Architecture: m68k-amigaos, other
//
\\
\\>>Fitz:main<< - Lightweight TCP/IP network file server and mounter
\\-------------------------------------------------------------------------
\\for Amiga and Unix (Linux, FreeBSD, macOS, ...)
\\
\\ 1. <<About>>
\\ 2. <<Example_use>>
\\ 3. <<Requirements>>
\\ 4. <<Build_and_install>>
\\ 5. <<Getting_started>>
\\ 6. <<Share_a_directory>>
\\ 7. <<Mount_a_share>>
\\ 8. <<Service_names_and_discovery>>
\\ 9. <<System_time,_Amiga_and_general_notes>>
\\10. <<Capability_management>>
\\11. <<Encryption>>
\\12. <<FitzCtrl>> - GUI prefs program
\\13. <<Rationale>>
\\14. <<Disclaimer>>
\\15. <<Authors>>
\\

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:FitzCtrl>> is included.

Fitz goes both ways: You can <<share:Share_a_directory>> and <<mount:Mount_a_share>> - on all platforms, both directions are supported. You can share an Amiga directory with other Amigas, or mount it under Unix. You can run as many instances as you like. There is no central server.

Fitz <<supports:Capability_management>> 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.


2. >>Example_use<<
-------------------------------------------------------------------------

Assume you have three computers in your home 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

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 into /usr/local/bin:

  $ make all
  $ sudo make install
  
Building for Amiga requires the vbcc toolchain:

  $ 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:Share_a_directory>> 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, but if you place symlinks in a share, these can be traversed by clients, even if they cannot create them or resolve them to their actual paths.

3. When there is no need for clients to write to a share, use the 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.


6. >>Share_a_directory<<
-------------------------------------------------------------------------

$ fitz serve [rootdir] [PORT num] [RO] [IFACE addr[:port]] [ASKPASS]
             [SERVICE name] [ENCRYPT] ( [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.
TZOFFS (Amiga only) specifies a time zone offset in seconds. See also <<notes_on_system_time:System_time,_Amiga_and_general_notes>>.

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
  # 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 192.168.1.5:8888 ~/net mount 192.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 the 'status' command to see the task numbers of Fitz processes. 'fitz query' will also display the task numbers of <<named_services:Service_names_and_discovery>>.


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
    

9. >>System_time,_Amiga_and_general_notes<<
-------------------------------------------------------------------------

- 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), 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 correct 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, accounts for NTP, DST, and assumes you have the TZ variable set.

  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

- See also the <<FitzCtrl>> utility, which allows you to configure Fitz mounts and shares with a graphical user interface, and launch them all at once in your network startup script.

- OH (OMITHIDDEN) can give confusing results when recursively deleting
directories which are not empty due to invisible dot-files.

- Remember that you will probably want to include xattrs for backups
and copies of Amiga directories on a Unix server 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.


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. If you use passwords or request encryption, 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.

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 intent was to obfuscate the data rather than to encrypt it by modern standards - so it won't get picked up too easily with packet sniffing.

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 (opportunistic) encryption from clients
  # fitz mount encrypt   require (opportunistic) 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:mount_a_share>> and <<shares:Share_a_directory>> on an Amiga. FitzCtrl depends on Fitz and is a purely optional front-end.

Copy FitzCtrl (with icon) wherever you want, usually SYS:Prefs. FitzCtrl will call fitz many times, therefore it is recommended to make fitz resident, as this will save a lot of memory and run things more smoothly. See also <<installation:Build_and_install>>.

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:System_time,_Amiga_and_general_notes>>.

When FitzCtrl is started, you will be presented 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 another computer on your LAN.

With a double-click on a list entry or by clicking 'Start' you can mount a share, and by clicking 'Stop' you can unmount it.

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' and 'Omithidden'. 

With the 'Add Mount' button you can create new entries for shares which do not have a <<service_name:Service_names_and_discovery>>, 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. In the Project menu are some functions to start and stop entries by the groups 'Auto' and 'User'. 

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'.

You can specify some options:

- Use the option 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, so it 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 passwords, you can also save passwords in the configuration. However, passwords in the FitzCtrl configuration file, ENVARC:fitzctrl.conf, are plain text, unencrypted. If you don't want to save passwords, 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. Now 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 become ineffective, confused, and blathering. So after a while I stopped using it. The prefs program FitzCtrl was entirely written by hand again.


14. >>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.


15. >>Authors<<
-------------------------------------------------------------------------

- Timm S. Mueller <tmueller et schulze-mueller piste de>
  Code, concept, architecture, testing, refactoring, documentation
  
- Claude Sonnet 4.6
  Code, test-bedding, interface and architecture consulting

No emulators were harmed during development.
