memcached.json - memcached configuration file
memcached.json is a JSON encoded file specifying the properties used to configure the memcached server. Some of the parameters may be changed at runtime by instructing memcached to reread the configuration file. These properties is explicitly marked as such.
The following sections describes the various attributes that may be specified.
The breakpad attribute is used to configure the Breakpad crash catcher. When enabled (and on a supported platform), if memcached crashes a minidump containing information on the state of memcached will be written to disk. It is an object with the following attributes:
enabled A boolean value specifying if Breakpad is enabled.
If true (and *minidump_dir* is set) minidumps will
be output to directory specified by *minidump_dir*.
If not specified then defaults to false.minidump_dir A string value specifying the directory to write any
outputted minidumps to. If not specified then
Breakpad is not enabled.content A string value specifying what data will be included
in generated minidumps. Currently the only permitted
value is "default".enabled, minidump_dir and content may be modified at runtime by instructing memcached to reread the configuration file.
The privilege_debug attribute is a boolean value that may be set (in development) to make all missing privilege calls return success (and the missing privilege is logged). See docs/rbac.md for more information.
The threads attribute specify the number of threads used to serve clients. By default this number is set to 75% of the number of cores available on the system (but no less than 4). The value for threads should be specified as an integral number.
The tcp_keepalive_idle attribute is an integral value specifying the number of seconds before the first TCP keepalive probe gets sent. Set the value to 0 to use the operating system default value.
The tcp_keepalive_interval attribute is an integral value specifying the number of seconds between each TCP keepalive probe gets sent.Set the value to 0 to use the operating system default value.
The tcp_keepalive_probes attribute is an integral value specifying the number keepalive probes which should be sent before marking the connection as dead. Set the value to 0 to use the operating system default value.
The tcp_user_timeout attribute is an integral value specifying the number of seconds data may be stuck in the send buffer before closing the connection. This only applies to connections binding to the user interface (and is only available on Linux). Setting the value to 0 (default) disable the functionality.
The tcp_unauthenticated_user_timeout attribute is an integral value specifying the number of seconds data may be stuck in the send buffer before closing the connection. This only applies to connections binding to the user interface (and is only available on Linux). Setting the value to 0 (default) disable the functionality. Once the client successfully authenticates the value gets replaced with tcp_user_timeout.
The prometheus is a object with the following properties:
port The port number to bind to
family The address family to use (IPv4/IPv6)The phosphor_config attribute is used to provide the configuration to use for Phosphor tracing. It is specified in a string value. By default a ring buffer of 20MB is used with all categories enabled.
|
Note
|
The in order to change the configuration one would also need to stop and start phosphor via ioctl command. |
The interfaces attribute is used to specify an array of interfaces memcached should listen at. Each entry in the interfaces array is an object describing a single interface with the following properties:
tag A string value specifying a name for the interface
to allow the server to find the interface if an
ephemeral port is being used (port = 0)system Set to true if this interface is to be considered as
a system interface (with its own connection limit).
Set to false if this interface is to be used for normal
connections.host A string value specifying the hostname to bind to.
If the attribute is missing (or set to "*")
IN_ADDR_ANY is used.port An integral number specifying the port numberIPv4 & IPv6 A string value specifying if the given protocol (IPv4 or
IPv6) should be enabled, and if so how failure to bind should
be handled. Permitted values:"required" The specified protocol must be enabled on this
interface. If it cannot be enabled, then
memcached will fail to start."optional" The specified protocol should be enabled on this
interface. If it cannot be enabled, then permit
memcached to still start."off" Do not attempt to enable the specified protocol
on this interface.The default value is "optional".Backward compatability note: To support old configurations
(before the tri-state string was introduced), a boolean value
is accepted which maps to the above string values:true -> "optional"
false -> "off"tls Boolean if TLS should be used or notThe stdin_listener attribute is a boolean attribute set to true if the standard input listener should be used or not.
The default_reqs_per_event attribute is an integral value specifying the number of request that may be served per client before serving the next client (to avoid starvation). The default value is 20.
default_reqs_per_event may be updated by instructing memcached to reread the configuration file.
The reqs_per_event_high_priority attribute is an integral value specifying the number of request that may be served per high priority client before serving the next client (to avoid starvation). The default value is 20.
reqs_per_event_high_priority may be updated by instructing memcached to reread the configuration file.
The reqs_per_event_med_priority attribute is an integral value specifying the number of request that may be served per medium priority client before serving the next client (to avoid starvation). The default value is 20.
reqs_per_event_med_priority may be updated by instructing memcached to reread the configuration file.
The reqs_per_event_low_priority attribute is an integral value specifying the number of request that may be served per low priority client before serving the next client (to avoid starvation). The default value is 20.
reqs_per_event_low_priority may be updated by instructing memcached to reread the configuration file.
The command_time_slice attribute is an integral value specifying the number of milliseconds a connection may spend executing commands before backing off the CPU
The verbosity attribute is an integral value specifying the amount of output produced by the memcached server. By default this value is set to 0 resulting in only warnings to be emitted. Setting this value too high will produce a lot of output which is most likely meaningless for most people.
verbosity may be updated by instructing memcached to reread the configuration file.
The connection_idle_time attribute is an integral value specifying the number of seconds a connection may be idle until the server will disconnect.
By default the connection idle time is set to 5 minutes.
connection_idle_time may be updated by instructing memcached to reread the configuration file.
The connection_limit_mode attribute is a string value specifying how the system should behave when it reach the maximum number of user connections. It may be one of the following values:
disconnect Accept the new connection and immediately close the
socket and disconnect the client. This is the default
behavior if no mode is specified.recycle Accept the connection and immediately try to disconnect
a client which is "least recently used" on the thread
chosen to serve the client. Once 99% of the user
connections (or the number specified by
*free_connection_pool_size* described below) are in
use the system will try to disconnect another client.
Once the hard limit is reached new connections will
be disconnected immediately.Note that this mode only applies to user connections and connections not bound to the system interfaces. Connections authenticated as internal users will not be forcefully disconnected.
The free_connection_pool_size attribute is an integral number specifying the size of the pool the system should try to keep available (by disconnecting least recently used connections) in "connection_limit_mode=recycle". If not specified the number is 1% of the maximum user connections.
The datatype_json attribute is a boolean value to enable the support for using the datatype JSON extension. By default this support is enabled.
The datatype_snappy attribute is a boolean value to enable the support for using the datatype snappy extension. By default this support is enabled.
The max_packet_size attribute is an integer value that specify the maximum packet size (in MB) allowed to be received from clients without disconnecting them. This is a safetynet for avoiding the server to try to spool up a 4GB packet. When a packet is received on the network with a body bigger than this threshold EINVAL is returned to the client and the client is disconnected.
the sasl_mechanisms attribute is a string value containing the SASL mechanisms that should be available for clients. It is not a dynamic value and require restart in order to change.
the ssl_sasl_mechanisms attribute is a string value containing the SASL
mechanisms that should be available for clients connecting over SSL.
It is not a dynamic value and require restart in order to change.
By default this value is set to PLAIN (the default value may be cleared
by setting the environment variable COUCHBASE_I_DONT_TRUST_SSL to a
non-null value.
The client_cert_auth object is used to enable client certificate authentication and control how the username is extracted from the client certificate. It contains the following attributes.
state. Possible values for this paramters can be disabled, enabled or mandatory. When enabled, if the server will request a certificate from the client but if the certificate cannot be verified it will stil allow the connection. In mandatory mode, the client connection is dropped if the client certificate cannot be verified.
The path attribute specifies the field which will be used to extract the username from the certificate and map that to user defined in Couchbase. Currently only subject.cn, san.uri, san.email and san.dnsname are allowed. This attribute is optional, however if defined, then the provided client certificates must contain the fields which is used for the mapping, and the user must be defined in Couchbase for the connection to be established.
The prefix attribute specifices the prefix value to be ignored while extracting the username from the certificate.
The delimiter attribute can be a string of characters and the parsing of the username ends when one of the characters in the string is found.
The max_concurrent_authentications attribute is a number used to set the maximum number of concurrent authentication tasks to run in parallel. By default it is set to 6.
The dedupe_nmvb_maps attribute is a boolean value to enable deduplication of the cluster maps in the "Not My VBucket" response messages sent to the clients. By default this value is set to false.
A directory containing one or more JSON-formatted error maps. The error maps are returned to the client using the GET_ERROR_MAP protocol command. Multiple error maps correspond to multiple versions.
The format of the error map itself is described in docs/ErrorMap.md
The xattrs_enabled attribute is a boolean value to enable or disable the use of extended attributes on documents. It may be overridden by privileged connections to allow them to set up replication streams before users create them.
The tracing_enabled attribute is a boolean value to enable or disable retrieving tracedata from the server. If enabled, the time the request took on the server will be sent back as a part of the response.
The external_auth_service attribute is a boolean value to enable or disable the use of an external authentication service.
The active_external_users_push_interval attribute is a numeric parameter to specify the number of seconds between each time memcached push the set of active external users to the authentication providers.
The opcode-attributes-override attribute is an object which follows the syntax outlined in etc/couchbase/kv/opcode-attributes.d/README.md
The max_send_queue_size attribute is an unsigned number used to specify the limit (in MB) of data we may insert in the send queue for a given client before we stop accept new commands and wait for the client to drain the socket. The motivation is to make sure that we don’t end up consuming GB of memory serving a single client. The max queue size is set to 40MB by default (2x the max document size)
The max_so_sndbuf_size attribute is an unsigned number used to specify the max size to set SO_SNDBUF to for authenticated clients. (NOTE: The settings in the operating system may cause a lower value to be used, and the system will try to use the highest permitted value)
Specifies the number of reader or writer threads, respectively. The value can be encoded either a string specifying a mode which memcached will interpret to calculate the number of threads, of as a unsigned number specifying the exact number. Possible values:
- "default" or 0
-
Configure the number of threads based on the properties of the running system (currently logical CPU core count, capped at conservative values).
- "disk_io_optimized"
-
Configure the number of for optimized disk throughput / latency based on the properties of the running system (currently logical CPU core count, with higher caps than
"default"). - <positive integer>
-
Use the exact number of threads specified.
Specifies the number of AuxIO or NonIO threads, respectively. The value as an unsigned number specifying the exact number.
Possible values:
- "default" or 0
-
Configure the number of threads based on the properties of the running system (currently logical CPU core count, capped at conservative values).
- <positive integer>
-
Use the exact number of threads specified.
Specifies the number of storage backend threads. If 0 means that memcached should use the default number of storage threads which is calculated as 3 x num_writer_threads.
The logger attribute is used to specify properties for the logger used by memcached. It is an object with the following properties:
filename The prefix of the files to use for logging. The
logger appends: nnnnnn.txt to the prefix specified
where nnnnnn is replaced with a sequence number.
If no filename is specified, no files will be written.buffersize The buffers used by the logger to buffer data before
dumping to disk. This property is only used when
filename is present.cyclesize The number of bytes to write to a file before starting
a new one.sleeptime The number of seconds to allow buffering before flushing
to disk.unit_test Boolean variable set to true when used for unit testsconsole Boolean variable (defaults to true) if log messages
should be sent to standard error as well.A Sample memcached.json:
{
"root" : "/opt/couchbase",
"breakpad" :
{
"enabled" : true,
"minidump_dir" : "/opt/couchbase/var/crash",
"content" : "default"
},
"audit_file" : "/opt/couchbase/etc/security/audit.json",
"rbac_file" : "/opt/couchbase/etc/security/rbac.json",
"privilege_debug" : false,
"error_maps_dir": "/opt/couchbase/etc/error_maps",
"threads" : 4,
"interfaces" :
[
{
"tag" : "ssl",
"host" : "*",
"port" : 11209,
"IPv4" : true,
"IPv6" : true,
"tls" : true
}
],
"stdin_listener" : false,
"default_reqs_per_event" : 20,
"reqs_per_event_high_priority" : 40,
"reqs_per_event_med_priority" : 20,
"reqs_per_event_low_priority" : 10,
"verbosity" : 2,
"datatype_json" : true,
"datatype_snappy" : true,
"max_packet_size" : 25,
"max_send_queue_size" : 25,
"sasl_mechanisms" : "SCRAM-SHA512 SCRAM-SHA256 SCRAM-SHA1",
"dedupe_nmvb_maps" : true,
"xattr_enabled" : true,
"tracing_enabled" : true,
"external_auth_service" : false,
"active_external_users_push_interval" : 180,
"opcode-attributes-override": {
"version": 1,
"get": {
"slow": 200
}
}
}