Connect to Ozone via CLI

Sergei Tikhomirov

Contents

Overview
Examples

Overview

Ozone has a CLI tool that allows access to some specific functionality that can’t be performed otherwise. These commands are normally performed once during the setup, like volume creation or ACL management.

The general way to invoke an Ozone shell command is as follows:

$ ozone sh <object> <action> [params]

where:

<object> is an Ozone object such as bucket, key, prefix, snapshot, user, token, or volume.
<action> is an action to perform with an object. For example, to create a volume, the action would be create.
[params] are additional parameters that some actions require.

The CLI tool offers a help manual at both the object and action level. That is, to see possible actions for an object, call the following command:

$ ozone sh <object> --help

And to see the necessary parameters for an action, call:

$ ozone sh <object> <action> --help

NOTE

Currently, there’s no online documentation for the Ozone shell objects and actions. It’s recommended to refer to the help manual of the tool itself.

Examples

Volume commands

A functionality that is unique to the CLI tool includes the ability to create a volume with a quota. To do this, run the following command:

$ ozone sh volume create <volume_name> --quota=<quota_in_bytes>

To check if the volume was created successfully with the right quota, list all the volumes as follows:

$ ozone sh volume ls

This command returns a list of volumes with some information about them:

[ {
  "metadata" : { },
  "name" : "vol1",
  "admin" : "sergei",
  "owner" : "sergei",
  "quotaInBytes" : 1073741824,
  "quotaInNamespace" : -1,
  "usedNamespace" : 0,
  "creationTime" : "2025-01-13T13:20:43.173Z",
  "modificationTime" : "2025-01-13T13:20:43.173Z",
  "acls" : [ {
    "type" : "USER",
    "name" : "sergei",
    "aclScope" : "ACCESS",
    "aclList" : [ "ALL" ]
  }, {
    "type" : "GROUP",
    "name" : "sergei",
    "aclScope" : "ACCESS",
    "aclList" : [ "ALL" ]
  } ],
  "refCount" : 0
} ]

Bucket commands

An exclusive ability to create buckets with encryption keys can be utilized with the following command:

$ ozone sh bucket create -k <key_name> <URI>

where:

<key_name> is the name of an encryption key that was created with the hadoop key create command.
<URI> is a bucket name that includes a volume name (e.g. /vol1/bucket1).

You can also control the bucket replication settings:

$ ozone sh bucket set-replication-config -t=<type> -r=<replication> <value>

where:

<type> is a replication type. The supported types are RATIS and EC.
<replication> is a replication definition. The valid values are based on the replication type. For RATIS it may be ONE or THREE, while for EC it should follow the CODEC-DATA-PARITY-CHUNK_SIZE pattern, e.g. rs-3-2-1024k.
<value> is the URI of a bucket.

Consider the following command:

$ ozone sh bucket set-replication-config -t=RATIS -r=ONE vol1/bucket1

It will add the following information to the bucket:

"replicationConfig" : {
  "replicationFactor" : "ONE",
  "requiredNodes" : 1,
  "replicationType" : "RATIS"
}

ACL management

The CLI tool allows you to add and remove ACL for volumes and buckets. Below, you can find a sample command that adds an ACL to a volume:

$ ozone sh volume addacl -s=<URI> -a=<type>:<entity>:<permissions> <value>

where:

<store> is a type of store — OZONE or S3.
<type> is a system entity type like user or group.
<entity> is a user or a group the permissions for which you want to control.
<permissions> is a sequence of letters that defines the entity’s permissions. The following values are available:
- r — read the resource data.
- w — write data to the resource.
- c — create objects at the resource.
- d — delete objects at the resource.
- l — list objects stored at the resource.
- x — read the access control list of the resource.
- y — edit the access control list of the resource.
- a — all of the above.
- n — no permissions.
<value> is the URI of a volume/bucket.

Consider the following volume before an ACL addition:

[ {
  "metadata" : { },
  "name" : "vol1",
  "admin" : "s_tikhomirov_krb1",
  "owner" : "s_tikhomirov_krb1",
  "quotaInBytes" : -1,
  "quotaInNamespace" : -1,
  "usedNamespace" : 0,
  "creationTime" : "2025-01-22T21:23:28.796Z",
  "modificationTime" : "2025-01-22T21:23:28.796Z",
  "acls" : [ {
    "type" : "USER",
    "name" : "s_tikhomirov_krb1",
    "aclScope" : "ACCESS",
    "aclList" : [ "ALL" ]
  } ],
  "refCount" : 0
} ]

Here, an ACL is present only for the user who has created it. Running the addacl command with the -a=user:sergei:rwcdlxy option adds the corresponding ACL:

[ {
  "metadata" : { },
  "name" : "vol1",
  "admin" : "s_tikhomirov_krb1",
  "owner" : "s_tikhomirov_krb1",
  "quotaInBytes" : -1,
  "quotaInNamespace" : -1,
  "usedNamespace" : 0,
  "creationTime" : "2025-01-22T21:23:28.796Z",
  "modificationTime" : "2025-01-22T21:53:56.260Z",
  "acls" : [ {
    "type" : "USER",
    "name" : "s_tikhomirov_krb1",
    "aclScope" : "ACCESS",
    "aclList" : [ "ALL" ]
  }, {
    "type" : "USER",
    "name" : "sergei",
    "aclScope" : "ACCESS",
    "aclList" : [ "READ", "WRITE", "CREATE", "LIST", "DELETE", "READ_ACL", "WRITE_ACL" ]
  } ],
  "refCount" : 0
} ]

You can remove an ACL by calling the removeacl command:

$ ozone sh volume removeacl -s=OZONE -a=user:sergei:rwcdlxy vol1

Found a mistake? Seleсt text and press Ctrl+Enter to report it