import features pages

Author: dormando

content/features/restart.md

@@ -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.
+

content/features/tls.md

@@ -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.
+