From a075b5e10165239e471350cdbd6803b24e041a3d Mon Sep 17 00:00:00 2001 From: Jessie Mongeon Date: Mon, 26 Feb 2024 16:08:51 -0600 Subject: [PATCH 1/4] Update ic-admin page --- docs/developer-docs/setup/ic-admin.md | 280 ++++++++++++++++++++++++-- 1 file changed, 261 insertions(+), 19 deletions(-) diff --git a/docs/developer-docs/setup/ic-admin.md b/docs/developer-docs/setup/ic-admin.md index a5a8a23c49..7cb61e7ef9 100644 --- a/docs/developer-docs/setup/ic-admin.md +++ b/docs/developer-docs/setup/ic-admin.md @@ -1,37 +1,279 @@ -# IC Admin +# IC-admin -`ic-admin` is a tool used to create and submit NNS proposals. +`ic-admin` is a tool used to view current network information, such as subnet and node info. It can also be used to create and submit NNS proposals. -## Installing +## Installing `ic-admin` -### MacOS +To install `ic-admin`, first determine the commit ID of the latest IC release. This commit can be found in [the DFINITY/ic repo](https://github.com/dfinity/ic/releases/latest). -1. Retrieve the file +For example, the latest commit at this time is `85bd56a70e55b2cea75cae6405ae11243e5fdad8`. + +Then, download the `ic-admin` file for your operating system. For macOS, download the `darwin` file; for Linux, download the `linux` file: + +#### macOS ```bash -$ curl "https://download.dfinity.systems/ic/7445081734e6d896d090295967d50710975c4f25/openssl-static-binaries/x86_64-darwin/ic-admin.gz" -o - | gunzip > ./ic-admin -$ chmod +x ./ic-admin +curl "https://github.com/dfinity/ic/releases/download/release-2024-02-21_23-01-p2p/ic-admin-x86_64-darwin.gz" -o - | gunzip > ./ic-admin +chmod +x ./ic-admin ``` -2. Verify the binary +#### Linux ```bash -$ diff <(shasum -a 256 ./ic-admin | cut -d' ' -f1) <(echo 3f75026d2f28f171068e332a42c82a2795c93fbf5ab351baef30b30eb901cdba) && echo "ic-admin checksum matches" || echo "***ERROR***: ic-admin checksum does not match" +curl "https://github.com/dfinity/ic/releases/download/release-2024-02-21_23-01-p2p/ic-admin-x86_64-linux.gz" -o - | gunzip > ./ic-admin +chmod +x ./ic-admin ``` -### Linux +## Using `ic-admin` -NOTE: The instructions below have been tested with the Ubuntu 20.04 release. +### View network info -1. Retrieve the file +To view detailed information about the network's current topology, use the command: -```bash -$ curl "https://download.dfinity.systems/ic/7445081734e6d896d090295967d50710975c4f25/openssl-static-binaries/x86_64-linux/ic-admin.gz" -o - | gunzip > ./ic-admin -$ chmod +x ./ic-admin +``` +./ic-admin --nns-urls https://ic0.app get-topology ``` -2. Verify the binary +This will return output about current subnets and nodes, such as: -```bash -$ diff <(shasum -a 256 ./ic-admin | cut -d' ' -f1) <(echo e29bb9cc462e800b8b960ad49c412e5f5fdbb5ae2ae9fde0c13058422ba32802) && echo "ic-admin checksum matches" || echo "***ERROR***: ic-admin checksum does not match" -``` \ No newline at end of file +``` +... +///Info on a subnet: +"bkfrj-6k62g-dycql-7h53p-atvkj-zg4to-gaogh-netha-ptybj-ntsgw-rqe": +{ + "version": 41127, + "records": [ + { + "key": "subnet_record_bkfrj-6k62g-dycql-7h53p-atvkj-zg4to-gaogh-netha-ptybj-ntsgw-rqe", + "version": 41127, + "value": { + "membership": [ + "kwgrq-dixu3-iztnh-3nucy-zfo73-lstek-xtehy-4lywo-ojb3n-7wbdl-dqe", + "xzpf4-zeihc-upncx-zz65w-rep5j-xh2sy-yw6bg-qtgwu-5z3ez-er2gz-sae", + "popmv-gccw7-zincv-gtcgo-jxfby-ar7zq-odvna-4jcs2-cnovy-qiha6-yae", + "w3phu-4ihah-tqdl6-n32hp-e5254-l6ybu-kvmmx-thj6t-q7z7k-swvi4-iqe", + "a3xcb-ezfy5-yib3b-5bo75-5nok4-kaolh-a6akg-ilxck-qdbph-pwppb-dae", + "foa3b-mjkuu-3qlgu-6o64i-2omzt-x6suc-5gzcq-6j2gz-bftru-j5idg-gae", + "dzol4-3eqco-5b5ag-ritui-tyl7u-i3iwz-ex2qo-cbfjx-5fmxw-yfgwo-tqe", + "7exbb-k4tu4-mw24y-3zylh-bopa5-fwdsc-f4a3z-45hh4-twpin-4zv4a-yae", + "3yok3-yvswm-l4ior-bjh62-fsi73-vfqp3-77wji-coglq-l2bjw-rxrph-uqe", + "ldqxr-qdliy-howvj-2tamr-3fwul-liakv-7523k-tmhrz-5geyk-jlu7b-uae", + "c2dnc-3ozfd-ew52a-yvmrc-mjyss-edoch-k7cki-f7vzk-zqapg-aw44i-mqe", + "lzjli-4do6u-xcbtx-co7r7-35gzq-5mmqw-k4jb3-3s63m-facun-6riew-lae", + "lj6xb-t5tcb-dol3s-ay52b-dulse-zyezk-25qyv-l7yqj-4zrc2-hp5qz-sae" + ], + "max_ingress_bytes_per_message": 2097152, + "max_ingress_messages_per_block": 1000, + "max_block_payload_size": 4194304, + "unit_delay_millis": 1000, + "initial_notary_delay_millis": 600, + "replica_version_id": "3e25df8f16f794bc93caaefdce41467304d1b0c7", + "dkg_interval_length": 499, + "gossip_config": { + "max_artifact_streams_per_peer": 20, + "max_chunk_wait_ms": 15000, + "max_duplicity": 1, + "max_chunk_size": 4096, + "receive_check_cache_size": 5000, + "pfn_evaluation_period_ms": 1000, + "registry_poll_period_ms": 3000, + "retransmission_request_ms": 60000 + }, + "start_as_nns": false, + "subnet_type": "application", + "max_instructions_per_message": 20000000000, + "max_instructions_per_round": 7000000000, + "max_instructions_per_install_code": 200000000000, + "features": { + "canister_sandboxing": false, + "http_requests": true, + "bitcoin": null, + "sev_status": null + }, + "max_number_of_canisters": 0, + "ssh_readonly_access": [], + "ssh_backup_access": [], + "ecdsa_config": null + } + } + ] +} +... +/// Info on node IDs and their operator IDs: +{ + "node_id": "kqtlh-qojsl-k4xyd-baow4-ihgyb-y47y7-nvrhv-k35k3-432ti-l4ci6-tae", + "node_operator_id": "mpmyf-juliu-5qwcu-ofamg-es7ug-4mjt4-w5lht-dbrfb-ualjm-hcwmn-pae" + }, + { + "node_id": "kqurf-2p6ca-j4zte-3wkx5-rovid-kgn7s-yih6m-mj74k-claji-7uoje-vae", + "node_operator_id": "5mhxl-exk6r-cvm3q-ose77-qojd2-dybc4-hvrdj-5dnr6-ylvg7-wtn23-2qe" + }, + { + "node_id": "kr7kb-gysmk-v4sym-effou-xcfto-y5ztu-ntc3l-6vmf6-s2xvk-kluxb-zae", + "node_operator_id": "vkwql-433e7-au6b7-v5g7z-tduiu-no4od-6wb4c-z5zru-vzssq-zwspo-dqe" + }, + { + "node_id": "krwx5-u5srm-kqbyx-szogs-gaseq-qzef4-txjmy-ql5em-k6q5n-h3ono-bae", + "node_operator_id": "dpt4y-mkhk4-7gchc-yx2by-hzfe6-czv2t-xebyb-as4q3-gkspj-ivvsv-hae" + }, + { + "node_id": "kv4yb-otkiz-ilqle-wk3b3-upqjh-hvkhv-wmbqq-ca4qq-5va4r-matmt-oqe", + "node_operator_id": "wmrev-cdq34-iqwdm-oeaak-f6kch-s4axw-ojbhe-yuolf-bazh4-rjdty-oae" + }, + { + "node_id": "kvj4i-xw67n-f673e-7unem-npgcc-ag7ya-f46sk-g7qq6-ep6l4-brrkt-tqe", + "node_operator_id": "3nu7r-l6i5c-jlmhi-fmmhm-4wcw4-ndlwb-yovrx-o3wxh-suzew-hvbbo-7qe" + }, + { + "node_id": "kwict-ujiu6-u4ss3-nlwqq-dchsd-2h5lh-nzkke-24ij3-3otqq-rswre-vqe", + "node_operator_id": "sjstt-kr4xo-ikp7w-uyhck-mbgjx-h6y7c-ay3a2-ffkdb-qe46z-hsji4-mqe" + }, + { + "node_id": "kwryq-ezysk-c4ono-aet7a-hh6h5-4o3bb-a33et-ef4g5-42tot-zaek6-fae", + "node_operator_id": "ymenq-4sr5h-3imm6-kjjw6-2knuy-ntmlu-oqf5k-vdnzv-z427q-gqdot-sae" + }, +... +``` + +### View specific subnet info + +To view information on a specific subnet, use the command: + +``` +./ic-admin --nns-url=https://ic0.app get-subnet +``` + +This command will return output such as: + +``` +{ + "version": 41127, + "records": [ + { + "key": "subnet_record_bkfrj-6k62g-dycql-7h53p-atvkj-zg4to-gaogh-netha-ptybj-ntsgw-rqe", + "version": 41127, + "value": { + "membership": [ + "kwgrq-dixu3-iztnh-3nucy-zfo73-lstek-xtehy-4lywo-ojb3n-7wbdl-dqe", + "xzpf4-zeihc-upncx-zz65w-rep5j-xh2sy-yw6bg-qtgwu-5z3ez-er2gz-sae", + "popmv-gccw7-zincv-gtcgo-jxfby-ar7zq-odvna-4jcs2-cnovy-qiha6-yae", + "w3phu-4ihah-tqdl6-n32hp-e5254-l6ybu-kvmmx-thj6t-q7z7k-swvi4-iqe", + "a3xcb-ezfy5-yib3b-5bo75-5nok4-kaolh-a6akg-ilxck-qdbph-pwppb-dae", + "foa3b-mjkuu-3qlgu-6o64i-2omzt-x6suc-5gzcq-6j2gz-bftru-j5idg-gae", + "dzol4-3eqco-5b5ag-ritui-tyl7u-i3iwz-ex2qo-cbfjx-5fmxw-yfgwo-tqe", + "7exbb-k4tu4-mw24y-3zylh-bopa5-fwdsc-f4a3z-45hh4-twpin-4zv4a-yae", + "3yok3-yvswm-l4ior-bjh62-fsi73-vfqp3-77wji-coglq-l2bjw-rxrph-uqe", + "ldqxr-qdliy-howvj-2tamr-3fwul-liakv-7523k-tmhrz-5geyk-jlu7b-uae", + "c2dnc-3ozfd-ew52a-yvmrc-mjyss-edoch-k7cki-f7vzk-zqapg-aw44i-mqe", + "lzjli-4do6u-xcbtx-co7r7-35gzq-5mmqw-k4jb3-3s63m-facun-6riew-lae", + "lj6xb-t5tcb-dol3s-ay52b-dulse-zyezk-25qyv-l7yqj-4zrc2-hp5qz-sae" + ], + "max_ingress_bytes_per_message": 2097152, + "max_ingress_messages_per_block": 1000, + "max_block_payload_size": 4194304, + "unit_delay_millis": 1000, + "initial_notary_delay_millis": 600, + "replica_version_id": "3e25df8f16f794bc93caaefdce41467304d1b0c7", + "dkg_interval_length": 499, + "gossip_config": { + "max_artifact_streams_per_peer": 20, + "max_chunk_wait_ms": 15000, + "max_duplicity": 1, + "max_chunk_size": 4096, + "receive_check_cache_size": 5000, + "pfn_evaluation_period_ms": 1000, + "registry_poll_period_ms": 3000, + "retransmission_request_ms": 60000 + }, + "start_as_nns": false, + "subnet_type": "application", + "max_instructions_per_message": 20000000000, + "max_instructions_per_round": 7000000000, + "max_instructions_per_install_code": 200000000000, + "features": { + "canister_sandboxing": false, + "http_requests": true, + "bitcoin": null, + "sev_status": null + }, + "max_number_of_canisters": 0, + "ssh_readonly_access": [], + "ssh_backup_access": [], + "ecdsa_config": null + } + } + ] +} +``` + +### View unassigned nodes + +To get a list of nodes that are currently unassigned, use the command: + +``` +./ic-admin --nns-url https://ic0.app get-unassigned-nodes +``` + +This will return output such as: + +``` +Fetching the most recent value for key: "unassigned_nodes_config" +Most recent version is 41097. Value: +UnassignedNodesConfigRecord { ssh_readonly_access: [], replica_version: "5c60feaf3d64a745b9a44aa61d44b91d6921541b" } +``` + +### Create a proposal to remove a node + +To create an NNS proposal to remove a node from the network, use the command: + +``` +./ic-admin \ + --nns-url https://ic0.app/ \ + propose-to-remove-node-operators +``` + +### Submit proposals to the local network + +To create and submit a proposal to your local network rather than the mainnet, use the `nns-url` value of `http://localhost:8080` rather than `https://ic0.app/`. For example, this proposal sets an application subnet as authorized on the local network: + +``` +./ic-admin \ + --nns-url http://localhost:8080 propose-to-set-authorized-subnetworks \ + --test-neuron-proposer \ + --proposal-title "Set authorized subnets" \ + --proposal-url "https://forum.dfinity.org" \ + --summary "This proposal sets the application subnet as authorized" \ + --subnets "${APP_SUB}" +``` + +Replace `APP_SUB` with the principal ID of the local subnet without the prefix added by `ic-regedit`. To get this info, use the `ic-regedit` command: + +``` +./ic-regedit snapshot ~/.local/share/dfx/network/local/state/replicated_state/ic_registry_local_store | jq -r .nns_subnet_id.principal_id.raw +``` + +:::caution +This workflow is supported in `dfx` v0.15.3. +::: + +### Get node info + +To get detailed information on a specific node, use the command: + +``` +./ic-admin --nns-url https://ic0.app get-node +``` + +Replace `NODE_ID` with the node's principal ID. This command will return output such as: + +``` +Fetching the most recent value for key: "node_record_ebih2-65fto-thxfj-knxfn-xxdmq-z42dj-oty4c-n3fbj-qry6f-g3oe2-nqe" +Most recent version is 41233. Value: +NodeRecord { xnet: Some(ConnectionEndpoint { ip_addr: "2400:a240:0:2:6801:63ff:fe71:6299", port: 2497, protocol: Unspecified }), http: Some(ConnectionEndpoint { ip_addr: "2400:a240:0:2:6801:63ff:fe71:6299", port: 8080, protocol: Unspecified }), p2p_flow_endpoints: [], prometheus_metrics_http: None, public_api: [], private_api: [], prometheus_metrics: [], xnet_api: [], node_operator_id: [29, 176, 153, 226, 186, 19, 197, 234, 173, 3, 118, 16, 214, 109, 168, 0, 32, 75, 232, 171, 67, 238, 42, 223, 204, 191, 230, 205, 2], chip_id: [] } +``` + +### Using `ic-admin` as a node provider + +To learn how to use `ic-admin` as a node provider, check out [the Node Provider onboarding wiki page](https://wiki.internetcomputer.org/wiki/Node_Provider_Onboarding). + +Examples of node provider proposals include proposals to add your node provider to the network, register your data center, and create a ndoe operator record. \ No newline at end of file From bfc80d185571281bc09e2ec172a6c357e1e0e1c3 Mon Sep 17 00:00:00 2001 From: Jessie Mongeon Date: Mon, 26 Feb 2024 16:11:17 -0600 Subject: [PATCH 2/4] Update ic-admin page --- .../cli-tools/ic-admin.mdx} | 0 docs/developer-docs/setup/_category_.yml | 9 --------- plugins/utils/redirects.js | 1 + sidebars.js | 1 + 4 files changed, 2 insertions(+), 9 deletions(-) rename docs/developer-docs/{setup/ic-admin.md => developer-tools/cli-tools/ic-admin.mdx} (100%) delete mode 100644 docs/developer-docs/setup/_category_.yml diff --git a/docs/developer-docs/setup/ic-admin.md b/docs/developer-docs/developer-tools/cli-tools/ic-admin.mdx similarity index 100% rename from docs/developer-docs/setup/ic-admin.md rename to docs/developer-docs/developer-tools/cli-tools/ic-admin.mdx diff --git a/docs/developer-docs/setup/_category_.yml b/docs/developer-docs/setup/_category_.yml deleted file mode 100644 index 2ca6064ee9..0000000000 --- a/docs/developer-docs/setup/_category_.yml +++ /dev/null @@ -1,9 +0,0 @@ -label: 'Getting started' -position: 2 -collapsible: true # make the category collapsible -collapsed: true # keep the category open by default -# link: -# type: doc -# id: index -customProps: - description: This description can be used in the swizzled DocCard \ No newline at end of file diff --git a/plugins/utils/redirects.js b/plugins/utils/redirects.js index 7aea9389c6..18124aa743 100644 --- a/plugins/utils/redirects.js +++ b/plugins/utils/redirects.js @@ -356,6 +356,7 @@ const redirects = ` /docs/current/developer-docs/frontend/index /docs/current/developer-docs/web-apps/application-frontends/overview /docs/current/developer-docs/integrations/bitcoin/ckBTC-reference /docs/current/developer-docs/integrations/bitcoin/ckbtc-reference /docs/current/tutorials/developer-journey/level-4/4.3-ckBTC-and-bitcoin /docs/current/tutorials/developer-journey/level-4/4.3-ckbtc-and-bitcoin + /docs/current/developer-docs/setup/ic-admin /docs/current/developer-docs/developer-tools/cli-tools/ic-admin ` .split(/[\r\n]+/) .map((line) => line.trim().replace(/^#.*$/, "").trim()) diff --git a/sidebars.js b/sidebars.js index 06e3fa3b7d..0aa42a7fa8 100644 --- a/sidebars.js +++ b/sidebars.js @@ -391,6 +391,7 @@ const sidebars = { "developer-docs/developer-tools/cli-tools/quill-cli-reference/quill-update-node-provider", ], }, + "developer-docs/developer-tools/cli-tools/ic-admin", ], }, { From 0ca8778fb86a4cd8693a1c05f00378490bd2fae9 Mon Sep 17 00:00:00 2001 From: Jessie Mongeon Date: Tue, 27 Feb 2024 08:23:43 -0600 Subject: [PATCH 3/4] Update ic-admin page --- .../integrations/sns/launching/launch-steps-1proposal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/integrations/sns/launching/launch-steps-1proposal.md b/docs/developer-docs/integrations/sns/launching/launch-steps-1proposal.md index de0e9118af..7133adcd85 100644 --- a/docs/developer-docs/integrations/sns/launching/launch-steps-1proposal.md +++ b/docs/developer-docs/integrations/sns/launching/launch-steps-1proposal.md @@ -13,7 +13,7 @@ through the same, with the difference that the commands here target the canister - [x] Install the IC SDK. See: [installing the IC SDK](/docs/current/developer-docs/getting-started/install). -- [x] Install `ic-admin`. See: [installing the `ic-admin`](../../../setup/ic-admin.md). +- [x] Install `ic-admin`. See: [installing the `ic-admin`](/docs/current/developer-docs/developer-tools/cli-tools/ic-admin). - [x] Install `sns` CLI. From 8b8934c71e6db04c022833ed6f010d23d4cb89c2 Mon Sep 17 00:00:00 2001 From: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> Date: Tue, 27 Feb 2024 10:27:23 -0600 Subject: [PATCH 4/4] Update ic-admin.mdx --- docs/developer-docs/developer-tools/cli-tools/ic-admin.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/developer-docs/developer-tools/cli-tools/ic-admin.mdx b/docs/developer-docs/developer-tools/cli-tools/ic-admin.mdx index 7cb61e7ef9..0a366dc73c 100644 --- a/docs/developer-docs/developer-tools/cli-tools/ic-admin.mdx +++ b/docs/developer-docs/developer-tools/cli-tools/ic-admin.mdx @@ -2,6 +2,7 @@ `ic-admin` is a tool used to view current network information, such as subnet and node info. It can also be used to create and submit NNS proposals. + ## Installing `ic-admin` To install `ic-admin`, first determine the commit ID of the latest IC release. This commit can be found in [the DFINITY/ic repo](https://github.com/dfinity/ic/releases/latest). @@ -276,4 +277,4 @@ NodeRecord { xnet: Some(ConnectionEndpoint { ip_addr: "2400:a240:0:2:6801:63ff:f To learn how to use `ic-admin` as a node provider, check out [the Node Provider onboarding wiki page](https://wiki.internetcomputer.org/wiki/Node_Provider_Onboarding). -Examples of node provider proposals include proposals to add your node provider to the network, register your data center, and create a ndoe operator record. \ No newline at end of file +Examples of node provider proposals include proposals to add your node provider to the network, register your data center, and create a ndoe operator record.