|
||
---|---|---|
.idea | ||
bin | ||
public | ||
src | ||
tests | ||
.gitignore | ||
composer.json | ||
composer.lock | ||
config.json.sample | ||
log.txt | ||
phpunit.xml | ||
README.md |
1. Overview
This package provides an API for the Bind nameserver. It consists of two parts, the API itself and a CLI tool to configure the available functions.
2. Features
2.1. CLI
The CLI is used to perform configuration and some checks:
- check
- Permissions: The API needs to be able to access some files and create new ones
- Panels: This checks one or all panels if every nameserver is aware of all domains
- Domain: TODO
- panels
- List: List all panels which are configured on this server
- Create: Adds a new panel to the configuration
- Update: Changes one or more parameters of the panel
- Delete: Deletes the given panel
- ApiPing: Calls the /ping endpoint of the given server or all if no Panel is specified
- some additional API call might be added
- nameservers
- similar to panels, but for the nameservers
- domains
- similar usage to panels/domains, manage all slave zones
- apikeys
- manage the keys to access this nameserver via API
2.2. API
The APi is a RESTful API, there is a self explaining Swagger/OpenAPI available.
On the site you can authorize with an API key (creation of the key is described later in this document).
And enter you API key:
After successful authorization you can use the APi via the OpenAPI Interface, e.g. call the /ping endpoint to check if the API is alive.
You have to click on „Try it out“:
And then hit Execute:
Of course, you can issue the same command in your shell:
curl -X 'GET' \ 'https://ns1.24unix.net/api/ping' \ -H 'accept: application/json' \ -H 'X-API-Key: 61f27a57c9d1f.[truncated]'
A helpful tool when dealing with API is Postman, if offers the same options as from the OpenAPI interface or via shell with curl.
3. Installation
You can install the bindAPi on either a standalone server or an existing KeyHelp Panel. However, slave zones are only managed for masters which lie on Keyhelp panels.
3.1. Installation on a KeyHelp panel
In KeyHelp, install PHP 8.1. This is mandatory, the API relies on features only available since PHP 8.0. It might run on PHP 8.0 but has not been tested as there is no reason not to install PHP 8.1.
So head over to: Settings => Configuration => Feature Settings => PHP Interpreter
Set the checkmark and press Save.
Wait about a minute, the installation is started via a cronjob which runs every minute.
Now you see the newly installed PHP interpreters:
Next create a domain, e.g. ns1.24unix.net:
I created the domain in ns1.24unix.net below the /www folder.
We'll change the base directory later.
Now we need to log into our server, using e.g. iTerm2 or under Linux whichever Terminal you prefer.
As root (or via sudo):
apt install git wget
We need this to check out the bindAPi from git later.
So as we are still root, we need to install composer, two reasonable locations are under /bindAPI/bin or /usr/local/bin. Here I will install it under /usr/local/bin, in the example with the standalone server I'll install it under /bindAPI/bin.
wget https://getcomposer.org/installer
php composer-setup.php --install-dir=/usr/local/bin --filename=composer
Now we can change into our new user, remind to give him shell access in the panel.
su - tfunix
In my example I assume the user is called tfunix, his home points to /home/users/tfunix.
Base directory for the bindAPI is ~/www/ns1.24unix.net/bindApi (~ => home folder).
So, we head over to our directory:
cd www/ns1.24unix.net/bindAPI
Remove the defaults files:
rm *
Next, we'll need to fetch the bindAPI (currently it has no release tag, that will change later)
git clone https://git.24unix.net/tracer/bindAPI.git
Cloning into 'bindAPI'...
remote: Enumerating objects: 878, done.
remote: Counting objects: 100% (878/878), done.
remote: Compressing objects: 100% (670/670), done.
remote: Total 878 (delta 510), reused 225 (delta 139), pack-reused 0
Receiving objects: 100% (878/878), 3.25 MiB | 4.46 MiB/s, done.
Resolving deltas: 100% (510/510), done.
We need to pill the dependencies for composer:
/usr/bin/keyhelp-php81 /usr/local/bin/composer update
You might notice a quite strange command. We need to call php with full path, and explicitly the 8.1 version. KeyHelp relies on the default PHP installation, so the php binary will always point to 7.4 when your on Debian Bullseye.
So, in bin/console the path to /usr/bin/keyhelp-php81 is hardcoded after the shebang, a step we have to remind if we install the standalone version.
Now make the CLU executable:
chmod +x bin/console
And give it a try:
% ./bin/console
Missing config file
Should I create a new config based on config.json.sample? (y/N): n
You first have to setup the bindAPI. Bye.
Sp now we can head back to our panel and set the Document root to /home/users/tfunix/ns1.24unix.net/bindAPI/public.
OK, we are finished with the installation and head over to the 4. Configuration.
3.2. Installation on a plain debian Bullseye
So, at first you should read and understand all steps in 3.1, as we will learn only the differences.
We assume that you're on a fresh minimal installation.
You need at first to pull some essentials:
apt install git vim wget zsh
To get access to all flavors of PHP sury.org is the perfect match, he's also the official maintainer für the Debian PHP packages (and Ubuntu, as anyone would care).
Execute this commands:
wget -O /etc/apt/trusted.gpg.d/php.gpg https://packages.sury.org/php/apt.gpg
echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list
apt update
We need at leas php-fpm, php-cli, and besides that php-curl, php-xlm and php-mbstring:
apt install ph8.1-fpm, php8.1-cli, and besides that php8.1-curl, php8.1-xml and php8.1-mbstring
We also need MariaDB, the successor of MySQL.
(Maria is the second daughter of Michael Widenius, guess what, his first is named My.
So MySQl and MariDB even makes more sense ^^)
apt install mysql
And, we need the webserver, of course:
apt install apache2 libapache-mod-fcgid php8.1-fpm
And enable fpm support:
a2econf php8.1-fpm
Disable the default site:
a2dissite 000*
<VirtualHost *:80>
ServerName ns1.24unix.net
ServerAdmin tracer@24unix.net
DocumentRoot /var/www/html
ErrorLog ${APACHE_LOG_DIR}/ns1.24unix.net/error.log
CustomLog ${APACHE_LOG_DIR}/ns1.24unix.net/access.log combined
RewriteEngine on
RewriteCond %{SERVER_NAME} =ns1.24unix.net
RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
</VirtualHost>
<IfModule mod_ssl.c>
<VirtualHost *:443>
ServerName ns1.24unix.net
ServerAdmin tracer@24unix.net
Protocols h2 h2c http/1.1
DocumentRoot /var/www/html/bindAPI/public
ErrorLog ${APACHE_LOG_DIR}/ns1.24unix.net/error.log
CustomLog ${APACHE_LOG_DIR}/ns1.24unix.net/access.log combined
SSLCertificateFile /etc/letsencrypt/live/ns1.24unix.net/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/ns1.24unix.net/privkey.pem
Include /etc/letsencrypt/options-ssl-apache.conf
<FilesMatch \.php$>
SetHandler "proxy:unix:/run/php/php8.1-fpm.sock|fcgi://localhost"
</FilesMatch>
<Directory /var/www/html/bindAPI/public>
Options -Indexes +FollowSymLinks +MultiViews
AllowOverride All
Require all granted
</Directory>
</VirtualHost>
</IfModule>