S3-asiakasohjelma

Tässä luvussa kuvataan, miten Allas-objektitallennuspalvelua käytetään s3cmd-komentoriviasiakkaalla. Tämä asiakasohjelma käyttää S3-protokollaa, joka eroaa Rclone-, swift- ja a-commands -esimerkeissä käytetystä Swift-protokollasta. Tavallisesti S3:lla palveluun ladattua dataa voidaan käyttää myös swift-protokollalla. Allakseen swiftillä ladattuja yli 5 Gt:n tiedostoja ei kuitenkaan voi ladata S3-protokollalla.

Käyttäjän näkökulmasta yksi tärkeimmistä eroista S3- ja Swift-protokollien välillä on se, että Swift-pohjaiset yhteydet pysyvät voimassa kahdeksan tuntia kerrallaan, mutta S3:ssa yhteys pysyy pysyvästi avoinna. Pysyvä yhteys on käytännöllinen monella tavalla, mutta siihen liittyy tietoturvanäkökulma: jos CSC-käyttäjätunnuksesi vaarantuu, myös objektitallennustilasi vaarantuu.

Käytä versiota 2.0.2 tai uudempaa.

Komennon s3cmd syntaksi:

s3cmd -options command parameters

Yleisimmin käytetyt s3cmd-komennot:

s3cmd command	Function
mb	Luo ämpäri
put	Lataa objekti palveluun
ls	Listaa objektit ja ämpärit
get	Lataa objektit ja ämpärit
cp	Siirrä objekti
del	Poista objektit tai ämpärit
md5sum	Hae tarkistussumma
info	Näytä metadata
signurl	Luo väliaikainen URL
put -P	Tee objektista julkinen
setacl --acl-grant	Hallitse käyttöoikeuksia

Yllä oleva taulukko sisältää vain tärkeimmät s3cmd-komennot. Täydellisemmän listan löydät s3cmd:n manuaalisivulta tai kirjoittamalla:

s3cmd -h

s3cmd:n käytön aloittaminen

Jos käytät Allasta Puhdissa tai Mahdissa, kaikki tarvittavat paketit ja ohjelmistot on jo asennettu. Tässä tapauksessa voit ohittaa tämän luvun ja siirtyä kohtaan S3-yhteyden määrittäminen supertietokoneissa.

Jotta voit määrittää s3cmd-yhteyden, ympäristöösi on asennettava OpenStack ja s3cmd.

OpenStack- ja s3cmd-asennus:

Fedora/RHEL-johdannaiset:

sudo yum update
sudo yum install python3
sudo pip3 install python-openstackclient
sudo yum install s3cmd

Debian-johdannaiset:

sudo apt install python3-pip
sudo pip3 install python-openstackclient
sudo apt install restic
curl https://rclone.org/install.sh | sudo bash
sudo pip3 install s3cmd

OSX:

python3 virtualenv
pip3 install s3cmd
s3cmd

Katso alkuperäinen dokumentaatio osoitteista http://s3tools.org/download ja http://s3tools.org/usage.

Asenna lisäksi allas-conf.

S3-yhteyden määrittäminen

Jotta voit käyttää s3cmd:tä Puhdissa ja Mahdissa, sinun on ensin määritettävä yhteys:

module load allas
allas-conf --mode S3

Paikallisella tietokoneella:

source allas_conf --mode S3 --user your-csc-username

Katso lisätietoja ja lisävalintoja kohdasta allas-conf.

Ämpäreiden luominen ja objektien lataaminen palveluun

Luo uusi ämpäri:

s3cmd mb s3://my_bucket

Lataa tiedosto ämpäriin:

s3cmd put my_file s3://my_bucket

Objektien ja ämpäreiden listaaminen

Listaa kaikki projektin ämpärit:

s3cmd ls

Listaa kaikki ämpärin objektit:du Listaa kaikki ämpärin objektit:

s3cmd ls s3://my_bucket

Näytä ämpärin tiedot:

s3cmd info s3://my_bucket

Näytä objektin tiedot:

s3cmd info s3://my_bucket/my_file

Tarkista projektisi objektitallennuksen käyttö:

s3cmd du -H

Objektien ja ämpäreiden lataaminen

Lataa objekti:

s3cmd get s3://my_bucket/my_file new_file_name

Parametri new_file_name on valinnainen. Se määrittää ladatulle tiedostolle uuden nimen.

Komennolla md5sum voit tarkistaa, ettei tiedosto ole muuttunut tai vioittunut:

$ md5sum my_file new_file_name
   39bcb6992e461b269b95b3bda303addf  my_file
   39bcb6992e461b269b95b3bda303addf  new_file_name

Yllä olevassa esimerkissä tarkistussummat vastaavat toisiaan alkuperäisen ja ladatun tiedoston välillä.

Lataa koko ämpäri:

s3cmd get -r s3://my_bucket/

Objektien siirtäminen

Kopioi objekti toiseen ämpäriin. Huomaa, että näitä komentoja tulisi käyttää vain objekteille, jotka on ladattu Allakseen S3-protokollalla:

s3cmd cp s3://sourcebucket/objectname s3://destinationbucket

Esimerkiksi:

$ s3cmd cp s3://bigbucket/bigfish s3://my-new-bucket
remote copy: 's3://bigbucket/bigfish' -> 's3://my-new-bucket/bigfish'

Nimeä tiedosto uudelleen kopioinnin yhteydessä:

$ s3cmd cp s3://bigbucket/bigfish s3://my-new-bucket/newname
remote copy: 's3://bigbucket/bigfish' -> 's3://my-new-bucket/newname'

Objektien ja ämpäreiden poistaminen

Poista objekti:

s3cmd del s3://my_bucket/my_file

Poista ämpäri:

s3cmd rb s3://my_bucket

Huom: Voit poistaa vain tyhjiä ämpäreitä.

s3cmd ja julkiset objektit

Tässä esimerkissä pseudo-kansiossa fishes oleva objekti salmon.jpg tehdään julkiseksi:

$ s3cmd put fishes/salmon.jpg s3://my_fishbucket/fishes/salmon.jpg -P
Public URL of the object is: https://a3s.fi/my_fishbucket/fishes/salmon.jpg

Toisen projektin lukuoikeuden antaminen ämpäriin

Voit hallita käyttöoikeuksia komennolla s3cmd setacl. Tämä komento vaatii sen projektin UUID:n (universally unique identifier), jolle haluat myöntää käyttöoikeuden. Projektin jäsenet voivat tarkistaa projektitunnuksensa osoitteessa https://pouta.csc.fi/dashboard/identity/ tai komennolla openstack project show. Esimerkiksi Puhdissa ja Mahdissa:

module load allas
allas-conf -k --mode s3cmd
openstack project show $OS_PROJECT_NAME

s3cmd:n tapauksessa luku- ja kirjoitusoikeuksia voidaan hallita sekä ämpäreille että objekteille:

Seuraava komento antaa projektille, jonka UUID on 3d5b0ae8e724b439a4cd16d1290, lukuoikeuden ämpäriin my_fishbucket, mutta ei sen sisällä oleviin objekteihin:

s3cmd setacl --acl-grant=read:3d5b0ae8e724b439a4cd16d1290 s3://my_fishbucket

Vastaavasti seuraava komento antaa kirjoitusoikeuden vain yhteen objektiin:

s3cmd setacl --acl-grant=write:3d5b0ae8e724b439a4cd16d1290 s3://my_fishbucket/bigfish

Jos haluat muuttaa kaikkien ämpärissä olevien objektien käyttöoikeuksia, voit lisätä komentoon valinnan --recursive:

s3cmd setacl --recursive --acl-grant=read:3d5b0ae8e724b439a4cd16d1290 s3://my_fishbucket

Voit tarkistaa käyttöoikeudet komennolla s3cmd info:

$ s3cmd info s3://my_fishbucket|grep -i acl
   ACL:       other_project_uuid: READ
   ACL:       my_project_uuid: FULL_CONTROL

Valintaa --acl-revoke voidaan käyttää luku- tai kirjoitusoikeuden poistamiseen:

s3cmd setacl --recursive --acl-revoke=read:$other_project_uuid s3://my_fishbucket

Jaettuja objekteja ja ämpäreitä voidaan käyttää sekä S3- että Swift-pohjaisilla työkaluilla. Huomaa kuitenkin, että listauskomennot näyttävät vain projektisi omistamat ämpärit. Jaettujen ämpäreiden ja objektien tapauksessa sinun on tiedettävä ämpäreiden nimet voidaksesi käyttää niitä.

Yllä olevan esimerkin tapauksessa projektin 3d5b0ae8e724b439a4cd16d1290 käyttäjä ei näe my_fishbucket-ämpäriä, kun se on jaettu, komennolla:

s3cmd ls

Hän voi kuitenkin listata ämpärin sisällön komennolla:

s3cmd ls s3://my_fishbucket

Poudan selainkäyttöliittymässä käyttäjä voi siirtyä jaettuun ämpäriin määrittämällä ämpärin nimen URL-osoitteessa. Siirry johonkin projektisi ämpäriin ja korvaa URL-osoitteen lopussa oleva ämpärin nimi jaetun ämpärin nimellä:

https://pouta.csc.fi/dashboard/project/containers/container/my_fishbucket

Käyttöesimerkki

Tässä esimerkissä tallennamme yksinkertaisen aineiston Allakseen käyttäen s3cmd:tä.

Luo ensin uusi ämpäri. Komento s3cmd ls paljastaa, että objektitallennus on aluksi tyhjä. Luo sitten uusi fish-bucket-niminen ämpäri komennolla s3cmd mb.

$ s3cmd ls
ls

$ s3cmd mb s3://fish-bucket
mb s3://fish-bucket/
Bucket 's3://fish-bucket/' created

$ s3cmd ls
ls
2018-03-12 13:01  s3://fish-bucket

On suositeltavaa koota tallennettava data suuremmiksi kokonaisuuksiksi ja pakata se ennen sen lataamista palveluun.

Tässä esimerkissä tallennamme seeprakalan (danio rerio) Bowtie2-indeksit ja genomin fish-bucket-ämpäriin. Komennon ls -lh suorittaminen näyttää, että indeksitiedostot ovat saatavilla nykyisessä hakemistossa:

$ ls -lh
total 3.2G
-rw------- 1 kkayttaj csc 440M Mar 12 13:41 Danio_rerio.1.bt2
-rw------- 1 kkayttaj csc 327M Mar 12 13:41 Danio_rerio.2.bt2
-rw------- 1 kkayttaj csc 217K Mar 12 13:20 Danio_rerio.3.bt2
-rw------- 1 kkayttaj csc 327M Mar 12 13:20 Danio_rerio.4.bt2
-rw------- 1 kkayttaj csc 1.3G Mar 12 13:13 Danio_rerio.GRCz10.dna.toplevel.fa
-rw------- 1 kkayttaj csc 440M Mar 12 14:03 Danio_rerio.rev.1.bt2
-rw------- 1 kkayttaj csc 327M Mar 12 14:03 Danio_rerio.rev.2.bt2
-rw------- 1 kkayttaj csc 599K Mar 12 13:13 log

Data kootaan ja pakataan yhdeksi tiedostoksi komennolla tar:

tar zcf zebrafish.tgz Danio_rerio*

Tuloksena syntyvän tiedoston koko on noin 2 Gt. Pakattu tiedosto voidaan ladata fish-bucket-ämpäriin komennolla s3cmd put:

$ ls -lh zebrafish.tgz
-rw------- 1 kkayttaj csc 9.3G Mar 12 15:23 zebrafish.tgz

$ s3cmd put zebrafish.tgz s3://fish-bucket
put zebrafish.tgz s3://fish-bucket
upload: 'zebrafish.tgz' -> 's3://fish-bucket/zebrafish.tgz'  [1 of 1]
 2081306836 of 2081306836   100% in   39s    50.16 MB/s  done

$ s3cmd ls s3://fish-bucket
ls s3://fish-bucket
2019-10-01 12:11 9982519261   s3://fish-bucket/zebrafish.tgz

2 Gt:n datan lataaminen palveluun vie aikaa. Nouda palveluun ladattu tiedosto:

s3cmd get s3://fish-bucket/zebrafish.tgz

Oletusarvoisesti tähän ämpäriin pääsevät käsiksi vain projektin jäsenet. Komennolla s3cmd setacl voit kuitenkin tehdä tiedostosta julkisesti saatavilla olevan.

Tee ensin fish-bucket-ämpäristä julkinen:

s3cmd setacl --acl-public s3://fish-bucket

Tee sitten seeprakalan genomitiedostosta julkinen:

s3cmd setacl --acl-public s3://fish-bucket/zebrafish.tgz

Tiedoston URL-osoitteen syntaksi:

https://a3s.fi/bucket_name/object_name

Tässä tapauksessa tiedosto olisi saatavilla linkillä https://a3s.fi/fish-bucket/zebrafish.tgz

Objektien väliaikainen julkaiseminen allekirjoitetuilla URL-osoitteilla

Komennolla s3cmd signurl Allaksessa oleva objekti voidaan julkaista väliaikaisesti URL-osoitteella, joka sisältää tietoturvaa parantavan käyttöoikeustunnisteen.

Edellisessä esimerkissä objekti s3://fish-bucket/zebrafish.tgz tehtiin pysyvästi saataville yksinkertaisella staattisella URL-osoitteella. Komennolla signurl sama objekti voidaan jakaa turvallisemmin ja vain rajoitetuksi ajaksi. Esimerkiksi komento:

s3cmd signurl s3://fish-bucket/zebrafish.tgz +3600

tulostaisi URL-osoitteen, joka pysyy voimassa 3600 s (1 h). Tässä tapauksessa yllä olevan komennon tuottama URL-osoite näyttäisi suunnilleen tältä:

https://fish-bucket.a3s.fi/zebrafish.tgz?AWSAccessKeyId=78e6021a086d52f092b3b2b23bfd7a67&Expires=1599835116&Signature=OLyyCY14s%2F0HxKOOd108mldINyE%3D

Objektin elinkaaren määrittäminen

Jotta objektit voidaan poistaa tai vanhentaa automaattisesti, Allas-ämpärille voidaan määrittää elinkaarikäytäntö. Ämpärin objekteja käsitellään elinkaarikäytännön mukaisesti, jos vastaavat ehdot täyttyvät. Vastaavat ehdot voidaan määrittää objektin etuliitteelle ja/tai tunnisteille. Elinkaarikäytäntö soveltuu erityisen hyvin tilanteisiin, joissa data täytyy poistaa tietyn ajan kuluttua "ylläpitotoimenpiteenä".

Warning

Ennen elinkaarikäytännön määrittämistä varmista osastoltasi/tiimiltäsi, että se vastaa oikein projektin datan säilytyskäytäntöä. (Lainsäädännölliset tai sääntelyyn liittyvät rajoitteet).

Seuraavassa elinkaarikäytännössä on määritetty kaksi sääntöä. Nimetään tiedosto mypolicy.xml.

<?xml version="1.0" ?>
<LifecycleConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <Rule>
      <ID>1-days-expiration</ID>
      <Status>Enabled</Status>
      <Expiration>
         <Days>1</Days>
      </Expiration>
      <Filter>
         <Tag>
            <Key>days</Key>
            <Value>1</Value>
         </Tag>
      </Filter>
   </Rule>
   <Rule>
      <ID>30-days-expiration</ID>
      <Status>Enabled</Status>
      <Expiration>
         <Days>30</Days>
      </Expiration>
      <Filter>
         <Tag>
            <Key>days</Key>
            <Value>30</Value>
         </Tag>
      </Filter>
   </Rule>
</LifecycleConfiguration>

Vaihtoehtoisesti ehdot voidaan määrittää käyttäen prefix-määrettä, jota voidaan ajatella folder-vastineena. Molempia menetelmiä voidaan myös yhdistää käyttämällä <And>-tagia.

<?xml version="1.0" ?>
<LifecycleConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <Rule>
      <ID>Daily</ID>
      <Status>Enabled</Status>
      <Prefix>daily/</Prefix>
      <Expiration>
         <Days>30</Days>
      </Expiration>
   </Rule>
   <Rule>
      <ID>Weekly</ID>
      <Status>Enabled</Status>
      <Prefix>weekly/</Prefix>
      <Expiration>
         <Days>365</Days>
      </Expiration>
   </Rule>
</LifecycleConfiguration>

Tämän elinkaarikäytännön asettamiseen ämpäriimme käytämme alikomentoa setlifecycle:

s3cmd setlifecycle mypolicy.xml s3://MY_BUCKET

Voimme tarkistaa nykyisen käytännön alikomennolla getlifecycle:

s3cmd getlifecycle s3://MY_BUCKET

Ämpärin (tai objektin) tarkasteluun alikomennolla info:

s3cmd info s3://MY_BUCKET

s3://MY_BUCKET/ (bucket):
   Location:  cpouta-production
   Payer:     BucketOwner
   Expiration Rule: objects with key prefix 'weekly/' will expire in '365' day(s) after creation
   Policy:    none
   CORS:      none
   ACL:       project_xxxxxxx: FULL_CONTROL

Jotta objektisi kuuluvat elinkaarikäytännön piiriin, voit käyttää tunnisteita ja/tai etuliitteitä.

Tunnisteet lisätään otsakkeella muodossa x-amz-tagging:KEY=VALUE.
Etuliitettä voidaan ajatella "kansiona".

Tarkastellaan seuraavia tapauksia:

# Should be removed in 24 hours per rule ID: 1-days-expiration
s3cmd --add-header=x-amz-tagging:days=1 put MY_FILE_01.tar.gz s3://MY_BUCKET/
s3cmd --add-header=x-amz-tagging:days=1 put MY_FILE_02.tar.gz s3://MY_BUCKET/gone-in-one-day/

# Should be removed in 30 days per rule ID: 30-days-expiration
s3cmd --add-header=x-amz-tagging:days=30 put MY_FILE_03.tar.gz s3://MY_BUCKET/

# Should be removed in 30 days per rule ID: Daily
s3cmd put MY_FILE_04.tar.gz s3://MY_BUCKET/daily/

# Should be removed in 365 days per rule ID: Weekly
s3cmd put MY_FILE_05.tar.gz s3://MY_BUCKET/weekly/

Muita viitteitä elinkaaren määrittämiseen:

RedHat developer guide for Ceph storage.
Creating an intelligent object storage system with Ceph’s Object Lifecycle Management
Multiple lifecycles - s3cmd
Yllä olevaan liittyvä yllätyslöytö osoitteessa cloud.blog.csc.fi

Ämpärin käytön rajoittaminen tiettyihin IP-osoitteisiin

Voit rajoittaa ämpärin käytön tiettyihin IP-osoitteisiin määrittämällä käytännön.

Warning

Muista olla estämättä omaa pääsyäsi ämpäriin, sillä et voi käyttää ämpäriä tai korjata käytäntöä, jos teet niin.

Seuraavassa IP-käytäntöesimerkissä sallimme pääsyn ämpäriin POLICY-EXAMPLE-BUCKET IP-aliverkosta 86.50.164.0/24. Nimetään käytäntötiedosto myippolicy.json.

{
    "Version": "2012-10-17",
    "Id": "S3PolicyExample",
    "Statement": [
        {
            "Sid": "IPAllow",
            "Effect": "Deny",
            "Principal": "*",
            "Action": "s3:*",
            "Resource": [
                "arn:aws:s3:::POLICY-EXAMPLE-BUCKET",
                "arn:aws:s3:::POLICY-EXAMPLE-BUCKET/*"
            ],
            "Condition": {
                "NotIpAddress": {
                    "aws:SourceIp": "86.50.164.0/24"
                }
            }
        }
    ]
}

Tämän IP-käytännön asettamiseen ämpäriimme käytämme alikomentoa setpolicy:

s3cmd setpolicy myippolicy.json s3://POLICY-EXAMPLE-BUCKET

Nykyinen käytäntö voidaan tarkastella alikomennolla info.

Voimme poistaa nykyisen käytännön alikomennolla delpolicy:

s3cmd delpolicy s3://POLICY-EXAMPLE-BUCKET
s3://POLICY-EXAMPLE-BUCKET/: Policy deleted