doc/manual/connectors.rst
author Andrey Skvortsov <andrej.skvortzov@gmail.com>
Mon, 07 Jan 2019 20:32:40 +0000
branchpy3-fix
changeset 2564 186f0137b0ca
parent 1455 4ba27ed51e48
permissions -rw-r--r--
Close branch py3-fix.
1455
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
     1
Beremiz and Beremiz_service connectors 
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
     2
======================================
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
     3
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
     4
To connect a PLC, Beremiz provides 2 types of connectors :
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
     5
 * a Pyro connector
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
     6
 * a WAMP connector
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
     7
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
     8
To configure the connection, you have to set the *URI_location* in your project Config tab according to this documentation. 
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
     9
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    10
The Pyro connector
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    11
----------------------------
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    12
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    13
Pyro is an advanced and powerful Distributed Object Technology system written entirely in Python.
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    14
Beremiz_service spawns a Pyro server, serving a PLCObject (see runtime/PLCObject.py). Therefore, Beremiz acts as a Pyro client.
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    15
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    16
TODO:: link to PLCObject API documentation
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    17
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    18
URI_location :
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    19
 * LOCAL:// is a facility that starts the PLC service locally and connect Beremiz to it via Pyro.
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    20
   This is intended for use in development stage.
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    21
 * PYRO://<ip:port> normal connection to a remote PLC. PLC default port is 3000.
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    22
 * PYROS://<ip:port> SSL connection to a remote PLC, see below.
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    23
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    24
more information about Pyro can be found on http://pythonhosted.org//Pyro/1-intro.html
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    25
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    26
===========================
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    27
Setup a Pyro SSL connection
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    28
===========================
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    29
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    30
Pyro v3 has a limited TLS/SSL support based on m2crypto. Pyro v4 had dropped it.
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    31
In order to have a full and reliable SSL, we recommand to use a TLS/SSL wrapper as nginx, stub or stunnel.
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    32
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    33
--------------------
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    34
TLS-PSK with stunnel
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    35
--------------------
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    36
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    37
In this example, we setup a simple TLS-PSK connection according to rfc4279.
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    38
This ciphersuite avoid the need for public key operations and certificate management.
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    39
It is perfect for a performance-constrained environments with limited CPU power as a PLC.
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    40
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    41
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    42
Needed :
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    43
 * stunnel >= 5.09
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    44
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    45
verify openssl support for PSK cipher::
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    46
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    47
    openssl ciphers -v 'PSK'
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    48
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    49
----------------------
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    50
Client setup (Beremiz)
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    51
----------------------
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    52
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    53
You need to choose an identity for your client, here *client1*.
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    54
generate a valid and strong key::
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    55
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    56
    $ echo client1:$(openssl rand -base64 48) > pskclient1.txt
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    57
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    58
write a stunnel client configuration file *stunnel-client.conf*::
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    59
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    60
    output = stunnel-client.log
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    61
    client = yes
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    62
    
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    63
    [beremiz]
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    64
    accept = 3002
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    65
    connect = [PLC]:3001
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    66
    PSKidentity = client1
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    67
    PSKsecrets = pskclient1.txt
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    68
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    69
start stunnel client side::
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    70
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    71
    stunnel stunnel-client.conf
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    72
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    73
You could now connect beremiz with classic URI_location = PYRO://127.0.0.1:3002
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    74
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    75
--------------------
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    76
Server setup (PLC)
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    77
--------------------
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    78
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    79
import the client key in a keyfile psk.txt, concatening all client key.
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    80
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    81
write a stunnel server  configuration file *stunnel-server.conf*::
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    82
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    83
    output = stunnel-server.log
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    84
    
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    85
    [beremiz]
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    86
    accept = 3001
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    87
    connect = 127.0.0.1:3000
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    88
    PSKsecrets = psk.txt
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    89
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    90
start stunnel server side::
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    91
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    92
    stunnel stunnel-server.conf
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    93
    
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    94
more documentation on stunnel http://www.stunnel.org/docs.html
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    95
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    96
The WAMP connector
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    97
------------------
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    98
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
    99
WAMP is an open standard WebSocket subprotocol that provides two application messaging 
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
   100
patterns in one unified protocol: Remote Procedure Calls + Publish & Subscribe.
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
   101
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
   102
Beremiz WAMP connector implementation uses Autobahn and crossbar.
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
   103
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
   104
URI_location :
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
   105
	* WAMP://127.0.0.1:8888#Automation#2534667845
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
   106
4ba27ed51e48 add pyrossl client side
Ronan Bignaux <r.bignaux@rbi.io>
parents:
diff changeset
   107
more information about WAMP can be found on http://wamp.ws/