# Setting up for the wired network in Charité

Since Charité is a hospital, it is relatively strict about connecting to any service from inside to the outside of its internal network. This is a problem when trying to use Gin client using the wired network in Charité.

Here we consider how to work around this problem.

**Having troubles using the proxy-server settings?**: please visit [here](https://gin.g-node.org/larkumlab/LabProxy_Settings/src/master/troubleshooting.md), or create an issue [here](https://gin.g-node.org/larkumlab/LabProxy_Settings/issues).

### Contents

- Too long; Don't want to read (below; for busy people)
- [Concepts about networks](#concepts-about-networks) (protocols, firewall, proxy servers)
- [Problems and workarounds](problems-and-workarounds) (i.e. what to do to use gin client from within Charité)
  - [Setting up the HTTP proxy](#setting-up-the-http-proxy)
  - [Setting up the SSH proxy](#setting-up-the-ssh-proxy)

## Too long; Don't want to read

- Terminal emulators (e.g. `cmd.exe`, or `Terminal.app`) does not appreciate the network settings in System Configuration / Control Panels.
- set the environmental variables `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` explicitly for the terminal emulators.
- use [lab SSH proxy server settings](https://gin.g-node.org/larkumlab/LabProxy_Settings) to let gin client communicate with the Gin server. 

| Name          | Value                             | Description                        |
| ------------- | --------------------------------- | ---------------------------------- |
| `HTTP_PROXY`  | `proxy.charite.de:8080`           | Proxy server for HTTP              |
| `HTTPS_PROXY` | `proxy.charite.de:8080`           | Proxy server for HTTPS             |
| `NO_PROXY`    | `localhost,127.0.0.1,.charite.de` | Domains where no proxy is required |

## Concepts about networks

### Protocols

When two computers talk, both of them have to know how to communicate with each other. A specification on how to talk to different computers is called a **protocol**, and it is like a **language for computers** on a network.

![Protocols](images/protocols.png)

Well-known protocols include:

- HTTP (Hypertext Transfer Protocol): used to transfer web pages
- FTP (File Transfer Protocol): used to transfer files in the ancient ages (but not so frequently used anymore)
- SMTP (Simple Mail Transfer Protocol): used to send e-mails.
- IMAP (Internet Mail Access Protocol): used to manage the online mailbox.
- SSH (Secure Shell): used to control the remote system

### Firewall

In corporate internal networks, one must not be slack about information security. "Easy come, easy go" strategy can result in privacy / legal violations.

![Potential risk](images/nowall.png)

So, typically **all the connections between the inside and the outside of the network is blocked**. This is why you cannot access any internet website without a proper setting, while you can access e.g. http://intranet.charite.de freely, from the wired connection in Charité.

![Firewall](images/withwall.png)

This barrier made between the inside and the outside of the network is called a **firewall**.

### Proxy server

But it would be extremely uncomfortable if you cannot have access to any web pages from Charité wired network. 

To avoid this problem, there is often a computer within the intranet:

- that is **allowed to perform communication with the outside**
- that has a **capability of mediating communications between computers inside the intranet from computers outside of the intranet**.

Thus, a computer inside the intranet can ask this computer to work as a proxy in communication with a computer outside, and thereby bypass the firewall. The role of this computer is therefore called a **proxy service**, and this computer is called a **proxy server**.

![Proxy server](images/proxy.png)

What is good about setting up a proxy server? One advantage is that **one can restrict the protocols used for communication**. For example, the SSH protocol is used for controlling remote computers, so allowing this protocol can be really dangerous. On the other hand, the HTTP protocol for requesting web pages on the remote servers is less harmful. So a proxy server (including the one in Charité) typically allows communications over the HTTP protocol, and not over the SSH.

Another benefit is that **one can watch and control all the (HTTP) communications with the outside**, in cases it is really required. Suppose that it is announced that a server in Estonia transfers a malicious program over the HTTP protocol. Then you can set the proxy server to block connections specifically to this server, without sending out lots of e-mails asking for cautious internet uses. Also, through logging what computer connects to what server in the world, it may become a useful source of information in the future when somebody in Charité commits a cyber crime.

## Problems and workarounds

Here I assume the situation of **permanently setting the PC to use a set of proxy servers**. So note that the solutions would not be appropriate for computers that you move around between your home and the office.

### Setting up the HTTP proxy

When you use internet browsers (Chrome, Firefox, Safari, Edge...), they normally appreciate the system-wide proxy-server settings i.e. in System Configuration or Control Panels.

![Web browsers vs terminal emulators](images/settings.png)

However, gin client works from terminal emulators (`cmd.exe` or `Terminal.app`, for example), and terminal emulators do not check what is on System Configuration. So you cannot connect to e.g. https://www.google.com/ from a terminal emulator without explicitly setting the HTTP proxy server.

In doing so, the following **environment variables** must be set:

| Name          | Value                             | Description                        |
| ------------- | --------------------------------- | ---------------------------------- |
| `HTTP_PROXY`  | `proxy.charite.de:8080`           | Proxy server for HTTP              |
| `HTTPS_PROXY` | `proxy.charite.de:8080`           | Proxy server for HTTPS             |
| `NO_PROXY`    | `localhost,127.0.0.1,.charite.de` | Domains where no proxy is required |

#### Windows: HOWTO HTTP proxy settings

1. [Find the "Environment Variables" window](https://www.techjunkie.com/environment-variables-windows-10/) (depends on the OS version).
2. Add the variables as above (should be fine either as the "system variable" or as the "user variable").

#### Mac: HOWTO HTTP proxy settings

Situations are a bit more complex on the Mac (although we rarely use a desktop Mac).

First, you need to check what type of environment you use (since Apple changes their policy on this point over time).

1. Open `Terminal.app` (enter "terminal" in 🔍Spotlight, and the app suggests Terminal.app to you)
2. Enter `echo $SHELL` (please mind for spelling)

The output should be one of `/bin/tcsh`, `/bin/bash`, or `/bin/zsh`.

##### Bash settings

For the following steps, I first take the case where the output was `/bin/bash`.

Enter the following lines, one after another (probably you can copy and paste the lines):

```bash
echo "export HTTP_PROXY=proxy.charite.de:8080" >>~/.bash_profile
```

```bash
echo "export HTTPS_PROXY=proxy.charite.de:8080" >>~/.bash_profile
```

```bash
echo "export NO_PROXY=localhost,127.0.0.1,.charite.de" >>~/.bash_profile
```

##### Tcsh settings

In the case of `/bin/tcsh`, the syntax differs:

```bash
echo "set HTTP_PROXY=proxy.charite.de:8080" >>~/.tcshrc
```

```bash
echo "set HTTPS_PROXY=proxy.charite.de:8080" >>~/.tcshrc
```

```bash
echo "set NO_PROXY=localhost,127.0.0.1,.charite.de" >>~/.tcshrc
```

##### Zsh settings

Syntax is _almost_ the same for `/bin/zsh`:

```bash
echo "export HTTP_PROXY=proxy.charite.de:8080" >>~/.zshrc
```

```bash
echo "export HTTPS_PROXY=proxy.charite.de:8080" >>~/.zshrc
```

```bash
echo "export NO_PROXY=localhost,127.0.0.1,.charite.de" >>~/.zshrc
```

### Setting up the SSH proxy

By default, SSH communication is by no ways supported from within the Charité firewall to the outside internet. The default proxy server `proxy.charite.de` does not allow any SSH communication.

So a single computer `larkumlab-data-micro.charite.de` was set up and registered as a proxy server for the SSH protocol.

To register this proxy server for gin client:

1. Follow instructions on [the "Lab proxy settings" repository](https://gin.g-node.org/larkumlab/LabProxy_Settings)
2. Install the client by following the instructions [here](https://gin.g-node.org/G-Node/Info/wiki/GIN+CLI+Setup)

