confidential · · 2018-04-18modified introduction, & previously modified areas 8 20170110 ft...

CONFIDENTIAL

Instruction

Z-Ware Web Server Installation Guide

Document No.: INS12905

Version:

Description: Z-Ware Web Server Installation, Configuration, Administration & Building Guide

Written By: SAMBAT;YANYAN;FTEO;BBR

Date:

Reviewed By: BYEO;KMEEL

Restrictions: Partners Only

Approved by:

This document is the property of Silicon Labs. The data contained herein, in whole or in part, may not be duplicated, used or disclosed outside the recipient for any purpose. This restriction does not limit the recipient's right to use information contained in the data if it is obtained from another source without restriction.

INS12905-11 Z-Ware Web Server Installation Guide 2018-03-05

silabs.com | Building a more connected world. Page ii of v

CONFIDENTIAL

REVISION RECORD

Doc. Rev

Date By Pages affected

Brief description of changes

1 20131226 KSS ALL Initial revision

2 20140930 SNA 25 v1.00.01 – added SMTP Authentication option; updated Ref

3 20150226 SNA 22 Added build info

4 20151012 AYY 19 Added fullclean command

5 20151013 AMD 12,13 Added Scenes configuration

6 20160310 AYY 2, 14,16, 22

Updated run time dependencies, added auto-start option, added device database, updated Reference

7 20160922 AYY SNA

2- 5, 7-8, 15, 17 1

Added log rotate function, added server certificate section. Merged CE version installation guide into this doc. Added parallel keyword for compilation. Added additional installation settings. Modified introduction, & previously modified areas

8 20170110 FT AYY

1,2,8 13-14

Update CE version for RPi3 support Added Operating System Common CA Certificate Configuration Added generation of ZIPGW certificate during portal registration

9 20170224 AYY 9-10 Added OAuth2 Database settings, IFTTT settings, Operation system CA certificate setting.

10 20170516 FT AYY

3 8 9 14-15

Untar with sub-directory created. Update document with the missing Email sender name. Re-order OAuth2 Clients, IFTTT, OS Common CA setting in documents. Update ZIPGW certificate generation process during portal registration

11 20170717 AYY 2, 22 Added toolchain and OS image for BeagleBone Black and Raspberry Pi 3

12 20180305 BBR All Added Silicon Labs template

https://www.silabs.com/


silabs.com | Building a more connected world. Page iii of v

CONFIDENTIAL

Table of Contents

1 INTRODUCTION ................................................................................................................................... 1

1.1 Purpose .............................................................................................................................................. 1 1.2 Audience and prerequisites ................................................................................................................ 1

2 INSTALLATION .................................................................................................................................... 2

2.1 Deployment systems .......................................................................................................................... 2 2.2 Runtime package dependencies ........................................................................................................ 2 2.3 User privilege ...................................................................................................................................... 2 2.4 Selection of deployment directory ...................................................................................................... 2 2.5 Installation (Deployment) procedure .................................................................................................. 2 2.6 Install time only Configurations .......................................................................................................... 3

2.6.1 Upstart Settings ........................................................................................................................ 3 2.6.2 Autostart Setting ....................................................................................................................... 4 2.6.3 BBB Wi-Fi Cape Setting (BBB version Only) ........................................................................... 4

2.7 Software License ................................................................................................................................ 4

3 SYSTEM CONFIGURATION ................................................................................................................ 5

3.1 Configuration Description ................................................................................................................... 5 3.1.1 System Settings ....................................................................................................................... 5 3.1.2 Z-Ware Portal Daemon Settings .............................................................................................. 6 3.1.3 Z-Ware Web Settings ............................................................................................................... 7 3.1.4 HTTP Server Settings .............................................................................................................. 7 3.1.5 Email Settings (Portal Version Only) ........................................................................................ 8 3.1.6 LDAP Settings (Portal Version Only) ....................................................................................... 8 3.1.7 OAuth2 Clients Settings (Portal Version Only) ........................................................................ 9 3.1.8 IFTTT Settings (Portal Version Only) ....................................................................................... 9 3.1.9 Operating System Common CA Certificate Configuration ....................................................... 9 3.1.10 SSL Settings ..........................................................................................................................10

3.2 Sample SMTP Configuration (Portal Version Only) .........................................................................11 3.3 Secure HTTP ....................................................................................................................................11 3.4 Certificate and Key generation .........................................................................................................12 3.5 Scenes Configuration .......................................................................................................................12

3.5.1 Group: SECURITY SCENE NOTIFICATION EMAIL .............................................................13 3.5.2 Group: SECURITY SCENE NOTIFICATION SMS ................................................................13 3.5.3 Group: SMTP .........................................................................................................................13

3.6 Device specific configuration and information database ..................................................................14 3.7 Generation of ZIPGW certificate during Portal registration ..............................................................14

4 SERVICE MANAGEMENT .................................................................................................................16

4.1 Managing services directly using Upstart .........................................................................................16 4.2 Auto start Z-Ware service after system boot ....................................................................................17 4.3 LDAP entries (Portal Version Only) ..................................................................................................17

5 LOG FILES ..........................................................................................................................................18

5.1 Z-Ware Portal Daemon ....................................................................................................................18 5.2 Z-Ware Web (CGI) ...........................................................................................................................18 5.3 Apache HTTP Server .......................................................................................................................18 5.4 OpenLDAP (Portal Version Only) .....................................................................................................19

6 USER INTERFACE (WEB) .................................................................................................................20

6.1 Security .............................................................................................................................................20



silabs.com | Building a more connected world. Page iv of v

CONFIDENTIAL

6.1.1 HTTPS Server certificate .......................................................................................................20 6.2 Firmware Update ..............................................................................................................................20 6.3 Admin Access (Portal Version Only) ................................................................................................21

7 BUILDING ...........................................................................................................................................22

7.1 Platforms ..........................................................................................................................................22 7.2 Dependencies...................................................................................................................................22

7.2.1 Toolchain for BBB and RPi 3 .................................................................................................22 7.3 User Privilege ...................................................................................................................................22 7.4 Location ............................................................................................................................................22 7.5 Procedure .........................................................................................................................................23

REFERENCES ...........................................................................................................................................25

Table of Tables

Table 2-1: Upstart Settings .......................................................................................................................... 3 Table 2-2: BBB Wi-Fi Cape Settings ........................................................................................................... 4 Table 3-1: System Settings ......................................................................................................................... 5 Table 3-2: Z-Ware Portal Daemon Settings ................................................................................................ 6 Table 3-3: Z-Ware Web Settings ................................................................................................................. 7 Table 3-4: HTTP Server Settings ................................................................................................................ 7 Table 3-5: Email Settings ............................................................................................................................ 8 Table 3-6: LDAP Settings ............................................................................................................................ 8 Table 3-7: OAuth2 Clients Settings ............................................................................................................. 9 Table 3-8: IFTTT Settings ............................................................................................................................ 9 Table 3-9: Operating System Common CA Certificate Settings ................................................................. 9 Table 3-10: SSL Settings ........................................................................................................................... 10 Table 3-11: SSL file locations .................................................................................................................... 11 Table 3-12: Security Scene Notification Email Settings ............................................................................ 13 Table 3-13: Security Scene Notification SMS Settings ............................................................................. 13 Table 3-14: Scene SMTP Settings ............................................................................................................ 13

Table 2-1: Upstart Settings .......................................................................................................................... 3 Table 2-2: BBB Wi-Fi Cape Settings ........................................................................................................... 4 Table 3-1: System Settings ......................................................................................................................... 5 Table 3-2: Z-Ware Portal Daemon Settings ................................................................................................ 6 Table 3-3: Z-Ware Web Settings ................................................................................................................. 7 Table 3-4: HTTP Server Settings ................................................................................................................ 7 Table 3-5: Email Settings ............................................................................................................................ 8 Table 3-6: LDAP Settings ............................................................................................................................ 8 Table 3-7: OAuth2 Clients Settings ............................................................................................................. 9 Table 3-8: IFTTT Settings ............................................................................................................................ 9 Table 3-9: Operating System Common CA Certificate Settings ................................................................. 9 Table 3-10: SSL Settings ........................................................................................................................... 10 Table 3-11: SSL file locations .................................................................................................................... 11 Table 3-12: Security Scene Notification Email Settings ............................................................................ 13 Table 3-13: Security Scene Notification SMS Settings ............................................................................. 13 Table 3-14: Scene SMTP Settings ............................................................................................................ 13



silabs.com | Building a more connected world. Page v of v

CONFIDENTIAL



silabs.com | Building a more connected world. Page 1 of 25

CONFIDENTIAL

1 INTRODUCTION

1.1 Purpose

Z-Ware Web Server (see [1]) can be built on a Linux PC for 3 targets:

Portal on Linux PC

CE (Consumer Electronics) on Linux PC

CE on BBB (Texas Instrument’s BeagleBone Black board, See https://beagleboard.org/black)

CE on RPi3 (Raspberry Pi 3 Model B board, See https://www.raspberrypi.org/products/raspberry-pi-3-model-b/)

The document covers the Installation, Configuration, Administration and Building of Z-Ware Web Server for these targets.

1.2 Audience and prerequisites

Silicon Labs Z-Wave Partners who are

familiar with ZIPGW (Z-Wave over Internet Protocol Gateway)

have read the Z-Ware Web User Guide

familiar with Linux Administration


https://beagleboard.org/black



CONFIDENTIAL

2 INSTALLATION

2.1 Deployment systems

The software is tested for Ubuntu Desktop/Server 14.04 & 16.04 LTS 32 & 64-bit. The CE version is also tested on BBB and RPi3.

Z-Ware CE BBB version is tested with the following Platform image:

http://debian.beagleboard.org/images/bone-debian-8.3-lxqt-4gb-armhf-2016-01-24-4gb.img.xz Z-Ware CE RPi 3 version is tested with the following Platform image:

http://vx2-downloads.raspberrypi.org/raspbian_lite/images/raspbian_lite-2017-04-10/2017-04-10-raspbian-jessie-lite.zip

The CE version of the ARM binary installation package created for BBB can be installed directly to RPi3. During BBB or RPi3 installation, the installation configuration will automatically handle the differences between BeagleBone Debian and Raspbian OS. The below procedure targeting BBB would also applicable for RPi3.

2.2 Runtime package dependencies

The following is the list of required dependency packages in addition to the ones that get installed by default as part of the OS distribution.

gettext

ia32-libs (applicable only for 64-bit OS and needed only when 32-bit version of this software is required to run in 64-bit OS)

sendmail-bin (needed only when SMTP Server is not used)

rsyslogd (needed only when logging via syslog is used)

sendmail-bin (needed only when SMTP Server is not used)

binutils (needed only for LTS Server version)

2.3 User privilege

The deployment user should not be ‘root’ but must have super user privileges via sudo.

2.4 Selection of deployment directory

The absolute path name of the deployment directory must not contain white spaces.

2.5 Installation (Deployment) procedure

1) If this software is already installed and one or more services running, stop those services. Refer ‘Service Management’ section to find instructions on shutting down the services.

2) Change directory to the path where the installer is placed


http://debian.beagleboard.org/images/bone-debian-8.3-lxqt-4gb-armhf-2016-01-24-4gb.img.xz





CONFIDENTIAL

cd /home/<user>/installer/

3) Extract the contents of the installer. Use one of the following commands depending on the OS type – 64 bit or 32 bit.

tar -zxvf zwareportal-x86_64.tar.gz # (64-bit) tar -zxvf zwareportal-i386.tar.gz # (32-bit) tar -zxvf zwarelocal-x86_64.tar.gz # (64-bit) tar -zxvf zwarelocal-i386.tar.gz # (32-bit) tar -zxvf zwarelocal-beaglebone.tar.gz # (32-bit)

4) For PC portal or local installation, start installation by specifying the deployment path

cd zwareportal-x86_64 # OR cd zwareportal-i386 ./install.sh /home/<user>/zwareportal/

OR

cd zwarelocal-x86_64 # OR cd zwarelocal-i386 ./install.sh /home/<user>/zwarelocal/

On a fresh BBB OS, run the following command and Z-Ware will auto configure BBB OS network and the ZIPGW config file

cd zwarelocal-beaglebone/ ./install.sh --configure-beaglebone /home/<user>/zwarelocal/

For re-installation of Z-Ware on BBB, or if BBB OS network configuration and the ZIPGW config file modification are not desired, run the following command

cd zwarelocal-beaglebone/ ./install.sh /home/<user>/zwarelocal/

‘sudo’ password for the user shall be prompted.

System configurations shall be prompted, if there were no previous configurations or if there were additional set of configurations after an update of this software. Refer ‘System Configuration’ section for details of various configuration options.

2.6 Install time only Configurations

These settings are only available during installation.

2.6.1 Upstart Settings

This determines whether various Z-Ware services should be added to system ‘upstart’ service manager.

Table 2-1: Upstart Settings

Z-Ware Service Option Default

zware-http Y/N N

zware-ldap (Portal version only) Y/N N




CONFIDENTIAL

zware-memcached (Portal version only) Y/N N

zware-portal Y/N N

2.6.2 Autostart Setting

This determines if Z-Ware is auto-started on system boot.

Setting: Enable this package to be auto started after system boot up? Option: Y/N Default: Y for BBB, N for PC platform

2.6.3 BBB Wi-Fi Cape Setting (BBB version Only)

If BBB Wi-Fi Cape is installed, Z-Ware can auto configure the Wi-Fi connection.

Table 2-2: BBB Wi-Fi Cape Settings

Setting Option Default

Network Router Wi-Fi 2.4GHz SSID <string> none

Network Router Wi-Fi 2.4GHz Password <string> none

Network Wi-Fi ISO/IEC alpha2 Country Code

<string> US

For more information, see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

Please note that Z-Ware will not store the Wi-Fi SSID and password information. These are for one-time setup purpose. If the Wi-Fi SSID and/or password changes, the installation needs to be re-run with the new SSID and/or password information to re-configure Wi-Fi setting.

2.7 Software License

The license applicable for the software is placed at the following location. Licenses applicable to external (third-party) software are pointed to from this file.

<install-path>/LICENSE

Here, <install-path> is the deployment directory in deployment machine which is usually /home/<user>/zwareportal/ or, /home/<user>/zwarelocal/ or /home/<user>/zwarebeaglebone/ .


https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2



CONFIDENTIAL

3 SYSTEM CONFIGURATION

System configuration is performed as part of installation (See 2). If a change in system configuration is required in an existing installation, perform the following steps.

1) Change to deployment directory in the deployment machine.

cd /home/<user>/zwareportal/

2) Get system configuration from user

./config/config-config.sh

The texts shown between square brackets [ ] indicate current configuration values. Pressing just the 'Enter/Return' key at the prompt retains the current configuration value.

The texts shown between less-than and greater-than symbols < > indicate comments.

The texts separated by pipe symbol | indicate the valid set of values for a given configuration item. If the options are given as (y|n), the character ‘y’ indicates ‘yes’ and the character ‘n’ indicates ‘no’.

3) Stop selected or all services depending on the set of configuration parameters being changed. Refer ‘Service Management’ section to find instructions on shutting down the services.

4) Apply the system configuration in various configuration files

./config/configure.sh

5) Start the stopped services. Refer ‘Service Management’ section to find instructions on starting the services.

3.1 Configuration Description

The following is the description of various configuration settings.

For each of these settings, a list of services is listed against ‘Services to restart’. For the changes in a given set of configuration settings to take effect, the corresponding set of these services must be stopped before running “configure.sh” script and started again then after. Refer ‘Service Management’ section to find instructions on stopping and starting services.

3.1.1 System Settings

Table 3-1: System Settings


Hostname <string> zware-portal.com

Services to restart: httpd

Hostname is the network label that identifies the deployment machine. Usually, this is set to the name with which the web service shall be hosted. If not already set, a FQDN hostname is suggested.




CONFIDENTIAL

Target Configuration debug|release release

Services to restart: httpd, zwportald

This setting helps to select the tradeoff between ease of debugging and better performance. The ‘debug’ configuration selects debug versions of Z-Ware Portal Daemon and Z-Ware Web thus enabling extensive logging for easier debugging. The ‘release’ configuration selects release versions of Z-Ware Portal Daemon and Z-Ware Web thus going with minimal logging and improved performance.

3.1.2 Z-Ware Portal Daemon Settings

Services to restart: zwportald

Table 3-2: Z-Ware Portal Daemon Settings


Log Target console|release console

The ‘console’ setting results in logging to a file. The ‘syslog’ setting results in sending the log to LOG_USER facility of rsyslogd. Refer manual of rsyslogd for more information.

Log Rotate Size Eg. 100, 100k, 100M, 100G 500M

Size above which the Portal Daemon log is rotated. The setting must be a valid value for 'size' directive in logrotate configuration file. The size check is done every 5 minutes (/etc/cron.d/logrotate)

Z-Ware Portal Http server - Access Log Rotate Size

Eg. 100, 100k, 100M, 100G 10M

Size above which Apache server access log is rotated. The setting must be a valid value for 'size' directive in logrotate configuration file. The size check is done every 5 minutes (/etc/cron.d/logrotate)

Z-Ware Portal Http server - Error Log Rotate Size

Eg. 100, 100k, 100M, 100G 10M

Size above which Apache server error log is rotated. The setting must be a valid value for 'size' directive in logrotate configuration file. The size check is done every 5 minutes (/etc/cron.d/logrotate)

Z-Ware Portal Zweb - Access Log Rotate Size

Eg. 100, 100k, 100M, 100G 10M

Size above which Zweb access log is rotated. The setting must be a valid value for 'size' directive in logrotate configuration file. The size check is done every 5 minutes (/etc/cron.d/logrotate)

Z-Ware Portal Zweb - Error Log Rotate Size

Eg. 100, 100k, 100M, 100G 10M

Size above which Zweb error log is rotated. The setting must be a valid value for 'size' directive in logrotate configuration file. The size check is done every 5 minutes (/etc/cron.d/logrotate)

Server Initial Thread Count <number> 10

This parameter sets the initial number of worker threads that can service concurrent requests from Z-Ware Web (FastCGI). This value will also be used as the maximum number of idle worker threads. This value decides how well the daemon responds to sudden spike in the number of concurrent users. Lower values (when number of concurrent users is high) shall result in longer latency response time for a short period of time until the required number of additional worker threads are made available. Higher values (when number of concurrent users is low) shall result in unused (idle) worker threads occupying system resources wastefully for longer period of time.

Server Maximum Thread Count <number> 50

This parameter sets the maximum number of worker threads that can service concurrent requests from




CONFIDENTIAL

Z-Ware Web (FastCGI). This value provides an upper limit for the number of worker threads to have control over the daemon’s impact on overall system load. Lower values (when number of concurrent users is high) shall result in longer latency response time for a long period of time. Higher values (when number of concurrent users is low) typically does not have any adverse impact. But, if there is spike in the number of concurrent users, there shall be spike in overall system load and thus also starving other processes.

Z-Wave Report Wait Timeout <number> 11

This parameter sets the time (in seconds) to wait for a Z-Wave Report from the Z-Wave node to which a Z-Wave Get command is sent. Note: The value for this setting must be at most a few seconds less than the value for ‘Portal Receive Timeout’ setting of Z-Ware Web. Lower values for this setting shall increase the likelihood of older report values being sent in the response. This is especially true for Z-Wave nodes that take longer time to respond with a Z-Wave Report. In such cases, typically the newer report values are carried by subsequent Passive Get calls from the UI. Since Passive Get calls are sent periodically, the end result shall be slower UI reaction time for the expected report values. Higher values for this setting shall result in worker threads being occupied for longer duration thus increasing the worker thread count. In a severe case, this may even hit the ‘Server Maximum Thread Count’. The problem is aggravated by more number of Z-Wave nodes that take longer time to respond with a Z-Wave Report.

3.1.3 Z-Ware Web Settings

Table 3-3: Z-Ware Web Settings


Portal Receive Timeout <number> 15


This parameter sets the time (in seconds) for which Z-Ware Web (FastCGI) shall wait for Z-Ware Portal Daemon to respond to its request.

Note: The value of this setting must be at least a few seconds more than the value for ‘Z-Wave Report Wait Timeout’ setting of Z-Ware Portal Daemon.

Lower values for this setting shall force lower values for ‘Z-Ware Report Wait Timeout’ setting of Z-Ware Portal Daemon. So the corresponding impact mentioned under its section applies.

Higher values for this setting shall result in FastCGI processes being occupied for longer duration thus increasing the number of FastCGI processes. In a severe case, this count may hit the maximum limit for the number of FastCGI processes.

3.1.4 HTTP Server Settings

Table 3-4: HTTP Server Settings


Use Secure HTTP? y|n y


The option ‘y’ enables HTTPS in the web server. The option ‘n’ disables HTTPS in web server thus supporting only unsecure HTTP.




CONFIDENTIAL

3.1.5 Email Settings (Portal Version Only)

Table 3-5: Email Settings


Use SMTP Server? y|n n

If the option is ‘y’, emails are sent using SMTP server with provisions for sender authentication. Sender authentication with DKIM supported SMTP servers decreases the likelihood of emails being marked as spam in the recipient's mailbox. If the option is ‘n’, the emails are sent using sendmail program without sender authentication.

SMTP Server Address <String> smtp.zware-portal.com

This setting is to specify the address of SMTP server to be used for sending emails.

SMTP Server Port <number> 587

This setting is to specify the port number of SMTP server used for sending emails.

SMTP Security Method tls|ssl|none tls

This setting is to specify the security method of SMTP server used for sending emails.

Email Sender Address <string> [email protected]

This setting is to specify the email address of sender.

Use SMTP Authentication? y|n n

This setting is to specify whether email sender password is required.

Email Sender Password <string> Secret

This setting is to specify the password for the email sender. If already set, the comment <existing password> is shown instead of showing the actual existing password. This is for security reasons.

Email Sender Name <string> email_sender_user_id

If absent, the email sender user id is suggested as the default value for this setting.

3.1.6 LDAP Settings (Portal Version Only)

Table 3-6: LDAP Settings


LDAP Suffix <String> dc=zware-portal,dc=com

Services to restart: openldap, zwportald

This setting is to specify the LDAP suffix. This is usually the ‘suffix’ configuration directive in OpenLDAP configuration file slapd.conf.

LDAP Root Password <string> <auto generated password>

Services to restart: openldap, zwportald

This setting is to specify the password for LDAP rootdn. This is usually the ‘rootpw’ configuration directive in OpenLDAP configuration file slapd.conf. If not already set, a password is auto-generated and suggested as the default. If already set, the comment <existing password> is shown instead of showing the actual existing password. This is for security reasons. Note: LDAP Root Password is used as the password for ‘admin’ user that manages user accounts




CONFIDENTIAL

LDAP User Password Hashing Scheme CRYPT|MD5|SMD5|SHA|SSHA SSHA

Services to restart: none

This setting is to specify the hashing scheme for user passwords in LDAP. Any change in scheme is applicable only for passwords set subsequently. The hashing schemes of all existing passwords remain the same.

3.1.7 OAuth2 Clients Settings (Portal Version Only)

Table 3-7: OAuth2 Clients Settings


OAuth2 Client ID <String> none

This parameter specifies a unique OAuth 2 Client ID account with third-party service (Eg. IFTTT).

OAuth2 Client Secret <String> none

This parameter specifies a unique OAuth 2 Client ID account secret with third-party service (Eg. IFTTT).

OAuth2 Client Redirect URI <String> none

This parameter specifies OAuth 2 Client ID account redirect URI with third-party service (Eg. IFTTT). For example: https://ifttt.com/channels/your_ifttt_channels_name/authorize For multiple redirect URIs, use <space> as separator.

3.1.8 IFTTT Settings (Portal Version Only)

Table 3-8: IFTTT Settings


IFTTT Channel Key <String> none


This setting is to specify IFTTT Channel Key (Service API Key). This Channel key shall be obtained from IFTTT for a newly created Channel. Without this Channel key, IFTTT function will be blocked.

IFTTT Realtime API POST interval (in milliseconds)

<Number> 1000


This setting is to specify the time interval (in milliseconds) between Realtime API POST calls to IFTTT server.

IFTTT Realtime API POST retry counts <Number> 2


This setting is to specify the number of retry attempts to POST a given set of trigger identities to IFTTT server using its Realtime API.

3.1.9 Operating System Common CA Certificate Configuration

Table 3-9: Operating System Common CA Certificate Settings



https://ifttt.com/channels/your_ifttt_channels_name/authorize



CONFIDENTIAL

Operating System Common CA certificates directory

<String> /etc/ssl/certs


This parameter specifies the directory where Operating System Common CA certificates can be found. Every Operating System is likely to have installed the 'ca-certificates' package. In Ubuntu, these CA certificates are installed in the directory: /etc/ssl/certs/. When PHP attempt TLS/SSL connection with SMTP server, PHP will try to verify the SMTP server certificate is been signed by a valid certificate authority (CA).

3.1.10 SSL Settings

These setting will only be used when no official HTTPS certificate is available.

Table 3-10: SSL Settings


CA Certificate DN Organization (O) <String> Certification Authority Name

This setting is to specify the ‘Organization’ (O) of Certification Authority.

CA Certificate DN Organizational Unit (OU) <String> Certification Authority Name

This setting is to specify the ‘Organizational Unit’ (OU) of Certification Authority.

CA Certificate DN Common Name (CN) <String> Certification Authority Name

This setting is to specify the ‘Common Name’ (CN) of Certification Authority.

CA Certificate Validity <Number> 5000

This setting is to specify the number of days for which a generated CA certificate is valid.

CA Key Length <Number> 2048

This setting is to specify the length (in bits) of a generated CA key.

Portal Certificate DN Organization (O) <String> Company Name

This setting is to specify the ‘Organization’ (O) of Portal Service Provider.

Portal Certificate DN Organizational Unit (OU) <String> Portal

This setting is to specify the ‘Organizational Unit’ (OU) of Portal Service Provider.

Portal Certificate DN Common Name (CN) <String> <hostname>

This setting is to specify the ‘Common Name’ (CN) of Portal Service Provider.

Portal Certificate Validity <Number> 5000

This setting is to specify the number of days for which a generated Portal Service Provider certificate is valid.

Portal Key Length <Number> 2048

This setting is to specify the length (in bits) of a generated Portal Service Provider key.




CONFIDENTIAL

3.2 Sample SMTP Configuration (Portal Version Only)

The following is a sample configuration for using GMail's SMTP server. Use valid values in place of values shown to start with 'My'.

Getting Email Settings... Use SMTP Server? (y|n) [y]: y SMTP Server Address [smtp.zware-portal.com]: smtp.gmail.com SMTP Server Port (587|25|2525|465|<others>) [587]: 587 SMTP Security Method (tls|ssl|none) [tls]: tls Email Sender Address [[email protected]]: [email protected] Email Sender Password [secret <default password>]: MyPassword Email Sender Name [MyUserName]: My Name

3.3 Secure HTTP

The web server expects the security related files in the following locations under deployment folder (/home/<user>/zwareportal/).

Table 3-11: SSL file locations

File Location

Server Certificate install/httpd/conf/Z-Wave/ssl.crt/<hostname>.crt

Server Key install/httpd/conf/Z-Wave/ssl.key/<hostname>.key

CA Certificate install/httpd/conf/Z-Wave/ssl.ca.crt/<hostname>.ca.crt

CA Key install/httpd/conf/Z-Wave/ssl.ca.key/<hostname>.ca.key

<hostname> is the 'Hostname' given during installation or configuration of this software.

Server Certificate and Server Key are minimal requirement for enabling secure HTTP. If Server Certificate is signed by using a Certificate Authority, the corresponding CA Certificate shall also be placed under the relevant directory.

Though CA Key is needed for signing the Server Certificate, the CA Key itself is not needed for the working of the secure server. In fact, the CA Key should not be placed anywhere in the deployment system due to security considerations.

If Server Certificate and/or Server Key is not present for the configured Hostname, when Apache httpd service is started, a prompt is shown to check if Server Key and Server Certificate can be generated. If CA Certificate and CA Key are present in the expected location, they are used to sign the generated Server Certificate.

Server Certificates, Server Keys and CA Certificates are installed for the following hostnames. Since these files are bundled within the installer and Server Certificates being self -signed, these are not meant to be used directly in any serious deployment.

zware-portal.com

zipr.sigmadesigns.com

Note: If the Server Certificate is not signed by any CA, a security warning message shall be thrown by the web client (browser) indicating that the certificate is not trusted because it is self-signed.




CONFIDENTIAL

Note: If the Server Certificate is signed by a CA Key and CA Certificate that are locally generated, a security warning message shall be thrown by the web client (browser) indicating that the certificate is not trusted because the issuer is not trusted.

The ideal solution is to use certificates got from SSL certificate providers like Symantec (Verisign) or DigiCert. The CA certificates of such providers are typically included in most browsers out of the box as trusted CA certificates.

3.4 Certificate and Key generation

The self-signed security related files can be directly generated using the following commands after changing to the deployment directory (/home/<user>/zwareportal/).

The following command generates Server Certificate and Server Key.

./install/openssl/scripts/ssl-certificate-generate.sh <certificate-path> <key-path> [<CA-certificate-path> <CA-key-path>]

<certificate-path> is the generated Server Certificate. <key-path> is the Server Key. If already present, it is used. Otherwise it is also generated. <CA-certificate-path> is the CA Certificate. If it is not present, CA signing is skipped. <CA-key-path> is the CA Key. If it is not present, CA signing is skipped.

The following command generates CA Certificate and CA Key.

./install/openssl/scripts/ssl-ca-certificate-generate.sh <CA-certificate-path> <CA-key-path>

<CA-certificate-path> is the generated CA Certificate. <CA-key-path> is the generated CA Key.

Generating own CA Certificate and CA Key is not recommended for any serious deployment.

3.5 Scenes Configuration

Scenes configuration file zwscenes.conf can be found at the following location.

install-path>/install/zwportald/var/networks/zwscenes.conf

The format of this file is as follows

[GROUP 1] key1=value1 key2=value2 [GROUP 2] key1=value1 …

The valid groups and keys are described below.




CONFIDENTIAL

3.5.1 Group: SECURITY SCENE NOTIFICATION EMAIL

This group contains settings of Security Scenes email feature.

Table 3-12: Security Scene Notification Email Settings

Key Value Description

enable <true | false> Enable or disable Security Scenes sending notification email

sender <string> Sender’s email address

Example:

[SECURITY SCENE NOTIFICATION EMAIL] enable=true [email protected]

3.5.2 Group: SECURITY SCENE NOTIFICATION SMS

This group contains settings of Security Scenes SMS (text message) feature.

Table 3-13: Security Scene Notification SMS Settings


enable <true | false> Enable or disable Security Scenes sending notification SMS

sender <string> Sender’s email address

gateway <string> Email to SMS gateway server

The gateway will be used to send SMS using <number>@<gateway> format where the number would be given in a Security Scene while gateway must be defined in zwscene.conf.

If the number is +6512345678 and configuration file contains “gateway=onewaysms.asia” then libzwscene will send an email to [email protected].

Example:

[SECURITY SCENE NOTIFICATION SMS] enable=true [email protected] gateway=onewaysms.asia

3.5.3 Group: SMTP

This group contains settings of SMTP.

Table 3-14: Scene SMTP Settings


enable <true | false> Enable or disable Security Scenes sending SMS

auth_enable <true | false> Enable SMTP authentication

username <string> SMTP username

password <string> SMTP user’s password

server_hostname <string> SMTP server’s hostname/IP address


mailto:[email protected]

mailto:[email protected]



CONFIDENTIAL

server_port <number> SMTP server’s port number

secure_method <string> Security method e.g. tls

Security Scenes email for notification email or SMS through email-to-SMS gateway can be sent either via local installation of “sendmail” program or via an external SMTP server.

If key “enable” in group SMTP is true then Security Scenes email is sent via SMTP server.

If key “auth_enable” is true then authentication information (username and password) is used to authenticate with SMTP server.

Example:

[SMTP] enable=true auth_enable=true [email protected] password=_Pass100 server_hostname=smtpcorp.com server_port=2525 secure_method=tls

NOTE 1: When key “enable” in group “SMTP” is true then values of key “sender” in group “SECURITY SCENE NOTIFICATION EMAIL” and “SECURITY SCENE NOTIFICATION SMS” do not matter as the sender’s address will always be SMTP user only.

This means that when using “sendmail” to send email we can have different senders for email and SMS but when using SMTP the sender to both would be the same as we only have a single connection to the SMTP server.

NOTE 2: When installing Z-Ware the email settings described in section Email Settings are automatically applied to zwscenes.conf.

3.6 Device specific configuration and information database

The device specific configuration and information database is used by Z-Ware to compensate (early version of) devices that do not provide supported device types or properties. In addition, it also includes configuration settings for the devices during inclusion or even at run time. The device database

configuration file Z-Wave_device_rec.txt can be found at the following location.

<install-path>/install/zwportald/etc/Z-Wave_device_rec.txt

The database file adopts standard JSON format to enable easy editing by user- See [2].

3.7 Generation of ZIPGW certificate during Portal registration

If ZIPGW certificate and PIN is not available during the registration, Z-Ware portal is able to auto generate a PIN and a set of certificates for user’s ZIPGW. In this case, user should select “Register new account” option on the UI then “Z/IP Gateway on Other Boards”. Z-Ware portal will generate a PIN and a set of certificates and send to the user’s registered email address.

If both ZIPGW certification and PIN are available during registration, user can select “ZIPR” option after “Register new account” and fill in the ZIPGW RAC and PIN accordingly.




CONFIDENTIAL

In order to generate ZIPGW PIN and a set of certificates, Z-Ware portal would need to be enabled the functionality with the following steps:

1) Create a “cert” directory under "<INSTALL_PATH>/zweb/htdocs/register/” 2) Set the “cert” directory rights and owner:

3) Copy the certificate authority (CA) files to “<INSTALL_PATH>/zweb/certgeneration/certgen/CA"

4) Set the appropriate rights and own for “CA” directory and “certgeneration” directory:

chown -R daemon.daemon "<INSTALL_PATH>/zweb/certgeneration" chmod 770 "<INSTALL_PATH>/zweb/certgeneration/certgen/CA”

chown -R daemon.daemon "<INSTALL_PATH>/zweb/htdocs/register/cert" chmod 770 "<INSTALL_PATH>/zweb/htdocs/register/cert”




CONFIDENTIAL

4 SERVICE MANAGEMENT

Four services must be up and running to use Z-Ware Portal – Memcached, Apache HTTP Server, OpenLDAP Server and Z-Ware Portal Daemon.

Change to deployment directory in the deployment machine.

cd /home/<user>/zwareportal/

To start/stop/restart all services

./service/service.sh start|stop|restart

One of these actions is applied on all services.

To start/stop/restart Memcached

./service/service-memcached.sh start|stop|restart

To start/stop/restart Apache HTTP Server

./service/service-httpd.sh start|stop|restart

To start/stop/restart OpenLDAP Server

./service/service-openldap.sh start|stop|restart

To start/stop/restart Z-Ware Portal Daemon

./service/service-zwportald.sh start|stop|restart

Z-Ware Portal Daemon shuts down if LDAP connection fails. So the LDAP server should be started before starting Z-Ware Portal Daemon.

The above scripts first try to start the services using upstart. If it fails, the scripts fall back by trying to launch the services on their own.

Z-Ware services launched via upstart have re-spawn mechanism – that is, when a service is found to be down, upstart launches it again. This is to mitigate the impact of application crash in an unattended deployment setup. So ‘killing’ the services directly doesn’t guarantee that the service is shutdown. When a service is started via upstart, its shutdown is guaranteed only when it is stopped via upstart.

4.1 Managing services directly using Upstart

The following commands are applicable if Z-Ware services are added to 'upstart' service manager. This is done during installation only if user accepts installation of upstart scripts under '/etc/init/' directory.

To start/stop/restart memcached, use one of the following commands.

sudo start|stop|restart|status zware-memcached sudo service zware-memcached start|stop|restart|status




CONFIDENTIAL

5 LOG FILES

<install-path> in this section is the deployment directory in deployment machine which is usually /home/<user>/zwareportal/.

5 log files (Z-Ware portal daemon log, Z-Ware Web error log and access log, Apache server error log and access log) will be monitor by Logrotate of the system. Once a particular log file reaches the size defined during configuration stage, Logrotate will “rotate” the log file by rename the file with a “.1” extension. The subsequent log messages will be logged into a new log file with the original file name. Currently at most only 1 extra “rotation” will be kept. This means when the new log file reaches the configured size again, the old “.1” extension file will be deleted and the new log file will be renamed with “.1” extension. The interval for Logrotate to check the file size is 5 mins.

5.1 Z-Ware Portal Daemon

When ‘Log Target’ setting is 'console', the daemon logs the messages at the following location.

<install-path>/install/zwportald/var/log/zwportald.log

When ‘Log Target’ setting is 'syslog', the daemon logs the messages at syslog’s LOG_USER facility. By default, rsyslogd logs them at the following location.

/var/log/syslog

The location of this log file may change depending on the configuration of rsyslogd. The log file may also be rotated and compressed. Refer manual for rsyslogd.

5.2 Z-Ware Web (CGI)

The error log for Z-Ware Web is at the following location.

<install-path>/install/zweb/logs/error_log

The access log for Z-Ware Web is at the following location.

<install-path>/install/zweb/logs/access_log

5.3 Apache HTTP Server

The error log for HTTP Server is at the following location.

<install-path>/install/httpd/logs/error_log

The access log for HTTP Server is at the following location.

<install-path>/install/httpd/logs/access_log




CONFIDENTIAL

5.4 OpenLDAP (Portal Version Only)

OpenLDAP Server logs the messages at LOG_LOCAL4 facility of syslog. Adding the following line in relevant rsyslogd configuration file (/etc/rsyslog.d/50-default.conf) and restarting rsyslogd shall log the messages in the given location (/var/log/ldap.log). Refer manual for rsyslogd.

local4.* /var/log/ldap.log




CONFIDENTIAL

6 USER INTERFACE (WEB)

The web interface can be accessed at

http://<hostname>/

<hostname> is the name assigned to the deployment machine using a name service like DNS.

Any IP address by which the deployment machine is reachable shall also be used. But, the browser may throw security warning messages because of mismatch between hostname and CN in certificate.

6.1 Security

When ‘y’ is selected for “Use Secure HTTP?” configuration option, even when the browser accesses unsecure URL (HTTP), it gets redirected to a secure URL (HTTPS). Depending on the security settings in the web server, the browser shall throw security warnings. Some such cases are as follows.

The server certificate is self-signed.

The server certificate is not signed by a trusted Certificate Authority (CA).

The common name (CN) in the certificate does not match the host name.

In a test setup, it may be fine to proceed further by ignoring such warnings and accepting the risks. But in a production setup, such warnings are typically not acceptable and would need appropriate fix in the web server.

6.1.1 HTTPS Server certificate

The first time Z-Ware service starts, it will check the server certificates and if there aren’t any, it will auto-generate self-signed certificates according to the domain names specified during the installation/configuration.

If the official server certificates are available, they should be placed / replaced in the following location:

<install-path>/install/httpd/conf/zwave/ssl.ca.crt/<domain-name>.ca.crt <install-path>/install/httpd/conf/zwave/ssl.crt/<domain-name>.crt <install-path>/install/httpd/conf/zwave/ssl.key/<domain-name>.key

Z-Ware also supports Letsencrypt HTTPS certificates by default. It will look at the default location for Letsencrypt certificates at

/etc/letsencrypt/live/<domain-name>/cert.pem

If official server certificates exist in the above location, Z-Ware will create a symbolic link in the installation path to the Letsencrypt certificates instead of copying the certificates over to facilitate the certificate renewal process.

6.2 Firmware Update

The firmware files to be used for updating devices using 'Firmware Update Meta Data' command class are to be placed under the following directory location.




CONFIDENTIAL

<install-path>/install/zwportald/var/firmwares/

Here, <install-path> is the deployment directory in deployment machine which is usually /home/<user>/zwareportal/.

6.3 Admin Access (Portal Version Only)

1) In the login page, use "admin" as Username and LDAP administrator password - 'LDAP Root Password’ as Password to enter into "User Account Administration" interface.

2) To list all user, enter "*" in the search box and choose "User ID" as search type. 3) In the search result, each user account can be edited by clicking the "User ID" of the search entry.




CONFIDENTIAL

7 BUILDING

7.1 Platforms

Build has been tested on Ubuntu Desktop LTS 14.04 & 16.04 32 & 64-bit.

7.2 Dependencies

make

cmake

libtool

autoconf

openjdk-6-jre/openjdk-7-jre

g++

unzip

pkg-config

patch

gettext

libglib2.0-dev

zlib1g

zlib1g-dev

flex

bison

7.2.1 Toolchain for BBB and RPi 3

Z-Ware Server for RPi 3 can be cross-compiled on Ubuntu Linux with the following Linaro toolchain. BBB and RPi 3 use the same Z-Ware Server binary and share the same toolchain:

https://releases.linaro.org/components/toolchain/binaries/6.2-2016.11/arm-linux-gnueabihf/gcc-linaro-6.2.1-2016.11-i686_arm-linux-gnueabihf.tar.xz (for 32-bit Linux build system)

Toolchain will be automatically downloaded and configured properly should the user follows the build procedure for BBB.

7.3 User Privilege

The (build) user in build machine needs to have root privilege via sudo.

7.4 Location

The absolute path name of this bundle shall not contain white space.

Suggested path: /home/<user>/zwportal/


https://releases.linaro.org/components/toolchain/binaries/6.2-2016.11/arm-linux-gnueabihf/gcc-linaro-6.2.1-2016.11-i686_arm-linux-gnueabihf.tar.xz

https://releases.linaro.org/components/toolchain/binaries/6.2-2016.11/arm-linux-gnueabihf/gcc-linaro-6.2.1-2016.11-i686_arm-linux-gnueabihf.tar.xz



CONFIDENTIAL

7.5 Procedure

1) Change directory to the source bundle

cd /home/<user>/zwportal/

2) To build for target platforms 'x86-64' or 'i386' on PC, run the main build script as follows.

2.1) To build Z-Ware portal version, run

./build/build.sh portal [debug]

2.2) To build Z-Ware CE version, run

./build/build.sh local [debug]

2.3) To build Z-Ware CE BBB version, or Z-Ware CE Raspberry Pi 3 version, run

./build/build.sh local beaglebone [debug]

This should prompt for sudo password. System configurations (like hostname, LDAP root DN, LDAP root password, etc) will be prompted for, if there were no previous configurations or if there were additional set of configurations after an update of this software (See Section 3).

2.4) To enable parallel compilation for faster machine (eg. Machine with multiple CPUs and > 1GRAM), add “parallel” keyword. Eg.

./build/build.sh portal parallel

3) Build the installer

./build/build-installer.sh

Based on the build product type (i.e. CE or portal or beaglebone), installer will be created automatically for the given product type.

4) To fully clean up the generated files and folders during the build process and restore the project to fresh check-out state, add the “fullclean” keyword. Eg.

./build/build.sh portal fullclean

If the project is already in clean state, it may prompt configuration settings before executing the clean procedure.

5) For clean rebuild by component

zwportald: rm -rf compile/Z-Wave/zwportald ./build/build-zwportald.sh zweb: rm -rf compile/Z-Wave/zweb/ ./build/build-zweb.sh




CONFIDENTIAL

openssl: rm -rf compile/openssl* ./build/build-openssl.sh




CONFIDENTIAL

REFERENCES

[1] Silicon Labs, INS12903, INS, Z-Wave Web User Guide [2] Silicon Labs, INS13172, INS, Z-Wave Library User Guide


http://www.silabs.com

Silicon Laboratories Inc.400 West Cesar ChavezAustin, TX 78701USA

Smart. Connected. Energy-Friendly.

Productswww.silabs.com/products

Qualitywww.silabs.com/quality

Support and Communitycommunity.silabs.com

DisclaimerSilicon Labs intends to provide customers with the latest, accurate, and in-depth documentation of all peripherals and modules available for system and software implementers using or intending to use the Silicon Labs products. Characterization data, available modules and peripherals, memory sizes and memory addresses refer to each specific device, and "Typical" parameters provided can and do vary in different applications. Application examples described herein are for illustrative purposes only. Silicon Labs reserves the right to make changes without further notice and limitation to product information, specifications, and descriptions herein, and does not give warranties as to the accuracy or completeness of the included information. Silicon Labs shall have no liability for the consequences of use of the information supplied herein. This document does not imply or express copyright licenses granted hereunder to design or fabricate any integrated circuits. The products are not designed or authorized to be used within any Life Support System without the specific written consent of Silicon Labs. A "Life Support System" is any product or system intended to support or sustain life and/or health, which, if it fails, can be reasonably expected to result in significant personal injury or death. Silicon Labs products are not designed or authorized for military applications. Silicon Labs products shall under no circumstances be used in weapons of mass destruction including (but not limited to) nuclear, biological or chemical weapons, or missiles capable of delivering such weapons.

Trademark InformationSilicon Laboratories Inc.® , Silicon Laboratories®, Silicon Labs®, SiLabs® and the Silicon Labs logo®, Bluegiga®, Bluegiga Logo®, Clockbuilder®, CMEMS®, DSPLL®, EFM®, EFM32®, EFR, Ember®, Energy Micro, Energy Micro logo and combinations thereof, "the world’s most energy friendly microcontrollers", Ember®, EZLink®, EZRadio®, EZRadioPRO®, Gecko®, ISOmodem®, Micrium, Precision32®, ProSLIC®, Simplicity Studio®, SiPHY®, Telegesis, the Telegesis Logo®, USBXpress®, Zentri, Z-Wave and others are trademarks or registered trademarks of Silicon Labs. ARM, CORTEX, Cortex-M3 and THUMB are trademarks or registered trademarks of ARM Holdings. Keil is a registered trademark of ARM Limited. All other products or brand names mentioned herein are trademarks of their respective holders.

confidential · · 2018-04-18modified introduction, & previously modified areas 8 20170110 ft...

Documents