From 0dfe8474fec4ca75b50a55ae092f1d3464b30176 Mon Sep 17 00:00:00 2001 From: barriejc <73184215+barriejc@users.noreply.github.com> Date: Sat, 26 Feb 2022 18:13:27 -0800 Subject: [PATCH 1/6] created new how-to doc for MacOS --- docs/CLAB_MACOS.md | 124 +++++++++++++++++++++++++++++++++++++++++++ docs/CONTAINERLAB.md | 4 +- 2 files changed, 126 insertions(+), 2 deletions(-) create mode 100644 docs/CLAB_MACOS.md diff --git a/docs/CLAB_MACOS.md b/docs/CLAB_MACOS.md new file mode 100644 index 0000000..19263ae --- /dev/null +++ b/docs/CLAB_MACOS.md @@ -0,0 +1,124 @@ +# Visualizing ContainerLab topologies on MacOS + + According to [ContainerLab documentation](https://containerlab.srlinux.dev/install/#mac-os), running vanilla clab on MacOS is possible using Docker Desktop. Testing revealed that this does not work with new M1 silicon[^1], however, and was successful only on an older Intel-based chipset[^2]. It will also not support vrnetlab-based nodes; see clab docs linked above for full details. The following instructions assume you already have Docker Desktop and vanilla clab installed and running. + +## Prerequisites + +1. (Optional) The creation of a VM for experimentation with Graphite and custom ContainerLab builds was not tested for this macOS case, since a dedicated MacBook was available. There is probably a way to do this; in fact there is evidently a way to [use multipass with hyperkit or VirtualBox](https://multipass.run/docs/installing-on-macos), to emulate step 1 in the [main ubuntu example](CONTAINERLAB.md). Please let us know what steps worked if anyone is successful on macOS. + +2. Install `gcc` and [Go](https://golang.org/dl/) for your platform to build a custom ContainerLab binary. [Homebrew](https://brew.sh) was tested as the package manager for this macOS case, and Xcode Command Line Tools had already been installed on the test Mac. According to [this guy](https://mac.install.guide/commandlinetools/index.html), however, homebrew will install them for you if you haven't done so already. + + If homebrew is already installed on your system, use `brew info` to check if gcc and go are installed already. It's also a good idea to `brew update` and `brew upgrade` before installing. Otherwise, after a fresh install with the curl command, skip ahead to `brew install` for both packages. + + From a Terminal window: + +```shell +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +brew info gcc +brew info go +brew update +brew upgrade +brew install gcc +brew install go +go version +``` + +3. Build a new, custom ContainerLab binary with topology export capabilities. Create an alias `clabg` for the binary. + + Currently (Feb'22), the standard ContainerLab build doesn't have the capability to export a topology data model suitable for Graphite. There is a [proposal](https://github.com/srl-labs/containerlab/issues/703) to introduce such an option into the product, as well as a possible [implementation](https://github.com/netreplica/containerlab/tree/graph-json). The current Graphite version relies on that implementation. + + As a prerequisite, please build a custom ContainerLab binary with topology export capabilities. You can continue using the official build for all other ContainerLab operations, and use this custom build in parallel to export topology data. + +```shell +cd $HOME +git clone https://github.com/netreplica/containerlab.git +cd containerlab +git checkout graph-json +go build +``` + - At this point in the macOS installation, an `undefined: netlink.FAMILY_V4` error and a similar V6 error was encountered. This is evidently a limitation in the macOS go implementation; to work around this, cross-compile for linux as follows (of course, you may be able to set this environment variable in the first place before the "go build" above, but it was not tested). + +```shell +GOOS=linux +go build +``` + + - This is the point where we need Docker Desktop running as mentioned in the [clab docs](https://containerlab.srlinux.dev/install/#mac-os), so go ahead and start it up if it wasn't up already. Once it's running, minimize it and return to Terminal to continue starting up the shell for the custom clabg: + +```Shell +CLABG_WORKDIR=$HOME/containerlab +docker run --rm -it --privileged \ + --network host \ + -v /var/run/docker.sock:/var/run/docker.sock \ + -v /run/netns:/run/netns \ + --pid="host" \ + -w $CLABG_WORKDIR \ + -v $CLABG_WORKDIR:$CLABG_WORKDIR \ + ghcr.io/srl-labs/clab bash +```` + + Now you should get a `bash-5.1# ` prompt, which means you are in the container for the custom graphite-ready build of containerlab that you just created. We'll alias that to "clabg" so that it does not conflict with the vanilla clab directory that should also exist in $HOME if you installed that before. + +```Shell +alias clabg="`pwd`/containerlab" +clabg graph -h | grep json +```` + + You should see an output with `--json` option designed to `generate json file instead of launching the web server`. + + +4. Clone Graphite and NextUI repositories + +```Shell +mkdir -p $HOME/clabs +cd $HOME/clabs +git clone https://github.com/netreplica/graphite.git +git clone https://github.com/netreplica/next-bower.git +```` + +5. Install and configure Lighttpd, if it's not there already, to serve Graphite web pages. You can use any other web server you prefer, please use configuration below as a reference. + +```Shell +brew info lighttpd +brew install lighttpd +echo $HOME/clabs +sudo vi /usr/local/etc/lighttpd/lighttpd.conf +```` + +Replace `server.document-root` value with the full path to a directory with ContainerLabs topologies and Graphite file (see `echo` output above). WARNING! This is a very basic setup for experimentation without any security measures. DO NOT USE IT AS IS for ContainerLab deployments that contain sensitive device configurations. + +```` +server.document-root = "/Users/yourname/clabs" +```` + +Restart the server using `brew services restart` (you will have to use `brew tap` beforehand if this is a new install): + +```` +brew tap homebrew/services +brew services restart lighttpd +brew services list +```` + +You should see something like the following if lighttpd has started successfully: + +```shell +% brew services list +Name Status User File +lighttpd started yourname ~/Library/LaunchAgents/homebrew.mxcl.lighttpd.plist +``` + +6. Validate access to Graphite web pages by opening the following URL in the browser: `http://REPLACE_IP:8080/graphite/main.html`. You should be able to see a sample topology: + +![Default Graphite Topology Visualization](../images/3-nodes.clab.png) + + Note that brew's current install of lighttpd defaults to port 8080; it seems that this can be changed in the same lighttpd.conf file where you changed the server.document-root, and so the URL would change accordingly. On the test MacBook Pro, the localhost IP (127.0.0.1 from ifconfig) is what works, but this of course needs to be changed to the assigned externally-facing IP address if using a different system to browse. + +[Return to Graphite Docs](CONTAINERLAB.md#visualize-a-topology-generated-from-a-containerlab-yaml-file-offline-mode) to continue with clab visualization. + +[^1]: Although [Linux can finally run on Apple's M1 chipset](https://www.linux-magazine.com/Online/News/Linux-Can-Now-Run-on-Apple-s-M1-Chipset), the maintainer of ContainerLab, Roman Dodin, has said that it's "painful" to get Go apps to work on darwin/arm64, and even if they did get it working, thus far no NOS vendors have rebuilt their containerized images (such as srlinux and ceos) for the new Apple silicon. + +[^2]: Test system details: + - macOS Catalina (10.15.7) + - MacBook Pro (Retina, 13-inch, Late 2013) + - Processor: 2.4 GHz Dual-core Intel Core i5 + - Memory: 8GB 1600 MHz DDR3 diff --git a/docs/CONTAINERLAB.md b/docs/CONTAINERLAB.md index 425f76e..0a3ed76 100644 --- a/docs/CONTAINERLAB.md +++ b/docs/CONTAINERLAB.md @@ -10,9 +10,9 @@ multipass shell clab-graphite sudo apt update && sudo apt install jq docker.io -y ```` - If you prefer to use any other environment, please make sure it meets ContainerLab [prerequisites](https://containerlab.srlinux.dev/install/#pre-requisites) + If you prefer to use any other environment, please make sure it meets ContainerLab [prerequisites](https://containerlab.srlinux.dev/install/#pre-requisites). For the special case of Intel Macs, check out [this reference](CLAB_MACOS.md) instead of the following steps 2-6, and modify the rest of the instructions accordingly. -2. Install `gcc` and [Go](https://golang.org/dl/) for your platform to build a custom ContainerLab binary. Here is an example for Ubuntu: +2. Install `gcc` and [Go](https://golang.org/dl/) for your platform to build a custom ContainerLab binary. Here is an example for Ubuntu: ```Shell sudo apt update && sudo apt install build-essential -y From 4fff419be8347ff7d1000d005fb8a02ec273290a Mon Sep 17 00:00:00 2001 From: barriejc <73184215+barriejc@users.noreply.github.com> Date: Sat, 26 Feb 2022 18:20:18 -0800 Subject: [PATCH 2/6] footnote problems --- docs/CLAB_MACOS.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/CLAB_MACOS.md b/docs/CLAB_MACOS.md index 19263ae..f6afdc1 100644 --- a/docs/CLAB_MACOS.md +++ b/docs/CLAB_MACOS.md @@ -118,7 +118,7 @@ lighttpd started yourname ~/Library/LaunchAgents/homebrew.mxcl.lighttpd.plist [^1]: Although [Linux can finally run on Apple's M1 chipset](https://www.linux-magazine.com/Online/News/Linux-Can-Now-Run-on-Apple-s-M1-Chipset), the maintainer of ContainerLab, Roman Dodin, has said that it's "painful" to get Go apps to work on darwin/arm64, and even if they did get it working, thus far no NOS vendors have rebuilt their containerized images (such as srlinux and ceos) for the new Apple silicon. [^2]: Test system details: - - macOS Catalina (10.15.7) - - MacBook Pro (Retina, 13-inch, Late 2013) - - Processor: 2.4 GHz Dual-core Intel Core i5 - - Memory: 8GB 1600 MHz DDR3 + - macOS Catalina (10.15.7) + - MacBook Pro (Retina, 13-inch, Late 2013) + - Processor: 2.4 GHz Dual-core Intel Core i5 + - Memory: 8GB 1600 MHz DDR3 From e7cb27f912215b9ce5b534b5fdbd645a70571439 Mon Sep 17 00:00:00 2001 From: barriejc <73184215+barriejc@users.noreply.github.com> Date: Sat, 26 Feb 2022 18:32:55 -0800 Subject: [PATCH 3/6] tweaked wording for alias --- docs/CLAB_MACOS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CLAB_MACOS.md b/docs/CLAB_MACOS.md index f6afdc1..a651b0b 100644 --- a/docs/CLAB_MACOS.md +++ b/docs/CLAB_MACOS.md @@ -57,7 +57,7 @@ docker run --rm -it --privileged \ ghcr.io/srl-labs/clab bash ```` - Now you should get a `bash-5.1# ` prompt, which means you are in the container for the custom graphite-ready build of containerlab that you just created. We'll alias that to "clabg" so that it does not conflict with the vanilla clab directory that should also exist in $HOME if you installed that before. + Now you should get a `bash-5.1# ` prompt, which means you are in the container for the custom graphite-ready build of containerlab that you just created. We'll alias that to "clabg" for short (the long "containerlab" directory name was used so that it does not conflict with the vanilla "clab" directory that should also exist in $HOME if you installed that before). ```Shell alias clabg="`pwd`/containerlab" From 02f0e8c1b80ac26cabff54e4124d5c2a94035b19 Mon Sep 17 00:00:00 2001 From: barriejc <73184215+barriejc@users.noreply.github.com> Date: Sat, 26 Feb 2022 18:42:45 -0800 Subject: [PATCH 4/6] tweaked brew services --- docs/CLAB_MACOS.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/CLAB_MACOS.md b/docs/CLAB_MACOS.md index a651b0b..94ad193 100644 --- a/docs/CLAB_MACOS.md +++ b/docs/CLAB_MACOS.md @@ -1,8 +1,8 @@ # Visualizing ContainerLab topologies on MacOS - According to [ContainerLab documentation](https://containerlab.srlinux.dev/install/#mac-os), running vanilla clab on MacOS is possible using Docker Desktop. Testing revealed that this does not work with new M1 silicon[^1], however, and was successful only on an older Intel-based chipset[^2]. It will also not support vrnetlab-based nodes; see clab docs linked above for full details. The following instructions assume you already have Docker Desktop and vanilla clab installed and running. + According to the [ContainerLab documentation](https://containerlab.srlinux.dev/install/#mac-os), running vanilla clab on MacOS is possible using Docker Desktop. Testing revealed that this does not work with new M1 silicon[^1], however, and was successful only on an older Intel-based chipset[^2]. It will also not support vrnetlab-based nodes; see clab docs linked above for full details. The following instructions assume you already have Docker Desktop and vanilla clab installed and running. -## Prerequisites +## Install Instructions 1. (Optional) The creation of a VM for experimentation with Graphite and custom ContainerLab builds was not tested for this macOS case, since a dedicated MacBook was available. There is probably a way to do this; in fact there is evidently a way to [use multipass with hyperkit or VirtualBox](https://multipass.run/docs/installing-on-macos), to emulate step 1 in the [main ubuntu example](CONTAINERLAB.md). Please let us know what steps worked if anyone is successful on macOS. @@ -96,7 +96,6 @@ Restart the server using `brew services restart` (you will have to use `brew tap ```` brew tap homebrew/services brew services restart lighttpd -brew services list ```` You should see something like the following if lighttpd has started successfully: From 09453ca2e1443d9b95d2fcc08ca79f8501cef066 Mon Sep 17 00:00:00 2001 From: barriejc <73184215+barriejc@users.noreply.github.com> Date: Sat, 26 Feb 2022 18:46:28 -0800 Subject: [PATCH 5/6] tweaked spelling --- docs/CLAB_MACOS.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/CLAB_MACOS.md b/docs/CLAB_MACOS.md index 94ad193..4cc9724 100644 --- a/docs/CLAB_MACOS.md +++ b/docs/CLAB_MACOS.md @@ -1,6 +1,6 @@ -# Visualizing ContainerLab topologies on MacOS +# Visualizing ContainerLab topologies on macOS - According to the [ContainerLab documentation](https://containerlab.srlinux.dev/install/#mac-os), running vanilla clab on MacOS is possible using Docker Desktop. Testing revealed that this does not work with new M1 silicon[^1], however, and was successful only on an older Intel-based chipset[^2]. It will also not support vrnetlab-based nodes; see clab docs linked above for full details. The following instructions assume you already have Docker Desktop and vanilla clab installed and running. + According to the [ContainerLab documentation](https://containerlab.srlinux.dev/install/#mac-os), running vanilla clab on macOS is possible using Docker Desktop. Testing revealed that this does not work with new M1 silicon[^1], however, and was successful only on an older Intel-based chipset[^2]. It will also not support vrnetlab-based nodes; see clab docs linked above for full details. The following instructions assume you already have Docker Desktop and vanilla clab installed and running. ## Install Instructions @@ -25,7 +25,7 @@ go version 3. Build a new, custom ContainerLab binary with topology export capabilities. Create an alias `clabg` for the binary. - Currently (Feb'22), the standard ContainerLab build doesn't have the capability to export a topology data model suitable for Graphite. There is a [proposal](https://github.com/srl-labs/containerlab/issues/703) to introduce such an option into the product, as well as a possible [implementation](https://github.com/netreplica/containerlab/tree/graph-json). The current Graphite version relies on that implementation. + Currently (Feb '22), the standard ContainerLab build doesn't have the capability to export a topology data model suitable for Graphite. There is a [proposal](https://github.com/srl-labs/containerlab/issues/703) to introduce such an option into the product, as well as a possible [implementation](https://github.com/netreplica/containerlab/tree/graph-json). The current Graphite version relies on that implementation. As a prerequisite, please build a custom ContainerLab binary with topology export capabilities. You can continue using the official build for all other ContainerLab operations, and use this custom build in parallel to export topology data. From 576b52532755deef926fa4a91e8b976fc510c72e Mon Sep 17 00:00:00 2001 From: Alex Bortok Date: Sat, 26 Feb 2022 21:12:42 -0800 Subject: [PATCH 6/6] changed syntax for clabg compiling with linux as a target --- docs/CLAB_MACOS.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/CLAB_MACOS.md b/docs/CLAB_MACOS.md index 4cc9724..c25f24c 100644 --- a/docs/CLAB_MACOS.md +++ b/docs/CLAB_MACOS.md @@ -39,8 +39,7 @@ go build - At this point in the macOS installation, an `undefined: netlink.FAMILY_V4` error and a similar V6 error was encountered. This is evidently a limitation in the macOS go implementation; to work around this, cross-compile for linux as follows (of course, you may be able to set this environment variable in the first place before the "go build" above, but it was not tested). ```shell -GOOS=linux -go build +GOOS=linux go build ``` - This is the point where we need Docker Desktop running as mentioned in the [clab docs](https://containerlab.srlinux.dev/install/#mac-os), so go ahead and start it up if it wasn't up already. Once it's running, minimize it and return to Terminal to continue starting up the shell for the custom clabg: