Skip to main content

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.