diff --git a/README.md b/README.md index 7f0f56e..c0ea1ad 100644 --- a/README.md +++ b/README.md @@ -35,117 +35,7 @@ Once installed, **updates from the uptream app are managed from within the app** The MQTT broker mosquitto is integrated into the package. It requires its own domain or subdomain. It's an optional setting: during install if you set the same domaine as your main app domain, it won't be installed. -## Configuration - -### Broker Mosquitto - -During installation, a [MQTT](https://en.wikipedia.org/wiki/MQTT) broker, [Mosquitto](https://mosquitto.org/), is installed at the same time as Domoticz. The installed version is the one from the official project repo and not from Debian ones. -This broker requires a dedicated domain or subdomain to work (ex : mqtt.your.domain.tld) : creating this domain prior installation is a prerequisite - -#### Adding in domoticz - -To use mosquitto, you need to customize the communication between domoticz and the broker by following the [domoticz documentation](https://www.domoticz.com/wiki/MQTT#Installing_Mosquitto), part *Add hardware "MQTT Client Gateway"*. -User and password are automatically generated during installation, you may retrieve them with -```` -sudo yunohost app setting domoticz mqtt_user -sudo yunohost app setting domoticz mqtt_pwd -```` - -#### Publish/Subscribe - -By default, mosquitto will listen on 2 ports: -- 1883 on localhost using mqtt protocol -- 8883 using websocket protocol. Nginx redirect external port 443 to this internal port. - -Hence, To publish/subscribe on a topic from the outside, you have to use a software supporting websocket protocol (ex : paho python library). - -#### Mosquitto_pub et mosquitto_sub - -These 2 tools do not support websocket protocol, only direct mqtt: base settings will not allow communication from an outside device. -If you're using them directly from your server, this kind of syntax should work: -```` -mosquitto_pub -u *user* -P *password* -h mqtt.your.domain.tld -p 1883 -t 'domoticz/in' -m '{ "idx" : 1, "nvalue" : 0, "svalue" : "25.0" }' -```` -In the same way: -```` -mosquitto_sub -u *user* -P *password* -h mqtt.your.domain.tld -p 1883 -t 'domoticz/out' -```` - -If you wish to open direct mqtt protocol from an outside device, you'll need to: -- open port 1883 on Yunohost firewall (**Attention, security risk**) -- Allows IP addresses in mosquitto configuration for this listener -- Set the tls setting in mosquitto configuration by giving access to crt.pem and key.pem from your mqtt domain by setting respective certfile et keyfile variables. **This is mandatory to ensure a secure connection.** - -#### Upgrade from version without mosquitto -If you have package ynh3 or below, mosquitto is not installed by default. -If you have chosen to not set a domain during initial installation also. -So, if you need to activate mosquitto in retrospect, do following actions: -1. Create a domain or a subdomain (for example : 'mqtt.your.domain.tld') -2. Connect to your server in command line -3. Type following command : `yunohost app setting domoticz mqtt_domain -v mqtt.your.domain.tld` -4. Upgrade domoticz to last package. -If you're already on the last package version, use the following command : `yunohost app upgrade domoticz --force` - -## Configuration - -### Sensors, language and this kind of stuff -Main configuration of the app take place inside the app itself. - -### Zwave management -If you're using zwave devices, install mosquitto along domoticz and give a try to [zwave-JS-UI package](https://github.com/YunoHost-Apps/zwave-js-ui_ynh). -Once installed, just follow instructions from the [wiki](https://www.domoticz.com/wiki/Zwave-JS-UI) - -### Access and API -By default, access for the [JSON API](https://www.domoticz.com/wiki/Domoticz_API/JSON_URL's) is allowed on following path `/yourdomain.tld/api_/domoticzpath`. -So if you access domoticz via https://mydomainname.tld/domoticz, use the following webpath for the api : `/mydomainname.tld/api_/domoticz/json.htm?yourapicommand` - -By default, only sensor updates and switch toogle are authorized. To authorized a new command, you have to manually update the nginx config file : -```` -sudo nano /etc/nginx/conf.d/yourdomain.tld.d/api_domoticz.conf -```` -Then edit the following block by adding the regex of the command you want to allow: -```` - #set the list of authorized json command here in regex format - #you may retrieve the command from https://www.domoticz.com/wiki/Domoticz_API/JSON_URL's - #By default, sensors updates and toggle switch are authorized - if ( $args ~* type=command¶m=udevice&idx=[0-9]*&nvalue=[0-9]*&svalue=.*$|type=command¶m=switchlight&idx=[0-9]*&switchcmd=Toggle$) { - set $api "1"; - } -```` -For example, to add the json command to retrieve the status of a device (/json.htm?type=devices&rid=IDX),modify the line as this: -```` - if ( $args ~* type=command¶m=udevice&idx=[0-9]*&nvalue=[0-9]*&svalue=.*$|type=command¶m=switchlight&idx=[0-9]*&switchcmd=Toggle$|type=devices&rid=[0-9]* ) { - set $api "1"; - } -```` - -All IPv4 addresses within the local network (192.168.0.0/24) and *all IPv6* addresses are authorized as API. -As far as I know, there is no way to filter for IPv6 address on local network : You may remove the authorization by removing or commenting this line in `/etc/nginx/conf.d/yourdomain.tld.d/domoticz.conf`: -```` -allow ::/1; -```` -This will authorized only IPv4 within local network to access your domoticz API. -You may add individual IPv6 address in the same way. - -**Shipped version:** 2020.2~ynh7 -## Disclaimers / important information - - -## Limitations - -* No user management nor LDAP integration This function is [not planned to be implemented into the app](https://github.com/domoticz/domoticz/issues/838), hence it's not planned into the package neither. -* Backup cannot be restored on a different machine type (arm, x86...) as compiled sources are different - -## Security consideration - -Although you may activate a login page on the application (either from the *Setup/Settings/System/Website protection* menu or from the *Setup/More Options/Edit Users* menu), it doesn't seems to be very reliable and secure so far (version 2022.2 at the time of writing). Work is ongoing to strengthen the security ([see here](https://www.domoticz.com/wiki/Security)) in future version but is not yet released. - -### recommandation - -It seems advisable to not make the app publicly available outside of the yunohost sso (public = yes at install or setting the domoticz permission to 'visitors' in the admin panel). If for any reason you need to, I recommend the following: - - Activate the website protection/user management (with login page instead of Basic-auth) - - In *Setup/Settings/System/Local Networks (no username/password)* enter the address of the nginx proxy (should be "::1;127.0.0.1" in any standard Yunohost installation) so that the Fail2ban settings is active (see last lines of [this wiki](https://www.domoticz.com/wiki/WebServer_Proxy) - +**Shipped version:** 2023.1~ynh1 ## Documentation and resources * Official app website: diff --git a/README_fr.md b/README_fr.md index db2d3bd..4e3af27 100644 --- a/README_fr.md +++ b/README_fr.md @@ -34,117 +34,9 @@ Une fois installée, **les mises à jour de l'application sont gérées depuis l Le broker MQTT mosquitto est intégré au package et nécessite un sous-domaine ou un domaine distinct. Il est optionnel et si vous indiquez lors de l'installation le même domaine que le domaine principal, il ne sera pas installé. -## Configuration - -### Broker MQTT Mosquitto - -A l'installation, un broker [MQTT](https://fr.wikipedia.org/wiki/MQTT), [Mosquitto](https://mosquitto.org/), est installé en même temps que Domoticz. La version installée est celle du dépot officiel du projet, et non des dépots Debian. -Ce broker nécessite un domaine ou un sous-domaine particulier pour fonctionner (ex : mqtt.your.domain.tld) : il est nécessaire de créer ce domaine auparavant. - -#### Ajout dans domoticz - -Pour pouvoir l'utiliser, vous devez paramétrer la communication avec entre domoticz et le broker en suivant la [documentation de domoticz](https://www.domoticz.com/wiki/MQTT#Installing_Mosquitto) dans la partie *Add hardware "MQTT Client Gateway"* -Les users et mot de passe du broker sont automatiquement générés lors de l'installation. Vous pouvez les récupérer avec -```` -sudo yunohost app setting domoticz mqtt_user -sudo yunohost app setting domoticz mqtt_pwd -```` - -#### Publier/souscrire - -Par défaut, mosquitto va écouter sur 2 ports: -- Le 1883 sur localhost en protocole mqtt -- Le 8883 en protocole websocket. Nginx redirige le port 443 externe vers ce port en interne. -Pour publier/souscrire sur un topic depuis l'exterieur, vous devez donc utiliser un programme supportant le protocole websocket (ex : la bibliothèque python paho).: - -#### Mosquitto_pub et mosquitto_sub - -Ces deux programmes ne supportent pas le protocole websocket mais uniquement le mqtt : le paramétrage de base ne vous autorise donc pas à les utiliser pour communiquer depuis un client externe. -Si vous les utilisez directement depuis votre serveur, ce genre de syntaxe devrait marcher: -```` -mosquitto_pub -u *user* -P *password* -h mqtt.your.domain.tld -p 1883 -t 'domoticz/in' -m '{ "idx" : 1, "nvalue" : 0, "svalue" : "25.0" }' -```` -De la même manière:c -```` -mosquitto_sub -u *user* -P *password* -h mqtt.your.domain.tld -p 1883 -t 'domoticz/out' -```` -Si vous souhaitez ouvrir le protocole mqtt depuis l'extérieur afin de pouvoir les utiliser depuis un autre serveur, il vous faudra: -- ouvrir le port 1883 sur le firewall Yunohost (**Attention, risque de sécurité**) -- autoriser les adresses IP souhaitées dans la configuration de mosquitto pour ce listener -- paramétrer le tls dans la configuration de mosquitto en donnant accès au crt.pem et key.pem de votre domaine mqtt en les paramétrant respectivement avec les variables certfile et keyfile. **Ceci est obligatoire pour sécuriser la connexion.** - - -#### Mise à jour depuis les versions n'ayant pas mosquittoo -Si vous êtes sur le package ynh3 ou inférieur, mosquitto n'est pas installé par défaut. -De même si vous avez choisi de ne pas indiquer de domaine pour mosquitto lors de l'installation initiale. -Pour pouvoir l'installer après coup, faites les actions suivantes: -1. créez un domaine ou sous-domaine pour recevoir les informations (par exemple : 'mqtt.your.domain.tld') -2. connecter vous en ligne de commande à votre serveur -3. taper la commande suivante : `yunohost app setting domoticz mqtt_domain -v mqtt.your.domain.tld` -4. Procédez à la mise à jour. -Si vous êtes déjà sur la dernière version, utiliser la commmande suivante : `yunohost app upgrade domoticz --force` - - -### Senseurs, langue et ce genre de choses -Toute la configuration de l'application a lieu dans l'application elle même - -### Gestion du Zwave -Si vous utilisez des équipements zwave, installez mosquitto en plus de domoticz et essayez le [package zwave-JS-UI](https://github.com/YunoHost-Apps/zwave-js-ui_ynh). -Une fois installé, suivez simplement les indications du [wiki](https://www.domoticz.com/wiki/Zwave-JS-UI) - -### Accès et API -Par défaut, l'accès aux [API JSON](https://www.domoticz.com/wiki/Domoticz_API/JSON_URL's) est autorisé sur cette URL `/votredomaine.tld/api_/chemindedomoticz`. -Donc, si vous accédez à domoticz par https://votredomaine.tld/domoticz, utilisez le chemin suivant pour l'api: `/votredomaine.tld/api_/domoticz/json.htm?votrecommandeapi` - -Par défaut, seule la mise à jour de senseur et les interrupteurs sont autorisés. Pour autoriser une nouvelle commande, vous devez manuellement éditer le fichier de configuration nginx : -```` -sudo nano /etc/nginx/conf.d/yourdomain.tld.d/api_domoticz.conf -```` -Puis éditer le bloc suivant en y ajoutant le regex de la commmande à autoriser : -```` - #set the list of authorized json command here in regex format - #you may retrieve the command from https://www.domoticz.com/wiki/Domoticz_API/JSON_URL's - #By default, sensors updates and toggle switch are authorized - if ( $args ~* type=command¶m=udevice&idx=[0-9]*&nvalue=[0-9]*&svalue=.*$|type=command¶m=switchlight&idx=[0-9]*&switchcmd=Toggle$) { - set $api "1"; - } -```` -Par exemple, pour ajouter la commmande json pour retrouver le statut d'un équipement (/json.htm?type=devices&rid=IDX),il faut modifier la ligne comme ceci: -```` - if ( $args ~* type=command¶m=udevice&idx=[0-9]*&nvalue=[0-9]*&svalue=.*$|type=command¶m=switchlight&idx=[0-9]*&switchcmd=Toggle$|type=devices&rid=[0-9]* ) { - set $api "1"; - } -```` - -Toutes les adresses IPv4 du réseau local (192.168.0.0/24) et toutes les adresses IPv6 sont autorisées pour l'API. -A ma connaissance, il n'y a pas moyen d'effectuer un filtre pour les adresses IPv6 sur le réseau local, vous pouvez donc retirer leur autorisation en enlevant ou en commentant la ligne suivante dans `/etc/nginx/conf.d/yourdomain.tld.d/domoticz.conf`: -```` -allow ::/1; -```` -Ceci autorisera seulement les adresses IPv4 local a accéder aux API de domoticz. -Vous pouvez ajouter des adresses IPv6 de la même façon. - - -**Version incluse :** 2020.2~ynh7 -## Avertissements / informations importantes - - -## Limitations - -* Pas de gestion d'utilisateurs ni d'intégration LDAP. L'application ne [prévoit pas de gérer les utilisateurs par LDAP](https://github.com/domoticz/domoticz/issues/838), donc le package non plus. -* Un backup ne peut pas être restauré sur un type de machine différente de celle d'origine (x86, arm...) car les sources compilées sont différentes - -## A propos de la sécurité - -Bien que vous pouviez activer une page de connexion dans l'application (soit depuis le menu *Configuration/Paramètres/Système/Sécurité* ou depuis *Configuration/Plus d'options/Gérer les utilisateurs*), les fonctionnalités ne semblent pas très avancées ni safe pour l'instant (version 2022.2 au moment d'écrire). Un travail a été entrepris pour renforcer la sécurité ([voir ici](https://www.domoticz.com/wiki/Security)) dans les versions futures mais n'a pas encore été released. - -### recommandations - -Il semble conseillé de ne pas rendre l'application publique en dehors du sso yunohost (public = oui à l'installation ou mettre la permission domoticz à 'Visiteurs' dans le panel d'administration Yunohost). Si pour quelques raisons que ce soit, vous deviez le faire, je vous recommande: - - d'activer la sécurité de connexion à domoticz (plutot avec la login page qu'avec la basic-auth) - - Dans *Configuration/Système/Réseaux Locaux (pas d'authentification)* d'entrer les adresses du proxy nginx (cela devrait être "::1;127.0.0.1" dans une installation Yunohost Standard) afin que Fail2ban puisse bloquer les tentatives de connexions (voir les dernières lignes de [ce wiki](https://www.domoticz.com/wiki/WebServer_Proxy) +**Version incluse :** 2023.1~ynh1 ## Documentations et ressources * Site officiel de l’app :