From 572b1c08db9660de9442a2b0ba09f0cacf534604 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?So=C3=B3s=20P=C3=A9ter?= Date: Wed, 26 Dec 2018 16:30:23 +0100 Subject: [PATCH] Add note and example about RouterOS user rights + terminology fixes (#7615) * Added api-ssl related documentation * Updated to refer to the last changes in parent PR * Fixed typos * Fixed conflicts Fixed conflicts with the home-assistant/home-assistant.io * Fixed typos * More text correction * More fixes * Recommendation for using read only account in RouterOS. * Added more examples * Update device_tracker.mikrotik.markdown * Update device_tracker.mikrotik.markdown * Update device_tracker.mikrotik.markdown * Update device_tracker.mikrotik.markdown * Update device_tracker.mikrotik.markdown * Minor fixes * Try to unify the terminology * Terminology fixes * :pencil2: Tweaks --- .../device_tracker.mikrotik.markdown | 65 ++++++++++++++----- 1 file changed, 48 insertions(+), 17 deletions(-) diff --git a/source/_components/device_tracker.mikrotik.markdown b/source/_components/device_tracker.mikrotik.markdown index 8e839945c87..dcad31664af 100644 --- a/source/_components/device_tracker.mikrotik.markdown +++ b/source/_components/device_tracker.mikrotik.markdown @@ -1,7 +1,7 @@ --- layout: page -title: "Mikrotik" -description: "Instructions on how to integrate Mikrotik/Routerboard based routers into Home Assistant." +title: "MikroTik" +description: "Instructions on how to integrate MikroTik/RouterOS based devices into Home Assistant." date: 2017-04-28 16:03 sidebar: true comments: false @@ -12,10 +12,11 @@ ha_category: Presence Detection ha_release: 0.44 --- +The `mikrotik` platform offers presence detection by looking at connected devices to a [MikroTik RouterOS](http://mikrotik.com) based router. -The `mikrotik` platform offers presence detection by looking at connected devices to a [Mikrotik Routerboard](http://routerboard.com) based router. +## {% linkable_title Configuring `mikrotik` device tracker %} -You need to enable the RouterOS API to use this platform. +You have to enable accessing the RouterOS API on your router to use this platform. Terminal: @@ -26,41 +27,42 @@ set api disabled=no port=8728 Web Frontend: -Go to **IP** -> **Services** -> **API** and enable it. +Go to **IP** -> **Services** -> **api** and enable it. Make sure that port 8728 or the port you choose is accessible from your network. -To use a Mikrotik router in your installation, add the following to your `configuration.yaml` file: + +To use a MikroTik router in your installation, add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry device_tracker: - platform: mikrotik host: IP_ADDRESS - username: ADMIN_USERNAME - password: ADMIN_PASSWORD + username: ROUTEROS_USERNAME + password: ROUTEROS_PASSWORD ``` {% configuration %} host: - description: The IP address of your router. + description: The IP address of your MikroTik device. required: true type: string username: - description: The username of an user with administrative privileges. + description: The username of a user on the MikroTik device. required: true type: string password: - description: The password for your given admin account. + description: The password of the given user account on the MikroTik device. required: true type: string port: - description: Mikrotik API port. + description: RouterOS API port. required: false - default: 8728 (or 8729 if ssl is true) + default: 8728 (or 8729 if SSL is enabled) type: integer ssl: - description: Use api_ssl service instead of api. + description: Use SSL to connect to the API. required: false default: false type: boolean @@ -70,7 +72,9 @@ method: type: string {% endconfiguration %} -To use api_ssl service further configuration is required at RouterOS side. You have to upload or generate a certificate for api\-ssl service. Here is an example for a self signed certificate: +## {% linkable_title Use a certificate %} + +To use SSL to connect to the API (via `api-ssl` instead of `api` service) further configuration is required at RouterOS side. You have to upload or generate a certificate and configure `api-ssl` service to use it. Here is an example of a self-signed certificate: ```bash /certificate add common-name="Self signed demo certificate for API" days-valid=3650 name="Self signed demo certificate for API" key-usage=digital-signature,key-encipherment,tls-server,key-cert-sign,crl-sign @@ -78,9 +82,36 @@ To use api_ssl service further configuration is required at RouterOS side. You h /ip service set api-ssl certificate="Self signed demo certificate for API" /ip service enable api-ssl ``` -If everything is working you can disable the pure api service: + +Then add `ssl: true` to `mikrotik` device tracker entry in your `configuration.yaml` file. + +If everything is working fine you can disable the pure `api` service in RouterOS: ```bash /ip service disable api ``` -See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked. + +## {% linkable_title The user privileges in RouterOS %} + +To use this device tracker you need restricted privileges only. To enhance the security of your MikroTik device create a "read only" user who is able to connect to API only: + +```bash +/user group add name=homeassistant policy=read,api,!local,!telnet,!ssh,!ftp,!reboot,!write,!policy,!test,!winbox,!password,!web,!sniff,!sensitive on,!dude,!tikapp +/user add group=homeassistant name=homeassistant +/user set password="YOUR_PASSWORD" homeassistant +``` + +## {% linkable_title Using the additional configuration to the `mikrotik` device tracker entry in your `configuration.yaml` file: %} + +```yaml +device_tracker: + - platform: mikrotik + host: 192.168.88.1 + username: homeassistant + password: YOUR_PASSWORD + ssl: true + port: 8729 + method: capsman +``` + +See the [device tracker component page](/components/device_tracker/) for instructions on how to configure the people to be tracked.