Branch server-docs contains my documentation contribution for using Fossil as a Windows Service and with stunnel as a proxy. It probably needs some editing for clarity, but the important parts are all there.

I followed the suggested structure proposed in this post.

I figure we can all work together in this branch updating the server docs and getting things tied in together. I have not updated any of the shipping documentation at this time, I just added some files.

Thanks.

I've created a UI and framework for this.

The inline CSS styles within that <table> are temporary. These should move into the default skin eventually. I'd have done them in a <style> block, but Fossil Wiki purposely disallows that.

I'm hoping to replace this hand-rolled HTML with JS that generates it or a suitable replacement for it from a JSON-style data table on page load, but that's currently blocked by a different Fossil Wiki weakness.

Oh, on the topic of default skin CSS, this page's abuse of <blockquote> to get body text indents has long bugged me. This should be done globally via the skin.

For example...

If there are no objections to this plan, I'm willing to do the skin work, but it'll have to wait until after this branch merges. I don't want to do it on this branch, and I don't want the merge conflicts that will result if I do it on another branch, since it'll involve ripping <blockquote> out in this same server.wiki doc and any other that abuses it.

The changes to the skin should be little more than porting over elements of my own custom skin, shown in the example above. There are a few refinements I've been putting off making — things get tricky with nested sections since multiple CSS rules can apply — but it's mostly battle-tested in my repo already.

With the conversion of www/server.wiki to HTML as www/server/index.html, I now have a platform to demonstrate this idea within the Fossil tree. See the <style> block up at the top of this file. I propose to add something like it to the default skin, so that all wiki and embedded documents are indented this way.

I'm about done with this for the next day or so. See the recent items on the timeline for what all has been done.

Comments, complaints, kudos?

drh, I hope you can get to you wanted to go atop this new structure. If not, let's discuss.

Thank you for working on the documentation!

I think that having separate documents for specialized configurations (example: setting up Fossil on Windows using stunnel) is a great idea. Having a matrix with links to those various documents is a great idea too.

However, I think the main /www/server.wiki document should be more stand-alone. Server.wiki should contain information on how to set up a Fossil server using the four methods mentioned, at a generic level. Server.wiki should have sufficient information so that someone who is familiar with how systems work could read the document, say "Oh, I get it!" and then go off and set up their own Fossil server with no additional help (beyond man pages for whichever "fossil" command they use). The server.wiki document should also have links (including but not necessarily limited to the matrix) to more detailed step-by-step guides to various invocation methods and OSes.

Server.wiki need not have as much detail as it did formerly. For example, I don't think showing actual xinetd.d configuration scripts are necessary or appropriate inside of server.wiki. Instead of showing the example xinetd.d script, provide a hyperlink to a separate inetd-specific document.

As an example, I think the right level of detail for the "socket activation" method (aside: Is that the best name?) should be something like this:

• Uses technologies like inetd, xinetd, or stunnel4.
• Launches "fossil http" to handle each incoming HTTP request
• The "fossil http" command will read the incoming HTTP request off of standard input, and send the HTTP reply by writing to standard output.
• Perhaps a few words about various options to "fossil http" such as "--https"
• Maybe also a link to a separate page with lots of details about the "fossil http" command, more detail than provided by the man page.

So, basically, one or two or three paragraphs about each activation method. Keep the succinct bullet list of activation methods at the top, but then provide a little more detail about each one in the main document.

The goal is to give the reader a high-level understanding of what is to be done, in a single document. After reading server.wiki, and nothing else, someone with a basic understanding of how the internet and servers work should come away with a good foundational for how a Fossil server works. After skimming the server.wiki document and getting the gist of what is going on, the reader may want to click on a link that is a closer match to their particular setup in order to obtain more details. But that should not be required. A systems expert should be able to glean enough information from only the server.wiki document to do a complete installation (with perhaps also reference to the man page to whatever fossil command they use).

Also, I think each breakout document should have links back to server.wiki.

But, overall, I think the server-docs branch is a good start and I encourage you to continue. I will likely contribute to that branch some myself.

Or, to put it another way, server.wiki needs to demonstrate that setting up a Fossil server is simple.

If setting up a Fossil server is simple, then the how-to document should be simple too. I have in mind a document that is basically this:

The current document has too many extraneous details. (I admit that I share a lot of blame for that myself.) Certainly the information about chroot jails, and TLS details, and managing server load, and the fact that Fossil does not require a server at all are important things. But let's factor them out into separate document so that they do not distract from the point of server.wiki, which is to show how setting up Fossil is easy (stunningly easy in comparison to GitLab) and demonstrate that fact by keeping the document itself simple and easy to read.

the how-to document should be simple

Agreed.

The current document has too many extraneous details.

I've extracted all of that to separate docs and reduced it all to a set of bullet points. I know you said "separate document," singular, but I think it works better this way. My ideal is that each sub-document of server.wiki should fit on a single screen with the browser set to the size of a sheet of printer paper. For some docs, this is impossible (e.g. TLS-on-nginx) but it's a goal we can strive for.

I'm out of time to continue work on this, so consider the branch unlocked for others to play with for the next half day or so.

There are basically four ways to set up a Fossil server:

For each of your four options, I think we should cover one or maybe at most two of the available choices:

1. Socket listener: systemd to cover the bulk of the market today, and inetd to cover the BSDs

2. Standalone HTTP: just give "fossil server"; that's it.

3. SCGI: a bullet-point presentation of www/server/any/scgi.md

4. CGI: a bullet-point presentation of www/server/any/cgi.md, covering only the Apache case

By the way, I view my current server/frontend matrix as "too complex" as well. It should be two drop-downs with backing JS to produce a bullet list of links below the pull-downs, so that you never see more than about 10 links at any one time.

Again I refer you to the way Certbot handles this same problem.

Instead of showing the example xinetd.d script,

Isn't xinetd basically a has-been? Wasn't it a stop-gap between inetd and systemd on Linux? Who still uses it any more on new operating systems?

I'd much rather spend time writing a dedicated systemd doc than thinking about xinetd.

Also on my to-do list is to prove that IIS can reverse-proxy Fossil in both HTTP and SCGI modes, to provide TLS encryption.

"socket activation" method (aside: Is that the best name?)

I think the term comes from either Upstart or systemd. It's then retroactively applied by systemd users to SMF, launchd, inetd...

I've changed all of these to "socket listener" to be more generic and less...hmmm...enterprisey.

one or two or three paragraphs about each activation method

I won't start on that any time soon, so you've got at least 12 hours or so of me not creating merge conflicts if someone else wants to take a stab at this.

Isn't xinetd basically a has-been? Wasn't it a stop-gap between inetd and systemd on Linux?

I can't figure out how to configure systemd. I'd welcome a document that shows how to set up a Fossil server using systemd, or launchd on a Mac.

My person preference is for good old inetd (without the "x" up front). Simple, direct, and gets the job done. Completely explained by a single man-page. But, sadly, nobody seems to support inetd anymore. What a shame.

I would very much like to see documents on how to configure Fossil on all these systems:

• inetd
• xinetd
• systemd
• launchd

My hypothesis is that I have listed the documents from shortest to longest. Prove me wrong!

Following this idea further off the original topic...

Complexity is the enemy of security. The more complexity in your system, the harder it is to avoid security problems due to misconfiguration.

It does not take much time to verify an inetd configuration for security and correctness. But is it even possible to know whether or not your systemd setup is secure and correct?

In another thread someplace, the question arose about why I wrote althttpd instead of using an existing HTTP server. The reason is the same - the other systems were sufficiently complex that I could never be sure that I hadn't left some vulnerability in the configuration. Althttpd is difficult to misconfigure, since it has no configuration file. And the source code is small enough to be audited easily.

Fossil has become a very complex system itself, and it is increasingly difficult to know whether or not you have left security holes in its setup. That is why I invented the "Security Audit" page. And that is why I am constantly working to improve the "Security Audit" page. I think the Security Audit page is very important to Fossil since it gives peace of mind that the system is set up correctly and securely.

I would very much like to see documents on how to configure Fossil on...systemd

That's done now. I've written it from your apparent perspective, answering the question "Why would I want to tolerate the greater complexity of systemd as compared to inetd?"

I don't expect you to switch over immediately after reading it, but there are good reasons why systemd has taken over the bulk of the Linux world, and it isn't purely because of network effects.

I'm not sure if I'll move on to launchd or not. I'm typing this on a Mac, but I don't really need Fossil service on it, so it'd be more in the way of a pure challenge, like with my IIS docs, only this time without as much reward: I expect far more people to benefit from the IIS docs than from launchd docs.

Complexity is the enemy of security.

Certainly. But many eyeballs are good for security, and systemd has a lot of eyeballs on it.

Althttpd is difficult to misconfigure

One thing I've noticed in doing all this documentation work is how difficult CGI has become in the years since I stopped paying attention to it, shortly after the dawn of the web, when I switched to other technologies like mod_perl, FastCGI, SCGI, and PSGI/WSGI.

That makes me wonder how many of the lessons learned by Apache, IIS, etc. ended up in althttpd. It doesn't appear to segregate cgi-bin from the read-only documents, for example. I see that it does some permission checks on the CGI script, but it doesn't seem to check the permissions of all directories along the path to the cgi-bin dir, as Apache does, which complicates deployment of CGI on new servers. I don't know how much any of this matters, but I can't imagine those maintaining Apache did all that work for no good reason. I assume there are exploits allowed by not doing these extra checks.

It seems to me that in the current world, CGI is only easy when you're given an account on an old-style shared web host where someone else has set up all of the security apparatus for you. Otherwise, fossil server blows CGI away in terms of simplicity.

My hypothesis is that I have listed the documents from shortest to longest. Prove me wrong!

You called it: the new launchd configs for Fossil are pretty darn verbose, longer even than the systemd ones, which is itself fairly verbose. (But highly readable!)

Good luck with IIS. Perhaps I was just too caught up in the asp.net methodology of using IIS. I no longer work directly with IIS as most of our hosting has moved to Azure Web Apps and that is an entirely different beast.

And along another line, if anyone wants to take a crack at cleaning up the Fossil Windows Server and Fossil Windows stunnel articles for clarity or grammar, go ahead. I won't be able to get back to them until next week. I'm pretty sure I got all the important bits in them, but sometimes what I write is clear as mud to others.

Thanks.

Good luck with IIS.

I win. :)

I may fill in the rest later, or I might just let it go. I really just wanted to see if I could do it. I don't actually use IIS. This was my first time in the IIS Manager, ever. (My Google-fu is strong.)

Looks like you ran into similar issues as I did when trying to get Fossil to run as CGI under IIS. I really think CGI under IIS is broken in later versions of IIS.

Your documentation on using IIS as a reverse proxy is very useful though for anyone wanting to add Fossil repository serving to an existing website. It looks like it still takes advantage of running Fossil as a service, which I feel may be the primary way to run a Fossil server on Windows. It certainly seems the most reliable for all the reasons that have come up.

I admire your tenacity on working through this problem on a platform you don't commonly use. That is some dedication right there.

Looks like you ran into similar issues as I did when trying to get Fossil to run as CGI under IIS.

You saw the CPU pegging symptom, too? If so, that's good: it means that two different people following two different paths to the same goal caused the Fossil + IIS pairing to give the same behavior. A reproducible bug is a dead bug walking.

I really think CGI under IIS is broken in later versions of IIS.

My bet is that IIS CGI is "broken" in the "doesn't follow standards" sense, whether formal or de facto, and Fossil is depending on its caller to follow those standards. That would fit Microsoft's historical pattern, particularly back in the days when the IIS CGI module probably got its last substantial attention from a Microsoft developer.

However, I suspect we could cope with this expected nonstandard IIS CGI behavior inside Fossil. Someone's just got to attach a debugger to fossil.exe while it's in this CPU-gobbling loop and find out what's going on in its brain to put it into that loop. Once we know that, the solution should be obvious.

While I was in the code, I saw a compile-time option in main() that would let someone force a CPU breakpoint shortly after Fossil starts, which you should be able to trap in a debugger, thus attaching from the start of the process rather than after the symptom shows up.

That is some dedication right there.

It's just the sort of puzzle I like: one that gives practical benefits when solved. To me, it's a game, but to someone else, it's an obstacle removed. And since obstacles to others' use of Fossil benefits me, too, it's ultimately not all that altruistic after all.

I think the "chroot.md" file has been accidentally omitted from the branch.

Fixed.

This branch is ready to merge down to trunk, in my estimation.

That claim was a bit premature. I've found several things to clean up since posting the above. It's now in much better shape. There are no merge conflicts, and the internal hyperlinks appear to be all fixed.

At this point, I need fresh eyes on this branch. I'm to the point where I just keep glazing over when staring at the same set of changes I've been working on for the past 5 days. (Has it really only been that long?)