CLI (Command Line Interface, zcli)

Назначение

CLI (Command Line Interface) — интерфейс командной строки, позволяющий управлять различными процессами объектного хранилища.

С Закрома.Хранение можно использовать стандартный AWS CLI (основные команды), но использование ZCLI позволяет получить доступ к расширенному набору операций (в том числе администрирование), присутствующему только в ЗАКРОМА. ZCLI поставляется вместе с дистрибутивом приложения.

Общие замечания

Во всех командах, например create storage, в которых нужно задавать сложную конфигурацию, она представляется в виде строки названий параметров и их значений, разделенных запятыми или точкой с запятой. Имя параметра отделяется от его значения знаком равенства(=). Строка параметров может быть с пробелами для читаемости, но, в таком случае, её следует заключить в кавычки, чтобы она рассматривалась интерпретатором команд как единое целое.

Все команды имеют как полную, так и сокращенную форму:

Copy
1
2подкоманды:
3
4s3-credentials, s3-cred
Развернуть

Использование переменных окружения

Опции корневой команды могут быть заданы в переменных окружения. Например, вы можете выполнить команду

Copy
1
2zcli -E ZAKROMA_ ...
3

тогда опция —user будет взята из ZAKROMA_USER, —secret_key (or -s) из ZAKROMA_SECRET_KEY, —server.host из ZAKROMA_SERVER_HOST.

Внимание! По умолчанию предполагается префикс ZCL_.

Чтобы задать пустой префикс: zcli -E "" …

Вы должны позаботиться о том, чтобы соответствующие переменные окружения были установлены.

Файл конфигурации

По умолчанию файл конфигурации ~/.zakroma-config.yaml, что в Unix-подобных системах обычно

/home/$USER/.zakroma-config.yaml, а в Windows C:\Users\%USER%\.zakroma-config.yaml.

Если использование файла по умолчанию нежелательно, то можно задать произвольный файл:

Copy
1
2zcli --config some_path/local.yml ...
3
4или
5
6z-cli -c some_path/local.yml ...
7

Файл конфигурации лучше создавать не вручную, а с помощью подкоманды save-cfg:

Copy
1
2в случае использования файла по умолчанию:
3
4zcli save-cfg --server.proto http --server.host zakroma-cloud.acme.com --server.port 8081 --server.path_prefix api --user admin --password passwd --access_key_id keyid --access_key seckey
5
6для произвольного some_path/local.yml:
7
8zcli --config some_path/local.yml save-cfg --server.proto http --server.host zakroma-cloud.acme.com --server.port 8081 --server.path_prefix api --user admin --password passwd --access_key_id keyid --access_key seckey
9
10или в более краткой версии:
11
12zcli -c some_path/local.yml save-cfg --server.proto http --server.host zakroma-cloud.acme.com --server.port 8081 --server.path_prefix api --u admin -p passwd -a keyid -s seckey
13
14если access_key_id не задан, он предполагается таким же, как имя пользователя (--user).
15

В конфигурацию можно добавить workspace по умолчанию и bucket по умолчанию с помощью —workspace и —bucket.

Workspace по умолчанию используется в подкомандах для бакетов, а workspace и bucket по умолчанию используются в подкомандах объектов и управления версионностью бакетов, если workspace и bucket не заданы в команде явно. Workspace и bucket по умолчанию также могут быть заданы с помощью переменных окружения.

Copy
1
2пример задания workspace и bucket:
3
4zcli save-cfg --server.proto http --server.host zakroma-cloud.acme.com --server.port 8081 --user admin --password passwd --w wrkspc1 --b bucket1
5
6workspace и bucket можно добавить(изменить) в уже существующую конфигурацию:
7
8zcli save-cfg --w wrkspc1 --b bucket1
9

Замечание! Если при создании конфигурации не задать —access_key (и access_key_id), то команда будет, при необходимости, пытаться получить ключ с сервера.

Управление хранилищами

Создание хранилища типа S3

Copy
1
2zcli --config local.yml storage create s3 --storage "name=s3storage, version=Common, host=localhost:9000, useSSL=no, skipCertificateVerification=true, region=us-east-1, usePathStyle=true, timeout=10, accessKey=otherkey, secretKey=someotherkey, defaultBucket=bucket, defaultPrefix=prefix"
3
4или
5
6zcli --config local.yml storage create s3
7

Создание хранилища типа ZDS

Copy
1
2zcli --config local.yml storage create zds --storage "name=zdsstorage, version=v1, bootstrapServers=localhost:2222|localhost:3333, useSSL=no, skipCertificateVerification=true, timeout=10, accessKey=otherkey, secretKey=someotherkey, defaultPath=cccc"
3
4или
5
6zcli --config local.yml s crt zds
7

Можно вводить параметры хранилища с клавиатуры. В этом случае команда будет показывать название параметра и ждать его ввода.

Copy
1
2zcli --config .auxdta/local.yml storage create s3
3

Удаление хранилища

Copy
1
2zcli --config local.yml storage delete --name st0002
3

Вывод списка хранилищ

Copy
1
2zcli --config local.yml storage list
3
4или
5
6zcli --c local.yml stg ls
7
8или
9
10zcli --c local.yml s l
11

Управление рабочими областями (Workspaces).

Copy
1
2zcli --config local.yml workspace create --workspace "name=wrkspc4, description=space4, defaultStorage=st0002, replicating=true"
3
4zcli --config local.yml workspace create --workspace name=wrkspc4,description=space4,defaultStorage=st0002,replicating=false
5
6cat wrkspc_cfg.txt | zcli --config local.yml workspace create
7
8zcli --config local.yml workspace update --name wrkspc4 --workspace name=wrkspc04,description=space04,defaultStorage=st0002
9
10zcli --config local.yml workspace delete --name wrkspc4
11
12zcli --config local.yml workspace list
13
14или, например, сокращенная версия команды:
15
16zcli -c local.yml wsp upd --n wrkspc4 --w name=wrkspc04,description=space04,defaultStorage=st0002
17
18или
19
20zcli -c local.yml w u --n wrkspc4 --w name=wrkspc04,description=space04,defaultStorage=st0002
21

Управление бакетами (Buckets)

Copy
1
2zcli --config local.yml bucket create --workspace wrkspc1 --bucket bck1
3
4zcli --config local.yml bucket delete --workspace wrkspc1 --bucket bck1
5
6zcli --config local.yml bucket list --workspace wrkspc1
7
8или, например, сокращенная версия команды:
9
10zcli --config local.yml b c --w wrkspc1 --b bck1
11
12или
13
14zcli -c local.yml b l --w wrspc1
15

Управление версионностью

Copy
1
2zcli --config local.yml bucket versioning get --workspace wrkspc1 --bucket bck1
3
4zcli --config local.yml bucket versioning put --workspace wrkspc1 --bucket bck1 --versioning enabled ('on' instead of 'enabled' is possible)
5
6zcli --config local.yml bucket versioning put --workspace wrkspc1 --bucket bck1 --versioning suspended ('off' instead of 'suspended' is possible)
7
8или, например, сокращенная версия команды:
9
10zcli -c local.yml bck vrs put --w wrkspc1 --b bck1 --v off
11
12или
13
14zcli -c local.yml b v p --w wrkspc1 --b bck1 --v off
15

Управление политиками хранения бакета

Copy
1
2Получить список групп для бакета:
3
4zcli mirgroup --workspace wrkspc1 --bucket bucket2w11 list
5
6Добавить для бакета группу и том:
7
8zcli mg --w wrkspc1 --b bucket2w11 add
9
10или (для тома zds хранилища типа Historical)
11
12zcli mg --w wrkspc1 --b bck1 add --mg "name=volume1, type=Historical, version=v1, sync=true,maxSize=10, storageName=zds,path=path1, zakromaPrefix=prefix"
13
14или (для тома zds хранилища типа Folder)
15
16zcli mg --w wrkspc1 --b bck1 add --mg "name=volume2, type=Folder, version=v1, maxSize=10, sync=true, storageName=zds, encryptionKey=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,path=path2"
17
18или (для тома s3 хранилища типа Historical)
19
20zcli mg --w wrkspc2 --b bck1 add --mg "name=volume3, type=Historical, version=v1, maxSize=10, sync=true, storageName=s3storage, bucket=bck2, prefix=prefix, zakromaPrefix=prefix"
21
22или (для тома s3 хранилища типа Folder)
23
24zcli mg --w wrkspc2 --b bck1 add --mg "name=volume3, type=Folder, version=v1, maxSize=10, sync=true, storageName=s3storage, bucket=bck2, encryptionKey=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA, prefix=prefix"
25
26Изменить порядковый номер группы:
27
28zcli mg --w wrkspc1 --b bucket2w11 ord --n mgb2w11 --order 4
29
30Изменить группу:
31
32zcli mg --w wrkspc1 --b bucket2w11 chg --n mgb2w11 --new-name mg1-b2w11 -max-size 42949672960
33
34Добавить том к группе:
35
36zcli mg --w wrkspc1 --b bck1 add --mg "name=volume3, type=Historical, version=v1, sync=true,maxSize=10, storageName=zds,path=path3"
37
38Удалить группу:
39
40zcli mg --w wrkspc1 --b bucket2w11 dlt --name mgb2w11
41
42Удалить том из группы:
43
44zcli mg --w wrkspc1 --b bucket2w11 rmv --name mgb2w11 --id 1f378b40-8e34-4352-9be7-322f52621b85
45
46  
47

Управление объектами

Общие команды

Copy
1
2Получить список объектов:
3
4zcli --config local.yml object list --workspace wrkspc1 --bucket bucket1 --start-after file1.txt
5
6zcli -c local.yml o l --w wrkspc1 --b bucket1 --s file1.txt
7
8Получить список версий:
9
10zcli --config local.yml object list-versions --workspace wrkspc1 --bucket bucket1 --key-marker file1.txt
11
12zcli -c local.yml o lv --w wrkspc1 --b bucket1 --k file1.txt
13
14Загрузить файл /home/doc/file.txt как объект file1.txt:
15
16zcli --config local.yml object put --workspace wrkspc1 --bucket bucket1 --object-key file1.txt --file-name /home/doc/file.txt
17
18zcli -c local.yml o p --w wrkspc1 --b bucket1 --k file1.txt --f /home/doc/file.txt
19
20Скачать объект file1.txt поместить его в /home/doc/new_file1.txt:
21
22zcli --config local.yml object get --workspace wrkspc1 --bucket bucket1 --object-key file1.txt --file-name /home/doc/new_file1.txt
23
24zcli -c local.yml o g --w wrkspc1 --b bucket1 --k file1.txt --f /home/doc/new_file1.txt
25
26При скачивании без использования опции --file-name содержимое объекта будет помещено в текущую директорию под именем объекта.
27

Работа с тегами объектов.

Copy
1
2Добавить теги:
3
4zcli --config local.yml object tags put --workspace wrkspc1 --bucket bucket1 --object-key file1.txt --version-id 21AB8121297712F --tags "key1 = val1, key2 =val2 "
5
6zcli -c local.yml o t p --w wrkspc1 --b bucket1 --k file1.txt --v 21AB8121297712F --t key1=val1,key2=val2
7
8cat tags.txt | zcli -c local.yml o t p --w wrkspc1 --b bucket1 --k file1.txt --v 21AB8121297712F
9
10Получить теги:
11
12zcli --config local.yml object tags get --workspace wrkspc1 --bucket bucket1 --object-key file1.txt --version-id 21AB8121297712F
13
14zcli -c local.yml o t g --w wrkspc1 --b bucket1 --k file1.txt --v 21AB8121297712F
15
16Удалить теги:
17
18zcli --config local.yml object tags delete --workspace wrkspc1 --bucket bucket1 --object-key file1.txt --version-id 21AB8121297712F
19
20zcli -c local.yml o t d --w wrkspc1 --b bucket1 --k file1.txt --v 21AB8121297712F
21

Multipart uploads.

CLI выполнит Multipart upload автоматически, если загружаемый файл окажется больше 5 Гигабайт (5 368 709 120 байт), разделив файл на части по 8 Мб.

Размер последней часть будет равен остатку от деления размера файла на 8 Мб. С помощью параметра —part-size(—s) можно задать желаемый размер части.

Однако, надо иметь в виду, что он не может быть меньше 5 Мб и больше 5 Гб. Кроме того, если количество частей при заданном part-size превысит 10000, CLI автоматически увеличит размер части так, чтобы количество частей не превышало 10000. Если в процессе автоматической multipart-загрузки произойдет ошибка, можно попробовать продолжить загрузку, заново запустив команду с дополнительным параметром —start-from-part(—p), указав номер части, загрузка которой прервалась из-за ошибки.

Замечание! Даже если размер загружаемого файла не превышает 5 Гб, и задан параметр —part-size, CLI выполнит multipart upload.

Также возможна загрузка нескольких файлов, как единого объекта с помощью команд Create multipart upload + Upload object part + Complete multipart upload.

Части, загружаемые с помощью команды Upload object part, можно загружать в любом порядке, но объект будет собран в порядке возрастания номеров частей.

При необходимости можно отказаться от создания объекта, инициированного командой Create multipart upload, и очистить хранилище от уже загруженных частей объекта с помощью команды Abort multipart upload. Например:

Copy
1
2Инициировать загрузку - Create multipart upload:
3
4zcli -c local.yml m cr --w wrkspc1 --b bucket1 --k file1.txt
5
6Загрузить части - Upload parts:
7
8zcli -c local.yml m u --w wrkspc1 --b bucket1 --k file1.txt --i cf333a14-01e5-4ed1-bbd8-4af105823591 --n 1 --f /home/doc/file1.txt
9
10...
11
12zcli -c local.yml m u --w wrkspc1 --b bucket1 --k file1.txt --i cf333a14-01e5-4ed1-bbd8-4af105823591 --n 15 --f /home/doc/file15.txt
13
14Завершить и создать объект - Complete multipart upload:
15
16zcli -c local.yml m cm --w wrkspc1 --b bucket1 --k file1.txt --i cf333a14-01e5-4ed1-bbd8-4af105823591
17
18Или прекратить/уничтожить загрузку и очистить память хранилища от уже загруженных частей - Abort multipart upload:
19
20zcli -c local.yml m a --w wrkspc1 --b bucket1 --k file1.txt --i cf333a14-01e5-4ed1-bbd8-4af105823591
21
22Получить список инициированных, но не завершенных и не уничтоженных загрузок:
23
24zcli -c local.yml m lu --w wrkspc1 --b bucket1
25
26Есть команда получения списка уже загруженных частей объекта:
27
28zcli -c local.yml m lp --w wrkspc1 --b bucket1 --k file1.txt --i cf333a14-01e5-4ed1-bbd8-4af105823591
29

Управление ключами доступа (S3 Credentials)

Copy
1
2Получить s3 credentials:
3
4zcli --config local.yml s3-credentials get
5
6zcli --config local.yml s3-cred g
7
8Создать s3 credentials:
9
10zcli --config local.yml s3-credentials create --s3-credentials "accessKeyId=accessKeyId, secretKey=accessKey, expirationTime=2026-01-02 15:04:05"
11
12zcli --config local.yml s3-cred create
13

Управление политиками доступа бакета и рабочей области

Copy
1Получить список политик доступа рабочей области:
2
3zcli --config local.yml access-rules get-wrk --wname=wrk
4
5zcli --config local.yml acr get-wrk --workspace=wrk
Развернуть

Presigned URLs

Copy
1
2Если конфигурация не задана ни в файле, ни в переменных окружения:
3
4zcli --server.proto http --server.host zakroma-cloud.acme.com --server.port 8081 --user admin --password passwd --access_key_id keyid --access_key secrkey p u --f test_cli.txt --l 600
5
6--access_key_id и --access_key, впрочем, писать необязательно, так как команда может взять их с сервера.
7
8Если задана конфигурация:
9
10URL для загрузки объекта действительный в течение 10 минут, начиная с 11 ноября 2023 с 21:21:00 местного времени:
11
12zcli p u --f test_cli.txt --l 600 --t 2023-11-10T21:21:00
13
14zcli presign upload --f test_cli.txt --l 600 --t 2023-11-10T21:21:00
15
16URL для скачивания объекта, действительный в течение 24 часов начиная с момента исполнения команды:
17
18zcli p g --k test_cli.txt --l 86400
19
20zcli presign download --object-key test_cli.txt --l 86400
21
22URL для удаления объекта действительный в течение 10 минут, начиная с 12 ноября 2023 с 00:00:00 по Гринвичу:
23
24zcli p d --k test_cli.txt --t "2023-11-12 21:21:00Z" --l 600
25
26zcli presign delete --object-key test_cli.txt --t "2023-11-12 21:21:00Z" --l 600
27
28URL для инициации multipart загрузки объекта:
29
30zcli p cr --k test_cli.txt --t "2023-11-12 21:21:00Z" --l 600
31
32zcli presign create-multipart-upload --k test_cli.txt --t "2023-11-12 21:21:00Z" --l 600
33
34URL для нормального завершения multipart загрузки и сборки объекта из частей:
35
36zcli p cm --k test_cli.txt --t "2023-11-12 21:21:00Z" --i cf333a14-01e5-4ed1-bbd8-4af105823591 --l 600
37
38zcli presign complete-multipart-upload --k test_cli.txt --upload-id cf333a14-01e5-4ed1-bbd8-4af105823591 --t "2023-11-12 21:21:00Z" --l 600
39
40URL для отказа от multipart загрузки объекта и очистки памяти в хранилище от уже загруженных частей:
41
42zcli p ab --k test_cli.txt --i cf333a14-01e5-4ed1-bbd8-4af105823591 --t "2023-11-12 21:21:00Z" --l 600
43
44zcli p abort-multipart-upload --object-key test_cli.txt --upload-id cf333a14-01e5-4ed1-bbd8-4af105823591 --t "2023-11-12 21:21:00Z" --l 600
45

Для пользователей ОС Windows:

Флаг командной строки —escape-win/—ew/-e заменяет в сгенерированном URL символ % на %%, а символ & на ^&, что позволяет использовать получившийся URL в интерпретаторе команд CMD.EXE непосредственно, например следующие 3 команды делают:

1. создаёт в текущей директории файл getfile.bat и записывает в него слово ‘curl ‘;
2. дописывает в файл сгенерированный URL;
3. исполняет getfile.bat, что приводит к скачиванию объекта test_cli.txt. file.bat

Copy
1< nul (set /p s=curl ) > getfile.bat
2zcli p g --k test_cli.txt --l 6000 -e >> getfile.bat
3.\get
4