#2057 update docs on httpd configuration
Merged 2 years ago by tkopecek. Opened 2 years ago by tkopecek.
tkopecek/koji issue1878  into  master

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

  ^^^^^^^^^^^^^^^^^^^^^

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

2 years ago

pretty please pagure-ci rebuild

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.

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.

1 new commit added

  • Make the docs more in line with our example configs
2 years ago

Commit 1a9129c fixes this pull-request

Pull-Request has been merged by tkopecek

2 years ago