Metadata-Version: 2.2
Name: bisos.dnsCap
Version: 0.13
Summary: bisos.dnsCap:  DNS Management Facilities for BISOS Capabilities
Author: Mohsen Banan
Author-email: libre@mohsen.1.banan.byname.net
Maintainer: Mohsen Banan
Maintainer-email: libre@mohsen.1.banan.byname.net
License: AGPL
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: bisos
Requires-Dist: bisos.b
Requires-Dist: bisos.common
Requires-Dist: bisos.csPlayer
Requires-Dist: bisos.csSeed
Requires-Dist: setuptools==75.8.0
Requires-Dist: wheel==0.38.4
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: license
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: requires-dist
Dynamic: summary

==============================================================
bisos.dnsCap: DNS Management Facilities for BISOS Capabilities
==============================================================

.. contents::
   :depth: 3
..

Overview
========

*bisos.dnsCap* provides DNS management facilities that contribute to
BISOS **Capabilities**. In BISOS, a **Capability** is a specific
concept, specified and realized through *bisos.capability*. ``dnsCap``
is not itself a Capability; it is one ingredient — the DNS aspect — of a
full **CBS** (Capability Bundle Specification), alongside sibling
aspects such as ``webCap`` and ``sbom``.

Concretely, ``dnsCap`` supplies the DNS naming an application needs. Its
first backend maintains ``/etc/hosts`` entries for the ``.here`` domain
(e.g. ``airflow.here``), using the ``bisos.banna`` dblock machinery to
keep those entries in sync.

``dnsCap_seed.cs`` is a seed. Common usages take the form of a
``<name>-here-dns.pcs`` plant that names the fqdn to manage.

.. _table-of-contents:

Table of Contents TOC
=====================

-  `Overview <#overview>`__
-  `Relation to BISOS Capabilities <#relation-to-bisos-capabilities>`__
-  `Part of BISOS — ByStar Internet Services Operating
   System <#part-of-bisos--bystar-internet-services-operating-system>`__
-  `bisos.dnsCap is a Command-Only PyCS
   Facility <#bisosdnscap-is-a-command-only-pycs-facility>`__
-  `Installation <#installation>`__

   -  `Installation With pip <#installation-with-pip>`__
   -  `Installation With pipx <#installation-with-pipx>`__

-  `Usage <#usage>`__

   -  `Example: managing airflow.here in
      /etc/hosts <#example-managing-airflowhere-in-etchosts>`__
   -  `Commands <#commands>`__

-  `Key Files <#key-files>`__
-  `Documentation and Blee-Panels <#documentation-and-blee-panels>`__
-  `Support <#support>`__
-  `Planned Improvements <#planned-improvements>`__

Relation to BISOS Capabilities
==============================

A BISOS **Capability** is specified and realized by *bisos.capability*
as a **CBS** (Capability Bundle Specification) — a bundle of component
aspects. ``dnsCap`` is the DNS aspect of that bundle. Its sibling
aspects include:

-  ``dnsCap`` — DNS naming (this package): ``/etc/hosts`` and, later,
   other DNS backends.
-  ``webCap`` — the web-service aspect.
-  ``sbom`` — the Software Bill Of Materials aspect (typically a
   ``*-sbom.pcs`` plant).

A CBS composes these aspects into the complete specification of a
Capability. ``dnsCap`` can be used on its own (as shown below) or as an
ingredient invoked from within a CBS. For the Capability concept itself,
see `bisos.capability <https://github.com/bisos-pip/capability>`__.

Part of BISOS — ByStar Internet Services Operating System
=========================================================

Layered on top of Debian, **BISOS** (By\* Internet Services Operating
System) is a unified and universal framework for developing both
internet services and software-service continuums that use internet
services. See `Bootstrapping ByStar, BISOS and
Blee <https://github.com/bxGenesis/start>`__ for information about
getting started with BISOS.

**BISOS** is a foundation for **The Libre-Halaal ByStar Digital
Ecosystem** which is described as a cure for losses of autonomy and
privacy in a book titled: `Nature of
Polyexistentials <https://github.com/bxplpc/120033>`__

*bisos.dnsCap* is part of BISOS. It is a standalone package that can be
used independently of the full BISOS environment.

bisos.dnsCap is a Command-Only PyCS Facility
============================================

bisos.dnsCap is a command-line tool. It is a PyCS single-unit command
service. PyCS is a framework that converges development of CLI tools and
services. PyCS is an alternative to FastAPI, Typer and Click.

bisos.dnsCap uses the PyCS-Framework to provide the DNS aspect of a
BISOS Capability:

#. Update ``/etc/hosts`` with the DNS entries for a ``.here`` fqdn (via
   the ``bisos.banna`` dblock machinery).
#. Verify that ``/etc/hosts`` contains the expected banna dblock
   markers.
#. Resolve and ping a managed fqdn to confirm the entry is in effect.

The core of PyCS-Framework is the *bisos.b* package (the
PyCS-Foundation). See `bisos.b <https://github.com/bisos-pip/b>`__ for
an overview.

Installation
============

The sources for the bisos.dnsCap pip package are maintained at:
https://github.com/bisos-pip/dnsCap.

The bisos.dnsCap pip package is available at PYPI as
https://pypi.org/project/bisos.dnsCap

You can install bisos.dnsCap with pip or pipx.

Installation With pip
---------------------

If you need access to bisos.dnsCap as a python module, you can install
it with pip:

.. code:: bash

   pip install bisos.dnsCap

Installation With pipx
----------------------

If you only need access to bisos.dnsCap on command-line, you can install
it with pipx:

.. code:: bash

   pipx install bisos.dnsCap

Usage
=====

Example: managing airflow.here in /etc/hosts
--------------------------------------------

A plant such as ``airflow-here-dns.pcs`` names the fqdn and the DNS
backend:

.. code:: python

   from bisos.dnsCap import dnsCap_seedInfo
   cntrlInfo = dnsCap_seedInfo.cmndsControlInfo
   cntrlInfo.dnsSpecMethod = dnsCap_seedInfo.DnsSpecMethod.etcHosts
   cntrlInfo.fqdn = "airflow.here"

With that plant in place, the full cycle is:

.. code:: bash

   bin/airflow-here-dns.pcs -i dnsCap_update

   bin/airflow-here-dns.pcs -i dnsCap_verify

   bin/airflow-here-dns.pcs -i dnsCap_resolve  airflow.here
   bin/airflow-here-dns.pcs -i dnsCap_fqdnPing airflow.here

After ``dnsCap_update``, ``/etc/hosts`` contains a banna-generated
block, e.g.:

.. code:: text

   ####+BEGIN: bx:dblock:global:run-result-stdout :command "bannaInfo.cs -i bannaForEtcHosts"
   127.0.22.100  airflow.here  # port=24006
   127.0.22.101  csLineInvoker.here  # port=24002
   127.0.22.102  csLineInvoker_dev.here  # port=25002
   127.0.22.103  csPlayerPerf.here  # port=23001
   127.0.22.104  csPlayerPerf_dev.here  # port=23501
   127.0.22.105  csPlayerUi.here  # port=24001
   127.0.22.106  csPlayerUi_dev.here  # port=25001
   127.0.22.107  sonCliLineInvoker.here  # port=24004
   127.0.22.108  sonCliLineInvoker_dev.here  # port=25004
   127.0.22.109  sonCliPlayerUi.here  # port=24003
   127.0.22.110  sonCliPlayerUi_dev.here  # port=25003
   127.0.22.111  starterSidebar.here  # port=24005
   127.0.22.112  starterSidebar_dev.here  # port=25005

   ####+END:

and ``ping airflow.here`` then resolves to ``127.0.22.100``.

Commands
--------

+---------------------+-----------------------------------------------+
| Command             | What it does                                  |
+=====================+===============================================+
| ``dnsCap_update``   | Safe-copy ``/etc/hosts``, then rewrite its    |
|                     | banna dblock (sudo).                          |
+---------------------+-----------------------------------------------+
| ``dnsCap_verify``   | Check that ``/etc/hosts`` has the banna       |
|                     | dblock BEGIN/END markers.                     |
+---------------------+-----------------------------------------------+
| ``dnsCap_resolve``  | Resolve the fqdn via ``getent hosts``.        |
+---------------------+-----------------------------------------------+
| ``dnsCap_fqdnPing`` | Ping the fqdn once to confirm the entry is in |
|                     | effect.                                       |
+---------------------+-----------------------------------------------+

Key Files
=========

-  ``py3/bin/dnsCap_seed.cs`` — the seed entry point.
-  ``py3/bin/airflow-here-dns.pcs`` — example plant for
   ``airflow.here``.
-  ``py3/bin/exmpl-here-dns.pcs`` — example plant for ``exmpl.here``.
-  ``py3/bisos/dnsCap/dnsCap_csu.py`` — the four ``dnsCap_*`` commands.
-  ``py3/bisos/dnsCap/dnsCap_seedInfo.py`` — ``DnsSpecMethod`` enum
   (``etcHosts``, ``tinydns``) and the ``fqdn`` / ``dnsSpecMethod``
   control info.

Documentation and Blee-Panels
=============================

bisos.dnsCap is part of ByStar Digital Ecosystem http://www.by-star.net.

This module's primary documentation is in the form of Blee-Panels.

See
`file:./panels/bisos.dnsCap/_nodeBase_/fullUsagePanel-en.org <./panels/bisos.dnsCap/_nodeBase_/fullUsagePanel-en.org>`__
for a starting point.

Support
=======

| For support, criticism, comments and questions; please contact the
  author/maintainer
| `Mohsen Banan <http://mohsen.1.banan.byname.net>`__ at:
  http://mohsen.1.banan.byname.net/contact

Planned Improvements
====================

-  Implement the ``tinydns`` backend (``DnsSpecMethod.tinydns`` is
   currently a placeholder).
-  Handle ``dnsCap_update`` on a fresh ``/etc/hosts`` with no
   pre-existing dblock markers.
