From 14daa94d82587eedc4b45430d2b558159d2b1d9d Mon Sep 17 00:00:00 2001 From: Ken Dreyer Date: Wed, 27 May 2020 15:38:05 -0600 Subject: [PATCH] doc: rewrite PostgreSQL authorization instructions Rewrite the PostgreSQL authorization instructions in the Server HowTo guide. Provide two complete examples: the "all-in-one localhost" option, and the "separate postgres over the network" option. This reduces the decision trees and makes it easier to copy and paste the entire pg_hba.conf file. Explain what each mystery setting does and link to the PostgreSQL documentation. Only set listen_addresses to "*" if we need it, and turn it off if we don't. Simplify the instructions so that the user only restarts the postgresql daemon once. Clarify that koji-web does not need DB access, and the hub is the only service that requires direct DB access. Remove the example of authorizing the apache system user, because that implies that the admin must run a series of complicated GRANT instructions to allow both koji and apache to write to the DB. Just grant the koji user full trust access for simplicity. --- docs/source/server_howto.rst | 129 +++++++++++++++++++++-------------- 1 file changed, 76 insertions(+), 53 deletions(-) diff --git a/docs/source/server_howto.rst b/docs/source/server_howto.rst index a084e519..c65dd81a 100644 --- a/docs/source/server_howto.rst +++ b/docs/source/server_howto.rst @@ -442,53 +442,87 @@ The following commands will: This will ensure all objects are owned by the koji database user. Upgrades may be difficult if this was not done correctly. -Authorize Koji-web and Koji-hub resources ------------------------------------------ +Authorize Koji-hub to PostgreSQL +-------------------------------- -.. note:: - In this example, Koji-web and Koji-hub are running on localhost. +Koji-hub is the only service that needs direct access to the database. Every +other Koji service talks with the koji-hub via the API calls. -``/var/lib/pgsql/data/pg_hba.conf`` - These settings need to be valid and inline with other services - configurations. Please note, the first matching auth line is used so this - line must be above any other potential matches. Add: +Example: Everything on localhost +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - :: +In this example, the koji-hub Apache server is running on the same system +as the PostgreSQL server, so we can use local-only connections over a Unix +domain socket. - #TYPE DATABASE USER CIDR-ADDRESS METHOD - host koji koji 127.0.0.1/32 trust - host koji koji ::1/128 trust +#. Edit ``/var/lib/pgsql/data/pg_hba.conf`` to have the following + contents:: - It may also be necessary to add an entry for your machine's external IP - address: + #TYPE DATABASE USER CIDR-ADDRESS METHOD + local koji koji trust + local all postgres peer - :: + Explanation: - host koji koji $IP_ADDRESS/32 trust + * The ``local`` connection type means the postgres connection uses a local + Unix socket, so PostgreSQL is not exposed over TCP/IP at all. - You can also use UNIX socket access. The DBHost variable must be unset to - use this method. Add: + * The local ``koji`` user should only have access to the ``koji`` database. + The local ``postgres`` user will have access to everything (in order to + create the ``koji`` database and user.) - :: + * The ``CIDR-ADDRESS`` column is blank, because this example only uses + local Unix sockets. - local koji apache trust - local koji koji trust + * The `trust `_ + method means that PosgreSQL will permit any connections from any local + user for this username. We set this for the ``koji`` user because Apache + httpd runs as the ``apache`` system user rather than the ``koji`` user + when it connects to the Unix socket. ``trust`` is not secure on a + multi-user system, but it is fine for a single-purpose Koji system. - .. note:: - To enforce password based logins to the database, change ``trust`` to ``md5``. + The `peer `_ + method means that PostgreSQL will obtain the client's operating system + username and use that as the allowed username. This is safer than + ``trust`` because only the local ``postgres`` system user will be able to + access PostgreSQL with this level of access. - :: +#. Edit ``/var/lib/pgsql/data/postgresql.conf`` and set ``listen_addresses`` + to prevent TCP/IP access entirely:: - #TYPE DATABASE USER CIDR-ADDRESS METHOD - host koji koji 127.0.0.1/32 md5 - host koji koji ::1/128 md5 - host koji koji $IP_ADDRESS/32 md5 + listen_addresses = '' -Make auth changes live: -You must reload the PostgreSQL configuration for these changes to become -active. +Example: Separate PostgreSQL and Apache servers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +In this example, the PostgreSQL server "db.example.com" is running on one +host, and the koji-hub Apache server talks to this PostgreSQL server over the +network. The koji-hub Apache server has an IP address of 192.0.2.1 (IPv4) and +2001:db8::1 (IPv6), so we authorize connections from both addresses for the +``koji`` user account. + +#. Edit ``/var/lib/pgsql/data/pg_hba.conf`` to have the following contents:: + + #TYPE DATABASE USER CIDR-ADDRESS METHOD + host koji koji 192.0.2.1/32 md5 + host koji koji 2001:db8::1/128 md5 + local all postgres peer + + The ``md5`` authentication mechanism is available in PostgreSQL 9 (RHEL 7). + On PostgreSQL 10 (RHEL 8+ and Fedora), use the stronger ``scram-sha-256`` + mechanism instead, and set ``password_encryption = scram-sha-256`` in + ``postgresql.conf``. + +#. Edit ``/var/lib/pgsql/data/postgresql.conf`` and set ``listen_addresses`` + so that PostgreSQL will listen on all network interfaces:: + + listen_addresses = '*' + +Activating changes +^^^^^^^^^^^^^^^^^^ + +You must reload the PostgreSQL daemon to activate changes to +``postgresql.conf`` or ``pg_hba.conf``:: root@localhost$ systemctl reload postgresql @@ -600,23 +634,6 @@ complete the authentication setup and the kojihub configuration. If you wish to access koji via a web browser, you will also need to get kojiweb up and running. -Set Database To Listen On All Addresses -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The ``koji-hub`` service will attempt to connect to the database server in the -manner you configure. If you use the system hostname, then the database will -need to be available on that address. To configure this please perform the -following: - -#. Edit ``/var/lib/pgsql/data/postgresql.conf`` -#. Set ``listen_address`` so postgres will listen on all interfaces: - :: - - listen_addresses = '*' -#. Reload the postgresql service: - :: - - systemctl restart postgresql - Koji Hub ======== @@ -727,14 +744,20 @@ beginning. DBName = koji DBUser = koji - DBPass = mypassword - DBHost = db.example.com + + # If PostgreSQL is on another host, set that here: + #DBHost = db.example.com + #DBPass = mypassword + KojiDir = /mnt/koji LoginCreatesUser = On KojiWebURL = http://kojiweb.example.com/koji -If kojihub is running on the same server as the koji db, then DBHost should be -set to 127.0.0.1 +If koji-hub is running on the same server as PostgreSQL and you are using Unix +sockets to query the database, omit the ``DBHost``, ``DBPort``, and ``DBPass`` +variables. Do not set ``DBHost`` to ``localhost``, or else PostgreSQL will +attempt to connect with TCP through ``127.0.0.1`` instead of using the Unix +socket. Authentication Configuration ----------------------------