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

30 июня 2025 12 мин 17

Инструмент s3cmd — это универсальный интерфейс командной строки для управления объектами и бакетами Amazon S3. Он позволяет пользователям:

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

В статье рассказываем о том, как установить, настроить s3cmd и начать с ним работу.

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

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

  • адрес,
  • ключ доступа,
  • секретный ключ,
  • регион.

Установка

Вот несколько вариантов установки приложения s3cmd:

  • Через пакетный менеджер ОС — самый простой способ, но приложение может отсутствовать в репозитории вашей системы.
  • Из репозитория PyPA (Python Package Authority) — удобный вариант для пользователей Python, так как s3cmd можно установить через pip.
  • Из исходного кода — вы можете скачать архив с файлами программы со страницы релизов и собрать её вручную.

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

Чтобы выполнить установку через пакетный менеджер, следует выполнить одну из команд в зависимости от вашей системы:

  • macOS или Lunix с установленным пакетным менеджером Homebrew
brew install s3cmd
  • Debian и производные дистрибутивы (Ubuntu и другие)
sudo apt install s3cmd
  • современные RedHat-based системы
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

Полный вывод процесса настройки выглядит так:

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

  • Access Key — Ключ доступа, полученный ранее в разделе Доступы.
  • Secret Key — Секретный ключ из данных для доступа Объектного хранилища.
  • S3 Endpoint — адрес сервера, куда направляются API-запросы для выполнения различных операций с объектным хранилищем. Значение: s3.1dedic.ru.
  • DNS-style bucket+hostname:port template for accessing a bucket — формат доменного имени для доступа к бакетам в domain-based стиле. Значение: %(bucket)s.s3.1dedic.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/1dedic.s3cfg --configure
Папка, выбранная для хранения конфигурационного файла, должна быть создана заранее. Если каталога не существует, приложение не сможет сохранить в него настройки.

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

alias s31dedic='s3cmd -c $HOME/s3/1dedic.s3cfg'

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

s31dedic --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 позволяет задать MIME-тип по умолчанию, когда автоматическое распознавание типа файла отключено или его не удалось определить.
  • --guess-mime-type для автоматического определения типа.
  • --no-guess-mime-type отключает автоматическое определение типа файлов.
  • --no-mime-magic отключает mime magic при автоматическом определении типов файлов.
  • -m MIME/TYPE, --mime-type=MIME/TYPE устанавливает указанный MIME-тип для всех загружаемых файлов.

По умолчанию файлы, размер которых больше указанного в настройках, загружаются частями (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 — поддержка размещения статических веб-сайтов. Активируется для отдельного бакета, а доступ к сайту осуществляется по специальному адресу формата:

http://ИМЯ_БАКЕТА.s3w.1dedic.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.1dedic.ru/.

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

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

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

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

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

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

Initiated Path Id

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

Чтобы просмотреть загруженные части, нужно выполнить команду:

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

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

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

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

Чтобы прервать загрузку и освободить занятое ею место, выполните следующую команду:

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 — показывать размеры объектов в удобочитаемом формате,
  • 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.1dedic.ru/),
  • website_error — имя файла ошибок для статических сайтов,
  • website_index — имя файла индексной страницы статических сайтов по умолчанию.

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

При составной загрузке (multipart)

  • максимальное количество частей: 10 000,
  • минимальный размер части: 5 Мб (кроме последней).

При одиночной загрузке (put)

  • максимальный размер файла: 5 Гб.