Add note and example about RouterOS user rights + terminology fixes (h…

…ome-assistant#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 * ✏️ Tweaks
sorinyo2004 · Dec 26, 2018 · 572b1c0 · 572b1c0
1 parent 723a3ed
commit 572b1c0
Showing 1 changed file with 48 additions and 17 deletions.
diff --git 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,17 +72,46 @@ 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
 /certificate sign "Self signed demo certificate for API"
 /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.