Holo Guide ‐ Setting up dependencies

External dependencies.

It would be great if we could start dealing with holo off the bat, but unfortunately holo doesn't exist in a vacuum (get it ? holo...vacuum).

Away from the dry jokes, we have dependencies we need to install on our machine before we get started.

Ubuntu / Debian

Run this script to install required dependencies. If Rust is already installed, you can omit lines 8 and 9.

Other OSes

You'll need to install:

• Git
• Rust
• Gcc / cc
• Cmake
• libyang: our yang2 / yang3 libraries are built on top of this, therefore it needs to be installed
• protoc: used for our gRPC connections

We should also remember to install the nightly toolchain in rust:

rustup update
rustup update nightly

Holo uses some nightly features at the time being, so this is necessary for it to run.

Cloning the repository

Once the various external dependencies are set up, we can now get started.

Clone the repository and switch to the guide branch:

git clone https://github.com/holo-routing/holo
git checkout tags/v0.5.0
# this moves you to a new branch called guide. 
# call the branch whatever you want. 
git switch -c guide

We have jumped to the project's v0.5.0, since that is what this tutorial will be based on. If you view the repository at a later date, the VRRP protocol might already have been implemented and this whole journey may not make so much sense, maybe just as a follow along.

Project structure

After cloning, you'll see the following directories and files:

├── Cargo.lock
├── Cargo.toml
├── INSTALL.md
├── LICENSE
├── README.md
├── codecov.yml
├── docker
├── holo-bfd
├── holo-bgp
├── holo-daemon
├── holo-interface
├── holo-keychain
├── holo-ldp
├── holo-northbound
├── holo-ospf
├── holo-policy
├── holo-protocol
├── holo-rip
├── holo-routing
├── holo-tools
├── holo-utils
├── holo-yang
├── proto
├── rustfmt.toml
└── target

19 directories, 7 files

If you have dealt with networking protocols, some of these should already look familiar(OSPF, BGP, BFD...). Feel free to jump in there and have a look at how a holo module is structured.

The holo-daemon module contains the main function, while holo-yang is where we'll focus on setting up the YANG module for VRRP.

Let's move there:

cd holo-yang/modules/

Holo YANG

The structure you see should be roughly similar to what we have in YangModels/yang, where we source most of our models. We don’t add all models at once; instead, we upload them as needed. For this tutorial, we’ll add the VRRP model.

Download and Placement

1. Navigate to the Modules Directory:

Go to [project-root]/holo-yang/modules

2. Download the VRRP YANG Model:

Run the following command to download the VRRP YANG model:

cd ietf
wget https://raw.githubusercontent.com/YangModels/yang/main/standard/ietf/RFC/ietf-vrrp%402018-03-13.yang

Alternatively, you can download the file here and move it to [project-root]/holo-yang/modules/ietf

Using the same method we can add the augmentation and the deviation files to their respective directories using the following commands

cd ../deviations
wget https://raw.githubusercontent.com/holo-routing/holo/vrrp/holo-yang/modules/deviations/ietf-vrrp-holo-deviations.yang

cd ../augmentations
wget https://raw.githubusercontent.com/holo-routing/holo/vrrp/holo-yang/modules/augmentations/holo-vrrp.yang

We can also get the augmentation file here and deviation file here for those who prefer a manual download.

Although we won't delve too deep into what augmentations and deviations, let us touch touch briefly on what they are.

• deviations are used when we see an item on the main YANG file we want to change. e.g default values, name of an item etc.
• augmentations are used when we want to append items to what already exists in the YANG model we have. They may be used e.g by vendors to add custom items to the YANG model.

Update Rust code

1. Modify lib.rs

Navigate to the [project-root]/holo-yang/src/lib.rs file. This is a Rust file with a list of the YANG module together with various helper functions you don't need to worry about yet.

Currently our main concern is to get the VRRP yang model added to the list of yang models.

2. Add to YANG_EMBEDDED_MODULES

Locate the YANG_EMBEDDED_MODULES definition and include the VRRP model:

// [project-root]/holo-yang/src/lib.rs
pub static YANG_EMBEDDED_MODULES: Lazy<EmbeddedModules> = Lazy::new(|| {
    hashmap! {
        ...
        EmbeddedModuleKey::new("ietf-vrrp", Some("2018-03-13"), None, None) =>
            include_str!("../modules/ietf/[email protected]"),
        EmbeddedModuleKey::new("holo-vrrp", None, None, None) =>
            include_str!("../modules/augmentations/holo-vrrp.yang"),
        EmbeddedModuleKey::new("ietf-vrrp-holo-deviations", None, None, None) =>
            include_str!("./modules/deviations/ietf-vrrp-holo-deviations.yang"),
    }
});

Inside the "..." is the list of yang modules and their content. We are going to add the vrrp yang module to this list:

3. Add to YANG_IMPLEMENTED_MODULES

Similarly, update the YANG_IMPLEMENTED_MODULES list:

// [project-root]/holo-yang/src/lib.rs
pub static YANG_IMPLEMENTED_MODULES: Lazy<Vec<&'static str>> =
    Lazy::new(|| {
        vec![
            ...
            "ietf-vrrp",
            "holo-vrrp",
        ]
    });

Finally, we add a validator to the YANG_FEATURES:

pub static YANG_FEATURES: Lazy<HashMap<&'static str, Vec<&'static str>> = 
    Lazy::new(|| {
        hashmap! {
            ...
            "ietf-vrrp" => vec![
                "validate-interval-errors"
            ],
        }
    });

Checkpoint.

Let us build the project to make sure everything is running fine:

cargo +nightly build

If it doesn't throw any errors, this means everything is running okay so far. We then commit our progress to git:

git add .
git commit

In the commit message:

yang: add vrrp yang module. 

checkpoint 1
Add the vrrp yang module inside the `[project-root]/holo-yang/modules`
Also added the deviation to the `[project-root]/holo-yang/deviations` 
and the augmentations to the `[project-root]/holo-yang/augmentations`

modify the holo-yang lib.rs to accomodate the above changes
Signed-off-by: My Name <[email protected]>

We have our first checkpoint. Way to go partner !!!

Next Steps

With VRRP YANG model added, next we are creating the holo-vrrp module and start looking into how we structure it.