Skip to main content

Get started with ioncli and S6

Josh Fraser

Josh Fraser

Engineer @ Ionburst Cloud

Overview#

ioncli is a simple Command Line Interface tool that allows data to be uploaded, downloaded and deleted from Ionburst Cloud S6. ioncli also allows the listing of available classifications.

The aim of this tutorial is to learn how to setup ioncli, and use it to perform basic operations against the Ionburst Cloud S6 API.

Shared Responsibility Model Breakdown#

Customer Responsibility#

  • You, the customer, are responsible for the secure management of the Ionburst Cloud credentials used by the ioncli tool.
  • ioncli does not provide any client-side encryption functionality. If this is used in conjunction with the usage of ioncli, it is the reponsibility of the customer to manage.
  • ioncli does not provide any metadata tracking or management for data stored. It is the customer's responsibility to track and record this information.

Ionburst Cloud Responsibility#

  • We are responsible for the security of all data stored in Ionburst Cloud S6 using the ioncli tool.
  • We are responsible for the underlying security and availability of the Ionburst Cloud services.

Getting Started#

In this tutorial we will cover:

  1. Setting up the ioncli credentials profile.
  2. Retrieving the available Ionburst Cloud classifications.
  3. Uploading a file to Ionburst Cloud S6.
  4. Downloading a file from Ionburst Cloud S6.
  5. Deleting a file from Ionburst Cloud S6.

1. Credentials#

ioncli requires a profile configured in the Ionburst credentials file, a well-known directory in the user's home folder.

  • On MacOS/Linux, this file is located at ~/.ionburst/credentials, and
  • on Windows, it is located at %USERPROFILE%\.ionburst\credentials.
note

If you have already created an Ionburst credentials file, and added a profile to it, you can jump ahead.

If you are still to set one up, we will now walk through how to create a credentials file.

An example of the final credentials file should look similar to this. In this example, the credentials profile we will create is called ioncli-example, and the profile is configured to use the Ionburst Cloud eu-west-1 region.

[ioncli-example]
ionburst_id=IBGCFRFEUJ2TDEXAMPLE
ionburst_key=bG9va211bWknbWFiYXNlNjRlbmNvZGVkc3RyaW5n
ionburst_uri=https://api.eu-west-1.ionburst.cloud

1.1 - Creating the credentials file#

1.1.1 - Open a new terminal.

1.1.2 - Next, we need to create the .ionburst directory:

mkdir ~/.ionburst

1.1.3 - The credentials file can then be created within this directory:

touch ~/.ionburst/credentials

1.1.4 - You can now verify this with the following:

ls ~/.ionburst/credentials

1.1.5 - On verifying, the output should look similar to this:

[hello@ioncli-example ~]$ ls ~/.ionburst/credentials
/home/hello/.ionburst/credentials

1.2 Add a profile to the credentials file#

1.2.1 - To create a new profile in the Ionburst credentials file, the following can be used:

echo "[ioncli-example]" >> ~/.ionburst/credentials
echo "ionburst_id=IBGCFRFEUJ2TDEXAMPLE" >> ~/.ionburst/credentials
echo "ionburst_key=bG9va211bWknbWFiYXNlNjRlbmNvZGVkc3RyaW5n" >> ~/.ionburst/credentials
echo "ionburst_uri=https://api.eu-west-1.ionburst.cloud" >> ~/.ionburst/credentials

1.2.2 - This will add a profile ioncli-example to the credentials file. Please ensure the >> operator is used to avoid overwriting any existing contents in the credentials file.

The file contents can be verified with the following:

cat ~/.ionburst/credentials

1.2.3 - An example output should look similar to:

[hello@ioncli-example ~]$ echo "[ioncli-example]" >> ~/.ionburst/credentials
[hello@ioncli-example ~]$ echo "ionburst_id=IBGCFRFEUJ2TDEXAMPLE" >> ~/.ionburst/credentials
[hello@ioncli-example ~]$ echo "ionburst_key=bG9va211bWknbWFiYXNlNjRlbmNvZGVkc3RyaW5n" >> ~/.ionburst/credentials
[hello@ioncli-example ~]$ echo "ionburst_uri=https://api.eu-west-1.ionburst.cloud" >> ~/.ionburst/credentials
[hello@ioncli-example ~]$ cat ~/.ionburst/credentials
[ioncli-example]
ionburst_id=IBGCFRFEUJ2TDEXAMPLE
ionburst_key=bG9va211bWknbWFiYXNlNjRlbmNvZGVkc3RyaW5n
ionburst_uri=https://api.eu-west-1.ionburst.cloud

Basic Usage#

Once a credentials profile is configured, ioncli can be used. ioncli provides functionality for the following:

  • Classifications listing.
  • PUT - Uploading data to Ionburst Cloud S6.
  • GET - Downloading data from Ionburst Cloud S6.
  • DELETE - Deleting data from Ionburst Cloud S6.
note

If you already have a profile configured in your Ionburst credentials file, you should use this for the examples below.

2. Classifications#

Data can be secured by Ionburst Cloud S6 according to available security classifications. ioncli can be used to view the policies currently available to an Ionburst Cloud party.

To list available policies, the following can be used:

ioncli --profile ioncli-example classifications list

The output for this command should look like:

[hello@ioncli-example ~]$ ioncli --profile ioncli-example classifications list
Classifications: 1
Classification
-----------------
Restricted

3. Uploading Data#

To upload data to Ionburst Cloud S6 using ioncli, an object ID and file must be supplied. In this example we will upload the file my-file.txt as ID my-ioncli-put.

Creating my-file.txt:

echo "We may guard your data, but we'll never take its freedom" > my-file.txt

Uploading my-file.txt with ioncli:

ioncli --profile ioncli-example put my-ioncli-put my-file.txt

This operation does not return any output on success.

4. Downloading Data#

To retrieve data from Ionburst Cloud S6 using ioncli, an object ID and output path must be provided. In this example, we will download the previously uploaded object, my-ioncli-put, to the path/file my-downloaded-file.txt.

Downloading my-ioncli-put:

ioncli --profile ioncli-example get my-ioncli-put my-downloaded-file.txt

This operation does not return any output on success.

We can now view the downloaded file:

cat my-ioncli-put

The output for this command should look like:

[hello@ioncli-example ~]$ cat my-ioncli-put
We may guard your data, but we'll never take its freedom

5. Deleting Data#

To delete data from Ionburst Cloud S6 using ioncli, an object ID must be provided. In this example, we will download the previously used object, my-ioncli-put.

Deleting my-ioncli-put:

ioncli --profile ioncli-example delete my-ioncli-put

This operation does not return any output on success.

We can verify the object has been deleted by attempting to download my-ioncli-put:

ioncli --profile ioncli-example get my-ioncli-put my-downloaded-file.txt

The output for this command should look like:

[hello@ioncli-example ~]$ ioncli --profile ioncli-example get my-ioncli-put my-downloaded-file.txt
2021/06/27 18:59:22 Error performing Ionburst API Operation: [GET] https://api.eu-west-1.ionburst.cloud/api/data/my-ioncli-put :: 404 ->

Conclusion#

You should now be able to perform basic data operations on Ionburst Cloud S6 using the ioncli tool. If you're interested in learning more about our more fully-featured command-line tool, IonFS, which features object metadata management and filesystem-like interactions, please see the Ionburst Cloud docs.