Antctl is a command-line application for installing, managing, and operating antnode as a service.
It runs on Linux, macOS and Windows.
The latest version can be installed via safeup:
safeup antctl
A binary can also be obtained for your platform from the releases in this repository.
The primary use case for Antctl is to setup antnode as a long-running background service, using
the service infrastructure provided by the operating system.
On macOS and most distributions of Linux, user-mode services are supported. Traditionally, services are system-wide infrastructure that require elevated privileges to create and work with. However, with user-mode services, they can be defined and used without sudo. The main difference is, a user-mode service requires an active user session, whereas a system-wide service can run completely in the background, without any active session. It's a user decision as to which is more appropriate for their use case. On Linux, some service managers, like OpenRC, used on Alpine, do not support user-mode services. Most distributions use Systemd, which does have support for them.
The commands defined in the rest of this guide will operate on the basis of a user-mode service, and
so will not use sudo. If you would like to run system-wide services, you can go through the same
guide, but just prefix each command with sudo.
Windows does not support user-mode services at all, and therefore, Antctl must always be used in an elevated, administrative session.
First, use the add command to create some services:
$ antctl add --count 3 --peer /ip4/139.59.168.228/udp/56309/quic-v1/p2p/12D3KooWFTMtaqu24ddDSXk9v5YxnuhJmTLFRunER1CG4wZ2XLUU
This downloads the latest version of the antnode binary and creates three services that will initially connect to the specified peer. Soon, specification of a peer will not be required.
There are many arguments available for customising the service. For example, you can choose the port the node will run on, or the version of antnode. Run antctl add --help to see all available options.
Note: elevated privileges are required for creating services, on all platforms.
Now run the status command:
$ antctl status
=================================================
Antnode Services
=================================================
Refreshing the node registry...
Service Name Peer ID Status Connected Peers
antnode1 - ADDED -
antnode2 - ADDED -
antnode3 - ADDED -
We can see the services have been added, but they are not running yet.
Use the start command to start each service:
$ antctl start
Providing no arguments will start all available services. If need be, it's possible to start services individually, using the --service-name argument.
With the services started, run the status command again:
$ antctl status
=================================================
Antnode Services
=================================================
Refreshing the node registry...
Service Name Peer ID Status Connected Peers
antnode1 12D3KooWGQu92xCXuiK6AysbHn6kHyfXqyzNDxNGnnDTgd56eveq RUNNING 81
antnode2 12D3KooWQGVfcwrPFvC6PyCva1cJu8NZVhdZCuPHJ4vY79yuKC3A RUNNING 82
antnode3 12D3KooWMqRH6EF1Km61TAW9wTuv9LgDabKMY9DJSGyrxUafXP6b RUNNING 79
We can see our services are running and the nodes have connections to other peers.
Now, run the status command again, but with the --details flag:
=================================================
Antnode Services
=================================================
Refreshing the node registry...
============================
antnode1 - RUNNING
============================
Version: 0.105.0
Peer ID: 12D3KooWGQu92xCXuiK6AysbHn6kHyfXqyzNDxNGnnDTgd56eveq
RPC Socket: 127.0.0.1:41785
Listen Addresses: Some["/ip4/127.0.0.1/udp/34653/quic-v1/p2p/12D3KooWGQu92xCXuiK6AysbHn6kHyfXqyzNDxNGnnDTgd56eveq", "/ip4/192.168.121.7/udp/34653/quic-v1/p2p/12D3KooWGQu92xCXuiK6AysbHn6kHyfXqyzNDxNGnnDTgd56eveq"]
PID: 3137
Data path: /var/antctl/services/antnode1
Log path: /var/log/antnode/antnode1
Bin path: /var/antctl/services/antnode1/antnode
Connected peers: 10
<remaining output snipped>
We get some more details for each node, including the path to its logs. Using the location provided, feel free to take a look at the logs being generated by the node.
The nodes could now be left running like this, but for the purposes of this guide, we will do some more things.
It's possible to run the add command again, as before:
antctl add --count 3 --peer /ip4/46.101.80.187/udp/58070/quic-v1/p2p/12D3KooWKgJQedzCxrp33u3dBD1mUZ9HTjEjgrxskEBvzoQWkRT9
The subsequent status command will show us an additional three nodes, for a total of six:
$ antctl status
=================================================
Antnode Services
=================================================
Refreshing the node registry...
Service Name Peer ID Status Connected Peers
antnode1 12D3KooWGQu92xCXuiK6AysbHn6kHyfXqyzNDxNGnnDTgd56eveq RUNNING 4
antnode2 12D3KooWQGVfcwrPFvC6PyCva1cJu8NZVhdZCuPHJ4vY79yuKC3A RUNNING 4
antnode3 12D3KooWMqRH6EF1Km61TAW9wTuv9LgDabKMY9DJSGyrxUafXP6b RUNNING 3
antnode4 - ADDED -
antnode5 - ADDED -
antnode6 - ADDED -
Again, the new nodes have not been started.
Run the start command to start them, then observe the status:
$ antctl status
=================================================
Antctl Services
=================================================
Refreshing the node registry...
Service Name Peer ID Status Connected Peers
antnode1 12D3KooWGQu92xCXuiK6AysbHn6kHyfXqyzNDxNGnnDTgd56eveq RUNNING 138
antnode2 12D3KooWQGVfcwrPFvC6PyCva1cJu8NZVhdZCuPHJ4vY79yuKC3A RUNNING 177
antnode3 12D3KooWMqRH6EF1Km61TAW9wTuv9LgDabKMY9DJSGyrxUafXP6b RUNNING 144
antnode4 12D3KooWLH9VRAoUMj4bUjtzcKS3mqfzyc46TxBkBzvUXfV1bjaT RUNNING 2
antnode5 12D3KooWEcbpvSSTmSyuzqP3gE9bE7uqYFatHhkJXr8PBiqmESEG RUNNING 1
antnode6 12D3KooWBip2g5FakT1dZHdrhdmnctgKqhbRBQA5ZpvtHh4XPRXJ RUNNING 30
If for some reason we want to remove one of our nodes, we can do so using the remove command.
Suppose we wanted to remove the 5th service. First of all, we need to stop the service. Run the following command:
$ antctl stop --service-name antnode5
Observe that antnode5 has been stopped, but the others are still running:
$ antctl status
=================================================
Antnode Services
=================================================
Refreshing the node registry...
Service Name Peer ID Status Connected Peers
antnode1 12D3KooWGQu92xCXuiK6AysbHn6kHyfXqyzNDxNGnnDTgd56eveq RUNNING 10
antnode2 12D3KooWQGVfcwrPFvC6PyCva1cJu8NZVhdZCuPHJ4vY79yuKC3A RUNNING 5
antnode3 12D3KooWMqRH6EF1Km61TAW9wTuv9LgDabKMY9DJSGyrxUafXP6b RUNNING 2
antnode4 12D3KooWLH9VRAoUMj4bUjtzcKS3mqfzyc46TxBkBzvUXfV1bjaT RUNNING 2
antnode5 12D3KooWEcbpvSSTmSyuzqP3gE9bE7uqYFatHhkJXr8PBiqmESEG STOPPED -
antnode6 12D3KooWBip2g5FakT1dZHdrhdmnctgKqhbRBQA5ZpvtHh4XPRXJ RUNNING 29
Now that it's been stopped, remove it:
$ antctl remove --service-name antnode5
The status command will no longer show the service:
vagrant@ubuntu2204:~$ antctl status
=================================================
Antnode Services
=================================================
Refreshing the node registry...
Service Name Peer ID Status Connected Peers
antnode1 12D3KooWGQu92xCXuiK6AysbHn6kHyfXqyzNDxNGnnDTgd56eveq RUNNING 2
antnode2 12D3KooWQGVfcwrPFvC6PyCva1cJu8NZVhdZCuPHJ4vY79yuKC3A RUNNING 96
antnode3 12D3KooWMqRH6EF1Km61TAW9wTuv9LgDabKMY9DJSGyrxUafXP6b RUNNING 127
antnode4 12D3KooWLH9VRAoUMj4bUjtzcKS3mqfzyc46TxBkBzvUXfV1bjaT RUNNING 76
antnode6 12D3KooWBip2g5FakT1dZHdrhdmnctgKqhbRBQA5ZpvtHh4XPRXJ RUNNING 133
However, we will still see it in the detailed view:
$ antctl status --details
=================================================
Antnode Services
=================================================
Refreshing the node registry...
<output snipped>
============================
antnode5 - REMOVED
============================
Version: 0.105.0
Peer ID: 12D3KooWEcbpvSSTmSyuzqP3gE9bE7uqYFatHhkJXr8PBiqmESEG
RPC Socket: 127.0.0.1:38579
Listen Addresses: Some(["/ip4/127.0.0.1/udp/58354/quic-v1/p2p/12D3KooWEcbpvSSTmSyuzqP3gE9bE7uqYFatHhkJXr8PBiqmESEG", "/ip4/192.168.121.7/udp/58354/quic-v1/p2p/12D3KooWEcbpvSSTmSyuzqP3gE9bE7uqYFatHhkJXr8PBiqmESEG"])
PID: -
Data path: /var/antctl/services/antnode5
Log path: /var/log/antnode/antnode5
Bin path: /var/antctl/services/antnode5/antnode
Connected peers: -
<output snipped>
Antctl can be used to continually upgrade node services.
Suppose we have five services:
$ antctl status
=================================================
Antnode Services
=================================================
Refreshing the node registry...
Service Name Peer ID Status Connected Peers
antnode1 12D3KooWKaNFPoRf8E2vsdSwBNyhWpe7csNkqwXaunNVxXGarxap RUNNING 1
antnode2 12D3KooWNbRBR43rdFR44EAbwzBrED3jWUiWKkHD2oabw2jKZ9eF RUNNING 1
antnode3 12D3KooWGYEuqXRhKVF2WK499oCBpkh9c6K7jy8BNSfqGosSzNZ8 RUNNING 1
antnode4 12D3KooWS6WGnhbSfLywaepfZbbqgxTLhr66N1PXU4GVLWDBRZRF RUNNING 1
antnode5 12D3KooWNdEYQAutzcGo26rZayew2rzE24y5VFVxTnsefNevc1Ly RUNNING 1
Using the --details flag, we can see they are not at the latest version:
$ antctl status --details
=================================================
Antnode Services
=================================================
Refreshing the node registry...
============================
antnode1 - RUNNING
============================
Version: 0.104.38
Peer ID: 12D3KooWKaNFPoRf8E2vsdSwBNyhWpe7csNkqwXaunNVxXGarxap
RPC Socket: 127.0.0.1:37931
Listen Addresses: Some(["/ip4/127.0.0.1/udp/39890/quic-v1/p2p/12D3KooWKaNFPoRf8E2vsdSwBNyhWpe7csNkqwXaunNVxXGarxap", "/ip4/192.168.121.114/udp/39890/quic-v1/p2p/12D3KooWKaNFPoRf8E2vsdSwBNyhWpe7csNkqwXaunNVxXGarxap"])
PID: 3285
Data path: /var/antctl/services/antnode1
Log path: /var/log/antnode/antnode1
Bin path: /var/antctl/services/antnode1/antnode
Connected peers: 0
<remaining output snipped>
For brevity, the remaining output is snipped, but the four others are also at 0.104.38. At the time of writing, the latest version is 0.105.3.
We can use the upgrade command to get each service on the latest version:
$ antctl upgrade
=================================================
Upgrade Antnode Services
=================================================
Retrieving latest version of antnode...
Latest version is 0.105.3
Downloading antnode version 0.105.3...
Download completed: /tmp/ae310e50-d104-45bc-9619-22e1328d8c8b/antnode
Refreshing the node registry...
<output snipped>
Upgrade summary:
✓ antnode1 upgraded from 0.104.38 to 0.105.3
✓ antnode2 upgraded from 0.104.38 to 0.105.3
✓ antnode3 upgraded from 0.104.38 to 0.105.3
✓ antnode4 upgraded from 0.104.38 to 0.105.3
✓ antnode5 upgraded from 0.104.38 to 0.105.3
Again, for brevity some output from the command was snipped, but the summary indicates that each service was upgraded from 0.104.38 to 0.105.3.
As with other commands, if no arguments are supplied, upgrade operates over all services, but it's possible to use the --service-name or --peer-id arguments to upgrade specific services. Both those arguments can be used multiple times to operate over several services.
Antctl will determine the latest version of antnode, download it, then for each running service, if the service is older than the latest, it will stop it, copy the new binary over the old one, and start the service again.
In some situations, it may be necessary to downgrade antnode to a previous version. The upgrade command supports this by providing --version and --force arguments. Each of those can be used to force Antctl to accept a lower version.
Antctl can also create local networks, which are useful for development or quick experimentation. In a local network, nodes will run as processes rather than services. Local operations are defined under the local subcommand.
To create a local network, use the run command:
$ antctl local run
=================================================
Launching Local Network
=================================================
Retrieving latest version for faucet...
Downloading faucet version 0.4.3...
Download completed: /tmp/4dc310dd-74ef-4dc5-af36-3bc92a882db1/faucet
Retrieving latest version for antnode...
Downloading antnode version 0.105.3...
Download completed: /tmp/f63d3ca8-2b8e-4630-9df5-a13418d5f826/antnode
Launching node 1...
Logging to directory: "/home/chris/.local/share/autonomi/node/12D3KooWPArH2XAw2sapcthNNcJRbbSuUtC3eBZrJtxi8DfcN1Yn/logs"
Node started
<remaining output snipped>
Note: elevated privileges are not required for local networks.
Check the output of the status command:
$ antctl status
=================================================
Local Network
=================================================
Refreshing the node registry...
Service Name Peer ID Status Connected Peers
antnode-local1 12D3KooWPArH2XAw2sapcthNNcJRbbSuUtC3eBZrJtxi8DfcN1Yn RUNNING 7
antnode-local2 12D3KooWShWom22VhgkDX7APqSzCmXPNsfZA17Y2GSJpznunAp8M RUNNING 0
antnode-local3 12D3KooWJwLaqsHvVaBkTHLn8Zf5hZdBaoC9pUNtgANymjF3XEmR RUNNING 0
antnode-local4 12D3KooWP1dwBpCQa6mNY62h9LYN5w4gsTqpQfsH1789pvbNVkSQ RUNNING 0
antnode-local5 12D3KooWADWar7uP8pgxahjcgNsvpzVdp2HxtwQoc5ytvgjjFN8r RUNNING 0
antnode-local6 12D3KooWEvPZzdGXPFNGBR5xjt55tSTFJa9ByqLvZAWZ9uYRqYh1 RUNNING 0
antnode-local7 12D3KooWAbLW3UfF9VdeTxtha7TMuMmFyhZGpXi9Anv9toNLQgfv RUNNING 0
antnode-local8 12D3KooWMYhdDsp2eUjGGgqGrStGxyVzoZsui9YQH4N9B6Fh36H3 RUNNING 2
antnode-local9 12D3KooWFMQ9rumJKjayipPgfnCP355oXcD6uzoBFZq985ij1MZP RUNNING 7
antnode-local10 12D3KooWEN8bW2yPfBhJPG9w5xT3zkWGqA9JYY7qkgc1LmuWJshF RUNNING 0
antnode-local11 12D3KooWSUi43YFYQxoRk8iyh7XE3SSeFvLYvANjRjSTS2CAXTwF RUNNING 0
antnode-local12 12D3KooWNhwMVs8jBSwsfM6gD4vhwksVUaP2EMmwReNiibMqPBYT RUNNING 0
antnode-local13 12D3KooWDqgKpbrenxeWyAAw2j45wW7tCpiHYxNnTL7tFioBCTSv RUNNING 1
antnode-local14 12D3KooWAxzJjhxrr2QD4UwkrovVTy5PnjWCFkBPrUJdPVzdNmDP RUNNING 0
antnode-local15 12D3KooWCE3Ccp1GEiXLU8pQdYJued5G6xAiRiarSSgXRhHwG6XJ RUNNING 7
antnode-local16 12D3KooWRC9wjjsnUTEjP8F6pNVu4LacgPMYNP8p3WNeBcgqEGZH RUNNING 0
antnode-local17 12D3KooWKNnLBkDXvdyPV8FALGApnZjtyuxhfzBED4boBQX8gwvD RUNNING 7
antnode-local18 12D3KooWGvMXmnGU3s7g8XZXSExmscXfV8cqHrAQkVKicRxJrx5E RUNNING 1
antnode-local19 12D3KooWHFzdXEiajdSbJRRLnJq56qw2pke9HvneeziuWZB7TTsD RUNNING 2
antnode-local20 12D3KooWMWuuiPwz1mASasxDuT2QpkDFg46RjNiY6FXprFrgFAbT RUNNING 7
antnode-local21 12D3KooWAkgCaCPMBG2gkZJRQJwfM5XYyJ66LmCSidXK6R8x2b7q RUNNING 6
antnode-local22 12D3KooWPep6B7YfsXWdmjDtyNvm8TZ3bvmn9dZ9w9CPtssW2Wtz RUNNING 7
antnode-local23 12D3KooWF486Rjn5DZ7VXcZi99bTabZsWNf73dnnfmpdjusdeEu9 RUNNING 0
antnode-local24 12D3KooWLLWGzyFtB3i1WNrsdu2eW4k3gT7Wewf9D8srgb1dNwcj RUNNING 0
antnode-local25 12D3KooWPpVim2rRHeAYTrM8mSkZjUt5SjQ4v5xPF2h7wi8H1jRj RUNNING 0
faucet - RUNNING -
So by default, 25 node processes have been launched, along with a faucet. The faucet dispenses tokens for use when uploading files. We can now run safe commands against the local network.
The most common scenario for using a local network is for development, but you can also use it to exercise a lot of features locally. For more details, please see the 'Using a Local Network' section of the main README.
Once you've finished, run antctl local kill to dispose the local network.
Sometimes it will be necessary to run the integration tests in a local setup. The problem is, the system-wide tests need root access to run, and they will also create real services, which you don't necessarily want on your development machine.
The tests can be run from a VM, which is provided by a Vagrantfile in the ant_node_manager crate directory. The machine is defined to use libvirt rather than Virtualbox, so an installation of that is required, but that is beyond the scope of this document.
Assuming that you did have an installation of libvirt, you can get the VM by running vagrant up. Once the machine is available, run vagrant ssh to get a shell session inside it. For running the tests, switch to the root user using sudo su -. As part of the provisioning process, the current safe_network code is copied to the root user's home directory. To run the tests:
cd safe_network
just node-man-integration-tests
The target in the Justfile will create a local network and the tests will then run against that.