Merge pull request #224 from zeromind/doc_update

Update documentation for 5.0 release

.github/workflows/release_dim.yml

@@ -24,7 +24,7 @@ jobs:
         env:
           _REF: ${{ github.ref }}
       - run: apt-get update
-      - run: apt-get install --yes python3-dnspython python3-sphinx make git
+      - run: apt-get install --yes python3-dnspython python3-sphinx graphviz make git
       - uses: actions/checkout@v2
       - run: sphinx-build -b html doc doc/_build/html
         working-directory: dim

VM-SETUP.md

@@ -1,6 +1,6 @@
 # Setup DB, DIM and PDNS Server and Shell environment
 
-The following steps assume that you have a minimal CentOS 8 installed.
+The following steps assume that you have a minimal EL8 installed.
 
 ### Disable SELINUX
 
@@ -81,7 +81,7 @@ Install necessary tools
 # cat <<EOF >/etc/yum.repos.d/mariadb.repo
 [mariadb]
 name = MariaDB
-baseurl = http://yum.mariadb.org/10.5/centos8-amd64
+baseurl = http://yum.mariadb.org/10.5/rhel8-amd64
 gpgkey=https://yum.mariadb.org/RPM-GPG-KEY-MariaDB
 gpgcheck=1
 module_hotfixes=1
@@ -118,7 +118,7 @@ grant select on pdns_int.* to pdns_int_user@localhost identified by 'SuperSecret
 
 Install repo file and install software
 ```
-# curl -o /etc/yum.repos.d/powerdns-auth-44.repo https://repo.powerdns.com/repo-files/centos-auth-44.repo
+# curl -o /etc/yum.repos.d/powerdns-auth-44.repo https://repo.powerdns.com/repo-files/el-auth-44.repo
 # dnf install pdns-tools pdns-backend-mysql
 ```
 
@@ -234,7 +234,7 @@ use systemctl status to verify that startup worked.
 Install pdns-recursor software
 
 ```
-# curl -o /etc/yum.repos.d/powerdns-rec-45.repo https://repo.powerdns.com/repo-files/centos-rec-45.repo
+# curl -o /etc/yum.repos.d/powerdns-rec-45.repo https://repo.powerdns.com/repo-files/el-rec-45.repo
 
 # dnf install pdns-recursor
 ```

dim/CHANGES

@@ -1,3 +1,8 @@
+5.0.0rc3
+--------
+* make layer3domain optional for `history ipblock` (#222)
+* deprecate `login_prompt()` in dimclient (#182)
+
 5.0.0rc2
 --------
 * fix missing /32 entries in list containers (#104)

dim/dim/version.py

@@ -1 +1 @@
-VERSION = '5.0.0rc2'
+VERSION = '5.0.0rc3'

dim/doc/administrator.rst

@@ -4,6 +4,11 @@
 Administrator Documentation
 ===========================
 
+System requirements
+===================
+* Python 3.9+ for DIM
+* Python 3.5+ for dimclient/ndcli
+
 dim provides three scripts in ``/opt/dim/bin``:
 
 * manage_db
@@ -66,7 +71,7 @@ report pool
 -----------
 
 The template file used formatting the report contains a `Python format string
-<http://docs.python.org/release/2.6.7/library/string.html#formatstrings>`_. It
+<https://docs.python.org/3.9/library/string.html#format-string-syntax>`_. It
 uses the following variables:
 
 - *pool_name*
@@ -158,13 +163,13 @@ run ``ndcli list registrar-account RA zones -t -v``.
 Apache configuration
 ====================
 
-Instructions for CentOS 7:
+Instructions for EL8:
 
 1. Edit ``/etc/dim/dim.cfg``.
 
 2. Install the necessary httpd modules::
 
-    yum install mod_ssl mod_wsgi
+    dnf install python39-mod_wsgi
 
 3. Adjust the hostname in the ``Redirect`` directive and the SSL configuration
    from ``/etc/httpd/conf.d/dim.conf``.

dim/doc/api.rst

@@ -280,6 +280,22 @@ Pool Functions
    Remove the vlan from *pool* and all its subnets.
 
 
+.. function:: ippool_set_layer3domain(pool, layer3domain)
+
+   Moves *pool* from its origin layer3domain to *layer3domain*.
+   Subnets of the pool, the contained entries and delegations are also being moved to layer3domain.
+   Reverse entries are stored in views named after the layer3domain.
+   All reverse entries are being deleted from the old view and then created in the new view.
+   If the view does not exist, it will be created.
+
+   **Please remember to add eventually newly created views to their appropriate zone-profile.**
+   Forward entries will be fixed to keep their reference to the reverse record.
+
+   **This operation can take a long time** to succeed depending on
+   the number of existing subnets, IPs, forward DNS entries and reverse DNS entries.
+   During this time, the pool and its entries can't be modified.
+
+
 .. function:: ippool_get_access(pool) -> array of objects
 
    Returns a list of access rights. Each access right has the following properties:
@@ -373,6 +389,10 @@ Pool Functions
    delegation.
 
 
+.. function:: ippool_unset_owner(poolname)
+   Unset owner for pool.
+
+
 .. function:: ippool_list(pool[, options]) -> array of objects
 
    Returns the list of pools matching the criteria specified in *options*. Each
@@ -381,6 +401,7 @@ Pool Functions
    - *name*
    - *vlan*
    - *subnets* (array of strings): list of CIDRs (one for each subnet)
+   - *layer3domain*
 
    Valid *options*:
 
@@ -395,6 +416,7 @@ Pool Functions
    - *include_subnets*: whether to include the *subnets* field in the response
    - *can_allocate*: whether to include only pools with the allocate right for the current user
    - *fields*: if true, add a *can_allocate* field to each object returned
+   - *layer3domain*: selects only pools which are in *layer3domain*
 
    The options *pool*, *vlan*, *cidr* and *owner* are mutually exclusive. If none is
    specified, all pools are returned.
@@ -408,6 +430,8 @@ Pool Functions
    - *vlan*
    - *cidr*
    - *can_allocate*
+   - *owner*
+   - *layer3domain*
 
    The options have the same meaning as for :func:`ippool_list`.
 
@@ -541,6 +565,20 @@ Block Functions
    delegation.
 
 
+.. function:: ipblock_move_to(cidr, block, layer3domain, to_layer3domain[, options])
+
+   Moves a `container` from *layer3domain* to the layer3domain *to_layer3domain*.
+   IP addresses that are not part of a pool are moved, too.
+   The container must have a parent. All `subnets` contained in the container get reassigned to the parent container.
+   If not present, new views for the affected reverse zones will be created with the name of the layer3domain to_layer3domain.
+   Entries for the IP addresses will then be deleted in the old view and recreated in the new view.
+
+   **This operation can take a long time** to succeed depending on the size of the container,
+   the number of subnets and the number of IPs allocated in the container.
+   In this time any write actions against the container,
+   subnets or reverse zones may get blocked at the database level.
+
+
 Subnet Functions
 ----------------
 

dim/doc/conf.py

@@ -48,7 +48,7 @@
 # built documents.
 #
 # The short X.Y version.
-version = '5.0.0rc1'
+version = '5.0.0rc3'
 # The full version, including alpha/beta/rc tags.
 release = version
 

dim/doc/dimclient.rst

@@ -72,14 +72,16 @@ Reference
 
 .. module:: dimclient
 
-.. class:: DimClient(server_url, cookie_file=None)
+.. class:: DimClient(server_url, cookie_file=None, cookie_umask=None)
 
    Instances of this class are proxies forwarding (most) method calls to the dim
    server.
 
    *cookie_file* is the name of a file (in libwww-perl Set-Cookie3 format) where
    cookies are read and/or written.
 
+   *cookie_umask* is the umask used for the cookie file.
+
    .. method:: login(username, password, permanent_session=False)
 
       If *permanent_session* is True, a permanent cookie is requested from the
@@ -88,11 +90,13 @@ Reference
 
    .. attribute:: logged_in
 
-      A boolean value indicating whether the user is logged in. This costs an
-      HTTP request.
+      A boolean value indicating whether the user is logged in. This uses
+      the *get_username* API call.
 
    .. method:: login_prompt(username=None, password=None, permanent_session=False, ignore_cookie=False)
 
+      *Deprecated* sice 1.0.0: CLIs should implement their own interactive prompt.
+
       If *ignore_cookie* is ``True`` or :attr:`logged_in` is ``False``, this
       method asks for username (unless *username* is set) and password (unless
       *password* is set) and forwards them to the :meth:`login` method.

dim/doc/index.rst

@@ -5,7 +5,7 @@ documentation).
 
 If you are looking to interface with dim you should read the :ref:`developer`.
 
-If you are an administrator, check out :ref:`Quick Start <quickstart>`
+If you are an administrator, check out :ref:`administrator`.
 
 Contents
 ========

ndcli/dimcli/version.py

@@ -1 +1 @@
-VERSION = '5.0.0rc2'
+VERSION = '5.0.0rc3'

ndcli/doc/conf.py

@@ -48,7 +48,7 @@
 # built documents.
 #
 # The short X.Y version.
-version = '2.5.0'
+version = '5.0.0rc3'
 # The full version, including alpha/beta/rc tags.
 release = version