#+title: bisos.facter:  Adoption and adaptation of facter to Python and as Command-Services
#+DATE: <2024-02-19 Mon 16:27>
#+AUTHOR: Mohsen BANAN
#+OPTIONS: toc:4

* Overview
bisos.facter is a python package that uses the PyCS-Framework for adoption and
adaptation of *facter* to python and PyCS-Framework. It is a BISOS-Capability and
a Standalone-BISOS-Package.

/bisos.facter/ provides access to facter information through python.

/bisos.facter/ is based on the [[https://github.com/bisos-pip/b][PyCS-Foundation]] and can be used both as a Command and
as a Service (invoke/perform model of remote operations) using RPYC for central
management of multiple systems.


* Table of Contents     :TOC:
- [[#overview][Overview]]
- [[#about-facter][About facter]]
- [[#about-bisos-----bystar-internet-services-operating-system][About BISOS --- ByStar Internet Services Operating System]]
- [[#bisosfacter-is-a-command-services-pycs-facility][bisos.facter is a Command-Services PyCS Facility]]
- [[#bisosfacter-as-a-standalone-piece-of-bisos][bisos.facter as a Standalone Piece of BISOS]]
- [[#installation][Installation]]
  - [[#with-pip][With pip]]
  - [[#with-pipx][With pipx]]
  - [[#post-installation-basic-testing][Post Installation Basic Testing]]
- [[#usage][Usage]]
  - [[#locally-system-command-line][Locally (system command-line)]]
  - [[#remotely-as-a-service----performerinvoker][Remotely (as a service -- Performer+Invoker)]]
    - [[#performer][Performer]]
    - [[#invoker][Invoker]]
  - [[#use-by-python-script][Use by python script]]
- [[#bisosfacter-as-an-example-of-command-services-pycs----code-walkthrough][bisos.facter as an Example of Command Services (PyCS) -- Code Walkthrough]]
  - [[#py3binfactercs--binroperf-factercs--binroinv-factercs][./py3/bin/facter.cs  (./bin/roPerf-facter.cs  ./bin/roInv-facter.cs)]]
  - [[#py3bisosfacterfacterpy-comeega-python][./py3/bisos/facter/facter.py (COMEEGA Python)]]
  - [[#py3bisosfacterfacter_convpy-conventional-python][./py3/bisos/facter/facter_conv.py (Conventional Python)]]
  - [[#py3bisosfacterfacter_csupy][./py3/bisos/facter/facter_csu.py]]
  - [[#pypi-and-github-packaging][PyPi and Github Packaging]]
- [[#documentation-and-blee-panels][Documentation and Blee-Panels]]
  - [[#bisosfacter-blee-panels][bisos.facter Blee-Panels]]
- [[#support][Support]]
- [[#planned-improvements][Planned Improvements]]

* About facter

[[https://www.puppet.com/docs/puppet/7/facter.html][Facter]] gathers information about the system, which can be used as variables.
Facter is part of [[https://www.puppet.com/][puppet]], but it can also be used without puppet.

To install facter:

#+begin_src bash
sudo apt-get install -y facter
#+end_src

Facter is a ruby package. This bisos.facter python package provides access to
facter information through python both locally and remotely.

* About 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 [[https://github.com/bxGenesis/start][Bootstrapping
ByStar, BISOS and Blee]] for information about getting started with BISOS.

Within BISOS, [[bisos.cmdb]] uses bisos.facter for Configuration Management DataBase
purposes.

/bisos.facter/ as a PyCS facility is a small piece of a much bigger picture. *BISOS*
is a foundation for *The Libre-Halaal ByStar Digital Ecosystem* which is described
as a cure for losses of autonomy and privacy that we are experiencing in a book
titled: [[https://github.com/bxplpc/120033][Nature of Polyexistentials]]



* bisos.facter is a Command-Services PyCS Facility

bisos.facter can be used locally on command-line or remotely as a service.
bisos.facter is a PyCS multi-unit command-service.
PyCS is a framework that converges development of CLI and Services.
PyCS is an alternative to FastAPI, Typer and Click.

bisos.facter uses the PyCS-Framework to:

1) Provide access to facter facilities through native python.
2) Provide local access to facter facilities on CLI.
3) Provide remote access to facter facilities through remote invocation of
   python Expectation Complete Operations using [[https://github.com/tomerfiliba-org/rpyc][rpyc]].
4) Provide remote access to facter facilities on CLI.

What is unique in the PyCS-Framework is that these four models are all
a single abstraction.

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

* bisos.facter as a Standalone Piece of BISOS

bisos.facter is a standalone piece of BISOS. It can be used as a self-contained
Python package separate from BISOS. Follow the installation and usage
instructions below for your own use.


* Installation

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

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

You can install bisos.facter with pip or pipx.

** With pip

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

#+begin_src bash
pip install bisos.facter
#+end_src

** With pipx

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

#+begin_src bash
pipx install bisos.facter
#+end_src

The following commands are made available:
- facter.cs
- roInv-facter.cs
- roPerf-facter.cs

These are all one file with 3 names. _roInv-facter.cs_ and _roPerf-facter.cs_ are sym-links to _facter.cs_

** Post Installation Basic Testing

After the installation, run some basic tests:

#+begin_src bash
facter.cs
facter networking.interfaces.lo.bindings
#+end_src


* Usage

** Locally (system command-line)

=facter.cs= does the equivalent of facter.

#+begin_src bash
bin/facter.cs
#+end_src

** Remotely (as a service -- Performer+Invoker)

You can also run:


*** Performer

Invoke performer as:

#+begin_src bash
bin/roPerf-facter.cs
#+end_src

*** Invoker

#+begin_src bash
bin/roInv-facter.cs
#+end_src

** Use by python script

bisos.facter Source Code is in written in COMEEGA (Collaborative Org-Mode Enhanced Emacs Generalized Authorship) -- https://github.com/bx-blee/comeega.

The primary API for bisos.facter is [[file:./py3/bisos/facter/facter_csu.py]]. It is self documented in COMEEGA.

* bisos.facter as an Example of Command Services (PyCS) -- Code Walkthrough

An overview of the relevant files of the bisos.facter package is provided below.

** ./py3/bin/facter.cs  (./bin/roPerf-facter.cs  ./bin/roInv-facter.cs)

The file [[file:./py3/bin/facter.cs]] is a CS-MU (Command-Services Multi-Unit).
It is fundamentally a boiler plate that has the main framework org-mode Dynamic Block and
which imports its commands from bisos.facter.facter_csu and bisos.banna.bannaPortNu modules.

** ./py3/bisos/facter/facter.py (COMEEGA Python)

The file [[file:./py3/bisos/facter/facter.py]] includes functions that run a sub-process with "facter --json",
obtain the json result as a collection of namedtuples. This can then be subjected to caching and
then retrieved based on string representations mapping to namedtuples.

** ./py3/bisos/facter/facter_conv.py (Conventional Python)

The file [[file:./py3/bisos/facter/facter_conv.py]] is same as  [[file:./py3/bisos/facter/facter.py]]
without use of COMEEGA. Without Emacs, it is not easy to read the COMEEGA files and some people
prefer not to use or know about COMEEGA. In such situations facter_conv.py can be considered as
conventional sample code.

** ./py3/bisos/facter/facter_csu.py

The file [[file:./py3/bisos/facter/facter_csu.py]] is a CS-U (Command-Services Unit).
It includes definitions of commands and their CLI params and args.

Implementation of commands in facter_csu.py rely on facilities provided in facter.py.

** PyPi and Github Packaging

All bisos-pip repos in the https://github.com/bisos-pip github organization follow the same structure.
They all have [[file:./py3/setup.py]] files that are driven by [[file:./py3/pypiProc.sh]].

The [[file:./py3/setup.py]] file is a series of consistent org-mode Dynamic Block
that automatically determine the module name and the installed and pypi revisions.

The [[file:./py3/pypiProc.sh]] uses setup.py and pushes to pypi when desired and
allows for isolated testing using pipx.

* Documentation and Blee-Panels

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

This module's primary documentation is in the form of Blee-Panels.
Additional information is also available in: [[http://www.by-star.net/PLPC/180047]]

** bisos.facter Blee-Panels

bisos.facter Blee-Panles are in ./panels directory.
From within Blee and BISOS these panles are accessible under the
Blee "Panels" menu.

See [[file:./py3/panels/_nodeBase_/fullUsagePanel-en.org]] for a starting point.

* Support

For support, criticism, comments and questions; please contact the
author/maintainer\\
[[http://mohsen.1.banan.byname.net][Mohsen Banan]] at:
[[http://mohsen.1.banan.byname.net/contact]]


* Planned Improvements

One material use of bisos.facter is to facilitate developement of an automated
Configuration Management DataBase (CMDB) as a centralized facility that
organizes information about system, including the relationships between
hardware, software, and networks. On a per-system base, bisos.facter can obtain
much of that information and through PyCS it can deliver that information
remotely to centralized CMDBs. In this context CMDBs generally function as
invokers and we need to facilitate ever present bisos.facter performers.

The CMDB invoker part is implemented as bisos.cmdb.

Each BISOS platform needs to run an instance under systemd.
I have done something similar to this for bisos.marmee.
That piece need to be absorbed.

# Local Variables:
# eval: (setq-local toc-org-max-depth 4)
# End:
