Управление объектным хранилищем с помощью s3cmd

Инструмент s3cmd — бесплатное консольное приложение без графического интерфейса с открытым исходным кодом для управления объектными хранилищами с поддержкой Amazon S3 API. 

Для использования приложения вам понадобится активная услуга «Объектное хранилище S3» и данные доступа к S3 API, которые можно получить по кнопке Доступы в списке услуг:

Для дальнейшей работы с приложением вам понадобятся:

• Адрес
• Ключ доступа
• Секретный ключ
• Регион

Установка приложения

Установка s3cmd может быть выполнена несколькими способами:

• через пакетный менеджер операционной системы (приложение может отсутствовать в репозитории),
• из репозитория PyPA (Python Package Authority),
• из файлов исходного кода, поставляемых со страницы релизов программы.

Последние два способа дают доступ к последней версии программы, тогда как версия в официальном репозитории операционной системы может быть устаревшей. 

Для установки через пакетный менеджер нужно выполнить одну из команд:

• macOS или Lunix с установленным пакетным менеджером Homebrew:

brew install s3cmd

• для Debian-based дистрибутивов Linux:

sudo apt install s3cmd

• для актуальных версий RedHat-based дистрибутивов Linux:

sudo dnf install s3cmd

• для предыдущих версий RedHat-based дистрибутивов Linux:

sudo yum install s3cmd

Для установки актуальной версии из PyPA репозитория вам может предварительно понадобится установка пакетного менеджера Python - pip через установленный на вашем компьютере пакетный менеджер, например:

yum install python-pip

После этого само приложение можно установить командой:

sudo pip install s3cmd

Для установки из файлов исходного кода или в случае проблем с установкой можно обратиться к официальной документации приложения.

Настройка приложения

После установки s3cmd, для работы с объектным хранилищем, нужно его настроить, в том числе указать реквизиты доступа. Для запуска настройки выполните команду:

s3cmd --configure

Полный вывод процесса настройки выглядит следующим образом:

Enter new values or accept defaults in brackets with Enter.      
Refer to user manual for detailed description of all options.
Access key and Secret key are your identifiers for Amazon S3. Leave them empty for using the env variables.
Access Key: XXXXXXXXXXXXXXXXXXXX
Secret Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Default Region [US]: default
Use "s3.amazonaws.com" for S3 Endpoint and not modify it to the target Amazon S3.
S3 Endpoint [s3.amazonaws.com]: s3.firstvds.ru
Use "%(bucket)s.s3.amazonaws.com" to the target Amazon S3. "%(bucket)s" and "%(location)s" vars can be used
if the target S3 system supports dns based buckets.
DNS-style bucket+hostname:port template for accessing a bucket [%(bucket)s.s3.amazonaws.com]: %(bucket)s.s3.firstvds.ru
Encryption password is used to protect your files from reading
by unauthorized persons while in transfer to S3
Encryption password: ********
Path to GPG program [/usr/bin/gpg]: 
When using secure HTTPS protocol all communication with Amazon S3
servers is protected from 3rd party eavesdropping. This method is
slower than plain HTTP, and can only be proxied with Python 2.7 or newer
Use HTTPS protocol [Yes]: Yes
On some networks all internet access must go through a HTTP proxy.
Try setting it here if you can't connect to S3 directly
HTTP Proxy server name: 
New settings:
  Access Key: XXXXXXXXXXXXXXXXXXXX
  Secret Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  Default Region: default
  S3 Endpoint: s3.firstvds.ru
  DNS-style bucket+hostname:port template for accessing a bucket: %(bucket)s.s3.firstvds.ru
  Encryption password: ********
  Path to GPG program: /usr/bin/gpg
  Use HTTPS protocol: True
  HTTP Proxy server name: 
  HTTP Proxy server port: 0
Test access with supplied credentials? [Y/n] Y
Please wait, attempting to list all buckets...
Success. Your access key and secret key worked fine :-)
Now verifying that encryption works...
Success. Encryption and decryption worked fine :-)
Save settings? [y/N] y

В процессе настройки s3cmd запрашивает следующие данные:

• Access Key — данные из поля Ключ доступа из данных для доступа услуги.
• Secret Key — данные из поля Секретный ключ из данных для доступа услуги.
• Default Region — регион расположения серверов. Значение: default.
• S3 Endpoint — адрес сервера, на который будут отправляться API-запросы для работы с объектным хранилищем. Значение: s3.firstvds.ru.
• DNS-style bucket+hostname:port template for accessing a bucket — шаблон имени домена для обращения к бакетам объектного хранилища в domain-based стиле. Значение: %(bucket)s.s3.firstvds.ru.
• Encryption password — пароль для шифрования данных в момент передачи их в объектное хранилище.
• Path to GPG program — путь к программе шифрования. Обычно определяется автоматически и не требует изменения.
• Use HTTPS protocol — флаг использования HTTPS-протокола для взаимодействия с хранилищем. Значение: Yes.
• HTTP Proxy server name и HTTP Proxy server port необходимо указывать, только если ваша система использует прокси-сервер для доступа в интернет.

После ввода всех настроек программа предложит вам проверить введенные значения, после чего произведёт их проверку и в случае успеха предложит сохранить данные.

Теперь s3cmd готова для работы с вашим объектным хранилищем.

Поддержка нескольких конфигураций

По умолчанию приложение сохраняет настройки в конфигурационный файл .s3cfg в домашней директории пользователя. Это позволяет работать только с одним набором учётных данных для доступа к объектному хранилищу. При этом есть возможность использовать несколько файлов конфигурации для разных учётных данных и хранить их в удобном для вас месте.

Чтобы указать имя файла конфигурации, необходимо вызывать приложение с указанием параметра  -c имя_файла_настроек, например, для запуска процедуры настройки нового подключения:

s3cmd -c $HOME/s3/firstvds.s3cfg --configure

Важно: каталог для сохранения файла конфигурации должен существовать, иначе после указания приложение не сможет сохранить настройки в файл.

Также имя файла конфигурации нужно будет указывать при выполнении всех действий с объектным хранилищем в будущем. Для удобства работы в будущем вы можете создать алиас команды с уже указанным конфигом. Для bash это можно сделать, отредактировав привычным для вас текстовым редактором файл $HOME/.bashrc, добавив строку вида:

alias s3firstvds='s3cmd -c $HOME/s3/firstvds.s3cfg'

В этом случае предыдущая команда будет выглядеть уже так:

s3firstvds --configure

Часто для применения настроек алиасов требуется создание новой сессии bash. То есть нужно либо перезайти в консоль, либо открыть новое окно консоли.

Работа с бакетами и объектами

Объектное хранилище содержит в себе две сущности: бакеты — верхний уровень разделения объектов хранилища и объекты, размещаемые в бакетах. При этом имена объектов могут имитировать иерархическую структуру, похожую на каталоги файловой системы. Программа s3cmd поддерживает широкий набор функций для работы как с бакетами, так и с объектами.

Работа с бакетами

Для создания нового бакета используется команда:

s3cmd mb s3://ИМЯ_БАКЕТА

Важно. На имя бакета действуют следующие ограничения: 

• имя бакета по формату не должно совпадать с форматом IP-адресов,
• имя бакета должно быть в пределах от 3 до 63 символов,
• имя бакета должно быть серией из одной или нескольких "меток", смежные “метки” разделяются одной точкой (.),
• “метка” может содержать строчные буквы, цифры и дефисы и должна начинаться и заканчиваться строчной буквой или цифрой.

Для вывода списка бакетов используется команда:

s3cmd ls

Для вывода списка бакетов с объектами в них используется команда:

s3cmd la

Для удаления бакета используется команда: 

s3cmd rb s3://ИМЯ_БАКЕТА

Важно: удалить можно только пустой бакет, то есть не содержащий в себе объектов. При этом префиксы, имитирующие структуру каталогов для объектов, не учитываются.

Переименование бакетов не поддерживается, но можно создать новый бакет и переместить все объекты из старого бакета в новый одной командой:

s3cmd mv --recursive s3://ИМЯ_БАКЕТА_1 s3://ИМЯ_БАКЕТА_2

Для просмотра занятого всеми или одним бакетом места используется команда:

s3cmd du [-H] [s3://ИМЯ_БАКЕТА[/ПРЕФИКС]]

Если не указывать часть “[s3://ИМЯ_БАКЕТА[/ПРЕФИКС]]”, будет выведена информация по всем доступным бакетам. Если указать “[/ПРЕФИКС]”, будет отображена информация по конкретному виртуальному каталогу бакета. Флаг “[-H]” включает отображение занятого места в более удобном формате.

Посмотреть дополнительную информацию о бакете можно командой:

s3cmd info s3://ИМЯ_БАКЕТА[/ПРЕФИКС]

Команда выводит информацию о размещении бакета, настроенной политике, правилах CORS и настройках доступа.

Работа с объектами

Для загрузки файла (файлов) в бакет используется команда:

s3cmd put ФАЙЛ [ФАЙЛ...] s3://ИМЯ_БАКЕТА[/ПРЕФИКС]

Где ФАЙЛ — локальный путь к файлу или файлам, загружаемым в бакет, “[/ПРЕФИКС]” — имя виртуального каталога, в который будет загружен файл или файлы. 

При загрузке файлов можно сразу назначить правила доступа к объектам, указав параметр “--acl-public” для предоставления публичного доступа или “--acl-private” — для ограничения доступа владельцем бакета, если сам бакет имеет публичный доступ.

Также, при загрузке файлов, можно управлять mime типом загружаемых файлов, который будет использоваться, например, при доступе к объектам из браузера. Для этого команда поддерживает несколько дополнительных параметров:

• --default-mime-type=DEFAULT_MIME_TYPE для указания типа файла по умолчанию, если отключено автоматическое определение типа или тип определить не удалось,
• --guess-mime-type для автоматического отправления типа,
• --no-guess-mime-type для отключения автоматического определения типа файлов,
• --no-mime-magic для отключения mime magic при автоматическом определении типов файлов,
• -m MIME/TYPE, --mime-type=MIME/TYPE для загрузки все всех файлов с указанным типом.

По умолчанию все файлы, размер которых превышает указанный в настройках, загружаются по частям (multi-part upload). Чтобы попробовать загрузить файл полностью одним запросом, даже если его размер превышает указанную настройку, указывается параметр --disable-multipart. Использовать данный параметр не рекомендуется, так как есть определённые ограничения на размер загружаемых данных в одном запросе, заданные в самом объектном хранилище.

Для скачивания объекта из бакета используется команда:

s3cmd get s3://ИМЯ_БАКЕТА[/ПРЕФИКС]/ОБЪЕКТ ФАЙЛ

Скачать файл можно, только если вы являетесь владельцем бакета/объекта или вашему пользователю предоставлен к нему доступ.

Для удаления объекта из бакета используется команда:

s3cmd del s3://ИМЯ_БАКЕТА[/ПРЕФИКС]/ОБЪЕКТ ФАЙЛ

Также можно использовать “s3cmd rm” — данная команда является псевдонимом для указанной выше.

Для удаления всех файлов в бакете можно использовать команду:

s3cmd del --force --recursive s3://ИМЯ_БАКЕТА

Для получения дополнительной информации об объекте можно использовать команду:

s3cmd info s3://ИМЯ_БАКЕТА[/ПРЕФИКС]/ОБЪЕКТ

Команда выводит информацию о размере объекта, дате изменения, mime типе, настроенных политиках, правилах доступа и дополнительную мета информацию об объекте.

Для копирования объекта используется команда:

s3cmd cp s3://ИМЯ_БАКЕТА_1[/ПРЕФИКС]/ОБЪЕКТ_1 s3://ИМЯ_БАКЕТА_2[[/ПРЕФИКС]/ОБЪЕКТ_2]

Для перемещения объекта используется команда:

s3cmd mv s3://ИМЯ_БАКЕТА_1[/ПРЕФИКС]/ОБЪЕКТ_1 s3://ИМЯ_БАКЕТА_2[[/ПРЕФИКС]/ОБЪЕКТ_2]

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

Для бакетов и объектов в объектном хранилище можно настраивать правила доступа (ACL) для анонимных пользователей, а также для других пользователей хранилища. 

Для предоставления общего доступа к бакету и/или объектам в нём используется команда:

s3cmd setacl --acl-public s3://ИМЯ_БАКЕТА_1[[/ПРЕФИКС]/ОБЪЕКТ]

Для закрытия общего доступа к бакету и/или объектам в нём используется команда:

s3cmd setacl --acl-private s3://ИМЯ_БАКЕТА_1[[/ПРЕФИКС]/ОБЪЕКТ]

Для применения настроек ко всем имеющимся в бакете объектам можно добавить к команде параметр --recursive.

Также права доступа к объекту или бакету можно назначить определённому пользователю объектного хранилища. Для этого нужно в настройках другой услуги объектного хранилища узнать имя пользователя и использовать одну из команд:

s3cmd setacl --acl-grant=ПРАВА:ПОЛЬЗОВАТЕЛЬ s3://ИМЯ_БАКЕТА_1[[/ПРЕФИКС]/ОБЪЕКТ]

или

s3cmd setacl --acl-revoke=ПРАВА:ПОЛЬЗОВАТЕЛЬ s3://ИМЯ_БАКЕТА_1[[/ПРЕФИКС]/ОБЪЕКТ]

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

Параметр ПРАВА может принимать одно из следующих значений:

• read — даёт права на чтение списка объектов в бакете или на чтение указанных объектов бакета,
• write — даёт права на добавление объектов в бакет. Не используется для конкретных объектов,
• read_acp — даёт права на чтение настроек доступа к бакету или объектам,
• write_acp — даёт права на изменение настроек доступа к бакету или объектам,
• full_control — даёт все указанные выше права на бакет или объекты.

Доступ по ссылке

Дополнительно s3cmd позволяет сгенерировать ссылку с ограниченным по времени публичным доступом к бакету или объекту:

s3cmd signurl s3://ИМЯ_БАКЕТА_1[[/ПРЕФИКС]/ОБЪЕКТ] +ВРЕМЯ_В_СЕКУНДАХ 

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

Дополнительные функции бакетов

Включение статического веб-сайта

Одной из дополнительных возможностей объектного хранилища S3 является возможность размещения статических веб-сайтов. Функция включается для определённого бакета, а доступ к сайту выполняется по URL с именем вида http://ИМЯ_БАКЕТА.s3w.firstvds.ru/

Для включения функции веб-сайта нужно выполнить команду:

s3cmd ws-create --ws-index=INDEX --ws-error=ERROR s3://ИМЯ_БАКЕТА

Где параметры:

• --ws-index — имя объекта в бакете с HTML-кодом страницы сайта,
• --ws-error — имя объекта в бакете с HTML-кодом страницы ошибок.

Для отключения функции веб-сайта для бакета нужно выполнить команду:

s3cmd ws-delete s3://ИМЯ_БАКЕТА

Для просмотра текущей конфигурации веб-сайта для бакета нужно выполнить команду:

s3cmd ws-info s3://ИМЯ_БАКЕТА

Для корректного отображения ссылок на сайт программой в файле конфигурации нужно изменить значение параметра website_endpoint на http://%(bucket)s.s3w.firstvds.ru/.

Управление незавершенными загрузками

В процессе загрузки больших файлов в объектное хранилище могут возникать ошибки или обрывы связи. В таком случае часть файлов остается загруженной не до конца, но будет занимать место в бакете и хранилище. Рекомендуется периодически проверять хранилище на наличие таких загрузок и принудительно их завершать (или настроить политику срока жизни незавершенных загрузок).

Для просмотра списка незавершенных загрузок по бакету нужно выполнить команду:

s3cmd multipart s3://ИМЯ_БАКЕТА

Список незавершённых загрузок выглядит следующим образом:

s3://ИМЯ_БАКЕТА/
Initiated Path Id
ДАТА s3://ИМЯ_БАКЕТА/ОБЪЕКТ ID_ЗАГРУЗКИ

Для просмотра уже загруженных частей загрузки нужно выполнить команду:

s3cmd listmp s3://ИМЯ_БАКЕТА/ОБЪЕКТ ID_ЗАГРУЗКИ

Для продолжения загрузки (при наличии такой возможности) нужно выполнить команду:

s3cmd put ФАЙЛ --upload-id ID_ЗАГРУЗКИ s3://ИМЯ_БАКЕТА/[/ПРЕФИКС]

То есть команда идентична загрузке файла в хранилище, но с указанием ID существующей загрузки.

Для прерывания загрузки и очистки занимаемого ей места нужно выполнить команду:

s3cmd abortmp s3://ИМЯ_БАКЕТА/ОБЪЕКТ ID_ЗАГРУЗКИ

Команда отменит незавершённую загрузку и удалит ранее загруженные части файла.

Дополнительные параметры файла конфигурации

Для тонкой настройки приложения может понадобится редактирование файла конфигурации s3cmd ($HOME/.s3cfg - файл настроек по умолчанию). Например, можно изменить значение по умолчанию следующих параметров:

• default_mime_type — mime тип загружаемых файлов по умолчанию,
• guess_mime_type - True или False — нужно ли определять тип загружаемых файлов, если не указан параметр при загрузке файлов,
• use_mime_magic - True или False — нужно ли использовать magic для определения типа файлов,
• human_readable_sizes - True или False — нужно ли по умолчанию выводить размер объектов в человеко-читаемом (human readable) формате,
• multipart_chunk_size_mb — размер одной части при multipart загрузки,
• multipart_copy_chunk_size_mb — размер одной части при multipart копировании,
• multipart_max_chunks — максимальное количество частей, на которые может быть разбит файл при multipart загрузке,
• preserve_attrs - True или False — нужно ли сохранять атрибуты файлов при загрузке в metadata,
• public_url_use_https - True или False — использовать ли https в ссылках для доступа к объектам,
• website_endpoint — шаблон имени статических сайтов (рекомендуется установить значение https://%(bucket)s.w3s.firstvds.ru/),
• website_error — имя файла ошибок статических сайтов по умолчанию,
• website_index — имя файла индексной страницы статических сайтов по умолчанию.

Настройки, касающиеся загрузки файлов (multipart_chunk_size_mb, multipart_copy_chunk_size_mb, multipart_max_chunks), нужно менять с осторожностью, так как у хранилища есть собственные ограничения:

• 10000 — максимальное количество отдельных частей при составной (multipart) загрузке,
• 5 Мб — минимальный размер части при составной (multipart) загрузке, кроме последней части,
• 5 Гб — максимальный размер файла за один put-запрос.