Skip to content

Commit 8a573cc

Browse files
axxelGaxxelG
committed
Move documentation from branch to subfolder
1 parent a78e1a9 commit 8a573cc

File tree

6 files changed

+189
-0
lines changed

6 files changed

+189
-0
lines changed

‎docs/config.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Config
2+
3+
## Config settings
4+
5+
| Property | Description | Default |
6+
|---------------------|-------------|---------|
7+
| ConfigFile | Path and filename to the config file | OS dependent |
8+
| LogFileMain | Path and filename to the main log file | stdout |
9+
| LogFileHTTPError | Path and filename to the HTTP error log | stdout |
10+
| LogFileHTTPAccess | Path and filename to the HTTP access log | stdout |
11+
| ControlsFiles | Path of the directory containing controls files | OS dependent |
12+
| ListenPort | Local TCP port where loxwebhook will listen. You can choose any [valid](https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers) and free local port as long as loxwebhook is reachable on port 443 from the public internet. | 443 |
13+
| PublicURI | URI (host and domain) where loxwebhook will be reachable on the public internet | none |
14+
| LetsEncryptCache | Path of the directory where we will store the Let's Encrypt cache. It's important to keep the cache during restarts to avoid hitting Let's Encrypt [rate limits](https://letsencrypt.org/docs/rate-limits/) | `./cache/letsencrypt` |
15+
| MiniserverURL | URL to reach the Loxone Miniserver including protocol and port `http://192.168.123.1:80` | none |
16+
| MiniserverUser | Username to access the Loxone Miniserver | `admin` |
17+
| MiniserverPassword | Password to access the Loxone Miniserver | `admin` |
18+
| MiniserverTimeout | Timeout (seconds) for requests to Loxone Miniserver | 2 |
19+
20+
## Set config values
21+
22+
You can set config values in a config file, set environment variables or set flags when you start loxwebhook.
23+
24+
Settings in environment variables will overwrite settings in a config file and settings given by flags will overwrite both.
25+
26+
## Config file
27+
28+
You can use `config.example.toml` ([online](https://github.com/axxelG/loxwebhook/blob/master/config.example.toml)) as a starting point
29+
30+
The default location for the config file depends on the operating system.
31+
32+
- Windows: `.\config.toml`
33+
- Other (Linux): `/etc/loxwebhook/config.toml`
34+
35+
You can set a custom file location via environment variable or by flag
36+
37+
- Environment variable: Set `LOXWEBHOOK_CONFIG` to `<path>/<filename>`
38+
- Flag: Call `loxwebhook --config <path>/<filename>`
39+
40+
## Environment variables
41+
42+
- Must be prefixed with `LOXWEBHOOK_`
43+
- Must be all uppercase
44+
45+
Examples:
46+
47+
- Windows:
48+
- cmd `set LOXWEBHOOK_LISTENPORT=1234`
49+
- powershell `$env:LOXWEBHOOK_LISTENPORT = 1234`
50+
- Linux: `export LOXWEBHOOK_LISTENPORT=1234`
51+
52+
## Flags
53+
54+
Use `loxwebhook -h` to get a list with all possible flags

‎docs/controls_files.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# controls files
2+
3+
## Controls directory
4+
5+
You can use `controls.d/example.toml.disable` ([online version](https://github.com/axxelG/loxwebhook/blob/master/controls.d/example.toml.disabled)) as a good starting point to create your own controls file.
6+
7+
All filles ending with `.toml` in the controls directory will be imported.
8+
9+
The decision to keep everything in one file or use multiple files is up to you. All authentication keys and names of controls must be unique for all files. If you have configured an authentication key `Key1` in `file1.toml` you cannot configure `Key1` again in `file2.toml` but you can use `Key1` in a control definition in `file2.toml`.
10+
11+
## Controls files
12+
13+
Control files must be valid [TOML](https://github.com/toml-lang/toml)
14+
15+
### Section `[AuthKeys]`
16+
17+
List of key/value pairs. Format: `name = "key"`
18+
You can use any ASCII-Character (A-Z upper and lower case), numbers, hyphens (-) and underscores (_). Authentication keys are case sensitive.
19+
20+
Example
21+
22+
```toml
23+
[AuthKeys]
24+
testOne = "43b2c690-f281-42bb-af2d-979f5dbe9517"
25+
testTwo = "69b9a1ad-1224-4c93-8411-e88e65ebe582"
26+
testThree = "84627dbd-bd68-476f-9e53-35522285783b"
27+
```
28+
29+
### Section `[Controls]`
30+
31+
Table (dictionary) of control definitions.
32+
33+
### Control definition
34+
35+
The name of a control definition must only consist of ASCII-Characters (A-Z), numbers, hyphens (-) and underscores (_).
36+
37+
| Field | Descriptions |
38+
|----------|---------------------------------------------------------------|
39+
| Category | Type of control. Currently only `dvi` for "digital virtual input" is supported |
40+
| ID | Miniserver internal ID number of the control. You can find the ID number in Loxone Config if you select the control and look at Property / Common / Connection |
41+
| Allowed | Array of allowed commands. You can find a list of allowed command on the [Loxone website](https://www.loxone.com/enen/kb/web-services/) |
42+
| AuthKeys | Array of key names that can access this control. The names must exactly match a name configured in Section `[AuthKeys]`. You can use authentication keys defined in another controls file. |
43+
44+
Examples
45+
46+
```toml
47+
[Controls.test1]
48+
Category = "dvi"
49+
ID = 7
50+
Allowed = [
51+
"on",
52+
]
53+
AuthKeys = [
54+
"testOne",
55+
]
56+
57+
[Controls.test2]
58+
Category = "dvi"
59+
ID = 6
60+
Allowed = [
61+
"on",
62+
"off",
63+
]
64+
AuthKeys = [
65+
"testTwo",
66+
"testThree",
67+
]
68+
```

‎docs/index.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# loxwebhook
2+
3+
## Quickstart
4+
5+
You can find everything you need for a quick start on the projects github page: [https://github.com/axxelG/loxwebhook](https://github.com/axxelG/loxwebhook)
6+
7+
## Documentation
8+
9+
- [Security Q & A](security_qa.md)
10+
- [Config](config.md)
11+
- [Request](request.md)
12+
- [Controls files](controls_files.md)

‎docs/request.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Request
2+
3+
## Parts of a request
4+
5+
A request to loxwebhook looks like this:
6+
7+
`https://your.domain.com/dvi/garage_door/open?k=11111111-1111-1111-1111-111111111111`
8+
9+
or more abstract
10+
11+
`https://domain/control_type/control_name/control_action?k=SecretKey`
12+
13+
| Part | Description |
14+
| --------- | ---------------------------------- |
15+
| domain | The domain where the server that runs loxwebhook is reachable |
16+
| control_type | The type of the control we are accessing. Currently only `dvi` for "Digital virtual input" is supported |
17+
| control_name | The name of the control. It must exactly match the name we used in the [controls file](controls_files.md). |
18+
| control_action | The action we want to send to the control. The action must be allowed in the [controls file](controls_files.md). |
19+
| SecretKey | A secret key configured in the [controls file](controls_files.md). Please read and understand the [Security Q&A](security_qa.md) before you choose a key. |
20+
21+
## Additional parameters
22+
23+
| Parameter | Descriptions |
24+
|-------------|--------------|
25+
| simulate | Prevents loxwebhook from sending requests to the Loxone Miniserver and returns config details |

‎docs/security_qa.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Security Q & A
2+
3+
## Is it secure to use loxwebhook and expose my Loxone Miniserver to the public internet?
4+
5+
Yes, beside the fact that it is never 100 % secure to connect something to the internet, you can consider the usage as secure. Loxwebhook has implemented measurements to mitigate the risks:
6+
7+
1. **Key authentication** A request is only forwarded to the Loxone Miniserver if a matching authentication key is provided. Please read the question "How can I be sure my authentication keys are secure?" on this page.
8+
9+
1. **Transport layer encryption** Data that is transferred over the public internet is [TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) encrypted. Only [https](https://en.wikipedia.org/wiki/HTTPS) connections are allowed. A widely trusted [CA](https://en.wikipedia.org/wiki/Certificate_authority) ([Let's Encrypt](https://letsencrypt.org/)) is used. This keeps the data save while it is on the public internet.
10+
11+
1. **Rate limiting for Requests** Loxwebhook does not accept more than ~1 request per second. This makes [brute force attacks](https://en.wikipedia.org/wiki/Brute-force_attack) on the secret keys nearly impossible and prevents the Loxone Miniserver from being overloaded.
12+
13+
Beside all security measurements provided by Loxwebhook you need to be aware that every use case for loxwebhook involves someone who sends requests. You need to trust this second party.
14+
15+
## How can I be sure my authentication keys are secure?
16+
17+
Everybody who knows a key can access the assigned control(s) on you Loxone Miniserver. That's why you must keep them secret. You can (and should) use any ASCII-Character (A-Z upper and lower case), numbers, hyphens (-) and underscores (_).
18+
19+
- Use hard to guess and long keys. It's obvious that a key like "lamp" is not suitable. UUIDs are a good choice. You can easily create them. Use `cat /proc/sys/kernel/random/uuid` on Linux or `[guid]::NewGuid()` in Windows Powershell.
20+
21+
- Create a unique authentication key for every purpose.

‎docs/supported_os.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Supported operating systems
2+
3+
| OS | Support | Install |
4+
|-------------|-------------------------------------|---------|
5+
| Raspian | Fully tested and used in production | .deb-package
6+
| Debian | Not tested but very likely to work | .deb-package
7+
| Other Linux | Not tested but might work | binaries provided manually config necessary |
8+
| Windows 10 | Tested during development but not in production | binaries provided manually config necessary |
9+
| Windows Server 2016 | Will most probably work but is not tested | binaries provided manually config necessary |

0 commit comments

Comments
 (0)