.. raw:: html
Quick-start - VMs and Barebone
==============================
Welcome to the StorageFabric quick-start guide.
This guide provides instructions to getting started with StorageFabric
using the StorageFabric software repository.
For more detailed instructions, refer to :doc:`../installation` and the StorageFabric :doc:`../tutorials`.
Prior to using this guide, you may also be interested in learning :doc:`../../about/howitworks`.
*****
To get started with StorageFabric, take the following steps:
#. `Create Buckets and Access Keys with Storage Providers`_
#. `Install StorageFabric`_
#. `Setup StorageFabric`_
#. `Configure StorageFabric`_
#. `Upload files securely using StorageFabric`_
*****
|
Create Buckets and Access Keys with Storage Providers
-----------------------------------------------------
Create buckets where your StorageFabric configuration data
and your user data will be stored.
With StorageFabric, all data (including configuration)
is stored with providers. This makes StorageFabric components stateless, resulting in less
management overhead for users and enabling quick disaster recovery.
:stepnumberonedigit:`1` :stepheading:`Create a configuration bucket and a data bucket with a storage provider.`
.. include:: common/prerequisites-buckets.rst
*****
:stepnumberonedigit:`2` :stepheading:`Get your storage provider access credentials.`
.. include:: common/prerequisites-credentials.rst
Next Step: `Install StorageFabric`_
|
*****
Install StorageFabric
---------------------
Using the Virtalica Repository
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. note::
Prior to proceeding with repository setup, you must create
buckets and access keys as described in the Section `Create Buckets and Access Keys with Storage Providers`_.
:stepnumberonedigit:`1` :stepheading:`Get access to the Virtalica repository.`
To access StorageFabric software packages, you must obtain access to
the Virtalica repository. For a step-by-step guide to setting
up repository access, refer to the tutorial :doc:`../tutorials/getting-access-to-repository`.
*****
:stepnumberonedigit:`2` :stepheading:`Install the StorageFabric Components.`
**2a.** Install the :ref:`glossary-configuration-manager`.
.. parsed-literal::
sudo yum install storagefabric-configuration-manager
sudo storagefabric-configuration-manager-post-install
|
**2b.** Install the :ref:`glossary-proxy`.
.. parsed-literal::
sudo yum install storagefabric-gateway
sudo storagefabric-gateway-post-install
Next Step: :ref:`quickstart-setup-configure`.
|
*****
.. _quickstart-setup-configure:
|setup| StorageFabric
---------------------
:stepnumberonedigit:`1` :stepheading:`Change to the storagefabric user.`
.. parsed-literal::
sudo su storagefabric
*****
:stepnumberonedigit:`2` :stepheading:`Save license file.`
In order to use StorageFabric, you must have a valid :ref:`glossary-license`.
Prior to setting up the Configuration Manager, save your license file
in the folder **/etc/storagefabric/licenses/**.
*****
:stepnumberonedigit:`3` :stepheading:`Set Up StorageFabric Components.`
**3a.** |setup| the :ref:`glossary-configuration-manager`.
|setup| the :ref:`glossary-configuration-manager` with your
:ref:`glossary-master-bucket` and access keys.
First, generate a new :ref:`glossary-master-encryption-key` with the following command:
.. parsed-literal::
storagefabric-keygen --master-encryption-key
A new :ref:`glossary-master-encryption-key` will be displayed. For example:
.. parsed-literal::
|value master encryption key|
Then, setup the Configuration Manager for your chosen provider:
.. content-tabs::
.. tab-container:: tab1
:title: Amazon
.. parsed-literal::
storagefabric-configuration-manager-setup \\
--master-encryption-key \\
--configuration-provider-url s3.amazonaws.com \\
--configuration-bucket \\
--configuration-access-key-id \\
--configuration-secret-access-key
In the above command, replace
* ```` with the Master Encryption Key from **Step 2a**.
* ```` with your AWS configuration bucket.
* ```` with your Amazon access key ID.
* ```` with your Amazon secret access key.
.. tab-container:: tab2
:title: Google
.. parsed-literal::
storagefabric-configuration-manager-setup \\
--master-encryption-key \\
--configuration-provider-url storage.googleapis.com \\
--configuration-bucket \\
--configuration-access-key-id \\
--configuration-secret-access-key
In the above command, replace
* ```` with the Master Encryption Key from **Step 2a**.
* ```` with your Google access key ID.
* ```` with your Google secret access key.
.. tab-container:: tab3
:title: Azure
.. parsed-literal::
storagefabric-configuration-manager-setup \\
--master-encryption-key \\
--configuration-provider-url .blob.core.windows.net \\
--configuration-bucket \\
--configuration-access-key-id \\
--configuration-secret-access-key \\
--configuration-provider-api-type azure
In the above command, replace
* ```` with the Master Encryption Key from **Step 2a**.
* ```` with your Azure storage account.
* ```` with your Azure container access key.
.. note::
If you want this setup to persist after your machine is rebooted, the ``--persist`` flag is required.
.. note::
If you make a mistake and want to run the ``storagefabric-configuration-manager-setup`` again,
the ``--reset-local`` flag is required to overwrite existing configuration.
|
**3b.** Get the :ref:`glossary-view-encryption-key`.
Get the :ref:`glossary-view-encryption-key`. We will use it in the next step to setup the
:ref:`glossary-proxy`.
.. parsed-literal::
storagefabric-configuration-manager-setup -V --include-view-keys
The :ref:`glossary-view-encryption-key` for the **default** view will
be displayed similar to the following
.. parsed-literal::
Encrypted View Encryption Key for view default: |value encrypted master encryption key short|
Note down the displayed **Encryption Key** for the **default** view.
We will use it in the next step to setup the |proxy|.
|
**3c.** |setup| the :ref:`glossary-proxy`.
|setup| the :ref:`glossary-proxy` with your
:ref:`glossary-view-encryption-key`, :ref:`glossary-master-bucket`, and access keys.
.. content-tabs::
.. tab-container:: tab1
:title: Amazon
.. parsed-literal::
storagefabric-gateway-setup \\
--gateway-domain |value top level domain| \\
--view default \\
--encrypted-view-encryption-key |value encrypted master encryption key short| \\
--configuration-provider-url s3.amazonaws.com \\
--configuration-bucket \\
--configuration-access-key-id \\
--configuration-secret-access-key
In the above command, replace
* with the Master Encryption Key from **Step 2a**.
* with your configuration bucket name.
* with your Amazon access key ID.
* with your Amazon secret access key.
.. tab-container:: tab2
:title: Google
.. parsed-literal::
storagefabric-gateway-setup \\
--gateway-domain |value top level domain| \\
--view default \\
--encrypted-view-encryption-key |value encrypted master encryption key short| \\
--configuration-provider-url storage.googleapis.com \\
--configuration-bucket \\
--configuration-access-key-id \\
--configuration-secret-access-key
In the above command, replace
* with the Master Encryption Key from **Step 2a**.
* with your configuration bucket name.
* with your Google access key ID.
* with your Google secret access key.
.. tab-container:: tab3
:title: Azure
.. parsed-literal::
storagefabric-gateway-setup \\
--gateway-domain |value top level domain| \\
--view default \\
--encrypted-view-encryption-key |value encrypted master encryption key short| \\
--configuration-provider-url .blob.core.windows.net \\
--configuration-bucket |value azure master bucket| \\
--configuration-access-key-id \\
--configuration-secret-access-key \\
--configuration-provider-api-type azure
In the above command, replace
* with the Master Encryption Key from **Step 2a**.
* with your Azure storage account.
* with your Azure container access key.
.. note::
If you want this setup to persist after your machine is rebooted, the **--persist** flag is required.
.. note::
If you make a mistake and want to run the **storagefabric-gateway-setup** again, the **--reset-local** flag is required to overwrite existing configuration.
.. note::
If S3 cloud services are accessible via a HTTP Proxy, use parameters (options)
**--http-proxy-host** and **--http-proxy-port** to specify the proxy details.
After setting up the :ref:`glossary-proxy`, exit from the storagefabric user
.. parsed-literal::
exit
Next Step: `Configure StorageFabric`_
*****
Configure StorageFabric
-----------------------
StorageFabric can be configured via the Command Line Interface (CLI),
the StorageFabric Web Interface, or the StorageFabric Configuration
Manager REST API.
In this tutorial, we will use either the CLI or web interface. For using the REST API,
refer to :doc:`../tutorials/using-the-configuration-rest-api`.
Click on a link below to configure StorageFabric based on your preferred method.
* `Configure StorageFabric using the StorageFabric CLI`_
* `Configure StorageFabric using the Configuration Manager Web interface`_
Configure StorageFabric using the StorageFabric CLI
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Add your :ref:`glossary-data-bucket`, create :ref:`glossary-client-access-keys`,
grant client access to the |data bucket|, and sync configuration changes between
the StorageFabric Configuration Manager and |proxy|.
.. note:: Perform the following commands as the **storagefabric** user (``sudo su storagefabric``).
**1.** Add access keys for your :ref:`glossary-data-bucket` to StorageFabric configuration.
Access keys for |data buckets| are also referred to as :ref:`glossary-cloud-access-keys`.
Provider Access Keys are used by the :ref:`glossary-proxy` to access the |data bucket|.
.. content-tabs::
.. tab-container:: tab1
:title: Amazon
.. parsed-literal::
storagefabric-configure add-cloud-access-key \\
--access-key-id \\
--secret-access-key
In the above command, replace
* with your Amazon access key ID.
* with your Amazon secret access key.
.. tab-container:: tab2
:title: Google
.. parsed-literal::
storagefabric-configure add-cloud-access-key \\
--access-key-id \\
--secret-access-key
In the above command, replace
* with your Google access key ID.
* with your Google secret access key.
.. tab-container:: tab3
:title: Azure
.. parsed-literal::
storagefabric-configure add-cloud-access-key \\
--access-key-id \\
--secret-access-key
In the above command, replace
* with your Azure storage account.
* with your Azure container access key.
|
**2.** Add your :ref:`glossary-data-bucket`.
.. content-tabs::
.. tab-container:: tab1
:title: Amazon
.. parsed-literal::
storagefabric-configure add-bucket \\
--provider amazon \\
--views default \\
--cloud-access-key-id \\
--bucket virtual-data-bucket \\
--cloud-name
In the above command, replace
* with your Amazon access key ID.
* with an existing AWS data bucket name.
.. tab-container:: tab2
:title: Google
.. parsed-literal::
storagefabric-configure add-bucket \\
--provider google \\
--views default \\
--cloud-access-key-id \\
--bucket virtual-data-bucket \\
--cloud-name
In the above command, replace
* with your Google access key ID.
* with an existing Google data bucket name.
.. tab-container:: tab3
:title: Azure
.. parsed-literal::
storagefabric-configure add-provider \\
--provider \\
--base-url .blob.core.windows.net \\
--api-type AZURE \\
--country US \\
--multipart-mode disabled \\
--tail-range-disable
.. parsed-literal::
storagefabric-configure add-bucket \\
--provider \\
--views default \\
--cloud-access-key-id \\
--bucket virtual-data-bucket \\
--cloud-name azure-data-bucket
In the above commands, replace
* with your Azure storage account.
* with your Azure container access key.
.. note::
In the above commands, :literal:`--bucket` specifies a :ref:`glossary-virtual-bucket-name`,
whereas :literal:`--cloud-name` is the actual bucket name with the backend provider.
:literal:`cloud-name` must refer to an existing backend bucket, this command does not create
a new backend bucket.
.. note::
In this case, data encryption keys are automatically generated.
KMS integrations are also possible.
|
**3.** Create access keys for :ref:`glossary-client`.
Access keys used by clients to authenticate to the :ref:`glossary-proxy`
are referred to as :ref:`glossary-client-access-keys`.
.. parsed-literal::
storagefabric-configure create-client-access-key
New client access keys are generated and displayed as follows.
.. parsed-literal::
{
"Code": "SUCCESS",
"ClientAccessKeyID": "|value client access key id|",
"ClientSecretAccessKey": "|value client secret access key|",
"SuccessMessage": "Client Access Key created"
}
Save the client access key ID and secret access key generated for you,
similar to the ones shown above.
We will use them later to upload files securely via the :ref:`glossary-proxy`.
|
**4.** Setup access control for :ref:`glossary-client-access-keys`.
Grant the |client access key| generated in step **3** read-write access
to the :ref:`glossary-data-bucket`.
.. parsed-literal::
storagefabric-configure add-role-to-client-access-key \\
--access-key-id \\
--role-name admin \\
--context '{ "providers" : "^.*$", "buckets" : "^.*$", "paths" : "^.*$" }'
In the above command, replace with the client access key ID
generated in **Step 3** above.
.. note::
In the above command, we assigned the built-in role **admin** to the
client access key. For more information on creating and managing
role-based access control, refer to :doc:`../access-control`.
|
**5.** Sync configuration changes between the StorageFabric Configuration Manager and |proxy|.
.. parsed-literal::
storagefabric-sync --gateway
.. note::
Manual syncing is only for the purpose of this quickstart guide.
In StorageFabric deployments, auto-syncing happens periodically
in the background.
*****
**6.** Revert to prior system user.
.. parsed-literal::
exit
Next Step: `Upload files securely using StorageFabric`_
|
|
|
*****
Configure StorageFabric using the Configuration Manager Web interface
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Install and setup the Web Interface as described in the tutorial
:doc:`../tutorials/setting-up-configuration-manager-web-interface`.
Once logged in to the Web Interface, continue to configure StorageFabric
as follows.
**1.** Add access keys for your :ref:`glossary-data-bucket` to StorageFabric configuration.
Access keys for |data buckets| are also referred to as :ref:`glossary-cloud-access-keys`.
Provider Access Keys are used by the :ref:`glossary-proxy` to access the |data bucket|.
.. include:: ../common/add-cloud-keys-web-ui.rst
|
**2.** Add your :ref:`glossary-data-bucket`.
Link your |data bucket| with the Provider Access Key ID from **Step 1**.
.. include:: ../common/add-virtual-bucket-web-ui.rst
In this case, data encryption keys are automatically generated.
KMS integrations are also possible.
|
**3.** Create access keys for :ref:`glossary-client`.
Access keys used by clients to authenticate to the :ref:`glossary-proxy`
are referred to as :ref:`glossary-client-access-keys`.
.. include:: ../common/create-client-keys-web-ui.rst
New client access keys are generated and displayed at the top of the form.
Save the client access key ID and secret access key generate for you,
similar to the ones shown above. We will use them later
to upload files securely via the :ref:`glossary-proxy`.
|
**4.** Sync configuration changes between the StorageFabric Configuration Manager and |proxy|.
.. parsed-literal::
sudo su - storagefabric -c "storagefabric-sync --gateway"
.. note::
Manual syncing is only for the purpose of this quickstart guide.
In StorageFabric deployments, auto-syncing happens periodically
in the background.
Next Step: `Upload files securely using StorageFabric`_
|
|
|
*****
Upload files securely using StorageFabric
-----------------------------------------
In this guide, we will use `s3cmd `_ as the client-side
tool. Many other existing client-side tools can be used with StorageFabric.
For more details, refer to the tutorial :doc:`../tutorials/using-client-tools-and-sdks`.
First, create a sample file using the command:
.. parsed-literal::
touch mydata.txt
Then, upload the sample file to your **virtual-data-bucket** using the following
command with the |client access keys| generated in step **3** earlier.
.. parsed-literal::
s3cmd put mydata.txt s3://virtual-data-bucket/ \\
--host localhost:|value proxy port| \\
--host-bucket localhost:|value proxy port| \\
--access_key \\
--secret_key \\
--signature-v2 --no-ssl
For remote clients, first add your |top level domain| to clients' **/etc/hosts** file
or set up DNS for your :ref:`glossary-top-level-domain`.
.. parsed-literal::
54.164.102.219 |value top level domain|
Then, use your :ref:`glossary-top-level-domain` to access cloud storage services via the StorageFabric |proxy|.
.. parsed-literal::
s3cmd put mydata.txt s3://virtual-data-bucket/ \\
--host |value top level domain|:|value proxy port| \\
--host-bucket |value top level domain|:|value proxy port| \\
--access_key \\
--secret_key \\
--signature-v2 --no-ssl
.. note::
To use SSL connections between clients and the StorageFabric |proxy|, refer
to the tutorial :doc:`../tutorials/setting-up-clients-ssl-connections`.
|
.. seealso::
:doc:`Detailed Installation <../installation>`, :doc:`../configuration`