|
|
1
|
+
|
|
|
2
|
+.. _configuration:
|
|
|
3
|
+
|
|
|
4
|
+Configuration
|
|
|
5
|
+=============
|
|
|
6
|
+
|
|
|
7
|
+The details of how to tune BuildGrid's configuration.
|
|
|
8
|
+
|
|
|
9
|
+
|
|
|
10
|
+.. _configuration-location:
|
|
|
11
|
+
|
|
|
12
|
+Configuration location
|
|
|
13
|
+----------------------
|
|
|
14
|
+
|
|
|
15
|
+Unless a configuration file is explicitly specified on the command line when
|
|
|
16
|
+invoking `bgd`, BuildGrid will always attempt to load configuration resources
|
|
|
17
|
+from ``$XDG_CONFIG_HOME/buildgrid``. On most Linux based systems, the location
|
|
|
18
|
+will be ``~/.config/buildgrid``.
|
|
|
19
|
+
|
|
|
20
|
+This location is refered as ``$CONFIG_HOME`` is the rest of the document.
|
|
|
21
|
+
|
|
|
22
|
+
|
|
|
23
|
+.. _tls-encryption:
|
|
|
24
|
+
|
|
|
25
|
+TLS encryption
|
|
|
26
|
+--------------
|
|
|
27
|
+
|
|
|
28
|
+Every BuildGrid gRPC communication channel can be encrypted using SSL/TLS. By
|
|
|
29
|
+default, the BuildGrid server will try to setup secure gRPC endpoints and return
|
|
|
30
|
+in error if that fails. You must specify ``--allow-insecure`` explicitly if you
|
|
|
31
|
+want it to use non-encrypted connections.
|
|
|
32
|
+
|
|
|
33
|
+The TLS protocol handshake relies on an asymmetric cryptography system that
|
|
|
34
|
+requires the server and the client to own a public/private key pair. BuildGrid
|
|
|
35
|
+will try to load keys from these locations by default:
|
|
|
36
|
+
|
|
|
37
|
+- Server private key: ``$CONFIG_HOME/server.key``
|
|
|
38
|
+- Server public key/certificate: ``$CONFIG_HOME/server.crt``
|
|
|
39
|
+- Client private key: ``$CONFIG_HOME/client.key``
|
|
|
40
|
+- Client public key/certificate: ``$CONFIG_HOME/client.crt``
|
|
|
41
|
+
|
|
|
42
|
+
|
|
|
43
|
+Server key pair
|
|
|
44
|
+~~~~~~~~~~~~~~~
|
|
|
45
|
+
|
|
|
46
|
+The TLS protocol requires a key pair to be used by the server. The following
|
|
|
47
|
+example generates a self-signed key ``server.key``, which requires clients to
|
|
|
48
|
+have a copy of the server certificate ``server.crt``. You can of course use a
|
|
|
49
|
+key pair obtained from a trusted certificate authority instead.
|
|
|
50
|
+
|
|
|
51
|
+.. code-block:: sh
|
|
|
52
|
+
|
|
|
53
|
+ openssl req -new -newkey rsa:4096 -x509 -sha256 -days 3650 -nodes -batch -subj "/CN=localhost" -out server.crt -keyout server.key
|
|
|
54
|
+
|
|
|
55
|
+
|
|
|
56
|
+Client key pair
|
|
|
57
|
+~~~~~~~~~~~~~~~
|
|
|
58
|
+
|
|
|
59
|
+If the server requires authentication in order to be granted special permissions
|
|
|
60
|
+like uploading to CAS, a client side key pair is required. The following example
|
|
|
61
|
+generates a self-signed key ``client.key``, which requires the server to have a
|
|
|
62
|
+copy of the client certificate ``client.crt``.
|
|
|
63
|
+
|
|
|
64
|
+.. code-block:: sh
|
|
|
65
|
+
|
|
|
66
|
+ openssl req -new -newkey rsa:4096 -x509 -sha256 -days 3650 -nodes -batch -subj "/CN=client" -out client.crt -keyout client.key
|
