From e71fa7da39c46a42624052deec7a7ca5841669f5 Mon Sep 17 00:00:00 2001 From: Corine de Kater Date: Sat, 4 Nov 2023 12:55:34 +0100 Subject: [PATCH 01/68] First draft content --- doc/deploy/deployment.rst | 151 ++++++++++++++++++++++++++++++++++++++ doc/index.rst | 14 ++++ 2 files changed, 165 insertions(+) create mode 100644 doc/deploy/deployment.rst diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst new file mode 100644 index 0000000000..c25d7c3295 --- /dev/null +++ b/doc/deploy/deployment.rst @@ -0,0 +1,151 @@ +.. _deployment-guide: + +Setting Up a Demo Environment +============================= + +This document helps you set up a SCION demo environment, which consists of a stand-alone full-scale environment distributed among five computers. + + +Setup +----- + + +Sample SCION Setup +.................. + +This is the sample setup: + +======================= ==== ========= ======== ============= +DNS Name ISD AS Purpose Notes +======================= ==== ========= ======== ============= +scion01.martincoit.net 42 ffaa:1:1 Core +scion02.martincoit.net 42 ffaa:2:1 Core +scion04.martincoit.net 42 ffaa:3:1 Core +scion05.martincoit.net 42 ffaa:1:1 Leaf +scion06.martincoit.net 42 ffaa:2:1 Leaf +======================= ==== ========= ======== ============= + +*Table 1: Sample setup* + + +Sample SCION Topology +..................... + +The SCION topology looks like this: + +https://app.diagrams.net/#G1WWprufQyCWXVKGZ5z5m_fIQyzTYcnNFk + + + +.. _prerequisites: + +Prerequisites +------------- + +There are some prerequisites before you can start setting up your demo environment. These are listed here: + + +- 5 VMs - **Ubuntu** 22.04.3 LTS (Jammy Jellyfish). For more information, see `Ubuntu Jammy Jellyfish `_. +- Memory? CPU? +- Network interfaces? (just one?) +- OS Configuration? + + - User accounts? + - System accounts? + + + +Steps to Perform +---------------- + +To create this environment, you need to perform the following steps, in this order: + +- Step 1: Installation (:ref:`step1`) +- Step 2: Configuration (:ref:`step2`) +- Step 3: Making sure the environment works (:ref:`step3`) +- Step 4: Testing (:ref:`step4`) + + +The following sections explain the required steps, one section per step. + + + +.. _step1: + +Installation +............ + +This section guides you through the installation of the SCION software. + +First, you need to get the SCION software. You have two options: + +- Install from packages (coming later in 2024). +- Install from binaries. The latest software can be found at: + + - `Latest official release `_ + - `Latest nightly build `_ + + +In this example, we use the following official release version: +*scion_v0.9.1_amd64_linux.tar.gz* + + +1. Download and extract the latest scionproto binary release by executing the following command: + +.. code-block:: + +wget https://github.com/scionproto/scion/releases/download/v0.9.1/scion_v0.9.1_amd64_linux.tar.gz +tar -xzvf scion_v0.9.1_amd64_linux.tar.gz + + +2. You can now install the selected software packages by executing a couple of commands. +AS #1 Core +The first machine will be AS #1 +Sudo -i +Cd /tmp +wget https://github.com/scionproto/scion/releases/download/v0.9.1/scion_v0.9.1_amd64_linux.tar.gz +Mkdir /usr/local/scion +Cd /usr/local/scion +tar xfz /tmp/scion_v0.9.1_amd64_linux.tar.gz + + + + +.. _step2: + +Configuration +............. + +Introduction + +Tasks + +1. Do this +2. Do that + + +.. _step3: + +Making Sure the Environment Works +................................. + +Introduction + +Tasks + +1. Do this +2. Do that + + +.. _step4: + +Testing +....... + + +Introduction + +Tasks + +1. Do this +2. Do that \ No newline at end of file diff --git a/doc/index.rst b/doc/index.rst index ce12baffaa..9726376b8b 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -88,6 +88,20 @@ implementation `_. 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... + + + +Deployment Guide +^^^^^^^^^^^^^^^^ + +.. toctree:: + :maxdepth: 1 + :caption: Deployment Guide + :hidden: + + deploy/deployment + + Developer Documentation ^^^^^^^^^^^^^^^^^^^^^^^ From 41c01f7de8a44d4d59c05f3a02e14cf6214454ce Mon Sep 17 00:00:00 2001 From: Corine de Kater Date: Sat, 4 Nov 2023 17:11:40 +0100 Subject: [PATCH 02/68] Deployment Guide - II --- doc/deploy/SCION-deployment-guide.drawio.png | Bin 0 -> 65628 bytes doc/deploy/deployment.rst | 211 +++++++++++++++---- 2 files changed, 167 insertions(+), 44 deletions(-) create mode 100644 doc/deploy/SCION-deployment-guide.drawio.png diff --git a/doc/deploy/SCION-deployment-guide.drawio.png b/doc/deploy/SCION-deployment-guide.drawio.png new file mode 100644 index 0000000000000000000000000000000000000000..43a94cd71e1442861cae91a3a773958f797fdb8d GIT binary patch literal 65628 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 fBx@NVJ<*+g2IZ-)M~ig2_JEHS$`_. -- Memory? CPU? -- Network interfaces? (just one?) -- OS Configuration? - - - User accounts? - - System accounts? +- 5 VMs - **Ubuntu** 22.04.3 LTS (Jammy Jellyfish). For more information, see `Ubuntu Jammy Jellyfish `_. These 5 virtual maschines resemble the ASes shown in the setup overview above - each maschine is one AS. +.. note:: + It is useful to give the machines names that fit/suit the setup of your demo environment. -Steps to Perform ----------------- -To create this environment, you need to perform the following steps, in this order: -- Step 1: Installation (:ref:`step1`) -- Step 2: Configuration (:ref:`step2`) -- Step 3: Making sure the environment works (:ref:`step3`) -- Step 4: Testing (:ref:`step4`) +Tasks to Perform +---------------- +To create this environment, you need to perform the following tasks, in this order: -The following sections explain the required steps, one section per step. +- Task 1: Installation (:ref:`step1`) +- Task 2: Configuration (:ref:`step2`) +- Task 3: Making sure the environment works (:ref:`step3`) +- Task 4: Testing (:ref:`step4`) +The following sections explain the required tasks, one section per task. .. _step1: @@ -76,8 +76,7 @@ Installation ............ This section guides you through the installation of the SCION software. - -First, you need to get the SCION software. You have two options: +Here is where you can get the software: - Install from packages (coming later in 2024). - Install from binaries. The latest software can be found at: @@ -86,42 +85,166 @@ First, you need to get the SCION software. You have two options: - `Latest nightly build `_ -In this example, we use the following official release version: +In this example, we install software with the following release version: *scion_v0.9.1_amd64_linux.tar.gz* +Note that we have to install the software five times: Once for each virual machine we created previously, where three machines represent core ASes and two machines are non-core, leaf ASes. Proceed as described in the following sections. + + +Downloading and Installing the SCION Software +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To download the software and install it on your virtual machines, execute the following commands in your shell/terminal: + +.. note:: + + These steps are the same for each virtual machine. So you have to repeat these steps five times, once per virtual machine. -1. Download and extract the latest scionproto binary release by executing the following command: .. code-block:: -wget https://github.com/scionproto/scion/releases/download/v0.9.1/scion_v0.9.1_amd64_linux.tar.gz -tar -xzvf scion_v0.9.1_amd64_linux.tar.gz + Sudo -i + + Cd /tmp + + wget https://github.com/scionproto/scion/releases/download/v0.9.1/scion_v0.9.1_amd64_linux.tar.gz + Mkdir /usr/local/scion -2. You can now install the selected software packages by executing a couple of commands. -AS #1 Core -The first machine will be AS #1 -Sudo -i -Cd /tmp -wget https://github.com/scionproto/scion/releases/download/v0.9.1/scion_v0.9.1_amd64_linux.tar.gz -Mkdir /usr/local/scion -Cd /usr/local/scion -tar xfz /tmp/scion_v0.9.1_amd64_linux.tar.gz + Cd /usr/local/scion + tar xfz /tmp/scion_v0.9.1_amd64_linux.tar.gz +As each virtual machine represents an AS in your demo environment, we will now refer to the VMs as ASes. + .. _step2: Configuration ............. -Introduction +To configure your demo SCION environment, perform the following steps. + + +Step 1 - Configure the topology (files) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, you have to configure the topology files for your demo environment. +You have to create is one "global" topology file which describes the setup of the entire ISD environment, as well as one specific AS topology file, one for each of the ASes in your demo ISD. The topology file of an AS specifies all the inter-AS connections to neighboring ASes, and defines the underlay IP/UDP addresses of services and routers running in this AS. This implies that the topology file will be different for each AS in your demo environment. + +The topology information is needed by Router and Control Service instances, and also by end-host applications. For more information on the topology files, see ``_ + +1. First, create a "global" topology file with the name *GlobalDeploymentTopology.topo*, by executing the following command: + + .. code-block:: + + Cat > GlobalDeploymentTopology.topo + +2. Fill this file with the following content: + + .. code-block:: + + ASes: + "42-ffaa:1:1": + core: true + voting: true + authoritative: true + issuing: true + "42-ffaa:1:2": + core: true + cert_issuer: 42-ffaa:1:1 + "42-ffaa:1:3": + core: true + cert_issuer: 42-ffaa:1:1 + "42-ffaa:1:4": + cert_issuer: 42-ffaa:1:1 + "42-ffaa:1:5": + cert_issuer: 42-ffaa:1:1 + + links: + - {a: "42-ffaa:1:1#1", b: "42-ffaa:1:4#1", linkAtoB: CHILD} + - {a: "42-ffaa:1:1#2", b: "42-ffaa:1:2#1", linkAtoB: CORE} + - {a: "42-ffaa:1:1#3", b: "42-ffaa:1:3#1", linkAtoB: CORE} + - {a: "42-ffaa:1:2#2", b: "42-ffaa:1:3#2", linkAtoB: CORE} + - {a: "42-ffaa:1:2#3", b: "42-ffaa:1:5#1", linkAtoB: CHILD} + - {a: "42-ffaa:1:3#3", b: "42-ffaa:1:4#2", linkAtoB: CHILD} + - {a: "42-ffaa:1:3#4", b: "42-ffaa:1:5#2", linkAtoB: CHILD} + + +3. Save the just-created global topology file (with the name *GlobalDeploymentTopology.topo*). + +4. Now you have to create a topology file per AS. **TODO** + + +Step 2 - Generate all required certificates +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The next step is to generate all required certificates by using the global topology file. Proceed as follows: + +1. To generate all required certificates using the global topology file, execute the following command: + + .. code-block:: + + /usr/local/scion/scion-pki testcrypto -t GlobalDeploymentTopology.topo + + This will generate all the required keys in the *gen/* directory. + +2. Now you have to distribute the just-generated keys to the AS routers. Proceed as follows: + + - Copy the *gen/* directory with its content to each of the five AS routers. **TODO** + - Now for each AS, execute the commands in the following code block. Pay attention to the following: + + - All lines except for the last line are the same for each AS. + - The part *ASffaa_1_1* in the last line needs to be adapted per AS, so that it contains the correct AS number for the corresponding AS. + + .. code-block:: + + mkdir -p /etc/scion/keys + dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master0.key + dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master1.key + mkdir /etc/scion/certs + cp gen/trcs/* /etc/scion/certs + mkdir -p /etc/scion/crypto/as + cp ./gen/ASffaa_1_1/crypto/as/* /etc/scion/crypto/as/ + + + .. note:: + + The above script will distribute the SCION control-plane PKI keys/certificates to the ASes. Additionally, it will create the two symmetric keys *master0.key* and *master1.key* per AS, and store them in the AS's */etc/scion/keys/* directory. The symmetric key is used by the AS in the date plane to verify the MACs in the hop fields of a SCION path (header). + + +Step 3 - Create the directories for the support database files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To create the required directories for the support database files, execute the following command. Do this once per each AS. + +.. code-block:: + + mkdir /var/lib/scion + + +Step 4 - Copy over the configuration files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**TODO** + + +Step 5 - Start the services +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You now have to start the services on each of the five ASes. Execute the following commands on each AS: + +.. code-block:: + + screen /usr/local/scion/router --config /etc/scion/br.toml + screen /usr/local/scion/dispatcher --config /etc/scion/dispatcher.toml + screen /usr/local/scion/control --config /etc/scion/cs.toml + screen /usr/local/scion/daemon --config /etc/scion/sd.toml + + -Tasks -1. Do this -2. Do that .. _step3: From be469055762408685cd1d319f1f9857e41cadbbc Mon Sep 17 00:00:00 2001 From: Corine de Kater Date: Sat, 4 Nov 2023 17:49:45 +0100 Subject: [PATCH 03/68] Deployment Guide - III --- doc/deploy/SCION-deployment-guide.drawio.png | Bin 65628 -> 52727 bytes doc/deploy/deployment.rst | 81 ++++++++++++++++--- 2 files changed, 72 insertions(+), 9 deletions(-) diff --git a/doc/deploy/SCION-deployment-guide.drawio.png b/doc/deploy/SCION-deployment-guide.drawio.png index 43a94cd71e1442861cae91a3a773958f797fdb8d..85ce0ea8c89d439f809ed57df38cd199425cd921 100644 GIT binary patch literal 52727 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

Yw2~W2`i)+l)9HRMkCw#A*Y~M1Xq> zgCfsaE8cpq?4`e#i7Uo*bh%~5PSY`4lUTcC{GGmAnZELi4Dt~OCLi?wf}Ac2%_Z`rrX}B5xR}x6 z$b7BGQTAH)1Y3NHBHD>);;vA&H@<#=nl}P;>Atat1)FaLt@~i^gp%#pZFv$eUurO; z$vf=FPMMCt9yTNV%@thLLTH5_OV!^SQOUch_-N;=Gu-2+2O3iOBR7uH$a<`wiWLh* zBS#m?1CCE4BA=lgH=k#}=7~*@_Ig^*xyT`%e@@cc{nhg8lqZd+3uwJIEzcmr*}A$c z<9+&5p6TLB^ZgjAQrFuGXKq!6FOHPvR&NuWTe8UkGe&N8B3Eu|G-~#kIGFhGT3dxg z%5F5)22IJDa{l-+DmXwMzKzY|6>z*bkdQRLnNW;0e@_FVW(y7`LZF4Bjw+m z1W?vZXE&9^RFxETSp*CoF=nf;Kl;;V4dLOAE)}IXI}*hI$>m8tts8z>%STP4cvWCp zBrP{UfA0qj^|+}|_6&Q*UuTEgN{rEe^;dII&}~xmtk4mYtdPU<^yDB#nq8jQEFY!6 zR9p)Fy1x_Y=P8jDnjdt7`NDd+){2^nFI$YRJUbnSb}CmM_e+#2WAZMU>K)Y^^!Zx~ z&P;jTU$f2}%ix>^3qCI8+>|i;6-uvE`2+`~UwStsE3blvQ!WZu=89=3=N{6k6I?qW z+ImKrE@e*b0RWQC+ zUp{3y@pQc-k!;f)fqy zjkHfIcegMNU6&osnIeC5b0@oh&M!Q!XxSe7y{?y(SvjFpXJi(IUx@YYLBHaf?t5}8 z&b<$|JYg894orozu}o`fsu46(Z~M~Je)Fz+ zSq5I!J!VlxI~i|rzR>b{8%k!qTsK@%1FvO3B)U6US7fJI zNf$On8hHcR(nb5mgg^Rgw=iQ*aM@}Jm@(%+i0=|d!Zr< zyI%8J@(ZYgRqn8hIYvXum-%+Y9llgZphPE|Ezv(Q7A{J@UYc-R0 z){*LJT)8Tu)z0%hHj*7EAP=kvP^ia@Eyn`ID8;(MSp=?q$E0^XzCy>G^RQ=2cW3Z# z81h`t(w@8Y$1y3%Ge6STV*>K=hb z^xl+qJ|T5LV}M6^>$auz1E)rEy{Och|8+6*+B39Pr*t~Hp9~mS4wu*A^NTS7>u>|{ zVd!JmjQ(UPRK#3*n)e`)2d1^<#2ji$!+vvUG2gmlEs`b^TjE7#6X3D-6n&orIFAsj zBKx=opexy!zPV4jYk2%IcMkJ$S_pO2^c5FKvgF0o*eznWZ{w^lK4(~Mwip=VE=+=( z99yl_o@NcEVSr@k&6HE-}|5I!#0a)sQ; zD=Ax5eDS1kzNDQ@x}hD%#oC>m`~h?MDgd!&Rg-vt>)59U%GK}LmfA|R)PaPL$vux$IBjEaV!HY77QupL0Ce;gesNVLp_X{=D3ZL5(}7BkA8rC#i+ zH2cF*oyC?1pv-`L3>>9B5b-h=&?Ki=fuf$E0#lm(BA63eV1SePe-;BOken0uest^T z2tEH<>+u^M=G*}zN18Q7pZI-gzgFXruMPmDZYqgr|8ChhxDH5(Kx5$f9T(N(|Lq;P z`5fTW{~v>}MVTqydI309guh7s)2RmC@}@udU&4KY4^{K!xS~|-hk33Y!21X52U?@P zU;YWZ9$fiZECh7yL1AaHArIh)`FRN}H}to8P;wMeCz1X2Ki5IcELgg8xiQ!OTU5DU m+WUWl{CgVz|2SRS$edd@zP@Z~qBsQps3@r`7F@sQ_x}KONs7M! literal 65628 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 fBx@NVJ<*+g2IZ-)M~ig2_JEHS$ Date: Sat, 4 Nov 2023 17:59:12 +0100 Subject: [PATCH 04/68] deployment guide - corrections --- doc/deploy/deployment.rst | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index eab4bdda7c..75db45aa63 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -3,7 +3,7 @@ Setting Up a Demo Environment ============================= -This document helps you set up a SCION demo environment, which consists of a stand-alone full-scale SCION environment distributed among five computers. The demo environment resembles one SCION Isolation Domain, with three core ASes and three non-core, leaf ASes. +This document helps you set up a SCION demo environment, which consists of a stand-alone full-scale SCION environment distributed among five computers. The demo environment resembles one SCION Isolation Domain, with three core ASes and two non-core, leaf ASes. Setup @@ -15,15 +15,15 @@ Sample SCION Setup This is the sample setup: -======================= ==== ========= ======== ================= -DNS Name ISD AS Purpose Notes -======================= ==== ========= ======== ================= +======================= ==== ========= ======== =========== =============== +DNS Name ISD AS Purpose Notes IP Address +======================= ==== ========= ======== =========== =============== scion01.martincoit.net 42 ffaa:1:1 Core ISD Voting scion02.martincoit.net 42 ffaa:1:2 Core ISD Voting scion04.martincoit.net 42 ffaa:1:3 Core ISD Voting scion05.martincoit.net 42 ffaa:1:4 Leaf scion06.martincoit.net 42 ffaa:1:5 Leaf -======================= ==== ========= ======== ================= +======================= ==== ========= ======== =========== =============== *Table 1: Sample setup* @@ -103,15 +103,15 @@ To download the software and install it on your virtual machines, execute the fo .. code-block:: - Sudo -i + sudo -i - Cd /tmp + cd /tmp wget https://github.com/scionproto/scion/releases/download/v0.9.1/scion_v0.9.1_amd64_linux.tar.gz - Mkdir /usr/local/scion + mkdir /usr/local/scion - Cd /usr/local/scion + cd /usr/local/scion tar xfz /tmp/scion_v0.9.1_amd64_linux.tar.gz @@ -135,11 +135,7 @@ You have to create is one "global" topology file which describes the setup of th The topology information is needed by Router and Control Service instances, and also by end-host applications. For more information on the topology files, see ``_ -1. First, create a "global" topology file with the name *GlobalDeploymentTopology.topo*, by executing the following command: - - .. code-block:: - - Cat > GlobalDeploymentTopology.topo +1. First, create a "global" topology file with the name *GlobalDeploymentTopology.topo*. 2. Fill this file with the following content: From 085aaccd75fe51b0ed3ca3682ceee282176e8eed Mon Sep 17 00:00:00 2001 From: Corine de Kater Date: Sat, 4 Nov 2023 18:10:52 +0100 Subject: [PATCH 05/68] deployment guide - more corrections --- doc/deploy/deployment.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 75db45aa63..614a9505c2 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -9,6 +9,10 @@ This document helps you set up a SCION demo environment, which consists of a sta Setup ----- +This first section provides an overview of the setup and topology of the sample demo environment. It lists some details of the ISD and each AS in the ISD, such as the ISD- and AS number, the DNS names, the kind of AS (core or leaf) and the IP addresses. + +The topology of the ISD includes the inter-AS connections to neighboring ASes, and defines the underlay IP/UDP addresses of services and routers running in this AS. This is specified in topology files - this guide explains how to configure these files. + Sample SCION Setup .................. @@ -46,8 +50,7 @@ The SCION topology looks like this: Prerequisites ------------- -There are some prerequisites before you can start setting up your demo environment. These are listed here: - +Before you can start setting up your demo environment, you need to set up some virtual machines (VMs), one per AS in our ISD/demo environment. We recommend the following VMs: - 5 VMs - **Ubuntu** 22.04.3 LTS (Jammy Jellyfish). For more information, see `Ubuntu Jammy Jellyfish `_. These 5 virtual maschines resemble the ASes shown in the setup overview above - each maschine is one AS. From d2d68d6d83d94cc2b7a3a71f0d4234e0477d0e96 Mon Sep 17 00:00:00 2001 From: Corine de Kater Date: Sat, 4 Nov 2023 18:15:48 +0100 Subject: [PATCH 06/68] Update deployment guide --- doc/deploy/deployment.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 614a9505c2..3c21983f9a 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -275,7 +275,7 @@ The files including their names are listed below. Use the added sample code snip socket_file_mode = "0770" -- **Service discovery**: *sd.toml* file +- **SCION deamon**: *sd.toml* file .. code-block:: From 7372b00accc0cb1021eba8fa52cc0a7831b6bad6 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sat, 4 Nov 2023 10:18:36 -0700 Subject: [PATCH 07/68] Update deployment.rst --- doc/deploy/deployment.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 3c21983f9a..0b703dfa4b 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -299,10 +299,12 @@ You now have to start the services on each of the five ASes. Execute the followi .. code-block:: - screen /usr/local/scion/router --config /etc/scion/br.toml - screen /usr/local/scion/dispatcher --config /etc/scion/dispatcher.toml - screen /usr/local/scion/control --config /etc/scion/cs.toml - screen /usr/local/scion/daemon --config /etc/scion/sd.toml + screen -dmS BR /usr/local/scion/router --config /etc/scion/br.toml + + screen -dmS BorderRouter /usr/local/scion/router --config /etc/scion/br.toml + screen -dmS Dispatcher /usr/local/scion/dispatcher --config /etc/scion/dispatcher.toml + screen -dmS Control /usr/local/scion/control --config /etc/scion/cs.toml + screen -dmS Daemon /usr/local/scion/daemon --config /etc/scion/sd.toml @@ -333,4 +335,4 @@ Introduction Tasks 1. Do this -2. Do that \ No newline at end of file +2. Do that From 34887fa0d52f399b8b7e9263f8a52aa494728ce7 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sat, 4 Nov 2023 10:21:13 -0700 Subject: [PATCH 08/68] Update deployment.rst --- doc/deploy/deployment.rst | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 0b703dfa4b..37c40f98d6 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -323,6 +323,39 @@ Tasks 1. Do this 2. Do that +# /usr/local/scion/scion address +42-ffaa:1:1,127.0.0.1 + + + +# /usr/local/scion/scion ping 42-ffaa:1:5,127.0.0.1 -c 5 +Resolved local address: + 127.0.0.1 +Using path: + Hops: [42-ffaa:1:1 3>1 42-ffaa:1:3 4>2 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 + +PING 42-ffaa:1:5,127.0.0.1:0 pld=0B scion_pkt=112B +120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=0 time=0.788ms +120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=1 time=3.502ms +120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=2 time=3.313ms +120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=3 time=3.838ms +120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=4 time=3.401ms + +--- 42-ffaa:1:5,127.0.0.1 statistics --- +5 packets transmitted, 5 received, 0% packet loss, time 5000.718ms +rtt min/avg/max/mdev = 0.788/2.968/3.838/1.105 ms + + +# /usr/local/scion/scion showpaths 42-ffaa:1:5 +Available paths to 42-ffaa:1:5 +3 Hops: +[0] Hops: [42-ffaa:1:1 2>1 42-ffaa:1:2 3>1 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 +[1] Hops: [42-ffaa:1:1 3>1 42-ffaa:1:3 4>2 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 +4 Hops: +[2] Hops: [42-ffaa:1:1 2>1 42-ffaa:1:2 2>2 42-ffaa:1:3 4>2 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 +[3] Hops: [42-ffaa:1:1 3>1 42-ffaa:1:3 2>2 42-ffaa:1:2 3>1 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 + + .. _step4: From 4bd46fd5082fa3b21048b7dc28fbde8191701363 Mon Sep 17 00:00:00 2001 From: Corine de Kater Date: Sat, 4 Nov 2023 18:41:27 +0100 Subject: [PATCH 09/68] correction --- doc/deploy/deployment.rst | 96 +++++++++++++++------------------------ 1 file changed, 37 insertions(+), 59 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 37c40f98d6..d19918fadd 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -22,11 +22,11 @@ This is the sample setup: ======================= ==== ========= ======== =========== =============== DNS Name ISD AS Purpose Notes IP Address ======================= ==== ========= ======== =========== =============== -scion01.martincoit.net 42 ffaa:1:1 Core ISD Voting -scion02.martincoit.net 42 ffaa:1:2 Core ISD Voting -scion04.martincoit.net 42 ffaa:1:3 Core ISD Voting -scion05.martincoit.net 42 ffaa:1:4 Leaf -scion06.martincoit.net 42 ffaa:1:5 Leaf +scion01.martincoit.net 42 ffaa:1:1 Core ISD Voting 147.28.184.149 +scion02.martincoit.net 42 ffaa:1:2 Core ISD Voting 147.28.184.150 +scion04.martincoit.net 42 ffaa:1:3 Core ISD Voting 147.28.184.146 +scion05.martincoit.net 42 ffaa:1:4 Leaf 147.28.184.147 +scion06.martincoit.net 42 ffaa:1:5 Leaf 147.28.184.148 ======================= ==== ========= ======== =========== =============== *Table 1: Sample setup* @@ -67,8 +67,7 @@ To create this environment, you need to perform the following tasks, in this ord - Task 1: Installation (:ref:`step1`) - Task 2: Configuration (:ref:`step2`) -- Task 3: Making sure the environment works (:ref:`step3`) -- Task 4: Testing (:ref:`step4`) +- Task 3: Testing your environment (:ref:`step3`) The following sections explain the required tasks, one section per task. @@ -173,7 +172,8 @@ The topology information is needed by Router and Control Service instances, and 3. Save the just-created global topology file (with the name *GlobalDeploymentTopology.topo*). -4. Now you have to create a topology file per AS. **TODO** +4. Now you have to create a topology file per AS. +**TODO - Link to sample config files per AS** Step 2 - Generate All Required Certificates @@ -299,8 +299,7 @@ You now have to start the services on each of the five ASes. Execute the followi .. code-block:: - screen -dmS BR /usr/local/scion/router --config /etc/scion/br.toml - + screen -dmS BR /usr/local/scion/router --config /etc/scion/br.toml screen -dmS BorderRouter /usr/local/scion/router --config /etc/scion/br.toml screen -dmS Dispatcher /usr/local/scion/dispatcher --config /etc/scion/dispatcher.toml screen -dmS Control /usr/local/scion/control --config /etc/scion/cs.toml @@ -308,64 +307,43 @@ You now have to start the services on each of the five ASes. Execute the followi - - - .. _step3: -Making Sure the Environment Works -................................. - -Introduction - -Tasks - -1. Do this -2. Do that +Testing the Environment +....................... -# /usr/local/scion/scion address -42-ffaa:1:1,127.0.0.1 +You can now test your environment. This section shows how. +.. code-block:: + # /usr/local/scion/scion address + 42-ffaa:1:1,127.0.0.1 -# /usr/local/scion/scion ping 42-ffaa:1:5,127.0.0.1 -c 5 -Resolved local address: - 127.0.0.1 -Using path: - Hops: [42-ffaa:1:1 3>1 42-ffaa:1:3 4>2 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 - -PING 42-ffaa:1:5,127.0.0.1:0 pld=0B scion_pkt=112B -120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=0 time=0.788ms -120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=1 time=3.502ms -120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=2 time=3.313ms -120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=3 time=3.838ms -120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=4 time=3.401ms - ---- 42-ffaa:1:5,127.0.0.1 statistics --- -5 packets transmitted, 5 received, 0% packet loss, time 5000.718ms -rtt min/avg/max/mdev = 0.788/2.968/3.838/1.105 ms - - -# /usr/local/scion/scion showpaths 42-ffaa:1:5 -Available paths to 42-ffaa:1:5 -3 Hops: -[0] Hops: [42-ffaa:1:1 2>1 42-ffaa:1:2 3>1 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 -[1] Hops: [42-ffaa:1:1 3>1 42-ffaa:1:3 4>2 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 -4 Hops: -[2] Hops: [42-ffaa:1:1 2>1 42-ffaa:1:2 2>2 42-ffaa:1:3 4>2 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 -[3] Hops: [42-ffaa:1:1 3>1 42-ffaa:1:3 2>2 42-ffaa:1:2 3>1 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 - - + # /usr/local/scion/scion ping 42-ffaa:1:5,127.0.0.1 -c 5 + Resolved local address: + 127.0.0.1 + Using path: + Hops: [42-ffaa:1:1 3>1 42-ffaa:1:3 4>2 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 -.. _step4: + PING 42-ffaa:1:5,127.0.0.1:0 pld=0B scion_pkt=112B + 120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=0 time=0.788ms + 120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=1 time=3.502ms + 120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=2 time=3.313ms + 120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=3 time=3.838ms + 120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=4 time=3.401ms -Testing -....... + --- 42-ffaa:1:5,127.0.0.1 statistics --- + 5 packets transmitted, 5 received, 0% packet loss, time 5000.718ms + rtt min/avg/max/mdev = 0.788/2.968/3.838/1.105 ms + # /usr/local/scion/scion showpaths 42-ffaa:1:5 + Available paths to 42-ffaa:1:5 + 3 Hops: + [0] Hops: [42-ffaa:1:1 2>1 42-ffaa:1:2 3>1 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 + [1] Hops: [42-ffaa:1:1 3>1 42-ffaa:1:3 4>2 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 + 4 Hops: + [2] Hops: [42-ffaa:1:1 2>1 42-ffaa:1:2 2>2 42-ffaa:1:3 4>2 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 + [3] Hops: [42-ffaa:1:1 3>1 42-ffaa:1:3 2>2 42-ffaa:1:2 3>1 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 -Introduction -Tasks -1. Do this -2. Do that From e54560acfb883e382899d62926f2b586bd83712d Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sat, 4 Nov 2023 10:42:37 -0700 Subject: [PATCH 10/68] Create br.toml --- doc/deploy/br.toml | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 doc/deploy/br.toml diff --git a/doc/deploy/br.toml b/doc/deploy/br.toml new file mode 100644 index 0000000000..1985179efb --- /dev/null +++ b/doc/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" From 360bbcd5aac5511b4e03f3040932d3facb891f4f Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sat, 4 Nov 2023 10:43:46 -0700 Subject: [PATCH 11/68] Create cs.toml --- doc/deploy/cs.toml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 doc/deploy/cs.toml diff --git a/doc/deploy/cs.toml b/doc/deploy/cs.toml new file mode 100644 index 0000000000..b98063667e --- /dev/null +++ b/doc/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" From 66dd3e053dedb159021dc49c6c7994ee1aee7a67 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sat, 4 Nov 2023 10:45:02 -0700 Subject: [PATCH 12/68] Create dispatcher.toml --- doc/deploy/dispatcher.toml | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 doc/deploy/dispatcher.toml diff --git a/doc/deploy/dispatcher.toml b/doc/deploy/dispatcher.toml new file mode 100644 index 0000000000..8e219e3151 --- /dev/null +++ b/doc/deploy/dispatcher.toml @@ -0,0 +1,12 @@ +# Dispatcher configuration file. +# Save this file as /etc/scion/dispatcher.toml + +[log.console] +# Console logging level (debug|info|error) (default info) +level = "info" + +[dispatcher] +id = "dispatcher" + +# File permissions of the ApplicationSocket socket file, in octal. (default "0770") +socket_file_mode = "0770" From 489c57cc8c73319904371f787e7042fe36cf939e Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sat, 4 Nov 2023 10:45:59 -0700 Subject: [PATCH 13/68] Create sd.toml --- doc/deploy/sd.toml | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 doc/deploy/sd.toml diff --git a/doc/deploy/sd.toml b/doc/deploy/sd.toml new file mode 100644 index 0000000000..913cfcbc24 --- /dev/null +++ b/doc/deploy/sd.toml @@ -0,0 +1,13 @@ +# SCION Daemon configuration file +# Save this file as /etc/scion/sd.toml + +[general] +id = "sd" +config_dir = "/etc/scion" +reconnect_to_dispatcher = true + +[trust_db] +connection = "/var/lib/sd.trust.db" + +[path_db] +connection = "/var/lib/sd.path.db" From 4ee2c8ea012db19eeeea65269ca71ce196a2d41a Mon Sep 17 00:00:00 2001 From: Nicola Rustignoli Date: Sat, 4 Nov 2023 19:40:39 +0100 Subject: [PATCH 14/68] sample topology files --- doc/deploy/topology1.json | 51 +++++++++++++++++++++++++++++++++ doc/deploy/topology2.json | 51 +++++++++++++++++++++++++++++++++ doc/deploy/topology3.json | 60 +++++++++++++++++++++++++++++++++++++++ doc/deploy/topology4.json | 40 ++++++++++++++++++++++++++ doc/deploy/topology5.json | 40 ++++++++++++++++++++++++++ 5 files changed, 242 insertions(+) create mode 100644 doc/deploy/topology1.json create mode 100644 doc/deploy/topology2.json create mode 100644 doc/deploy/topology3.json create mode 100644 doc/deploy/topology4.json create mode 100644 doc/deploy/topology5.json diff --git a/doc/deploy/topology1.json b/doc/deploy/topology1.json new file mode 100644 index 0000000000..8b06984c34 --- /dev/null +++ b/doc/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": "147.28.184.149:50014", + "remote": "147.28.184.147:50014" + }, + "isd_as": "42-ffaa:1:4", + "link_to": "child", + "mtu": 1472 + }, + "2": { + "underlay": { + "public": "147.28.184.149:50012", + "remote": "147.28.184.150:50012" + }, + "isd_as": "42-ffaa:1:2", + "link_to": "core", + "mtu": 1472 + }, + "3": { + "underlay": { + "public": "147.28.184.149:50013", + "remote": "147.28.184.146:50013" + }, + "isd_as": "42-ffaa:1:3", + "link_to": "core", + "mtu": 1472 + } + } + } + } +} diff --git a/doc/deploy/topology2.json b/doc/deploy/topology2.json new file mode 100644 index 0000000000..2725d6ddbd --- /dev/null +++ b/doc/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": "147.28.184.150:50012", + "remote": "147.28.184.149:50012" + }, + "isd_as": "42-ffaa:1:1", + "link_to": "core", + "mtu": 1472 + }, + "2": { + "underlay": { + "public": "147.28.184.150:50023", + "remote": "147.28.184.146:50023" + }, + "isd_as": "42-ffaa:1:3", + "link_to": "core", + "mtu": 1472 + }, + "3": { + "underlay": { + "public": "147.28.184.150:50025", + "remote": "147.28.184.148:50025" + }, + "isd_as": "42-ffaa:1:5", + "link_to": "child", + "mtu": 1472 + } + } + } + } +} diff --git a/doc/deploy/topology3.json b/doc/deploy/topology3.json new file mode 100644 index 0000000000..5473c0b597 --- /dev/null +++ b/doc/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": "147.28.184.146:50013", + "remote": "147.28.184.149:50013" + }, + "isd_as": "42-ffaa:1:1", + "link_to": "core", + "mtu": 1472 + }, + "2": { + "underlay": { + "public": "147.28.184.146:50023", + "remote": "147.28.184.150:50023" + }, + "isd_as": "42-ffaa:1:2", + "link_to": "core", + "mtu": 1472 + }, + "3": { + "underlay": { + "public": "147.28.184.146:50034", + "remote": "147.28.184.147:50034" + }, + "isd_as": "42-ffaa:1:4", + "link_to": "child", + "mtu": 1472 + }, + "4": { + "underlay": { + "public": "147.28.184.146:50035", + "remote": "147.28.184.148:50035" + }, + "isd_as": "42-ffaa:1:5", + "link_to": "child", + "mtu": 1472 + } + } + } + } +} diff --git a/doc/deploy/topology4.json b/doc/deploy/topology4.json new file mode 100644 index 0000000000..7dfaee7efa --- /dev/null +++ b/doc/deploy/topology4.json @@ -0,0 +1,40 @@ +{ + "attributes": [], + "isd_as": "42-ffaa:1:4", + "mtu": 1472, + "control_service": { + "cs42-ffaa_1_4-1": { + "addr": "127.0.0.1:31000" + } + }, + "discovery_service": { + "cs42-ffaa_1_4-1": { + "addr": "127.0.0.1:31000" + } + }, + "border_routers": { + "br42-ffaa_1_4-1": { + "internal_addr": "127.0.0.1:31002", + "interfaces": { + "1": { + "underlay": { + "public": "147.28.184.147:50014", + "remote": "147.28.184.149:50014" + }, + "isd_as": "42-ffaa:1:1", + "link_to": "parent", + "mtu": 1472 + }, + "2": { + "underlay": { + "public": "147.28.184.147:50034", + "remote": "147.28.184.146:50034" + }, + "isd_as": "42-ffaa:1:3", + "link_to": "parent", + "mtu": 1472 + } + } + } + } +} diff --git a/doc/deploy/topology5.json b/doc/deploy/topology5.json new file mode 100644 index 0000000000..19dd58cc5a --- /dev/null +++ b/doc/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": "147.28.184.148:50025", + "remote": "147.28.184.150:50025" + }, + "isd_as": "42-ffaa:1:2", + "link_to": "parent", + "mtu": 1472 + }, + "2": { + "underlay": { + "public": "147.28.184.148:50035", + "remote": "147.28.184.146:50035" + }, + "isd_as": "42-ffaa:1:3", + "link_to": "parent", + "mtu": 1472 + } + } + } + } +} From 7d26f683c5d287161b46476f92f0a006cc96affe Mon Sep 17 00:00:00 2001 From: Corine de Kater Date: Sat, 4 Nov 2023 20:41:01 +0100 Subject: [PATCH 15/68] Last corrections deployment guide --- doc/deploy/deployment.rst | 114 ++++++++++++-------------------------- 1 file changed, 35 insertions(+), 79 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index d19918fadd..fd4b271acc 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -3,21 +3,18 @@ Setting Up a Demo Environment ============================= -This document helps you set up a SCION demo environment, which consists of a stand-alone full-scale SCION environment distributed among five computers. The demo environment resembles one SCION Isolation Domain, with three core ASes and two non-core, leaf ASes. +This document helps you set up a SCION demo configuration, which consists of a stand-alone full-scale SCION environment distributed among five computers. The demo environment resembles one SCION Isolation Domain ISD, with three core ASes and two non-core, leaf ASes. Setup ----- -This first section provides an overview of the setup and topology of the sample demo environment. It lists some details of the ISD and each AS in the ISD, such as the ISD- and AS number, the DNS names, the kind of AS (core or leaf) and the IP addresses. +This first section provides an overview of the setup and topology of the sample demo environment. -The topology of the ISD includes the inter-AS connections to neighboring ASes, and defines the underlay IP/UDP addresses of services and routers running in this AS. This is specified in topology files - this guide explains how to configure these files. - - -Sample SCION Setup -.................. +Sample SCION Demo Setup +....................... -This is the sample setup: +The sample SCION demo setup consists of one ISD with three core ASes and two non-core, leaf ASes. The following table lists some details of the sample ISD and each AS in it, such as the DNS names, the ISD- and AS numbers, the kind of AS (core or leaf) and the IP addresses. ======================= ==== ========= ======== =========== =============== DNS Name ISD AS Purpose Notes IP Address @@ -32,10 +29,10 @@ scion06.martincoit.net 42 ffaa:1:5 Leaf 147.28.184.148 *Table 1: Sample setup* -Sample SCION Topology -..................... +Sample SCION Demo Topology +.......................... -The SCION topology looks like this: +The topology of the ISD includes the inter-AS connections to neighboring ASes, and defines the underlay IP/UDP addresses of services and routers running in this AS. This is specified in topology files - this guide later explains how to configure these files. A following graphic depicts the topology on a high level. .. figure:: SCION-deployment-guide.drawio.png :width: 95 % @@ -50,20 +47,20 @@ The SCION topology looks like this: Prerequisites ------------- -Before you can start setting up your demo environment, you need to set up some virtual machines (VMs), one per AS in our ISD/demo environment. We recommend the following VMs: +Before you can start setting up your demo environment, you need to set up five virtual machines (VMs), one per AS in our ISD/demo environment. We recommend using Ubuntu VMs for this. - 5 VMs - **Ubuntu** 22.04.3 LTS (Jammy Jellyfish). For more information, see `Ubuntu Jammy Jellyfish `_. These 5 virtual maschines resemble the ASes shown in the setup overview above - each maschine is one AS. .. note:: - It is useful to give the machines names that fit/suit the setup of your demo environment. + It is useful to give each VM a name that fits/suits the setup of your demo environment. Tasks to Perform ---------------- -To create this environment, you need to perform the following tasks, in this order: +To create the sample ISD environment, you need to perform the following tasks, in this order: - Task 1: Installation (:ref:`step1`) - Task 2: Configuration (:ref:`step2`) @@ -90,7 +87,7 @@ Here is where you can get the software: In this example, we install software with the following release version: *scion_v0.9.1_amd64_linux.tar.gz* -Note that we have to install the software five times: Once for each virual machine we created previously, where three machines represent core ASes and two machines are non-core, leaf ASes. Proceed as described in the following sections. +Note that we have to install the software five times: Once per virtual machine we created previously. Proceed as described in the following sections. Downloading and Installing the SCION Software @@ -133,7 +130,7 @@ Step 1 - Configure the Topology (Files) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ First, you have to configure the topology files for your demo environment. -You have to create is one "global" topology file which describes the setup of the entire ISD environment, as well as one specific AS topology file, one for each of the ASes in your demo ISD. The topology file of an AS specifies all the inter-AS connections to neighboring ASes, and defines the underlay IP/UDP addresses of services and routers running in this AS. This implies that the topology file will be different for each AS in your demo environment. +You have to create one "global" topology file which describes the setup of the entire ISD environment, as well as one specific AS topology file per AS in your demo ISD. The topology file of an AS specifies all the inter-AS connections to neighboring ASes, and defines the underlay IP/UDP addresses of services and routers running in this AS. This implies that the topology file will be different for each AS in your demo environment. The topology information is needed by Router and Control Service instances, and also by end-host applications. For more information on the topology files, see ``_ @@ -172,8 +169,18 @@ The topology information is needed by Router and Control Service instances, and 3. Save the just-created global topology file (with the name *GlobalDeploymentTopology.topo*). -4. Now you have to create a topology file per AS. -**TODO - Link to sample config files per AS** +4. Now you have to create a topology file per AS. Sample topology files for each AS in our sample ISD environment are listed below. Click on the file name to download it, then copy the file to the corresponding AS. + + - **AS 1 (ffaa:1:1)**: `topology1.json `_ + + - **AS 2 (ffaa:1:2)**: `topology2.json `_ + + - **AS 3 (ffaa:1:3)**: `topology3.json `_ + + - **AS 4 (ffaa:1:4)**: `topology4.json `_ + + - **AS 5 (ffaa:1:5)**: `topology5.json `_ + Step 2 - Generate All Required Certificates @@ -192,7 +199,7 @@ The next step is to generate all required certificates by using the global topol 2. Now you have to distribute the just-generated keys to the AS routers. Proceed as follows: - Copy the *gen/* directory with its content to each of the five AS routers. **TODO** - - Now for each AS, execute the commands in the following code block. Pay attention to the following: + - For each AS, execute the commands in the following code block. Pay attention to the following: - All lines except for the last line are the same for each AS. - The part *ASffaa_1_1* in the last line needs to be adapted per AS, so that it contains the correct AS number for the corresponding AS. @@ -226,76 +233,24 @@ To create the required directories for the support database files, execute the f Step 4 - Create the Configuration Files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Next, you have to create ("copy over") a couple of configuration files in the */etc/scion/* directory. -The files including their names are listed below. Use the added sample code snippets to configure the files. Again, you have to create these files on every AS machine. - -- **Border router**: *br.toml* file - - .. code-block:: - - [general] - id = "br" - config_dir = "/etc/scion" - - -- **Control service**: *cs.toml* file +Next, you have to create ("copy over") a couple of configuration files in the */etc/scion/* directory of each AS. - .. code-block:: +The files including their names are listed below. Click on the corresponding link to download the file, then copy it into the */etc/scion/* directory of each AS. - [general] - id = "cs" - config_dir = "/etc/scion" - reconnect_to_dispatcher = true +- **Border router**: `br.toml `_ - [log.console] - level = "info" +- **Control service**: `cs.toml `_ - [beacon_db] - connection = "/var/lib/scion/control.beacon.db" +- **Dispatcher**: `dispatcher.toml `_ - [path_db] - connection = "/var/lib/scion/control.path.db" - - [trust_db] - connection = "/var/lib/scion/control.trust.db" - - -- **Dispatcher**: *dispatcher.toml* file - - .. code-block:: - - [log.console] - # Console logging level (debug|info|error) (default info) - level = "info" - - [dispatcher] - id = "dispatcher" - - # File permissions of the ApplicationSocket socket file, in octal. (default "0770") - socket_file_mode = "0770" - - -- **SCION deamon**: *sd.toml* file - - .. code-block:: - - [general] - id = "sd" - config_dir = "/etc/scion" - reconnect_to_dispatcher = true - - [trust_db] - connection = "/var/lib/sd42-ffaa_1_1.trust.db" - - [path_db] - connection = "/var/lib/sd42-ffaa_1_1.path.db" +- **SCION deamon**: `sd.toml `_ Step 5 - Start the Services ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You now have to start the services on each of the five ASes. Execute the following commands on every AS: +As a last step, you have to start the services on each of the five ASes. Execute the following commands on every AS: .. code-block:: @@ -312,7 +267,8 @@ You now have to start the services on each of the five ASes. Execute the followi Testing the Environment ....................... -You can now test your environment. This section shows how. +You can now test your environment. The code block below includes some PING tests you could perform to check whether your environment works well. + .. code-block:: From 6df205e60c911d58fb2c0f5453b133958cae257a Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 01:52:35 -0700 Subject: [PATCH 16/68] Update deployment.rst --- doc/deploy/deployment.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index fd4b271acc..a6167e22ad 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -1,7 +1,7 @@ .. _deployment-guide: -Setting Up a Demo Environment -============================= +Deployment Tutorial +=================== This document helps you set up a SCION demo configuration, which consists of a stand-alone full-scale SCION environment distributed among five computers. The demo environment resembles one SCION Isolation Domain ISD, with three core ASes and two non-core, leaf ASes. From 560008f1694369cc7eb6b9185a61fd9827cb79f7 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 01:55:10 -0700 Subject: [PATCH 17/68] Update deployment.rst --- doc/deploy/deployment.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index a6167e22ad..b65ca282be 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -3,7 +3,7 @@ Deployment Tutorial =================== -This document helps you set up a SCION demo configuration, which consists of a stand-alone full-scale SCION environment distributed among five computers. The demo environment resembles one SCION Isolation Domain ISD, with three core ASes and two non-core, leaf ASes. +This document helps you set up a SCION demo configuration, which consists of a stand-alone full-scale SCION environment distributed among five computers. The demo environment consists of one SCION Isolation Domain (ISD), with three core ASes and two non-core, leaf ASes. Setup @@ -16,15 +16,15 @@ Sample SCION Demo Setup The sample SCION demo setup consists of one ISD with three core ASes and two non-core, leaf ASes. The following table lists some details of the sample ISD and each AS in it, such as the DNS names, the ISD- and AS numbers, the kind of AS (core or leaf) and the IP addresses. -======================= ==== ========= ======== =========== =============== -DNS Name ISD AS Purpose Notes IP Address -======================= ==== ========= ======== =========== =============== -scion01.martincoit.net 42 ffaa:1:1 Core ISD Voting 147.28.184.149 -scion02.martincoit.net 42 ffaa:1:2 Core ISD Voting 147.28.184.150 -scion04.martincoit.net 42 ffaa:1:3 Core ISD Voting 147.28.184.146 -scion05.martincoit.net 42 ffaa:1:4 Leaf 147.28.184.147 -scion06.martincoit.net 42 ffaa:1:5 Leaf 147.28.184.148 -======================= ==== ========= ======== =========== =============== +======== ==== ========= ======== =========== =============== +Hostname ISD AS Purpose Notes IP Address +======== ==== ========= ======== =========== =============== +scion01 42 ffaa:1:1 Core Voting 147.28.184.149 +scion02 42 ffaa:1:2 Core Non-Voting 147.28.184.150 +scion04 42 ffaa:1:3 Core Non-Voting 147.28.184.146 +scion05 42 ffaa:1:4 Leaf 147.28.184.147 +scion06 42 ffaa:1:5 Leaf 147.28.184.148 +======= ==== ========= ======== =========== =============== *Table 1: Sample setup* From 66f8e9f61caa96a2f0259808b95420861413d4d4 Mon Sep 17 00:00:00 2001 From: Corine de Kater Date: Sun, 5 Nov 2023 09:55:59 +0100 Subject: [PATCH 18/68] deploy guide - first changes --- doc/deploy/deployment.rst | 2 ++ doc/index.rst | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index b65ca282be..4c721ab3f4 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -5,6 +5,8 @@ Deployment Tutorial This document helps you set up a SCION demo configuration, which consists of a stand-alone full-scale SCION environment distributed among five computers. The demo environment consists of one SCION Isolation Domain (ISD), with three core ASes and two non-core, leaf ASes. +- If you want to go deep and help develop SCION, use the development environment. See +- If you want to use SCION in a large environment, use the SCIONLab. For more information, see Setup ----- diff --git a/doc/index.rst b/doc/index.rst index 9726376b8b..31e7ee9f4a 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -96,7 +96,7 @@ Deployment Guide .. toctree:: :maxdepth: 1 - :caption: Deployment Guide + :caption: Deployment Tutorial :hidden: deploy/deployment From cd446952c49aabe38612de8f3b4f350acb8bd5d5 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 01:00:16 -0800 Subject: [PATCH 19/68] Update deployment.rst --- doc/deploy/deployment.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 4c721ab3f4..65155a61a5 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -26,7 +26,7 @@ scion02 42 ffaa:1:2 Core Non-Voting 147.28.184.150 scion04 42 ffaa:1:3 Core Non-Voting 147.28.184.146 scion05 42 ffaa:1:4 Leaf 147.28.184.147 scion06 42 ffaa:1:5 Leaf 147.28.184.148 -======= ==== ========= ======== =========== =============== +======== ==== ========= ======== =========== =============== *Table 1: Sample setup* From d70d005d4bf501fd2d6f173387cd21461f32c3b8 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 01:01:33 -0800 Subject: [PATCH 20/68] Update deployment.rst --- doc/deploy/deployment.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 65155a61a5..ce9f7de132 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -13,10 +13,10 @@ Setup This first section provides an overview of the setup and topology of the sample demo environment. -Sample SCION Demo Setup -....................... +Infrastructure +.............. -The sample SCION demo setup consists of one ISD with three core ASes and two non-core, leaf ASes. The following table lists some details of the sample ISD and each AS in it, such as the DNS names, the ISD- and AS numbers, the kind of AS (core or leaf) and the IP addresses. +The sample SCION demo setup consists of one ISD with three core ASes and two non-core, leaf ASes. The following table lists some details of the sample ISD and each AS in it, such as the DNS names, the ISD- and AS numbers, the kind of AS (core or leaf) and the IP addresses. This infrastructure could be virtual machines or bare metal. ======== ==== ========= ======== =========== =============== Hostname ISD AS Purpose Notes IP Address @@ -28,7 +28,7 @@ scion05 42 ffaa:1:4 Leaf 147.28.184.147 scion06 42 ffaa:1:5 Leaf 147.28.184.148 ======== ==== ========= ======== =========== =============== -*Table 1: Sample setup* +*Table 1: Required Infrastructure* Sample SCION Demo Topology From 11d4cccf2292204e98de673812ab113d58ae45cc Mon Sep 17 00:00:00 2001 From: Corine de Kater Date: Sun, 5 Nov 2023 10:02:38 +0100 Subject: [PATCH 21/68] deploy guide - corrected table --- doc/deploy/deployment.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 4c721ab3f4..65155a61a5 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -26,7 +26,7 @@ scion02 42 ffaa:1:2 Core Non-Voting 147.28.184.150 scion04 42 ffaa:1:3 Core Non-Voting 147.28.184.146 scion05 42 ffaa:1:4 Leaf 147.28.184.147 scion06 42 ffaa:1:5 Leaf 147.28.184.148 -======= ==== ========= ======== =========== =============== +======== ==== ========= ======== =========== =============== *Table 1: Sample setup* From 8a1b36f191006a6b51a03f42221d105258cfe21f Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 01:03:21 -0800 Subject: [PATCH 22/68] Update deployment.rst --- doc/deploy/deployment.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index ce9f7de132..19d4cf39f8 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -5,8 +5,8 @@ Deployment Tutorial This document helps you set up a SCION demo configuration, which consists of a stand-alone full-scale SCION environment distributed among five computers. The demo environment consists of one SCION Isolation Domain (ISD), with three core ASes and two non-core, leaf ASes. -- If you want to go deep and help develop SCION, use the development environment. See -- If you want to use SCION in a large environment, use the SCIONLab. For more information, see +- If you want to go deep and help develop SCION, use the development environment. See https://docs.scion.org/en/latest/dev/setup.html +- If you want to use SCION in a large environment, use the SCIONLab. For more information, see https://www.scionlab.org/ Setup ----- From 335fcea0531c0d8c5ab136d8942f399deafe3d62 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 01:05:56 -0800 Subject: [PATCH 23/68] private IP addressing --- doc/deploy/deployment.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 19d4cf39f8..eccb9fb0ed 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -21,11 +21,11 @@ The sample SCION demo setup consists of one ISD with three core ASes and two non ======== ==== ========= ======== =========== =============== Hostname ISD AS Purpose Notes IP Address ======== ==== ========= ======== =========== =============== -scion01 42 ffaa:1:1 Core Voting 147.28.184.149 -scion02 42 ffaa:1:2 Core Non-Voting 147.28.184.150 -scion04 42 ffaa:1:3 Core Non-Voting 147.28.184.146 -scion05 42 ffaa:1:4 Leaf 147.28.184.147 -scion06 42 ffaa:1:5 Leaf 147.28.184.148 +scion01 42 ffaa:1:1 Core Voting 10.0.1.1 +scion02 42 ffaa:1:2 Core Non-Voting 10.0.1.2 +scion03 42 ffaa:1:3 Core Non-Voting 10.0.1.3 +scion04 42 ffaa:1:4 Leaf 10.0.1.4 +scion05 42 ffaa:1:5 Leaf 10.0.1.5 ======== ==== ========= ======== =========== =============== *Table 1: Required Infrastructure* From eea07108bbb6e346d21152521f3d10b587598034 Mon Sep 17 00:00:00 2001 From: Corine de Kater Date: Sun, 5 Nov 2023 10:13:46 +0100 Subject: [PATCH 24/68] added copy code button to conf.py --- doc/conf.py | 2 ++ doc/deploy/deployment.rst | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index a3bd61c410..30db34d78e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -22,8 +22,10 @@ 'sphinx_rtd_theme', 'sphinx.ext.extlinks', 'sphinxcontrib.openapi', + 'sphinx_copybutton', ] + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index eccb9fb0ed..8ab15a597d 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -51,7 +51,7 @@ Prerequisites Before you can start setting up your demo environment, you need to set up five virtual machines (VMs), one per AS in our ISD/demo environment. We recommend using Ubuntu VMs for this. -- 5 VMs - **Ubuntu** 22.04.3 LTS (Jammy Jellyfish). For more information, see `Ubuntu Jammy Jellyfish `_. These 5 virtual maschines resemble the ASes shown in the setup overview above - each maschine is one AS. +- 5 VMs - **Ubuntu** 22.04.3 LTS (Jammy Jellyfish). For more information, see `Ubuntu Jammy Jellyfish `_. These 5 virtual machines resemble the ASes shown in the setup overview above - each machine is one AS. .. note:: @@ -245,7 +245,7 @@ The files including their names are listed below. Click on the corresponding lin - **Dispatcher**: `dispatcher.toml `_ -- **SCION deamon**: `sd.toml `_ +- **SCION daemon**: `sd.toml `_ From ac3e6b00d59b394c9090c1ea52f242b80eba7c93 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 01:16:00 -0800 Subject: [PATCH 25/68] added VM hardware requirements --- doc/deploy/deployment.rst | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index eccb9fb0ed..1cd35f149d 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -18,15 +18,15 @@ Infrastructure The sample SCION demo setup consists of one ISD with three core ASes and two non-core, leaf ASes. The following table lists some details of the sample ISD and each AS in it, such as the DNS names, the ISD- and AS numbers, the kind of AS (core or leaf) and the IP addresses. This infrastructure could be virtual machines or bare metal. -======== ==== ========= ======== =========== =============== -Hostname ISD AS Purpose Notes IP Address -======== ==== ========= ======== =========== =============== -scion01 42 ffaa:1:1 Core Voting 10.0.1.1 -scion02 42 ffaa:1:2 Core Non-Voting 10.0.1.2 -scion03 42 ffaa:1:3 Core Non-Voting 10.0.1.3 -scion04 42 ffaa:1:4 Leaf 10.0.1.4 -scion05 42 ffaa:1:5 Leaf 10.0.1.5 -======== ==== ========= ======== =========== =============== +======== ==== ========= ======== =========== =============== ====================== ======== ==== +Hostname ISD AS Purpose Notes IP Address OS Disk RAM +======== ==== ========= ======== =========== =============== ====================== ======== ==== +scion01 42 ffaa:1:1 Core Voting 10.0.1.1 **Ubuntu** 22.04.3 LTS 4 GB 1 GB +scion02 42 ffaa:1:2 Core Non-Voting 10.0.1.2 **Ubuntu** 22.04.3 LTS 4 GB 1 GB +scion03 42 ffaa:1:3 Core Non-Voting 10.0.1.3 **Ubuntu** 22.04.3 LTS 4 GB 1 GB +scion04 42 ffaa:1:4 Leaf 10.0.1.4 **Ubuntu** 22.04.3 LTS 4 GB 1 GB +scion05 42 ffaa:1:5 Leaf 10.0.1.5 **Ubuntu** 22.04.3 LTS 4 GB 1 GB +======== ==== ========= ======== =========== =============== ====================== ======== ==== *Table 1: Required Infrastructure* @@ -46,10 +46,11 @@ The topology of the ISD includes the inter-AS connections to neighboring ASes, a .. _prerequisites: -Prerequisites -------------- +Infrastructure Prerequisites +---------------------------- -Before you can start setting up your demo environment, you need to set up five virtual machines (VMs), one per AS in our ISD/demo environment. We recommend using Ubuntu VMs for this. +This deployment requires five virtual machines (VMs) - one for each AS. +, one per AS in our ISD/demo environment. We recommend using Ubuntu VMs for this. - 5 VMs - **Ubuntu** 22.04.3 LTS (Jammy Jellyfish). For more information, see `Ubuntu Jammy Jellyfish `_. These 5 virtual maschines resemble the ASes shown in the setup overview above - each maschine is one AS. From 86761029ed5dde6a1f66d409861a1690155e19fc Mon Sep 17 00:00:00 2001 From: Corine de Kater Date: Sun, 5 Nov 2023 10:19:33 +0100 Subject: [PATCH 26/68] installing copy button --- doc/requirements.in | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/requirements.in b/doc/requirements.in index 880a8fd665..bbac42f584 100644 --- a/doc/requirements.in +++ b/doc/requirements.in @@ -3,3 +3,4 @@ recommonmark sphinx-autobuild sphinx-rtd-theme sphinxcontrib-openapi +sphinx_copybutton From b86400efa3693bdd944cb96d5817f7bbfa7be41b Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 01:24:36 -0800 Subject: [PATCH 27/68] Update deployment.rst --- doc/deploy/deployment.rst | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index a68b9c2d6a..f26f4c423d 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -270,15 +270,20 @@ As a last step, you have to start the services on each of the five ASes. Execute Testing the Environment ....................... -You can now test your environment. The code block below includes some PING tests you could perform to check whether your environment works well. +You can now test your environment. The code block below includes some tests you could perform to check whether your environment works well. +Verify that each host has a SCION address. This can be verified with the "scion address" command as shown below. .. code-block:: - # /usr/local/scion/scion address + scion01$ /usr/local/scion/scion address 42-ffaa:1:1,127.0.0.1 - # /usr/local/scion/scion ping 42-ffaa:1:5,127.0.0.1 -c 5 +Verify that each host can ping the other hosts via SCION. This can be done with the "scion ping" command. In the example below, we are pinging between scion01 (AS 42-ffaa:1:1) to scion05 (AS 42-ffaa:1:5). Very that each AS can ping every other AS. + +.. code-block:: + + scion01$ /usr/local/scion/scion ping 42-ffaa:1:5,127.0.0.1 -c 5 Resolved local address: 127.0.0.1 Using path: @@ -295,7 +300,11 @@ You can now test your environment. The code block below includes some PING tests 5 packets transmitted, 5 received, 0% packet loss, time 5000.718ms rtt min/avg/max/mdev = 0.788/2.968/3.838/1.105 ms - # /usr/local/scion/scion showpaths 42-ffaa:1:5 +Verify that each host has a full table of available paths to the other ASes. This can be done with the "scion showpaths" command. In the example below, we are displaying the paths between scion01 (AS 42-ffaa:1:1) to scion05 (AS 42-ffaa:1:5). There should be multiple paths through the core ASes. + +.. code-block:: + + scion01$ /usr/local/scion/scion showpaths 42-ffaa:1:5 Available paths to 42-ffaa:1:5 3 Hops: [0] Hops: [42-ffaa:1:1 2>1 42-ffaa:1:2 3>1 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 From 6cef9b0d3e4c41728bd2e59110511d2b53a04d77 Mon Sep 17 00:00:00 2001 From: Corine de Kater Date: Sun, 5 Nov 2023 10:25:33 +0100 Subject: [PATCH 28/68] update deploy guide --- doc/deploy/deployment.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index f26f4c423d..6efaf4a9e6 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -49,8 +49,7 @@ The topology of the ISD includes the inter-AS connections to neighboring ASes, a Infrastructure Prerequisites ---------------------------- -This deployment requires five virtual machines (VMs) - one for each AS. -, one per AS in our ISD/demo environment. We recommend using Ubuntu VMs for this. +This deployment requires five virtual machines (VMs) - one for each AS. We recommend using Ubuntu VMs for this. - 5 VMs - **Ubuntu** 22.04.3 LTS (Jammy Jellyfish). For more information, see `Ubuntu Jammy Jellyfish `_. These 5 virtual machines resemble the ASes shown in the setup overview above - each machine is one AS. From a6fb5739ee6eba28ba723fe4ac34cf9b1ce4e0b0 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 01:28:44 -0800 Subject: [PATCH 29/68] Create TutorialDeploymentTopology.topo --- doc/deploy/TutorialDeploymentTopology.topo | 30 ++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 doc/deploy/TutorialDeploymentTopology.topo diff --git a/doc/deploy/TutorialDeploymentTopology.topo b/doc/deploy/TutorialDeploymentTopology.topo new file mode 100644 index 0000000000..20a57cc9a1 --- /dev/null +++ b/doc/deploy/TutorialDeploymentTopology.topo @@ -0,0 +1,30 @@ +--- +ASes: + "42-ffaa:1:1": + core: true + voting: true + authoritative: true + issuing: true + "42-ffaa:1:2": + core: true + voting: true + authoritative: true + issuing: true + "42-ffaa:1:3": + core: true + voting: true + authoritative: true + issuing: true + "42-ffaa:1:4": + cert_issuer: 42-ffaa:1:1 + "42-ffaa:1:5": + cert_issuer: 42-ffaa:1:2 + +links: + - {a: "42-ffaa:1:1#1", b: "42-ffaa:1:4#1", linkAtoB: CHILD} + - {a: "42-ffaa:1:1#2", b: "42-ffaa:1:2#1", linkAtoB: CORE} + - {a: "42-ffaa:1:1#3", b: "42-ffaa:1:3#1", linkAtoB: CORE} + - {a: "42-ffaa:1:2#2", b: "42-ffaa:1:3#2", linkAtoB: CORE} + - {a: "42-ffaa:1:2#3", b: "42-ffaa:1:5#1", linkAtoB: CHILD} + - {a: "42-ffaa:1:3#3", b: "42-ffaa:1:4#2", linkAtoB: CHILD} + - {a: "42-ffaa:1:3#4", b: "42-ffaa:1:5#2", linkAtoB: CHILD} From 2f8027571811b80619e7017850ca50f230a05c55 Mon Sep 17 00:00:00 2001 From: FR4NK-W Date: Sun, 5 Nov 2023 10:33:16 +0100 Subject: [PATCH 30/68] Update requirements.txt --- doc/requirements.txt | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/requirements.txt b/doc/requirements.txt index 05ea6e77e0..651c7a8585 100644 --- 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 \ From 7f45238822136827301baaf34889c18c6d520a23 Mon Sep 17 00:00:00 2001 From: Corine de Kater Date: Sun, 5 Nov 2023 10:41:52 +0100 Subject: [PATCH 31/68] added topology file --- doc/deploy/deployment.rst | 39 +++++---------------------------------- 1 file changed, 5 insertions(+), 34 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 6efaf4a9e6..f349b7b8d4 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -136,42 +136,13 @@ You have to create one "global" topology file which describes the setup of the e The topology information is needed by Router and Control Service instances, and also by end-host applications. For more information on the topology files, see ``_ -1. First, create a "global" topology file with the name *GlobalDeploymentTopology.topo*. +1. First, create a "global" topology file with the name *TutorialDeploymentTopology.topo*. A sample topology file is listed below. Click on the file name to download it, then copy the file to your demo environment. -2. Fill this file with the following content: + - `TutorialDeploymentTopology.topo `_ - .. code-block:: +2. Save the just-created global topology file (with the name *TutorialDeploymentTopology.topo*). - ASes: - "42-ffaa:1:1": - core: true - voting: true - authoritative: true - issuing: true - "42-ffaa:1:2": - core: true - cert_issuer: 42-ffaa:1:1 - "42-ffaa:1:3": - core: true - cert_issuer: 42-ffaa:1:1 - "42-ffaa:1:4": - cert_issuer: 42-ffaa:1:1 - "42-ffaa:1:5": - cert_issuer: 42-ffaa:1:1 - - links: - - {a: "42-ffaa:1:1#1", b: "42-ffaa:1:4#1", linkAtoB: CHILD} - - {a: "42-ffaa:1:1#2", b: "42-ffaa:1:2#1", linkAtoB: CORE} - - {a: "42-ffaa:1:1#3", b: "42-ffaa:1:3#1", linkAtoB: CORE} - - {a: "42-ffaa:1:2#2", b: "42-ffaa:1:3#2", linkAtoB: CORE} - - {a: "42-ffaa:1:2#3", b: "42-ffaa:1:5#1", linkAtoB: CHILD} - - {a: "42-ffaa:1:3#3", b: "42-ffaa:1:4#2", linkAtoB: CHILD} - - {a: "42-ffaa:1:3#4", b: "42-ffaa:1:5#2", linkAtoB: CHILD} - - -3. Save the just-created global topology file (with the name *GlobalDeploymentTopology.topo*). - -4. Now you have to create a topology file per AS. Sample topology files for each AS in our sample ISD environment are listed below. Click on the file name to download it, then copy the file to the corresponding AS. +3. Now you have to create a topology file per AS. Sample topology files for each AS in our sample ISD environment are listed below. Click on the file name to download it, then copy the file to the corresponding AS. - **AS 1 (ffaa:1:1)**: `topology1.json `_ @@ -271,7 +242,7 @@ Testing the Environment You can now test your environment. The code block below includes some tests you could perform to check whether your environment works well. -Verify that each host has a SCION address. This can be verified with the "scion address" command as shown below. +Verify that each host has a SCION address. This can be verified with the "scion address" command as shown below. .. code-block:: From 91ef4456f150543f2fad66fe115d3404ea89d1cb Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 01:43:53 -0800 Subject: [PATCH 32/68] Update deployment.rst --- doc/deploy/deployment.rst | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 6efaf4a9e6..6e7dd928d0 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -51,7 +51,12 @@ Infrastructure Prerequisites This deployment requires five virtual machines (VMs) - one for each AS. We recommend using Ubuntu VMs for this. -- 5 VMs - **Ubuntu** 22.04.3 LTS (Jammy Jellyfish). For more information, see `Ubuntu Jammy Jellyfish `_. These 5 virtual machines resemble the ASes shown in the setup overview above - each machine is one AS. +- 5 VMs - **Ubuntu** 22.04.3 LTS (Jammy Jellyfish). For more information, see `Ubuntu Jammy Jellyfish `_. +- Each VM should have at least one IP address reachable by the other VMs. (If on AWS, be sure to setup the appropriate security groups.) +- Each VM will need internet access to download the required files (or you will need an alternate way to download the SCION binaries). +- One VM (scion01) should have SSH access to copy generated SCION keys to the other hosts scion{02-05}. +- Using the naming convention for each VM of scion01, scion02, scion03, scion04, and scion05 will help follow along with this tutorial. +- The VM names scion01-scion05 can be configured in /etc/hosts. .. note:: @@ -70,6 +75,20 @@ To create the sample ISD environment, you need to perform the following tasks, i The following sections explain the required tasks, one section per task. +.. _step0: + +OS Setup +........ + +The host file (/etc/hosts) will need to be updated with the IP addresses of 5 VMs. This will need to be updated on scion01-scion05. Replace the IP addresses with the assigned IP addresses for the VMs deployed. + +.. code-block:: +10.0.1.1 scion01 +10.0.1.2 scion02 +10.0.1.3 scion03 +10.0.1.4 scion04 +10.0.1.5 scion05 + .. _step1: From 748a849312d89c1f57a9842986939e75cc54c25c Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 01:45:49 -0800 Subject: [PATCH 33/68] Update deployment.rst --- doc/deploy/deployment.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 3784366152..04a3fc2a73 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -83,13 +83,13 @@ OS Setup The host file (/etc/hosts) will need to be updated with the IP addresses of 5 VMs. This will need to be updated on scion01-scion05. Replace the IP addresses with the assigned IP addresses for the VMs deployed. .. code-block:: + 10.0.1.1 scion01 10.0.1.2 scion02 10.0.1.3 scion03 10.0.1.4 scion04 10.0.1.5 scion05 - .. _step1: Installation From 26dcc9d2a54861481c4f4e070ca21c5aff40e0a3 Mon Sep 17 00:00:00 2001 From: Corine de Kater Date: Sun, 5 Nov 2023 10:50:15 +0100 Subject: [PATCH 34/68] correction --- doc/deploy/deployment.rst | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 04a3fc2a73..71a91238db 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -69,26 +69,29 @@ Tasks to Perform To create the sample ISD environment, you need to perform the following tasks, in this order: -- Task 1: Installation (:ref:`step1`) -- Task 2: Configuration (:ref:`step2`) -- Task 3: Testing your environment (:ref:`step3`) +- Task 1: OS setup (:ref:`step0`) +- Task 2: Installation (:ref:`step1`) +- Task 3: Configuration (:ref:`step2`) +- Task 4: Testing your environment (:ref:`step3`) The following sections explain the required tasks, one section per task. + .. _step0: OS Setup ........ -The host file (/etc/hosts) will need to be updated with the IP addresses of 5 VMs. This will need to be updated on scion01-scion05. Replace the IP addresses with the assigned IP addresses for the VMs deployed. +The host file (*/etc/hosts*) will need to be updated with the IP addresses of 5 VMs. This will need to be updated on scion01-scion05. Replace the IP addresses with the assigned IP addresses for the VMs deployed. .. code-block:: -10.0.1.1 scion01 -10.0.1.2 scion02 -10.0.1.3 scion03 -10.0.1.4 scion04 -10.0.1.5 scion05 + 10.0.1.1 scion01 + 10.0.1.2 scion02 + 10.0.1.3 scion03 + 10.0.1.4 scion04 + 10.0.1.5 scion05 + .. _step1: From 08e4d9b95b3916fbae60ee58040b3412f9714410 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 01:56:44 -0800 Subject: [PATCH 35/68] software download --- doc/deploy/deployment.rst | 33 ++++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 04a3fc2a73..88b1c579af 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -85,35 +85,42 @@ The host file (/etc/hosts) will need to be updated with the IP addresses of 5 VM .. code-block:: 10.0.1.1 scion01 + 10.0.1.2 scion02 + 10.0.1.3 scion03 + 10.0.1.4 scion04 + 10.0.1.5 scion05 + .. _step1: -Installation -............ +Software Selection, Download, and Installation +.............................................. -This section guides you through the installation of the SCION software. -Here is where you can get the software: +This section guides you through the download and installation of the SCION software. -- Install from packages (coming later in 2024). -- Install from binaries. The latest software can be found at: +Software Selection +~~~~~~~~~~~~~~~~~~ - - `Latest official release `_ - - `Latest nightly build `_ +The SCION software is available as a nightly and official release TAR file. We recommend selecting an official release. +- `Latest official release `_ +- `Latest nightly build `_ -In this example, we install software with the following release version: -*scion_v0.9.1_amd64_linux.tar.gz* +In this example, we install software with the following release version: *scion_v0.9.1_amd64_linux.tar.gz* Note that we have to install the software five times: Once per virtual machine we created previously. Proceed as described in the following sections. +Installation from packages is under development (available 2024). Downloading and Installing the SCION Software ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +With the software selected (from above), it will need to be downloaded and installed on each of the VMs scion01-scion05. + To download the software and install it on your virtual machines, execute the following commands in your shell/terminal: .. note:: @@ -125,15 +132,11 @@ To download the software and install it on your virtual machines, execute the fo sudo -i - cd /tmp - wget https://github.com/scionproto/scion/releases/download/v0.9.1/scion_v0.9.1_amd64_linux.tar.gz mkdir /usr/local/scion - cd /usr/local/scion - - tar xfz /tmp/scion_v0.9.1_amd64_linux.tar.gz + tar xfz /tmp/scion_v0.9.1_amd64_linux.tar.gz -C /usr/local/scion As each virtual machine represents an AS in your demo environment, we will now refer to the VMs as ASes. From 622c1241afcededefee22f5b5c971a713c545501 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 02:20:47 -0800 Subject: [PATCH 36/68] Update deployment.rst --- doc/deploy/deployment.rst | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index a37d4b8e0b..c3530e3707 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -191,6 +191,25 @@ The next step is to generate all required certificates by using the global topol 2. Now you have to distribute the just-generated keys to the AS routers. Proceed as follows: + - Create the required directories. + +Repeat these commands on scion01-scion05. + + .. code-block:: + + mkdir -p /etc/scion/certs + mkdir -p /etc/scion/crypto/as + mkdir -p /etc/scion/keys + + - Generate the MAC secret keys + +Two symmetric keys *master0.key* and *master1.key* are required per AS as the forwarding secret keys. These symmetric keys are used by the AS in the data plane to verify the MACs in the hop fields of a SCION path (header). + + .. code-block:: + + dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master0.key + dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master1.key + - Copy the *gen/* directory with its content to each of the five AS routers. **TODO** - For each AS, execute the commands in the following code block. Pay attention to the following: @@ -199,14 +218,14 @@ The next step is to generate all required certificates by using the global topol .. code-block:: - mkdir -p /etc/scion/keys - dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master0.key - dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master1.key mkdir /etc/scion/certs cp gen/trcs/* /etc/scion/certs mkdir -p /etc/scion/crypto/as cp ./gen/ASffaa_1_1/crypto/as/* /etc/scion/crypto/as/ + .. code-block:: + + .. note:: From 888b97f144769fd9a844eee1c4569118d7869c93 Mon Sep 17 00:00:00 2001 From: Nicola Rustignoli Date: Sun, 5 Nov 2023 11:38:56 +0100 Subject: [PATCH 37/68] added copying files around --- doc/deploy/deployment.rst | 59 +++++++++++++++++++++++++++------------ 1 file changed, 41 insertions(+), 18 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index c3530e3707..a6dd435878 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -156,13 +156,15 @@ You have to create one "global" topology file which describes the setup of the e The topology information is needed by Router and Control Service instances, and also by end-host applications. For more information on the topology files, see ``_ -1. First, create a "global" topology file with the name *TutorialDeploymentTopology.topo*. A sample topology file is listed below. Click on the file name to download it, then copy the file to your demo environment. - - - `TutorialDeploymentTopology.topo `_ +1. First, download a "global" topology file. This contains a concise representation of the topology drawn above. A sample topology file is available here: `TutorialDeploymentTopology.topo `_ . Download the file to one the hosts of your demo environment (e.g. scion01). + +.. code-block:: + + cd /tmp + wget https://github.com/cdekater/scion/raw/ietf118-hackathon/doc/deploy/TutorialDeploymentTopology.topo -2. Save the just-created global topology file (with the name *TutorialDeploymentTopology.topo*). -3. Now you have to create a topology file per AS. Sample topology files for each AS in our sample ISD environment are listed below. Click on the file name to download it, then copy the file to the corresponding AS. +1. Now you have to create a topology file per AS. Sample topology files for each AS in our sample ISD environment are listed below. Click on the file name to download it, then copy the file to the corresponding AS. - **AS 1 (ffaa:1:1)**: `topology1.json `_ @@ -174,6 +176,12 @@ The topology information is needed by Router and Control Service instances, and - **AS 5 (ffaa:1:5)**: `topology5.json `_ + Replace IP addressed from this guide with the IPs of your machines: + + .. code-block:: + + sed -i 's/XXXX/XXXX/g' /etc/scion/topology.json + Step 2 - Generate All Required Certificates @@ -181,15 +189,15 @@ Step 2 - Generate All Required Certificates The next step is to generate all required certificates by using the global topology file. Proceed as follows: -1. To generate all required certificates using the global topology file, execute the following command: +1. To generate all required certificates using the global topology file, execute the following command on the machine where you downloaded the global topology: .. code-block:: - /usr/local/scion/scion-pki testcrypto -t GlobalDeploymentTopology.topo + /usr/local/scion/scion-pki testcrypto -t TutorialDeploymentTopology.topo - This will generate all the required keys in the *gen/* directory. + This will generate all the required keys in the *gen/* directory for all the SCION ASes in all topology. -2. Now you have to distribute the just-generated keys to the AS routers. Proceed as follows: +2. Now you have to copy the just-generated keys to the respective AS routers. Proceed as follows: - Create the required directories. @@ -210,18 +218,33 @@ Two symmetric keys *master0.key* and *master1.key* are required per AS as the fo dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master0.key dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master1.key - - Copy the *gen/* directory with its content to each of the five AS routers. **TODO** - - For each AS, execute the commands in the following code block. Pay attention to the following: - - All lines except for the last line are the same for each AS. - - The part *ASffaa_1_1* in the last line needs to be adapted per AS, so that it contains the correct AS number for the corresponding AS. + - Copy the content of *gen/ASffaa_1_X/* to */etc/scion/* on each of the five AS routers + On the machine where you generated the material + - The part *ASffaa_1_X in the last line needs to be adapted per AS, so that it contains the correct AS number for the corresponding AS. + + .. code-block:: + + mkdir /etc/scion + mkdir /etc/scion/certs + cp -r gen/ASffaa_1_1/ /etc/scion/ + Copy from machine 1 to all other machine the respective certs + + .. code-block:: + + scp -r scion1:/tmp/gen . + scp -r gen/ASffaa_1_X/crypto scion1:/etc/scion/ + scp -r gen/trcs scionX:/etc/scion/certs + + - For each AS, create the AS secret + .. code-block:: - mkdir /etc/scion/certs - cp gen/trcs/* /etc/scion/certs - mkdir -p /etc/scion/crypto/as - cp ./gen/ASffaa_1_1/crypto/as/* /etc/scion/crypto/as/ + mkdir -p /etc/scion/keys + + dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master0.key + dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master1.key .. code-block:: @@ -229,7 +252,7 @@ Two symmetric keys *master0.key* and *master1.key* are required per AS as the fo .. note:: - The above script will distribute the SCION control-plane PKI keys/certificates to the ASes. Additionally, it will create the two symmetric keys *master0.key* and *master1.key* per AS, and store them in the AS's */etc/scion/keys/* directory. The symmetric key is used by the AS in the date plane to verify the MACs in the hop fields of a SCION path (header). + The command above generates two symmetric keys *master0.key* and *master1.key* per AS, and store them in the AS's */etc/scion/keys/* directory. The symmetric key is used by the AS in the date plane to verify the MACs in the hop fields of a SCION path (header). Step 3 - Create the Directories For the Support Database Files From 5e0dc0d5243a0c95a50d9f9305a05ece6148673a Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 02:40:36 -0800 Subject: [PATCH 38/68] Update deployment.rst --- doc/deploy/deployment.rst | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index a6dd435878..9885156ec1 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -237,23 +237,6 @@ Two symmetric keys *master0.key* and *master1.key* are required per AS as the fo scp -r gen/ASffaa_1_X/crypto scion1:/etc/scion/ scp -r gen/trcs scionX:/etc/scion/certs - - For each AS, create the AS secret - - .. code-block:: - - mkdir -p /etc/scion/keys - - dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master0.key - dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master1.key - - .. code-block:: - - - - .. note:: - - The command above generates two symmetric keys *master0.key* and *master1.key* per AS, and store them in the AS's */etc/scion/keys/* directory. The symmetric key is used by the AS in the date plane to verify the MACs in the hop fields of a SCION path (header). - Step 3 - Create the Directories For the Support Database Files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From e55e89799dc9cc155757e618a454f468e9e5aa48 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 02:50:40 -0800 Subject: [PATCH 39/68] Update deployment.rst --- doc/deploy/deployment.rst | 59 +++++++++++++++++++-------------------- 1 file changed, 29 insertions(+), 30 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 9885156ec1..29db64acbb 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -147,22 +147,8 @@ Configuration To configure your demo SCION environment, perform the following steps. - -Step 1 - Configure the Topology (Files) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -First, you have to configure the topology files for your demo environment. -You have to create one "global" topology file which describes the setup of the entire ISD environment, as well as one specific AS topology file per AS in your demo ISD. The topology file of an AS specifies all the inter-AS connections to neighboring ASes, and defines the underlay IP/UDP addresses of services and routers running in this AS. This implies that the topology file will be different for each AS in your demo environment. - -The topology information is needed by Router and Control Service instances, and also by end-host applications. For more information on the topology files, see ``_ - -1. First, download a "global" topology file. This contains a concise representation of the topology drawn above. A sample topology file is available here: `TutorialDeploymentTopology.topo `_ . Download the file to one the hosts of your demo environment (e.g. scion01). - -.. code-block:: - - cd /tmp - wget https://github.com/cdekater/scion/raw/ietf118-hackathon/doc/deploy/TutorialDeploymentTopology.topo - +Step 2 - Download AS Specific Topology Files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. Now you have to create a topology file per AS. Sample topology files for each AS in our sample ISD environment are listed below. Click on the file name to download it, then copy the file to the corresponding AS. @@ -183,13 +169,24 @@ The topology information is needed by Router and Control Service instances, and sed -i 's/XXXX/XXXX/g' /etc/scion/topology.json - -Step 2 - Generate All Required Certificates +Step 2 - Generate the Required Certificates ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +For this tutorial deployment, a sample topology file has been provided. As part of this tutorial deployment, this file will be processed to generated the required crypto graphics keys. + +This topology file wdescribes the setup of the entire ISD environment including all 5 ASes and the associated network links between the ASes. The topology file of an AS specifies all the inter-AS connections to neighboring ASes, and defines the underlay IP/UDP addresses of services and routers running in this AS. + +The topology information is needed by Router and Control Service instances, and also by end-host applications. For more information on the topology files, see ``_ + +1. First, download the provided tutorial deployment topology file. This contains a concise representation of the topology drawn above. This topology file is available at: `TutorialDeploymentTopology.topo `_ . Download the file to the scion01 VM. + +.. code-block:: + + wget https://github.com/cdekater/scion/raw/ietf118-hackathon/doc/deploy/TutorialDeploymentTopology.topo + The next step is to generate all required certificates by using the global topology file. Proceed as follows: -1. To generate all required certificates using the global topology file, execute the following command on the machine where you downloaded the global topology: +2. To generate all required certificates using the global topology file, execute the following command on the machine where you downloaded the global topology: .. code-block:: @@ -197,7 +194,7 @@ The next step is to generate all required certificates by using the global topol This will generate all the required keys in the *gen/* directory for all the SCION ASes in all topology. -2. Now you have to copy the just-generated keys to the respective AS routers. Proceed as follows: +3. Now you have to copy the just-generated keys to the respective AS routers. Proceed as follows: - Create the required directories. @@ -209,14 +206,7 @@ Repeat these commands on scion01-scion05. mkdir -p /etc/scion/crypto/as mkdir -p /etc/scion/keys - - Generate the MAC secret keys -Two symmetric keys *master0.key* and *master1.key* are required per AS as the forwarding secret keys. These symmetric keys are used by the AS in the data plane to verify the MACs in the hop fields of a SCION path (header). - - .. code-block:: - - dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master0.key - dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master1.key - Copy the content of *gen/ASffaa_1_X/* to */etc/scion/* on each of the five AS routers @@ -237,8 +227,17 @@ Two symmetric keys *master0.key* and *master1.key* are required per AS as the fo scp -r gen/ASffaa_1_X/crypto scion1:/etc/scion/ scp -r gen/trcs scionX:/etc/scion/certs +Step 3 - Generate Forwarding Secret Keys +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Two symmetric keys *master0.key* and *master1.key* are required per AS as the forwarding secret keys. These symmetric keys are used by the AS in the data plane to verify the MACs in the hop fields of a SCION path (header). + + .. code-block:: + + dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master0.key + dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master1.key -Step 3 - Create the Directories For the Support Database Files +Step 4 - Create the Directories For the Support Database Files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To create the required directories for the support database files, execute the following command. Do this once per each AS. @@ -248,7 +247,7 @@ To create the required directories for the support database files, execute the f mkdir /var/lib/scion -Step 4 - Create the Configuration Files +Step 5 - Create the Configuration Files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Next, you have to create ("copy over") a couple of configuration files in the */etc/scion/* directory of each AS. @@ -265,7 +264,7 @@ The files including their names are listed below. Click on the corresponding lin -Step 5 - Start the Services +Step 6 - Start the Services ~~~~~~~~~~~~~~~~~~~~~~~~~~~ As a last step, you have to start the services on each of the five ASes. Execute the following commands on every AS: From 32302aba97ace8bbca594b32ccea7afb7b69c529 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 02:52:56 -0800 Subject: [PATCH 40/68] Update deployment.rst --- doc/deploy/deployment.rst | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 29db64acbb..1378787ccc 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -58,12 +58,6 @@ This deployment requires five virtual machines (VMs) - one for each AS. We recom - Using the naming convention for each VM of scion01, scion02, scion03, scion04, and scion05 will help follow along with this tutorial. - The VM names scion01-scion05 can be configured in /etc/hosts. -.. note:: - - It is useful to give each VM a name that fits/suits the setup of your demo environment. - - - Tasks to Perform ---------------- @@ -77,7 +71,7 @@ To create the sample ISD environment, you need to perform the following tasks, i The following sections explain the required tasks, one section per task. -.. _step0: +.. _step1: OS Setup ........ @@ -93,7 +87,7 @@ The host file (*/etc/hosts*) will need to be updated with the IP addresses of 5 10.0.1.5 scion05 -.. _step1: +.. _step2: Software Selection, Download, and Installation .............................................. @@ -140,7 +134,7 @@ To download the software and install it on your virtual machines, execute the fo As each virtual machine represents an AS in your demo environment, we will now refer to the VMs as ASes. -.. _step2: +.. _step3: Configuration ............. @@ -279,7 +273,7 @@ As a last step, you have to start the services on each of the five ASes. Execute -.. _step3: +.. _step4: Testing the Environment ....................... From e69bf79641583cfc935137825f63cb1fe8c3cb04 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 02:58:01 -0800 Subject: [PATCH 41/68] topology AS specific files --- doc/deploy/deployment.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 1378787ccc..7df293741e 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -144,17 +144,18 @@ To configure your demo SCION environment, perform the following steps. Step 2 - Download AS Specific Topology Files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -1. Now you have to create a topology file per AS. Sample topology files for each AS in our sample ISD environment are listed below. Click on the file name to download it, then copy the file to the corresponding AS. +1. For this tutorial, we have provided the AS specific topology files - one per each AS. These files have been generated from the master AS toplogy file for this tutorial deployment for simplicty. +Now you have to create a topology file per AS. Sample topology files for each AS in our sample ISD environment are listed below. Click on the file name to download it, then copy the file to the corresponding AS. - - **AS 1 (ffaa:1:1)**: `topology1.json `_ + - **AS 1 (ffaa:1:1)**: `topology-42-ffaa:1:1.json `_ - - **AS 2 (ffaa:1:2)**: `topology2.json `_ + - **AS 2 (ffaa:1:2)**: `topology-42-ffaa:1:2.json `_ - - **AS 3 (ffaa:1:3)**: `topology3.json `_ + - **AS 3 (ffaa:1:3)**: `topology-42-ffaa:1:3.json `_ - - **AS 4 (ffaa:1:4)**: `topology4.json `_ + - **AS 4 (ffaa:1:4)**: `topology-42-ffaa:1:4.json `_ - - **AS 5 (ffaa:1:5)**: `topology5.json `_ + - **AS 5 (ffaa:1:5)**: `topology-42-ffaa:1:5.json `_ Replace IP addressed from this guide with the IPs of your machines: From 779b7b7dc417f14a45cf8799004c3bd8739f0d00 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 02:59:32 -0800 Subject: [PATCH 42/68] Update deployment.rst --- doc/deploy/deployment.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 7df293741e..814250ddfe 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -147,15 +147,15 @@ Step 2 - Download AS Specific Topology Files 1. For this tutorial, we have provided the AS specific topology files - one per each AS. These files have been generated from the master AS toplogy file for this tutorial deployment for simplicty. Now you have to create a topology file per AS. Sample topology files for each AS in our sample ISD environment are listed below. Click on the file name to download it, then copy the file to the corresponding AS. - - **AS 1 (ffaa:1:1)**: `topology-42-ffaa:1:1.json `_ + - **AS 1 (ffaa:1:1)**: `topology-42-ffaa:1:1.json `_ - - **AS 2 (ffaa:1:2)**: `topology-42-ffaa:1:2.json `_ + - **AS 2 (ffaa:1:2)**: `topology-42-ffaa:1:2.json `_ - - **AS 3 (ffaa:1:3)**: `topology-42-ffaa:1:3.json `_ + - **AS 3 (ffaa:1:3)**: `topology-42-ffaa:1:3.json `_ - - **AS 4 (ffaa:1:4)**: `topology-42-ffaa:1:4.json `_ + - **AS 4 (ffaa:1:4)**: `topology-42-ffaa:1:4.json `_ - - **AS 5 (ffaa:1:5)**: `topology-42-ffaa:1:5.json `_ + - **AS 5 (ffaa:1:5)**: `topology-42-ffaa:1:5.json `_ Replace IP addressed from this guide with the IPs of your machines: From 942e169c979ce8f60d3303e0f08837165748d91a Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 03:13:50 -0800 Subject: [PATCH 43/68] Update deployment.rst --- doc/deploy/deployment.rst | 56 ++++++++++++++++++++++++--------------- 1 file changed, 35 insertions(+), 21 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 814250ddfe..aa33a2363a 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -76,8 +76,12 @@ The following sections explain the required tasks, one section per task. OS Setup ........ + - Setup the Host file + The host file (*/etc/hosts*) will need to be updated with the IP addresses of 5 VMs. This will need to be updated on scion01-scion05. Replace the IP addresses with the assigned IP addresses for the VMs deployed. +Set this up on scion01-scion05. + .. code-block:: 10.0.1.1 scion01 @@ -86,6 +90,19 @@ The host file (*/etc/hosts*) will need to be updated with the IP addresses of 5 10.0.1.4 scion04 10.0.1.5 scion05 + - Create required directories. + +These directories are required to store the certificates, keys, and database files. + +Repeat these commands on scion01-scion05. + + .. code-block:: + + mkdir -p /etc/scion/certs + mkdir -p /etc/scion/crypto/as + mkdir -p /etc/scion/keys + mkdir -p /var/lib/scion + .. _step2: @@ -159,9 +176,24 @@ Now you have to create a topology file per AS. Sample topology files for each AS Replace IP addressed from this guide with the IPs of your machines: - .. code-block:: +.. code-block:: + + wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/topology1.json + wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/topology2.json + wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/topology3.json + wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/topology4.json + wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/topology5.json + +.. code-block:: + + sed -i 's/10.0.0.1/YOUR_SCION01_IP/g' /etc/scion/topology1.json + sed -i 's/10.0.0.2/YOUR_SCION02_IP/g' /etc/scion/topology2.json + sed -i 's/10.0.0.3/YOUR_SCION03_IP/g' /etc/scion/topology3.json + sed -i 's/10.0.0.4/YOUR_SCION04_IP/g' /etc/scion/topology4.json + sed -i 's/10.0.0.5/YOUR_SCION05_IP/g' /etc/scion/topology5.json + +.. code-block:: - sed -i 's/XXXX/XXXX/g' /etc/scion/topology.json Step 2 - Generate the Required Certificates @@ -191,15 +223,7 @@ The next step is to generate all required certificates by using the global topol 3. Now you have to copy the just-generated keys to the respective AS routers. Proceed as follows: - - Create the required directories. -Repeat these commands on scion01-scion05. - - .. code-block:: - - mkdir -p /etc/scion/certs - mkdir -p /etc/scion/crypto/as - mkdir -p /etc/scion/keys @@ -232,17 +256,8 @@ Two symmetric keys *master0.key* and *master1.key* are required per AS as the fo dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master0.key dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master1.key -Step 4 - Create the Directories For the Support Database Files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To create the required directories for the support database files, execute the following command. Do this once per each AS. - -.. code-block:: - - mkdir /var/lib/scion - -Step 5 - Create the Configuration Files +Step 4 - Create the Configuration Files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Next, you have to create ("copy over") a couple of configuration files in the */etc/scion/* directory of each AS. @@ -266,7 +281,6 @@ As a last step, you have to start the services on each of the five ASes. Execute .. code-block:: - screen -dmS BR /usr/local/scion/router --config /etc/scion/br.toml screen -dmS BorderRouter /usr/local/scion/router --config /etc/scion/br.toml screen -dmS Dispatcher /usr/local/scion/dispatcher --config /etc/scion/dispatcher.toml screen -dmS Control /usr/local/scion/control --config /etc/scion/cs.toml From 776466624c4a111853104464284233a486ecafe0 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 03:21:38 -0800 Subject: [PATCH 44/68] standardized on 10 IPs --- doc/deploy/topology1.json | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/deploy/topology1.json b/doc/deploy/topology1.json index 8b06984c34..6d7ff0c2ae 100644 --- a/doc/deploy/topology1.json +++ b/doc/deploy/topology1.json @@ -20,8 +20,8 @@ "interfaces": { "1": { "underlay": { - "public": "147.28.184.149:50014", - "remote": "147.28.184.147:50014" + "public": "10.0.0.1:50014", + "remote": "10.0.0.4:50014" }, "isd_as": "42-ffaa:1:4", "link_to": "child", @@ -29,8 +29,8 @@ }, "2": { "underlay": { - "public": "147.28.184.149:50012", - "remote": "147.28.184.150:50012" + "public": "10.0.0.1:50012", + "remote": "10.0.0.2:50012" }, "isd_as": "42-ffaa:1:2", "link_to": "core", @@ -38,8 +38,8 @@ }, "3": { "underlay": { - "public": "147.28.184.149:50013", - "remote": "147.28.184.146:50013" + "public": "10.0.0.1:50013", + "remote": "10.0.0.3:50013" }, "isd_as": "42-ffaa:1:3", "link_to": "core", From 9463d7ada97332cb808a10c77928d6b09772f563 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 03:23:29 -0800 Subject: [PATCH 45/68] private IPs --- doc/deploy/topology2.json | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/deploy/topology2.json b/doc/deploy/topology2.json index 2725d6ddbd..28ad633a0f 100644 --- a/doc/deploy/topology2.json +++ b/doc/deploy/topology2.json @@ -20,8 +20,8 @@ "interfaces": { "1": { "underlay": { - "public": "147.28.184.150:50012", - "remote": "147.28.184.149:50012" + "public": "10.0.0.2:50012", + "remote": "10.0.0.1:50012" }, "isd_as": "42-ffaa:1:1", "link_to": "core", @@ -29,8 +29,8 @@ }, "2": { "underlay": { - "public": "147.28.184.150:50023", - "remote": "147.28.184.146:50023" + "public": "10.0.0.2:50023", + "remote": "10.0.0.3:50023" }, "isd_as": "42-ffaa:1:3", "link_to": "core", @@ -38,8 +38,8 @@ }, "3": { "underlay": { - "public": "147.28.184.150:50025", - "remote": "147.28.184.148:50025" + "public": "10.0.0.2:50025", + "remote": "10.0.0.5:50025" }, "isd_as": "42-ffaa:1:5", "link_to": "child", From ee9af3e8dc2828c4cd81d8a6f637b31bc931e88b Mon Sep 17 00:00:00 2001 From: Corine de Kater Date: Sun, 5 Nov 2023 12:24:15 +0100 Subject: [PATCH 46/68] fixed some typos --- doc/deploy/deployment.rst | 32 ++++++++++++++------------------ 1 file changed, 14 insertions(+), 18 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index aa33a2363a..30c780e814 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -52,7 +52,7 @@ Infrastructure Prerequisites This deployment requires five virtual machines (VMs) - one for each AS. We recommend using Ubuntu VMs for this. - 5 VMs - **Ubuntu** 22.04.3 LTS (Jammy Jellyfish). For more information, see `Ubuntu Jammy Jellyfish `_. -- Each VM should have at least one IP address reachable by the other VMs. (If on AWS, be sure to setup the appropriate security groups.) +- Each VM should have at least one IP address reachable by the other VMs. (If on AWS, be sure to set up the appropriate security groups.) - Each VM will need internet access to download the required files (or you will need an alternate way to download the SCION binaries). - One VM (scion01) should have SSH access to copy generated SCION keys to the other hosts scion{02-05}. - Using the naming convention for each VM of scion01, scion02, scion03, scion04, and scion05 will help follow along with this tutorial. @@ -76,7 +76,7 @@ The following sections explain the required tasks, one section per task. OS Setup ........ - - Setup the Host file + - Set up the host file The host file (*/etc/hosts*) will need to be updated with the IP addresses of 5 VMs. This will need to be updated on scion01-scion05. Replace the IP addresses with the assigned IP addresses for the VMs deployed. @@ -128,7 +128,7 @@ Installation from packages is under development (available 2024). Downloading and Installing the SCION Software ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -With the software selected (from above), it will need to be downloaded and installed on each of the VMs scion01-scion05. +With the software selected (from above), it will need to be downloaded and installed on each of the VMs scion01-scion05. To download the software and install it on your virtual machines, execute the following commands in your shell/terminal: @@ -161,7 +161,7 @@ To configure your demo SCION environment, perform the following steps. Step 2 - Download AS Specific Topology Files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -1. For this tutorial, we have provided the AS specific topology files - one per each AS. These files have been generated from the master AS toplogy file for this tutorial deployment for simplicty. +1. For this tutorial, we have provided the AS specific topology files - one per each AS. These files have been generated from the master AS topology file for this tutorial deployment for simplicity. Now you have to create a topology file per AS. Sample topology files for each AS in our sample ISD environment are listed below. Click on the file name to download it, then copy the file to the corresponding AS. - **AS 1 (ffaa:1:1)**: `topology-42-ffaa:1:1.json `_ @@ -174,7 +174,7 @@ Now you have to create a topology file per AS. Sample topology files for each AS - **AS 5 (ffaa:1:5)**: `topology-42-ffaa:1:5.json `_ - Replace IP addressed from this guide with the IPs of your machines: + Replace IP addressed from this guide with the IPs of your machines: .. code-block:: @@ -199,16 +199,16 @@ Now you have to create a topology file per AS. Sample topology files for each AS Step 2 - Generate the Required Certificates ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For this tutorial deployment, a sample topology file has been provided. As part of this tutorial deployment, this file will be processed to generated the required crypto graphics keys. +For this tutorial deployment, a sample topology file has been provided. As part of this tutorial deployment, this file will be processed to generate the required crypto graphics keys. -This topology file wdescribes the setup of the entire ISD environment including all 5 ASes and the associated network links between the ASes. The topology file of an AS specifies all the inter-AS connections to neighboring ASes, and defines the underlay IP/UDP addresses of services and routers running in this AS. +This topology file describes the setup of the entire ISD environment including all 5 ASes and the associated network links between the ASes. The topology file of an AS specifies all the inter-AS connections to neighboring ASes, and defines the underlay IP/UDP addresses of services and routers running in this AS. The topology information is needed by Router and Control Service instances, and also by end-host applications. For more information on the topology files, see ``_ -1. First, download the provided tutorial deployment topology file. This contains a concise representation of the topology drawn above. This topology file is available at: `TutorialDeploymentTopology.topo `_ . Download the file to the scion01 VM. - +1. First, download the provided tutorial deployment topology file. This contains a concise representation of the topology drawn above. This topology file is available at: `TutorialDeploymentTopology.topo `_ . Download the file to the scion01 VM. + .. code-block:: - + wget https://github.com/cdekater/scion/raw/ietf118-hackathon/doc/deploy/TutorialDeploymentTopology.topo The next step is to generate all required certificates by using the global topology file. Proceed as follows: @@ -223,14 +223,9 @@ The next step is to generate all required certificates by using the global topol 3. Now you have to copy the just-generated keys to the respective AS routers. Proceed as follows: - - - - - - - Copy the content of *gen/ASffaa_1_X/* to */etc/scion/* on each of the five AS routers + - Copy the content of *gen/ASffaa_1_X/* to */etc/scion/* on each of the five AS routers On the machine where you generated the material - - The part *ASffaa_1_X in the last line needs to be adapted per AS, so that it contains the correct AS number for the corresponding AS. + - The part *ASffaa_1_X* in the last line needs to be adapted per AS, so that it contains the correct AS number for the corresponding AS. .. code-block:: @@ -238,7 +233,7 @@ The next step is to generate all required certificates by using the global topol mkdir /etc/scion/certs cp -r gen/ASffaa_1_1/ /etc/scion/ - Copy from machine 1 to all other machine the respective certs + Copy from machine 1 to all other machines the respective certs .. code-block:: @@ -246,6 +241,7 @@ The next step is to generate all required certificates by using the global topol scp -r gen/ASffaa_1_X/crypto scion1:/etc/scion/ scp -r gen/trcs scionX:/etc/scion/certs + Step 3 - Generate Forwarding Secret Keys ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 55ee091ebc6dd295684fee5af545155bb7dfb950 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 03:26:52 -0800 Subject: [PATCH 47/68] private 10 IPs --- doc/deploy/topology3.json | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/deploy/topology3.json b/doc/deploy/topology3.json index 5473c0b597..1063a9730f 100644 --- a/doc/deploy/topology3.json +++ b/doc/deploy/topology3.json @@ -20,8 +20,8 @@ "interfaces": { "1": { "underlay": { - "public": "147.28.184.146:50013", - "remote": "147.28.184.149:50013" + "public": "10.0.0.3:50013", + "remote": "10.0.0.1:50013" }, "isd_as": "42-ffaa:1:1", "link_to": "core", @@ -29,8 +29,8 @@ }, "2": { "underlay": { - "public": "147.28.184.146:50023", - "remote": "147.28.184.150:50023" + "public": "10.0.0.3:50023", + "remote": "10.0.0.2:50023" }, "isd_as": "42-ffaa:1:2", "link_to": "core", @@ -38,8 +38,8 @@ }, "3": { "underlay": { - "public": "147.28.184.146:50034", - "remote": "147.28.184.147:50034" + "public": "10.0.0.3:50034", + "remote": "10.0.0.4:50034" }, "isd_as": "42-ffaa:1:4", "link_to": "child", @@ -47,8 +47,8 @@ }, "4": { "underlay": { - "public": "147.28.184.146:50035", - "remote": "147.28.184.148:50035" + "public": "10.0.0.3:50035", + "remote": "10.0.0.5:50035" }, "isd_as": "42-ffaa:1:5", "link_to": "child", From 212c1428524fee7994407b1cf73b66375a4bcf0c Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 03:27:50 -0800 Subject: [PATCH 48/68] private 10 IPs --- doc/deploy/topology4.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/deploy/topology4.json b/doc/deploy/topology4.json index 7dfaee7efa..72552f1387 100644 --- a/doc/deploy/topology4.json +++ b/doc/deploy/topology4.json @@ -18,8 +18,8 @@ "interfaces": { "1": { "underlay": { - "public": "147.28.184.147:50014", - "remote": "147.28.184.149:50014" + "public": "10.0.0.4:50014", + "remote": "10.0.0.1:50014" }, "isd_as": "42-ffaa:1:1", "link_to": "parent", @@ -27,8 +27,8 @@ }, "2": { "underlay": { - "public": "147.28.184.147:50034", - "remote": "147.28.184.146:50034" + "public": "10.0.0.4:50034", + "remote": "10.0.0.3:50034" }, "isd_as": "42-ffaa:1:3", "link_to": "parent", From 5c1b6187e5db5a33adc3e4a0f933bad7223192dc Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 03:28:55 -0800 Subject: [PATCH 49/68] private 10 IPs --- doc/deploy/topology5.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/deploy/topology5.json b/doc/deploy/topology5.json index 19dd58cc5a..222b04964e 100644 --- a/doc/deploy/topology5.json +++ b/doc/deploy/topology5.json @@ -18,8 +18,8 @@ "interfaces": { "1": { "underlay": { - "public": "147.28.184.148:50025", - "remote": "147.28.184.150:50025" + "public": "10.0.0.5:50025", + "remote": "10.0.0.2:50025" }, "isd_as": "42-ffaa:1:2", "link_to": "parent", @@ -27,8 +27,8 @@ }, "2": { "underlay": { - "public": "147.28.184.148:50035", - "remote": "147.28.184.146:50035" + "public": "10.0.0.5:50035", + "remote": "10.0.0.3:50035" }, "isd_as": "42-ffaa:1:3", "link_to": "parent", From 620b669b85fd928397b9d05f589c124d6faf73b4 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 03:29:30 -0800 Subject: [PATCH 50/68] correct dir --- doc/deploy/sd.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/deploy/sd.toml b/doc/deploy/sd.toml index 913cfcbc24..aac173aaf4 100644 --- a/doc/deploy/sd.toml +++ b/doc/deploy/sd.toml @@ -7,7 +7,7 @@ config_dir = "/etc/scion" reconnect_to_dispatcher = true [trust_db] -connection = "/var/lib/sd.trust.db" +connection = "/var/lib/scion/sd.trust.db" [path_db] -connection = "/var/lib/sd.path.db" +connection = "/var/lib/scion/sd.path.db" From 6f2044ea757bf85c8368009db99941c36a8a3f50 Mon Sep 17 00:00:00 2001 From: Corine de Kater Date: Sun, 5 Nov 2023 12:39:39 +0100 Subject: [PATCH 51/68] Corrected some mistakes --- doc/deploy/deployment.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 30c780e814..29a5f03dca 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -71,7 +71,7 @@ To create the sample ISD environment, you need to perform the following tasks, i The following sections explain the required tasks, one section per task. -.. _step1: +.. _step0: OS Setup ........ @@ -104,7 +104,7 @@ Repeat these commands on scion01-scion05. mkdir -p /var/lib/scion -.. _step2: +.. _step1: Software Selection, Download, and Installation .............................................. @@ -125,8 +125,9 @@ Note that we have to install the software five times: Once per virtual machine w Installation from packages is under development (available 2024). + Downloading and Installing the SCION Software -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ With the software selected (from above), it will need to be downloaded and installed on each of the VMs scion01-scion05. @@ -151,14 +152,14 @@ To download the software and install it on your virtual machines, execute the fo As each virtual machine represents an AS in your demo environment, we will now refer to the VMs as ASes. -.. _step3: +.. _step2: Configuration ............. To configure your demo SCION environment, perform the following steps. -Step 2 - Download AS Specific Topology Files +Step 1 - Download AS Specific Topology Files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. For this tutorial, we have provided the AS specific topology files - one per each AS. These files have been generated from the master AS topology file for this tutorial deployment for simplicity. @@ -242,7 +243,7 @@ The next step is to generate all required certificates by using the global topol scp -r gen/trcs scionX:/etc/scion/certs -Step 3 - Generate Forwarding Secret Keys +Step 3 - Generate Forwarding Secret Keys ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Two symmetric keys *master0.key* and *master1.key* are required per AS as the forwarding secret keys. These symmetric keys are used by the AS in the data plane to verify the MACs in the hop fields of a SCION path (header). @@ -270,7 +271,7 @@ The files including their names are listed below. Click on the corresponding lin -Step 6 - Start the Services +Step 5 - Start the Services ~~~~~~~~~~~~~~~~~~~~~~~~~~~ As a last step, you have to start the services on each of the five ASes. Execute the following commands on every AS: @@ -284,7 +285,7 @@ As a last step, you have to start the services on each of the five ASes. Execute -.. _step4: +.. _step3: Testing the Environment ....................... From 89a1941f9e86f8324de3cb307a2259f7ba762a08 Mon Sep 17 00:00:00 2001 From: Corine de Kater Date: Sun, 5 Nov 2023 12:42:18 +0100 Subject: [PATCH 52/68] more corrections --- doc/deploy/deployment.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 29a5f03dca..ba086125ef 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -162,7 +162,7 @@ To configure your demo SCION environment, perform the following steps. Step 1 - Download AS Specific Topology Files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -1. For this tutorial, we have provided the AS specific topology files - one per each AS. These files have been generated from the master AS topology file for this tutorial deployment for simplicity. +For this tutorial, we have provided the AS specific topology files - one per each AS. These files have been generated from the master AS topology file for this tutorial deployment for simplicity. Now you have to create a topology file per AS. Sample topology files for each AS in our sample ISD environment are listed below. Click on the file name to download it, then copy the file to the corresponding AS. - **AS 1 (ffaa:1:1)**: `topology-42-ffaa:1:1.json `_ @@ -193,7 +193,6 @@ Now you have to create a topology file per AS. Sample topology files for each AS sed -i 's/10.0.0.4/YOUR_SCION04_IP/g' /etc/scion/topology4.json sed -i 's/10.0.0.5/YOUR_SCION05_IP/g' /etc/scion/topology5.json -.. code-block:: From a36a65790fc232831d7fa3a400b0ff93809a69c8 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 04:16:18 -0800 Subject: [PATCH 53/68] generic id names --- doc/deploy/topology4.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/deploy/topology4.json b/doc/deploy/topology4.json index 72552f1387..1b6782f1fd 100644 --- a/doc/deploy/topology4.json +++ b/doc/deploy/topology4.json @@ -3,17 +3,17 @@ "isd_as": "42-ffaa:1:4", "mtu": 1472, "control_service": { - "cs42-ffaa_1_4-1": { + "cs": { "addr": "127.0.0.1:31000" } }, "discovery_service": { - "cs42-ffaa_1_4-1": { + "cs": { "addr": "127.0.0.1:31000" } }, "border_routers": { - "br42-ffaa_1_4-1": { + "br": { "internal_addr": "127.0.0.1:31002", "interfaces": { "1": { From fd887c2d49771702d8a51cc1715baab75a1402e4 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 04:26:05 -0800 Subject: [PATCH 54/68] AS topology file --- doc/deploy/deployment.rst | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index ba086125ef..44c2e02c8c 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -84,12 +84,14 @@ Set this up on scion01-scion05. .. code-block:: +# additions to /etc/hosts 10.0.1.1 scion01 10.0.1.2 scion02 10.0.1.3 scion03 10.0.1.4 scion04 10.0.1.5 scion05 + - Create required directories. These directories are required to store the certificates, keys, and database files. @@ -140,8 +142,6 @@ To download the software and install it on your virtual machines, execute the fo .. code-block:: - sudo -i - wget https://github.com/scionproto/scion/releases/download/v0.9.1/scion_v0.9.1_amd64_linux.tar.gz mkdir /usr/local/scion @@ -159,7 +159,7 @@ Configuration To configure your demo SCION environment, perform the following steps. -Step 1 - Download AS Specific Topology Files +Step 1 - AS Specific Topology Files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For this tutorial, we have provided the AS specific topology files - one per each AS. These files have been generated from the master AS topology file for this tutorial deployment for simplicity. @@ -175,25 +175,30 @@ Now you have to create a topology file per AS. Sample topology files for each AS - **AS 5 (ffaa:1:5)**: `topology-42-ffaa:1:5.json `_ - Replace IP addressed from this guide with the IPs of your machines: +Download the AS specific topology files onto each host scion01 through scion05. + +For example, on scion01, download the topology1.json file. On scion02, download topology2.json and repeat as such on scion03, scion04, and scion05. .. code-block:: - wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/topology1.json - wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/topology2.json - wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/topology3.json - wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/topology4.json - wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/topology5.json + wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/topology1.json -O /etc/scion/topology.json + + +Repeat the above 5 times - once for each scion host. Be sure to change topology1.json to topology2.json, etc for different hosts/AS. + + +The downloaded AS topology file is configured with generic IP address (10.0.0.1-5) for the hosts scion01-05. These IP addresses will need to be changed to the VM IP specific addresses. .. code-block:: - sed -i 's/10.0.0.1/YOUR_SCION01_IP/g' /etc/scion/topology1.json - sed -i 's/10.0.0.2/YOUR_SCION02_IP/g' /etc/scion/topology2.json - sed -i 's/10.0.0.3/YOUR_SCION03_IP/g' /etc/scion/topology3.json - sed -i 's/10.0.0.4/YOUR_SCION04_IP/g' /etc/scion/topology4.json - sed -i 's/10.0.0.5/YOUR_SCION05_IP/g' /etc/scion/topology5.json + sed -i 's/10.0.0.1/YOUR_SCION01_IP/g' /etc/scion/topology.json + sed -i 's/10.0.0.2/YOUR_SCION02_IP/g' /etc/scion/topology.json + sed -i 's/10.0.0.3/YOUR_SCION03_IP/g' /etc/scion/topology.json + sed -i 's/10.0.0.4/YOUR_SCION04_IP/g' /etc/scion/topology.json + sed -i 's/10.0.0.5/YOUR_SCION05_IP/g' /etc/scion/topology.json +Repeat the above 5 times - once for each scion host replacing YOUR_SCIONXX_IP with the VM specific IP address. Step 2 - Generate the Required Certificates From d70a6cfe9e8ffd4ce24380e6e56c871d81b63e62 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 04:44:04 -0800 Subject: [PATCH 55/68] Update deployment.rst --- doc/deploy/deployment.rst | 66 +++++++++++++++++++++------------------ 1 file changed, 36 insertions(+), 30 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 44c2e02c8c..8fcc17d504 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -204,47 +204,37 @@ Repeat the above 5 times - once for each scion host replacing YOUR_SCIONXX_IP wi Step 2 - Generate the Required Certificates ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For this tutorial deployment, a sample topology file has been provided. As part of this tutorial deployment, this file will be processed to generate the required crypto graphics keys. +The various cryptographic certificates need to be generated for each of the ASes. For this tutorial, we have provided the relevant AS wide topology file which will be used to generate the required keys and certificates. -This topology file describes the setup of the entire ISD environment including all 5 ASes and the associated network links between the ASes. The topology file of an AS specifies all the inter-AS connections to neighboring ASes, and defines the underlay IP/UDP addresses of services and routers running in this AS. +This topology file describes the setup of the entire ISD environment including all 5 ASes and the associated network links between the ASes. The topology file of an AS specifies all the inter-AS connections to neighboring ASes, and defines the underlay IP/UDP addresses of services and routers running in this AS. (The AS specific topology files used above were generated from this larger AS wide topology file.) The topology information is needed by Router and Control Service instances, and also by end-host applications. For more information on the topology files, see ``_ -1. First, download the provided tutorial deployment topology file. This contains a concise representation of the topology drawn above. This topology file is available at: `TutorialDeploymentTopology.topo `_ . Download the file to the scion01 VM. +1. First, download the provided AS wide tutorial deployment topology file. This contains a concise representation of the topology drawn above. This topology file is available at: `TutorialDeploymentTopology.topo `_ . Download the file to the scion01 VM. .. code-block:: wget https://github.com/cdekater/scion/raw/ietf118-hackathon/doc/deploy/TutorialDeploymentTopology.topo -The next step is to generate all required certificates by using the global topology file. Proceed as follows: - -2. To generate all required certificates using the global topology file, execute the following command on the machine where you downloaded the global topology: +2. Using the above AS wide tutorial file, the required certificates will be generated and then distributed across all the hosts. To generate all required certificates, execute the following command on the machine where you downloaded the global topology (scion01). .. code-block:: /usr/local/scion/scion-pki testcrypto -t TutorialDeploymentTopology.topo - This will generate all the required keys in the *gen/* directory for all the SCION ASes in all topology. + This will generate all the required keys in a new *gen/* directory for all the SCION ASes. -3. Now you have to copy the just-generated keys to the respective AS routers. Proceed as follows: +3. The just-generated keys in gen/* can now be copied to the respective AS routers from scion01. - - Copy the content of *gen/ASffaa_1_X/* to */etc/scion/* on each of the five AS routers - On the machine where you generated the material - - The part *ASffaa_1_X* in the last line needs to be adapted per AS, so that it contains the correct AS number for the corresponding AS. + - Copy the TRC certificates and cryptographic keys to each of the five AS routers (scion01 - scion05). .. code-block:: - mkdir /etc/scion - mkdir /etc/scion/certs - cp -r gen/ASffaa_1_1/ /etc/scion/ - - Copy from machine 1 to all other machines the respective certs - - .. code-block:: - - scp -r scion1:/tmp/gen . - scp -r gen/ASffaa_1_X/crypto scion1:/etc/scion/ - scp -r gen/trcs scionX:/etc/scion/certs + for i in {1..5} + do + scp -r gen/ASffaa_1_$i/crypto scion01:/etc/scion/ + scp -r gen/trcs scion0$i:/etc/scion/certs + done Step 3 - Generate Forwarding Secret Keys @@ -257,11 +247,13 @@ Two symmetric keys *master0.key* and *master1.key* are required per AS as the fo dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master0.key dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master1.key +Repeat the above on each host scion01 - scion05. + -Step 4 - Create the Configuration Files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Step 4 - Service Configuration Files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Next, you have to create ("copy over") a couple of configuration files in the */etc/scion/* directory of each AS. +Next, you have to download the service configuration files into the */etc/scion/* directory of each AS host scion01-scion05. The files including their names are listed below. Click on the corresponding link to download the file, then copy it into the */etc/scion/* directory of each AS. @@ -275,18 +267,32 @@ The files including their names are listed below. Click on the corresponding lin +Alternatively, the files can be downloaded directly onto each host with wget. + +.. code-block:: + + wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/br.toml -O /etc/scion/br.toml + wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/cs.toml -O /etc/scion/cs.toml + wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/dispatcher.toml -O /etc/scion/dispatcher.toml + wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/sd.toml -O /etc/scion/sd.toml + + +These steps need to be repeated on each host scion01 - scion05. + Step 5 - Start the Services ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -As a last step, you have to start the services on each of the five ASes. Execute the following commands on every AS: +Start the services on each of the five ASes. Execute the following commands on every AS: .. code-block:: - screen -dmS BorderRouter /usr/local/scion/router --config /etc/scion/br.toml - screen -dmS Dispatcher /usr/local/scion/dispatcher --config /etc/scion/dispatcher.toml - screen -dmS Control /usr/local/scion/control --config /etc/scion/cs.toml - screen -dmS Daemon /usr/local/scion/daemon --config /etc/scion/sd.toml + /usr/local/scion/router --config /etc/scion/br.toml + /usr/local/scion/dispatcher --config /etc/scion/dispatcher.toml + /usr/local/scion/control --config /etc/scion/cs.toml + /usr/local/scion/daemon --config /etc/scion/sd.toml + +These steps need to be repeated on each host scion01 - scion05. .. _step3: From f73d3866ca14ce61753a98ce6a543c4812f329ec Mon Sep 17 00:00:00 2001 From: Corine de Kater Date: Sun, 5 Nov 2023 14:09:55 +0100 Subject: [PATCH 56/68] last updates --- doc/conf.py | 4 ++ doc/deploy/deployment.rst | 90 +++++++++++++++++++-------------------- 2 files changed, 48 insertions(+), 46 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 30db34d78e..75328db3a6 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -25,6 +25,10 @@ 'sphinx_copybutton', ] +copybutton_prompt_text = r'\$ ' +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/deploy/deployment.rst b/doc/deploy/deployment.rst index 8fcc17d504..473bb74e44 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -3,7 +3,7 @@ Deployment Tutorial =================== -This document helps you set up a SCION demo configuration, which consists of a stand-alone full-scale SCION environment distributed among five computers. The demo environment consists of one SCION Isolation Domain (ISD), with three core ASes and two non-core, leaf ASes. +This document helps you set up a SCION demo configuration, which consists of a stand-alone full-scale SCION environment distributed among five computers. The demo environment contains one SCION Isolation Domain (ISD), with three core ASes and two non-core, leaf ASes. - If you want to go deep and help develop SCION, use the development environment. See https://docs.scion.org/en/latest/dev/setup.html - If you want to use SCION in a large environment, use the SCIONLab. For more information, see https://www.scionlab.org/ @@ -58,6 +58,7 @@ This deployment requires five virtual machines (VMs) - one for each AS. We recom - Using the naming convention for each VM of scion01, scion02, scion03, scion04, and scion05 will help follow along with this tutorial. - The VM names scion01-scion05 can be configured in /etc/hosts. + Tasks to Perform ---------------- @@ -76,34 +77,33 @@ The following sections explain the required tasks, one section per task. OS Setup ........ - - Set up the host file - -The host file (*/etc/hosts*) will need to be updated with the IP addresses of 5 VMs. This will need to be updated on scion01-scion05. Replace the IP addresses with the assigned IP addresses for the VMs deployed. +- Set up the host file -Set this up on scion01-scion05. + The host file (*/etc/hosts*) will need to be updated with the IP addresses of 5 VMs. This will need to be updated on scion01-scion05. Replace the IP addresses with the assigned IP addresses for the VMs deployed. -.. code-block:: + Set this up on scion01-scion05. -# additions to /etc/hosts - 10.0.1.1 scion01 - 10.0.1.2 scion02 - 10.0.1.3 scion03 - 10.0.1.4 scion04 - 10.0.1.5 scion05 + .. code-block:: + # additions to /etc/hosts + 10.0.1.1 scion01 + 10.0.1.2 scion02 + 10.0.1.3 scion03 + 10.0.1.4 scion04 + 10.0.1.5 scion05 - - Create required directories. -These directories are required to store the certificates, keys, and database files. +- Create required directories. -Repeat these commands on scion01-scion05. + These directories are required to store the certificates, keys, and database files. + Repeat these commands on scion01-scion05. - .. code-block:: + .. code-block:: - mkdir -p /etc/scion/certs - mkdir -p /etc/scion/crypto/as - mkdir -p /etc/scion/keys - mkdir -p /var/lib/scion + mkdir -p /etc/scion/certs + mkdir -p /etc/scion/crypto/as + mkdir -p /etc/scion/keys + mkdir -p /var/lib/scion .. _step1: @@ -175,27 +175,26 @@ Now you have to create a topology file per AS. Sample topology files for each AS - **AS 5 (ffaa:1:5)**: `topology-42-ffaa:1:5.json `_ -Download the AS specific topology files onto each host scion01 through scion05. +Download the AS specific topology files onto each host scion01 through scion05. For example, on scion01, download the topology1.json file. On scion02, download topology2.json and repeat as such on scion03, scion04, and scion05. .. code-block:: - wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/topology1.json -O /etc/scion/topology.json + wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/topology1.json -O /etc/scion/topology.json Repeat the above 5 times - once for each scion host. Be sure to change topology1.json to topology2.json, etc for different hosts/AS. - The downloaded AS topology file is configured with generic IP address (10.0.0.1-5) for the hosts scion01-05. These IP addresses will need to be changed to the VM IP specific addresses. .. code-block:: - sed -i 's/10.0.0.1/YOUR_SCION01_IP/g' /etc/scion/topology.json - sed -i 's/10.0.0.2/YOUR_SCION02_IP/g' /etc/scion/topology.json - sed -i 's/10.0.0.3/YOUR_SCION03_IP/g' /etc/scion/topology.json - sed -i 's/10.0.0.4/YOUR_SCION04_IP/g' /etc/scion/topology.json - sed -i 's/10.0.0.5/YOUR_SCION05_IP/g' /etc/scion/topology.json + sed -i 's/10.0.0.1/YOUR_SCION01_IP/g' /etc/scion/topology.json + sed -i 's/10.0.0.2/YOUR_SCION02_IP/g' /etc/scion/topology.json + sed -i 's/10.0.0.3/YOUR_SCION03_IP/g' /etc/scion/topology.json + sed -i 's/10.0.0.4/YOUR_SCION04_IP/g' /etc/scion/topology.json + sed -i 's/10.0.0.5/YOUR_SCION05_IP/g' /etc/scion/topology.json Repeat the above 5 times - once for each scion host replacing YOUR_SCIONXX_IP with the VM specific IP address. @@ -212,9 +211,9 @@ The topology information is needed by Router and Control Service instances, and 1. First, download the provided AS wide tutorial deployment topology file. This contains a concise representation of the topology drawn above. This topology file is available at: `TutorialDeploymentTopology.topo `_ . Download the file to the scion01 VM. -.. code-block:: + .. code-block:: - wget https://github.com/cdekater/scion/raw/ietf118-hackathon/doc/deploy/TutorialDeploymentTopology.topo + wget https://github.com/cdekater/scion/raw/ietf118-hackathon/doc/deploy/TutorialDeploymentTopology.topo 2. Using the above AS wide tutorial file, the required certificates will be generated and then distributed across all the hosts. To generate all required certificates, execute the following command on the machine where you downloaded the global topology (scion01). @@ -228,13 +227,13 @@ The topology information is needed by Router and Control Service instances, and - Copy the TRC certificates and cryptographic keys to each of the five AS routers (scion01 - scion05). - .. code-block:: + .. code-block:: - for i in {1..5} - do - scp -r gen/ASffaa_1_$i/crypto scion01:/etc/scion/ - scp -r gen/trcs scion0$i:/etc/scion/certs - done + for i in {1..5} + do + scp -r gen/ASffaa_1_$i/crypto scion01:/etc/scion/ + scp -r gen/trcs scion0$i:/etc/scion/certs + done Step 3 - Generate Forwarding Secret Keys @@ -242,10 +241,10 @@ Step 3 - Generate Forwarding Secret Keys Two symmetric keys *master0.key* and *master1.key* are required per AS as the forwarding secret keys. These symmetric keys are used by the AS in the data plane to verify the MACs in the hop fields of a SCION path (header). - .. code-block:: +.. code-block:: - dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master0.key - dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master1.key + dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master0.key + dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master1.key Repeat the above on each host scion01 - scion05. @@ -266,18 +265,17 @@ The files including their names are listed below. Click on the corresponding lin - **SCION daemon**: `sd.toml `_ - Alternatively, the files can be downloaded directly onto each host with wget. .. code-block:: - wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/br.toml -O /etc/scion/br.toml - wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/cs.toml -O /etc/scion/cs.toml - wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/dispatcher.toml -O /etc/scion/dispatcher.toml - wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/sd.toml -O /etc/scion/sd.toml + wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/br.toml -O /etc/scion/br.toml + wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/cs.toml -O /etc/scion/cs.toml + wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/dispatcher.toml -O /etc/scion/dispatcher.toml + wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/sd.toml -O /etc/scion/sd.toml -These steps need to be repeated on each host scion01 - scion05. +These steps need to be repeated on each host scion01 - scion05. Step 5 - Start the Services ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -292,7 +290,7 @@ Start the services on each of the five ASes. Execute the following commands on e /usr/local/scion/daemon --config /etc/scion/sd.toml -These steps need to be repeated on each host scion01 - scion05. +These steps need to be repeated on each host scion01 - scion05. .. _step3: From 2ff026c154620fe1e8d06ffdb647fcdba09a31e5 Mon Sep 17 00:00:00 2001 From: John Studarus Date: Sun, 5 Nov 2023 07:02:41 -0800 Subject: [PATCH 57/68] Update deployment.rst --- doc/deploy/deployment.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 473bb74e44..4739974bfb 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -54,7 +54,7 @@ This deployment requires five virtual machines (VMs) - one for each AS. We recom - 5 VMs - **Ubuntu** 22.04.3 LTS (Jammy Jellyfish). For more information, see `Ubuntu Jammy Jellyfish `_. - Each VM should have at least one IP address reachable by the other VMs. (If on AWS, be sure to set up the appropriate security groups.) - Each VM will need internet access to download the required files (or you will need an alternate way to download the SCION binaries). -- One VM (scion01) should have SSH access to copy generated SCION keys to the other hosts scion{02-05}. +- One VM (scion01) should have SSH access (password or SSH keys) to the other hosts scion{02-05} to copy generated configuration files and keys. - Using the naming convention for each VM of scion01, scion02, scion03, scion04, and scion05 will help follow along with this tutorial. - The VM names scion01-scion05 can be configured in /etc/hosts. From 386f2e5fe087b2e18b5686fd629ae727a7ee70cc Mon Sep 17 00:00:00 2001 From: Nicola Rustignoli Date: Sun, 5 Nov 2023 16:17:43 +0100 Subject: [PATCH 58/68] fix scp --- doc/deploy/deployment.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 4739974bfb..e098444609 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -231,8 +231,8 @@ The topology information is needed by Router and Control Service instances, and for i in {1..5} do - scp -r gen/ASffaa_1_$i/crypto scion01:/etc/scion/ - scp -r gen/trcs scion0$i:/etc/scion/certs + scp -r gen/ASffaa_1_$i/crypto scion0Si:/etc/scion/ + scp -r gen/trcs/ISD42-B1-S1.trc scion$i:/etc/scion/certs/ done From e3df2c098c5f06724e39958f99bddb829a6b45e5 Mon Sep 17 00:00:00 2001 From: Nicola Rustignoli Date: Sun, 5 Nov 2023 16:25:02 +0100 Subject: [PATCH 59/68] typo --- doc/deploy/deployment.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index e098444609..691fb31d1c 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -231,7 +231,7 @@ The topology information is needed by Router and Control Service instances, and for i in {1..5} do - scp -r gen/ASffaa_1_$i/crypto scion0Si:/etc/scion/ + scp -r gen/ASffaa_1_$i/crypto scion0$i:/etc/scion/ scp -r gen/trcs/ISD42-B1-S1.trc scion$i:/etc/scion/certs/ done From 30e4c5343c6b5bca8029969a38314673c5bf6744 Mon Sep 17 00:00:00 2001 From: Nicola Rustignoli Date: Mon, 6 Nov 2023 09:40:59 +0100 Subject: [PATCH 60/68] add note about new TRC --- doc/deploy/deployment.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 691fb31d1c..e6e3323012 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -223,6 +223,11 @@ The topology information is needed by Router and Control Service instances, and This will generate all the required keys in a new *gen/* directory for all the SCION ASes. + .. note:: + + The step above will generate a new TRC for your ISD and must be done exactly once. Once you deploy such TRC on your machines, further TRC updates must be sequential. If for any reason you need to reset your setup and you need to deploy a fresh new TRC generated with the script above, then you must first delete the local DB files on your hosts (in `/var/lib/scion/`). + + 3. The just-generated keys in gen/* can now be copied to the respective AS routers from scion01. - Copy the TRC certificates and cryptographic keys to each of the five AS routers (scion01 - scion05). From 4a00b87e6aea199b1c08d71544f3870cf650fefd Mon Sep 17 00:00:00 2001 From: Nicola Rustignoli Date: Mon, 6 Nov 2023 09:58:11 +0100 Subject: [PATCH 61/68] change mkdir --- doc/deploy/deployment.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index e6e3323012..8c8f81b7d4 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -96,14 +96,17 @@ OS Setup - Create required directories. These directories are required to store the certificates, keys, and database files. - Repeat these commands on scion01-scion05. + Repeat these commands on scion01-scion05. We assume you'll run the SCION binaries with user `ubuntu`. .. code-block:: + sudo mkdir /etc/scion + sudo mkdir -p /var/lib/scion + sudo chown -R ubuntu:ubuntu /etc/scion/ + sudo chown -R ubuntu:ubuntu /var/lib/scion/ mkdir -p /etc/scion/certs mkdir -p /etc/scion/crypto/as mkdir -p /etc/scion/keys - mkdir -p /var/lib/scion .. _step1: From 49e3c7fe136be9f2806e2cb7f50638f42dabd2cc Mon Sep 17 00:00:00 2001 From: Nicola Rustignoli Date: Mon, 6 Nov 2023 10:44:25 +0100 Subject: [PATCH 62/68] scp typo --- doc/deploy/deployment.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 8c8f81b7d4..9c91dcc79e 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -240,7 +240,7 @@ The topology information is needed by Router and Control Service instances, and for i in {1..5} do scp -r gen/ASffaa_1_$i/crypto scion0$i:/etc/scion/ - scp -r gen/trcs/ISD42-B1-S1.trc scion$i:/etc/scion/certs/ + scp -r gen/trcs/ISD42-B1-S1.trc scion0$i:/etc/scion/certs/ done From 6cdf9a87dc6b9249f4fa40babc90bf12b3b9a345 Mon Sep 17 00:00:00 2001 From: Matthias Frei Date: Mon, 6 Nov 2023 10:51:01 +0100 Subject: [PATCH 63/68] fixup file download links --- doc/deploy/deployment.rst | 48 ++++++++++++--------------------------- 1 file changed, 14 insertions(+), 34 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 9c91dcc79e..772b6fdd7b 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -168,27 +168,22 @@ Step 1 - AS Specific Topology Files For this tutorial, we have provided the AS specific topology files - one per each AS. These files have been generated from the master AS topology file for this tutorial deployment for simplicity. Now you have to create a topology file per AS. Sample topology files for each AS in our sample ISD environment are listed below. Click on the file name to download it, then copy the file to the corresponding AS. - - **AS 1 (ffaa:1:1)**: `topology-42-ffaa:1:1.json `_ - - - **AS 2 (ffaa:1:2)**: `topology-42-ffaa:1:2.json `_ - - - **AS 3 (ffaa:1:3)**: `topology-42-ffaa:1:3.json `_ - - - **AS 4 (ffaa:1:4)**: `topology-42-ffaa:1:4.json `_ - - - **AS 5 (ffaa:1:5)**: `topology-42-ffaa:1:5.json `_ + - **AS 1 (ffaa:1:1)**: :download:`topology-42-ffaa:1:1.json ` + - **AS 2 (ffaa:1:2)**: :download:`topology-42-ffaa:1:2.json ` + - **AS 3 (ffaa:1:3)**: :download:`topology-42-ffaa:1:3.json ` + - **AS 4 (ffaa:1:4)**: :download:`topology-42-ffaa:1:4.json ` + - **AS 5 (ffaa:1:5)**: :download:`topology-42-ffaa:1:5.json ` Download the AS specific topology files onto each host scion01 through scion05. -For example, on scion01, download the topology1.json file. On scion02, download topology2.json and repeat as such on scion03, scion04, and scion05. +Copy the download link above and use ``wget`` to download appropriate file for each host, installing it as ``/etc/scion/topology.json``. +On scion01, download the topology1.json file. On scion02, download topology2.json and repeat as such on scion03, scion04, and scion05. .. code-block:: - wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/topology1.json -O /etc/scion/topology.json + wget LINK_TO_TOPOLOGY.JSON_FILE -O /etc/scion/topology.json -Repeat the above 5 times - once for each scion host. Be sure to change topology1.json to topology2.json, etc for different hosts/AS. - The downloaded AS topology file is configured with generic IP address (10.0.0.1-5) for the hosts scion01-05. These IP addresses will need to be changed to the VM IP specific addresses. .. code-block:: @@ -212,11 +207,7 @@ This topology file describes the setup of the entire ISD environment including a The topology information is needed by Router and Control Service instances, and also by end-host applications. For more information on the topology files, see ``_ -1. First, download the provided AS wide tutorial deployment topology file. This contains a concise representation of the topology drawn above. This topology file is available at: `TutorialDeploymentTopology.topo `_ . Download the file to the scion01 VM. - - .. code-block:: - - wget https://github.com/cdekater/scion/raw/ietf118-hackathon/doc/deploy/TutorialDeploymentTopology.topo +1. First, download the provided AS wide tutorial deployment topology file. This contains a concise representation of the topology drawn above. This topology file is available at: :download:`TutorialDeploymentTopology.topo ` . Download the file to the scion01 VM. 2. Using the above AS wide tutorial file, the required certificates will be generated and then distributed across all the hosts. To generate all required certificates, execute the following command on the machine where you downloaded the global topology (scion01). @@ -264,24 +255,13 @@ Next, you have to download the service configuration files into the */etc/scion/ The files including their names are listed below. Click on the corresponding link to download the file, then copy it into the */etc/scion/* directory of each AS. -- **Border router**: `br.toml `_ - -- **Control service**: `cs.toml `_ - -- **Dispatcher**: `dispatcher.toml `_ - -- **SCION daemon**: `sd.toml `_ - - -Alternatively, the files can be downloaded directly onto each host with wget. - -.. code-block:: +- **Border router**: :download:`br.toml` +- **Control service**: :download:`cs.toml` +- **Dispatcher**: :download:`dispatcher.toml` +- **SCION daemon**: :download:`sd.toml` - wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/br.toml -O /etc/scion/br.toml - wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/cs.toml -O /etc/scion/cs.toml - wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/dispatcher.toml -O /etc/scion/dispatcher.toml - wget https://github.com/cdekater/scion/blob/ietf118-hackathon/doc/deploy/sd.toml -O /etc/scion/sd.toml +Alternatively, the files can be downloaded directly onto each host with ``wget`` into the ``/etc/scion`` directory. These steps need to be repeated on each host scion01 - scion05. From 928b3bd3b1db18af677d3c60ea7c360f58d77afb Mon Sep 17 00:00:00 2001 From: Matthias Frei Date: Mon, 6 Nov 2023 11:07:52 +0100 Subject: [PATCH 64/68] fixup: copy button prompt match --- doc/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 75328db3a6..e41f7b1b42 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -25,7 +25,7 @@ 'sphinx_copybutton', ] -copybutton_prompt_text = r'\$ ' +copybutton_prompt_text = r'\w*\$ ' # matches e.g. $ copybutton_prompt_is_regexp = True copybutton_only_copy_prompt_lines = True From 904da4696d703dc7f2896514787b211bf7efbe3b Mon Sep 17 00:00:00 2001 From: Matthias Frei Date: Mon, 6 Nov 2023 11:08:04 +0100 Subject: [PATCH 65/68] fixup: fix internal references --- doc/deploy/deployment.rst | 8 +++----- doc/index.rst | 6 +++--- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/doc/deploy/deployment.rst b/doc/deploy/deployment.rst index 772b6fdd7b..2f0b8bb47c 100644 --- a/doc/deploy/deployment.rst +++ b/doc/deploy/deployment.rst @@ -1,11 +1,9 @@ -.. _deployment-guide: - Deployment Tutorial =================== This document helps you set up a SCION demo configuration, which consists of a stand-alone full-scale SCION environment distributed among five computers. The demo environment contains one SCION Isolation Domain (ISD), with three core ASes and two non-core, leaf ASes. -- If you want to go deep and help develop SCION, use the development environment. See https://docs.scion.org/en/latest/dev/setup.html +- If you want to go deep and help develop SCION, use the development environment. See :ref:`setting-up-the-development-environment`. - If you want to use SCION in a large environment, use the SCIONLab. For more information, see https://www.scionlab.org/ Setup @@ -205,7 +203,7 @@ The various cryptographic certificates need to be generated for each of the ASes This topology file describes the setup of the entire ISD environment including all 5 ASes and the associated network links between the ASes. The topology file of an AS specifies all the inter-AS connections to neighboring ASes, and defines the underlay IP/UDP addresses of services and routers running in this AS. (The AS specific topology files used above were generated from this larger AS wide topology file.) -The topology information is needed by Router and Control Service instances, and also by end-host applications. For more information on the topology files, see ``_ +The topology information is needed by Router and Control Service instances, and also by end-host applications. For more information on the topology files, see :ref:`common-conf-topo`. 1. First, download the provided AS wide tutorial deployment topology file. This contains a concise representation of the topology drawn above. This topology file is available at: :download:`TutorialDeploymentTopology.topo ` . Download the file to the scion01 VM. @@ -219,7 +217,7 @@ The topology information is needed by Router and Control Service instances, and .. note:: - The step above will generate a new TRC for your ISD and must be done exactly once. Once you deploy such TRC on your machines, further TRC updates must be sequential. If for any reason you need to reset your setup and you need to deploy a fresh new TRC generated with the script above, then you must first delete the local DB files on your hosts (in `/var/lib/scion/`). + The step above will generate a new TRC for your ISD and must be done exactly once. Once you deploy such TRC on your machines, further TRC updates must be sequential. If for any reason you need to reset your setup and you need to deploy a fresh new TRC generated with the script above, then you must first delete the local DB files on your hosts (in `/var/lib/scion/`). 3. The just-generated keys in gen/* can now be copied to the respective AS routers from scion01. diff --git a/doc/index.rst b/doc/index.rst index 31e7ee9f4a..c8e8cc62c5 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -91,12 +91,12 @@ implementation `_. -Deployment Guide -^^^^^^^^^^^^^^^^ +Guides and Tutorials +^^^^^^^^^^^^^^^^^^^^ .. toctree:: :maxdepth: 1 - :caption: Deployment Tutorial + :caption: Guides and Tutorials :hidden: deploy/deployment From 66c4248577561bd97b4d1fd463271b8059d947ff Mon Sep 17 00:00:00 2001 From: Matthias Frei Date: Thu, 9 Nov 2023 17:51:03 +0100 Subject: [PATCH 66/68] Move tutorial into subfolder, add index entry --- doc/index.rst | 6 ++-- .../deployment.rst => tutorials/deploy.rst} | 30 ++++++++---------- .../deploy/SCION-deployment-guide.drawio.png | Bin .../deploy/TutorialDeploymentTopology.topo | 0 doc/{ => tutorials}/deploy/br.toml | 0 doc/{ => tutorials}/deploy/cs.toml | 0 doc/{ => tutorials}/deploy/dispatcher.toml | 0 doc/{ => tutorials}/deploy/sd.toml | 0 doc/{ => tutorials}/deploy/topology1.json | 0 doc/{ => tutorials}/deploy/topology2.json | 0 doc/{ => tutorials}/deploy/topology3.json | 0 doc/{ => tutorials}/deploy/topology4.json | 0 doc/{ => tutorials}/deploy/topology5.json | 0 13 files changed, 15 insertions(+), 21 deletions(-) rename doc/{deploy/deployment.rst => tutorials/deploy.rst} (94%) rename doc/{ => tutorials}/deploy/SCION-deployment-guide.drawio.png (100%) rename doc/{ => tutorials}/deploy/TutorialDeploymentTopology.topo (100%) rename doc/{ => tutorials}/deploy/br.toml (100%) rename doc/{ => tutorials}/deploy/cs.toml (100%) rename doc/{ => tutorials}/deploy/dispatcher.toml (100%) rename doc/{ => tutorials}/deploy/sd.toml (100%) rename doc/{ => tutorials}/deploy/topology1.json (100%) rename doc/{ => tutorials}/deploy/topology2.json (100%) rename doc/{ => tutorials}/deploy/topology3.json (100%) rename doc/{ => tutorials}/deploy/topology4.json (100%) rename doc/{ => tutorials}/deploy/topology5.json (100%) diff --git a/doc/index.rst b/doc/index.rst index c8e8cc62c5..8c1ada6505 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -88,9 +88,6 @@ implementation `_. 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 ^^^^^^^^^^^^^^^^^^^^ @@ -99,8 +96,9 @@ Guides and Tutorials :caption: Guides and Tutorials :hidden: - deploy/deployment + 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/deploy/deployment.rst b/doc/tutorials/deploy.rst similarity index 94% rename from doc/deploy/deployment.rst rename to doc/tutorials/deploy.rst index 2f0b8bb47c..ed6a0846c7 100644 --- a/doc/deploy/deployment.rst +++ b/doc/tutorials/deploy.rst @@ -1,5 +1,5 @@ -Deployment Tutorial -=================== +Tutorial: Freestanding Deployment +================================= This document helps you set up a SCION demo configuration, which consists of a stand-alone full-scale SCION environment distributed among five computers. The demo environment contains one SCION Isolation Domain (ISD), with three core ASes and two non-core, leaf ASes. @@ -34,7 +34,7 @@ Sample SCION Demo Topology The topology of the ISD includes the inter-AS connections to neighboring ASes, and defines the underlay IP/UDP addresses of services and routers running in this AS. This is specified in topology files - this guide later explains how to configure these files. A following graphic depicts the topology on a high level. -.. figure:: SCION-deployment-guide.drawio.png +.. figure:: deploy/SCION-deployment-guide.drawio.png :width: 95 % :figwidth: 100 % @@ -166,11 +166,11 @@ Step 1 - AS Specific Topology Files For this tutorial, we have provided the AS specific topology files - one per each AS. These files have been generated from the master AS topology file for this tutorial deployment for simplicity. Now you have to create a topology file per AS. Sample topology files for each AS in our sample ISD environment are listed below. Click on the file name to download it, then copy the file to the corresponding AS. - - **AS 1 (ffaa:1:1)**: :download:`topology-42-ffaa:1:1.json ` - - **AS 2 (ffaa:1:2)**: :download:`topology-42-ffaa:1:2.json ` - - **AS 3 (ffaa:1:3)**: :download:`topology-42-ffaa:1:3.json ` - - **AS 4 (ffaa:1:4)**: :download:`topology-42-ffaa:1:4.json ` - - **AS 5 (ffaa:1:5)**: :download:`topology-42-ffaa:1:5.json ` +- **AS 1 (ffaa:1:1)**: :download:`topology-42-ffaa:1:1.json ` +- **AS 2 (ffaa:1:2)**: :download:`topology-42-ffaa:1:2.json ` +- **AS 3 (ffaa:1:3)**: :download:`topology-42-ffaa:1:3.json ` +- **AS 4 (ffaa:1:4)**: :download:`topology-42-ffaa:1:4.json ` +- **AS 5 (ffaa:1:5)**: :download:`topology-42-ffaa:1:5.json ` Download the AS specific topology files onto each host scion01 through scion05. @@ -205,7 +205,7 @@ This topology file describes the setup of the entire ISD environment including a The topology information is needed by Router and Control Service instances, and also by end-host applications. For more information on the topology files, see :ref:`common-conf-topo`. -1. First, download the provided AS wide tutorial deployment topology file. This contains a concise representation of the topology drawn above. This topology file is available at: :download:`TutorialDeploymentTopology.topo ` . Download the file to the scion01 VM. +1. First, download the provided AS wide tutorial deployment topology file. This contains a concise representation of the topology drawn above. This topology file is available at: :download:`TutorialDeploymentTopology.topo `. Download the file to the scion01 VM. 2. Using the above AS wide tutorial file, the required certificates will be generated and then distributed across all the hosts. To generate all required certificates, execute the following command on the machine where you downloaded the global topology (scion01). @@ -253,11 +253,10 @@ Next, you have to download the service configuration files into the */etc/scion/ The files including their names are listed below. Click on the corresponding link to download the file, then copy it into the */etc/scion/* directory of each AS. -- **Border router**: :download:`br.toml` -- **Control service**: :download:`cs.toml` -- **Dispatcher**: :download:`dispatcher.toml` -- **SCION daemon**: :download:`sd.toml` - +- **Border router**: :download:`br.toml ` +- **Control service**: :download:`cs.toml ` +- **Dispatcher**: :download:`dispatcher.toml ` +- **SCION daemon**: :download:`sd.toml ` Alternatively, the files can be downloaded directly onto each host with ``wget`` into the ``/etc/scion`` directory. @@ -326,6 +325,3 @@ Verify that each host has a full table of available paths to the other ASes. Thi 4 Hops: [2] Hops: [42-ffaa:1:1 2>1 42-ffaa:1:2 2>2 42-ffaa:1:3 4>2 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 [3] Hops: [42-ffaa:1:1 3>1 42-ffaa:1:3 2>2 42-ffaa:1:2 3>1 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 - - - diff --git a/doc/deploy/SCION-deployment-guide.drawio.png b/doc/tutorials/deploy/SCION-deployment-guide.drawio.png similarity index 100% rename from doc/deploy/SCION-deployment-guide.drawio.png rename to doc/tutorials/deploy/SCION-deployment-guide.drawio.png diff --git a/doc/deploy/TutorialDeploymentTopology.topo b/doc/tutorials/deploy/TutorialDeploymentTopology.topo similarity index 100% rename from doc/deploy/TutorialDeploymentTopology.topo rename to doc/tutorials/deploy/TutorialDeploymentTopology.topo diff --git a/doc/deploy/br.toml b/doc/tutorials/deploy/br.toml similarity index 100% rename from doc/deploy/br.toml rename to doc/tutorials/deploy/br.toml diff --git a/doc/deploy/cs.toml b/doc/tutorials/deploy/cs.toml similarity index 100% rename from doc/deploy/cs.toml rename to doc/tutorials/deploy/cs.toml diff --git a/doc/deploy/dispatcher.toml b/doc/tutorials/deploy/dispatcher.toml similarity index 100% rename from doc/deploy/dispatcher.toml rename to doc/tutorials/deploy/dispatcher.toml diff --git a/doc/deploy/sd.toml b/doc/tutorials/deploy/sd.toml similarity index 100% rename from doc/deploy/sd.toml rename to doc/tutorials/deploy/sd.toml diff --git a/doc/deploy/topology1.json b/doc/tutorials/deploy/topology1.json similarity index 100% rename from doc/deploy/topology1.json rename to doc/tutorials/deploy/topology1.json diff --git a/doc/deploy/topology2.json b/doc/tutorials/deploy/topology2.json similarity index 100% rename from doc/deploy/topology2.json rename to doc/tutorials/deploy/topology2.json diff --git a/doc/deploy/topology3.json b/doc/tutorials/deploy/topology3.json similarity index 100% rename from doc/deploy/topology3.json rename to doc/tutorials/deploy/topology3.json diff --git a/doc/deploy/topology4.json b/doc/tutorials/deploy/topology4.json similarity index 100% rename from doc/deploy/topology4.json rename to doc/tutorials/deploy/topology4.json diff --git a/doc/deploy/topology5.json b/doc/tutorials/deploy/topology5.json similarity index 100% rename from doc/deploy/topology5.json rename to doc/tutorials/deploy/topology5.json From 40ede34b748b4e7234258d4d655b579eaa6c7747 Mon Sep 17 00:00:00 2001 From: Matthias Frei Date: Tue, 13 Feb 2024 10:40:09 +0100 Subject: [PATCH 67/68] Update tutorial to install deb packages, avoid testcrypto command - Update instructions for installation from packages Simplified: removed choice to download nightly build or release. Updated instructions for starting service (using systemd) and paths to tools. Some of the configuration files are no longer needed as they come with defaults from the packages. - Remove the scion-pki testcrypto invocation in favor of a lengthy but more transparent script to generate all the crypto material As the "global" .topo file is no longer necessary, simplify the terminology around the "normal", "AS specific" topology.json files. - Misc simplifications of the text where instructions were overly repetitive. - Add cross-references to glossary and manuals - Add conclusion (text suggested by JC) --- doc/manuals/install.rst | 2 + doc/tutorials/deploy.rst | 319 ++++++++++-------- .../deploy/TutorialDeploymentTopology.topo | 30 -- doc/tutorials/deploy/dispatcher.toml | 12 - doc/tutorials/deploy/sd.toml | 13 - 5 files changed, 187 insertions(+), 189 deletions(-) delete mode 100644 doc/tutorials/deploy/TutorialDeploymentTopology.topo delete mode 100644 doc/tutorials/deploy/dispatcher.toml delete mode 100644 doc/tutorials/deploy/sd.toml diff --git a/doc/manuals/install.rst b/doc/manuals/install.rst index 83ca84aa4d..d7d0c3a25e 100644 --- a/doc/manuals/install.rst +++ b/doc/manuals/install.rst @@ -2,6 +2,8 @@ Installation ************ +.. _install-debian-packages: + Debian packages =============== diff --git a/doc/tutorials/deploy.rst b/doc/tutorials/deploy.rst index ed6a0846c7..7c86d3f595 100644 --- a/doc/tutorials/deploy.rst +++ b/doc/tutorials/deploy.rst @@ -1,10 +1,10 @@ Tutorial: Freestanding Deployment ================================= -This document helps you set up a SCION demo configuration, which consists of a stand-alone full-scale SCION environment distributed among five computers. The demo environment contains one SCION Isolation Domain (ISD), with three core ASes and two non-core, leaf ASes. +This document helps you set up a SCION demo configuration, which consists of a stand-alone full-scale SCION environment distributed among five computers. The demo environment contains one SCION Isolation Domain (:term:`ISD`), with three core :term:`ASes ` and two non-core, leaf ASes. - If you want to go deep and help develop SCION, use the development environment. See :ref:`setting-up-the-development-environment`. -- If you want to use SCION in a large environment, use the SCIONLab. For more information, see https://www.scionlab.org/ +- If you want to experiment with SCION in a larger environment, use SCIONLab. For more information, see https://www.scionlab.org/. Setup ----- @@ -81,7 +81,7 @@ OS Setup Set this up on scion01-scion05. - .. code-block:: + .. code-block:: sh # additions to /etc/hosts 10.0.1.1 scion01 @@ -91,63 +91,23 @@ OS Setup 10.0.1.5 scion05 -- Create required directories. - - These directories are required to store the certificates, keys, and database files. - Repeat these commands on scion01-scion05. We assume you'll run the SCION binaries with user `ubuntu`. - - .. code-block:: - - sudo mkdir /etc/scion - sudo mkdir -p /var/lib/scion - sudo chown -R ubuntu:ubuntu /etc/scion/ - sudo chown -R ubuntu:ubuntu /var/lib/scion/ - mkdir -p /etc/scion/certs - mkdir -p /etc/scion/crypto/as - mkdir -p /etc/scion/keys - - .. _step1: -Software Selection, Download, and Installation -.............................................. - -This section guides you through the download and installation of the SCION software. - -Software Selection -~~~~~~~~~~~~~~~~~~ - -The SCION software is available as a nightly and official release TAR file. We recommend selecting an official release. - -- `Latest official release `_ -- `Latest nightly build `_ - -In this example, we install software with the following release version: *scion_v0.9.1_amd64_linux.tar.gz* - -Note that we have to install the software five times: Once per virtual machine we created previously. Proceed as described in the following sections. - -Installation from packages is under development (available 2024). +Software Download and Installation +.................................. -Downloading and Installing the SCION Software -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The SCION software can be installed from :ref:`Debian packages `, downloaded from our `latest release `_. +Note that we have to install the software five times, on each of the VMs scion01-scion05. +Execute the following commands on each VM: -With the software selected (from above), it will need to be downloaded and installed on each of the VMs scion01-scion05. +.. code-block:: sh -To download the software and install it on your virtual machines, execute the following commands in your shell/terminal: + cd /tmp/ + wget https://github.com/scionproto/scion/releases/download/v0.10.0/scion_v0.10.0_deb_amd64.tar.gz + tar xfz scion_v0.10.0_deb_amd64.tar.gz -.. note:: - - These steps are the same for each virtual machine. So you have to repeat these steps five times, once per virtual machine. - - -.. code-block:: - - wget https://github.com/scionproto/scion/releases/download/v0.9.1/scion_v0.9.1_amd64_linux.tar.gz - - mkdir /usr/local/scion - - tar xfz /tmp/scion_v0.9.1_amd64_linux.tar.gz -C /usr/local/scion + sudo apt install ./scion*.deb As each virtual machine represents an AS in your demo environment, we will now refer to the VMs as ASes. @@ -160,31 +120,30 @@ Configuration To configure your demo SCION environment, perform the following steps. -Step 1 - AS Specific Topology Files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Step 1 - AS Topology Files +~~~~~~~~~~~~~~~~~~~~~~~~~~ -For this tutorial, we have provided the AS specific topology files - one per each AS. These files have been generated from the master AS topology file for this tutorial deployment for simplicity. -Now you have to create a topology file per AS. Sample topology files for each AS in our sample ISD environment are listed below. Click on the file name to download it, then copy the file to the corresponding AS. +For this tutorial, we have provided the AS :ref:`topology files ` - one per each AS. These files represent each AS's local view of the global network topology described above. -- **AS 1 (ffaa:1:1)**: :download:`topology-42-ffaa:1:1.json ` -- **AS 2 (ffaa:1:2)**: :download:`topology-42-ffaa:1:2.json ` -- **AS 3 (ffaa:1:3)**: :download:`topology-42-ffaa:1:3.json ` -- **AS 4 (ffaa:1:4)**: :download:`topology-42-ffaa:1:4.json ` -- **AS 5 (ffaa:1:5)**: :download:`topology-42-ffaa:1:5.json ` +- **AS 1 (42-ffaa:1:1)**: :download:`topology1.json ` +- **AS 2 (42-ffaa:1:2)**: :download:`topology2.json ` +- **AS 3 (42-ffaa:1:3)**: :download:`topology3.json ` +- **AS 4 (42-ffaa:1:4)**: :download:`topology4.json ` +- **AS 5 (42-ffaa:1:5)**: :download:`topology5.json ` -Download the AS specific topology files onto each host scion01 through scion05. +Download the AS topology files onto each host scion01 through scion05. Copy the download link above and use ``wget`` to download appropriate file for each host, installing it as ``/etc/scion/topology.json``. On scion01, download the topology1.json file. On scion02, download topology2.json and repeat as such on scion03, scion04, and scion05. -.. code-block:: +.. code-block:: sh wget LINK_TO_TOPOLOGY.JSON_FILE -O /etc/scion/topology.json -The downloaded AS topology file is configured with generic IP address (10.0.0.1-5) for the hosts scion01-05. These IP addresses will need to be changed to the VM IP specific addresses. +The downloaded AS topology file is configured with generic IP address (10.0.0.1-5) as placeholder for the hosts scion01-05. These IP addresses will need to be changed to the VM IP specific addresses. -.. code-block:: +.. code-block:: sh sed -i 's/10.0.0.1/YOUR_SCION01_IP/g' /etc/scion/topology.json sed -i 's/10.0.0.2/YOUR_SCION02_IP/g' /etc/scion/topology.json @@ -192,56 +151,125 @@ The downloaded AS topology file is configured with generic IP address (10.0.0.1- sed -i 's/10.0.0.4/YOUR_SCION04_IP/g' /etc/scion/topology.json sed -i 's/10.0.0.5/YOUR_SCION05_IP/g' /etc/scion/topology.json - -Repeat the above 5 times - once for each scion host replacing YOUR_SCIONXX_IP with the VM specific IP address. +Replace ``YOUR_SCIONXX_IP`` with the VM specific IP address and apply on each scion host. Step 2 - Generate the Required Certificates ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The various cryptographic certificates need to be generated for each of the ASes. For this tutorial, we have provided the relevant AS wide topology file which will be used to generate the required keys and certificates. +The various cryptographic certificates need to be generated for each of the ASes. +This requires first setting up the :term:`TRC` for this ISD, and then issuing AS-certificates from the :term:`CAs `. -This topology file describes the setup of the entire ISD environment including all 5 ASes and the associated network links between the ASes. The topology file of an AS specifies all the inter-AS connections to neighboring ASes, and defines the underlay IP/UDP addresses of services and routers running in this AS. (The AS specific topology files used above were generated from this larger AS wide topology file.) +For the sake of simplicity in this tutorial, we create all the keys and certificates centrally, and distribute the crypto material to the individual ASes. +In practice, the private keys of ASes are of course never revealed to other entities; the TRC would be created in a :ref:`trc-ceremony` involving representatives of all core ASes. The creation of the AS-certificates would involve a certificate-signing request to the CA. -The topology information is needed by Router and Control Service instances, and also by end-host applications. For more information on the topology files, see :ref:`common-conf-topo`. +.. admonition:: Challenge -1. First, download the provided AS wide tutorial deployment topology file. This contains a concise representation of the topology drawn above. This topology file is available at: :download:`TutorialDeploymentTopology.topo `. Download the file to the scion01 VM. + Instead of following the steps below, act out the full TRC creation ceremony and the creation of AS certificates via certificate signing requests. + Refer to the documentation on the :ref:`trc-ceremony`, :ref:`ca-cert` and :ref:`ca-ops-as-certs`. -2. Using the above AS wide tutorial file, the required certificates will be generated and then distributed across all the hosts. To generate all required certificates, execute the following command on the machine where you downloaded the global topology (scion01). - .. code-block:: - /usr/local/scion/scion-pki testcrypto -t TutorialDeploymentTopology.topo +#. To generate all required certificates, execute the following script on any machine where ``scion-pki`` is installed (e.g. scion01). - This will generate all the required keys in a new *gen/* directory for all the SCION ASes. + .. code-block:: bash - .. note:: + #!/bin/bash + + set -euo pipefail + + mkdir /tmp/tutorial-scion-certs && cd /tmp/tutorial-scion-certs + mkdir AS{1..5} + + # Create voting and root keys and (self-signed) certificates for core ASes + pushd AS1 + scion-pki certificate create --profile=sensitive-voting <(echo '{"isd_as": "42-ffaa:1:1", "common_name": "42-ffaa:1:1 sensitive voting cert"}') sensitive-voting.pem sensitive-voting.key + scion-pki certificate create --profile=regular-voting <(echo '{"isd_as": "42-ffaa:1:1", "common_name": "42-ffaa:1:1 regular voting cert"}') regular-voting.pem regular-voting.key + scion-pki certificate create --profile=cp-root <(echo '{"isd_as": "42-ffaa:1:1", "common_name": "42-ffaa:1:1 cp root cert"}') cp-root.pem cp-root.key + popd + + pushd AS2 + scion-pki certificate create --profile=cp-root <(echo '{"isd_as": "42-ffaa:1:2", "common_name": "42-ffaa:1:2 cp root cert"}') cp-root.pem cp-root.key + popd - The step above will generate a new TRC for your ISD and must be done exactly once. Once you deploy such TRC on your machines, further TRC updates must be sequential. If for any reason you need to reset your setup and you need to deploy a fresh new TRC generated with the script above, then you must first delete the local DB files on your hosts (in `/var/lib/scion/`). + pushd AS3 + scion-pki certificate create --profile=sensitive-voting <(echo '{"isd_as": "42-ffaa:1:3", "common_name": "42-ffaa:1:3 sensitive voting cert"}') sensitive-voting.pem sensitive-voting.key + scion-pki certificate create --profile=regular-voting <(echo '{"isd_as": "42-ffaa:1:3", "common_name": "42-ffaa:1:3 regular voting cert"}') regular-voting.pem regular-voting.key + popd + # Create the TRC + mkdir tmp + echo ' + isd = 42 + description = "Demo ISD 42" + serial_version = 1 + base_version = 1 + voting_quorum = 2 -3. The just-generated keys in gen/* can now be copied to the respective AS routers from scion01. + core_ases = ["ffaa:1:1", "ffaa:1:2", "ffaa:1:3"] + authoritative_ases = ["ffaa:1:1", "ffaa:1:2", "ffaa:1:3"] + cert_files = ["AS1/sensitive-voting.pem", "AS1/regular-voting.pem", "AS1/cp-root.pem", "AS2/cp-root.pem", "AS3/sensitive-voting.pem", "AS3/regular-voting.pem"] - - Copy the TRC certificates and cryptographic keys to each of the five AS routers (scion01 - scion05). + [validity] + not_before = '$(date +%s)' + validity = "365d"' \ + > trc-B1-S1-pld.tmpl - .. code-block:: + scion-pki trc payload --out=tmp/ISD42-B1-S1.pld.der --template trc-B1-S1-pld.tmpl + rm trc-B1-S1-pld.tmpl - for i in {1..5} - do - scp -r gen/ASffaa_1_$i/crypto scion0$i:/etc/scion/ - scp -r gen/trcs/ISD42-B1-S1.trc scion0$i:/etc/scion/certs/ - done + # Sign and bundle the TRC + scion-pki trc sign tmp/ISD42-B1-S1.pld.der AS1/sensitive-voting.{pem,key} --out tmp/ISD42-B1-S1.AS1-sensitive.trc + scion-pki trc sign tmp/ISD42-B1-S1.pld.der AS1/regular-voting.{pem,key} --out tmp/ISD42-B1-S1.AS1-regular.trc + scion-pki trc sign tmp/ISD42-B1-S1.pld.der AS3/sensitive-voting.{pem,key} --out tmp/ISD42-B1-S1.AS3-sensitive.trc + scion-pki trc sign tmp/ISD42-B1-S1.pld.der AS3/regular-voting.{pem,key} --out tmp/ISD42-B1-S1.AS3-regular.trc + + scion-pki trc combine tmp/ISD42-B1-S1.AS{1,3}-{sensitive,regular}.trc --payload tmp/ISD42-B1-S1.pld.der --out ISD42-B1-S1.trc + rm tmp -r + + # Create CA key and certificate for issuing ASes + pushd AS1 + scion-pki certificate create --profile=cp-ca <(echo '{"isd_as": "42-ffaa:1:1", "common_name": "42-ffaa:1:1 CA cert"}') cp-ca.pem cp-ca.key --ca cp-root.pem --ca-key cp-root.key + popd + pushd AS2 + scion-pki certificate create --profile=cp-ca <(echo '{"isd_as": "42-ffaa:1:2", "common_name": "42-ffaa:1:2 CA cert"}') cp-ca.pem cp-ca.key --ca cp-root.pem --ca-key cp-root.key + popd + + # Create AS key and certificate chains + scion-pki certificate create --profile=cp-as <(echo '{"isd_as": "42-ffaa:1:1", "common_name": "42-ffaa:1:1 AS cert"}') AS1/cp-as.pem AS1/cp-as.key --ca AS1/cp-ca.pem --ca-key AS1/cp-ca.key --bundle + scion-pki certificate create --profile=cp-as <(echo '{"isd_as": "42-ffaa:1:2", "common_name": "42-ffaa:1:2 AS cert"}') AS2/cp-as.pem AS2/cp-as.key --ca AS2/cp-ca.pem --ca-key AS2/cp-ca.key --bundle + scion-pki certificate create --profile=cp-as <(echo '{"isd_as": "42-ffaa:1:3", "common_name": "42-ffaa:1:3 AS cert"}') AS3/cp-as.pem AS3/cp-as.key --ca AS1/cp-ca.pem --ca-key AS1/cp-ca.key --bundle + scion-pki certificate create --profile=cp-as <(echo '{"isd_as": "42-ffaa:1:4", "common_name": "42-ffaa:1:4 AS cert"}') AS4/cp-as.pem AS4/cp-as.key --ca AS1/cp-ca.pem --ca-key AS1/cp-ca.key --bundle + scion-pki certificate create --profile=cp-as <(echo '{"isd_as": "42-ffaa:1:5", "common_name": "42-ffaa:1:5 AS cert"}') AS5/cp-as.pem AS5/cp-as.key --ca AS2/cp-ca.pem --ca-key AS2/cp-ca.key --bundle + + + .. note:: + + The script above will generate a new TRC for your ISD and must be done exactly once. Once you deploy such TRC on your machines, further TRC updates must be sequential. If for any reason you need to reset your setup and you need to deploy a fresh new TRC generated with the script above, then you must first delete the local DB files on your hosts (in `/var/lib/scion/`). + + +#. The just-generated crypto material in can now be copied to the respective AS VMs. + + .. code-block:: bash + + cd /tmp/tutorial-scion-certs + for i in {1..5} + do + ssh scion0$i 'mkdir -p /etc/scion/{crypto,certs}' + scp ASS$i/* scion0$i:/etc/scion/crypto/ + scp ISD42-B1-S1.trc scion0$i:/etc/scion/certs/ + done Step 3 - Generate Forwarding Secret Keys ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Two symmetric keys *master0.key* and *master1.key* are required per AS as the forwarding secret keys. These symmetric keys are used by the AS in the data plane to verify the MACs in the hop fields of a SCION path (header). +Two symmetric keys *master0.key* and *master1.key* are required per AS as the forwarding :ref:`secret keys `. These symmetric keys are used by the AS in the data plane to verify the MACs in the hop fields of a SCION path (header). -.. code-block:: +.. code-block:: bash - dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master0.key - dd if=/dev/urandom bs=16 count=1 | base64 - > /etc/scion/keys/master1.key + head -c 16 /dev/urandom | base64 - > /etc/scion/keys/master0.key + head -c 16 /dev/urandom | base64 - > /etc/scion/keys/master1.key Repeat the above on each host scion01 - scion05. @@ -249,31 +277,32 @@ Repeat the above on each host scion01 - scion05. Step 4 - Service Configuration Files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Next, you have to download the service configuration files into the */etc/scion/* directory of each AS host scion01-scion05. +Next, you have to download the service configuration file for the router and control service into the ``/etc/scion/`` directory of each AS host scion01-scion05. +Refer to the :ref:`router-conf-toml` and :ref:`control-conf-toml` manuals for details. +We use default settings for most of the available options, so that the same configuration file can be used in all of the VMs. -The files including their names are listed below. Click on the corresponding link to download the file, then copy it into the */etc/scion/* directory of each AS. +Download the files, then copy it into the ``/etc/scion/`` directory of each host scion01 - scion05. - **Border router**: :download:`br.toml ` - **Control service**: :download:`cs.toml ` -- **Dispatcher**: :download:`dispatcher.toml ` -- **SCION daemon**: :download:`sd.toml ` - -Alternatively, the files can be downloaded directly onto each host with ``wget`` into the ``/etc/scion`` directory. - -These steps need to be repeated on each host scion01 - scion05. Step 5 - Start the Services ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Start the services on each of the five ASes. Execute the following commands on every AS: +Start the SCION services on each of the five ASes. +Specifically, we start the :doc:`/manuals/router`, :doc:`/manuals/control`, :doc:`/manuals/daemon` +and :doc:`/manuals/dispatcher` processes, by starting their systemd units. The dispatcher starts +automatically as dependency of the control service and daemon. -.. code-block:: +Execute the following commands on every AS: - /usr/local/scion/router --config /etc/scion/br.toml - /usr/local/scion/dispatcher --config /etc/scion/dispatcher.toml - /usr/local/scion/control --config /etc/scion/cs.toml - /usr/local/scion/daemon --config /etc/scion/sd.toml +.. code-block:: sh + sudo systemctl start scion-router@br.service + sudo systemctl start scion-control@cs.service + sudo systemctl start scion-daemon.service + # Check that all services are active + systemctl status scion-*.service These steps need to be repeated on each host scion01 - scion05. @@ -285,43 +314,65 @@ Testing the Environment You can now test your environment. The code block below includes some tests you could perform to check whether your environment works well. -Verify that each host has a SCION address. This can be verified with the "scion address" command as shown below. +- Verify that each host has a SCION address. This can be verified with the :ref:`scion address ` command as shown below. + + .. code-block:: none + + scion01$ scion address + 42-ffaa:1:1,127.0.0.1 + +- Verify that each host can ping the other hosts via SCION. This can be done with the :ref:`scion ping ` command. In the example below, we are pinging between scion01 (AS 42-ffaa:1:1) to scion05 (AS 42-ffaa:1:5). Very that each AS can ping every other AS. + + .. code-block:: none + + scion01$ scion ping 42-ffaa:1:5,127.0.0.1 -c 5 + Resolved local address: + 127.0.0.1 + Using path: + Hops: [42-ffaa:1:1 3>1 42-ffaa:1:3 4>2 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 + + PING 42-ffaa:1:5,127.0.0.1:0 pld=0B scion_pkt=112B + 120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=0 time=0.788ms + 120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=1 time=3.502ms + 120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=2 time=3.313ms + 120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=3 time=3.838ms + 120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=4 time=3.401ms + + --- 42-ffaa:1:5,127.0.0.1 statistics --- + 5 packets transmitted, 5 received, 0% packet loss, time 5000.718ms + rtt min/avg/max/mdev = 0.788/2.968/3.838/1.105 ms + +- Verify that each host has a full table of available paths to the other ASes. This can be done with the :ref:`scion showpaths ` command. In the example below, we are displaying the paths between scion01 (AS 42-ffaa:1:1) to scion05 (AS 42-ffaa:1:5). There should be multiple paths through the core ASes. + + .. code-block:: none -.. code-block:: + scion01$ scion showpaths 42-ffaa:1:5 + Available paths to 42-ffaa:1:5 + 3 Hops: + [0] Hops: [42-ffaa:1:1 2>1 42-ffaa:1:2 3>1 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 + [1] Hops: [42-ffaa:1:1 3>1 42-ffaa:1:3 4>2 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 + 4 Hops: + [2] Hops: [42-ffaa:1:1 2>1 42-ffaa:1:2 2>2 42-ffaa:1:3 4>2 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 + [3] Hops: [42-ffaa:1:1 3>1 42-ffaa:1:3 2>2 42-ffaa:1:2 3>1 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 - scion01$ /usr/local/scion/scion address - 42-ffaa:1:1,127.0.0.1 -Verify that each host can ping the other hosts via SCION. This can be done with the "scion ping" command. In the example below, we are pinging between scion01 (AS 42-ffaa:1:1) to scion05 (AS 42-ffaa:1:5). Very that each AS can ping every other AS. +Conclusion +---------- -.. code-block:: +Congratulations, you now have a working SCION configuration, which consists of a stand-alone complete SCION environment distributed among five computers. This environment contains one SCION Isolation Domain (ISD), with three core ASes and two non-core, leaf ASes. Being a demo, this configuration has some limitations: - scion01$ /usr/local/scion/scion ping 42-ffaa:1:5,127.0.0.1 -c 5 - Resolved local address: - 127.0.0.1 - Using path: - Hops: [42-ffaa:1:1 3>1 42-ffaa:1:3 4>2 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 +- The certificates are only good for three days unless explicitly renewed using :ref:`scion-pki certificate renew `. +- Each AS contains a single host running all the SCION services. In a typical deployment, these services would run a separate hosts and include multiple border routers. +- This environment does not include a :doc:`SCION-IP gateway `. - PING 42-ffaa:1:5,127.0.0.1:0 pld=0B scion_pkt=112B - 120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=0 time=0.788ms - 120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=1 time=3.502ms - 120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=2 time=3.313ms - 120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=3 time=3.838ms - 120 bytes from 42-ffaa:1:5,127.0.0.1: scmp_seq=4 time=3.401ms - --- 42-ffaa:1:5,127.0.0.1 statistics --- - 5 packets transmitted, 5 received, 0% packet loss, time 5000.718ms - rtt min/avg/max/mdev = 0.788/2.968/3.838/1.105 ms +.. seealso:: -Verify that each host has a full table of available paths to the other ASes. This can be done with the "scion showpaths" command. In the example below, we are displaying the paths between scion01 (AS 42-ffaa:1:1) to scion05 (AS 42-ffaa:1:5). There should be multiple paths through the core ASes. + :doc:`/overview` + Introduction to the SCION architecture and core concepts. -.. code-block:: + :doc:`/dev/setup` + If you would like to learn more and help develop SCION, consider :doc:`setting up the development environment `. - scion01$ /usr/local/scion/scion showpaths 42-ffaa:1:5 - Available paths to 42-ffaa:1:5 - 3 Hops: - [0] Hops: [42-ffaa:1:1 2>1 42-ffaa:1:2 3>1 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 - [1] Hops: [42-ffaa:1:1 3>1 42-ffaa:1:3 4>2 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 - 4 Hops: - [2] Hops: [42-ffaa:1:1 2>1 42-ffaa:1:2 2>2 42-ffaa:1:3 4>2 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 - [3] Hops: [42-ffaa:1:1 3>1 42-ffaa:1:3 2>2 42-ffaa:1:2 3>1 42-ffaa:1:5] MTU: 1472 NextHop: 127.0.0.1:31002 Status: alive LocalIP: 127.0.0.1 + `SCIONLab `_ + If you would like to experiment with SCION in a larger deployment, consider joining `SCIONLab `_. diff --git a/doc/tutorials/deploy/TutorialDeploymentTopology.topo b/doc/tutorials/deploy/TutorialDeploymentTopology.topo deleted file mode 100644 index 20a57cc9a1..0000000000 --- a/doc/tutorials/deploy/TutorialDeploymentTopology.topo +++ /dev/null @@ -1,30 +0,0 @@ ---- -ASes: - "42-ffaa:1:1": - core: true - voting: true - authoritative: true - issuing: true - "42-ffaa:1:2": - core: true - voting: true - authoritative: true - issuing: true - "42-ffaa:1:3": - core: true - voting: true - authoritative: true - issuing: true - "42-ffaa:1:4": - cert_issuer: 42-ffaa:1:1 - "42-ffaa:1:5": - cert_issuer: 42-ffaa:1:2 - -links: - - {a: "42-ffaa:1:1#1", b: "42-ffaa:1:4#1", linkAtoB: CHILD} - - {a: "42-ffaa:1:1#2", b: "42-ffaa:1:2#1", linkAtoB: CORE} - - {a: "42-ffaa:1:1#3", b: "42-ffaa:1:3#1", linkAtoB: CORE} - - {a: "42-ffaa:1:2#2", b: "42-ffaa:1:3#2", linkAtoB: CORE} - - {a: "42-ffaa:1:2#3", b: "42-ffaa:1:5#1", linkAtoB: CHILD} - - {a: "42-ffaa:1:3#3", b: "42-ffaa:1:4#2", linkAtoB: CHILD} - - {a: "42-ffaa:1:3#4", b: "42-ffaa:1:5#2", linkAtoB: CHILD} diff --git a/doc/tutorials/deploy/dispatcher.toml b/doc/tutorials/deploy/dispatcher.toml deleted file mode 100644 index 8e219e3151..0000000000 --- a/doc/tutorials/deploy/dispatcher.toml +++ /dev/null @@ -1,12 +0,0 @@ -# Dispatcher configuration file. -# Save this file as /etc/scion/dispatcher.toml - -[log.console] -# Console logging level (debug|info|error) (default info) -level = "info" - -[dispatcher] -id = "dispatcher" - -# File permissions of the ApplicationSocket socket file, in octal. (default "0770") -socket_file_mode = "0770" diff --git a/doc/tutorials/deploy/sd.toml b/doc/tutorials/deploy/sd.toml deleted file mode 100644 index aac173aaf4..0000000000 --- a/doc/tutorials/deploy/sd.toml +++ /dev/null @@ -1,13 +0,0 @@ -# SCION Daemon configuration file -# Save this file as /etc/scion/sd.toml - -[general] -id = "sd" -config_dir = "/etc/scion" -reconnect_to_dispatcher = true - -[trust_db] -connection = "/var/lib/scion/sd.trust.db" - -[path_db] -connection = "/var/lib/scion/sd.path.db" From 12c76dac25b2c53b2edfe6621990f6c78c6f7cdf Mon Sep 17 00:00:00 2001 From: Matthias Frei Date: Tue, 13 Feb 2024 11:34:19 +0100 Subject: [PATCH 68/68] Fix up role description of core ASes in table to match script Also, full-scale -> complete --- doc/tutorials/deploy.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/tutorials/deploy.rst b/doc/tutorials/deploy.rst index 7c86d3f595..c31417e6db 100644 --- a/doc/tutorials/deploy.rst +++ b/doc/tutorials/deploy.rst @@ -1,7 +1,7 @@ Tutorial: Freestanding Deployment ================================= -This document helps you set up a SCION demo configuration, which consists of a stand-alone full-scale SCION environment distributed among five computers. The demo environment contains one SCION Isolation Domain (:term:`ISD`), with three core :term:`ASes ` and two non-core, leaf ASes. +This document helps you set up a SCION demo configuration, which consists of a stand-alone complete SCION environment distributed among five computers. The demo environment contains one SCION Isolation Domain (:term:`ISD`), with three core :term:`ASes ` and two non-core, leaf ASes. - If you want to go deep and help develop SCION, use the development environment. See :ref:`setting-up-the-development-environment`. - If you want to experiment with SCION in a larger environment, use SCIONLab. For more information, see https://www.scionlab.org/. @@ -16,15 +16,15 @@ Infrastructure The sample SCION demo setup consists of one ISD with three core ASes and two non-core, leaf ASes. The following table lists some details of the sample ISD and each AS in it, such as the DNS names, the ISD- and AS numbers, the kind of AS (core or leaf) and the IP addresses. This infrastructure could be virtual machines or bare metal. -======== ==== ========= ======== =========== =============== ====================== ======== ==== -Hostname ISD AS Purpose Notes IP Address OS Disk RAM -======== ==== ========= ======== =========== =============== ====================== ======== ==== -scion01 42 ffaa:1:1 Core Voting 10.0.1.1 **Ubuntu** 22.04.3 LTS 4 GB 1 GB -scion02 42 ffaa:1:2 Core Non-Voting 10.0.1.2 **Ubuntu** 22.04.3 LTS 4 GB 1 GB -scion03 42 ffaa:1:3 Core Non-Voting 10.0.1.3 **Ubuntu** 22.04.3 LTS 4 GB 1 GB -scion04 42 ffaa:1:4 Leaf 10.0.1.4 **Ubuntu** 22.04.3 LTS 4 GB 1 GB -scion05 42 ffaa:1:5 Leaf 10.0.1.5 **Ubuntu** 22.04.3 LTS 4 GB 1 GB -======== ==== ========= ======== =========== =============== ====================== ======== ==== +======== ==== ========= ======== =============== =============== ====================== ======== ==== +Hostname ISD AS Purpose Notes IP Address OS Disk RAM +======== ==== ========= ======== =============== =============== ====================== ======== ==== +scion01 42 ffaa:1:1 Core Voting, CA 10.0.1.1 **Ubuntu** 22.04.3 LTS 4 GB 1 GB +scion02 42 ffaa:1:2 Core Non-Voting, CA 10.0.1.2 **Ubuntu** 22.04.3 LTS 4 GB 1 GB +scion03 42 ffaa:1:3 Core Voting 10.0.1.3 **Ubuntu** 22.04.3 LTS 4 GB 1 GB +scion04 42 ffaa:1:4 Leaf 10.0.1.4 **Ubuntu** 22.04.3 LTS 4 GB 1 GB +scion05 42 ffaa:1:5 Leaf 10.0.1.5 **Ubuntu** 22.04.3 LTS 4 GB 1 GB +======== ==== ========= ======== =============== =============== ====================== ======== ==== *Table 1: Required Infrastructure*