cwinfo/powerdns-admin
5
0
Fork 0
mirror of https://github.com/cwinfo/powerdns-admin.git synced 2024-11-08 14:40:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1327 from dmcken/docs-updates

Browse Source 
Docs updates
This commit is contained in:
Matt Scott 2022-12-13 08:20:27 -05:00 committed by GitHub
commit c03f799c4a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 134 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
docs/wiki/README.md
View File

@ -1,10 +1,12 @@
# Welcome to the PowerDNS-Admin wiki!
# PowerDNS-Admin wiki
## Database Setup guides
## Database Setup guides:
- [MySQL / MariaDB](database-setup/Setup-MySQL-or-MariaDB.md)
- [PostgreSQL](database-setup/Setup-PostgreSQL.md)
## Installation guides:
## Installation guides
- [General (Read this first)](install/General.md)
- BSD:
- [Install on FreeBSD 12.1-RELEASE](install/Running-on-FreeBSD.md)
@ -17,16 +19,15 @@
- [Install on Fedora 23](install/Running-PowerDNS-Admin-on-Fedora-23.md)
- [Install on Fedora 30](install/Running-PowerDNS-Admin-on-Fedora-30.md)
### Post install Setup
### Post install Setup:
- [Environment Variables](configuration/Environment-variables.md)
- [Getting started](configuration/Getting-started.md)
- SystemD:
- [Running PowerDNS-Admin as a service using Systemd](install/Running-PowerDNS-Admin-as-a-service-(Systemd).md)
### Web Server configuration:
### Web Server configuration
- [Supervisord](web-server/Supervisord-example.md)
- [Systemd](web-server/Systemd-example.md)
- [Systemd + Gunicorn + Nginx](web-server/Running-PowerDNS-Admin-with-Systemd-Gunicorn-and-Nginx.md)
@ -34,10 +35,12 @@
- [uWSGI](web-server/uWSGI-example.md)
- [WSGI-Apache](web-server/WSGI-Apache-example.md)
## Using PowerDNS-Admin:
## Using PowerDNS-Admin
- Setting up a domain
- Adding a record
- <whatever else>
## Feature usage
- [DynDNS2](features/DynDNS2.md)

56
docs/wiki/configuration/Environment-variables.md
View File

@ -2,8 +2,60 @@
| Variable | Description | Required | Default value |
| ---------| ----------- | -------- | ------------- |
| SQLALCHEMY_DATABASE_URI | SQL Alchemy URI to connect to database | N | no default |
| BIND_ADDRESS |
| CSRF_COOKIE_SECURE |
| FILESYSTEM_SESSIONS_ENABLED |
| LDAP_ENABLED |
| LOCAL_DB_ENABLED |
| LOG_LEVEL |
| MAIL_DEBUG |
| MAIL_DEFAULT_SENDER |
| MAIL_PASSWORD |
| MAIL_PORT |
| MAIL_SERVER |
| MAIL_USERNAME |
| MAIL_USE_SSL |
| MAIL_USE_TLS |
| OFFLINE_MODE |
| OIDC_OAUTH_API_URL | | | |
| OIDC_OAUTH_AUTHORIZE_URL |
| OIDC_OAUTH_TOKEN_URL | | | |
| PORT |
| REMOTE_USER_COOKIES |
| REMOTE_USER_LOGOUT_URL |
| SALT |
| SAML_ASSERTION_ENCRYPTED |
| SAML_ATTRIBUTE_ACCOUNT |
| SAML_ATTRIBUTE_ADMIN |
| SAML_ATTRIBUTE_EMAIL |
| SAML_ATTRIBUTE_GIVENNAME |
| SAML_ATTRIBUTE_GROUP |
| SAML_ATTRIBUTE_NAME |
| SAML_ATTRIBUTE_SURNAME |
| SAML_ATTRIBUTE_USERNAME |
| SAML_CERT |
| SAML_DEBUG |
| SAML_ENABLED |
| SAML_GROUP_ADMIN_NAME |
| SAML_GROUP_TO_ACCOUNT_MAPPING |
| SAML_IDP_SSO_BINDING |
| SAML_IDP_ENTITY_ID |
| SAML_KEY |
| SAML_LOGOUT |
| SAML_LOGOUT_URL |
| SAML_METADATA_CACHE_LIFETIME |
| SAML_METADATA_URL |
| SAML_NAMEID_FORMAT |
| SAML_PATH |
| SAML_SIGN_REQUEST |
| SAML_SP_CONTACT_MAIL |
| SAML_SP_CONTACT_NAME |
| SAML_SP_ENTITY_ID |
| SAML_WANT_MESSAGE_SIGNED |
| SECRET_KEY | Flask secret key [^1] | Y | no default |
| SESSION_COOKIE_SECURE |
| SIGNUP_ENABLED |
| SQLALCHEMY_DATABASE_URI | SQL Alchemy URI to connect to database | N | no default |
| SQLALCHEMY_TRACK_MODIFICATIONS |
[^1]: Flask secret key (see https://flask.palletsprojects.com/en/1.1.x/config/#SECRET_KEY for how to generate)

28
docs/wiki/database-setup/Setup-MySQL-or-MariaDB.md
View File

@ -2,28 +2,35 @@
This guide will show you how to prepare a MySQL or MariaDB database for PowerDNS-Admin.
We assume the database is installed per your platform's directions (apt, yum, etc).
We assume the database is installed per your platform's directions (apt, yum, etc). Directions to do this can be found below:
- MariaDB:
- https://mariadb.com/kb/en/getting-installing-and-upgrading-mariadb/
- https://www.digitalocean.com/community/tutorials/how-to-install-mariadb-on-ubuntu-20-04
- MySQL:
- https://dev.mysql.com/downloads/mysql/
- https://www.digitalocean.com/community/tutorials/how-to-install-mysql-on-ubuntu-20-04
The following directions assume a default configuration and for productions setups `mysql_secure_installation` has been run.
## Setup database:
Connect to the database (Usually using `mysql -u root -p` - then enter your MySQL/MariaDB root users password if applicable), then enter the following:
Connect to the database (Usually using `mysql -u root -p` if a password has been set on the root database user or `sudo mysql` if not), then enter the following:
```
CREATE DATABASE `powerdnsadmin` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
GRANT ALL PRIVILEGES ON `powerdnsadmin`.* TO 'pdnsadminuser'@'localhost' IDENTIFIED BY 'YOUR_PASSWORD_HERE';
FLUSH PRIVILEGES;
quit
```
- If your database server is located on a different machine then change 'localhost' to '%'
- Replace YOUR_PASSWORD_HERE with a secure password.
Once there are no errors you can type `quit` in the mysql shell to exit from it.
## Install required packages:
### Red-hat based systems:
```
yum install MariaDB-shared mariadb-devel mysql-community-devel
```
If you use MariaDB ( from [MariaDB repositories](https://mariadb.com/resources/blog/installing-mariadb-10-on-centos-7-rhel-7/) )
### Debian based systems:
```
apt install libmysqlclient-dev
@ -34,7 +41,6 @@ apt install libmysqlclient-dev
pip3 install mysqlclient==2.0.1
```
## Known issues:
Problem: If you plan to manage large zones, you may encounter some issues while applying changes. This is due to PowerDNS-Admin trying to insert the entire modified zone into the column history.detail.
@ -42,7 +48,9 @@ Problem: If you plan to manage large zones, you may encounter some issues while
Using MySQL/MariaDB, this column is created by default as TEXT and thus limited to 65,535 characters.
Solution: Convert the column to MEDIUMTEXT:
```
USE powerdnsadmin;
ALTER TABLE history MODIFY detail MEDIUMTEXT;
```
1. Connect to the database shell as described in the setup database section:
2. Execute the following commands:
```
USE powerdnsadmin;
ALTER TABLE history MODIFY detail MEDIUMTEXT;
```

38
docs/wiki/database-setup/Setup-PostgreSQL.md
View File

@ -1,8 +1,15 @@
# Setup Postgres database for PowerDNS-Admin
We assume you already have a postgres database software installed for your platform.
This guide will show you how to prepare a PostgreSQL database for PowerDNS-Admin.
### Create database
We assume the database is installed per your platform's directions (apt, yum, etc). Directions to do this can be found below:
- https://www.postgresql.org/download/
- https://www.digitalocean.com/community/tutorials/how-to-install-postgresql-on-ubuntu-22-04-quickstart
We assume a default configuration and only the postgres user existing.
## Setup database
The below will create a database called powerdnsadmindb and a user of powerdnsadmin.
```
@ -42,19 +49,6 @@ On debian based systems these files are located in:
/etc/postgresql/<version>/main/
```
## Docker
TODO: Setup a local Docker postgres database ready to go (should probably move to the top).
```
docker run --name pdnsadmin-test -e BIND_ADDRESS=0.0.0.0
-e SECRET_KEY='a-very-secret-key'
-e PORT='9191'
-e SQLA_DB_USER='powerdns_admin_user'
-e SQLA_DB_PASSWORD='exceptionallysecure'
-e SQLA_DB_HOST='192.168.0.100'
-e SQLA_DB_NAME='powerdns_admin_test'
-v /data/node_modules:/var/www/powerdns-admin/node_modules -d -p 9191:9191 ixpict/powerdns-admin-pgsql:latest
```
## Install required packages:
### Red-hat based systems:
```
@ -74,3 +68,17 @@ pip3 install psycopg2
## Known Issues:
** To fill in **
## Docker (TODO: to move to docker docs)
TODO: Setup a local Docker postgres database ready to go (should probably move to the top).
```
docker run --name pdnsadmin-test -e BIND_ADDRESS=0.0.0.0
-e SECRET_KEY='a-very-secret-key'
-e PORT='9191'
-e SQLA_DB_USER='powerdns_admin_user'
-e SQLA_DB_PASSWORD='exceptionallysecure'
-e SQLA_DB_HOST='192.168.0.100'
-e SQLA_DB_NAME='powerdns_admin_test'
-v /data/node_modules:/var/www/powerdns-admin/node_modules -d -p 9191:9191 ixpict/powerdns-admin-pgsql:latest
```

BIN
docs/wiki/install/Architecture.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.4 KiB

31
docs/wiki/install/General.md
View File

@ -1,7 +1,32 @@
# General installation
## PowerDNS-Admin Architecture
## Requirements:
![PowerDNS-Admin Component Layout](Architecture.png)
- A linux based system with python 3 or later available. Debian and Red-hat based systems are recommended, others (Arch-based for example) may work but are currently not tested.
- A database for PowerDNS-Admin, if you are using a database for PowerDNS itself this must be separate to that database.
A PowerDNS-Admin installation includes four main components:
- PowerDNS-Admin Database
- PowerDNS-Admin Application Server
- PowerDNS-Admin Frontend Web server
- PowerDNS server that
All 3 components can be installed on one server or if your installation is large enough or for security reasons can be split across multiple servers.
## Requirements for PowerDNS-Admin:
- A linux based system. Others (Arch-based for example) may work but are currently not tested.
- Ubuntu versions tested:
- To fill in
- Red hat versions tested:
- To fill in
- Python versions tested:
- 3.6
- 3.7
- 3.8
- 3.9
- 3.10
- 3.11 - Failing due to issue with python3-saml later than 1.12.0
- A database for PowerDNS-Admin, if you are using a database for PowerDNS itself this must be separate to that database. The currently supported databases are:
- MySQL
- PostgreSQL
- SQLite
- A PowerDNS server that PowerDNS-Admin will manage.