diff --git a/README.md b/README.md index 95ccf12..ce9d8c3 100644 --- a/README.md +++ b/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.