Skip to content

Commit 5cc1466

Browse files
kateandrewskateandrews
authored
Docs: Split our reference section
Signed-off-by: Kate Andrews <keandrews@gmail.com>
1 parent dd77c80 commit 5cc1466

1 file changed

Lines changed: 273 additions & 0 deletions

File tree

‎docs/reference.md‎

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
# CipherStash Proxy reference guide
2+
3+
This page contains reference documentation for configuring CipherStash Proxy and its features.
4+
5+
## Table of contents
6+
7+
- [Proxy config options](#proxy-config-options)
8+
- [Recommended settings for development](#recommended-settings-for-development)
9+
- [Prometheus metrics](#prometheus-metrics)
10+
- [Available metrics](#available-metrics)
11+
12+
13+
## Proxy config options
14+
15+
You can configure CipherStash Proxy with a config file, enviroment variables, or a combination of the two – see [Configuring Proxy](#configuring-proxy) for instructions.
16+
17+
The following are all the configuration options available for Proxy, with their equivalent environment variables:
18+
19+
```toml
20+
21+
[server]
22+
# Proxy host address
23+
# Optional
24+
# Default: `0.0.0.0`
25+
# Env: CS_SERVER__HOST
26+
host = "0.0.0.0"
27+
28+
# Proxy host posgt
29+
# Optional
30+
# Default: `6432`
31+
# Env: CS_SERVER__PORT
32+
port = "6432"
33+
34+
# Enforce TLS connections
35+
# Optional
36+
# Default: `false`
37+
# Env: CS_SERVER__REQUIRE_TLS
38+
require_tls = "false"
39+
40+
# Shutdown timeout in ms
41+
# Sets how long to wait for connections to drain on shutdown
42+
# Optional
43+
# Default: `2000`
44+
# Env: CS_SERVER__SHUTDOWN_TIMEOUT
45+
shutdown_timeout = "2000"
46+
47+
# Number of worker threads the server should use
48+
# Optional
49+
# Default: `NUMBER_OF_CORES/2` or `4`
50+
# Env: CS_SERVER__WORKER_THREADS
51+
worker_threads = "4"
52+
53+
# Thread stack size in bytes
54+
# Optional
55+
# Default: `2 * 1024 * 1024` (2MiB) or `4 * 1024 * 1024` (4MiB) if log level is DEBUG or TRACE
56+
# Env: CS_SERVER__THREAD_STACK_SIZE
57+
thread_stack_size = "2097152"
58+
59+
60+
[database]
61+
# Database host address
62+
# Optional
63+
# Default: `0.0.0.0`
64+
# Env: CS_DATABASE__HOST
65+
host = "0.0.0.0"
66+
67+
# Database host post
68+
# Optional
69+
# Default: `5432`
70+
# Env: CS_DATABASE__PORT
71+
port = "5432"
72+
73+
# Database name
74+
# Env: CS_DATABASE__NAME
75+
name = "database"
76+
77+
# Database username
78+
# Env: CS_DATABASE__USERNAME
79+
username = "username"
80+
81+
# Database password
82+
# Env: CS_DATABASE__PASSWORD
83+
password = "password"
84+
85+
# Connection timeout in ms
86+
# Sets how long to hold an open idle connection
87+
# In production environments this should be greater than the idle timeout of any connection pool in the application.
88+
#
89+
# Optional
90+
# No Default (NO TIMEOUT)
91+
# Env: CS_DATABASE__CONNECTION_TIMEOUT
92+
connection_timeout = "300000"
93+
94+
# Enable TLS verification
95+
# Optional
96+
# Default: `false`
97+
# Env: CS_DATABASE__WITH_TLS_VERIFICATION
98+
with_tls_verification = "false"
99+
100+
# Encrypt configuration reload interval in sec
101+
# Sets how frequently Encrypted index configuration should be reloaded
102+
# The configuration specifies the encrypted columns in the database
103+
# Optional
104+
# Default: `60`
105+
# Env: CS_DATABASE__CONFIG_RELOAD_INTERVAL
106+
config_reload_interval = "60"
107+
108+
# Schema configuration reload interval in sec
109+
# Sets how frequently the database schema should be reloaded
110+
# The schema is used to analyse SQL statements
111+
# Optional
112+
# Default: `60`
113+
# Env: CS_DATABASE__SCHEMA_RELOAD_INTERVAL
114+
schema_reload_interval = "60"
115+
116+
117+
[tls]
118+
# Certificate path
119+
# Env: CS_TLS__CERTIFICATE_PATH
120+
certificate_path = "./server.cert"
121+
122+
# Private Key path
123+
# Env: CS_TLS__PRIVATE_KEY_PATH
124+
private_key_path = "./server.key"
125+
126+
# Certificate path
127+
# Env: CS_TLS__CERTIFICATE_PEM
128+
certificate_pem = "..."
129+
130+
# Private Key path
131+
# Env: CS_TLS__PRIVATE_KEY_PEM
132+
private_key_pem = "..."
133+
134+
135+
[auth]
136+
# CipherStash Workspace ID
137+
# Env: CS_WORKSPACE_ID
138+
workspace_id = "cipherstash-workspace-id"
139+
140+
# CipherStash Client Access Key
141+
# Env: CS_CLIENT_ACCESS_KEY
142+
client_access_key = "cipherstash-client-access-key"
143+
144+
[encrypt]
145+
# CipherStash Dataset ID
146+
# Env: CS_DEFAULT_KEYSET_ID
147+
default_keyset_id = "cipherstash-dataset-id"
148+
149+
# CipherStash Client ID
150+
# Env: CS_CLIENT_ID
151+
client_id = "cipherstash-client-id"
152+
153+
# CipherStash Client Key
154+
# Env: CS_CLIENT_KEY
155+
client_key = "cipherstash-client-key"
156+
157+
158+
[log]
159+
# Log level
160+
# Optional
161+
# Valid values: `error | warn | info | debug | trace`
162+
# Default: `info`
163+
# Env: CS_LOG__LEVEL
164+
level = "info"
165+
166+
# Log format
167+
# Optional
168+
# Valid values: `pretty | text | structured (json)`
169+
# Default: `pretty` if Proxy detects during startup that a terminal is attached, otherwise `structured`
170+
# Env: CS_LOG__FORMAT
171+
format = "pretty"
172+
173+
# Log format
174+
# Optional
175+
# Valid values: `stdout | stderr`
176+
# Default: `info`
177+
# Env: CS_LOG__OUTPUT
178+
output = "stdout"
179+
180+
# Enable ansi (colored) output
181+
# Optional
182+
# Default: `true` if Proxy detects during startup that a terminal is attached, otherwise `false`
183+
# Env: CS_LOG__ANSI_ENABLED
184+
ansi_enabled = "true"
185+
186+
187+
[prometheus]
188+
# Enable prometheus stats
189+
# Optional
190+
# Default: `false`
191+
# Env: CS_PROMETHEUS__ENABLED
192+
enabled = "false"
193+
194+
# Prometheus exporter post
195+
# Optional
196+
# Default: `9930`
197+
# Env: CS_PROMETHEUS__PORT
198+
port = "9930"
199+
```
200+
201+
### Recommended settings for development
202+
203+
The default configuration settings are biased toward running in production environments.
204+
Although Proxy attempts to detect the environment and set a sensible default for logging, your mileage may vary.
205+
206+
To turn on human-friendly logging:
207+
208+
```bash
209+
CS_LOG__FORMAT = "pretty"
210+
CS_LOG__ANSI_ENABLED = "true"
211+
```
212+
213+
If you are frequently changing the database schema or making updates to the column encryption configuration, it can be useful to reload the config and schema more frequently:
214+
215+
```bash
216+
CS_DATABASE__CONFIG_RELOAD_INTERVAL = "10"
217+
CS_DATABASE__SCHEMA_RELOAD_INTERVAL = "10"
218+
```
219+
220+
## Prometheus metrics
221+
222+
To enable a Prometheus exporter on the default port (`9930`) use either:
223+
224+
```toml
225+
[prometheus]
226+
enabled = "true"
227+
```
228+
229+
```env
230+
CS_PROMETHEUS__ENABLED = "true"
231+
```
232+
233+
When enabled, metrics can be accessed via `http://localhost:9930/metrics`.
234+
If the proxy is running on a host other than localhost, access on that host.
235+
236+
237+
### Available metrics
238+
239+
| Name | Target | Description |
240+
|-------------------------------------------------------|-----------|-----------------------------------------------------------------------------|
241+
| `cipherstash_proxy_clients_active_connections` | Gauge | Current number of connections to CipherStash Proxy from clients |
242+
| `cipherstash_proxy_clients_bytes_received_total` | Counter | Number of bytes received by CipherStash Proxy from clients |
243+
| `cipherstash_proxy_clients_bytes_sent_total` | Counter | Number of bytes sent from CipherStash Proxy to clients |
244+
| `cipherstash_proxy_decrypted_values_total` | Counter | Number of individual values that have been decrypted |
245+
| `cipherstash_proxy_decryption_duration_seconds` | Histogram | Duration of time CipherStash Proxy spent performing decryption operations |
246+
| `cipherstash_proxy_decryption_duration_seconds_count` | Counter | Number of observations of requests to CipherStash ZeroKMS to decrypt values |
247+
| `cipherstash_proxy_decryption_duration_seconds_sum` | Counter | Total time CipherStash Proxy spent performing decryption operations |
248+
| `cipherstash_proxy_decryption_error_total` | Counter | Number of decryption operations that were unsuccessful |
249+
| `cipherstash_proxy_decryption_requests_total` | Counter | Number of requests to CipherStash ZeroKMS to decrypt values |
250+
| `cipherstash_proxy_encrypted_values_total` | Counter | Number of individual values that have been encrypted |
251+
| `cipherstash_proxy_encryption_duration_seconds` | Histogram | Duration of time CipherStash Proxy spent performing encryption operations |
252+
| `cipherstash_proxy_encryption_duration_seconds_count` | Counter | Number of observations of requests to CipherStash ZeroKMS to encrypt values |
253+
| `cipherstash_proxy_encryption_duration_seconds_sum` | Counter | Total time CipherStash Proxy spent performing encryption operations |
254+
| `cipherstash_proxy_encryption_error_total` | Counter | Number of encryption operations that were unsuccessful |
255+
| `cipherstash_proxy_encryption_requests_total` | Counter | Number of requests to CipherStash ZeroKMS to encrypt values |
256+
| `cipherstash_proxy_rows_encrypted_total` | Counter | Number of encrypted rows returned to clients |
257+
| `cipherstash_proxy_rows_passthrough_total` | Counter | Number of non-encrypted rows returned to clients |
258+
| `cipherstash_proxy_rows_total` | Counter | Total number of rows returned |
259+
| `cipherstash_proxy_server_bytes_received_total` | Counter | Number of bytes CipherStash Proxy received from the PostgreSQL server |
260+
| `cipherstash_proxy_server_bytes_sent_total` | Counter | Number of bytes CipherStash Proxy sent to the PostgreSQL server |
261+
| `cipherstash_proxy_statements_duration_seconds` | Histogram | Duration of time CipherStash Proxy spent executing SQL statements |
262+
| `cipherstash_proxy_statements_duration_seconds_count` | Count | Number of observations of CipherStash Proxy statement duration |
263+
| `cipherstash_proxy_statements_duration_seconds_sum` | Count | Total time CipherStash Proxy spent executing SQL statements |
264+
| `cipherstash_proxy_statements_encrypted_total` | Counter | Number of SQL statements that required encryption |
265+
| `cipherstash_proxy_statements_passthrough_total` | Counter | Number of SQL statements that did not require encryption |
266+
| `cipherstash_proxy_statements_total` | Counter | Total number of SQL statements processed by CipherStash Proxy |
267+
| `cipherstash_proxy_statements_unmappable_total` | Counter | Total number of unmappable SQL statements processed by CipherStash Proxy |
268+
269+
---
270+
271+
### Didn't find what you wanted?
272+
273+
[Click here to let us know what was missing from our docs.](https://github.com/cipherstash/proxy/issues/new?template=docs-feedback.yml&title=[Docs:]%20Feedback%20on%20reference.md)

0 commit comments

Comments
 (0)