Set Up a Storage Node

This page walks you through the full initial setup of a Walrus storage node, from system preparation to registration and first startup.

caution

If you deviate from the standard setup below (user, directories, ports), make sure to adjust later steps accordingly. Some Walrus and Sui configuration files include absolute paths, so moving files without adjusting those paths might cause issues.

Prerequisites

• Linux operating system (Ubuntu 24.04 recommended), x86_64 with AVX2 and SSSE3 support
• A large disk partition for blob storage, mounted at /opt/walrus/db
• A public IP address with a DNS name pointing to it
• Complete initial system setup

Initial system setup instructions

Step 1: Create a walrususer and group.

sudo useradd -s /bin/bash walrus

Step 2: Create the directory structure.

sudo install -d -o walrus -g walrus -m 0755 \
  /opt/walrus /opt/walrus/config /opt/walrus/config/tls /opt/walrus/bin /opt/walrus/db

Step 3: Mount the storage partition.

Mount the large storage partition to /opt/walrus/db and ensure it persists across reboots (for example, by adding an entry in /etc/fstab).

Step 4: Configure the firewall:

Open port 9185 (storage node) and port 80 (automatic certificate renewal). If you plan to run an aggregator or publisher on the same host, also open port 9000 (aggregator) or port 9001 (publisher), or port 443 if you use a reverse proxy (recommended for production):

for PORT in 80 443 9185; do
  sudo iptables -A INPUT -p tcp --dport $PORT -j ACCEPT
done

Make the firewall configuration persistent across reboots:

sudo apt-get install iptables-persistent
sudo iptables-save

Verify the rules with sudo iptables -L INPUT -n.

You can test your firewall setup by running nc -l PORT_NUMBER on the Walrus host and echo test | nc HOSTNAME PORT_NUMBER from a different machine. You do not need to open the metrics port (port 9184).

TLS setup

The storage node handles TLS directly. If you deploy a reverse proxy in front of the storage node, you must disable TLS termination on the proxy or ensure it uses the same key as the storage node.

caution

Do not use self-signed certificates. They prevent the node from communicating with browsers.

You can use any tool to obtain and renew certificates. Ensure you generate a key of the correct type (ECDSA secp256r1) in the correct format (PKCS8) and use the full certificate chain in PEM format.

The following steps use certbot to request and manage certificates.

Step 1: Install certbot.

Install certbot using snap from the edge channel. This is necessary for PKCS#8 key format:

sudo snap install --classic certbot --channel=edge

Step 2: Set the SERVER_NAME environment variable.

Set this to the public hostname of the node:

SERVER_NAME=  # your node's public hostname

# Verify: the external IP should match where the DNS name resolves
curl ifconfig.me; echo
dig +short $SERVER_NAME

Step 3: Create the deploy hook script.

Save the following script at /opt/walrus/bin/tls-deploy-hook.sh. Certbot uses this script to copy certificates to the TLS directory of the storage node after issuance or renewal:

#!/usr/bin/env bash
set -euo pipefail

# Absolute directory in which to place the TLS certificate and private key.
WALRUS_TLS_DIR="$1"
# The directory from which to copy the issued/renewed certificates.
# The variable $RENEWED_LINEAGE is automatically populated by certbot.
TLS_SOURCE_DIR="$RENEWED_LINEAGE"

# Remove the previous certificate files
rm -f "$WALRUS_TLS_DIR/cert.pem" "$WALRUS_TLS_DIR/chain.pem" \
      "$WALRUS_TLS_DIR/fullchain.pem" "$WALRUS_TLS_DIR/privkey.pem"
# Copy the newly issued/renewed certificate and key into the walrus TLS directory.
/usr/bin/env cp -rL "$TLS_SOURCE_DIR"/* "$WALRUS_TLS_DIR/"
# Change the owner from root to walrus
/usr/bin/env chown walrus:walrus "$WALRUS_TLS_DIR"/*

Step 4: Set the correct permissions.

sudo chown walrus /opt/walrus/bin/tls-deploy-hook.sh
sudo chmod u=rwx,g=rx,o=rx /opt/walrus/bin/tls-deploy-hook.sh

Step 5: Perform a dry run.

sudo certbot certonly --standalone \
  --reuse-key --key-type ecdsa --elliptic-curve=secp256r1 \
  --domain $SERVER_NAME --cert-name walrus-storage-node \
  --deploy-hook="/opt/walrus/bin/tls-deploy-hook.sh /opt/walrus/config/tls" \
  --dry-run

Step 6: Obtain the certificate.

If the dry run succeeded, re-run the command without --dry-run to obtain the actual certificate.

After this, certbot automatically renews the certificate before it expires, and the node picks up changes to the file. You can verify the setup:

# Check the renewal configuration
cat /etc/letsencrypt/renewal/walrus-storage-node.conf

# Check the renewal timer is active
sudo systemctl status snap.certbot.renew.timer

If you need to manually re-run the deploy hook, use sudo certbot reconfigure --cert-name walrus-storage-node --run-deploy-hooks.

Install jemalloc

It is highly recommended to install jemalloc for improved memory allocation performance:

sudo apt-get install libjemalloc2

This is configured through LD_PRELOAD in the systemd service file below.

The library path /usr/lib/x86_64-linux-gnu/libjemalloc.so.2 is for x86_64 Ubuntu. If you use a different architecture, adjust the path accordingly.

Create the systemd service file

Create a systemd service at /etc/systemd/system/walrus-node.service:

[Unit]
Description=Walrus Node

[Service]
User=walrus
Environment=RUST_BACKTRACE=1
Environment=RUST_LOG=info
Environment="LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2"
ExecStart=/opt/walrus/bin/walrus-node run --config-path /opt/walrus/config/walrus-node.yaml
Restart=always
TimeoutStopSec=300

LimitNOFILE=4294967296

[Install]
WantedBy=multi-user.target

TimeoutStopSec=300 gives the node up to 5 minutes to shut down gracefully, including terminating open connections and flushing the database. If you find this too short, you can increase it.

Download binaries and generate configuration

Run all the following commands as the walrususer:

sudo su walrus

Set environment variables

Mainnet

NETWORK=mainnet

Testnet

NETWORK=testnet

Set the server name (as configured in the TLS setup section):

SERVER_NAME=  # your node's public hostname

Download binaries

Download the walrus-node and walrus binaries:

cd /opt/walrus/bin
for BIN in walrus walrus-node; do
  curl -L "https://storage.googleapis.com/mysten-walrus-binaries/$BIN-$NETWORK-latest-ubuntu-x86_64" -o $BIN
  chmod 0755 $BIN
done

Verify the versions match the latest release for the target network:

./walrus-node -V
./walrus -V

Alternatively, you can download the binaries directly from the GitHub releases page.

For signed binaries and verification, see Verifying Signed Binaries.

Create the client configuration

CLIENT_CONFIG=/opt/walrus/config/client_config.yaml
curl "https://docs.wal.app/setup/client_config_$NETWORK.yaml" -o $CLIENT_CONFIG

Generate the node configuration

The walrus-node setup command generates the node configuration and a Sui wallet. Key options:

• --node-capacity: The capacity you can dedicate to the Walrus database. Accepts values like 3.14TB, 2.718TiB, and similar units.
• --sui-network: The Sui full node URL used to configure the wallet of the storage node.
• --sui-rpc: The Sui RPC URL used for all Sui interactions. This can be the same as --sui-network or a separate endpoint. See the FAQ for the distinction.
• --checkpoint-bucket: URL for checkpoint-based transaction reading as a fallback.
• --additional-rpc-endpoints: Additional Sui RPC endpoints for redundancy (you can specify this option multiple times).
• --storage-price and --write-price: Your voting parameters for the storage price per MiB and epoch, and write price per MiB (one-time fee). You can specify the currency with the --price-currency flag (defaults to FROST). Check with the Walrus Foundation for the current recommended values.
• --commission-rate: Commission rate in basis points (100 bp = 1%). See the FAQ for details. The default value of 6000 bp (60%) is the maximum commission rate if you intend to receive staking from the Walrus Foundation.
• --metrics-push-url: URL for pushing Prometheus metrics. The Walrus Foundation provides a metrics endpoint for committee members.
• --image-url, --project-url, --description: Optional metadata about your node.

You can also change all of these options in the generated configuration file after setup.

Operators who set up their node in coordination with the Walrus Foundation or Mysten Labs can get access to a dedicated Sui full node. Otherwise, you need to run your own or use a third-party RPC provider. The Sui full node must sustain at least 10 requests per second for checkpoint data. If you run your own Sui RPC node, make sure to always keep it up to date and not enable aggressive pruning (keep all data for at least 1 week on Mainnet or 2 days on Testnet).

Extract the system and staking object IDs from the client configuration file you downloaded earlier:

SYSTEM_OBJECT=$(awk '/^system_object:/ {print $2}' $CLIENT_CONFIG)
STAKING_OBJECT=$(awk '/^staking_object:/ {print $2}' $CLIENT_CONFIG)

Set the remaining variables and run the setup command:

NODE_CAPACITY=   # for example, 3.14TB or 2.718TiB
NODE_NAME=""     # an arbitrary string identifying your node; include your entity name
PUBLIC_PORT=9185 # change if you deviate from defaults or use a reverse proxy
SUI_RPC_URL=     # URL of a Sui full node for the target network

/opt/walrus/bin/walrus-node setup \
  --sui-network "$SUI_RPC_URL" \
  --config-directory /opt/walrus/config \
  --storage-path /opt/walrus/db \
  --sui-rpc "$SUI_RPC_URL" \
  --system-object "$SYSTEM_OBJECT" \
  --staking-object "$STAKING_OBJECT" \
  --node-capacity "$NODE_CAPACITY" \
  --public-host $SERVER_NAME \
  --public-port $PUBLIC_PORT \
  --name "$NODE_NAME" \
  --network-key-path /opt/walrus/config/tls/privkey.pem \
  --certificate-path /opt/walrus/config/tls/fullchain.pem \
  --metrics-push-url "https://walrus-metrics-$NETWORK.mystenlabs.com/publish/metrics" \
  --checkpoint-bucket "https://checkpoints.$NETWORK.sui.io" \
  --force

Run walrus-node setup --help for a full description of all options.

After setup, review the generated configuration file at /opt/walrus/config/walrus-node.yaml and verify IP addresses, DNS names, port numbers, and file paths. You can edit the file directly or re-run the setup command.

Wallet configuration

The walrus-node setup command creates a Sui wallet at /opt/walrus/config/sui_config.yaml with the private key in /opt/walrus/config/sui.keystore. You can replace these with a different wallet, but you might have to adjust absolute paths in sui_config.yaml.

caution

Do not reuse any keys, wallets, or other secrets from Testnet or anywhere else. Each network deployment should use freshly generated credentials.

Register and start the node

Step 1: Fund the wallet.

Send SUI to the wallet address shown during setup. 1 SUI is sufficient for registration, but the node needs additional SUI for ongoing operation. A recommended initial balance is approximately 20 SUI.

Mainnet

Transfer SUI from an existing wallet or exchange to the address shown during setup.

Testnet

You can use the Sui Testnet faucet to obtain test SUI. The faucet has rate limits, so you might need to make multiple requests or wait between attempts. Alternatively, transfer SUI from an existing Testnet wallet.

Step 2: Register the node.

/opt/walrus/bin/walrus-node register --config-path /opt/walrus/config/walrus-node.yaml

caution

You must run registration during initial setup. It creates the onchain records for your node.

Step 3: Set up commission and governance authorization.

Designate a secure wallet address for receiving commission and authorizing governance operations. See Commission and Governance for details.

Step 4: Start the node.

sudo systemctl daemon-reload
sudo systemctl enable --now walrus-node.service

Step 5: Verify the node is running.

sudo systemctl status walrus-node.service
journalctl -efu walrus-node

Before the node is selected for the committee, you might see error messages like "message":"unable to push metrics","error":"metrics push failed: [403 Forbidden]". This is expected because your node is not part of the committee yet and must be specifically allowlisted to send metrics.

Step 6: Check the health endpoint.

Run the following command from a different machine to also verify the firewall setup:

curl https://PUBLIC_ADDRESS:9185/v1/health | jq

The storage node serves HTTPS only (it handles TLS directly). When checking from localhost, use curl -k to skip certificate verification:

curl -sk https://localhost:9185/v1/health | jq

This should return a 200 status with a non-empty JSON payload. The nodeStatus value should be Standby. You can also check https://PUBLIC_ADDRESS:9185/v1/api in a browser to verify the TLS certificate is set up correctly.

Step 7: Verify the onchain key.

Use the walrus health command. This performs a cryptographic check that the node uses the key registered onchain:

/opt/walrus/bin/walrus --config /opt/walrus/config/client_config.yaml health --node-id YOUR_NODE_ID