140 lines
3.7 KiB
Markdown
140 lines
3.7 KiB
Markdown
# nymea remote proxy server
|
|
|
|
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.
|
|
|
|
## Features
|
|
|
|
- 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.
|
|
|
|
## 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
|
|
|
|
```
|
|
cd nymea-remoteproxy
|
|
mkdir -p build && cd build
|
|
qmake ../
|
|
make -j$(nproc)
|
|
```
|
|
|
|
The resulting binaries and libraries will be available in the `build` directory. When running directly from there, the helper libraries must be discoverable:
|
|
|
|
```
|
|
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
|
|
|
|
Official nymea packages are available:
|
|
|
|
```
|
|
sudo 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.
|
|
|
|
### From build directory
|
|
|
|
```
|
|
sudo make install
|
|
```
|
|
|
|
## Configuration
|
|
|
|
The package ships `/etc/nymea/nymea-remoteproxy.conf` which can be used verbatim or as a template:
|
|
|
|
```
|
|
[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
|
|
```
|
|
|
|
## Test coverage
|
|
|
|
To generate a line coverage report:
|
|
|
|
- Run `qmake CONFIG+=coverage` and execute the tests to produce the `.gcno`/`.gcda` data.
|
|
- Install tooling and generate the HTML report:
|
|
|
|
```
|
|
sudo apt install lcov gcovr
|
|
./create-coverage-html.sh
|
|
```
|
|
|
|
The HTML output lives in `coverage-html/`.
|
|
|
|
## Testing a local server
|
|
|
|
You can experiment with a local instance by issuing a self-signed certificate and pointing the proxy to it.
|
|
|
|
```
|
|
sudo apt update
|
|
sudo apt install nymea-remoteproxy nymea-remoteproxy-tunnelclient
|
|
```
|
|
|
|
After installation the daemon starts automatically using `/etc/nymea/nymea-remoteproxy.conf`, which you can adapt for local testing. Create a throwaway 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/
|
|
```
|
|
|
|
Adjust the config:
|
|
|
|
```
|
|
certificate=/etc/ssl/certs/test-proxy-certificate.crt
|
|
certificateKey=/etc/ssl/private/test-proxy-certificate.key
|
|
```
|
|
|
|
Restart manually for verbose output:
|
|
|
|
```
|
|
sudo systemctl stop nymea-remoteproxy.service
|
|
sudo nymea-remoteproxy -c /etc/nymea/nymea-remoteproxy.conf --verbose
|
|
```
|
|
|
|
## 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.
|