From 637bdb28eb43ce4eec21328a4fec8bef08a3941b Mon Sep 17 00:00:00 2001 From: Jordi Subira Nieto Date: Thu, 8 May 2025 16:03:42 +0200 Subject: [PATCH 1/3] fix _examples links --- docs/source/reverse-proxy.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/reverse-proxy.rst b/docs/source/reverse-proxy.rst index 0f4d9b5..29a62ad 100644 --- a/docs/source/reverse-proxy.rst +++ b/docs/source/reverse-proxy.rst @@ -59,7 +59,7 @@ Then, you can follow the steps below to install the plugin: sudo setcap cap_net_bind_service=+ep /usr/local/bin/scion-caddy -- Optionally you can create a systemd service and enable it. You can use the example service file ``scion-caddy.service`` in the `examples `__. +- Optionally you can create a systemd service and enable it. You can use the example service file ``scion-caddy.service`` in the `examples `__. - The reverse proxy can work in two modes, `layer-5 <#layer-5-reverse-proxy>`__ or `layer-4 (passthrough) <#layer-4-reverse-proxy-passthrough>`__. Check the corresponding sections to configure the reverse proxy accordingly. @@ -148,7 +148,7 @@ The plugin configuration for caddy is extended with: The address follows the `network address convention `_ for Caddy, e.g., ``scion/[1-ff00:0:112,127.0.0.1]:8443`` or ``scion+single-stream/[1-ff00:0:112,127.0.0.1]:7443``. -One can follow the example in `examples `__ to configure the reverse proxy to serve specific domains in this mode. +One can follow the example in `examples `__ to configure the reverse proxy to serve specific domains in this mode. For more information on how to configure Caddy, see the `Caddy documentation `_. Layer-4 Reverse Proxy (Passthrough) @@ -164,7 +164,7 @@ The plugin configuration for caddy is extended with: - ``scion+single-stream``: The SCION network listener for single-stream connection over SCION. -One can follow the example in the `examples `__ to configure the reverse proxy to serve specific domains in this mode. +One can follow the example in the `examples `__ to configure the reverse proxy to serve specific domains in this mode. For more information on how to configure Caddy, see the `Caddy layer-4 documentation `_. .. note:: From af276829e8d1d1f1b1ee67f65ae8e5c110ebac32 Mon Sep 17 00:00:00 2001 From: Jordi Subira Nieto Date: Fri, 9 May 2025 11:10:41 +0200 Subject: [PATCH 2/3] add listening protocol information --- docs/source/reverse-proxy.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/source/reverse-proxy.rst b/docs/source/reverse-proxy.rst index 29a62ad..739846b 100644 --- a/docs/source/reverse-proxy.rst +++ b/docs/source/reverse-proxy.rst @@ -151,6 +151,13 @@ The address follows the `network address convention `__ to configure the reverse proxy to serve specific domains in this mode. For more information on how to configure Caddy, see the `Caddy documentation `_. +It is important to configure the HTTP protocols consistently using the ``listen_protocols`` `option `_ in the Caddy JSON config. +The possible combinations are (one can config one or serveral out of the following protocols for each listener): + +- ``[h3]`` for the ``scion`` listener. +- ``[h1, h2]`` for the ``scion+single-stream`` listener. +- ``[h1, h2, h3]`` for regular HTTP listeners. + Layer-4 Reverse Proxy (Passthrough) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If TLS termination option is not desirable due to the setup, the SCION HTTP Reverse Proxy can act as a layer-4 reverse proxy, forwarding the TCP connection to the backend server. From c74eafbeab59141f5fa02ed457e2b295ce1f7423 Mon Sep 17 00:00:00 2001 From: Jordi Subira Nieto Date: Fri, 9 May 2025 11:25:47 +0200 Subject: [PATCH 3/3] typos --- docs/source/reverse-proxy.rst | 70 +++++++++++++++++------------------ 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/docs/source/reverse-proxy.rst b/docs/source/reverse-proxy.rst index 739846b..f8e2d91 100644 --- a/docs/source/reverse-proxy.rst +++ b/docs/source/reverse-proxy.rst @@ -9,7 +9,7 @@ If you are looking for the forward proxy, see :doc:`Forward Proxy `_. +You can install the SCION HTTP Reverse Proxy by building it for the target platform or downloading the pre-built binary in `releases `_. Build for Linux ~~~~~~~~~~~~~~~ -You can build the caddy server containing the SCION plugin from source as follows: +You can build the Caddy server containing the SCION plugin from source as follows: - Download the source code from the `Caddy SCION repository `_. - Depending on what protocol the reverse proxy should support, you can build the binary with the following commands: - Native HTTP3 support: - .. code-block:: bash + .. code-block:: bash - go build -o ./build/scion-caddy-native ./cmd/scion-caddy-native + go build -o ./build/scion-caddy-native ./cmd/scion-caddy-native - HTTP1.1, HTTP2.0 and native HTTP3 over SCION: - .. code-block:: bash + .. code-block:: bash - go build -o ./build/scion-caddy-reverse ./cmd/scion-caddy-reverse + go build -o ./build/scion-caddy-reverse ./cmd/scion-caddy-reverse Then, you can follow the steps below to install the plugin: @@ -55,11 +55,11 @@ Then, you can follow the steps below to install the plugin: - Copy the binary to ``/usr/local/bin`` or any other directory in your ``$PATH``. - Add network capabilities to the binary: - .. code-block:: bash + .. code-block:: bash - sudo setcap cap_net_bind_service=+ep /usr/local/bin/scion-caddy + sudo setcap cap_net_bind_service=+ep /usr/local/bin/scion-caddy -- Optionally you can create a systemd service and enable it. You can use the example service file ``scion-caddy.service`` in the `examples `__. +- Optionally, you can create a systemd service and enable it. You can use the example service file ``scion-caddy.service`` in the `examples `__. - The reverse proxy can work in two modes, `layer-5 <#layer-5-reverse-proxy>`__ or `layer-4 (passthrough) <#layer-4-reverse-proxy-passthrough>`__. Check the corresponding sections to configure the reverse proxy accordingly. @@ -71,25 +71,25 @@ Build for Windows .. note:: Experimental option. The SCION HTTP reverse proxy has not been tested on Windows yet. -You can build the caddy server containing the SCION plugin from source as follows: +You can build the Caddy server containing the SCION plugin from source as follows: - Download the source code from the `Caddy SCION repository `_. - Depending on what protocol the reverse proxy should support, you can build the binary with the following commands: - Native HTTP3 support: - .. code-block:: bash + .. code-block:: bash - GOOS=windows GOARCH=amd64 go build -o ./build/scion-caddy-native ./cmd/scion-caddy-native + GOOS=windows GOARCH=amd64 go build -o ./build/scion-caddy-native ./cmd/scion-caddy-native - HTTP1.1, HTTP2.0 and native HTTP3 over SCION: - .. code-block:: bash + .. code-block:: bash - GOOS=windows GOARCH=amd64 go build -o ./build/scion-caddy-reverse ./cmd/scion-caddy-reverse + GOOS=windows GOARCH=amd64 go build -o ./build/scion-caddy-reverse ./cmd/scion-caddy-reverse -Then, you follow the steps below: +Then, follow the steps below: - Ensure that you are running the scion-endhost stack as described in the `SCION documentation `_. @@ -100,7 +100,7 @@ Then, you follow the steps below: .. code-block:: bash - .\\scion-caddy run -conf \\path\\to\\your\\config.json + .\\scion-caddy run -conf \\path\\to\\your\\config.json .. warning:: The SCION endhost stack is not officially supported on Windows, but it can be built and run with some limitations. @@ -114,20 +114,20 @@ One can enable two modes of operation: layer-5 reverse proxy and layer-4 reverse ISD-AS environment ~~~~~~~~~~~~~~~~~~ -The SCION HTTP Reverse Proxy can be configured to serve resources for different ISD-ASes. Those are configured in ``/etc/scion/environment.json`` file. +The SCION HTTP Reverse Proxy can be configured to serve resources for different ISD-ASes. Those are configured in the ``/etc/scion/environment.json`` file. You can specify a different location by setting the ``SCION_ENV_PATH`` environment variable. The file format is as follows: .. code-block:: json { - "ases": { - "": { - "daemon_address": ":" - }, - "": { - "daemon_address": ":" - } + "ases": { + "": { + "daemon_address": ":" + }, + "": { + "daemon_address": ":" } + } } @@ -138,9 +138,9 @@ The SCION HTTP Reverse Proxy can act as a layer-5 reverse proxy, terminating the In this case, the reverse proxy must provide the expected certificate for the specified domain. Afterwards, it will forward the HTTP request to the backend server. -The plugin configuration for caddy is extended with: +The plugin configuration for Caddy is extended with: -- ``scion module`` `_ +- ``scion module`` ``_ - SCION network listener configuration, which is used to specify the SCION address and port to listen on, we extend with the following network names: - ``scion``: The SCION network listener for native HTTP3 over SCION. @@ -148,11 +148,11 @@ The plugin configuration for caddy is extended with: The address follows the `network address convention `_ for Caddy, e.g., ``scion/[1-ff00:0:112,127.0.0.1]:8443`` or ``scion+single-stream/[1-ff00:0:112,127.0.0.1]:7443``. -One can follow the example in `examples `__ to configure the reverse proxy to serve specific domains in this mode. +You can follow the example in `examples `__ to configure the reverse proxy to serve specific domains in this mode. For more information on how to configure Caddy, see the `Caddy documentation `_. It is important to configure the HTTP protocols consistently using the ``listen_protocols`` `option `_ in the Caddy JSON config. -The possible combinations are (one can config one or serveral out of the following protocols for each listener): +The possible combinations are (one can configure one or several out of the following protocols for each listener): - ``[h3]`` for the ``scion`` listener. - ``[h1, h2]`` for the ``scion+single-stream`` listener. @@ -165,27 +165,27 @@ In this case, the reverse proxy will not terminate the TLS connection, but will This feature is enabled via the non-standard layer-4 module (see `Caddy layer-4 documentation `_). -The plugin configuration for caddy is extended with: +The plugin configuration for Caddy is extended with: - SCION network listener configuration, which is used to specify the SCION address and port to listen on, we extend with the following network names: - ``scion+single-stream``: The SCION network listener for single-stream connection over SCION. -One can follow the example in the `examples `__ to configure the reverse proxy to serve specific domains in this mode. +You can follow the example in the `examples `__ to configure the reverse proxy to serve specific domains in this mode. For more information on how to configure Caddy, see the `Caddy layer-4 documentation `_. .. note:: Layer-4 reverse proxy for HTTP3 clients has not been tested yet. One may try to use the "scion" network listener with the layer-4 module to achieve this, especially in combination with ``layer4.matchers.quic``. - For more information you can check `Caddy layer-4 github repo `_. + For more information, you can check `Caddy layer-4 github repo `_. Forward Proxy and Reverse Proxy ecosystem ----------------------------------------- -The SCION HTTP Reverse Proxy can be used in combination with the `SCION Forward Proxy ` to provide a SCION browsing experience. +The SCION HTTP Reverse Proxy can be used in combination with the `SCION Forward Proxy `_ to provide a SCION browsing experience. The figure below shows the enabled ecosystem. .. _reverse-proxy-figure: .. image:: img/https_combinations.png - :alt: SCION HTTP Reverse Proxy Diagram - :align: center + :alt: SCION HTTP Reverse Proxy Diagram + :align: center