Update README.md
Simon Stürz
parent
94112c0c11
commit
3f683faea6
186
README.md
186
README.md
|
|
@ -1,129 +1,139 @@
|
|||
# nymea remote proxy server
|
||||
----------------------------------------------
|
||||
|
||||
The nymea remote proxy server is the meeting point of nymea servers and nymea clients in order to establishing a secure remote connection.
|
||||
The nymea remote proxy server acts as the rendezvous point between nymea servers and nymea clients and provides a secure tunnel to reach devices that sit behind NAT or firewalled networks.
|
||||
|
||||
# Build
|
||||
## Features
|
||||
|
||||
In order to build the proxy server you need to install the qt default package.
|
||||
- Secure TLS-protected tunnels between nymea instances.
|
||||
- JSON-RPC based control plane with optional monitoring interface.
|
||||
- Usable as system service or launched from a build tree for development.
|
||||
|
||||
apt install qtbase5-dev qtbase5-dev-tools libqt5websockets5-dev libncurses5-dev dpkg-dev debhelper
|
||||
## Requirements
|
||||
|
||||
To build the proxy from source, install the Qt development packages and the helper tools that produce the Debian packages:
|
||||
|
||||
```
|
||||
sudo apt install debhelper dpkg-dev pkg-config qt6-base-dev qt6-base-dev-tools \
|
||||
qt6-websockets-dev libncurses5-dev
|
||||
```
|
||||
|
||||
## Build from source
|
||||
Change into the source directory and run following commands
|
||||
|
||||
$ cd nymea-remoteproxy
|
||||
$ mkdir build
|
||||
$ cd build
|
||||
$ qmake ../
|
||||
$ make -j$(nproc)
|
||||
```
|
||||
cd nymea-remoteproxy
|
||||
mkdir -p build && cd build
|
||||
qmake ../
|
||||
make -j$(nproc)
|
||||
```
|
||||
|
||||
In the build directory you can find the resulting library and binary files.
|
||||
The resulting binaries and libraries will be available in the `build` directory. When running directly from there, the helper libraries must be discoverable:
|
||||
|
||||
If you want to start the proxy server from the build directory, you need to export the library path before starting the application:
|
||||
```
|
||||
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$(pwd)/libnymea-remoteproxy:$(pwd)/libnymea-remoteproxyclient
|
||||
./server/nymea-remoteproxy -c ../nymea-remoteproxy/nymea-remoteproxy.conf
|
||||
```
|
||||
|
||||
$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$(pwd)/libnymea-remoteproxy:$(pwd)/libnymea-remoteproxyclient
|
||||
$ ./server/nymea-remoteproxy -c ../nymea-remoteproxy/nymea-remoteproxy.conf
|
||||
## Install
|
||||
|
||||
### From repository
|
||||
|
||||
# Install
|
||||
Official nymea packages are available:
|
||||
|
||||
## From repository
|
||||
There is a public version available in the nymea repository.
|
||||
```
|
||||
sudo apt install nymea-remoteproxy nymea-remoteproxy-tunnelclient nymea-remoteproxy-monitor
|
||||
```
|
||||
|
||||
$ apt install nymea-remoteproxy nymea-remoteproxy-tunnelclient nymea-remoteproxy-monitor
|
||||
The installation starts the `nymea-remoteproxy.service` systemd unit and also installs a test client.
|
||||
|
||||
This will install a systemd service called `nymea-remoteproxy.service` and the client application for testing.
|
||||
### From build directory
|
||||
|
||||
## From build directory
|
||||
```
|
||||
sudo make install
|
||||
```
|
||||
|
||||
Simply run following command in the build dir:
|
||||
## Configuration
|
||||
|
||||
$ sudo make install
|
||||
The package ships `/etc/nymea/nymea-remoteproxy.conf` which can be used verbatim or as a template:
|
||||
|
||||
# Configure
|
||||
```
|
||||
[ProxyServer]
|
||||
name=nymea-remoteproxy
|
||||
writeLogs=false
|
||||
logFile=/var/log/nymea-remoteproxy.log
|
||||
logEngineEnabled=false
|
||||
monitorSocket=/tmp/nymea-remoteproxy-monitor.sock
|
||||
jsonRpcTimeout=10000
|
||||
inactiveTimeout=8000
|
||||
|
||||
The package will deliver a default configuration file with following content (`/etc/nymea/nymea-remoteproxy.conf`):
|
||||
|
||||
[ProxyServer]
|
||||
name=nymea-remoteproxy
|
||||
writeLogs=false
|
||||
logFile=/var/log/nymea-remoteproxy.log
|
||||
logEngineEnabled=false
|
||||
monitorSocket=/tmp/nymea-remoteproxy-monitor.sock
|
||||
jsonRpcTimeout=10000
|
||||
inactiveTimeout=8000
|
||||
|
||||
[SSL]
|
||||
enabled=false
|
||||
certificate=/etc/ssl/certs/ssl-cert-snakeoil.pem
|
||||
certificateKey=/etc/ssl/private/ssl-cert-snakeoil.key
|
||||
certificateChain=
|
||||
|
||||
[UnixSocketServerTunnelProxy]
|
||||
unixSocketFileName=/run/nymea-remoteproxy.socket
|
||||
|
||||
[WebSocketServerTunnelProxy]
|
||||
host=127.0.0.1
|
||||
port=2212
|
||||
|
||||
[TcpServerTunnelProxy]
|
||||
host=127.0.0.1
|
||||
port=2213
|
||||
|
||||
[SSL]
|
||||
enabled=false
|
||||
certificate=/etc/ssl/certs/ssl-cert-snakeoil.pem
|
||||
certificateKey=/etc/ssl/private/ssl-cert-snakeoil.key
|
||||
certificateChain=
|
||||
|
||||
## Test coverage report
|
||||
[UnixSocketServerTunnelProxy]
|
||||
unixSocketFileName=/run/nymea-remoteproxy.socket
|
||||
|
||||
If you want to create a line coverage report from the tests simply run following command in the source directory:
|
||||
[WebSocketServerTunnelProxy]
|
||||
host=127.0.0.1
|
||||
port=2212
|
||||
|
||||
> Note: run `qmake` with the argument `CONFIG+=converage` in order to generate coverage data for the tests. Then run the tests before creating the coverage report.
|
||||
[TcpServerTunnelProxy]
|
||||
host=127.0.0.1
|
||||
port=2213
|
||||
```
|
||||
|
||||
$ apt install lcov gcovr
|
||||
$ ./create-coverage-html.sh
|
||||
## Test coverage
|
||||
|
||||
The resulting coverage report will be place in the `coverage-html` directory.
|
||||
To generate a line coverage report:
|
||||
|
||||
# Testing a local server
|
||||
- Run `qmake CONFIG+=coverage` and execute the tests to produce the `.gcno`/`.gcda` data.
|
||||
- Install tooling and generate the HTML report:
|
||||
|
||||
With following steps you can test a local instance with a self signed certificate.
|
||||
```
|
||||
sudo apt install lcov gcovr
|
||||
./create-coverage-html.sh
|
||||
```
|
||||
|
||||
## Start the server
|
||||
The HTML output lives in `coverage-html/`.
|
||||
|
||||
In order to test a connection and play with the server API, you can install the proxy server on your machine and try to connect to it.
|
||||
## Testing a local server
|
||||
|
||||
$ sudo apt update
|
||||
$ sudo apt install nymea-remoteproxy nymea-remoteproxy-tunnelclient
|
||||
You can experiment with a local instance by issuing a self-signed certificate and pointing the proxy to it.
|
||||
|
||||
Once installed, the `nymea-remoteproxy` will start automatically using the default configurations shipped in `/etc/nymea/nymea-remoteproxy.conf`.
|
||||
Using this file allowes you to configure the server for your test purposes.
|
||||
```
|
||||
sudo apt update
|
||||
sudo apt install nymea-remoteproxy nymea-remoteproxy-tunnelclient
|
||||
```
|
||||
|
||||
The only thing you need is a certificate, which can be loaded from the server. The server does not support insecure connection for now. If you don't have any certificate, you can create one for testing.
|
||||
After installation the daemon starts automatically using `/etc/nymea/nymea-remoteproxy.conf`, which you can adapt for local testing. Create a throwaway certificate:
|
||||
|
||||
> *Note:* you can enter whatever you like for the certificate.
|
||||
```
|
||||
cd /tmp
|
||||
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
|
||||
-keyout test-proxy-certificate.key \
|
||||
-out test-proxy-certificate.crt
|
||||
sudo cp test-proxy-certificate.crt /etc/ssl/certs/
|
||||
sudo cp test-proxy-certificate.key /etc/ssl/private/
|
||||
```
|
||||
|
||||
$ cd /tmp/
|
||||
$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout test-proxy-certificate.key -out test-proxy-certificate.crt
|
||||
Adjust the config:
|
||||
|
||||
Now place the certificate and the key where they belong:
|
||||
```
|
||||
certificate=/etc/ssl/certs/test-proxy-certificate.crt
|
||||
certificateKey=/etc/ssl/private/test-proxy-certificate.key
|
||||
```
|
||||
|
||||
$ sudo cp /tmp/test-proxy-certificate.crt /etc/ssl/certs/
|
||||
$ sudo cp /tmp/test-proxy-certificate.key /etc/ssl/private/
|
||||
Restart manually for verbose output:
|
||||
|
||||
Change following configuration in the `/etc/nymea/nymea-remoteproxy.conf`:
|
||||
```
|
||||
sudo systemctl stop nymea-remoteproxy.service
|
||||
sudo nymea-remoteproxy -c /etc/nymea/nymea-remoteproxy.conf --verbose
|
||||
```
|
||||
|
||||
...
|
||||
certificate=/etc/ssl/certs/test-proxy-certificate.crt
|
||||
certificateKey=/etc/ssl/private/test-proxy-certificate.key
|
||||
...
|
||||
## License
|
||||
|
||||
Now stop the proxy server and start it manually:
|
||||
|
||||
$ sudo systemctl stop nymea-remoteproxy.service
|
||||
|
||||
$ sudo nymea-remoteproxy -c /etc/nymea/nymea-remoteproxy --verbose
|
||||
|
||||
|
||||
# License
|
||||
|
||||
This is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License.
|
||||
The nymea-remoteproxy server, monitoring tools, and tunnel client are distributed under the terms of the GNU General Public License version 3.
|
||||
|
||||
The reusable libraries located in `libnymea-remoteproxy` and `libnymea-remoteproxyclient` are provided under the GNU Lesser General Public License version 3 (or later).
|
||||
See `LICENSE.GPL3` and `LICENSE.LGPL3` for the full texts.
|
||||
|
|
|
|||
Loading…
Reference in New Issue