Skip to content

Commit

Permalink
Update OCM sharing tutorial (#1587)
Browse files Browse the repository at this point in the history
  • Loading branch information
@ishank011
ishank011 authored Mar 26, 2021
1 parent 69c54fb commit fb410ea
Show file tree
Hide file tree
Showing 2 changed files with 78 additions and 93 deletions.
2 changes: 1 addition & 1 deletion cmd/reva/ocm-invite-forward.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ func ocmInviteForwardCommand() *command {
if forwardToken.Status.Code != rpc.Code_CODE_OK {
return formatError(forwardToken.Status)
}
fmt.Println(forwardToken.Status.Code)
fmt.Println("OK")
return nil
}
return cmd
Expand Down
169 changes: 77 additions & 92 deletions docs/content/en/docs/tutorials/share-tutorial.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,10 @@ title: "OCM share functionality in Reva"
linkTitle: "OCM share functionality"
weight: 5
description: >
OCM (Open Cloud Mesh) share functionality in Reva locally.
OCM (Open Cloud Mesh) share functionality in Reva.
---

This is a guide on how to try the share functionality in Reva in your local environment.
This is a guide on how to try the OCM share functionality in Reva in your local environment.

## Prerequisites
* golang
Expand All @@ -22,142 +22,127 @@ git clone https://github.com/cs3org/reva
```

## 2. Build Reva
Follow the instructions in https://reva.link/docs/getting-started/install-reva/ for how to build reva. If you will do local
changes in reva, follow the "Build from sources" instructions.
Follow the instructions in https://reva.link/docs/getting-started/install-reva/ for how to build reva. If you're making any local changes in reva, follow the "Build from sources" instructions.

## 4. Run Reva
Now we need to start two Reva daemons corresponding to two different mesh providers, thus enabling sharing of files between users belonging to these two providers. For our example, we consider the example of CERNBox deployed at localhost:19001 and the CESNET owncloud at localhost:17001. Follow these steps:

```
cd examples/ocmd/ && mkdir -p /tmp/reva
```
## 3. Run Reva
Now we need to start two Reva daemons corresponding to two different mesh providers, thus enabling sharing of files between users belonging to these two providers. For our example, we consider the example of CERNBox deployed at localhost:19000 and the CESNET owncloud at localhost:17000. Follow these steps:

```
cd examples/ocmd/ && mkdir -p /var/tmp/reva
../../cmd/revad/revad -c ocmd-server-1.toml & ../../cmd/revad/revad -c ocmd-server-2.toml &
```

This should start two Reva daemon (revad) services at the aforementioned endpoints.

## 5. Invitation Workflow
## 4. Invitation Workflow
Before we start sharing files, we need to invite users belonging to different mesh providers so that file sharing can be initiated.
### 5.1 Generate invite token
Generate an invite token for user einstein on CERNBox:
```
curl --location --request GET 'localhost:19001/ocm/invites/' \
--user einstein:relativity
```
You would get a response similar to
```
{"token":"2b51e7a3-7b19-482d-bbf6-b09e2375c0c2","user_id":{"idp":"http://cernbox.cern.ch","opaque_id":"4c510ada-c86b-4815-8820-42cdf82c3d51"},"expiration":{"seconds":1588069874}}
```
Each token is valid for 24 hours from the time of creation.
### 5.2 Accept the token
Now a user on a different mesh provider needs to accept this token in order to initiate file sharing. So we need to call the corresponding endpoint as user marie on CESNET.
```
curl --location --request POST \
'localhost:17001/ocm/invites/forward?token=2b51e7a3-7b19-482d-bbf6-b09e2375c0c2&providerDomain=http://cernbox.cern.ch' \
--user marie:radioactivity
```
An HTTP OK response indicates that the user marie has accepted an invite from einstein to receive shared files.
### 4.1 Generate invite token
Log in to reva as einstein at CERNBox

## 6. Sharing functionality
Creating shares at the origin is specific to each vendor and would have different implementations across providers. Thus, to skip the OCS HTTP implementation provided with reva, we would directly make calls to the exposed GRPC Gateway services through the reva CLI.
### 6.1 Create a share on the original user's provider
#### 6.1.1 Create an example file
```
echo "Example file" > example.txt
./cmd/reva/reva -insecure -host localhost:19000
>> login basic
login: einstein
password: relativity
OK
```

#### 6.1.2 Log in to reva
And generate an invite token:
```
./cmd/reva/reva login basic
>> ocm-invite-generate
status:<code:CODE_OK trace:"64a00a149f07ad5d7134b0eeb7c830f6" > invite_token:<token:"f9a25050-a0cf-4717-badb-b3574e3c0963" user_id:<idp:"cernbox.cern.ch" opaque_id:"4c510ada-c86b-4815-8820-42cdf82c3d51" > expiration:<seconds:1616847728 > >
```

If you now get an error saying that you need to run reva configure, do as follows:
Each token is valid for 24 hours from the time of creation.

### 4.2 Accept the token
Now a user on a different mesh provider needs to accept this token in order to initiate file sharing. So we need to call the corresponding endpoint as user marie at CESNET.

```
./cmd/reva/reva configure
./cmd/reva/reva -insecure -host localhost:17000
>> login basic
login: marie
password: radioactivity
OK
```

and use

And accept the invite token generated by einstein:
```
host: localhost:19000
>> ocm-invite-forward -idp cernbox.cern.ch -token f9a25050-a0cf-4717-badb-b3574e3c0963
OK
```

Once configured, run:

## 5. Sharing functionality
Creating shares at the origin is specific to each vendor and would have different implementations across providers. Thus, to skip the OCS HTTP implementation provided with reva, we would directly make calls to the exposed GRPC Gateway services through the reva CLI.
### 5.1 Create a share on the original user's provider
#### 5.1.1 Create an example file
```
./cmd/reva/reva login basic
echo "Example file" > example.txt
```

And use the following log in credentials:
#### 5.1.2 Log in to reva as einstein

```
./cmd/reva/reva -insecure -host localhost:19000
>> login basic
login: einstein
password: relativity
```
#### 6.1.3 Upload the example.txt file
Create container folder:

```
./cmd/reva/reva mkdir /home/
OK
```

Upload the example file:

```
./cmd/reva/reva upload example.txt /home/example.txt
```
#### 6.1.4 Create the share
Call the ocm-share-create method with the required options. For now, we use the unique ID assigned to each user to identify the recipient of the share, but it can be easily modified to accept the email ID as well (`f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c` is the unique ID for the user marie; the list of all users can be found at `examples/ocmd/users.demo.json`).
```
./cmd/reva/reva ocm-share-create -grantee f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c -idp http://cesnet.cz /home/example.txt
```
This would create a local share on einstein's mesh provider and call the unprotected endpoint `/ocm/shares` on the recipient's provider to create a remote share. The response would look like:
```
+--------------------------------------+------------------------+--------------------------------------+----------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+-------------------+------------------+--------------------------------------+--------------------------------+--------------------------------+
| # | OWNER.IDP | OWNER.OPAQUEID | RESOURCEID | PERMISSIONS | TYPE | GRANTEE.IDP | GRANTEE.OPAQUEID | CREATED | UPDATED |
+--------------------------------------+------------------------+--------------------------------------+----------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+-------------------+------------------+--------------------------------------+--------------------------------+--------------------------------+
| c530f6b3-8eb7-4b68-af68-272ab8845bf8 | http://cernbox.cern.ch | 4c510ada-c86b-4815-8820-42cdf82c3d51 | storage_id:"123e4567-e89b-12d3-a456-426655440000" opaque_id:"fileid-home/example.txt" | permissions:<get_path:true initiate_file_download:true list_container:true list_file_versions:true stat:true > | GRANTEE_TYPE_USER | http://cesnet.cz | f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c | 2020-04-27 15:23:18 +0200 CEST | 2020-04-27 15:23:18 +0200 CEST |
+--------------------------------------+------------------------+--------------------------------------+----------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+-------------------+------------------+--------------------------------------+--------------------------------+--------------------------------+
```
### 6.2 Accessing the share on the recipient's side
The recipient can access the list of shares shared with them. Similar to the create shares functionality, this implementation is specific to each vendor, so for the demo, we can access it through the reva CLI.
#### 5.1.3 Upload the example.txt file
Create a folder and upload the file:

#### 6.2.1 Log in to reva
Reva CLI stores the configuration and authentication tokens in `.reva.config` and `.reva-token` files in the user's home directory. For now, this is not configurable so we need to set these again to access the platform as the user marie.
```
./cmd/reva/reva configure
>> mkdir /home/my-folder
>> upload example.txt /home/my-folder/example.txt
Local file size: 15 bytes
Data server: http://localhost:19001/data/tus/d9360db0-3484-441a-8b7f-c9c0b8e63918
Allowed checksums: [type:RESOURCE_CHECKSUM_TYPE_MD5 priority:100 type:RESOURCE_CHECKSUM_TYPE_UNSET priority:1000 ]
Checksum selected: RESOURCE_CHECKSUM_TYPE_MD5
Local XS: RESOURCE_CHECKSUM_TYPE_MD5:085f396b2bdea443f3d5b889f84d49f5
File uploaded: 123e4567-e89b-12d3-a456-426655440000:fileid-einstein%2Fmy-folder%2Fexample.txt 15 /home/my-folder/example.txt
```

and use

```
host: localhost:17000
#### 5.1.4 Create the share
Call the ocm-share-create method with the required options. The user can list which all users have accepted the invite token and create shares using the retrieved info.
```
>> ocm-find-accepted-users
+--------------------------------------+-----------+-----------------+-------------+
| OPAQUEID | IDP | MAIL | DISPLAYNAME |
+--------------------------------------+-----------+-----------------+-------------+
| f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c | cesnet.cz | [email protected] | Marie Curie |
+--------------------------------------+-----------+-----------------+-------------+
Once configured run:
>> ocm-share-create -grantee f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c -idp cesnet.cz /home/my-folder
+--------------------------------------+-----------------+--------------------------------------+--------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+-------------------+-------------+--------------------------------------+-------------------------------+-------------------------------+
| # | OWNER.IDP | OWNER.OPAQUEID | RESOURCEID | PERMISSIONS | TYPE | GRANTEE.IDP | GRANTEE.OPAQUEID | CREATED | UPDATED |
+--------------------------------------+-----------------+--------------------------------------+--------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+-------------------+-------------+--------------------------------------+-------------------------------+-------------------------------+
| 23498b71-363e-4804-9f22-8c35dc070a06 | cernbox.cern.ch | 4c510ada-c86b-4815-8820-42cdf82c3d51 | storage_id:"123e4567-e89b-12d3-a456-426655440000" opaque_id:"fileid-einstein%2Fmy-folder" | permissions:<get_path:true initiate_file_download:true list_container:true list_file_versions:true stat:true > | GRANTEE_TYPE_USER | cesnet.cz | f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c | 2021-03-26 13:30:12 +0100 CET | 2021-03-26 13:30:12 +0100 CET |
+--------------------------------------+-----------------+--------------------------------------+--------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+-------------------+-------------+--------------------------------------+-------------------------------+-------------------------------+
```
./cmd/reva/reva login basic
```
This would create a local share on einstein's mesh provider and call the unprotected endpoint `/ocm/shares` on the recipient's provider to create a remote share.

And use the following log in credentials:
### 5.2 Accessing the share on the recipient's side
The recipient can access the list of shares shared with them. Similar to the create shares functionality, this implementation is specific to each vendor, so for the demo, we can access it through the reva CLI.

#### 5.2.1 Log in to reva as marie
```
./cmd/reva/reva -insecure -host localhost:17000
>> login basic
login: marie
password: radioactivity
OK
```
#### 6.2.2 Access the list of received shares

#### 5.2.2 Access the list of received shares
Call the ocm-share-list-received method.
```
./cmd/reva/reva ocm-share-list-received
```
```
+--------------------------------------+------------------------+--------------------------------------+----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+------------------+--------------------------------------+--------------------------------+--------------------------------+---------------------+
| # | OWNER.IDP | OWNER.OPAQUEID | RESOURCEID | PERMISSIONS | TYPE | GRANTEE.IDP | GRANTEE.OPAQUEID | CREATED | UPDATED | STATE |
+--------------------------------------+------------------------+--------------------------------------+----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+------------------+--------------------------------------+--------------------------------+--------------------------------+---------------------+
| e327bf7d-cda7-4cdc-bb82-fbeef017dd16 | http://cernbox.cern.ch | 4c510ada-c86b-4815-8820-42cdf82c3d51 | storage_id:"123e4567-e89b-12d3-a456-426655440000" opaque_id:"fileid-home/example.txt" | permissions:<get_path:true get_quota:true initiate_file_download:true list_grants:true list_container:true list_file_versions:true list_recycle:true stat:true > | GRANTEE_TYPE_USER | http://cesnet.cz | f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c | 2020-04-27 15:23:18 +0200 CEST | 2020-04-27 15:23:18 +0200 CEST | SHARE_STATE_PENDING |
+--------------------------------------+------------------------+--------------------------------------+----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+------------------+--------------------------------------+--------------------------------+--------------------------------+---------------------+
>> ocm-share-list-received
+--------------------------------------+-----------------+--------------------------------------+--------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+-------------+--------------------------------------+-------------------------------+-------------------------------+---------------------+
| # | OWNER.IDP | OWNER.OPAQUEID | RESOURCEID | PERMISSIONS | TYPE | GRANTEE.IDP | GRANTEE.OPAQUEID | CREATED | UPDATED | STATE |
+--------------------------------------+-----------------+--------------------------------------+--------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+-------------+--------------------------------------+-------------------------------+-------------------------------+---------------------+
| 48bf1892-da3f-4e18-b9af-766595683689 | cernbox.cern.ch | 4c510ada-c86b-4815-8820-42cdf82c3d51 | storage_id:"123e4567-e89b-12d3-a456-426655440000" opaque_id:"fileid-einstein%2Fmy-folder" | permissions:<get_path:true get_quota:true initiate_file_download:true list_grants:true list_container:true list_file_versions:true list_recycle:true stat:true > | GRANTEE_TYPE_USER | cesnet.cz | f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c | 2021-03-26 13:30:12 +0100 CET | 2021-03-26 13:30:12 +0100 CET | SHARE_STATE_PENDING |
+--------------------------------------+-----------------+--------------------------------------+--------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+-------------+--------------------------------------+-------------------------------+-------------------------------+---------------------+
```

0 comments on commit fb410ea

Please sign in to comment.