diff --git a/guides/Best_practise--Connecting_Hawk_to_the_world b/guides/Best_practise--Connecting_Hawk_to_the_world index bb71f80..8f76140 100644 --- a/guides/Best_practise--Connecting_Hawk_to_the_world +++ b/guides/Best_practise--Connecting_Hawk_to_the_world @@ -1,11 +1,11 @@ # Best Practice -- Connecting Hawk to the world -Hawk is surrounded by a strict outgoing firewall. Users can not open arbitrary connections to hosts on the internet. Connections can only be established through a proxy host. This document describes how to set up a proxy, and how to use this proxy in a number of common use cases. +Hawk is surrounded by a strict outgoing firewall. Users can not open arbitrary connections to hosts on the internet. Connections can only be established through a proxy host. This document describes how to set up a proxy, and how to use this proxy in a number of common use cases. Common use cases include: - working on remote repositories with git - installing Python packages from PyPi, etc - - access to package registries for languages such as Golang, Rust, etc. + - access to package registries for languages such as Golang, Rust, etc. When following this guide, you will have to execute actions or command on Hawk, but also on your local workstation or laptop. For clarity, examples below will use prompts `local>` and `hawk>`, respectively. @@ -21,7 +21,7 @@ Note however, that the tunnel is open on the remote side. Every user on Hawk wil Tunnels are associated to _ports_. In the following, you will have to specify a port which is referred by the environment variable `$MY_PROXY_PORT`. You may choose the port numbers freely in the suggested range 10000 to 60000. It may happen, that a port is currently used by another user ... just choose a different one. -Ok, let's do it. +Ok, let's do it. The following will open a regular ssh connection to Hawk. In addition, the argument `-D $MY_PROXY_PORT` will establish a reverse dynamic port forwarding tunnel which opens at port `$MY_PROXY_PORT` on the Hawk side and connects to a SOCKS5 proxy on your local side. ```bash @@ -41,7 +41,7 @@ Requirements: Most applications which support https or http protocols can use proxies. Most of them will take the proxy from the environment variables `$https_proxy` and `$http_proxy`. Sometimes, you will have to specify the proxy through command line arguments. -Example usage: +Example usage: ```bash # set up proxy with ssh and continue in the terminal which just opened hawk> MY_PROXY_PORT=XXXX # choose same port as above @@ -59,9 +59,10 @@ hawk> # close terminal to close reverse tunnel when done Most of the other use cases will build on the usage of these environment variables. Therefore we recommend to set them in you `.bashrc`. ==**TODO: do we recommend this?**== + ## Installing Python packages with pip -Requirements: +Requirements: - set up a proxy with ssh as describe in [this section](#setting-up-a-proxy-with-ssh) - set https proxy variables as describe in [this section](#httpshttp-proxy-variables) @@ -87,13 +88,14 @@ If you get error messages related to missing SOCKS5 support in pip, do hawk> python3 -m pip install /sw/general/x86_64/development/python/share/PySocks-1.7.1-py3-none-any.whl ``` + ## Using proxy with git Git essentially supports two [protocols](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols) for communication with remote repositories: - HTTP protocol - SSH protocol -Both protocols can routed through a SOCKS5 proxy. +Both protocols can routed through a SOCKS5 proxy. ==**TODO: do we recommend one over the other?**== @@ -135,14 +137,14 @@ Any of these commands may ask you for credentials such as username and password. ### Git with ssh protocol -Requirements: +Requirements: - set up a proxy with ssh as describe in [this section](#setting-up-a-proxy-with-ssh) The other protocol for accessing remote git repositories uses ssh. Repository URLs for this protocol in general look like ```bash [user@]server:[somepath/]project.git ``` -On github.com for instance, it is +On github.com, for instance, it is ```bash git@github.com:user/project.git ```