-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
2 changed files
with
174 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,81 @@ | ||
+++ | ||
title = 'Warm Restart' | ||
date = 2024-09-04T13:57:33-07:00 | ||
+++ | ||
|
||
Memcached 1.5.18 and newer can recover its cache between clean restarts. It can restart after upgrades of the | ||
binary, most changes in settings, and so on. It now also supports | ||
using persistent memory via DAX filesystem mounts. See below for more details. | ||
|
||
Use it by adding: `-e /tmpfs_mount/memory_file` to your startup options. | ||
|
||
`/tmpfs_mount/` must be a ram disk of some sort, big enough to satisfy the | ||
memory limit specified on startup with `-m`. To gracefully restart; send a | ||
SIGUSR1 signal to the daemon, and wait for it to shut down and exit. | ||
|
||
It will create a `/tmpfs_mount/memory_file.meta` file on shutdown. On restart | ||
it will read this file and ensure the restart is compatible. If it is not | ||
compatible or the file is corrupt, it will start with a clean cache. | ||
|
||
If you change some parameters the cache will come up clean: | ||
|
||
- The memory limit (`-m`) | ||
- The max item size. | ||
- Slab chunk sizes. | ||
- Whether CAS is enabled or not. | ||
- Whether slab reassignment is allowed or not. | ||
|
||
... you are able to change all other options inbetween restarts! | ||
|
||
Important Caveats (see below for more detail): | ||
|
||
- System clock must be set correctly and must not jump while memcached | ||
is down. | ||
- Deletes, sets, adds, incr/decr/etc commands will be missed while instance | ||
restarts! | ||
- The earliest version you can restart from is 1.5.18. Older versions cannot | ||
upgrade to 1.5.18 without losing the cache. | ||
|
||
## DETAILS | ||
|
||
This works by putting memory related to item data into an external | ||
mmap file (specified via `-e`). All other memory: the hash table, connection | ||
memory, etc, stay in main RAM. When the daemon is restarted, it runs a pass | ||
over the item data and fixes up the internal pointers and regenerates | ||
the hash table. This typically takes a few seconds, but if you have close to a | ||
billion items in memory it can take two or three minutes. | ||
|
||
Once restarted, there is no performance difference between restartable and | ||
non-restartable modes. | ||
|
||
### DAX mounts and persistent memory | ||
|
||
If you have a persistent memory device, you can utilize this feature to extend | ||
memcached's memory into persistent memory. This does _not_ make | ||
memcached crash safe! It will put item memory into your persistent memory | ||
mount, while the rest of memory (hash table/buffers/etc) use system DRAM. This | ||
is a very high performance mode as the majority of memory accesses stay in DRAM. Also, with a graceful shutdown memcached can be | ||
restarted after reboots so long as the DAX mount persists. | ||
|
||
See your persistent memory vendor's documentation for how to configure a DAX | ||
mount. | ||
|
||
You can see extensive testing we did in this and other modes on our blog: https://memcached.org/blog/persistent-memory/ | ||
|
||
### CAVEATS | ||
|
||
Your system clock _must_ be set correctly, or at least it must not move before | ||
memcached has restarted. The only way to tell how much time has passed while | ||
the binary was dead, is to check the system clock. If the clock jumps forward | ||
or backwards it could impact items with a specific TTL. | ||
|
||
Users must keep in mind that while an instance is stopped, it may be missing | ||
updates from the network; deletes, sets, and so on. It is only safe to restart | ||
memcached if your architecture can handle this by either pausing/buffering | ||
updates, or restarting at a time when no changes are happening to the cache. | ||
|
||
### FUTURE WORK | ||
|
||
This feature is presently incompatible with extstore. Please let us know if | ||
you have other feedback or requests related to this feature. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,93 @@ | ||
+++ | ||
title = 'TLS Support' | ||
date = 2024-09-04T13:57:26-07:00 | ||
+++ | ||
|
||
This documentation is incomplete but the TLS support in memcached is stable. See `doc/tls.txt` in the repository for design and some implementation details. | ||
|
||
## Quick Start | ||
|
||
Memcached 1.5.13+ supports authentication and encryption via TLS. This requires: | ||
- OpenSSL 1.1.1 or later | ||
- Memcached client which can communicate over TLS | ||
- Server built using ./configure --enable-tls. | ||
|
||
### When to use this? | ||
|
||
- Encryption: data is required to be encrypted on the wire between clients and the server. | ||
- Authentication : server and client are required to authenticate each other. | ||
- Data integrity: ensure data is not tampered or altered when transmitted between client and server. | ||
|
||
### How to use it? | ||
|
||
Grab the latest memcached. | ||
|
||
Build with `./configure --enable-tls && make && make test && sudo make install` | ||
|
||
Obtain a valid certificate and a key | ||
|
||
Use your normal startup options and add `-Z -o ssl_chain_cert=/home/user/cert,ssl_key=/home/user/key` | ||
|
||
`-Z` (or `--enable-ssl`) enables the TLS and `ssl_chain_cert` and `ssl_key` to specify the cert and the key. | ||
|
||
If you have trouble starting the server, use verbose levels ('memcached -v') to print errors and warnings. | ||
|
||
If there are no errors, all TCP interfaces you’ve specified support TLS. | ||
|
||
You can quickly test the server with OpenSSL `s_client`. | ||
|
||
`$ openssl s_client -connect host:port` | ||
|
||
### Other options | ||
You can obtain all available options using the `memcached -h` | ||
|
||
If required, you can specify a different private key format using `-o ssl_keyformat=`. The default format is PEM (1). This value has to be an integer. Refer to OpenSSL certificate formats for more details. | ||
|
||
To change the peer certificate verification mode, use `-o ssl_verify_mode=`. Default is 0 (None). Valid values are 0 (None), 1 (Request), 2 (Require) or 3 (Once). Refer OpenSSL verification modes for more details. | ||
|
||
To limit supported ciphers, use `-o ssl_ciphers=`. Refer OpenSSL cipher names for valid options. | ||
|
||
If required, provide a CA cert using `-o ssl_ca_cert=`. Only PEM file format is accepted. | ||
|
||
If you invalidate old server certificates, received new ones and requires memcached to use them, you don’t need to restart the server. | ||
Connect with the server and run the `refresh_certs` command. | ||
Memcached will reload new certificates (cert name and paths has to be same as the original ones) and new connections will use new certificates. | ||
Existing connections will continue to use session keys created using old certificates. | ||
|
||
You can opt out TLS for certain interfaces (e.g. use plain text on localhost). This can be specified via `-l` or `--listen=`. Add `notls:` prefix to the interfaces that don’t require TLS. | ||
E.g. `-l notls:<host>:<port>` | ||
|
||
### Monitoring | ||
You can increase the verbosity of the server to print detailed error/warning messages. | ||
|
||
`stats settings` command will show the current TLS settings, prefixed with `ssl_`. | ||
|
||
`stats` will print `time_since_server_cert_refresh`. This shows the number of seconds elapsed since server loaded certificates. This is helpful when you need to refresh certificates. | ||
|
||
### How to tune it? | ||
|
||
The current TLS implementation splits large messages (more than 16K by default) and send them in chunks. | ||
|
||
This limit can be increased via `--o ssl_wbuf_size=` option. The size is in KB and the default is 16KB. | ||
This buffer is allocated at each worker thread level; hence you can calculate the memory budget (in KB) by `ssl_wbuf_size * number of worker threads`. | ||
|
||
--- | ||
|
||
## Performance | ||
|
||
`TBD` | ||
|
||
--- | ||
|
||
## Session Resumption | ||
|
||
`TODO` see `memcached -h` | ||
|
||
--- | ||
|
||
## Quick notes | ||
|
||
See `doc/tls.txt` for design and some implementation details. | ||
See `memcached -h` for start arguments. | ||
Run `./configure --enable-tls` to compile the feature in. | ||
|