@ -38,7 +38,7 @@ Where the server name is the name of a data node, the port is the data node HTTP
Please look at the [command line interface]({{< ref "CommandShell.md#shell" >}}) for more info.
Ozone supports both REST and RPC protocols. Clients can choose either of these protocols to communicate with Ozone. Please see the [client documentation]({{< ref "JavaApi.md" >}}) for more details.
Ozone supports both (S3 compatible) REST and RPC protocols. Clients can choose either of these protocols to communicate with Ozone. Please see the [client documentation]({{< ref "JavaApi.md" >}}) for more details.
Ozone separates namespace management and block space management; this helps
ozone to scale much better. The namespace is managed by a daemon called
@ -96,13 +96,13 @@ The data node where data is stored. SCM monitors these nodes via heartbeat.
### Clients
Ozone ships with a set of clients. Ozone [CLI]({{< ref "CommandShell.md#shell" >}}) is the command line interface like 'hdfs' command. [Freon] ({{<ref"Freon.md">}}) is a load generation tool for Ozone.
### REST Handler
Ozone provides an RPC (Remote Procedure Call) as well as a REST (Representational State Transfer) interface. This allows clients to be written in many languages quickly. Ozone strives to maintain an API compatibility between REST and RPC.
For most purposes, a client can make one line change to switch from REST to RPC or vice versa.
## S3 gateway
Ozone provides and [S3 compatible REST gateway server]({{< ref "S3.md">}}). All of the main S3 features are supported and any S3 compatible client library can be used.
### Ozone File System
Ozone file system (TODO: Add documentation) is a Hadoop compatible file system. This allows Hadoop services and applications like Hive and Spark to run against
Ozone without any change.
[Ozone file system]({{< ref "OzoneFS.md">}}) is a Hadoop compatible file system. This allows Hadoop services and applications like Hive and Spark to run against
Ozone without any change. (For example: you can use `hdfs dfs -ls o3fs://...` instead of `hdfs dfs -ls hdfs://...`)
### Ozone Client
This is similar to DFSClient in HDFS. This is the standard client to talk to Ozone. All other components that we have discussed so far rely on Ozone client. Ozone client supports both RPC and REST protocols.
This is similar to DFSClient in HDFS. This is the standard client to talk to Ozone. All other components that we have discussed so far rely on Ozone client. Ozone client supports RPC protocol.
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
The Ozone REST API's allows user to access ozone via REST protocol.
## Authentication and Authorization
For time being, The default authentication mode of REST API is insecure access
mode, which is *Simple* mode. Under this mode, ozone server trusts the user
name specified by client and it does not perform any authentication.
User name can be specified in HTTP header by
* `x-ozone-user: {USER_NAME}`
for example if add following header *x-ozone-user: bilbo* in the HTTP request,
then operation will be executed as *bilbo* user.
In *Simple* mode, there is no real authorization either. Client can be
authorized to obtain administrator privilege by using HTTP header
* `Authorization: {AUTH_METHOD} {SIGNATURE}`
for example set following header *Authorization: OZONE root* in the HTTP request,
then ozone will authorize the client with administrator privilege.
## Common REST Headers
The following HTTP headers must be set for each REST call.
| Property | Description |
|:---- |:----
| Authorization | The authorization field determines which authentication method is used by ozone. Currently only *simple* mode is supported, the corresponding value is *OZONE*. Optionally an user name can be set as *OZONE {USER_NAME}* to authorize as a particular user. |
| Date | Standard HTTP header that represents dates. The format is - day of the week, month, day, year and time (military time format) in GMT. Any other time zone will be rejected by ozone server. Eg. *Date : Mon, Apr 4, 2016 06:22:00 GMT*. This field is required. |
| x-ozone-version | A required HTTP header to indicate which version of API this call will be communicating to. E.g *x-ozone-version: v1*. Currently ozone only publishes v1 version API. |
## Common Reply Headers
The common reply headers are part of all Ozone server replies.
| Property | Description |
|:---- |:----
| Date | This is the HTTP date header and it is set to server’s local time expressed in GMT. |
| x-ozone-request-id | This is a UUID string that represents an unique request ID. This ID is used to track the request through the ozone system and is useful for debugging purposes. |
| x-ozone-server-name | Fully qualified domain name of the sever which handled the request. |
## Volume APIs
### Create a Volume
This API allows admins to create a new storage volume.
this request creates a volume as user *bilbo*, the authorization field is set to *OZONE root* because this call requires administration privilege. The client receives a response with zero content length.
This API allows administrators to update volume info such as ownership and quota. This API requires administration privilege.
Schema:
- `PUT /{volume}?quota=<VOLUME_QUOTA>`
Query Parameter:
| Query Parameter | Value | Description |
|:---- |:---- |:----
| quota | long<BYTES \| MB \| GB \| TB> \| remove | Optional. Quota size in BYTEs, MBs, GBs or TBs. Or use string value *remove* to remove an existing quota for a volume. |
this request gets all volumes owned by *bilbo* and each volume's name contains prefix *Jan*, the result at most contains *100* entries. The client receives a list of SON objects, each of them describes the info of a volume.
this request adds an ACL policy specified by HTTP header *x-ozone-acl* to bucket */volume-of-bilbo/bucket-to-update*, the ACL field *ADD user:peregrin:rw* gives add additional read/write permission to user *peregrin* to this bucket.
Deletes a bucket if it is empty. An user can only delete bucket owned by themselves, and administrators can delete buckets owned by any user, as long as it is empty.
this request lists all the buckets under volume *volume-of-bilbo*, and the result at most contains 10 entries. The client receives response of a array of JSON objects, each of them represents for a bucket info.
this request uploads a local file */path/to/localfile* specified by option *-T* to ozone as user *bilbo*, mapped to ozone key */volume-of-bilbo/bucket-0/file-0*. The client receives a zero length content response.
### Get Key
This API allows user to get or download a key from an ozone bucket.
this request reads the content of key */volume-of-bilbo/bucket-0/file-0*. If the content of the file is plain text, it can be directly dumped onto stdout.
if the file is not plain text, specify *-O* option in curl command and the file *file-0* will be downloaded into current working directory, file name will be same as the key. A sample request like following:
this request list keys under bucket */volume-of-bilbo/bucket-0*, the listing result is filtered by prefix *file*. The client receives an array of JSON objects, each of them represents the info of a matched key.
Ozone is a scalable, distributed object store for Hadoop. Applications like
Apache Spark, Hive and YARN, can run against Ozone without any
modifications. Ozone comes with a [Java client library]({{<ref"JavaApi.md"
>}}) and a [command line interface] ({{<ref"CommandShell.md#shell">}}) which makes it easy to use Ozone. This client library supports both RPC and REST protocols.
>}}), a [S3]({{< ref "S3.md" >}}) and a [command line interface]
({{<ref"CommandShell.md#shell">}}) which makes it easy to use Ozone.
Ozone consists of volumes, buckets, and Keys.
Ozone consists of volumes, buckets, and Keys:
* Volumes are similar to user accounts. Only administrators can create or delete volumes.
* Buckets are similar to directories. A bucket can contain any number of keys, but buckets cannot contain other buckets.
Anu Engineer