Quick Start Guide

This guide contains the information you need to get up and running using ZEM. As such, this guide will cover the steps needed from the creation of a site, to connecting your first switch. As a basic requirement, the ZEM On-Site Appliance (OSA) requires either Docker or Podman, docker-compose or podman-compose and an internet connection.

On-Site Appliance (OSA)

The On-Site Appliance (OSA) is a container or collection of containers that run on a local server or virtual machine. It can be thought of primarily as the probe that allows ZEM to connect to devices on your network. As such, it is a critical part of the system when managing a real-world network.

To prepare for the installation of the OSA (which is required if you would like to have ZEM interface with the actual network), you will need a machine (virtual or physical) within the network, able to "reach" switches within the network. There are many valid OSA hosts, including but not limited to a virtual machine, a Raspberry PI, even (for testing purposes) a MacBook or Windows machine.

In order to install the OSA, you will need to install Docker and docker-compose (or Podman and podman-compose) on the host machine. The OSA is a containerized application, so it will run in a Docker container. Depending on how you configure your OSA (i.e. enable additional modules), other containers may be included in the OSA installation as well.

Installing Docker and docker-compose

How to install Docker depends on your OS. Please find the installation strategies for your OS below.

Click to show installation instructions for Ubuntu

To install Docker using the apt package-manager, follow the steps below. 1. Configure the Docker apt repository:

sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
    $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
      sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
      sudo apt-get update

2. Install Docker and docker-compose using apt

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

3. Check that Docker has successfully installed:

sudo docker run hello-world

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (arm64v8)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

Click to show installation instructions for Windows

For Windows, we recommend Docker Desktop for Windows. This is a straight-forward installation process with an installer that will guide you through the steps.

Click to show installation instructions for macOS

For macOS, we recommend Docker Desktop for Mac. This is a straight-forward installation process with an installer that will guide you through the steps.

Creating a site

In ZEM, the digital twin of any network is called a 'site'. Sites are distinct environments with their own users, devices, and configurations. ZEM users can have access to multiple sites, but each site is isolated from the others.

Administrators can create a new site by logging in to ZEM and clicking the site name in the top-left corner of the screen. Click "Create new site", enter a name for your site and click "Create".

Downloading and installing the On-Site Appliance (OSA)

On the Dashboard of the new site, click "Set up On-Site Appliance" and copy the installation command to your clipboard. The installation link should look something like curl -sfL https://app.zem.com/i/xxxxxxx -o i.sh && sh i.sh. Paste the installation link into the terminal of your container host and press enter:

> curl -sfL https://app.zem.com/i/iilRVsEr -o i.sh && sh i.sh
        ◢◣
      ◢■◤  ◢◣
     ◥◤  ◢■◤  ◢◣
       ◢■◤  ◢■◤
     ◢■◤  ◢■◤     ZEM - Building better networks, together
   ◢■◤  ◢■◤       https://zem.com
  ◥◤  ◢■◤  ◢◣
     ◥◤  ◢■◤
        ◥◤

OSA Installer
This script will authenticate with the ZEM container registry and generate a docker-compose.yml file representing the on-site appliance.

Container registry
WARNING! Your password will be stored unencrypted in /Users/corne/.docker/config.json.
Configure a credential helper to remove this warning. See
https://docs.docker.com/engine/reference/commandline/login/#credentials-store

Login Succeeded

Password vault
Where should we store encrypted device passwords?
It's very important that you do not lose this data.
You can leave this empty to use a docker-managed volume (not recommended)

Enter a path or leave empty, then press enter:

Now enter a path for the password vault or let the container engine automatically provision a volume. This is the location where all the switch passwords are stored. Once the On-Site Appliance is successfully started, you should be greeted by the following:

Starting relay client in background
Appliance UUID: O15k33G5A1UadwrK87veqdTWFZLw3uSl
[27-Mar-2024 15:10:09] NOTICE: fpm is running, pid 25
[27-Mar-2024 15:10:09] NOTICE: ready to handle connections

> start
> node ./index.js

[2024-03-27T15:10:13.402Z] Connecting to https://relay.zem.com...
[2024-03-27T15:10:13.802Z] Connected... emitting [hello]

You can press ctrl+c to exit the logs. The OSA will keep running in the background. If you refresh your dashboard, you will now see the OSA is connected.

Warning

ZEM does not store these passwords in the cloud. Please make sure you regularly back-up the password vault file. See On-Site Appliance for details.

The On-Site Appliance is now ready to connect to devices on your network.

Creating the first entities

It's time to start adding some new entities to the site. These can generally added through their overview pages, by navigating via the menu and using the create button in the top bar.

This action can also be performed by using the create button from within the side menu, shown when hovering the sidebar menu item. This requires you to access the create form without needing to navigate to the entity overview page itself.

Keep in mind that these examples will

Creating a group

Let's create a group. The only requirement here is that we give it a unique name, and we can leave the other fields for now. An example of a possible group input:

After adding a group, it's dashboard will be displayed. To learn in more detail about the options and relations shown in the group dashboard, visit the Groups page.

We will have to create a VLAN and a device profile before we can start connecting switches to this group.

Creating a VLAN

Let's add the first VLAN. We'll give it a unique ID, name and provide an IP range. As we don't have a Switch added yet, we cannot set any of the router options yet and will leave this option empty. An example of a VLAN input:

When the VLAN has been added, you will be returned to the VLAN overview. We can set a VLAN allocation here, which is a prerequisite for adding devices, but to do that we must first configure a device profile.

To learn in more detail about VLANs, visit the VLANs page.

Configuring a device profile

Let's configure the first device profile. We'll give it a unique name and leave the rest of the options on default for this example. Example of a possible device profile input:

When the device profile has been added, you will be returned to the Device Profile overview.

To learn in more detail about device profiles, visit the Device profiles page.

Connecting a switch

Let's connect our first switch. This can also be done using Switch Discovery, but we'll add the first one manually. A switch can be added from the Group dashboard, or via the Switch overview page.

Below example is from the overview page, as a Group has to be manually assigned. Example of a possible Switch input:

The access and SNMP entries will have to be match the local setup to perform actions and/or connect to this switch.

To learn in more detail about Switches, visit the Switch page.

Creating a VLAN allocation

Before we can add a device, we must add a valid VLAN allocation. This can be done by visiting the VLAN overview page and clicking the "x Groups" under "allocations" on our previously created VLAN, as shown below.

We'll add our group:

And our device profile:

Upon saving the allocation form, our VLAN will now show the group as a valid allocation. More information on allocations can be found on the VLANs page.

Adding a device

Let's add the first device to our switch. We'll give it a unique hostname and assign it the profile, group and VLAN we just created. An example of possible device input:

After adding a device, it's dashboard will be displayed. To learn in more detail about the options and relations shown in the device dashboard, like adding a port or adjusting the port config, visit the Devices page.