commit de66473dc03b17b7683e72b9bab8ea86d0919309 parent ca313cfea3161b573ac1c37e73d02344a3f0e57a Author: aabacchus <ben@bvnf.space> Date: Mon, 16 May 2022 01:19:09 +0100 Import old community wiki Diffstat:
| A | wiki/boot/efistub/index.txt | | | 88 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/boot/efivarfs/index.txt | | | 27 | +++++++++++++++++++++++++++ |
| A | wiki/boot/index.txt | | | 5 | +++++ |
| A | wiki/console/bkeymaps/index.txt | | | 46 | ++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/console/fonts/index.txt | | | 39 | +++++++++++++++++++++++++++++++++++++++ |
| A | wiki/console/index.txt | | | 5 | +++++ |
| A | wiki/desktops/index.txt | | | 4 | ++++ |
| A | wiki/desktops/kde/index.txt | | | 737 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/dev/index.txt | | | 4 | ++++ |
| A | wiki/dev/replacing-udev/index.txt | | | 116 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/init/busybox/index.txt | | | 78 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/init/changing-init/index.txt | | | 111 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/init/index.txt | | | 6 | ++++++ |
| A | wiki/init/sysmgr/index.txt | | | 90 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/kernel/config/index.txt | | | 169 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/kernel/firmware/index.txt | | | 383 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/kernel/index.txt | | | 6 | ++++++ |
| A | wiki/kernel/patches/kernel-no-perl.patch | | | 292 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/kernel/thinkpad/index.txt | | | 31 | +++++++++++++++++++++++++++++++ |
| A | wiki/kiss/index.txt | | | 4 | ++++ |
| A | wiki/kiss/style-guide/index.txt | | | 473 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/software/acpid/index.txt | | | 149 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/software/alsa-utils/index.txt | | | 84 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/software/dhcpcd/index.txt | | | 166 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/software/eiwd/index.txt | | | 139 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/software/git/index.txt | | | 287 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/software/index.txt | | | 14 | ++++++++++++++ |
| A | wiki/software/man-pages/index.txt | | | 64 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/software/opendoas/index.txt | | | 52 | ++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/software/openssh/index.txt | | | 141 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/software/tzdata/index.txt | | | 65 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/software/vim/index.txt | | | 211 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/software/wpa_supplicant/index.txt | | | 143 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/storage/disks/index.txt | | | 603 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/storage/index.txt | | | 6 | ++++++ |
| A | wiki/storage/zram/index.txt | | | 124 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/storage/zswap/index.txt | | | 92 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/wayland/index.txt | | | 4 | ++++ |
| A | wiki/wayland/install-wayland/index.txt | | | 160 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/xorg/index.txt | | | 9 | +++++++++ |
| A | wiki/xorg/keyboard-layout/index.txt | | | 52 | ++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/xorg/sx/index.txt | | | 74 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/xorg/x11-forwarding/index.txt | | | 135 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/xorg/x11vnc/index.txt | | | 71 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/xorg/xinit/index.txt | | | 64 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | wiki/xorg/xorg-server/index.txt | | | 125 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
46 files changed, 5748 insertions(+), 0 deletions(-)
diff --git a/wiki/boot/efistub/index.txt b/wiki/boot/efistub/index.txt @@ -0,0 +1,88 @@ +EFISTUB [0] +________________________________________________________________________________ + +The Linux kernel has the ability to act as an EFI executable which simplifies +the boot process by removing the need for a bootloader. + + +Prerequisites +________________________________________________________________________________ + +Begin by first verifying that you have efibootmgr installed: + ++------------------------------------------------------------------------------+ +| | +| $ kiss b efibootmgr && kiss i efibootmgr | +| | ++------------------------------------------------------------------------------+ + +The kernel must be configured to support acting as an EFISTUB. + ++------------------------------------------------------------------------------+ +| | +| CONFIG_EFI_STUB=y | +| | ++------------------------------------------------------------------------------+ + +The UEFI variables must be mounted. + +See: @/efivarfs + ++------------------------------------------------------------------------------+ +| | +| TIP: Keep your kernel's name as 'vmlinuz' to avoid having to update the | +| EFI entries with each kernel update. | +| | ++------------------------------------------------------------------------------+ + + +Create an UEFI boot entry +________________________________________________________________________________ + +Use the following command to create a boot entry. Replace /dev/sdXN with your +EFI system partition and /dev/sdYM with your root partition. Check to see that +the entry was added with 'efibootmgr --verbose'. + ++------------------------------------------------------------------------------+ +| | +| $ efibootmgr \ | +| --create \ | +| --disk /dev/sdX \ | +| --part N \ | +| --label KISS \ | +| --loader /vmlinuz \ | +| --unicode 'root=/dev/sdYM' \ | +| --verbose | +| | ++------------------------------------------------------------------------------+ + +The root partition can also be referred to by its partition UUID which can be +found using blkid. + ++------------------------------------------------------------------------------+ +| | +| --unicode 'root=PARTUUID=aaaaaaaa-aaaa-4aaa-aaa-aaaaaaaaaaaa' | +| | ++------------------------------------------------------------------------------+ + +The above command, the --unicode option specifies the parameters passed to the +kernel. If you require other parameters to boot your system, pass them here. + + +Removing a UEFI boot entry +________________________________________________________________________________ + +To remove an entry, find your entry's boot number using 'efibootmgr --verbose' +and run the following command. + ++------------------------------------------------------------------------------+ +| | +| $ efibootmgr --bootnum XXXX --delete-bootnum | +| | ++------------------------------------------------------------------------------+ + + +References +________________________________________________________________________________ + +[0] https://www.kernel.org/doc/Documentation/efi-stub.txt diff --git a/wiki/boot/efivarfs/index.txt b/wiki/boot/efivarfs/index.txt @@ -0,0 +1,27 @@ +EFIVARFS [0] +________________________________________________________________________________ + +To use efibootmgr and other software to manipulate the UEFI boot entries, the +efivars filesystem must be mounted. This isn't handled automatically by KISS due +to the security implications in doing so. [1] + ++------------------------------------------------------------------------------+ +| Mount efivars. | ++------------------------------------------------------------------------------+ +| | +| $ mount -t efivarfs none /sys/firmware/efi/efivars/ | +| | ++------------------------------------------------------------------------------+ +| Unmount efivars. | ++------------------------------------------------------------------------------+ +| | +| $ umount /sys/firmware/efi/efivars/ | +| | ++------------------------------------------------------------------------------+ + + +References +________________________________________________________________________________ + +[0] https://www.kernel.org/doc/Documentation/filesystems/efivarfs.txt +[1] https://github.com/systemd/systemd/issues/2402 diff --git a/wiki/boot/index.txt b/wiki/boot/index.txt @@ -0,0 +1,5 @@ +BOOT +________________________________________________________________________________ + +- @/efistub +- @/efivarfs diff --git a/wiki/console/bkeymaps/index.txt b/wiki/console/bkeymaps/index.txt @@ -0,0 +1,46 @@ +BKEYMAPS [0] +________________________________________________________________________________ + +Binary keymaps to set the keyboard layout. + + +Install keymaps +________________________________________________________________________________ + + +Begin by verifying that you have bkeymaps installed from the Community +repository. + ++------------------------------------------------------------------------------+ +| | +| $ kiss b bkeymaps && kiss i bkeymaps | +| | ++------------------------------------------------------------------------------+ + +Available keymaps are in /usr/share/bkeymaps. + + +Load Keymaps at login +________________________________________________________________________________ + +To load a keymap at login, add the following command to your .profile. + ++------------------------------------------------------------------------------+ +| Load keymap using busybox's loadkmap. | ++------------------------------------------------------------------------------+ +| | +| $ loadkmap < file | +| | ++------------------------------------------------------------------------------+ +| Load keymap using kbd's loadkeys. | ++------------------------------------------------------------------------------+ +| | +| $ loadkeys file | +| | ++------------------------------------------------------------------------------+ + + +References +________________________________________________________________________________ + +[0] https://dev.alpinelinux.org/bkeymaps/ diff --git a/wiki/console/fonts/index.txt b/wiki/console/fonts/index.txt @@ -0,0 +1,39 @@ +CHANGING THE CONSOLE FONT +________________________________________________________________________________ + +The Linux console font can be changed using the setfont utility (part of busybox +and installed by default). + + +Available Fonts +________________________________________________________________________________ + +Currently packaged Linux console fonts. + +- terminus-font (Community). +- spleen-font (Community). +- unifont (Community). + + +Changing the Console Font +________________________________________________________________________________ + +Use the following command to set the console font _after_ a user has logged in. +Add it to your ~/.profile or /etc/profile to make the change permanent. + ++------------------------------------------------------------------------------+ +| | +| [ "$DISPLAY" ] || setfont /usr/share/consolefonts/FONT_NAME | +| | ++------------------------------------------------------------------------------+ + +To change the console font _before_ a user has logged in, add the following to +your /etc/inittab or /etc/rc.conf. + ++------------------------------------------------------------------------------+ +| /etc/rc.conf | ++------------------------------------------------------------------------------+ +| | +| /usr/bin/setfont /usr/share/consolefonts/FONT_NAME -C /dev/tty1 | +| | ++------------------------------------------------------------------------------+ diff --git a/wiki/console/index.txt b/wiki/console/index.txt @@ -0,0 +1,5 @@ +CONSOLE +________________________________________________________________________________ + +- @/bkeymaps +- @/console-font diff --git a/wiki/desktops/index.txt b/wiki/desktops/index.txt @@ -0,0 +1,4 @@ +DESKTOPS +________________________________________________________________________________ + +- @/kde diff --git a/wiki/desktops/kde/index.txt b/wiki/desktops/kde/index.txt @@ -0,0 +1,737 @@ +KDE +________________________________________________________________________________ + +KDE [0] is desktop environment which consists of the Plasma Desktop, the KDE +Frameworks, and a collection of free and open source, cross-platform programs. +The project makes integral use of the Qt framework [1] to help provide a +uniform experience for users between all of the software a user will install. + +$/dilyn-corner/KISS-kde is still considered to be under heavy development. While +the desktop environment works quite well, many things have yet to be tested. If +you run into bugs, problems, or have suggestions, submit issues or pull requests +on the GitHub page! + +NOTE: due to the KISS Guidestones [2], the $/dilyn-corner/KISS-kde project is +entirely community maintained. It will always remain separate from the core KISS +project, including the community repository. Specifically, KDE violates the +software inclusion guidestone. The required violations are dbus and wayland. +However, logind, polkit, and PAM are optional to build and use KDE. + + +Index +________________________________________________________________________________ + +- Getting Started [0.0] + - Authentication [0.1] + - Session Management [0.2] + - Default Window Manager [0.3] + +- From Scratch [1.0] + - Prerequisites [1.1] + - Installing [1.2] + - Launching [1.3] + +- The KISS-kde tarball [2.0] + +- Starting KDE [3.0] + - Console [3.1] + - Login Manager [3.2] + +- Post-Install [4.0] + - Window Managers [4.1] + - Greeters [4.2] + - Extras [4.3] + +- Troubleshooting [5.0] + - My fonts don't work! [5.1] + - I can't login from a screen lock! [5.2] + - I can't change the system time! [5.3] + - XYZ package fails to build! [5.4] + +- How You Can Help [6.0] +- References [7.0] + + +[0.0] Getting Started +________________________________________________________________________________ + +To begin using the K Desktop Environment there are two choices. The first option +is to use a prebuilt tarball similar to the KISS release tarballs and install it +analogously to how one installs KISS. The second is to build every package from +source from an existing KISS installation. Beyond this, one need only clone two +git repositories, install dbus, and choose whether to use libudev-zero or eudev. + +There are several optional features that users have a choice on. These choices +include authentication backends, login managers, and window managers. These +choices can be changed at any time, and will simply require rebuilding certain +packages. The following subsections offer an explanation of what these choices +are and how best to handle their consequences. + +The first thing to do is clone the repositories and add them to your $KISS_PATH. +Assuming that you keep these repositories in $HOME, + ++------------------------------------------------------------------------------+ +| | +| $ git clone https://github.com/kiss-community/community | +| $ git clone https://github.com/dilyn-corner/KISS-kde | +| | +| $ export KISS_PATH="$HOME/KISS-kde/extra:$KISS_PATH" | +| $ export KISS_PATH="$HOME/KISS-kde/plasma:$KISS_PATH" | +| $ export KISS_PATH="$HOME/KISS-kde/frameworks:$KISS_PATH" | +| $ export KISS_PATH="$KISS_PATH:$HOME/community/community" | +| | +| # you can optionally include the kde path for sddm, dolphin, etc. | +| $ export KISS_PATH="$KISS_PATH:$HOME/KISS-kde/kde" | +| | ++------------------------------------------------------------------------------+ + + + [0.1] Authentication + ____________________________________________________________________________ + + KDE utilizes polkit and PAM for authentication. They provide a robust + backend and sets of features which allow for more fine-grained control of + which users can perform what actions. However, there are no strict + requirements to use them. For instance, kauth (the framework responsible for + providing access to the polkit backend) only optionally requires polkit. + Additionally, kscreenlocker (the program responsible for locking the screen) + only requires PAM in instances where the login manager has failed to + properly track user sessions and will not allow the user to login. + + In the case of single-seat or single-user machines, complicated + authentication frameworks might be seen as a needless additional form of + security. If users decide they do not wish to make use of these features, + they are not required to do anything. + + In cases where users would prefer to have fine-grained controls over access, + the only prerequisite is to install a user permissions backend and polkit + prior to building the rest of KDE. The permission systems allowed are + linux-pam or shadow. If users intend on installing a login manager (such as + elogind), PAM should be chosen. Otherwise, shadow is an excellent option + (and is available in community). + + If a user wishes to go this route, simply build and install linux-pam or + shadow, and then install polkit: + + +--------------------------------------------------------------------------+ + | | + | $ kiss b linux-pam && kiss i linux-pam | + | $ kiss b polkit && kiss i polkit | + | $ kiss b polkit-qt-1 && kiss i polkit-qt-1 | + | | + +--------------------------------------------------------------------------+ + + If users change their mind after setting up KDE, reverting is as simple as + rebuilding the relevant packages. For instance, if a user decided to build + polkit and linux-pam and wishes to drop the stack entirely, + + +--------------------------------------------------------------------------+ + | | + | # Uninstall linux-pam and polkit | + | $ KISS_FORCE=1 kiss r linux-pam polkit polkit-qt-1 | + | | + | # Rebuild kauth, kscreenlocker | + | $ kiss b kauth kscreenlocker | + | $ kiss i kauth kscreenlocker | + | | + +--------------------------------------------------------------------------+ + + Known issues with lacking proper authentication backends includes the + inability to use systemsettings to alter things like the time. + + NOTE: currently there seems to be an issue with authentication in general; + kscreenlocker does not allow users to log back in, and users cannot change + the date or time. Without linux-pam installed, the former issue is resolved. + + + [0.2] Session Management + ____________________________________________________________________________ + + Currently, users can either start plasma sessions via TTY or from a greeter. + Login managers provide a way by which certain other programs can track + sessions, and provide a measure of security for the system. For instance, + networkmanager optionally requires logind for ensuring internet features + return after the system wakes up from sleep, and sddm allows restrictions + on which UIDs can login to a system. + + For users who have limited interest in managing their sessions via logind, + no action is required. + + For users who wish to have session-tracking features or would like to + utilize programs like sddm, elogind is required (other options are + currently being explored). elogind requires PAM. As a result, users choosing + to use elogind should do the following: + + +--------------------------------------------------------------------------+ + | | + | # Uninstall shadow if it is installed | + | $ KISS_FORCE=1 kiss r shadow | + | | + | # Install linux-pam | + | $ kiss b linux-pam && kiss i linux-pam | + | | + | # Rebuild polkit | + | $ kiss b polkit polkit-qt-1 && kiss i polkit polkit-qt-1 | + | | + | # Install elogind | + | $ kiss b elogind && kiss i elogind | + | | + | # Because of the way we build polkit, rebuild it | + | $ kiss b polkit && kiss i polkit | + | | + +--------------------------------------------------------------------------+ + + See [4.2] on configuration options for sddm. + + NOTE: to take advantage of the authentication backend, users should + reinstall kauth and kscreenlocker. + + + [0.3] Default Window Manager + ____________________________________________________________________________ + + Currently there are two primary window managers that can be chosen: kwin and + kwinft. kwinft [3] is a composited window manager for X11 and Wayland + systems. Most of the differences between kwinft and kwin are in the + underlying code; kwinft is designed to have better coding practices and be + well-organized. However, any features that appear in kwinft can be expected + to eventually show up in kwin. So if you prefer a more bleeding edge, + potentially better window manager for KDE, kwinft is an option. + + By default, kwin will be installed. If you wish to change this, fork + plasma-{workspace,desktop} and alter the depends files. All you are required + to do is uncomment the kwinft lines in the dependencies lists and comment + out kwin. For more information on forking packages, see [4]. In order to + change which is used on an existing installation, + + +--------------------------------------------------------------------------+ + | | + | $ pkill X | + | | + | $ KISS_FORCE=1 kiss r kwin kwayland-server | + | | + | $ kiss b kwinft && kiss i kwinft | + | | + | $ kiss b plasma-workspace && kiss i plasma-workspace | + | $ kiss b plasma-desktop && kiss i plasma-desktop | + | | + | $ startx | + | | + +--------------------------------------------------------------------------+ + + +[1.0] From Scratch +________________________________________________________________________________ + +Building KDE is a very straightforward process. In fact, if users already have a +working xorg setup, then it is as simple as building a single package - the +package manager will take care of the rest. + +The package to install when going this route is plasma-desktop. This package +will pull in the required packages to have a fully working desktop environment, +and will additionally include a system settings manager, a default theme +(breeze), and some default icons (breeze-icons). There are some extra packages +which can be installed for more features, such as bluedevil, drkonqi, and +powerdevil. See [4.0] for more information. + + + [1.1] Prerequisites + ____________________________________________________________________________ + + Ensure that you have the proper required packages installed: libudev-zero, + dbus, and xorg-server. libudev-zero has been tested to work with KDE. + Optionally, eudev also works. The choice is up to you! Currently, + dbus-alternatives (like a stub library) are untested. The dependencies of + the KDE packages assume many Xorg libraries are already installed. Not + having xorg-server might result in missing dependencies. + + These are the only requirements for building plasma-desktop. + + NOTE: in order to build certain extras, coreutils is required. Specifically: + elogind, libblockdev, and udisks2 require three separate programs. Patches + are welcome to resolve this! coreutils provides files which conflict with + other KISS packages, such as busybox. To ensure we are using the correct + programs when we attempt to build these extras, we use the alternatives + system! For more information on this system, see [5]. This is not required + if you do not care about elogind. + + +-------------+------------------------------------------------------------+ + | Package | Requirement | + |-------------+------------------------------------------------------------| + | | | + | elogind | /usr/bin/realpath --relative-to | + | udisks2 | /usr/bin/ln -r | + | libblockdev | /usr/bin/mktemp --tmpdir | + | | | + +-------------+------------------------------------------------------------+ + + NOTE: additionally, if desired, you must enable cgroup support in your + kernel for elogind. see [6] for more details. + + Ensure the relevant prerequisites are installed: + + +--------------------------------------------------------------------------+ + | | + | $ kiss b libudev-zero dbus | + | $ kiss i libudev-zero dbus | + | $ kiss b xorg-server libinput xf86-input-libinput | + | $ kiss i xorg-server libinput xf86-input-libinput | + | | + | # If you opt to install e.g. elogind | + | $ kiss b coreutils && kiss i coreutils | + | $ kiss a coreutils /usr/bin/realpath | + | $ kiss a coreutils /usr/bin/mktemp | + | $ kiss a coreutils /usr/bin/ln | + | | + +--------------------------------------------------------------------------+ + + NOTE: If you had packages like xorg-server installed, you might want to + rebuild them to pickup on the new device manager they can take advantage of. + If you do not currently have xorg-server installed, you will want to get it. + A pure wayland KDE is both untested and unlikely to work. + + NOTE: with the release of plasma 5.20.0, KDE is more aggressively supporting + a wayland environment. xorg support may be dropped in the future! + + Make sure you do not currently have qt5 installed. The build files have been + tweaked for this repository to make use of dbus and libudev-zero. As a + result, carrying over the community version of these packages will lead to + unknown problems. + + Because of the time required to build qt5* packages, some prebuilt tarballs + are available on the Github repository [7]. They are built in a standard + KISS tarball, with C(XX)FLAGS=-march=x86-64 -mtune=generic -Os -pipe. + + NOTE: In general, it is a security risk to install prebuilt packages. these + archives are provided as a courtesy by $/dilyn-corner. Always verify the + authenticity of packages, and the identities of packagers! + + The current release is 5.15.1, available with the 2020.10-1 release. + + +--------------------------------------------------------------------------+ + | | + | $ ver=2020.10-1 | + | $ qtver=5.15.1-1 | + | $ url=https://github.com/dilyn-corner/KISS-kde/releases/download/$ver | + | | + | $ wget $url/qt5.$qtver.tar.gz \ | + | -O qt5@$qtver.tar.gz | + | $ wget $url/qt5-declarative.$qtver.tar.gz \ | + | -O qt5-declarative@$qtver.tar.gz | + | | + | # Not a build-time requirement, but useful for e.g. falkon | + | $ wget $url/qt5-webengine.$qtver.tar.gz \ | + | -O qt5-webengine@$qtver.tar.gz | + | | + +--------------------------------------------------------------------------+ + + It is recommended to verify the checksums for these tarballs to ensure + package integrity! + + +--------------------------------------------------------------------------+ + | | + | $ wget $url/qt5.$qtver.tar.gz.sha256 | + | | + | $ sha256sum -c < qt5@$qtver.tar.gz | + | $ sha256sum -c < qt5-declarative@$qtver.tar.gz | + | $ sha256sum -c < qt5-webengine@$qtver.tar.gz | + | | + +--------------------------------------------------------------------------+ + + +--------------------------------------------------------------------------+ + | | + | $ kiss i qt5@$qtver.tar.gz | + | $ kiss i qt5-declarative@$qtver.tar.gz | + | $ kiss i qt5-webengine@$qtver.tar.gz | + | | + +--------------------------------------------------------------------------+ + + + [1.2] Installing + ____________________________________________________________________________ + + Now that all of the build requirements are taken care of, we can install + the desktop environment. Just over a hundred packages are required. + + +--------------------------------------------------------------------------+ + | | + | $ kiss b plasma-desktop && kiss i plasma-desktop | + | | + +--------------------------------------------------------------------------+ + + Optionally, enable and start the dbus service: + + +--------------------------------------------------------------------------+ + | | + | $ ln -s /etc/sv/dbus /var/service | + | $ sv up dbus | + | | + +--------------------------------------------------------------------------+ + + No services are required to be running in order to start a plasma session. + + + [1.3] Launching + ____________________________________________________________________________ + + Once plasma-desktop has been installed, launching KDE is as simple as + adding the following to whatever script you use to start X: + + +--------------------------------------------------------------------------+ + | | + | $ exec dbus-launch --exit-with-session startplasma-x11 | + | | + +--------------------------------------------------------------------------+ + + The default fonts KDE usually ships with are hack and noto-sans. The former + is available in community, and the latter is included in KISS-kde/extra. + Ensure that you have a font installed prior to launching Plasma! + + +[2.0] The KISS-kde tarball +________________________________________________________________________________ + +Similarly to KISS itself, a tarball containing a fully-functional KISS with +KDE setup is available from the GitHub repository [7]. This archive can be +chrooted into or directly unpacked to '/'. It is built from a kiss-chroot +archive with identical generic C(XX)FLAGS, and is ~330MB in size. + +NOTE: In general, it is a security risk to install prebuilt packages. This +archive is provided as a courtesy by $/dilyn-corner. Always verify the +authenticity of packages, and the identities of packagers! + +The KISS-kde archive is a fully installed version of plasma-desktop, but does +not make choices for the user. As a result, it should be installed +identically to how KISS is normally installed, using the KISS install guide. +See [8] for KISS setup instructions. + +There will be monthly releases of the KISS-kde tarball to keep up with upstream. +The format of releases will be in YYYY-MM format. + +To download e.g. the first October 2020 release, + ++------------------------------------------------------------------------------+ +| | +| $ ver=2020.10-1 | +| $ url=https://github.com/dilyn-corner/KISS-kde/releases/download/$ver | +| $ wget $url/kiss-kde-$ver.tar.xz | +| | ++------------------------------------------------------------------------------+ + +It is strongly recommended to verify the checksums to avoid problems like +using a partially downloaded archive. + ++------------------------------------------------------------------------------+ +| | +| $ wget $url/kiss-kde-$ver.tar.xz.sha256 | +| $ sha256sum -c < kiss-kde-$ver.tar.xz.sha256 | +| | ++------------------------------------------------------------------------------+ + +After setting up your disks, mount your desired root partition to '/mnt' and +to install the latest release, + ++------------------------------------------------------------------------------+ +| | +| $ tar xf kiss-kde-$ver.tar.xz -C /mnt | +| | ++------------------------------------------------------------------------------+ + +and enter the chroot environment, + ++------------------------------------------------------------------------------+ +| | +| $ /mnt/bin/kiss-chroot /mnt | +| | ++------------------------------------------------------------------------------+ + +From here, simply follow the rest of the install guide [8]. +For help with kernels, see @/kernel. For help with bootloaders, see @/boot. + +It is recommended that you change the root password; the default is "toor". + +After setting up everything, it should be as simple as: + ++------------------------------------------------------------------------------+ +| | +| $ exit | +| $ reboot | +| $ startx | +| | ++------------------------------------------------------------------------------+ + +You should now be greeted with a fresh Plasma Desktop! + + +[3.0] Starting KDE +________________________________________________________________________________ + +You have two choices on how to launch KDE. Either you can start it directly from +the console, or you can make use of a login manager. + + + [3.1] Console + ____________________________________________________________________________ + + Launching a KDE session directly from the console is very straightforward. + If you would like to use wayland instead of X, replace x11 by wayland in the + below command. + Simply add a line to your xinitrc file: + + +--------------------------------------------------------------------------+ + | | + | $ launch="exec dbus-launch --exit-with-session startplasma-x11" | + | $ echo "$launch" >> "$HOME/.xinitrc" | + | | + +--------------------------------------------------------------------------+ + + It may be useful to set a runtime directory. A wayland session requires this + be set, and an X session will default to /tmp if you do not set one. Add + this example to somewhere like .profile: + + +--------------------------------------------------------------------------+ + | | + | export XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/tmp/$(id -u)-runtime}" | + | | + | [ -d "$XDG_RUNTIME_DIR" ] || { | + | mkdir -p "$XDG_RUNTIME_DIR" | + | chmod 0700 "$XDG_RUNTIME_DIR" | + | } | + | | + +--------------------------------------------------------------------------+ + + + [3.2] Login Manager + ____________________________________________________________________________ + + The KISS-kde repository also includes sddm [9], the Simple Desktop Display + Manager, as an option for a greeter. It requires a login manager. elogind is + the default; other options are currently being tested. First, build and + install elogind + + +--------------------------------------------------------------------------+ + | | + | $ kiss b elogind && kiss i elogind | + | # So that polkit will build the correct libs to support elogind, | + | $ kiss b polkit && kiss i polkit | + | | + +--------------------------------------------------------------------------+ + + Then, install sddm + + +--------------------------------------------------------------------------+ + | | + | # sddm is in the KISS-kde/kde repo | + | $ kiss b sddm && kiss i sddm | + | | + +--------------------------------------------------------------------------+ + + NOTE: by default, it may not be possible for root to login via sddm. Best + practices would dictate that you login as an unprivileged user. + + Enable the requisite services for sddm to function properly. For KISS' + default service manager, + + +--------------------------------------------------------------------------+ + | | + | $ ln -s /etc/sv/polkitd /var/service | + | $ ln -s /etc/sv/elogind /var/service | + | $ ln -s /etc/sv/sddm /var/service | + | | + | $ sv up polkitd | + | $ sv up elogind | + | $ sv up sddm | + | | + +--------------------------------------------------------------------------+ + + If everything went well, sddm should immediately launch after you start the + sddm service. + + +[4.0] Post-Install +________________________________________________________________________________ + +Everything you do from here on is to customize your new Plasma Desktop to your +own needs! No further setup or configuration is required. However, there are a +few things available to you that you can change, if you so choose. + + + [4.1] Window Managers + ____________________________________________________________________________ + + It is possible to use your favorite window manager with KDE, and it is + shockingly simple. All that is required is to install whatever window + manager you would prefer (dwm, i3, sowm, etc.), and add the following to + your environment: + + +--------------------------------------------------------------------------+ + | | + | # replace 'sowm' with whichever wm you prefer | + | $ export KDEWM=sowm | + | | + +--------------------------------------------------------------------------+ + + A 'good place' is up to the user; for per-user choice, add it to .profile or + your xinitrc file. To use the choice system-wide, add it to /etc/profile or + /etc/X11/xinit/xinitrc. + + + [4.2] Greeters + ____________________________________________________________________________ + + sddm is a feature-rich but straightforward greeter; see [3.2] for + installation and setup instructions. sddm can be configured heavily. + Configuration is read from /etc/sddm.conf. If it does not exist, you can + generate it: + + +--------------------------------------------------------------------------+ + | | + | $ sddm --example-config >> /etc/sddm.conf | + | | + +--------------------------------------------------------------------------+ + + You can manually edit this file to allow for autologins, changing themes, + changing the user icons, or even changing the range of UIDs that can login + through sddm. + + Alternatively, configuration can be done graphically during a plasma + session. Simply install sddm-kcm and a sddm configuration section in + systemsettings should become available. + + +--------------------------------------------------------------------------+ + | | + | $ kiss b sddm-kcm && kiss i sddm-kcm | + | | + +--------------------------------------------------------------------------+ + + NOTE: other greeters are untested. If you find success with alternatives, + make a PR to add them! + + + [4.3] Extras + ____________________________________________________________________________ + + Several things are included in KISS-kde/kde. Examples include sddm, + kvantum [10] and latte-dock [11]. + + Separate from these are the KDE Applications, such as krita or dolphin. + Some useful (and working) applications include dolphin and konsole. + + Finally, there are several useful extra programs which will enhance the + standard KDE experience. + + +-------------+------------------------------------------------------------+ + | Package | Description | + |-------------+------------------------------------------------------------| + | | | + | sddm | The Simple Desktop Display Manager | + | kvantum | An svg-based theme engine for qt5 | + | latte-dock | A feature-rich dock based on the Plasma Framework | + | | | + | dolphin | The default KDE file manager | + | konsole | The default KDE terminal emulator | + | | | + | baloo | A framework for file indexing and metadata management | + | drkonqi | A useful crash handler | + | udisks2 | A disk manager | + | kgamma5 | Change the monitor's gamma | + | khotkeys | Expanded hotkey modification | + | bludevil | Bluetooth integration | + | powerdevil | Power usage settings | + | kinfocenter | Displays useful system information | + | | | + +-------------+------------------------------------------------------------+ + + +[5.0] Troubleshooting +________________________________________________________________________________ + +Here is a collection of some common issues you might encounter in buiding or +running KDE. If you encounter any other problems, please submit an issue at +$/dilyn-corner/KISS-kde. + + + [5.1] My fonts don't work! + ____________________________________________________________________________ + + If the fonts you have installed don't appear in any Qt applications, such as + konsole, but DO appear in other applications, such as st, Qt is not properly + identifying your font location. This can be confirmed by running a Qt app + from a terminal and seeing warnings about how Qt does not ship fonts, and it + could not find them in /usr/lib/fonts. Additionally, qtdiag may inform you + that the default system font is noto-sans, regardless of whether or not + noto-sans is installed. + + This issue should be resolved by merely rebuilding qt5. + + + [5.2] I can't login from a screen lock! + ____________________________________________________________________________ + + This is a known issue with kscreenlocker and KISS. The problem would + seemingly lie with PAM not properly authenticating the user. This remains + unresolved. + + If the user trying to login is root, you may have luck killing the + kscreenlocker_greet process. + + The short term fix is to disable screen locking during inactivity, not + require a password while unlocking, or to simply never lock the screen. + + This issue does not exist on systems which do not have linux-pam installed. + + + [5.3] I can't change the system time! + ____________________________________________________________________________ + + Administrative actions currently cannot be executed as any user in places + such as systemsettings. + + A solution to resolve this issue is currently unknown. + + + [5.4] XYZ package fails to build! + ____________________________________________________________________________ + + Please open an issue on the GitHub page! The dependencies have been + minimized as much as possible to ensure the fewest things required are + pulled in to have a working system. As a result, some things may fail to + build independently. Some dependency requirements are simple fixes. Some + examples include: + + +---------------+----------------------------------------------------------+ + | required pkg | Error | + |---------------+----------------------------------------------------------| + | | | + | pkgconf | ...pkg foo not found... | + | linux-headers | linux/bar.h not found | + | | | + +---------------+----------------------------------------------------------+ + + +[6.0] How You Can Help +________________________________________________________________________________ + +The KISS-kde project is always looking for more contributors. Whether it is +fixing build errors, submitting patches, or adding applications, every +contribution is welcome! + +For a current list of project milestones, check out the first section of the +README at $/dilyn-corner/KISS-kde. + + +[7.0] References +________________________________________________________________________________ + +[0] https://kde.org +[1] https://qt.io +[2] https://k1sslinux.org/guidestones +[3] https://gitlab.com/kwinft/kwinft +[4] https://k1sslinux.org/package-manager#3.2 +[5] https://k1sslinux.org/package-manager#5.3 +[6] http://linuxfromscratch.org/blfs/view/svn/general/elogind.html +[7] https://github.com/dilyn-corner/KISS-kde/releases +[8] https://k1sslinux.org/install +[9] https://wiki.archlinux.org/index.php/SDDM +[10] https://github.com/tsujan/Kvantum +[11] https://github.com/KDE/latte-dock diff --git a/wiki/dev/index.txt b/wiki/dev/index.txt @@ -0,0 +1,4 @@ +DEVICE MANAGERS +________________________________________________________________________________ + +- @/replacing-udev diff --git a/wiki/dev/replacing-udev/index.txt b/wiki/dev/replacing-udev/index.txt @@ -0,0 +1,116 @@ +REPLACING UDEV +________________________________________________________________________________ + +As of the 20/01/2020, it is now possible to replace eudev with libudev-zero and +the device manager of your choosing. This Wiki page will cover replacing eudev +with busybox mdev, however the steps are more or less the same for all other +device managers (smdev, vdev, ...). + + +BENEFITS +________________________________________________________________________________ + +- Use any device manager, swap between them or use none at all. +- Alternatives are simpler and lighter. +- Faster boot process. + + +PURGING EUDEV +________________________________________________________________________________ + +* Disable the udevd service + + # unlink /var/service/udevd + + +* Remove the eudev package + + The removal is forced as the packages which depend on eudev will be rebuilt. + + $ KISS_FORCE=1 kiss r eudev + + +* Generate a list of all packages which need to be rebuilt + + $ kiss-revdepends eudev + libinput/depends:eudev + xorg-server/depends:eudev + + +* Build libudev-zero + + $ kiss b libudev-zero && kiss i libudev-zero + + +* Rebuild all required packages + + NOTE: Some packages may have a mandatory dependency on eudev. You may receive + errors when attempting to rebuild them. Simply re-install eudev until + you are able to investigate further. + + NOTE: If the package manager pulls in eudev as part of the rebuild process, + the package you are trying to rebuild has a mandatory dependency on + eudev (and you cannot continue this exercise). + + $ kiss b libinput xorg-server + + +* Verify that the eudev dependence is gone + + The following command should output nothing. If it does not, the outputted + packages require a rebuild. + + $ kiss-revdepends eudev + + +CHANGING DEVICE MANAGERS +________________________________________________________________________________ + +* busybox mdev + + Simply enable the `mdev` service. + + # ln -s /etc/sv/mdev/ /var/service + + +* uevent helper (Alternate method) + + Modify your KISS hook to install the uevent helper with libudev-zero: + + +--------------------------------------------------------------------------+ + | | + | case $TYPE in | + | post-build) | + | case "$PKG" in | + | libudev-zero) | + | "${CC:-cc}" contrib/helper.c -o helper | + | install -Dm755 helper "$DEST/usr/bin/uevent-helper" | + | ;; | + | esac | + | | + +--------------------------------------------------------------------------+ + + Enable CONFIG_UEVENT_HELPER in your kernel configuration and set + CONFIG_UEVENT_HELPER_PATH to /usr/bin/uevent-helper. + + Alternatively, the uevent helper path can be set by the init system. + + # echo "/bin/echo /usr/bin/uevent-helper <dir> > /proc/sys/kernel/hotplug" + # > /etc/rc.d/uevent-helper.boot + + Replace <dir> with the path where you want the uevent files to be stored, or + leave it empty to use the default path. + + +* Other device managers + + Open an issue in $/kiss-community/init as the init scripts will need support + for other device managers. + + +REBOOT +________________________________________________________________________________ + +If all went well, you should now be using mdev as your device manager while +retaining a fully working graphical environment with hotplugging functionality. +If input doesn't work under Xorg, refer to the Xorg log file for information. diff --git a/wiki/init/busybox/index.txt b/wiki/init/busybox/index.txt @@ -0,0 +1,78 @@ +MANAGING SERVICES WITH BUSYBOX +________________________________________________________________________________ + +KISS uses busybox's init with busybox's runit utilities for services by default. + + +Basic usage +________________________________________________________________________________ + ++---------+--------------------------------------------------------------------+ +| Action | Command | +|---------+--------------------------------------------------------------------| +| List | $ ls /etc/sv/ | +| | | +| Enable | $ ln -s /etc/sv/SERVICE_NAME/ /var/service | +| Disable | $ unlink /var/service/SERVICE_NAME | +| | | +| Stop | $ sv down SERVICE_NAME | +| Start | $ sv up SERVICE_NAME | +| | | ++---------+--------------------------------------------------------------------+ + +See https://git.busybox.net/busybox/tree/runit/sv.c for full usage. + + +Running commands during boot/shutdown +________________________________________________________________________________ + +This can be accomplished in a generic way (using /etc/rc.d) or by modifying the +busybox-init only /etc/inittab file. + + + Using /etc/rc.d + ____________________________________________________________________________ + + This method of configuration works with every init system which uses the + KISS init framework. See $/kiss-community/init + + +--------------------------------------------------------------------------+ + | Run command during boot. | + +--------------------------------------------------------------------------+ + | | + | # Load the iwlwifi kernel module. | + | echo "modprobe iwlwifi" > /etc/rc.d/wifi.boot | + | | + +--------------------------------------------------------------------------+ + | Run command during shutdown. | + +--------------------------------------------------------------------------+ + | | + | # Save system time to hwclock. | + | echo "hwclock -w" > /etc/rc.d/hwclock.pre.shutdown | + | | + +--------------------------------------------------------------------------+ + | | + | TIP: .post.shutdown can also be used. | + | | + +--------------------------------------------------------------------------+ + + + Using /etc/inittab + ____________________________________________________________________________ + + +--------------------------------------------------------------------------+ + | Run command during boot. | + +--------------------------------------------------------------------------+ + | | + | # Load the iwlwifi kernel module. | + | ::once:/bin/modprobe iwlwifi | + | | + +--------------------------------------------------------------------------+ + | Run command during shutdown. | + +--------------------------------------------------------------------------+ + | | + | # Save system time to hwclock. | + | ::shutdown:/bin/hwclock -w | + | | + +--------------------------------------------------------------------------+ + diff --git a/wiki/init/changing-init/index.txt b/wiki/init/changing-init/index.txt @@ -0,0 +1,111 @@ +Changing Init Systems +________________________________________________________________________________ + +KISS' default init system and service manager are provided by busybox. The +service manager being an independent implementation of runit's utilities. This +default should work with all system configurations though one may still wish to +swap to the init system and service manager of their choosing. + +This is very easily done via the package manager's alternatives system as +nothing is tightly coupled or dependent on a specific init or service manager. + + +[0.0] Index +________________________________________________________________________________ + +- Rebooting after switching init systems [1.0] +- runit [2.0] +- Hummingbird [3.0] + - Setting up runsvdir [3.1] + + +[1.0] Rebooting after switching init systems +________________________________________________________________________________ + +After switching init systems, your running init system may not accept the +new poweroff commands. You will need to reboot/poweroff using the running init's +utilities for the new utilities to work. These commands are for the init system +currently running on your system and not the one you are switching to. + ++------------------------------------------------------------------------------+ +| Busybox | ++------------------------------------------------------------------------------+ +| | +| $ busybox reboot | +| | ++------------------------------------------------------------------------------+ +| Runit | ++------------------------------------------------------------------------------+ +| | +| $ runit-init 6 | +| | ++------------------------------------------------------------------------------+ +| sinit/shinit and Hummingbird | ++------------------------------------------------------------------------------+ +| | +| $ kill -s INT 1 | +| | ++------------------------------------------------------------------------------+ + + +[2.0] runit +________________________________________________________________________________ + +Begin by first verifying that runit is installed. + ++------------------------------------------------------------------------------+ +| | +| # Available in the Community repository. | +| $ kiss b runit && kiss i runit | +| | ++------------------------------------------------------------------------------+ + +Finally, use the alternatives system to swap to runit. + ++------------------------------------------------------------------------------+ +| | +| # See #/package-manager#3.2 for more information. | +| $ kiss a runit /usr/bin/init | +| $ kiss a runit /usr/bin/poweroff | +| $ kiss a runit /usr/bin/reboot | +| | ++------------------------------------------------------------------------------+ + + +[3.0] Hummingbird +________________________________________________________________________________ + +Make sure to install Hummingbird. + ++------------------------------------------------------------------------------+ +| | +| # Available in the Community repository. | +| $ kiss b hummingbird-git && kiss i hummingbird-git | +| | ++------------------------------------------------------------------------------+ + +Then, swap to Hummingbird by using the alternatives system. + ++------------------------------------------------------------------------------+ +| | +| $ kiss a hummingbird-git /usr/bin/init | +| $ kiss a hummingbird-git /usr/bin/reboot | +| | ++------------------------------------------------------------------------------+ + +Once you have booted using Hummingbird, take note that the command used to +turn the system off is "shutdown". + + + [3.1] Setting up runsvdir + ____________________________________________________________________________ + + Hummingbird doesn't provide a service manager, and doesn't read from + inittab either. Some people find it useful to have one, such as runsvdir. + + +--------------------------------------------------------------------------+ + | | + | $ mkdir /etc/rc.d | + | $ echo 'runsvdir -P /var/service &' > /etc/rc.d/runsvdir.boot | + | | + +--------------------------------------------------------------------------+ diff --git a/wiki/init/index.txt b/wiki/init/index.txt @@ -0,0 +1,6 @@ +INIT +________________________________________________________________________________ + +- @/busybox +- @/changing-init +- @/sysmgr diff --git a/wiki/init/sysmgr/index.txt b/wiki/init/sysmgr/index.txt @@ -0,0 +1,90 @@ +Managing services with SYSMGR +________________________________________________________________________________ + +sysmgr is an alternative service supervisor written in POSIX sh. It is similar +in usage to runit. + + +Installation +________________________________________________________________________________ + +Begin by first verifying that you have sysmgr installed. + ++------------------------------------------------------------------------------+ +| | +| # Available in the Community repository. | +| $ kiss b sysmgr && kiss i sysmgr | +| | ++------------------------------------------------------------------------------+ + + +Basic usage +________________________________________________________________________________ + +As mentioned above, the usage of sysmgr is similar to runit. + ++---------+--------------------------------------------------------------------+ +| Action | Command | ++---------+--------------------------------------------------------------------+ +| List | $ ls /etc/sysmgr/ | +| | | +| Enable | $ ln -s /etc/sysmgr/SERVICE_NAME /var/sysmgr | +| Disable | $ unlink /var/sysmgr/SERVICE_NAME | +| | | +| Stop | $ svctl stop SERVICE_NAME | +| Start | $ svctl start SERVICE_NAME | +| | | ++---------+--------------------------------------------------------------------+ + +See svctl(1) for more usage information. + + +Running sysmgr on startup +________________________________________________________________________________ + +sysmgr can be run at boot via /etc/inittab or a hook in /etc/rc.d. + ++------------------------------------------------------------------------------+ +| Enabling on inittab | ++------------------------------------------------------------------------------+ +| | +| ::respawn:/usr/bin/sysmgr | +| | ++------------------------------------------------------------------------------+ +| Enabling from /etc/rc.d/sysmgr.boot | ++------------------------------------------------------------------------------+ +| | +| while :; do /usr/bin/sysmgr; done & | +| | ++------------------------------------------------------------------------------+ + + +Switching from runit +________________________________________________________________________________ + +In order to switch from runit to sysmgr, copy the contents of the /var/service +directory to /var/sysmgr, and the same for /etc/sv to /etc/sysmgr. + ++------------------------------------------------------------------------------+ +| Create the service directory for sysmgr | ++------------------------------------------------------------------------------+ +| | +| $ mkdir -p /etc/sysmgr | +| | ++------------------------------------------------------------------------------+ +| Copy runit services | ++------------------------------------------------------------------------------+ +| | +| for service in /etc/sv/*; do | +| cp "$service/run" "/etc/sysmgr/${service##*/}" | +| done | +| | ++------------------------------------------------------------------------------+ +| Copy all enabled services | ++------------------------------------------------------------------------------+ +| | +| for service in /var/service/*; do | +| ln -sf /etc/sysmgr/${service##*/} /var/sysmgr | +| done | +| | ++------------------------------------------------------------------------------+ diff --git a/wiki/kernel/config/index.txt b/wiki/kernel/config/index.txt @@ -0,0 +1,169 @@ +KERNEL CONFIGURATION GUIDE +________________________________________________________________________________ + +Configuring the Linux kernel is arguably the hardest step in the installation +process. The kernel is humongous and figuring out what to enable in the +seemingly endless option list can be a daunting task. + +The most important factor for success is how well one knows their hardware. +Spend a little time doing some research prior to configuring the kernel. Knowing +what is inside one's system is of immense value in all contexts. + +The physical realm however, is only part of the equation. Configuration extends +to general features, file-systems, networking protocols, cryptography, security, +processor features and more. + +This Wiki page will document kernel options, their requirement level +(conditional, recommended or mandatory), a brief description and a rationale if +necessary. Information about pre-built hardware as a whole will not be covered. + + +[0.0] Index +________________________________________________________________________________ + +- Getting a config [1.0] +- Modifying a config [2.0] +- Busybox compatibility [3.0] +- Never lose your .config ever again [4.0] +- Removing the perl requirement [5.0] + + +[1.0] Getting a config +________________________________________________________________________________ + +The first step in this process is creating a .config file in the Linux source +tree. It is essentially just a text file containing KEY=value pairs (along with +comments), each of which control something in the linux build process. + +An important subset of the options control "drivers"; sections of code that give +the kernel the capability to interact with filesystems, protocols and hardware +components. These options typically have three possible values: "n" to not +compile the driver, "y" to compile it into the kernel binary and "m" to compile +the driver as a module (.ko files stored in /usr/lib/modules). Modules can be +loaded/unloaded dynamically by the kernel as needed. + +A fairly generic and compatible base configuration for your architecture can be +created by running the following command. This handles a large portion of the +work required during the configuration stage. + ++------------------------------------------------------------------------------+ +| | +| $ make defconfig | +| | ++------------------------------------------------------------------------------+ + +There are countless flows of configuring the Linux kernel, and there are fun +things to try scattered all over the internet. Good luck! + + +[2.0] Modifying a config +________________________________________________________________________________ + +There are several ways to modify an existing config file that are more +convenient than editing each of them by hand, most of them very well +documented. They arrange all of the config options in neat menus and submenus +and provide descriptions for each of them, allowing the Linux kernel to be +comprehended by mere mortals. + ++------------------------------------------------------------------------------+ +| Terminal based configuration tools (requires ncurses) | ++------------------------------------------------------------------------------+ +| | +| $ make menuconfig | +| $ make nconfig | +| | ++------------------------------------------------------------------------------+ +| Graphical configuration tools (requires a working Xorg server and QT/GTK) | ++------------------------------------------------------------------------------+ +| | +| $ make xconfig # Requires qt5. | +| $ make gconfig # Requires gtk+3. | +| | ++------------------------------------------------------------------------------+ + +Another option you may find very useful to easily trim down general (default, +distro, etc.) configuration files is: + ++------------------------------------------------------------------------------+ +| | +| $ make localyesconfig | +| | ++------------------------------------------------------------------------------+ + +This modifies the current .config to only compile whatever drivers are loaded in +the host kernel's current state. Running this after connecting all the hardware +you will be using is a pretty quick way to come up with a pretty lean +configuration. + + +[3.0] Package compatibility +________________________________________________________________________________ + +Various parts of the Linux build system use non-standard options with core +utilities, this causes a build failure when using busybox. Thankfully, this non- +standard usage depends on unimportant and rarely used kernel features. + +When these options are disabled (is the case by default unless 'allyesconfig' is +used), the kernel builds just fine. + ++------------------------------------------------------------------------------+ +| | +| The following options are mandatory (when using busybox) (=n). | +| | +| CONFIG_IKHEADERS This option enables access to the in-kernel | +| headers that are generated during the build | +| process. These can be used to build eBPF tracing, | +| or similar programs. | +| | ++------------------------------------------------------------------------------+ + +Because gmp, mpc, and mpfr are bundled with our gcc instead of being built as +standalone packages, the headers are missing. This results in build failures +when building GCC Plugins. Either install gmp & mpc separately from gcc, or +disable CONFIG_HAVE_GCC_PLUGINS in the kernel config. + ++------------------------------------------------------------------------------+ +| | +| The following options are mandatory (when using busybox) (=n). | +| | +| CONFIG_HAVE_GCC_PLUGINS This option enables loadable modules that provide | +| plugins for GCC which are useful for runtime | +| instrumentation and static analysis. | +| | ++------------------------------------------------------------------------------+ + + +[4.0] Never lose your .config ever again +________________________________________________________________________________ + +The kernel can be configured to store its configuration file to later make it +accessible via /proc/config.gz. Storing the .config in the kernel ensures that +you will never lose your config so long as you have its kernel. + ++------------------------------------------------------------------------------+ +| | +| The following options are recommended (=y). | +| | +| CONFIG_IKCONFIG Store the .config in the kernel. | +| CONFIG_IKCONFIG_PROC Make the .config accessible as /proc/config.gz | +| | ++------------------------------------------------------------------------------+ + + +[5.0] Removing the perl requirement +________________________________________________________________________________ + +Perl is needed by the build_OID_registry script which will be executed during +the compilation process in most systems. This makes perl a mandatory dependency +to build the kernel. + +A patch can be applied which adds a POSIX shell implementation of the perl +script. This fully removes the perl requirement. + +@/patches/kernel-no-perl.patch (Written by $/E5ten) + ++------------------------------------------------------------------------------+ +| | +| TIP: All links like this one are also available via 'kiss help'! | +| | ++------------------------------------------------------------------------------+ diff --git a/wiki/kernel/firmware/index.txt b/wiki/kernel/firmware/index.txt @@ -0,0 +1,383 @@ +FIRMWARE +________________________________________________________________________________ + +Linux firmware is a package distributed alongside the Linux kernel that contains +firmware binary blobs necessary for partial or full functionality of certain +hardware devices. These binary blobs are usually proprietary because some +hardware manufacturers do not release source code necessary to build the +firmware itself. + +This Wiki page will document firmare/driver configuration for various +peripherals, their requirement level (conditional, recommended or mandatory), a +brief description and a rationale if necessary. + + +[0.0] Index +________________________________________________________________________________ + +- Overview [1.0] + - Incorporating Firmware [1.1] + - Rebuilding the Kernel [1.2] +- Processor [2.0] + - AMD Microcode [2.1] + - Intel Microcode [2.2] +- Graphics [3.0] + - NVIDIA [3.1] + - AMDGPU [3.2] +- Wireless [4.0] + - Intel (iwlwifi) [4.1] +- Bluetooth [5.0] +- Sound [6.0] +- References [7.0] + + +[1.0] Overview +________________________________________________________________________________ + +The following are considered some best practices when configuring firmware for +peripherals. + + + [1.1] Incorporating Firmware + ____________________________________________________________________________ + + When building drivers into the kernel, ensure that the firmware blobs + (*.ucode files) are referenced and the firmware root directory is set. + + Replace '****.ucode' with the firmware you would like to bake into the + kernel. Values are paths to files, separated by spaces with locations + relative to the value of CONFIG_EXTRA_FIRMWARE_DIR. + + +--------------------------------------------------------------------------+ + | ".config" Example | + +--------------------------------------------------------------------------+ + | | + | CONFIG_EXTRA_FIRMWARE_DIR="/lib/firmware" | + | CONFIG_EXTRA_FIRMWARE="****.ucode" | + | | + +--------------------------------------------------------------------------+ + + If you are using the menuconfig tool, it should look something like the + following: + + +--------------------------------------------------------------------------+ + | "menuconfig" Example | + +--------------------------------------------------------------------------+ + | | + | Device Drivers ---> | + | Generic Driver Options ---> | + | Firmware loader ---> | + | -*- Firmware loading facility | + | (****.ucode) Build named firmware blobs into the kernel binary | + | (/lib/firmware) Firmware blobs root directory | + | | + +--------------------------------------------------------------------------+ + + Note: The CONFIG_EXTRA_FIRMWARE should be a list of all of the required + firmware blobs, delimited by a single space character. + + + [1.2] Rebuilding the Kernel + ____________________________________________________________________________ + + Configuring a kernel is difficult and everyone is bound to make a few + mistakes or forget a step in the process.. fear not! The road to "recovery" + is quick and painless. + + The process after updating the .config file with the required changes would + be as follows: + + +--------------------------------------------------------------------------+ + | Rebuild the Kernel | + +--------------------------------------------------------------------------+ + | | + | $ make -j "$(nproc)" && make modules_install | + | | + +--------------------------------------------------------------------------+ + | Remount the boot partition | + +--------------------------------------------------------------------------+ + | | + | $ mount /boot | + | | + +--------------------------------------------------------------------------+ + | Install the built kernel (to /boot). (Ignore the LILO error). | + +--------------------------------------------------------------------------+ + | | + | $ make install | + | | + +--------------------------------------------------------------------------+ + | Rename the kernel/system.map (vmlinuz -> vmlinuz-VERSION). | + +--------------------------------------------------------------------------+ + | | + | $ mv /boot/vmlinuz /boot/vmlinuz-VERSION | + | $ mv /boot/System.map /boot/System.map-VERSION | + | | + +--------------------------------------------------------------------------+ + | Update the boot loader (assuming using GRUB2) | + +--------------------------------------------------------------------------+ + | | + | $ grub-mkconfig -o /boot/grub/grub.cfg | + | | + +--------------------------------------------------------------------------+ + | Reboot for the new kernel configuration to take effect: | + +--------------------------------------------------------------------------+ + | | + | $ reboot | + | | + +--------------------------------------------------------------------------+ + + +[2.0] Processor +________________________________________________________________________________ + +The following sections describe the kernel requirements for microcode loading +for various manufacturers. + + + [2.1] AMD Microcode + ____________________________________________________________________________ + + Microcode updates for AMD processors are provided by linux-firmware + package. AMD specific microcode is located in the amd-ucode/ and amd/ + folders. [1] + + In order determine which microcode firmware blob is required, you can use + grep to search for the "cpu family" value in /proc/cpuinfo: + + +--------------------------------------------------------------------------+ + | | + | $ grep -F -m 1 "cpu family" /proc/cpuinfo | + | | + +--------------------------------------------------------------------------+ + + Use the output from the command above to determine which firmware blob file + is required below: + + +---------------------------------+---------+------------------------------+ + | File(s) | Dec. | CPU Family Name | + +---------------------------------+---------+------------------------------+ + | | | | + | microcode_amd.bin | 16 | K10 | + | | 17 | Turion | + | | 18 | Llano, Fusion | + | | 20 | Bobcat | + | | | | + | microcode_amd_fam15h.bin | 21 | Bulldozer, Piledriver, | + | | | Steamroller, Excavato | + | | | | + | microcode_amd_fam16h.bin | 22 | Jaguar, Puma | + | | | | + | microcode_amd_fam17h.bin | 23 | Zen | + | amd_sev_fam17h_model0xh.sbin | | | + | | | | + +---------------------------------+---------+------------------------------+ + + Remember to reference the firmware blobs in CONFIG_EXTRA_FIRMWARE. [1.1] + + + [2.2] Intel Microcode + ____________________________________________________________________________ + + Microcode updates for Intel processors are provided by the + "Intel-Linux-Processor-Microcode-Data-Files" package [2] and located in the + intel-ucode/ folder. + + In order determine which microcode firmware blob is required, you can use + grep to search for "cpu family", "model" and "stepping" values in + /proc/cpuinfo [3]: + + +--------------------------------------------------------------------------+ + | | + | $ grep -F -m 1 "cpu family" /proc/cpuinfo | + | $ grep -F -m 1 "model" /proc/cpuinfo | + | $ grep -F -m 1 "stepping" /proc/cpuinfo | + | | + +--------------------------------------------------------------------------+ + + Use the outputed values (converted to Hex) from the commands above to + determine which firmware blob file is required by using the following naming + convention: + + +--------------------------------------------------------------------------+ + | | + | [cpu_family]-[model]-[stepping] | + | | + +--------------------------------------------------------------------------+ + + Note: If converting to Hex isn't your think, user $/illiliti has provided an + example POSIX compliant shell script that can do this for you + "automagically": + + +--------------------------------------------------------------------+ + | | + | #!/bin/sh -f | + | while IFS=: read -r key val; do | + | case $key in | + | stepping*) : ${stepping:=$val} ;; | + | cpu*family*) : ${family:=$val} ;; | + | model*) : ${model:=$val} ;; | + | esac | + | done < /proc/cpuinfo | + | printf "%02x-%02x-%02x\n" "$family" "$model" "$stepping" | + | | + +--------------------------------------------------------------------+ + + Remember to reference the firmware blobs in CONFIG_EXTRA_FIRMWARE. [1.1] + + +[3.0] Graphics +________________________________________________________________________________ + +The following sections describe the kernel requirements for graphics cards from +various manufacturers. + + + [3.1] NVIDIA + ____________________________________________________________________________ + + (this is a placeholder) + + + [3.2] AMDGPU + ____________________________________________________________________________ + + Setting up a system to use AMDGPU requires identifying the proper card, + installing the corresponding firmware, configuring the kernel, and + installing the X11 driver. + + Begin by identifying the family and chipset of your AMDGPU: + + +--------------+-------------------------+---------------------------------+ + | Family | Chipset | Product Name | + +--------------+-------------------------+---------------------------------+ + | | | | + | Southern | CAPE VERDE, | HD7750-HD7970, R9 270, | + | Island | PITCAIRN, TAHITI, | R9 280, R9 370X, R7 240, | + | | OLAND, HAINAN | R7 250 | + | | | | + | Sea | BONAIRE, KABINI, | HD7790, R7 260, R9 290, | + | Island | KAVERI, HAWAII, | R7 360, R9 390 | + | | MULLINS | | + | | | | + | Volcanic | CARRIZO, FIJI, | R9 285, R9 380, R9 380X, | + | Island | STONEY, TONGA, | R9 Fury, R9 Nano, | + | | TOPAZ, WANI | R9 Fury X, Pro Duo | + | | | | + | Arctic | POLARIS10/11/12 | RX 460, RX 470, RX 480, | + | Island | | RX 540, RX 550, RX 560, | + | | | RX 570, RX 580, RX 590 | + | | | | + | Vega | VEGA10/11/12/20, | RX Vega 56, RX Vega 64, | + | | RAVEN | Raven Ridge APU series5, | + | | | Radeon Vega II, Radeon VII | + | | | | + | Navi | NAVI10 | RX 5500, RX 5500 XT, | + | | | RX 5600, RX 5600 XT, | + | | | RX 5700, RX 5700 XT | + | | | | + +--------------+-------------------------+---------------------------------+ + + For more information on each chipset, refer to the Gentoo AMDGPU Wiki [0]. + + The kernel can now be configured based on the information obtained above: + + +--------------------------------------------------------------------------+ + | | + | The following options are required (=y). | + | | + | CONFIG_MTRR Memory Type Range Register Support | + | CONFIG_DRM_FBDEV_EMULATION Direct Rendering Manager | + | CONFIG_DRM_AMDGPU | + | CONFIG_DRM_AMDGPU_SI Support for SI parts | + | CONFIG_DRM_AMDGPU_CIK Support for CIK parts | + | (only for Sea Islands GPUs with the amdgpu | + | driver) | + | CONFIG_DRM_AMD_ACP AMD Audio CoProcessor IP support | + | (only needed for APUs) | + | CONFIG_DRM_AMD_DC AMD DC - Enable new display engine | + | CONFIG_DRM_AMD_DC_DCN DCN 1.0 Raven family | + | (only Vega RX as part of Raven Ridge APUs) | + | CONFIG_HSA_AMD HSA kernel driver for AMD GPU devices | + | CONFIG_DRM_PANEL | + | | + +--------------------------------------------------------------------------+ + + Note: When using AMDGPU, it is recommended to unset the ATI Radeon option so + that the radeon module is not built. [0] + + Remember to reference the firmware blobs, per Section [1.1]. The correct + AMDGPU firmware blobs can be found in the amdgpu/ folder of the + linux-firmware package. For example, if I was using a GPU with the TONGA + chipset, I would want to reference all amdgpu/tonga_* files. + + +[4.0] Wireless Devices +________________________________________________________________________________ + +The following sections describe the kernel requirements for wireless devices +from various manufacturers. + + + [4.1] Intel (iwlwifi) + ____________________________________________________________________________ + + Determine which module your wireless device uses (iwldvm or iwlmvm), along + with which firmware (iwlwifi-****.ucode) your device requires. + + * https://wireless.wiki.kernel.org/en/users/drivers/iwlwifi + + Once determined, ensure that the following kernel requirements are met: + + +--------------------------------------------------------------------------+ + | | + | The following options are required (=y). | + | | + | WLAN_VENDOR_INTEL Store the .config in the kernel. | + | MAC80211 Enables hardware independent IEEE 802.11 | + | CFG80211 Enables the Linux Wireless LAN config API | + | IWLWIFI Enables the IWLWIFI driver. | + | | + | One of the following options is required (=y) | + | | + | IWLMVM Driver that supports MVM firmware | + | IWLDVM Driver that supports DVM firmware | + | | + +--------------------------------------------------------------------------+ + + Remember to reference the firmware blobs in CONFIG_EXTRA_FIRMWARE. [1.1] + + +[5.0] Bluetooth +________________________________________________________________________________ + +(this is a placeholder) + + +[6.0] Sound +________________________________________________________________________________ + +The options from the Sound card support menu need only to be set if the card +supports HDMI or DisplayPort audio and you want to use it. On newer kernels +where Enable AMD Audio CoProcessor IP support appears, that should also be set. + ++-----------------------------------------------------------------------------+ +| | +| The following options are required for soundcard support (=y). | +| | +| CONFIG_SND_PCI CI sound devices | +| CONFIG_SND_HDA_INTEL HD Audio PCI | +| CONFIG_SND_HDA_PATCH_LOADER Patch loading for HD-audio | +| CONFIG_SND_HDA_CODEC_HDMI HDMI/DisplayPort HD-audio codec support | +| | +| (Remember to also specify whatever codec your soundcard needs.) | +| | ++-----------------------------------------------------------------------------+ + + +[7.0] References +________________________________________________________________________________ + +[0] https://wiki.gentoo.org/wiki/AMDGPU +[1] https://wiki.gentoo.org/wiki/AMD_microcode +[2] https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files +[3] https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files/issues/16 diff --git a/wiki/kernel/index.txt b/wiki/kernel/index.txt @@ -0,0 +1,6 @@ +KERNEL +________________________________________________________________________________ + +- @/config +- @/firmware +- @/thinkpad diff --git a/wiki/kernel/patches/kernel-no-perl.patch b/wiki/kernel/patches/kernel-no-perl.patch @@ -0,0 +1,292 @@ +--- a/lib/Makefile ++++ b/lib/Makefile +@@ -271,7 +271,7 @@ + $(call cmd,build_OID_registry) + + quiet_cmd_build_OID_registry = GEN $@ +- cmd_build_OID_registry = perl $(srctree)/$(src)/build_OID_registry $< $@ ++ cmd_build_OID_registry = $(CONFIG_SHELL) $(srctree)/$(src)/build_OID_registry <$< >$@ + + clean-files += oid_registry_data.c + +--- a/lib/build_OID_registry ++++ b/lib/build_OID_registry +@@ -1,4 +1,4 @@ +-#!/usr/bin/perl -w ++#!/bin/sh + # SPDX-License-Identifier: GPL-2.0-or-later + # + # Build a static ASN.1 Object Identified (OID) registry +@@ -7,197 +7,93 @@ + # Written by David Howells (dhowells@redhat.com) + # + +-use strict; +- +-my @names = (); +-my @oids = (); +- +-if ($#ARGV != 1) { +- print STDERR "Format: ", $0, " <in-h-file> <out-c-file>\n"; +- exit(2); +-} +- + # +-# Open the file to read from ++# Read OID lines and determine the lengths of the encoded data arrays. + # +-open IN_FILE, "<$ARGV[0]" || die; +-while (<IN_FILE>) { +- chomp; +- if (m!\s+OID_([a-zA-z][a-zA-Z0-9_]+),\s+/[*]\s+([012][.0-9]*)\s+[*]/!) { +- push @names, $1; +- push @oids, $2; +- } +-} +-close IN_FILE || die; ++set -f -- # use "$@" array for data ++total_length=0 IFS='.' ++while IFS=' ' read -r line; do ++ if [ "${line#OID_[a-z]}" != "$line" ]; then ++ name="${line#*_}" name="${name%,*}" oid="${line#*/* }" oid="${oid% */}" ++ # shellcheck disable=SC2086 ++ size="$(set -- $oid; printf '%u' "$(($# - 1))")" ++ for c in $oid; do ++ # We will base128 encode the number ++ : "$((size += c ? $(awk "BEGIN{print int(log($c)/log(2)/7)}") : 0))" ++ done ++ set -- "$@" "$name:$oid:$total_length" ++ : "$((total_length += size))" ++ fi ++done + + # +-# Open the files to write into +-# +-open C_FILE, ">$ARGV[1]" or die; +-print C_FILE "/*\n"; +-print C_FILE " * Automatically generated by ", $0, ". Do not edit\n"; +-print C_FILE " */\n"; +- +-# +-# Split the data up into separate lists and also determine the lengths of the +-# encoded data arrays. +-# +-my @indices = (); +-my @lengths = (); +-my $total_length = 0; +- +-for (my $i = 0; $i <= $#names; $i++) { +- my $name = $names[$i]; +- my $oid = $oids[$i]; +- +- my @components = split(/[.]/, $oid); +- +- # Determine the encoded length of this OID +- my $size = $#components; +- for (my $loop = 2; $loop <= $#components; $loop++) { +- my $c = $components[$loop]; +- +- # We will base128 encode the number +- my $tmp = ($c == 0) ? 0 : int(log($c)/log(2)); +- $tmp = int($tmp / 7); +- $size += $tmp; +- } +- push @lengths, $size; +- push @indices, $total_length; +- $total_length += $size; +-} +- +-# + # Emit the look-up-by-OID index table + # +-print C_FILE "\n"; +-if ($total_length <= 255) { +- print C_FILE "static const unsigned char oid_index[OID__NR + 1] = {\n"; +-} else { +- print C_FILE "static const unsigned short oid_index[OID__NR + 1] = {\n"; +-} +-for (my $i = 0; $i <= $#names; $i++) { +- print C_FILE "\t[OID_", $names[$i], "] = ", $indices[$i], ",\n" +-} +-print C_FILE "\t[OID__NR] = ", $total_length, "\n"; +-print C_FILE "};\n"; ++printf '/*\n * Automatically generated by %s. Do not edit\n */\n\n' "$0" ++if [ "$total_length" -le 255 ]; then ++ printf 'static const unsigned char oid_index[OID__NR + 1] = {\n' ++else ++ printf 'static const unsigned short oid_index[OID__NR + 1] = {\n' ++fi ++for i do ++ printf '\t[OID_%s] = %u,\n' "${i%%:*}" "${i##*:}" ++done ++printf '\t[OID__NR] = %u\n};\n\n' "$total_length" + + # +-# Encode the OIDs ++# Encode the OIDs and emit the OID data + # +-my @encoded_oids = (); ++printf 'static const unsigned char oid_data[%u] = {\n' "$total_length" ++for i do ++ IFS='.' j=0 i="${i%:*}" ++ for c in ${i##*:}; do ++ case "$((j += 1))" in ++ 1) o="$((c * 40))";; ++ 2) : "$((o += c))";; ++ *) ++ # Base128 encode the number ++ tmp="$((c ? $(awk "BEGIN{print int(log($c)/log(2)/7)+1}") : 1))" ++ while [ "$((tmp -= 1))" -gt 0 ]; do ++ o="$o.$((c >> tmp * 7 & 127 | 128))" ++ done ++ o="$o.$((c & 127))" ++ esac ++ done + +-for (my $i = 0; $i <= $#names; $i++) { +- my @octets = (); ++ set -- "$@" "${i%:*}:$o" ++ shift + +- my @components = split(/[.]/, $oids[$i]); ++ printf '\t' ++ printf '%s, ' $o ++ printf '\t// %s\n' "${i%:*}" ++done ++printf '};\n\n' + +- push @octets, $components[0] * 40 + $components[1]; ++printf 'static const struct {\n\tunsigned char hash;\n' ++printf '\tenum OID oid : %u;\n} oid_search_table[OID__NR] = {' \ ++ "$(($# <= 255 ? 8 : 16))" + +- for (my $loop = 2; $loop <= $#components; $loop++) { +- my $c = $components[$loop]; +- +- # Base128 encode the number +- my $tmp = ($c == 0) ? 0 : int(log($c)/log(2)); +- $tmp = int($tmp / 7); +- +- for (; $tmp > 0; $tmp--) { +- push @octets, (($c >> $tmp * 7) & 0x7f) | 0x80; +- } +- push @octets, $c & 0x7f; +- } +- +- push @encoded_oids, \@octets; +-} +- + # +-# Create a hash value for each OID ++# Create a hash value for each OID and build and emit the search index and hash ++# value table (ordered by length then hash then content) + # +-my @hash_values = (); +-for (my $i = 0; $i <= $#names; $i++) { +- my @octets = @{$encoded_oids[$i]}; +- +- my $hash = $#octets; +- foreach (@octets) { +- $hash += $_ * 33; +- } +- +- $hash = ($hash >> 24) ^ ($hash >> 16) ^ ($hash >> 8) ^ ($hash); +- +- push @hash_values, $hash & 0xff; +-} +- +-# +-# Emit the OID data +-# +-print C_FILE "\n"; +-print C_FILE "static const unsigned char oid_data[", $total_length, "] = {\n"; +-for (my $i = 0; $i <= $#names; $i++) { +- my @octets = @{$encoded_oids[$i]}; +- print C_FILE "\t"; +- print C_FILE $_, ", " foreach (@octets); +- print C_FILE "\t// ", $names[$i]; +- print C_FILE "\n"; +-} +-print C_FILE "};\n"; +- +-# +-# Build the search index table (ordered by length then hash then content) +-# +-my @index_table = ( 0 .. $#names ); +- +-@index_table = sort { +- my @octets_a = @{$encoded_oids[$a]}; +- my @octets_b = @{$encoded_oids[$b]}; +- +- return $hash_values[$a] <=> $hash_values[$b] +- if ($hash_values[$a] != $hash_values[$b]); +- return $#octets_a <=> $#octets_b +- if ($#octets_a != $#octets_b); +- for (my $i = $#octets_a; $i >= 0; $i--) { +- return $octets_a[$i] <=> $octets_b[$i] +- if ($octets_a[$i] != $octets_b[$i]); +- } +- return 0; +- +-} @index_table; +- +-# +-# Emit the search index and hash value table +-# +-print C_FILE "\n"; +-print C_FILE "static const struct {\n"; +-print C_FILE "\tunsigned char hash;\n"; +-if ($#names <= 255) { +- print C_FILE "\tenum OID oid : 8;\n"; +-} else { +- print C_FILE "\tenum OID oid : 16;\n"; +-} +-print C_FILE "} oid_search_table[OID__NR] = {\n"; +-for (my $i = 0; $i <= $#names; $i++) { +- my @octets = @{$encoded_oids[$index_table[$i]]}; +- printf(C_FILE "\t[%3u] = { %3u, OID_%-35s }, // ", +- $i, +- $hash_values[$index_table[$i]], +- $names[$index_table[$i]]); +- printf C_FILE "%02x", $_ foreach (@octets); +- print C_FILE "\n"; +-} +-print C_FILE "};\n"; +- +-# +-# Emit the OID debugging name table +-# +-#print C_FILE "\n"; +-#print C_FILE "const char *const oid_name_table[OID__NR + 1] = {\n"; +-# +-#for (my $i = 0; $i <= $#names; $i++) { +-# print C_FILE "\t\"", $names[$i], "\",\n" +-#} +-#print C_FILE "\t\"Unknown-OID\"\n"; +-#print C_FILE "};\n"; +- +-# +-# Polish off +-# +-close C_FILE or die; ++i=-1 ++for j do ++ IFS='.' ++ # shellcheck disable=SC2086 ++ count="$(set -- ${j##*:}; printf '%u' "$(($# - 1))")" ++ hash="$count" ++ set -- # use as array for reversing octet set ++ for k in ${j##*:}; do ++ : "$((hash += k * 33))" ++ set -- "$k" "$@" ++ done ++ hash="$((hash >> 24 ^ hash >> 16 ^ hash >> 8 ^ hash & 255))" ++ IFS=':' ++ printf '%u:%s:%s:%u:%s\n' "$hash" "${j##*:}" "${j%%:*}" "$count" "$*" ++done | sort -nt: -k1,1 -k4,4 -k5 | while IFS=':' read -r num octets name _; do ++ printf '\n\t[%3u] = { %3u, OID_%-35s }, // ' "$((i += 1))" "$num" "$name" ++ # shellcheck disable=SC2086 ++ printf '%02x' $octets ++done ++printf '\n};\n' diff --git a/wiki/kernel/thinkpad/index.txt b/wiki/kernel/thinkpad/index.txt @@ -0,0 +1,31 @@ +Kernel configuration for IBM ThinkPad +________________________________________________________________________________ + + +X230 +________________________________________________________________________________ + +A defconfig is sufficent for the machine to boot. Sound and WIFI must be manu- +ally enabled. A firmware blob for INTEL Centrino Advanced-N 6205 is necessary. +It can be found in the root directory of the proprietary kernel firmware. Think- +Pad specific ACPI options _can_ be enabled. + ++------------------------------------------------------------------------------+ +| | +| $ make defconfig | +| $ cp iwlwifi-6000g2a-6.ucode /usr/lib/firmware | +| | ++------------------------------------------------------------------------------+ + ++------------------------------------------------------------------------------+ +| .config | ++------------------------------------------------------------------------------+ +| | +| CONFIG_IWLWIFI=y | +| CONFIG_IWLDVM=y | +| CONFIG_EXTRA_FIRMWARE="iwlwifi-6000g2a-6.ucode" | +| CONFIG_EXTRA_FIRMWARE_DIR="/usr/lib/firmware" | +| CONFIG_SND_HDA_CODEC_REALTEK=y | +| CONFIG_THINKPAD_ACPI=y | +| | ++------------------------------------------------------------------------------+ diff --git a/wiki/kiss/index.txt b/wiki/kiss/index.txt @@ -0,0 +1,4 @@ +KISS +________________________________________________________________________________ + +- @/style-guide diff --git a/wiki/kiss/style-guide/index.txt b/wiki/kiss/style-guide/index.txt @@ -0,0 +1,473 @@ +PACKAGE STYLE GUIDE +________________________________________________________________________________ + +This document is a style guide which will double as documentation for a possible +package linter in the future. Every package in the Official Repositories and the +Community repository adheres to this style guide. + +NOTE: Exceptions are made where it makes sense. + + +MAINTAINERSHIP +________________________________________________________________________________ + +* Each package has a set maintainer stored via git commits. Use 'git log' or + 'kiss-maintainer pkg' to find the maintainer's contact information. + +* Only the maintainer of a package has the ability to make changes to said + package. Any pull requests by a non-maintainer for a package will be closed. + +* If you would like to make a change to an existing package, contact the + maintainer and they will do so on your behalf. + +* If the maintainer leaves a package out of date and does not respond in a + reasonable time frame, the package will be orphaned and up for grabs. + +* If no one steps forward to adopt an orphaned package, it will be dropped from + the repositories. + + +GENERAL +________________________________________________________________________________ + + + [0000]---------------------------------------------------------------------- + + Package is not suitable for inclusion in the Community repository. The same + rules above may apply to other software at the discretion of the BDFL. + + Examples: ConsoleKit, dbus, electron, gettext, gtk2, intltool, libsn, + logind, pam, pipewire, polkit, pulseaudio, systemd, wayland and + all Desktop Environments. + + + [0001]---------------------------------------------------------------------- + + No new packages shall use Python 2 as it will be removed once Chromium drops + it as a dependency. + + + [0002]---------------------------------------------------------------------- + + Packages which are binaries should contain the suffix '-bin' to reflect + this fact. Similarly, packages which pull from git should contain the + suffix '-git'. The version of git packages should also be set to 'git'. + + + +BUILD +________________________________________________________________________________ + + + [0200]---------------------------------------------------------------------- + + This guide should be used alongside shellcheck and not in place of it. + + + [0201]---------------------------------------------------------------------- + + All shell code must pass the shellcheck linter. Any false-positives or + intended behavior must have a rationale attached with the exclusion. + + # Disable warning as CFLAGS must work this way. + # shellcheck disable=2086 + "${CC:-cc}" $CFLAGS ... + + + [0202]---------------------------------------------------------------------- + + Use 4 spaces for indentation. + + + [0203]---------------------------------------------------------------------- + + Lines should not exceed 80 characters in length. + + + [0204]---------------------------------------------------------------------- + + All packages must use the POSIX shell shebang with '-e' to exit on error. + Additionally, '-ef' can be used if word-splitting is required. + + There must also be a blank line directly below the shebang. + + #!/bin/sh -e + + # Code starts here. + + + [0205]---------------------------------------------------------------------- + + All comments must start with a capital letter and use proper spelling, + grammar and punctuation. + + # This is a comment. + + + [0206]---------------------------------------------------------------------- + + Leave comments to explain *why* the code is needed and not *what* it does. + + Bad: + + # Create a directory. + mkdir -p "$1/usr/bin" + + Good: + + # 'make install' doesn't create the directory. + mkdir -p "$1/usr/bin" + + + [0207]---------------------------------------------------------------------- + + Avoid adding braces around variables if unneeded. + + Bad: printf '%s\n' "${var}" + Good: printf '%s\n' "$var" + Good: printf '%s\n' "${var}.${var2}" + + + [0208]---------------------------------------------------------------------- + + Avoid quotes when unneeded. + + Bad: [ "$var" = "test" ] + Good: [ "$var" = test ] + + Bad: install -Dm755 "file" "$1/usr/bin/file" + Good: install -Dm755 file "$1/usr/bin/file" + + + [0209]---------------------------------------------------------------------- + + Quote entire strings instead of variables. + + Bad: install -Dm644 cat "$1"/usr/bin/cat + Good: install -Dm644 cat "$1/usr/bin/cat" + + + [0210]---------------------------------------------------------------------- + + Align arguments in blocks of command calls. + + Bad: + + install -D file.h "$1/usr/include/file.h" + install -D libfile.so "$1/usr/lib/libfile.so" + + Good: + + install -D file.h "$1/usr/include/file.h" + install -D libfile.so "$1/usr/lib/libfile.so" + + + [0211]---------------------------------------------------------------------- + + Use 'install' instead of ... + + Bad: + + mkdir -p "$1/usr/bin" + cp ls "$1/usr/bin/" + + Good: + + install -Dm755 ls "$1/usr/bin/ls" + + + [0212]---------------------------------------------------------------------- + + Prefer $CC to ... + + Bad: gcc -o file file.c + Good: "${CC:-cc}" -o file file.c + + + [0213]---------------------------------------------------------------------- + + Always use '-p' with 'mkdir'. + + + +GNU AUTOTOOLS +________________________________________________________________________________ + + + [0400]---------------------------------------------------------------------- + + Use the following style: + + ./configure \ + --prefix=/usr \ + --more_args_here + + make + make DESTDIR="$1" install + + + [0401]---------------------------------------------------------------------- + + Avoid running ./autogen.sh, autoreconf or similar tools prior to starting + the build process. If there are no pre-generated configure or Makefiles, an + alternate source must be sought. + + An exception can be made for packages in which no such source exists. If + autogen.sh or autoreconf are required, prefer autoreconf. + + + +MESON +________________________________________________________________________________ + + + [0600]---------------------------------------------------------------------- + + Use the following style: + + export DESTDIR="$1" + + meson \ + --prefix=/usr \ + -Dexample=false \ + . output + + ninja -C output + ninja -C output install + + + +CMAKE +________________________________________________________________________________ + + + [0800]---------------------------------------------------------------------- + + Use the following style: + + export DESTDIR="$1" + + cmake -B build \ + -DCMAKE_INSTALL_PREFIX=/usr \ + -DFLAG=1 + + cmake --build build + cmake --install build + + + +MAKE +________________________________________________________________________________ + + + [1000]---------------------------------------------------------------------- + + Use one of the following style when applicable: + + make + make DESTDIR="$1" PREFIX=/usr install + + + make PREFIX=/usr + make DESTDIR="$1" install + + + make PREFIX=/usr + make DESTDIR="$1" PREFIX=/usr install + + + For packages which require a few variables be set, prefer this style. + + make \ + PREFIX=/usr \ + SBINDIR=/usr/bin \ + OPT="$CFLAGS" + + make \ + DESTDIR="$1" \ + PREFIX=/usr \ + install + + + For packages which require the variables be set for all calls to make, + prefer this style. + + mk() { + make \ + PREFIX=/usr \ + DESTDIR="$1" \ + EXAMPLE=1 \ + "$@" + } + + mk + mk install + + + +RUST +________________________________________________________________________________ + + + [1050]---------------------------------------------------------------------- + + Use the following style: + + cargo build --release + + install -Dm755 target/release/rg "$1/usr/bin/rg" + + + +GO +________________________________________________________________________________ + + + [1100]---------------------------------------------------------------------- + + Use the following style: + + export GOPATH="$PWD/go" + export GO111MODULE=on + + go build \ + -modcacherw \ + -trimpath + + install -Dm755 lazygit "$1/usr/bin/lazygit" + + Note: If the directory 'vendor' is available in the root directory of the + source, the preffered method is to omit GOPATH and GO111MODULE and use: + + go build \ + -mod=vendor \ + -further-options + + to prevent cluttering $HOME and enable offline building. + +PYTHON +________________________________________________________________________________ + + + [1150]---------------------------------------------------------------------- + + Use the following style: + + python setup.py build + python setup.py install --prefix=/usr --root="$1" + + + +DEPENDS +________________________________________________________________________________ + + + [1201]---------------------------------------------------------------------- + + This dependency is unneeded and can be removed. + + + [1202]---------------------------------------------------------------------- + + This dependency is implicit. Some packages are assumed to always be + available. This dependency can be removed. + + Examples: gcc, make, musl. + + + [1203]---------------------------------------------------------------------- + + This dependency needs 'make' as it is only required during build time. + + Common Examples: autoconf, automake, cmake, meson. + + + [1204]---------------------------------------------------------------------- + + This dependency doesn't need 'make' as it is required during runtime. + + + [1205]---------------------------------------------------------------------- + + The depends list must be sorted. + + + [1206]---------------------------------------------------------------------- + + The depends file is empty and should be removed. + + + +SOURCES +________________________________________________________________________________ + + + [1401]---------------------------------------------------------------------- + + Use a HTTPS source if at all possible. + + + [1402]---------------------------------------------------------------------- + + Don't specify patches remotely. Store them as a part of the package's + repository files. + + Bad: https://example.com/fix-build.patch + Good: patches/fix-build.patch + + + [1403]---------------------------------------------------------------------- + + Don't use a git repository in place of a release tarball unless it makes + sense to do so. + + + [1404]---------------------------------------------------------------------- + + Drop www. and .git from all sources if possible. + + + +VERSION +________________________________________________________________________________ + + + [1601]---------------------------------------------------------------------- + + Version doesn't match upstream. + + + [1602]---------------------------------------------------------------------- + + Use 'git' in place of '9999'. + + + [1603]---------------------------------------------------------------------- + + Missing relative version number. + + Bad: 1.0.0 + Good: 1.0.0 1 + + + +PATCHES +________________________________________________________________________________ + + + [1800]---------------------------------------------------------------------- + + Use the following style: + + patch -p1 < patch.patch + + # If there is more than one patch. + for patch in *.patch; do + patch -p1 < "$patch" + done + + + [1801]---------------------------------------------------------------------- + + All patches should use the same strip amount. If this is not possible, + modify the patches. Strip amount is controlled by the -p flag. diff --git a/wiki/software/acpid/index.txt b/wiki/software/acpid/index.txt @@ -0,0 +1,149 @@ +ACPID +________________________________________________________________________________ + +Acpid is a daemon that executes certain actions whenever ACPI events are +received. Depending on your hardware and kernel configuration, these events +include closing a laptop lid, connecting to an AC power adapter, pressing +buttons and more. + + +Index +________________________________________________________________________________ + +- Usage [0.0] +- Kernel Setup [1.0] +- Busybox acpid [2.0] +- acpid2 [3.0] + + +[0.0] Usage +________________________________________________________________________________ + +KISS Linux offers two options for acpid management: busybox acpid, which is +installed by default, and acpid2 [1], which can be installed with the acpid +package. To use either version of acpid, you will need to enable a few kernel +options and enable the acpid service. See @/init/busybox. + + +[1.0] Kernel Setup +________________________________________________________________________________ + +ACPI-related kernel drivers must be enabled for acpid to function properly. In +menuconfig, these options are found under Power management and ACPI options +> Power Management support > ACPI support. Most of the drivers are +self-explanatory, but the following notable options can be safely disabled: + ++------------------------------------------------------------------------------+ +| | +| CONFIG_ACPI_PROCFS_POWER This option is deprecated | +| CONFIG_ACPI_EC_DEBUGFS Potentially interferes with reboot | +| CONFIG_ACPI_TABLE_UPGRADE KISS does not use an initrd by default | +| CONFIG_ACPI_DEBUG Adds 50k to kernel size | +| CONFIG_ACPI_PCI_SLOT Usually unnecessary | +| CONFIG_ACPI_CUSTOM_METHOD Potential security flaw | +| | ++------------------------------------------------------------------------------+ + + +[2.0] Busybox acpid +________________________________________________________________________________ + +When events are received, acpid checks /etc/acpi.map for a matching event and +/etc/acpid.conf for a corresponding handler script in /etc/acpi/ to execute. + +Create the files below to suspend your laptop whenever the lid is closed: + ++------------------------------------------------------------------------------+ +| /etc/acpi.map | ++------------------------------------------------------------------------------+ +| | +| EV_SW 0x05 SW_LID 0 1 button/lid LID0 00000080 | +| | ++------------------------------------------------------------------------------+ +| /etc/acpid.conf | ++------------------------------------------------------------------------------+ +| | +| LID0 LID/00000080 | +| | ++------------------------------------------------------------------------------+ +| /etc/acpi/LID/00000080 | ++------------------------------------------------------------------------------+ +| | +| #!/bin/sh | +| | +| printf mem > /sys/power/state | +| | ++------------------------------------------------------------------------------+ + +Each line in /etc/acpi.map has six space-delimited fields: + 1. Type name (EV_SW), + 2. Type numerical value (0x05) + 3. Keycode name (SW_LID) + 4. Keycode numerical value (0) + 5. Value (1) + 6. Description (button/lid LID0 00000080) + +Event types and keycodes are listed in /usr/include/linux/input-event-codes.h. +For example, a keyboard WLAN button event would use EV_KEY 0x05 and KEY_WLAN +238. The event value should be 1 and the event description can be any string +potentially including spaces. + +Each line in /etc/acpid.conf has a key (LID0) and an action (LID/00000080). The +key is any unique substring of the event description in /etc/acpi.map and the +action is the relative path to an executable script in /etc/acpi/. + +To see if a configured event is received, check /var/log/acpid.log for output +lines that list the path of your handler scripts. + + +[3.0] acpid2 +________________________________________________________________________________ + +acpid2 is a more user-friendly version of acpid that avoids the tedious process +of mapping events with flexible configuration and better documentation. The +acpid package also installs acpi_listen which prints events as they occur. For +example, pressing the volume mute button will print something like this: + ++------------------------------------------------------------------------------+ +| | +| button/mute MUTE 00000080 00000000 K | +| | ++------------------------------------------------------------------------------+ + +When events are received, acpid2 checks files in /etc/acpi/event/ for a matching +event and a corresponding handler script to execute. Create the following files +to handle the mute button event by toggling the Master audio channel: + ++------------------------------------------------------------------------------+ +| /etc/acpi/event/anything | ++------------------------------------------------------------------------------+ +| | +| event=.* | +| action=/etc/acpi/handler.sh %e | +| | ++------------------------------------------------------------------------------+ +| /etc/acpi/handler.sh | ++------------------------------------------------------------------------------+ +| | +| #!/bin/sh | +| | +| case $1 in | +| button/mute) | +| amixer sset Master toggle | +| ;; | +| esac | +| | ++------------------------------------------------------------------------------+ + +Files in /etc/acpi/event/ match events using event=REGEX with an action to +execute. In this example, .* matches all events and the action executes +/etc/acpi/handler.sh. The argument %e expands to five event parameters: +$1=button/mute, $2=MUTE, $3=00000080, $4=00000000, $5=K. The event parameters +provide an easy way to handle all events in a single script instead of the more +complex multi-file system used by busybox. + + +References +________________________________________________________________________________ + +[0] https://sourceforge.net/projects/acpid2 diff --git a/wiki/software/alsa-utils/index.txt b/wiki/software/alsa-utils/index.txt @@ -0,0 +1,84 @@ +ALSA-UTILS [0] +________________________________________________________________________________ + +The Advanced Linux Sound Architecture (ALSA) provides audio and MIDI +functionality to the Linux operating system. + + +Configuration +________________________________________________________________________________ + +First verify that you have alsa-utils installed: + ++------------------------------------------------------------------------------+ +| | +| $ kiss b alsa-utils && kiss i alsa-utils | +| | ++------------------------------------------------------------------------------+ + +By default, ALSA routes audio to card "0" and device "0" (see /etc/asound.conf +file), which may not be preferred. Luckily, we can change this behavior via +local user configuration: + ++------------------------------------------------------------------------------+ +| ~/.asoundrc, simple example | ++------------------------------------------------------------------------------+ +| | +| defaults.pcm!card 1 | +| defaults.pcm.!device 7 | +| | ++------------------------------------------------------------------------------+ + +In the example, the numeric device name is specified. When multiple sound cards +are in use, the device numbers could be reordered across boots, such that using +a descriptive device name is preferred. + +You can then test your local sound card configuration with the command below: + ++------------------------------------------------------------------------------+ +| | +| $ speaker-test -c 2 | +| | ++------------------------------------------------------------------------------+ + +Note: Replace the "2" to match the number of channels in your sound card. + + +Tips and Tricks +________________________________________________________________________________ + +- Use the following command to obtain a list of available sound card and device + numbers: + + +----------------------------------------------------------------------------+ + | | + | $ aplay -L | + | | + +----------------------------------------------------------------------------+ + +- A list of descriptive device names can be obtained with the following command: + + +----------------------------------------------------------------------------+ + | | + | $ cat /sys/class/sound/card*/id | + | | + +----------------------------------------------------------------------------+ + +- Use the following command to open an easy to use, terminal based alsa control interface: + + +----------------------------------------------------------------------------+ + | | + | $ alsamixer | + | | + +----------------------------------------------------------------------------+ + +- More "complex" .asoundrc configuration file examples can be found on the + Gentoo Wiki [1] and Arch Linux Wiki [2]. + + +References +________________________________________________________________________________ + +[0] https://www.alsa-project.org/wiki/Main_Page +[1] https://wiki.gentoo.org/wiki/ALSA +[2] https://wiki.archlinux.org/index.php/Advanced_Linux_Sound_Architecture diff --git a/wiki/software/dhcpcd/index.txt b/wiki/software/dhcpcd/index.txt @@ -0,0 +1,166 @@ +DHCPCD [0] +________________________________________________________________________________ + +Dynamic Host Configuration Protocol Client Daemon is a popular DHCP client +capable of handling both IPv4 and IPv6 configuration. + + +Dynamic IP Configuration +________________________________________________________________________________ + +Begin by first verifying that you have dhcpcd installed: + ++------------------------------------------------------------------------------+ +| | +| $ kiss b dhcpcd && kiss i dhcpcd | +| | ++------------------------------------------------------------------------------+ + +Once installed, dhcpcd can be used to automatically configure a network device +interface: + ++------------------------------------------------------------------------------+ +| | +| $ dhcpcd INTERFACE | +| | ++------------------------------------------------------------------------------+ + +Remember to replace INTERFACE in the command above with the name of the device +that you wish to configure. + +A network device's interface status can be inspected via ip-link: + ++------------------------------------------------------------------------------+ +| | +| $ ip link show dev INTERFACE | +| | ++------------------------------------------------------------------------------+ + +ip-link can also be used to enable or disable an interface: + ++------------------------------------------------------------------------------+ +| | +| $ ip link set INTERFACE down # disable the interface | +| $ ip link set INTERFACE up # enable the interface | +| | ++------------------------------------------------------------------------------+ + + +Static IP Configuration +________________________________________________________________________________ + +Continuing from the previous section, we can use ip-address to display the +current DHCP address information: + ++------------------------------------------------------------------------------+ +| | +| $ ip address show | +| | ++------------------------------------------------------------------------------+ + +Using the output of the previous command, add the following lines to the +/etc/dhcpcd.conf file using your preferred text editor: + ++------------------------------------------------------------------------------+ +| | +| interface INTERFACE | +| static ip_address=STATIC_IP | +| static routers=GATEWAY | +| static domain_name_servers=DNS_SERVER | +| | ++------------------------------------------------------------------------------+ + +Remember to replace the INTERFACE, STATIC_IP, GATEWAY and DNS_SERVER in the +block above with your own parameters. + + +Hostname +________________________________________________________________________________ + +A system's hostname can be set by simply creating a /etc/hostname file: + ++------------------------------------------------------------------------------+ +| | +| $ echo "HOSTNAME" > /etc/hostname | +| | ++------------------------------------------------------------------------------+ + +Remember to replace HOSTNAME with the string of your choosing. + +Note: Valid characters for hostnames include ASCII letters from A to Z, digits + from 0 to 9, and the hyphen character (-). A hostname may not start with + a hyphen. + + +Managed via runsv +________________________________________________________________________________ + +Busybox's runsv can be used to create a new managed service with the following +command: + ++------------------------------------------------------------------------------+ +| | +| $ ln -s /etc/sv/dhcpcd/ /var/service | +| | ++------------------------------------------------------------------------------+ + +To start the new managed service, use the following command: + ++------------------------------------------------------------------------------+ +| | +| $ sv up dhcpcd | +| | ++------------------------------------------------------------------------------+ + + +Tips and Tricks +________________________________________________________________________________ + +* A list of possible INTERFACE names can be obtained by running the following: + + +----------------------------------------------------------------------------+ + | | + | $ ls /sys/class/net | + | | + +----------------------------------------------------------------------------+ + +* The ping command can be used to verify connectivity with a network device + interface: + + +----------------------------------------------------------------------------+ + | | + | $ ping www.google.com | + | | + +----------------------------------------------------------------------------+ + +* Some network administrators require that the hostname and domain name provided + by the DHCP server is used by the system. In that case, pass the "-HD" switch: + + +----------------------------------------------------------------------------+ + | | + | $ dhcpcd -HD INTERFACE | + | | + +----------------------------------------------------------------------------+ + +* If you are not sure what to put in the STATIC_IP, GATEWAY and DNS_SERVER, you + can use the following example for reference: + + +----------------------------------------------------------------------------+ + | | + | interface eth0 | + | static ip_address=192.168.0.4/24 | + | static routers=192.168.0.1 | + | static domain_name_servers=192.168.0.1 | + | | + +----------------------------------------------------------------------------+ + + Notice the "/24" suffix, which is an abbreviation for the subnet mask + 255.255.255.0. Also, GATEWAY and DNS_SERVER are the same in this example. + + +References +________________________________________________________________________________ + +[0] https://github.com/rsmarples/dhcpcd +[1] https://wiki.archlinux.org/index.php/Network_configuration +[2] https://wiki.gentoo.org/wiki/Dhcpcd diff --git a/wiki/software/eiwd/index.txt b/wiki/software/eiwd/index.txt @@ -0,0 +1,139 @@ +EIWD [0] +________________________________________________________________________________ + +eiwd is iNet Wireless Daemon (iwd) without dbus. iNet Wireless Daemon aims to +replace @/wpa_supplicant while providing the following benefits: + +* Simplification of network management. +* Faster network discovery. +* Fast and reliable roaming. +* Use less system resources. +* Use features offered by the linux kernel. +* Support for enterprise security methods like EAP. +* Support for kernel asymetric key rings and trusted platform modules (TPM). +* Support for multiple clients. + + +Configuration +________________________________________________________________________________ + +Ensure that you have the following dependencies installed: + ++------------------------------------------------------------------------------+ +| | +| $ kiss b eiwd && kiss i eiwd | +| $ kiss b openresolv && kiss i openresolv | +| | ++------------------------------------------------------------------------------+ + +Create a new daemon configuration file: + ++------------------------------------------------------------------------------+ +| | +| $ mkdir -p /etc/iwd | +| $ touch /etc/iwd/main.conf | +| | ++------------------------------------------------------------------------------+ + +Using a preferred text editor, add the following lines to the main.conf file +generated above: + ++------------------------------------------------------------------------------+ +| | +| [General] | +| EnableNetworkConfiguration=true | +| | +| [Network] | +| RoutePriorityOffset=200 | +| NameResolvingService=resolvconf | +| | ++------------------------------------------------------------------------------+ + + +Adding A Wireless Network +________________________________________________________________________________ + +eiwd ships with a iwd_passphrase, which can be used for generating iwd network +files: + ++------------------------------------------------------------------------------+ +| | +| $ printf PASSWORD | iwd_passphrase BSSID | +| | ++------------------------------------------------------------------------------+ + +Remember to replace BSSID and PASSWORD with your respective network credentials. + +Using a preferred text editor, copy the output of the command above to the +following location: /var/lib/iwd/BSSID.psk + + +Managed via runsv +________________________________________________________________________________ + +Busybox's runsv can be used to create a new managed service with the following +command: + ++------------------------------------------------------------------------------+ +| | +| $ ln -s /etc/sv/eiwd/ /var/service | +| | ++------------------------------------------------------------------------------+ + +To start the new managed service, use the following command: + ++------------------------------------------------------------------------------+ +| | +| $ sv up eiwd | +| | ++------------------------------------------------------------------------------+ + + +Tips and Tricks +________________________________________________________________________________ + +* To prevent iwd from continuous scanning while not connected, add the following + to your main.conf file: + + +----------------------------------------------------------------------------+ + | | + | [Scan] | + | DisablePeriodicScan=true | + | | + +----------------------------------------------------------------------------+ + +* To prevent iwd from destroying / recreating wireless interfaces at startup, + add the following to your main.conf file: + + +----------------------------------------------------------------------------+ + | | + | [General] | + | UseDefaultInterface=true | + | | + +----------------------------------------------------------------------------+ + +* If iwd fails to start, check to make that you have the required kernel + options: + + CONFIG_CRYPTO_USER_API_HASH + CONFIG_CRYPTO_USER_API_SKCIPHER + CONFIG_KEY_DH_OPERATIONS + CONFIG_CRYPTO_ECB + CONFIG_CRYPTO_MD5 + CONFIG_CRYPTO_CBC + CONFIG_CRYPTO_SHA256 + CONFIG_CRYPTO_AES + CONFIG_CRYPTO_DES + CONFIG_CRYPTO_CMAC + CONFIG_CRYPTO_HMAC + CONFIG_CRYPTO_SHA512 + CONFIG_CRYPTO_ARC4 + CONFIG_CRYPTO_SHA1 + + +References +________________________________________________________________________________ + +[0] https://github.com/dylanaraps/eiwd +[1] https://wiki.gentoo.org/wiki/Iwd +[2] https://manpages.debian.org/testing/iwd/iwd.config.5.en.html diff --git a/wiki/software/git/index.txt b/wiki/software/git/index.txt @@ -0,0 +1,287 @@ +GIT [0] +________________________________________________________________________________ + +Git is a free and open source distributed version control system designed to +handle everything from small to very large projects with speed and efficiency. + + +[0.0] Index +________________________________________________________________________________ + +- Git Commands [1.0] +- Example 1: Staying Up-to-Date [2.0] +- Example 2: Squashing Your Latest Commits Into One [3.0] +- Example 3: Writing a new KISS Wiki article [4.0] +- References [5.0] + + +[1.0] Git Commands +________________________________________________________________________________ + +New KISS users may have various levels of exposure to git and other forms of +version control systems. The following is intended to be a "quick" reference +sheet of git commands. + ++-------------------+----------------------------------------------------------+ +| Action | Command | ++-------------------+----------------------------------------------------------+ +| | | +| Set Default | $ git config --global user.name "FIRSTNAME LASTNAME" | +| Username | # stored in ~/.gitconfig | +| | | +| Set Default | $ git config --global user.email "EMAIL@EXAMPLE.COM" | +| Email Address | # stored in ~/.gitconfig | +| | | +| Set Default | $ git config --global core.editor vim | +| Text Editor | # stored in ~/.gitconfig | +| | | +| Store User | $ git config credential.helper store | +| Credentials | # credentials saved in ~/.git-credentials | +| | | +| Clone Repo. | $ git clone GIT_URL | +| | | +| Clone Branch | $ git clone GIT_URL -b BRANCH_NAME | +| | | +| Repo. Status | $ git status | +| | | +| Add/Update | $ git add FILE_OR_PATH | +| Project Files | | +| | | +| Apply a patch | $ git apply PATH_FILE | +| | | +| Remove | $ git add FILE_OR_PATH | +| Project Files | | +| | | +| Checkout | $ git checkout BRANCH_NAME | +| | # switch branches or restore working tree files | +| | | +| Commit | $ git commit | +| | # records changes to the repository | +| | | +| Push | $ git push | +| | # updates remote refs along with associated objects | +| | | +| Pull | $ git pull | +| | # fetch and integrate with another repository/branch | +| | | +| Fetch | $ git fetch | +| | # download objects and refs from another repository | +| | | +| Merge | $ git merge | +| | # join two or more development histories together | +| | | +| Rebase | $ git rebase | +| | # reapply commits on top of another base tip | +| | | ++-------------------+----------------------------------------------------------+ + + +[2.0] Example 1: Staying Up-to-Date [1] +________________________________________________________________________________ + +In a standard setup, you generally have an origin and an upstream remote - the +latter being the gatekeeper of the project or the source of truth to which you +wish to contribute. + +First, verify that you have already setup a remote for the upstream repository, +and hopefully an origin too: + ++------------------------------------------------------------------------------+ +| | +| $ git remote -v | +| | ++------------------------------------------------------------------------------+ + +If you don't have an upstream you can easily add it with the remote command: + ++------------------------------------------------------------------------------+ +| | +| $ git remote add upstream UPSTREAM_URL | +| | ++------------------------------------------------------------------------------+ + +Now you can collect the latest changes of the upstream repository with fetch. +Repeat this every time you want to get updates: + ++------------------------------------------------------------------------------+ +| | +| $ git fetch upstream | +| | ++------------------------------------------------------------------------------+ + +Generally, you want to keep your local master branch as a close mirror of the +upstream master and execute any work in feature branches, as they might later +become pull requests. + +At this point, it does not matter if you use merge or rebase, as the result +will typically be the same. Let's use merge: + ++------------------------------------------------------------------------------+ +| | +| $ git checkout master | +| $ git merge upstream/master | +| | ++------------------------------------------------------------------------------+ + + +[3.0] Example 2: Squashing Your Latest Commits Into One [2] +________________________________________________________________________________ + +With git it’s possible to squash previous commits into one. This is a great way +to group certain changes together before sharing them with others. Let’s say +this is your current git log: + ++------------------------------------------------------------------------------+ +| | +| * df71a27 - (HEAD feature_x) Updated CSS for new elements (4 minutes ago) | +| * ba9dd9a - Added new elements to page design (15 minutes ago) | +| * f392171 - Added new feature X (1 day ago) | +| * d7322aa - (origin/feature_x) Proof of concept for feature X (3 days ago) | +| | ++------------------------------------------------------------------------------+ + +You have a branch “feature_x” here. You’ve already pushed d7322aa with the proof +of concept of the new feature X. After that you’ve been working to add new +element to the feature, including some changes in CSS. Now, you want to squash +your last three commits in one to make your history look pretty. + +The command to accomplish that is: + ++------------------------------------------------------------------------------+ +| | +| $ git rebase -i HEAD~3 | +| | ++------------------------------------------------------------------------------+ + +This will open up your editor with the following: + ++------------------------------------------------------------------------------+ +| | +| pick f392171 Added new feature X | +| pick ba9dd9a Added new elements to page design | +| pick df71a27 Updated CSS for new elements | +| | ++------------------------------------------------------------------------------+ + +Now you can tell git what to do with each commit. Let’s keep the commit f392171, +the one were we added our feature. We’ll squash the following two commits into +the first one - leaving us with one clean commit with features X in it, +including the added element and CSS. + +Change your file to this: + ++------------------------------------------------------------------------------+ +| | +| pick f392171 Added new feature X | +| squash ba9dd9a Added new elements to page design | +| squash df71a27 Updated CSS for new elements | +| | ++------------------------------------------------------------------------------+ + +When done, save and quit your editor. Git will now squash the commits into one. + +Note: Do not squash commits that you’ve already shared with others. You are + changing history and it will cause trouble for others. + + +[4.0] Example 3: Writing a new KISS Wiki article. +________________________________________________________________________________ + +Note: The method described below requires a GitHub user account. If you do not + have a GitHub user account or do not wish to create one, you can still + submit your articles or ideas directly to dylan@k1ss.org. + +Lets say you are interested in writing a new article for the KISS Wiki. The +process is fairly straight forward! + +Begin by first creating a fork of the KISS Wiki repository. One way to do this +is from a web browser by going to the https://github.com/kiss-community/wiki +page, clicking the "Fork" button in the upper right corner of the page. Doing so +should create a copy of the KISS Wiki repository on your user account (e.g. +https://github.com/USERNAME/wiki). + +Clone the forked repository to your PC with the following command. Remember to +replace USERNAME with your actual GitHub username. + ++------------------------------------------------------------------------------+ +| | +| $ git clone https://github.com/USERNAME/wiki.git | +| | ++------------------------------------------------------------------------------+ + +Once cloned to your PC, navigate to the wiki directory: + ++------------------------------------------------------------------------------+ +| | +| $ cd wiki | +| | ++------------------------------------------------------------------------------+ + +Add your new article in this directory per the #/wiki/help/adding-a-page +guidelines. Once you are ready to publish your newly created article, you need +to add/update your forked repository. From the main wiki directory, you can +check the status of all changes or newly created files: + ++------------------------------------------------------------------------------+ +| | +| $ git status | +| | ++------------------------------------------------------------------------------+ + +Using the output of command above, update/add the new files your forked +repository that are ready to be published: + ++------------------------------------------------------------------------------+ +| | +| $ git add FILE_NAME1 FILE_NAME | +| | ++------------------------------------------------------------------------------+ + +Alternatively, you can add ALL newly updated/created files in a single command: + ++------------------------------------------------------------------------------+ +| | +| $ git add * | +| | ++------------------------------------------------------------------------------+ + +Next, you will commit your changes. + ++------------------------------------------------------------------------------+ +| | +| $ git commit -m "YOUR_COMMIT_MSG" | +| | ++------------------------------------------------------------------------------+ + +Replace YOUR_COMMIT_MSG with a short description of change(s) or the new article +(i.e. "git: new article" or "git: add new git example"). + +At this point you are ready to push your changes to the GitHub server with the +following command. + ++------------------------------------------------------------------------------+ +| | +| $ git push | +| | ++------------------------------------------------------------------------------+ + +Upon doing so, you will be prompted to enter your GitHub user credentials. Once +entered, the latest changes will be uploaded to your forked Wiki repository +on GitHub. + +The last step is to initiate a Pull Request (PR). A PR can be initiated via a +web browser by going to the https://github.com/USERNAME/wiki page and pressing +the "New pull request" button near the top of the page. In the Title field, +enter the reason for initiating a PR (i.e. "git: new article") and press the +"Create pull request" button. + +Note: Pay attention to which branch is being merged into the master branch of + the repository :kiss-community/wiki". + + +[5.0] References +________________________________________________________________________________ + +[0] https://git-scm.com +[1] https://www.atlassian.com/git/tutorials/git-forks-and-upstreams +[2] https://www.devroom.io/2011/07/05/git-squash-your-latests-commits-into-one/ diff --git a/wiki/software/index.txt b/wiki/software/index.txt @@ -0,0 +1,14 @@ +SOFTWARE +________________________________________________________________________________ + +- @/alsa-utils +- @/acpid +- @/dhcpcd +- @/eiwd +- @/git +- @/man-pages +- @/opendoas +- @/openssh +- @/tzdata +- @/vim +- @/wpa_supplicant diff --git a/wiki/software/man-pages/index.txt b/wiki/software/man-pages/index.txt @@ -0,0 +1,64 @@ +MAN PAGES +________________________________________________________________________________ + +A man page (short for manual page) is a form of software documentation usually +found on a Unix or Unix-like operating systems. Topics covered include computer +programs (including library and system calls), formal standards and conventions, +and even abstract concepts. A user may invoke a man page by issuing the man +command. [0] + + +The man utility +________________________________________________________________________________ + +The 'mandoc' [1] package is the default provider of the 'man' utility. + ++------------------------------------------------------------------------------+ +| Install mandoc | ++------------------------------------------------------------------------------+ +| | +| $ kiss b mandoc && kiss i mandoc | +| | ++------------------------------------------------------------------------------+ + +By default, man typically uses a terminal pager program such as more or less to +display its output. This can be configured via the $PAGER environment variable. + + +Linux manuals +________________________________________________________________________________ + +The Linux man-pages project [2] documents the Linux kernel and C library +interfaces that are employed by user-space programs. + ++------------------------------------------------------------------------------+ +| Install man-pages | ++------------------------------------------------------------------------------+ +| | +| $ kiss b man-pages && kiss i man-pages | +| | ++------------------------------------------------------------------------------+ + + +POSIX manuals +________________________________________________________________________________ + +These are pages from POSIX.1-2008, Technical Corrigendum 1. Since TC1 appeared +in 2013, it is also known as POSIX.1-2013. The man pages contain descriptions of +the headers, the utilities, and the functions documented in that standard. + ++------------------------------------------------------------------------------+ +| Install man-pages-posix | ++------------------------------------------------------------------------------+ +| | +| $ kiss b man-pages-posix && kiss i man-pages-posix | +| | ++------------------------------------------------------------------------------+ + + +References +________________________________________________________________________________ + +[0] https://en.wikipedia.org/wiki/Man_page +[1] https://mandoc.bsd.lv/ +[2] https://kernel.org/doc/man-pages/ diff --git a/wiki/software/opendoas/index.txt b/wiki/software/opendoas/index.txt @@ -0,0 +1,52 @@ +OPENDOAS [0] +________________________________________________________________________________ + +doas is a minimal replacement for the venerable sudo. It was initially written +by Ted Unangst of the OpenBSD project to provide 95% of the features of sudo +with a fraction of the codebase. + + +Configuration +________________________________________________________________________________ + +Begin by first verifying that you have opendoas installed: + ++------------------------------------------------------------------------------+ +| | +| $ kiss b opendoas && kiss i opendoas | +| | ++------------------------------------------------------------------------------+ + +Using your preferred text editor, modify the /etc/doas.conf file. Within the +doas.conf, there are plenty of examples of rules to choose from and modify. + +Below are a few examples of *basic* rules that could be set: + ++------------------------------------------------------------------------------+ +| Allow a specific regular user, USER, to escalate to root permissions. | ++------------------------------------------------------------------------------+ +| | +| permit USER | +| | ++------------------------------------------------------------------------------+ +| Allow a specific group (i.e. "wheel") to escalate to root permissions. | ++------------------------------------------------------------------------------+ +| | +| permit wheel | +| | ++------------------------------------------------------------------------------+ +| You can also allow privilege escalation without a password. | ++------------------------------------------------------------------------------+ +| | +| permit nopass [GROUP OR USER] | +| | ++------------------------------------------------------------------------------+ + +Refer to OpenBSD doas.conf manual page [1] for more information. + + +References +________________________________________________________________________________ + +[0] https://github.com/Duncaen/OpenDoas +[1] https://man.openbsd.org/doas.conf.5 diff --git a/wiki/software/openssh/index.txt b/wiki/software/openssh/index.txt @@ -0,0 +1,141 @@ +OPENSSH [0] +________________________________________________________________________________ + +OpenSSH (also known as OpenBSD Secure Shell) is a suite of secure networking +utilities based on the Secure Shell (SSH) protocol, which provides a secure +channel over an unsecured network in a client-server architecture. + + +Remote Server Configuration +________________________________________________________________________________ + +Begin by first verifying that you have openssh installed on the remote server: + ++------------------------------------------------------------------------------+ +| | +| $ kiss b openssh && kiss i openssh | +| | ++------------------------------------------------------------------------------+ + +Using busybox's runsv, create a new managed service for the ssh daemon: + ++------------------------------------------------------------------------------+ +| | +| $ ln -s /etc/sv/sshd /var/service | +| | ++------------------------------------------------------------------------------+ + +At this point, you can either restart the remote server or manually start the +SSH daemon: + ++------------------------------------------------------------------------------+ +| | +| $ sv up sshd | +| | ++------------------------------------------------------------------------------+ + + +Client Authentication +________________________________________________________________________________ + +From an SSH client, use the following command to connect to the remote SSH +server: + ++------------------------------------------------------------------------------+ +| | +| $ ssh USERNAME@SERVER | +| | ++------------------------------------------------------------------------------+ + +Replace USERNAME with the name of a regular user and SERVER with the hostname or +IP address of the SSH remote server. Upon pressing return, you will also be +prompted to enter the password of the regular user specified. + + +Passwordless Authentication (Optional) +________________________________________________________________________________ + +Passwordless login to a remove server can be achieved by creating a key pair. +From the SSH client, use the following command to generate the key: + ++------------------------------------------------------------------------------+ +| | +| $ ssh-keygen -t rsa | +| | ++------------------------------------------------------------------------------+ + +Copy the id_rsa.pub file generated from the previous step into the remote +server's ~/.ssh/authorized_keys with the following command: + ++------------------------------------------------------------------------------+ +| | +| $ ssh-copy-id USERNAME@SERVER | +| | ++------------------------------------------------------------------------------+ + +Replace USERNAME with the name of a regular user and SERVER with the hostname or +IP address of the SSH remote server. Upon pressing return, you will also be +prompted to enter the password of the regular user specified. + +Verify that the key was copied to the remote server and passwordless login works +by entering the following command from the previous section: + ++------------------------------------------------------------------------------+ +| | +| $ ssh USERNAME@SERVER | +| | ++------------------------------------------------------------------------------+ + +Once passwordless login has been verified, disable password authentication on +the remote server: + ++------------------------------------------------------------------------------+ +| | +| $ echo "PasswordAuthentication no" >> /etc/ssh/sshd_config | +| | ++------------------------------------------------------------------------------+ + + +Tips and Tricks +________________________________________________________________________________ + +* When connecting to an SSH server, there are three different levels of debug + modes that can help with troubleshooting issues. Use the "-v" switch when + connecting to print the debugging messages: + ++------------------------------------------------------------------------------+ +| | +| $ ssh USERNAME@SERVER -v | +| $ ssh USERNAME@SERVER -vv | +| $ ssh USERNAME@SERVER -vvv | +| | ++------------------------------------------------------------------------------+ + +* If you are looking to forward GUI-based applications through an SSH tunnel, + refer to the #/wiki/xorg/x11-forwarding article. + + +troubleshooting +________________________________________________________________________________ + +* you can fix errors such as this one + ++------------------------------------------------------------------------------+ +| | +| top error: Error opening terminal: xterm-256color | +| | ++------------------------------------------------------------------------------+ + +By running this command in your ssh session + ++------------------------------------------------------------------------------+ +| | +| $ export TERM=xterm | +| | ++------------------------------------------------------------------------------+ + +References +________________________________________________________________________________ + +[0] https://www.openssh.com/openbsd.html +[1] https://wiki.gentoo.org/wiki/SSH diff --git a/wiki/software/tzdata/index.txt b/wiki/software/tzdata/index.txt @@ -0,0 +1,65 @@ +TZDATA [0] +________________________________________________________________________________ + +The Time Zone Database (called tz, tzdb or zoneinfo) contains code and data that +represent the history of local time for many representative locations around the +globe. + + +Configuration +________________________________________________________________________________ + +Begin by first verifying that you have tzdata installed: + ++------------------------------------------------------------------------------+ +| | +| $ kiss b tzdata && kiss i tzdata | +| | ++------------------------------------------------------------------------------+ + +Look for the available timezones in /usr/share/zoneinfo/: + ++------------------------------------------------------------------------------+ +| | +| $ ls /usr/share/zoneinfo | +| | ++------------------------------------------------------------------------------+ + +Write your preferred timezone to the /etc/timezone file: + ++------------------------------------------------------------------------------+ +| | +| $ echo "TZ" > /etc/timezone | +| | ++------------------------------------------------------------------------------+ + +Remember to replace TZ with with your preferred timezone. For example, if I +lived in the US Eastern timezone, I would replace TZ with "US/Eastern". + +Lastly, copy the preferred timezone file to /etc/localtime: + ++------------------------------------------------------------------------------+ +| | +| $ cp TZ_PATH /etc/localtime | +| | ++------------------------------------------------------------------------------+ + +Remember to replace TZ_PATH with with the complete timezone path. For the +example given above, the complete TZ_PATH for "US/Eastern" would be +"/usr/share/zoneinfo/US/Eastern". + +As an optional final step, remove the tzdata package. + ++------------------------------------------------------------------------------+ +| | +| $ kiss r tzdata | +| | ++------------------------------------------------------------------------------+ + + +References +________________________________________________________________________________ + +[0] https://github.com/eggert/tz +[1] https://wiki.gentoo.org/wiki/Handbook:AMD64/Installation/Base#Timezone +[2] https://wiki.archlinux.org/index.php/System_time diff --git a/wiki/software/vim/index.txt b/wiki/software/vim/index.txt @@ -0,0 +1,211 @@ +VIM [0] +________________________________________________________________________________ + +Vim is an improved version of the good old UNIX editor, vi. Many new features +have been added: multi-level undo, syntax highlighting, command line history, +on-line help, spell checking, filename completion, block operations, script +language, etc. There is also a Graphical User Interface (GUI) available. Still, +vi compatibility is maintained, those who have vi "in the fingers" will feel at +home. + +Configuration +________________________________________________________________________________ + +Vim configuration is stored in a local user's ~/.vimrc file. The contents of +this file are based on the user's preferences. + +The following configuration is an example based on Sven Gucke's [1] published +vim setup and modified to satisfy the KISS #/kiss/style-guide. + +Note: There are no "fancy" text decorations or highlighting. Just a core set of + features selected to assist in code and article writing. + ++------------------------------------------------------------------------------+ +| Sven Gucke's Modified VIMRC | ++------------------------------------------------------------------------------+ +| | +| set ai nocp digraph ek hid ru sc vb wmnu noeb noet nosol | +| syntax on | +| set bs=2 fo=cqrt ls=2 shm=at tw=80 sw=4 ts=4 sts=4 ww=<,>,h,l | +| set comments=b:#,:%,n:> | +| set list listchars=tab:»·,trail:· | +| autocmd FileType markdown,text setlocal spell | +| | ++------------------------------------------------------------------------------+ + +The following is an explanation of each parameter. You can learn more about each +by using the ":help OPTION" command in vim. + ++------------------------+-----------------------------------------------------+ +| Command | Description | ++------------------------+-----------------------------------------------------+ +| | | +| nocompatible | This changes the values of many options, | +| set nocp | enabling features which are not vi compatible | +| | (but really really nice). | +| | | +| digraph | Enables input of special characters by a | +| set digraph | combination of two characters. Example: Type | +| | 'a', erase it by typing CTRL-H - and then type | +| | ':' - this results in the umlaut: ä So Vim | +| | remembers the character you have erased and | +| | combines it with the character you have typed | +| | "over" the previous one. | +| | | +| esckeys | Enables recognition of arrow key codes which | +| set ek | start off with an ESC. This would normally end | +| | your current mode (insert/append/open mode) and | +| | return you command mode (aka normal mode), and | +| | the rest of the code would trigger commands. | +| | | +| hidden | Allows hidden buffers even though they contain | +| set hid | modifications which have not yet been written | +| | back to the associated file. | +| | | +| ruler | Shows the "ruler" for the cursor (i.e, its | +| set ru | current position with line+column and the | +| | percentage within the buffer). | +| | | +| showcmd | Show the input of an *incomplete* command. So | +| set sc | while you are typing the command "y23dd" you | +| | will see "y23dd before you type the last 'd' | +| | which completes the command. Makes learning Vi | +| | much simpler as you get some feedback to what | +| | you have already typed. | +| | | +| visualbell | Chose "visual bell" effect rather than | +| set vb | "beeping". | +| | | +| wildmenu | Make use of the "status line" to show possible | +| set wmnu | completions of command line commands, file | +| | names and more. Allows one to cycle forward and | +| | backward through the list. | +| | | +| noerrorbells | Turn off the bell. You do know the "beep" you | +| set noeb | get when you type ESC in normal mode? | +| | Be nice to your co-workers - turn it off! ;-) | +| | | +| noexpandtab | When inserting text, do not expand TABs to | +| set noet | spaces. You can always make vim expand the TABs | +| | later (using the ":retab" command). | +| | | +| nostartofline | Prevent the cursor from changing the current | +| set nosol | column when jumping to other lines within the | +| | window. | +| | | +| syntax on | Enable syntax highlighting. | +| | | +| autoindent | Automatic indentation. This automatically | +| set ai | inserts the indentation from the current line | +| | when you start a new line; in insert mode you | +| | would start a new line by ending the current | +| | one by inserting CTRL-J or CTRL-M - and in | +| | command mode you'd "open" a new line with | +| | either 'o' or 'O' for below or above the | +| | current line, respectively. | +| | | +| backspace | Backspace with this value allows to use the | +| set bs=2 | backspace character (aka CTRL-H or "<-"). | +| | for moving the cursor over automatically | +| | inserted indentation and over the start/end of | +| | a line (see also the whichwrap option). | +| | | +| formatoptions | The format options affect the built-in "text | +| set fo=cqrt | formatting" command. The default value omits | +| | the "flag" 'r', which makes vim insert a | +| | "comment leader" when starting a new line. This | +| | allows to add text to a comment and still be | +| | within the comment after you start a new line. | +| | It also allows to break the line within a | +| | comment without breaking the comment. | +| | | +| laststatus | This makes vim show a status line even when | +| set ls=2 | only one window is visible. | +| | | +| shortmess | This shortens about every message to a minimum | +| set shm=at | and thus avoids scrolling within the output of | +| | messages and the "press a key" prompt that goes | +| | with these. | +| | | +| tabstop | Effectively, how many columns of whitespace a | +| ts=4 | \t is worth. | +| | | +| softtabstop | How many columns of whitespace a tab keypress | +| sts=4 | or a backspace keypress is worth. | +| | | +| shiftwidth | How many columns of whitespace a “level of | +| sw=4 | indentation” is worth or a backspace keypress | +| | is worth. | +| | | +| textwidth | This explicitly sets the width of text to 80 | +| set tw=80 | characters. After each completion of a word in | +| | insert mode, vim checks whether its end is past | +| | this width; if so then it will break the word | +| | onto the next line. Note that vim will remove | +| | trailing spaces when applying the word wrap - | +| | a feature which many editors are missing (and | +| | which will leave trailing spaces, of course). | +| | | +| | NOTE: The word wrap applies only when the | +| | *completed* word goes over the line; when you | +| | insert a word before that which moves other | +| | words over the line then vim will *not* break | +| | the words at the end of the line onto the next | +| | line! Programmers certainly don't want that. | +| | It's a feature!! | +| | | +| | | +| whichwrap | There are several commands which move the | +| set ww=<,>,h,l | cursor within a line. When you get to the | +| | start/end of a line then these commands will | +| | fail as you cannot goon. However, many users | +| | expect the cursor to be moved onto the | +| | previous/next line. Vim allows you to chose | +| | which commands will "wrap" the cursor around | +| | the line borders. In this particular example | +| | left/right, as well as the 'h' and 'l', | +| | keys to do that. | +| | | +| comments | Vim can reformat text and preserve comments | +| set com=b:#,:%,n:> | (i.e. commented lines) even when several kinds | +| | of comment indentations "nest" within. This is | +| | particularly useful for reformatting quoted | +| | text in Email and News. | +| | | +| list listchars | This option is cool! Or let's say that "other | +| set list | editors don't have at all". These characters | +| set lcs=tab:»· | are called "list characters" as they are | +| set lcs+=trail:· | related to the list option of vanilla vi. | +| | This will show the end-of-lines by adding a '$' | +| | sign after the last character of each line, and | +| | by replacing all TABs by '^I'. However, it is | +| | much nicer to have TABs shown in expanded form. | +| | Vim takes it one step further by also making | +| | trailing spaces visible. Being able to see | +| | EOLs, TABs, and trailing space has become an | +| | absolute MUST with every editor. | +| | | ++------------------------+-----------------------------------------------------+ + +In summary, there are MANY configurations that can be applied to vim in just a +few lines of text! As a best practice, test vim out without any configuration +applied, then slowly add in needed features. A good *starter* configuration file +might look something like this: + ++------------------------------------------------------------------------------+ +| Starter VIMRC | ++------------------------------------------------------------------------------+ +| | +| set ai nocp hid ru sc | +| filetype plugin indent on | +| syntax on | +| set bs=2 ls=2 shm=at tw=72 sw=4 ts=4 sts=4 ww=<,>,h,l | +| | ++------------------------------------------------------------------------------+ + + +References +________________________________________________________________________________ + +[0] https://github.com/vim/vim +[1] http://www.guckes.net/vim/setup.html diff --git a/wiki/software/wpa_supplicant/index.txt b/wiki/software/wpa_supplicant/index.txt @@ -0,0 +1,143 @@ +WPA_SUPPLICANT [0] +________________________________________________________________________________ + +wpa_supplicant is a cross-platform supplicant with support for WEP, WPA and WPA2 +(IEEE 802.11i). It is suitable for desktops, laptops and embedded systems. It is +the IEEE 802.1X/WPA component that is used in the client stations. It implements +key negotiation with a WPA authenticator and it controls the roaming and IEEE +802.11 authentication/association of the wireless driver. + + +Configuration +________________________________________________________________________________ + +Begin by first verifying that you have wpa_supplicant installed: + ++------------------------------------------------------------------------------+ +| | +| $ kiss b wpa_supplicant && kiss i wpa_supplicant | +| | ++------------------------------------------------------------------------------+ + +At this point, you will want to create a wpa_supplicant file to store your +wireless network information and credentials: + ++------------------------------------------------------------------------------+ +| | +| $ mkdir -p /etc/wpa_supplicant | +| $ touch /etc/wpa_supplicant/wpa_supplicant.conf | +| | ++------------------------------------------------------------------------------+ + +The following wpa_supplicant.conf can be used as a *starter* configuration +file. Remember to replace the BSSID and PASSWORD with your actual wireless +network credentials. + ++------------------------------------------------------------------------------+ +| | +| # Allow users in the 'wheel' group to control wpa_supplicant | +| ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel | +| | +| # Make this file writable for wpa_gui / wpa_cli | +| update_config=1 | +| | +| network={ | +| ssid="BSSID" | +| psk="PASSWORD" | +| } | +| | ++------------------------------------------------------------------------------+ + +For additional network requirements, refer to the "wpa_supplicant" Arch Linux +Wiki page [0]. + + +Generating a Passphrase +________________________________________________________________________________ + +NOTE: This section is not required but HIGHLY recommended since storing your + password in clear text is not good practice. + +To allow for quicker connections to a network whose BSSID is already known, we +can make use of wpa_passphrase, a command line tool which generates the minimal +configuration needed by wpa_supplicant: + ++------------------------------------------------------------------------------+ +| | +| $ wpa_passphrase BSSID PASSWORD | +| | ++------------------------------------------------------------------------------+ + +Replace BSSID and PASSWORD with your actual wireless network credentials. The +output of this command can then be used to replace the network section of the +wpa_supplicant.conf file created in the previous section (just remember to +delete the line containing your password in clear text). + + +Manual Wireless Connection +________________________________________________________________________________ + +A new wireless connection can be manually started with the following command: + ++------------------------------------------------------------------------------+ +| | +| $ wpa_supplicant -B -i INTERFACE \ | +| -c /etc/wpa_supplicant/wpa_supplicant.conf | +| | ++------------------------------------------------------------------------------+ + +Replace INTERFACE with your appropriate wireless LAN interface name. After, +use your preferred method to manually obtain an IP address. For example, when +using dhcpcd, run the following: + ++------------------------------------------------------------------------------+ +| | +| $ dhcpcd INTERFACE | +| | ++------------------------------------------------------------------------------+ + +The wireless status connection can be verified by reviewing the output of the +following command: + ++------------------------------------------------------------------------------+ +| | +| $ ifconfig | +| | ++------------------------------------------------------------------------------+ + + +Managed Wireless Connection via dhcpcd +________________________________________________________________________________ + +Assuming that dhcpcd is already installed, busybox's runsv can be used to create +new managed services for wpa_supplicant and dhcpcd: + ++------------------------------------------------------------------------------+ +| | +| $ ln -s /usr/share/dhcpcd/hooks/10-wpa_supplicant \ | +| /usr/lib/dhcpcd/dhcpcd-hooks/ | +| $ ln -s /etc/sv/dhcpcd/ /var/service | +| | ++------------------------------------------------------------------------------+ + + +Tips and Tricks +________________________________________________________________________________ + +* A list of possible INTERFACE names can be obtained by running the following: + + +----------------------------------------------------------------------------+ + | | + | $ ls /sys/class/net | + | | + +----------------------------------------------------------------------------+ + +* While testing arguments/configuration it may be helpful to launch + wpa_supplicant in the foreground (i.e. without the -B option) for better + debugging messages. + + +References +________________________________________________________________________________ + +[0] https://wiki.archlinux.org/index.php/wpa_supplicant diff --git a/wiki/storage/disks/index.txt b/wiki/storage/disks/index.txt @@ -0,0 +1,603 @@ +STORAGE +________________________________________________________________________________ + +This article will provide general guidance on the process of preparing a disk +device (SSD or HDD) for a new installation of KISS Linux. Advanced storage +formats (e.g. RAID, LVM) are considered out of scope. + + +Index +________________________________________________________________________________ + +- Overview [0.0] + - Terminology [0.1] + - Tools [0.2] + +- Partitioning Schemata [1.0] + - Minimum Partition Layouts [1.1] + - Swap Partition vs File [1.2] + +- Partitioning Example [2.0] + +- Formatting [3.0] + - Filesystems [3.1] + - Swap Partition [3.2] + - Swap File [3.3] + +- fstab [4.0] +- References [5.0] + + +[0.0] Overview +________________________________________________________________________________ + +Next to kernel configuration, preparing a disk device for installing a Linux +distribution is one of the more intimidating topics for a new UNIX user to +tackle. This process is not only highly dependent on user circumstances (the +type of hardware you have access to, your file system needs, your backup +requirements, etc.), but the process varies based on the tools used for the job. +Therefore, the first step to a successful installation is understanding the +terminology and the tools which are required throughout the process. + + + [0.1] Terminology + ____________________________________________________________________________ + + +------------------+-------------------------------------------------------+ + | | | + | Block Device | Represents an abstract interface to the disk. | + | | User programs can use these block devices to | + | | interact with the disk without worrying about | + | | whether the drives are SATA, SCSI, or something | + | | else. (e.g. /dev/sd*, /dev/nvme0n*, etc) | + | | | + | Partition | Represent smaller, more manageable block devices. | + | | These can be thought of as the places where user | + | | data lives. | + | | | + | Filesystem | A filesystem allows for data to actually be written | + | | to a given partition. Filesystems vary in features, | + | | requirements, and read/write access. In short, a | + | | filesystem is the structure for a given partition. | + | | | + | DOS | The DOS disklabel setup uses 32-bit identifiers | + | | for the start sector and length of the partitions, | + | | and supports three partition types: primary, | + | | extended, and logical. Primary partitions have | + | | their information stored in the master boot | + | | record itself - a very small (usually 512 bytes) | + | | location at the very beginning of a disk. Due to | + | | this small space, only four primary partitions | + | | are supported (for instance, /dev/sda1 to | + | | /dev/sda4). This is the old format for disklabels. | + | | | + | GPT | GPT (GUID Partition Table) setup uses 64-bit | + | | identifiers for the partitions. The location in | + | | which it stores the partition information is much | + | | bigger than the 512 bytes of a DOS disklabel, | + | | which means there is practically no limit on the | + | | amount of partitions for a GPT disk. Also the | + | | size of a partition is bounded by a much greater | + | | limit (almost 8 ZB - yes, zettabytes). A GPT disk | + | | is required for UEFI systems. | + | | | + | ROOTFS | ROOTFS (Root Filesystem) is the primary partition | + | | where the entire system is directly or indirectly | + | | mounted to. This is commonly referred to as '/'. | + | | | + | BOOT | The boot partition is where important files | + | | required at boot time, such as the kernel, are | + | | stored. This partition is required only on UEFI | + | | systems. It is usually mounted at /boot. | + | | | + | HOME | This partition is where most user data is stored. | + | | It is usually mounted at /home. | + | | | + | SWAP | Swap space can take the form of a disk partition | + | | or a file. Users may create a swap space during | + | | installation or at any later time as desired. | + | | Swap space can be used for two purposes: to | + | | extend the virtual memory beyond the installed | + | | physical memory (RAM), and also for hibernation | + | | or for suspend-to-disk support. | + | | | + +------------------+-------------------------------------------------------+ + + Some useful facts and things to keep in mind: + + Due to using 32-bit identifiers, DOS partitioning tables cannot handle disks + that are >2 TBs in size. + + Unless an extended partition is created, DOS disk labels supports a maximum + of four partitions. + + Using GPT on a BIOS-based computer works, and is referred to as a hybrid + setup. This type of setup requries a 1MB BIOS boot partition (unformatted) + so that extra data can be stored by the bootloader (like GRUB2). This setup + is useful in cases where more than four primary or secondary partitions are + required for a system. + Unfortunately this has several limitations. For instance, you cannot + dual-boot with a Microsoft Windows operating system, as Windows will boot in + UEFI mode if it detects a GPT partition label. Also note that some buggy + (old) motherboard firmware configured to boot in BIOS/CSM/legacy mode might + also have problems with booting from GPT labeled disks. As such, this style + is undesireable, and in general it is a good idea to use GPT in cases where + UEFI can be used. + + UEFI/GPT and BIOS/MBR are not synonymous. UEFI/BIOS refer to particular + types of systems that utilize the Unified Extensible Firmware Interface or + the Basic Input/Output System. This is determined strictly by the + motherboard used in a given system. GPT/DOS, however, refer to particular + disk labels: GUID Partition Tables versus the DOS label. These types + directly limit the structures available on any given disk drive - both the + number of partitions available, as well as the size of any given partition. + A good rule of thumb, however, is that UEFI systems use GPT disk labels, + BIOS systems use DOS disk labels, and hybrid systems use BIOS + GPT. + + The BOOT partition is a source of much confusion for users. For instance, + it is erroneously claimed that it must be mounted to /efi, or that kernel + images should be named vmlinuz.efi. + In point of fact, it is only necessary on UEFI systems, though it may be + useful on BIOS systems. The BOOT partition need not be mounted to /efi. + Indeed, the only requirements are that it be formatted to FAT32 (in the case + of UEFI systems), and be at least 100MB in size. The recommended minimum + size for UEFI systems is 256MB. + That the kernel be named vmlinuz.efi serves only to make the fact that it + is a UEFI system explicit. + If users intend on using a multiboot system, a single BOOT partition can be + shared by all operating systems. + + An important point of consideration is whether or not a separate HOME + partition should be used. This is useful in cases where users wish to keep + their data in a location separate from their operating system, for instance + in cases of critical failures requiring the OS to be reinstalled, or if + users wish to encrypt their personal data separately from their core OS. + This separation between / and /home allow users to easily migrate their data + across many different operating systems; they need only remount the HOME + partition to /home on the new system. In general, this is recommended. + + In addition to a separate HOME, several other additional partition options + exist. For instance, a separate var (/var) and data partitions can be used. + Separate data partitions are useful in instances where users would like to + easily share data across different operating systems, as allowing write + access to a user's home directory is a security risk. A separate /var is + useful in niche cases where /usr is read-only. For more detailed information + on filesystem structures, refer to the Filesystem Hierarcy Standard [0]. + Additionally, the Linux From Scratch project has some useful rationales [1]. + + + [0.2] Tools + ____________________________________________________________________________ + + Depending on which live environment the user chooses for installing a KISS + Linux system, the tools available vary. On most UNIX systems, the following + can usually be expected: + + - fdisk: a dialogue driven partition manipulator [2] + - gdisk: GPT fdisk (note that busybox fdisk also supports GPT) [3] + - cfdisk: a partition editor with a curses-based UI, part of util-linux [4] + - parted: a GNU partition editor [5] + + It is also possible to use the live CD version of parted, GParted [6], to + partition disks, and it offers many other useful features for disk + management and data recovery. + + In general, most programs can handle the majority of use-cases. The tool of + choice is almost entirely user preference. However, some utilities have + powerful and advanced features that can aid in fixing damaged disks. fdisk + is one such program, and is useful in cases where more fine-grained control + is required. For general system setup, however, any tool will do. + + +[1.0] Partitioning Schemata +________________________________________________________________________________ + +Great care should be taken when picking a partition structure, as changing it +afterwards is (generally) a difficult endeavor. Ensure that the chosen structure +meets your use case. Things to consider include whether or not a swap partition +is needed, whether to use a separate home partition, whether separate partitions +are needed for general data storage (like music or photos), and whether +dual-booting is desired. + + + [1.1] Minimum Partition Layouts + ____________________________________________________________________________ + + The number of partitions required is highly variable and dependent on the + use case. The following table provides examples of common partition + schemata, formats, and recommended minimum sizes: + + +----------------------------+---------------------------------------------+ + | Schemata Description | Partition (Type, Format, Size) | + +----------------------------+---------------------------------------------+ + | | | + | GPT + UEFI (with /home) | /dev/sda1 (BOOT, FAT32, 256MB) | + | | /dev/sda2 (ROOTFS, EXT4, 30GB ) | + | | /dev/sda3 (HOME, EXT4, * ) | + | | | + | Legacy DOS (with swap) | /dev/sda1 (SWAP, swap, RAM ) | + | | /dev/sda2 (ROOTFS, EXT4, * ) | + | | | + | Hybrid BIOS/GPT | /dev/sda1 (BIOS BOOT, XXXX, 1MB ) | + | | /dev/sda2 (SWAP, swap, RAM ) | + | | /dev/sda3 (ROOTFS, EXT4, xxxGB) | + | | /dev/sda4 (HOME, XFS, yyyGB) | + | | /dev/sda5 (DATA, BTRFS, zzzGB) | + | | | + +----------------------------+---------------------------------------------+ + + The boot partition is generally only used for storing kernels or an + initramfs. As these files are usually very small (<20MB), 256MB is more + than enough to accomodate most use-cases. 512MB is plenty. A separate BOOT + is only required on UEFI systems. + + In cases where no other additional partition is desired, the ROOTFS or HOME + partition should span the remainder of the disk. + + For source-based distributions like KISS, maximizing the amount RAM that can + be used is paramount for successful builds, especially for large packages + such as rust, firefox, or qt5-webengine. If the amount of RAM available is + less than 8GB, the usage of a swap partition or swap file is strongly + recommended to avoid build failures due to out-of-memory (OOM) issues. A + decent rule of thumb for swap size is to have the same amount of swap as + you have RAM. + + These examples only serve to show a minimum partition layout required for + each type of disk style (UEFI + GPT, BIOS + DOS, hybrid). + + + [1.2] Swap Partition vs File + ____________________________________________________________________________ + + When considering swap space, there are benefits and tradeoffs to certain + choices. The traditional recommendation has been to create a swap partition + as close to the first partition as possible, that is at least half the + amount of RAM available - this number is a sliding scale and varies by use + case. For instance, if few RAM intensive programs are going to be used, and + little compiling will be done on the host system, less swap space is needed + (if any at all). + + Historically, swap was placed at the beginning of disks as this allowed for + the fastest possible seek times on traditional spinning disk drives (hard + drives). This was preferred because disk access times are orders of + magnitude slower than RAM access times, and long swap operations result in + a desktop feeling 'slow' or 'laggy'. However, with the rise in popularity + of solid state drives (and, more recently, NVMe based storage), along with + the precipitous decrease in storage space cost, the requirement of a + separate swap partition has laxed. If users have access to low latency, + large storage drives, a swap file may be a preferable alternative. + + Swap files allow for ondemand, resizeable swap spaces. Swap may not be + necessary for day-to-day operation but only in cases where large builds are + happening. With access to these newer technologies, users can simply create + a file and define it to be a dedicated swap location which is used + identically to the traditional swap partition. This has left the need for a + swap partition largely to cases where solid state storage is not an option. + + For more modern systems, swap files are in general preferable to partitions. + Care should be taken, however. Changes may occur outside of the user's + control that necessitate intervention. For instance, if a swapfile + disappears but is still referenced in /etc/fstab, disk mounting will fail + at boot and the system will drop users into an emergency shell. + Additionally, file fragmentation can cause swap files to become unreliable. + Finally, kernel updates could potentially cause issues [7]. + + In addition to swap, @/zswap and @/zram are useful options to consider for + maximizing swap usage and memory management. + + +[2.0] Partitioning Example +________________________________________________________________________________ + +The following is a step-by-step partitioning example. + +PLEASE BE AWARE: The following commands can cause irreparable damage to the +data on your drives. Ensure that the data on these drives is backed up to a +separate device, and make sure you select the correct device for partitioning. + +Again, these commands are dangerous and WILL CAUSE DATA LOSS. + +In order to identify the correct disk, there are several commands that can help + ++------------------------------------------------------------------------------+ +| | +| $ fdisk -l | +| $ sfdisk -l | +| $ parted -l | +| $ lsblk | +| | ++------------------------------------------------------------------------------+ + +While partitioning disks, you will be asked multiple questions. These include +the starting sector of the partition, the last sector of the partition, and the +hex code for that partition. + +Generally, using the default as the first sector is the best choice - this will +ensure there are no strange breaks between partitions. + +Most programs support relative last sector locations. Therefore, instead of +typing out the desired sector number, one need only write '+400GB' to make the +partition start at the first available sector and continue for the next 400GB. + +Hex codes or partition IDs are hexadecimal identifiers which the kernel and +filesystem programs can interpret, and programs like fdisk and cfdisk will use +the hex code of a given partition to display a useful fact about the partition, +like that it's specifically an EFI partition, or a Linux root partition, or a +Solaris partition. Because GPT uses 64-bit partitions identifiers, far more +partition types are available for use on GPT systems over MBR systems. + +Be aware that altering partitions on in-use disks could cause data corruption, +and the changes in partition layout may not be available until the next reboot. + +This example assumes the target device block of /dev/nvme0n1, using gdisk +for the actual partitioning process. + +To create a GPT + EFI disk with a separate /home, + ++------------------------------------------------------------------------------+ +| | +| $ gdisk /dev/nvme0n1 | +| | +| # Enter '?' for a list of available commands | +| | +| # Delete partition data by creating a new GPT: | +| $ o | +| This option deletes all partitions and creates a new GPT. | +| Proceed? (Y/N): y | +| | +| # Create Partition 1 (/boot): | +| $ n | +| Partition Number: (RETURN key for 1) | +| First sector: (RETURN key for first available) | +| Last sector: +128M | +| Hex Code (L to show codes): ef00 | +| | +| # Create Partition 2 (ROOTFS): | +| $ n | +| Partition Number: (RETURN key for 2) | +| First sector: (RETURN key for first available) | +| Last sector: +30G | +| Hex Code: 0304 | +| | +| # Create Partition 3 (HOME): | +| $ n | +| Partition Number: (RETURN key for 3) | +| First sector: (RETURN key for first available) | +| Last sector: (RETURN key for rest of disk) | +| Hex Code: 0302 | +| | +| # Write Partition Table To Disk: | +| $ w | +| Do you want to proceed? (Y/N): Y | +| | ++------------------------------------------------------------------------------+ + +cfdisk may be preferable to users who prefer a more visual representation of +partition manipulation and a constantly updating table of information on the +current partition layout and structure. + + +[3.0] Formatting +________________________________________________________________________________ + +Now that the disks have been partitioned, it is time to create the relevant +filesystems for each partition. + + + [3.1] Filesystems + ____________________________________________________________________________ + + There are many different filesystems to choose from on any given Linux + system. Which filesystem is used depends almost entirely on the use-case of + the system. For simple data storage read only by UNIX systems, EXT4 is a + perfectly normal choice. For data that needs to be accessible to Windows, + FAT or NTFS is required. The Apple Filesystem (APFS) is used by Macs. + In the simple case where only Linux systems require access to a given + partition, many choices exist. Below is a list of filesystems which are + available in KISS either in the official repository or in community. + + +--------------+------------------------+----------------------------------+ + | Filesystem | Package | Command | + +--------------+------------------------+----------------------------------+ + | | | | + | swap | core/busybox | mkswap | + | EXT2/3/4 | extra/e2fsprogs | mkfs.ext2/3/4 | + | DOS/FATxx | extra/dosfstools | mkfs.dos/fat/vfat | + | XFS | extra/xfsprogs | mkfs.xfs | + | BTRFS | community/btrfs-progs | mkfs.btrfs | + | NTFS | community/ntfs-3g | mkfs.ntfs | + | | | | + +--------------+------------------------+----------------------------------+ + + Other filesystems exist with varying degrees of popularity, including JFS, + ReiserFS, and ZFS. The community repository is an excellent place to share + work in including these filesystems in KISS! Others are available in + user-created repositories. ZFS is one such example [8]. Due to licensing + restrictions, ZFS requires more work to use than other filesystems. + + EXT4 is a solid, general purpose filesystem. For UEFI systems, FAT32 is a + required filesystem for the BOOT partition. BTRFS is an experimental + filesystem which sees heavy development by organizations like Facebook, + and offers a different way of managing storage than more traditional (EXT, + DOS, NTFS) filesystems. All of these have built-in kernel support. + + For a more complete list of other filesystem options and what limitations + and features exist for them, refer to the Arch Wiki [9]. + + Continuing from the partition example in [2.0], we will make a FAT32 + parition on BOOT (/dev/nvme0n1p1), and an EXT4 partition on ROOTFS and HOME + (/dev/nvme0n1p2 and /dev/nvme0n1p3, respectively): + + +--------------------------------------------------------------------------+ + | | + | $ mkfs.ext4 /dev/nvme0n1p2 | + | $ mkfs.ext4 /dev/nvme0n1p3 | + | $ mkfs.fat -F32 /dev/nvme0n1p1 | + | | + | $ mount /dev/nvme0n1p2 /mnt | + | $ mount /dev/nvme0n1p3 /mnt/home | + | $ mount /dev/nvme0n1p1 /mnt/boot | + | | + +--------------------------------------------------------------------------+ + + + [3.2] Swap Partition + ____________________________________________________________________________ + + To set up a partition as a Linux swap space, the mkswap command is used. + Replace X with the drive where the swap partition is located, and Y by the + partition on that drive that will be formatted as swap. + + +--------------------------------------------------------------------------+ + | | + | $ mkswap /dev/sdXY | + | $ swapon /dev/sdXY | + | | + +--------------------------------------------------------------------------+ + + + [3.3] Swap File + ____________________________________________________________________________ + + As an alternative to creating an entire partition, a swap file offers + similar functionality, and the added benefits of being able to vary its size + on-the-fly, as well as being more easily removed. This may be especially + desirable if disk space is at a premium. + + The most straightforward way to create a swap file is to use dd: + + +--------------------------------------------------------------------------+ + | | + | $ dd if=/dev/zero of=$LOCATION bs=$BYTES count=$BLOCKS | + | | + +--------------------------------------------------------------------------+ + + $LOCATION is where the swapfile should be made. Assume $LOCATION=/swapfile. + + $BYTES is the size of each block to be written to the file. Disks have + varying supported block sizes; choosing the correct size for the partition + where the swapfile will be is important for optimizing read/write + throughput. dd defaults to 512 bytes, but this is suboptimal for drives + with larger supported block sizes. To determine the block size for your + device, you can use stat: + + +--------------------------------------------------------------------------+ + | | + | $ stat -fc %s . | + | | + +--------------------------------------------------------------------------+ + + For instance, if the result is 4096, $BYTES=4k should be chosen. + + $BLOCKS is the number of blocks of size $BYTES you wish to write to + $LOCATION. $BLOCKS determines the final size of the swapfile. + + $BYTES and $BLOCKS can be suffixed by b (512 bytes), kB (1,000 bytes), k + (1,024 bytes), MB (a thousand kB), M (a thousand k), GB (a million kB), or + G (a million k). + + To create a 16G swapfile at /swapfile with a 4k block size, + + +--------------------------------------------------------------------------+ + | | + | $ dd if=/dev/zero of=/swapfile bs=4k count=4M | + | | + +--------------------------------------------------------------------------+ + + Set the permissions, create the swap filesystem, and activate it as swap, + + +--------------------------------------------------------------------------+ + | | + | $ chmod 600 /swapfile | + | $ mkswap /swapfile | + | $ swapon /swapfile | + | | + +--------------------------------------------------------------------------+ + + To remove a swap file, it's as simple as disabling and deleting it, + + +--------------------------------------------------------------------------+ + | | + | $ swapoff /swapfile | + | $ rm -f /swapfile | + | | + +--------------------------------------------------------------------------+ + + +[4.0] fstab +________________________________________________________________________________ + +The fstab file contains a list of partitions with their filesystem type, their +mount location, and the options they should be mounted with. The mount program +will read the fstab file (by default /etc/fstab) and will mount all of the +partitions and filesystems for you. This is useful for automatically mounting +things like BOOT, HOME, and tmpfs during the init process. + +The fstab is NOT required - the kernel location and ROOTFS should be specified +in the bootloader entry. If you find yourself mounting the same partitions +repeatedly with consistent options, the fstab file serves to automate this +prcess for you. + +Here is an example fstab, which will mount ROOTFS to /, BOOT to /boot, HOME to +/home, enable the swap file, and mount some important virtual filesystems: + ++------------------------------------------------------------------------------+ +| | +| # device mount-point type options dump fsck order | +| | +| /dev/sda2 / ext4 defaults 0 1 | +| /dev/sda1 /boot vfat defaults 0 2 | +| /dev/sda3 /home ext4 defaults 0 2 | +| /swapfile none swap defaults 0 0 | +| tmpfs /tmp tmpfs rw,nodev,nosuid 0 0 | +| proc /proc proc defaults 0 0 | +| sysfs /sys sysfs defaults 0 0 | +| devpts /dev/pts devpts gid=4,mode=620 0 0 | +| | ++------------------------------------------------------------------------------+ + +tmpfs, proc, sysfs, and devpts should be mounted during the init process. +Therefore, proc, sysfs, and devpts can be left out of the fstab. A reason to +keep tmpfs in the fstab is to use it for building packages in RAM. To only do +this for certain packages, see [10]. + +Devices can be referred to either by their /dev pathname, by a label, by UUID, +or by Part-UUID. For systems with multiple drives, it is recommended to use +UUIDs or labels instead of /dev pathnames, as these are volatile and could +change during each system reboot. See [11] for details on identifying disks. +NOTE: busybox does not support mounting disks by Part-UUID. + +The dump entry refers to the backup utility, dump [12]. + +fsck order gives the order in which a filesystem check should be ran in. ROOTFS +should be specified with a 1. All other filesystems should be specified with 2 +or 0. swap and virtual filesystems should not be fsck'd. + +There are a large number of options that you can choose from for mounting +partitions. 'defaults' is a basic, filesystem-independent option which will +mount the partition rw,suid,dev,exec,auto,nouser,async. For an explanation of +these options (and far more detailed information on the fstab) see [13]. + +CAUTION: an improperly configured fstab will result in the user being dumped +into an emergency shell! Even a small typo will result in this. If it occurs, +simply check the fstab for errors, mount the partitions that failed to be +mounted, and exit the emergency shell. + + +[5.0] References +________________________________________________________________________________ + +[0] https://refspecs.linuxfoundation.org/fhs.shtml +[1] http://linuxfromscratch.org/lfs/view/stable/chapter02/creatingpartition.html +[2] https://man7.org/linux/man-pages/man8/fdisk.8.html +[3] http://rodsbooks.com/gdisk/ +[4] https://linux.die.net/man/8/cfdisk +[5] https://gnu.org/software/parted/manual/parted.html +[6] https://gparted.org/ +[7] https://bugzilla.kernel.org/show_bug.cgi?id=207585 +[8] https://github.com/jedavies-dev/kiss-zfs +[9] https://wiki.archlinux.org/index.php/file_systems +[10] https://k1sslinux.org/package-manager#6.3 +[11] https://wiki.archlinux.org/index.php/Fstab#Identifying_filesystems +[12] https://linux.die.net/man/8/dump +[13] https://man7.org/linux/man-pages/man5/fstab.5.html diff --git a/wiki/storage/index.txt b/wiki/storage/index.txt @@ -0,0 +1,6 @@ +STORAGE +________________________________________________________________________________ + +- @/disks +- @/zram +- @/zswap diff --git a/wiki/storage/zram/index.txt b/wiki/storage/zram/index.txt @@ -0,0 +1,124 @@ +ZRAM [0] +________________________________________________________________________________ + +zram is a kernel feature which allows for the creation of compressible ramdisks, +or RAM-based block devices. These virtual devices can be used to extend the +amount of RAM available on a system by utilizing in-RAM compression, in a +similar sense to how swap is used in low-memory conditions. Unlike zswap, zram +does not require a swapfile or swap partition to exist on a drive. As a result, +zram can be incredibly useful on systems where memory availability is low and +disk-space is at a premium. + + +Prerequisites +________________________________________________________________________________ + +zram is managed by the kernel and requires very little user intervention to +enable and configure. First, ensure zram is enabled in the kernel: + ++------------------------------------------------------------------------------+ +| | +| General setup ---> | +| <*> Support for paging of anonymous memory (swap) | +| | +| Memory Management options ---> | +| <*> Memory allocator for compressed pages | +| | +| Device Drivers ---> | +| <*> Block devices ---> | +| <M> Compressed RAM block device support | +| | +| # To use the lz4 algorithm with zram, | +| Cryptographic API ---> | +| <*> LZ4 compression algorithm | +| | +| | ++------------------------------------------------------------------------------+ + +lz4 is available in community. The default compression algorithm is lzo and +CONFIG_CRYPTO_LZO=y/m is forced when CONFIG_ZRAM=y/m. + +Building compressed RAM block devices as a module is recommended because it +enables runtime block device creation. If it is built-in to the kernel, pass +zram.num_devices=X in the kernel commandline (bootloader or built-in). + + +Setup +________________________________________________________________________________ + +Compressed block devices can be setup on-the-fly or at boot-time. A quick +method using an /etc/rc.d/zram.{boot,pre.shutdown} script is shown below. +Because multiple ramdisks are allowed, it might be preferable to create +multiple zram devices for better utilization on multicore systems. + +The compression used on zram block devices cannot be changed once the device is +initialized. This means that you cannot swap compression algorithms at run-time, +unlike with zswap. + +$SIZE below can be given in bytes or suffixed by M,G. + ++------------------------------------------------------------------------------+ +| /etc/rc.d/zram.boot | ++------------------------------------------------------------------------------+ +| #!/bin/sh -e | +| | +| # Create four zram devices for swap, one for tmpfs | +| | +| modprobe zram num_devices=5 | +| | +| # create zram devices of $SIZE 2G | +| # Use lz4 compression on the devices | +| # Mark the devices as swap devices | +| # Enable the swap devices | +| | +| for dev in 0 1 2 3; do | +| echo lz4 > "/sys/block/zram$dev/comp_algorithm" | +| echo 2G > "/sys/block/zram$dev/disksize" | +| mkswap "/dev/zram$dev" | +| swapon "/dev/zram$dev" -p 10 | +| done | +| | +| # Create a 4G ext4 zram device to use as tmpfs with lz4 compression | +| | +| echo lz4 > /sys/block/zram4/comp_algorithm | +| echo 4G > /sys/block/zram4/disksize | +| mkfs.ext4 /dev/zram4 | +| mount /dev/zram4 /tmp | +| | +| # /tmp requires sticky bit permissions for nonroot user access | +| chmod 1777 /tmp | +| | ++------------------------------------------------------------------------------+ + ++------------------------------------------------------------------------------+ +| /etc/rc.d/zram.pre.shutdown | ++------------------------------------------------------------------------------+ +| #!/bin/sh -e | +| | +| # Disable the swap devices | +| # Reset the swap devices | +| for dev in 0 1 2 3; do | +| swapoff "/dev/zram$dev" | +| echo 1 > "/sys/block/zram$dev/reset" | +| done | +| | +| # Unmount /tmp, reset zram device | +| umount /dev/zram4 | +| echo 1 > /sys/block/zram4/reset | +| | ++------------------------------------------------------------------------------+ + +Note: because zram has a 2:1 compression ratio, a total disk size of no more +than twice the amount of available RAM should be selected - otherwise, space +will be wasted. + +In addition to manipulating values in /sys/block/zramX/*, users can use the +zramctl program provided by util-linux to manage their zram devices. See [1] for +more information. + + +References +________________________________________________________________________________ + +[0] https://kernel.org/doc/Documentation/blockdev/zram.txt +[1] https://man7.org/linux/man-pages/man8/zramctl.8.html diff --git a/wiki/storage/zswap/index.txt b/wiki/storage/zswap/index.txt @@ -0,0 +1,92 @@ +ZSWAP [0] +________________________________________________________________________________ + +zswap is a feature built-in to the Linux kernel [1] which allows users to +utilize compressed caches in RAM as swap pages. Instead of the kernel +immediately swapping pages in RAM and writing them to the hard drive, wasting +time on I/O operations, it compresses them into a pool in RAM. Only when the +available RAM is exhausted will the kernel then write-out the least recently +used page as an uncompressed file to swap on the drive. + +When swap will be used, zswap should provide performance improvements. + + +Prerequisites +________________________________________________________________________________ + +zswap works in conjuction with swap and is handled entirely by the kernel. As +such, there are only two requirements: zswap enabled in the kernel and a +swapfile or swap partition on the system. + +Several compression options are available for zswap. The choice is use-case +dependent, with the primary trade-offs being speed or size. See [2] for example +benchmarks of compressors in general. + +Ensure zswap (CONFIG_ZSWAP) support and a compressor are enabled in the kernel: + ++------------------------------------------------------------------------------+ +| | +| Memory Management options ---> | +| <*> Compressed cache for swap pages | +| Compressed cache for swap pages default compressor (xxx) | +| Compressed cache for swap pages default allocator (xxx) | +| <*> Enable the compression cache for swap pages by default | +| | ++------------------------------------------------------------------------------+ + +Either set CONFIG_ZSWAP_DEFAULT_ON=y in the kernel config or add zswap_enabled=1 +to your kernel command line (via the bootloader or the built-in command line) to +have zswap enabled at boot-time. To enable zswap at runtime, + ++------------------------------------------------------------------------------+ +| | +| $ echo 1 > /sys/module/zswap/parameters/enabled | +| | ++------------------------------------------------------------------------------+ + +zswap has many options that can also be configured at runtime, including which +compressor is in use. To see them all, + ++------------------------------------------------------------------------------+ +| | +| $ grep -R . /sys/module/zswap/parameters | +| | ++------------------------------------------------------------------------------+ + +For information on setting up a swapfile or swap partition, see @/storage/disks. + + +zbud versus z3fold versus zsmalloc +________________________________________________________________________________ + +There are three different allocators to choose from for compressed pages: + ++-------------+----------------------------------------------------------------+ +| Allocator | Description | +|-------------+----------------------------------------------------------------| +| | | +| zbud | Uses a 2:1 compressed:uncompressed page allocation (legacy) | +| z3fold | Uses a 3:1 ratio | +| zsmalloc | Designed for zram - better under low memory conditions | +| | | ++-------------+----------------------------------------------------------------+ + +In general, z3fold should be preferred to zbud; the latter is supported solely +for compatibility purposes. z3fold provides a better compression ratio and +should be preferred when possible. + +zsmalloc has a very different page allocation method than either zbud or z3fold, +and provides for greater storage density. However, zsmalloc does not implement +compressed page eviction; it can only reject new pages when full. + +For more information on z3fold and zsmalloc, see [3] and [4]. + + +References +________________________________________________________________________________ + +[0] https://kernel.org/doc/html/latest/vm/zswap.html +[1] https://lkml.iu.edu/hypermail/linux/kernel/1212.1/01472.html +[2] https://github.com/lz4/lz4 +[3] https://kernel.org/doc/html/latest/vm/z3fold.html +[4] https://kernel.org/doc/html/latest/vm/zsmalloc.html diff --git a/wiki/wayland/index.txt b/wiki/wayland/index.txt @@ -0,0 +1,4 @@ +Wayland +________________________________________________________________________________ + +- @/install-wayland diff --git a/wiki/wayland/install-wayland/index.txt b/wiki/wayland/install-wayland/index.txt @@ -0,0 +1,160 @@ +Wayland +________________________________________________________________________________ + +Wayland [0] is a display protocol that aims to be a simpler and modern +replacement for the X Window System. [1] The Wayland protocol follows a +client–server model in which clients are the graphical applications requesting +the display of pixel buffers on the screen, and the server (compositor) is the +service provider controlling the display of these buffers. [2] + +Unlike Xorg, which is at the center of the universe (and everyone must talk to), +Wayland puts the Linux kernel and its components (DRI, DRM, etc) in the middle. +This effectively leaves the Wayland compositor off in the corner as its little +more than a special application. [3] + +Wayland has been in development since September of 2008 [4] and is usable today +for a large number of use-cases. Some hardware configurations (namely NVIDIA +GPUs) [5] [6] and a number of features are not currently supported by +compositors. + + +Caveats +________________________________________________________________________________ + +While the Wayland protocol is more or less done, the growing list of compositors +are in differing stages of completeness. Xorg is still in wide use and a lot of +software still requires it. + +The major downside to Wayland (compositors) is the reduction in choice. While +the Wayland protocol does not define what a compositor shall depend on, they +typically lock the user into udev, libinput and systemd/logind. + +The lack of standardized, desktop-oriented protocols has created a situation +where software may only work in some compositors and not others. This should +improve over time as more protocols become standardized. + +- Limited hardware and driver support. [5] [6] [7] [8] +- Non-standard and compositor specific software. [10] [11] [12] +- No Wayland support in SDL 1 (must use XWayland). [13] +- Starting compositors without logind requires SUID permissions. [14] +- Locked into using udev. [15] + + +Benefits +________________________________________________________________________________ + +Wayland has a large number of benefits and improvements over Xorg. The above +caveats do not apply to everyone (or every system). Those unaffected or willing +to live with the caveats will have no problem swapping over. + +- Less moving parts [13], although some software still heavily relies on the + Xorg libraries (Mesa [16], Firefox [17], etc). +- No screen tearing by design [18]. +- Hardware accelerated video playback in Firefox [19] and Webkit2GTK [20] + + +Prerequisites +________________________________________________________________________________ + +Though KISS does not support Wayland officially there is no problem in making it +capable through personal or 3rd party repositories. The official +repositories satisfy all dependencies. After "wayland" and "wayland-protocols" +are installed, some package adjustments are required to make them to known +citizens of your system. + +NOTE: From this point it is expected that "wayland" and "wayland-protocols" are + installed and you have forked the required packages with modified + configure flags at the beginning of KISS_PATH. [21] Managing repositories + +* Packages which need to be forked [23]: + + firefox --enable-default-toolkit=cairo-gtk3-wayland + gtk+3 --enable-wayland-backend + mesa -Dplatforms=x11,drm,wayland + + +* Packages which pick up Wayland automatically at compile time [23]: + [needs expansion and verification] + + cairo + intel-vaapi-driver + libva + mpv + pango + sdl2 + webkit2gtk + + +Install Wayland on top Xorg KISS +________________________________________________________________________________ + +Mesa must be rebuilt first, followed by the aforementioned packages [22] in +a dependency given ascending order. + +NOTE: kiss-revdepends is the tool you need. + +mesa, cairo, pango, gtk+3, firefox/webkit2gtk + qt5-wayland + mpv + libva, intel-vaapi-driver + sdl2 + +$ kiss b mesa && kiss i mesa && kiss b pango && kiss i pango ... + + +Install Wayland on top base KISS +________________________________________________________________________________ + +Starting off a fresh base installation there is no manual intervention needed as +everything _should_ be autoconfigured. +[needs reproduction] + + +Post installation +________________________________________________________________________________ + +* In environments without systemd/elogind/consolekit the XDG_RUNTIME_DIR + variable must be set manually. [23] Export this in your shellrc. + ++------------------------------------------------------------------------------+ +| .ashrc, .bashrc, .zshrc, etc | ++------------------------------------------------------------------------------+ +| | +| export XDG_RUNTIME_DIR=${XDG_RUNTIME_DIR:-/tmp/$(id -u)-runtime-dir} | +| | +| [ -d "$XDG_RUNTIME_DIR" ] || { | +| mkdir -p "$XDG_RUNTIME_DIR" | +| chmod 0700 "$XDG_RUNTIME_DIR" | +| } | +| | ++------------------------------------------------------------------------------+ + +* Install a Compositor of your choosing. + + +References +________________________________________________________________________________ + +[0] https://wayland.freedesktop.org/ +[1] https://wayland.freedesktop.org/faq.html#heading_toc_j_4 +[2] https://en.wikipedia.org/wiki/Wayland_(display_server_protocol) +[3] https://lwn.net/Articles/413335/ +[4] https://cgit.freedesktop.org/wayland/wayland/commit/?id=97f1ebe8d5c2e166fabf757182c289fed266a45a +[5] https://github.com/swaywm/sway/issues/490 +[6] https://drewdevault.com/2017/10/26/Fuck-you-nvidia.html +[7] $/swaywm/sway/wiki#nvidia-users +[8] https://wayland.freedesktop.org/building.html (Hardware / Drivers) + +[10] $/Alexays/Waybar +[11] $/any1/wayvnc +[12] $/fzwoch/obs-gnome-screencast +[13] https://hansdegoede.livejournal.com/22212.html +[14] $/swaywm/sway/wiki/Running-Sway-without-systemd +[15] $/swaywm/wlroots#building #udev +[16] $/kiss-community/repo/blob/master/extra/mesa/depends +[17] $/kiss-community/repo-bin/blob/main/bin/firefox/depends +[18] https://people.freedesktop.org/~daniels/lca2013-wayland-x11.pdf +[19] https://bugzilla.mozilla.org/show_bug.cgi?id=1610199 +[20] (webkit2gtk VAAPI source needed) +[21] #/kiss/managing-repositories +[22] https://wiki.gentoo.org/wiki/Sway#Other diff --git a/wiki/xorg/index.txt b/wiki/xorg/index.txt @@ -0,0 +1,9 @@ +XORG +________________________________________________________________________________ + +- @/keyboard-layout +- @/sx +- @/x11-forwarding +- @/x11vnc +- @/xinit +- @/xorg-server diff --git a/wiki/xorg/keyboard-layout/index.txt b/wiki/xorg/keyboard-layout/index.txt @@ -0,0 +1,52 @@ +SETTING THE KEYBOARD LAYOUT IN X +________________________________________________________________________________ + + +Using setxkbmap +________________________________________________________________________________ + + +First, install setxkbmap: + ++------------------------------------------------------------------------------+ +| | +| $ kiss b setxkbmap && kiss i setxkbmap | +| | ++------------------------------------------------------------------------------+ + +Available layouts can be found in /usr/share/X11/xkb/symbols/ and set from the +command line: + ++------------------------------------------------------------------------------+ +| | +| $ setxkbmap latam | +| | ++------------------------------------------------------------------------------+ + +Put the above command in ~/.xinitrc to load it whenever an X session is started. + + +Exiting xorg configuration files +________________________________________________________________________________ + +Create 00-keyboard.conf in /etc/X11/xorg.conf.d/ and edit the Xkb* options +below to suit your needs. [0] + ++------------------------------------------------------------------------------+ +| | +| Section "InputClass" | +| Identifier "system-keyboard" | +| MatchIsKeyboard "on" | +| Option "XkbLayout" "de" | +| Option "XkbModel" "pc105" | +| Option "XkbVariant" ",qwertz" | +| Option "XkbOptions" "grp:alt_shift_toggle" | +| EndSection | +| | ++------------------------------------------------------------------------------+ + + +References +________________________________________________________________________________ + +[0] https://www.x.org/releases/X11R7.5/doc/input/XKB-Config.html diff --git a/wiki/xorg/sx/index.txt b/wiki/xorg/sx/index.txt @@ -0,0 +1,74 @@ +SX [0] +________________________________________________________________________________ + +sx is a simple alternative to both xinit and startx for starting an Xorg +server. + + +Configuration +________________________________________________________________________________ + +Ensure that you have sx installed first: + ++------------------------------------------------------------------------------+ +| | +| $ kiss b sx && kiss i sx | +| | ++------------------------------------------------------------------------------+ + +The default XDG_DATA_HOME and XDG_CONFIG_HOME directories can be modified via +environment variables: + ++------------------------------------------------------------------------------+ +| | +| $ echo "export XDG_DATA_HOME=$HOME/.config" >> ~/.profile | +| $ echo "export XDG_CONFIG_HOME=$HOME/.config" >> ~/.profile | +| | ++------------------------------------------------------------------------------+ + +Create the required directories and rc file: + ++------------------------------------------------------------------------------+ +| | +| $ mkdir -p ~/.config/sx | +| $ touch ~/.config/sx/sxrc | +| $ chmod +x ~/.config/sx/sxrc | +| | ++------------------------------------------------------------------------------+ + +At this point, you can add content to your sxrc file. For example, if you +wanted to start sowm window manager, you could add the following: + ++------------------------------------------------------------------------------+ +| | +| $ echo "exec sowm" >> ~/.config/sx/sxrc | +| | ++------------------------------------------------------------------------------+ + +You should now be able to start your window manager and X server with sx: + ++------------------------------------------------------------------------------+ +| | +| $ sx | +| | ++------------------------------------------------------------------------------+ + + +Start After Login +________________________________________________________________________________ + +Add the following to the bottom of your ~/.profile file: + ++------------------------------------------------------------------------------+ +| | +| $ [ -z "$DISPLAY" ] && [ "$(tty)" = /dev/tty1 ] && exec sx | +| | ++------------------------------------------------------------------------------+ + +If you would like to remain logged in when the X session ends, remove exec. + + +References +________________________________________________________________________________ + +[0] https://github.com/Earnestly/sx diff --git a/wiki/xorg/x11-forwarding/index.txt b/wiki/xorg/x11-forwarding/index.txt @@ -0,0 +1,135 @@ +X11-FORWARDING [0] +________________________________________________________________________________ + +X11-Forwarding is a secure shell feature, which allows one to forward/tunnel +X11 connections through an existing SSH session. This is used to run X11 +programs on a server while the ssh-client displays the graphical window through +the user's X11-server. + + +Dependencies +________________________________________________________________________________ + +In most cases, you will already have the required dependencies. At minimum, +ensure that you have the following installed: + ++------------------------------------------------------------------------------+ +| | +| $ kiss b xorg-server && kiss i xorg-server | +| $ kiss b xauth && kiss i xauth | +| | ++------------------------------------------------------------------------------+ + + +Remote Server Configuration +________________________________________________________________________________ + +Configuring X11-Forwarding for a remote server is straightfoward and, once +completed, a viable alternative to most opensource VNC and RDP server options. +All that is required are a few modifications to configuration files that exist +on your remote X server: + ++------------------------------------------------------------------------------+ +| | +| $ echo "XauthLocation /usr/bin/xauth" >> /etc/ssh/sshd_config | +| $ echo "X11Fordwarding yes" >> /etc/ssh/sshd_config | +| | ++------------------------------------------------------------------------------+ + +At this point you are ready to test your server! + + +Client Configuration +________________________________________________________________________________ + +In order to connect to your remote server, you will need an SSH client that +supports X11-Forwarding, as well as an X server running on the same client. Some +popular cross-platform options include the following: + +* vcxsrv (recommended, server only) [1] +* MobaXterm (both SSH client and X server, for Windows only) [2] +* Xming (server only) [3] +* X410 (server only) [4] + +From the client side, connect to the server via SSH through your favorite +terminal application while passing the "-X" switch. Pay attention to any +errors that may occur on connection. More verbose output can be achieved by +passing the "-v" switch: + ++------------------------------------------------------------------------------+ +| | +| $ ssh -X -v user@localhost | +| | ++------------------------------------------------------------------------------+ + +You can now start any X program on the remote server, the output will be +forwarded to your local session: + ++------------------------------------------------------------------------------+ +| | +| $ xclock | +| | ++------------------------------------------------------------------------------+ + +This should create a new window with the xclock application on your client side +X server. + +Use an "&" at the end of the command to prevent tying up the terminal in +question: + ++------------------------------------------------------------------------------+ +| | +| $ xclock & | +| | ++------------------------------------------------------------------------------+ + + +Tips and Tricks +________________________________________________________________________________ + +* If your connection is slow, try enabling SSH compression by passing the "-C" + switch. + + +----------------------------------------------------------------------------+ + | | + | $ ssh -X -C user@localhost | + | | + +----------------------------------------------------------------------------+ + +* You can further improve your connection speed by using a cypher to connect to + the remove server. This can be passed as an argument using the "-c" switch + at the initialization of a new SSH connection. [5] + + +----------------------------------------------------------------------------+ + | | + | $ ssh -X -C -c aes256-ctr user@localhost | + | | + +----------------------------------------------------------------------------+ + +* Your remote system most likely has many cypher options already available for + you to choose from (es128-ctr, aes192-ctr, aes256-ctr, arcfour256, arcfour128, + aes128-cbc, 3des-cbc, blowfish-cbc, cast128-cbc, aes192-cbc, aes256-cbc, + arcfour, etc.) and each will vary in performance and security. Check out + websites that benchmark the various security cyphers and choose the one that + works best for you. [6] + +* Can you forward an entire desktop session? Why yes, you can! Instructions for + doing so vary per client, server configuration, and platform [7]. If you chose + vcxsrv as your client on a Windows host, then I would recommend checking out + the following youtube video: + + "Linux and Windows | X11 Forwarding with SSH | VNC Alternative" by knary + https://www.youtube.com/watch?v=UWlsS6Jaibc + + +References +________________________________________________________________________________ + +[0] https://wiki.archlinux.org/index.php/OpenSSH#X11_forwarding +[1] https://sourceforge.net/projects/vcxsrv/ +[2] https://mobaxterm.mobatek.net/ +[3] http://straightrunning.com/XmingNotes/ +[4] https://x410.dev +[5] https://cyberciti.biz/faq/speeding-up-ssh-x11-forwarding-with-unix-osx-linux-bsd/ +[6] https://blog.famzah.net/2010/06/11/openssh-ciphers-performance-benchmark/ +[7] https://blog.warbel.net/index.php/2018/02/21/using-xnest-or-putty-vcxsrv-to-start-a-full-remote-session/ diff --git a/wiki/xorg/x11vnc/index.txt b/wiki/xorg/x11vnc/index.txt @@ -0,0 +1,71 @@ +X11VNC [0] +________________________________________________________________________________ + +x11vnc allows one to view remotely and interact with real X displays (i.e. a +display corresponding to a physical monitor, keyboard, and mouse) with any VNC +viewer. + + +Dependencies +________________________________________________________________________________ + +Refer to the @/xorg/xorg-server page for X server and Window Manager setup and +configuration. + + +Configuration +________________________________________________________________________________ + +First verify that you have x11vnc installed: + ++------------------------------------------------------------------------------+ +| | +| $ kiss b x11vnc && kiss i x11vnc | +| | ++------------------------------------------------------------------------------+ + +Assuming that you have an X session already running, you can start x11vnc from +a virtual terminal: + ++------------------------------------------------------------------------------+ +| | +| $ x11vnc -forever | +| | ++------------------------------------------------------------------------------+ + +The "-forever" switch is not required, but prevents the x11vnc from exiting at +the end of a client session. For more information on this switch or additional +switch options, refer to the man page [1]. + + +Tips and Tricks +________________________________________________________________________________ + +* If x11vnc fails to start or you are not operating from a virtual terminal + (e.g. over SSH), you may also need to specify the xauthority file location in + addition to the display: + + +----------------------------------------------------------------------------+ + | "sx" example, configured per #/wiki/xorg/sx | + +----------------------------------------------------------------------------+ + | | + | $ x11vnc -forever -display :1 -auth /home/USER/.config/sx/xauthority | + | | + +----------------------------------------------------------------------------+ + | "startx" example, configured per #/wiki/xorg/startx | + +----------------------------------------------------------------------------+ + | | + | $ x11vnc -forever -display :1 -auth /home/USER/.Xauthority | + | | + +----------------------------------------------------------------------------+ + + Note: Remember to replace USER with the name of the regular user. + +* You can start x11vnc in the background by passing the optional "-bg" switch. + + +References +________________________________________________________________________________ + +[0] https://github.com/LibVNC/x11vnc +[1] https://linux.die.net/man/1/x11vnc diff --git a/wiki/xorg/xinit/index.txt b/wiki/xorg/xinit/index.txt @@ -0,0 +1,64 @@ +XINIT [0] +________________________________________________________________________________ + +The xinit program is used to start the X Window System server and a first client +program on systems that are not using a display manager such as xdm or in +environments that use multiple window systems. + + +Configuration +________________________________________________________________________________ + +Ensure that you have xinit installed first: + ++------------------------------------------------------------------------------+ +| | +| $ kiss b xinit && kiss i xinit | +| | ++------------------------------------------------------------------------------+ + +Create the required rc file as a regular user: + ++------------------------------------------------------------------------------+ +| | +| $ touch ~/.xinitrc | +| | ++------------------------------------------------------------------------------+ + +At this point, you can add content to your .xinitrc file. For example, if you +wanted to start sowm windows manager, you could add the following: + ++------------------------------------------------------------------------------+ +| | +| $ echo "exec sowm" >> ~/.xinitrc | +| | ++------------------------------------------------------------------------------+ + +You should now be able to start your X server with startx: + ++------------------------------------------------------------------------------+ +| | +| $ startx | +| | ++------------------------------------------------------------------------------+ + + +Start After Login +________________________________________________________________________________ + +Add the following to the bottom of your ~/.profile file: + ++------------------------------------------------------------------------------+ +| | +| $ [ -z "$DISPLAY" ] && [ "$(tty)" = /dev/tty1 ] && exec startx | +| | ++------------------------------------------------------------------------------+ + +If you would like to remain logged in when the X session ends, remove exec. + + +References +________________________________________________________________________________ + +[0] https://www.x.org/releases/X11R7.6/doc/man/man1/xinit.1.xhtml +[1] https://wiki.archlinux.org/index.php/Xinit diff --git a/wiki/xorg/xorg-server/index.txt b/wiki/xorg/xorg-server/index.txt @@ -0,0 +1,125 @@ +XORG-SERVER [0] +________________________________________________________________________________ + +The xorg-server, part of the X.Org releases, is the main component of the X +Window system which abstracts the hardware and provides the foundation for most +graphical user interfaces, like desktop environments or window managers, and +their applications. + + +[0.0] Index +________________________________________________________________________________ + +- Getting Started [1.0] +- Graphics Drivers [2.0] +- Window Managers [3.0] +- Remote X Session Management [4.0] + - VNC [4.1] + - x11-forwarding [4.2] +- References [5.0] + + +[1.0] Getting Started +________________________________________________________________________________ + +If you are following along from the KISS installation guide, you should already +have the following packages installed: + +* xorg-server +* xf86-input-libinput +* liberation-fonts (optional) + +In order to start the X window system server, you will also need to install +and configure _ONE_ of the following packages: + +* xinit (@/xinit) +* sx (@/sx) + + +[2.0] Graphics Drivers +________________________________________________________________________________ + +Depending on your graphics card hardware, one of the following graphics card +packages should also be installed: + +* xf86-video-amdgpu +* xf86-video-ati +* xf86-video-intel +* xf86-video-nouveau +* xf86-video-vesa + +Note: xf86-video-intel is not needed for Intel GPUs as the generic modesetting + driver built into Xorg works really well. + + +[3.0] Window Managers +________________________________________________________________________________ + +Note: Installing a window manager is entirely optional and based on user + preference. + +A window manager (WM) is system software that controls the placement and +appearance of windows within a windowing system in a graphical user interface. +There are many great WM solutions available for KISS, most of which have been +contributed by individuals via the Community repository. + +The following is a snapshot of some of the available WMs at this time: + ++--------------------+---------------------------------------------------------+ +| Window Manager | Description | ++--------------------+---------------------------------------------------------+ +| | | +| 2bwm | A fast floating WM, with the particularity of | +| | having 2 borders, written over the XCB library and | +| | derived from mcwm written by Michael Cardell. [1] | +| | | +| bspwm | bspwm is a tiling window manager that represents | +| | windows as the leaves of a full binary tree. [2] | +| | | +| dwm | dwm is a dynamic window manager for X. It manages | +| | windows in tiled, monocle and floating layouts. All | +| | of the layouts can be applied dynamically, | +| | optimising the environment for the application in | +| | use and the task performed. [3] | +| | | +| sowm | An itsy bitsy floating window manager. [4] | +| | | +| xwm | A tiny XCB floating window manager. [5] | +| | | ++--------------------+---------------------------------------------------------+ + +[4.0] Remote X Session Management +________________________________________________________________________________ + +The following tools are currently available for remote X session management. + + + [4.1] VNC + ____________________________________________________________________________ + + A Virtual Network Computing (VNC) is a graphical desktop-sharing system that + uses the Remote Frame Buffer protocol (RFB) to remotely control another + computer. The following VNC tools are currently offered through the + Community repository: + + * x11vnc (#/wiki/software/x11vnc) + + + [4.2] x11-forwarding + ____________________________________________________________________________ + + What if you need to access your applications remotely (with no additional + applications)? The solution is to utilize X server's "baked in" X11 + forwarding solution. For for more information, check out the + @/x11-forwarding article. + + +[5.0] References +________________________________________________________________________________ + +[0] https://www.x.org/wiki/ +[1] https://github.com/venam/2bwm +[2] https://github.com/baskerville/bspwm +[3] https://dwm.suckless.org/ +[4] https://github.com/dylanaraps/sowm +[5] https://github.com/mcpcpc/xwm