docs: Canister settings guide

[marc0olo]

Summary

• Complete reference for all canister settings: controllers, compute allocation, memory allocation, freezing threshold, reserved cycles limit, Wasm memory limit/threshold, log visibility, log memory limit, snapshot visibility, environment variables
• Each setting includes type, default value, icp.yaml key, and yaml/CLI examples
• Covers three layers: icp.yaml configuration, direct CLI updates (icp canister settings update), and programmatic updates via the management canister (Motoko and Rust)
• Documents common controller models (developer, multi-sig, DAO-governed, immutable)
• Note on snapshot_visibility: Available via management canister calls; icp-cli/icp.yaml support not yet implemented (will be picked up on icp-cli bump)
• wasm_memory_limit default: 3 GiB (3,221,225,472 bytes) per cdk-rs

Sync recommendation

informed by dfinity/portal — docs/building-apps/canister-management/settings.mdx, docs/building-apps/canister-management/control.mdx, docs/references/_attachments/ic.did (snapshot_visibility field); dfinity/icp-cli — docs/reference/canister-settings.md, docs/reference/cli.md; dfinity/icskills — skills/cycles-management/SKILL.md

[marc0olo]

Review: Canister settings guide

Must fix

• Motoko CanisterSettings type is incomplete (lines 326-331): Only 4 fields shown (controllers, compute_allocation, memory_allocation, freezing_threshold), but the actual canister_settings type in ic.did has 9 fields (also reserved_cycles_limit, log_visibility, wasm_memory_limit, wasm_memory_threshold, environment_variables). This could mislead readers into thinking only 4 settings exist. Either include all fields (with null values) or explicitly note that additional fields are omitted.
• wasm_memory_limit default value is likely outdated (line 140): Page says "Default: 0 (no limit)". However, the CDK source (ic-management-canister-types/src/lib.rs) now documents the default as 3_221_225_472 (3 GiB). The page should either update the default to 3 GiB or add a verification flag: <!-- Needs human verification: wasm_memory_limit default may now be 3 GiB per CDK docs -->.
• log_memory_limit is not a management canister setting (lines 198-212): Presented alongside management canister settings, but it is absent from ic.did and the Rust CDK's CanisterSettings struct. It exists only in the icp-cli configuration layer (confirmed in .sources/icp-cli/docs/reference/canister-settings.md). The page should clarify that log_memory_limit is an icp-cli/icp.yaml-only setting, not a setting exposed by the management canister's update_settings endpoint.

Suggestions

• Content brief asks for "canister metadata (name, description, git commit for dashboard visibility)" but the page does not cover this. If metadata uses a different mechanism (icp canister metadata rather than icp canister settings), a note or link to where metadata is covered would address the brief.
• Launchtrail control model from portal is omitted: The portal's control.mdx describes a "Launchtrail" model (scheduling upgrades with public review). The page covers Developer/Team, Multi-sig, DAO, and Immutable but skips Launchtrail. Worth considering.
• -e production vs -e ic: Line 306-309 says "For mainnet canisters, add -e production" but earlier examples use -e ic. Using -e production implies the user has configured an environment named "production" in icp.yaml. Consider a brief note or consistently use -e ic.
• Missing CLI flags from the icp canister settings update section (lines 286-304): --reserved-cycles-limit, --wasm-memory-threshold, --log-memory-limit all exist in the CLI reference but aren't shown. Since the page shows a "Multiple settings at once" example, noting that additional flags are available would be helpful.
• Consider documenting --add-log-viewer/--remove-log-viewer/--set-log-viewer alongside log_visibility — the CLI reference shows these flags for managing allowed_viewers via CLI, but the page only shows YAML-based configuration.
• Motoko/Rust example inconsistency: Rust example includes environment_variables: None but Motoko example does not have environment variables at all.

Verified

• Frontmatter complete and consistent (title, description, sidebar order)
• No dfx references anywhere
• .mdx with proper import for Tabs/TabItem and JSX comment syntax
• Tab order correct (Motoko first, then Rust), syncKey="lang" used
• CLI commands verified against .sources/icp-cli/docs/reference/cli.md: icp canister settings show, icp canister settings update, icp canister settings sync, --add-controller, --remove-controller, --set-controller, --compute-allocation, --freezing-threshold, --wasm-memory-limit, --log-visibility all confirmed
• All internal links resolve: cycles-management.md, ../../reference/cycles-costs.md, ../../reference/management-canister.md, ../governance/launching.md
• External links match linking rules (https://cli.internetcomputer.org/, https://github.com/dfinity/threshold)
• Rust update_settings from ic_cdk::management_canister matches CDK source exactly (all 9 fields in Rust example)
• Upstream comment present in correct {/* */} format listing portal, icp-cli, and icskills
• Controllers section accurate: 10-controller maximum, blackholing, caution admonition
• Freezing threshold: 2,592,000 seconds (~30 days) default, frozen canister behavior correct
• Reserved cycles limit: 750 GiB threshold, 5T default correct
• Build passes
• Diataxis how-to pattern followed
• Code examples under 30 lines each
• Uses core not base for Motoko imports

[marc0olo]

icp-cli was bumped to v0.2.3. The following content on this PR may be outdated:

1. icp canister settings show behavior change. The command was rewritten (#499): it now calls canister_status directly and requires the caller to be a controller — it errors instead of falling back to the public state tree. The PR uses this command without mentioning the controller requirement. A note like "You must be a controller of the canister to run this command" should be added to the Viewing settings section.

2. New features worth noting (optional). icp deploy now accepts install args (--arg, --arg-file) and there is a new --proxy flag for routing canister calls through a proxy canister. These are out of scope for the settings guide but may be relevant to a future deployment guide.

Please review before merging.

[marc0olo]

portal was bumped to e636b0a and ic.did was updated. A new canister setting was added that this PR needs to document:

snapshot_visibility — controls who can list and read canister snapshots. Same structure as log_visibility:

Variant	Meaning
controllers (default)	Only controllers can access snapshots
public	Anyone can list and read snapshots
allowed_viewers	Specific principals (same pattern as log_visibility)

Add a ### Snapshot visibility section modelled on the existing ### Log visibility section, including the icp.yaml configuration examples. The new setting lives in canister_settings (optional) and definite_canister_settings (required) in the management canister interface.

Please review before merging.

[marc0olo]

Correction to my previous comment: The canister settings show behavior change (requiring controller access, erroring for non-controllers) is in the icp-cli development branch after the v0.2.3 release — it has not shipped yet. Please ignore that item. The v0.2.3 behavior is: falls back to public state tree data for non-controllers. Document the current released behavior.

The snapshot_visibility setting note still stands — that is an IC protocol change reflected in ic.did, independent of the icp-cli release.

[marc0olo]

Feedback addressed:

• Updated Motoko CanisterSettings example to show all fields from ic.did (now 10 fields including snapshot_visibility, reserved_cycles_limit, log_visibility, wasm_memory_threshold, environment_variables)
• Added verification flag on wasm_memory_limit default value (may be 3 GiB per CDK docs rather than 0)
• Added verification flag on log_memory_limit status (present in icp-cli but absent from ic.did)
• Added ### Snapshot visibility section for new snapshot_visibility setting (portal bump) — documents controllers and public variants with icp.yaml example
• Updated Rust update_settings example to include snapshot_visibility: None
• Fixed -e production inconsistency: now reads -e <env> with a note that ic or production are common names, and the example uses ic
• Added note about additional CLI flags available (--reserved-cycles-limit, --wasm-memory-threshold, --log-memory-limit, --add-environment-variable)
• Updated <!-- Upstream: --> comment to explicitly reference ic.did as the source for snapshot_visibility

[marc0olo]

Review complete. All findings addressed in commit e5cdce7:

Fixed:

• snapshot_visibility icp.yaml key and yaml example removed — icp-cli/icp.yaml support is not yet implemented. Section now states this clearly and points to the programmatic management canister approach. Will be updated on the next icp-cli bump.
• Rust CanisterSettings: removed non-existent snapshot_visibility field (would fail to compile)
• Motoko snapshot_visibility type: added missing #allowed_viewers : [Principal] variant to match ic.did (three variants, not two)
• Motoko environment_variables type: ?[(Text, Text)] → ?[{name : Text; value : Text}] to match the management canister's Candid record type
• wasm_memory_limit default: 0 (no limit) → 3_221_225_472 (3 GiB) per cdk-rs source; resolved and removed the verification comment
• Freezing threshold description: added that survival estimate includes memory usage and subnet storage cost, not just execution rate

Verified:

• All internal links resolve; CLI flags verified against .sources/icp-cli/; Rust API verified against .sources/cdk-rs/; ic.did consulted for management canister types; build passes