Advanced Zbox Commands

0Chain
Search…
Explorer
ZWallet CLI
Zbox CLI
Get Started
Zbox Commands
Uploading and Managing Files
Advanced Zbox Commands
Tips & Troubleshooting
Setup a 0Chain Testnet
Blobber
0miner
0Chain Diagnostics Glossary
Advanced Zbox Commands
Sync
./zbox sync command is used to sync all files in the local folder. Creation, deletion and updation will be done automatically. Parameter details can be viewed using the ./zbox sync --help command.
Here are the Parameters:
Parameter
Required
Description
default
Valid values
allocation
yes
allocation id
​
string
commit
no
commet metadata to blockchain
false
boolean
encryptpath
no
local directory path to be uploaded as encrypted
false
boolean
excludepath
no
paths to exclude from sync
​
string array
localcache
no
local cache of remote snapshot. Used for comparsion with remote. After sync will be updated.
​
string
localpath
yes
local directory to which to sync
​
file path
uploadonly
no
only upload and update files
false
boolean
Example:
Let's sync files stored in the local directory .The local directory for sync in the command below is mapped to local variable. Variable cache is marked to local cache text file located inside the local directory..
Command:
1
./zbox sync --localpath $local --localcache $cache --allocation $ALLOC
Copied!
Response:
Verify whether all the files located in the local directory are synced to dStorage using
1
./zbox list --remotepath / --allocation $ALLOC 
Copied!
Batch upload files to dStorage
./zbox sync command with --uploadonly flag can be used to upload all the files in local folder to dStorage. Parameter details can be viewed using the ./zbox sync --help
Here are the Parameters:
Parameter
Required
Description
default
Valid values
allocation
yes
allocation id
​
string
commit
no
commet metadata to blockchain
false
boolean
encryptpath
no
local directory path to be uploaded as encrypted
false
boolean
excludepath
no
paths to exclude from sync
​
string array
localcache
no
local cache of remote snapshot. Used for comparsion with remote. After sync will be updated.
​
string
localpath
yes
local directory to which to sync
​
file path
uploadonly
no
only upload and update files
false
boolean
Example:
We will create three txt files and move them into a directory to specify it as a local path for the ./zbox sync command.
Here is the list of contents of the directory:
1
file1.txt  file2.txt  file3.txt​
Copied!
Now by using the ./zbox sync command with --uploadonlyflag we will batch upload these files to the dStorage .Variable local is marked to local directory containing all the files for upload. Variable cache is marked to local cache text file located inside the local directory.
Command:
1
./zbox sync --uploadonly --localpath $local --localcache $cache 
Copied!
Response
1
  OPERATION |    PATH
2
+-----------+------------+
3
  Upload    | /file1.txt
4
  Upload    | /file2.txt
5
  Upload    | /file3.txt
6
​
7
 12 / 12 [=======================================================================================================================================================================] 100.00% 0s
8
Status completed callback. Type = application/octet-stream. Name = file1.txt
9
 24 / 24 [=======================================================================================================================================================================] 100.00% 0s
10
Status completed callback. Type = application/octet-stream. Name = file2.txt
11
 28 / 28 [=======================================================================================================================================================================] 100.00% 0s
12
Status completed callback. Type = application/octet-stream. Name = file3.txt
13
​
14
Sync Complete
15
​
Copied!
Verify whether the files are uploaded using
1
./zbox list --remotepath / --allocation $ALLOC
Copied!
Response:
All the files located in the local directory should be listed in the remotepath.
1
  TYPE |   NAME    |    PATH    | SIZE | NUM BLOCKS |                           LOOKUP HASH                            | IS ENCRYPTED | DOWNLOADS PAYER
2
+------+-----------+------------+------+------------+------------------------------------------------------------------+--------------+-----------------+
3
  d    | myfiles   | /myfiles   |      |          4 | e8129c2bc551226f0043b17c218f27bfaababd3e6340c60590e4edbbd9cb2517 |              | owner
4
  f    | file1.txt | /file1.txt |   12 |          4 | 899454ceec5d3791f15743dfd91ce22eb9b365f1563c5e389bf3b0ca2e92f85f | NO           | owner
5
  f    | file2.txt | /file2.txt |   24 |          4 | 585d0cc1fcffbf5d2c13697489eb3d49247deaebda380c60afd759b4ca15dad6 | NO           | owner
6
  f    | file3.txt | /file3.txt |   28 |          4 | 63c8f593b9341873f4b5f478c49da1b6d9c58a3aefc4f483a017b86840ba0e7d | NO           | owner
Copied!
Private File Sharing
Private sharing of files can be implemented using the ./zbox share command.Parameters can be viewed using./zbox share --helpare shown below:
Parameter
Required
Description
Valid values
allocation
yes
allocation id
string
clientid
no
id of user to share file with, leave blank for public share
string
encryptionpublickey
no
public key of the client to share file with, required if clientId
string
expiration-seconds
no
seconds before auth ticket expires
int
remotepath
yes
remote path of file to share
string
revoke
no
revoke share for remote path
flag
Note: Private File Sharing only works with encrypted files.
Let's consider two users (User A and B) and User A wants to privately share the info.txt file located in myfiles/info.txt directory in dStorage with User B.
1.User A will upload the encrypted info.txt file. For instructions on how to upload an encrypted file check Uploading an Encrypted file on dStorage.
2. User B has to share his client id and encryption public key which can be retrieved using thegetwalletcommand. Here we are showing the output of the UserB getwallet command
Command:
1
./zbox getwallet
Copied!
Response:
1
 PUBLIC KEY                       |     CLIENTID          |   ENCRYPTION PUBLIC KEY      
2
9bdb7137eab401bf715d49479fd7790a35b270ac08b23b5778fea005c81f2f19a66785bb7917830d2d
3
513afffc4061bc578fa9af09eb2cf17fd8a6fdb877ef8e  
4
 | 8e4e5ad06a7fef3e3810074f0f6b2d203170d0e386a84936ea5fc94428ce18c9 
5
 | qpV7bqX77UEzNj722qIrxgpHBVR5i8sR6UDdQ70ZSys=
6
​
Copied!
3.Let's export the User B clientid and public encryption key to a variable named UserB and PUBLIC_KEY_UserB
1
export UserB=8e4e5ad06a7fef3e3810074f0f6b2d203170d0e386a84936ea5fc94428ce18c9
2
export PUBLIC_KEY_UserB=qpV7bqX77UEzNj722qIrxgpHBVR5i8sR6UDdQ70ZSys=
Copied!
4.Now use the ./zbox share command with above exported variables .Also specify the allocation and remote path for the file shared by User A which is myfiles/info.txt .
So the sample command for the UserA is:
1
./zbox share --clientid $UserB --encryptionpublickey $PUBLIC_KEY_UserB --allocation $ALLOC --remotepath /myfiles/info.txt                                                                                                          
Copied!
Response:
1
Auth token:eyJjbGllbnRfaWQiOiIyNmU1YjcwZmNiYTNmNzJhNDc1ZWYxZGJjNjZlNDU0ZDNiNDU4Yjk1MGQ2MmM2ZWMyMThjYzM0MjVlM2I2MjFmIiwib3duZXJfaWQiOiJlZmE1MDVhOGFiMzBkNGE3ZTAzNTM4OGE1YzA5OTg1YWY5YTNhMDQyYmFkYzBkODY4YjYyYWRkMjQyMzlkNWExIiwiYWxsb2NhdGlvbl9pZCI6IjFkYTBmYzhmNTgwZTZmZTI3M2QwN2MyZTU0NGEyNjA4MDRlMmVmNTBiMjM4OTAwZGYzMzAwNDIzYzI0YjYwYmQiLCJmaWxlX3BhdGhfaGFzaCI6IjNjNDRkNWRhNDM2ODdhMjJkMmUxMDM1NTQ3NDQ1YjA4NDFlMzQ0YWVmMzk1NGU1MWM3MzAwYTU3NDgwNzVkMWUiLCJmaWxlX25hbWUiOiJpbmZvLnR4dCIsInJlZmVyZW5jZV90eXBlIjoiZiIsImV4cGlyYXRpb24iOjE2Mjg1MzM5NzUsInRpbWVzdGFtcCI6MTYyMDc1Nzk3NSwicmVfZW5jcnlwdGlvbl9rZXkiOiJ7XCJyMVwiOlwiRHY3WTNQTFEyNXJ3VEFuZjdQRlI5TWw1cHRlTDFSeXpvQ1VJbjJZMXU3Zz1cIixcInIyXCI6XCJSV0tKSzNLUnE3SHBHQ1BUd2M5YUc4NE8xaXdjSkFWQitXQTdsTEg2UmFjPVwiLFwicjNcIjpcIjArRG5QU0ZOQzZuMWpwSlduS2R4M3dqRlYwcjFzTnduNHBOUEhtNUJmQUE9XCJ9Iiwic2lnbmF0dXJlIjoiYjA0YmFiYTM4NTk0MDg0ZTBjZjI4ZjlmMjg5MDc5ZGJkODg3YWM2MWYwMDEyYjdhOTc3ZjY2YmM3MzQ1ODgwZCJ9
2
​
Copied!
The Response provides an encrypted auth token string that only UserB can use for private download. Any other user using this AuthToken will not be able to download the file.
5.Let's use ./zbox download using Authtoken provided on UserB computer to privately download the file. Necessary Flags are Authtoken and local path to save the file. Make sure to point encrypted auth token using the export AUTH=<Auth token> before running the download command.
1
./zbox download --authticket $AUTH --localpath /root/  
Copied!
Response:
1
 23 / 23 [=======================================================================================================================================================================] 100.00% 0s
2
Status completed callback. Type = application/octet-stream. Name = info.txt•
Copied!
6.To check sharing details and verify whether the file is encrypted. You can also base decode the Authtoken using:
1
echo 'eyJjbGllbnRfaWQiOiIyNmU1YjcwZmNiYTNmNzJhNDc1ZWYxZGJjNjZlNDU0ZDNiNDU4Yjk1MGQ2MmM2ZWMyMThjYzM0MjVlM2I2MjFmIiwib3duZXJfaWQiOiJlZmE1MDVhOGFiMzBkNGE3ZTAzNTM4OGE1YzA5OTg1YWY5YTNhMDQyYmFkYzBkODY4YjYyYWRkMjQyMzlkNWExIiwiYWxsb2NhdGlvbl9pZCI6IjFkYTBmYzhmNTgwZTZmZTI3M2QwN2MyZTU0NGEyNjA4MDRlMmVmNTBiMjM4OTAwZGYzMzAwNDIzYzI0YjYwYmQiLCJmaWxlX3BhdGhfaGFzaCI6IjNjNDRkNWRhNDM2ODdhMjJkMmUxMDM1NTQ3NDQ1YjA4NDFlMzQ0YWVmMzk1NGU1MWM3MzAwYTU3NDgwNzVkMWUiLCJmaWxlX25hbWUiOiJpbmZvLnR4dCIsInJlZmVyZW5jZV90eXBlIjoiZiIsImV4cGlyYXRpb24iOjE2Mjg1MzM5NzUsInRpbWVzdGFtcCI6MTYyMDc1Nzk3NSwicmVfZW5jcnlwdGlvbl9rZXkiOiJ7XCJyMVwiOlwiRHY3WTNQTFEyNXJ3VEFuZjdQRlI5TWw1cHRlTDFSeXpvQ1VJbjJZMXU3Zz1cIixcInIyXCI6XCJSV0tKSzNLUnE3SHBHQ1BUd2M5YUc4NE8xaXdjSkFWQitXQTdsTEg2UmFjPVwiLFwicjNcIjpcIjArRG5QU0ZOQzZuMWpwSlduS2R4M3dqRlYwcjFzTnduNHBOUEhtNUJmQUE9XCJ9Iiwic2lnbmF0dXJlIjoiYjA0YmFiYTM4NTk0MDg0ZTBjZjI4ZjlmMjg5MDc5ZGJkODg3YWM2MWYwMDEyYjdhOTc3ZjY2YmM3MzQ1ODgwZCJ9' | base64 --decode
Copied!
Response:
The response will provide all the private sharing details and encryption key for the shared file under re_encryption_key field.
1
{"client_id":"26e5b70fcba3f72a475ef1dbc66e454d3b458b950d62c6ec218cc3425e3b621f",
2
"owner_id":"efa505a8ab30d4a7e035388a5c09985af9a3a042badc0d868b62add24239d5a1",
3
"allocation_id":"1da0fc8f580e6fe273d07c2e544a260804e2ef50b238900df3300423c24b60bd",
4
"file_path_hash":"3c44d5da43687a22d2e1035547445b0841e344aef3954e51c7300a5748075d1e",
5
"file_name":"info.txt","reference_type":"f","expiration":1628533975,"timestamp":1620757975,
6
"re_encryption_key":"{\"r1\":\"Dv7Y3PLQ25rwTAnf7PFR9Ml5pteL1RyzoCUIn2Y1u7g=\",\"r2\
7
":\"RWKJK3KRq7HpGCPTwc9aG84O1iwcJAVB+WA7lLH6Rac=\",\"r3\":\"0+DnPSFNC6n1jpJWnKdx3wjFV0r1sNwn4pNPHm5BfAA=\"}",
8
"signature":"b04baba38594084e0cf28f9f289079dbd887ac61f0012b7a977f66bc734"
Copied!
Cancel Sharing of File for a Particular User
./zbox share --revoke is used to cancel the share for particular buyer that performed by the seller through Private File Sharing.
Note : ./zbox share --revokeonly works for encrypted files on dStorage.
Required Parameters for Cancel Share are :
Parameter
Required
Description
Valid Values
allocation
yes
allocation id
string
remotepath
yes
remote path of an encrypted file that was earlier shared with the user
duration
clientid
yes
Wallet Client ID of the user whose share access has to be revoked
string
Command :
1
./zbox share --revoke --remotepath $remote --clientid User_CLIENT_ID --allocation $ALLOC
Copied!
Response :
1
Share revoked for client User_CLIENT_ID
Copied!
Private Directory Sharing
Private sharing of directories can be implemented using the ./zbox share command.Parameters can be viewed using./zbox share --helpare shown below:
Parameter
Required
Description
Valid values
allocation
yes
allocation id
string
clientid
no
id of user to share file with, leave blank for public share
string
encryptionpublickey
no
public key of the client to share file with, required if clientId
string
expiration-seconds
no
seconds before auth ticket expires
int
remotepath
yes
remote path of file to share
string
revoke
no
revoke share for remote path
flag
Note: Private Directory Sharing works for both encrypted and non-encrypted files
Let's consider two users (User A and B) and User A wants to privately share the docs directory in dStorage with User B.
1.User A should check whether the docsdirectory exists on dStorage using the list command.
Command :
1
./zbox list --remotepath /docs --allocation c6507f3f6470972a928576a2f0cb00019fcc4ca8e60c8c9e085a8a905da6d838
Copied!
Response :
1
  TYPE |   NAME    |      PATH       | SIZE | NUM BLOCKS |                           LOOKUP HASH                            | IS ENCRYPTED | DOWNLOADS PAYER  
2
-------+-----------+-----------------+------+------------+------------------------------------------------------------------+--------------+------------------
3
  f    | info.txt  | /docs/info.txt  |   48 |          4 | 3b256a3b8fbf1f497eea5b7d149228fc23e39c98c7f06b960949690070157d3b | NO            
4
  f    | hello.txt | /docs/hello.txt |   30 |          3 | 4f2515f95d35c7d6641197cc024608b4dc2af1b4c8fb9af0f2637e0c89c3c5cc | NO            
5
​
Copied!
2. Now User B has to share his client id and encryption public key which can be retrieved using thegetwalletcommand. Here we are showing the output of the UserB getwallet command
Command:
1
./zbox getwallet
Copied!
Response:
1
 PUBLIC KEY  |    CLIENTID                             |            ENCRYPTION PUBLIC KEY              
2
-----------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------+-----------------------------------------------
3
  9332ca57e335f286f1d3edc2dd7589594dbb4b30fae19766b5f67712520fde09f8eac6a979f3574ccd89e5680a6b47dcdc88ae0544dc30633cce2a7831ce0014 | 9460d64ab63340a0b4305d20a032690a495ed50d6dc92d238a42b25fdf79258b | bKodfMsHfUNXr/rr8msPe4Rv2nLP34aUIasK44p7tRs=
4
​
Copied!
3.Let's export the User B clientid and public encryption key to a variable named UserB and PUBLIC_KEY_UserB
1
export UserB=9460d64ab63340a0b4305d20a032690a495ed50d6dc92d238a42b25fdf79258b
2
export PUBLIC_KEY_UserB=bKodfMsHfUNXr/rr8msPe4Rv2nLP34aUIasK44p7tRs=
Copied!
4.Now use the ./zbox share command with above exported variables .Also specify the allocation and remote path for the directory .
1
./zbox share --clientid $UserB --encryptionpublickey $PUBLIC_KEY_UserB --allocation $ALLOC --remotepath /docs                                                                                                        
Copied!
Response:
The Response provides an encrypted auth token string that only UserB can use for private download. Any other user using this AuthToken will not be able to download the file.
1
Auth token :eyJjbGllbnRfaWQiOiI5NDYwZDY0YWI2MzM0MGEwYjQzMDVkMjBhMDMyNjkwYTQ5NWVkNTB
2
kNmRjOTJkMjM4YTQyYjI1ZmRmNzkyNThiIiwib3duZXJfaWQiOiJjZTk1ZGM4YWM5MzMyNDlhMjE4NTM3NT
3
FkMzk5OWMzMWFhNjlmNmRiMDBjMDFmMTY2YTg3ODI4MzJmZWE3ZmQ4IiwiYWxsb2NhdGlvbl9pZCI6ImM2
4
NTA3ZjNmNjQ3MDk3MmE5Mjg1NzZhMmYwY2IwMDAxOWZjYzRjYThlNjBjOGM5ZTA4NWE4YTkwNWRhNmQ4Mzg
5
iLCJmaWxlX3BhdGhfaGFzaCI6IjE0OGY3YjAyNWE2ZTA1ZWZlZWQ5N2YxMTA5ZmJjYzg1ZGIyMTU4MTRjZj
6
JhODJmNjYyOTdjZjI3NWRjMjYyMDciLCJhY3R1YWxfZmlsZV9oYXNoIjoiYTU5MTc1NGM3MTY1Yzk0NzcwN
7
GU4ZTM3OGY4ZmI2NTI4NjdhNjFjMSIsImZpbGVfbmFtZSI6ImRvY3MiLCJyZWZlcmVuY2VfdHlwZSI6ImYi
8
LCJleHBpcmF0aW9uIjoxNjM3NTMxNTIzLCJ0aW1lc3RhbXAiOjE2Mjk3NTU1MjMsInJlX2VuY3J5cHRpb25
9
fa2V5IjoiIiwiZW5jcnlwdGVkIjp0cnVlLCJzaWduYXR1cmUiOiJmNThhNDViZGVkOGQzNDMwMzcyMzU3ZWQ
10
1MmEzODFmZmI5ZDk4MWNjMzc0NzQ4OTk3M2QzMDFmOGZjMDVjMzFkIn0=
Copied!
5. The string is encoded , to know the sharing details of the string UserB can decode it using the command :
1
echo 'eyJjbGllbnRfaWQiOiI5NDYwZDY0YWI2MzM0MGEwYjQzMDVkMjBhMDMyNjkwYTQ5NWVkNTBkNmRjOT
2
JkMjM4YTQyYjI1ZmRmNzkyNThiIiwib3duZXJfaWQiOiJjZTk1ZGM4YWM5MzMyNDlhMjE4NTM3NTFkMzk5O
3
WMzMWFhNjlmNmRiMDBjMDFmMTY2YTg3ODI4MzJmZWE3ZmQ4IiwiYWxsb2NhdGlvbl9pZCI6ImM2NTA3ZjNm
4
NjQ3MDk3MmE5Mjg1NzZhMmYwY2IwMDAxOWZjYzRjYThlNjBjOGM5ZTA4NWE4YTkwNWRhNmQ4MzgiLCJmaWx
5
lX3BhdGhfaGFzaCI6IjE0OGY3YjAyNWE2ZTA1ZWZlZWQ5N2YxMTA5ZmJjYzg1ZGIyMTU4MTRjZjJhODJmNj
6
YyOTdjZjI3NWRjMjYyMDciLCJhY3R1YWxfZmlsZV9oYXNoIjoiYTU5MTc1NGM3MTY1Yzk0NzcwNGU4ZTM3O
7
GY4ZmI2NTI4NjdhNjFjMSIsImZpbGVfbmFtZSI6ImRvY3MiLCJyZWZlcmVuY2VfdHlwZSI6ImYiLCJleHBpc
8
mF0aW9uIjoxNjM3NTMxNTIzLCJ0aW1lc3RhbXAiOjE2Mjk3NTU1MjMsInJlX2VuY3J5cHRpb25fa2V5Ijoi
9
IiwiZW5jcnlwdGVkIjp0cnVlLCJzaWduYXR1cmUiOiJmNThhNDViZGVkOGQzNDMwMzcyMzU3ZWQ1MmEzODFm
10
ZmI5ZDk4MWNjMzc0NzQ4OTk3M2QzMDFmOGZjMDVjMzFkIn0=' | base64 --decode
Copied!
Response :
1
{"client_id":"9460d64ab63340a0b4305d20a032690a495ed50d6dc92d238a42b25fdf79258b",
2
"owner_id":"ce95dc8ac933249a21853751d3999c31aa69f6db00c01f166a8782832fea7fd8",
3
"allocation_id":"c6507f3f6470972a928576a2f0cb00019fcc4ca8e60c8c9e085a8a905da6d838",
4
"file_path_hash":"148f7b025a6e05efeed97f1109fbcc85db215814cf2a82f66297cf275dc26207"
5
,"actual_file_hash":"a591754c7165c947704e8e378f8fb652867a61c1","file_name":"docs",
6
"reference_type":"f","expiration":1637531523,"timestamp":1629755523,"re_encryption_key":"",
7
"encrypted":true,"signature":"f58a45bded8d3430372357ed52a381ffb9d981cc3747489973d301f8fc05c31d"}
Copied!
6. Now UserB can download files inside the shared directory with the AUTH token. First point the encrypted auth token to a variable using the export command.
1
export AUTH = eyJjbGllbnRfaWQiOiI5NDYwZDY0YWI2MzM0MGEwYjQzMDVkMjBhMDMyNjkwYTQ5NWVkNTBkNmRjOTJkMjM4YTQyYjI1ZmRmNzkyNThiIiwib3duZXJfaWQiOiJjZTk1ZGM4YWM5MzMyNDlhMjE4NTM3NTFkMzk5OWMzMWFhNjlmNmRiMDBjMDFmMTY2YTg3ODI4MzJmZWE3ZmQ4IiwiYWxsb2NhdGlvbl9pZCI6ImM2NTA3ZjNmNjQ3MDk3MmE5Mjg1NzZhMmYwY2IwMDAxOWZjYzRjYThlNjBjOGM5ZTA4NWE4YTkwNWRhNmQ4MzgiLCJmaWxlX3BhdGhfaGFzaCI6IjE0OGY3YjAyNWE2ZTA1ZWZlZWQ5N2YxMTA5ZmJjYzg1ZGIyMTU4MTRjZjJhODJmNjYyOTdjZjI3NWRjMjYyMDciLCJhY3R1YWxfZmlsZV9oYXNoIjoiYTU5MTc1NGM3MTY1Yzk0NzcwNGU4ZTM3OGY4ZmI2NTI4NjdhNjFjMSIsImZpbGVfbmFtZSI6ImRvY3MiLCJyZWZlcmVuY2VfdHlwZSI6ImYiLCJleHBpcmF0aW9uIjoxNjM3NTMxNTIzLCJ0aW1lc3RhbXAiOjE2Mjk3NTU1MjMsInJlX2VuY3J5cHRpb25fa2V5IjoiIiwiZW5jcnlwdGVkIjp0cnVlLCJzaWduYXR1cmUiOiJmNThhNDViZGVkOGQzNDMwMzcyMzU3ZWQ1MmEzODFmZmI5ZDk4MWNjMzc0NzQ4OTk3M2QzMDFmOGZjMDVjMzFkIn0=
Copied!
7. Download the files inside the directory by using the following command
1
zbox download --localpath $local --authticket $AUTH --remotepath $remote --allocation $ALLOC
Copied!
Response:
1
 19 / 19 [=====================================================================================================================================================================================] 100.00% 0s
2
Status completed callback. Type = application/octet-stream. Name = docs
3
​
Copied!
Note : The allocation ID required in the command above can be retrieved from decoding the AUTH string. For remote path the actual path for the shared directory should be specified.
If you are not able to download files and getting Error in file operation: File content didn't match with uploaded file response check Error 2 in Tips and Troubleshooting Section.
File Collaboration
Add a collaborator for a file in dStorage
./zbox add-collabcommand can be used for adding collaborators on all blobbers for the given file. Parameters can be viewed using ./zbox add-collab --help
Parameter
Required
Description
default
Valid values
allocation
yes
allocation id
​
string
collabid
yes
id of collaberator
​
string
remotepath
yes
file on which to collaberate
​
string
Steps:

1.The collaborator has to share the wallet Client ID by using the ./zbox getwalletcommand . Here is the sample output of the getwallet command.
Command:
1
./zbox getwallet
Copied!
Response:
1
 PUBLIC KEY                       |     CLIENTID   |       ENCRYPTION PUBLIC KEY   
2
 9bdb7137eab401bf715d49479fd7790a35b270ac08b23b5778fea005c81f2f19a66785bb7917830d2d
3
 513afffc4061bc578fa9af09eb2cf17fd8a6fdb877ef8e  
4
  | fde00f70ddc4b2d9c5d5cb3761e7baede145b054d7e49e28525b5c76721e603d 
5
  | qpV7bqX77UEzNj722qIrxgpHBVR5i8sR6UDdQ70ZSys=
6
​
Copied!
3.Let's export the collaborator clientid to a variable.
1
export collab_id=fde00f70ddc4b2d9c5d5cb3761e7baede145b054d7e49e28525b5c76721e603d
Copied!
4.Now execute the add-collab command by mentioning the remote path, allocation ID and collab ID. Here is a sample command for adding collaborator on dStorage.
1
./zbox add-collab --collabid $collab_id --remotepath $remote --allocation $ALLOC 
Copied!
Response
1
Collaborator fde00f70ddc4b2d9c5d5cb3761e7baede145b054d7e49e28525b5c76721e603d 
2
added successfully for the file /file1.txt
3
​
Copied!
Successful Response will output confirmation that collaborator is added for the given file.
5.You can verify whether the collaborators for a file are available.
Command:
1
./zbox meta --allocation $ALLOC --remotepath $remote --json
Copied!
Response:
1
Output:
2
{"Name":"file1.txt","Type":"f","Path":"/file1.txt",
3
"LookupHash":"899454ceec5d3791f15743dfd91ce22eb9b365f1563c5e389bf3b0ca2e92f85f",
4
"Hash":"f572d396fae9206628714fb2ce00f72e94f2258f","MimeType":"application/octet-stream",
5
"Size":6,"EncryptedKey":"","CommitMetaTxns":[],
6
"Collaborators":[{"ref_id":261,"client_id":"fde00f70ddc4b2d9c5d5cb3761e7baede145b05
7
4d7e49e28525b5c76721e603d","created_at":"2021-04-22T00:29:21.304637Z"}],
8
"Attributes":{}}
Copied!
As you scroll right in the response, the Collaborators column of the response will contain the client_id of the collaborator added.
Delete a collaborator for a file in dStorage
./zbox delete-collab command can be used for deleting collaborators on all blobbers for the given file. Parameters can be viewed using ./zbox delete-collab --help
Parameter
Required
Description
default
Valid values
allocation
yes
allocation id
​
string
collabid
yes
id of collaberator
​
string
remotepath
yes
file on which to collaberate
​
string
Steps:
To delete a collaborator for a file
1.First check the collaborators for a file using the ./zbox meta command.
1
./zbox meta --remotepath $remote --json --allocation $ALLOC
Copied!
Response:
1
Output:
2
{"Name":"file1.txt","Type":"f","Path":"/file1.txt","LookupHash":"899454ceec5d3791f15743dfd91ce22eb9b365f1563c5e389bf3b0ca2e92f85f","Hash":"f572d396fae9206628714fb2ce00f72e94f2258f","MimeType":"application/octet-stream","Size":6,"EncryptedKey":"","CommitMetaTxns":[],"Collaborators":[{"ref_id":261,"client_id":"fde00f70ddc4b2d9c5d5cb3761e7baede145b054d7e49e28525b5c76721e603d","created_at":"2021-04-22T00:29:21.304637Z"}],"Attributes":{}}
Copied!
As you scroll right in the response, the Collaborators column contains the client_id's of the collaborators.
2.Export the client_id that has to be deleted to a variable .
1
export collab_id=fde00f70ddc4b2d9c5d5cb3761e7baede145b054d7e49e28525b5c76721e603d
Copied!
3.Now execute the delete-collab command by mentioning the remote path,allocation ID and collab-id.
Here is a sample command for deleting the collaborator for the file on dStorage.
1
./zbox delete-collab --collabid $collab_id --remotepath $remote --allocation $ALLOC 
Copied!
Response:
1
Collaborator fde00f70ddc4b2d9c5d5cb3761e7baede145b054d7e49e28525b5c76721e603d 
2
removed successfully for the file <file-path>.
Copied!
4.Verify whether the collaborators for a file are deleted using the command
1
./zbox meta --remotepath $remote --json --allocation $ALLOC 
Copied!
Response:
1
Output:
2
{"Name":"file1.txt","Type":"f","Path":"/file1.txt",
3
"LookupHash":"899454ceec5d3791f15743dfd91ce22eb9b365f1563c5e389bf3b0ca2e92f85f",
4
"Hash":"f572d396fae9206628714fb2ce00f72e94f2258f",
5
"MimeType":"application/octet-stream","Size":6,
6
"EncryptedKey":"",
7
"CommitMetaTxns":[],
8
"Collaborators":[],
9
"Attributes":{}}
10
​
Copied!
As you can see there is no ClientID mentioned in the Collaborators column of the response which signifies the collaborator is successfully deleted.
Repair a file on dStorage
Use ./zbox start-repair command to repair a file on dStorage. Parameters can be viewed using the --help flag.
Parameter
Required
Description
default
Valid values
allocation
yes
allocation id
​
string
repairpath
yes
remote path of files on dStorage to repair
​
string
rootpath
yes
File path for local files. Files from rootpath will be compared with files on dStorage for data blocks error.
​
string
​Sample Command:
1
./zbox start-repair --repairpath /myfiles --rootpath $root --allocation $ALLOC
Copied!
Response:
1
Repair file completed, Total files repaired:  0
Copied!
In the above response the total number of files repaired were 0 which means all the data blocks for the files are not altered or damaged.
Asking the receiver to pay for download (RX_pay)
RX pay is a specified boolean flag in ./zbox download command which asks the file receiver to pay for their file download.
Parameters for --rx_pay flag can be viewed using the zbox download --help​.
Parameter
Required
Description
Default
Valid values
allocation
yes
allocation id
​
string
authticket
no
auth ticked if not owner of the allocation, use share to get auth ticket
​
string
blockspermarker
no
download multiple blocks per marker
10
int
commit
no
save metadata to blockchain
false
boolean
endblock
no
download until specified block number
​
int
localpath
yes
local path to which to download the file to
​
file path
remotepath
yes
remote path to which the file was uploaded
​
string
rx_pay
no
authticket must be valid, true = sender pays, false = allocation owner pays
false
boolean
startblock
no
start download from specified block
​
int
thumbail
no
only download the thumbnail
false
boolean
As we can see that RX pay requires download by auth ticket and a rx_pay boolean set to true .
Example: Let's take two users (User A and User B). User A is the seller of the file downloaded by User B (receiver).
1.User A will upload a file on dstorage and share an authtoken for the file. For example we are uploading
info1.txt file located on myfiles directory of dStorage which User B will download and pay for himself using --rxpay.
2.To make the file available for pay User A has to set the--attr-who-pays-for-reads for upload command to 3rd_party (by default it is set to "owner")
Sample Command:
1
./zbox upload --attr-who-pays-for-reads 3rd_party --remotepath $remote --allocation $ALLOC 
Copied!
3.To verify whether downloads payer are properly configured use:
1
./zbox list --remotepath $remote --allocation $ALLOC 
Copied!
Response:
1
  TYPE |   NAME    |        PATH        | SIZE | NUM BLOCKS | LOOKUP HASH 
2
  | IS ENCRYPTED | DOWNLOADS PAYER
3
​
4
  f    | info1.txt | /myfiles/info1.txt |   44 |      4 | bf58c1b39eb26ae8762822623
5
  e38f919358338017f8b2144e5cf6ccab23fd2af  | NO  | 3rd_party
6
​
Copied!
In the response, you will notice that the downloads payers section for info1.txt are successfully set to 3rd-party.
4.To know how to share a file on dStorage and get an AuthToken for a file have a look at the sharing a file on dStorage .
5.Once the auth token is created and marked to a variable, share it with the receiver(UserB) who will run the .zbox download command to download the file with --rx_pay flag.
Command for User B:
1
./zbox download --authticket $AUTH --localpath /root/ --rx_pay true 
Copied!
Response:
1
 23 / 23 [=======================================================================================================================================================================] 100.00% 0s
2
Status completed callback. Type = application/octet-stream. Name = info1.txt
3
​
Copied!
To verify whether (UserB) has paid successfully for the download check the wallet and read pool balance for change using ./zwallet getbalance and /zbox rp-info.
Note: Do unlock read tokens using rp-unlock before using ./zwallet getbalanceto let the download money reflect in wallet.
Video Streaming
Video streaming with Zboxcli can be implemented with players for different operating platforms(iOS, Android, Mac). Zbox CLI does not have a player itself and uses the following helping functions :
downloadFileByBlocks - properly returns file-chunks with correct byte range,.
getFileMeta - returns actuaBlockNumbers and actualFileSize (exclude thumbnail size)
getFileMetaByAuth - same updates as getFileMeta
listAllocation - returns actuaBlockNumbers and actualFileSize (exclude thumbnail size)
For all the Platforms streaming implementation using ZboxCLi has the following flow:
When the user starts the video player (ExoPlayer for Android or AVPlayer for iOS), A ZChainDataSource starts chunked download and requests chunks of video from the buffer(a Middleman between streaming player and Zbox).
After the arrival of the first chunk, the player starts requesting more chunks from the buffer which request the Zbox SDK .Zbox SDK which is built using GO makes use of the downloadFileByBlocks method to reliably download large files by chunking them into a sequence of parts that can be downloaded individually. Once the blocks are downloaded they are read into input streams and added to the media source of the streaming player.
The task of downloading files and writing them to buffer using ZboxSDK happens constantly and If player request random bits of video they are delivered instantly by the buffer.
In a case, if the player didn't receive chunks (for example it's still not downloaded), then the player switches to STALE state and the video stream will pause. During the STALE state, player tries to make multiple requests for chunks, if didn't receive a response the video stream stops.
To understand how Zbox CLI provides downloading of files by blocks check the below demonstration:
For instance, Let's consider an allocation which has a audio.mp3file stored on dStorage. Make sure the file has a large size(more than 64 kB(64000 bytes) ) to download the file by blocks. The size and other attributes of the sampleaudio.mp3file can be viewed using
1
./zbox list --allocation $ALLOC --remotepath /myfiles
Copied!
Response:
1
  TYPE |   NAME    |        PATH        |  SIZE   | NUM BLOCKS |LOOKUP HASH      
2
  | IS ENCRYPTED | DOWNLOADS PAYER
3
+------+-----------+--------------------+---------+------------+----------------
4
  f    | audio.mp3 | /myfiles/audio.mp3 | 5992396 |         92 | 3cea39505cc30fb9f6fc5c6045284188feb14eac8ff3a19577701c4f6d973239 
5
  | NO           | owner
6
​
7
​
8
​
Copied!
Here we can see audio.mp3 file has size (5993286) bytes and has 92 blocks. If we want to download a certain number of blocks for the info.txt file we can use --endblock or --startblock flag with ./zbox download command. Other flags for download can be viewed using ./zbox download --help
1
Flags:
2
    
3
  -b, --blockspermarker int   pass this option to download multiple blocks per marker (default 10)                                                               -e, --endblock int          pass this option to download till specific block number                                                                                               
4
  -h, --help                  help for download
5
--localpath string      Local path of file to download                           --remotepath string     Remote path to download
6
 -s, --startblock int        pass this option to download from specific block number                                                                                                         
Copied!
To download only 3 blocks of audio.mp3 file we specify --startblock and--endblock with an integer value of 1 and 3. --blockspermarkerflag can also be specified to download multiple blocks at a time(default is 10).
The whole download command for downloading till 3rd block of audio.mp3 file would be:
1
./zbox download --localpath /root --remotepath /myfiles/audio.mp3 --allocation $ALLOC --startblock 1 --endblock 3 
Copied!
Response:
1
 393216 / 2996198 [====================>-----------------------------------------------------------------------------------------------------------------------------------------]  13.12% 1s
2
Status completed callback. Type = audio/mpeg. Name = audio.mp3
3
​
Copied!
As we can see, the downloaded file size(393216) is quite less than the original(2996198) which means zbox has downloaded some blocks of the file.
Uploading and Managing Files
Tips & Troubleshooting
Last modified 1mo ago
Copy link
Contents
Sync
Batch upload files to dStorage
Private File Sharing
Cancel Sharing of File for a Particular User
Private Directory Sharing
File Collaboration
Repair a file on dStorage
Asking the receiver to pay for download (RX_pay)
Video Streaming