aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorQuentin Dufour <quentin@deuxfleurs.fr>2022-01-24 13:44:39 +0100
committerQuentin Dufour <quentin@deuxfleurs.fr>2022-01-24 13:44:39 +0100
commit11f54e2b8be8b301da309e326b81ed58b4b37870 (patch)
tree11c007028018f04bed5c5e69b2e088423d87dc94
parenta8ef761731473ef073c60a1e924eb5b58a022d98 (diff)
downloadgarage-11f54e2b8be8b301da309e326b81ed58b4b37870.tar.gz
garage-11f54e2b8be8b301da309e326b81ed58b4b37870.zip
Add support for duck
-rw-r--r--doc/book/src/connect/cli.md107
1 files changed, 106 insertions, 1 deletions
diff --git a/doc/book/src/connect/cli.md b/doc/book/src/connect/cli.md
index c78ed305..e5c4a495 100644
--- a/doc/book/src/connect/cli.md
+++ b/doc/book/src/connect/cli.md
@@ -3,6 +3,15 @@
CLI tools allow you to query the S3 API without too many abstractions.
These tools are particularly suitable for debug, backups, website deployments or any scripted task that need to handle data.
+| Name | Status | Note |
+|------|--------|------|
+| [Minio client](#minio-client-recommended) | ✅ | |
+| [AWS CLI](#aws-cli) | ✅ | |
+| [rclone](#rclone) | ✅ | |
+| [s3cmd](#s3cmd) | ✅ | |
+| [(Cyber)duck](#cyberduck--duck) | ✅ | |
+
+
## Minio client (recommended)
Use the following command to set an "alias", i.e. define a new S3 server to be
@@ -161,6 +170,102 @@ s3cmd get s3://my-bucket/hello.txt hello.txt
## Cyberduck & duck
-TODO
+Both Cyberduck (the GUI) and duck (the CLI) have a concept of "Connection Profiles" that contain some presets for a specific provider.
+We wrote the following connection profile for Garage:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+ <dict>
+ <key>Protocol</key>
+ <string>s3</string>
+ <key>Vendor</key>
+ <string>garage</string>
+ <key>Scheme</key>
+ <string>https</string>
+ <key>Description</key>
+ <string>GarageS3</string>
+ <key>Default Hostname</key>
+ <string>127.0.0.1</string>
+ <key>Default Port</key>
+ <string>4443</string>
+ <key>Hostname Configurable</key>
+ <false/>
+ <key>Port Configurable</key>
+ <false/>
+ <key>Username Configurable</key>
+ <true/>
+ <key>Username Placeholder</key>
+ <string>Access Key ID (GK...)</string>
+ <key>Password Placeholder</key>
+ <string>Secret Key</string>
+ <key>Properties</key>
+ <array>
+ <string>s3service.disable-dns-buckets=true</string>
+ </array>
+ <key>Region</key>
+ <string>garage</string>
+ <key>Regions</key>
+ <array>
+ <string>garage</string>
+ </array>
+ </dict>
+</plist>
+```
+
+*Note: If your garage instance is configured with vhost access style, you can remove `s3service.disable-dns-buckets=true`.*
+
+### Instructions for the GUI
+
+Copy the connection profile, and save it anywhere as `garage.cyberduckprofile`.
+Then find this file with your file explorer and double click on it: Cyberduck will open a connection wizard for this profile.
+Simply follow the wizard and you should be done!
+
+### Instuctions for the CLI
+
+To configure duck (Cyberduck's CLI tool), start by creating its folder hierarchy:
+
+```
+mkdir -p ~/.duck/profiles/
+```
+
+Then, save the connection profile for Garage in `~/.duck/profiles/garage.cyberduckprofile`.
+To set your credentials in `~/.duck/credentials`, use the following commands to generate the appropriate string:
+
+```bash
+export AWS_ACCESS_KEY_ID="GK..."
+export AWS_SECRET_ACCESS_KEY="..."
+export HOST="s3.garage.localhost"
+export PORT="4443"
+export PROTOCOL="https"
+
+cat > ~/.duck/credentials <<EOF
+$PROTOCOL\://$AWS_ACCESS_KEY_ID@$HOST\:$PORT=$AWS_SECRET_ACCESS_KEY
+EOF
+```
+And finally, I recommend appending a small wrapper to your `~/.bashrc` to avoid setting the username on each command (do not forget to replace `GK...` by your access key):
+```bash
+function duck { command duck --username GK... $@ ; }
+```
+
+Finally, you can then use `duck` as follow:
+
+```bash
+# List buckets
+duck --list garage:/
+
+# List objects in a bucket
+duck --list garage:/my-files/
+
+# Download an object
+duck --download garage:/my-files/an-object.txt /tmp/object.txt
+
+# Upload an object
+duck --upload /tmp/object.txt garage:/my-files/another-object.txt
+
+# Delete an object
+duck --delete garage:/my-files/an-object.txt
+```