Skip to content

Commit 89dd7f0

Browse files
krishnangovindrajkrishnangovindraj
committed
Squash: Encryption & config guide
1 parent 19fb677 commit 89dd7f0

File tree

2 files changed

+255
-5
lines changed

2 files changed

+255
-5
lines changed

‎maintenance-operation/modules/ROOT/pages/typedb-configuration.adoc

Lines changed: 174 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,176 @@
11
= TypeDB Configuration
2-
:page-aliases: {page-version}@manual::configure.adoc
2+
:keywords: typedb, config, CLI
3+
:pageTitle: Server configuration manual
4+
:summary: TypeDB Server configuration.
35

4-
[placeholder]
5-
Configure TypeDB servers.
6+
You can configure a TypeDB server via two means: a YAML config file or command line options.
7+
Command line options override values defined in the config file.
8+
9+
For a full list of configurable properties run:
10+
11+
[source,bash]
12+
----
13+
typedb server --help
14+
----
15+
16+
This page lists & explains the available options.
17+
18+
== General CLI arguments
19+
20+
General, non-configuration arguments available on the CLI.
21+
22+
[cols=".^3,^.^1,5"]
23+
|===
24+
3+^| General CLI arguments
25+
26+
| `--config <path-to-file>`
27+
|
28+
| Specify a custom configuration file
29+
30+
| `--help`
31+
| `-h`
32+
| Show help message.
33+
34+
| `--version`
35+
| `-V`
36+
| Print version information and exit.
37+
38+
|===
39+
40+
== Configuration file
41+
By default, TypeDB looks for a `config.yml` file in the same folder as the TypeDB server executable (i.e., `/server/config.yml`).
42+
This path can be overridden using the CLI argument: `--config <path-to-your-config>`.
43+
44+
== Command line overrides
45+
46+
When using the command line to override a specific option, all CLI arguments must:
47+
48+
* start with the double dash prefix `--`,
49+
* be separated from their value (if any) either by an equals sign (`--arg=val`) or a whitespace (`--arg val`).
50+
51+
e.g., `--server.address=0.0.0.0:1730`
52+
53+
54+
[#_overview]
55+
== Configuration options
56+
57+
[#_server]
58+
=== Server
59+
60+
The `server` section of the configuration contains network and encryption options.
61+
For example, a server can be booted up on `0.0.0.0:1730` by using this command:
62+
63+
[source,bash]
64+
----
65+
typedb server --server.address=0.0.0.0:1730
66+
----
67+
[cols=".^3,5"]
68+
|===
69+
2+^| Server
70+
| `server.address`
71+
| Server host and port. Default value: `0.0.0.0:1729`. +
72+
73+
| `server.http.enabled`
74+
| Enable/disable HTTP endpoint. Default value: `true`. +
75+
76+
| `server.http.address`
77+
| HTTP endpoint host and port. Cannot be the same as `server.address`. Default value: `0.0.0.0:8000`. +
78+
79+
| `server.authentication.token-expiration-seconds`
80+
| The amount of seconds generated authentication tokens will remain valid, specified in seconds. Default value: `14400` (4 hours). +
81+
82+
|===
83+
84+
[#_encryption]
85+
==== Encryption
86+
87+
Configure the TLS certificate & private-key to be used for inflight encryption.
88+
89+
[cols=".^3,5"]
90+
|===
91+
2+^| Server encryption
92+
| `server.encryption.enabled`
93+
| Enable in-flight encryption. Do not specify this argument to leave it disabled. +
94+
95+
| `server.encryption.certificate`
96+
| Encryption certificate in PEM format. Must be supplied if encryption is enabled. +
97+
98+
| `server.encryption.certificate-key`
99+
| Encryption certificate key. Must be supplied if encryption is enabled. +
100+
101+
| `server.encryption.ca-certificate`
102+
| Encryption CA in PEM format. (Optional) +
103+
104+
|===
105+
106+
[#_storage]
107+
=== Storage
108+
109+
The `storage` section of the configuration contains the storage layer options.
110+
111+
[IMPORTANT]
112+
====
113+
For production use, it is recommended that the `storage.data-directory` is set to a path outside the `$TYPEDB_HOME`
114+
(directory with TypeDB server files).
115+
This helps to make the process of upgrading TypeDB easier.
116+
====
117+
118+
[cols=".^3,5"]
119+
|===
120+
2+^| Storage
121+
| `storage.data-directory`
122+
| Path to the user data directory. Defaults to within the server distribution under `server/data`. +
123+
|===
124+
125+
[#_diagnostics]
126+
=== Diagnostics
127+
128+
TypeDB optionally reports anonymous diagnostics to guide the development and optimisation of TypeDB.
129+
This data includes unexpected errors and occasional system status updates for number and size of databases, as well as numbers of transactions and queries executed per hour.
130+
131+
To see what information is being reported, enable and access the monitoring Web page of the server (e.g. `localhost:4104/diagnostics?format=json`).
132+
133+
[cols=".^3,5"]
134+
|===
135+
2+^| Diagnostics
136+
| `diagnostics.reporting.metrics`
137+
| Enable usage metrics reporting by setting a boolean flag. Default value: `true`. +
138+
139+
| `diagnostics.reporting.errors`
140+
| Enable critical error reporting by setting a boolean flag. Default value: `true`. +
141+
142+
| `diagnostics.monitoring.enable`
143+
| Enable a diagnostics monitoring HTTP endpoint by setting a boolean flag. Default value: `true`. +
144+
145+
| `diagnostics.monitoring.port`
146+
| Port on which to expose the diagnostics monitoring endpoint. Default value: `4104`. +
147+
148+
|===
149+
150+
[#_log]
151+
=== Logging
152+
153+
You can configure the directory that TypeDB uses for server logs.
154+
[cols=".^3,5"]
155+
|===
156+
2+^| Logging
157+
| `logging.directory`
158+
| Path to the server logs directory. Defaults to within the server distribution under `server/logs`. +
159+
|===
160+
161+
[#_machine_requirements]
162+
== Host machine configuration
163+
This section describes recommended changes to the host OS.
164+
165+
=== Open file limit
166+
167+
To support large data volumes, it is important to check the open file limit the operating system imposes.
168+
Some Unix distributions default to `1024` open file descriptors.
169+
This can be checked with the following command:
170+
171+
[source,bash]
172+
----
173+
ulimit -n
174+
----
175+
176+
We recommend this is increased to at least `50 000`.

‎maintenance-operation/modules/ROOT/pages/typedb-in-flight-encryption.adoc

Lines changed: 81 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,83 @@
11
= TypeDB In-flight Encryption
22

3-
[placeholder]
4-
Configure in-flight encryption for TypeDB servers.
3+
Communication with a TypeDB server can be secured using TLS.
4+
TLS serves two purposes:
5+
6+
1. Encrypting connections to prevent eavesdropping
7+
2. Authenticating the server's identity by validating its certificate is signed by a trusted issuing authority.
8+
9+
To enable TLS, TypeDB must be configured with a private-key & certificate.
10+
The relevant fields in the config file are:
11+
[,yaml]
12+
----
13+
server:
14+
...
15+
encryption:
16+
enabled: true
17+
certificate: /path/to/certificate
18+
certificate-key: /path/to/private-key
19+
# Optional:
20+
ca-certificate: /path/to/ca-certificate
21+
----
22+
23+
== Self-signed certificates for development
24+
We start with a quick, non-mathematical refresher.
25+
26+
=== Public & private keys
27+
A key-pair consists of a private & public key
28+
which together can be used for encrypted communication, and digital signatures.
29+
30+
For encrypted communication, a server sends over the "public" key to the client.
31+
The client uses this key to encrypt messages, which the server can decrypt using its private key.
32+
33+
For signatures, the private key is used to sign a message. This signature can be verified using the corresponding public key.
34+
35+
[IMPORTANT]
36+
====
37+
It is *critical* the private key remains confidential
38+
to prevent others from decrypting messages or forging signatures.
39+
====
40+
41+
=== Certificates
42+
43+
A server establishes its identity by sending over a certificate.
44+
A certificate contains a public-key, some metadata for the identity, and a signature.
45+
The authenticity of the certificate is verified by validating that it has been signed by some other certificate that we "trust".
46+
47+
Typically, an Operating System comes pre-loaded with certificates of few major certificate authorities (CA) that are trusted in the real world - such as Verisign.
48+
A user can choose to trust any certificate, including ones that they have created & signed themselves.
49+
The https://github.com/FiloSottile/mkcert[mkcert] utility can be used to easily generate self-signed certificates.
50+
51+
=== Self-signed certificates with mkcert
52+
53+
On first use, `mkcert` creates a fresh CA certificate & signing key for your machine.
54+
It will use this to sign any certificates it generates.
55+
To see the location of these files, run `mkcert -CAROOT`.
56+
You will see `rootCA-key.pem` and `rootCA.pem` at the location.
57+
58+
The following command generates a `private-key.pem` and corresponding `certificate.pem`,
59+
valid for a server with hostname `localhost`, or IP `127.0.0.1`
60+
[,sh]
61+
----
62+
mkcert -cert-file certificate.pem -key-file private-key.pem localhost 127.0.0.1
63+
----
64+
65+
We now have 4 files:
66+
67+
* `rootCA-key.pem`: The private-key `mkcert` uses to sign certificates. Only `mkcert` needs this.
68+
* `rootCA.pem`: The certificate generated from and (self) signed by `rootCA-key.pem`. TypeDB drivers can use this to authenticate the server.
69+
* `private-key.pem`: The private-key for the server. To be configured as `server.encryption.certificate-key`
70+
* `certificate.pem`: The certificate for the server generated from `private-key.pem`, and signed by `rootCA-key.pem`. To be configured as `server.encryption.certificate`
71+
72+
[NOTE]
73+
====
74+
Unless you have already run `mkcert -install`, you will have seen the following error:
75+
[,]
76+
----
77+
Note: the local CA is not installed in the system trust store.
78+
Run "mkcert -install" for certificates to be trusted automatically ⚠️
79+
----
80+
As the message suggests, you can add the `rootCA.pem` certificate to the system's trust store.
81+
Most applications will "trust" any certificates signed by a CA in the store.
82+
Then you will not need to configure TypeDB drivers running on that system to trust `rootCA.pem`
83+
====

0 commit comments

Comments
 (0)