IC-admin
Intermediate
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 latest IC release version found in the DFINITY/ic repo.
Then, download the ic-admin file for your operating system. For macOS, download the darwin file; for Linux, download the linux file, replacing [latest-release] with the most recent version number such as release-2024-07-10_23-01-base:
macOS
curl -L "https://github.com/dfinity/ic/releases/download/[latest-release]/ic-admin-x86_64-darwin.gz" -o - | gunzip > ./ic-admin
chmod +x ./ic-admin
Linux
curl -L "https://github.com/dfinity/ic/releases/download/[latest-release]/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:4943 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:4943 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
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: 4943, 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.
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.