diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/book/connect/repositories.md | 2 | ||||
| -rw-r--r-- | doc/book/development/devenv.md | 6 | ||||
| -rw-r--r-- | doc/book/operations/multi-hdd.md | 4 | ||||
| -rw-r--r-- | doc/book/quick-start/_index.md | 4 | ||||
| -rw-r--r-- | doc/book/reference-manual/configuration.md | 22 | ||||
| -rw-r--r-- | doc/book/reference-manual/features.md | 2 | ||||
| -rw-r--r-- | doc/book/reference-manual/monitoring.md | 2 | ||||
| -rw-r--r-- | doc/book/working-documents/design-draft.md | 4 | ||||
| -rw-r--r-- | doc/book/working-documents/migration-04.md | 2 | ||||
| -rw-r--r-- | doc/book/working-documents/testing-strategy.md | 2 | ||||
| -rw-r--r-- | doc/drafts/k2v-spec.md | 2 |
11 files changed, 37 insertions, 15 deletions
diff --git a/doc/book/connect/repositories.md b/doc/book/connect/repositories.md index 66365d64..537b02e7 100644 --- a/doc/book/connect/repositories.md +++ b/doc/book/connect/repositories.md @@ -17,7 +17,7 @@ Garage can also help you serve this content. ## Gitea -You can use Garage with Gitea to store your [git LFS](https://git-lfs.github.com/) data, your users' avatar, and their attachements. +You can use Garage with Gitea to store your [git LFS](https://git-lfs.github.com/) data, your users' avatar, and their attachments. You can configure a different target for each data type (check `[lfs]` and `[attachment]` sections of the Gitea documentation) and you can provide a default one through the `[storage]` section. Let's start by creating a key and a bucket (your key id and secret will be needed later, keep them somewhere): diff --git a/doc/book/development/devenv.md b/doc/book/development/devenv.md index 88f8ba06..518fd232 100644 --- a/doc/book/development/devenv.md +++ b/doc/book/development/devenv.md @@ -36,7 +36,7 @@ sudo killall nix-daemon Now you can enter our nix-shell, all the required packages will be downloaded but they will not pollute your environment outside of the shell: ```bash -nix-shell +nix-shell -A devShell ``` You can use the traditional Rust development workflow: @@ -65,8 +65,8 @@ nix-build -j $(nproc) --max-jobs auto ``` Our build has multiple parameters you might want to set: - - `release` build with release optimisations instead of debug - - `target allows` for cross compilation + - `release` to build with release optimisations instead of debug + - `target` allows for cross compilation - `compileMode` can be set to test or bench to build a unit test runner - `git_version` to inject the hash to display when running `garage stats` diff --git a/doc/book/operations/multi-hdd.md b/doc/book/operations/multi-hdd.md index 36445b0a..1cbcd805 100644 --- a/doc/book/operations/multi-hdd.md +++ b/doc/book/operations/multi-hdd.md @@ -21,14 +21,14 @@ data_dir = [ ``` Garage will automatically balance all blocks stored by the node -among the different specified directories, proportionnally to the +among the different specified directories, proportionally to the specified capacities. ## Updating the list of storage locations If you add new storage locations to your `data_dir`, Garage will not rebalance existing data between storage locations. -Newly written blocks will be balanced proportionnally to the specified capacities, +Newly written blocks will be balanced proportionally to the specified capacities, and existing data may be moved between drives to improve balancing, but only opportunistically when a data block is re-written (e.g. an object is re-uploaded, or an object with a duplicate block is uploaded). diff --git a/doc/book/quick-start/_index.md b/doc/book/quick-start/_index.md index 5f17447b..b74500d5 100644 --- a/doc/book/quick-start/_index.md +++ b/doc/book/quick-start/_index.md @@ -199,7 +199,7 @@ For instance here you could write just `garage layout assign -z dc1 -c 1G 563e`. The layout then has to be applied to the cluster, using: ```bash -garage layout apply +garage layout apply --version 1 ``` @@ -349,7 +349,7 @@ Check [our s3 compatibility list](@/documentation/reference-manual/s3-compatibil ### Other tools for interacting with Garage -The following tools can also be used to send and recieve files from/to Garage: +The following tools can also be used to send and receive files from/to Garage: - [minio-client](@/documentation/connect/cli.md#minio-client) - [s3cmd](@/documentation/connect/cli.md#s3cmd) diff --git a/doc/book/reference-manual/configuration.md b/doc/book/reference-manual/configuration.md index 2779bd19..f0a3b438 100644 --- a/doc/book/reference-manual/configuration.md +++ b/doc/book/reference-manual/configuration.md @@ -13,6 +13,7 @@ consistency_mode = "consistent" metadata_dir = "/var/lib/garage/meta" data_dir = "/var/lib/garage/data" +metadata_snapshots_dir = "/var/lib/garage/snapshots" metadata_fsync = true data_fsync = false disable_scrub = false @@ -105,6 +106,7 @@ Top-level configuration options: [`metadata_auto_snapshot_interval`](#metadata_auto_snapshot_interval), [`metadata_dir`](#metadata_dir), [`metadata_fsync`](#metadata_fsync), +[`metadata_snapshots_dir`](#metadata_snapshots_dir), [`replication_factor`](#replication_factor), [`consistency_mode`](#consistency_mode), [`rpc_bind_addr`](#rpc_bind_addr), @@ -275,6 +277,7 @@ 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` {#data_dir} The directory in which Garage will store the data blocks of objects. @@ -295,6 +298,25 @@ data_dir = [ See [the dedicated documentation page](@/documentation/operations/multi-hdd.md) on how to operate Garage in such a setup. +#### `metadata_snapshots_dir` (since Garage `v1.0.2`) {#metadata_snapshots_dir} + +The directory in which Garage will store metadata snapshots when it +performs a snapshot of the metadata database, either when instructed to do +so from a RPC call or regularly through +[`metadata_auto_snapshot_interval`](#metadata_auto_snapshot_interval). + +By default, Garage will store snapshots into a `snapshots/` subdirectory +of [`metadata_dir`](#metadata_dir). This might quickly fill up your +metadata storage space if you use snapshots, because Garage will need up +to 4x the space of the existing metadata database: each snapshot requires +roughly as much space as the original database, and Garage temporarily +needs to store up to three different snapshots before it cleans up the oldest +snapshot to go back to two stored snapshots. + +To prevent filling your disk, you might to change this setting to a +directory with ample available space, e.g. on the same storage space as +[`data_dir`](#data_dir). + #### `db_engine` (since `v0.8.0`) {#db_engine} Since `v0.8.0`, Garage can use alternative storage backends as follows: diff --git a/doc/book/reference-manual/features.md b/doc/book/reference-manual/features.md index 34f692cc..481aef01 100644 --- a/doc/book/reference-manual/features.md +++ b/doc/book/reference-manual/features.md @@ -61,7 +61,7 @@ directed to a Garage cluster can be handled independently of one another instead of going through a central bottleneck (the leader node). As a consequence, requests can be handled much faster, even in cases where latency between cluster nodes is important (see our [benchmarks](@/documentation/design/benchmarks/index.md) for data on this). -This is particularly usefull when nodes are far from one another and talk to one other through standard Internet connections. +This is particularly useful when nodes are far from one another and talk to one other through standard Internet connections. ### Web server for static websites diff --git a/doc/book/reference-manual/monitoring.md b/doc/book/reference-manual/monitoring.md index 53608d95..4696791e 100644 --- a/doc/book/reference-manual/monitoring.md +++ b/doc/book/reference-manual/monitoring.md @@ -392,7 +392,7 @@ table_merkle_updater_todo_queue_length{table_name="block_ref"} 0 #### `table_sync_items_received`, `table_sync_items_sent` (counters) -Number of data items sent to/recieved from other nodes during resync procedures +Number of data items sent to/received from other nodes during resync procedures ``` table_sync_items_received{from="<remote node>",table_name="bucket_v2"} 3 diff --git a/doc/book/working-documents/design-draft.md b/doc/book/working-documents/design-draft.md index 6560dbed..8d3a31f0 100644 --- a/doc/book/working-documents/design-draft.md +++ b/doc/book/working-documents/design-draft.md @@ -42,7 +42,7 @@ The general principle are similar, but details have not been updated.** A version is defined by the existence of at least one entry in the blocks table for a certain version UUID. We must keep the following invariant: if a version exists in the blocks table, it has to be referenced in the objects table. We explicitly manage concurrent versions of an object: the version timestamp and version UUID columns are index columns, thus we may have several concurrent versions of an object. -Important: before deleting an older version from the objects table, we must make sure that we did a successfull delete of the blocks of that version from the blocks table. +Important: before deleting an older version from the objects table, we must make sure that we did a successful delete of the blocks of that version from the blocks table. Thus, the workflow for reading an object is as follows: @@ -95,7 +95,7 @@ Known issue: if someone is reading from a version that we want to delete and the Usefull metadata: - list of versions that reference this block in the Casandra table, so that we can do GC by checking in Cassandra that the lines still exist -- list of other nodes that we know have acknowledged a write of this block, usefull in the rebalancing algorithm +- list of other nodes that we know have acknowledged a write of this block, useful in the rebalancing algorithm Write strategy: have a single thread that does all write IO so that it is serialized (or have several threads that manage independent parts of the hash space). When writing a blob, write it to a temporary file, close, then rename so that a concurrent read gets a consistent result (either not found or found with whole content). diff --git a/doc/book/working-documents/migration-04.md b/doc/book/working-documents/migration-04.md index d9d3ede1..52c56737 100644 --- a/doc/book/working-documents/migration-04.md +++ b/doc/book/working-documents/migration-04.md @@ -68,7 +68,7 @@ The migration steps are as follows: 5. Turn off Garage 0.3 6. Backup metadata folders if you can (i.e. if you have space to do it - somewhere). Backuping data folders could also be usefull but that's much + somewhere). Backuping data folders could also be useful but that's much harder to do. If your filesystem supports snapshots, this could be a good time to use them. diff --git a/doc/book/working-documents/testing-strategy.md b/doc/book/working-documents/testing-strategy.md index 7d6be8ef..fff706d7 100644 --- a/doc/book/working-documents/testing-strategy.md +++ b/doc/book/working-documents/testing-strategy.md @@ -37,7 +37,7 @@ There are two reasons for this: Reminder: rules of simplicity, concerning changes to Garage's source code. Always question what we are doing. -Never do anything just because it looks nice or because we "think" it might be usefull at some later point but without knowing precisely why/when. +Never do anything just because it looks nice or because we "think" it might be useful at some later point but without knowing precisely why/when. Only do things that make perfect sense in the context of what we currently know. ## References diff --git a/doc/drafts/k2v-spec.md b/doc/drafts/k2v-spec.md index 3956fa31..f9696717 100644 --- a/doc/drafts/k2v-spec.md +++ b/doc/drafts/k2v-spec.md @@ -562,7 +562,7 @@ token>", v: ["<value1>", ...] }`, with the following fields: - in case of concurrent update and deletion, a `null` is added to the list of concurrent values - if the `tombstones` query parameter is set to `true`, tombstones are returned - for items that have been deleted (this can be usefull for inserting after an + for items that have been deleted (this can be useful for inserting after an item that has been deleted, so that the insert is not considered concurrent with the delete). Tombstones are returned as tuples in the same format with only `null` values |