Skip to content

Commit ecfae1a

Browse files
RawanMostafa08RawanMostafa08
authored
Cmds doc (#73)
* doc: flistd documentation * doc: storaged documentation * doc: api_gateway documentation * doc: contd documentation * doc: gateway documentation * doc: networkd documentation * fix: fix documentation typos * doc: powerd documentation * doc: noded documentation * doc: provisiond documentation * doc: qsfsd documentation * doc: zui documentation * doc: vmd documentation * doc: zbusdebug documentation * fix: fix folder structure * doc: internet documentation moved from zos/cmds/internet * doc: identityd documentation * doc: zos documentation
1 parent 050125e commit ecfae1a

File tree

17 files changed

+497
-0
lines changed

17 files changed

+497
-0
lines changed

‎docs/assets/zui.png‎

56.9 KB
Loading

‎docs/cmds/identityd.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Identityd
2+
3+
`Identity manager` is responsible for maintaining the node identity (public key). The manager make sure the node has one valid ID during the entire lifetime of the node. It also provide service to sign, encrypt and decrypt data using the node identity.
4+
On first boot, the identity manager will generate an ID and then persist this ID for life.
5+
6+
`Identityd` is also responsible for Node live software updates.
7+
8+
## How it works
9+
10+
- Connects to `Redis` message broker over `zbus`
11+
- Prints its output according to the passed bool flags
12+
- Do upgrade to latest version (this might means it needs to restart itself), that's why it's implemented as a standalone binary
13+
- Register the node to `BCDB`
14+
- Start `zbus` server to serve identity interface
15+
- Start watcher for new version
16+
- On update, re-register the node with new version to `BCDB`
17+
18+
## Usage
19+
20+
```sh
21+
identityd -root /var/cache/modules/identityd \
22+
> -broker unix:///var/run/redis.sock \
23+
> -interval 600
24+
```
25+
26+
```sh
27+
identityd -v
28+
```
29+
```sh
30+
identityd -d
31+
```
32+
### Command-line flags
33+
34+
| Flag | Description | Default |
35+
| ------------- | --------------------------------------------------------- | ------------------------------- |
36+
| `-broker` | Connection string to the message BROKER | `unix:///var/run/redis.sock` |
37+
| `-root` | ROOT working directory of the module | `/var/cache/modules/identityd` |
38+
| `-interval` | interval in seconds between update check | `600` |
39+
| `-address` | prints the node ss58 address and exits | `false` |
40+
| `-farm` | prints the node farm id and exits | `false` |
41+
| `-d` | (debug) when set, no self update is done before upgrading | `false` |
42+
| `-id` | [deprecated] prints the node ID and exits | `false` |
43+
| `-net` | prints the node network and exits | `false` |
44+
| `-v` | show version and exit | `false` |

‎docs/cmds/internet.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Internet
2+
3+
The internet module is responsible for connecting zos node to the internet.
4+
5+
## How it works
6+
7+
The internet module bootstraps the private zos network as follows:
8+
9+
- Find a physical interface that can get an IPv4 over DHCP or use `priv vlan` if configured as kernel param.
10+
11+
- Create a bridge called `zos` and attach the interface to it.
12+
13+
- Start a DHCP daemon after the Bridge and interface are brought UP to get an IP.
14+
15+
- Test the internet connection by trying to connect to some addresses `"bootstrap.grid.tf:http", "hub.grid.tf:http"`
16+
17+
## Build
18+
19+
The internet binary is build as a part of the build process of zos base image as follows:
20+
21+
- The `0-initramfs` first installs bootstrap.
22+
23+
- The installation builds and copies the internet binary to initramfs root bin along with other bootstrap binaries.

‎docs/cmds/modules/api_gateway.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# API Gateway
2+
3+
API Gateway module acts as the entrypoint for incoming and outgoing requests to access Threefold chain and incoming rmb calls.
4+
5+
## How it works
6+
7+
- Connects to `Redis` message broker over `zbus`
8+
- Loads the node’s identity key.
9+
- Creates a substrate manager to handle blockchain interactions.
10+
- Creates substrate gateway and registers it as the `api-gateway` module.
11+
- Handles incoming `Rmb` calls from nodes and routes them.
12+
- Periodically checks for updates in relay and substrate urls.
13+
14+
## Usage
15+
16+
```sh
17+
api-gateway --broker unix:///var/run/redis.sock \
18+
--workers 2
19+
```
20+
21+
### Command-line flags
22+
23+
| Flag | Description | Default |
24+
| ----------- | -------------------------------------------| ---------------------------- |
25+
| `--broker` | Connection string to the message BROKER | `unix:///var/run/redis.sock` |
26+
| `--workers` | Number of workers N | `1` |

‎docs/cmds/modules/contd.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Contd
2+
3+
Container module is responsible for handling starting, stopping and inspecting of containers.
4+
5+
Contd provides the entrypoint of the contd module, exposing it as a service over the message bus (zbus) so that other modules can handle the containers.
6+
7+
## How it works
8+
9+
- Ensure that `shim-logs` binary is available, backoff until it's found.
10+
- Creates module root directory.
11+
- Connects to `Redis` message broker over `zbus`.
12+
- Register itself as a `containerd` module.
13+
- Starts watching for events coming from `containerd`.
14+
15+
16+
## Usage
17+
18+
```sh
19+
contd --root /var/cache/modules/contd \
20+
> --broker unix:///var/run/redis.sock \
21+
> --congainerd /run/containerd/containerd.sock \
22+
> --workers 2
23+
```
24+
25+
### Command-line flags
26+
27+
| Flag | Description | Default |
28+
| ----------- | ------------------------------------------------| ---------------------------- |
29+
| `--root` | `ROOT` working directory of the module | `/var/cache/modules/contd` |
30+
| `--broker` | Connection string to the message BROKER | `unix:///var/run/redis.sock` |
31+
| `--congainerd` | connection string to containerd `CONTAINERD` | `/run/containerd/containerd.sock` |
32+
| `--workers` | Number of workers N | `1` |

‎docs/cmds/modules/flistd.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Flistd
2+
3+
The flist module is responsible for mounting of flists. The mounted directory contains all the files required by containers or VMs.
4+
5+
Flistd provides the entrypoint of the flist module, exposing it as a service over the message bus (zbus) so that other modules can mount and manage flists.
6+
7+
## How it works
8+
9+
- Connects to `Redis` message broker over `zbus`
10+
- Registers itself as the `flist` module to expose its methods through zbus
11+
- A background cleaner runs every **24h** to remove cached flists that are older than **90 days**
12+
13+
## Usage
14+
15+
```sh
16+
flistd --root /var/cache/modules/flistd \
17+
--broker unix:///var/run/redis.sock \
18+
--workers 2
19+
```
20+
21+
### Command-line flags
22+
23+
| Flag | Description | Default |
24+
| ----------- | -------------------------------------------| ---------------------------- |
25+
| `--broker` | Connection string to the message BROKER | `unix:///var/run/redis.sock` |
26+
| `--root` | ROOT working directory of the module | `/var/cache/modules/flistd` |
27+
| `--workers` | Number of workers N | `1` |

‎docs/cmds/modules/gateway.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Gateway
2+
3+
The gateway modules is used to register traefik routes and services to act as a reverse proxy, forwarding traffic to backend workloads.
4+
5+
cmds/gateway provides the entrypoint of the gateway module, exposing it as a service over the message bus (zbus) so that other modules can use it.
6+
7+
## How it works
8+
9+
- Connects to `Redis` message broker over `zbus`.
10+
- Register itself as a `gateway` module.
11+
12+
## Usage
13+
14+
```sh
15+
gateway --root /var/cache/modules/gateway \
16+
> --broker unix:///var/run/redis.sock \
17+
> --workers 2
18+
```
19+
20+
### Command-line flags
21+
22+
| Flag | Description | Default |
23+
| ----------- | ------------------------------------------------| ---------------------------- |
24+
| `--root` | `ROOT` working directory of the module | `/var/cache/modules/gateway` |
25+
| `--broker` | Connection string to the message BROKER | `unix:///var/run/redis.sock` |
26+
| `--workers` | Number of workers N | `1` |

‎docs/cmds/modules/networkd.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Networkd
2+
Network module handles network resources and user networks.
3+
4+
After the internet process sets up a bridge (zos) which will have an IP address that has Internet access, the rest of the system can be started, where ultimately, the networkd daemon is started.
5+
6+
The networkd daemon receives tasks from the provisioning daemon, so that it can create the necessary resources in the User Network.
7+
8+
## How it works
9+
10+
- Creates `root` directory
11+
- Waits for `yggdrasil` binary to be available
12+
- Checks that the `zos` bridge is created and of the correct type
13+
- Connects to `Redis` message broker over `zbus`
14+
- Ensures the system has the correct existing host `nft` rules
15+
- Creates the public setup, to make sure bridges are created and wired correctly, and initialize public name space. If no exit nic is set the node tries to detect the exit br-pub nic based on the following criteria
16+
- physical nic
17+
- wired and has a signal
18+
- can get public slaac IPv6
19+
if no nic is found zos is selected.
20+
- Creates `ndmz` namespace which represents the router between private user networks and public internet
21+
- Sets up and starts `yggdrasil`
22+
- Sets up and starts `mycelium`
23+
- Creates a `networker` module that can be used over `zbus` and registers itself as the `network` module
24+
25+
## Usage
26+
27+
```sh
28+
networkd --root /var/cache/modules/networkd \
29+
> --broker unix:///var/run/redis.sock
30+
```
31+
32+
### Command-line flags
33+
34+
| Flag | Description | Default |
35+
| ----------- | ------------------------------------------------| ---------------------------- |
36+
| `--root` | `ROOT` working directory of the module | `/var/cache/modules/networkd` |
37+
| `--broker` | Connection string to the message BROKER | `unix:///var/run/redis.sock` |

‎docs/cmds/modules/noded.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Noded
2+
3+
This module is responsible of registering the node on the grid, and handling of grid events. It reports the node’s capacity (CPU, memory, storage, GPU, etc.), monitors performance and health, registers the node on the blockchain.
4+
5+
## How it works
6+
7+
- Connects to `Redis` message broker over `zbus`
8+
- Prints **Node ID** or **Node network** if their flags were passed
9+
- Collects node info:
10+
- Node capacity (CPU, memory, disk)
11+
- Whether the node is booted via `efi`
12+
- `DMI` Info (Desktop Management Interface)
13+
- Name of the hypervisor used on the node
14+
- List of available GPUs, logs GPUs info
15+
- Starts a registrar service and publishes node info
16+
- Registers the node on the blockchain
17+
- Monitor node performance:
18+
- `NTP` check
19+
- `iperf` (network performance measurement)
20+
- `cpubench` (CPU benchmark)
21+
- `public ip` (validity of public ip)
22+
- Streams events to the blockchain
23+
- Keeps track of environment changes (substrate URLs)
24+
25+
## Usage
26+
27+
```sh
28+
noded --broker unix:///var/run/redis.sock
29+
```
30+
31+
```sh
32+
noded --id
33+
```
34+
35+
```sh
36+
noded --net
37+
```
38+
39+
### Command-line flags
40+
41+
| Flag | Description | Default |
42+
| ---------- | ----------------------------------------------- | --------------------------- |
43+
| `--broker` | Connection string to the message BROKER | `unix:///var/run/redis.sock`|
44+
| `--id` | print node id and exit | false |
45+
| `--net` | print node network and exit | false |

‎docs/cmds/modules/powerd.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Powerd
2+
3+
Power module handles the node power events (node uptime reporting, wake on lan, etc...)
4+
5+
## How it works
6+
- Loads the running environment of the node to get the `farmID`
7+
- Connects to `Redis` message broker over `zbus`
8+
- Get node information like `nodeID`, `twinID`
9+
- Loads the node’s identity key.
10+
- Creates a substrate manager, substrate gateway to handle blockchain interactions.
11+
- Reports **node uptime**
12+
- Enables **Wake On Lan** feature if supported
13+
14+
## Usage
15+
16+
```sh
17+
powerd --broker unix:///var/run/redis.sock
18+
```
19+
20+
### Command-line flags
21+
22+
| Flag | Description | Default |
23+
| ----------- | ------------------------------------------------| ---------------------------- |
24+
| `--broker` | Connection string to the message BROKER | `unix:///var/run/redis.sock` |

0 commit comments

Comments
 (0)