Knowledge Base (Posts about documentation)

Thoughts on my documentation process

bgstack15 — Thu, 15 Jul 2021 13:15:59 GMT

When I write a solution for myself, such as my gallery or my transparent web proxy, I write a master document that describes how I built it, why I built it, and how to use it. Why I built it usually starts the document, and explains what I needed it for: What problem it solves. Sometimes my solutions are proof-of-concept or demonstrations only. But still, I like to remind my future self of what it's for. How I built it ("Architecture") is the section that explains the initial steps, such as packages installed, users added, selinux contexts or policies built (and not necessarily the methodology for building an selinux policy, at this point, due to the repetition), pip packages versus system packages, and so on. Anything that I needed to do only once for the solution (per host, if a multi-node solution). The how to use it section is titled "Operations." I describe how to do tasks, such as set up a new entry or new instance, or modify a commonly-updated setting. This section tends to grow over time as I update the solution. On rare occasions I need to update the architecture section of the document because I had to make a one-time change for the solution. The how-to section can duplicate some information from the Architecture section, if I expect some of those first-time steps are what are repeated for the proposed future steps. When I publish a solution, I try to move all my configs to a separate conf file, so that I can include a app.conf.example file or similar, and exclude app.conf from source control. I even have a small sed script that helps scrub my private data:

$ sed -r -f /mnt/public/work/gitlab/scrub.sed < app.conf > app.conf.example

The contents of the script are mostly just substitutions.

s/privateservername([0-9]*)/serve\1/g;
s/username73/exampleuser5/g;

I always include a References section, so that I can review my sources in the future. I do return to them, because I am seeking to expand my solution or fix a part that breaks (i.e., used to work but doesn't now).

Users, Groups, and Access Policy for Linux

bgstack15 — Fri, 24 Jul 2020 12:32:29 GMT

Summary of policy

User accounts for humans must be domain accounts.
Groups must be domain groups.
Service accounts must be local accounts and have a unique uid within the entire environment.
Passwordless login is allowed within guidelines.
The name of a user or group must not have any spaces.
Access to servers is granted to only groups, not individual users.
Service accounts may be granted direct ssh access within guidelines.

Annotated policy

User accounts for humans must be domain accounts.
Groups must be domain groups.
1. Centralized user and group administration is a corporate standard and is necessary for our scale of operations.
2. The domain to use, unless under special circumstances, is Active Directory domain PROD1.
Service accounts must be local accounts.
1. Service accounts are used by applications and processes that should run independently of any individual users, and should not depend on domain resolution.
2. UIDs for local accounts must be unique within the entire environment. For example, the service account "abcapp" is UID 9950 and no other local account can use that UID anywhere. These UIDs are managed by the Linux Engineering team in file control5:/etc/ansible/uid_gid.
Passwordless login is allowed within guidelines.
1. Kerberos (GSSAPI) authentication between hosts joined to the same domain is enabled by our server configuration standard.
2. Ssh key authentication for users and service accounts is allowed and users may manage their own keys.
The name of a user or group must not have any spaces.
1. While spaces can technically be used, the complexity of supporting spaces in user and group names reduces the effectiveness of automation.
Access to servers is granted to only groups, not individual users.
1. To comply with RBAC guidelines, access must be provided to only groups, even if this means adding a group in the same domain as a single user to provide access to that user. A recommended group name is username_ssh, e.g., mysql_ssh.
Service accounts may be granted direct ssh access within guidelines.
1. Most access to service accounts is through sudo su $SERVICEACCOUNT.
2. Applications and processes with a valid business justification for direct ssh access will be granted direct access after approval . Abuse of a service account direct ssh access includes a human logging in to a service account over direct ssh to an interactive shell. Any such abuse may cause the service account direct ssh access to be revoked.

Found: OBS service documentation

bgstack15 — Mon, 24 Feb 2020 14:20:04 GMT

For some unknown reason, it is really hard to find good documentation on how to use the _service file for the Open Build Service. The Open Build Service (OBS) is a project from the openSUSE team, and they run a public instance at https://build.opensuse.org/. This server application provides a build environment for many distributions' package methods. I use it for my public Devuan packages (see my "OBS" link in the links section of this site, usually a sidebar on each page). The _service file has some generic documentation in the main obs online man pages. I find this documentation extremely lacking in explaining how to use a service file fully. And I've learned by examples extant on the public OBS instance already. So, just to be clear, a _service file is a file in an obs project, that defines a number of steps for the server to take. By default, each service runs for each commit, or whenever you select the "trigger services" button on the web page for a project. I finally found a list of available service names to use! And the links take you to the projects on the Internet where they live and are fully documented. There are quite a few I plan on using in the future... like regex_replace.

Example _service file

With my service file set up to pull down the source debian/ directory as debian.tar.xz, and the entire source as a tar.gz, and extract out my .dsc file from that source, I can manage my OBS project way easier.

<services>
   <service name="tar_scm">
      <param name="scm">git</param>
      <param name="url">https://gitlab.com/bgstack15/fluxbox-themes-stackrpms.git</param>
      <param name="subdir">debian</param>
      <param name="filename">debian</param>
      <param name="revision">local-dsc-file</param>
      <param name="version">_none_</param>
   </service>
   <service name="recompress">
      <param name="file">*.tar</param>
      <param name="compression">xz</param>
   </service>
   <service name="tar_scm">
      <param name="scm">git</param>
      <param name="url">https://gitlab.com/bgstack15/fluxbox-themes-stackrpms.git</param>
      <param name="revision">local-dsc-file</param>
      <param name="version">_none_</param>
   </service>
   <service name="recompress">
      <param name="file">*.tar</param>
      <param name="compression">gz</param>
   </service>
   <service name="extract_file">
      <param name="archive">*.tar.gz</param>
      <param name="files">*/*.dsc</param>
   </service>
</services>

The .dsc file is modified from the output from a proper debuild -us -uc locally. I learned the trick of zeroing out the checksums from another OBS project, waterfox-classic- kpe.

Format: 3.0 (quilt)
Source: fluxbox-themes-stackrpms
Binary: fluxbox-themes-stackrpms
Architecture: all
Version: 0.0.1-1+devuan
Maintainer: Ben Stack 
Homepage: /posts/
Standards-Version: 4.1.4
Build-Depends: debhelper (>= 12~)
Package-List:
 fluxbox-themes-stackrpms deb x11 optional arch=all
Files:
 00000000000000000000000000000000 1 fluxbox-themes-stackrpms_0.0.1.orig.tar.gz
 00000000000000000000000000000000 1 fluxbox-themes-stackrpms_0.0.1-1+devuan.debian.tar.xz

And since the filenames do not match, I think that section is not even necessary. Thankfully OBS figures out what tarballs to use where for the debuild. To quote my original distro (Korora): "Standing on the shoulders of giants."

Conclusion

I can control my osc package with only one file in the obs source control: the _service file! This reduces the need to pass multiple assets, which can be large.

References

Internet searches

How I actually found the main weblink open build service services recompress

Weblinks

https://en.opensuse.org/openSUSE:Build_Service_Concept_SourceService#All_OBS_services_available

Sudoers policy

bgstack15 — Thu, 27 Dec 2018 13:41:50 GMT

Summary of policy

Full sudo access will not be granted.
Sudo su (switch user) access will be granted to service accounts upon request.
Sudo access to specific commands run as specific users is granted upon request.
Sudo chmod is unnecessary because the owning user can already chmod files.
Sudo chown will be granted when applied to specific directories.

Annotated policy

Full sudo access will not be granted, with exceptions granted only by the Linux Engineering team.
1. Full sudo is what is assumed when users ask for "sudo access" without any qualifiers. Users may not mean this; they might mean sudo su $SHAREDACCOUNT but this cannot be assumed. Requests should be explicit as to what user they should run as, and what commands to run.
2. Exceptions will be granted for development/sandbox environments as approved by the Linux Engineering team.
Sudo su (switch user) access will be granted to service accounts as requested through PARs and approved by the Linux Engineering team.
1. Normal access to servers is through individual user accounts, who then switch user to a shared account to manage files and services. Some teams connect directly as a shared account which is not recommended but outside the scope of this policy.
2. Usage of sudo to switch user, when using rules like the example below, include these commands:
```
    sudo su - apache
```
  sudo su apache sudo -i apache sudo -su apache
Sudo access to specific commands run as specific users is granted as requested through PARs and approved by the Linux Engineering team.
1. Perhaps not shells are needed, but just specific commands run as a different user. Switching users to an interactive shell is normal activity.
Sudo chmod is unnecessary because the owning user can already chmod files.
1. A user should not run chmod against files that are not his because this is an unacceptable escalation of privilege.
Sudo chown will be granted when applied to specific directories.
1. If sudo chown * were to be granted, the user could take over system files and is not permissible.
2. Permissible options involve a specific directory name, with the recursive flag.
[appdeployer ~]$ sudo chown -R appdeployer.appdeployer /opt/appdeployer/v5

The entry in sudoers:

appdeployer hostname = (root) /bin/chown -R appdeployer.appdeployer /opt/appdeployer/v5, /usr/bin/chown -R appdeployer.appdeployer /opt/appdeployer/v5

Definitions

Term	Meaning
Full sudo	sudo su root or any other command that uses sudo to achieve a
root shell
PAR	Permission access request ticket

Example sudoers

DB example

This is an example sudoers file.

# file: /etc/sudoers.d/30_db_dbas_sudo
# managed by ansible
# last updated 2018-12-10 20:11Z

User_Alias DBUSERS = %db_dbas, !db
Host_Alias DBHOSTS = l*dbr*, l*dbr*.ad.example.com, l*dbr*.ipa.example.com
Host_Alias DBHOSTS_DEV = l2*dbr*, l2*dbr*.ad.example.com, l2*dbr*.ipa.example.com
Cmnd_Alias BECOME_CMNDS = /bin/su - db, /bin/su db
Cmnd_Alias DBCMNDS = /bin/ls, /bin/ps
Cmnd_Alias DBCMNDS_DEV = ALL

# Users may switch to shared local user
Defaults:DBUSERS !authenticate
DBUSERS DBHOSTS = (root) BECOME_CMNDS
DBUSERS DBHOSTS = (db) ALL

# Local user may run these commands
Defaults: db !authenticate
db DBHOSTS = (root) DBCMNDS
db DBHOSTS_DEV = (root) DBCMNDS_DEV

Webstats example

Another example

# file: /etc/sudoers.d/60_webstats
# managed by ansible
# last updated 2019-01-29T13:12Z
User_Alias WEBSTATSUSERS = %webstats_linux@EXAMPLE.COM
Host_Alias WEBSTATSHOSTS = webstats1*,webstats1*.example.com
Cmnd_Alias WEBSTATSCMNDS = /bin/su - htdocs, /bin/su htdocs, /usr/bin/top *

Cmnd_Alias NGINX_CMNDS = /bin/systemctl start nginx.service, /bin/systemctl restart nginx.service, /bin/systemctl stop nginx.service, /bin/systemctl reload nginx.service, /bin/systemctl status nginx.service, /bin/systemctl enable nginx.service, /bin/systemctl disable nginx.service, /bin/systemctl start nginx, /bin/systemctl restart nginx, /bin/systemctl stop nginx, /bin/systemctl reload nginx, /bin/systemctl status nginx, /bin/systemctl enable nginx, /bin/systemctl disable nginx
Cmnd_Alias PHP_CMNDS = /bin/systemctl start php56-php-fpm.service, /bin/systemctl stop php56-php-fpm.service, /bin/systemctl restart php56-php-fpm.service, /bin/systemctl status php56-php-fpm.service, /bin/systemctl enable php56-php-fpm.service, /bin/systemctl disable php56-php-fpm.service, /bin/systemctl start php56-php-fpm, /bin/systemctl stop php56-php-fpm, /bin/systemctl restart php56-php-fpm, /bin/systemctl reload php56-php-fpm, /bin/systemctl status php56-php-fpm, /bin/systemctl enable php56-php-fpm, /bin/systemctl disable php56-php-fpm
Cmnd_Alias EXTRA_CMNDS = /usr/bin/top *, /usr/local/bin/wsprodapp-permissions.sh, /bin/systemctl daemon-reload, /usr/bin/chown -R htdocs.htdocs /mnt/wsprodapp, /usr/bin/chmod -R u+rwX\,g+rwX /mnt/wsprodapp
Cmnd_Alias HTDOCSCMNDS = NGINX_CMNDS, PHP_CMNDS, EXTRA_CMNDS

# Users may switch to htdocs
WEBSTATSUSERS WEBSTATSHOSTS = (root) WEBSTATSCMNDS
WEBSTATSUSERS WEBSTATSHOSTS = (htdocs) ALL

# htdocs may run these commands
Defaults:htdocs !authenticate
htdocs WEBSTATSHOSTS = (root) HTDOCSCMNDS
User_Alias KUBUSERS = %container_sudoers@AD.EXAMPLE.COM, %containers
Runas_Alias KUBRUNAS = root, containers
Host_Alias KUBHOSTS = k8s*,k8s*.example.com
Cmnd_Alias KUBCMNDS = /usr/bin/docker *, /bin/systemctl start docker.service, /bin/systemctl start docker, /bin/systemctl stop docker.service, /bin/systemctl stop docker, /bin/systemctl restart docker.service, /bin/systemctl restart docker, /bin/systemctl reload docker.service, /bin/systemctl reload docker, /bin/systemctl enable docker.service, /bin/systemctl enable docker, /bin/systemctl disable docker.service, /bin/systemctl disable docker, /bin/systemctl status docker.service, /bin/systemctl status docker, /bin/systemctl daemon-reload, /bin/su containers, /bin/su - containers
KUBUSERS KUBHOSTS=(KUBRUNAS) NOPASSWD: KUBCMNDS

Full sudo

If the Linux Engineering team grants full sudo access, it can be done in this way.

# FS_RUNDECK_USERS is for Full Sudoers
User_Alias FS_RUNDECK_USERS = %appgroup1, %appgroup2
Host_Alias FS_RUNDECK_HOSTS = rundeck*, rundeck*.example.com
Cmnd_Alias FS_RUNDECK_CMNDS = /bin/su, /bin/su - root, /bin/su -
Runas_Alias FS_RUNDECK_RUNAS = root

FS_RUNDECK_USERS FS_RUNDECK_HOSTS = (root) FS_RUNDECK_CMNDS
FS_RUNDECK_USERS FS_RUNDECK_HOSTS = (FS_RUNDECK_RUNAS) ALL

Guidelines for sudoers.d/ filenames

Best practice for sudoers.d/ files is to have them sorted numerically. The company uses number ranges between 00 and 99.

10_low_level_sudo
20_linux_admins_sudo
60_application_group_sudo