~ Return to the rest of the site

# software

## Foreword

Due to the majority of designers having typical ability, use of computers may be significantly more challenging for users with disabilities, especially affecting sight and reading. Change in this regard for those that simply lack the facilities to read but have the patience to do so is inevitable but slow, with current measures being proprietary (designed first to make money and second for function) or sorely lacking in actual useability. Helping users with a deeper inability to read extensively is a tougher problem to which the solution may not yet be known even vaguely. The only advice I can offer is that everyone should, until the point at which it harms others, see to the removal of obstacles to their ability, without hesitation or apology. If you give up on computing, so be it. There are more valuable things to explore in life.

Computers encase lightning within sand with the purpose of creating a lifelike inanimate robot that can consider particularly boring thought. Measures should be taken to avoid attachment, whether mental, emotional, or physical, to computers. Caution can accompany admiration. Ultimately, the humans were the ones that produced the computers, and computers amplify human flaws as well as human feats. Try to be kind to everyone but don't take anything too seriously.

This guide encompasses usage of IBM-compatible, amd64 processor architecture computers, particularly with POSIX and other UNIX-like operating systems like Linux and DragonflyBSD. Non-standard, proprietary operating systems such as Microsoft Windows or OS/2 are out of scope.

## UNIX

- Unix (Wikipedia)
- unix-history-repo (GitHub)

## Advanced Configuration and Power Interface

- Advanced Configuration and Power Interface (Wikipedia)

The Advanced Configuration and Power Interface, or ACPI, is the interface through which the operating system and client programs can control features in your computer's firmware. Usually this is used with an ACPI client or opaquely controlled by the operating environment.

On Linux, `acpi(1)` can be used to read and control ACPI events manually. `acpid(8)`, `elogind(8)`, SystemD, and many desktop environments can control the ACPI automatically.

On NetBSD, see `acpi(4)`.

## C Language

For compilation, `tcc(1)`, `gcc(1)`, and `clang(1)` are all reasonable choices depending on your needs.

On Alpine Linux, the standard library headers are in the `musl-dev` package.

In most system package managers, standard library documentation can be found in the `man-pages` and `man-pages-posix` packages.

Many Linux software distributions' system package managers have meta-packages that pull all necessities for C development as dependencies. Alpine has `build-base` and Debian has `build-essential`.

## echo(1)

- Variations in echo implementations

Don't use `echo(1)`, use `printf(1)`. `printf(1)` simulates the `printf(3)` function in the C standard I/O library which has no significant variations, whereas the functionality of `echo(1)` can vary between vendors. The following `sh(1)` program provides `echo(1)` through `printf(1)`:

    #!/bin/sh
    printf "%s" "$*"

## find(1)

- find (Wikipedia

## Fonts

## fstab

See `fstab(5).`

postmarketOS requires that the `localmount` OpenRC service be enabled for the system to read `fstab(5)`.

Arch and Artix have fstab generators at `genfstab(8)` and `fstabgen(8)` respectively in their installation scripts.

## Linux

- How to Linux
- How to Use User Mode Linux
- LINUX's History
- The Linux Kernel documentation
- LINUX is obsolete
- Linux From Scratch
- Move your Linux from BIOS to UEFI in place
- Using the Linux kernel's Case-insensitive feature in Ext4

### Audio

Most audio servers recommend that they be run in userspace with user privileges, with PulseAudio going so far as to exiting when run as root without additional configuration. The Alpine wiki currently recommends `pipewire(1)`, with postmarketOS, which is based on Alpine, coming pre-configured with PipeWire. PipeWire is relatively new and the typical audio server used is PulseAudio; Debian and many popular Debian-based distributions come pre-configured with PulseAudio.

#### ALSA

- Adding sound (Alpine Linux Wiki)
- ALSA lib conf Evaluate error
- ALSA lib pcm_dmix.c:1108:(snd_pcm_dmix_open) unable to open slave

The Alpine wiki ("Adding sound") says to install `alsa-conf`, `alsa-lib`, and `alsa-utils`, add yourself to the `audio` group, and then do some more configuration that I've never needed to do: Use `alsamixer(1)` to find a working sound card (press `F6` from the first screen ALSAMixer presents) and edit `/usr/share/alsa/alsa.conf` and change `defaults.ctl.card` and `defaults.pcm.card` to the sound card that works.

The Alpine wiki doesn't mention this but you'll need to enable the `alsa` OpenRC service and either start it or reboot. I also installed `gstreamer` but I don't know why.

ALSA is clunky, many people prefer to use a frontend such as Pipewire or PulseAudio that exposes its own interface while remaining compatible with ALSA.

#### OSS

Deprecated, unfortunately.

#### PipeWire

- PipeWire (Alpine Linux Wiki)
- PipeWire (FreeDesktop Wiki)

Provided by the `pipewire` package on Alpine.

    RTKit error: org.freedesktop.DBus.Error.ServiceUnknown

This means you need `rtkit` installed and running through your initialization system.

#### PulseAudio

On Alpine you'll need the `pulseaudio`, `pulseaudio-alsa`, and `alsa-plugins-pulse` packages for PulseAudio with ALSA compatibility. Start `pulseaudio(1)` when you want audio, ideally in your `.xinitrc`.

### Distribution

Linux is usually obtained as part of a software distribution put together to form a useable operating system.

#### Alpine

- Alpine repositories content search

##### Always install manual pages

Alpine doesn't include man pages in program packages to save on space, instead keeping them in `[package]-doc` sibling packages. To always install doc packages with program packages, `apk add docs`.

#### Arch

Arch is known for using the latest versions of programs, which has given it an undeserved reputation of instability.

##### Bootstrapping

Use `pacstrap(8)`.

At a minimum you need the `base` package. Select a kernel and install the corresponding package; `linux`, `linux-lts`, or another Linux configuration or fork. The Arch wiki says you need to install `linux-firmware`, this isn't strictly necessary but it is recommended. Install `base-devel` if you plan on using the AUR or if you don't know what the AUR is yet.

It's also a good idea to install any utilities you'll need on the bootstrapped system. Text editors, network managers or utilities, and other administration tools, for example. Manual utilities such as `man-db` and others would also be useful.

##### Ubiquitous packages missing

From the anals of my notes, 2021-06-04:

    Had an issue with pacman missing some ubiquitous packages (esr's `ascii`, xorg-xev, etc).
    This fixed it. I don't really know why - maybe some issues with my repos?
    This was cleanly installed artix-openrc.

    [5:46 PM] Bassman Leyla: So what I did is I went into /etc/pacman.d/mirrorlist-arch and uncommented a local mirror
    [5:46 PM] Bassman Leyla: Then I appended a config block a package maintainer gave me onto /etc/pacman.conf
    [5:46 PM] Bassman Leyla: I'll paste it in
    [5:47 PM] Bassman Leyla:
    ```
    #
    # ARCHLINUX
    #

    #[testing]
    #Include = /etc/pacman.d/mirrorlist-arch

    [extra]
    Include = /etc/pacman.d/mirrorlist-arch

    #[community-testing]
    #Include = /etc/pacman.d/mirrorlist-arch

    [community]
    Include = /etc/pacman.d/mirrorlist-arch

    #[multilib-testing]
    #Include = /etc/pacman.d/mirrorlist-arch

    #[multilib]
    #Include = /etc/pacman.d/mirrorlist-arch
    ```

#### Artix

- Artix Linux
- Artix Linux (Wikipedia)

Artix refers to the series of Arch derivatives which use initialization systems other than SystemD's.

##### Bootstrapping

This process differs from Arch's bootstrapping process. Artix uses `basestrap(8)` rather than `pacstrap(8)`; you need to select the initialization you want to use: `66`, `dinit`, `openrc`, `runit`, or `s6-base`, as a package separate from `base`; and Artix's official wiki says you need to install the appropriate `elogind` package (`elogind-[initialization system]` e.g. `elogind-66`) but like `linux-firmware` though it is helpful it isn't strictly necessary.

#### Debian

- Debian
- Debian (Wikipedia)

Debian is known for its stability and longevity. Debian uses SystemD as its initialization system, the GNU core utilities, and dpkg and apt for package management.

While it's possible to use non-Linux kernels within Debian, it's uncommon and the only non-Linux option currently maintained is the GNU HURD microkernel.

pkgsrc can be used on Debian.

#### postmarketOS

postmarketOS is an Alpine-based Linux software distribution that makes configuring and using Linux easy on mobile devices.

##### Random MAC address generation on Wifi

By default, postmarketOS will generate a random software MAC address when connecting to a new WLAN network. You can disable this by adding a NetworkManager rule. In `/etc/NetworkManager/conf.d/` you can make a file with any name that has the following:

    [device]
    wifi.scan-rand-mac-address=no

On a live system you can then `rc-service networkmanager restart` to restart NetworkManager and have it load the new configuration.

#### Ubuntu

- How to get root on Ubuntu 20.04 by pretending nobody's /home

Ubuntu is a derivative of Debian.

### logind

- elogind
- elogind (Gentoo Wiki)
- org.freedesktop.login1
- logind (NixOS Wiki)

logind (`systemd-logind.service(8)`) is a component of SystemD that exposes information about active users on the system via the org.freedesktop.login1 D-Bus interface which is used by the popular desktop environments GNOME and KDE. It also handles ACPI events. It can be configured in `logind.conf(5)`.

On systems without SystemD and with conflicting software, `elogind(8)` may be used.

### Xenia

- A hacker fox!

Xenia was an entry for the Linux logo competition which Tux eventually won.

## Make utility

`make(1)` in modern times is fragmented into the GNU version (in context, `gmake`) and the {Free,Open,Net}BSD version (`bmake`). Complex Makefiles may not be useable in both. It's custom for Linux systems to have `make(1)` as GNU Make and `bmake(1)` as BSD Make, and BSD-based systems to have `make(1)` as BSD Make and `gmake(1)` as GNU Make.

## On-line manual

In the context of POSIX and UNIX-like systems, an "on-line" manual is a manual that is accessible via the computer system it documents. Particularly, the `man(1)` utility and the manual "pages" it references.

Alpine by default uses `mandoc`.

## Paging

`less(1)` is `more(1)`; more or less.

## Partitions and filesystems

- EFI system partition (Arch Wiki)
- Installation#Partition your disk - Artix wiki
- Installation guide#Partition the disks - Arch wiki

Don't use partitioners included with OS media where the same job can be done by GParted (which has live media available) or another good general-purpose partitioner. BSDs and Plan 9 are exceptions to this rule due to their exotic partitioning systems. Using utilities from a shell or TUIs does not make you "cooler" than someone who needs a GUI for partitioning; in some cases, messing up partitioning can have serious consequences, so it's always nice to have some idiot-proofing. I always partition my disks with the GParted live media.

You should do your own research on how you should partition your disks. I personally use separate partitions for /boot, /home, /, and swap. Your needs will vary.

Please note that a separate boot partition is mandatory if you intend to boot via (U)EFI. Check out the linked pages in the "See also" section.

Use `mkfs(8)` for creating filesystems and `mount(8)` for mounting partitions' filesystems.

### gpart

- Gpart (Wikipedia)

Available as `sysutils/gpart` in pkgsrc.

`gpart(8)` is a tool that scans a file (or block device presented as a file) for drive partitions regardless of any table present on the medium.

### LUKS

- Automatically Unlock LUKS Encrypted Drives With A Keyfile
- Dm-crypt (Gentoo Wiki)
- How to backup and restore LUKS header on Linux
- How To Encrypt Partition on Linux
- LUKS passphrases: Changing, adding, removing
- LVM on LUKS (Alpine Wiki)

`e2fsprogs` is needed for the `dm_mod` kernel module used for LUKS partition decryption.

To format a partition to a LUKS volume, determine the physical block device location for that partition and run `cryptsetup luksFormat [partition]`. The passphrase used can be changed or removed after creation.

To open a LUKS volume, use `cryptsetup luksOpen [partition] [name]`. This name is the name the decrypted block device location will take in `/dev/mapper/`.

Before the decrypted block device has a filesystem it'll just be cleared space - format as normal but use the decrypted block device location.

To mount a partition in an opened LUKS volume, use `mount(8)` as normal, just with the decrypted block device location.

To close an open LUKS volume, `umount(8)` any mapped and mounted partitions from the volume and `cryptsetup luksClose [name]`.

To make the LUKS partition openable via keyfile, first make a keyfile (`dd if=/dev/urandom of=/root/keyfile bs=1024 count=4` seems to work), and optionally make it readable by root only (`chmod 0400 [keyfile]`). Then add the keyfile to the partition's LUKS header with `cryptsetup luksAddKey [physical partition block device] [keyfile]`.

#### dm-crypt

`dm-crypt` is a service that automatically mounts LUKS volumes at boot.

On most OpenRC-initialized distributions, the `cryptsetup-openrc` package provides `dmcrypt`. Make sure that service is added to runlevel boot.

Configuration is in `/etc/conf.d/dmcrypt` and further configuration should be done in `fstab`. `dm-crypt` will need the UUID of the physical block device while fstab (if being configured with UUIDs will need the UUID of the decrypted block device in the device mapper.

### TestDisk

- TestDisk (Wikipedia)

## NetBSD

- netbsd.org
- NetBSD Guide
- pkgsrc Guide

### Battery

`envstat(1)` can show the current battery status.

### Mounting filesystems

1. Connect the drive with the filesystem you want to access.
2. Use `dmesg(8)` to determine the location in `/dev/` of the disk.
3. `disklabel(8)` the drive to determine which partition on the disk you want to access (`disklabel /dev/disk`)
4. `mount(8)` the filesystem.
5. `umount(8)` the filesystem when done using it.

#### ext4

Install `filesystems/fuse` and `filesystems/fuse-ext2`. `disklabel(8)` will list ext4 filesystems as of type "Linux Ext2". Use `fuse-ext2(1)` to mount the filesystem.

`fuse-ext2(1)` is spotty in places and may not work correctly.

#### exFAT

Install `filesystems/fuse` and `filesystems/fuse-exfat`. Use `mount.exfat` to mount the filesystem (the manual page for which is `mount.exfat-fuse(8)`).

### Fix `SSL certificate problem: unable to get local issuer certificate`

- Depending on security/ca-certificates?
- Installing CA certificates on NetBSD
- SSL Certificate Problem (ohmyzsh/ohmyzsh#8321)

Install `security/mozilla-rootcerts-openssl`.

Do not use SSL workarounds like (in the case of git) `GIT_SSL_NO_VERIFY`. These leave your system open to man-in-the-middle attacks.

### rc.d

- The Design and Implementation of the NetBSD rc.d system

### System logging

- System instability on unstable version - how do I get logs?

See `syslogd(8)` and `syslog.conf(5)`, which pertain to system logging.

Setting `DDB_ONPANIC` (see `options(4)` and `sysctl(8)`) will save a crash dump at `/var/crash` on kernel panic.

### Upgrading

- The NetBSD Guide - Chapter 4: Upgrading NetBSD
- Upgrading NetBSD using sysinst

## PCI Utilities

- pciutils/pciutils (GitHub)

Available as `sysutils/pciutils` from pkgsrc. Supplies `lspci(8)`, `setpci(8)`, and `update-pciids(8)`.

`update-pciids(8)` is not part of the `pciutils` package in Alpine Linux repositories.

NetBSD includes `pcictl(8)` which offers similar functionality. `pcictl pci0 list` outputs roughly the same information as `lspci(8)`, though `lspci(8)` may offer slightly more detailed information.

## pkgsrc

- the pkgsrc user's guide

### Upgrading packages

- Using pkgsrc (the pkgsrc user's guide)
- how to upgrade packages (NetBSD Developer Wiki snapshot; 2020-09-09)

See `pkgtools/pkg_rolling_replace`.

## Power settings

Power is managed by ACPI.

## SSH keys

- Adding a new SSH key to your GitHub account (GitHub Docs)
- Checking for existing SSH keys (GitHub Docs)
- Generating a new SSH key and adding it to the ssh-agent (GitHub Docs)

SSH keys are typically stored in `$HOME/.ssh`.

Typically, the public key's filename will be suffixed with `.pub`, while the private key will not.

You can generate an SSH key with `ssh-keygen(1)`. Currently the preferred implementation is `openssh-keygen`, part of the OpenSSH suite.

Microsoft GitHub documentation suggests a user create a key with `ssh-keygen -t ed25519 -C "[e-mail address]"`. This generates an Ed25519 SSH key with an e-mail address in the key comment.

## Pronunciation

- Common pronunciations of Linux directories, commands, etc

## Task management

`top(1)` comes with busybox, otherwise use `htop`.

## Text editing

`nano(1)` is a text editor that's usually recommended for beginners because its controls are more intuitive. `ne(1)` is like `nano(1)` but with different superpowers. Not yet in pkgsrc.

### ed

- Ed Cheat Sheet

A particularly shoddy attempt at `ed(1)` is provided by `busybox`. A traditional `ed(1)` implementation is in plan9ports. I'm pretty sure some later UNIX-based OSes doubled the `ed(1)` buffers, there's pretty much no downside to doing so in the modern era but it should be very easy to do yourself if it hasn't already been done (just double some of the array sizes in the beginning of `ed.c`).

### vi

Unlike `busybox`'s `ed(1)` implementation, its `vi(1)` is very useable. `vim(1)` is a popular re-implementation of `vi(1)`.

### emacs

Emacs ("editor macros") is a text editor with a very powerful Lisp interpreter included. Lisp is mostly antiquated due to its undeserved lack of popularity. Linus Torvalds uses his own fork of uEmacs ("micro Emacs"), an Emacs without the Lisp interpreter(?).

### cat

Technically `cat(1)` and other UNIX utilities can be used in a hacky way for text editing functions. You'd be better off using `ed(1)`; the UX is very similar.

## true(1)

- CHAMBERS John - The /bin/true Command and Copyright
- PIKE Rob - "/bin/true used to be an empty file."
- RAITER Brian - A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux
- true(1p) (The Open Group, 2003)
- Notable true implementations
  - ongoing started 1992 - GNU/coreutils - src/true.c
  - ongoing forked from 4.4BSD-Lite2 - NetBSD/src - usr.bin/true/true.sh

`true(1)` is a tool that only quits silently with an exit status of 0. Similarly, `false(1)` is a tool that only quits silently with an exit status of 1. Recognizing arguments, printing to standard output, reading from standard input, or otherwise exiting with any other status of 0, is a violation of the POSIX specification for `true(1)`. These utilities find use in shell scripting, which, though extremely relevant to these utilities, is beyond the scope of this article.

Because `true(1)`'s required functionality is so simple a POSIX-compliant implementation is a one-liner in most languages, so long as you're willing to make an exception in your code styling. For example, in C:

    int main(void) { return 0; }

Because executing an empty shellscript file will in most shells do nothing and return an exit status of 0, technically an empty shellscript file is a POSIX-compliant `true(1)` implementation in 0 bytes. This was the `true(1)` implementation on early versions of UNIX, including Research UNIX, System V, and Sun's Solaris, according to both Rob Pike and John Chambers. A more explicit implementation also exists in POSIX shell:

    #!/bin/sh
    exit 0

This happens to be nearly identical in source to the implementation used by NetBSD.

Python has the same 0 byte `true(1)` implementation feature as most shells. Here's `false(1)` in Python rather than `true(1)` to demonstrate how exiting with an arbitrary exit status can be done:

    import sys
    sys.exit(1)

In some shells, `true(1)` is a shell built-in command, so running `true` will run the shell author's implementation of `true(1)` rather than the system implementation.

GNU `true(1)`, from the GNU coreutils, is well known for being a maximalist implementation - it's eighty lines long and directly includes four C header files. Their `true.c` is 2.3 kilobytes and parses the arguments `--help` and `--version` (only if either are the first argument to the program). The GNU coreutils implementation of `true(1)` is not POSIX compliant.

## util-linux

- util-linux - Wikipedia

`util-linux` is distributed on all popular Linux distributions and contains utilities users may expect to be already present on their systems, like `more(1)` or `hexdump(1)`.

## WiFi

### wpa_supplicant

`wpa_supplicant(1)` is usually good enough for establishing WiFi connections.

Here's an example configuration for a simple WPA-2 PSK access point.

    network={
    	ssid="My SSID"
    	key_mgmt=WPA-PSK
    	scan_ssid=1
    	psk="My password"
    }

See `wpa_supplicant.conf(5)`.

## X

- Cool, but obscure X11 tools
- Xorg (Arch Wiki)

X is a graphical windowing system that can be used on Linux, FreeBSD, OpenBSD, NetBSD, and some proprietary operating systems as well. X is not the only windowing system; `twin(1)` exists for windowed multitasking within a framebuffer and Wayland is another windowing system intended to replace X.

Xorg requires the user to be a member of the `input` and `video` groups (or superuser), otherwise it won't be able to access the relevent device files. These errors look like `Failed to open /dev/input/event[number] (Permission denied)` when not in the `input` group and `Failed to open /dev/tty[number] (Permission denied)` when not in the `video` group.

Some Linux software distributions have included scripts to automatically fetch and install an X server. Alpine has `setup-xorg-base`, which adds the packages `xorg-server`, `xf86-input-libinput`, `eudev`, and `mesa`, and then enables the OpenRC services for udev.

`startx(1)` is provided as part of xinit.

Arch has the `xorg` and `xorg-apps` package groups. Documentation can be found within `xorg-docs`, drivers within the `xorg-drivers` package group, the server itself as `xorg-server`, the X event monitor as `xorg-xev`, xinit as `xorg-xinit`, xinput as `xorg-xinput`, XRandR as `xorg-xrandr`, the X resource database manager as `xorg-xrdb`, xset as `xorg-xset`, and xsetroot as `xorg-xsetroot`.

Alpine has xinput as `xinput`.

### Media

`mpv(1)` and `vlc(1)` are good options.

### Window Management

It's possible to make X exec a window manager at the end of initialization to ease the creation, deletion, and manipulation of windows. Contrary to what is now popular belief, window managers are not necessary (thought they're extremely convenient compared to the lack of them).

#### ctwm

- Configurations for ctwm (and twm)

### Web Browsing

#### TOR Browser

TOR Browser is available through pkgsrc at `security/tor-browser`.