Skip to main content

Settings

Beginner

Overview​

Each canister has a group of possible settings that control its behavior. Only a controller of the canister can read and modify its settings. Currently, there are seven canister setting fields:

  1. controllers: The list of controllers of the canister.
  2. compute_allocation: Amount of compute that this canister has allocated.
  3. memory_allocation: Amount of memory (storage) that this canister has allocated.
  4. freezing_threshold: A safety threshold to protect against canister deletion due to running out of cycles.
  5. reserved_cycles_limit: A safety threshold to protect against spending too many cycles for resource reservation.
  6. log_visibility: Controls who can read the canister logs.
  7. wasm_memory_limit: A safety threshold to protect against reaching the 4GiB hard limit of 32-bit Wasm memory.

Viewing a canister's current settings​

There are two ways to read the settings of a canister:

  1. Command line: dfx canister status <canister-id>. Note that this command returns canister settings together with other canister status information.
  2. Programmatically: Call the canister_status endpoint of the IC management canister. The canister settings will be in the settings field of the result.

Note that only a controller of the canister can read canister settings.

An example of using dfx in a command line:

> dfx canister status ajuq4-ruaaa-aaaaa-qaaga-cai
Canister status call result for ajuq4-ruaaa-aaaaa-qaaga-cai.
Controllers: bi7oa-57tth-fsnsf-6xrdb-rruo4-fsiws-xkedg-2uzrc-t6jas-7fo3c-jqe bnz7o-iuaaa-aaaaa-qaaaa-cai
Memory allocation: 0
Compute allocation: 0
Freezing threshold: 2_592_000
Reserved cycles limit: 5_000_000_000_000 Cycles
Wasm memory limit: 0 Bytes
...

An example of programmatically reading canister settings:

use ic_cdk::api::call::CallResult;
use ic_cdk::api::management_canister::main::{
    canister_status, CanisterIdRecord, DefiniteCanisterSettings,
};

#[ic_cdk::update]
async fn read_canister_settings() -> CallResult<DefiniteCanisterSettings> {
    let response = canister_status(CanisterIdRecord {
        canister_id: ic_cdk::id(),
    })
    .await?
    .0;
    println!("settings: {:?}", response.settings);
    Ok(response.settings)
}

Modifying settings​

There are two ways to modify the settings of a canister:

  1. Command line: dfx canister update-settings <canister-id> --<field-name> <field-value>.
  2. Programmatically: Call the update_settings endpoint of the IC management canister.

Note that only a controller of the canister can modify canister settings.

An example of using dfx in a command line:

> dfx canister update-settings ajuq4-ruaaa-aaaaa-qaaga-cai --wasm-memory-limit 3000000000
> dfx canister status ajuq4-ruaaa-aaaaa-qaaga-cai
...
Wasm memory limit: 3_000_000_000 Bytes
...

An example of programmatically modifying canister settings:

use ic_cdk::api::call::CallResult;
use ic_cdk::api::management_canister::main::{
    update_settings, CanisterSettings, UpdateSettingsArgument,
};
use candid::Nat;

#[ic_cdk::update]
async fn modify_canister_settings() -> CallResult<()> {
    update_settings(UpdateSettingsArgument{
        canister_id: ic_cdk::id(),
        settings: CanisterSettings {
            wasm_memory_limit: Some(Nat::from(3_000_000_000_u64)),
            // Other fields remain the same.
            .. CanisterSettings::default()
        }
    })
    .await
}