kych.README.Debian (6185B)
1 kych for Debian 2 =============== 3 4 The service is installed disabled and will not start on its own: it has no 5 usable defaults for the database or for the OAuth 2.0 clients it serves, so 6 the three steps below have to happen first. Later upgrades of the package 7 do restart a running service, and migrate the database schema before doing 8 so, without any of this having to be repeated. 9 10 What is configured where 11 ------------------------ 12 13 /usr/share/kych/config.d/00-kych-defaults.conf defaults, owned by the 14 package -- do not edit 15 /etc/kych/kych.conf your settings 16 17 Both are read on every start, in that order, and the second one wins. The 18 defaults cover every option the gateway requires, which is why kych.conf 19 ships holding nothing but comments; put only what you actually change into 20 it, and an upgrade of the defaults will never prompt you about a conffile. 21 22 See kych.conf(5) for the options, and note the one syntax wart: a comment 23 must stand on a line of its own, never after a value. 24 25 1. Create the database 26 ---------------------- 27 28 kych-dbconfig 29 30 That creates the PostgreSQL role "kych" and a database "kych" owned by it, 31 and loads the schema. The daemon runs as the system user kych and the 32 shipped configuration connects over the local PostgreSQL socket using peer 33 authentication, so no password is stored anywhere. 34 35 If your PostgreSQL is not the stock one on port 5432, set DATABASE in 36 /etc/kych/kych.conf *before* running kych-dbconfig -- it takes the server to 37 act on from there, so the database ends up where the daemon will look for it: 38 39 [kych-oauth2-gateway] 40 DATABASE = postgres://localhost:5433/kych?host=/var/run/postgresql 41 42 Note the shape of that line: "?host=" with a path selects the Unix socket 43 directory, while the port is only read from the authority part ("?port=" is 44 ignored), so both have to be written as above. kych.conf(5) spells this out. 45 46 To use a remote database or password authentication instead, set DATABASE to 47 a full connection URI before running kych-dbconfig. A 48 password does not have to live in the main file: with 49 50 @inline-secret@ kych-oauth2-gateway /etc/kych/secrets/database.conf 51 52 the DATABASE line can sit in a file of its own, restricted to root:kych, 53 while kych.conf itself stays readable. 54 55 Schema upgrades are not your job: the package runs kych-dbinit(1) from its 56 postinst on every upgrade, which applies the SQL patches the database does 57 not have yet and does nothing when there is nothing to apply. You can run it 58 by hand too, and ask what it would do: 59 60 sudo -u kych kych-dbinit -c /etc/kych/kych.conf --dry-run 61 62 2. Configure 63 ------------ 64 65 Edit /etc/kych/kych.conf. The parts worth touching are the recommended 66 ALLOWED_SCOPES ceiling and at least one [client_*] section; the credential 67 settings (VC_*) already describe the Swiss e-ID beta credential. 68 69 Then register the clients in the database -- the running gateway reads 70 clients from there, not from the configuration file: 71 72 kych-client-management -c /etc/kych/kych.conf sync 73 kych-client-management -c /etc/kych/kych.conf list 74 75 Re-run "sync" after every change to a [client_*] section. Note that it does 76 not rotate an existing client's secret; delete and re-create the client for 77 that. 78 79 3. Start it 80 ----------- 81 82 systemctl enable --now kych 83 systemctl status kych 84 85 Behaviour on upgrade 86 -------------------- 87 88 Installing a new version of the package: 89 90 * applies any new schema patches (kych-dbinit, from the postinst), and 91 * restarts the service if it was running -- including when it was started 92 without being enabled. 93 94 A service that was not running stays stopped, and a first install never 95 starts anything. Nothing has to be done by hand in either case. 96 97 Removing the package 98 -------------------- 99 100 A purge removes /etc/kych/kych.conf, as always. The kych database is not 101 touched -- it is site state, and dropping it would throw away the registered 102 clients -- so remove it by hand if that is what you want: 103 104 sudo -u postgres dropdb kych 105 sudo -u postgres dropuser kych 106 107 Anything you put in /etc/kych/secrets/ also stays behind, since the package 108 does not own those files. 109 110 111 The verifier 112 ------------ 113 114 KyCH does not verify credentials itself; it drives a SWIYU verifier over 115 OpenID4VP. The swiyu-verifier package (recommended by this one) runs that 116 service on the same host, and /usr/share/doc/swiyu-verifier/README.Debian 117 describes its setup. A verifier operated elsewhere works just as well: all 118 the gateway needs is its URL in the client's VERIFIER_URL. 119 120 Note that the verifier must be reachable *from the gateway* for the 121 management API, and reachable *from the user's wallet* over public HTTPS for 122 the OID4VP API. 123 124 Socket activation (optional) 125 ---------------------------- 126 127 With the default SERVE = unix the daemon binds /run/kych/kych.sock itself and 128 kych.socket must stay disabled -- the two would fight over the same path. To 129 let systemd own the socket instead, so that it exists from boot and the daemon 130 starts on the first connection, set in /etc/kych/kych.conf 131 132 SERVE = systemd 133 134 and swap the units: 135 136 systemctl disable --now kych.service 137 systemctl enable --now kych.socket 138 139 The socket path, its group (www-data) and its mode (0660) are the same either 140 way, so nothing changes for the reverse proxy. kych.socket is the place to 141 edit them in this mode; UNIXPATH_MODE is not consulted. 142 143 Reverse proxy 144 ------------- 145 146 The gateway speaks plain HTTP on the Unix socket /run/kych/kych.sock and does 147 not terminate TLS. The socket has group www-data and mode 0660, so a proxy 148 running as www-data can reach it. No web-server snippets are shipped; for 149 nginx the essential part is 150 151 location / { 152 proxy_pass http://unix:/run/kych/kych.sock; 153 proxy_set_header Host $host; 154 proxy_set_header X-Forwarded-Proto $scheme; 155 } 156 157 Do not expose the gateway directly: /notification accepts unauthenticated 158 webhooks from the SWIYU verifier and should additionally be restricted to the 159 verifier's address at the proxy. 160 161 Logs go to the journal: 162 163 journalctl -u kych -f 164 165 -- Taler Systems SA <deb@taler.net>