Skip to content

Commit 6dfb82b

Browse files
authored
Merge pull request #1263 from input-output-hk/jpraynaud/enhance-signer-setup-guide
Enhance signer setup guide for SPO
2 parents a6c50a0 + cdc08dc commit 6dfb82b

File tree

1 file changed

+38
-8
lines changed

1 file changed

+38
-8
lines changed

docs/website/root/manual/getting-started/run-signer-node.md

Lines changed: 38 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -234,7 +234,7 @@ Replace this value with the correct user. We assume that the user used to run th
234234
* `STORE_RETENTION_LIMIT`: if set, this will limit the number of records in some internal stores (5 is a good fit).
235235
* `ERA_READER_ADAPTER_TYPE=cardano-chain`: replace `cardano-chain` with the era reader adapter type used in your Mithril network
236236
* `ERA_READER_ADAPTER_PARAMS={"address": "...", "verification_key": "..."}`: replace `{"address": "...", "verification_key": "..."}` with the era reader parameters that you need to compute by running the command `jq -nc --arg address $(wget -q -O - **YOUR_ERA_READER_ADDRESS**) --arg verification_key $(wget -q -O - **YOUR_ERA_READER_VERIFICATION_KEY**) '{"address": $address, "verification_key": $verification_key}'`
237-
* `RELAY_ENDPOINT=http://192.168.1.50:3128` **(optional)**: this is the endpoint of the **Mithril relay**, which is required for **production** deployment only. For **naive** deployment, do not set this variable in your environment file.
237+
* `RELAY_ENDPOINT=http://192.168.1.50:3132` **(optional)**: this is the endpoint of the **Mithril relay**, which is required for **production** deployment only. For **naive** deployment, do not set this variable in your environment file.
238238
:::
239239

240240
:::tip
@@ -248,7 +248,7 @@ Here is an **example** set of values for **release-preprod** that will be used i
248248
* ****YOUR_ERA_READER_ADAPTER_TYPE****: `cardano-chain`
249249
* ****YOUR_ERA_READER_ADAPTER_PARAMS****: `{"address": "addr_test1qpkyv2ws0deszm67t840sdnruqgr492n80g3y96xw3p2ksk6suj5musy6w8lsg3yjd09cnpgctc2qh386rtxphxt248qr0npnx", "verification_key": "5b35352c3232382c3134342c38372c3133382c3133362c34382c382c31342c3138372c38352c3134382c39372c3233322c3235352c3232392c33382c3234342c3234372c3230342c3139382c31332c33312c3232322c32352c3136342c35322c3130322c39312c3132302c3230382c3134375d"}`
250250
* ****YOUR_RELAY_ENDPOINT****: `192.168.1.50`
251-
* ****YOUR_RELAY_LISTENING_PORT****: `3128`
251+
* ****YOUR_RELAY_LISTENING_PORT****: `3132`
252252
* ****YOUR_BLOCK_PRODUCER_INTERNAL_IP****: `192.168.1.75`
253253
* ****YOUR_SIGNER_LOGS_PATH****: `/var/log/syslog`
254254
* ****YOUR_PARTY_ID****: `pool1hp72sauk0g0yqm4dzllz0pz6j93gewhllkzphn4hykkfmne43y`
@@ -294,7 +294,7 @@ DATA_STORES_DIRECTORY=/opt/mithril/stores
294294
STORE_RETENTION_LIMIT=5
295295
ERA_READER_ADAPTER_TYPE=cardano-chain
296296
ERA_READER_ADAPTER_PARAMS={"address": "addr_test1qpkyv2ws0deszm67t840sdnruqgr492n80g3y96xw3p2ksk6suj5musy6w8lsg3yjd09cnpgctc2qh386rtxphxt248qr0npnx", "verification_key": "5b35352c3232382c3134342c38372c3133382c3133362c34382c382c31342c3138372c38352c3134382c39372c3233322c3235352c3232392c33382c3234342c3234372c3230342c3139382c31332c33312c3232322c32352c3136342c35322c3130322c39312c3132302c3230382c3134375d"}
297-
RELAY_ENDPOINT=http://192.168.1.50:3128
297+
RELAY_ENDPOINT=http://192.168.1.50:3132
298298
EOF'
299299
```
300300

@@ -392,6 +392,23 @@ Finally, monitor the logs of the service:
392392
tail /var/log/syslog
393393
```
394394

395+
### Rotating the KES keys
396+
397+
:::danger
398+
399+
When the KES keys expire, the Mithril signer is unable to register with the Mithril protocol.
400+
401+
:::
402+
403+
After rotating the KES keys on your Cardano block producer, we recommend following this upgrade procedure for your Mithril signer node:
404+
1. Update the `KES_SECRET_KEY_PATH` entry of your environment file to reflect the location of the **new KES secret key file**.
405+
2. Update the `OPERATIONAL_CERTIFICATE_PATH` entry of your environment file to reflect the location of the **new operational certificate file**.
406+
3. Restart your Mithril signer service with the following command:
407+
```bash
408+
sudo systemctl restart mithril-signer
409+
```
410+
4. Check the logs of your signer node and make sure that it has successfully registered after restarting (the following log should be displayed: `STATE MACHINE: new cycle: Registered`).
411+
395412
## Set up the Mithril relay node
396413

397414
:::caution
@@ -426,7 +443,7 @@ Prepare the forward proxy configuration file:
426443

427444
```bash
428445
sudo bash -c 'cat > /etc/squid/squid.conf << EOF
429-
# Listening port (port 3128 is recommended)
446+
# Listening port (port 3132 is recommended)
430447
http_port **YOUR_RELAY_LISTENING_PORT**
431448
432449
# ACL for internal IP of your block producer node
@@ -481,8 +498,8 @@ Here is an example of the aforementioned command created with the example set fo
481498

482499
```bash
483500
sudo bash -c 'cat > /etc/squid/squid.conf << EOF
484-
# Listening port (port 3128 is recommended)
485-
http_port 3128
501+
# Listening port (port 3132 is recommended)
502+
http_port 3132
486503
487504
# ACL for internal IP of your block producer node
488505
acl block_producer_internal_ip src 192.168.1.75
@@ -532,6 +549,19 @@ EOF'
532549

533550
:::
534551

552+
:::tip
553+
554+
In case you are using the same Cardano relay for multiple Cardano block producers, you will need to add a new line per block producer for authorizing its internal IP:
555+
556+
```bash
557+
# ACL for internal IP of your block producer node
558+
acl block_producer_internal_ip src **YOUR_BLOCK_PRODUCER_INTERNAL_IP_1**
559+
acl block_producer_internal_ip src **YOUR_BLOCK_PRODUCER_INTERNAL_IP_2**
560+
acl block_producer_internal_ip src **YOUR_BLOCK_PRODUCER_INTERNAL_IP_3**
561+
```
562+
563+
:::
564+
535565
With this configuration, the proxy will:
536566
- accept incoming traffic originating from the internal IP of the block-producing machine
537567
- accept incoming traffic directed to the listening port of the proxy
@@ -589,7 +619,7 @@ sudo ufw allow from **YOUR_BLOCK_PRODUCER_INTERNAL_IP** to any port **YOUR_RELAY
589619
Here is an example of the aforementioned command created with the example set for `release-preprod`:
590620

591621
```bash
592-
sudo ufw allow from 192.168.1.75 to any port 3128 proto tcp
622+
sudo ufw allow from 192.168.1.75 to any port 3132 proto tcp
593623
```
594624

595625
:::
@@ -607,7 +637,7 @@ sudo service netfilter-persistent save
607637
Here is an example of the aforementioned command created with the example set for `release-preprod`:
608638

609639
```bash
610-
sudo iptables -A INPUT -s 192.168.1.75 -p tcp --dport 3128 -j ACCEPT
640+
sudo iptables -A INPUT -s 192.168.1.75 -p tcp --dport 3132 -j ACCEPT
611641
sudo iptables -L -v
612642
sudo service netfilter-persistent save
613643
```

0 commit comments

Comments
 (0)