289 lines
No EOL
15 KiB
HTML
289 lines
No EOL
15 KiB
HTML
<!doctype html>
|
||
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
|
||
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
|
||
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
|
||
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
|
||
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
|
||
<title>HTTP - Home Assistant</title>
|
||
<meta name="author" content="Home Assistant">
|
||
<meta name="description" content="Offers a web framework to serve files.">
|
||
|
||
<meta name="viewport" content="width=device-width">
|
||
<link rel="canonical" href="https://home-assistant.io/components/http/">
|
||
|
||
<meta property="fb:app_id" content="338291289691179">
|
||
<meta property="og:title" content="HTTP">
|
||
<meta property="og:site_name" content="Home Assistant">
|
||
<meta property="og:url" content="https://home-assistant.io/components/http/">
|
||
<meta property="og:type" content="article">
|
||
<meta property="og:description" content="Offers a web framework to serve files.">
|
||
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
|
||
|
||
<meta name="twitter:card" content="summary_large_image">
|
||
<meta name="twitter:site" content="@home_assistant">
|
||
|
||
<meta name="twitter:title" content="HTTP">
|
||
<meta name="twitter:description" content="Offers a web framework to serve files.">
|
||
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
|
||
|
||
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
|
||
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
|
||
<link rel='shortcut icon' href='/images/favicon.ico' />
|
||
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
|
||
</head>
|
||
|
||
<body >
|
||
|
||
<header>
|
||
<div class="grid-wrapper">
|
||
<div class="grid">
|
||
|
||
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
|
||
<a href="/" class="site-title">
|
||
<img width='40' src='/demo/favicon-192x192.png'>
|
||
<span>Home Assistant</span>
|
||
</a>
|
||
</div>
|
||
|
||
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
|
||
<nav>
|
||
<input type="checkbox" id="toggle">
|
||
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
|
||
<ul class="menu pull-right">
|
||
|
||
<li><a href="/getting-started/">Getting started</a></li>
|
||
<li><a href="/components/">Components</a></li>
|
||
<li><a href="/docs/">Docs</a></li>
|
||
<li><a href="/cookbook/">Examples</a></li>
|
||
<li><a href="/developers/">Developers</a></li>
|
||
<li><a href="/blog/">Blog</a></li>
|
||
<li><a href="/help/">Need help?</a></li>
|
||
</ul>
|
||
</nav>
|
||
</div>
|
||
|
||
</div>
|
||
</div>
|
||
</header>
|
||
|
||
|
||
|
||
<div class="grid-wrapper">
|
||
<div class="grid grid-center">
|
||
|
||
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
|
||
|
||
|
||
<article class="page">
|
||
|
||
|
||
|
||
|
||
<header>
|
||
<h1 class="title indent">
|
||
HTTP
|
||
</h1>
|
||
</header>
|
||
<hr class="divider">
|
||
|
||
|
||
<p>The <code class="highlighter-rouge">http</code> component serves all files and data required for the Home Assistant frontend. You only need to add this to your configuration file if you want to change any of the default settings.</p>
|
||
|
||
<p class="note warning">
|
||
It’s HIGHLY recommended that you set the <code class="highlighter-rouge">api_password</code>, especially if you are planning to expose your installation to the internet.
|
||
</p>
|
||
|
||
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="c1"># Example configuration.yaml entry</span>
|
||
<span class="s">http</span><span class="pi">:</span>
|
||
<span class="s">api_password</span><span class="pi">:</span> <span class="s">YOUR_PASSWORD</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>Configuration variables:</p>
|
||
|
||
<ul>
|
||
<li><strong>api_password</strong> (<em>Optional</em>): Protect Home Assistant with a password.</li>
|
||
<li><strong>server_host</strong> (<em>Optional</em>): Only listen to incoming requests on specific ip/host (default: accept all)</li>
|
||
<li><strong>server_port</strong> (<em>Optional</em>): Let you set a port to use. Defaults to 8123.</li>
|
||
<li><strong>base_url</strong> (<em>Optional</em>): The url that Home Assistant is available on the internet. For example: <code class="highlighter-rouge">hass-example.duckdns.org:8123</code>. Defaults to local IP address.</li>
|
||
<li><strong>development</strong> (<em>Optional</em>): Disable caching and load unvulcanized assets. Useful for Frontend development.</li>
|
||
<li><strong>ssl_certificate</strong> (<em>Optional</em>): Path to your TLS/SSL certificate to serve Home Assistant over a secure connection.</li>
|
||
<li><strong>ssl_key</strong> (<em>Optional</em>): Path to your TLS/SSL key to serve Home Assistant over a secure connection.</li>
|
||
<li><strong>cors_allowed_origins</strong> (<em>Optional</em>): A list of origin domain names to allow <a href="https://en.wikipedia.org/wiki/Cross-origin_resource_sharing">CORS</a> requests from. Enabling this will set the <code class="highlighter-rouge">Access-Control-Allow-Origin</code> header to the Origin header if it is found in the list, and the <code class="highlighter-rouge">Access-Control-Allow-Headers</code> header to <code class="highlighter-rouge">Origin, Accept, X-Requested-With, Content-type, X-HA-access</code>. You must provide the exact Origin, i.e. <code class="highlighter-rouge">https://home-assistant.io</code> will allow requests from <code class="highlighter-rouge">https://home-assistant.io</code> but <strong>not</strong> <code class="highlighter-rouge">http://home-assistant.io</code>.</li>
|
||
<li><strong>use_x_forwarded_for</strong> (<em>Optional</em>): Enable parsing of the <code class="highlighter-rouge">X-Forwarded-For</code> header, passing on the client’s correct IP address in proxied setups. You should only enable this in a trustworthy network environment, as clients passing that header could easily spoof their source IP address. Defaults to False.</li>
|
||
<li><strong>trusted_networks</strong> (<em>Optional</em>): List of trusted networks, consisting of IP addresses or networks, that are allowed to bypass password protection when accessing Home Assistant. It should be noted that if you use a reverse proxy, all requests to home assistant, regardless of source, will arrive from the reverse proxy IP address. Therefore in a reverse proxy scenario this option should be used with extreme care.</li>
|
||
<li><strong>ip_ban_enabled</strong> (<em>Optional</em>): Flag indicating whether additional IP filtering is enabled. Defaults to False.</li>
|
||
<li><strong>login_attempts_threshold</strong> (<em>Optional</em>): Number of failed login attemt from single IP after which it will be automatically banned if <code class="highlighter-rouge">ip_ban_enabled</code> is True. Defaults to -1, meaning that no new automatic bans will be added.</li>
|
||
</ul>
|
||
|
||
<p>The sample below shows a configuration entry with possible values:</p>
|
||
|
||
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="c1"># Example configuration.yaml entry</span>
|
||
<span class="s">http</span><span class="pi">:</span>
|
||
<span class="s">api_password</span><span class="pi">:</span> <span class="s">YOUR_PASSWORD</span>
|
||
<span class="s">server_port</span><span class="pi">:</span> <span class="s">12345</span>
|
||
<span class="s">ssl_certificate</span><span class="pi">:</span> <span class="s">/etc/letsencrypt/live/hass.example.com/fullchain.pem</span>
|
||
<span class="s">ssl_key</span><span class="pi">:</span> <span class="s">/etc/letsencrypt/live/hass.example.com/privkey.pem</span>
|
||
<span class="s">cors_allowed_origins</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="s">https://google.com</span>
|
||
<span class="pi">-</span> <span class="s">https://home-assistant.io</span>
|
||
<span class="s">use_x_forwarded_for</span><span class="pi">:</span> <span class="s">True</span>
|
||
<span class="s">trusted_networks</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="s">127.0.0.1</span>
|
||
<span class="pi">-</span> <span class="s">::1</span>
|
||
<span class="pi">-</span> <span class="s">192.168.0.0/24</span>
|
||
<span class="pi">-</span> <span class="s">2001:DB8:ABCD::/48</span>
|
||
<span class="s">ip_ban_enabled</span><span class="pi">:</span> <span class="s">True</span>
|
||
<span class="s">login_attempts_threshold</span><span class="pi">:</span> <span class="s">5</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>The <a href="/blog/2015/12/13/setup-encryption-using-lets-encrypt/">Set up encryption using Let’s Encrypt</a> blog post gives you details about the encryption of your traffic using free certificates from <a href="https://letsencrypt.org/">Let’s Encrypt</a>.</p>
|
||
|
||
<p>On top of the <code class="highlighter-rouge">http</code> component is a <a href="/developers/rest_api/">REST API</a> and a <a href="/developers/python_api/">Python API</a> available. There is also support for <a href="/developers/server_sent_events/">Server-sent events</a> available.</p>
|
||
|
||
<p>The <code class="highlighter-rouge">http</code> platforms are not real platforms within the meaning of the terminology used around Home Assistant. Home Assistant’s <a href="/developers/rest_api/">REST API</a> sends and receives messages over HTTP.</p>
|
||
|
||
<p>To use those kind of <a href="/components/sensor.http/">sensors</a> or <a href="components/binary_sensor.http/">binary sensors</a> in your installation no configuration in Home Assistant is needed. All configuration is done on the devices themselves. This means that you must be able to edit the target URL or endpoint and the payload. The entity will be created after the first message has arrived.</p>
|
||
|
||
<p>All <a href="/developers/rest_api/#post-apistatesltentity_id">requests</a> need to be sent to the endpoint of the device and must be <strong>POST</strong>.</p>
|
||
|
||
<p>If you want to use Home Assistant to host or serve static files then create a directory called <code class="highlighter-rouge">www</code> under the <code class="highlighter-rouge">.homeassistant</code> configuration path. The static files in <code class="highlighter-rouge">.homeassistant/www/</code> can be accessed by the following URL <code class="highlighter-rouge">http://your.domain:8123/local/</code>.</p>
|
||
|
||
<p>If you want to apply additional IP filtering, and automatically ban bruteforce attempts, set <code class="highlighter-rouge">ip_ban_enabled</code> to <code class="highlighter-rouge">True</code> and select number of attempts. After first ban file <code class="highlighter-rouge">ip_bans.yaml</code> will be created in the root configuration folder. It will have IP address and time in UTC when it was added:</p>
|
||
|
||
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">127.0.0.1</span><span class="pi">:</span>
|
||
<span class="s">banned_at</span><span class="pi">:</span> <span class="s1">'</span><span class="s">2016-11-16T19:20:03'</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>After a ban is added a Persistent Notification is populated to the Home Assistant frontend.</p>
|
||
|
||
<p class="note warning">
|
||
Please note, that sources from <code class="highlighter-rouge">trusted_networks</code> won’t be banned automatically.
|
||
</p>
|
||
|
||
|
||
</article>
|
||
|
||
|
||
</div>
|
||
|
||
|
||
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
|
||
<div class="grid">
|
||
|
||
|
||
<section class="aside-module grid__item one-whole lap-one-half">
|
||
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/_components/http.markdown'>Edit this page on GitHub</a></div>
|
||
<div class='brand-logo-container section'>
|
||
<img src='/images/supported_brands/http.png' />
|
||
</div>
|
||
<div class='section'>
|
||
<h1 class='title delta'>Related components</h1>
|
||
<ul class='divided'>
|
||
<li><a href='/components/binary_sensor.http/'>
|
||
HTTP Binary Sensor
|
||
</a></li>
|
||
<li><a href='/components/sensor.http/'>
|
||
HTTP Sensor
|
||
</a></li>
|
||
</ul>
|
||
</div>
|
||
<div class='section'>
|
||
<h1 class="title delta">Category Other</h1>
|
||
<ul class='divided'>
|
||
<li>
|
||
<a href='/components/browser/'>Browser</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/config/'>Config</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/configurator/'>Configurator</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/demo/'>Demo platforms</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/discovery/'>Discovery</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/feedreader/'>Feedreader</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/frontend/'>Frontend</a>
|
||
</li>
|
||
<li>
|
||
HTTP
|
||
</li>
|
||
<li>
|
||
<a href='/components/ha/'>Home Assistant 0.39</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/introduction/'>Introduction</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/keyboard_remote/'>Keyboard Remote</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/logger/'>Logger</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/mqtt_eventstream/'>MQTT Eventstream</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/persistent_notification/'>Persistent notification</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/upnp/'>UPnP</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/updater/'>Updater</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/zeroconf/'>Zeroconf/Avahi/Bonjour</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</section>
|
||
|
||
</div>
|
||
</aside>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
<footer>
|
||
<div class="grid-wrapper">
|
||
<div class="grid">
|
||
<div class="grid__item">
|
||
<div class="copyright">
|
||
<a rel="me" href='https://twitter.com/home_assistant'><i class="icon-twitter"></i></a>
|
||
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
|
||
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
|
||
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
|
||
|
||
<div class="credit">
|
||
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
|
||
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
|
||
Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.
|
||
</div>
|
||
<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">home-assistant.io</span> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License</a>.
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</footer>
|
||
|
||
<script>
|
||
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
|
||
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
|
||
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
|
||
s.parentNode.insertBefore(g,s)}(document,'script'));
|
||
</script>
|
||
</body>
|
||
</html> |