diff --git a/docs/wiki/README.md b/docs/wiki/README.md index 8a002bd..62f1bf1 100644 --- a/docs/wiki/README.md +++ b/docs/wiki/README.md @@ -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 - ## Feature usage + - [DynDNS2](features/DynDNS2.md) \ No newline at end of file diff --git a/docs/wiki/configuration/Environment-variables.md b/docs/wiki/configuration/Environment-variables.md index 7b835e2..3ee84c4 100644 --- a/docs/wiki/configuration/Environment-variables.md +++ b/docs/wiki/configuration/Environment-variables.md @@ -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) diff --git a/docs/wiki/database-setup/Setup-MySQL-or-MariaDB.md b/docs/wiki/database-setup/Setup-MySQL-or-MariaDB.md index 00586a5..5242b69 100644 --- a/docs/wiki/database-setup/Setup-MySQL-or-MariaDB.md +++ b/docs/wiki/database-setup/Setup-MySQL-or-MariaDB.md @@ -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; + ``` diff --git a/docs/wiki/database-setup/Setup-PostgreSQL.md b/docs/wiki/database-setup/Setup-PostgreSQL.md index 74af46f..a6e3364 100644 --- a/docs/wiki/database-setup/Setup-PostgreSQL.md +++ b/docs/wiki/database-setup/Setup-PostgreSQL.md @@ -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//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 +``` diff --git a/docs/wiki/install/Architecture.png b/docs/wiki/install/Architecture.png new file mode 100644 index 0000000..04440be Binary files /dev/null and b/docs/wiki/install/Architecture.png differ diff --git a/docs/wiki/install/General.md b/docs/wiki/install/General.md index 98dfa1f..f0823c8 100644 --- a/docs/wiki/install/General.md +++ b/docs/wiki/install/General.md @@ -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. \ No newline at end of file +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.