Narzędzia CLI

Narzędzia CLI to podstawowy i najprostszy sposób obsługi S3 w systemach rodziny Linux.

W niniejszym przewodniku opisano konfigurację oraz podstawowe operacje wykonywane za pomocą rekomendowanych narzędzi:

• mc (MinIO Client) - prosta konfiguracja, zelcane narzędzie przy wykonywaniu podstawowych operacji
• rclone - upload większego wolumenu danych (rzędu TB), szyfrowanie po stronie klienta danych przechowywanych w usłudze
• s3cmd - zalecane podczas korzystania z zaawansowanych funkcji API S3 (np. wersjonowanie i retencja obiektów)

MinIO Client

Narzędzie charakteryzuje się prostotą konfiguracji oraz optymalnymi domyślnymi parametrami połączenia.

Instalacja

Narzędzie jest dystrybuowane w postaci pojedynczego pliku binarnego. Należy go pobrać oraz nadać uprawnienia umozliwiające jego wykonanie.

Linux: https://dl.min.io/client/mc/release/linux-amd64/mc

Windows: https://dl.min.io/client/mc/release/windows-amd64/mc.exe

Uwaga: Midnight Commander równiez jest uruchamiany poleceniem mc

Konfiguracja

Wykonujemy polecenie:

mc config alias add cyfs3 https://<endpoint>

Nastepnie podajemy Access key oraz Secret access key.

Oficjalna dokumentacja

Oficjalna dokumentacja dostępna jest na stronie: https://docs.min.io/docs/minio-client-complete-guide.html

Podstawowe polecenia

Wyświetlenie dostepnych poleceń

mc

Wyświetlenie pomocy dla polecenia ls

mc ls --help

Listowanie bucketów

mc ls cyfs3

Listowanie obiektów znajdujących się w buckecie

mc ls cyfs3/bucket

Kopiowanie lokalnego pliku data.dat do bucketu o nazwie qwerty

mc cp data.dat cyfs3/qwerty

Kopiowanie pliku data2.dat z bucketu o nazwie abc do lokalnego katalogu roboczego

mc cp cyfs3/abc/data2.dat .

Shell auto-completion

mc --autocompletion

s3cmd

Najbardziej uniwersalnym narzędziem do obsługi S3 jest s3cmd.

Poniżej opisano jego standardową konfigurację. Domyślna lokalizacja pliku konfiguracyjnego dla narzędzia to $HOME/.s3cfg, alternatywną ścieżkę dla pliku konfiguracyjnego można podać korzystając z opcji s3mcd -c <lokalizacja_pliku_konfiguracyjnego>. Podstawowy plik przyjmuje następującą formę:

[default]
access_key = <access_key>
secret_key = <secret_key>
bucket_location = us-east-1
check_ssl_certificate = True
check_ssl_hostname = True
enable_multipart = True
host_base = <endpoint> # na przykład: s3.cloud.cyfronet.pl
host_bucket = %(bucket).<endpoint> # na przykład: %(bucket).s3.cloud.cyfronet.pl
multipart_chunk_size_mb = 256
use_https = True
signurl_use_https = True

Konfiguracja

Autoryzacja

access_key, secret_key

Każdy użytkownik posiada indywidualny zestaw kluczy access_key oraz secret_key otrzymany przy zakładaniu konta. W przypadku otrzymywania błędów uwierzytelniania należy sprawdzić czy:

• klucze składają się wyłącznie z dużych i małych liter oraz cyfr;
• podano prawidłowy endpoint.

Region

bucket_location

W polu region powinna znaleźć się wartość domyślna (puste pole). Alternatywnie można tu także wpisać region: us-east-1, który jest regionem domyślnym dla AWS S3.

Endpoint

host_base

W polu s3_endpoint zawsze powinno się znaleźć s3.cloud.cyfronet.pl lub s3p.cloud.cyfronet.pl.

Bezpieczeństwo

use_https, signurl_use_https, check_ssl_certificate, check_ssl_hostname

S3 korzysta z protokołu HTTPS z szyfrowaniem TLS, z tego powodu wszystkie wyżej wymienione opcje powinny być zdefiniowane jako True. Opcja druga, signurl_use_https, jest istotna dla użytkowników linków tymczasowych.

Wydajność

multipart_chunk_size_mb

Parametr ten dotyczy podziału dużego pliku na części podczas jego uploadu. Można w tym miejscu uznać, że wartość 256MB jest bezpieczną wartością, przy założeniu posiadania stabilnego połączenia internetowego. W przypadku połączenia o mniejszej przepustowości zaleca się zmniejszenie tej wartości (do 128MB / 64MB).

Podstawowe operacje

Tworzenie bucketu

s3cmd mb s3://[bucket]

Wyświetlanie bucketów

s3cmd ls

Listowanie zawartości konkretnego bucketu

s3cmd la s3://[bucket]

Listowanie wszystkich obiektów

s3cmd la

Upload pliku (obiektu)

s3cmd put [file] s3://[bucket]

Download

s3cmd get s3://[bucket]/[obiekt] .

Info

s3cmd info s3://[bucket][/obiekt]

Usuwanie pliku (obiektu)

s3cmd del s3://[bucket]/[obiekt]

rclone

rclone to narzędzie dostępne z repozytorium EPEL w przypadku systemów CentOS oraz wielu natywnych repozytoriach pozostałych dystrybucji.

Narzędzie, z uwagi na opcje sterujące przebiegiem uploadu, sprawdza się dobrze przy uploadach większego wolumenu danych (rzędu kilkuset TB), a także danych, na które składają się głównie duże ilości małych plików.

Konfiguracja

Polecenie rclone config umożliwia interaktywną edycję pliku konfiguracyjnego narzędzia.

Poniżej przedstawiono standardowy plik konfiguracyjny narzędzia. Jego domyślna lokalizacja to: $HOME/.config/rclone/rclone.conf a uprawnienia nadane plikowi to 0600. W dalszych krokach założono, że podana konfiguracja została zdefiniowana pod nazwą user:

[user]
type = s3
provider = Ceph
env_auth = false
access_key_id = <access_key>
secret_access_key = <secret_key>
region =
endpoint = <endpoint>
location_constraint =
acl = private

Istnieje także możliwość definiowania podanych parametrów jako zmienne środowiskowe, co jest szczególnie przydatne w przypadku integracji wielu narzędzi. Wtedy powyższemu plikowi konfiguracyjnemu będą odpowiadać następujące zmienne:

export RCLONE_CONFIG_USER_TYPE=s3 \
RCLONE_CONFIG_USER_PROVIDER=Ceph \
RCLONE_CONFIG_USER_ACCESS_KEY_ID=<access_key> \
RCLONE_CONFIG_USER_SECRET_ACCESS_KEY=<secret_key> \
RCLONE_CONFIG_USER_ENDPOINT=<endpoint> \
RCLONE_CONFIG_USER_REGION= \
RCLONE_CONFIG_USER_LOCATION_CONSTRAINT= \
RCLONE_CONFIG_USER_ACL=private

należy zwrócić uwagę na to, żeby przy tak podanej konfiguracji ustawić odpowiednio także zmienną env_auth:

export RCLONE_CONFIG_USER_ENV_AUTH=true

Autoryzacja

access_key_id, secret_access_key

Każdy użytkownik posiada indywidualny zestaw kluczy access_key oraz secret_key otrzymany przy zakładaniu konta. W przypadku otrzymywania błędów uwierzytelniania należy sprawdzić czy:

• klucze składają się wyłącznie z dużych i małych liter oraz cyfr;
• podano prawidłowy endpoint.

Region

W polu region powinna znaleźć się wartość domyślna (puste pole).

Endpoint

W polu endpoint zawsze powinno się znaleźć s3.cloud.cyfronet.pl lub s3p.cloud.cyfronet.pl.

ACL

W tym polu należy zdefiniować domyślne ACL dla nowoutworzonych obiektów oraz bucketów. W większości przypadków zaleca się ustawienie tego parametru na private.

Wydajność

rclone udostępnia trzy parametry konfiguracyjne pozwalające na sterowanie sposobem uploadu plików:

chunk_size = 256
upload_concurrency = 8
upload_cutoff = 256

RCLONE_CONFIG_USER_CHUNK_SIZE = 256
RCLONE_CONFIG_USER_UPLOAD_CONCURRENCY = 8
RCLONE_CONFIG_USER_UPLOAD_CUTOFF = 2

Pozwalają one na zdefiniowanie, w jaki sposób ma być przeprowadzony upload dużych plików, czyli takich, których wielkość została zdefiniowana parametrem upload_cutoff (domyślnie 200MB). Powyżej tej wartości plik zostaje podzielony na części (chunki) o wielkości zdefiniowanej parametrem chunk_size. Następnie plik zostaje uploadowany w częściach, po upload_concurrency części równocześnie. Opcje te polecane są szczególnie dla dużych plików.

rclone posiada także globalną opcję --transfers=N, która pozwala na zdefiniowanie liczby plików uploadowanych równocześnie na S3. W przypadku dużej liczby małych plików zaleca się jej zmianę z domyślnej wartości (4) na większą.

Pozostałe informacje

Kompletna lista parametrów pliku konfiguracyjnego dla S3 oraz odpowiadających im zmiennych środowiska znajduje się na oficjalnej stronie rclone.

Podstawowe operacje

W przypadku konfiguracji zdefiniowanej jak powyżej, w miejscu [remote] wstawiamy user

Tworzenie bucketu

rclone mkdir [remote]:[bucket]

Wyświetlanie bucketów

rclone lsd [remote]:

Listowanie zawartości konkretnego bucketu

rclone ls [remote]:[bucket]

Wyświelanie obiektów w bucketcie z czasem modyfikacji, sumą kontrolną i rozmiarem

rclone lsf --hash MD5 --format pths --separator  [remote]:[bucket]

Upload pliku (obiektu)

rclone copy [file] [remote]:[bucket]

Download

rclone copy [remote]:[bucket]/file .

Usuwanie pliku (obiektu)

rclone delete [remote]:[bucket]/[file]

Odpowiednik rsync

rclone sync [dir] [remote]:bucket

Montowanie bucketu poprzez FUSE

Opcja eksperymentalna, ze względu na niewielką wydajność nie zaleca się jej używania do operacji na dużych (>4GB) plikach oraz bucketach z większą ilością małych plików.

rclone mount [remote]:[bucket] [mountpoint] --daemon