bindAPI/README.md

1. [Overview](#1-overview)
2. [Features](#2-features)
3. [Installation](#3-installation)
4. [Configuration](#4-configuration)
5. [The API](#5-the-api)
6. [Conclusion](#6-conclusion)

<a name="overview"></a>
# 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.


<a name="features"></a>
# 2. Features

## 2.1. CLI

![CLI Interface](https://bindapi.24unix.net/assets/bindAPI_cli.png)

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

![OpenAPI](https://bindapi.24unix.net/assets/bindAPI_api1.png)

The APi is a RESTful API, there is a self explaining Swagger/OpenAPI available.



<a name="installation"></a>
# 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
![Php Interpreter](https://bindapi.24unix.net/assets/bindAPI_php1.png)


Set the checkmark and press Save.

Wait about a minute, the installation is started via a cronjob which runs every minute.
![Install Php Interpreter](https://bindapi.24unix.net/assets/bindAPI_php2.png)

Now you see the newly installed PHP interpreters:
![Php Interpreter](https://bindapi.24unix.net/assets/bindAPI_php3.png)

Next create a domain, e.g. ns1.24unix.net:

![Php Interpreter](https://bindapi.24unix.net/assets/bindAPI_installation1.png)

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.

![Php Interpreter](https://bindapi.24unix.net/assets/bindAPI_shell.png)

` 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 pull 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 CLI 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.
```

So 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](#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:

```apt -y install apt-transport-https lsb-release ca-certificates curl
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 least php-fpm, php-cli, and besides that php-curl, php-xml 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 MariaDB 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>
```

php installer --install-dir=./bin/ TODO

/usr/bin/keyhelp-php81 bin/composer.phar update


<a name="configuration"></a>
# 4. Configuration

So, another call of our binary, this time we agree to get a config written:

```
# ./bin/console
Missing config file
Should I create a new config based on config.json.sample? (y/N): y
Config file has been generated. Adjust it to your needs, then proceed to database setup.
```

So, what's in it?

```
cat config.json
{
  "dbHost": "localhost",
  "dbPort": 3306,
  "dbDatabase": "sampledb",
  "dbUser": "sampleuser",
  "dbPassword": "secret"
}
```
We'll start the installer another time:

```
$ ./bin/console
SQLSTATE[HY000] [1698] Access denied for user 'sampleuser'@'localhost'
Did you create the database and adjust the config file?

You can create database an user via a panel or manually in mysql shell:
Created an initial password: T6BpmtNk
CREATE DATABASE bindAPI;
CREATE USER 'bindAPI'@'localhost' IDENTIFIED BY 'T6BpmtNk';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, INDEX, DROP, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES ON bindAPI.* TO 'bindAPI'@'localhost';
There is no need to run FLUSH PRIVILEGES when using GRANT!
```

So, now it offers us the create statements for the needed database.
If were on plain debian, we just can copy and paste (the password is random) this as root into mysql.

If we're using hte panel, lets create a database and write down the credentials and update config.json.


Now we can finally begin to populate our configuration:

TODO


<a name="theapi"></a>
# 5. The API
On the site you can authorize with an API key (creation of the key is described later in this document).

![Authorize](https://bindapi.24unix.net/assets/bindAPI_api2.png)

And enter you API key:

![Enter Apikey](https://bindapi.24unix.net/assets/bindAPI_api3.png)

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“:

![Try it out](https://bindapi.24unix.net/assets/bindAPI_api4.png)


And then hit Execute:

![Try it out](https://bindapi.24unix.net/assets/bindAPI_api5.png)


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](https://https://www.postman.com/), if offers the same options as from the OpenAPI interface or via shell with curl.

![Php Interpreter](https://bindapi.24unix.net/assets/bindAPI_api6.png)
<a name="conclusion"></a>
# 6. Conclusion