0Chain
Search…
Zbox Commands
Global Flags
Global Flags are parameters in zbox that can be used with any command to override the default configuration. zbox supports the following global parameters.
Flags
Description
Usage
--config string
Specify a zbox configuration file (default is $HOME/.zcn/config.yaml)
zbox [command] --config config1.yaml
--configDir string
Specify a zbox configuration directory (default is $HOME/.zcn)
zbox [command] --configDir /$HOME/.zcn2
-h, --help
Gives more information about a particular command.
zbox [command] --help
--network string
Specify a network file to overwrite the network details(default is $HOME/.zcn/network.yaml)
zbox [command] --network network1.yaml
--silent
Hides details as to what the particular zbox command is doing.
zbox [command] --verbose
--wallet string
Specify a wallet file or 2nd wallet (default is $HOME/.zcn/wallet.json)
zbox [command] --wallet wallet2.json
--wallet_client_id string
Specify a wallet client id (By default client_id specified in $HOME/.zcn/wallet.json is used)
zbox [command] --wallet_client_id
--wallet_client_key string
Specify a wallet client_key (By default client_key specified in $HOME/.zcn/wallet.json is used)
zbox [command] --wallet_client_key < client_key>
Assigning Variables
We will use the following variables using the export command for easy demonstration of
zboxfunctionalities.1
export ALLOC = <your allocation ID >
Copied!
1
export AUTH = <your Auth ticket>
Copied!
1
export lookuphash =<lookup hash for your uploaded file>
Copied!
1
export local=<local path of the the file/directory on local computer >
Copied!
1
export remote=<remote path of the file/directory on dStorage>
Copied!
Creating and Managing Allocations
List Allocations
./zbox listallocations show active storage allocations on dStorage. If you have not created any storage allocation we would suggest creating a storage allocation following this guide.Command:
1
./zbox listallocations
Copied!
Response:
The response should contains the list of all your allocations with their specifications.(size, datashards, parityshards ,read price etc.)
1
ID | SIZE | EXPIRATION | DATASHARDS | PARITYSHARDS | FINALIZED | CANCELED | R PRICE | W PRICE
2
+------------------------------------------------------------------+------------+-------------------------------+------------+--------------+-----------+----------+----------+----------+
3
52fb9b5926c06e43a9290e9d7ad3217a4aee51c94684baf0fc174aa41abe6059 | 2147483648 | 2021-05-14 17:50:59 +0000 UTC | 2 | 2 | false | false | 0.04 | 0.04
4
637191e4cc5d78c5e8f3943b96a7de6509ec7cba28fd593d302a86b4c062a6ef | 115000000 | 2021-04-23 04:11:44 +0000 UTC | 3 | 3 | false | false | 0.06 | 0.0
Copied!
Custom Allocation
Creating a custom allocation requires execution of
./zbox newallocation command with customized parameters. If you are creating your first allocation we would suggest reading Creating a Storage Allocation section first.Required parameters for creating a custom allocation can be viewed by using the command
./zbox newallocation --helpHere are the parameters :
Parameter
Description
Default
Valid Values
allocationFileName
local file to store allocation information
allocation.txt
file path
cost
returns the cost of the allocation, no allocation created
flag
data
number of data shards, effects upload and download speeds
2
int
expire
duration to allocation expiration
720h
duration
free_storage
free storage marker file.
file path
owner
owner's id, use for funding an allocation for another
string
owner_public_key
public key, use for funding an allocation for another
string
lock
lock write pool with given number of tokens
float
mcct
max challenge completion time
1h
duration
parity
number of parity shards, effects availability
2
int
read_price
filter blobbers by read price range
0-inf
range
size
size of space reserved on blobbers
2147483648
bytes
usd
give token value in USD
flag
write_price
filter blobbers by write price range
0-inf
range
Example:
Let's create an allocation with 3 parity and data shards . Specify allocation expiration to 200hrs, change allocation size from default 2GB(2147483648) to near 1GB (1000000000), and lock tokens.
Command :
1
./zbox newallocation --data 3 --parity 3 --expire 200h --size 100000000 --lock 0.2
Copied!
Response:
Verify the custom allocation by using the
./zbox listallocationscommandOutput:
1
ID | SIZE | EXPIRATION | DATASHARDS | PARITYSHARDS | FINALIZED | CANCELED | R PRICE | W PRICE
2
+------------------------------------------------------------------+------------+-------------------------------+------------+--------------+-----------+----------+----------+----------+
3
52fb9b5926c06e43a9290e9d7ad3217a4aee51c94684baf0fc174aa41abe6059 | 2147483648 | 2021-05-14 17:50:59 +0000 UTC | 2 | 2 | false | false | 0.04 | 0.04
4
637191e4cc5d78c5e8f3943b96a7de6509ec7cba28fd593d302a86b4c062a6ef | 100000000 | 2021-04-23 04:11:44 +0000 UTC | 3 | 3 | false | false | 0.06 | 0.06
5
Copied!
Your custom allocation should be listed with specifications.
Update Allocation
./zbox updateallocationcommand is used to update the existing allocation for various parameters, Parameters for updating the allocation can be viewed by using the./zbox updateallocation --help command.Here are the parameters:
Parameter
Required
Description
Valid Values
allocation
yes
allocation id
string
expiry
adjust storage expiration time
duration
free_storage
free storage marker file
string
lock
yes*
lock additional tokens in write pool
int
set_immutable
sets allocation so that data can no longer be modified
boolean
size
adjust allocation size
bytes
* only required if free_storage not set.As mentioned in the above table , the allocation can be updated for size, expiry and immutability(set_immutable). We will provide an example for updating size and expiry of allocation below.
To know how to make an allocation immutable check Create an Immutable Allocation .
Example:
Let's edit an already created allocation for size and expiry.
Steps:
- 1.
2. Use the
updateallocation command and provide the new size .1
./zbox updateallocation --allocation $ALLOC --size 15000000
Copied!
3. Now provide the new expiry time
1
./zbox updateallocation --allocation $ALLOC --expiry 600h
Copied!
Sample Response:
.gif?alt=media)
Add a curator
A curator can be added to transfer ownership of an allocation. Only a curator can change an allocation's ownership.
To add a curator using the
addcurator command , following parameters are required :Parameter
Required
Description
Valid Values
allocation
yes
allocation id
string
curator
yes
Wallet Client ID of new curator to add to allocation
string
Steps:
2. Export the new Curator Wallet Client ID to a variable.
1
export CURATOR_WALLET_CLIENT_ID=9460d64ab63340a0b4305d20a032690a495ed50d6dc92d238a42b25fdf79258b
Copied!
3. Use the
addcurator command1
./zbox addcurator --curator $CURATOR_WALLET_CLIENT_ID --allocation $ALLOC
Copied!
Sample Response:
List Curators
Each allocation maintains a list of curators which can be viewed using the
./zbox get allocation command. To view the list of curators using the get command , following parameters are required :Parameter
Required
Description
Valid Values
allocation
yes
allocation id
string
Steps:
1. Use the
get command and pass the allocation ID of the allocation for which you want the list of curators .1
./zbox get --allocation $ALLOC
Copied!
2. The curators will be mentioned in the end of the response with their configuration:
(NOTE: The output below has been edited for length.)
Remove a curator
A curator can be removed for an allocation by using the
removecurator command ,
Following parameters are required to remove a curator :Parameter
Required
Description
Valid Values
allocation
yes
allocation id
string
curator
yes
Wallet Client ID of a curator to remove from allocation
string
Steps:
2. Export the Curator ID that has to be removed to a variable.
1
export CURATOR_WALLET_CLIENT_ID=<CURATOR_ID>
Copied!
3. Use the
removecurator command1
./zbox removecurator --curator $CURATOR_WALLET_CLIENT_ID --allocation $ALLOC
Copied!
Sample Response:
Transfer allocation ownership
transferallocation changes the owner of an allocation. Only a curator, previously added through addcurator command can change an allocation's ownership. If the current owner wants to transfer ownership they have to first add themselves as a curator using addcurator.transferallocation does not move any funds, only changes the owner, and the owner's public key.To transfer the ownership of an allocation using the
transferallocation command, following parameters are requiredParameter
Required
Description
Valid Values
allocation
yes
Allocation id of the allocation whose ownership has to be changed
string
newowner
yes
Wallet Client ID of new Owner
string
new__owner__key
yes
Wallet Public Key of the new Owner
string
Steps:
2. Export the new Owner Wallet Client ID to a variable.
1
export OWNER_WALLET_CLIENT_ID=9460d64ab63340a0b4305d20a032690a495ed50d6dc92d238a42b25fdf79258b
Copied!
3. Export the new Owner Public Key to a variable
1
export OWNER_WALLET_PUBLIC_KEY=383a51ac8424d5079fa1402e26a3455a42ca9c03c8bff7d0f8eb0431d4f22b199b5ecae4405a5aa29c624c5299d79b8ba023c43e3d0599c2b60e74d445b3ae
Copied!
4. Use the
transferallocation command.1
./zbox transferallocation --new_owner $OWNER_WALLET_CLIENT_ID --new_owner_key $OWNER_WALLET_PUBLIC_KEY --allocation $ALLOC
Copied!
Note: Only the curator can transfer ownership of allocation.
Sample Response:
Create an Immutable Allocation
You can prevent an allocation from any crud( create, read, update and delete) operations by making it immutable through the
updateallocation command.To create an immutable allocation using the
updateallocation command , following parameters are required.Parameter
Required
Description
Valid Values
allocation
yes
allocation id
string
set_immutable
yes
Boolean for the immutable allocation. Has to be set to true for making the allocation immutable.
boolean
Steps:
- 1.Use the
updateallocationcommand.
1
./zbox updateallocation --set_immutable true --allocation $ALLOC
Copied!
Response :
1
Allocation updated with txId : 1aef0e669af8b96d7240c3594643cca2b47a5a463d4381a5448168e15461f58e
Copied!
You can check whether the allocation has become immutable by uploading a file to the allocation. It should deny access with the following error
1
[ERROR] 2021/09/25 01:53:41.310951 chunked_upload_blobber.go:75:
2
http://0.fra.zcn.zeroservices.eu:5054
3
Upload error response: 400{"code":"immutable_allocation","error":"immutable_allocation:
4
Cannot write to an immutable allocation"}
5
Copied!
Get Allocation Details
./zbox get command is used to get detailed information about the allocation such as total size ,used size, number of challenges, etc .The command can accept the following parameters :
Parameter
Required
Description
Valid Values
--allocation
yes
Allocation ID of an allocation
string
--json
Use this flag to print detailed allocation information as json data.
durati
Example Command:
1
./zbox get --allocation $ALLOC
Copied!
Here $ALLOC variable refers to the allocation id specified.
The response should contain information about blobbers allocated and stats for the allocation as mentioned below.
List all files in an Allocation
./zbox list-all command is used to list all the files stored with an allocation. Additional Parameters can be viewed using the ./zbox list-all --help command.Parameter
Required
Description
Valid Values
allocation
yes
allocation id
string
Command :
1
./zbox list-all --allocation $ALLOC
Copied!
Response :
Cancel Allocation
./zbox alloc-cancel immediately return all remaining tokens from challenge pool back to the allocation's owner and cancels the allocation. If blobbers already got some tokens, the tokens will not be returned. Remaining min lock payment to the blobber will be funded from the allocation's write pools.Note : Cancelling an allocation can only occur if the amount of failed challenges exceed a preset threshold.
Parameter
Required
Description
Valid Values
allocation
yes
allocation id
string
Command :
1
./zbox alloc-cancel --allocation $ALLOC
Copied!
Response :
1
Allocation canceled with txId : 62ff90a533d63023fcbc3244be9d0f6fd1f8c737fd24c9474dd24055cdb60e39
Copied!
Finalize Allocation
./zbox alloc-fini command is used to finalize an allocation after it is expired. An allocation becomes expired when the expiry time has passed followed by a period equal to the challenge completion period. Any remaining min lock payment to the blobber will be funded from the allocation's write pools. Any available money in the challenge pool returns to the allocation's owner.Note : An allocation can be finalized by the owner or one of the allocation blobbers.
Parameter
Required
Description
Valid Values
allocation
yes
allocation id
string
Command:
1
./zbox alloc-fini --allocation $ALLOC
Copied!
Get Wallet Information
Use the
getwalletcommand to get additional wallet information including Public Key, Client ID , Encryption Public Key required for Proxy Re-Encryption.Parameter
Required
Description
default
Valid values
json
no
print response in json format
false
boolean
Command
1
./zbox getwallet
Copied!
Response:
Get GoSDK and Zbox version
The version of Zbox and Gosdk can be fetched using the
./zbox version command.Command:
1
./zbox version
Copied!
Response:
List blobbers
Show active blobbers in dStorage .
Command
1
./zbox ls-blobbers
Copied!
Response usually outputs several blobbers and their specifications.
Sample Response:
Last modified 1mo ago
Copy link
Contents
Global Flags
Assigning Variables
Creating and Managing Allocations
List Allocations
Custom Allocation
Update Allocation
Add a curator
List Curators
Remove a curator
Transfer allocation ownership
Create an Immutable Allocation
Get Allocation Details
List all files in an Allocation
Cancel Allocation
Finalize Allocation
Get Wallet Information
Get GoSDK and Zbox version
List blobbers