Unverified Commit 1ecbec55 authored by Mattias Päivärinta's avatar Mattias Päivärinta Committed by GitHub
Browse files

Profiles doc (#332)

* Update API documentation
* Start configuration docs
* Remove obsolete terms from glossary
parent b71a3bb6
Zonemaster Backend
==================
# Zonemaster Backend
[![Build Status](https://travis-ci.org/dotse/zonemaster-backend.svg?branch=master)](https://travis-ci.org/dotse/zonemaster-backend)
### Purpose
This repository is one of the components of the Zonemaster software. For an
overview of the Zonemaster software, please see the
......@@ -14,7 +15,7 @@ run the Zonemaster engine on many domains)
A Zonemaster user needs to install the backend only in the case where there is a
need of logging the Zonemaster test runs in one's own respective database for
analysing.
analysing.
### Prerequisites
......@@ -24,6 +25,7 @@ Zonemaster Engine installed. Please see the
[Zonemaster Engine installation
instructions](https://github.com/dotse/zonemaster-engine/blob/master/docs/Installation.md).
### Upgrade
If you are upgrading Zonemaster Backend from 1.0.X to 1.1.X please follow the
......@@ -33,17 +35,15 @@ relevant parts of the installation instructions below.
For all other upgrades follow the relevant parts of the installation
instructions below.
### Installation
Follow the detailed [installation instructions](docs/Installation.md).
### Configuration
Zonemaster *Backend* is configured as a whole from `/etc/zonemaster/backend_config.ini`.
### Configuration
>
> At this time there is no documentation for `backend_config.ini`.
>
See the [configuration documentation].
### Documentation
......@@ -66,8 +66,10 @@ The [docs](docs/) directory also contains the SQL commands for manipulating the
database.
License
=======
## License
The software is released under the 2-clause BSD license. See separate
[LICENSE](LICENSE) file.
[Configuration documentation]: docs/Configuration.md
......@@ -140,19 +140,12 @@ The typical use case for this parameter would be a setup with several separate T
Basic data type: string
The name of a [*profile*](Architecture.md#profile).
One of the strings:
* `"default_profile"`
* `"test_profile_1"`
* `"test_profile_2"`
* Must consist entirely of letters A-Z and a-z, digits 0-9, hyphen '-'
and underscore '_'.
Must not start or end with hyphen or underscore.
* Length must be between 1 and 32 characters inclusive.
The `"test_profile_2"` *profile* is identical to `"default_profile"`.
>
> TODO: What is the expected behavior when a *profile* other than the ones listed above is requested?
>
The name of a [*profile*](Architecture.md#profile).
### Progress percentage
......@@ -453,14 +446,14 @@ An object with the following properties:
* `"client_id"`: A free-form string, optional.
* `"domain"`: A *domain name*, required.
* `"profile"`: A *profile name*, optional.
* `"profile"`: A *profile name*, optional (default `"default"`). Run
the test using the given profile.
* `"client_version"`: A free-form string, optional.
* `"nameservers"`: A list of *name server* objects, optional.
* `"ds_info"`: A list of *DS info* objects, optional.
* `"advanced"`: **Deprecated**. A boolean, optional.
* `"ipv6"`: A boolean, optional. (default `false`)
* `"ipv4"`: A boolean, optional. (default `false`)
* `"config"`: A string, optional. The name of a *config profile*.
* `"user_ip"`: A ..., optional.
* `"user_location_info"`: A ..., optional.
* `"priority"`: A *priority*, optional
......@@ -490,6 +483,9 @@ started within the recent configurable short time.
#### `"error"`
* If the given `profile` is not among the [available profiles], a user
error is returned.
>
> TODO: List all possible error codes and describe what they mean enough for clients to know how react to them.
>
......@@ -884,14 +880,14 @@ An object with the following properties:
The value of `"test_params"` is an object with the following properties:
* `"client_id"`: A free-form string, optional.
* `"profile"`: A *profile name*, optional.
* `"profile"`: A *profile name*, optional (default `"default"`). Run
the tests using the given profile.
* `"client_version"`: A free-form string, optional.
* `"nameservers"`: A list of *name server* objects, optional.
* `"ds_info"`: A list of *DS info* objects, optional.
* `"advanced"`: **Deprecated**. A boolean, optional.
* `"ipv6"`: A boolean, optional. (default: `false`)
* `"ipv4"`: A boolean, optional. (default: `false`)
* `"config"`: A string, optional. The name of a *config profile*.
* `"user_ip"`: A ..., optional.
* `"user_location_info"`: A ..., optional.
* `"priority"`: A *priorty*, optional
......@@ -923,6 +919,9 @@ A *batch id*.
* You can't create a new batch job.
A *batch* with unfinished *tests* already exists for this *api user*.
* If the given `profile` is not among the [available profiles], a user
error is returned.
>
> TODO: List all possible error codes and describe what they mean enough for clients to know how react to them.
......@@ -1039,13 +1038,12 @@ An object with the following properties:
* `"ipv6"`: an optional `1`, `0`, `true` or `false`.
* `"ds_info"`: an optional list of *DS info* objects.
* `"nameservers"`: an optional list of objects each of *name server* objects.
* `"profile"`: an optional *profile name*.
* `"profile"`: A *profile name*, optional (default `"default"`).
* `"advanced"`: an optional `true` or `false`.
* `"client_id"`: ...
* `"client_version"`: ...
* `"user_ip"`: ...
* `"user_location_info"`: ...
* `"config"`: ...
If the `"nameservers"` key is _not_ set, a recursive query made by the
server to its locally configured resolver for NS records for the
......@@ -1056,8 +1054,7 @@ At least one of `"ipv4"` and `"ipv6"` must be present and either `1` or `true`.
>
> TODO: Clarify the data type of the following `"params"` properties:
> `"client_id"`, `"client_version"`, `"user_ip"`, `"user_location_info"` and
> `"config"`.
> `"client_id"`, `"client_version"`, `"user_ip"`, `"user_location_info"`.
>
> TODO: Clarify the purpose of each `"params"` property.
>
......@@ -1072,6 +1069,9 @@ An object with the following properties:
#### `"error"`
* If the given `profile` is not among the [available profiles], a user
error is returned.
>
> TODO: List all possible error codes and describe what they mean enough for clients to know how react to them.
>
......@@ -1107,3 +1107,5 @@ The `"params"` object sent to `start_domain_test` when the *test* was started.
>
> TODO: List all possible error codes and describe what they mean enough for clients to know how react to them.
>
[Available profiles]: Configuration.md#profiles-section
......@@ -67,24 +67,31 @@ soon as it can, and all of the real work will be done as that user.
### Message
### Policy
### Profile
>
> TODO: Come up with a better name to distinguish it from *config profiles*.
>
A profile is a configuration for Zonemaster Engine; see the [profiles
overview] for context.
Zonemaster Backend allows administrators to [configure the set of
available profiles].
### Config profile
Each available profile has a [profile name].
A profile named `default` is always available.
Each available profile is based on the [Zonemaster Engine default profile].
Each one (with the possible exception of `default`) has a [profile file]
with profile data overriding the Zonemaster Engine default profile.
*Config profiles* are configured under the the `ZONEMASTER` section of `zonemaster_backend.ini`.
>
> TODO: Describe this in greater detail.
>
The [RPC-API] contains several methods that accept profile name arguments.
### Engine
The Zonemaster *Engine* is a library for performing *tests*. It's hosted in [its
own repository](https://github.com/dotse/zonemaster-engine/).
--------
[Configure the set of available profiles]: Configuration.md#profiles-section
[Profile file]: https://metacpan.org/pod/Zonemaster::Engine::Config#PROFILE-DATA
[Profile name]: API.md#profile-name
[Profiles overview]: https://github.com/dotse/zonemaster/blob/master/docs/design/Profiles.md
[RPC-API]: API.md
[Zonemaster Engine default profile]: https://metacpan.org/pod/Zonemaster::Engine::Config#DESCRIPTION
# Configuration
Zonemaster Backend is configured as a whole from `/etc/zonemaster/backend_config.ini`.
Each section in `backend_config.ini` is documented below.
## DB section
TBD
## GEOLOCATION section
TBD
## LOG section
TBD
## PERL section
TBD
## PROFILES section
The PROFILES section defines the available [profiles].
Keys are [profile names], and values are absolute file system paths to
[profile JSON files].
Each profile JSON file contains a (possibly empty) set of overrides to
the [Zonemaster Engine default profile].
There is a `default` profile that is special.
It is always available.
If it is not explicitly mapped to a profile JSON file, it is implicitly
mapped to the Zonemaster Engine default profile.
Specifying a profile JSON file that contains a complete set of profile
data is equivalent to specifying a profile JSON file with only the parts
that differ from the Zonemaster Engine default profile.
Specifying a profile JSON file that contains no profile data is equivalent
to specifying a profile JSON file containing the entire Zonemaster Engine
default profile.
## ZONEMASTER section
TBD
--------
[Profile JSON files]: https://metacpan.org/pod/Zonemaster::Engine::Config#PROFILE-DATA
[Profile names]: API.md#profile-name
[Profiles]: Architecture.md#profile
[Zonemaster Engine default profile]: https://metacpan.org/pod/Zonemaster::Engine::Config#DESCRIPTION
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment