Metadata-Version: 2.1
Name: funtoo-ramdisk
Version: 1.0.6
Summary: Funtoo framework for creating initial ramdisks.
Home-page: https://code.funtoo.org/bitbucket/users/drobbins/repos/funtoo-ramdisk/browse
Author: Daniel Robbins
Author-email: drobbins@funtoo.org
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.7
Description-Content-Type: text/x-rst

**************
Funtoo Ramdisk
**************

Copyright 2023 Daniel Robbins, Funtoo Solutions, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Introduction
============

The Funtoo ramdisk tool, called ``ramdisk`` is a stand-alone tool to create an
initial RAM disk filesystem (initramfs) for booting your Linux system.

The internal initramfs logic is based on the logic found in Gentoo Linux's
genkernel tool, but has been rewritten to be simpler and more efficient.

You can use this tool to create an initramfs to boot to a Funtoo Linux root
ext4 or XFS filesystem, which is what we support in our official installation
documentation at https://www.funtoo.org/Install -- but that's about it.

What's Not Included
===================

Nearly all "extra" genkernel features are intentionally not yet implemented.
This tool doesn't build your kernel or modules.

It also currently doesn't support dmraid, zfs, btrfs, encrypted root, or LiveCD
or LiveUSB booting.

Why not? Because one of the main design goals of this project is to create a
very elegant and easy-to-understand initramfs whose core logic is not cluttered
with tons of complicated features. To start from a clean slate, we are starting
from very minimal functionality and then will very carefully add back various
features while keeping the code clean, simple, elegant and effective.

What's Included
===============

So, what *does* Funtoo's ramdisk tool actually offer? Here's a list:

* genkernel-style initramfs without the cruft. In comparison to genkernel's
  initramfs, the shell code is about 10x simpler and a lot cleaner, but does
  the same thing and has been modernized. About 100 lines of shell script,
  with another 215 lines of functions in a support file.

* Rootless operation. You do not need enhanced privileges to create the
  initramfs.

* You can read the ``linuxrc`` script and actually understand what it does.
  It is written to be easy to understand and adapt. So it's not just short,
  but easy to grasp.

* Enhanced module loading engine on the initramfs which is significantly
  faster than genkernel. This effectively eliminates the "watching the
  stream of useless modules being loaded" issue with genkernel. Modern
  systems with NVMe drives will load just a handful of modules to boot
  -- all without requiring any special action from the user.

* If you are still able to find some modules that got loaded that you
  don't want loaded, you can use the "magic modules" feature to specify
  just the modules you want to load. Specify ``magic=mod1,mod2,mod3``
  as a kernel argument and just these modules will be loaded.

* Effective Python-based command to actually build the ramdisk, which is
  called: ``ramdisk``. This gives us an extensible platform for the future.

* Enhanced ini-style system for selecting modules to include on your initramfs.
* Enhanced ini-style system for selecting module groups to autoload on the initramfs.
* Support for xz and zstd compression.

How To Use It
=============

First, install the package, via ``emerge ramdisk`` on Funtoo Linux, or alternatively
``pip3 install --user funtoo-ramdisk``. You will then have a ``ramdisk`` command
in your path, which can be used to build a ramdisk.

Then, as a regular user, you can run::

  ramdisk /var/tmp/my-new-initramfs
  sudo cp /var/tmp/my-new-initramfs /boot

By default, ``ramdisk`` will use your ``/usr/src/linux`` symlink to determine which
kernel to use to build a ramdisk for. It will parse ``/usr/src/linux/Makefile``,
extract kernel version information, and then find the appropriate directory in
``/lib/modules/<kernel_name>`` for copying modules.

Since this is brand-new software, it is highly recommended that you DO NOT OVERWRITE
YOUR EXISTING, WORKING INITRAMFS THAT YOU CURRENTLY USE TO BOOT YOUR SYSTEM.

Instead -- create a NEW BOOT ENTRY to test your initramfs. In GRUB, you can also
press 'e' to edit an entry and type in the name of the new initramfs to give it a try.

Enjoy -- and let me know how it works for you! Please report issues and feature
requests to https://bugs.funtoo.org.


ChangeLog
=========

funtoo-ramdisk 1.0.6
--------------------

Releaed on August 21, 2023.

Two new options:

* ``--modules_root`` to set the root filesystem to scan for modules.
  It defaults to ``/``.

* ``--temp_root`` to set the default path to use for creating a
   temporary directory. It defaults to ``/var/tmp``.

funtoo-ramdisk 1.0.5
--------------------

Released on August 21, 2023.

This is a features/maintenance/bug fix release.

In addition to a bunch of minor fixes and clean-ups, which you can
view in the git history, the following significant changes were
made:

* Use kmod ``/sbin/modprobe`` instead of busybox's modprobe. Busybox's modprobe
  may be fine, but for it to work, we must use busybox's ``depmod`` -- and we're
  not. We're using ``kmod``'s. So for now, let's just copy the right modprobe
  over. This fixes an issue where we get invalid symbols when loading modules
  using busybox ``modprobe``. ``modprobe`` is now resolving deps properly! :)

  At some point, we could make a "toggle" to select kmod/busybox mode. The
  best time to run ``depmod`` for busybox is probably once the ramdisk first
  boots, since it doesn't have a "root" option, making it hard to call from our
  ramdisk script.

* Remove unused control character definitions in ``initrd.defaults``.

* Mitigate an issue where ``ash`` shell could start before all USB keyboards
  have been detected, resulting in lack of input. We now wait 5 seconds
  before starting a rescue shell, to give the kernel time to enumerate
  devices on the USB2/3 bus. This isn't a full fix, but should resolve
  the problem of ``ash`` starting and not having any way to type, because
  it didn't connect to your main keyboard.

Try to work around issues related to ATA/SCSI disk enumeration which could
prevent the root filesystem from being mounted (see FL-11532).

* Detect when a user has a ``/dev/sd*`` root block device and warn them that
  this is not a good idea, and can cause problems if you have multiple
  disks. Show them how to fix the problem by switching to UUID.

* Remove scsi_debug module which is evil and if we force-load it, will create
  a new SCSI device 8MB in size and trigger the problem above for anyone
  with a SATA disk.

* To implement above feature, added a feature to allow masking of modules in
  ``modules.copy`` via "-mod_shortname" in a specific section. Also added a
  lot of sanity checking and warnings. If you happen to mask a module in the
  wrong section, so it still gets included on the initramfs due to other
  section(s), we will warn you.


funtoo-ramdisk 1.0.4
--------------------

Released on August 18, 2023.

This is a maintenance/bug fix release.

* Fix ability to run from the git repo. This wasn't working.

* Fix issue found by grouche, where if a module is built-in to the
  kernel but listed in ``modules.autoload``, ``ramdisk`` would throw
  an error because it would think it's not copied to the initramfs.
  We now read in the ``modules.builtin`` file and use this in the
  internal logic -- if a module is built-in to the kernel, we can
  not worry if it is our ``modules.autoload`` list. We still have it.
  We will also not worry about trying to load it at boot.

* Add a debug output whenever a module is referenced that is actually
  a built-in. This helps to audit the behavior of the above
  functionality and could be useful to users of the tool as well.

* Announce we are in debug mode with ``log.info()`` instead of a
  warning. Looks a bit nicer.

