Whaleshares Logo

Witness Server - Update and Upgrade - Step by Step Manual

ijmmaiwitnessPosted to Public2 months ago5 min read


Starting a Witness Server

To start a witness server, all you have to do is carefully follow the steps described in the guide @bushkill-witness keeps up to date. Not difficult, although at times you can come across error-messages. Most of those are related to not following the guide correctly. When it happens, ask for help in the witness channel on Discord.

Update and Upgrade

From time to time the software needs to be updated. This can be due to a found bug, or some kind of security precaution. Most of the time it is just the whaled file that needs to be updated.

A Hard Fork, abbreviated HF, is an upgrade. These changes actually change the way the blockchain and/or the economics involved, work. Upgrades always involve a --replay-blockchain action. Our next HF will be HF4.

Update or upgrade is reflected in the version number. We are currently on version 0.3.1. If an update would occur prior to HF4, the version would change to 0.3.2.
HF4 will be version 0.4.0
As long as the project is in beta, the first number will be zero.


This is what is needed, in short. Every step will be explained below

  • Keep wallet.whaleshares.io (Tools -> Witness) tab open for emergencies
  • Log in to your server
  • Go to whaleshares folder
  • rename whaled to whaled.old
  • download, unzip the new file
  • clean up the tar file
  • go into the Screen container: witness
  • stop and start the process
  • if needed replace nullkey with your own key

How Things Relate to one and other


How to create each container

whaleshares folderThe whaleshares folder is created when setting up the server, following the guide, with the mkdir whaleshares command
Screen containerA screen container is created while setting up the server, following the guide by the Screen -S witness command for the whaled program and the Screen -S wallet command for the cli_wallet program
Docker containerThe Docker containers are created when setting up the server, by the long command in the guide. One inside the Screen container:witness one inside the Screen container:wallet

Updating the Whaled file

The wallet file doesn't always need to be updated, the whaled file most of the time does.

Step one - Set the nullkey

You can start with setting the nullkey. This will prevent you from missing blocks while working on the server. Your witness account will show up "Disabled" on the witness page.

Two ways to do this:

  • on the server directly (in the cli_program inside the Docker container:wallet)
  • in your wallet on whaleshares.io

I usually don't set the nullkey but have the whaleshares.io wallet open in a browser tab, so I can set it quickly in case things turn south.

Step two - Log in to your server

Log in to your server. I use Putty, but maybe you are using something else.

Step three - Go to the whaleshares folder

Use either

  • cd whaleshares
  • cd /home/username/whaleshares
    just to be sure use dir -ls to check the files in the folder.(see image above)

Step four - Download New File

The current version of whaled is present in memory, therefore you can do what you want with the whaled file on disk.

  • rename the current version file (just in case you need to rollback)
    sudo mv whaled whaled.old
    or anything else that fits your logic
  • download the new version sudo wget <download-url>

Step five - Unzip the downloaded file, and clean up

The downloaded file is a zipped file, a tar.gz file. To unzip it use

sudo tar -xzf <filename>

You can use dir -ls again to check you have a whaled file again.
Remove the zipped file with the sudo rm *.gz command

Step six - Go to the Screen Container

You can use the screen -ls command to check that you have two screen containers. One named wallet, one named witness. The Screens overview should show both containers "detached".

We want to enter the Screen container:witness. You can enter the Screen container with the screen -r witness command. In case the container didn't show up as "detached", you can detach it by using the screen -d witness command first.

Step seven - Inside the Screen Container

You should see the blocks being produced, one every 3 seconds.

Stop the process by using Ctrl+c

  • When everything goes well, you have a clean exit, the prompt shows up.
    Use the up-arrow on your keyboard to display the last used command.
    Check if it has the --replay-blockchain option at the end. Decide whether or not you need that. Remove or add that part.
    Press Enter
    The Docker container witness should restart and process blocks again.

  • When things don't go as planned
    Sometimes you don't see the clean exit. The prompt doesn't show up either.
    If you haven't set the nullkey earlier on, this may be a good moment to set it.

Exit the Screen container:witness by pressing Ctrl+A+D (not sure this is needed but that is what I do)
Stop the Docker container:witness with the command sudo docker stop witness
Go back into the Screen container:witness screen -r witness
Press up-arrow, press Enter

You are done! (Unless you set the nullkey)

In case you set the nullkey:

  • exit the Screen container:witness (Ctrl+A+D)
  • enter the Screen container:wallet (screen -r wallet)
  • up-arrow, Enter

Image Source

Use your witness votes wisely

Jump over to the Block Producer / Witness page and cast your witness votes. Simply click on the (^) up arrow next to the witness names of your choice (consider voting for "krazywitness" and "ijmmaiwitness") and supply your private active key to lock in your vote. Refresh the page in case your vote doesn't seem to stick.


Sort byOldest