jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-23 17:27:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

Move all scripts to one location as one page per script (#4554)

Browse Source
This commit is contained in:
Fabian Affolter 2018-01-31 09:43:05 +01:00 committed by GitHub
parent 556a0b08b4
commit 5b6c51c154
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 282 additions and 209 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
source/_components/influxdb.markdown
View File

@ -49,123 +49,13 @@ Configuration variables:
- **tags** (*Optional*): Tags to mark the data. - **tags** (*Optional*): Tags to mark the data.
- **tags_attributes** (*Optional*): The list of attribute names which should be reported as tags and not fields to InfluxDB. For example, if set to `friendly_name`, it will be possible to group by entities' friendly names as well, in addition to their ids. - **tags_attributes** (*Optional*): The list of attribute names which should be reported as tags and not fields to InfluxDB. For example, if set to `friendly_name`, it will be possible to group by entities' friendly names as well, in addition to their ids.
## {% linkable_title Data migration %} ## {% linkable_title Helper scripts %}
Starting with 0.36 the InfluxDB component has a new schema to store values in the InfluxDB databases. - [Helper script `influxdb_import`](/docs/tools/influxdb_import/)
- [Helper script `db_migrator`](/docs/tools/db_migrator/) (only used for [Home Assistant 0.36](/blog/2017/01/14/iss-usps-images-packages/#influxdb-export))
- There will no longer be any tags/fields named `time`.
- All numeric fields (int/float/bool) will be stored as float inside InfluxDB database.
- All string fields corresponding to state attributes will be renamed as `FIELDNAME_str`, where `FIELDNAME` is the state attribute, to avoid type conflicts.
- All string fields corresponding to a state will be renamed as `state` (former value).
- Fields named `value` will always be stored as float.
- Fields named `state` will always be stored as string.
### {% linkable_title Migration script %}
If you need to migrate your database, you may require to run the `influxdb_migrator` script. Run the script after upgrade to 0.36 but before the first regular start of `hass` version 0.36.
These are the steps the script will perform:
1. Create a new database (called `DBNAME__old`) to store old data.
2. Copy data from `DBNAME` database to `DBNAME__old` database.
3. Empty `DBNAME` database (using `drop` then `create`). `DBNAME` database is now considered as the new database.
4. For each measurement of `DBNAME__old` database:
1. Read all points from the current measurement (in groups of 1000 points by default) and convert them.
2. Send group of points to `DBNAME` database.
5. Delete the `DBNAME__old` database if needed.
Example to run the script:
```bash
$ hass --script influxdb_migrator \
-H IP_INFLUXDB_HOST -u INFLUXDB_USERNAME -p INFLUXDB_PASSWORD \
-d INFLUXDB_DB_NAME
```
Script arguments:
```
required arguments:
-d dbname, --dbname dbname InfluxDB database name
optional arguments:
-h, --help show this help message and exit
-H host, --host host InfluxDB host address
-P port, --port port InfluxDB host port
-u username, --username username
InfluxDB username
-p password, --password password
InfluxDB password
-s step, --step step How many points to migrate at the same time
-o override_measurement, --override-measurement override_measurement
Store all your points in the same measurement
-D, --delete Delete old database
```
- If you run the script with only the `-h` option, you will get a help printout with a short explanation of the different options.
- The host option defaults to `'127.0.0.1'`.
- The port option defaults to `8086`.
- You should be able to omit username and password if InfluxDB authentication is disabled, which it is by default.
- The step option defaults to `1000`.
## {% linkable_title Data import script %}
If you want to import all the recorded data from your recorder database you can use the data import script.
It will read all your state_change events from the database and add them as data-points to the InfluxDB.
You can specify the source database either by pointing the `--config` option to the config directory which includes the default SQLite database or by giving a sqlalchemy connection URI with `--uri`.
The writing to InfluxDB is done in batches that can be changed with `--step`.
You can control, which data is imported by using the command line options `--exclude_entities` and `--exclude_domains`.
Both get a comma separated list of either entity-ids or domain names that are excluded from the import.
To test what gets imported you can use the `--simulate` option, which disables the actual write to the InfluxDB instance.
This only writes the statistics how much points would be imported from which entity.
Example to run the script:
```bash
$ hass --script influxdb_import --config CONFIG_DIR \
-H IP_INFLUXDB_HOST -u INFLUXDB_USERNAME -p INFLUXDB_PASSWORD \
--dbname INFLUXDB_DB_NAME --exclude_domains automation,configurator
```
Script arguments:
```
required arguments:
-d dbname, --dbname dbname
InfluxDB database name
optional arguments:
-h, --help show this help message and exit
-c path_to_config_dir, --config path_to_config_dir
Directory that contains the Home Assistant
configuration
--uri URI Connect to URI and import (if other than default
sqlite) eg: mysql://localhost/homeassistant
-H host, --host host InfluxDB host address
-P port, --port port InfluxDB host port
-u username, --username username
InfluxDB username
-p password, --password password
InfluxDB password
-s step, --step step How many points to import at the same time
-t tags, --tags tags Comma separated list of tags (key:value) for all
points
-D default_measurement, --default-measurement default_measurement
Store all your points in the same measurement
-o override_measurement, --override-measurement override_measurement
Store all your points in the same measurement
-e exclude_entities, --exclude_entities exclude_entities
Comma separated list of excluded entities
-E exclude_domains, --exclude_domains exclude_domains
Comma separated list of excluded domains
-S, --simulate Do not write points but simulate preprocessing
and print statistics
```
## {% linkable_title Examples %} ## {% linkable_title Examples %}
### {% linkable_title Full configuration %} ### {% linkable_title Full configuration %}
```yaml ```yaml

58
source/_docs/configuration/secrets.markdown
View File

@ -53,65 +53,15 @@ logger: debug
``` ```
This will not print the actual secret's value to the log. This will not print the actual secret's value to the log.
*Option 2*: View where secrets are retrieved from and the contents of all `secrets.yaml` files used, you can use the `check_config` script from the command line: *Option 2*: View where secrets are retrieved from and the contents of all `secrets.yaml` files used, you can use the [`check_config` script](/docs/tools/check_config/) from the command line:
```bash ```bash
$ hass --script check_config --secrets $ hass --script check_config --secrets
``` ```
This will print all your secrets. This will print all your secrets.
### {% linkable_title Storing passwords in a keyring managed by your OS %} ## {% linkable_title Alternatives to `secrets.yaml` %}
Using [Keyring](https://github.com/jaraco/keyring) is an alternative way to `secrets.yaml`. They can be managed from the command line via the `keyring` script. - [Using a keyring that is managed by your OS to store secrets](/docs/tools/keyring/)
- [Storing passwords securely in AWS](/docs/tools/credstash/)
```bash
$ hass --script keyring --help
```
To store a password in keyring, replace your password or API key with `!secret` and an identifier in `configuration.yaml` file.
```yaml
http:
api_password: !secret http_password
```
Create an entry in your keyring.
```bash
$ hass --script keyring set http_password
```
If you launch Home Assistant now, you will be prompted for the keyring password to unlock your keyring.
```bash
$ hass
Config directory: /home/homeassistant/.homeassistant
Please enter password for encrypted keyring:
```
<p class='note warning'>
If you are using the Python Keyring, [autostarting](/getting-started/autostart/) of Home Assistant will no longer work.
</p>
### {% linkable_title Storing passwords securely in AWS %}
Using [Credstash](https://github.com/fugue/credstash) is an alternative way to `secrets.yaml`. They can be managed from the command line via the credstash script.
Before using credstash, you need to set up AWS credentials either via the `aws` command line tool or using environment variables as explained in the [AWS CLI docs](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) as well as creating a KMS key named `credstash` as explained in the [credstash Readme](https://github.com/fugue/credstash#setting-up-kms). After that is complete, you can use the provided script to add secrets to your Home Assistant secret store in credstash.
```bash
$ hass --script credstash --help
```
To store a password in credstash, replace your password or API key with `!secret` and an identifier in `configuration.yaml` file.
```yaml
http:
api_password: !secret http_password
```
Create an entry in your credstash store.
```bash
$ hass --script credstash set http_password
```

20
source/_docs/tools/benchmark.markdown Normal file
View File

@ -0,0 +1,20 @@
---
layout: page
title: "benchmark"
description: "Script to perform benchmarking of Home Assistant"
release_date: 2017-02-23 11:00:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /docs/tools/scripts/#benchmark
---
For testing the performance of Home Assistant the Benchmark script runs until you exit using Control+C.
Firing and handling of a million events.
```bash
$ hass --script benchmark async_million_events
```

18
source/_docs/tools/check_config.markdown Normal file
View File

@ -0,0 +1,18 @@
---
layout: page
title: "check_config"
description: "Script to perform a check of the current configuration"
release_date: 2017-02-23 11:00:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /docs/tools/scripts/#configuration-check
---
Test any changes to your `configuration.yaml` file before launching Home Assistant. This script allows you to test changes without the need to restart Home Assistant.
```bash
$ hass --script check_config
```

33
source/_docs/tools/credstash.markdown Normal file
View File

@ -0,0 +1,33 @@
---
layout: page
title: "credstash"
description: "Script to store credentials securely in AWS"
release_date: 2017-02-23 11:00:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /docs/configuration/secrets/#storing-passwords-securely-in-aws
---
Using [Credstash](https://github.com/fugue/credstash) is an alternative way to `secrets.yaml`. They can be managed from the command line via the credstash script.
Before using credstash, you need to set up AWS credentials either via the `aws` command line tool or using environment variables as explained in the [AWS CLI docs](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) as well as creating a KMS key named `credstash` as explained in the [credstash Readme](https://github.com/fugue/credstash#setting-up-kms). After that is complete, you can use the provided script to add secrets to your Home Assistant secret store in credstash.
```bash
$ hass --script credstash --help
```
To store a password in credstash, replace your password or API key with `!secret` and an identifier in `configuration.yaml` file.
```yaml
http:
api_password: !secret http_password
```
Create an entry in your credstash store.
```bash
$ hass --script credstash set http_password
```

72
source/_docs/tools/db_migrator.markdown Normal file
View File

@ -0,0 +1,72 @@
---
layout: page
title: "db_migrator"
description: "Script to migrate data in an InfluxDB database"
release_date: 2017-02-23 11:00:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /components/influxdb/#data-migration
---
<p class='note warning'>
This script was only use for 0.36 release cycle!
</p>
Starting with 0.36 the [InfluxDB](omponents/influxdb/) component has a new schema to store values in the InfluxDB databases.
- There will no longer be any tags/fields named `time`.
- All numeric fields (int/float/bool) will be stored as float inside InfluxDB database.
- All string fields corresponding to state attributes will be renamed as `FIELDNAME_str`, where `FIELDNAME` is the state attribute, to avoid type conflicts.
- All string fields corresponding to a state will be renamed as `state` (former value).
- Fields named `value` will always be stored as float.
- Fields named `state` will always be stored as string.
## {% linkable_title Migration script %}
If you need to migrate your database, you may require to run the `influxdb_migrator` script. Run the script after upgrade to 0.36 but before the first regular start of `hass` version 0.36.
These are the steps the script will perform:
1. Create a new database (called `DBNAME__old`) to store old data.
2. Copy data from `DBNAME` database to `DBNAME__old` database.
3. Empty `DBNAME` database (using `drop` then `create`). `DBNAME` database is now considered as the new database.
4. For each measurement of `DBNAME__old` database:
1. Read all points from the current measurement (in groups of 1000 points by default) and convert them.
2. Send group of points to `DBNAME` database.
5. Delete the `DBNAME__old` database if needed.
Example to run the script:
```bash
$ hass --script influxdb_migrator \
-H IP_INFLUXDB_HOST -u INFLUXDB_USERNAME -p INFLUXDB_PASSWORD \
-d INFLUXDB_DB_NAME
```
Script arguments:
```
required arguments:
-d dbname, --dbname dbname InfluxDB database name
optional arguments:
-h, --help show this help message and exit
-H host, --host host InfluxDB host address
-P port, --port port InfluxDB host port
-u username, --username username
InfluxDB username
-p password, --password password
InfluxDB password
-s step, --step step How many points to migrate at the same time
-o override_measurement, --override-measurement override_measurement
Store all your points in the same measurement
-D, --delete Delete old database
```
- If you run the script with only the `-h` option, you will get a help printout with a short explanation of the different options.
- The host option defaults to `'127.0.0.1'`.
- The port option defaults to `8086`.
- You should be able to omit username and password if InfluxDB authentication is disabled, which it is by default.
- The step option defaults to `1000`.

18
source/_docs/tools/ensure_config.markdown Normal file
View File

@ -0,0 +1,18 @@
---
layout: page
title: "ensure_config"
description: "Script to perform a check if the configuration file exists"
release_date: 2017-02-23 11:00:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /docs/tools/scripts/#existence-of-configuration
---
This script checks if the `configuration.yaml` file exists. If the file is not available, one is created.
```bash
$ hass --script ensure_config
```

64
source/_docs/tools/influxdb_import.markdown Normal file
View File

@ -0,0 +1,64 @@
---
layout: page
title: "influxdb_import"
description: "Script to import data into an InfluxDB database"
release_date: 2017-02-23 11:00:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /components/influxdb/#data-import-script
---
If you want to import all the recorded data from your recorder database you can use the data import script. It will read all your state_change events from the database and add them as data-points to the InfluxDB. You can specify the source database either by pointing the `--config` option to the config directory which includes the default SQLite database or by giving a sqlalchemy connection URI with `--uri`.
The writing to InfluxDB is done in batches that can be changed with `--step`.
You can control, which data is imported by using the command line options `--exclude_entities` and `--exclude_domains`. Both get a comma separated list of either entity-ids or domain names that are excluded from the import.
To test what gets imported you can use the `--simulate` option, which disables the actual write to the InfluxDB instance. This only writes the statistics how much points would be imported from which entity.
Example to run the script:
```bash
$ hass --script influxdb_import --config CONFIG_DIR \
-H IP_INFLUXDB_HOST -u INFLUXDB_USERNAME -p INFLUXDB_PASSWORD \
--dbname INFLUXDB_DB_NAME --exclude_domains automation,configurator
```
Script arguments:
```
required arguments:
-d dbname, --dbname dbname
InfluxDB database name
optional arguments:
-h, --help show this help message and exit
-c path_to_config_dir, --config path_to_config_dir
Directory that contains the Home Assistant
configuration
--uri URI Connect to URI and import (if other than default
sqlite) eg: mysql://localhost/homeassistant
-H host, --host host InfluxDB host address
-P port, --port port InfluxDB host port
-u username, --username username
InfluxDB username
-p password, --password password
InfluxDB password
-s step, --step step How many points to import at the same time
-t tags, --tags tags Comma separated list of tags (key:value) for all
points
-D default_measurement, --default-measurement default_measurement
Store all your points in the same measurement
-o override_measurement, --override-measurement override_measurement
Store all your points in the same measurement
-e exclude_entities, --exclude_entities exclude_entities
Comma separated list of excluded entities
-E exclude_domains, --exclude_domains exclude_domains
Comma separated list of excluded domains
-S, --simulate Do not write points but simulate preprocessing
and print statistics
```

42
source/_docs/tools/keyring.markdown Normal file
View File

@ -0,0 +1,42 @@
---
layout: page
title: "keyring"
description: "Script to store secrets in a keyring"
release_date: 2017-02-23 11:00:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /docs/configuration/secrets/#storing-passwords-in-a-keyring-managed-by-your-os
---
Using [Keyring](https://github.com/jaraco/keyring) is an alternative way to `secrets.yaml`. The secrets can be managed from the command line via the `keyring` script.
```bash
$ hass --script keyring --help
```
To store a password in keyring, replace your password or API key with `!secret` and an identifier in `configuration.yaml` file.
```yaml
http:
api_password: !secret http_password
```
Create an entry in your keyring.
```bash
$ hass --script keyring set http_password
```
If you launch Home Assistant now, you will be prompted for the keyring password to unlock your keyring.
```bash
$ hass
Config directory: /home/homeassistant/.homeassistant
Please enter password for encrypted keyring:
```
<p class='note warning'>
If you are using the Python Keyring, [autostarting](/getting-started/autostart/) of Home Assistant will no longer work.
</p>

42
source/_docs/tools/scripts.markdown
View File

@ -7,47 +7,7 @@ sidebar: true
comments: false comments: false
sharing: true sharing: true
footer: true footer: true
redirect_from: /docs/tools/
--- ---
The command-line and the frontend which simplify common tasks, are helping with migrations, and ensure that Home Assistant runs properly. Please do not confuse those with Home Assistant's [script](/docs/scripts/) feature.
### {% linkable_title Configuration check %}
Test any changes to your `configuration.yaml` file before launching Home Assistant. This script allows you to test changes without the need to restart Home Assistant.
```bash
$ hass --script check_config
```
### {% linkable_title Existence of configuration %}
This script checks if the `configuration.yaml` file exists. If the file is not available, one is created.
```bash
$ hass --script ensure_config
```
### {% linkable_title Secrets %}
There is a method to store secrets outside of your `configuration.yaml` file. For further details, please refer to the [Storing Secrets](/docs/configuration/secrets/) documentation.
```bash
$ hass --script keyring
```
### {% linkable_title Benchmark %}
For testing the performance of Home Assistant the Benchmark script runs until you exit using Control+C.
Firing and handling of a million events.
```bash
$ hass --script benchmark async_million_events
```
### {% linkable_title Old scripts %}
Usually those scripts were only used when a massive update happened and was announced in the release notes.
- `db_migrator`: Migrate an existing SQLite database to the new schema.
- `influxdb_migrator`: Convert an old InfluxDB to the new format.

8
source/_includes/asides/docs_navigation.html
View File

@ -87,7 +87,13 @@
<ul> <ul>
<li>{% active_link /docs/tools/dev-tools/ Developer Tools %}</li> <li>{% active_link /docs/tools/dev-tools/ Developer Tools %}</li>
<li>{% active_link /docs/tools/hass/ hass %}</li> <li>{% active_link /docs/tools/hass/ hass %}</li>
<li>{% active_link /docs/tools/scripts/ Scripts %}</li> <li>{% active_link /docs/tools/benchmark/ benchmark %}</li>
<li>{% active_link /docs/tools/check_config/ check_config %}</li>
<li>{% active_link /docs/tools/credstash/ credstash %}</li>
<li>{% active_link /docs/tools/db_migrator/ db_migrator %}</li>
<li>{% active_link /docs/tools/ensure_config/ ensure_config %}</li>
<li>{% active_link /docs/tools/influxdb_import/ influxdb_import %}</li>
<li>{% active_link /docs/tools/keyring/ keyring %}</li>
</ul> </ul>
</li> </li>
<li> <li>