Merge pull request #2563 from dfinity/update-ic-admin

Update ic-admin doc
dfinity · Feb 27, 2024 · dddb896 · dddb896
2 parents fcdf7c8 + 8b8934c
commit dddb896
Show file tree

Hide file tree

Showing 6 changed files with 283 additions and 47 deletions.
diff --git a/docs/developer-docs/developer-tools/cli-tools/ic-admin.mdx b/docs/developer-docs/developer-tools/cli-tools/ic-admin.mdx
@@ -0,0 +1,280 @@
+# IC-admin
+
+`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).
+
+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://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
+```
+
+#### Linux
+
+```bash
+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
+```
+
+## Using `ic-admin`
+
+### View network info
+
+To view detailed information about the network's current topology, use the command:
+
+```
+./ic-admin --nns-urls https://ic0.app get-topology
+```
+
+This will return output about current subnets and nodes, such as:
+
+```
+...
+///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 <SUBNET_ID>
+```
+
+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 <NODE_PROVIDER_ID>
+```
+
+### 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 <NODE_ID>
+```
+
+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.
diff --git 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.
 

diff --git a/docs/developer-docs/setup/_category_.yml b/docs/developer-docs/setup/_category_.yml
diff --git a/docs/developer-docs/setup/ic-admin.md b/docs/developer-docs/setup/ic-admin.md
diff --git 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
@@ -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",
           ],
         },
         {
-Original file line number
+Diff line change
@@ Expand Up / @@ -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",
               ],
             },
             {
@@ Expand Down @@