## **Operate a Stake Pool**

There are excellent guidelines available on how to set up cardano-node as a stake pool. You may even set one up without any prior Linux experience or concern for best practices. Simply copy and paste the commands from the instructions into your shell.

Unfortunately, simply getting your node up and running is insufficient. You must be able to manage, update, and safeguard it. To do so, you must first comprehend what you are doing in one of the testnets. Consider this category an entry point into the Cardano Pool Operator Community.

**What are the prerequisites for persons who wish to learn 
how to run a stake pool?**

Knowledge of how to manage a server. You must be familiar with the operating system of your choosing in order to administer, maintain, and secure your server.

This includes a thorough understanding of how networks operate, as well as how to backup and restore data.

Experienced in interpreting documentation and implementing best practices.

Understand Cardano, blockchain, wallets, and key pairs on a fundamental level.

**What if I don't meet the requirements?**

If you don't meet all of the qualifications, you'll need a strong desire to study and the understanding that you won't be able to learn everything in a few weeks.

We observed people who had no prior knowledge of Linux, shells, or networking, but who were committed and had enough time to properly deal with it, and who now manage a profitable stake pool. It isn't for everyone, and it isn't going to be simple. Here are a few resources to get you started:

[Start playing around with Linux.](https://ubuntu.com/tutorials/command-line-for-beginners#1-overview)

[Have a look at nix and NixOS.
](https://nixos.org/)

[Stake pool operator forum.](https://forum.cardano.org/c/staking-delegation/156)

**Choose security over comfort**

Best practices should always be a key consideration when running a stake pool. Security isn't something you can turn on or off or change in a configuration file. It is both an attitude and a way of life, therefore consider following the [security related topics with stake pool operators](https://forum.cardano.org/c/staking-delegation/stake-pool-security/157) on the Cardano Forum. Make sure to fully understand Cardano Key Pairs in the basic category.

**Learn the basics**

The basic category starts with an introduction to Cardano, you will learn the relay and block producer topology, what the hardware requirements are, which keys are available, which are hot and sensitive, and which you should never save on a server, no matter how convenient it is.

**Stake pool operator resources**

[Guild Operators](https://cardano-community.github.io/guild-operators), famous for their CNTools and top-notch content.

[Topology Updater](https://cardano-community.github.io/guild-operators/#/Scripts/topologyupdater) is intended to be a temporary solution to allow everyone to activate their relay nodes without having to postpone and wait for manual topology completion requests.

[CNCLI](https://github.com/cardano-community/cncli) is a collection of utilities to enhance and extend cardano-cli.

[Jormanager](https://bitbucket.org/muamw10/jormanager/src/develop/) a Cardano stake pool management software.

[Stake Pool Operator Scripts](https://github.com/gitmachtl/scripts) a collection of scripts to manage your stake pool step-by-step.

[Coin Cashew Guides](https://www.coincashew.com/coins/overview-ada/guide-how-to-build-a-haskell-stakepool-node) for stake pool operators.

[RaspberryPi with Docker](https://github.com/speedwing/cardano-staking-pool-edu) Full guide to build and run both testnet and mainnet Cardano stake pool with Docker on Raspberry Pi. [Youtube Playlist](https://www.youtube.com/playlist?list=PLBhbLwOuj0DfTnneuG3vyoDHY7Dv_aiyq)

[TOPO Guide](https://es-kb.topopool.com/primeros-pasos). A friendly and complete guide to create a stake pool in Spanish

[Cardano Course](https://cardano-course.gitbook.io/cardano-course/), a cardano-node and cardano-cli course by IOG.

Operate a Stake Pool

## **(Re)introduction to Cardano**

Developing Cardano is no small feat. There is no other project that has ever been built to these parameters, combining peer reviewed cryptographic research with an implementation in highly secure Haskell code.

This is not the copy and paste code seen in so many other blockchains. Instead, Cardano was designed with input from a large global team including leading experts and professors in the fields of computer programming languages, network design and cryptography.

We are extremely proud of Cardano, which required a months-long meticulous and painstaking development process by our talented engineers.

If you haven't seen it yet, watch the legendary whiteboard video from 2017. Some details are a bit outdated, but it is still worth seeing to understand what Cardano is and where Cardano came from.

<iframe width="859" height="325" src="https://www.youtube.com/embed/Ja9D0kpksxw" title="IOHK | Cardano whiteboard; overview with Charles Hoskinson" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

**Understanding Consensus**

Consensus is the process by which a majority opinion is reached by everyone who is involved in running the blockchain. Agreement must be made on which blocks to produce, which chain to adopt, and to determine the single state of the network. The consensus protocol determines how individual nodes assess the current state of the ledger system and reach a consensus. It has three main responsibilities; to perform a leader check and decide if a block should be produced, to handle chain selection, and to verify blocks that are produced.

Blockchains create consensus by allowing participants to bundle transactions that others have submitted to the system in blocks, and add them to their chain (sequence of blocks). Determining who is allowed to produce a block when, and what to do in case of conflicts, (such as two participants adding different blocks at the same point of the chain), is the purpose of the different consensus protocols. Our ground-breaking proof-of-stake consensus protocol Ouroboros is proven to have the same security guarantees that proof of work has. Rigorous security guarantees are established by Ouroboros and it was delivered with several peer-reviewed papers that were presented in top-tier conferences and publications in the area of cybersecurity and cryptography. Different implementations of Ouroboros have been developed. For further details on each flavour of Ouroboros, you can read the technical specifications for Classic, Byzantine Fault Tolerance (BFT), Genesis, Praos, and more recently the scalability solution Hydra.

**Stake Pools**

By running a Cardano node, users participate in and contribute to the network.

A stake pool is a reliable server node that focuses on maintenance and holds the combined stake of various stakeholders in a single entity. Stake pools are responsible for processing transactions and producing new blocks and are at the core of Ouroboros, the Cardano proof-of-stake protocol.

To be secure, Ouroboros requires a good number of ada holders to be online and maintaining sufficiently good network connectivity at any given time. This is why Ouroboros relies on stake pools, entities committed to run the protocol 24/7, on behalf of the contributing ada holders.

While Ouroboros is cheaper to run than a proof of work protocol, running Ouroboros still incurs some costs. Therefore, stake pool operators are rewarded for running the protocol in the form of incentives that come from the transaction fees and from inflation of the circulating supply of ada.

**How Are New Blocks Produced?**

The goal of blockchain technology is the production of an independently-verifiable and cryptographically-linked chain of records (blocks). A network of block producers works to collectively advance the blockchain. A consensus protocol provides transparency and decides which candidate blocks should be used to extend the chain.

Submitted valid transactions might be included in any new block. A block is cryptographically signed by its producer (the stake pool) and linked to the previous block in the chain. This makes it impossible to delete transactions from a block, alter the order of the blocks, remove a block from the chain (if it already has a number of other blocks following it), or to insert a new block into the chain without alerting all the network participants. This ensures the integrity and transparency of the blockchain expansion.

**Slots and Epochs**

The Cardano blockchain uses the Ouroboros Praos protocol to facilitate consensus on the chain.

Ouroboros Praos divides time into epochs. Each Cardano epoch consists of a number of slots, where each slot lasts for one second. A Cardano epoch currently includes 432,000 slots (5 days). In any slot, zero or more block-producing nodes might be nominated to be the slot leader. On average, one node is expected to be nominated every 20 seconds, for a total of 21,600 nominations per epoch. If randomly elected slot leaders produce blocks, one of them will be added to the chain. Other candidate blocks will be discarded.

**Slot Leader Election**

The Cardano network consists of a number of stake pools that control the aggregated stake of their owners and other delegators, also known as stakeholders. Slot leaders are elected randomly from among the stake pools. The more stake the pool controls, the greater the chance it has of being elected as a slot leader to produce a new block that is accepted into the blockchain. This is the concept of proof-of-stake (PoS).

**Transaction Validation**

When validating a transaction, a slot leader needs to ensure that the sender has included enough funds to pay for that transaction and must also ensure that the transaction’s parameters are met. Assuming that the transaction meets all these requirements, the slot leader will record it as a part of a new block, which will then be connected to other blocks in the chain.

**Ouroboros Protocol**

**Consensus**

Blockchains require an agreement mechanism between the participants of the network on how to add new transactions to the ledger and its state at any given moment. This mechanism is known as a consensus protocol.

The goal of the consensus protocol is to ensure that only one chain is adopted and followed, otherwise, the system would collapse immediately.

**The Proof-of-work consensus algorithm**

Bitcoin implemented a Proof-of-work consensus algorithm. In this protocol, for a new block to be added to the blockchain, the node that attempts it must provide a proof-of-work, which is expressed by the solution of a mathematical puzzle. This process is known as mining.

The node that solves the puzzle gets the right to create the new block and is rewarded for it.

This scheme puts all nodes into a race against each other, and since only one node is rewarded, wastes a lot of computational power and energy.

Such waste has raised concerns about the Bitcoin’s environmental impact. Currently, the Bitcoin mining process consumes as much energy as countries like the Netherlands or Iceland.

Apart from the environmental concerns, the rewards scheme of the proof-of-work algorithm has also led to the centralization of the Bitcoin network. Up to 75% of the Bitcoin network computing power is located in China. And a single player, Bitmain, controls over 40% of the network hash rate.

The underlying problem is that Bitcoin makes a clear distinction between the actual users of the network and the miners. Owning Bitcoins does not grant you any control over the network, nor any power over the decisions on the evolution of it. The system is controlled by a small pool of developers and miners.

Ouroboros, a Proof-of-stake consensus algorithm
In Ouroboros, there is no race between stakeholders to produce a block. Instead, a slot leader is randomly selected, proportionally to the amount of tokens he owns (the stake), to get the opportunity to produce a new block.

So it is not hashing power what gives you the opportunity to produce a new block (and get rewarded for it), it is your stake what increases your chances to be elected.

Since there is no race to mine a block, there is no waste of energy or computational resources. In that sense, Ouroboros is a more efficient and cheaper protocol to run than Bitcoin’s proof-of-work, while keeping all the security guarantees.

**What if you are not online? (Stake pools)**

To produce a block you have to be online, but asking everyone to be online at every moment is impractical and unrealistic. This is why Ouroboros introduces the figure of Stake Delegation. As stakeholder, you can delegate your stake to a third party to act on your behalf whenever you are elected slot leader. Such delegates are known as staking pools. They are members of the community that commit to run the protocol on your behalf and to be online close to 100% of the time.

An important thing to notice is that you only delegate your rights to participate in the protocol, not your actual funds. Your ada are still secure and under your control in your wallet, and funds are not locked, you can still make transactions.

**What about the incentives?**

Stakeholders that issue blocks are incentivized to participate in the protocol by collecting transaction fees. But Ouroboros does not incentivize stakeholders to invest computational resources to issue blocks. Rather, availability and transaction verification are preferred.

Rewards come from two sources: transaction fees and funds drawn from the ada Reserve.

In Ouroboros, incentives are not block-dependant, instead, rewards from an epoch are collected in a pool and distributed among the stakeholders and stake pools that participated during these slots proportional to their stake.

In the case of stake pools, those get a fraction of the rewards to cover operational costs and a profit margin. The rest is distributed among the pool members, including the pool owners, proportionally to the stake that they contributed to the pool.

To participate in the protocol, you can choose a staking pool or choose to act on your own at any moment creating your own stake pool.

**What if for some reason there is a fork?**

Given that stakeholders are not always online, they come and go (a.k.a. dynamic availability), and sometimes they are offline for long periods, it is important for them to be able to resynchronize with the correct chain when they come back online.

The key feature of Ouroboros Genesis is that thanks to a unique chain selection rule, it allows new or re-joining parties to synchronize to the “good chain” with only a trusted copy of the genesis block. This makes the protocol secure against the so-called “long-range attack”.

**Self-produced randomness**

Making the slot leader selection fair and secure (staking procedure) requires a good source of randomness.

Ouroboros protocol (specifically Ouroboros Praos and Ouroboros Genesis) incorporates a Global Random Oracle feature that produces new and fresh randomness at every epoch.

This is achieved by the implementation of a Verifiable Random Function. When evaluated with the key of a stakeholder, It returns a random value which is stored in every new block produced. The hashing of all values from the previous epoch becomes the random seed for the staking procedure. The blockchain itself becomes its source of new randomness.

This is why the protocol is named Ouroboros, the snake that eats its own tail.

**Promoting decentralization**

Finally, the Ouroboros incentives mechanism promotes the decentralization of the system in a better way than Proof-of-work does. Because Ouroboros considers two key scenarios:

In one hand, a staking pool can only act as a delegate if it represents a certain number of stakeholders whose aggregate stake exceeds a given threshold, for example, 0.1% of all the stake in the blockchain. This prevents a fragmentation attack, where someone tries to affect the performance of the protocol by increasing the delegates population.

At the same time, when the aggregate stake of a stake pool grows beyond a certain threshold, rewards become constant. This makes that particular stake pool less attractive since stakeholders would not be maximizing their rewards. For example, if the threshold is set to 1%, a stake pool with a stake of 2% would gain the same rewards as other that has a stake of only 1%.

All these functionalities make Ouroboros the best proof of stake ledger protocol to date. And its only implementation is currently in the Cardano blockchain.

**How it works**

Time is divided into epochs and slots and begins at Genesis. At most one block is produced in every slot. Only the slot leader can sign a block for a particular slot.
Register: The first thing a user needs to do to participate in the protocol is registering to:
a network to synchronize with the ledger
a global clock that indicates the current slot
a global random oracle that produces random values (v) and delivers them to the user

**Staking procedure**

At the beginning of every epoch, the online stakeholders fetch (from the blockchain) the stake distribution from the last block of 2 epochs ago. For example, if the current epoch is epoch 100, the stake distribution used is the distribution as it was in the last block of epoch 98.

Random Oracle: Is a hashing function that takes the random values “v” (included in each block by the slot leader for this purpose) from the first ⅔ slots in previous epoch and hash them together and use it as the random seed to select the slot leaders.

Stakeholders evaluate with their secret key the Verifiable Random Function (VRF) at every slot. If the output value (v) is below a certain threshold, the party becomes slot leader for that block.

**Certificate:** The VRF produces two outputs: a random value (v) and a proof (π) that the slot leader will include in the block he produces to certify that he is the legitimate slot leader for that particular slot.

**Slot leader performs the following duties**

Collects the transactions to be included in his block.
Includes in his block the random value (v) and proof (π) obtained from the VRF output.

Before broadcasting the block, the slot leader generates a new secret key (Key-evolving signature). The public key remains the same, but the secret key is updated in every step and the old key is erased.

It is impossible to forge old signatures with new keys. And it is also impossible to derive previous keys from new ones.
Finally, the slot leader broadcast the new block to the network.

The rewards obtained by the slot leaders are calculated at the end of the epoch. Rewards come from transaction fees and funds from the ada reserve.

**What happens in the case of a fork in the chain?**

A key aspect of the procedure described above is that from time to time, it will produce slots without a slot leader and slots with multiple slot leaders. Meaning that nodes might receive valid chains from multiple sources. To determine which chain to adopt, each party collects all valid chains and applies the Chain Selection Rule. The same thing is done by users that have been offline for a while and need to synchronize with the blockchain.

The node filters all valid chains (chains whose signatures are consistent with the genesis block and with the keys recorded in the Key Evolving Signature protocol, the variable random function and the global random oracle.

**Then applies the Chain Selection Rule**: pick the longest chain as long as it grows more quickly (is denser) in the slots following the last common block to both competing chains.

This chain selection rule allows for a party that joins the network at any time to synchronize with the correct blockchain, based only on a trusted copy of the genesis block and by observing how the chain grows for a sufficient time.

**Reference material**

[**Ouroboros:**](https://eprint.iacr.org/2016/889.pdf) A Provably Secure Proof-of-Stake Blockchain Protocol

[**Ouroboros Praos:**](https://eprint.iacr.org/2017/573.pdf) An adaptively-secure, semi-synchronous proof-of-stake blockchain

[**Ouroboros Genesis:**](https://eprint.iacr.org/2018/378.pdf) Composable Proof-of-Stake Blockchains with Dynamic Availability

**Video**: **What’s an Ouroboros and how you cook it?**

<iframe width="859" height="325" src="https://www.youtube.com/embed/U92Ks8rucDQ" title="Ourobors protocol. The heart of Cardano." frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>


(Re)introduction to Cardano

## **Understanding the Relay and Block Producer topology**

Before we start with the stake pool installation and configuration, it is essential to understand the logical topology of stake pools. Typically every stake pool has one block producer and at least one relay node. To ensure fast propagation of blocks the pool produces, it is recommended to have relays in different geographical locations. To secure the block producer from the internet it should only connect to its own relays, or relays you trust. The relays then connect to the rest of the Cardano network. To minimise the risk of height battles, it is recommended to regularly monitor the propagation time of the relays. We will talk more on this topic in our pool monitoring section later.

In the example below, one block producer is connected to three relays and they are connected to other relays of the Cardano network.

![](https://developers.cardano.org/assets/images/stake-pool-network-11b74855d8543cf9eb0684a2bbc0e829.jpg)

For the operation of a stake pool, some additional nodes in the topology might be useful. For example, a back-up node for block producer is helpful in case the main block producer has an issue e.g. during an upgrade. Depending on the number of stake pools that are being managed, a monitoring node can be used to monitor them and generate alarms. Stake pool operators also need a air-gapped system to store the pool cold keys. Some pool operators use a hardware wallet for storing the pool pledge.

A logical topology of all the components, without considering firewalls and other security aspects can be shown as follows.

![](https://developers.cardano.org/assets/images/stake-pool-setup-3eb92171620ee7e5ea3ab3e0779e9220.jpg)



Understanding the Relay and Block Producer topology

## **Minimum hardware requirements to run a stake pool**

The latest technical specifications and supported platforms can be found on the Cardano Node release page.

Currently the following specifications are recommended on Mainnet:

**Servers:** 1 for block producer node + at least 2 for relay nodes

**CPU:** An Intel or AMD x86 processor with two or more cores at 2GHz or faster

**Memory:** 24GB of RAM

**Storage:** 150GB of free storage (250GB recommended for future growth)

**Operating system**: 64-bit Linux (Ubuntu 18.04+, Mint 19.3+, Debian 10.3+)

**Broadband:** a good network connection with about 1 GB of bandwidth per hour on a public IP4 address

Air-gapped environment for key security

For testnet pools, some requirements are smaller:

Memory: 4GB of RAM

Storage: 20GB of free storage

Air-gapped environment not required

Minimum hardware requirements to run a stake pool

## **Cardano Key Pairs**

It's critical to understand the numerous cryptographic key pairs connected with Cardano, as well as the purpose of each key pair and best practices for securing those keys, before you start working with it. Every ambitious Cardano developer and stake pool operator should get a complete grasp of these key pairs, as well as the ramifications of a single secret (private) key being hacked. Any Cardano developer or stake pool operator must learn how to manage, safeguard, and store private keys in order to succeed.

Cardano cryptographic keys are made up of ed25519 key pairs, which include a public verification key file and a secret (private) key file. The public key file is commonly referred to as keyname.vkey, whereas the private key file is referred to as keyname.skey. The private key file, which is used to sign transactions, is extremely sensitive and should be adequately safeguarded. Under all circumstances, this entails limiting third-party access to your private keys. The most effective technique to prevent private key exposure is to guarantee that the necessary private key is never held for any length of time on any internet-connected machine (hot node). Please note that key pair filenames are completely random and can be named whatever you want.

**danger**

Use extreme caution to avoid losing or overwriting secret (private) keys.

**Wallet address key pairs**

Currently, Cardano wallet addresses only have two parts: a payment address and a counterpart staking address. A payment address (together with its associated key pairs) is used to store, receive, and send money. A stake address (and related keys) is used to store and withdraw rewards, as well as to define the stake pool owner and rewards accounts, as well as the wallet's target stake pool delegation.

payment.vkey is the public verification key file for the payment address (not sensitive; may be shared publicly).

payment.skey is a highly sensitive payment address secret (private) signing key file. The private signing key file gives you access to monies in your payment address and should be kept safe at all times.

**danger**

**Never place payment signing keys on a hot node.**

stake.vkey - stake address public verification key file (not sensitive; may be shared publicly).

stake.skey - It is a sensitive stake address secret (private) signing key file. This private signing key file gives you access to any awards cash held in the stake address, as well as the ability to delegate the wallet to a pool. It's also a good idea to keep an eye on the stake.skey.

payment.addr - This is a Cardano wallet payment address that is usually generated with the help of both a payment.vkey and a stake. As inputs, use the vkey file. If a payment address is merely going to be used to send and receive money, no crucial components need to be staked. In addition, there is a single payment. Multiple unique stake.vkey files can be coupled with vkey to establish different payment addresses that can be staked independently.

stake.addr - stake address for a Cardano wallet and is generated using the stake.vkey file

**Cardano stake pool key pairs**

**Stake pool cold keys**

cold.skey - secret (private) signing key file for a Cardano stake pool (extremely sensitive). The cold.skey is required to register a stake pool, to update a stake pool registration certificate parameters, to rotate a stake pool KES keys and to retire a stake pool.

cold.vkey - public verification key file for a stake pool's cold.skey private signing key file (cold.vkey is not sensitive; can be shared publicly).

cold.counter - incrementing counter file that tracks the number of times an operational certificate (opcert) has been generated for the relevant stake pool.

danger
Always rotate KES keys using the latest cold.counter.

**VRF hot keys**

vrf.skey - secret (private) signing key file for a Cardano stake pool's VRF key (required to start a stake pool's block producing node; sensitive but must be placed on a hot node in order to start a stake pool).

vrf.vkey - public verification key file for a Cardano stake pool's vrf.skey (not sensitive and is not required to start a stake pool's block producing node).

**KES hot keys**

kes.skey- secret (private) signature key file for the stake pool's KES key (needed to start the stake pool's block producing node; sensitive, but must be placed on a hot node to start a stake pool and rotated on a regular basis). KES keys are needed to establish a stake pool's operating certificate, which expires 90 days after the opcert's defined KES period has passed. As a result, fresh KES keys must be generated along with a new opcert every 90 days or sooner for a Cardano Stake pool to continue minting blocks.

kes.vkey - public verification key file for a Cardano stake pool's corresponding kes.skey (not sensitive and is not required to a block producer).

**[References](https://cips.cardano.org/cip/CIP-0019)**

CIP 19 Cardano Addresses

Cardano Key Pairs

## **Cardano Node Installation process (Environment Setup)**

The Cardano node is the core component that underpins the Cardano network. Ultimately, a blockchain network is just a collection of interconnected nodes, all working together to validate transactions and blocks by means of consensus. The definition of consensus for any given network varies, but for the Cardano network it’s defined by the Ouroboros protocol.

In this section, we will walk you through the process of downloading, compiling, and installing cardano-node and cardano-cli into your Linux-based operating system.

**note**

Refer to the official document Installing the node from source in case of difficulties.

**Installing Operating System dependencies**

To download the source code and build it, you need the following packages and tools on your Linux system:

the version control system git,

the gcc C-compiler,

C++ support for gcc,

developer libraries for the arbitrary precision library gmp,

developer libraries for the compression library zlib,

developer libraries for systemd,

developer libraries for ncurses,

ncurses compatibility libraries,

the Haskell build tool cabal,

the GHC Haskell compiler (version 8.10.7 or above).
In Redhat, Fedora, and Centos:

`sudo yum update -y
sudo yum install git gcc gcc-c++ tmux gmp-devel make tar xz wget zlib-devel libtool autoconf jq -y
sudo yum install systemd-devel ncurses-devel ncurses-compat-libs -y`

For Debian/Ubuntu, use the following instead:

`sudo apt-get update -y && sudo apt-get upgrade -y
sudo apt-get install automake build-essential curl pkg-config libffi-dev libgmp-dev libssl-dev libtinfo-dev libsystemd-dev zlib1g-dev make g++ tmux git jq wget libncursesw5 libtool autoconf -y`

If you are using a different flavor of Linux, you will need to use the correct package manager for your platform instead of yum or apt-get, and the names of the packages you need to install might differ.

Installing GHC and Cabal
A popular way to install GHC (Glasgow Haskell Compiler) and Cabal (Common Architecture for Building Applications and Libraries) is to use ghcup.

Use the following command to install ghcup

`curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh`


If you are using a different flavor of Linux, you will need to use the correct package manager for your platform instead of yum or apt-get, and the names of the packages you need to install might differ.

**Installing GHC and Cabal**

A popular way to install GHC (Glasgow Haskell Compiler) and Cabal (Common Architecture for Building Applications and Libraries) is to use ghcup.

Use the following command to install ghcup

`curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh`

Please follow the instructions and provide the necessary input to the installer.

Do you want ghcup to automatically add the required PATH variable to "/home/ubuntu/.bashrc"? - (P or enter)

Do you want to install haskell-language-server (HLS)? - (N or enter)

Do you want to enable better integration of stack with GHCup? - (N or enter)

Press ENTER to proceed or ctrl-c to abort. (enter)

Once complete, you should have ghc and cabal installed to your system.

**note**

ghcup will try to detect your shell and ask you to add it to the environment variables. Please restart your shell/terminal after installing ghcup or apply them in your current terminal session by typing


`source $HOME/.bashrc`

You can check if ghcup has been installed correctly by typing ghcup --version into the terminal. You should see something similar to the following:

`ghcup --version

The GHCup Haskell installer, version v0.1.18.0`

`ghcup will install the latest stable version of ghc. However, as of the time of writing this, Input-Output recommends using ghc 8.10.7. So, we will use ghcup to install and switch to the required version.`


ghcup will install the latest stable version of cabal. However, as of the time of writing this, Input-Output recommends using cabal 3.6.2.0. So, we will use ghcup to install and switch to the required version.

`ghcup install cabal 3.8.1.0
ghcup set cabal 3.8.1.0`

Finally, we check if we have the correct ghc and cabal versions installed.

Check ghc version:

`ghc --version`

You should see something like this:

The Glorious Glasgow Haskell Compilation System, version 8.10.7

Check cabal version:

cabal --version

You should see something like this:

cabal-install version 3.6.2.0
compiled using version 3.6.2.0 of the Cabal library

important
Please confirm that the versions you have installed match the recommended versions above. If not, check if you have missed any of the previous steps.

Downloading & Compiling
Let's create a working directory to store the source-code and builds for the components.

mkdir -p $HOME/cardano-src
cd $HOME/cardano-src

Next, we will download, compile and install libsodium.

git clone https://github.com/IntersectMBO/libsodium
cd libsodium
git checkout dbb48cc
./autogen.sh
./configure
make
sudo make install

Then we will add the following environment variables to your shell profile. E.G $HOME/.zshrc or $HOME/.bashrc depending on what shell application you are using. Add the following to the bottom of your shell profile/config file so that the compiler can be aware that libsodium is installed on your system.

export LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"
export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"

Once saved, we will then reload your shell profile to use the new variables. We can do that by typing source $HOME/.bashrc or source $HOME/.zshrc (depending on the shell application you use).

We need to install secp256k1 which is required from cardano-node version 1.35.0 onward:

Download and install libsecp256k1:

cd $HOME/cardano-src
git clone https://github.com/bitcoin-core/secp256k1
cd secp256k1
git checkout ac83be33
./autogen.sh
./configure --enable-module-schnorrsig --enable-experimental
make
make check
sudo make install
sudo ldconfig

Now we are ready to download, compile and install cardano-node and cardano-cli. But first, we have to make sure we are back at the root of our working directory:

cd $HOME/cardano-src

Download the cardano-node repository:

git clone https://github.com/IntersectMBO/cardano-node.git
cd cardano-node
git fetch --all --recurse-submodules --tags

Switch the repository to the latest tagged commit:

git checkout $(curl -s https://api.github.com/repos/IntersectMBO/cardano-node/releases/latest | jq -r .tag_name)


important
If upgrading an existing node, please ensure that you have read the release notes on GitHub for any changes.

Configuring the build options
We explicitly use the ghc version that we installed earlier. This avoids defaulting to a system version of ghc that might be newer or older than the one you have installed.

cabal update
cabal configure --with-compiler=ghc-8.10.7

If you are running non x86/x64 platform (eg. ARM) please install and configure LLVM with:

sudo apt install llvm-9
sudo apt install clang-9 libnuma-dev
sudo ln -s /usr/bin/llvm-config-9 /usr/bin/llvm-config
sudo ln -s /usr/bin/opt-9 /usr/bin/opt
sudo ln -s /usr/bin/llc-9 /usr/bin/llc
sudo ln -s /usr/bin/clang-9 /usr/bin/clang

Building and installing the node
We can now build the Haskell-based cardano-node to produce executable binaries.

cabal build cardano-node cardano-cli

Install the newly built node and CLI commands to the $HOME/.local/bin directory:

mkdir -p $HOME/.local/bin
cp -p "$(./scripts/bin-path.sh cardano-node)" $HOME/.local/bin/
cp -p "$(./scripts/bin-path.sh cardano-cli)" $HOME/.local/bin/

We have to add this line below our shell profile so that the shell/terminal can recognize that cardano-node and cardano-cli are global commands. ($HOME/.zshrc or $HOME/.bashrc depending on the shell application you use)

export PATH="$HOME/.local/bin/:$PATH"

Once saved, reload your shell profile by typing source $HOME/.zshrc or source $HOME/.bashrc (depending on the shell application you use).

Check the version that has been installed:

cardano-cli --version
cardano-node --version

Congratulations, you have successfully installed Cardano components into your Linux system! 🎉🎉🎉

**References**

[Building cardano-node from source with cabal](https://github.com/input-output-hk/cardano-node-wiki/wiki/install)

[Building cardano-node from source with Nix](https://github.com/input-output-hk/cardano-node-wiki/wiki/building-the-node-using-nix)

Cardano Node Installation process (Environment Setup)

## **Cardano Relay Configuration (Startup scripts, Systemd)**

In the last section, we went through the process of downloading, compiling, and installing cardano-node and cardano-cli into your Linux-based operating system. Now in this section we will walk through the process of configuring the installed node as a relay node.

**Configuration Files**

The cardano-node application requires the following configuration files to run as of writing this article.

**Main Config:** It contains general node settings such as logging and versioning. It also points to the Byron Genesis and the Shelly Genesis file.

**Byron Genesis**: It contains the initial protocol parameters and instructs the cardano-node on how to bootstrap the Byron Era of the Cardano blockchain.

**Shelly Genesis:** It contains the initial protocol parameters and instructs the cardano-node on how to bootstrap the Shelly Era of the Cardano blockchain.

**Alonzo Genesis**: It contains the initial protocol parameters and instructs the cardano-node on how to bootstrap the Alonzo Era of the Cardano blockchain.

**Topology:** It contains the list of network peers (IP Address and Port of other nodes running the blockchain network) that your node will connect to.

**important**

Currently, the cardano-node topology is manually set by the community of network operators in the Cardano blockchain. But an automated p2p (peer-to-peer) system is in the works. For more information visit Introducing our new peer-to-peer (P2P) testnet.

For more information about Cardano blockchain eras and upgrades, please visit the Cardano Roadmap.

The focus of this tutorial is on learning how to setup a stake pool. So we will go through the steps of configuring the relay on a testnet network and not the Mainnet. You can download the current Cardano blockchain network configuration files here:

**Pre-Production Testnet**

`mkdir -p $HOME/cardano-testnet
cd $HOME/cardano-testnet

curl -O -J https://book.world.dev.cardano.org/environments/preprod/config.json
curl -O -J https://book.world.dev.cardano.org/environments/preprod/topology.json
curl -O -J https://book.world.dev.cardano.org/environments/preprod/byron-genesis.json
curl -O -J https://book.world.dev.cardano.org/environments/preprod/shelley-genesis.json
curl -O -J https://book.world.dev.cardano.org/environments/preprod/alonzo-genesis.json
curl -O -J https://book.world.dev.cardano.org/environments/preprod/conway-genesis.json`

**note**

Each network has a config file, genesis file(s), topology file, and unique identifier called the Network Magic.

If your Block Producer node is already setup, you can add it to your relay topology file by adding its IP address and port number to "localRoots".

`nano topology.json

{
  "LocalRoots": {
    "groups": [
      {
        "localRoots": {
          "accessPoints": [
            { "address": "your-blockproducer-address", "port": 6000 }
          ],
          "advertise": false
        },
        "valency": 1
      }
    ]
  },
  "PublicRoots": [
    {
      "publicRoots": {
        "accessPoints": [
          {
            "address": "preprod-node.world.dev.cardano.org",
            "port": 30000
          }
        ],
        "advertise": false
      }
    }
  ],
  "useLedgerAfterSlot": 4642000
}`

**Save and close the topology.json file**.

useLedgerAfterSlot indicates after which slot peers should be fetched from the ledger. A negative value will disable fetching peers from the ledger, and you will need to manually add peers to the topology file.
valency is the number of connections that your node should establish towards a specific group. If you have one IP in localRoots, then it should be 1; if you have one DNS name with two IPs behind it, then it should be 2; or if you have two IPs/DNS names with single IP behind each, then it should also be 2, and so on.

localRoots are for peers which the node should always have as hot connections, such as your BP or your other relays.
publicRoots represent a source of fallback peers, a source of peers to be used if peers from the ledger (useLedgerAfterSlot) are disabled or unavailable.
You can tell the node that the topology configuration file has changed by sending a SIGHUP signal to the cardano-node process, e.g. pkill -HUP cardano-node. After receiving the signal, cardano-node will re-read the file and restart all DNS resolution. Please note that this only applies to the topology configuration file!

**Creating Startup Scripts and Services**

To run an instance of Cardano Node, we create a bash script and configure the options. Additionally, we create a systemd service to start the node which ensures that in case of system reboot or crashes, the Cardano Node starts again automatically.

First, switch to the directory containing configuration files

`cd $HOME/cardano-testnet`

Now create the start script startTestNode.sh

nano startTestNode.sh

**note**

Replace <$HOME> with local values of the $HOME environment variable on each machine. To find those values, run echo $HOME.

copy the following in the file

`#!/bin/bash
# Set a variable to indicate the port where the Cardano Node listens
PORT=6000
# Set a variable to indicate the local IP address of the computer where Cardano Node runs
# 0.0.0.0 listens on all local IP addresses for the computer
HOSTADDR=0.0.0.0
# Set a variable to indicate the file path to your topology file
TOPOLOGY=<$HOME>/cardano-testnet/topology.json
# Set a variable to indicate the folder where Cardano Node stores blockchain data
DB_PATH=<$HOME>/cardano-testnet/db
# Set a variable to indicate the path to the Cardano Node socket for Inter-process communication (IPC)
SOCKET_PATH=<$HOME>/cardano-testnet/db/socket
# Set a variable to indicate the file path to your main Cardano Node configuration file
CONFIG=<$HOME>/cardano-testnet/config.json
#
# Run Cardano Node using the options that you set using variables
#
/usr/local/bin/cardano-node run --topology ${TOPOLOGY} --database-path ${DB_PATH} --socket-path ${SOCKET_PATH} --host-addr ${HOSTADDR} --port ${PORT} --config ${CONFIG}`

**note**

For a detailed understanding of all the configuration parameters, please refer to Running cardano-node

Save and close the startTestNode.sh file.

To set execute permissions for the startTestNode.sh file, type:

chmod +x $HOME/cardano-testnet/startTestNode.sh

To create the folder where Cardano Node stores blockchain data, type:

mkdir $HOME/cardano-testnet/db

To run Cardano Node as a service, use nano to create a file named cardano-testnode.service and then add the following contents to the file.

**note**

Replace <$USER> and <$HOME> with their values of the environment variable. To find the values use following commands:

echo $USER echo $HOME

`[Unit]
Description       = Cardano TestNode Service
Wants             = network-online.target
After             = network-online.target

[Service]
User              = <$USER>
Type              = simple
WorkingDirectory  = <$HOME>/cardano-testnet
ExecStart         = /bin/bash -c '<$HOME>/cardano-testnet/startTestNode.sh'
ExecReload        = pkill -HUP cardano-node
KillSignal        = SIGINT
RestartKillSignal = SIGINT
TimeoutStopSec    = 300
LimitNOFILE       = 32768
Restart           = always
RestartSec        = 5
SyslogIdentifier  = cardano-testnode

[Install]
WantedBy          = multi-user.target`

Save and close the cardano-testnode.service file.

To move the cardano-node.service file to the folder /etc/systemd/system and set file permissions, type:

sudo mv $HOME/cardano-testnet/cardano-testnode.service /etc/systemd/system/cardano-testnode.service sudo chmod 644 /etc/systemd/system/cardano-testnode.service

**Launching Cardano Relay Node**

To start Cardano Node as a service when the computer boots, type:

sudo systemctl daemon-reload sudo systemctl enable cardano-testnode.service

**Now the relay node is ready to start**

sudo systemctl reload-or-restart cardano-testnode

If you have everything set correctly, you should see something like this on using the command journalctl --unit=cardano-node --follow:

`Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.protocol:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] Byron; Shelley
Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.version:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] 1.35.4
Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.commit:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] ebc7be471b30e5931b35f9bbc236d21c375b91bb
Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.nodeStartTime:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] 2022-12-01 14:31:40.958841061 UTC
Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.systemStartTime:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] 2022-06-01 00:00:00 UTC
Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.slotLengthByron:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] 20s
Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.epochLengthByron:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] 21600
Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.slotLengthShelley:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] 1s
Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.epochLengthShelley:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] 432000
Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.slotsPerKESPeriodShelley:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] 129600
Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.slotLengthAllegra:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] 1s
Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.epochLengthAllegra:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] 432000
Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.slotsPerKESPeriodAllegra:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] 129600
Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.slotLengthMary:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] 1s
Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.epochLengthMary:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] 432000
Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.slotsPerKESPeriodMary:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] 129600
Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.slotLengthAlonzo:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] 1s
Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.epochLengthAlonzo:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] 432000
Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.slotsPerKESPeriodAlonzo:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] 129600
Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.slotLengthBabbage:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] 1s
Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.epochLengthBabbage:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] 432000
Dec  1 15:31:40 localhost cardano-testnode[162851]: #033[35m[localhos:cardano.node.basicInfo.slotsPerKESPeriodBabbage:Notice:5]#033[0m [2022-12-01 14:31:40.95 UTC] 129600`

Syncing the blockchain from zero can take a while. Please be patient. If you want to stop syncing, you can do so using the command sudo systemctl stop cardano-node. Restarting the relay node will resume syncing the blockchain.

**Reloading the Topology configuration**

In case you have made an update to topology.json file, since this node is assumed to be running in P2P mode - you can can load these changes without having to perform a full node restart using command below:

sudo systemctl reload cardano-node

Cardano Relay Configuration (Startup scripts, Systemd)

## **Monitoring with gLiveView**

Guild LiveView, often known as gLiveView, is a local bash CLI monitoring utility with an easy-to-use interface for monitoring node status. It connects to the locally running node via the specified EKG/Prometheus node endpoints to collect and show node metrics, network information, and other information in real time. The program recognizes whether the node is being used as a relay or a block producer and adjusts the output accordingly.

To install gLiveView:

Download the latest Guild LiveView script files, type:
curl -s -o gLiveView.sh https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/cnode-helper-scripts/gLiveView.sh
curl -s -o env https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/cnode-helper-scripts/env


To set file permissions on the gLiveView.sh file that you downloaded in step 1, type:
chmod 755 gLiveView.sh

For most setups, it's enough to set CNODE_PORT in the env file.

**note**

Detailed guide and more information can be found on Guild Operators Page

Monitoring with gLiveView

## **Grafana Dashboard Tutorial**

![](https://developers.cardano.org/assets/images/snsky_dashboard-711ff4dc902654c377900fa0269c6848.jpg)

Once your Cardano pool is successfully set up, then comes the most beautiful part - setting up your Dashboard and Alerts!

This documentation brings some of the available information in greater detail and will hopefully help Stake Pool Operators manage their pools more efficiently. This tutorial is for education and learning purposes only!

Prerequisites:

Ubuntu Server 20.04 LTS

Cardano Block Producer Node up and running

Cardano Relay Nodes up and running

**1. Install prometheus node exporter**

First, install Prometheus node exporter on the Block Producing and all Relay Nodes:

`$ sudo apt-get install -y prometheus-node-exporter

$ sudo systemctl enable prometheus-node-exporter.service`

$ sudo apt-get install -y prometheus-node-exporter

$ sudo systemctl enable prometheus-node-exporter.service


Update mainnet-config.json config files with new hasEKG and has Prometheus ports:

$ cd $NODE_HOME
$ sed -i config.json -e "s/127.0.0.1/0.0.0.0/g"

On Producer Node open ports 12798 and 9100

$ sudo ufw allow proto tcp from <Monitoring Node IP address> to any port 9100

$ sudo ufw allow proto tcp from <Monitoring Node IP address> to any port 12798

$ sudo ufw reload

Restart the nodes:

$ sudo systemctl restart <your node name e.g. cardano-testnode>

2. Install Prometheus on the Monitoring Node
Install Prometheus on the Monitoring Node - the Node where the Grafana Server will run. This could be one of the Relay nodes or a separate dedicated node for monitoring.

$ sudo apt-get install -y prometheus

3. Install Grafana on Monitoring Node
$ wget -q -O - https://packages.grafana.com/gpg.key | sudo apt-key add -

$ echo "deb https://packages.grafana.com/oss/deb stable main" > grafana.list
$ sudo mv grafana.list /etc/apt/sources.list.d/grafana.list

$ sudo apt-get update && sudo apt-get install -y grafana

Enable services so they start automatically:

$ sudo systemctl enable grafana-server.service
$ sudo systemctl enable prometheus.service
$ sudo systemctl enable prometheus-node-exporter.service

Update prometheus.yml located in /etc/prometheus/prometheus.yml:

Change the ip address in the following command:


`$ cat > prometheus.yml << EOF
global:
  scrape_interval:     15s # By default, scrape targets every 15 seconds.

  # Attach these labels to any time series or alerts when communicating with
  # external systems (federation, remote storage, Alertmanager).
  external_labels:
    monitor: 'codelab-monitor'

# A scrape configuration containing exactly one endpoint to scrape:
# Here it's Prometheus itself.
scrape_configs:
  # The job name is added as a label job=<job_name> to any timeseries scraped from this config.
  - job_name: 'prometheus'

    static_configs:
      - targets: ['localhost:9100']

        labels:
          alias: 'relaynode1'
          type:  'cardano-node'

      - targets: ['<relay node 2 public ip address>:9100']

        labels:
          alias: 'relaynode2'
          type:  'cardano-node'
      - targets: ['<block producer public ip address>:9100']

        labels:
          alias: 'block-producer-node'
          type:  'cardano-node'
     - targets: ['localhost:12798']
        labels:
          alias: 'relaynode1'
          type:  'cardano-node'

     - targets: ['<relay node 2 public ip address>:12798']

        labels:
          alias: 'relaynode2'
          type:  'cardano-node'

     - targets: ['<block producer public ip address>:12798']
        labels:
          alias: 'block-producer-node'
          type:  'cardano-node'

EOF`

if you have more than two Relay Nodes, add all your Relays as new "targets" in the config above:

$ sudo mv prometheus.yml /etc/prometheus/prometheus.yml

Restart the services:

$ sudo systemctl restart grafana-server.service
$ sudo systemctl restart prometheus.service
$ sudo systemctl restart prometheus-node-exporter.service

Verify that the services are running properly:

$ sudo systemctl status grafana-server.service prometheus.service prometheus-node-exporter.service

On the Monitoring Node, open port 3000 for Grafana:

$ sudo ufw allow from <your home IP address from where you plan to access Grafana> to any port 3000

**note**

Please refer to Grafana Labs Security for hardening: e.g. by default the communication with the Grafana server is unencrypted.

4. Setting up Grafana Dashboard
On Relay Node, open http://localhost:3000 or http://your Relay Node ip address:3000 in your local browser.

Login with admin / admin

Change password

![](https://developers.cardano.org/assets/images/snsky_prometheus-9048448c210ab690edf45f82500421d4.jpg)


Click the configuration gear icon, then Add data Source

Select Prometheus

Set Name to "Prometheus"

Set URL to http://localhost:9090

Click Save & Test

Download my Dashboard that you see on the top of this page, from the following GitHub link and save the JSON file

SNSKY Dashboard Example

in Grafana, Click Create + icon (in left Menu) > Import Add dashboard by Upload JSON file Click the Import button.

If you nodes are in several time zones, it is useful to add the Grafana Clock panel

`$ grafana-cli plugins install grafana-clock-panel`


Installed panels are available immediately in the Dashboards section in your Grafana main menu.

To see a list of installed panels, click the Plugins item in the main menu. Both core panels and installed panels will appear.

5. Add Data from Cexplorer to the Dashboard
Cexplorer provides API where we can collect data for our pool. Run following commands to create directory for our pool statistic and script. Metric adapools_pledged is missing in cexplorer(a tool what will substitute adapools), so you might see relative data missing on dashboard from SNSKY, mentioned above.

`cd /$NODE_HOME

mkdir -p poolStat

cd poolStat

echo "curl https://js.cexplorer.io/api-static/pool/< YOUR POOL BECH 32 POOL ID >.json 2>/dev/null \\
| jq '.data' | jq 'del(.stats, .url , .img, .updated, .handles, .pool_id, .name, .pool_id_hash)' \\
| tr -d \\\"{},: \\
| awk NF \\
| sed -e 's/^[ \t]*/cexplorer_/' > poolStat.prom" > getstats.sh

chmod +x getstats.sh

./getstats.sh
`

check the content of poolStat.prom and it should not contain only numeric values:

$ nano poolStat.prom

Configure prometheus-node-exporter.service to grab data from the poolStat.prom file:

$ sudo cp /lib/systemd/system/prometheus-node-exporter.service /lib/systemd/system/prometheus-node-exporter.service_backup

$ sudo nano /lib/systemd/system/prometheus-node-exporter.service


Change ExecStart line to:

ExecStart=/usr/bin/prometheus-node-exporter --collector.textfile.directory=< YOUR NODE FULL PATH >/poolStat --collector.textfile


Reload daemon and restart services:

$ sudo systemctl daemon-reload

$ sudo systemctl restart prometheus-node-exporter.service

$ sudo systemctl restart prometheus.service

Now you should see in the Dashboard all Cexplorer statistics

Since the statistics will change, lets set cron job to update data from Cexplorer everyday

$ crontab -e

##############################

#Get data from Cexplorer every day at 06:00

0 6 * * * <YOUR NODE FULL PATH >/poolStat/getstats.sh

##############################

Done!

6. Set up Grafana Alerting and Email Notifications
Set up SMTP in Grafana:

$ sudo nano /etc/grafana/grafana.ini

Edit the SMTP section:

#############################

[smtp]
enabled = true
host = smtp.<email server>:465
user = <email user name>
# If the password contains # or ; you have to wrap it with triple quotes. Ex """#password;"""
password = <email password>
from_address = sam@sanskys.de
from_name = Grafana

#############################

Log in to Grafana with username and password:


![](https://developers.cardano.org/assets/images/snsky_EmailAlert-7dff5020a2aadc8ac4af1264fa3118ae.jpg)

Click on the "Bell" icon on the left sidebar.

Select "Notification channels."

Click on "Add Channel." This will open a form for adding new notification channel.

Give a name to this channel. I am using "Alert"

Select Email from "Type" as we want to send notifications over email.

Check the "Send on all alerts" in case you want email on all alerts.

Select the checkbox of "Include image" in case you want to include the image of the panel as the body in the notification email.

Add the target email in "Email addresses" text area. You can use multiple email address separated by ";"

Click on "Send Test" if you want to verify your settings. This will send a sample email using the SMTP details we configured earlier.

Click on "Save" to add this channel

Create an Alert if Producer Node is not reachable

`https://developers.cardano.org/assets/images/snsky_PeerAlert-88ec86223b142e44ee49fa17fe71c336.jpg`


Please not that Alerts can only be created for "Graph" panels!

Now we create an Alert to get an email if the Producer Node is not reachable

In the "Connected Peers" panel go to Alerts

Define the Rule "Connected Peer Alert" Evaluate every "1m" For "2m"

Condition

WHEN "last()" OF "query(A, 1m, now)" "HAS NO VALUE"

No Data & Error Handling

If no data or all values are null SET STATE TO "No Data"

If execution error or timeout SET STATE TO "Alerting"

Notifications

Send To - Choose your notification channel, which in my case is "Alert"

Message - type in your alert message that should appear in the email

Press on "test Rule" to ensure that the Alert is correct and has no issues.

Now you are done! Stop you Producer Node and you should get an Alert within 4min.

note

If everything works, now you should have a smile on your face! And if you wish to support the Tutorial work, you could donate or delegate to my pool - SNSKY

Donation Address
 addr1qyyhd8cpv4gmhr5axerhezhtzldrw4rp9ayf0fc6arnme4cg46du2qg366943uy0dw5yjmna7arfw265lu4r2fjccl4scf7xrw SNSKY Pool ID 075578defd7ee97cbeaa2937e5819099cb3835ac9f9c8b1a2c3a3578

**7. Recommended:** Disabling Grafana Registrations and Anonymous Access

We should make Grafana a bit more secure. To do so let's change two settings:

$ sudo nano /etc/grafana/grafana.ini

Locate the following allow_sign_up directive under the [users] heading and change the line as follows:

`##########

[users] # disable user signup / registration

allow_sign_up = false

##########`

Next, locate the following enabled directive under the [auth.anonymous] heading and change the line as follows:

[auth.anonymous]

enabled = false

Save the file and exit your text editor. To activate the changes, restart Grafana.

$ sudo systemctl restart grafana-server

**8. Advanced Users: Slot Leader Panel**

`https://developers.cardano.org/assets/images/snsky_leaderPanel-ad1d395b4ef55b3e7ca790b1eb2fdaa5.jpg`

Once your pool gets big and is regularly minting blocks, it becomes difficult to keep track of all Leader Slots and also to identify the available gaps for pool maintenance. This Slot Leader Panel is quite helpful as it gives a good overview of all scheduled Slots in TimeSeries.

Use cardano-cli to query the leadership schedule. Since the result has to interpreted by Grafana, we need to format the query output to a CSV readable syntax.

note
The cardano-cli query requires additional RAM. Please refer to query leadership-schedule for more details. I needed 16GB RAM + 8GB SWAP and it took several minutes to query the leadership schedule.

The whole script can be copied from here:

Slot Leader Script

In case the slot.csv file is on a different node, copy it to your Grafana Monitoring node manually. This step could be automated but I don't wish to open extra ports for this so I just copy and paste the content of the slot.csv file.

Next, we add the CSV Plugin to Grafana. Please follow the instructions under the section "Installing on a local Grafana:"

Grafana CSV Plugin

After the installation, in Data Sources now the CSV Plugin should be listed. Configure the CSV Plugin by specifying the location of the slot.csv file. Save & Test and if all steps were followed correctly, you should get the green success message.

The final step is to add the Slot Leader Panel to your dashboard. For that click on the "Add Panel" and "Add New Panel" icons.

Then click on "Query inspector" and and "JSON" buttons.

Delete the existing JSON code and replace it with the following:

Slot Leader Panel

Now click on "Apply" and thats it! You should be able to see all your Leader Slots from last 6 Hrs to next 18 Hrs and this time window shifts automatically.

**Happy minting!**

9. Adding crypto exchange rates to your Grafana
It may not be healthy to look into price all day long, but it could be useful to have it in one place on the Grafana dashboard.

Below is an example using Kraken exchange's API for fetching prices. One may elect any alternate API provider for price and adapt the suggestions easily.

Below is the main snippet that will populate data to Prometheus (keeping in line with the folder structure used on this page). It is essential to ensure that jq and curl are already present on the system.

Let's start by creating $NODE_HOME/poolStat/prices.sh with contents as per below:


`PRICES=$(curl -s https://api.kraken.com/0/public/Ticker?pair=ADAEUR,ADAUSD,XXBTZUSD,XETHZUSD)
echo $PRICES | jq .result.ADAEUR.c | jq .[0] | sed 's/"//g'| sed 's/^/adaeur /' > $NODE_HOME/poolStat/price.prom
echo $PRICES | jq .result.ADAUSD.c | jq .[0] | sed 's/"//g'| sed 's/^/adausd /' >> $NODE_HOME/poolStat/price.prom
echo $PRICES | jq .result.XXBTZUSD.c | jq .[0] | sed 's/"//g'| sed 's/^/btcusd /' >> $NODE_HOME/poolStat/price.prom
echo $PRICES | jq .result.XETHZUSD.c | jq .[0] | sed 's/"//g'| sed 's/^/ethusd /' >> $NODE_HOME/poolStat/price.prom`

As you can see it is very simple script with self explanatory code and if you need any other currency to be added first just check out curl -s https://api.kraken.com/0/public/AssetPairs as it should return all available asset pairs and add your needed pair in the bottom with respective code(what should be quite easy to do).

Now you need to make this script executable:


chmod +x $NODE_HOME/poolStat/prices.sh

Run $NODE_HOME/poolStat/prices.sh at shell and ensure that you see file $NODE_HOME/poolStat/price.prom with content similar to below:

adaeur 0.502300
adausd 0.531625
btcusd 30187.90000
ethusd 2012.02000

Then you should go to your Grafana and check explore and then metrics browser menu and there you should able to see adaeur, adausd and other metrics what we write to file.

If metrics are there, then you must configure cron to run that script every minute, so you will get fresh data every minute:

crontab -l 2>/dev/null; echo "* * * * * $NODE_HOME/poolStat/prices.sh") | crontab -

Now all is left is to create a graph with prices: it is a rather trivial task and no explanation is necessary.

Cheers!

Grafana Dashboard Tutorial

## **Generating wallet keys (Faucet for tADA)**

Once the relay nodes in our last section are in sync with our chosen testnet network, it's time to configure one of these relays into a block producing node. In this section we will create wallet keys which are needed to register a pool and run the block producer.

A wallet address is needed to pay the pool deposit, to pay transaction costs of the network, and for staking to a pool. So it's a combination of payment keys and stake keys.

Let's first create a directory to store all the keys.

mkdir -p $HOME/cardano-testnet/keys
cd $HOME/cardano-testnet/keys

**important**

Due to security reasons, for the Mainnet these keys should be generated and stored on an air-gapped system, but since we are working on a testnet, we can generate and keep them on the block producing node.

**Generating Payment Keys**

Create a new payment key pair: payment.skey & payment.vkey

`cardano-cli address key-gen \
    --verification-key-file payment.vkey \
    --signing-key-file payment.skey`

cardano-cli address key-gen: generates a payment key-pair.

--verification-key-file: points to the path where you want to save the vkey file.

--signing-key-file: points to the path where you want to save the skey file.

.vkey / Public Verification Key : Is used to derive a Cardano wallet address, a wallet address is basically the hash string value that you share to other users to provide them a way to send ada / tAda or other assets in the Cardano blockchain into your wallet.

.skey / Private Signing Key : Is used to sign / approve transactions for your wallet. As you can imagine, it is very important to not expose this file to the public and must be kept secure.

**Generating Stake Keys**

Create a new stake address key pair: stake.skey & stake.vkey

`cardano-cli stake-address key-gen \
    --verification-key-file stake.vkey \
    --signing-key-file stake.skey`

Create your stake address from the stake address verification key and store it in stake.addr:

`cardano-cli stake-address build \
    --stake-verification-key-file stake.vkey \
    --out-file stake.addr \
    --testnet-magic 1`

Generating Wallet Keys
The next step would be to generate a wallet address for the payment key payment.vkey which will delegate to the stake address stake.vkey:

`cardano-cli address build \
    --payment-verification-key-file payment.vkey \
    --out-file payment.addr \
    --testnet-magic 1`

cardano-cli address build : Generates a wallet address from a vkey file.
--payment-verification-key-file : The path to the vkey file to be used for the derivation.
--out-file : The path to save the wallet address file.
--testnet-magic : The NetworkMagic of the network that where you want to use the wallet address. In this case it is 1.
The payment.addr file contains the derived wallet address from your vkey file. It should look something like this:

`addr_test1vqe09nt0rxgwn83upxuhqzs4aqrzdjqmhrh5l4g5hh4kc6qsncmku`

The wallet is currently empty, so if we check its balance now:

`cardano-cli query utxo \
    --address $(cat payment.addr)\
    --testnet-magic 1`

`cardano-cli query utxo \
    --address $(cat payment.addr)\
    --testnet-magic 1`

we should get something like this:

                           TxHash                                 TxIx        Amount
--------------------------------------------------------------------------------------

The next step is to fund the payment address.

Testnets faucet
Since the Cardano testnets are independent networks, separate from the Cardano mainnet, they require their own tokens.

The faucet is a web-based service that provides test ada to users of the Cardano testnets. While these tokens have no "real world" value, they enable users to experiment with Cardano testnet features, without having to spend real ada on the Mainnet.

To apply for Testnets faucet please follow the instructions on the webpage below and choose the Pre-Production Testnet.

Cardano Docs - Testnets faucet

Once the test ADA are transferred and you run the above query utxo again, you should see something like this:

                           TxHash                                 TxIx        Amount
--------------------------------------------------------------------------------------
531f4bec36af503654c3c6fa34ecf07e5c29f67da8e2b84c8923b8c735b011c9     0        10000000000 lovelace + TxOutDatumNone


Now the pool wallet and stake keys are ready and we can go to the next step of creating the pool keys.

References

[CIP 19 Cardano Addresses](https://cips.cardano.org/cip/CIP-0019)





Generating wallet keys (Faucet for tADA)

## **Generating Cardano Block producer Keys**

To run a stake pool, three key pairs are needed:

Cold keys

KES keys

VRF keys

To understand the purpose of these keys, refer to Cardano Key Pairs.

First we change to the keys folder we created in last chapter -

cd $HOME/cardano-testnet/keys

Generating Cold Keys
Make a set of cold keys and create the cold counter file.

cardano-cli node key-gen \
    --cold-verification-key-file cold.vkey \
    --cold-signing-key-file cold.skey \
    --operational-certificate-issue-counter cold.counter

Generating KES Keys
cardano-cli node key-gen-KES \
    --verification-key-file kes.vkey \
    --signing-key-file kes.skey

Generating VRF Keys
Make a VRF key pair.

cardano-cli node key-gen-VRF \
    --verification-key-file vrf.vkey \
    --signing-key-file vrf.skey

and update vrf key permissions to read-only.

chmod 400 vrf.skey

StakePool operational certificate generation
Determine the number of slots per KES period from the genesis file.

slotsPerKESPeriod=$(cat ../shelley-genesis.json | jq -r '.slotsPerKESPeriod')
echo slotsPerKESPeriod: ${slotsPerKESPeriod}

slotNo=$(cardano-cli query tip --testnet-magic 1 | jq -r '.slot')
echo slotNo: ${slotNo}

Find kesPeriod by dividing the slot tip number by slotsPerKESPeriod.

kesPeriod=$((${slotNo} / ${slotsPerKESPeriod}))
echo kesPeriod: ${kesPeriod}
startKesPeriod=${kesPeriod}
echo startKesPeriod: ${startKesPeriod}

With this calculation, we can generate an operational certificate for the pool. Change the {startKesPeriod} in script from the value above accordingly.

cardano-cli node issue-op-cert \
    --kes-verification-key-file kes.vkey \
    --cold-signing-key-file cold.skey \
    --operational-certificate-issue-counter cold.counter \
    --kes-period <startKesPeriod> \
    --out-file node.cert

Update Startup Script
If we run gLiveView now, we will see that the node is running as a Relay.

cd ..
./gLiveView.sh

![](https://developers.cardano.org/assets/images/snsky_relay-e95925003b4152a67443bee8bf3a46ef.jpg)

To update the node startup script with the new KES, VRF and Operation Certificate:

`cat > startTestNode.sh<< EOF 
#!/bin/bash
# Set a variable to indicate the port where the Cardano Node listens
PORT=6001
# Set a variable to indicate the local IP address of the computer where Cardano Node runs
# 0.0.0.0 listens on all local IP addresses for the computer
HOSTADDR=0.0.0.0
# Set a variable to indicate the file path to your topology file
TOPOLOGY=$HOME/cardano-testnet/topology.json
# Set a variable to indicate the folder where Cardano Node stores blockchain data
DB_PATH=$HOME/cardano-testnet/db
# Set a variable to indicate the path to the Cardano Node socket for Inter-process communication (IPC)
SOCKET_PATH=$HOME/cardano-testnet/db/socket
# Set a variable to indicate the file path to your main Cardano Node configuration file
CONFIG=$HOME/cardano-testnet/config.json
# Set the pool keys
KES=$HOME/cardano-testnet/keys/kes.skey
VRF=$HOME/cardano-testnet/keys/vrf.skey
CERT=$HOME/cardano-testnet/keys/node.cert
#
# Run Cardano Node using the options that you set using variables
#
cardano-node run --topology \${TOPOLOGY} --database-path \${DB_PATH} --socket-path \${SOCKET_PATH} --host-addr \${HOSTADDR} --port \${PORT} --config \${CONFIG} --shelley-kes-key \${KES} --shelley-vrf-key \${VRF} --shelley-operational-certificate \${CERT}
EOF`

Restart the node:

sudo systemctl reload-or-restart cardano-testnode

After the restart, if we run gLiveView again we should see that the node has changed from Relay to Core Node:


`https://developers.cardano.org/assets/images/snsky_producer-6b045bf03699b4e569f33cab1e6d3320.jpg`

Now we have converted the relay node to block producing node. The next step will be to register the pool on the network.


Generating Cardano Block producer Keys

## **Registering a Stake Address**

Registering a new stake pool involves two steps - Registering a stake address and registering the the pool metadata. The stake address needs to be registered on the blockchain to be useful and it requires:

Creating a registration certificate.
Submitting the certificate to the blockchain with a transaction.
To build the transaction the following information will be collected first:

tx-in: UTXO of the address that pays for the transaction and deposit
tx-out: The transaction output as ADDRESS VALUE
invalid-hereafter: Time that transaction is valid until (in slots)
certificate-file: stake address registration certificate
fee: The fee amount in Lovelace
tx-in:
Query the UTXO of the address that pays for the transaction and deposit:

cd $HOME/cardano-testnet/keys

cardano-cli query utxo \
    --address $(cat payment.addr) \
    --testnet-magic 1 > fullUtxo.out

The result should look like the following:

cat fullUtxo.out
>                            TxHash                                 TxIx      Amount
> ----------------------------------------------------------------------------------------
> b64ae44e1195b04663ab863b62337e626c65b0c9855a9fbb9ef4458f81a6f5ee     1      1000000000 lovelace

so in this case the required UTXO would be b64ae44e1195b04663ab863b62337e626c65b0c9855a9fbb9ef4458f81a6f5ee#1.

tx-out:
This would be payment.addr and the amount that has to be paid. Since we don't know how much the transaction will cost we put it as 1 ADA for the moment - $(cat payment.addr)+1000000

invalid-hereafter:
Find out the current slot:

currentSlot=$(cardano-cli query tip --testnet-magic 1 | jq -r '.slot')
echo Current Slot: $currentSlot

The invalid-hereafter value must be greater than the current tip. In this example, we use current slot + 1000 - $currentSlot+1000.

certificate:
Create a stake address registration certificate:

cardano-cli stake-address registration-certificate \
    --stake-verification-key-file stake.vkey \
    --out-file stake.cert

witness-override:
When calculating the fee for a transaction, the --witness-count option indicates the number of keys signing the transaction. You must sign a transaction submitting a stake address registration certificate to the blockchain using the secret key for the payment address spending the input, as well as the secret key for the stake address to register.

**fee:**

Now, we build the transaction which will return the tx.raw transaction file and also the transaction fees:

cardano-cli conway transaction build \
    --tx-in b64ae44e1195b04663ab863b62337e626c65b0c9855a9fbb9ef4458f81a6f5ee#1 \
    --tx-out $(cat payment.addr)+1000000 \
    --change-address $(cat payment.addr) \
    --testnet-magic 1 \
    --certificate-file stake.cert \
    --invalid-hereafter $(( ${currentSlot} + 1000)) \
    --witness-override 2 \
    --out-file tx.raw

The output is the transaction fee in lovelace:

Estimated transaction fee: Lovelace 172013

Registering the stake address, not only pays transaction fees, but also includes a deposit (which you get back when deregister the key) as indicated in the protocol parameters.

The deposit amount can be found in protocol.json under stakeAddressDeposit:

cardano-cli query protocol-parameters \
    --testnet-magic 1  \
    --out-file protocol.json

stakeAddressDeposit=$(cat protocol.json | jq -r '.stakeAddressDeposit')
echo $stakeAddressDeposit

Build the transaction
Next, the complete transaction output is calculated by subtracting the deposit and transaction fees from the amount we have in our payment address:

txOut=$((1000000000-${stakeAddressDeposit}-172013))
echo ${txOut}

Now we have all the information in place to build the final transaction file:

cardano-cli conway transaction build-raw \
    --tx-in b64ae44e1195b04663ab863b62337e626c65b0c9855a9fbb9ef4458f81a6f5ee#1 \
    --tx-out $(cat payment.addr)+${txOut} \
    --invalid-hereafter $((${currentSlot} + 1000)) \
    --fee 172013 \
    --certificate-file stake.cert \
    --out-file tx.raw

Sign and Submit the transaction
Sign the transaction with both the payment and stake secret keys:

cardano-cli conway transaction sign \
    --tx-body-file tx.raw \
    --signing-key-file payment.skey \
    --signing-key-file stake.skey \
    --testnet-magic 1 \
    --out-file tx.signed

And submit it:

cardano-cli conway transaction submit \
    --tx-file tx.signed \
    --testnet-magic 1 

In the next section we will register the pool metadata.

References

[CIP 19 Cardano Addresses](https://cips.cardano.org/cip/CIP-0019)

Registering a Stake Address

## **Registering a Pool (JSON Metadata)**

Registering your stake pool requires:

Create JSON file with your metadata and store it in the node and in a URL you maintain

Get the hash of your JSON file

Generate the stake pool registration certificate

Create a delegation certificate pledge

Submit the certificates to the blockchain

**note**

Generating the stake pool registration certificate and the delegation certificate requires the cold keys. So, when doing this on mainnet you may want to generate these certificates in your local machine taking the proper security measures to avoid exposing your cold keys to the internet.

**Create JSON file with your metadata**

ticker must be between 3-9 characters in length. Characters must be A-Z and 0-9 only. description cannot exceed 255 characters in length.

`cat > poolMetaData.json << EOF
{
"name": "YourPoolName",
"description": "Your pool description",
"ticker": "PN",
"homepage": "https://yourpoollink.com"
}
EOF`

Calculate the hash of your metadata file. Here it's saved to poolMetaDataHash.txt:

cardano-cli stake-pool metadata-hash --pool-metadata-file poolMetaData.json > poolMetaDataHash.txt

Get the hash of your JSON file
Make your poolMetadata.json available as a web URL accessible on internet, ideally without redirections. You can do so by uploading it to your website as well. Verify the metadata hashes by comparing your uploaded .json file and your local .json file's hash.

cardano-cli stake-pool metadata-hash --pool-metadata-file <(curl -s -L <https://REPLACE WITH YOUR METADATA_URL>)

cat poolMetaDataHash.txt


Both the hashes must be equal. If the hashes do no match, then the uploaded .json file likely was truncated or extra whitespace caused issues. Upload the .json again or to a different web host.

Generate the stake pool registration certificate
Find the minimum pool cost:

minPoolCost=$(cat protocol.json | jq -r .minPoolCost)
echo minPoolCost: ${minPoolCost}

Generate the stake pool registration certificate:

cardano-cli stake-pool registration-certificate \
    --cold-verification-key-file cold.vkey \
    --vrf-verification-key-file vrf.vkey \
    --pool-pledge 100000000 \
    --pool-cost 340000000 \
    --pool-margin 0.01 \
    --pool-reward-account-verification-key-file stake.vkey \
    --pool-owner-stake-verification-key-file stake.vkey \
    --testnet-magic 1 \
    --single-host-pool-relay <dns based relay, example ~ relaynode1.yourpoolname.com>  \
    --pool-relay-port 6000 \
    --metadata-url <url where you uploaded poolMetaData.json> \
    --metadata-hash $(cat poolMetaDataHash.txt) \
    --out-file pool.cert

important
In case you have multiple relays, please substitute the single-host-pool-relay & pool-relay-port lines from above with the below code accordingly.

DNS based relays, 1 entry per DNS record

    --single-host-pool-relay <relaynode1.yourpoolname.com> \
    --pool-relay-port 6000 \
    --single-host-pool-relay <relaynode2.yourpoolname.com> \
    --pool-relay-port 6000 \

Round Robin DNS based relays, 1 entry per SRV DNS record

    --multi-host-pool-relay <relaynodes.yourpoolname.com> \
    --pool-relay-port 6000 \

IP based relays, 1 entry per IP address

    --pool-relay-port 6000 \
    --pool-relay-ipv4 <first relay node public IP> \
    --pool-relay-port 6000 \
    --pool-relay-ipv4 <second relay node public IP> \

![](https://media.discordapp.net/attachments/980490396356476938/1335904858854789203/image.png?ex=67a1ddda&is=67a08c5a&hm=3ef6d19c1f1044ecdb5d4bbfd4df6e4e32a999ec44ef2bfc4ade0b6b79eab93d&=&format=webp&quality=lossless&width=777&height=846)

*--metadata-url: The provided string must have at most 64 characters, but it has 70 characters

and you must generate the certificate again with the new, shorter URL.

Create a delegation certificate pledge
To honor your pledge, create a delegation certificate:

cardano-cli stake-address delegation-certificate \
    --stake-verification-key-file stake.vkey \
    --cold-verification-key-file cold.vkey \
    --out-file deleg.cert

This creates a delegation certificate which delegates funds from all stake addresses associated with key stake.vkey to the pool belonging to cold key cold.vkey. If there are many staking keys as pool owners in the first step, we need delegation certificates for all of them.

Submit the certificates to the blockchain
To understand the basics of submitting a transaction on the chain, refer to Register Stake Address.

Registering a stake pool requires a deposit. This amount is specified in the already created protocol.json:

stakePoolDeposit=$(cat protocol.json | jq -r '.stakePoolDeposit')
echo $stakePoolDeposit

Let's find out how much balance is in our wallet:

`cardano-cli query utxo \
    --address $(cat payment.addr) \
    --testnet-magic 1 > fullUtxo.out

tail -n +3 fullUtxo.out | sort -k3 -nr > balance.out

cat balance.out

tx_in=""
total_balance=0
while read -r utxo; do
    type=$(awk '{ print $6 }' <<< "${utxo}")
    if [[ ${type} == 'TxOutDatumNone' ]]
    then
        in_addr=$(awk '{ print $1 }' <<< "${utxo}")
        idx=$(awk '{ print $2 }' <<< "${utxo}")
        utxo_balance=$(awk '{ print $3 }' <<< "${utxo}")
        total_balance=$((${total_balance}+${utxo_balance}))
        echo TxHash: ${in_addr}#${idx}
        echo ADA: ${utxo_balance}
        tx_in="${tx_in} --tx-in ${in_addr}#${idx}"
    fi
done < balance.out
txcnt=$(cat balance.out | wc -l)
echo Total available ADA balance: ${total_balance}
echo Number of UTXOs: ${txcnt}`

You should get output similar to below:

Total available ADA balance: 9497237500
Number of UTXOs: 1

Calculate the change for --tx-out. Since we don't know the exact transaction fees yet, we take 1 ada for the calculation:

expr UTxO BALANCE - poolDeposit - TRANSACTION FEE

which in our case would be 9497237500 - 500000000 - 1000000 = 8996237500

`cardano-cli conway transaction build \
    ${tx_in} \
    --tx-out $(cat payment.addr)+8996237500 \
    --change-address $(cat payment.addr) \
    --testnet-magic 1 \
    --certificate-file pool.cert \
    --certificate-file deleg.cert \
    --invalid-hereafter $(( ${currentSlot} + 1000)) \
    --witness-override 2 \
    --out-file tx.raw`

would give transaction fees as output like:

Estimated transaction fee: Lovelace 172189

So now we replace the 1 ada with 172189 Lovelace in our calculation:

txOut=$((9497237500-${stakePoolDeposit}-172189))
echo ${txOut}

Build the transaction:

`cardano-cli conway transaction build-raw \
    ${tx_in} \
    --tx-out $(cat payment.addr)+${txOut} \
    --invalid-hereafter $((${currentSlot} + 1000)) \
    --fee 172189 \
    --certificate-file pool.cert \
    --certificate-file deleg.cert \
    --out-file tx.raw`

`Sign the transaction:`

`cardano-cli conway transaction sign \
    --tx-body-file tx.raw \
    --signing-key-file payment.skey \
    --signing-key-file cold.skey \
    --signing-key-file stake.skey \
    --testnet-magic 1 \
    --out-file tx.signed`

Submit the transaction:

`cardano-cli conway transaction submit \
    --tx-file tx.signed \
    --testnet-magic 1`

In case you took a break, you might have passed the --invalid-hereafter slot and would get an error. In that case you would need to submit the transaction again with it's updated value. Another common error message is FeeTooSmallUTxO, which means that the transaction fee we provided before is not enough and we need to change the fees to the new value provided with the error message and resubmit.

Verify that your stake pool registration was successful
Get pool ID:

cardano-cli stake-pool id --cold-verification-key-file cold.vkey --output-format hex > stakepoolid.txt
cat stakepoolid.txt

Check for the presence of your pool ID on the network, with:

cardano-cli query stake-snapshot --stake-pool-id $(cat stakepoolid.txt) --testnet-magic 1

A non-empty string returned means you're registered. Congratulations!

Additionally you can check your pool on any of the PreProd explorers like PreProd Cexplorer

Registering a Pool (JSON Metadata)

## **Hardening the server**

Before installing your Cardano node, you need to have a clean and secured OS. This guide explains how to secure your server, in 10 steps.

Prerequisites
This guide is designed for Ubuntu Server (22.04 LTS or 20.04 LTS)
A SSH client on your local machine. If you are using a Windows machine, install OpenSSH Client (guide)
SSH server up and running on your Ubuntu Server
1- Create a non-root user for your Cardano node
First thing first : you should never use the root account to connect to your server and manage it. Instead, use a non-root account, that can use sudo. We are going to create one.

Connect to your server with SSH (for this time only, you might use root. We'll disable it after anyway. You can also use the default user created by the Ubuntu installer).
ssh <defaultuser>@server-ip

New user creation called cardano (or whatever you want)
sudo useradd -m -s /bin/bash cardano

Set a strong password
sudo passwd cardano

Allow cardano user to use sudo command
sudo usermod -aG sudo cardano

Disconnect from your server, and reconnect using your new user
ssh cardano@server-ip

Remove default user if needed
sudo userdel <defaultuser>

2- Disable root
You should never use root account. Always use sudo to run commands with privileges. We are going to disable it.

sudo passwd -l root

3- Update System
It's time to update your system with the latest pathes available.

sudo apt-get update -y
sudo apt-get upgrade -y
sudo apt-get autoremove
sudo apt-get autoclean

Reboot your server.

sudo reboot

4- Activate Unattended-upgrades for automatic security updates
Next step is to enable unattended upgrades to automatically install security updates.

important
By default, the unattended-upgrades service only installs security updates automatically. These updates WONT make your server automatically reboot.

The primary argument against enabling unattended-upgrades is that one day, a less stable package may install and cause stability or dependencies issues. While this argument is technically valid, the fact remains that without this package installed and enabled, it's more likely that a Linux server might host a software with remotely exploitable security vulnerabilities.

sudo apt-get install unattended-upgrades
sudo dpkg-reconfigure -plow unattended-upgrades

5- Generate SSH keys
The next step might be one of the most important things to do, to secure your server. Passwords are not safe to use. Instead, use SSH keys. We are going to create a new SSH key pair on your local machine. I strongly recommend using ED25519 algorithm.

On your local machine
Generate a a new key-pair. You will be asked to enter a filename to save your key
ssh-keygen -t ed25519

Copy the public key to your server
ssh-copy-id -i $HOME/.ssh/<filename> cardano@server-ip

Now disconnect from your server, and try to login again from your local machine where your private key is. This time you won't need to enter your password.
ssh cardano@server-ip

caution
Your private SSH key is what allow you to connect to your server. It is stored on your local machine. You should backup it to a secured cold storage, and never ever share it

6- Hardening SSH configuration
The next-step is to tweak the sshd_config on your server, to make it much more secured

Open the /etc/ssh/sshd_config file
sudo nano /etc/ssh/sshd_config

Then locate and update if needed, all the options below
PubkeyAuthentication yes
PasswordAuthentication no
PermitRootLogin prohibit-password
PermitEmptyPasswords no
X11Forwarding no
TCPKeepAlive no
Compression no
AllowAgentForwarding no
AllowTcpForwarding no
KbdInteractiveAuthentication no

Change the default sshd listening port as well with your own custom port (choose between 1024 - 49150)
Port <custom port number>

Save and close your /etc/ssh/sshd_config. Validate the configuration
sudo sshd -t

Then restart sshd
sudo systemctl restart sshd

Disconnect from your server, and reconnect
ssh cardano@server-ip -p <custom port number>

7- Firewall configuration
We are going to use UFW firewall to secure network access to your Cardano node. We are only focusing on ports that are used for SSH, and Cardano node. If you want to use Grafana and Prometheus for monitoring, please, refer to this guide, to add appropriate ports to your UFW configuration.

On your Relay Node :
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow to any proto tcp port <CUSTOM SSHD PORT>
sudo ufw allow to any proto tcp port <YOUR CARDANO NODE PORT>
sudo ufw enable

On your Block Producer Node :
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow to any proto tcp port <custom sshd port>
sudo ufw allow from <RELAY 1 NODE IP> to any proto tcp port <YOUR CARDANO NODE PORT>
sudo ufw allow from <RELAY 2 NODE IP> to any proto tcp port <YOUR CARDANO NODE PORT>
sudo ufw enable

If you want to permit SSH connections to your node from specific IP, replace :

sudo ufw allow to any proto tcp port <CUSTOM SSHD PORT>

by

sudo ufw allow from <SPECIFIC IP> to any proto tcp port <CUSTOM SSHD PORT>

8- Fail 2 ban installation and configuration
Fail2ban is a very useful tool to block repetitive intrusion attempts. It can detect failed logins from specific IP and patterns, and blacklist it.

Installation and service activation :

sudo apt-get install fail2ban -y 
sudo systemctl start fail2ban
sudo systemctl enable fail2ban

Create a jail.local file and open it

sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local
sudo nano /etc/fail2ban/jail.local

Locate the [DEFAULT] block and adjust to your needs. Here is a configuration example that allows 2 logins attempts within 10minutes, and ban for 1hour any IP that fails. After 1h, if the IP tries again and fails, the bantime will be incremented by factor *2. The maximum bantime is set to 5 weeks.

bantime  = 1h
bantime.increment = true
bantime.factor = 2
bantime.maxtime = 5w
findtime  = 10m
maxretry = 2

Locate the [sshd] block and adjust to your needs.

mode   = aggressive
enabled = true
port    = <YOUR SSHD CUSTOM PORT>
filter = sshd
maxretry = 2
logpath = /var/log/auth.log
backend = %(sshd_backend)s

Save and close. Open the sshd.conf filter file

sudo nano /etc/fail2ban/filter.d/sshd.conf

Locate the mode variable and set it to "aggressive"

mode = aggressive

Save and close.

Restart fail2ban

sudo systemctl restart fail2ban

important
Once again, please adjust fail2ban configuration above to your needs. You might want to allow more than 2 failed attempts, or decrease bantime

**9- /etc/sysctl.conf hardening**

sysctl allows you to make changes to your linux kernel, and set advanced security options of the TCP/IP stack, and system settings. Here is a configuration recommendation to prevent some attacks on IPv4 networking layer.

Open /etc/sysctl.conf file

sudo nano /etc/sysctl.conf

Add these options at the end of the file

`# Avoid a smurf attack
net.ipv4.icmp_echo_ignore_broadcasts = 1

# Turn on protection for bad icmp error messages
net.ipv4.icmp_ignore_bogus_error_responses = 1

# Turn on syncookies for SYN flood attack protection
net.ipv4.tcp_syncookies = 1

# Turn on and log spoofed, source routed, and redirect packets
net.ipv4.conf.all.log_martians = 1
net.ipv4.conf.default.log_martians = 1

# No source routed packets here
net.ipv4.conf.all.accept_source_route = 0
net.ipv4.conf.default.accept_source_route = 0

# Increase TCP max buffer size setable using setsockopt()
net.ipv4.tcp_rmem = 4096 87380 8388608
net.ipv4.tcp_wmem = 4096 87380 8388608

# No redirects
net.ipv4.conf.all.accept_redirects = 0
net.ipv4.conf.default.accept_redirects = 0
net.ipv4.conf.all.secure_redirects = 0

## Disable packet forwarding
net.ipv4.ip_forward = 0

# Synflood protection
net.ipv4.tcp_synack_retries = 5`

Save and close. Reload sysctl

sudo sysctl -p

10- Shared Memory hardening
Shared memory can be used in an attack against a running service. To secure it, modify /etc/fstab

sudo nano /etc/fstab

Add the following line at the end of the file

tmpfs	/run/shm	tmpfs	ro,noexec,nosuid	0 0

Save and close. Reboot your server

sudo reboot

Hardening the server

## **Improve Grafana Security**

Once your Grafana Server is installed, up and running, you can drastically improve its security and accessibility by installing an SSL Reverse Proxy, and enabling 2-Factor Authentication with Google OAuth.

Prerequisites
NGINX Reverse Proxy :

You must have a proper domain name; and FQDN set to your grafana’s public IP address
You can buy a domain name basically on any hosting site like namecheap.
2FA Google OAuth :

You need to have your own domain mail address (and of course a secure mail server). For example, you could have "grafana@yourdomain.com"
You need to create a Google account with this mail address.
Nginx Reverse Proxy
The main issue if you want to access your Grafana Dashboard from anywhere, out-of-the-box, is that you have to expose the application port (http:3000 by default) on the public address of your server. To avoid that, a popular solution is to simply create an SSH tunnel with a port forwarding option to your Grafana Server. A more elegant and still secure solution is to configure a reverse proxy, with an SSL certificate.

Nginx installation
Install nginx

sudo apt install nginx

Check nginx status

sudo systemctl status nginx

Create Firewall Rules on your server

Ports 80 and 443 need to be opened on your Grafana server. Nginx will automatically forward any HTTP requests to HTTPS, but it’s important to have both open, in order for Certbot to renew your SSL certificate every 3 month. Here is an example with UFW : deny any incoming connections, except SSH, HTTP and HTTPS, an allow any outgoing connections. Modify to suit your needs, especially if you are running Grafana on a Stake Pool Relay server, you'll need to add Cardano Port.

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Now you should be able to visit your server's public IP address : http://your-ip-address which should lead to the default Nginx page.

Create and edit an nginx config file for your Grafana server

(change with your actual FQDN like grafana.yourdomain.com)

cd /etc/nginx/sites-enabled
sudo nano <your FQDN>.conf

Add this block

server { 
listen 80;
server_name <your FQDN>;

location / {
proxy_set_header Host $http_host;
proxy_pass http://localhost:3000/;
} 
}

Save your file and restart Nginx

sudo systemctl restart nginx

Now access your monitoring server http://your-FQDN : you should see the Grafana login page.

Nginx cleanup : remove the default enabled site

rm /etc/nginx/sites-enabled/default

SSL certificate installation
Now that we have a working Reverse Proxy on our monitoring server, we are going to add SSL layer to encrypt properly access to your Cardano Stakepool Grafana dashboard. To do this, we are going to use a free SSL certificate provider, Let’s Encrypt, with Certbot.

Use snap to install certbot

sudo snap install core; sudo snap refresh core
sudo snap install --classic certbot

Make a sym link so you can use certbot command anywhere

sudo ln -s /snap/bin/certbot /usr/bin/certbot

Start the installation and follow the instructions

sudo certbot --nginx

Respond to prompts to configure your HTTPS settings (FQDN,email..). At the end of installation, you should be able to access your Grafana Server with HTTPS :

https://your-FQDN

Post install nginx hardening
Block any unwanted HTTP method, except PUT POST GET and HEAD and configure websocket

sudo nano /etc/nginx/sites-enabled/<your FQDN.conf>

Paste this line inside your "location /" block :

limit_except PUT GET HEAD POST { deny all; }

Paste this sub-block inside the first server { block

# Proxy Grafana Live WebSocket connections.
  location /api/live/ {
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_set_header Host $http_host;
    proxy_pass http://grafana;
  }

Save and close.

Nginx configuration file hardening

sudo nano /etc/nginx/nginx.conf

Remove old cipher suites TLSv1.0 and TLSv1.1 : the SSL Settings should look like this :

##
# SSL Settings
##

ssl_protocols TLSv1.2 TLSv1.3; # Dropping SSLv3, ref: POODLE
ssl_prefer_server_ciphers on;

Prevent DoS and Buffer Oversized attacks : add this lines inside "http" block :

## Start: Size Limits & Buffer Overflows ##
 client_body_buffer_size  3K;
 client_header_buffer_size 3k;
 client_max_body_size 80k;
 large_client_header_buffers 2 10k;
 ## END: Size Limits & Buffer Overflows ##

### Directive describes the zone, in which the session states are stored i.e. store in slimits. ###
### 1m can handle 32000 sessions with 32 bytes/session, set to 5m x 32000 session ###
  limit_conn_zone $binary_remote_addr zone=addr:5m;

### Control maximum number of simultaneous connections for one session i.e. ###
### restricts the amount of connections from a single ip address ###
   limit_conn addr 10;

Save and close.

Restart Nginx server

sudo systemctl restart nginx

Google OAuth setup
We are going to replace the local login/password access to Grafana server, by a much more robust authentication : Google OAuth. Remember : you must have your mail address on your own domain (see Pre-Requisites), and create a Google account with that address.

Activate 2FA on your Google Account
Connect to the Google account you created with your own mail address, and activate 2FA Authentication :

1- In the navigation panel, select Security.

2- Under “Signing in to Google,” select 2-Step Verification. Get started.

3- Follow the on-screen steps.

Create Google API credentials
1- Go to https://console.developers.google.com/apis/credentials and log in with the Google account you created with your own mail address.

2- Click on "Create Credentials" on top of the page, and then click OAuth Client ID . (You may have to setup a “Consent page” first. Use defaults, it’s not very important in our case).

3- Enter these settings :

Application Type: Web Application
Name: Grafana
Authorized JavaScript Origins: https://your-FQDN-used-to-access-your-grafana-server
Authorized Redirect URLs: https://your-FQDN-used-to-access-your-grafana-server/login/google
4- Click on Create

5- You’ll get a Client ID and Client Secret. Copy them.

Edit Grafana config file
Open grafana.ini

sudo nano /etc/grafana/grafana.ini

In the Server section, find this setting and modify it

root_url = https://your-FQDN-used-to-access-your-grafana-server/

Next, go to the Google Auth section and modify these settings

[auth.google] enabled = true
client_id = <copy your Google API client id>
client_secret = <copy your Google API clien secret>
scopes = https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email
auth_url = https://accounts.google.com/o/oauth2/auth
token_url = https://accounts.google.com/o/oauth2/token
allowed_domains = <your domain, like "yourdomain.com">
allow_sign_up =false 

Save and close the file

Restart grafana server

sudo systemctl restart grafana-server.service

Access to your Grafana FQDN : https://your-FQDN-used-to-access-your-grafana-server

You should now have a “Sign-in with Google” option on the login page. You can now use the account you created with your own domain name to access your Grafana Cardano dashboards.

Optional: Admin configuration
Give the Google Account the administrator role, and then remove the local Admin/Password account

1- Access your Grafana UI with your local Admin account

2- Go to "Users", and make your Google Account "Admin" by changing its role

3- Log in with your Google Account, go to "Users", and remove the local Admin account.

Disable login form to allow only Google OAuth

sudo nano /etc/grafana/grafana.ini

In the [auth] section :

disable_login_form = true

Save and close the file

Improve Grafana Security

## **Audit your node**

In order to check if your node configuration is correct, you can run an audit script that checks SecOps basic settings, and Cardano node compliance (topology, version, key files...)

**What the script does :**
The script runs several checks on your Cardano stake pool node. It works on various types of Cardano installation (CNODE Guild Operatos, Coincashew, others...). Configuration files and services are parsed and analysed by the script :

**Cardano compliance**

New 9.1.0 Cardano-Node version requirement for Chang hardfork
Cardano-node latest version verification
Cardano bootstrap check
Environment Variables
Systemd cardano-node file verification and parsing
Cardano startup script verification and parsing
Node operation mode (Block Producer ? Relay ?)
Topology mode (p2p enabled)
Topology configuration file parsing and compliance checks
Cardano security checks (hot keys permissions, cold keys detection)
KES keys rotation alert
Security and system checks

**SSHD hardening**

Null passwords check
Important services running (ufw, fail2ban, ntp server...)
Firewalling rules extract
sysctl.conf hardening check
Please note that this script is only intended to help you identify configuration and basic security issues. It does not guarantee that your server is fully protected.

**Pre-Requisites :**

1- The script is 100% shell bash. It works on Linux systems.

2- cardano-node up and running. You can setup a Cardano node with :

Coincashew guide : https://www.coincashew.com/coins/overview-ada/guide-how-to-build-a-haskell-stakepool-node)
CNODE (Guild-Operators) : https://cardano-community.github.io/guild-operators/
Developper Portal guide : https://developers.cardano.org/docs/operate-a-stake-pool/
3- Several bash commands are necessary (tput, date, grep, awk, jq). A check is performed when the script starts.

4- cardano-cli is also used for KES key rotate check.

**How to use :**

Download the script and make it executable :
The script can be found on this GitHub repository

You can directly download the repository from your Cardano Nodes :

wget --show-progress -q https://github.com/Kirael12/cardano-node-audit/releases/latest/download/audit-cardano-node.sh
chmod +x audit-cardano-node.sh


**Run the script**

The script must be ran with sudo and the -E option, to include your environment variables.

sudo -E ./audit-cardano-node.sh

A selection menu allow you to select your Cardano installation type. You can also choose to perform Security Checks only. You can then choose to export the results to a file.

**Results**

It takes around 20 seconds for the script to complete. You'll get information about your node and will immediately be able to check whether your configuration is good or not, and make appropriate changes.

Audit your node

## **On-Chain Polls**

In the 8.0.0 version of Cardano-node, we incorporated a new group of commands to facilitate voting among stake pool operators. An "official" poll is characterized by being endorsed with a genesis delegate key.

important
This tutorial requires cardano-node 8.0.0

https://github.com/IntersectMBO/cardano-node/releases/tag/8.0.0

CIP-0094 - Poll participation
Pre-requisites
​For this guide, you require a Cardano-cli that has the governance poll subcommands. You can use anything from the Cardano-node release v8.0.0 or a specially backported 1.35.7 version. Once a Genesis Delegate Key holder has signed and posted a new poll question on the chain, it will appear in this Cardano Foundation CIP-0094-polls repository.

You can find the JSON file containing the poll question in CBOR format by navigating into the specific subfolder.

For instance, the first PreProd network Test question appears like this: poll.json

{
    "type": "GovernancePoll",
    "description": "An on-chain poll for SPOs: How satisfied are you with the current rewards and incentives scheme?",
    "cborHex": "a1185ea200827840486f77207361746973666965642061726520796f752077697468207468652063757272656e74207265776172647320616e6420696e63656e74697665732073636568656d653f0183816c646973736174697366696564816a6e6f206f70696e696f6e8169736174697366696564"
}


info
The signature from the genesis delegate key isn't included in this metadata but is employed as an additional signatory on the initiating transaction.

Download this file to your node.

Creating answer
​From that point, you can generate a metadata entry to respond to the poll using the governance answer-poll command in the following way:​

$ cardano-cli governance answer-poll --poll-file poll.json

​This command will invite an interactive response from you. If you prefer not to respond interactively, you can employ --answer along with the index of the answer.

Executing this command will present the survey in a format easy to comprehend and will ask for your answer, as demonstrated below:​

How satisfied are you with the current rewards and incentives scheme?
[0] dissatisfied
[1] no opinion
[2] satisfied
​
Please indicate an answer (by index): _

You can move forward by entering one of the possible answer indices (in this case, 0, 1, or 2) followed by a newline. This will generate witnessed metadata in the form of a detailed JSON schema, which should be subsequently posted on-chain in any transaction and signed with your stake pool's cold key: ideally, this is achieved by constructing a basic transaction directed to yourself that carries the metadata.

Here is a sample of metadata where the answer 2 is selected:

answer.json

{
  "94": {
    "map": [
      {
        "k": { "int": 2 },
        "v": { "bytes": "62c6be72bdf0b5b16e37e4f55cf87e46bd1281ee358b25b8006358bf25e71798" }
      },
      {
        "k": { "int": 3 },
        "v": { "int": 2 }
      }
    ]
  }
}

Publishing answer
​From this point, you can utilize the transaction build command to generate a transaction for posting on-chain. You will require a signing key linked to a UTxO possessing sufficient funds to facilitate the transaction (approximately 0.2 Ada if you're making a basic transaction to yourself).

Assuming you have stored the metadata generated from the previous step in a file named answer.json, the command to construct the transaction would appear as follows:

$ cardano-cli conway transaction build \
    --babbage-era \
    --cardano-mode \
    --mainnet \
    --tx-in $TXID#$IX \
    --change-address $ADDRESS \
    --metadata-json-file answer.json \
    --json-metadata-detailed-schema \
    --required-signer-hash $POOL_ID \
    --out-file answer.tx

caution
Please be aware that adding --required-signer-hash is crucial for the response to be considered valid for the survey; this serves as your identification as a stake pool operator.

You can produce the $POOL_ID hash from the Bech32 formatted pool ID using the Bech32 command:​

$ bech32 <<< pool1....

To submit the response to the chain, you need to provide the respective values for --tx-in & --change-address from one of your wallets.

From this point, you can sign answer.tx using your stake pool's cold key and any necessary payment key, then submit the result as usual. If everything proceeds correctly, the cardano-cli should present a transaction id that you can monitor on-chain to confirm your survey response was correctly published.

SPO-Poll Dashboards where your transaction should now be visible:

Cardanoscan.io [PreProd] [Mainnet]​
Verifying Answers
​Lastly, you can validate answers observed on-chain using the governance verify-poll command. The term 'verify' here has a dual meaning:

It verifies that an answer is valid in the context of a specific survey
It provides a list of the signatory key hashes found in the transaction; in the case of a valid submission, one key hash will correspond to a recognized stake pool id.
Assuming you still have the original poll.json file, and a signed transaction carrying a survey answer as answer.signed, you can confirm its validity using:​

$ cardano-cli governance verify-poll \
  --poll-file poll.json \
  --tx-file answer.signed

​Upon successful execution, this should produce something like:​

Found valid poll answer, signed by:
[
    "f8db28823f8ebd01a2d9e24efb2f0d18e387665770274513e370b5d5"
]

​Alternatively, the command will identify a problem with the answer and/or poll.

**References**

[Entering Voltaire: on-chain poll for SPOs](https://forum.cardano.org/t/entering-voltaire-on-chain-poll-for-spos/117330?u=adatainment)

[Cardano Node 8.0.0 release](https://github.com/IntersectMBO/cardano-node/releases/tag/8.0.0)

[Cardano Node documentation: Governance](https://github.com/input-output-hk/cardano-node-wiki/wiki/cardano-governance)


On-Chain Polls

## **Get Started with Guild Operators Tools**

**Guild Operators Suite**

The Guild-Operators suite is a set of tools and scripts for setting up, managing, and monitoring Cardano stake pools, as well as managing tokens and keys. It's the outcome of a community collaborative effort by long-time active community members to make common chores for operators easier. We'll try to provide a fast run-through of the tools involved and a high-level overview of procedures to get you started since complete documentation for the suite is hosted here.

**Tools**

**CNTools**

CNTools is a swiss army knife for pool operators who want to make routine tasks easier. It's a menu-driven bash GUI application for creating and managing wallets, sending ada and tokens, and just about any pool function. In addition, the tool has been enhanced with new features and improvements since its initial release in July 2020, coinciding with the introduction of the Cardano Shelley MainNet. More information regarding CNTools can be found [here.](https://cardano-community.github.io/guild-operators/Scripts/cntools/)

![](https://developers.cardano.org/assets/images/guild_cntools-36556cd11e661e0e6a3816e286286b6d.png)


**gLiveView**

Guild LiveView, often known as gLiveView, is a local bash CLI monitoring utility with an easy-to-use interface for monitoring node status. It connects to the locally running node via the specified EKG/Prometheus node endpoints to collect and show node metrics, network information, and other information in real time. The program recognizes whether the node is being used as a relay or a block producer and adjusts the output accordingly. More information regarding gLiveView can be found [here.](https://cardano-community.github.io/guild-operators/Scripts/gliveview/)

![](https://developers.cardano.org/assets/images/guild_gliveview-93df9a85076ee987dd6ab12c4e7eef0d.png)

**Topology Updater**

Topology Updater was built as a workaround to allow stake pool relays to auto-discover and pair with peers on the network. While P2P implementation was put on hold owing to other priorities, this script has become one of the most important tools for avoiding having to manually contact friends and request that individual nodes be included to topology files. More information about the tool may be found [here.](https://cardano-community.github.io/guild-operators/Scripts/topologyupdater/)

![](https://developers.cardano.org/assets/images/guild_topologyupdater-90c51a68d6d752708cc281eb63414b24.png)


**Guild Network and Support for other networks**

Guild Network is a brief (60-minute epoch) network that functions similarly to the Cardano testnets but is entirely governed by the community. It's excellent for experimenting with things in the sandbox, as well as testing out viable features before releasing them to other networks. This network is already supported by all of the tools in the repo, including Mainnet, testnets, and staging.

**Others..**

Other utility scripts on a lesser scale include creating core components from source for particular components, setting up environment pre-requisites, and so on. Starting here, you can read about specifics as you go across the homepage here.

**note**

Please ensure to read the disclaimers on guild website before continuing

**Setting Up Pre-Requisites..**

For installing OS Packages, dependencies, setting up a sample directory structure used as an example template input (customisable) for guild tools, fetching of configuration, genesis artifacts, downloading tool scripts, etc , you can use the commands below. The script does have quite a few options (you can use -h to check any optional components/arguments you'd want to include).

`mkdir "$HOME/tmp";cd "$HOME/tmp"
curl -sS -o guild-deploy.sh https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/cnode-helper-scripts/guild-deploy.sh
chmod 755 guild-deploy.sh
./guild-deploy.sh -b master -n mainnet -s pdl
. "$HOME"/.bashrc`

note
-s pdl
installs (p)rerequisites for the operating system, (d)ownloads the precompiled binaries and also compiles and installs the IOG fork of (l)ibsodium.

consider guild-deploy.sh --help for options when you update the system or want to install additional modules

Build of Node/DBSync components
We assume you'd have already seen the guide here. There are similar build scripts/instructions available for building different cardano-node, cardano-db-sync, offline-metadata-tools and setting up postgres+postgREST with dbsync) on guild documentations. You can navigate instructions for each of them here. The instructions will also deploy these as a systemd service, which is recommended to avoid manually managing services.

Customise configuration
Now that you've set-up your OS dependencies and built/installed node binaries, it's time for you to customise your configuration, paths, names, etc for your node. You can use env file to modify these. Each line contains default value, and a simple explanation about what variable means.

**Contributions/Feedback..**

Issue/PRs are welcome on the github repository.

**Support Requests**

We do have the Koios Discussions telegram channel for support requests , but note that we intend to have support channel only for baseline skillset highlighted on [homepage.](https://cardano-community.github.io/guild-operators)




Get Started with Guild Operators Tools

## **Get Started with Ansible for Stake Pools**

Overview
The Ansible cardano-node repository contains an Ansible playbook for provisioning secure, optimized Cardano nodes for Stake Pool Operators (SPOs). It was originally developed by the **[MOAI Pool operators but is now being made available to the greater Cardano community.

The following is handled out of the box:

Basic Linux security (SSH hardening, firewall setup, etc.)
Installation of a cardano-node (compiled from IOHK source)
Base configuration for block producer and relay nodes
Setup of administration & monitoring tools (cncli, gLiveView, etc.)
To facilitate the above the following minimal software packages are installed:

git-core
ufw
unattended-upgrades
logrotate
logwatch
net-tools
tmuxinator
vim
htop
curl
Contents
Why Ansible?
Installation
Playbooks
Organization
Inventory setup
User setup
Using tags
Running a playbook
Base configuration
Optional components
Pro tips
Why Ansible?
Ansible is a provisioning, application deployment, and configuration management automation tool. Gone are the days of putting together bash scripts or SSH'ing into our servers to conduct a task.

Ansible is agentless, which means it doesn't require any specific software on the remote systems. SSH is used to run all commands through Ansible.

Commands executed via Ansible are idempotent, meaning they can be safely run multiple times without anything being changed, unless required. Need to ensure a cardano-node configuration is up-to-date on all hosts? Simply run the command and Ansible will ensure only those that need the update will receive it. All other hosts will remain untouched.

Ansible is an extremely popular open source project with hundreds of available modules.

Installation
A single control machine can be setup to execute Ansible commands. The example below uses OS X, but any platform with Python installed will work (including Windows).

Note: Ansible is written in Python, but it isn't necessary to code in Python. You never have to touch Python unless you want to. The Ansible scripts themselves are written in the very simple YAML format.

First, verify that pip is installed:

sudo apt install python-pip

Then install Ansible and the netaddr Python package. The latter is used by the ipaddr() filter in our Jinja2 templates:

sudo pip install ansible
sudo pip install netaddr

Alternatively, if you have Homebrew installed (surely you must) then you can install Ansible like so:

brew install ansible 

Once the installation has finished you can verify that everything installed correctly by issuing:

ansible --version

Playbooks
Playbooks are a method of chaining commands to create a blueprint or collection of procedural instructions. Ansible runs the playbook in order, verifying each command's output before going on to the next. If you stop the playbook execution in the middle and continue it later, only the instructions that haven't finished yet will run; the remainder will be skipped.

Some basic playbook terminology is given below.

Roles help playbooks stay organized. They broke down complicated build instructions into manageable parts. This allows roles to be shared between playbooks without having to duplicate code.

Templates are files that contain variables and expressions that the Ansible template module can replace with the appropriate values. This makes the file more reusable because it can be used dynamically to configure several servers with the same file.

Hosts and group variables are part of Ansible's inventory setup to manage individual hosts and logical groups of hosts (detailed below). This negates the need to remember individual IP addresses or domain names. It also provides a simple method of managing host-specific configurations.

Handlers contain logic that should be performed after a module has finished executing. They work very similar to notifications or events. For example, when the ufw configuration has changed the handler restarts the firewall service. It’s important to note that these events are only fired when the module state has changed.

Organization
The basic directory structure used to organize the playbook is shown below:

├── ansible-cardano-node/
│   ├── filter_plugins
│   ├── group_vars
│   └── inventories
│       ├── block-producer/
│       ├── relay-node/
│       ├── all.yml
│       ├── vault
│   ├── roles/
│   │   ├── cardano-node/
│   │   ├── common/
│   │   ├── ssh/
│   │   └── ufw/
│   ├── ansible.cfg
│   ├── apt_periodic
│   └── provision.yml

All the various Ansible tasks, handlers, configurations and so on are contained above. The specifics are described in the following sections.

Inventory setup
We need to tell Ansible what will run where before we do anything else. Ansible uses a list or group of lists called inventory to work against numerous managed nodes or hosts in our infrastructure at the same time. After we've built our inventory, we can utilize patterns to choose the hosts or groups that Ansible should execute against. The most straightforward solution is to create a single 'hosts' file that contains all known hosts. The format of this file can be INI or YAML. The following is an example of a hosts INI file:

[node]
foo.mypool.com
bar.mypool.com

This inventory arrangement works well for simple configurations, but as the complexity of a configuration rises, it reveals its limitations. A preferable technique for our needs is to divide a single hosts declaration into functional groups. This organization style has no hard and fast rules, which is one of Ansible's strong advantages. When creating an inventory from scratch, though, this versatility might be intimidating. We can make groups that keep track of:

What - An application, stack or microservice (e.g., database servers, web servers, etc.)
Where - A datacenter or geographic region, to talk to local DNS, storage, etc. (e.g., east, west, Newark, Paris, Cape Town)
When - The development stage, to avoid testing on production resources (e.g., Mainnet, testnets)
For our purposes, we have chosen a combination of the "what" and "when" group structures. Let's look at a high-level overview of our inventory group structure:

├── ansible-cardano-node/
    └── inventories
        ├── block-producer/
        └── relay-node/

You can see that each of these groups correspond to a unique node type. Within block-producer we find an INI file like so:

[node]
blockprod.mypool.com ansible_user=deploy

Here the Ansible user deploy is used throughout, although a different user with specific rights/capabilities could be defined for each host. You can also see that the functional (or "what") groups are defined here with each of the fully-qualified domain names (FQDN) corresponding to a production backend host.

note
For security reasons, you may wish to obfuscate, or hide, your block producer(s) public IP addresses. In this case, you may replace the FQDN in the example above with an IP address. The end results are the same.

Group variables
Groups are nice for organization, but they are also used to handle variables. For example, the file /groups_vars/all has the following definitions:

---
# Cross-environent variables are stored here

# ports 
ssh_port: "22"
cardano_default_port: "6000"


This is a very minimal example. However, you can think about how group_vars can be used to store variables or other settings on a functional or per-group basis.

note
Ansible provides a vault facility to encrypt data such as passwords or keys, rather than as plaintext in playbooks.

User setup
We enhance security and ease of use by requiring public key authentication for our user accounts. Thereafter Ansible only interacts via the deploy account.

Start by creating the deploy user:

useradd deploy
mkdir /home/deploy
mkdir /home/deploy/.ssh
chmod 700 /home/deploy/.ssh
chown -R deploy:deploy /home/deploy

Set a strong password for the new user: passwd deploy. You'll use this once when adding your public key in the next step. Thereafter passwords won't be needed by Ansible.

Securely copy the public key from your workstation to the remote host (relay1.mypool.com, in this example):

ssh-copy-id -i ~/.ssh/id_rsa.pub deploy@relay1.mypool.com

The authenticity of host 'relay1.mypool.com (<no hostip for proxy command>)' can't be established.
ECDSA key fingerprint is SHA256:HRTSF5/nHmrgiNDvHFZ6OhxF9whXl4o7O1KwuW6Fbd0.
Are you sure you want to continue connecting (yes/no)? yes
/usr/local/bin/ssh-copy-id: INFO: attempting to log in with the new key(s), to filter out any that are already installed
/usr/local/bin/ssh-copy-id: INFO: 1 key(s) remain to be installed -- if you are prompted now it is to install the new keys
deploy@relay1.mypool.com's password:

Number of key(s) added: 1


Now try logging into the machine with ssh deploy@relay1.mypool.com to verify that the key was added successfully.

Use visudo to grant sudo access to the deploy user and don't require a password each time:
visudo

Comment all existing user/group grant lines and add:

# User privilege specification
root    ALL=(ALL:ALL) ALL
deploy  ALL=(ALL) NOPASSWD:ALL
	
# Allow members of group sudo to execute any command
%sudo  ALL=(ALL:ALL) NOPASSWD:ALL


Login as the deploy user and verify that you have sudo access with the -v (validate) option:

sudo -v

You will probably want to change the default shell to bash:

sudo chsh -s /bin/bash deploy

**Using tags**

Tags are attributes defined in an Ansible structure that can be used to perform a subset of tasks selectively. Tags are highly valuable since they allow us to run only a portion of a huge playbook instead of the entire thing. In Ansible, tags can be used to a variety of structures, although their most basic application is with individual tasks. Two tasks inside the 'cardano-node' role that employ distinct tags are shown below:

- name: "Node Install | Building Cardano node"
  shell: cd /home/{{ server_username }}/cardano-node && cabal build cardano-node cardano-cli
  tags:
    - install
    - node

- name: "Node Install | Stop cardano-node service"
  systemd:
    name: cardano-node.service
    state: stopped
  tags:
    - binaries
    - install
    - node

When running a playbook, you can use –tags or –skip-tags to execute a subset of tasks. You can also see which tasks will be executed with these options by combining it with --list-tasks. For example:

ansible-playbook provision.yml --tags "install" --list-tasks

Advanced tag usage including inheritance and special tags are covered here.

**Running a playbook**

An example playbook execution is shown below. This playbook targets the relay-node inventory using vault credentials. The optional --tags specify tasks tagged as "configuration" settings. Finally the --check mode is a "dry run" option that does not make any changes on remote systems:

ansible-playbook provision.yml -i inventories/relay-node --vault-password-file ~/.vault_pass.txt --tags "install" --check


Assuming the host file is populated and the hosts are accessible, you should see some output like this:

**playbook**

The process above includes downloading and compiling cardano-node from source, along with the latest dependencies, if needed.

**Base configuration**

A set of known-good base settings are provided in this playbook. Where applicable, under each role you will find a file called /defaults/main.yml. These files contain default values for variables and should be modified prior to provisioning a live host. For example, the ssh role applies several Linux security best practices to harden secure shell access to your nodes. The file ssh/defaults/main.yml should be modified to match your remote administration IP address (that is, the machine you execute Ansible from):

ssh_allowed_users: "AllowUsers deploy@127.0.0.1/32"

The ufw role configures the Linux firewall service and requires that the following default values be defined:

# Relay node public IP addresses
relay_node_ips:
  - 127.0.0.1/32  #relay1.mypool.com
  - 127.0.0.2/32  #relay2.mypool.com

# Trusted IP addresses, used for remote access/administration
trusted_ips:
  - 127.0.10.1/32
  - 127.0.10.2/32

The placeholder values for the relay nodes above must agree with your real relay host IP addresses, else they will not be able to communicate with the block producer or each other.

Likewise, the file cardano-node/defaults/main.yml contains values that will be used to populate your pool's metadata. These placeholder values should be replaced:

# Pool metadata
cardano_pool_name: "My Cardano Stake Pool"
cardano_pool_description: "A description of my stake pool"
cardano_pool_ticker: "My Pool ticker symbol"
cardano_pool_homepage: "https://mypool.com/"
cardano_pool_extended: "https://mypool.com/extendedMetaData.json"

Be sure to define your inventory before executing the playbook. The inventory file for your relay nodes must contain FQDNs for each of your relays. This file exists in inventories/relay-node/inventory:

**[node]**

relay1.mypool.com ansible_user=deploy
relay2.mypool.com ansible_user=deploy

Likewise, assign a public IP address for your block producer. This file exists in inventories/block-producer/inventory:

[node]
127.0.0.1 ansible_user=deploy

Optional components
cardano-submit-api

The cardano-submit-api provides a web API that allows transactions (generated by an external wallet, for example) to be posted to the Cardano blockchain. To submit a transaction to the network (Mainnet, staging, or any of the testnets), cardano-node must be running and have access to the genesis file and genesis hash value for the network. Given that our playbook installs a full cardano-node, this requirement is already fulfilled.

Stake pool operators may wish to install and enable the web API on one or more of their relays. This provides another mempool for users to submit their transactions to. This component is disabled by default. To enable it, set the following value in /roles/cardano-node/defaults/main.yml to true:

# Cardano submit API (optional)
cardano_submit_api: false

You may wish to install the cardano-submit-api as part of your default relay node setup, or selectively after your relays are up and running. In the latter case, you may install the web API by specifying the associated tag when executing the playbook, like so:

ansible-playbook provision.yml -i inventories/relay-node --vault-password-file ~/.vault_pass.txt --tags "api"

Note: To prevent installation of cardano-submit-api on the block producer, these tasks will only be executed if the relay-node inventory is specified during playbook execution.

The associated tasks will handle the build process and installation of cardano-submit-api to /usr/bin. It will also check for and, optionally, download IOHK's mainnet base configuration settings.

Finally, two scripts are created: 1) tx-api.sh is added to /opt/cardano/cnode/scripts to handle startup of the API, and 2) tx-api.service is installed to /etc/systemd/system and enabled. The latter systemd service allows the API to started and its running status to be checked, like so:

sudo systemctl start tx-api.service
sudo systemctl status tx-api.service

With the API service active, your relay node(s) will have a tx submit api running on port 8090. To make this available outside of your local network, you will need to open the port. This may be done with ufw like so:

**sudo ufw allow 8090/tcp**

An example signed transaction is shown below:

$ curl --header "Content-Type: application/cbor" -X POST http://localhost:8090/api/submit/tx --data-binary @tx.signed.cbor
"8a3d63d4d95f669ef62570f2936ad50d2cfad399e04808ca21474e70b11987ee"%


**Pro tips**

Use Ansible's --check option when executing a playbook for the first time. This will safely execute the playbook and check for any errors without modifying your hosts.

If you have manually configured your Cardano nodes in the past, it is strongly advised that you start with a fresh install of Ubuntu 20.04 LTS and execute your Ansible playbook against this new host.

Get Started with Ansible for Stake Pools

## **Get Started with the Frankenwallet**

An encrypted, air-gapped Linux bootable USB drive for Cardano (and other) secure operations
Frankenwallet is not a package, library or product, but rather a set of installation guides, security standards and templates that allow Cardano SPOs, token minters, users with funds in bare addresses, and smart contract creators to configure an ordinary USB drive to boot Linux with a level of security isolation and software prerequisites appropriate to their use case.

When one's primary computer is booted from this removable drive, the secure ("cold") configuration & workflow conventions allow operators to:

store and work securely and flexibly with private keys
sign transactions and securely keep records of transaction details
keep encrypted records & backups without ever revealing keys or passwords in the insecure host environment
warning - Linux veterans only
These instructions may be difficult or unsafe to follow unless you have experience with "dual boot" Linux installations and other custom OS & booting configurations.

Operators needing a safer path can follow instructions at the Air Gap Environment page.

**How to use this guide**

This tool has been developed by the COSD stake pool, beginning as a publication of their own operating environment when scared to death of losing their pool pledge and not being able to come by a second machine for the conventional air gap environment (see origin story: Why was the Frankenwallet developed?).

At the time of this writing, the full instructions for:

the reasons you would want to use this tool
how to provision & build your own Frankenwallet
how to use the tool for stake pool operations & secure transactions
… are in the online book at this external link: The Frankenwallet.  If you see any problems with this material, please submit an issue at:

github:rphair/frankenwallet if you find an error in the material in the externally linked web site
github:cardano-foundation/developer-portal with any updates or corrections to this page itself.
This is a one-page summary of those external instructions to help you (the operator) decide if the Frankenwallet is something you might use in your workflow according to your own level of interest & expertise.

**Use cases for the Frankenwallet**

➤ Anyone working with private keys & secure transaction signing, seed phrases, or other high value resources targeted by hackers (e.g., stake pool keys).

➤ Anyone wishing to work in high security with these resources without either a second computer (e.g. perpetual travellers, students, and hardware minimalists) or a hardware wallet (Why wouldn't I want a hardware wallet?)

➤ Anyone wanting or needing direct access to all their own files on their main computer in the air-gapped environment.

➤ Anyone who has wondered how you might get the same (or better) features as a hardware wallet on an easily obtainable & anonymous USB drive: including a full featured operating system with applications that can edit encrypted and richly formatted files and prepare encrypted document archives.

➤ Anyone using memory sticks to store or back up private keys who has worried about an unencrypted memory stick being lost or stolen.

➤ Anyone wanting to prepare an off-site or even a network backup of their keys, wallet seed phrases, and other cryptocurrency asset records… given that AES based encryption is considered unbreakable when properly used (i.e. never entering the passphrase on a network-connected machine).

If so universally useful, why the build instructions & not just a downloadable ISO image?

TL;DR because then all Frankenwallets would be the same, and any security flaw found in one of them might allow all of them to be exploited before a response could be mounted (see Why is there no ISO image for Frankenwallet?).

Some other use cases & limitations of this material

➤ You can use the Frankenwallet instructions to set up an Air Gap node on a full computer… but since the time of its development, this procedure has been adapted to a more appropriate page on the Dev Portal (the aforementioned Air Gap Environment).

From Frankenwallet > Miscellaneous FAQ's:

➤ Your VirtualBox or other VM software on your host computer does not isolate you from the network, even if you have the network device disabled… nor can it be ever assumed that the screen or keyboard are isolated either… so VMs are generally unsuitable to create an air gap or to implement these instructions.

➤ Ubuntu + GNOME, though heavyweight and tainted by default with proprietary software, are chosen for their universal documentation especially when it comes to issues of OS installation (without that proprietary software!) and dual booting.

➤ Read more about the Evil Maid to see what she, he, or it can & cannot do with your Frankenwallet by compromising your host computer's BIOS in a way to which all commercial computers are vulnerable.

Preparing to build the Frankenwallet
From Frankenwallet > Preparation:

Planning your communication with the host computer
You will avoid moving files around on memory sticks and transferring them over a network (impossible with Air Gap machines) because, when you boot from a USB device based operating system, the main disk on that computer is also accessible as if it were an external device.

Therefore you can plan an area on your host computer (called here the Host Folder) which the Frankenwallet will use to store any encrypted files… as well as read the raw data for the transactions that you will prepare in the air gapped environment.

**warning**

Remember early & often that nothing should be stored on the host computer that is not saved an encrypted document or archive.

**Procuring your hardware**

Though regularly used Frankenwallets have been built on cheap & slow USB drives, to make this tool a dependable part of your workflow you should get either:

a memory stick with a high benchmark for reading and writing speed, or
(for best results in author's experience) a SATA SSD drive plus a SATA-to-USB adapter cable.
Users who have built dual-boot configurations before will also know you should familiarise yourself with the computer's BIOS settings in anticipation of the same type of setup.

Note there are limitations about using a Mac as host computer which stem from the different means of booting (see Frankenwallet > Hardware Requirements > What if I have a Mac?).

Choosing passwords
(from Frankenwallet passwords > low security & high security)

The low security password can be one you've already used to encrypt files on the host computer… strong enough you feel comfortable backing up files over the net.

The high security password… called the Frankenwallet password itself… should also be strictly long & complex, but should never have been used in a network environment, not even on a network connected machine… otherwise you will be defeating the purpose of using the Air Gap for any purposes of file storage or backup of files to the host computer

See each of these web links to see which of the Cardano asset & stake pool files it would typically be used to encrypt.

**optional**

If you intend to use the "cool" Frankenwallet configuration (supporting light browser-based wallets) with a Chrome-based browser like Brave, you should be ready with a second high-security password used only to encrypt your most confidential data… since by default you will have to enter the user account password in the browser UI to unlock the GNOME keyring and therefore expose it in an uncertain security context.

**tip**

For ease of use, you can separate the "low security" and "high security" stake pool files into two subdirectories, so they can be backed up as two separately password-encrypted archives.

Installing the OS onto the USB device
(from Frankenwallet > Host computer & media though end of Installation section)

The full instructions mainly document the installation of Ubuntu in the common "dual boot" configuration: something the target audience should feel comfortable with, and can probably improvise for themselves if also following these checklists during the installation & setup or the installed environment:

Installation notes: software
No need to disconnect from the Internet yet because you will be using it to do your first package updates & software installation.

Purists might want to do this without Internet access at all: if feeling comfortable with the baseline OS alone (no upgrades) + getting your packages by saving them in your computer's & installing them from there.
Select the Minimal software installation (no network hungry apps & games) and plan to install the LibreOffice package later.

Don't tick third party hardware for graphics and WiFi because the proprietary vendor software provided for these devices can contain institutional spyware.

**Installation notes: partitioning**

When you select erase disk and install Ubuntu you will get the options under Advanced Features for:

use LVM (the Logical Volume Manager), allowing more flexible disk usage

select Encrypt the new Ubuntu Installation
enter the "High Security" password you chose as the drive encryption password

Note the password you chose will be required now to boot the OS as well as decrypt the the partition it creates on any other devices (so your drive is secure when not booting).

**warning**

At the next screen Erase disk and install Ubuntu, watch out that you don't accidentally select your computer's own drive… this can be very easy to do!

**Setup notes: operating system**

Don't let Ubuntu link with any online accounts in its initialisation process: refuse everything like location services, "livepatch", etc.
Disable lots of little services & settings which might leak your information (see Frankenwallet > First boot: Secure system settings)
Setup notes: packages
(details: Frankenwallet > First boot: Package installation)

Remove all "snaps" and disable Snap.

Remove CUPS (network printer service).

Disable unattended upgrades.

Upgrade the remainder of the system (apt update; apt upgrade; apt autoremove)

Install document & security-oriented packages

secure-delete (in case you accidentally write unencrypted keys or secure data to your host computer drive)
LibreOffice (supporting AES256 encrypted documents)
p7zip (supporting AES256 encrypted archives)
Tune browser & turn off network access FOREVER
Lock down the browser settings, just in case, even if you think you'll never use it (Frankenwallet > Securing Firefox browser)

At this point you disable Wi-Fi and all other networks in the system settings, and go on without any future connection to the Internet in your new environment.

What to use the Frankenwallet for

From a growing body of material beginning at Frankenwallet > Usage:

Prepare and submit secure transactions
You can now follow the instructions recommended in Secure Transaction Workflow, with the following modifications:

Create a file on your networked host computer in the Host Folder, encrypted with the Low Security password (so you feel safe backing it up over the Internet, but won't store any keys or wallet passphrases there).

When planning your transaction, save the transaction details and any commands to cut-and-paste, in this file.
Boot into the Frankenwallet and navigate to your Host Folder.

Copy-paste the transaction commands and/or transaction data into the Frankenwallet command line.
Save the resulting transaction file to your Host Folder.
Reboot into the host computer, upload your transaction file if necessary, and submit it.

Some copy-paste models & templates for basic Cardano transactions are being assembled here: Frankenwallet > Transaction templates

Making & verifying backups of assets & keys
from Frankenwallet > Backups to host machine:

For highly secure stake pool & asset files, and any documents storing wallet key phrases or raw private key data:

First create the file archive (with 7z) or text document (with LibreOffice) using your "high security" password.

Then copy it to your host folder, where it can remain stored or backed up (over the network if desired) along with all your other computer's data.

This is safe (pending the usual arguments) because you never have entered, and never will enter, the Frankenwallet (high security) password on your host computer or any other machine.

This means you can only verify these backups on this or another Frankenwallet… never on the host computer environment itself!

For less secure stake pool & asset files, and documents with general transaction records & source data:

First create the file archive (with 7z) or text document (with LibreOffice) using your "high security" password.
These files you might feel comfortable verifying on your host computer.

NOTE for less urgently secure stake pool pool files (e.g. verification keys, operational certificate counters) you might provide a second dedicated password… with "security level" between your general encryption password and the "high security" password… which you only use for the purposes of your assets & stake pool public keys.
The "cool" Frankenwallet: a sandbox for crypto wallets
from Frankenwallet > Cool environments:

Relaxing the Internet environment (meaning this device should no longer be used for cold, unencrypted key storage) allows you to use this device for node- or browser-based wallets.

Even low-bandwidth memory sticks have been tested in use with the resource intensive Daedalus node wallet, and they still work.  But keep in mind that a node wallet will be considered very slow to sync… especially when your "daily driver" computer is booted from your Frankenwallet and can be used for no other purpose until booted normally again.

For browser-based wallets, the performance will be better… although the Firefox (or other browser) configuration becomes vital to avoid some institutional or extension spyware possibly compromising your keys.

In either case, you can still use the Frankenwallet to copy the wallet key phrases to an encrypted file on your host computer: so you can keep them encrypted with a password that has never been entered on your host machine.

Also keep in mind your security isolation can never be considered complete once you've allowed Internet connection from this "cool" environment… though this "sandbox" is still better than the complete exposure you'd have by running a node or browser based wallet on your network-connected, daily-use machine.

Get Started with the Frankenwallet

There are excellent guidelines available on how to set up cardano-node as a stake pool. You may even set one up without any prior Linux experience or concern for best practices. Simply copy and paste the commands from the instructions into your shell.

Operate a Stake Pool

Course Details

Level

Ratings

Modules

Lessons

Holder $WORK Price

Contact Us

Documentation

Navigation