docs/source/reference/minio-mc/mc-alias-set.rst

.. _minio-mc-alias-set:
.. _minio-mc-alias:
.. _alias:

================
``mc alias set``
================

.. default-domain:: minio

.. contents:: Table of Contents
   :local:
   :depth: 2

.. mc:: mc alias
.. mc:: mc alias set

.. |command| replace:: :mc-cmd:`mc alias set`

Syntax
------

.. start-mc-alias-set-desc

The :mc:`mc alias set` command adds or updates an alias to the local
:program:`mc` configuration.

.. end-mc-alias-set-desc

.. tab-set::

   .. tab-item:: EXAMPLE

      The following command adds an :ref:`alias <alias>` for a MinIO
      deployment ``myminio`` running at the URL
      ``https://myminio.example.net``. :program:`mc` uses the specified 
      username and password for authenticating to the MinIO deployment:

      .. code-block:: shell
         :class: copyable
         
         mc alias set myminio https://myminio.example.net minioadminuser minioadminpassword

      If the ``myminio`` alias already exists, the command overwrites that
      alias with the new URL, access key, and secret key.

   .. tab-item:: SYNTAX

      The :mc-cmd:`mc alias set` command has the following syntax:

      .. code-block:: shell
         :class: copyable

         mc [GLOBALFLAGS] alias set \ 
                          [--api "string"]                           \
                          [--path "string"]                          \
                          ALIAS                                      \ 
                          URL                                        \
                          ACCESSKEY                                  \
                          SECRETKEY

      .. include:: /includes/common-minio-mc.rst
         :start-after: start-minio-syntax
         :end-before: end-minio-syntax

Parameters
~~~~~~~~~~

.. mc-cmd:: ALIAS

   *Required* The name to associate to the S3-compatible service.

.. mc-cmd:: URL

   *Required* The URL to the S3-compatible service endpoint. For example:

   ``https://minio.example.net``

.. mc-cmd:: ACCESSKEY
   
   *Required*

   The access key for authenticating to the S3 service.

.. mc-cmd:: SECRETKEY

   *Required*

   The secret key for authenticating to the S3 service.

.. mc-cmd:: --api
   
   
   *Optional*

   Specifies the signature calculation method to use when connecting to the
   S3-compatible service. Supports the following values:

   - ``S3v4`` (Default)
   - ``S3v2``

   .. note::

      AWS Signature V2 is considered
      `deprecated <https://aws.amazon.com/blogs/aws/amazon-s3-update-sigv2-deprecation-period-extended-modified/>`__
      by AWS. :mc-cmd:`mc alias set` includes this option only for S3 buckets
      or services still reliant on the Signature V2.
      
      Use ``S3v4`` unless explicitly required by the S3-compatible service.
      MinIO server does not rely on nor require ``S3v2``, nor are all API
      operations available on ``S3v2``. 

.. mc-cmd:: --path
   

   *Optional*

   Specifies the bucket path lookup setting used by the server. Supports the
   following values:

   - ``"auto"`` (Default)
   - ``"on"``
   - ``"off"``

Global Flags
~~~~~~~~~~~~

.. include:: /includes/common-minio-mc.rst
   :start-after: start-minio-mc-globals
   :end-before: end-minio-mc-globals

Examples
--------

Add or Update an Alias for a MinIO Deployment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Use :mc-cmd:`mc alias set` to add an S3-compatible service for use with
:program:`mc`:

.. tab-set::

   .. tab-item:: Example

      The following command creates a new alias ``myminio`` pointing at a
      MinIO deployment at ``https://minio.example.net``. The
      alias uses the ``miniouser`` and ``miniopassword`` credentials for
      performing operations against the deployment.

      .. code-block:: shell
         :class: copyable

         mc alias set myminio https://minio.example.net miniouser miniopassword

      If the ``myminio`` alias already exists, the 
      :mc-cmd:`mc alias set` command overwrites that alias with the specified
      arguments.

   .. tab-item:: Syntax

      .. code-block:: shell
         :class: copyable

         mc alias set ALIAS HOSTNAME ACCESSKEY SECRETKEY

      - Replace ``ALIAS`` with the the name to associate to the 
        MinIO service.

      - Replace ``HOSTNAME`` with the URL for any node in the MinIO
        deployment. You can alternatively specify the URL for a load balancer
        or reverse proxy managing connections to the MinIO deployment.

      - Replace ``ACCESSKEY`` and ``SECRETKEY`` with credentials for a user
        on the MinIO deployment.

Behavior
--------

S3 Compatibility
~~~~~~~~~~~~~~~~

.. include:: /includes/common-minio-mc.rst
   :start-after: start-minio-mc-s3-compatibility
   :end-before: end-minio-mc-s3-compatibility

Required Credentials and Access Control
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:mc-cmd:`mc alias set` requires specifying an access key and corresponding
secret key for the S3-compatible host. :program:`mc` functionality is limited
based on the policies associated to the specified credentials. For example, if
the specified credentials do not have read/write access to a specific bucket,
:program:`mc` cannot perform read or write operations on that bucket.

For more information on MinIO Access Control, see
:ref:`minio-access-management`. 

For more complete documentation on S3 Access Control, see
:s3-docs:`Amazon S3 Security <security.html>`.

For all other S3-compatible services, defer to the documentation for that
service.