doc: tutorial freestanding deployment

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']
 

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
 ^^^^^^^^^^^^^^^^^^^^^^^
 

doc/manuals/install.rst

@@ -2,6 +2,8 @@
 Installation
 ************
 
+.. _install-debian-packages:
+
 Debian packages
 ===============
 

doc/requirements.in

@@ -3,3 +3,4 @@ recommonmark
 sphinx-autobuild
 sphinx-rtd-theme
 sphinxcontrib-openapi
+sphinx_copybutton

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 \

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"

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"

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
+        }
+      }
+    }
+  }
+}

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
+        }
+      }
+    }
+  }
+}

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
+        }
+      }
+    }
+  }
+}

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
+        }
+      }
+    }
+  }
+}

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
+        }
+      }
+    }
+  }
+}