Everyware Cloud Developer's Hub

Everyware Cloud (EC) is an IoT Integration Platform distributed and supported by Eurotech. Based on Eclipse Kapua, Everyware Cloud offers an open and modular IoT Cloud Platform based on a micro-services architecture. Everyware Cloud provides device management, diagnostics, provisioning, remote access of IoT gateways and devices and integration services for the telemetry data.

Get Started

Administration

Admin User Configuration

The first and most important action to take after completing the installation is to change the credentials of the admin user. To do so login to the Console with the default EC credentials.

Username

ec-sys

Password

ec-password

Once you are logged in, click over the username located in the top right portion of the window and select Change password. The password for ec-sys should match the one configured in the Secrets section of Installation.

Certificates

At first access the EC auto generates two certificates used for authentication and message signing. These certificates can be replaced if needed; as a good practice, for a pre-production and production environments consider to install the correct certificates before start connecting devices, this will save time later. For more details regarding certificate management refer to section Certificates

VPN Configuration

Currently, to configure a running VPN server in EC you need to insert some values directly into the database.

First, create a VPN server entry. Change the host address and the port based on your environment configuration.

INSERT INTO `vpn_server` VALUES (1,1,NOW(),1,NOW(),1,'Demo VPN','vpn.demo.example.com',31194,0,NULL,NULL);

Then you can insert the OpenVPN configuration files that will be downloaded by the users or sent to the devices to establish connections.

INSERT INTO `vpn_configuration` VALUES (1,1,'2017-12-06 16:33:47',1,'2017-12-06 16:33:47',1,1,'clientOvpn','<CONFIG_DATA>',NULL,NULL,NULL),(2,1,'2017-12-06 16:33:47',1,'2017-12-06 16:33:47',1,1,'clientOvpnSafe','<SAFE_CONFIG_DATA>',NULL,NULL,NULL),(3,1,'2017-12-06 16:33:47',1,'2017-12-06 16:33:47',1,1,'clientDevice','<DEVICE_CONFIG_DATA>',NULL,NULL,NULL);

The three CONFIG_DATA cells need to be filled with the content of the following template files contextualised to your environments.

The templates contain various placeholders that need to be replaced. PLACEHOLDER_VPN_HOST and PLACEHOLDER_VPN_PORT need to be changed to reflect the values you previously set in the vpn_server table.
PLACEHOLDER_CA_CHAIN is a placeholder the PEM formatted CA chain certificates, of which your certificate is the leaf.
PLACEHOLDER_CERT_SUBJECT has to be replaced with the subject of your certificate. For example C=XX, ST=YY, L=ZZZ ZZZ, O=Example Company, CN=*.example.com. Note that for the device configuration you will need to rewrite it in the following format: /C=XX/ST=YY/L=ZZZ_ZZZ/O=Example_Company/CN=_.example.com.

##############################################
# Sample client-side OpenVPN 2.0 config file #
# for connecting to multi-client server.     #
#                                            #
# This configuration can be used by multiple #
# clients, however each client should have   #
# its own cert and key files.                #
#                                            #
# On Windows, you might want to rename this  #
# file so it has a .ovpn extension           #
##############################################

# Specify that we are a client and that we
# will be pulling certain config file directives
# from the server.
client

# Use the same setting as you are using on
# the server.
# On most systems, the VPN will not function
# unless you partially or fully disable
# the firewall for the TUN/TAP interface.
;dev tap
dev tun

# Windows needs the TAP-Win32 adapter name
# from the Network Connections panel
# if you have more than one.  On XP SP2,
# you may need to disable the firewall
# for the TAP adapter.
;dev-node MyTap

# Are we connecting to a TCP or
# UDP server?  Use the same setting as
# on the server.
;proto tcp
proto udp

# The hostname/IP and port of the server.
# You can have multiple remote entries
# to load balance between the servers.
remote PLACEHOLDER_VPN_HOST PLACEHOLDER_VPN_PORT

# Choose a random host from the remote
# list for load-balancing.  Otherwise
# try hosts in the order specified.
;remote-random

# Keep trying indefinitely to resolve the
# host name of the OpenVPN server.  Very useful
# on machines which are not permanently connected
# to the internet such as laptops.
resolv-retry infinite

# Most clients don't need to bind to
# a specific local port number.
nobind

# Downgrade privileges after initialization (non-Windows only)
;user nobody
;group nobody

# Try to preserve some state across restarts.
persist-key
persist-tun

# If you are connecting through an
# HTTP proxy to reach the actual OpenVPN
# server, put the proxy server/IP and
# port number here.  See the man page
# if your proxy server requires
# authentication.
;http-proxy-retry # retry on connection failures
;http-proxy [proxy server] [proxy port #]

# Wireless networks often produce a lot
# of duplicate packets.  Set this flag
# to silence duplicate packet warnings.
;mute-replay-warnings

# SSL/TLS parms.
# See the server config file for more
# description.  It's best to use
# a separate .crt/.key file pair
# for each client.  A single ca
# file can be used for all clients.
;ca ca.crt
;cert client.crt
;key client.key

# Verify server certificate by checking
# that the certicate has the nsCertType
# field set to "server".  This is an
# important precaution to protect against
# a potential attack discussed here:
#  http://openvpn.net/howto.html#mitm
#
# To use this feature, you will need to generate
# your server certificates with the nsCertType
# field set to "server".  The build-key-server
# script in the easy-rsa folder will do this.
;ns-cert-type server

# If a tls-auth key is used on the server
# then every client must also have the key.
;tls-auth ta.key 1

tls-cipher DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-SHA256:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA:DHE-RSA-CAMELLIA-256-CBC-SHA:DHE-RSA-CAMELLIA-128-CBC-SHA:AES256-SHA:AES128-SHA

verify-x509-name "PLACEHOLDER_CERT_SUBJECT"

# Select a cryptographic cipher.
# If the cipher option is used on the server
# then you must also specify it here.
cipher AES-128-CBC

auth SHA256

# Enable compression on the VPN link.
# Don't enable this unless it is also
# enabled in the server config file.
comp-lzo

# Set log file verbosity.
verb 3

# Silence repeating messages
;mute 20

# Everyware Cloud Security
auth-user-pass

# Disable key renegotiation
reneg-sec 0

# Everyware Cloud Network Configuration
inactive 300
ping 10
ping-exit 60

# Notify disconnect to server (UDP)
explicit-exit-notify 1

<ca>
PLACEHOLDER_CA_CHAIN
</ca>
##############################################
# Sample client-side OpenVPN 2.0 config file #
# for connecting to multi-client server.     #
#                                            #
# This configuration can be used by multiple #
# clients, however each client should have   #
# its own cert and key files.                #
#                                            #
# On Windows, you might want to rename this  #
# file so it has a .ovpn extension           #
##############################################

# Specify that we are a client and that we
# will be pulling certain config file directives
# from the server.
client

# Use the same setting as you are using on
# the server.
# On most systems, the VPN will not function
# unless you partially or fully disable
# the firewall for the TUN/TAP interface.
;dev tap
dev tun

# Windows needs the TAP-Win32 adapter name
# from the Network Connections panel
# if you have more than one.  On XP SP2,
# you may need to disable the firewall
# for the TAP adapter.
;dev-node MyTap

# Are we connecting to a TCP or
# UDP server?  Use the same setting as
# on the server.
;proto tcp
proto udp

# The hostname/IP and port of the server.
# You can have multiple remote entries
# to load balance between the servers.
remote PLACEHOLDER_VPN_HOST PLACEHOLDER_VPN_PORT

# Choose a random host from the remote
# list for load-balancing.  Otherwise
# try hosts in the order specified.
;remote-random

# Keep trying indefinitely to resolve the
# host name of the OpenVPN server.  Very useful
# on machines which are not permanently connected
# to the internet such as laptops.
resolv-retry infinite

# Most clients don't need to bind to
# a specific local port number.
nobind

# Downgrade privileges after initialization (non-Windows only)
;user nobody
;group nobody

# Try to preserve some state across restarts.
persist-key
persist-tun

# If you are connecting through an
# HTTP proxy to reach the actual OpenVPN
# server, put the proxy server/IP and
# port number here.  See the man page
# if your proxy server requires
# authentication.
;http-proxy-retry # retry on connection failures
;http-proxy [proxy server] [proxy port #]

# Wireless networks often produce a lot
# of duplicate packets.  Set this flag
# to silence duplicate packet warnings.
;mute-replay-warnings

# SSL/TLS parms.
# See the server config file for more
# description.  It's best to use
# a separate .crt/.key file pair
# for each client.  A single ca
# file can be used for all clients.
;ca ca.crt
;cert client.crt
;key client.key

# Verify server certificate by checking
# that the certicate has the nsCertType
# field set to "server".  This is an
# important precaution to protect against
# a potential attack discussed here:
#  http://openvpn.net/howto.html#mitm
#
# To use this feature, you will need to generate
# your server certificates with the nsCertType
# field set to "server".  The build-key-server
# script in the easy-rsa folder will do this.
;ns-cert-type server

# If a tls-auth key is used on the server
# then every client must also have the key.
;tls-auth ta.key 1

tls-cipher DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-SHA256:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA:DHE-RSA-CAMELLIA-256-CBC-SHA:DHE-RSA-CAMELLIA-128-CBC-SHA:AES256-SHA:AES128-SHA

verify-x509-name "PLACEHOLDER_CERT_SUBJECT"

# Select a cryptographic cipher.
# If the cipher option is used on the server
# then you must also specify it here.
cipher AES-128-CBC

auth SHA256

# Enable compression on the VPN link.
# Don't enable this unless it is also
# enabled in the server config file.
comp-lzo

# Set log file verbosity.
verb 3

# Silence repeating messages
;mute 20

# Everyware Cloud Security
auth-user-pass

# Disable key renegotiation
reneg-sec 0

# Everyware Cloud Network Configuration
inactive 300
ping 10
ping-exit 60

# Route all the client traffic through the VPN
redirect-gateway def1

# Notify disconnect to server (UDP)
explicit-exit-notify 1

<ca>
PLACEHOLDER_CA_CHAIN
</ca>
##############################################
# Sample client-side OpenVPN 2.0 config file #
# for connecting to multi-client server.     #
#                                            #
# This configuration can be used by multiple #
# clients, however each client should have   #
# its own cert and key files.                #
#                                            #
# On Windows, you might want to rename this  #
# file so it has a .ovpn extension           #
##############################################

# Specify that we are a client and that we
# will be pulling certain config file directives
# from the server.
client

# Use the same setting as you are using on
# the server.
# On most systems, the VPN will not function
# unless you partially or fully disable
# the firewall for the TUN/TAP interface.
;dev tap
dev tun

# Windows needs the TAP-Win32 adapter name
# from the Network Connections panel
# if you have more than one.  On XP SP2,
# you may need to disable the firewall
# for the TAP adapter.
;dev-node MyTap

# Are we connecting to a TCP or
# UDP server?  Use the same setting as
# on the server.
;proto tcp
proto udp

# The hostname/IP and port of the server.
# You can have multiple remote entries
# to load balance between the servers.
remote PLACEHOLDER_VPN_HOST PLACEHOLDER_VPN_PORT

# Choose a random host from the remote
# list for load-balancing.  Otherwise
# try hosts in the order specified.
;remote-random

# Keep trying indefinitely to resolve the
# host name of the OpenVPN server.  Very useful
# on machines which are not permanently connected
# to the internet such as laptops.
resolv-retry infinite

# Most clients don't need to bind to
# a specific local port number.
nobind

# Downgrade privileges after initialization (non-Windows only)
;user nobody
;group nobody

# Try to preserve some state across restarts.
persist-key
persist-tun

# If you are connecting through an
# HTTP proxy to reach the actual OpenVPN
# server, put the proxy server/IP and
# port number here.  See the man page
# if your proxy server requires
# authentication.
;http-proxy-retry # retry on connection failures
;http-proxy [proxy server] [proxy port #]

# Wireless networks often produce a lot
# of duplicate packets.  Set this flag
# to silence duplicate packet warnings.
;mute-replay-warnings

# SSL/TLS parms.
# See the server config file for more
# description.  It's best to use
# a separate .crt/.key file pair
# for each client.  A single ca
# file can be used for all clients.
;ca ca.crt
;cert client.crt
;key client.key

# Verify server certificate by checking
# that the certicate has the nsCertType
# field set to "server".  This is an
# important precaution to protect against
# a potential attack discussed here:
#  http://openvpn.net/howto.html#mitm
#
# To use this feature, you will need to generate
# your server certificates with the nsCertType
# field set to "server".  The build-key-server
# script in the easy-rsa folder will do this.
;ns-cert-type server

# If a tls-auth key is used on the server
# then every client must also have the key.
;tls-auth ta.key 1

tls-cipher DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-SHA256:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA:DHE-RSA-CAMELLIA-256-CBC-SHA:DHE-RSA-CAMELLIA-128-CBC-SHA:AES256-SHA:AES128-SHA

tls-remote "PLACEHOLDER_CERT_SUBJECT"

# Select a cryptographic cipher.
# If the cipher option is used on the server
# then you must also specify it here.
cipher AES-128-CBC

auth SHA256

# Enable compression on the VPN link.
# Don't enable this unless it is also
# enabled in the server config file.
comp-lzo

# Set log file verbosity.
verb 3

# Silence repeating messages
;mute 20

# Everyware Cloud Security
auth-user-pass

# Disable key renegotiation
reneg-sec 0

# Everyware Cloud Network Configuration
inactive 300
ping 10
ping-exit 60

# Notify disconnect to server (UDP)
explicit-exit-notify 1

<ca>
PLACEHOLDER_CA_CHAIN
</ca>