From 5ffcdb4634260c66b0db60e1e9de18866b5be550 Mon Sep 17 00:00:00 2001 From: Lapineige Date: Sat, 19 Aug 2023 15:17:51 +0000 Subject: fix typo --- doc/book/connect/apps/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/book') diff --git a/doc/book/connect/apps/index.md b/doc/book/connect/apps/index.md index 83aadec2..0ebb01b4 100644 --- a/doc/book/connect/apps/index.md +++ b/doc/book/connect/apps/index.md @@ -146,7 +146,7 @@ Keep the Key ID and the Secret key in a pad, they will be needed later. We need two buckets, one for normal videos (named peertube-video) and one for webtorrent videos (named peertube-playlist). ```bash -garage bucket create peertube-video +garage bucket create peertube-videos garage bucket create peertube-playlist ``` -- cgit v1.2.3 From 47e7f9e1229f3c5e25708cedd60eeb2e0e1a6cd2 Mon Sep 17 00:00:00 2001 From: Lapineige Date: Sat, 19 Aug 2023 20:29:24 +0000 Subject: another typo --- doc/book/connect/apps/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/book') diff --git a/doc/book/connect/apps/index.md b/doc/book/connect/apps/index.md index 0ebb01b4..baf6ba50 100644 --- a/doc/book/connect/apps/index.md +++ b/doc/book/connect/apps/index.md @@ -216,7 +216,7 @@ object_storage: # Same settings but for webtorrent videos videos: - bucket_name: 'peertube-video' + bucket_name: 'peertube-videos' prefix: '' # You must fill this field to make Peertube use our reverse proxy/website logic base_url: 'http://peertube-videos.web.garage.localhost' -- cgit v1.2.3 From 5feb6a1f64aaede10f8172c37645da18a96b419c Mon Sep 17 00:00:00 2001 From: networkException Date: Tue, 3 Oct 2023 17:49:30 +0200 Subject: docs: add documentation for specifying token / secret file as environment variables --- doc/book/reference-manual/configuration.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) (limited to 'doc/book') diff --git a/doc/book/reference-manual/configuration.md b/doc/book/reference-manual/configuration.md index 3110aab7..2a8c5df5 100644 --- a/doc/book/reference-manual/configuration.md +++ b/doc/book/reference-manual/configuration.md @@ -276,7 +276,7 @@ Compression is done synchronously, setting a value too high will add latency to This value can be different between nodes, compression is done by the node which receive the API call. -### `rpc_secret`, `rpc_secret_file` or `GARAGE_RPC_SECRET` (env) +### `rpc_secret`, `rpc_secret_file` or `GARAGE_RPC_SECRET`, `GARAGE_RPC_SECRET_FILE` (env) Garage uses a secret key, called an RPC secret, that is shared between all nodes of the cluster in order to identify these nodes and allow them to @@ -288,6 +288,9 @@ Since Garage `v0.8.2`, the RPC secret can also be stored in a file whose path is given in the configuration variable `rpc_secret_file`, or specified as an environment variable `GARAGE_RPC_SECRET`. +Since Garage `v0.9.0`, you can also specify the path of a file storing the secret +as the `GARAGE_RPC_SECRET_FILE` environment variable. + ### `rpc_bind_addr` The address and port on which to bind for inter-cluster communcations @@ -465,7 +468,7 @@ See [administration API reference](@/documentation/reference-manual/admin-api.md Alternatively, since `v0.8.5`, a path can be used to create a unix socket. Note that for security reasons, the socket will have 0220 mode. Make sure to set user and group permissions accordingly. -### `metrics_token`, `metrics_token_file` or `GARAGE_METRICS_TOKEN` (env) +### `metrics_token`, `metrics_token_file` or `GARAGE_METRICS_TOKEN`, `GARAGE_METRICS_TOKEN_FILE` (env) The token for accessing the Metrics endpoint. If this token is not set, the Metrics endpoint can be accessed without access control. @@ -475,8 +478,9 @@ You can use any random string for this value. We recommend generating a random t `metrics_token` was introduced in Garage `v0.7.2`. `metrics_token_file` and the `GARAGE_METRICS_TOKEN` environment variable are supported since Garage `v0.8.2`. +`GARAGE_METRICS_TOKEN_FILE` is supported since `v0.9.0`. -### `admin_token`, `admin_token_file` or `GARAGE_ADMIN_TOKEN` (env) +### `admin_token`, `admin_token_file` or `GARAGE_ADMIN_TOKEN`, `GARAGE_ADMIN_TOKEN_FILE` (env) The token for accessing all of the other administration endpoints. If this token is not set, access to these endpoints is disabled entirely. @@ -486,6 +490,7 @@ You can use any random string for this value. We recommend generating a random t `admin_token` was introduced in Garage `v0.7.2`. `admin_token_file` and the `GARAGE_ADMIN_TOKEN` environment variable are supported since Garage `v0.8.2`. +`GARAGE_ADMIN_TOKEN_FILE` is supported since `v0.9.0`. ### `trace_sink` -- cgit v1.2.3 From f83fa021937978e79c917c08b3499ba866120284 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A9lix=20Baylac=20Jacqu=C3=A9?= Date: Wed, 25 Oct 2023 11:34:39 +0200 Subject: Add allow_world_readable_secrets option to config file Sometimes, the secret files permissions checks gets in the way. It's by no mean complete, it doesn't take the Posix ACLs into account among other things. Correctly checking the ACLs would be too involving (see https://git.deuxfleurs.fr/Deuxfleurs/garage/issues/658#issuecomment-7102) and would likely still fail in some weird chmod settings. We're adding a new configuration file key allowing the user to disable this permission check altogether. The (already existing) env variable counterpart always take precedence to this config file option. That's useful in cases where the configuration file is static and cannot be easily altered. Fixes https://git.deuxfleurs.fr/Deuxfleurs/garage/issues/658 Co-authored-by: Florian Klink --- doc/book/reference-manual/configuration.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'doc/book') diff --git a/doc/book/reference-manual/configuration.md b/doc/book/reference-manual/configuration.md index 2a8c5df5..a536dd02 100644 --- a/doc/book/reference-manual/configuration.md +++ b/doc/book/reference-manual/configuration.md @@ -323,6 +323,18 @@ be obtained by running `garage node id` and then included directly in the key will be returned by `garage node id` and you will have to add the IP yourself. +### `allow_world_readable_secrets` + +Garage checks the permissions of your secret files to make sure +they're not world-readable. In some cases, the check might fail and +consider your files as world-readable even if they're not. Such as +when using Posix ACLs. + +Setting `allow_world_readable_secrets` to `true` bypass this +permission verification. + +Alternatively, you can set the `GARAGE_ALLOW_WORLD_READABLE_SECRETS` +environment variable to `true` to bypass the permissions check. ## The `[consul_discovery]` section -- cgit v1.2.3 From 7228695ee288012103355589caa1ab5dd666b164 Mon Sep 17 00:00:00 2001 From: Alex Auvolat Date: Mon, 15 Jan 2024 17:18:46 +0100 Subject: config: refactor secret sourcing --- doc/book/reference-manual/configuration.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'doc/book') diff --git a/doc/book/reference-manual/configuration.md b/doc/book/reference-manual/configuration.md index a536dd02..77720f7b 100644 --- a/doc/book/reference-manual/configuration.md +++ b/doc/book/reference-manual/configuration.md @@ -325,10 +325,9 @@ yourself. ### `allow_world_readable_secrets` -Garage checks the permissions of your secret files to make sure -they're not world-readable. In some cases, the check might fail and -consider your files as world-readable even if they're not. Such as -when using Posix ACLs. +Garage checks the permissions of your secret files to make sure they're not +world-readable. In some cases, the check might fail and consider your files as +world-readable even if they're not, for instance when using Posix ACLs. Setting `allow_world_readable_secrets` to `true` bypass this permission verification. -- cgit v1.2.3 From ee57dd922b9c396298473b41e4046c8d00ee77d5 Mon Sep 17 00:00:00 2001 From: Alex Auvolat Date: Tue, 16 Jan 2024 16:28:17 +0100 Subject: Bump version to 0.9.1 --- doc/book/cookbook/real-world.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'doc/book') diff --git a/doc/book/cookbook/real-world.md b/doc/book/cookbook/real-world.md index ea4ce1f9..ce0abddd 100644 --- a/doc/book/cookbook/real-world.md +++ b/doc/book/cookbook/real-world.md @@ -85,14 +85,14 @@ to store 2 TB of data in total. ## Get a Docker image Our docker image is currently named `dxflrs/garage` and is stored on the [Docker Hub](https://hub.docker.com/r/dxflrs/garage/tags?page=1&ordering=last_updated). -We encourage you to use a fixed tag (eg. `v0.9.0`) and not the `latest` tag. -For this example, we will use the latest published version at the time of the writing which is `v0.9.0` but it's up to you +We encourage you to use a fixed tag (eg. `v0.9.1`) and not the `latest` tag. +For this example, we will use the latest published version at the time of the writing which is `v0.9.1` but it's up to you to check [the most recent versions on the Docker Hub](https://hub.docker.com/r/dxflrs/garage/tags?page=1&ordering=last_updated). For example: ``` -sudo docker pull dxflrs/garage:v0.9.0 +sudo docker pull dxflrs/garage:v0.9.1 ``` ## Deploying and configuring Garage @@ -157,7 +157,7 @@ docker run \ -v /etc/garage.toml:/etc/garage.toml \ -v /var/lib/garage/meta:/var/lib/garage/meta \ -v /var/lib/garage/data:/var/lib/garage/data \ - dxflrs/garage:v0.9.0 + dxflrs/garage:v0.9.1 ``` With this command line, Garage should be started automatically at each boot. @@ -171,7 +171,7 @@ If you want to use `docker-compose`, you may use the following `docker-compose.y version: "3" services: garage: - image: dxflrs/garage:v0.9.0 + image: dxflrs/garage:v0.9.1 network_mode: "host" restart: unless-stopped volumes: -- cgit v1.2.3 From 91a51dd3e876bde7d9b6199b478c26c620994348 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arma=C3=ABl=20Gu=C3=A9neau?= Date: Sat, 27 Jan 2024 14:51:15 +0100 Subject: doc: fix some typos --- doc/book/operations/durability-repairs.md | 4 ++-- doc/book/operations/layout.md | 12 ++++++------ doc/book/operations/upgrading.md | 2 +- 3 files changed, 9 insertions(+), 9 deletions(-) (limited to 'doc/book') diff --git a/doc/book/operations/durability-repairs.md b/doc/book/operations/durability-repairs.md index b0d2c78a..578899a8 100644 --- a/doc/book/operations/durability-repairs.md +++ b/doc/book/operations/durability-repairs.md @@ -49,7 +49,7 @@ verifications. Of course, scrubbing the entire data store will also take longer. ## Block check and resync In some cases, nodes hold a reference to a block but do not actually have the block -stored on disk. Conversely, they may also have on disk blocks that are not referenced +stored on disk. Conversely, they may also have on-disk blocks that are not referenced any more. To fix both cases, a block repair may be run with `garage repair blocks`. This will scan the entire block reference counter table to check that the blocks exist on disk, and will scan the entire disk store to check that stored blocks @@ -95,7 +95,7 @@ using the `garage block purge` command. In [multi-HDD setups](@/documentation/operations/multi-hdd.md), to ensure that data blocks are well balanced between storage locations, you may run a -rebalance operation using `garage repair rebalance`. This is usefull when +rebalance operation using `garage repair rebalance`. This is useful when adding storage locations or when capacities of the storage locations have been changed. Once this is finished, Garage will know for each block of a single possible location where it can be, which can increase access speed. This diff --git a/doc/book/operations/layout.md b/doc/book/operations/layout.md index ee05aba1..cf1372b0 100644 --- a/doc/book/operations/layout.md +++ b/doc/book/operations/layout.md @@ -13,7 +13,7 @@ In Garage, all of the data that can be stored in a given cluster is divided into slices which we call *partitions*. Each partition is stored by one or several nodes in the cluster (see [`replication_mode`](@/documentation/reference-manual/configuration.md#replication_mode)). -The layout determines the correspondence between these partition, +The layout determines the correspondence between these partitions, which exist on a logical level, and actual storage nodes. ## How cluster layouts work in Garage @@ -94,10 +94,10 @@ follow the following recommendations: ## Understanding unexpected layout calculations When adding, removing or modifying nodes in a cluster layout, sometimes -unexpected assigntations of partitions to node can occur. These assignations -are in fact normal and logical, given the objectives of the algorihtm. Indeed, -**the layout algorithm prioritizes moving less data between nodes over the fact -of achieving equal distribution of load. It also tries to use all links between +unexpected assignations of partitions to node can occur. These assignations +are in fact normal and logical, given the objectives of the algorithm. Indeed, +**the layout algorithm prioritizes moving less data between nodes over +achieving equal distribution of load. It also tries to use all links between pairs of nodes in equal proportions when moving data.** This section presents two examples and illustrates how one can control Garage's behavior to obtain the desired results. @@ -270,5 +270,5 @@ that is moved to node1). This illustrates the second principle of the layout computation: **if there is a choice in moving data out of some nodes, then all links between pairs of nodes are used in equal proportions** (this is approximately true, there is -randomness in the algorihtm to achieve this so there might be some small +randomness in the algorithm to achieve this so there might be some small fluctuations, as we see above). diff --git a/doc/book/operations/upgrading.md b/doc/book/operations/upgrading.md index 9a738282..6b6ea26d 100644 --- a/doc/book/operations/upgrading.md +++ b/doc/book/operations/upgrading.md @@ -9,7 +9,7 @@ On a new version release, there is 2 possibilities: - protocols and data structures remained the same ➡️ this is a **minor upgrade** - protocols or data structures changed ➡️ this is a **major upgrade** -You can quickly now what type of update you will have to operate by looking at the version identifier: +You can quickly know what type of update you will have to operate by looking at the version identifier: when we require our users to do a major upgrade, we will always bump the first nonzero component of the version identifier (e.g. from v0.7.2 to v0.8.0). Conversely, for versions that only require a minor upgrade, the first nonzero component will always stay the same (e.g. from v0.8.0 to v0.8.1). -- cgit v1.2.3 From 561fad0b44f78372357c1c76e3708a062d703b33 Mon Sep 17 00:00:00 2001 From: Alex Auvolat Date: Fri, 9 Feb 2024 12:19:16 +0100 Subject: [nix-improvements] get rid of Drone --- doc/book/design/goals.md | 2 -- doc/book/development/devenv.md | 2 +- doc/book/development/miscellaneous-notes.md | 8 ++--- doc/book/development/release-process.md | 55 +++++++++-------------------- 4 files changed, 21 insertions(+), 46 deletions(-) (limited to 'doc/book') diff --git a/doc/book/design/goals.md b/doc/book/design/goals.md index 78ac7978..4efb6349 100644 --- a/doc/book/design/goals.md +++ b/doc/book/design/goals.md @@ -48,7 +48,5 @@ locations. They use Garage themselves for the following tasks: - As a backup target using `rclone` and `restic` -- In the Drone continuous integration platform to store task logs - The Deuxfleurs Garage cluster is a multi-site cluster currently composed of 9 nodes in 3 physical locations. diff --git a/doc/book/development/devenv.md b/doc/book/development/devenv.md index dd3bdec0..88f8ba06 100644 --- a/doc/book/development/devenv.md +++ b/doc/book/development/devenv.md @@ -80,7 +80,7 @@ nix-build \ --git_version $(git rev-parse HEAD) ``` -*The result is located in `result/bin`. You can pass arguments to cross compile: check `.drone.yml` for examples.* +*The result is located in `result/bin`. You can pass arguments to cross compile: check `.woodpecker/release.yml` for examples.* If you modify a `Cargo.toml` or regenerate any `Cargo.lock`, you must run `cargo2nix`: diff --git a/doc/book/development/miscellaneous-notes.md b/doc/book/development/miscellaneous-notes.md index f0083ae5..a421943f 100644 --- a/doc/book/development/miscellaneous-notes.md +++ b/doc/book/development/miscellaneous-notes.md @@ -81,12 +81,9 @@ Our cache will be checked. - http://www.lpenz.org/articles/nixchannel/index.html -## Drone +## Woodpecker -Do not try to set a build as trusted from the interface or the CLI tool, -your request would be ignored. Instead, directly edit the database (table `repos`, column `repo_trusted`). - -Drone can do parallelism both at the step and the pipeline level. At the step level, parallelism is restricted to the same runner. +Woodpecker can do parallelism both at the step and the pipeline level. At the step level, parallelism is restricted to the same runner. ## Building Docker containers @@ -99,3 +96,4 @@ We were: - Unable to use the kaniko container provided by Google as we can't run arbitrary logic: we need to put our secret in .docker/config.json. Finally we chose to build kaniko through nix and use it in a `nix-shell`. +We then switched to using kaniko from nixpkgs when it was packaged. diff --git a/doc/book/development/release-process.md b/doc/book/development/release-process.md index 3fed4add..0c6701c0 100644 --- a/doc/book/development/release-process.md +++ b/doc/book/development/release-process.md @@ -42,7 +42,7 @@ and the docker containers on Docker Hub. ## Automation -We automated our release process with Nix and Drone to make it more reliable. +We automated our release process with Nix and Woodpecker to make it more reliable. Here we describe how we have done in case you want to debug or improve it. ### Caching build steps @@ -62,52 +62,31 @@ Sending to the cache is done through `nix copy`, for example: nix copy --to 's3://nix?endpoint=garage.deuxfleurs.fr®ion=garage&secret-key=/etc/nix/signing-key.sec' result ``` -*Note that you need the signing key. In our case, it is stored as a secret in Drone.* +*The signing key possessed by the Garage maintainers is required to update the Nix cache.* -The previous command will only send the built packet and not its dependencies. -To send its dependency, a tool named `nix-copy-closure` has been created but it is not compatible with the S3 protocol. - -Instead, you can use the following commands to list all the runtime dependencies: +The previous command will only send the built package and not its dependencies. +In the case of our CI pipeline, we want to cache all intermediate build steps +as well. This can be done using this quite involved command (here as an example +for the `pkgs.amd64.relase` package): ```bash -nix copy \ - --to 's3://nix?endpoint=garage.deuxfleurs.fr®ion=garage&secret-key=/etc/nix/signing-key.sec' \ - $(nix-store -qR result/) +nix copy -j8 \ + --to 's3://nix?endpoint=garage.deuxfleurs.fr®ion=garage&secret-key=/etc/nix/nix-signing-key.sec' \ + $(nix path-info pkgs.amd64.release --file default.nix --derivation --recursive | sed 's/\.drv$/.drv^*/') ``` -*We could also write this expression with xargs but this tool is not available in our container.* - -But in certain cases, we want to cache compile time dependencies also. -For example, the Nix project does not provide binaries for cross compiling to i686 and thus we need to compile gcc on our own. -We do not want to compile gcc each time, so even if it is a compile time dependency, we want to cache it. +This command will simultaneously build all of the required Nix paths (using at +most 8 parallel Nix builder jobs) and send the resulting objects to the cache. -This time, the command is a bit more involved: - -```bash -nix copy --to \ - 's3://nix?endpoint=garage.deuxfleurs.fr®ion=garage&secret-key=/etc/nix/signing-key.sec' \ - $(nix-store -qR --include-outputs \ - $(nix-instantiate)) -``` - -This is the command we use in our CI as we expect the final binary to change, so we mainly focus on -caching our development dependencies. - -*Currently there is no automatic garbage collection of the cache: we should monitor its growth. -Hopefully, we can erase it totally without breaking any build, the next build will only be slower.* - -In practise, we concluded that we do not want to cache all the compilation dependencies. -Instead, we want to cache the toolchain we use to build Garage each time we change it. -So we removed from Drone any automatic update of the cache and instead handle them manually with: +This can be run for all the Garage packages we build using the following command: ``` source ~/.awsrc -nix-shell --run 'refresh_toolchain' +nix-shell --attr cache --run 'refresh_cache' ``` -Internally, it will run `nix-build` on `nix/toolchain.nix` and send the output plus its depedencies to the cache. - -To erase the cache: +We don't automate this step at each CI build, as *there is currently no automatic garbage collection of the cache.* +This means we should also monitor the cache's size; if it ever becomes too big we can erase it with: ``` mc rm --recursive --force 'garage/nix/' @@ -157,9 +136,9 @@ nix-shell --run refresh_index If you want to compile for different architectures, you will need to repeat all these commands for each architecture. -**In practise, and except for debugging, you will never directly run these commands. Release is handled by drone** +**In practice, and except for debugging, you will never directly run these commands. Release is handled by Woodpecker.** -### Drone +### Drone (obsolete) Our instance is available at [https://drone.deuxfleurs.fr](https://drone.deuxfleurs.fr). You need an account on [https://git.deuxfleurs.fr](https://git.deuxfleurs.fr) to use it. -- cgit v1.2.3 From c86ac264cb6789fdc4c83378f275b76d57d88132 Mon Sep 17 00:00:00 2001 From: emilylange Date: Mon, 12 Feb 2024 17:51:01 +0100 Subject: doc: mention `warn` and `error` as available log levels For some users, this might be their first time being interacting with the `env_logger` crate. As such, they might not be aware that less verbose log levels exist. Some might not want to log every incoming request, for example. This commit also adds syntax hints to the code-fence for bash for better syntax highlighting of that section, and repeats itself multiple times, that `info` is, in fact, the default. No changes to the recommendation of log levels were made. --- doc/book/quick-start/_index.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'doc/book') diff --git a/doc/book/quick-start/_index.md b/doc/book/quick-start/_index.md index 1b129f36..cf6eabde 100644 --- a/doc/book/quick-start/_index.md +++ b/doc/book/quick-start/_index.md @@ -110,10 +110,11 @@ garage -c path/to/garage.toml server If you have placed the `garage.toml` file in `/etc` (its default location), you can simply run `garage server`. -You can tune Garage's verbosity as follows (from less verbose to more verbose): +You can tune Garage's verbosity by setting the `RUST_LOG=` environment variable. \ +Available log levels are (from less verbose to more verbose): `error`, `warn`, `info` *(default)*, `debug` and `trace`. -``` -RUST_LOG=garage=info garage server +```bash +RUST_LOG=garage=info garage server # default RUST_LOG=garage=debug garage server RUST_LOG=garage=trace garage server ``` -- cgit v1.2.3