Michał Górny avatar Michał Górny committed de9cc6b

Add a README file.

Comments (0)

Files changed (1)

+eclean-kernel
+=============
+
+Introduction
+------------
+
+`eclean-kernel` is a small tool aimed at removing old and stale kernel files. It
+does not only remove old kernels itself but also tries to remove all related
+files including auxiliary files in /boot, kernel modules and even the source
+tree.
+
+
+Usage
+-----
+
+The typical use is:
+
+	eclean-kernel -n 3 -p
+
+where `-n 3` is used to keep three newest kernels around, and `-p` makes
+eclean-kernel only print kernels which would be removed.
+
+In case the results are satisfactory, use:
+
+	eclean-kernel -n 3
+
+to actually remove the kernels.
+
+If you are unsure whether kernel files are mapped correctly, you can use
+list mode:
+
+	eclean-kernel -l
+
+which just lists found kernels with file mappings.
+
+
+Fiding and mapping kernels
+--------------------------
+
+The first task performed by eclean-kernel is finding all currently installed
+kernels and matching auxiliary files to them. In order to do that, eclean-kernel
+first looks for files named in the form of:
+
+	/boot/PREFIX-VERSION
+
+where _PREFIX_ is one of the predefined file prefixes representing the file
+type, and _VERSION_ is a free-form string following it (preferably the kernel
+version).
+
+Right now, eclean-kernel supports the following prefixes:
+
+- `vmlinuz`, `vmlinux`, `kernel` and `bzImage` for kernel files,
+- `System.map` for system.map file,
+- `config` for kernel configuration.
+
+In case support for additional prefixes is needed, feel free to report a bug.
+
+Files belonging to the same kernel are grouped using the _VERSION_ part, e.g. it
+is assumed that `System.map-X.Y.Z` corresponds to `vmlinuz-X.Y.Z`.
+
+In addition to that, eclean-kernel looks for kernel modules in:
+
+	/lib/modules/REALVERSION
+
+where _REALVERSION_ corresponds to the actual kernel version string used
+by the kernel itself. It is read from kernel image itself and it is assumed to
+be equal to _VERSION_ for libdirs unmatched to any kernel image.
+
+In other words, genkernel-generated `kernel-genkernel-ARCH-X.Y.Z` will be
+matched to `System.map-genkernel-ARCH-X.Y.Z` but also to `/lib/modules/X.Y.Z`.
+
+
+Choosing kernels to remove
+--------------------------
+
+The kernel choice algorithm is quite simple:
+
+1. If the kernel is currently used, don't remove it;
+2. If the kernel is referenced by a bootloader, don't remove it
+	(unless `--destructive`);
+3. If auxiliary files do not map to existing kernel, remove them;
+4. If `--all` is used, remove the kernel;
+5. If kernel is not within _N_ newest kernels (where _N_ is the argument
+	to `-n`), remove it.
+
+The program always derefences symlinks and counts real path references. Thus,
+a particular file will be removed only if all kernels referencing it are removed
+as well. This is especially important for shared kernel sources.
+
+
+Bootloader support
+------------------
+
+In order to determine kernels currently used, eclean-kernel is supposed to read
+configuration files used by the bootloader. Right now, the following bootloaders
+are supported:
+
+1. lilo,
+2. grub,
+3. yaboot.
+
+There is also a pseudo-bootloader module called _symlinks_ which assumes files
+symlinked to `/boot/PREFIX` and `/boot/PREFIX.old` are used.
+
+By default, eclean-kernel uses the first bootloader from the above list for
+which a configuration file exists, and uses _symlinks_ as a fallback. This can
+be changed using `--bootloader` argument.
+
+
+Reporting bugs
+--------------
+
+Please report bugs either to [github][1] or [Gentoo Bugzie][2]. When reporting
+a bug, please attach the outputs of:
+
+	eclean-kernel -l
+	ls -l /boot /lib/modules/*
+
+If relevant, please attach bootloader configuration files as well.
+
+[1]:https://github.com/mgorny/eclean-kernel/issues/
+[2]:http://bugs.gentoo.org/
+
+
+<!-- vim:se syn=markdown : -->
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.