kych

OAuth 2.0 API for Swiyu to enable Taler integration of Swiyu for KYC (experimental)
Log | Files | Refs | Submodules | README | LICENSE

swiyu-verifier-dbconfig.1.rst (2916B)

      1 swiyu-verifier-dbconfig(1)
      2 ##########################
      3 
      4 .. only:: html
      5 
      6    Name
      7    ====
      8 
      9    **swiyu-verifier-dbconfig** - create the PostgreSQL database for the SWIYU verifier
     10 
     11 
     12 Synopsis
     13 ========
     14 
     15 **swiyu-verifier-dbconfig**
     16 [**-c** *FILENAME*]
     17 [**-n** *DBNAME*]
     18 [**-u** *DBUSER*]
     19 [**-d** *FILENAME*]
     20 [**-r**]
     21 [**-h**]
     22 
     23 
     24 Description
     25 ===========
     26 
     27 **swiyu-verifier-dbconfig** performs the one-time database setup for
     28 swiyu-verifier(1): it creates the PostgreSQL role the service connects as with
     29 a freshly generated password, creates the database with that role as its owner,
     30 and writes the password to ``/etc/swiyu-verifier/secrets/db.env``, mode 0640
     31 and owned by root:swiyu-verifier, which is where ``swiyu-verifier.service``
     32 reads it from.
     33 
     34 It must be run as root, because it works through the ``postgres``
     35 administrative user.
     36 
     37 Unlike kych-dbconfig(1) this does *not* create a schema: the verifier runs its
     38 own Flyway migrations on every start, so the database it is handed only has to
     39 exist and be owned by its role. For the same reason there is nothing to do
     40 after an upgrade of the package.
     41 
     42 A password is needed -- rather than ``peer`` authentication over the local
     43 socket, as KyCH uses -- because the connection is made by the PostgreSQL JDBC
     44 driver, which cannot authenticate that way.
     45 
     46 Running the script again generates a new password and sets it on the existing
     47 role, which is how a password is rotated; restart the service afterwards.
     48 
     49 
     50 Where the database goes is read from the service's own configuration rather
     51 than assumed: ``POSTGRES_JDBC`` in ``/etc/swiyu-verifier/swiyu-verifier.env``
     52 supplies the host, the port and the database name, and ``POSTGRES_USER`` the
     53 role. On a host whose PostgreSQL is not on port 5432 that is the difference
     54 between setting up the database the service will use and setting one up
     55 somewhere else.
     56 
     57 
     58 Options
     59 =======
     60 
     61 **-c** *FILENAME*
     62   Read the connection from *FILENAME* instead of
     63   ``/etc/swiyu-verifier/swiyu-verifier.env``.
     64 
     65 **-n** *DBNAME*
     66   The database to create, overriding the name in ``POSTGRES_JDBC``.
     67 
     68 **-u** *DBUSER*
     69   The role to create, overriding ``POSTGRES_USER``.
     70 
     71 **-d** *FILENAME*
     72   Write the generated password to *FILENAME* instead of
     73   ``/etc/swiyu-verifier/secrets/db.env``.
     74 
     75 **-r**
     76   Reset: drop an existing database before creating it again. **This destroys
     77   every verification in it** and is never needed for an upgrade.
     78 
     79 **-h**
     80   Print short help.
     81 
     82 
     83 Examples
     84 ========
     85 
     86 Set up the database as the package expects it:
     87 
     88 .. code-block:: shell
     89 
     90    $ sudo swiyu-verifier-dbconfig
     91    $ sudo systemctl restart swiyu-verifier
     92 
     93 Rotate the database password:
     94 
     95 .. code-block:: shell
     96 
     97    $ sudo swiyu-verifier-dbconfig
     98    $ sudo systemctl restart swiyu-verifier
     99 
    100 
    101 See Also
    102 ========
    103 
    104 swiyu-verifier(1), kych-dbconfig(1), kych-oauth2-gateway(1).
    105 
    106 
    107 Bugs
    108 ====
    109 
    110 Report bugs by using https://bugs.taler.net/ or by sending electronic
    111 mail to <taler@gnu.org>.