Skip to content

GitLab

Commit 2fead9a7 authored by Giacomo Strangolino's avatar Giacomo Strangolino
Browse files

Update README.md

parent 5e4237c0
Hide whitespace changes
Inline Side-by-side
README.md
View file @ 2fead9a7
# canone3
websocket and sse server to access Tango (and more) control systems from anywhere
The project architecture has been redesigned and this repository must be considered obsolete.
### Additional readings
Old canone3 has been replaced by three ingredients:
1. https://gitlab.elettra.eu/puma/server/canone3/blob/master/nchan-setup/nginx%2Bnchan-install.md
2. https://gitlab.elettra.eu/puma/server/canone3/blob/master/nchan-setup/ssl.md
3. https://gitlab.elettra.eu/puma/server/canone3/blob/master/nchan-setup/websocket-server.md
4. https://gitlab.elettra.eu/puma/server/canone3/blob/master/nchan-setup/ubuntu-install.md
1. [caserver-proxy](https://gitlab.elettra.eu/puma/server/caserver-proxy)
2. [caserver](https://gitlab.elettra.eu/puma/server/caserver/) as **sync instance** (synchronously replies to client requests)
3. [caserver](https://gitlab.elettra.eu/puma/server/caserver/) as **async instance** (nchan publisher for source monitoring)
#### Design rationale
5. https://gitlab.elettra.eu/puma/server/canone3/blob/master/rationale/methods.md
### Dependencies
1. nlohmann-json (https://github.com/nlohmann/json)
We require a recent version, 3.7.x at the moment of writing this document
Available through the package manager:
- apt-get install nlohmann-json-dev (debian, ubuntu) -- ubuntu 18.04 ships a too old version (2.1.1)
- pacman -S community/nlohmann-json (arch) -- version 3.7.3-4 at the moment of writing this document
Please refer to the installation instructions below for more details.
2. curl
3. cumbia, cumbia-tango, cumbia-epics (optional)
- sources: https://github.com/ELETTRA-SincrotroneTrieste/cumbia-libs
- documentation: https://elettra-sincrotronetrieste.github.io/cumbia-libs/
4. openssl libraries
#### <a href="install_instructions"></a>Installation instructions
Here installation instructions will be discussed.
bla bla bla...
### Rationale
Here design rationale will be discussed.
bla bla bla...
#### Data format
Data is delivered in Json format, whatever is the source.
## Usage
The [installation instructions](#install_instructions) cover the build and installation process of the *canone3* service
and its dependencies, as well as setting up the necessary *paths* for binary execution and
library deps. Once everything is configured (in the present documentation ~/.bashrc is employed),
we have to check the *nginx.conf* file for some details.
### Notes
According to the instructions in the aforementioned page, you will end up
with these locations as far as the installed files are concerned (example user: *controls*):
- *apps bin dir* /home/controls/.local/bin
will contain *caserver* and *cumbia-websocket-proxy-server*
- *nginx* /home/controls/.local/nginx
executable: */home/controls/.local/nginx/sbin/nginx*
- *cumbia libs prefix*: /home/controls/.local/cumbia-libs
- *nginx.conf*, in this tutorial we use the one provided by the *canone3* git distribution,
under the *nchan-setup* dir.
### nginx listen port
Open the *nginx.conf* file you intend to use (e.g. *nginx.conf*, provided by the *canone3*
git distribution under the *nchan-setup* dir) and look for the *listen* directive(s)
under the server section:
```bash
server {
listen 8001;
listen 8443 ssl;
```
That is the port(s) used by *clients* to connect to *nginx*.
Please note that alongside a secure https 8443 port, an unencrypted http
server is listening on the 8001 port number.
### upstream service (caservice) listen port
In the *nginx.conf* file, look for the following:
```bash
location = /upstream/sub {
proxy_pass http://127.0.0.1:9292/sub;
```
port *9292* is the port where *caservice* shall be listening.
### SSL certificate
Under the *server* section, locate the following *ssl_certificate...* directives:
```bash
server {
listen 8443 ssl;
server_name woody.elettra.eu;
ssl_certificate /etc/ssl/certs/woody-Elettra_Almighty-cert.pem;
ssl_certificate_key /home/giacomo/devel/utils/git/canone3/ssl-cert/woody-Elettra_Almighty-key.pem;
```
Suppose we already have *apache2* using an SSL certificate. We choose to reuse it.
We must locate
- the certificate
- the private key
Inspecting the file *default-ssl.conf* under */etc/apache2*, we find these two configuration keys:
```bash
SSLCertificateFile /etc/ssl/certs/myhost-dev_organisation_eu.crt
SSLCertificateKeyFile /etc/ssl/private/myhost-dev_organisation_eu.key
```
The two options
- ssl_certificate and
- ssl_certificate_key
must be adapted accordingly in the *nginx.conf* file.
/etc/ssl/certs/pwma-dev_elettra_eu.crt
/etc/ssl/private/pwma-dev_elettra_eu.key
### Start nginx
We are ready to start nginx
> sudo /home/controls/.local/nginx/sbin/nginx -c /home/controls/devel/canone3/nchan-setup/nginx.conf
If everything went smooth, *ps aux |grep nginx* should show these two entries:
```bash
root 1204 0.0 0.0 173328 3552 ? Ss 14:11 0:00 nginx: master process /home/controls/.local/nginx/sbin/nginx -c /home/controls/devel/canone3/nchan-setup/nginx.conf
nobody 1205 0.0 0.1 178112 6592 ? S 14:11 0:00 nginx: worker process
```
Due to our configuration, *nginx* will respond on http port 8001 and https 8443.
### Start caserver
The compulsory arguments are
- -p listen port (8001 or 8443)
- -u *nginx* url
- -a *authentication url*: where to send session information (cookies) for write operations, that require authentication
1. using *https*:
> caserver -p 9292 -u "https://pwma-dev.elettra.eu:8443/pub/" -a "https://pwma-dev.elettra.eu/session.php"
2. using *http*:
> caserver -p 9292 -u "http://pwma-dev.elettra.eu:8001/pub/" -a "https://pwma-dev.elettra.eu/session.php"
#### Command line options
- -h bind_address specify the bind address
- -c ssl_certificate
- -k do not verify ssl peer (same as curl -k)
- -d daemonize (fork and send to background). Cannot output on console in this case.
- -f logfile.log log on the given *logfile.log*. The directory hosting the file must be writable.
- -f syslog send messages to the system logger
- -w log level warning
- -i log level info
- -v log level debug
If you want *caserver* to print additional debug output on the console
you shall export one or both variables ahead of the command:
> export CUMBIA_PRINT=1
> export CUMBIA_CUPRINTF=1
## Interface to caserver
Please refer to the documentation in [rationale/methods.md](https://gitlab.elettra.eu/puma/server/canone3/blob/master/rationale/methods.md)
## 2. C++ clients
Since cumbia version *1.2.0* the *http* module supports canone3.
#### cumbia read
> cumbia read --url "http://woody.elettra.eu:8001/myreadchan" "test/device/1/double_scalar"
> cumbia read -l=medium --url "http://woody.elettra.eu:8001/myreadchan" "test/device/1/double_scalar"
The -l medium will print data bounds when available.
#### cumbia client
> cumbia client -u "http://woody.elettra.eu:8001/myclichan" "hokuto:20000/test/device/1/double_scalar"
#### example in cumbia-http module dir
Under the cumbia-http/examples/test you will find a small application that reads and writes some
variables to a *TangoTest* device given on the command line argument.
> cd path/to/cumbia-src/cumbia-http/examples/test
> qmake
> cuuimake -j9
> ./bin/test -u http://woody.elettra.eu:8001/testchan test/device/1
### error report
exemple of error log
```bash
2021-09-17 10:54:29 LOG_INFO OK
2021-09-17 10:55:00 LOG_ERR TypeError: NetworkError when attempting to fetch resource.
```
Refer to each project INSTALL.md file for installation instructions.
Please note that both projects need [caserver-lib](https://gitlab.elettra.eu/puma/server/caserver-lib) as prerequisite, since they
share common classes and functions
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment