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 operacjirclone
- upload większego wolumenu danych (rzędu TB), szyfrowanie po stronie klienta danych przechowywanych w usłudzes3cmd
- 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