# Creating and Managing Allocations * [Global Flags](#global-flags) * [Assigning Variables](#assigning-variables) * [Creating and Managing Allocations](#creating-and-managing-allocations) * [List Allocations](#list-allocations) * [Custom Allocation](#custom-allocation) * [Update Allocation](#update-allocation) * [Forbid Options in Allocation](#forbid-options-in-allocation) * [Create an Immutable Allocation](#create-an-immutable-allocation) * [Get Allocation Details](#get-allocation-details) * [List all files in an Allocation](#list-all-files-in-an-allocation) * [Cancel Allocation](#cancel-allocation) * [Finalize Allocation](#finalize-allocation) * [Get Wallet Information](#get-wallet-information) * [Get GoSDK and Zbox Version](#get-gosdk-and-zbox-version) * [List Blobbers](#list-blobbers) * [List All Validators](#list-all-validators) * [Get Validator Configuration](#get-validator-configuration) * [Update Validator Settings](#update-validator-settings) * [Kill Blobber](#kill-blobber) * [Kill Validator](#kill-validator) *** ## 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 | | --fee float | Transaction fee for the given transaction(if unset, it will be set to blockchain min fee) | zbox\[command] --fee 0.5 | | -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 | (default false) Do not show interactive sdk logs (shown by default) | zbox \[command] --silent | | --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> | | --withNonce int | nonce that will be used in transaction (default is 0) | zbox \[command] --withNonce 1 | ## Assigning Variables We will use the following variables using the export command for easy demonstration of `zbox`functionalities. ``` export ALLOC = ``` ``` export AUTH = ``` ``` export lookuphash = ``` ``` export local= ``` ``` export remote= ``` ## 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](#creating-a-storage-allocation). Command: ``` ./zbox listallocations ``` Response: The response should contains the list of all your allocations with their specifications.(size, datashards, parityshards ,read price etc.) ``` ID | SIZE | EXPIRATION | DATASHARDS | PARITYSHARDS | FINALIZED | CANCELED | R PRICE | W PRICE +------------------------------------------------------------------+------------+-------------------------------+------------+--------------+-----------+----------+----------+----------+ 52fb9b5926c06e43a9290e9d7ad3217a4aee51c94684baf0fc174aa41abe6059 | 2147483648 | 2021-05-14 17:50:59 +0000 UTC | 2 | 2 | false | false | 0.04 | 0.04 637191e4cc5d78c5e8f3943b96a7de6509ec7cba28fd593d302a86b4c062a6ef | 115000000 | 2021-04-23 04:11:44 +0000 UTC | 3 | 3 | false | false | 0.06 | 0.0 ``` ### 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 ](#creating-a-storage-allocation)section first. Required parameters for creating a custom allocation can be viewed by using the command `./zbox newallocation --help` Here 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 : ``` ./zbox newallocation --data 3 --parity 3 --expire 200h --size 100000000 --lock 0.2 ``` Response: ![](/files/eLLMX2qL0N7WzgvhabeM) Verify the custom allocation by using the `./zbox listallocations`command Output: ``` ID | SIZE | EXPIRATION | DATASHARDS | PARITYSHARDS | FINALIZED | CANCELED | R PRICE | W PRICE +------------------------------------------------------------------+------------+-------------------------------+------------+--------------+-----------+----------+----------+----------+ 52fb9b5926c06e43a9290e9d7ad3217a4aee51c94684baf0fc174aa41abe6059 | 2147483648 | 2021-05-14 17:50:59 +0000 UTC | 2 | 2 | false | false | 0.04 | 0.04 637191e4cc5d78c5e8f3943b96a7de6509ec7cba28fd593d302a86b4c062a6ef | 100000000 | 2021-04-23 04:11:44 +0000 UTC | 3 | 3 | false | false | 0.06 | 0.06 ​ ``` Your custom allocation should be listed with specifications. ### Update Allocation `./zbox updateallocation`command 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 | | --forbid\_copy | | specify if the users cannot copy object from this allocation | | | --forbid\_update | | specify if the users cannot update objects in this allocation | | | --forbid\_delete | | specify if the users cannot delete objects from this allocation | | | --forbid\_move | | specify if the users cannot move objects from this allocation | | | --forbid\_rename | | specify if the users cannot rename objects in this allocation | | | --forbid\_upload | | specify if users cannot upload to this allocation | | `*` 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 ](#create-an-immutable-allocation). Example: Let's edit an already created allocation for size and expiry.\ \ Steps: 1. Get the allocation ID for updating the parameters using the [listallocations](#list-allocations) command 2\. Use the `updateallocation` command and provide the new size . ``` ./zbox updateallocation --allocation $ALLOC --size 15000000 ``` 3\. Now provide the new expiry time ``` ./zbox updateallocation --allocation $ALLOC --expiry 600h ``` Sample Response: ![](/files/KqOTHLkxpaO3jp8aIFYY) ### Forbid Options in Allocation There are various operations which you can forbid on an allocation. Forbid flag works with [update allocation ](#update-allocation)command. Check its working first.\ \ Here are the operations: | Parameter | Description | | ---------------- | --------------------------------------------------------------- | | --forbid\_copy | specify if the users cannot copy object from this allocation | | --forbid\_update | specify if the users cannot update objects in this allocation | | --forbid\_delete | specify if the users cannot delete objects from this allocation | | --forbid\_move | specify if the users cannot move objects from this allocation | | --forbid\_rename | specify if the users cannot rename objects in this allocation | | --forbid\_upload | specify if users cannot upload to this allocation | Here is a sample command for `--forbid_upload .`Other parameters can be done same way. ``` ./zbox updateallocation --allocation $ALLOC --forbid_upload ``` Sample Response :
To test functionality try [uploading file to allocation](/guides/zbox-cli/uploading-and-managing-files.md#uploading-a-file-to-dstorage). You should get the following response ``` Upload failed. this options for this file is not permitted for this allocation: file_option_not_permitted. ``` To Unforbid an operation after forbiding: Sample Command: ``` ./zbox updateallocation --allocation $ALLOC --forbid_upload false ``` ### **Add Blobber** Use `add_blobber` flag with [update allocation](https://github.com/0chain/zboxcli/tree/hm90121-patch-1#update-allocation) command to add blobber to allocation.The new blobber will be added as a parity blobber.For more details [check how a file is stored on blobbers](https://docs.zus.network/concepts/store). Here are the necessary parameters for adding blobber. | Parameter | Description | Valid Values | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------ | | --allocation | Provide Allocation ID for adding blobber to allocation | string | | --add\_blobber | Provide Blobber ID to add. Can be fetched using [List blobbers](https://github.com/0chain/zboxcli/tree/hm90121-patch-1#list-blobbers). | string | Sample Command: ``` ./zbox updateallocation --allocation $ALLOC --add_blobber 98f14362f075caf467653044cf046eb9e8a5dfee88dc8b78cad1891748245003 ``` Sample Response: ``` Allocation updated with txId : d853a82907453d37ed978b9fc1a55663be99bb351d18cca31068c0dc95566edd ``` **Note:** Files will automatically be uploaded,splitted, and stored on added blobber. **Note:** An allocation is already hosted on a set of blobbers. To find a blobber that is available to add you should exclude the current set of blobbers hosting your allocation by checking them via [Get Allocation Info](#get-allocation-details) command. ### Replace Blobber Sometimes, a blobber might be malfunctioning or faulty or the blobber might be slow because it is far from your geolocation, in such cases, you might have to replace the blobber with a new one. Use `add_blobber` and `remove_blobber` flag with [update allocation](https://github.com/0chain/zboxcli#update-allocation) command to replace a blobber hosting an allocation. | Parameter | Description | Valid Values | | ----------------- | --------------------------------------------------------------------------------------------------------------- | ------------ | | --allocation | Provide Allocation ID for replacing blobber | string | | --add\_blobber | Provide new Blobber ID . Can be fetched using [List blobbers](https://github.com/0chain/zboxcli#list-blobbers). | string | | --remove\_blobber | Provide ID for the blobber which has to remove | string | Sample Command: ``` ./zbox updateallocation --allocation $ALLOC --add_blobber 8d19a8fd7147279d1dfdadd7e3ceecaf91c63ad940dae78731e7a64b104441a6 --remove_blobber 06166f3dfd72a90cd0b51f4bd7520d4434552fc72880039b1ee1e8fe4b3cd7ea ``` Sample Response: ``` allocation updated successfully ``` **Note:** To find a blobber that can be replaced you should check the current set of blobbers hosting your allocation with [Get Allocation Info ](#get-allocation-details)command.
### Free Allocation `free_storage` is an additional parameter of `./zbox newallocation` command that allows you to create free allocations using json storage markers. Entities can give free `0chain` storage in the form of markers. A typical json free storage marker file looks similar to this ``` { "assigner": "my_corporation", "recipient": "f174cdda7e24aeac0288afc2e8d8b20eda06b18333efd447725581dc80552977", "free_tokens": 2.1, "timestamp": 2000000, "signature": "9edb86c8710d5e3ee4fde247c638fd6b81af67e7bb3f9d60700aec8e310c1f06" } ``` Here: * `assigner` Name of the entity providing the free storage. * `recipient` : This contains the wallet id of the recipient who is provided free storage * `free_tokens` The maximum amount of free tokens available for creating an allocation. When creating a new allocation the free tokens will be split between the allocation's write pool, and a new read pool; the ratio of this split configured on the blockchain. * `timestamp` A unique timestamp. Used to prevent multiple applications of the same marker. * `signature` Signed by the assigner, validated using the stored public key on the blockchain. \ \ **Note: To understand how free storage is assigned check** [**free storage assigner**](#free-storage-assigner.) **command.** \ Syntax ``` ./zbox newallocation --free_storage {path/to/marker_json_file} ``` Sample Command ``` ./zbox newallocation --free_storage markers/marker.json ``` Response: ``` Allocation created: cb3a1efafa3e374718e51710d4ccfabd2f242b8e53cc2960e142d67164f1ea0c ``` ### Free storage assigner `./zbox add` command provide permission to chain applications to generate free allocation. Parameters:
FlagsDescriptionRequired
--keyThe wallet public key for signing free storage markers. This is the public key of wallet of the chain owner .yes
--limitDefines the maximum number of tokens that can be used to generate a free allocation (default is 1)yes
--maxTotal number of tokens free allocations can utilize (default is 1)yes
--nameAccount name that will be assigning free storage.yes
\ To demonstrate lets provide permission to [0box ](https://github.com/0chain/0box)to generate free allocation. ``` ./zbox add --name 0chain --limit 2.1 --max 3000 --key $CHAIN_OWNER_WALLET_PUBLIC_KEY ``` Here * The `./zbox add` command should be called from chain wallet owner only. * 0chain is the account name that will be assigning free storage. You can provide your chain/account name for better understanding . * 2.1 is the maximum amount of ZCN tokens that can be used by 0box to create each allocation * 3000 is the total number of ZCN tokens that are usable by 0box for creating allocations. * key is the public key of the wallet of chain owner . * Make sure `freestorage.public_key` and `name`variable in `0box.yaml` located inside (0box/docker.local/config) directory is similar to public key and account name of chain wallet owner. Sample Successful Response: ``` 0chain added as free storage assigner ``` ### 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 `updateallocation` command. ``` ./zbox updateallocation --set_immutable true --allocation $ALLOC ``` Response : ``` Allocation updated with txId : 1aef0e669af8b96d7240c3594643cca2b47a5a463d4381a5448168e15461f58e ``` You can check whether the allocation has become immutable by uploading a file to the allocation. It should deny access with the following error ``` [ERROR] 2021/09/25 01:53:41.310951 chunked_upload_blobber.go:75: http://0.fra.zcn.zeroservices.eu:5054 Upload error response: 400{"code":"immutable_allocation","error":"immutable_allocation: Cannot write to an immutable allocation"} ​ ``` ### Get Allocation Details `./zbox getallocation` 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: ``` ./zbox getallocation --allocation $ALLOC ``` 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.

Get Allocation

### 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 : ``` ./zbox list-all --allocation $ALLOC ``` Response : ![](/files/PWvQcEiMjA0t9kiYSgfl) ### 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 : ``` ./zbox alloc-cancel --allocation $ALLOC ``` Response : ``` Allocation canceled with txId : 62ff90a533d63023fcbc3244be9d0f6fd1f8c737fd24c9474dd24055cdb60e39 ``` ### 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: ``` ./zbox alloc-fini --allocation $ALLOC ``` ### Get Wallet Information Use the `getwallet`command 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 ``` ./zbox getwallet ``` Response: ![](/files/eSekE1LCweWhZkLOFBZZ) ### Get GoSDK and Zbox version The version of Zbox and Gosdk can be fetched using the `./zbox version` command. Command: ``` ./zbox version ``` Response: ![](/files/XVtx2vg90BFFMDYwnAI6) ### List blobbers Show active blobbers in dStorage .‌ Command ``` ./zbox ls-blobbers ``` Response usually outputs several blobbers and their specifications. Sample Response: ![](/files/q75kfQj2gNzfTmvlBZ2z) ### List All Validators List all active validators on the network Command: ``` ./zbox ls-validators ``` Response :
Formatted Shortened Response: ``` id: b9f4f244e2e483548795e42dad0c5b5bb8f5c25d70cadeafc202ce6011b7ff8c url: https://demo.zus.network/validator03/ settings: delegate_wallet: 9c693cb14f29917968d6e8c909ebbea3425b4c1bc64b6732cadc2a1869f49be9 min_stake: 1.000 ZCN max_stake: 100.000 ZCN num_delegates: 50 service_charge: 30 % id: c025fad27d3daa6fbe6a10ef38f1075dc5a6386760951816ece953391ff9804b url: https://demo.zus.network/validator02/ settings: delegate_wallet: 9c693cb14f29917968d6e8c909ebbea3425b4c1bc64b6732cadc2a1869f49be9 min_stake: 1.000 ZCN max_stake: 100.000 ZCN num_delegates: 50 service_charge: 30 % ``` ### Get Validator Configuration `./zbox validator-info` command is used to get a particular validator configuration . Here are the parameters for the command . | Parameter | Required | Description | | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | --validator\_id | Yes | Find validator id through [List All Validators](#list-all-validators) command. This will list all the validators on the network | | --json | Optional | Print response as json data | | --help | | Provide information about the command | \ Sample Command : 
./zbox validator-info --validator_id $VALIDATOR_ID
Sample Response :
### Update Validator Settings Use `./zbox validator-update` to update a validator's configuration settings. | Parameter | Required | Description | default | Valid values | | --------------- | -------- | ------------------------------------------- | ------- | ------------ | | validator\_id | yes | id of validator of which to update settings | | string | | num\_delegates | no | update maximum number of delegates | | int | | max\_stake | no | update maximum stake | | float | | min\_stake | no | update minimum stake | | float | | service\_charge | no | update service charge | | float | Sample Command: **Update validator max stake** ``` ./zbox validator-update --validator_id f82ab34a98406b8757f11513361752bab9cb679a5cb130b81a4e86cec50eefc3 --max_stake 7.5 ``` ### Kill Blobber `./zbox kill-blobber` command deactivates a blobber to avoid storage of data .Required parameters are
ParameterRequiredDescription
--idyesBlobber Id to deactivate a specific blobber ,can be retrieved using List blobbers command.
--h, --helpnoHelp will list all the parameters related to the command.
Sample Command : ``` ./zbox kill-blobber --id $BLOBBER_ID --wallet $CHAIN_OWNER_WALLET ``` **Note :** Kill Blobber command should be evoked from chain owner wallet only Sample Response : ``` killed blobber $BLOBBER_ID ``` ### Kill Validator `./zbox kill-validator` command deactivates a specific validator available on the network. Required parameters are : | Parameter | Required | Description | | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | --id | yes | Validator ID of a specific validator to deactivate.Validator ID can be retrieved using [List Validators](https://docs.zus.network/guides/zbox-cli/creating-and-managing-allocations#list-all-validators) command. | | --h,--help | no | Help will list all the parameters related to the command. | Sample Command ``` ./zbox kill-validator --id $VALIDATOR_ID --wallet $CHAIN_OWNER_WALLET ``` **Note :** Kill Validator command should be evoked from chain owner wallet only Sample Response : ``` killed validator, id: $VALIDATOR_ID ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs-old.zus.network/guides/zbox-cli/creating-and-managing-allocations.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.