add node operator documentation (MystenLabs#9190)

docker/fullnode/docker-compose.yaml

@@ -4,11 +4,9 @@ services:
   fullnode:
     image: mysten/sui-node:stable
     ports:
+    - "8084:8084/udp"
     - "9000:9000"
     - "9184:9184"
-    expose:
-    - "9000"
-    - "9184"
     volumes:
     - ./fullnode-template.yaml:/sui/fullnode.yaml:ro
     - ./genesis.blob:/sui/genesis.blob:ro

docker/sui-node/Dockerfile

@@ -51,6 +51,8 @@ ARG PROFILE=release
 WORKDIR sui
 # Both bench and release profiles copy from release dir
 COPY --from=builder /sui/target/release/sui-node /usr/local/bin
+# Staged migration from /usr/local/bin to /opt/sui/bin
+COPY --from=builder /sui/target/release/sui-node /opt/sui/bin
 
 ARG BUILD_DATE
 ARG GIT_REVISION

nre/README.md

@@ -0,0 +1,15 @@
+# Node and Network Reliability Engineering
+
+-----
+
+This repo contains:
+
+- [Sui for Node Operators](./sui_for_node_operators.md) - This documentation aggregates all the information about deploying and operating the Sui Node software for Node Operators.
+
+- `ansible/` - An ansible playbook for standing up your node. Successful execution of the playbook will result in a systemd managed process running sui-node. You can use this or just consult the steps when provisioning your node.
+
+- `config/` - Sui Node configuration templates.
+
+- `docker/` - A docker compose configuration for standing up your node. You can use this or just consult the steps when provisioning your node. 
+
+- `systemd/` - Steps to setup your node as a systemd service. You can use this or reference the steps when provisioning your node. 

nre/ansible/README.md

@@ -0,0 +1,32 @@
+# Configure a Linux system as a Sui Node using Ansible
+
+This is a self contained Ansible role for configuring a Linux system as a Sui Node.
+
+Tested with `ansible [core 2.13.4]` and:
+
+- ubuntu 20.04 (linux/amd64) on bare metal
+- ubuntu 22.04 (linux/amd64) on bare metal
+
+## Prerequisites and Setup
+
+1. Install [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html)
+
+2. Add the target host to the [Ansible Inventory](./inventory.yaml)
+
+3. Update the `sui_release` var in the [Ansible Inventory](./inventory.yaml)
+
+4. Update [validator.yaml](../config/validator.yaml) and copy it to this directory.
+
+5. Copy the genesis.blob to this directory (should be available after the Genesis ceremony).
+
+6. Udate the `keypair_path` var in the [Ansible Inventory](./inventory.yaml)
+
+## Example use:
+
+- Configure everything:
+
+`ansible-playbook -i inventory.yaml sui-node.yaml -e host=$inventory_name`
+
+- Software update:
+
+`TODO`

nre/ansible/inventory.yaml

@@ -0,0 +1,10 @@
+---
+validator:
+  hosts:
+    validator:
+      ansible_host: validator.example.com
+      ansible_user: ubuntu
+      sui_release: "$SUI_SHA" # UPDATE THIS
+      node_config: "./validator.yaml"
+      genesis_blob: "./genesis.blob"
+      keypair_path: "./key-pairs/"

nre/ansible/roles/sui-node/files/journald.conf

@@ -0,0 +1,3 @@
+[Journal]
+RateLimitBurst=500000
+ForwardToSyslog=no

nre/ansible/roles/sui-node/files/sui-node.service

@@ -0,0 +1,13 @@
+[Unit]
+Description=Sui Node
+
+[Service]
+User=sui
+WorkingDirectory=/opt/sui/
+Environment=RUST_BACKTRACE=1
+Environment=RUST_LOG=info,sui_core=debug,narwhal=debug,narwhal-primary::helper=info
+ExecStart=/opt/sui/bin/sui-node --config-path /opt/sui/config/validator.yaml
+Restart=always
+
+[Install]
+WantedBy=multi-user.target

nre/ansible/roles/sui-node/tasks/iptables.yaml

@@ -0,0 +1,87 @@
+---
+- name: Set the policy for the INPUT chain to ACCEPT (IPv4)
+  iptables:
+    chain: INPUT
+    ip_version: ipv4
+    policy: ACCEPT
+
+- name: Flush filter chains (IPv4)
+  ansible.builtin.iptables:
+    chain: "{{ item }}"
+    ip_version: ipv4
+    flush: yes
+  with_items: ["INPUT", "FORWARD", "OUTPUT"]
+
+- name: Flush filter chains (IPv6)
+  ansible.builtin.iptables:
+    chain: "{{ item }}"
+    ip_version: ipv6
+    flush: yes
+  with_items: ["INPUT", "FORWARD", "OUTPUT"]
+
+- name: Allow all loopback connectivity
+  ansible.builtin.iptables:
+    chain: INPUT
+    in_interface: lo
+    jump: ACCEPT
+
+- name: Allow TCP port 22 / SSH connectivity
+  ansible.builtin.iptables:
+    chain: INPUT
+    destination_port: 22
+    jump: ACCEPT
+    protocol: tcp
+
+- name: Allow established and related connectivity
+  iptables:
+    chain: INPUT
+    ctstate: ESTABLISHED,RELATED
+    jump: ACCEPT
+
+- name: Allow TCP destination port 8080 / sui-node protocol connectivity
+  iptables:
+    chain: INPUT
+    destination_port: 8080
+    jump: ACCEPT
+    protocol: tcp
+    comment: sui-node protocol
+
+- name: Allow UDP destination port 8081 / sui-node narwhal-primary-address connectivity
+  iptables:
+    chain: INPUT
+    destination_port: 8081
+    jump: ACCEPT
+    protocol: udp
+    comment: sui-node narwhal-primary-address
+
+- name: Allow UDP destination port 8082 / sui-node narwhal-worker-address connectivity
+  iptables:
+    chain: INPUT
+    destination_port: 8082
+    jump: ACCEPT
+    protocol: udp
+    comment: sui-node narwhal-worker-address
+
+- name: Allow UDP destination port 8084 / sui-node peer-to-peer connectivity
+  iptables:
+    chain: INPUT
+    destination_port: 8084
+    jump: ACCEPT
+    protocol: udp
+    comment: sui-node peer-to-peer
+
+- name: Set the policy for the INPUT chain to DROP (IPv4)
+  iptables:
+    chain: INPUT
+    ip_version: ipv4
+    policy: DROP
+
+- name: Set the policy for the INPUT chain to DROP (IPv6)
+  iptables:
+    chain: INPUT
+    ip_version: ipv6
+    policy: DROP
+
+- name: Save iptables configuration (/etc/iptables/)
+  ansible.builtin.command: netfilter-persistent save
+  become: yes

nre/ansible/roles/sui-node/tasks/main.yaml

@@ -0,0 +1,21 @@
+---
+- name: Install required system packages
+  apt: name={{ item }} state=latest update_cache=yes
+  loop: [
+    'iptables-persistent'
+  ]
+
+- name: Include Ubuntu tasks
+  ansible.builtin.include_tasks: "{{ role_path }}/tasks/ubuntu.yaml"
+  when: ansible_distribution == 'Ubuntu'
+
+- name: Include iptables tasks
+  ansible.builtin.include_tasks: "{{ role_path }}/tasks/iptables.yaml"
+  when: skip_iptables == false
+
+- name: Include monitoring tasks
+  ansible.builtin.include_tasks: "{{ role_path }}/tasks/monitoring.yaml"
+  when: skip_monitoring == false
+
+- name: Include Sui tasks
+  ansible.builtin.include_tasks: "{{ role_path }}/tasks/sui.yaml"

nre/ansible/roles/sui-node/tasks/monitoring.yaml

@@ -0,0 +1,12 @@
+---
+- name: Copy journald.conf
+  copy:
+    src: "../files/journald.conf"
+    dest: /etc/systemd/journald.conf
+    mode: 0644
+
+- name: Reload systemd-journald
+  systemd:
+    name: systemd-journald
+    state: restarted
+

nre/ansible/roles/sui-node/tasks/sui.yaml

@@ -0,0 +1,107 @@
+---
+- name: Add a sui user
+  ansible.builtin.user:
+    name: sui
+    shell: /bin/bash
+
+- name: Create sui directories
+  file:
+    path: "{{ item }}"
+    state: directory
+    owner: "sui"
+    group: "sui"
+    mode: 0755
+  loop:
+    - /opt/sui/bin
+    - /opt/sui/config
+    - /opt/sui/db
+    - /opt/sui/key-pairs
+
+- name: Copy validator configuration file
+  copy:
+    src: "{{ node_config }}"
+    dest: /opt/sui/config/validator.yaml
+    owner: "sui"
+    group: "sui"
+    mode: 0644
+
+- name: Copy genesis.blob
+  copy:
+    src: "{{ genesis_blob }}"
+    dest: /opt/sui/config/genesis.blob
+    owner: "sui"
+    group: "sui"
+    mode: 0644
+
+- name: Copy protocol.key
+  copy:
+    src: "{{ keypair_path }}protocol.key"
+    dest: /opt/sui/key-pairs/protocol.key
+    owner: "sui"
+    group: "sui"
+    mode: 0600
+
+- name: Copy account.key
+  copy:
+    src: "{{ keypair_path }}account.key"
+    dest: /opt/sui/key-pairs/account.key
+    owner: "sui"
+    group: "sui"
+    mode: 0600
+
+- name: Copy network.key
+  copy:
+    src: "{{ keypair_path }}network.key"
+    dest: /opt/sui/key-pairs/network.key
+    owner: "sui"
+    group: "sui"
+    mode: 0600
+
+- name: Copy worker.key
+  copy:
+    src: "{{ keypair_path }}worker.key"
+    dest: /opt/sui/key-pairs/worker.key
+    owner: "sui"
+    group: "sui"
+    mode: 0600
+
+- name: Stop sui-node
+  systemd:
+    name: sui-node
+    state: stopped
+  ignore_errors: yes
+
+- name: Remove authorities directory
+  file:
+    state: absent
+    path: "/opt/sui/db/authorities_db"
+  when: reset_db == true
+
+- name: Remove consensus directory
+  file:
+    state: absent
+    path: "/opt/sui/db/consensus_db"
+  when: reset_db == true
+
+- name: Place binary
+  ansible.builtin.get_url:
+    url: "https://releases.sui.io/{{ sui_release }}/sui-node"
+    dest: /opt/sui/bin/sui-node
+    force: true
+    mode: "0755"
+
+- name: Copy sui-node systemd service file
+  copy:
+    src: "../files/sui-node.service"
+    dest: /etc/systemd/system/sui-node.service
+
+- name: Reload sui-node systemd service file
+  ansible.builtin.systemd:
+    name: sui-node
+    state: reloaded
+
+- name: Start sui-node service
+  systemd:
+    name: sui-node
+    state: started
+  when: start_sui == true

nre/ansible/roles/sui-node/tasks/ubuntu.yaml

@@ -0,0 +1,6 @@
+---
+# disable ufw as iptables is being manipulated directly
+- name: Disable UFW
+  community.general.ufw:
+    state: disabled
+  when: skip_iptables == false and (ansible_distribution_version == "20.04" or ansible_distribution_version == "22.04")

nre/ansible/sui-node.yaml

@@ -0,0 +1,10 @@
+---
+- hosts: "{{ host }}"
+  become: yes
+  roles:
+    - sui-node
+  vars:
+    skip_iptables: false
+    skip_monitoring: false
+    reset_db: false
+    start_sui: true