interesting
/
go-ethereum
mirror of https://github.com/ethereum/go-ethereum.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update wnode instructions (#19449)

This commit is contained in:
Guillaume Ballet 2019-04-11 18:39:12 +02:00 committed by GitHub
parent 6e313f0a6d
commit b79ae69e15
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 170 additions and 145 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

315
docs/_whisper/Diagnostic-Tool-wnode.md
View File

@ -1,7 +1,7 @@
--- ---
title: Diagnostic tool wnode title: Diagnostic tool wnode
--- ---
## Wnode # Wnode
Wnode (whisper node) is a command-line diagnostic tool. It does not have a nice user interface, because its main purpose is diagnostic, and it's meant to be very light-weight rather than beautiful. Wnode might be used for different purposes, including: Wnode (whisper node) is a command-line diagnostic tool. It does not have a nice user interface, because its main purpose is diagnostic, and it's meant to be very light-weight rather than beautiful. Wnode might be used for different purposes, including:
@ -13,207 +13,223 @@ Wnode (whisper node) is a command-line diagnostic tool. It does not have a nice
- running fully functional mail server - running fully functional mail server
- testing functionality of mail client - testing functionality of mail client
#### Usage ## Usage
> wnode [flags/arguments] ```
> wnode [flags/arguments]
```
For example: ## Flags & Switches
> wnode -forwarder -standalone -ip=127.0.0.1:30381 -idfile=config.txt -mailserver -dbpath=tmp/db In case an argument is missing, `wnode` will either use the default value or prompt the user at startup. For security reasons, it is not possible to provide passwords in command-line arguments. In `test` mode, a hardcoded password ("test") is used.
#### Flags `-asym`: use asymmetric encryption in the chat
-asym: use asymmetric encryption in the chat `-boot`: A string representing the bootstrap node to connect to. For example:
-fileexchange: file exchange mode (send and receive files instead of text messages) ```
-forwarder: forwarder mode (only forward; neither send nor decrypt messages)
-mailserver: mail server mode (delivers expired messages on demand)
-mailclient: request expired messages from the mail server
-standalone: don't actively connect to any peers, wait for incoming connections instead
-test: use of predefined parameters for diagnostics, including passwords
-generatekey: generate a new private key (ECIES) and exit
#### Arguments
In case of missing arguments wnode will either use default value or ask you to provide them. For security reasons, you can not provide passwords in command-line arguments. Only in test mode hardcoded passwords are used.
-verbosity:
Verbosity level of logging. Int value between 0 and 5. Default value 1. For example: -verbosity=5.
-ttl:
Time-to-live for messages in seconds. Default value 30. For example: -ttl=20.
-maxsize:
Maximum allowed message size in bytes.
-work:
Maximum time in seconds allowed to spend on proof of work in order to achieve the target (set by 'pow' argument).
-pow:
PoW target for normal messages in float format (e.g. -pow=2.7).
-mspow:
PoW requirement for Mail Server request.
-ip:
IP address and port of this node (e.g. 127.0.0.1:30303).
-pub:
Public key of your peer (for asymmetric encryption). For example:
-pub=0x07af49cbe6353b8732a8b9eb20dd1472f3d4512cd1a11382ee2817cc6de9453bc07c32c730b93bc83877b11e4f47d718751297f4edcbf35015df2b34ff5fc6a75d
-idfile:
File name containing node ID (private key) in hexadecimal string format.
For example: -idfile=/home/vlad/tmp/config
Example of the file content: b3651aff593ef395ee7c16f3ca681830f7d8d0b2729cf472b14f2c4ebe833aa0
-boot:
The bootstrap node you want to connect to. For example:
-boot=enode://d25474361659861e9e651bc728a17e807a3359ca0d344afd544ed0f11a31faecaf4d74b55db53c6670fd624f08d5c79adfc8da5dd4a11b9213db49a3b750845e@52.178.209.125:30379 -boot=enode://d25474361659861e9e651bc728a17e807a3359ca0d344afd544ed0f11a31faecaf4d74b55db53c6670fd624f08d5c79adfc8da5dd4a11b9213db49a3b750845e@52.178.209.125:30379
```
-topic: `-dbpath`: The path to the server's DB directory, for incoming messages to be stored
Message topic in hexadecimal format. For example: -topic=70a4beef.
-dbpath: `-echo`: prints some arguments for diagnostics
Path to directory where Mail Server will store the incoming messages.
For example: -dbpath=tmp/myfiles/archive
-savedir: `-fileexchange`: file exchange mode (send and receive files instead of text messages)
Directory where successfully decrypted incoming messages will be saved as files in plain format.
Message hashes will be used as file names in order to avoid collisions.
By default, only big messages are stored there.
In 'fileexchange' mode all messages are stored there.
### Scenarios & Examples `-filereader`: load and decrypt messages saved as files, display as plain text
For simplicity, in these examples we assume that we only use wnode to communicate with another wnode. `-forwarder`: forwarder mode (only forward; neither send nor decrypt messages)
#### Start a bootstrap node for test network `-generatekey`: generate and show the private key, and exit
> wnode -standalone -forwarder -ip=127.0.0.1:30379 `-idfile`: file name containing a node ID (private key) in hexadecimal format
result output: `-ip`: IP address and port of this node (e.g. 127.0.0.1:30303)
my public key: 0x040ef7acd60781c336c52056b3782f7eae45be2063e591ac6b78472dc27ba770010bde445ffd2f3623ad656f3859e00d11ef518df4916c4d4e258c60b15f34c682 enode://15454fc65bbf0031155f4eee83fa732f1454c314e9f78ade9cba4d4a098d29edbf5431764ee65b200169025c3f900cacc3348a000dda7a8a0d9643d0b7618712@127.0.0.1:30379 `-mailclient`: request expired messages from the mail server
Bootstrap Whisper node started
`-mailserver`: mail server mode (delivers expired messages on demand)
`maxsize`: max size of message (default 1048576)
`-mspow`: PoW requirement for Mail Server request (default 0.2)
`-pow`: PoW for normal messages in float format (e.g. 2.7) (default 0.2)
`-pub`: public key for asymmetric encryption. For example:
```
-pub=0x07af49cbe6353b8732a8b9eb20dd1472f3d4512cd1a11382ee2817cc6de9453bc07c32c730b93bc83877b11e4f47d718751297f4edcbf35015df2b34ff5fc6a75d
```
`-savedir`: directory where all incoming messages will be saved as files. Only big messages are stored there, except in `fileexchange` mode where all files are stored there.
`-standalone`: don't actively connect to any peers, wait for incoming connections instead
`-test`: use of predefined parameters for diagnostics, including passwords
`-topic`: topic in hexadecimal format (e.g. 70a4beef)
`-ttl`: time-to-live for messages in seconds (default 30)
`-verbosity`: log verbosity level (default 1)
`-work`: work time in seconds (default 5)
## Scenarios & Examples
For simplicity, in these examples we assume that we only use `wnode` to communicate with another wnode.
### Start a bootstrap node for test network
```
$ wnode -standalone -forwarder -ip=127.0.0.1:30379
my public key: 0x040ef7acd60781c336c52056b3782f7eae45be2063e591ac6b78472dc27ba770010bde445ffd2f3623ad656f3859e00d11ef518df4916c4d4e258c60b15f34c682 enode://15454fc65bbf0031155f4eee83fa732f1454c314e9f78ade9cba4d4a098d29edbf5431764ee65b200169025c3f900cacc3348a000dda7a8a0d9643d0b7618712@127.0.0.1:30379
Bootstrap Whisper node started
```
### Connecting to a bootstrap node
After the bootstrap node has started, another local node can connect to it, using the resulting enode: After the bootstrap node has started, another local node can connect to it, using the resulting enode:
> wnode -test -boot=enode://15454fc65bbf0031155f4eee83fa732f1454c314e9f78ade9cba4d4a098d29edbf5431764ee65b200169025c3f900cacc3348a000dda7a8a0d9643d0b7618712@127.0.0.1:30379 ```
$ wnode -test -boot=enode://15454fc65bbf0031155f4eee83fa732f1454c314e9f78ade9cba4d4a098d29edbf5431764ee65b200169025c3f900cacc3348a000dda7a8a0d9643d0b7618712@127.0.0.1:30379
............................
Whisper node started
Connected to peer.
............................
```
result output: ### Persistent ID
............................ Upon restarting the bootstrap node, its enode will be different, because the ID is randomly generated. For persistence accross restarts, it is possible to specify an ID stored in a file using the 'idfile' argument.
Whisper node started
Connected to peer.
............................
Now, if you restart you bootstrap node, its enode will be different, because new ID will be randomly generated. If you need to repeat the tests multiple times, it will be extremely boring to copy and paste new enode every time you restart. Instead, you can load ID from file using 'idfile' argument.
Generating ID: Generating ID:
> wnode -generatekey ```
$ wnode -generatekey > pk1.txt
$ cat pk1.txt
b3651aff593ef395ee7c16f3ca681830f7d8d0b2729cf472b14f2c4ebe833aa0
```
result: `pk1.txt` now contains the key used to generate the ID.
c74ea2702eb32f523acb118649998e1c8b5690cf0a14bffda7e87b411db3499a
Then save it to file:
> echo c74ea2702eb32f523acb118649998e1c8b5690cf0a14bffda7e87b411db3499a > pk1.txt
Then start the bootstrap node with persistent ID: Starting the bootstrap node with a persistent ID:
> wnode -forwarder -standalone -ip=127.0.0.1:30379 -idfile=pk1.txt ```
bootnode $ wnode -forwarder -standalone -ip=127.0.0.1:30379 -idfile=pk1.txt
result: my public key: 0x04be81a00a90f5c21ead8887eaa254b3f7a37e06f8f2d776dcc46954a228bc50c6fb6dfd155f7e44e6fef9b62fdf6dad041759b864d2cbe4089b6f5c16a817ff46 enode://7d13360f5b1ddcf6947f244639113597a863abba0589d2fa5fffb2816ead0acea6211d5778a8be648e45e81ed881f4c1f5c9bbbf0e79065dfb54bcd97de3beab@127.0.0.1:30379
my public key: 0x04be81a00a90f5c21ead8887eaa254b3f7a37e06f8f2d776dcc46954a228bc50c6fb6dfd155f7e44e6fef9b62fdf6dad041759b864d2cbe4089b6f5c16a817ff46 enode://7d13360f5b1ddcf6947f244639113597a863abba0589d2fa5fffb2816ead0acea6211d5778a8be648e45e81ed881f4c1f5c9bbbf0e79065dfb54bcd97de3beab@127.0.0.1:30379
Filter is configured for the topic: 5a4ea131 Filter is configured for the topic: 5a4ea131
Bootstrap Whisper node started Bootstrap Whisper node started
```
Now you can always use the same command to connect to your bootstrap node: Now you can always use the same command to connect to your bootstrap node:
> wnode -test -boot=enode://7d13360f5b1ddcf6947f244639113597a863abba0589d2fa5fffb2816ead0acea6211d5778a8be648e45e81ed881f4c1f5c9bbbf0e79065dfb54bcd97de3beab@127.0.0.1:30379 ```
othernode $ wnode -test -boot=enode://7d13360f5b1ddcf6947f244639113597a863abba0589d2fa5fffb2816ead0acea6211d5778a8be648e45e81ed881f4c1f5c9bbbf0e79065dfb54bcd97de3beab@127.0.0.1:30379
```
Please note that ID file is stored unencrypted. It should be used only for test purposes. Be aware that the ID is stored unencrypted. This feature should only be used for test purposes.
Of course, two local whisper nodes are only useful for the most basic tests. In order to set up a bootstrap node on a server with a dedicated IP address, its IP and port need to be specified explicitly:
In order to set up a bootstrap node on a server with dedicated IP address, you need to specify its IP explicitly:
> wnode -forwarder -standalone -ip=52.178.211.103:30379 ```
bootnode $ wnode -forwarder -standalone -ip=52.178.211.103:30379
```
#### Chat ### Using a mail server
Now we will start a chat between two or more nodes sharing the same password, using symmetric encryption. One of the nodes should be started with 'standalone' flag, and another must connect to the first one. It is easy to do on the same machine or on a dedicated server. But what if two peers are behind distinct NAT? In that case, you need a third bootstrap node on a dedicated server, which both peers can connect to. At the time of writing we have out test node with the following enode: The mailserver is only provided as an example for people interested in building their own solution. It is not supported.
enode://d25474361659861e9e651bc728a17e807a3359ca0d344afd544ed0f11a31faecaf4d74b55db53c6670fd624f08d5c79adfc8da5dd4a11b9213db49a3b750845e@52.178.209.125:30379,
```
$ wnode -forwarder -standalone -ip=127.0.0.1:30381 -idfile=config.txt -mailserver -dbpath=tmp/db
```
### Chat with symmetric encryption
For two nodes to communicate using symmetric encryption, one of them must assume the role of a bootstrap node, and the second one that of the client. The bootstrap node is started with the `standalone` flag, and the client must connect to it. It is easy to do on the same machine or on a dedicated server. But what if two peers are behind distinct NAT? In that case, you need a third bootstrap node on a dedicated server, which both peers can connect to. At the time of writing we have out test node with the following enode:
`enode://d25474361659861e9e651bc728a17e807a3359ca0d344afd544ed0f11a31faecaf4d74b55db53c6670fd624f08d5c79adfc8da5dd4a11b9213db49a3b750845e@52.178.209.125:30379`,
to which both peers can connect with the following command: to which both peers can connect with the following command:
> wnode -boot=enode://d25474361659861e9e651bc728a17e807a3359ca0d344afd544ed0f11a31faecaf4d74b55db53c6670fd624f08d5c79adfc8da5dd4a11b9213db49a3b750845e@52.178.209.125:30379 ```
bootnode $ wnode -boot=enode://d25474361659861e9e651bc728a17e807a3359ca0d344afd544ed0f11a31faecaf4d74b55db53c6670fd624f08d5c79adfc8da5dd4a11b9213db49a3b750845e@52.178.209.125:30379
```
Then you will be prompted to enter the password for symmetric encryption. From this password symmetric key will be derived. The topic will be derived from the password as well, unless you provide your own (which is strongly encouraged for any meaningful communication): The user is prompted for the symmetric encryption password. The symmetric key is derived from this password. The topic will be derived from the password as well, unless it's provided by the user on the command line (which is strongly encouraged for any meaningful communication):
> wnode -topic=a6fcb30d -boot=enode://d25474361659861e9e651bc728a17e807a3359ca0d344afd544ed0f11a31faecaf4d74b55db53c6670fd624f08d5c79adfc8da5dd4a11b9213db49a3b750845e@52.178.209.125:30379 ```
othernode $ wnode -topic=a6fcb30d -boot=enode://d25474361659861e9e651bc728a17e807a3359ca0d344afd544ed0f11a31faecaf4d74b55db53c6670fd624f08d5c79adfc8da5dd4a11b9213db49a3b750845e@52.178.209.125:30379
```
Now you can type text messages: The communication is therefore established. Typing message in one console will echo:
hello world! ```
hello world!
1493061848 <031792461900245c6919c4b23447ef8ba43f79a2>: hello world! 1493061848 <031792461900245c6919c4b23447ef8ba43f79a2>: hello world!
```
You will see your own message successfully decrypted and printed on the screen. The first number (1493061848) is UNIX time in seconds. This format is useful for Mail Client/Server tests. The number in brackets is ID with which the message is signed. In this case -- your own ID. If you see only zeros there, it means the message is not signed, although encrypted with the right key. Another wnode peer will show the same output: The first number (1493061848) is UNIX timestamp. This format is useful for Mail Client/Server tests. The number in brackets is the ID with which the message is signed. Seeing an ID with only zeros means the message is not signed, although encrypted with the right key. Another `wnode` peer will show the same output:
1493061848 [031792461900245c6919c4b23447ef8ba43f79a2]: hello world! ```
1493061848 [031792461900245c6919c4b23447ef8ba43f79a2]: hello world!
```
Almost the same, only the brackets are different, indicating that this is not its own message -- originated from somebody else. Only the brackets are different, indicating that this message originated from another identity.
#### Chat with Asymmetric Encryption ### Chat with Asymmetric Encryption
Connect both peers to the same bootstrap node again, but this time with 'asym' flag: Using asymmetric encryption is as simple as using the `-asym` flag:
> wnode -topic=a6fcb30d -asym -boot=enode://d25474361659861e9e651bc728a17e807a3359ca0d344afd544ed0f11a31faecaf4d74b55db53c6670fd624f08d5c79adfc8da5dd4a11b9213db49a3b750845e@52.178.209.125:30379 ```
othernode $ wnode -topic=a6fcb30d -asym -boot=enode://d25474361659861e9e651bc728a17e807a3359ca0d344afd544ed0f11a31faecaf4d74b55db53c6670fd624f08d5c79adfc8da5dd4a11b9213db49a3b750845e@52.178.209.125:30379
result: my public key: 0x0405007821171295a716c9d091371e836e98a5206d5b9ce9177df90c83fc308ebae2786a9c7bff999ad83d12be08e597d4b5a5240f3bb0bc366f008b7d0908df8a
enode://efe233263c78482111ba6c058ccc69b7a2ea3372774733def4fd5a357dfbaa67657e665078d573f11876fd2b7d75d41926976f41e257f91b486e9d36f4143c8a@[::]:42562
Whisper node started
Connected to peer.
Please enter the peer's public key:
```
my public key: 0x0405007821171295a716c9d091371e836e98a5206d5b9ce9177df90c83fc308ebae2786a9c7bff999ad83d12be08e597d4b5a5240f3bb0bc366f008b7d0908df8a First line of the output contains the key which should be passed to another peer, and vice versa. Once both clients have entered their peer's public key, the chat session is active.
enode://efe233263c78482111ba6c058ccc69b7a2ea3372774733def4fd5a357dfbaa67657e665078d573f11876fd2b7d75d41926976f41e257f91b486e9d36f4143c8a@[::]:42562
Whisper node started
Connected to peer.
Please enter the peer's public key:
First line of the output contains the key which should be passed to anther peer, and vice versa. Then you can proceed with the chat as in the previous case. ### Sending and receiving files
#### Sending and receiving files File exchange is activated with the `fileexchange` flags. Examples here use the `-test` flag for simplicity. Assuming that the incoming messages are to be stored in `/home/tester/tmp/msg`, the resulting command line is:
Start wnode with 'fileexchange' flag, and 'test' flag for simplicity. Suppose we want to store the incoming messages in the directory /home/tester/tmp/msg. In that case: ```
bootnode $ wnode -standalone -ip=127.0.0.1:30379 -idfile=pk1.txt -fileexchange -savedir=/home/tester/tmp/msg
enode://7d13360f5b1ddcf6947f244639113597a863abba0589d2fa5fffb2816ead0acea6211d5778a8be648e45e81ed881f4c1f5c9bbbf0e79065dfb54bcd97de3beab@127.0.0.1:30379
```
> wnode -standalone -ip=127.0.0.1:30379 -idfile=pk1.txt -fileexchange -savedir=/home/tester/tmp/msg To send a file to this first `wnode`, type:
Now, start another wnode and connect to the first one: ```
othernode $ wnode -test -boot=enode://7d13360f5b1ddcf6947f244639113597a863abba0589d2fa5fffb2816ead0acea6211d5778a8be648e45e81ed881f4c1f5c9bbbf0e79065dfb54bcd97de3beab@127.0.0.1:30379
```
> wnode -test -boot=enode://7d13360f5b1ddcf6947f244639113597a863abba0589d2fa5fffb2816ead0acea6211d5778a8be648e45e81ed881f4c1f5c9bbbf0e79065dfb54bcd97de3beab@127.0.0.1:30379 Typing messages in the console of the second node, will cause the first one to display something like this:
After you will type and send messages from the second node, you will see the first one to display something like this: ```
1493124416 {624fdf6983940c7ffa8a4742f76dc78ae9775c47}: message received and saved as 'aa6f339e830c86718ddf4254038dd9fa8da6494e3f3c856af500a5aeaf0df62d' (4 bytes)
```
1493124416 {624fdf6983940c7ffa8a4742f76dc78ae9775c47}: message received and saved as 'aa6f339e830c86718ddf4254038dd9fa8da6494e3f3c856af500a5aeaf0df62d' (4 bytes) Messages are not displayed, but saved instead. Examine the contents of `/home/tester/tmp/msg/aa6f339e830c86718ddf4254038dd9fa8da6494e3f3c856af500a5aeaf0df62d` to confirm that the message is saved there.
As you see, messages are not displayed, but saved instead. Now you can open the file /home/tester/tmp/msg/aa6f339e830c86718ddf4254038dd9fa8da6494e3f3c856af500a5aeaf0df62d and examine its contents. It is possible to send a file directly by typing its path. For example:
If you want to send a file from the 'fileexchange' peer, just type the file name. For example: ```
> /home/tester/tmp/msg/aa6f339e830c86718ddf4254038dd9fa8da6494e3f3c856af500a5aeaf0df62d
> /home/tester/tmp/msg/aa6f339e830c86718ddf4254038dd9fa8da6494e3f3c856af500a5aeaf0df62d ```
Another peer should receive the message, decrypt and display it on the screen. Asymmetric encryption is also available in file exchange mode by providing the `asym` flag.
If you want to use your own password instead of hardcoded one, just call wnode without 'test' flag.
Of course, you can also switch to asymmetric encryption by providing 'asym' flag.
#### Mail Server & Client ### Mail Server & Client
Whisper protocol allows you to exchange messages with other peers only if you are online. But what if you go offline? Will important messages be lost forever? The golang implementation of Whisper v6 has a built-in support for Mail Client/Server functionality, which allows to create very secure (and even dark) anonymous email-like system. Wnode is designed to demonstrate the viability of such project. Whisper protocol allows you to exchange messages with other peers only if you are online. But what if you go offline? Will important messages be lost forever? The golang implementation of Whisper v6 has a built-in support for Mail Client/Server functionality, which allows to create very secure (and even dark) anonymous email-like system. Wnode is designed to demonstrate the viability of such project.
@ -221,22 +237,31 @@ Mail Server and Client must have direct connection, since they exchange special
Starting Mail Server: Starting Mail Server:
> wnode -mailserver -forwarder -standalone -test -ip=127.0.0.1:30381 -idfile=pk1.txt -dbpath=/home/tester/tmp/arj
```
bootnode $ wnode -mailserver -forwarder -standalone -test -ip=127.0.0.1:30381 -idfile=pk1.txt -dbpath=/home/tester/tmp/arj
```
Now start another node, connect to the Server, and send some test messages to fill the database: Now start another node, connect to the Server, and send some test messages to fill the database:
> wnode -test -boot=enode://7d13360f5b1ddcf6947f244639113597a863abba0589d2fa5fffb2816ead0acea6211d5778a8be648e45e81ed881f4c1f5c9bbbf0e79065dfb54bcd97de3beab@127.0.0.1:30381 ```
othernode $ wnode -test -boot=enode://7d13360f5b1ddcf6947f244639113597a863abba0589d2fa5fffb2816ead0acea6211d5778a8be648e45e81ed881f4c1f5c9bbbf0e79065dfb54bcd97de3beab@127.0.0.1:30381
```
Note the UNIX time of the messages. For example: 1493127055. Note the UNIX time of the messages. For example: `1493127055`.
Now start the Mail Client and connect to the Server: Now start the Mail Client and connect to the Server:
> wnode -mailclient -test -boot=enode://7d13360f5b1ddcf6947f244639113597a863abba0589d2fa5fffb2816ead0acea6211d5778a8be648e45e81ed881f4c1f5c9bbbf0e79065dfb54bcd97de3beab@127.0.0.1:30381 ```
othernode $ wnode -mailclient -test -boot=enode://7d13360f5b1ddcf6947f244639113597a863abba0589d2fa5fffb2816ead0acea6211d5778a8be648e45e81ed881f4c1f5c9bbbf0e79065dfb54bcd97de3beab@127.0.0.1:30381
```
You will be prompted to enter the time range of the archived messages you want to receive: You will be prompted to enter the time range of the archived messages you want to receive:
> Please enter the lower limit of the time range (unix timestamp): 1493127000 ```
> Please enter the upper limit of the time range (unix timestamp): 1493127099 Please enter the lower limit of the time range (unix timestamp): 1493127000
> Please enter the topic (hexadecimal): Please enter the upper limit of the time range (unix timestamp): 1493127099
Please enter the topic (hexadecimal):
```
You can leave the topic empty for now, in which case all the messages will be delivered, regardless of the topic. You can leave the topic empty for now, in which case all the messages will be delivered, regardless of the topic.
The message should be delivered by the the Server, decrypted by the Client and displayed on the screen. The message should be delivered by the the Server, decrypted by the Client and displayed on the screen.