You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Identity module is available on zbus over the following channel
6
+
7
+
| module | object | version |
8
+
|--------|--------|---------|
9
+
| identity|[manager](#interface)| 0.0.1|
10
+
11
+
## Home Directory
12
+
13
+
identity keeps some data in the following locations
14
+
15
+
| directory | path|
16
+
|----|---|
17
+
| root|`/var/cache/modules/identity`|
18
+
19
+
## Introduction
20
+
21
+
Identity manager is responsible for node identification on the grid. The manager make sure the node has one valid ID during the entire lifetime of the node, and that node id is registered on the grid.
22
+
23
+
On first boot, the identity manager will generate an ID and then persist this ID for life. The node registration happens to the BCDB once the network is reachable, and after that the node will be available for reservations.
24
+
25
+
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.
26
+
27
+
## On Node Booting
28
+
29
+
- Check if node already has a seed generated
30
+
- If yes, load the node identity
31
+
- If not, generate a new ID
32
+
- Once identity is loaded, register the node to bcdb, this will keep running in the background until successful.
33
+
- Start the zbus daemon.
34
+
35
+
## ID generation
36
+
37
+
At this time of development the ID generated by identityd is the base58 encoded public key of a ed25519 key pair.
38
+
39
+
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.
40
+
41
+
There is an open issue to make this all ID generation compatible with the rest of the Threefold ecosystem: https://github.com/threefoldtech/zos/issues/161
42
+
43
+
## Cryptography
44
+
45
+
The signing and encryption capabilities of the identity module rely on this ed25519 key pair.
46
+
47
+
For signing, it directly used the key pair.
48
+
For public key encryption, the ed25519 key pair is converted to its cure25519 equivalent and then use use to encrypt the data.
49
+
50
+
### zinit unit
51
+
52
+
The zinit unit file of the module specify the command line, test command, and the order where the services need to be booted.
53
+
54
+
`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.
55
+
The identityd daemon is only considered running if the seed file exists.
56
+
57
+
```yaml
58
+
exec: /bin/identityd
59
+
test: test -e /var/cache/modules/identity/seed.txt
60
+
after:
61
+
- storaged
62
+
```
63
+
64
+
## Interface
65
+
66
+
```go
67
+
package pkg
68
+
69
+
// Identifier is the interface that defines
70
+
// how an object can be used as an identity
71
+
type Identifier interface {
72
+
Identity() string
73
+
}
74
+
75
+
// StrIdentifier is a helper type that implement the Identifier interface
76
+
// on top of simple string
77
+
type StrIdentifier string
78
+
79
+
// Identity implements the Identifier interface
80
+
func (s StrIdentifier) Identity() string {
81
+
return string(s)
82
+
}
83
+
84
+
// IdentityManager interface.
85
+
type IdentityManager interface {
86
+
// NodeID returns the node id (public key)
87
+
NodeID() StrIdentifier
88
+
89
+
// FarmID return the farm id this node is part of. this is usually a configuration
90
+
// that the node is booted with. An error is returned if the farmer id is not configured
91
+
FarmID() (StrIdentifier, error)
92
+
93
+
// Sign signs the message with privateKey and returns a signature.
94
+
Sign(message []byte) ([]byte, error)
95
+
96
+
// Verify reports whether sig is a valid signature of message by publicKey.
97
+
Verify(message, sig []byte) error
98
+
99
+
// Encrypt encrypts message with the public key of the node
100
+
Encrypt(message []byte) ([]byte, error)
101
+
102
+
// Decrypt decrypts message with the private of the node
Storage module is available on zbus over the following channel
6
-
7
-
| module | object | version |
8
-
|--------|--------|---------|
9
-
| identity|[manager](#interface)| 0.0.1|
10
-
11
-
## Home Directory
12
-
identity keeps some data in the following locations
13
-
14
-
| directory | path|
15
-
|----|---|
16
-
| root|`/var/cache/modules/identity`|
17
-
18
-
19
3
## Introduction
20
4
21
-
Identity manager is responsible for node identification on the grid. The manager make sure the node has one valid ID during the entire lifetime of the node, and that node id is registered on the grid.
22
-
23
-
On first boot, the identity manager will generate an ID and then persist this ID for life. The node registration happens to the BCDB once the network is reachable, and after that the node will be available for reservations.
24
-
25
-
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.
26
-
27
-
## On Node Booting
28
-
29
-
- Check if node already has a seed generated
30
-
- If yes, load the node identity
31
-
- If not, generate a new ID
32
-
- Once identity is loaded, register the node to bcdb, this will keep running in the background until successful.
33
-
- Start the zbus daemon.
34
-
35
-
## ID generation
36
-
37
-
At this time of development the ID generated by identityd is the base58 encoded public key of a ed25519 key pair.
38
-
39
-
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.
40
-
41
-
There is an open issue to make this all ID generation compatible with the rest of the Threefold ecosystem: https://github.com/threefoldtech/zos/issues/161
42
-
43
-
## Cryptography
44
-
45
-
The signing and encryption capabilities of the identity module rely on this ed25519 key pair.
46
-
47
-
For signing, it directly used the key pair.
48
-
For public key encryption, the ed25519 key pair is converted to its cure25519 equivalent and then use use to encrypt the data.
49
-
50
-
### zinit unit
51
-
52
-
The zinit unit file of the module specify the command line, test command, and the order where the services need to be booted.
53
-
54
-
`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.
55
-
The identityd daemon is only considered running if the seed file exists.
56
-
57
-
```yaml
58
-
exec: /bin/identityd
59
-
test: test -e /var/cache/modules/identity/seed.txt
60
-
after:
61
-
- storaged
62
-
```
63
-
64
-
## Interface
65
-
66
-
```go
67
-
package pkg
68
-
69
-
// Identifier is the interface that defines
70
-
// how an object can be used as an identity
71
-
type Identifier interface {
72
-
Identity() string
73
-
}
74
-
75
-
// StrIdentifier is a helper type that implement the Identifier interface
76
-
// on top of simple string
77
-
type StrIdentifier string
78
-
79
-
// Identity implements the Identifier interface
80
-
func (s StrIdentifier) Identity() string {
81
-
return string(s)
82
-
}
83
-
84
-
// IdentityManager interface.
85
-
type IdentityManager interface {
86
-
// NodeID returns the node id (public key)
87
-
NodeID() StrIdentifier
88
-
89
-
// FarmID return the farm id this node is part of. this is usually a configuration
90
-
// that the node is booted with. An error is returned if the farmer id is not configured
91
-
FarmID() (StrIdentifier, error)
92
-
93
-
// Sign signs the message with privateKey and returns a signature.
94
-
Sign(message []byte) ([]byte, error)
95
-
96
-
// Verify reports whether sig is a valid signature of message by publicKey.
97
-
Verify(message, sig []byte) error
98
-
99
-
// Encrypt encrypts message with the public key of the node
100
-
Encrypt(message []byte) ([]byte, error)
5
+
Identity daemon is responsible for major two operations that is crucial for the node operation
101
6
102
-
// Decrypt decrypts message with the private of the node
103
-
Decrypt(message []byte) ([]byte, error)
104
-
}
105
-
```
7
+
-[Node ID generation and registration on the grid](identity.md)
Copy file name to clipboardExpand all lines: docs/identity/upgrade.md
+9-37Lines changed: 9 additions & 37 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,33 +1,5 @@
1
1
# Upgrade module
2
2
3
-
## Zbus
4
-
5
-
Upgrade module is available on zbus over the following channel
6
-
7
-
| module | object | version |
8
-
|--------|--------|---------|
9
-
|upgrade |[upgrade](#public-interface)| 0.0.1
10
-
11
-
## Public interface [](https://godoc.org/github.com/threefoldtech/zos/pkg/upgrade#Upgrader.Version)
12
-
13
-
```go
14
-
typeUpgradeModuleinterface {
15
-
// version return the current version 0-OS is running
16
-
Version() (semver.Version, error)
17
-
}
18
-
```
19
-
20
-
21
-
## Home Directory
22
-
Upgraded does not have a home directory, although it can keep track of some files under /tmp. The reason that those files
23
-
are kept in a tmpfs filesystem, and not persisted on disk is that they are only needed during the runtime. On reboot new
24
-
files will be written. More on that later
25
-
26
-
## zinit unit
27
-
28
-
Upgrade module depends on network and flist module. This is because is requires network connection to check for new update and the flist module to download the upgrade flist on the node.
29
-
30
-
31
3
## Philosophy
32
4
33
5
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.
@@ -40,10 +12,11 @@ The run mode defines which flist the node is going to use to boot. Run mode can
40
12
- 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.
41
13
- 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.
42
14
43
-
44
15
## Booting a new node
16
+
45
17
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
46
18
after initial start of the system, the boot program kicks in and it does the following:
19
+
47
20
- Detect the boot flist that the node must use to fully start. The default is hard-coded into the image, 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.
48
21
- 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.
49
22
- The flist information (name, and version) is saved under `/tmp/flist.name` and `/tmp/flist.info`.
@@ -53,16 +26,17 @@ after initial start of the system, the boot program kicks in and it does the fol
53
26
- Boot process continues.
54
27
55
28
## Runtime upgrade of a node
56
-
Once the node is up and running, upgraded takes over and it does the following:
29
+
30
+
Once the node is up and running, identityd takes over and it does the following:
31
+
57
32
- It loads the boot info files `/tmp/flist.name` and `/tmp/flist.info`
58
-
- If the `flist.name` file does **not** exist, `upgraded` will assume the node is booted with other means than an flist (for example overlay). In that case, upgraded will log this, and disable live upgrade of the node.
33
+
- 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.
59
34
- 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.
60
-
- Once the flist change is detected, upgraded will mount the flist, make sure upgraded is running the latest version. If not, upgraded will update itself first before continuing.
35
+
- 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.
61
36
- services that will need update will be gracefully stopped.
62
-
-`upgraded` will then make sure to update all services from the flist, and config files. and restart the services properly.
37
+
-`identityd` will then make sure to update all services from the flist, and config files. and restart the services properly.
63
38
- services are started again after all binaries has been copied
64
39
65
-
66
40
## Technical
67
41
68
42
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).
0 commit comments