updated smaller collections for manual
This commit is contained in:
@@ -0,0 +1,143 @@
|
||||
<h1> Node ID Generation</h1>
|
||||
|
||||
<h2> Table of Contents </h2>
|
||||
|
||||
- [Introduction](#introduction)
|
||||
- [ZBus](#zbus)
|
||||
- [Home Directory](#home-directory)
|
||||
- [Introduction](#introduction-1)
|
||||
- [On Node Booting](#on-node-booting)
|
||||
- [ID generation](#id-generation)
|
||||
- [Cryptography](#cryptography)
|
||||
- [zinit unit](#zinit-unit)
|
||||
- [Interface](#interface)
|
||||
|
||||
***
|
||||
|
||||
## Introduction
|
||||
|
||||
We explain the node ID generation process.
|
||||
|
||||
## ZBus
|
||||
|
||||
Identity module is available on zbus over the following channel
|
||||
|
||||
| module | object | version |
|
||||
|--------|--------|---------|
|
||||
| identity|[manager](#interface)| 0.0.1|
|
||||
|
||||
## Home Directory
|
||||
|
||||
identity keeps some data in the following locations
|
||||
|
||||
| directory | path|
|
||||
|----|---|
|
||||
| root| `/var/cache/modules/identity`|
|
||||
|
||||
## Introduction
|
||||
|
||||
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.
|
||||
|
||||
On first boot, the identity manager will generate an ID and then persist this ID for life.
|
||||
|
||||
Since the identity daemon is the only one that can access the node private key, it provides an interface to sign, verify and encrypt data. This methods are available for other modules on the local node to use.
|
||||
|
||||
## On Node Booting
|
||||
|
||||
- Check if node already has a seed generated
|
||||
- If yes, load the node identity
|
||||
- If not, generate a new ID
|
||||
- Start the zbus daemon.
|
||||
|
||||
## ID generation
|
||||
|
||||
At this time of development the ID generated by identityd is the base58 encoded public key of a ed25519 key pair.
|
||||
|
||||
The key pair itself is generated from a random seed of 32 bytes. It is this seed that is actually saved on the node. And during boot the key pair is re-generated from this seed if it exists.
|
||||
|
||||
## Cryptography
|
||||
|
||||
The signing and encryption capabilities of the identity module rely on this ed25519 key pair.
|
||||
|
||||
For signing, it directly used the key pair.
|
||||
For public key encryption, the ed25519 key pair is converted to its cure25519 equivalent and then use use to encrypt the data.
|
||||
|
||||
### zinit unit
|
||||
|
||||
The zinit unit file of the module specify the command line, test command, and the order where the services need to be booted.
|
||||
|
||||
`identityd` require `storaged` to make sure the seed is persisted over reboots, to make sure node has the same ID during the full life time of the node.
|
||||
The identityd daemon is only considered running if the seed file exists.
|
||||
|
||||
```yaml
|
||||
exec: /bin/identityd
|
||||
test: test -e /var/cache/modules/identity/seed.txt
|
||||
after:
|
||||
- storaged
|
||||
```
|
||||
|
||||
## Interface
|
||||
|
||||
For an up to date interface please check code [here](https://github.com/threefoldtech/zos/blob/main/pkg/identity.go)
|
||||
```go
|
||||
package pkg
|
||||
|
||||
// Identifier is the interface that defines
|
||||
// how an object can be used as an identity
|
||||
type Identifier interface {
|
||||
Identity() string
|
||||
}
|
||||
|
||||
// StrIdentifier is a helper type that implement the Identifier interface
|
||||
// on top of simple string
|
||||
type StrIdentifier string
|
||||
|
||||
// Identity implements the Identifier interface
|
||||
func (s StrIdentifier) Identity() string {
|
||||
return string(s)
|
||||
}
|
||||
|
||||
// IdentityManager interface.
|
||||
type IdentityManager interface {
|
||||
// NodeID returns the node id (public key)
|
||||
NodeID() StrIdentifier
|
||||
|
||||
// NodeIDNumeric returns the node registered ID.
|
||||
NodeIDNumeric() (uint32, error)
|
||||
|
||||
// FarmID return the farm id this node is part of. this is usually a configuration
|
||||
// that the node is booted with. An error is returned if the farmer id is not configured
|
||||
FarmID() (FarmID, error)
|
||||
|
||||
// Farm returns name of the farm. Or error
|
||||
Farm() (string, error)
|
||||
|
||||
//FarmSecret get the farm secret as defined in the boot params
|
||||
FarmSecret() (string, error)
|
||||
|
||||
// Sign signs the message with privateKey and returns a signature.
|
||||
Sign(message []byte) ([]byte, error)
|
||||
|
||||
// Verify reports whether sig is a valid signature of message by publicKey.
|
||||
Verify(message, sig []byte) error
|
||||
|
||||
// Encrypt encrypts message with the public key of the node
|
||||
Encrypt(message []byte) ([]byte, error)
|
||||
|
||||
// Decrypt decrypts message with the private of the node
|
||||
Decrypt(message []byte) ([]byte, error)
|
||||
|
||||
// EncryptECDH aes encrypt msg using a shared key derived from private key of the node and public key of the other party using Elliptic curve Diffie Helman algorithm
|
||||
// the nonce if prepended to the encrypted message
|
||||
EncryptECDH(msg []byte, publicKey []byte) ([]byte, error)
|
||||
|
||||
// DecryptECDH decrypt aes encrypted msg using a shared key derived from private key of the node and public key of the other party using Elliptic curve Diffie Helman algorithm
|
||||
DecryptECDH(msg []byte, publicKey []byte) ([]byte, error)
|
||||
|
||||
// PrivateKey sends the keypair
|
||||
PrivateKey() []byte
|
||||
}
|
||||
|
||||
// FarmID is the identification of a farm
|
||||
type FarmID uint32
|
||||
```
|
||||
@@ -0,0 +1,8 @@
|
||||
<h1> Identity Module </h1>
|
||||
|
||||
Identity daemon is responsible for two major operations that are crucial for the node operation.
|
||||
|
||||
<h2> Table of Contents </h2>
|
||||
|
||||
- [Node ID Generation](identity.md)
|
||||
- [Node Live Software Update](upgrade.md)
|
||||
@@ -0,0 +1,98 @@
|
||||
<h1> Node Upgrade</h1>
|
||||
|
||||
<h2> Table of Contents </h2>
|
||||
|
||||
- [Introduction](#introduction)
|
||||
- [Philosophy](#philosophy)
|
||||
- [Booting a new node](#booting-a-new-node)
|
||||
- [Runtime upgrade of a node](#runtime-upgrade-of-a-node)
|
||||
- [Technical](#technical)
|
||||
- [Flist layout](#flist-layout)
|
||||
|
||||
***
|
||||
|
||||
## Introduction
|
||||
|
||||
We provide information concerning node upgrade with ZOS. We also explain the philosophy behind ZOS.
|
||||
|
||||
## Philosophy
|
||||
|
||||
0-OS is meant to be a black box no one can access. While this provide some nice security features it also makes it harder to manage. Specially when it comes to update/upgrade.
|
||||
|
||||
Hence, zos only trust few sources for upgrade packages. When the node boots up it checks the sources for the latest release and make sure all the local binaries are up-to-date before continuing the booting. The flist source must be rock-solid secured, that's another topic for different documentation.
|
||||
|
||||
The run mode defines which flist the node is going to use to boot. Run mode can be specified by passing `runmode=<mode>` to the kernel boot params. Currently we have those different run modes.
|
||||
|
||||
- dev: ephemeral network only setup to develop and test new features. Can be created and reset at anytime
|
||||
- test: Mostly stable features that need to be tested at scale, allow preview and test of new features. Always the latest and greatest. This network can be reset sometimes, but should be relatively stable.
|
||||
- prod: Released of stable version. Used to run the real grid with real money. Cannot be reset ever. Only stable and battle tested feature reach this level.
|
||||
|
||||
## Booting a new node
|
||||
|
||||
The base image for zos contains a very small subset of tools, plus the boot program. Standing alone, the image is not really useful. On boot and
|
||||
after initial start of the system, the boot program kicks in and it does the following:
|
||||
|
||||
- Detect the boot flist that the node must use to fully start. The default is hard-coded into zos, but this can be overridden by the `flist=` kernel param. The `flist=` kernel param can get deprecated without a warning, since it's a development flag.
|
||||
- The bootstrap, will then mount this flist using 0-fs, this of course requires a working connection to the internet. Hence bootstrap is configured to wait for the `internet` service.
|
||||
- The flist information (name, and version) is saved under `/tmp/flist.name` and `/tmp/flist.info`.
|
||||
- The bootstrap makes sure to copy all files in the flist to the proper locations under the system rootfs, this include `zinit` config files.
|
||||
- Then zinit is asked to monitor new installed services, zinit takes care of those services and make sure they are properly working at all times.
|
||||
- Bootstrap, umounts the flist, cleans up before it exits.
|
||||
- Boot process continues.
|
||||
|
||||
## Runtime upgrade of a node
|
||||
|
||||
Once the node is up and running, identityd takes over and it does the following:
|
||||
|
||||
- It loads the boot info files `/tmp/flist.name` and `/tmp/flist.info`
|
||||
- If the `flist.name` file does **not** exist, `identityd` will assume the node is booted with other means than an flist (for example overlay). In that case, identityd will log this, and disable live upgrade of the node.
|
||||
- If the `flist.name` file exists, the flist will be monitored on the `https://hub.grid.tf` for changes. Any change in the version will initiate a life upgrade routine.
|
||||
- Once the flist change is detected, identityd will mount the flist, make sure identityd is running the latest version. If not, identityd will update itself first before continuing.
|
||||
- services that will need update will be gracefully stopped.
|
||||
- `identityd` will then make sure to update all services from the flist, and config files. and restart the services properly.
|
||||
- services are started again after all binaries has been copied
|
||||
|
||||
## Technical
|
||||
|
||||
0-OS is designed to provide maximum uptime for its workload, rebooting a node should never be required to upgrade any of its component (except when we push a kernel upgrade).
|
||||
|
||||
|
||||
|
||||
### Flist layout
|
||||
|
||||
The files in the upgrade flist needs to be located in the filesystem tree at the same destination they would need to be in 0-OS. This allow the upgrade code to stays simple and only does a copy from the flist to the root filesystem of the node.
|
||||
|
||||
Booting a new node, or updating a node uses the same flist. Hence, a boot flist must container all required services for node operation.
|
||||
|
||||
Example:
|
||||
|
||||
0-OS filesystem:
|
||||
|
||||
```
|
||||
/etc/zinit/identityd.yaml
|
||||
/etc/zinit/networkd.yaml
|
||||
/etc/zinit/contd.yaml
|
||||
/etc/zinit/init/node-ready.sh
|
||||
/etc/zinit/init
|
||||
/etc/zinit/redis.yaml
|
||||
/etc/zinit/storaged.yaml
|
||||
/etc/zinit/flistd.yaml
|
||||
/etc/zinit/readme.md
|
||||
/etc/zinit/internet.yaml
|
||||
/etc/zinit/containerd.yaml
|
||||
/etc/zinit/boot.yaml
|
||||
/etc/zinit/provisiond.yaml
|
||||
/etc/zinit/node-ready.yaml
|
||||
/etc/zinit
|
||||
/etc
|
||||
/bin/zlf
|
||||
/bin/provisiond
|
||||
/bin/flistd
|
||||
/bin/identityd
|
||||
/bin/contd
|
||||
/bin/capacityd
|
||||
/bin/storaged
|
||||
/bin/networkd
|
||||
/bin/internet
|
||||
/bin
|
||||
```
|
||||
Reference in New Issue
Block a user