TLS/HTTPS/SSL Documentation Maintenance

(1) By Warren Young (wyoung) on 2019-01-20 02:03:20 [source]

The TLS documentation in Fossil was getting rather outdated, evidenced by how often the topic comes up here. I decided, today, to begin remedying that. There are two major pieces, so far:

I all but rewrote the 7-year-old www/ssl.wiki document document. It covers much more than before, mainly by folding in the results from some of the recent discussions here on the forum.
I added a replacement for my old "HOWTO: TLS-protected Fossil with nginx and Let's Encrypt" posting from the mailing list, now available as www/tls-nginx.md. This has been on my wish list for a long time now. I was forced into it by Let's Encrypt, who deprecated the SNI-01 authentication method I was depending on in the old HOWTO. This new one now works in terms of the HTTP-01 method that should work indefinitely going forward.

I'd be stunned if both documents are entirely complete and correct at this stage. I've only checked them in now because it's been 8 or so hours, and I'm getting antsy having them in only one place.

Most especially, I doubt I've remembered to document everything about my nginx and Let's Encrypt configuration. Ideally, what I want is for someone who's never set up such a system to try following my guide and tell me all the places where I've left some critical bit of information out.

This thread is expected to be evergreen: as new problems with these docs come up, people can post to this thread to request updates to the docs, if they can't update the docs directly. This is one of my "itches," so making sure we have good TLS docs matters to me.

(2) By taa (tara) on 2019-08-02 04:19:06 in reply to 1 [link] [source]

I host many different repos all from a subdomain fossil.MYDOMAIN. I host via HTTP on FreeBSD. I installed fossil via `pkg install fossil` then I put all my fossil repos in `/home/fossil/repos`

my rc.conf:

  fossil_enable="YES"
  fossil_baseurl="https://fossil.birl.ca/"
  fossil_repolist="YES"
  fossil_directory="/home/fossil/repos"
  fossil_port="8081"
  fossil_user="fossil"

my nginx.conf

  # fossil.example.com
  server {
    listen 80;
    server_name "fossil.example.com";
    return         301 https://$server_name$request_uri;
  }
  server {
    listen 443 http2 ssl;
    ssl_certificate "/path/to/certificates/_.example.com.crt" ;
    ssl_certificate_key "/path/to/_.example.com.key" ;
    server_name "fossil.example.com";
        location / {
                proxy_pass http://127.0.0.1:8081/;
        }
 }

then it's just `service start fossil` and it's all up and running. I use wildcard certs from lets encrypt(LE), so my LE configuration is a little different as well, but that's outside of Fossil, so won't comment on that.

(3) By taa (tara) on 2019-08-02 04:20:56 in reply to 2 [link] [source]

I host many different repos all from a subdomain fossil.MYDOMAIN. I host via HTTP on FreeBSD. I installed fossil via pkg install fossil then I put all my fossil repos in /home/fossil/repos

my rc.conf:

  fossil_enable="YES"
  fossil_baseurl="https://fossil.example.com/"
  fossil_repolist="YES"
  fossil_directory="/home/fossil/repos"
  fossil_port="8081"
  fossil_user="fossil"

my nginx.conf

  # fossil.example.com
  server {
    listen 80;
    server_name "fossil.example.com";
    return         301 https://$server_name$request_uri;
  }
  server {
    listen 443 http2 ssl;
    ssl_certificate "/path/to/certificates/.example.com.crt" ;
    ssl_certificate_key "/path/to/.example.com.key" ;
    server_name "fossil.example.com";
        location / {
                proxy_pass http://127.0.0.1:8081/;
        }
 }

then it's just service start fossil and it's all up and running. I use wildcard certs from lets encrypt(LE), so my LE configuration is a little different as well, but that's outside of Fossil, so won't comment on that.

(4) By anonymous on 2019-08-02 13:37:08 in reply to 3 [link] [source]

Hi there,

Does this work fully, with the wiki and all?

I ask, because you have

fossil_baseurl="https://fossil.example.com/"

and I was under the impression that fossil currently accepts a --baseurl argument that ends in a slash, but does not usefully work when it ends in a slash.

(If that is (still) the case, and your example does not work fully, then possibly fossil could be changed to not accept a baseurl that ends in a slash.)

For what it's worth, I believe that for your case (where baseurl is "this server, but with https not http"), the "correct" config is to omit --baseurl with an argument and to add --https (without an argument).

(5) By anonymous on 2019-08-02 13:51:36 in reply to 1 [link] [source]

Hi there,

the tls-nginx.md file links to the the fslsrv shell script (https://fossil-scm.org/fossil/file/tools/fslsrv), which includes as the last line

start_one foo 1 https://foo.net

Does that work?

When I try to run a command like that, I get

argument to --baseurl should be 'http://host/path' or 'https://host/path'

because fossil requires that the --baseurl argument have at least a slash after the host part.

(I think that fossil also effectively requires that the argument not end in a slash, but that is not currently enforced at startup.)

Thanks,

(6) By Warren Young (wyoung) on 2019-08-02 18:02:11 in reply to 5 [link] [source]

I've updated the script to make that parameter optional, and made the foo.net example make use of this new freedom.

(7) By Warren Young (wyoung) on 2019-08-02 18:06:50 in reply to 4 [link] [source]

It's true that Fossil doesn't need --baseurl when it's hosted at the top level of the URL hierarchy. The baseurl parameter is there so it can generate absolute URLs correctly, and it needs that clue when it's hosted deeper down in the URL hierarchy only.

As for --https, that isn't needed when reverse proxying with nginx. I don't know why, but it's been running that way on my domains now for many years. I assume Fossil is getting the clue some other way.

(8) By ckennedy on 2019-08-02 19:01:55 in reply to 7 [link] [source]

I can confirm when running Fossil under Apache CGI on my hosted Linux server that I also don't pass https as an option to Fossil and everything is working fine. I'm assuming that Apache is handling all the http<>https translation for me.

(9) By anonymous on 2019-08-02 23:05:31 in reply to 8 [link] [source]

Yes, I believe that both nginx and Apache provide a HTTPS environment variable that fossil recognises as equivalent to --https, so that argument is not needed explicitly.

Cheers,