118 releases (10 breaking)
| new 0.11.3 | Nov 12, 2024 |
|---|---|
| 0.11.1 | Oct 29, 2024 |
| 0.10.1 | Jul 29, 2024 |
| 0.7.2 | Mar 28, 2024 |
| 0.1.1 | Nov 29, 2023 |
#207 in Development tools
440 downloads per month
Used in node-launchpad
1MB
25K
SLoC
Safenode Manager
Safenode Manager is a command-line application for installing, managing, and operating safenode as a service.
It runs on Linux, macOS and Windows.
Installation
The latest version can be installed via safeup:
safeup node-manager
A binary can also be obtained for your platform from the releases in this repository.
Nodes as Services
The primary use case for Safenode Manager is to setup safenode 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, the node manager must always be used in an elevated, administrative session.
Create Services
First, use the add command to create some services:
$ safenode-manager add --count 3 --peer /ip4/139.59.168.228/udp/56309/quic-v1/p2p/12D3KooWFTMtaqu24ddDSXk9v5YxnuhJmTLFRunER1CG4wZ2XLUU
This downloads the latest version of the safenode 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 safenode. Run safenode-manager add --help to see all available options.
Note: elevated privileges are required for creating services, on all platforms.
Now run the status command:
$ safenode-manager status
=================================================
Safenode Services
=================================================
Refreshing the node registry...
Service Name Peer ID Status Connected Peers
safenode1 - ADDED -
safenode2 - ADDED -
safenode3 - ADDED -
We can see the services have been added, but they are not running yet.
Start Services
Use the start command to start each service:
$ safenode-manager 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:
$ safenode-manager status
=================================================
Safenode Services
=================================================
Refreshing the node registry...
Service Name Peer ID Status Connected Peers
safenode1 12D3KooWGQu92xCXuiK6AysbHn6kHyfXqyzNDxNGnnDTgd56eveq RUNNING 81
safenode2 12D3KooWQGVfcwrPFvC6PyCva1cJu8NZVhdZCuPHJ4vY79yuKC3A RUNNING 82
safenode3 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:
=================================================
Safenode Services
=================================================
Refreshing the node registry...
============================
safenode1 - 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/safenode-manager/services/safenode1
Log path: /var/log/safenode/safenode1
Bin path: /var/safenode-manager/services/safenode1/safenode
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.
Add More Nodes
It's possible to run the add command again, as before:
safenode-manager 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:
$ safenode-manager status
=================================================
Safenode Services
=================================================
Refreshing the node registry...
Service Name Peer ID Status Connected Peers
safenode1 12D3KooWGQu92xCXuiK6AysbHn6kHyfXqyzNDxNGnnDTgd56eveq RUNNING 4
safenode2 12D3KooWQGVfcwrPFvC6PyCva1cJu8NZVhdZCuPHJ4vY79yuKC3A RUNNING 4
safenode3 12D3KooWMqRH6EF1Km61TAW9wTuv9LgDabKMY9DJSGyrxUafXP6b RUNNING 3
safenode4 - ADDED -
safenode5 - ADDED -
safenode6 - ADDED -
Again, the new nodes have not been started.
Run the start command to start them, then observe the status:
$ safenode-manager status
=================================================
Safenode Services
=================================================
Refreshing the node registry...
Service Name Peer ID Status Connected Peers
safenode1 12D3KooWGQu92xCXuiK6AysbHn6kHyfXqyzNDxNGnnDTgd56eveq RUNNING 138
safenode2 12D3KooWQGVfcwrPFvC6PyCva1cJu8NZVhdZCuPHJ4vY79yuKC3A RUNNING 177
safenode3 12D3KooWMqRH6EF1Km61TAW9wTuv9LgDabKMY9DJSGyrxUafXP6b RUNNING 144
safenode4 12D3KooWLH9VRAoUMj4bUjtzcKS3mqfzyc46TxBkBzvUXfV1bjaT RUNNING 2
safenode5 12D3KooWEcbpvSSTmSyuzqP3gE9bE7uqYFatHhkJXr8PBiqmESEG RUNNING 1
safenode6 12D3KooWBip2g5FakT1dZHdrhdmnctgKqhbRBQA5ZpvtHh4XPRXJ RUNNING 30
Removing Nodes
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:
$ safenode-manager stop --service-name safenode5
Observe that safenode5 has been stopped, but the others are still running:
$ safenode-manager status
=================================================
Safenode Services
=================================================
Refreshing the node registry...
Service Name Peer ID Status Connected Peers
safenode1 12D3KooWGQu92xCXuiK6AysbHn6kHyfXqyzNDxNGnnDTgd56eveq RUNNING 10
safenode2 12D3KooWQGVfcwrPFvC6PyCva1cJu8NZVhdZCuPHJ4vY79yuKC3A RUNNING 5
safenode3 12D3KooWMqRH6EF1Km61TAW9wTuv9LgDabKMY9DJSGyrxUafXP6b RUNNING 2
safenode4 12D3KooWLH9VRAoUMj4bUjtzcKS3mqfzyc46TxBkBzvUXfV1bjaT RUNNING 2
safenode5 12D3KooWEcbpvSSTmSyuzqP3gE9bE7uqYFatHhkJXr8PBiqmESEG STOPPED -
safenode6 12D3KooWBip2g5FakT1dZHdrhdmnctgKqhbRBQA5ZpvtHh4XPRXJ RUNNING 29
Now that it's been stopped, remove it:
$ safenode-manager remove --service-name safenode5
The status command will no longer show the service:
vagrant@ubuntu2204:~$ safenode-manager status
=================================================
Safenode Services
=================================================
Refreshing the node registry...
Service Name Peer ID Status Connected Peers
safenode1 12D3KooWGQu92xCXuiK6AysbHn6kHyfXqyzNDxNGnnDTgd56eveq RUNNING 2
safenode2 12D3KooWQGVfcwrPFvC6PyCva1cJu8NZVhdZCuPHJ4vY79yuKC3A RUNNING 96
safenode3 12D3KooWMqRH6EF1Km61TAW9wTuv9LgDabKMY9DJSGyrxUafXP6b RUNNING 127
safenode4 12D3KooWLH9VRAoUMj4bUjtzcKS3mqfzyc46TxBkBzvUXfV1bjaT RUNNING 76
safenode6 12D3KooWBip2g5FakT1dZHdrhdmnctgKqhbRBQA5ZpvtHh4XPRXJ RUNNING 133
However, we will still see it in the detailed view:
$ safenode-manager status --details
=================================================
Safenode Services
=================================================
Refreshing the node registry...
<output snipped>
============================
safenode5 - 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/safenode-manager/services/safenode5
Log path: /var/log/safenode/safenode5
Bin path: /var/safenode-manager/services/safenode5/safenode
Connected peers: -
<output snipped>
Upgrades
The node manager can be used to continually upgrade node services.
Suppose we have five services:
$ safenode-manager status
=================================================
Safenode Services
=================================================
Refreshing the node registry...
Service Name Peer ID Status Connected Peers
safenode1 12D3KooWKaNFPoRf8E2vsdSwBNyhWpe7csNkqwXaunNVxXGarxap RUNNING 1
safenode2 12D3KooWNbRBR43rdFR44EAbwzBrED3jWUiWKkHD2oabw2jKZ9eF RUNNING 1
safenode3 12D3KooWGYEuqXRhKVF2WK499oCBpkh9c6K7jy8BNSfqGosSzNZ8 RUNNING 1
safenode4 12D3KooWS6WGnhbSfLywaepfZbbqgxTLhr66N1PXU4GVLWDBRZRF RUNNING 1
safenode5 12D3KooWNdEYQAutzcGo26rZayew2rzE24y5VFVxTnsefNevc1Ly RUNNING 1
Using the --details flag, we can see they are not at the latest version:
$ safenode-manager status --details
=================================================
Safenode Services
=================================================
Refreshing the node registry...
============================
safenode1 - 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/safenode-manager/services/safenode1
Log path: /var/log/safenode/safenode1
Bin path: /var/safenode-manager/services/safenode1/safenode
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:
$ safenode-manager upgrade
=================================================
Upgrade Safenode Services
=================================================
Retrieving latest version of safenode...
Latest version is 0.105.3
Downloading safenode version 0.105.3...
Download completed: /tmp/ae310e50-d104-45bc-9619-22e1328d8c8b/safenode
Refreshing the node registry...
<output snipped>
Upgrade summary:
✓ safenode1 upgraded from 0.104.38 to 0.105.3
✓ safenode2 upgraded from 0.104.38 to 0.105.3
✓ safenode3 upgraded from 0.104.38 to 0.105.3
✓ safenode4 upgraded from 0.104.38 to 0.105.3
✓ safenode5 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.
The node manager will determine the latest version of safenode, 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.
Downgrading
In some situations, it may be necessary to downgrade safenode to a previous version. The upgrade command supports this by providing --version and --force arguments. Each of those can be used to force the node manager to accept a lower version.
Local Networks
Safenode Manager 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:
$ safenode-manager 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 safenode...
Downloading safenode version 0.105.3...
Download completed: /tmp/f63d3ca8-2b8e-4630-9df5-a13418d5f826/safenode
Launching node 1...
Logging to directory: "/home/chris/.local/share/safe/node/12D3KooWPArH2XAw2sapcthNNcJRbbSuUtC3eBZrJtxi8DfcN1Yn/logs"
Node started
<remaining output snipped>
Note: elevated privileges are not required for local networks.
Check the output of the status command:
$ safenode-manager status
=================================================
Local Network
=================================================
Refreshing the node registry...
Service Name Peer ID Status Connected Peers
safenode-local1 12D3KooWPArH2XAw2sapcthNNcJRbbSuUtC3eBZrJtxi8DfcN1Yn RUNNING 7
safenode-local2 12D3KooWShWom22VhgkDX7APqSzCmXPNsfZA17Y2GSJpznunAp8M RUNNING 0
safenode-local3 12D3KooWJwLaqsHvVaBkTHLn8Zf5hZdBaoC9pUNtgANymjF3XEmR RUNNING 0
safenode-local4 12D3KooWP1dwBpCQa6mNY62h9LYN5w4gsTqpQfsH1789pvbNVkSQ RUNNING 0
safenode-local5 12D3KooWADWar7uP8pgxahjcgNsvpzVdp2HxtwQoc5ytvgjjFN8r RUNNING 0
safenode-local6 12D3KooWEvPZzdGXPFNGBR5xjt55tSTFJa9ByqLvZAWZ9uYRqYh1 RUNNING 0
safenode-local7 12D3KooWAbLW3UfF9VdeTxtha7TMuMmFyhZGpXi9Anv9toNLQgfv RUNNING 0
safenode-local8 12D3KooWMYhdDsp2eUjGGgqGrStGxyVzoZsui9YQH4N9B6Fh36H3 RUNNING 2
safenode-local9 12D3KooWFMQ9rumJKjayipPgfnCP355oXcD6uzoBFZq985ij1MZP RUNNING 7
safenode-local10 12D3KooWEN8bW2yPfBhJPG9w5xT3zkWGqA9JYY7qkgc1LmuWJshF RUNNING 0
safenode-local11 12D3KooWSUi43YFYQxoRk8iyh7XE3SSeFvLYvANjRjSTS2CAXTwF RUNNING 0
safenode-local12 12D3KooWNhwMVs8jBSwsfM6gD4vhwksVUaP2EMmwReNiibMqPBYT RUNNING 0
safenode-local13 12D3KooWDqgKpbrenxeWyAAw2j45wW7tCpiHYxNnTL7tFioBCTSv RUNNING 1
safenode-local14 12D3KooWAxzJjhxrr2QD4UwkrovVTy5PnjWCFkBPrUJdPVzdNmDP RUNNING 0
safenode-local15 12D3KooWCE3Ccp1GEiXLU8pQdYJued5G6xAiRiarSSgXRhHwG6XJ RUNNING 7
safenode-local16 12D3KooWRC9wjjsnUTEjP8F6pNVu4LacgPMYNP8p3WNeBcgqEGZH RUNNING 0
safenode-local17 12D3KooWKNnLBkDXvdyPV8FALGApnZjtyuxhfzBED4boBQX8gwvD RUNNING 7
safenode-local18 12D3KooWGvMXmnGU3s7g8XZXSExmscXfV8cqHrAQkVKicRxJrx5E RUNNING 1
safenode-local19 12D3KooWHFzdXEiajdSbJRRLnJq56qw2pke9HvneeziuWZB7TTsD RUNNING 2
safenode-local20 12D3KooWMWuuiPwz1mASasxDuT2QpkDFg46RjNiY6FXprFrgFAbT RUNNING 7
safenode-local21 12D3KooWAkgCaCPMBG2gkZJRQJwfM5XYyJ66LmCSidXK6R8x2b7q RUNNING 6
safenode-local22 12D3KooWPep6B7YfsXWdmjDtyNvm8TZ3bvmn9dZ9w9CPtssW2Wtz RUNNING 7
safenode-local23 12D3KooWF486Rjn5DZ7VXcZi99bTabZsWNf73dnnfmpdjusdeEu9 RUNNING 0
safenode-local24 12D3KooWLLWGzyFtB3i1WNrsdu2eW4k3gT7Wewf9D8srgb1dNwcj RUNNING 0
safenode-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 safenode-manager local kill to dispose the local network.
Running Integration Tests
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 sn_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.
Dependencies
~66–105MB
~2M SLoC