Devel (#4)

* starting work on fedora.json

* missing comma

* doh, missing quote

* dammit, missing colon

* dev branch note

* more work on Fedora

* missing comma

* Fedora users through ftp

* Fedora through group 33

* json cleanup

* groups done

* describe Fedora JSON

* git ignore

* fix for Fedora JSON validation

* use 000-CONFIG for duplicate resolution

* update .gitignore

* Notes to self before I snooze

* silence pylint where it is wrong

* fix tab

* 120 characters for user comment field

* adjusted the Makefile

* update TODO

* README work

* work on readme

* readme work

* update spec file

* version update

* script to generate markdown

* hacking notes

* atypshell support

* missing docstring

* some code cleanup

* lots of code cleanup

* work on Fedora compatibility

* tweaks

* pedantic stuff

* goodnight

* new json properties for user accounts

* work on 000-CONFIG section

* adjusted header

* set shebang

* Updated TODO. Take nap.

* add modified property

* add metadata to 000-CONFIG

* add timestamp for JSON validation

* validate 000-CONFIG metadata

* more code cleanup

* Use 0644 on json

* some sys.exit cleanup

* cleanup on main()

* add adjustable dynamic range support

* final tweaks before documentation fix + bug testing

* adjust a few things

* update the man pages

* clarify docstring

* tidying up a bit.

* note to self

* clarifications

* man page tweaks

* squashed some bugs

* fix bug with non-common ID

* start recreating markdown

* initial markdown cleanup

* url typo fix

* minor adjustments

* update date

* update

* work on markdown

* markown fix

* partially done with markdown

* finish markdown

* update timestamp

* update Fedora stuff

* pre-merge final cleanup

* final tweak

.gitignore

@@ -0,0 +1,6 @@
+fubar.py
+.fubar.py.swp
+fubar.json
+.fubar.json.swp
+pylint.log
+.pylint.log.swp

DELETE-FEATURE.md

@@ -0,0 +1,13 @@
+Planned Delete Feature
+======================
+
+With the planned `--delete` feature, what I hope to do is list all
+users that use the group being deleted as their primary group and
+then switch those users to use `nogroup` as their primary group.
+
+In most cases that will be a list of one or zero but that can not
+be assumed.
+
+When deleting a user, first delete a group of same name as listed
+above, then delete the user but in non-destructive to any files
+owned by that user.

HACKING.md

@@ -0,0 +1,58 @@
+Hacking
+=======
+
+Largely notes to myself.
+
+1) Copy the file `functions.py` to `fubar.py`
+
+2) Edit the file `fubar.py`. In the function `myjson()` change
+   `jsonfile = 'yjl-sysusers.json'` to `jsonfile = 'fubar.json'`
+
+3) Further edit `fubar.py`. In the function `main()` change
+   `if myuid != 0:` to `if myuid == 0:`
+
+4) Whatever JSON file you want to work with, copy it to
+   `fubar.json`
+
+You can test the integrity of the JSON via:
+
+    python3 fubar.py --bootstrap
+
+You can test what it does when given arguments by:
+
+    python3 fubar.py [options] somename
+
+When done hacking, remember to run `pylint` on `fubar.py` and fix
+what is reasonable, integrate any changes into `functions.py`
+(using the `diff` command is useful) other than Steps 2 and 3 above,
+and if applicable, merge any JSON changes.
+
+
+New Version Notes
+-----------------
+
+Mostly notes to myself. I have poor short term memory.
+
+Before pull request merging development into main:
+
+1) Make sure both man pages reflect any changes.
+
+2) Make sure to update `Modified:` date in both man pages (line 6).
+
+3) Make sure to update the Month, year, and version in both man pages
+   (`.TH` line 10)
+
+4) run the script `make-docs.sh` (inside the `docs` dir) to regenerate
+   the markdown pages.
+
+5) Hand edit the resulting Markdown pages so they look good in both a
+   console as plain text, and in github markdown web viewer.
+
+6) Make sure version is correct in `yjl-sysusers.spec` file (the
+   `%global gitv` in first line)
+
+7) Make sure version is correct in README.md
+
+8) Merge into `master` branch
+
+9) create new tagged release `v` followed by version.

INSTALL.md

@@ -18,7 +18,7 @@ top level where the `functions.py` file is.
 __Second__, test your version of the `yjl-sysusers.json` file by running
 the following command:
 
-    python3 functions.py 000
+    python3 functions.py --bootstrap
 
 If your JSON is valid and your properties are valid, a bunch of JSON
 will be dumped to screen but the exit status will be 0.
@@ -34,9 +34,11 @@ __Fourth__, run the command
 
     make install
 
-More properly when building an RPM package etc.:
+More properly when building an RPM package:
 
-    DESTDIR=%{buildroot} make install
+    DESTDIR=%{buildroot} make install-rpm
+
+See the reference `yjl-sysusers.spec` file.
 
 __Fifth__, if your `yjl-sysusers.json` file is complete for the
 static UID/GID assignments of your GNU/Linux distribution, consider

Makefile

@@ -13,7 +13,9 @@ RPMMACRODIR = /usr/lib/rpm/macros.d
 dummy:
 	echo "run make install"
 
-install: install-macros install-man install-json install-program
+install-rpm: install install-macros
+
+install: install-man install-json install-program
 
 install-macros:
 	$(INSTALL) -Dm644 macros.yjl-sysusers $(DESTDIR)$(RPMMACRODIR)/macros.yjl-sysusers
@@ -24,16 +26,15 @@ install-man:
 
 install-json:
 	$(INSTALL) -d $(DESTDIR)$(DATADIR)/yjl-sysusers
-	$(PYTHON) functions.py 000 > $(DESTDIR)$(DATADIR)/yjl-sysusers/yjl-sysusers.json
-	$(CHMOD) 0444 $(DESTDIR)$(DATADIR)/yjl-sysusers/yjl-sysusers.json
+	$(PYTHON) functions.py --bootstrap > $(DESTDIR)$(DATADIR)/yjl-sysusers/yjl-sysusers.json
+	$(CHMOD) 0644 $(DESTDIR)$(DATADIR)/yjl-sysusers/yjl-sysusers.json
 
 install-program:
 	$(INSTALL) -d $(DESTDIR)$(SBINDIR)
 	$(SED) -e s?"cfgdir = ''"?"cfgdir = '$(DATADIR)/yjl-sysusers'"? < functions.py > $(DESTDIR)$(SBINDIR)/yjl-sysusers
 	$(CHMOD) 0750 $(DESTDIR)$(SBINDIR)/yjl-sysusers
 
 uninstall:
-	$(RM) -f $(DESTDIR)$(RPMMACRODIR)/macros.yjl-sysusers
 	$(RM) -f $(DESTDIR)$(MANDIR)/man8/yjl-sysusers.8
 	$(RM) -f $(DESTDIR)$(MANDIR)/man5/yjl-sysusers.json.5
 	$(RM) -f $(DESTDIR)$(DATADIR)/yjl-sysusers/yjl-sysusers.json

README.md

@@ -1,7 +1,7 @@
 yjl-sysusers
 ============
 
-__VERSION 0.1.0 PRE-RELEASE__
+__VERSION 0.1.5 PRE-RELEASE__
 
 For installation instructions, see [INSTALL.md](INSTALL.md)
 
@@ -10,55 +10,76 @@ source, that utility is simply called `functions.py` but it gets
 installed as `/usr/sbin/yjl-sysusers` with a single-line change
 to specify the location on the filesystem of the JSON file.
 
-I am developing this using Python 3.11.3 but it has been tested in
-Python 3.6.4 (CentOS 7) without issues.
+This project is currently being developed using Python 3.11.3 but it
+has been tested in Python 3.6.4 (CentOS 7.9.2009) without issues.
 
-The purpose is to provide an easy way to provide consistent user ID
-and group ID numbers for system users (as opposed to human login users)
-while also being able to on-the-fly use dynamic IDs if the static IDs
-have already been used for something else.
+The purpose is to provide an easy way to provide consistent static
+user ID and group ID numbers for system users (as opposed to human login
+users) while also being able to on-the-fly use dynamic IDs if the static
+IDs have already been used for something else.
 
 My use case is for RPM `%pre` scriptlets to ensure that the appropriate
 users and groups an RPM package needs exist when the package installs.
 
-See the [yjl-sysusers.8](docs/yjl-sysusers.8.md) man page.
+
+yjl-sysusers
+------------
+
+With the `yjl-sysusers` utility, portable RPM spec files which produce
+packages that are installable across multiple LSB compliant GNU/Linux
+distributions (sometimes with a rebuild for shared library resolution)
+becomes much easier.
+
+Theoretically (not yet implemented or tested) with the `yjl-sysusers`
+utility, translations of user comment (also called GECOS) `/etc/passwd`
+field into the default system locale will be automatic, assuming the
+translation is available.
+
+See the [yjl-sysusers.8](docs/yjl-sysusers.8.md) man page for usage.
 
 
 yjl-sysusers.json
 -----------------
 
-This JSON file contains all the information needed to create system
-users and groups for YellowJacket GNU/Linux.
+The `yjl-sysusers.json` file in the top-level directory of the source
+tarball is tailored to YellowJacket GNU/Linux.
 
-It is largely based upon the static system user information from
-LFS/BLFS 11.3 but there are some differences.
+The `yjl-sysusers.json` file installed by a package manager *should*
+be tailored to the distribution the package is built for.
 
-It is currently a work in progress, some of the JSON entries are not
-complete and others are planned but missing.
+This JSON file includes the distribution-specific static UID/GID
+assignments for certain users and groups, as well as distribution-
+specific configurations for how to handle things like dynamic UID/GID
+allocation.
+
+A network or organization administrator of multiple systems—even different
+distributions—can customize the JSON and rebuild the package to add
+specific static allocations that are needed for use cases specific to
+that network or organization.
 
 For the file format, see
 [yjl-sysusers.json.5](docs/yjl-sysusers.json.5.md) man page.
 
+As long as `yjl-sysusers.json` matches the specification of your
+distribution and the requirements of your distribution, you should
+be able to install this package and then any RPM package that uses
+`yjl-sysusers` to ensure system groups and users exist should do the
+right thing on your system.
 
 
 Validation Failures and Handling
 --------------------------------
 
-If the user running the `yjl-sysgroups` utility does not have `root`
-privileges, the utility will exit with a failure status.
-
 If the JSON file is malformed, the `yjl-sysgroups` utility will exit
 with a failure status. That should never happen unless the JSON file
 is improperly modified after install.
 
+If the user running the `yjl-sysgroups` utility does not have `root`
+privileges, the utility will exit with a failure status.
+
 If a username or groupname passed as an argument does not validate,
 the `yjl-sysusers` utility will exit with a failure status.
 
-If anything other than the case sensitive `True` or `False` is passed
-with the `--useradd`, `--groupadd`, or `--mkdir` options, the
-`yjl-sysusers` utility will exit with a failure status. I consider
-that to be a bug.
-
 If there are no available UIDs/GIDs left in the system user dynamic
 range when one is needed, the `yjl-sysusers` utility will exit with
 a failure status.
@@ -72,3 +93,75 @@ the home directory or `/sbin/nologin` as the login shell) if a bad
 value is passed to `yjl-sysusers` so that the user is created and
 the proper assignment of files belonging to users and groups the
 script is asked to create can still be made.
+
+
+Python Notes
+------------
+
+Python 3 is required. A few distributions (like CentOS 7) are still
+at present supported that use Python 2 as the distribution Python
+interpreter, but AFAIK all of those distributions offer Python 3 as
+well.
+
+One feature I know requires Python 3.6+, the script has been tested
+in Python 3.6.8 (CentOS 7.9.2009) and it works.
+
+I strive to always have a `pylint` score at or above 9 but even when
+at such a score, reported issues should be looked at.
+
+False positives are disables and `global keyword` warnings are disabled,
+this utility has a genuine use case for the `global keyword`.
+
+The `pylint` utility reports that the `adjust_username_object()` function
+has too many forks. That function has a lot of options to adjust for
+and I suspect refactoring that function to make `pylint` happy would
+only decrease readability.
+
+The `pylint` utility also reports some `No exception type(s) specified
+(bare-except)` warnings.
+
+At least some of those are safe to ignore, but I do not feel comfortable
+disabling that warning. It may be possible to properly deal with all
+of those cases.
+
+
+My Arrogant Distribution Packaging Rant
+---------------------------------------
+
+By ‘My Arrogant’, I do mean me.
+
+I literally __HATE__ distribution specific macros and how they have
+proliferated in quantity and complexity since the ‘Good Old Days’.
+
+Now get off my lawn, ya damn youngsters! Humor aside, it does seem RPM
+packaging is losing the KISS 😛 concept and I think that is bad for
+GNU/Linux.
+
+A desktop user should not have to be a packaging guru in order to
+successfully rebuild a spec file written for Distribution A on
+the user’s Distribution B system. That is incredibly frustrating
+and encourages users to just not utilize the package management
+system, often leading to future problems and frustrations.
+
+Something as simple and universal as ensuring the proper system users
+and groups exist should not, for example, require a
+`systemd-rpm-macros` package and the installation of a package-specific
+user metadata file that often only have meaning to a specific distribution.
+
+What the frack does SystemD have to do with basic Un•x user and group
+management?
+
+Yes, Fedora, I am talking smack about you. You are no longer the
+distribution I loved when Red Hat Linux became Fedora Core.
+
+Most RPM based distributions are guilty of the same thing, clearly
+making RPM unsuitable as an LSB-mandated package manager.
+
+I like RPM when used properly, but it is too easy for GNU/Linux
+distributions to do the wrong thing and decrease cross-distribution
+compatibility.
+
+Some added complexity is sometimes necessary, but SystemD being
+required for fundamental user and group management? No. Just No.
+
+![Nancy Reagan: Just Say No (national archives PD)](justsayno.jpg)

TODO.md

@@ -1,12 +1,13 @@
 TODO
 ====
 
-Right now it mostly works.
+add --delete option --- the argument is there, but it does not actually
+do anything yet.
 
-Need an installer (Makefile)
+--------------------------------
+
+Right now it mostly works but needs testing.
 
 It needs to be integrated with gettext for string i18n string
 translation.
 
-Need to fix the bugs referenced in
-[yjl-sysusers.8](docs/yjl-sysusers.8.md#bugs)

YJL-Notes.md

@@ -5,7 +5,7 @@ The Linux Standards Base (apparently now defunct) was a good concept
 but had some bad results, such as specifyung RPM as a package manager.
 
 That being said, much of what it did produce can be seen as ‘good practices’
-that distributions should adhere to unless there is a reason to (e.g.
+that distributions should adhere to unless there is a reason not to (e.g.
 no distribution should be compelled to support installation of third-party
 packages via RPM when plain old `tar` has been used for that in Un-x
 for decades).

contrib/README.md

@@ -0,0 +1,23 @@
+WARNING
+=======
+
+Fedora
+------
+
+Fedora JSON is based upon:
+
+https://docs.fedoraproject.org/en-US/packaging-guidelines/UsersAndGroups/
+(2023-05-28)
+
+It still needs some useradd metadata and needs to be double-checked.
+
+I was not able to find published information on what Fedora currently uses
+as `SYS_UID_MIN` or `SYS_UID_MAX` so I did not specify that within the
+__000-CONFIG__ section.
+
+Also I do not think it is complete. For example, `apache` is not listed
+there but at least historically, a static UID/GID was used in the
+Red Hat/Fedora world for `apache`.
+
+The Fedora JSON file however should be a decent base for someone more
+familiar with current Fedora to start with, assuming there is interest.