release
Last updated: 2024-12-24 01:09:56.596385 File source: link on GitLab
Device Management Service (DMS)
Table of Contents
About
Device Management Service or DMS enables a machine to join the decentralized NuNet network both as a compute provider, offering its resources to the network, or to leverage the compute power of other machines in the network for processing tasks. Eventually users with available hardware resources will get compensated whenever their machine is utilized for a computational job by other users in the network. The ultimate goal of the platorm is to create a decentralized compute economy that is able to sustain itself.
Payment
All transactions on the Nunet network are expected to be conducted using the platform's utility token NTX. However, DMS is currently in development, and payment isn't part of v0.5.0-boot
release. NTX payments are expected to be implemented in the Public Alpha Mainnet milestone within later release cycles.
Note: If you are a developer, please check out the DMS specifications and Building from Source sections of this document.
Installation
You can install Device Management Service (DMS) via binary releases or building it from source.
Binary releases
You can find all binary releases here and other builds in-between releases in the package registry. We currently support ARM and AMD64 architectures. You may check your architecture with appropriate command (uname -p
for linux) and refer to the architecture name mapping e.g. here for figuring correct package to download.
Note: If you intalled the binary from a release and you would like to act as compute provider, you may need to check permissions and features to enable some required and optional features.
Ubuntu/Debian
Download the latest .deb package from the package registry
Install the Debian package with
apt
ordpkg
:
Some dependencies such as
docker
andlibsystemd-dev
might be missing so it's recommended to fix install by running:
Building from source
We currently support Linux and MacOS (Darwin).
Dependencies
iproute2 (linux only)
build-essential (linux only)
libsystemd-dev (linux only)
go (v1.21.7 or later)
git-lfs (for downloading large files)
Clone the repository:
Configure git-lfs:
Build the CLI:
This will result in a binary file in builds/ folder named as dms_linux_amd64
or dms_darwin_arm64
depending on the platform.
Note: If you built from source and would like to act as a compute provider, you may need to check permissions and features to enable some required and optional features.
To cross compile to arm, cross compilers need to be installed. In particular arm-linux-gnueabihf and aarch64-linux-gnu. For debian systems, install with:
You can add the compiled binary to a directory in your $PATH
. See the Usage section for more information.
Permissions and features (for compute providers)
The following applies only for compute providers. If you're running a client/orchestrator, you do not need to set any permissions.
If you built DMS from source or installed the binary from one of our releases, you may need to set some permissions to the binary to enable some features.
Darwin users: unfortunately, the DMS can't work with granular permissions on Mac. So, for now, if running a compute provider, you will have to run the nunet daemon (
nunet run
) as root.
For Linux users, granular permissions will have to be set to the binary (optionally, but NOT recommended, you can run the binary as root).
Net-admin permission and IP over libp2p
Note: cap_net_admin
is a required capability for compute providers.
Setting the permission enables IP over libp2p which is a feature that enhances the capabilities of compute providers, allowing them to participate in a wider range of jobs. One capability enabled with this feature is to do port forwarding which it won't be possible without setting the right unix permissions.
One of the reasons for requiring this permission is because this feature depends on creating and managing tun interfaces.
To enable this feature, the nunet
binary requires network-admin
capabilities. These capabilities allow the application to perform network configuration tasks without needing to run the entire application as root, which is a more secure approach.
To set the necessary capabilities, run the following command:
The above command depends on: libcap2-bin
(Debian/Ubuntu) or libcap
(CentOS/RHEL/Arch...)
Firecracker (for compute providers)
Note: Linux only.
To act as a compute provider capable of receiving and running jobs with Firecracker, ensure your user is part of the kvm
group. You can do this by running:
Installation on VMs
Skip doing an unattended installation for the new Ubuntu VM as it might not add the user with administrative privileges.
Enable Guest Additions when installing the VM (VirtualBox only).
Always change the default NAT network setting to Bridged before booting the VM.
Install Extension Pack if using VirtualBox (recommended).
Install VMware Tools if using VMware (recommended).
ML on GPU jobs on VMs are not supported.
Installation on WSL
Install WSL through the Windows Store.
Install the Update KB5020030 (Windows 10 only).
Install Ubuntu 20.04 through WSL.
Enable systemd on Ubuntu WSL.
ML Jobs deployed on Linux cannot be resumed on WSL.
Though it is possible to run ML jobs on Windows machines with WSL, using Ubuntu 20.04 natively is highly recommended to avoid unpredictability and performance losses.
If you are using a dual-boot machine, make sure to use the wsl --shutdown
command before shutting down Windows and running Linux for ML jobs. Also, ensure your Windows machine is not in a hibernated state when you reboot into Linux.
System Requirements
CPU-only machines
Minimum System Requirements
We require you to specify CPU (MHz x no. of cores) and RAM, but your system must meet at least the following requirements before you decide to onboard it:
CPU: 2 GHz
RAM: 4 GB
Free Disk Space: 10 GB
Internet Download/Upload Speed: 4 Mbps / 0.5 MBps
If the above CPU has 4 cores, your available CPU would be around 8000 MHz. So if you want to onboard half your CPU and RAM on NuNet, you can specify 4000 MHz CPU and 2000 MB RAM.
Recommended System Requirements
CPU: 3.5 GHz
RAM: 8-16 GB
Free Disk Space: 20 GB
Internet Download/Upload Speed: 10 Mbps / 1.25 MBps
GPU Machines
Minimum System Requirements
CPU: 3 GHz
RAM: 8 GB
GPU: 4 GB VRAM (NVIDIA, AMD, or Intel discrete GPU with manually installed drivers)
Free Disk Space: 50 GB
Internet Download/Upload Speed: 50 Mbps
Note: For AMD64 platforms, we recommend using HiveOS as it comes with all necessary drivers pre-installed. For other setups, proper GPU drivers must be manually installed. See the GPU Driver Installation section for instructions.
Recommended System Requirements
CPU: 4 GHz
RAM: 16-32 GB
GPU: 8-12 GB VRAM (NVIDIA, AMD, or Intel discrete GPU with manually installed drivers)
Free Disk Space: 100 GB
Internet Download/Upload Speed: 100 Mbps
GPU Driver Installation
NuNet DMS requires properly installed GPU drivers to function correctly. We do not automatically install drivers to ensure compatibility and flexibility across different user setups.
For AMD64 Platforms:
We recommend using the Ubuntu-based HiveOS for the easiest setup.
If you prefer to use a different operating system or need to install drivers manually, please follow these steps:
NVIDIA GPUs:
Visit the NVIDIA Official Driver Downloads page.
Select your GPU model and operating system.
Download and install the recommended driver.
Install the NVIDIA Container Toolkit.
Reboot your system after installation.
AMD GPUs:
Visit the AMD Drivers and Support for Processors and Graphics page.
Select your GPU model and operating system.
Download and install the recommended driver.
Reboot your system after installation.
Along with the drivers, you will need to install amdgpu using ROCm for AMD GPUs. You can find the installation instructions here.
Make sure you select the rocm usecase when installing the amdgpu.
bash
$ sudo amdgpu-install --usecase=rocm
then the dms instance.
You can create as many identities as you want, specially if you want to manage multiple DMS instances.
Each time a new identity is generated it will prompt the user for a passphrase. The passphrase is associated with the created identity, thus a different passphrase can be set up for each identity. If you prefer, it's possible to set a DMS_PASSPHRASE
environment variable to avoid the command prompt.
The key did
command returns a DID key for the specified identity.
Remember to secure your keys and capability contexts, as they control access to your NuNet resources. They are encrypted and stored under $HOME/.nunet
by default.
Using a Ledger Wallet
It is also possible to use a Ledger Wallet instead of creating a new key; this is recommended for user contexts, but you should not use it for the dms context as it needs the key to sign capability tokens.
To set up a user context with a Ledger Wallet, you need the ledger-cli
script from NuNet's ledger wallet tool. The tool uses the Eth application and specifically the first Eth account with signing of personal messages. Everything that needs to be signed (namely capability tokens) will be presented on your Nano's screen in plaintext so that you can inspect it.
You can get your Ledger wallet's DID with:
To create the capability context for the user
Setting up Capabilities
NuNet's network communication is powered by the NuActor System, a zero-trust system that utilizes fine-grained capabilities, anchored on DIDs, following the UCAN model.
Once both identities are created, you'll need to set up capabilities. Specifically:
Create capability contexts for both the user and each of your DMS instances.
Add the user's DID as a root anchor for the DMS capability context. This ensures that the DMS instance fully trusts the user, granting complete control over the DMS (the root capability).
If you want your DMS to participate in the public NuNet testnet (and eventually the mainnet), you'll need to set up capability anchors for your DMS:
Create a capability anchor to allow your DMS to accept public behavior invocations from authorized users and DMSs in the NuNet ecosystem.
Add this token to your DMS as a require anchor.
Request a capability token from NuNet to invoke public behaviors on the network.
Add the token as a provide anchor in your personal capability context.
Delegate to your DMS the ability to make public invocations using your token.
Add the delegation token as a provide anchor in your DMS.
Add a root anchor for your DMS context
You can do this by invoking the dms cap anchor
command:
Where <user-did>
is the user did created above in Creating identities and can be obtained by:
or if you are using a Ledger Wallet
Setup your DMS for the public testnet
The NuNet DID
Create a capability anchor for public behaviors
Create the grant
or if you are using a Ledger Wallet
And the granted token as a require anchor
The first command grants nunet authorized users the capability to invoke public behaviors until December 31, 2024, and outputs a token.
The second command consumes the token and adds the require anchor for your DMS
Ask NuNet for a public network capability token
To request tokens for participating in the testnet, please go to did.nunet.io and submit the did you generated along with your gitlab username and an email address to receive the token. It's highly recommended that you use a Ledger hardware wallet for your keys.
Use the NuNet granted token to authorize public behavior invocations in the public network
3.1 Add the provide anchor to your personal context
or if you are using a Ledger Wallet
3.2 Delegate to your DMS
or if you are using a Ledger Wallet
3.3 Add the delegation token as a provide anchor in your DMS
The first command ingests the NuNet provided token and the last two commands use this token to delegate the public behavior capabilities to your DMS.
Running DMS
If everything was setup properly, you should be able to run:
Darwin users: If you plan to onboard your computer power to the network, You may need to run with
sudo
. See the optional features and permissions section for more information.
By default, DMS runs on port 9999.
Provide Compute Power to the Network
If you want to contribute your computer's resources (CPU, RAM, GPU, storage) to the network, you have to onboard your machine.
Follow our Compute Provider Guide to get started.
Deploy Jobs on the Network
Every node on the network can deploy workloads across available compute resources, given the necessary capabilities. Learn how deployments work by following our Deployments Guide.
REST Endpoints
Refer to the api
package README for the list of all endpoints. Head over to project's issue section and create an issue with your question.
Configuration
Config file
The DMS searches for a configuration file dms_config.json
in the following locations, in order of priority whenever it's started:
The current directory (
.
)$HOME/.nunet
/etc/nunet
The configuration file must be in JSON format and it does not support comments. It's recommended that only the parameters that need to be changed are included in the config file so that other parameters can retain their default values.
It's possible to manage configuration using the config
subcommand as well. nunet config set
allows setting each parameter individually and nunet config edit
will open the config file in the default editor from $EDITOR
Run Two DMS Instances Side by Side
As a developer, you might find yourself needing to run two DMS instances, one acting as an SP (Service Provider) and the other as a CP (Compute Provider).
Step 1:
Clone the repository to two different directories. You might want to use descriptive directory names to avoid confusion.
Step 2:
You need to modify some configurations so that both DMS instances do not end up trying to listen on the same port and use the same path for storage. For example, ports on p2p.listen_address
, rest.port
, general.user_dir
etc... neeed to be different for two instances on the same host.
The dms_config.json
file can be used to modify these settings. Here is a sample config file that can be modified to your preference:
Prefer to use absolute paths and have a look at the config structure for more info.
Tests
Some packages contain tests, and it is always best to run them to ensure there are no broken tests before submitting any changes. Before running the tests, the Firecracker executor requires some test data, such as a kernel file, which can be downloaded with:
After the download is complete, all unit tests can be run with the following command. It's necessary to include the unit
tag due to the existence of files that contain functional and integration tests.
Help in contributing tests is always appreciated :)
Specification
Description
NuNet is a computing platform that provides globally distributed and optimized computing power and storage for decentralized networks, by connecting data owners and computing resources with computational processes in demand of these resources. NuNet provides a layer of intelligent interoperability between computational processes and physical computing infrastructures in an ecosystem which intelligently harnesses latent computing resources of the community into the global network of computations.
Detailed information about the NuNet platform, concepts, architecture, models, stakeholders can be found in these two papers:
DMS (Device Management Service) acts as the foundation of the NuNet platform, orchestrating the complex interactions between various computing resources and users. DMS implementation is structured into packages, creating a more maintainable, scalable, and robust codebase that is easier to understand, test, and collaborate on. Here are the existing packages in DMS and their purposes:
dms
: Responsible for starting the whole application and core DMS functionality such as onboarding, job orchestration, job and resource management, etc.internal
: Code that will not be imported by any other packages and is used only on the running instance of DMS. This includes all configuration-related code, background tasks, etc.db
: Database used by the DMS.storage
: Disk storage management on each DMS for data related to DMS and jobs deployed by DMS. It also acts as an adapter to external storage services.api
: All API functionality (including REST API, etc.) to interact with the DMS.cmd
: Command line functionality and tools.network
: All network-related code such as p2p communication, IP over Libp2p, and other networks that might be needed in the future.executor
: Responsible for executing the jobs received by the DMS. Interface to various executors such as Docker, Firecracker, etc.telemetry
: Logs, traces, and everything related to telemetry.plugins
: Defined entry points and specs for third-party plugins, registration, and execution of plugin code.types
: Contains data models imported by various packages.utils
: Utility tools and functionalities.tokenomics
: Interaction with blockchain for the crypto-micropayments layer of the platform.
Design and Architecture
Conceptual Basis
Main concepts of the architecture of DMS, the main component of the NuNet platform, can be found in the Yellow Paper.
Ontology
The Nunet Ontology, which forms the basis of the design, is explained in the articles below:
Architecture
Refer to the following items to understand DMS architecture at a high level.
Research
Relevant research work that has informed the design of DMS can be found below:
Functionality
DMS is currently being refactored and new functionality will be added.
Data Types
Refer to the DMS global class diagram in this section and various packages for data models.
References
In addition to the relevant links added in the sections above, you can also find useful links here: NuNet Links.
Class Diagram
The global class diagram for the DMS is shown below.
Source File
Last updated