doc: tutorial freestanding deployment (#4435)

This tutorial was created at the IETF 118 hackathon. The goal is to make it easier to start tinkering with SCION outside of the complex and somewhat confusing development environment. Co-authored-by: John Studarus <[email protected]> Co-authored-by: Nicola Rustignoli <[email protected]> Co-authored-by: FR4NK-W <[email protected]> Co-authored-by: Matthias Frei <[email protected]>
scionproto · Feb 13, 2024 · fce093e · fce093e
1 parent 059f500
commit fce093e
Show file tree

Hide file tree

Showing 14 changed files with 669 additions and 0 deletions.
diff --git a/doc/conf.py b/doc/conf.py
@@ -22,8 +22,14 @@
     'sphinx_rtd_theme',
     'sphinx.ext.extlinks',
     'sphinxcontrib.openapi',
+    'sphinx_copybutton',
 ]
 
+copybutton_prompt_text = r'\w*\$ '  # matches e.g. <hostname>$
+copybutton_prompt_is_regexp = True
+copybutton_only_copy_prompt_lines = True
+
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

diff --git a/doc/index.rst b/doc/index.rst
@@ -91,6 +91,18 @@ implementation <https://github.com/scionproto/scion>`_.
    snet documentation should be a good starting point for using SCION as an application library.
    For this, the package documentation needs to be streamlined a bit...
 
+Guides and Tutorials
+^^^^^^^^^^^^^^^^^^^^
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Guides and Tutorials
+   :hidden:
+
+   tutorials/deploy
+
+* :doc:`tutorials/deploy`: Follow step by step instructions and see what a running SCION network could look like.
+
 Developer Documentation
 ^^^^^^^^^^^^^^^^^^^^^^^
 

diff --git a/doc/manuals/install.rst b/doc/manuals/install.rst
@@ -2,6 +2,8 @@
 Installation
 ************
 
+.. _install-debian-packages:
+
 Debian packages
 ===============
 

diff --git a/doc/requirements.in b/doc/requirements.in
@@ -3,3 +3,4 @@ recommonmark
 sphinx-autobuild
 sphinx-rtd-theme
 sphinxcontrib-openapi
+sphinx_copybutton
diff --git a/doc/requirements.txt b/doc/requirements.txt
@@ -332,12 +332,17 @@ sphinx==6.1.3 \
     #   -r requirements.in
     #   recommonmark
     #   sphinx-autobuild
+    #   sphinx-copybutton
     #   sphinx-rtd-theme
     #   sphinxcontrib-httpdomain
     #   sphinxcontrib-openapi
 sphinx-autobuild==2021.3.14 \
     --hash=sha256:8fe8cbfdb75db04475232f05187c776f46f6e9e04cacf1e49ce81bdac649ccac \
     --hash=sha256:de1ca3b66e271d2b5b5140c35034c89e47f263f2cd5db302c9217065f7443f05
+sphinx-copybutton==0.5.2 \
+    --hash=sha256:4cf17c82fb9646d1bc9ca92ac280813a3b605d8c421225fd9913154103ee1fbd \
+    --hash=sha256:fb543fd386d917746c9a2c50360c7905b605726b9355cd26e9974857afeae06e
+    # via -r requirements.in
     # via -r requirements.in
 sphinx-mdinclude==0.5.3 \
     --hash=sha256:02afadf4597aecf8255a702956eff5b8c5cb9658ea995c3d361722d2ed78cca9 \

diff --git a/doc/tutorials/deploy.rst b/doc/tutorials/deploy.rst
diff --git a/doc/tutorials/deploy/SCION-deployment-guide.drawio.png b/doc/tutorials/deploy/SCION-deployment-guide.drawio.png
diff --git a/doc/tutorials/deploy/br.toml b/doc/tutorials/deploy/br.toml
@@ -0,0 +1,5 @@
+# Deployment Guide Bridge Router Configuration File
+# Save this file as /etc/scion/br.toml
+[general]
+id = "br"
+config_dir = "/etc/scion"
diff --git a/doc/tutorials/deploy/cs.toml b/doc/tutorials/deploy/cs.toml
@@ -0,0 +1,18 @@
+# Sample Control Service configuration file
+# Save this file as /etc/scion/cs.toml
+[general]
+id = "cs"
+config_dir = "/etc/scion"
+reconnect_to_dispatcher = true
+
+[log.console]
+level = "info"
+
+[beacon_db]
+connection = "/var/lib/scion/control.beacon.db"
+
+[path_db]
+connection = "/var/lib/scion/control.path.db"
+
+[trust_db]
+connection = "/var/lib/scion/control.trust.db"
diff --git a/doc/tutorials/deploy/topology1.json b/doc/tutorials/deploy/topology1.json
@@ -0,0 +1,51 @@
+{
+  "attributes": [
+    "core"
+  ],
+  "isd_as": "42-ffaa:1:1",
+  "mtu": 1472,
+  "control_service": {
+    "cs": {
+      "addr": "127.0.0.1:31000"
+    }
+  },
+  "discovery_service": {
+    "cs": {
+      "addr": "127.0.0.1:31000"
+    }
+  },
+  "border_routers": {
+    "br": {
+      "internal_addr": "127.0.0.1:31002",
+      "interfaces": {
+        "1": {
+          "underlay": {
+            "public": "10.0.0.1:50014",
+            "remote": "10.0.0.4:50014"
+          },
+          "isd_as": "42-ffaa:1:4",
+          "link_to": "child",
+          "mtu": 1472
+        },
+        "2": {
+          "underlay": {
+            "public": "10.0.0.1:50012",
+            "remote": "10.0.0.2:50012"
+          },
+          "isd_as": "42-ffaa:1:2",
+          "link_to": "core",
+          "mtu": 1472
+        },
+        "3": {
+          "underlay": {
+            "public": "10.0.0.1:50013",
+            "remote": "10.0.0.3:50013"
+          },
+          "isd_as": "42-ffaa:1:3",
+          "link_to": "core",
+          "mtu": 1472
+        }
+      }
+    }
+  }
+}
diff --git a/doc/tutorials/deploy/topology2.json b/doc/tutorials/deploy/topology2.json
@@ -0,0 +1,51 @@
+{
+  "attributes": [
+    "core"
+  ],
+  "isd_as": "42-ffaa:1:2",
+  "mtu": 1472,
+  "control_service": {
+    "cs": {
+      "addr": "127.0.0.1:31000"
+    }
+  },
+  "discovery_service": {
+    "cs": {
+      "addr": "127.0.0.1:31000"
+    }
+  },
+  "border_routers": {
+    "br": {
+      "internal_addr": "127.0.0.1:31002",
+      "interfaces": {
+        "1": {
+          "underlay": {
+            "public": "10.0.0.2:50012",
+            "remote": "10.0.0.1:50012"
+          },
+          "isd_as": "42-ffaa:1:1",
+          "link_to": "core",
+          "mtu": 1472
+        },
+        "2": {
+          "underlay": {
+            "public": "10.0.0.2:50023",
+            "remote": "10.0.0.3:50023"
+          },
+          "isd_as": "42-ffaa:1:3",
+          "link_to": "core",
+          "mtu": 1472
+        },
+        "3": {
+          "underlay": {
+            "public": "10.0.0.2:50025",
+            "remote": "10.0.0.5:50025"
+          },
+          "isd_as": "42-ffaa:1:5",
+          "link_to": "child",
+          "mtu": 1472
+        }
+      }
+    }
+  }
+}
diff --git a/doc/tutorials/deploy/topology3.json b/doc/tutorials/deploy/topology3.json
@@ -0,0 +1,60 @@
+{
+  "attributes": [
+    "core"
+  ],
+  "isd_as": "42-ffaa:1:3",
+  "mtu": 1472,
+  "control_service": {
+    "cs": {
+      "addr": "127.0.0.1:31000"
+    }
+  },
+  "discovery_service": {
+    "cs": {
+      "addr": "127.0.0.1:31000"
+    }
+  },
+  "border_routers": {
+    "br": {
+      "internal_addr": "127.0.0.1:31002",
+      "interfaces": {
+        "1": {
+          "underlay": {
+            "public": "10.0.0.3:50013",
+            "remote": "10.0.0.1:50013"
+          },
+          "isd_as": "42-ffaa:1:1",
+          "link_to": "core",
+          "mtu": 1472
+        },
+        "2": {
+          "underlay": {
+            "public": "10.0.0.3:50023",
+            "remote": "10.0.0.2:50023"
+          },
+          "isd_as": "42-ffaa:1:2",
+          "link_to": "core",
+          "mtu": 1472
+        },
+        "3": {
+          "underlay": {
+            "public": "10.0.0.3:50034",
+            "remote": "10.0.0.4:50034"
+          },
+          "isd_as": "42-ffaa:1:4",
+          "link_to": "child",
+          "mtu": 1472
+        },
+        "4": {
+          "underlay": {
+            "public": "10.0.0.3:50035",
+            "remote": "10.0.0.5:50035"
+          },
+          "isd_as": "42-ffaa:1:5",
+          "link_to": "child",
+          "mtu": 1472
+        }
+      }
+    }
+  }
+}
diff --git a/doc/tutorials/deploy/topology4.json b/doc/tutorials/deploy/topology4.json
@@ -0,0 +1,40 @@
+{
+  "attributes": [],
+  "isd_as": "42-ffaa:1:4",
+  "mtu": 1472,
+  "control_service": {
+    "cs": {
+      "addr": "127.0.0.1:31000"
+    }
+  },
+  "discovery_service": {
+    "cs": {
+      "addr": "127.0.0.1:31000"
+    }
+  },
+  "border_routers": {
+    "br": {
+      "internal_addr": "127.0.0.1:31002",
+      "interfaces": {
+        "1": {
+          "underlay": {
+            "public": "10.0.0.4:50014",
+            "remote": "10.0.0.1:50014"
+          },
+          "isd_as": "42-ffaa:1:1",
+          "link_to": "parent",
+          "mtu": 1472
+        },
+        "2": {
+          "underlay": {
+            "public": "10.0.0.4:50034",
+            "remote": "10.0.0.3:50034"
+          },
+          "isd_as": "42-ffaa:1:3",
+          "link_to": "parent",
+          "mtu": 1472
+        }
+      }
+    }
+  }
+}
diff --git a/doc/tutorials/deploy/topology5.json b/doc/tutorials/deploy/topology5.json
@@ -0,0 +1,40 @@
+{
+  "attributes": [],
+  "isd_as": "42-ffaa:1:5",
+  "mtu": 1472,
+  "control_service": {
+    "cs": {
+      "addr": "127.0.0.1:31000"
+    }
+  },
+  "discovery_service": {
+    "cs": {
+      "addr": "127.0.0.1:31000"
+    }
+  },
+  "border_routers": {
+    "br": {
+      "internal_addr": "127.0.0.1:31002",
+      "interfaces": {
+        "1": {
+          "underlay": {
+            "public": "10.0.0.5:50025",
+            "remote": "10.0.0.2:50025"
+          },
+          "isd_as": "42-ffaa:1:2",
+          "link_to": "parent",
+          "mtu": 1472
+        },
+        "2": {
+          "underlay": {
+            "public": "10.0.0.5:50035",
+            "remote": "10.0.0.3:50035"
+          },
+          "isd_as": "42-ffaa:1:3",
+          "link_to": "parent",
+          "mtu": 1472
+        }
+      }
+    }
+  }
+}