Skip to content

Commit

Permalink
✏️ Split add-on documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@frenck
frenck committed May 28, 2020
1 parent fe232c8 commit 501598e
Show file tree
Hide file tree
Showing 3 changed files with 292 additions and 224 deletions.
223 changes: 2 additions & 221 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,224 +37,7 @@ home directories.
Of course, if you'd really want to, you could also use this add-on to again
access to your Home Assistant configuration via FTP.

## Installation

The installation of this add-on is pretty straightforward and not different in
comparison to installing any other Home Assistant add-on.

1. Search for the "FTP" add-on in the Supervisor add-on store and install it.
1. Start the "FTP" add-on
1. Check the logs of the "FTP" add-on to see if everything went well.

## Configuration

**Note**: _Remember to restart the add-on when the configuration is changed._

Example add-on configuration:

```yaml
log_level: info
port: 21
data_port: 20
banner: Welcome to the Hass.io FTP service.
pasv: true
pasv_min_port: 30000
pasv_max_port: 30010
pasv_address: ''
ssl: false
certfile: fullchain.pem
keyfile: privkey.pem
implicit_ssl: false
max_clients: 5
users:
- username: hassio
password: changeme
allow_chmod: true
allow_download: true
allow_upload: true
allow_dirlist: true
addons: false
backup: true
config: true
share: true
ssl: false
- username: camera
password: changeme
allow_chmod: false
allow_download: false
allow_upload: true
allow_dirlist: true
addons: false
backup: false
config: false
share: true
ssl: false
```
**Note**: _This is just an example, don't copy and paste it! Create your own!_
### Option: `log_level`

The `log_level` option controls the level of log output by the addon and can
be changed to be more or less verbose, which might be useful when you are
dealing with an unknown issue. Possible values are:

- `trace`: Show every detail, like all called internal functions.
- `debug`: Shows detailed debug information.
- `info`: Normal (usually) interesting events.
- `warning`: Exceptional occurrences that are not errors.
- `error`: Runtime errors that do not require immediate action.
- `fatal`: Something went terribly wrong. Add-on becomes unusable.

Please note that each level automatically includes log messages from a
more severe level, e.g., `debug` also shows `info` messages. By default,
the `log_level` is set to `info`, which is the recommended setting unless
you are troubleshooting.

These log level also affects the log levels of the FTP server.

### Option: `port`

The port the FTP will listen on for incoming FTP connections.

### Option: `data_port`

The port from which PORT style connections originate.

### Option: `banner`

This string option allows you to provide the greeting banner displayed by
the FTP server when a connection first comes in.

### Option: `pasv`

Set to `false` if you want to disallow the PASV method of obtaining a data
connection. For more information about passive versus active FTP, see
[this excellent Stack Overflow][passive-vs-active] answer.

### Option: `pasv_min_port`

The minimum port to allocate for PASV style data connections. Can be used to
specify a narrow port range to assist firewalling.

### Option: `pasv_max_port`

The maximum port to allocate for PASV style data connections. Can be used to
specify a narrow port range to assist firewalling.

### Option: `pasv_address`

Use this option to override the IP address that the FTP server will advertise
in response to the PASV command. Provide a numeric IP address, or provide a
hostname which will be DNS resolved for you at startup. When left empty, the
address is taken from the incoming connected socket.

### Option: `ssl`

Enables/Disables SSL on the FTP Server. Set it `true` to enable it,
`false` otherwise.

### Option: `certfile`

The certificate file to use for SSL.

**Note**: _The file MUST be stored in `/ssl/`, which is the default_

### Option: `keyfile`

The private key file to use for SSL.

**Note**: _The file MUST be stored in `/ssl/`, which is the default_

### Option: `implicit_ssl`

If set to `true`, an SSL handshake is the first thing expect on all connections
(the FTPS protocol).

### Option: `max_clients`

This is the maximum number of clients which may be connected at the same time.
Any additional clients connecting will get an error message.

### Option: `users`

This option allows you to specify a list of one or more users. Each user can
have its own permissions like defined in the sub-options below.

#### Sub-option: `username`

The username the user needs to use to login to the FTP server. A valid username
has a maximum of 32 characters, contains only `A-Z` and `0-9`.
Usernames may contain a hyphen (`-`) but must not start or end with one.

#### Sub-option: `password`

The password the user logs in with.

#### Sub-option: `allow_chmod`

Setting this option to `true` will allow the use of the `SITE CHMOD` command for
that user.

#### Sub-option: `allow_download`

Setting this option to `true` will allow the user to download files from the
FTP server.

#### Sub-option: `allow_upload`

This controls whether any FTP commands which change the filesystem are
allowed or not.

These commands are `STOR`, `DELE`, `RNFR`, `RNTO`, `MKD`, `RMD`,
`APPE`, and `SITE`.

#### Sub-option: `allow_dirlist`

Setting this option to `true`, allows to user to browse all directories
the user was given access to by using the list commands.

#### Sub-option: `addons`

Allow the user to access the `/addons` directory.

#### Sub-option: `backup`

Allow the user to access the `/backup` directory.

#### Sub-option: `config`

Allow the user to access the `/config` directory.

#### Sub-option: `share`

Allow the user to access the `/share` directory.

#### Sub-option: `ssl`

Allow the user to access the `/ssl` directory.

### Option: `i_like_to_be_pwned`

Adding this option to the add-on configuration allows to you bypass the
HaveIBeenPwned password requirement by setting it to `true`.

**Note**: _We STRONGLY suggest picking a stronger/safer password instead of
using this option! USE AT YOUR OWN RISK!_

## Changelog & Releases

This repository keeps a change log using [GitHub's releases][releases]
functionality. The format of the log is based on
[Keep a Changelog][keepchangelog].

Releases are based on [Semantic Versioning][semver], and use the format
of ``MAJOR.MINOR.PATCH``. In a nutshell, the version will be incremented
based on the following:

- ``MAJOR``: Incompatible or major changes.
- ``MINOR``: Backwards-compatible new features and enhancements.
- ``PATCH``: Backwards-compatible bugfixes and package updates.
[:books: Read the full add-on documentation][docs]

## Support

Expand Down Expand Up @@ -329,17 +112,16 @@ SOFTWARE.
[discord-ha]: https://discord.gg/c5DvZ4e
[discord-shield]: https://img.shields.io/discord/478094546522079232.svg
[discord]: https://discord.me/hassioaddons
[docs]: https://github.com/hassio-addons/addon-ftp/blob/master/ftp/DOCS.md
[forum-shield]: https://img.shields.io/badge/community-forum-brightgreen.svg
[forum]: https://community.home-assistant.io/t/home-assistant-community-add-on-ftp/36799?u=frenck
[frenck]: https://github.com/frenck
[github-sponsors-shield]: https://frenck.dev/wp-content/uploads/2019/12/github_sponsor.png
[github-sponsors]: https://github.com/sponsors/frenck
[gitlabci-shield]: https://gitlab.com/hassio-addons/addon-ftp/badges/master/pipeline.svg
[gitlabci]: https://gitlab.com/hassio-addons/addon-ftp/pipelines
[home-assistant]: https://home-assistant.io
[i386-shield]: https://img.shields.io/badge/i386-yes-green.svg
[issue]: https://github.com/hassio-addons/addon-ftp/issues
[keepchangelog]: http://keepachangelog.com/en/1.0.0/
[license-shield]: https://img.shields.io/github/license/hassio-addons/addon-ftp.svg
[maintenance-shield]: https://img.shields.io/maintenance/yes/2020.svg
[passive-vs-active]: https://stackoverflow.com/a/1699163/299699
Expand All @@ -350,4 +132,3 @@ SOFTWARE.
[releases-shield]: https://img.shields.io/github/release/hassio-addons/addon-ftp.svg
[releases]: https://github.com/hassio-addons/addon-ftp/releases
[repository]: https://github.com/hassio-addons/repository
[semver]: http://semver.org/spec/v2.0.0.htm
3 changes: 0 additions & 3 deletions ftp/.README.j2
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,6 @@ home directories.
Of course, if you'd really want to, you could also use this add-on to again
access to your Home Assistant configuration via FTP.

[Click here for the full documentation][docs]

{% if channel == "edge" %}
## WARNING! THIS IS AN EDGE VERSION!

Expand Down Expand Up @@ -67,7 +65,6 @@ If you are more interested in stable releases of our add-ons:
{% endif %}
[discord-shield]: https://img.shields.io/discord/478094546522079232.svg
[discord]: https://discord.me/hassioaddons
[docs]: {{ repo }}/blob/{{ version }}/README.md
[forum-shield]: https://img.shields.io/badge/community-forum-brightgreen.svg
[forum]: https://community.home-assistant.io/t/home-assistant-community-add-on-ftp/36799?u=frenck
[github-sponsors-shield]: https://frenck.dev/wp-content/uploads/2019/12/github_sponsor.png
Expand Down
Loading

0 comments on commit 501598e

Please sign in to comment.