diff options
Diffstat (limited to 'content/documentation/reference-manual')
| l--------- | content/documentation/reference-manual | 1 | ||||
| -rw-r--r-- | content/documentation/reference-manual/_index.md | 11 | ||||
| -rw-r--r-- | content/documentation/reference-manual/cli.md | 8 | ||||
| -rw-r--r-- | content/documentation/reference-manual/configuration.md | 241 | ||||
| -rw-r--r-- | content/documentation/reference-manual/layout.md | 78 | ||||
| -rw-r--r-- | content/documentation/reference-manual/s3_compatibility.md | 64 |
6 files changed, 1 insertions, 402 deletions
diff --git a/content/documentation/reference-manual b/content/documentation/reference-manual new file mode 120000 index 0000000..268614b --- /dev/null +++ b/content/documentation/reference-manual @@ -0,0 +1 @@ +../../garage/doc/book/reference-manual
\ No newline at end of file diff --git a/content/documentation/reference-manual/_index.md b/content/documentation/reference-manual/_index.md deleted file mode 100644 index 2718f4e..0000000 --- a/content/documentation/reference-manual/_index.md +++ /dev/null @@ -1,11 +0,0 @@ -+++ -title = "Reference Manual" -weight = 4 -sort_by = "weight" -template = "documentation.html" -+++ - - -A reference manual contains some extensive descriptions about the features and the behaviour of the software. -Reading of this chapter is recommended once you have a good knowledge/understanding of Garage. -It will be useful if you want to tune it or to use it in some exotic conditions. diff --git a/content/documentation/reference-manual/cli.md b/content/documentation/reference-manual/cli.md deleted file mode 100644 index b6b8867..0000000 --- a/content/documentation/reference-manual/cli.md +++ /dev/null @@ -1,8 +0,0 @@ -+++ -title = "Garage CLI" -weight = 15 -+++ - - -The Garage CLI is mostly self-documented. Make use of the `help` subcommand -and the `--help` flag to discover all available options. 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`). diff --git a/content/documentation/reference-manual/layout.md b/content/documentation/reference-manual/layout.md deleted file mode 100644 index ab93d7c..0000000 --- a/content/documentation/reference-manual/layout.md +++ /dev/null @@ -1,78 +0,0 @@ -+++ -title = "Cluster layout management" -weight = 10 -+++ - - -The cluster layout in Garage is a table that assigns to each node a role in -the cluster. The role of a node in Garage can either be a storage node with -a certain capacity, or a gateway node that does not store data and is only -used as an API entry point for faster cluster access. -An introduction to building cluster layouts can be found in the [production deployment](/documentation/cookbook/real-world/) page. - -## How cluster layouts work in Garage - -In Garage, a cluster layout is composed of the following components: - -- a table of roles assigned to nodes -- a version number - -Garage nodes will always use the cluster layout with the highest version number. - -Garage nodes also maintain and synchronize between them a set of proposed role -changes that haven't yet been applied. These changes will be applied (or -canceled) in the next version of the layout - -The following commands insert modifications to the set of proposed role changes -for the next layout version (but they do not create the new layout immediately): - -```bash -garage layout assign [...] -garage layout remove [...] -``` - -The following command can be used to inspect the layout that is currently set in the cluster -and the changes proposed for the next layout version, if any: - -```bash -garage layout show -``` - -The following commands create a new layout with the specified version number, -that either takes into account the proposed changes or cancels them: - -```bash -garage layout apply --version <new_version_number> -garage layout revert --version <new_version_number> -``` - -The version number of the new layout to create must be 1 + the version number -of the previous layout that existed in the cluster. The `apply` and `revert` -commands will fail otherwise. - -## Warnings about Garage cluster layout management - -**Warning: never make several calls to `garage layout apply` or `garage layout -revert` with the same value of the `--version` flag. Doing so can lead to the -creation of several different layouts with the same version number, in which -case your Garage cluster will become inconsistent until fixed.** If a call to -`garage layout apply` or `garage layout revert` has failed and `garage layout -show` indicates that a new layout with the given version number has not been -set in the cluster, then it is fine to call the command again with the same -version number. - -If you are using the `garage` CLI by typing individual commands in your -shell, you shouldn't have much issues as long as you run commands one after -the other and take care of checking the output of `garage layout show` -before applying any changes. - -If you are using the `garage` CLI to script layout changes, follow the following recommendations: - -- Make all of your `garage` CLI calls to the same RPC host. Do not use the - `garage` CLI to connect to individual nodes to send them each a piece of the - layout changes you are making, as the changes propagate asynchronously - between nodes and might not all be taken into account at the time when the - new layout is applied. - -- **Only call `garage layout apply` once**, and call it **strictly after** all - of the `layout assign` and `layout remove` commands have returned. diff --git a/content/documentation/reference-manual/s3_compatibility.md b/content/documentation/reference-manual/s3_compatibility.md deleted file mode 100644 index 9a66610..0000000 --- a/content/documentation/reference-manual/s3_compatibility.md +++ /dev/null @@ -1,64 +0,0 @@ -+++ -title = "S3 Compatibility status" -weight = 20 -+++ - - -## Global S3 features - -Implemented: - -- path-style URLs (`garage.tld/bucket/key`) -- vhost-style URLs (`bucket.garage.tld/key`) -- putting and getting objects in buckets -- multipart uploads -- listing objects -- access control on a per-key-per-bucket basis - -Not implemented: - -- object-level ACL -- [object versioning](https://git.deuxfleurs.fr/Deuxfleurs/garage/issues/166) -- encryption -- most `x-amz-` headers - - -## Endpoint implementation - -All APIs that are not mentionned are not implemented and will return a 501 Not Implemented. - -| Endpoint | Status | -|------------------------------|----------------------------------| -| AbortMultipartUpload | Implemented | -| CompleteMultipartUpload | Implemented | -| CopyObject | Implemented | -| CreateBucket | Implemented | -| CreateMultipartUpload | Implemented | -| DeleteBucket | Implemented | -| DeleteBucketWebsite | Implemented | -| DeleteObject | Implemented | -| DeleteObjects | Implemented | -| GetBucketLocation | Implemented | -| GetBucketVersioning | Stub (see below) | -| GetBucketWebsite | Implemented | -| GetObject | Implemented | -| HeadBucket | Implemented | -| HeadObject | Implemented | -| ListBuckets | Implemented | -| ListObjects | Implemented, bugs? (see below) | -| ListObjectsV2 | Implemented | -| ListMultipartUpload | Implemented | -| ListParts | Implemented | -| PutObject | Implemented | -| PutBucketWebsite | Partially implemented (see below)| -| UploadPart | Implemented | -| UploadPartCopy | Implemented | - - -- **GetBucketVersioning:** Stub implementation (Garage does not yet support versionning so this always returns -"versionning not enabled"). - -- **ListObjects:** Implemented, but there isn't a very good specification of what `encoding-type=url` covers so there might be some encoding bugs. In our implementation the url-encoded fields are in the same in ListObjects as they are in ListObjectsV2. - -- **PutBucketWebsite:** Implemented, but only stores the index document suffix and the error document path. Redirects are not supported. - |