jeena/home-assistant.github.io
1
0
Fork 0
Code Issues Pull requests Projects Packages Wiki Activity Actions

Site updated at 2017-12-03 14:35:15 UTC

Browse source
This commit is contained in:
Travis CI 2017-12-03 14:35:15 +00:00
parent 760ff5832e
commit ce6c5b8ee1
1629 changed files with 9107 additions and 3280 deletions
Download patch file Download diff file Expand all files Collapse all files

90
components/sensor.fail2ban/index.html
View file

@ -74,9 +74,9 @@
</h1>
</header>
<hr class="divider">
<p>The <code class="highlighter-rouge">fail2ban</code> sensor allows for IPs banned by <a href="https://www.fail2ban.org/wiki/index.php/Main_Page">fail2ban</a> to be displayed in the Home Assistant front-end.</p>
<p>The <code class="highlighter-rouge">fail2ban</code> sensor allows for IPs banned by <a href="https://www.fail2ban.org/wiki/index.php/Main_Page">fail2ban</a> to be displayed in the Home Assistant frontend.</p>
<p class="note">
Your system must have fail2ban installed and correctly configured for this sensor to work. In addition, Home Assistant must be able to read the fail2ban log file.
Your system must have <code class="highlighter-rouge">fail2ban</code> installed and correctly configured for this sensor to work. In addition, Home Assistant must be able to read the <code class="highlighter-rouge">fail2ban</code> log file.
</p>
<p>To enable this sensor, add the following lines to your <code class="highlighter-rouge">configuration.yaml</code>:</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="c1"># Example configuration.yaml entry</span>
@ -85,31 +85,42 @@ Your system must have fail2ban installed and correctly configured for this senso
<span class="s">jails</span><span class="pi">:</span>
<span class="pi">-</span> <span class="s">ssh</span>
<span class="pi">-</span> <span class="s">hass-iptables</span>
<span class="s">file_path</span><span class="pi">:</span> <span class="s">/var/log/fail2ban.log</span>
</code></pre>
</div>
<p>Configuration variables:</p>
<ul>
<li><strong>jails</strong> (<em>Required</em>): List of configured jails you want to display (each jail is its own sensor).</li>
<li><strong>name</strong> (<em>Optional</em>): Name of the sensor. Defaults to <code class="highlighter-rouge">fail2ban</code>.</li>
<li><strong>file_path</strong> (<em>Optional</em>): Path to the fail2ban log. Defaults to <code class="highlighter-rouge">/var/log/fail2ban.log</code>.</li>
<li><strong>scan_interval</strong> (<em>Optional</em>): Used to limit how often log file is read and must be a positive integer (representing number of seconds to wait). Defaults to 120.</li>
</ul>
<div class="config-vars">
<h3><a class="title-link" name="configuration-variables" href="#configuration-variables"></a> Configuration Variables</h3>
<dl class="">
<dt><a class="title-link" name="jails" href="#jails"></a> jails</dt>
<dd>
<p class="desc"><span class="type">(<span class="list">list</span>)</span><span class="required">(Required)</span><span class="description">List of configured jails you want to display.</span></p>
</dd>
<dt><a class="title-link" name="name" href="#name"></a> name</dt>
<dd>
<p class="desc"><span class="type">(<span class="string">string</span>)</span><span class="required">(Optional)</span><span class="description">Name of the sensor.</span></p>
<p class="default">Default value: fail2ban</p>
</dd>
<dt><a class="title-link" name="file_path" href="#file_path"></a> file_path</dt>
<dd>
<p class="desc"><span class="type">(<span class="string">string</span>)</span><span class="required">(Optional)</span><span class="description">Path to the fail2ban log.</span></p>
<p class="default">Default value: /var/log/fail2ban.log</p>
</dd>
</dl>
</div>
<h3><a class="title-link" name="set-up-fail2ban" href="#set-up-fail2ban"></a> Set up Fail2Ban</h3>
<p>For most set-ups, you can follow <a href="https://home-assistant.io/cookbook/fail2ban/">this tutorial</a> to set up fail2ban on your system. It will walk you through creating jails and filters, allowing you to monitor IPs that have been banned for too many failed ssh login attempts, as well as too many failed Home Assistant log in attempts.</p>
<p>For most setups, you can follow <a href="/cookbook/fail2ban/">this tutorial</a> to set up <code class="highlighter-rouge">fail2ban</code> on your system. It will walk you through creating jails and filters, allowing you to monitor IP addresses that have been banned for too many failed SSH login attempts, as well as too many failed Home Assistant login attempts.</p>
<h3><a class="title-link" name="fail2ban-with-docker" href="#fail2ban-with-docker"></a> Fail2Ban with Docker</h3>
<p class="note">
These steps assume you already have the Home Assistant docker running behind nginx and that it is externally accessible. It also assumes the docker is running with the <code class="highlighter-rouge">--net='host'</code> flag.
These steps assume you already have the Home Assistant docker running behind NGINX and that it is externally accessible. It also assumes the docker is running with the <code class="highlighter-rouge">--net='host'</code> flag.
</p>
<p>For those of us using Docker, the above tutorial may not be sufficient. The following steps specifically outline how to set up <code class="highlighter-rouge">fail2ban</code> and Home Assistant when running Home Assistant within a Docker behind nginx. The setup this was tested on was an unRAID server using the <a href="https://github.com/linuxserver/docker-letsencrypt">let’s encrypt docker</a> from linuxserver.io.</p>
<h4>Set http logger</h4>
<p>For those of us using Docker, the above tutorial may not be sufficient. The following steps specifically outline how to set up <code class="highlighter-rouge">fail2ban</code> and Home Assistant when running Home Assistant within a Docker behind NGINX. The setup this was tested on was an unRAID server using the <a href="https://github.com/linuxserver/docker-letsencrypt">let’s encrypt docker</a> from linuxserver.io.</p>
<h4><a class="title-link" name="set-http-logger" href="#set-http-logger"></a> Set http logger</h4>
<p>In your <code class="highlighter-rouge">configuration.yaml</code> file, add the following to the <code class="highlighter-rouge">logger</code> component to ensure that Home Assistant prints failed login attempts to the log.</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">logger</span><span class="pi">:</span>
<span class="s">logs</span><span class="pi">:</span>
<span class="s">homeassistant.components.http.ban</span><span class="pi">:</span> <span class="s">warning</span>
</code></pre>
</div>
<h4>Edit the <code class="highlighter-rouge">jail.local</code> file</h4>
<h4><a class="title-link" name="edit-the-jaillocal-file" href="#edit-the-jaillocal-file"></a> Edit the <code class="highlighter-rouge">jail.local</code> file</h4>
<p>Next, we need to edit the <code class="highlighter-rouge">jail.local</code> file that is included with the Let’s Encrypt docker linked above. Note, for this tutorial, we’ll only be implementing the <code class="highlighter-rouge">[hass-iptables]</code> jail from the <a href="https://home-assistant.io/cookbook/fail2ban/">previously linked tutorial</a>.</p>
<p>Edit <code class="highlighter-rouge">/mnt/user/appdata/letsencrypt/fail2ban/jail.local</code> and append the following to the end of the file:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>[hass-iptables]
@ -120,7 +131,7 @@ logpath = /hass/home-assistant.log
maxretry = 5
</code></pre>
</div>
<h4>Create a filter for the Home Assistant jail</h4>
<h4><a class="title-link" name="create-a-filter-for-the-home-assistant-jail" href="#create-a-filter-for-the-home-assistant-jail"></a> Create a filter for the Home Assistant jail</h4>
<p>Now we need to create a filter for <code class="highlighter-rouge">fail2ban</code> so that it can properly parse the log. This is done with a <code class="highlighter-rouge">failregex</code>. Create a file called <code class="highlighter-rouge">hass.local</code> within the <code class="highlighter-rouge">filter.d</code> directory in <code class="highlighter-rouge">/mnt/user/appdata/letsencrypt/fail2ban</code> and add the following:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>[INCLUDES]
before = common.conf
@ -134,7 +145,7 @@ ignoreregex =
datepattern = ^%%Y-%%m-%%d %%H:%%M:%%S
</code></pre>
</div>
<h4>Map log file directories</h4>
<h4><a class="title-link" name="map-log-file-directories" href="#map-log-file-directories"></a> Map log file directories</h4>
<p>First, we need to make sure that fail2ban log can be passed to Home Assistant and that the Home Assistant log can be passed to fail2ban. When starting the Let’s Encrypt docker, you need to add the following argument (adjust paths based on your setup):</p>
<div class="highlighter-rouge"><pre class="highlight"><code>/mnt/user/appdata/home-assistant:/hass
</code></pre>
@ -144,37 +155,37 @@ datepattern = ^%%Y-%%m-%%d %%H:%%M:%%S
<div class="highlighter-rouge"><pre class="highlight"><code>/mnt/user/appdata/letsencrypt/log/fail2ban:/fail2ban
</code></pre>
</div>
<h4>Send client IP to Home Assistant</h4>
<h4><a class="title-link" name="send-client-ip-to-home-assistant" href="#send-client-ip-to-home-assistant"></a> Send client IP to Home Assistant</h4>
<p>By default, the IP address that Home Assistant sees will be that of the container (something like <code class="highlighter-rouge">172.17.0.16</code>). What this means is that for any failed login attempt, assuming you have correctly configured <code class="highlighter-rouge">fail2ban</code>, the Docker IP will be logged as banned, but the originating IP is still allowed to make attempts. We need <code class="highlighter-rouge">fail2ban</code> to recognize the originating IP to properly ban it.</p>
<p>First, we have to add the following to the nginx configuration file located in <code class="highlighter-rouge">/mnt/user/appdata/letsencrypt/nginx/site-confs/default</code>.</p>
<div class="highlighter-rouge"><pre class="highlight"><code>proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>proxy_set_header X-Real-IP <span class="nv">$remote_addr</span>;
proxy_set_header X-Forwarded-For <span class="nv">$proxy_add_x_forwarded_for</span>;
</code></pre>
</div>
<p>This snippet should be added within your Home Assistant server config, so you have something like the following:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>server {
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>server <span class="o">{</span>
...
location / {
location / <span class="o">{</span>
proxy_pass http://192.168.0.100:8123;
proxy_set_header Host $host;
proxy_set_header Host <span class="nv">$host</span>;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
proxy_set_header Upgrade <span class="nv">$http_upgrade</span>;
proxy_set_header Connection <span class="s2">"upgrade"</span>;
proxy_set_header X-Real-IP <span class="nv">$remote_addr</span>;
proxy_set_header X-Forwarded-For <span class="nv">$proxy_add_x_forwarded_for</span>;
<span class="o">}</span>
location /api/websocket {
location /api/websocket <span class="o">{</span>
proxy_pass http://192.168.0.100:8123/api/websocket;
proxy_set_header Host $host;
proxy_set_header Host <span class="nv">$host</span>;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
proxy_set_header Upgrade <span class="nv">$http_upgrade</span>;
proxy_set_header Connection <span class="s2">"upgrade"</span>;
proxy_set_header X-Real-IP <span class="nv">$remote_addr</span>;
proxy_set_header X-Forwarded-For <span class="nv">$proxy_add_x_forwarded_for</span>;
<span class="o">}</span>
...
}
<span class="o">}</span>
</code></pre>
</div>
<p>Once that’s added to the nginx configuration, we need to modify the Home Assistant <code class="highlighter-rouge">configuration.yaml</code> such that the <code class="highlighter-rouge">X-Forwarded-For</code> header can be parsed. This is done by adding the following to the <code class="highlighter-rouge">http</code> component:</p>
@ -183,7 +194,7 @@ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
</code></pre>
</div>
<p>At this point, once the Let’s Encrypt and Home Assistant dockers are restarted, Home Assistant should be correctly logging the originating IP of any failed login attempt. Once that’s done and verified, we can move onto the final step.</p>
<h4>Add the fail2ban sensor</h4>
<h4><a class="title-link" name="add-the-fail2ban-sensor" href="#add-the-fail2ban-sensor"></a> Add the fail2ban sensor</h4>
<p>Now that we’ve correctly set everything up for Docker, we can add our sensors to <code class="highlighter-rouge">configuration.yaml</code> with the following:</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">sensor</span><span class="pi">:</span>
<span class="pi">-</span> <span class="s">platform</span><span class="pi">:</span> <span class="s">fail2ban</span>
@ -194,7 +205,7 @@ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
</div>
<p>Assuming you’ve followed all of the steps, you should have one fail2ban sensor, <code class="highlighter-rouge">sensor.fail2ban_hassiptables</code>, within your front-end.</p>
<h3><a class="title-link" name="other-debug-tips" href="#other-debug-tips"></a> Other debug tips</h3>
<p>If, after following these steps, you’re unable to get the fail2ban sensor working, here are some other steps you can take that may help:</p>
<p>If, after following these steps, you’re unable to get the <code class="highlighter-rouge">fail2ban</code> sensor working, here are some other steps you can take that may help:</p>
<ul>
<li>Add <code class="highlighter-rouge">logencoding = utf-8</code> to the <code class="highlighter-rouge">[hass-iptables]</code> entry</li>
<li>Ensure the <code class="highlighter-rouge">failregex</code> you added to <code class="highlighter-rouge">filter.d/hass.local</code> matches the output within <code class="highlighter-rouge">home-assistant.log</code></li>
@ -341,6 +352,9 @@ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
<li>
<a href='/components/sensor.history_stats/'>History Statistics Sensor</a>
</li>
<li>
<a href='/components/sensor.hive/'>Hive Sensor</a>
</li>
<li>
<a href='/components/sensor.homematic/'>Homematic Sensor</a>
</li>