diff options
Diffstat (limited to 'content/documentation/reference-manual/configuration.md')
| -rw-r--r-- | content/documentation/reference-manual/configuration.md | 241 |
1 files changed, 0 insertions, 241 deletions
diff --git a/content/documentation/reference-manual/configuration.md b/content/documentation/reference-manual/configuration.md deleted file mode 100644 index 72c22d1..0000000 --- a/content/documentation/reference-manual/configuration.md +++ /dev/null @@ -1,241 +0,0 @@ -+++ -title = "Configuration file format" -weight = 5 -+++ - - -Here is an example `garage.toml` configuration file that illustrates all of the possible options: - -```toml -metadata_dir = "/var/lib/garage/meta" -data_dir = "/var/lib/garage/data" - -block_size = 1048576 - -replication_mode = "3" - -compression_level = 1 - -rpc_secret = "4425f5c26c5e11581d3223904324dcb5b5d5dfb14e5e7f35e38c595424f5f1e6" -rpc_bind_addr = "[::]:3901" -rpc_public_addr = "[fc00:1::1]:3901" - -bootstrap_peers = [ - "563e1ac825ee3323aa441e72c26d1030d6d4414aeb3dd25287c531e7fc2bc95d@[fc00:1::1]:3901", - "86f0f26ae4afbd59aaf9cfb059eefac844951efd5b8caeec0d53f4ed6c85f332[fc00:1::2]:3901", - "681456ab91350f92242e80a531a3ec9392cb7c974f72640112f90a600d7921a4@[fc00:B::1]:3901", - "212fd62eeaca72c122b45a7f4fa0f55e012aa5e24ac384a72a3016413fa724ff@[fc00:F::1]:3901", -] - -consul_host = "consul.service" -consul_service_name = "garage-daemon" - -sled_cache_capacity = 134217728 -sled_flush_every_ms = 2000 - -[s3_api] -api_bind_addr = "[::]:3900" -s3_region = "garage" -root_domain = ".s3.garage" - -[s3_web] -bind_addr = "[::]:3902" -root_domain = ".web.garage" -index = "index.html" -``` - -The following gives details about each available configuration option. - -## Available configuration options - -#### `metadata_dir` - -The directory in which Garage will store its metadata. This contains the node identifier, -the network configuration and the peer list, the list of buckets and keys as well -as the index of all objects, object version and object blocks. - -Store this folder on a fast SSD drive if possible to maximize Garage's performance. - -#### `data_dir` - -The directory in which Garage will store the data blocks of objects. -This folder can be placed on an HDD. The space available for `data_dir` -should be counted to determine a node's capacity -when [configuring it](/documentation/reference-manual/layout/). - -#### `block_size` - -Garage splits stored objects in consecutive chunks of size `block_size` -(except the last one which might be smaller). The default size is 1MB and -should work in most cases. If you are interested in tuning this, feel free -to do so (and remember to report your findings to us!). If this value is -changed for a running Garage installation, only files newly uploaded will be -affected. Previously uploaded files will remain available. This however -means that chunks from existing files will not be deduplicated with chunks -from newly uploaded files, meaning you might use more storage space that is -optimally possible. - -#### `replication_mode` - -Garage supports the following replication modes: - -- `none` or `1`: data stored on Garage is stored on a single node. There is no redundancy, - and data will be unavailable as soon as one node fails or its network is disconnected. - Do not use this for anything else than test deployments. - -- `2`: data stored on Garage will be stored on two different nodes, if possible in different - zones. Garage tolerates one node failure before losing data. Data should be available - read-only when one node is down, but write operations will fail. - Use this only if you really have to. - -- `3`: data stored on Garage will be stored on three different nodes, if possible each in - a different zones. - Garage tolerates two node failure before losing data. Data should be available - read-only when two nodes are down, and writes should be possible if only a single node - is down. - -Note that in modes `2` and `3`, -if at least the same number of zones are available, an arbitrary number of failures in -any given zone is tolerated as copies of data will be spread over several zones. - -**Make sure `replication_mode` is the same in the configuration files of all nodes. -Never run a Garage cluster where that is not the case.** - -Changing the `replication_mode` of a cluster might work (make sure to shut down all nodes -and changing it everywhere at the time), but is not officially supported. - -### `compression_level` - -Zstd compression level to use for storing blocks. - -Values between `1` (faster compression) and `19` (smaller file) are standard compression -levels for zstd. From `20` to `22`, compression levels are referred as "ultra" and must be -used with extra care as it will use lot of memory. A value of `0` will let zstd choose a -default value (currently `3`). Finally, zstd has also compression designed to be faster -than default compression levels, they range from `-1` (smaller file) to `-99` (faster -compression). - -If you do not specify a `compression_level` entry, garage will set it to `1` for you. With -this parameters, zstd consumes low amount of cpu and should work faster than line speed in -most situations, while saving some space and intra-cluster -bandwidth. - -If you want to totally deactivate zstd in garage, you can pass the special value `'none'`. No -zstd related code will be called, your chunks will be stored on disk without any processing. - -Compression is done synchronously, setting a value too high will add latency to write queries. - -This value can be different between nodes, compression is done by the node which receive the -API call. - -#### `rpc_secret` - -Garage uses a secret key that is shared between all nodes of the cluster -in order to identify these nodes and allow them to communicate together. -This key should be specified here in the form of a 32-byte hex-encoded -random string. Such a string can be generated with a command -such as `openssl rand -hex 32`. - -#### `rpc_bind_addr` - -The address and port on which to bind for inter-cluster communcations -(reffered to as RPC for remote procedure calls). -The port specified here should be the same one that other nodes will used to contact -the node, even in the case of a NAT: the NAT should be configured to forward the external -port number to the same internal port nubmer. This means that if you have several nodes running -behind a NAT, they should each use a different RPC port number. - -#### `rpc_public_addr` - -The address and port that other nodes need to use to contact this node for -RPC calls. **This parameter is optional but recommended.** In case you have -a NAT that binds the RPC port to a port that is different on your public IP, -this field might help making it work. - -#### `bootstrap_peers` - -A list of peer identifiers on which to contact other Garage peers of this cluster. -These peer identifiers have the following syntax: - -``` -<node public key>@<node public IP or hostname>:<port> -``` - -In the case where `rpc_public_addr` is correctly specified in the -configuration file, the full identifier of a node including IP and port can -be obtained by running `garage node id` and then included directly in the -`bootstrap_peers` list of other nodes. Otherwise, only the node's public -key will be returned by `garage node id` and you will have to add the IP -yourself. - -#### `consul_host` and `consul_service_name` - -Garage supports discovering other nodes of the cluster using Consul. -This works only when nodes are announced in Consul by an orchestrator such as Nomad, -as Garage is not able to announce itself. - -The `consul_host` parameter should be set to the hostname of the Consul server, -and `consul_service_name` should be set to the service name under which Garage's -RPC ports are announced. - -#### `sled_cache_capacity` - -This parameter can be used to tune the capacity of the cache used by -[sled](https://sled.rs), the database Garage uses internally to store metadata. -Tune this to fit the RAM you wish to make available to your Garage instance. -More cache means faster Garage, but the default value (128MB) should be plenty -for most use cases. - -#### `sled_flush_every_ms` - -This parameters can be used to tune the flushing interval of sled. -Increase this if sled is thrashing your SSD, at the risk of losing more data in case -of a power outage (though this should not matter much as data is replicated on other -nodes). The default value, 2000ms, should be appropriate for most use cases. - - -## The `[s3_api]` section - -#### `api_bind_addr` - -The IP and port on which to bind for accepting S3 API calls. -This endpoint does not suport TLS: a reverse proxy should be used to provide it. - -#### `s3_region` - -Garage will accept S3 API calls that are targetted to the S3 region defined here. -API calls targetted to other regions will fail with a AuthorizationHeaderMalformed error -message that redirects the client to the correct region. - -#### `root_domain` - -The optionnal suffix to access bucket using vhost-style in addition to path-style request. -Note path-style requests are always enabled, whether or not vhost-style is configured. -Configuring vhost-style S3 required a wildcard DNS entry, and possibly a wildcard TLS certificate, -but might be required by softwares not supporting path-style requests. - -If `root_domain` is `s3.garage.eu`, a bucket called `my-bucket` can be interacted with -using the hostname `my-bucket.s3.garage.eu`. - -## The `[s3_web]` section - -Garage allows to publish content of buckets as websites. This section configures the -behaviour of this module. - -#### `bind_addr` - -The IP and port on which to bind for accepting HTTP requests to buckets configured -for website access. -This endpoint does not suport TLS: a reverse proxy should be used to provide it. - -#### `root_domain` - -The optionnal suffix appended to bucket names for the corresponding HTTP Host. - -For instance, if `root_domain` is `web.garage.eu`, a bucket called `deuxfleurs.fr` -will be accessible either with hostname `deuxfleurs.fr.web.garage.eu` -or with hostname `deuxfleurs.fr`. - -#### `index` - -The name of the index file to return for requests ending with `/` (usually `index.html`). |