Pi-Hole/docs
1
0
Fork 0
mirror of https://github.com/pi-hole/docs.git synced 2025-12-20 03:08:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1182 from buckaroogeek/webpassword

Browse Source 
Add notes on setting web interface password
This commit is contained in:
Adam Warner
2025-03-09 20:55:59 +00:00
committed by GitHub
parent e857a2d934 bcf85debca
commit 444c2c1ba0
1 changed files with 107 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

123
docs/docker/configuration.md
View File

@@ -4,22 +4,6 @@ The recommended way to configure the Pi-hole docker container is by utilizing [e
## Environment Variables ## Environment Variables
### Recommended Variables
#### `TZ` (Default: `UTC`)
Set your [timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) to make sure logs rotate at local midnight instead of at UTC midnight.
#### `FTLCONF_webserver_api_password` (Default: `unset`)
To set a specific password for the web interface, use the environment variable `FTLCONF_webserver_api_password` (per the quick-start example). If this variable is not detected, and you have not already set one previously inside the container via `pihole setpassword` or `pihole-FTL --config webserver.api.password`, then a random password will be assigned on startup, and will be printed to the log. You can find this password with the command `docker logs pihole | grep random password` on your host to find this password.
#### `FTLCONF_dns_upstreams` (Default: `8.8.8.8;8.8.4.4`)
- Upstream DNS server(s) for Pi-hole to forward queries to, separated by a semicolon
- Supports non-standard ports with #[port number] e.g `127.0.0.1#5053;8.8.8.8;8.8.4.4`
- Supports Docker service names and links instead of IPs e.g `upstream0;upstream1` where upstream0 and upstream1 are the service names of or links to docker services
### Configuring FTL Via The Environment ### Configuring FTL Via The Environment
While FTL's configuration file can be manually edited, set via the CLI (`pihole-FTL --config setting.name=value`), or set via the web interface - the recommended approach is to do this via environment variables While FTL's configuration file can be manually edited, set via the CLI (`pihole-FTL --config setting.name=value`), or set via the web interface - the recommended approach is to do this via environment variables
@@ -50,6 +34,22 @@ An example of how some of these variables may look in your compose file
FTLCONF_debug_api: 'true' FTLCONF_debug_api: 'true'
``` ```
### Recommended Variables
#### `TZ` (Default: `UTC`)
Set your [timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) to make sure logs rotate at local midnight instead of at UTC midnight.
#### `FTLCONF_webserver_api_password` (Default: `unset`)
To set a specific password for the web interface, use the environment variable `FTLCONF_webserver_api_password` (per the quick-start example). If this variable is not detected, and you have not already set one previously inside the container via `pihole setpassword` or `pihole-FTL --config webserver.api.password`, then a random password will be assigned on startup, and will be printed to the log. You can find this password with the command `docker logs pihole | grep random password` on your host to find this password. See [Notes On Web Interface Password](#notes-on-web-interface-password) below for usage examples.
#### `FTLCONF_dns_upstreams` (Default: `8.8.8.8;8.8.4.4`)
- Upstream DNS server(s) for Pi-hole to forward queries to, separated by a semicolon
- Supports non-standard ports with #[port number] e.g `127.0.0.1#5053;8.8.8.8;8.8.4.4`
- Supports Docker service names and links instead of IPs e.g `upstream0;upstream1` where upstream0 and upstream1 are the service names of or links to docker services
### Other Variables ### Other Variables
#### `TAIL_FTL_LOG` (Default: `1`) #### `TAIL_FTL_LOG` (Default: `1`)
@@ -85,8 +85,99 @@ Adding packages here is the same as running `apk add <package>` inside the conta
Setting this environment variable to `1` will set `-x`, making the scripts that run on container startup more verbose. Useful for debugging only. Setting this environment variable to `1` will set `-x`, making the scripts that run on container startup more verbose. Useful for debugging only.
#### `WEBPASSWORD_FILE` (Default: unset)
Set the web interface password using [Docker Compose Secrets](https://docs.docker.com/compose/how-tos/use-secrets/) if using Compose or [Docker Swarm secrets](https://docs.docker.com/engine/swarm/secrets/) if using Docker Swarm. If `FTLCONF_webserver_api_password` is set, `WEBPASSWORD_FILE` is ignored. If `FTLCONF_webserver_api_password` is empty, and `WEBPASSWORD_FILE` is set to a valid readable file path, then `FTLCONF_webserver_api_password` will be set to the contents of `WEBPASSWORD_FILE`. See [Notes On Web Interface Password](#notes-on-web-interface-password) below for usage examples.
### Variable Formatting ### Variable Formatting
Environment variables may be set in the format given here, or they may be entirely uppercase in the conventional manner. Environment variables may be set in the format given here, or they may be entirely uppercase in the conventional manner.
For example, both `FTLCONF_dns_upstreams` and `FTLCONF_DNS_UPSTREAMS` are functionally equivalent when used as environment variables. For example, both `FTLCONF_dns_upstreams` and `FTLCONF_DNS_UPSTREAMS` are functionally equivalent when used as environment variables.
## Notes On Web Interface Password
The web interface password can be set using the `FTLCONF_webserver_api_password` environment variable as documented above or using the `WEBPASSWORD_FILE` environment variable using [Docker Compose Secrets](https://docs.docker.com/compose/how-tos/use-secrets/) or [Docker Swarm secrets](https://docs.docker.com/engine/swarm/secrets/).
### `FTLCONF_webserver_api_password` Examples
The `FTLCONF_webserver_api_password` variable can be set in a `docker run` command or as an environment attribute in a Docker Compose yaml file.
#### Docker run example
```bash
docker run --name pihole -p 53:53/tcp -p 53:53/udp -p 80:80/tcp -p 443:443/tcp -e TZ=Europe/London -e FTLCONF_webserver_api_password="correct horse battery staple" -e FTLCONF_dns_listeningMode=all -v ./etc-pihole:/etc/pihole -v ./etc-dnsmasq.d:/etc/dnsmasq.d --cap-add NET_ADMIN --restart unless-stopped pihole/pihole:latest
```
#### Docker Compose examples
Set using a text value.
```yaml
...
environment:
FTLCONF_webserver_api_password: 'correct horse battery staple'
...
```
Set using an [environment variable](https://docs.docker.com/compose/how-tos/environment-variables/) called, for example, `ADMIN_PASSWORD`. The value of `ADMIN_PASSWORD` can be set in the shell of the `docker compose` command or in an `.env` file. See the link above for detailed information.
```yaml
...
environment:
FTLCONF_webserver_api_password: ${ADMIN_PASSWORD}
...
```
Define ADMIN_PASSWORD in shell.
```bash
export ADMIN_PASSWORD=correct horse battery staple
docker compose -f compose.yaml
```
Or define ADMIN_PASSWORD in `.env` file. The `.env` file is placed in the same directory where the Compose yaml file (e.g. `compose.yaml`) is located.
```bash
$ cat .env
ADMIN_PASSWORD=correct horse battery staple
$ docker compose -f compose.yaml
```
### `WEBPASSWORD_FILE` Example
Create a text file called `pihole_password.txt` containing the password in the same directory containing the Compose yaml file (e.g `compose.yaml`).
```bash
$cat pihole_password.txt
correct horse battery staple
```
Amend compose yaml file with Docker Secrets attributes.
```yaml
---
# define pihole service
services:
pihole:
container_name: pihole
image: pihole/pihole:latest
# lines deleted
environment:
WEBPASSWORD_file: pihole_webpasswd
# lines deleted
secrets:
- pihole_webpasswd
restart: unless-stopped
# define pihole_webpasswd secret
secrets:
pihole_webpasswd:
file: ./pihole_password.txt
...
```