From f725f908e8f395b08ae8275950382c9888578202 Mon Sep 17 00:00:00 2001 From: Roman Dodin Date: Wed, 24 Apr 2024 11:47:37 +0300 Subject: [PATCH 1/4] use distro detection script and install funcs for debian and ubuntu --- utils/debian-setup.sh | 73 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 64 insertions(+), 9 deletions(-) diff --git a/utils/debian-setup.sh b/utils/debian-setup.sh index 1841d6ae7..4bb44ca81 100644 --- a/utils/debian-setup.sh +++ b/utils/debian-setup.sh @@ -1,19 +1,74 @@ +DISTRO_TYPE="" + +function check_os { + if [ -f /etc/os-release ]; then + . /etc/os-release + if [ "$ID" = "debian" ]; then + ${DISTRO_TYPE}="debian" + elif [ "$ID" = "ubuntu" ]; then + ${DISTRO_TYPE}="ubuntu" + else + echo "This is not Debian or Ubuntu" + fi + else + echo "Cannot determine the operating system" + fi +} + function install-docker { - for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do sudo apt-get remove $pkg; done + # check OS to determine how to install docker + check_os + + if [ "${DISTRO_TYPE}" = "debian" ]; then + install-docker-debian + elif [ "${DISTRO_TYPE}" = "ubuntu" ]; then + install-docker-ubuntu + else + echo "Cannot determine the operating system" + exit 1 + fi +} + +function install-docker-debian { + # using instructions from: + # https://docs.docker.com/engine/install/debian/#install-using-the-repository + for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do sudo apt-get remove -y $pkg; done + + # Add Docker's official GPG key: + sudo apt-get update -y + sudo apt-get install -y ca-certificates curl + sudo install -m 0755 -d /etc/apt/keyrings + sudo curl -fsSL https://download.docker.com/linux/debian/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/debian \ + $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ + sudo tee /etc/apt/sources.list.d/docker.list > /dev/null + sudo apt-get update -y + + sudo apt-get -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin +} + +function install-docker-ubuntu { + # using instructions from: + # https://docs.docker.com/engine/install/debian/#install-using-the-repository + for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove -y $pkg; done # Add Docker's official GPG key: - sudo apt-get update - sudo apt-get install -y ca-certificates curl gnupg + sudo apt-get update -y + sudo apt-get install -y ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings - curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg - sudo chmod a+r /etc/apt/keyrings/docker.gpg + 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.gpg] https://download.docker.com/linux/debian \ - "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \ + "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 + sudo apt-get update -y sudo apt-get -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin } @@ -37,7 +92,7 @@ function install-containerlab { echo "deb [trusted=yes] https://apt.fury.io/netdevops/ /" | \ sudo tee -a /etc/apt/sources.list.d/netdevops.list - sudo apt update && sudo apt install containerlab + sudo apt update && sudo apt install -y containerlab } function all { From f89fe7b48d705ffa8b5fc16a4c0a48bec206dc07 Mon Sep 17 00:00:00 2001 From: Roman Dodin Date: Wed, 24 Apr 2024 11:48:28 +0300 Subject: [PATCH 2/4] rename script --- utils/{debian-setup.sh => quick-setup.sh} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename utils/{debian-setup.sh => quick-setup.sh} (100%) diff --git a/utils/debian-setup.sh b/utils/quick-setup.sh similarity index 100% rename from utils/debian-setup.sh rename to utils/quick-setup.sh From 5b775d4a17af7cd7fbcc92a762aaba63b3480849 Mon Sep 17 00:00:00 2001 From: Roman Dodin Date: Wed, 24 Apr 2024 11:50:33 +0300 Subject: [PATCH 3/4] fix var assignment --- utils/quick-setup.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/utils/quick-setup.sh b/utils/quick-setup.sh index 4bb44ca81..30e698aaf 100644 --- a/utils/quick-setup.sh +++ b/utils/quick-setup.sh @@ -4,9 +4,9 @@ function check_os { if [ -f /etc/os-release ]; then . /etc/os-release if [ "$ID" = "debian" ]; then - ${DISTRO_TYPE}="debian" + DISTRO_TYPE="debian" elif [ "$ID" = "ubuntu" ]; then - ${DISTRO_TYPE}="ubuntu" + DISTRO_TYPE="ubuntu" else echo "This is not Debian or Ubuntu" fi From abbd2b51512174229aaf7fefc7a1997f5b3e6d9f Mon Sep 17 00:00:00 2001 From: Roman Dodin Date: Wed, 24 Apr 2024 12:23:18 +0300 Subject: [PATCH 4/4] added quick setup instructions --- docs/install.md | 60 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 42 insertions(+), 18 deletions(-) diff --git a/docs/install.md b/docs/install.md index 545d53b46..3f720ffe5 100644 --- a/docs/install.md +++ b/docs/install.md @@ -4,7 +4,7 @@ hide: --- Containerlab is distributed as a Linux deb/rpm package and can be installed on any Debian- or RHEL-like distributive in a matter of a few seconds. -### Pre-requisites +## Pre-requisites The following requirements must be satisfied to let containerlab tool run successfully: @@ -12,7 +12,32 @@ The following requirements must be satisfied to let containerlab tool run succes * A Linux server/VM[^2] and [Docker](https://docs.docker.com/engine/install/) installed. * Load container images (e.g. Nokia SR Linux, Arista cEOS) that are not downloadable from a container registry. Containerlab will try to pull images at runtime if they do not exist locally. -### Install script +## Quick setup + +The easiest way to get started with containerlab is to use the [quick setup script](https://github.com/srl-labs/containerlab/blob/main/utils/quick-setup.sh) that installs all of the following components in one go (or allows to install them separately): + +* docker (docker-ce), docker compose +* Containerlab (using the package repository) +* [`gh` CLI tool](https://cli.github.com/) + +The script supports the following OSes: + +* Ubuntu 20.04, 22.04, 23.10 +* Debian 11, 12 + +To install all components at once, run the following command on any of the supported OSes: + +```bash +curl -sL https://containerlab.dev/setup | sudo bash -s "all" +``` + +To install an individual component, specify the function name as an argument to the script. For example, to install only `docker`: + +```bash +curl -sL https://containerlab.dev/setup | sudo bash -s "install-docker" +``` + +## Install script Containerlab can be installed using the [installation script](https://github.com/srl-labs/containerlab/blob/main/get.sh) that detects the operating system type and installs the relevant package: @@ -56,7 +81,7 @@ Since the installation script uses GitHub API, users may hit the rate limit impo GITHUB_TOKEN= bash -c "$(curl -sL https://get.containerlab.dev)" ``` -### Package managers +## Package managers It is possible to install official containerlab releases via public APT/YUM repository. @@ -109,7 +134,7 @@ yum install https://github.com/srl-labs/containerlab/releases/download/v0.7.0/co /// The package installer will put the `containerlab` binary in the `/usr/bin` directory as well as create the `/usr/bin/clab -> /usr/bin/containerlab` symlink. The symlink allows the users to save on typing when they use containerlab: `clab `. -### Container +## Container Containerlab is also available in a container packaging. The latest containerlab release can be pulled with: @@ -150,7 +175,7 @@ ghcr.io/srl-labs/clab deploy -t somelab.clab.yml /// -### Manual installation +## Manual installation If the linux distributive can't install deb/rpm packages, containerlab can be installed from the archive: @@ -172,15 +197,14 @@ tar -zxvf /tmp/clab.tar.gz -C /etc/containerlab mv /etc/containerlab/containerlab /usr/bin && chmod a+x /usr/bin/containerlab ``` -### Windows Subsystem Linux (WSL) +## Windows Subsystem Linux (WSL) Containerlab [runs](https://twitter.com/ntdvps/status/1380915270328401922) on WSL, but you need to [install docker-ce](https://docs.docker.com/engine/install/) inside the WSL2 linux system instead of using Docker Desktop[^3]. -If you are running Ubuntu 20.04 as your WSL2 machine, you can run [this script](https://gist.github.com/hellt/e8095c1719a3ea0051165ff282d2b62a) to install docker-ce. +If you are running Ubuntu/Debian as your WSL2 machine, you can use the [quick setup this script](https://github.com/srl-labs/containerlab/blob/main/utils/quick-setup.sh) to install docker-ce. ```bash -curl -L https://gist.githubusercontent.com/hellt/e8095c1719a3ea0051165ff282d2b62a/raw/1dffb71d0495bb2be953c489cd06a25656d974a4/docker-install.sh | \ -bash +curl -L https://containerlab.dev/setup | sudo bash -s "install-docker" | \ ``` Once installed, issue `sudo service docker start` to start the docker service inside WSL2 machine. @@ -189,15 +213,15 @@ Once installed, issue `sudo service docker start` to start the docker service in In Windows 11 with WSL2 it is now possible to [enable KVM support](https://serverfault.com/a/1115773/351978). Let us know if that worked for you in our [Discord](community.md). /// -### Apple macOS +## Apple macOS Running containerlab on macOS is possible both on ARM (M1/M2) and Intel chipsets with certain limitations and caveats rooted in different architectures and underlying OS. -#### ARM +### ARM At the moment of this writing, there are not a lot[^6] of Network OSes built for arm64 architecture. This fact alone makes it not practical to run containerlab natively on ARM-based Macs. Nevertheless, it is technically possible to run containerlab on ARM-based Macs by launching a Linux VM with x86_64 architecture and running containerlab inside this VM. This approach comes with a hefty performance penalty, therefore it is suitable only for tiny labs. -##### UTM +#### UTM The easiest way to start a Linux VM with x86_64 architecture on macOS is to use [UTM](https://mac.getutm.app/). UTM is a free[^7] and open-source graphical virtual machine manager that provides a simple and intuitive interface for creating, managing, and running virtual machines with qemu. @@ -223,7 +247,7 @@ sudo clab version upgrade and start downloading the labs you want to run. -##### Docker in Docker +#### Docker in Docker Another option to run containerlab on ARM-based Macs is to use Docker in Docker approach. With this approach, a docker-in-docker container is launched on the macOS inside the VM providing a docker environment. This setup also works on other operating systems where Docker is available. Below is a step-by-step guide on how to set it up. @@ -329,7 +353,7 @@ Once the devcontainer is defined as described above: * Start your Containerlab //// -#### Intel +### Intel On Intel based Macs, containerlab can be run in a Linux VM started by Docker Desktop for Mac[^4]. To start using containerlab in this Linux VM we start a container with containerlab inside and mount the directory with our lab files into the container. @@ -433,7 +457,7 @@ INFO[0001] Adding containerlab host entries to /etc/hosts file /// -### Upgrade +## Upgrade To upgrade `containerlab` to the latest available version issue the following command[^1]: @@ -445,7 +469,7 @@ This command will fetch the installation script and will upgrade the tool to its Or leverage `apt`/`yum` utilities if containerlab repo was added as explained in the [Package managers](#package-managers) section. -### From source +## From source To build containerlab from source: @@ -463,7 +487,7 @@ goreleaser --snapshot --skip-publish --rm-dist /// -### Uninstall +## Uninstall To uninstall containerlab when it was installed via installation script or packages: @@ -487,7 +511,7 @@ yum remove containerlab Containerlab binary is located at `/usr/bin/containerlab`. In addition to the binary, containerlab directory with static files may be found at `/etc/containerlab`. /// -### SELinux +## SELinux When SELinux set to enforced mode containerlab binary might fail to execute with `Segmentation fault (core dumped)` error. This might be because containerlab binary is compressed with [upx](https://upx.github.io/) and selinux prevents it from being decompressed by default.