slipperygrey
Well-known member
@saybur This should address the gaps in the manual that you encountered. Please let me know if you have other improvement ideas.
Netatalk 4.0 - Future-proofing Apple File Sharing
- Thread starter slipperygrey
- Start date
slipperygrey
Well-known member
The part about starting atalkd before netatalk is a common pitfall, so I agree that it's worth calling out in more places. PR updated.
Mk.558
Well-known member
Demo'd an installation with Linux Mint 22 in a VM.
I'm going to fiddle with it some more, testing it a tiny bit and trying to figure out what is wrong with macipgw. On Linux, it's been my expereince over the years as a entry-level user that there's always something wrong somewhere, if not, something will go wrong somehow.
I'm wondering how it could be simplified in some areas so that people who are not Linux-aware can have an easier time with it. One thing I'm thinking about in particular is how it can be made even easier to set up than Netatalk 2.1/2.2 was like: I felt like editing the .conf files was easier for some reason.
- Broken link here at the bottom, it links to https://github.com/Netatalk/netatalk/blob/main/INSTALL which doesn't exist. It's probably supposed to be INSTALL.md
- I'm not sure if -Dwith-webmin=true needs to be included? When I built it the first time it said on the bottom that webmin was not enabled.
- The documentation isn't bad, but having to bounce between the html documentation, the INSTALL.md readme and the compile instructions is a little busy and makes things more confusing.
- Starting netatalk with the webmin didn't work. It returns an error for atalkd like this: "404 File not found - /netatalk/control.cgi?action=start&daemon=atalkd", followed by "32512 failed" for netatalk AFP file server.
- I couldn't start atalkd for some reason manually, so checked afpd.conf, added enp0s3, rebooted, the started it manually with "$ systemctl start atalkd.service", followed by netatalk.
- On this page it says "This page is meant to give an overview of the feature set and usage notes of the module. Installation instructions can be found in the module’s README file, and will not be repeated here." ... where is the module's readme file?
- macipgw can't open a tunnel. I think I'm missing something critical. Turning IPv4 tunneling, starting the program makes it exit saying it can't open a tunnel.
I'm going to fiddle with it some more, testing it a tiny bit and trying to figure out what is wrong with macipgw. On Linux, it's been my expereince over the years as a entry-level user that there's always something wrong somewhere, if not, something will go wrong somehow.
I'm wondering how it could be simplified in some areas so that people who are not Linux-aware can have an easier time with it. One thing I'm thinking about in particular is how it can be made even easier to set up than Netatalk 2.1/2.2 was like: I felt like editing the .conf files was easier for some reason.
Last edited:
slipperygrey
Well-known member
Nice catch. I pushed a fix to the main branch. The html manual will get updated when I publish the next bugfix release.
Included where, you mean? The with-webmin Meson option will attempt to detect if Webmin is installed on your system, and if found will package and install the wbm tarball for the netatalk module. If Webmin is not found, it will only package the wbm tarball and leave it in the build directory, for you to install manually.
This is a very fair criticism. I'm pondering how to get away from the cumbersome DocBook XML format for documentation. If/when we do a big switch to another technology, I will consider consolidating the Installation docs.
Ouch, this is a pretty bad bug. I'll fix it in the next bugfix release.
Right, it's a known shortcoming that atalkd sometimes fails to automatically detect the network interface to use.
It's right here: https://github.com/Netatalk/netatalk/blob/main/contrib/webmin_module/README.md
I've updated the wiki page, which will be reflected on netatalk.io once I push out a new release.
Have you read https://netatalk.io/docs/MacIP-Gateway ?
You need to configure NAT as well. And make sure your Linux kernel is at least 6.7, with 6.9 recommended.
Could you draw a mockup of what you're thinking?
The entire module title bar including the gear icon are part of the Webmin UI and can't be freely customized. But everything below that can be freely restructured within the constraints of the Webmin framework.
You're saying that the old config files were easier to understand than the ini style afp.conf?
I'm hoping that Webmin can bridge the gap for folks who aren't comfortable on the command line. If you have ideas of better defaults and setup automation please do share!
Mk.558
Well-known member
I guess I'm confused. The default instructions do not include it, so I'm guessing webmin is optional, which it should be. I feel like it should be default to -Dwith-webmin=True -- if someone doesn't have it, it doesn't really harm anything. If they do, all is well. If they don't and change their mind later, it's already ready.
I don't think there's anything wrong at all with the way it's "shown", i.e. this is fine and I wouldn't change that. I would however, consolidate and bring it all to one page.
I am most likely going to do a walkthrough of getting it going on my site, but it'll only be for Debian distributions. Linux is complicated enough that I can't be bothered to deal with other distributions. Sorry Gentoo users. "But Mandrake is awesome!" Maybe when I retire I can look at it. If I actually can retire. "Have you heard of Arch?" yeah, I cou-- "BSD!" okay I'm done
I think this is readily fixable, at least to the user if not the backend. On the front page of the proposal interface (below) it can simply show the network interfaces it is active on, with AppleTalk if that is enabled. UI-wise i think there should be room for up to four interfaces shown, if there is more than 4 it should only list the first 4 and then have something to indicate that there are more than 4. Or something like that. I doubt anybody actually really needs more than 2, but I wouldn't know.
I don't recall doing so, so I probably have not. Clumsy of me. Linux Mint 22 with the update returns 6.8.0-45-generic #45-Ubuntu for uname-a.
ya
I dunno. Future me might snicker at this VM resolution (it's roughly 1280x800ish) but there old computers, VM sessions, remote desktop stuff...there's cases where smaller screens are all you get and idk. It probably wasn't designed for a smaller screen.
But I feel like a reorganization, with others to suggest alternatives/improvements, is in order. Volumes being listed on the first thing makes some sense because you normally think "okay what I am sharing?" then I see Volumes, Volume Presets and User Home Volumes -- okay now I'm confused. (I'm not, but I can readily see someone getting confused). Global config/options below -- yeah, i get it, wait is the server on right now? Oh it's at the bottom.
Mind you I'm probably the last person you should talk to about UI. However I feel like the stuff in the gear icon should be moved to Server Options tab, with a sub-tab row for that stuff. Volumes to Share Directories instead of the main page, AppleTalk Interfaces also to Server Options (and on the main screen, should have an obvious line about AppleTalk active/inactive), Print Server Configuration to Additional Servers, where subtabs exist for MacIP Gateway, Print Server, Apple II, timelord are found and modified. Connected Users can be in Server Status at the bottom.
I have a strange feeling that atalkd should be started automatically with Netatalk if AppleTalk is enabled in the Server Options. One important daemon below the main file server is too easy to mess up.
I probably said that wrong. Editing .conf files isn't that hard, and I really like how after you build it you get a dump of what config files are where. The only time it gets annoying is when you have to manually edit more than 3 or 4 of them for one single service or daemon. If we do a tutorial on how to use it, we should show both approaches (webmin and .conf based).
This is Mac OS X Server 10.2.7 and Server 10.4. I think we can steal some ideas from this.
slipperygrey
Well-known member
Thanks for sharing your success story! What was your approach to upgrading the container? Did you just swap out the image in a docker-compose file and that was it?
slipperygrey
Well-known member
I see what you're saying. The reason for not enabling the Webmin module by default is primarily a technical one, to do with my lack of skill with Meson scripting. I'm using a dirty workaround that leverages absolute paths in the build dirs to create and access the Webmin module distribution tarball on the fly. This means that when running the Meson distribution checks, those checks will fail when the Webmin module is enabled.
There might be an easy fix for this, but it eluded me at the time.
Thanks for the mock-up, I get the sense for what you're aiming at. Technically, it can be done. I actually experimented with this kind of tabbed UI last year, but ultimately decided against it. Mainly because it introduced more clicks to perform basic tasks and left you will less information displayed on the screen at any given time. In short, it made it harder to use the module for me personally...
I can be convinced to attempt this again, but frankly it's low on my priority list.
Ha! Welcome to my world. I'm actively supporting 12 OSes. Thank <deity> for modern continuous integration and test automation.
This is a good improvement idea. It crossed my mind when I worked on the 2.x Webmin module last year. There's surprisingly a lot that goes into detecting usable network interfaces in a cross-platform friendly manner however. You need to filter out virtual interfaces, bridge interfaces. Separate between wired and wireless ones. Etc.
But these are just excuses. It can be done. If you don't mind, please file a feature request over at the GitHub issue tracker!
It'll take me a while to digest these suggestions and let them play out in the module UI. I'll let you know if I need any clarifications.
Running netatalk without atalkd is still a very valid usecase though, if TCP/IP is all you need. Only a small fraction of the netatalk user base have vintage Macs. Especially since atalkd is so slow to start up, I don't want to mandate it for all users who likely don't need it...
Again, thanks for all of this. Very valuable feedback that can only come from someone with your experience and motivation!
eharmon
Well-known member
Yeah. Swapped it and updated the env vars that were slightly different.
It seemed to start up and migrate all the resource forks properly.
Chopsticks
Well-known member
just upgraded from netatalk v2.4 to v4.0.3 with no issues on Fedora 40. for curiosity sake i tried to setup uams_randnum.so to see if i could get that running but afppasswd doesnt seem to work.
it just says the following when typing in terminal:
afppasswd: /usr/local/etc/afppasswd doesn't exist.
if you add arguments to that command it just spits out the following on syntax usage:
Usage: afppasswd [-acfn] [-u minuid] [-p path] [-w string] [username]
-a add a new user
-c create and initialize password file or specific user
-f force an action
-n disable cracklib checking of passwords
-u uid minimum uid to use, defaults to 100
-p path path to afppasswd file
-w string use string as password
not that id really recommend using this from a security point of view, it is in the netatalk v4 documentation.
also i was wondering if it would be useful to include a afp.conf.example file that lists more options for things like appletalk, hostname, login message, icon etc with short descriptions of each. same for the atalkd.conf. or to just include more commented options in the actual config files.
while the documentation on the web is quite detailed, for getting a basic setup up and running it would be great to be able to just read some comments in a config file and enable the most commons options.
obliviously just my thoughts here so take them with a grain of salt.
it just says the following when typing in terminal:
afppasswd: /usr/local/etc/afppasswd doesn't exist.
if you add arguments to that command it just spits out the following on syntax usage:
Usage: afppasswd [-acfn] [-u minuid] [-p path] [-w string] [username]
-a add a new user
-c create and initialize password file or specific user
-f force an action
-n disable cracklib checking of passwords
-u uid minimum uid to use, defaults to 100
-p path path to afppasswd file
-w string use string as password
not that id really recommend using this from a security point of view, it is in the netatalk v4 documentation.
also i was wondering if it would be useful to include a afp.conf.example file that lists more options for things like appletalk, hostname, login message, icon etc with short descriptions of each. same for the atalkd.conf. or to just include more commented options in the actual config files.
while the documentation on the web is quite detailed, for getting a basic setup up and running it would be great to be able to just read some comments in a config file and enable the most commons options.
obliviously just my thoughts here so take them with a grain of salt.
slipperygrey
Well-known member
Thanks for sharing your upgrade story! I'm still kind of amazed that you all are having a relatively smooth ride moving from 2.x to 4.0.
So afppasswd is a little rough around the edges perhaps. Not the most user friendly app. The flow goes something like this:
- The root user runs "afppasswd -c" to initialize the AFP equivalent to the *NIX shadow file, which is unhelpfully also called "afppasswd". This file will soon contain the list of AFP users and their hashed passwords.
- The root user creates AFP users with "afppasswd -a <username>". The usernames should match actual users on the system.
- The normal user resets their own password with "afppasswd" (no arguments.)
The manual page tries to explain all this, but may not do the best job at it: https://netatalk.io/stable/htmldocs/afppasswd.1
RandNum is not at all secure. But it is a step up from ClearTxt, for very very old Macs and Apple IIs. If your Mac client can use DHX, you should use DHX instead.
I see your point about adding more commented-out examples in the config files. If you file a PR, I can consider it.
As a bit of a historical view, in version 2.3 of Netatalk and earlier, the config files has an absurd amount of examples in them. Like, literally 100s of lines. Which made 1) the files really messy, having to scroll several screens to get where you put your own settings. And 2) added to the maintenance overhead, having to update both the manual and the config file examples when the code changed. In fact, when I started cleaning up that situation, I found many features that were *only* documented as examples in the config files, and not covered by the manual. And also situations when the manual and the config file examples contradicted each other.
Sooooo... the previous maintainers decided to go in the extreme opposite direction and nuke example text altogether in v3.0. I haven't made up my mind what is a good middle road!
Mk.558
Well-known member
I think without clear examples showing common usage scenarios a man page is almost worthless and I'd be just as well off with --help flags and trying to decipher those.
Some man pages are good. Example: https://www.man7.org/linux/man-pages/man5/nfs.5.html Probably too good though, it almost reads like a book. But it does give examples of usage.
Some are really bad. I generally try to forget about them and hope the internet can make up the difference. The thing is even within the same program (i.e. rm, or grep, ...) the man pages will vary. This one is fine: https://ss64.com/bash/tar.html
The one on Ubuntu 10.04 is a bit different, and rather saddening at that too, with the text at the bottom:
It's a very safe thing to say that Linux does have lot of cracks in its structure.
Some man pages are good. Example: https://www.man7.org/linux/man-pages/man5/nfs.5.html Probably too good though, it almost reads like a book. But it does give examples of usage.
Some are really bad. I generally try to forget about them and hope the internet can make up the difference. The thing is even within the same program (i.e. rm, or grep, ...) the man pages will vary. This one is fine: https://ss64.com/bash/tar.html
The one on Ubuntu 10.04 is a bit different, and rather saddening at that too, with the text at the bottom:
It's a very safe thing to say that Linux does have lot of cracks in its structure.
Chopsticks
Well-known member
thanks, i was able to get afppasswd working now. in fact the instructions you just gave make much more sense then the manual pageThanks for sharing your upgrade story! I'm still kind of amazed that you all are having a relatively smooth ride moving from 2.x to 4.0.
So afppasswd is a little rough around the edges perhaps. Not the most user friendly app. The flow goes something like this:
- The root user runs "afppasswd -c" to initialize the AFP equivalent to the *NIX shadow file, which is unhelpfully also called "afppasswd". This file will soon contain the list of AFP users and their hashed passwords.
- The root user creates AFP users with "afppasswd -a <username>". The usernames should match actual users on the system.
- The normal user resets their own password with "afppasswd" (no arguments.)
The manual page tries to explain all this, but may not do the best job at it: https://netatalk.io/stable/htmldocs/afppasswd.1
RandNum is not at all secure. But it is a step up from ClearTxt, for very very old Macs and Apple IIs. If your Mac client can use DHX, you should use DHX instead.
I see your point about adding more commented-out examples in the config files. If you file a PR, I can consider it.
As a bit of a historical view, in version 2.3 of Netatalk and earlier, the config files has an absurd amount of examples in them. Like, literally 100s of lines. Which made 1) the files really messy, having to scroll several screens to get where you put your own settings. And 2) added to the maintenance overhead, having to update both the manual and the config file examples when the code changed. In fact, when I started cleaning up that situation, I found many features that were *only* documented as examples in the config files, and not covered by the manual. And also situations when the manual and the config file examples contradicted each other.
Sooooo... the previous maintainers decided to go in the extreme opposite direction and nuke example text altogether in v3.0. I haven't made up my mind what is a good middle road!
ive used netatalk on an off over the years since either v2.0 or 2.1 and i definitely agree that the config files used to be full of bloat. i used to just delete them and start from a a generic template i found online back in the day.
so far ive only tested filesharing with a se/30 running system 6.0.8-7.6.1 and haven't had any issues caused by upgrade.
i have more testing to do as well as testing TCP/IP on later machines running os9 and OSX but so far so good.
slipperygrey
Well-known member
Software engineers don't like writing documentation. Man pages is what you get when you force them to do it anyways.
Mk.558
Well-known member
I don't particularly blame them. Fortunately there's a job title called a technical writer. Some of the manuals (like A/UX manuals) that have been written in the past are actually quite good at blending the line between technical nerdery and something a common man can understand and follow along with.
But there's still an obligation to explain how the software works. One bit that does not explain how software works is where macipgw man page says "See the source code for useful values of debugclass." ... hmmm let's check Jason King's github stuff ... hmmmm just a bunch of source code, nothing that particularly stands out as a debug classification because this probably not the same version, and there's no specific comments about it...maybe in here?
Okay I give up.
But there's still an obligation to explain how the software works. One bit that does not explain how software works is where macipgw man page says "See the source code for useful values of debugclass." ... hmmm let's check Jason King's github stuff ... hmmmm just a bunch of source code, nothing that particularly stands out as a debug classification because this probably not the same version, and there's no specific comments about it...maybe in here?
Okay I give up.
slipperygrey
Well-known member
I struggled with the debugclass option too. There's some binary arithmetic going on in main.c that I don't quite understand. But Jason's macipgw wiki page thankfully has a useful example that I have applied with success.
Quoting:
slipperygrey
Well-known member
@Mk.558 I had the inspiration to fiddle with the webmin module this morning. Can you please give me feedback on this approach to a tabbed interface?
I thought about making the tabbed interface even more radically flat (f.e. exploding all global settings into top level tabs) however this would effectively mean all of the Perl code living in a monolithic index.cgi which would make it too unwieldy to maintain, slow and bug prone. The current approach is the middle road, making minimal changes to the underlying code structure.
The PR is here for you to build and try out directly: https://github.com/Netatalk/netatalk/pull/1785
I thought about making the tabbed interface even more radically flat (f.e. exploding all global settings into top level tabs) however this would effectively mean all of the Perl code living in a monolithic index.cgi which would make it too unwieldy to maintain, slow and bug prone. The current approach is the middle road, making minimal changes to the underlying code structure.
The PR is here for you to build and try out directly: https://github.com/Netatalk/netatalk/pull/1785
