diff --git a/docs/assets/images/openem/development-403-forbidden.png b/docs/assets/images/openem/development-403-forbidden.png new file mode 100644 index 0000000..475b701 Binary files /dev/null and b/docs/assets/images/openem/development-403-forbidden.png differ diff --git a/docs/operator/openem/socks5-proxy.md b/docs/operator/openem/socks5-proxy.md new file mode 100644 index 0000000..0041e27 --- /dev/null +++ b/docs/operator/openem/socks5-proxy.md @@ -0,0 +1,71 @@ +--- +title: Development Proxy +description: Configure a SOCKS5 proxy to access the OpenEM development environment. +--- + +# Development Proxy + +## 403 Errors + +The PSI development instance () is accessible +only from restricted networks. Connecting from a disallowed IP address returns a 403 +error. + +![Example 403 Forbidden error](../../assets/images/openem/development-403-forbidden.png){ style="border: solid #ccc 1px; padding: 5px" } + +To resolve this, connect through an allowed system. For operators, the recommended +approach is to configure a SOCKS5 proxy. + +## Intended audience + +This guide is for operators testing the Ingestor against the development SciCat +instance at . + +## Prerequisites + +You need SSH access to an allowed server, usually the Ingestor server, which PSI should +already have whitelisted. + +## Start the proxy + +### SSH from the command line + +If you can connect to the Ingestor with SSH, start a SOCKS5 proxy with the `-D` option: + +```sh +ssh -D 9999 ingestor.example.com +``` + +Alternatively, configure it in `~/.ssh/config` so it starts automatically when you +connect to the Ingestor: + +```config +Host ingestor.example.com + DynamicForward 9999 +``` + +### PuTTY (Windows) + +When using PuTTY, add `D9999` in **Connection → SSH → Tunnels**. See the [PuTTY documentation](https://the.earth.li/~sgtatham/putty/0.83/htmldoc/Chapter4.html#config-ssh-portfwd). + +## Enable the proxy in your browser + +Configure your browser to use the SOCKS5 proxy. The recommended option is the FoxyProxy +extension, available for [Firefox](https://addons.mozilla.org/en-US/firefox/addon/foxyproxy-standard/), [Chrome](https://chromewebstore.google.com/detail/foxyproxy/gcknhkkoolaabfmlnjonogaaifnjlfnp?pli=1), and [Edge](https://microsoftedge.microsoft.com/addons/detail/foxyproxy/flcnoalcefgkhkinjkffipfdhglnpnem?hl=en-US). + +After installing the extension, add a proxy with these values: + +| Setting | Value | +| --- | --- | +| Title | OpenEM | +| Type | SOCKS5 | +| Hostname | localhost | +| Port | 9999 | + +Enable the proxy after adding it. The FoxyProxy menu-bar icon should be coloured to +match the OpenEM proxy entry. + +## Testing + +Open . A successful connection confirms that the +proxy is active. diff --git a/mkdocs.yml b/mkdocs.yml index f6991b4..bcda24c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -71,6 +71,7 @@ nav: - Overview: operator/openem/installation.md - Ingestor: operator/openem/ingestor.md - Globus Connect Server: operator/openem/globus-connect-server.md + - Development Proxy: operator/openem/socks5-proxy.md - Further Information: - Overview: user/user-manuals.md - Support: support.md