Skip to main content

Get started with the IonFS CLI, NKV and AWS S3

Josh Fraser

Josh Fraser

Engineer @ Ionburst Cloud

Overview#

The IonFS Command Line Interface provides a set of tools to manage data stored by Ionburst Cloud as if it were a remote filesystem. With the release of NKV, IonFS can now store secrets, while storing the metadata in a customer-owned metadata repository.

Anyone that has been granted access to this repository, and the appropriate Ionburst Cloud credentials, can interact with the stored secrets.

For this tutorial, we will be using Amazon S3 as the ionfs metadata repository.

Shared Responsibility Model Breakdown#

Customer Responsibility#

  • You, the customer, are responsible for the secure management of the Ionburst Cloud credentials used by ionfs.
  • You, the customer, are responsible for the security of ionfs metadata repositories and the metadata stored in them.

Ionburst Cloud Responsibility#

  • We are responsible for the security of all secrets stored in Ionburst Cloud NKV using ionfs.
  • We are responsible for the underlying security and availability of the Ionburst Cloud platform.

Getting Started#

In this tutorial we will cover:

  1. Working with ionfs metadata repositories.
  2. Listing IBC classifications with ionfs.
  3. Working with ionfs directories.
  4. Managing secrets with ionfs.

Basic Usage#

ionfs allows us to do the following:

  • List configured metadata repositories.
  • List available IBC classifications.
  • Create, list and delete ionfs directories.
  • Upload, download and delete secrets from IBC.

1. Metadata Repositories#

ionfs makes use of metadata repositories, or repos, to track secrets that have been secured by Ionburst Cloud NKV. Metadata repos are specified in the configuration file stored under ~/.ionfs/appsettings.json.

To list the configured repos, the following ionfs command can be used:

ionfs repos

An example output would look like:

[hello@ionfs-example ~]$ ionfs repos
____ ___________
/ _/___ ____ / ____/ ___/
/ // __ \/ __ \/ /_ \__ \
_/ // /_/ / / / / __/ ___/ /
/___/\____/_/ /_/_/ /____/
Available Repositories (*default):
* [s] ion://s3-example-ionfs-nkv/ (Ionburst.Apps.IonFS.Repo.S3.MetadataS3)

2. Classifications#

Secrets can be secured by Ionburst Cloud according to available security policies. ionfs can be used to view the policies currently available to an Ionburst Cloud party.

To list available policies, the following can be used:

ionfs policy

An example output would look like:

[hello@ionfs-example ~]$ ionfs policy
____ ___________
/ _/___ ____ / ____/ ___/
/ // __ \/ __ \/ /_ \__ \
_/ // /_/ / / / / __/ ___/ /
/___/\____/_/ /_/_/ /____/
Available Classifications:
2:Restricted

3. Directories#

Secrets secured by Ionburst Cloud NKV through ionfs can partition its repo using a typical directory structure.

List directories#

To list available directories within a repo, the following can be used:

ionfs list

An example output would look like:

[hello@ionfs-example ~]$ ionfs list
____ ___________
/ _/___ ____ / ____/ ___/
/ // __ \/ __ \/ /_ \__ \
_/ // /_/ / / / / __/ ___/ /
/___/\____/_/ /_/_/ /____/
Secrets Repo of ion://s3-example-ionfs-nkv/
d example/

By default, this will list the contents of the repo's root directory. To list a specific directory, the following can be used:

ionfs list ion://example

An example output would look like:

[hello@ionfs-example ~]$ ionfs list ion://example
____ ___________
/ _/___ ____ / ____/ ___/
/ // __ \/ __ \/ /_ \__ \
_/ // /_/ / / / / __/ ___/ /
/___/\____/_/ /_/_/ /____/
Secrets Repo of ion://s3-example-ionfs-nkv/example/
Remote Secrets repository is empty is empty

Create a directory#

To create a new directory within a repo, the following can be used:

ionfs mkdir ion://new-directory

An example output would look like:

[hello@ionfs-example ~]$ ionfs mkdir ion://new-directory
[hello@ionfs-example ~]$ ionfs list
____ ___________
/ _/___ ____ / ____/ ___/
/ // __ \/ __ \/ /_ \__ \
_/ // /_/ / / / / __/ ___/ /
/___/\____/_/ /_/_/ /____/
Secrets Repo of ion://s3-example-ionfs-nkv/
d example/
d new-directory/

Delete a directory#

To remove a directory within a repo, the following can be used:

ionfs rmdir ion://new-directory

An example output would look like:

[hello@ionfs-example ~]$ ionfs rmdir ion://new-directory
[hello@ionfs-example ~]$ ionfs list
____ ___________
/ _/___ ____ / ____/ ___/
/ // __ \/ __ \/ /_ \__ \
_/ // /_/ / / / / __/ ___/ /
/___/\____/_/ /_/_/ /____/
Secrets Repo of ion://s3-example-ionfs-nkv/
d example/

4. Secrets#

Finally, and most importantly we can now look at uploading (Put), downloading (Get) and deleting Secrets from IBC NKV using ionfs. In these examples, we'll use a secret called my-secret, with the value "We may guard your data, but we'll never take its freedom".

Put#

To upload a secret with ionfs, the following can be used:

ionfs secrets put "We may guard your data, but we'll never take its freedom" ion:// my-secret

An example output would look like:

[hello@ionfs-example ~]$ ionfs secrets put "We may guard your data, but we'll never take its freedom" ion:// my-secret
[hello@ionfs-example ~]$ ionfs list
____ ___________
/ _/___ ____ / ____/ ___/
/ // __ \/ __ \/ /_ \__ \
_/ // /_/ / / / / __/ ___/ /
/___/\____/_/ /_/_/ /____/
Secrets Repo of ion://s3-example-ionfs-nkv/
d example/
my-secret 22/07/2021 13:10:14

To upload a secret to a specific directory within your repo, use the following:

ionfs secrets put "We may guard your data, but we'll never take its freedom" ion://example my-secret

An example output would look like:

[hello@ionfs-example ~]$ ionfs secrets put "We may guard your data, but we'll never take its freedom" ion:// my-secret
[hello@ionfs-example ~]$ ionfs list ion://example
____ ___________
/ _/___ ____ / ____/ ___/
/ // __ \/ __ \/ /_ \__ \
_/ // /_/ / / / / __/ ___/ /
/___/\____/_/ /_/_/ /____/
Secrets Repo of ion://s3-example-ionfs-nkv/example/
example/my-secret 22/07/2021 13:11:52

Get#

To retrieve a secret with ionfs, use the following:

ionfs secrets get ion://example/my-secret

An example output would look like:

[hello@ionfs-example ~]$ ionfs secrets get ion://example/my-secret
We may guard your data, but we'll never take its freedom

Delete#

To delete a secret from the ionfs repo and from Ionburst Cloud NKV, the following can be used:

ionfs secrets del ion://example/my-secret

An example output would look like:

[hello@ionfs-example ~]$ ionfs secrets del ion://example/my-secret
[hello@ionfs-example ~]$ ionfs list ion://example
____ ___________
/ _/___ ____ / ____/ ___/
/ // __ \/ __ \/ /_ \__ \
_/ // /_/ / / / / __/ ___/ /
/___/\____/_/ /_/_/ /____/
Secrets Repo of ion://s3-example-ionfs-nkv/example/
Remote Secrets repository is empty

Conclusion#

You should now be able to perform basic secrets operations on Ionburst Cloud NKV using the ionfs tool. If you're interested in learning more about the IonFS CLI, please see the Ionburst Cloud docs.