PR#2057: update docs on httpd configuration - koji

koji

#2057 update docs on httpd configuration

Merged 2 years ago by tkopecek. Opened 2 years ago by tkopecek.

tkopecek/koji issue1878 into master

Make the docs more in line with our example configs

Mike McLean • 2 years ago

bbe2e6d

update docs on httpd configuration

Tomas Kopecek • 2 years ago

61ff955

docs/source/server_howto.rst

file modified

+50 -11

		`@@ -642,6 +642,9 @@`
		`Required Configuration`
		`----------------------`

		+ We provide example configs for all services, so look for ``httpd.conf``, ``hub.conf``,
		+ ``kojiweb.conf`` and ``web.conf`` in source repo or related rpms.
		`+`
		`/etc/httpd/conf/httpd.conf`
		`^^^^^^^^^^^^^^^^^^^^^^^^^^`

		`@@ -676,11 +679,30 @@`
		`it based on your authentication type. Instructions are contained within the`
		`file and should be simple to follow.`

		`+ For example, if you are using SSL authentication, you will want to uncomment`
		`+ the section that looks like this:`
		`+`
		`+ ::`
		`+`
		`+ # uncomment this to enable authentication via SSL client certificates`
		`+ # <Location /kojihub/ssllogin>`
		`+ # SSLVerifyClient require`
		`+ # SSLVerifyDepth 10`
		`+ # SSLOptions +StdEnvVars`
		`+ # </Location>`
		`+`
		`+`
		`/etc/httpd/conf.d/ssl.conf`
		`^^^^^^^^^^^^^^^^^^^^^^^^^^`

		`- If using SSL you will also need to add the needed SSL options for apache. These`
		`- options should point to where the certificates are located on the hub.`
		`+ If you are configuring your server for httpd (and you really should), then your`
		+ ``SSLCertificate*`` directives will generally live in the main ``ssl.conf`` file.
		`+ This part is mostly independent of Koji.`
		`+ It's something you would do for any httpd instance.`
		`+`
		`+ The part that matters to Koji is this --`
		`+ if you are using SSL authentication, then the CA certificate you configure`
		`+ here should be the same one that you use to issue user certificates.`

		`::`

		`@@ -688,12 +710,7 @@`
		`SSLCertificateKeyFile /etc/pki/koji/private/kojihub.key`
		`SSLCertificateChainFile /etc/pki/koji/koji_ca_cert.crt`
		`SSLCACertificateFile /etc/pki/koji/koji_ca_cert.crt`
		`- SSLVerifyClient require`
		`- SSLVerifyDepth 10`
		`- # Python is currently not fully TLSv1.3 compatible and`
		`- # older TLS versions are no longer advised`
		`- # https://bugs.python.org/issue34670`
		`- SSLProtocol TLSv1.2`
		`+`

		`/etc/koji-hub/hub.conf`
		`^^^^^^^^^^^^^^^^^^^^^^`
		`@@ -892,15 +909,37 @@`
		`it based on your authentication type. Instructions are contained within the`
		`file and should be simple to follow.`

		`+ For example, if you are using SSL authentication, you would want to uncomment`
		`+ the section that looks like this:`
		`+`
		`+ ::`
		`+`
		`+ # uncomment this to enable authentication via SSL client certificates`
		`+ # <Location /koji/login>`
		`+ # SSLVerifyClient require`
		`+ # SSLVerifyDepth 10`
		`+ # SSLOptions +StdEnvVars`
		`+ # </Location>`
		`+`
		`+`
		`/etc/httpd/conf.d/ssl.conf`
		`^^^^^^^^^^^^^^^^^^^^^^^^^^`

		`- If you are using SSL you will need to add the needed SSL options for apache.`
		`+ Similarly to the hub configuration, if you are using https (as you should),`
		`+ then you will need to configure your certificates.`
		`+ This is something you might do for any httpd instance and is mostly independent`
		`+ of Koji`
		`+`
		`+ If you are using SSL authentication, then the CA certificate you configure`
		`+ here should be the same one that you use to issue user certificates.`

		`::`

		`- SSLVerifyClient require`
		`- SSLVerifyDepth 10`
		`+ SSLCertificateFile /etc/pki/koji/certs/kojihub.crt`
		`+ SSLCertificateKeyFile /etc/pki/koji/private/kojihub.key`
		`+ SSLCertificateChainFile /etc/pki/koji/koji_ca_cert.crt`
		`+ SSLCACertificateFile /etc/pki/koji/koji_ca_cert.crt`
		`+`

		`/etc/kojiweb/web.conf`
		`^^^^^^^^^^^^^^^^^^^^^`

tkopecek commented 2 years ago

Fixes: https://pagure.io/koji/issue/1878

Metadata Update from @tkopecek:
- Pull-request tagged with: no_qe

2 years ago

julian8628 commented 2 years ago

:thumbsup:

pretty please pagure-ci rebuild

2 years ago

mikem commented 2 years ago

There are many possible working variations for a kojihub httpd configuration. I'm not sure this is the optimal one.

Generally, the SSLVerifyClient, SSLVerifyDepth, and SSLOptions values are set in the appropriate <Location> blocks in the httpd config for kojihub and kojiweb, as shown in the example configs we ship. These settings are only required for a few urls, so they are very specific cases.

OTOH, the SSLCertificate* values should normally be set globally in ssl.conf because they apply to the entire VirtualHost.

Edited 2 years ago by mikem

ktdreyer commented 2 years ago

Agreed with Mike that we should keep those SSLCertificate* settings in the VirtualHost level.

By the way, I saw that this PR drops the references to TLSv1.2 vs TLSv1.3. This stood out to me because I found a regression in Ubuntu's recent TLSv1.3 backport to httpd mod_ssl on Bionic - more details at https://github.com/ktdreyer/koji-ansible/issues/114 . In my limited ad-hoc testing, it seems like Fedora clients and servers were fine with TLSv1.3 enabled in the httpd config now, but it made me think more about this.

The problem is that TLSv1.3 changes the way that SSLVerifyClient works within Apache's <Location> directive, and that whole feature is important to how Koji does SSL client authentication. The experience made me think that we should map out a full integration test matrix of "clients OS" authenticating to "server OS", since we are relying on several underlying pieces all working together there that slowly shift over time: OpenSSL, and Python, and urllib3, and python-requests, and Apache.

Edited 2 years ago by ktdreyer

mikem commented 2 years ago

Proposed changes here:
https://github.com/mikem23/koji-playground/commits/pagure/pr/2057

1 new commit added