============
cmkinitramfs
============
|github version badge|
|pypi version badge|
|qa badge|
|doc badge|
|py version badge|
|py implementation badge|
Tools to generate an initramfs from a configuration file.
Documentation is available at https://cmkinitramfs.readthedocs.io/.
.. |github version badge| image:: https://badge.fury.io/gh/teapot9%2Fcmkinitramfs.svg
:target: https://github.com/teapot9/cmkinitramfs
:alt: Github repository
.. |pypi version badge| image:: https://badge.fury.io/py/cmkinitramfs.svg
:target: https://pypi.org/project/cmkinitramfs/
:alt: PyPI package
.. |qa badge| image:: https://github.com/teapot9/cmkinitramfs/actions/workflows/qa.yml/badge.svg
:target: https://github.com/teapot9/cmkinitramfs/actions/workflows/qa.yml
:alt: Quality assurance
.. |doc badge| image:: https://readthedocs.org/projects/cmkinitramfs/badge/?version=latest
:target: https://cmkinitramfs.readthedocs.io/en/latest/
:alt: Documentation status
.. |py version badge| image:: https://img.shields.io/pypi/pyversions/cmkinitramfs.svg
:alt: Python version
.. |py implementation badge| image:: https://img.shields.io/pypi/implementation/cmkinitramfs.svg
:alt: Python implementation
About
=====
This project provides three main executables:
``cmkinit``, ``cmkcpiodir`` and ``cmkcpiolist``.
``cmkinit`` builds an init script from a configuration file.
``cmkcpiodir`` and ``cmkcpiolist`` build an initramfs,
including the init script, from the same configuration file.
``cmkcpiodir`` builds the initramfs into a directory on a filesystem,
and generates the CPIO archive from it.
``cmkcpiolist`` builds a CPIO list, using the same format as Linux kernel's
``gen_init_cpio`` utility, and generates the CPIO archive using
``gen_init_cpio``. See `the corresponding Linux kernel documentation`__
for more information.
.. __: https://www.kernel.org/doc/html/latest/filesystems/ramfs-rootfs-initramfs.html
Installation
============
Compatibility
-------------
Python version: this library is compatible with
**Python ≥ 3.7**.
Python implementation: this library is compatible with
**CPython** and **PyPy**.
Dependencies
------------
Python dependencies:
- bin (mkcpiodir and mkcpiolist) dependencies:
- ``pyelftools``
- Documentation:
- ``sphinx``
- ``sphinx_rtd_theme``
- Tests:
- QA:
- ``flake8``
- ``mypy``
- ``tox``
Other dependencies:
- initramfs (mkcpiodir and mkcpiolist) dependencies:
- ``loadkeys`` (kbd)
- ``busybox``
- ``modinfo`` (kmod, busybox)
- mkcpiodir dependencies:
- ``find`` (findutils, busybox)
- ``cpio`` (cpio, busybox)
- mkcpiolist dependencies:
- ``gen_init_cpio`` (linux kernel, linux-misc-apps)
Install
-------
Install from pypi:
.. code-block:: console
$ pip install cmkinitramfs
Install from source with setup.py:
.. code-block:: console
$ git clone https://github.com/teapot9/cmkinitramfs.git
$ cd cmkinitramfs
$ python3 setup.py install
Install from source with pip:
.. code-block:: console
$ git clone https://github.com/teapot9/cmkinitramfs.git
$ cd cmkinitramfs
$ pip3 install .
Configuration
=============
The configuration file is in an *ini* format.
Each section defines a data source, the section name is the data identifier.
Some options expects a data source as input, there are several data identifier
formats:
- ``DATA=data-name``: data defined in the section with the same name.
- ``data-name``: same as ``DATA=data-name``.
- ``PATH=/path/foo/bar``: data at the path ``/path/foo/bar``, this can
be a directory, a file, or a block device.
- ``/absolute/path``: same as ``PATH=/absolute/path``.
- ``UUID=1234-5678``: filesystem with UUID ``1234-5678``.
- ``LABEL=foo``: filesystem with label ``foo``.
- ``PARTUUID=1234-5678``: partition with UUID ``1234-5678``.
- ``PARTLABEL=foo``: partition with label ``foo``.
DEFAULT section
---------------
This section has default values for other sections, as well as
global configuration.
- ``root`` (mandatory): Data identifier for the data to use as new root.
- ``mountpoints`` (optional): Comma separated list of data identifier
to load in addition of rootfs.
- ``keymap`` (optional): Boolean value defining if a keymap should be
loaded. If set to ``no``, all ``keymap-*`` configurations will be ignored.
Defaults to ``no``.
- ``keymap-src`` (optional): Path of the keymap file to use. If not
specified but ``keymap`` is ``yes``, the converted keymap should already
exists at ``keymap-path``.
- ``keymap-path`` (optional): Path where the binary keymap will be
generated (generated from ``keymap-src``).
Defaults to ``/tmp/keymap.bmap``.
- ``keymap-dest`` (optional): Path of the keymap file within the initramfs.
Defaults to ``/root/keymap.bmap``.
- ``init-path`` (optional): Path where the init script will be generated
(generated from ``cmkinitramfs.init.mkinit()``).
Defaults to ``/tmp/init.sh``.
- ``files`` (optional): Additional files to include in the initramfs.
Each item is separated by a newline. Format: ``source:destination``
(e.g. ``files = /root/foo:/root/bar`` copy the file ``foo`` in the initramfs
renaming it ``bar``). If no destination is given, the file will be copied
to the same path as ``source`` in the initramfs. ``source`` can be an
absolute or relative path, ``destination`` must be an absolute path
within the initramfs.
- ``execs`` (optional): Additional executables to include in the initramfs.
Same format as ``files``, except that ``source`` will also be searched
in directories from the ``PATH`` environment variable.
- ``libs`` (optional): Additional libraries to include in the initramfs.
Same format as ``files``, except that ``source`` will also be searched
in directories from ``/etc/ld.so.conf`` and the ``LD_LIBRARY_PATH``
environment variable.
- ``busybox`` (optional): Additional executables to include in the initramfs.
Each item is separated by a newline. Format: ``exec``:
name of the command (basename).
If busybox provides the command, they will not be added. Otherwise,
the executable is searched in ``PATH``.
- ``cmkcpiodir-default-opts`` (optional): Options to append to the
``cmkcpiodir`` command line.
- ``cmkcpiolist-default-opts`` (optional): Options to append to the
``cmkcpiolist`` command line.
- ``modules`` (optional): Kernel modules to load in the initramfs.
One module per line, each line with the module name followed by the
module parameters (e.g. ``mymodule foo=bar``).
- ``scripts`` (optional): User scripts to run at a given breakpoint.
One user script per line with the format ``breakpoint:script``.
The script ``script`` will be run at the breakpoint ``breakpoint``.
A list of available breakpoints is available in
``cmkinitramfs.init.Breakpoint``.
These scripts will be run wether the breakpoint is enabled or not.
Example: ``init: ls /dev``: run ``ls /dev`` after initialization.
LUKS data sections
------------------
LUKS device to open.
- ``type = luks`` (mandatory).
- |need|
- |load-need|
- ``source`` (mandatory): Data identifier of the data to unlock.
- ``name`` (mandatory): Name to use for the luks device, this will be
used by cryptsetup.
- ``key`` (optional): Data identifier for the LUKS key.
- ``header`` (optional): Data identifier for the LUKS header.
- ``discard`` (optional): Enable discards. Boolean value (yes/no).
LVM data sections
-----------------
LVM logical volume to load.
- ``type = lvm`` (mandatory).
- |need|
- |load-need|
- ``vg-name`` (mandatory): Volume group name.
- ``lv-name`` (mandatory): Logical volume name.
Mount data sections
-------------------
Filesystem to mount.
- ``type = mount`` (mandatory).
- |need|
- |load-need|
- ``source`` (optional): Data identifier for the filesystem to mount.
If not set, it will set the source to "none" (e.g. for TMPFS).
- ``mountpoint`` (mandatory): Path where the filesystem will be mounted.
- ``filesystem`` (mandatory): Which filesystem to use, option passed
to ``mount -t filesystem``.
- ``options`` (optional): Mount options, defaults to ``ro``. Note for ZFS:
if the ``mountpoint`` property is not set to ``legacy``, the ``zfsutil``
option is required.
MD data sections
----------------
MD RAID data to load.
- ``type = md`` (mandatory).
- |need|
- |load-need|
- ``name`` (mandatory): Name of the MD RAID, this will be used by mdadm.
- ``source`` (mandatory): New line separated data identifiers of the
sources to use. Multiple block devices can be specified, or the
UUID of the MD RAID.
Clone data sections
-------------------
Clone a source to a destination.
- ``type = clone`` (mandatory).
- |need|
- |load-need|
- ``source`` (mandatory): Data identifier for the source of the clone.
- ``destination`` (mandatory): Data identifier of the destination
of the clone.
ZFS pool sections
-----------------
Import a ZFS pool.
- ``type = zfspool`` (mandatory).
- |need|
- |load-need|
- ``pool`` (mandatory): Pool name.
- ``cache`` (optional): Data identifier of the ZFS cache file (must be present
in the initramfs).
ZFS crypt sections
------------------
Unlock an encrypted ZFS dataset.
- ``type = zfscrypt`` (mandatory).
- |need|
- |load-need|
- ``pool`` (optional): Data identifier of the parent pool (defaults to same
as pool name).
- ``dataset`` (mandatory): Name of the dataset to unlock.
- ``key`` (optional): Data identifier of a keyfile to use.
Network sections
----------------
Configure a network interface.
- ``type = network`` (mandatory).
- |need|
- |load-need|
- ``device`` (mandatory): MAC address of the interface.
- ``ip`` (optional): IP address of the interface (DHCP if not set).
- ``mask`` (optional): IP mask (if static IP is defined).
- ``gateway`` (optional): default route IP (if static IP is defined).
ISCSI sections
--------------
Configure an iSCSI device.
- ``type = iscsi``
- |need|
- |load-need|
- ``initiator`` (mandatory): Initiator name.
- ``target`` (mandatory): iSCSI target.
- ``portal_group`` (mandatory): target portal group tag.
- ``address`` (mandatory): iSCSI server address.
- ``port`` (mandatory): iSCSI server port.
- ``username`` (optional): authentification username.
- ``password`` (optional): authentification password.
- ``username_in`` (optional): incoming authentification username.
- ``password_in`` (optional): incoming authentification password.
.. |need| replace:: ``need`` (optional): Hard dependencies: comma separated
list of data identifiers. Those dependencies are required to load
*and* use the data.
.. |load-need| replace:: ``load-need`` (optional): Load dependencies: comma
separated list of data identifiers. Those dependencies are only required
to load the data, they can be unloaded when the data has been successfully
loaded. (e.g. A LUKS key, an archive to decompress.)
Usage
=====
Kernel command-line parameters
------------------------------
The init script will check the kernel cmdline for known parameters.
- ``debug``: Same as ``rd.debug``.
- ``init=<path to init>``: Set the init process to run after the initramfs.
- ``quiet``: Same as ``rd.quiet``.
- ``rd.break=<breakpoint>``: Drop into a shell at a given point.
See ``cmkinitramfs.init.Breakpoint``.
- ``rd.debug``: Show debugging informations.
- ``rd.panic``: On fatal error: cause a kernel panic rather than droping
into a shell.
- ``rd.quiet``: Reduce log shown on console.
For more details, see ``cmkinitramfs.init.do_cmdline``.
cmkinit
-------
.. code-block:: console
$ cmkinit --help
usage: cmkinit [-h] [--version]
Build an init script
options:
-h, --help show this help message and exit
--version show program's version number and exit
Running ``cmkinit`` will generate an init script and output it to stdout.
No options are available, everything is defined in the configuration file.
The ``CMKINITCFG`` environment variable may be defined to use a custom
configuration file.
cmkcpiodir
----------
.. code-block:: console
$ cmkcpiodir --help
usage: cmkcpiodir [-h] [--verbose] [--quiet] [--version] [--debug]
[--output OUTPUT] [--binroot BINROOT] [--kernel KERNEL]
[--no-kmod] [--only-build-archive | --only-build-directory]
[--keep] [--clean] [--build-dir BUILD_DIR]
Build an initramfs using a directory.
options:
-h, --help show this help message and exit
--verbose, -v be verbose
--quiet, -q be quiet (can be repeated)
--version show program's version number and exit
--debug, -d debugging mode: non-root, implies -k
--output OUTPUT, -o OUTPUT
set the output of the CPIO archive
--binroot BINROOT, -r BINROOT
set the root directory for binaries (executables and
libraries)
--kernel KERNEL, -K KERNEL
set the target kernel versions of the initramfs,
defaults to the running kernel
--no-kmod disable kernel modules support
--only-build-archive, -c
only build the CPIO archive from an existing initramfs
directory
--only-build-directory, -D
only build the initramfs directory, implies -k
--keep, -k keep the created initramfs directory
--clean, -C overwrite temporary directory if it exists, use
carefully
--build-dir BUILD_DIR, -b BUILD_DIR
set the location of the initramfs directory
Running ``cmkcpiodir`` will generate the initramfs in a directory, then
it will create the CPIO archive from this directory.
``cmkcpiodir`` requires root privileges when run in non-debug mode,
see the ``do_nodes`` options of
``cmkinitramfs.initramfs.Initramfs.build_to_directory()``.
cmkcpiolist
-----------
.. code-block:: console
$ cmkcpiolist --help
usage: cmkcpiolist [-h] [--verbose] [--quiet] [--version] [--debug]
[--output OUTPUT] [--binroot BINROOT] [--kernel KERNEL]
[--no-kmod] [--only-build-archive | --only-build-list]
[--keep] [--cpio-list CPIO_LIST]
Build an initramfs using a CPIO list
options:
-h, --help show this help message and exit
--verbose, -v be verbose
--quiet, -q be quiet (can be repeated)
--version show program's version number and exit
--debug, -d debugging mode: non-root, implies -k
--output OUTPUT, -o OUTPUT
set the output of the CPIO archive
--binroot BINROOT, -r BINROOT
set the root directory for binaries (executables and
libraries)
--kernel KERNEL, -K KERNEL
set the target kernel versions of the initramfs,
defaults to the running kernel
--no-kmod disable kernel modules support
--only-build-archive, -c
only build the CPIO archive from an existing CPIO list
--only-build-list, -L
only build the CPIO list, implies -k
--keep, -k keep the created CPIO list
--cpio-list CPIO_LIST, -l CPIO_LIST
set the location of the CPIO list
Running ``cmkcpiolist`` will generate an initramfs CPIO list in a file,
then it will create the CPIO archive from this list with ``gen_init_cpio``.
``cmkcpiolist`` does not require root privileges.
findlib
-------
.. code-block:: console
$ findlib --help
usage: findlib [-h] [--verbose] [--quiet] [--version]
[--compatible COMPATIBLE] [--root ROOT] [--null] [--glob]
LIB [LIB ...]
Find a library on the system
positional arguments:
LIB library to search
options:
-h, --help show this help message and exit
--verbose, -v be verbose
--quiet, -q be quiet (can be repeated)
--version show program's version number and exit
--compatible COMPATIBLE, -c COMPATIBLE
set a binary the library must be compatible with
--root ROOT, -r ROOT set the root directory to search for the library
--null, -0 paths will be delemited by null characters instead of
newlines
--glob, -g library names are glob patterns
``findlib`` will search the absolute path of a library on the system.
It will search in directories from ``/etc/ld.so.conf``, ``LD_LIBRARY_PATH``,
and default library paths (see ``cmkinitramfs.bin.find_lib()`` and
``cmkinitramfs.bin.find_lib_iter()``).
Examples
========
Command-line interface
----------------------
.. code-block:: console
$ cmkcpiodir
..
- Creates init script in ``/tmp/init.sh``.
- If enabled, builds binary keymap in ``/tmp/keymap.bmap``.
- Builds initramfs in ``/tmp/initramfs`` (disable this step with
``--only-build-archive``).
- Builds CPIO archive from ``/tmp/initramfs`` to ``/usr/src/initramfs.cpio``
(disable this step with ``--only-build-directory``).
- Cleanup ``/tmp/initramfs`` directory (disable with ``--keep``).
.. code-block:: console
$ cmkcpiolist
..
- Creates init script in ``/tmp/init.sh``.
- If enabled, builds binary keymap in ``/tmp/keymap.bmap``.
- Builds CPIO list in ``/tmp/initramfs.list`` (disable this step with
``--only-build-archive``).
- Builds CPIO archive from ``/tmp/initramfs.list``
to ``/usr/src/initramfs.cpio`` (disable this step with
``--only-build-list``).
.. code-block:: console
$ findlib 'libgcc_s.so.1'
/usr/lib/gcc/x86_64-pc-linux-gnu/10.2.0/libgcc_s.so.1
..
- Searches the ``libgcc_s.so.1`` library on the system and prints it
to stdout.
.. code-block:: console
$ findlib -g 'libgcc_s.*'
/usr/lib/gcc/x86_64-pc-linux-gnu/10.2.0/libgcc_s.so.1
/lib64/libgcc_s.so.1
/lib64/libgcc_s.so.1
..
- Search any library matching ``libgcc_s.*`` on the system and prints them
to stdout.
Raw data
{
"_id": null,
"home_page": "https://github.com/teapot9/cmkinitramfs",
"name": "cmkinitramfs",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.7",
"maintainer_email": null,
"keywords": "initramfs, initramfs-generator",
"author": "Louis Leseur",
"author_email": "louis.leseur@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/61/a8/6b3b2d2d61ad3bde4786b1b18552f993e2a0eff1901f85930e7fd43b9fd9/cmkinitramfs-0.2.4.tar.gz",
"platform": "Linux",
"description": "============\ncmkinitramfs\n============\n\n|github version badge|\n|pypi version badge|\n|qa badge|\n|doc badge|\n|py version badge|\n|py implementation badge|\n\nTools to generate an initramfs from a configuration file.\n\nDocumentation is available at https://cmkinitramfs.readthedocs.io/.\n\n.. |github version badge| image:: https://badge.fury.io/gh/teapot9%2Fcmkinitramfs.svg\n :target: https://github.com/teapot9/cmkinitramfs\n :alt: Github repository\n\n.. |pypi version badge| image:: https://badge.fury.io/py/cmkinitramfs.svg\n :target: https://pypi.org/project/cmkinitramfs/\n :alt: PyPI package\n\n.. |qa badge| image:: https://github.com/teapot9/cmkinitramfs/actions/workflows/qa.yml/badge.svg\n :target: https://github.com/teapot9/cmkinitramfs/actions/workflows/qa.yml\n :alt: Quality assurance\n\n.. |doc badge| image:: https://readthedocs.org/projects/cmkinitramfs/badge/?version=latest\n :target: https://cmkinitramfs.readthedocs.io/en/latest/\n :alt: Documentation status\n\n.. |py version badge| image:: https://img.shields.io/pypi/pyversions/cmkinitramfs.svg\n :alt: Python version\n\n.. |py implementation badge| image:: https://img.shields.io/pypi/implementation/cmkinitramfs.svg\n :alt: Python implementation\n\nAbout\n=====\n\nThis project provides three main executables:\n``cmkinit``, ``cmkcpiodir`` and ``cmkcpiolist``.\n\n``cmkinit`` builds an init script from a configuration file.\n\n``cmkcpiodir`` and ``cmkcpiolist`` build an initramfs,\nincluding the init script, from the same configuration file.\n``cmkcpiodir`` builds the initramfs into a directory on a filesystem,\nand generates the CPIO archive from it.\n``cmkcpiolist`` builds a CPIO list, using the same format as Linux kernel's\n``gen_init_cpio`` utility, and generates the CPIO archive using\n``gen_init_cpio``. See `the corresponding Linux kernel documentation`__\nfor more information.\n\n.. __: https://www.kernel.org/doc/html/latest/filesystems/ramfs-rootfs-initramfs.html\n\n\nInstallation\n============\n\nCompatibility\n-------------\n\nPython version: this library is compatible with\n**Python \u2265 3.7**.\n\nPython implementation: this library is compatible with\n**CPython** and **PyPy**.\n\nDependencies\n------------\n\nPython dependencies:\n\n - bin (mkcpiodir and mkcpiolist) dependencies:\n\n - ``pyelftools``\n\n - Documentation:\n\n - ``sphinx``\n - ``sphinx_rtd_theme``\n\n - Tests:\n\n - QA:\n\n - ``flake8``\n - ``mypy``\n - ``tox``\n\nOther dependencies:\n\n - initramfs (mkcpiodir and mkcpiolist) dependencies:\n\n - ``loadkeys`` (kbd)\n - ``busybox``\n - ``modinfo`` (kmod, busybox)\n\n - mkcpiodir dependencies:\n\n - ``find`` (findutils, busybox)\n - ``cpio`` (cpio, busybox)\n\n - mkcpiolist dependencies:\n\n - ``gen_init_cpio`` (linux kernel, linux-misc-apps)\n\nInstall\n-------\n\nInstall from pypi:\n\n.. code-block:: console\n\n $ pip install cmkinitramfs\n\nInstall from source with setup.py:\n\n.. code-block:: console\n\n $ git clone https://github.com/teapot9/cmkinitramfs.git\n $ cd cmkinitramfs\n $ python3 setup.py install\n\nInstall from source with pip:\n\n.. code-block:: console\n\n $ git clone https://github.com/teapot9/cmkinitramfs.git\n $ cd cmkinitramfs\n $ pip3 install .\n\n\nConfiguration\n=============\n\nThe configuration file is in an *ini* format.\n\nEach section defines a data source, the section name is the data identifier.\n\nSome options expects a data source as input, there are several data identifier\nformats:\n\n - ``DATA=data-name``: data defined in the section with the same name.\n - ``data-name``: same as ``DATA=data-name``.\n - ``PATH=/path/foo/bar``: data at the path ``/path/foo/bar``, this can\n be a directory, a file, or a block device.\n - ``/absolute/path``: same as ``PATH=/absolute/path``.\n - ``UUID=1234-5678``: filesystem with UUID ``1234-5678``.\n - ``LABEL=foo``: filesystem with label ``foo``.\n - ``PARTUUID=1234-5678``: partition with UUID ``1234-5678``.\n - ``PARTLABEL=foo``: partition with label ``foo``.\n\nDEFAULT section\n---------------\n\nThis section has default values for other sections, as well as\nglobal configuration.\n\n - ``root`` (mandatory): Data identifier for the data to use as new root.\n\n - ``mountpoints`` (optional): Comma separated list of data identifier\n to load in addition of rootfs.\n\n - ``keymap`` (optional): Boolean value defining if a keymap should be\n loaded. If set to ``no``, all ``keymap-*`` configurations will be ignored.\n Defaults to ``no``.\n\n - ``keymap-src`` (optional): Path of the keymap file to use. If not\n specified but ``keymap`` is ``yes``, the converted keymap should already\n exists at ``keymap-path``.\n\n - ``keymap-path`` (optional): Path where the binary keymap will be\n generated (generated from ``keymap-src``).\n Defaults to ``/tmp/keymap.bmap``.\n\n - ``keymap-dest`` (optional): Path of the keymap file within the initramfs.\n Defaults to ``/root/keymap.bmap``.\n\n - ``init-path`` (optional): Path where the init script will be generated\n (generated from ``cmkinitramfs.init.mkinit()``).\n Defaults to ``/tmp/init.sh``.\n\n - ``files`` (optional): Additional files to include in the initramfs.\n Each item is separated by a newline. Format: ``source:destination``\n (e.g. ``files = /root/foo:/root/bar`` copy the file ``foo`` in the initramfs\n renaming it ``bar``). If no destination is given, the file will be copied\n to the same path as ``source`` in the initramfs. ``source`` can be an\n absolute or relative path, ``destination`` must be an absolute path\n within the initramfs.\n\n - ``execs`` (optional): Additional executables to include in the initramfs.\n Same format as ``files``, except that ``source`` will also be searched\n in directories from the ``PATH`` environment variable.\n\n - ``libs`` (optional): Additional libraries to include in the initramfs.\n Same format as ``files``, except that ``source`` will also be searched\n in directories from ``/etc/ld.so.conf`` and the ``LD_LIBRARY_PATH``\n environment variable.\n\n - ``busybox`` (optional): Additional executables to include in the initramfs.\n Each item is separated by a newline. Format: ``exec``:\n name of the command (basename).\n If busybox provides the command, they will not be added. Otherwise,\n the executable is searched in ``PATH``.\n\n - ``cmkcpiodir-default-opts`` (optional): Options to append to the\n ``cmkcpiodir`` command line.\n\n - ``cmkcpiolist-default-opts`` (optional): Options to append to the\n ``cmkcpiolist`` command line.\n\n - ``modules`` (optional): Kernel modules to load in the initramfs.\n One module per line, each line with the module name followed by the\n module parameters (e.g. ``mymodule foo=bar``).\n\n - ``scripts`` (optional): User scripts to run at a given breakpoint.\n One user script per line with the format ``breakpoint:script``.\n The script ``script`` will be run at the breakpoint ``breakpoint``.\n A list of available breakpoints is available in\n ``cmkinitramfs.init.Breakpoint``.\n These scripts will be run wether the breakpoint is enabled or not.\n Example: ``init: ls /dev``: run ``ls /dev`` after initialization.\n\nLUKS data sections\n------------------\n\nLUKS device to open.\n\n - ``type = luks`` (mandatory).\n\n - |need|\n\n - |load-need|\n\n - ``source`` (mandatory): Data identifier of the data to unlock.\n\n - ``name`` (mandatory): Name to use for the luks device, this will be\n used by cryptsetup.\n\n - ``key`` (optional): Data identifier for the LUKS key.\n\n - ``header`` (optional): Data identifier for the LUKS header.\n\n - ``discard`` (optional): Enable discards. Boolean value (yes/no).\n\nLVM data sections\n-----------------\n\nLVM logical volume to load.\n\n - ``type = lvm`` (mandatory).\n\n - |need|\n\n - |load-need|\n\n - ``vg-name`` (mandatory): Volume group name.\n\n - ``lv-name`` (mandatory): Logical volume name.\n\nMount data sections\n-------------------\n\nFilesystem to mount.\n\n - ``type = mount`` (mandatory).\n\n - |need|\n\n - |load-need|\n\n - ``source`` (optional): Data identifier for the filesystem to mount.\n If not set, it will set the source to \"none\" (e.g. for TMPFS).\n\n - ``mountpoint`` (mandatory): Path where the filesystem will be mounted.\n\n - ``filesystem`` (mandatory): Which filesystem to use, option passed\n to ``mount -t filesystem``.\n\n - ``options`` (optional): Mount options, defaults to ``ro``. Note for ZFS:\n if the ``mountpoint`` property is not set to ``legacy``, the ``zfsutil``\n option is required.\n\nMD data sections\n----------------\n\nMD RAID data to load.\n\n - ``type = md`` (mandatory).\n\n - |need|\n\n - |load-need|\n\n - ``name`` (mandatory): Name of the MD RAID, this will be used by mdadm.\n\n - ``source`` (mandatory): New line separated data identifiers of the\n sources to use. Multiple block devices can be specified, or the\n UUID of the MD RAID.\n\nClone data sections\n-------------------\n\nClone a source to a destination.\n\n - ``type = clone`` (mandatory).\n\n - |need|\n\n - |load-need|\n\n - ``source`` (mandatory): Data identifier for the source of the clone.\n\n - ``destination`` (mandatory): Data identifier of the destination\n of the clone.\n\nZFS pool sections\n-----------------\n\nImport a ZFS pool.\n\n - ``type = zfspool`` (mandatory).\n\n - |need|\n\n - |load-need|\n\n - ``pool`` (mandatory): Pool name.\n\n - ``cache`` (optional): Data identifier of the ZFS cache file (must be present\n in the initramfs).\n\nZFS crypt sections\n------------------\n\nUnlock an encrypted ZFS dataset.\n\n - ``type = zfscrypt`` (mandatory).\n\n - |need|\n\n - |load-need|\n\n - ``pool`` (optional): Data identifier of the parent pool (defaults to same\n as pool name).\n\n - ``dataset`` (mandatory): Name of the dataset to unlock.\n\n - ``key`` (optional): Data identifier of a keyfile to use.\n\nNetwork sections\n----------------\n\nConfigure a network interface.\n\n - ``type = network`` (mandatory).\n\n - |need|\n\n - |load-need|\n\n - ``device`` (mandatory): MAC address of the interface.\n\n - ``ip`` (optional): IP address of the interface (DHCP if not set).\n\n - ``mask`` (optional): IP mask (if static IP is defined).\n\n - ``gateway`` (optional): default route IP (if static IP is defined).\n\nISCSI sections\n--------------\n\nConfigure an iSCSI device.\n\n - ``type = iscsi``\n\n - |need|\n\n - |load-need|\n\n - ``initiator`` (mandatory): Initiator name.\n\n - ``target`` (mandatory): iSCSI target.\n\n - ``portal_group`` (mandatory): target portal group tag.\n\n - ``address`` (mandatory): iSCSI server address.\n\n - ``port`` (mandatory): iSCSI server port.\n\n - ``username`` (optional): authentification username.\n\n - ``password`` (optional): authentification password.\n\n - ``username_in`` (optional): incoming authentification username.\n\n - ``password_in`` (optional): incoming authentification password.\n\n.. |need| replace:: ``need`` (optional): Hard dependencies: comma separated\n list of data identifiers. Those dependencies are required to load\n *and* use the data.\n\n.. |load-need| replace:: ``load-need`` (optional): Load dependencies: comma\n separated list of data identifiers. Those dependencies are only required\n to load the data, they can be unloaded when the data has been successfully\n loaded. (e.g. A LUKS key, an archive to decompress.)\n\n\nUsage\n=====\n\nKernel command-line parameters\n------------------------------\n\nThe init script will check the kernel cmdline for known parameters.\n\n - ``debug``: Same as ``rd.debug``.\n - ``init=<path to init>``: Set the init process to run after the initramfs.\n - ``quiet``: Same as ``rd.quiet``.\n - ``rd.break=<breakpoint>``: Drop into a shell at a given point.\n See ``cmkinitramfs.init.Breakpoint``.\n - ``rd.debug``: Show debugging informations.\n - ``rd.panic``: On fatal error: cause a kernel panic rather than droping\n into a shell.\n - ``rd.quiet``: Reduce log shown on console.\n\nFor more details, see ``cmkinitramfs.init.do_cmdline``.\n\ncmkinit\n-------\n\n.. code-block:: console\n\n $ cmkinit --help\n usage: cmkinit [-h] [--version]\n \n Build an init script\n \n options:\n -h, --help show this help message and exit\n --version show program's version number and exit\n\nRunning ``cmkinit`` will generate an init script and output it to stdout.\nNo options are available, everything is defined in the configuration file.\nThe ``CMKINITCFG`` environment variable may be defined to use a custom\nconfiguration file.\n\ncmkcpiodir\n----------\n\n.. code-block:: console\n\n $ cmkcpiodir --help\n usage: cmkcpiodir [-h] [--verbose] [--quiet] [--version] [--debug]\n [--output OUTPUT] [--binroot BINROOT] [--kernel KERNEL]\n [--no-kmod] [--only-build-archive | --only-build-directory]\n [--keep] [--clean] [--build-dir BUILD_DIR]\n \n Build an initramfs using a directory.\n \n options:\n -h, --help show this help message and exit\n --verbose, -v be verbose\n --quiet, -q be quiet (can be repeated)\n --version show program's version number and exit\n --debug, -d debugging mode: non-root, implies -k\n --output OUTPUT, -o OUTPUT\n set the output of the CPIO archive\n --binroot BINROOT, -r BINROOT\n set the root directory for binaries (executables and\n libraries)\n --kernel KERNEL, -K KERNEL\n set the target kernel versions of the initramfs,\n defaults to the running kernel\n --no-kmod disable kernel modules support\n --only-build-archive, -c\n only build the CPIO archive from an existing initramfs\n directory\n --only-build-directory, -D\n only build the initramfs directory, implies -k\n --keep, -k keep the created initramfs directory\n --clean, -C overwrite temporary directory if it exists, use\n carefully\n --build-dir BUILD_DIR, -b BUILD_DIR\n set the location of the initramfs directory\n\nRunning ``cmkcpiodir`` will generate the initramfs in a directory, then\nit will create the CPIO archive from this directory.\n``cmkcpiodir`` requires root privileges when run in non-debug mode,\nsee the ``do_nodes`` options of\n``cmkinitramfs.initramfs.Initramfs.build_to_directory()``.\n\ncmkcpiolist\n-----------\n\n.. code-block:: console\n\n $ cmkcpiolist --help\n usage: cmkcpiolist [-h] [--verbose] [--quiet] [--version] [--debug]\n [--output OUTPUT] [--binroot BINROOT] [--kernel KERNEL]\n [--no-kmod] [--only-build-archive | --only-build-list]\n [--keep] [--cpio-list CPIO_LIST]\n \n Build an initramfs using a CPIO list\n \n options:\n -h, --help show this help message and exit\n --verbose, -v be verbose\n --quiet, -q be quiet (can be repeated)\n --version show program's version number and exit\n --debug, -d debugging mode: non-root, implies -k\n --output OUTPUT, -o OUTPUT\n set the output of the CPIO archive\n --binroot BINROOT, -r BINROOT\n set the root directory for binaries (executables and\n libraries)\n --kernel KERNEL, -K KERNEL\n set the target kernel versions of the initramfs,\n defaults to the running kernel\n --no-kmod disable kernel modules support\n --only-build-archive, -c\n only build the CPIO archive from an existing CPIO list\n --only-build-list, -L\n only build the CPIO list, implies -k\n --keep, -k keep the created CPIO list\n --cpio-list CPIO_LIST, -l CPIO_LIST\n set the location of the CPIO list\n\nRunning ``cmkcpiolist`` will generate an initramfs CPIO list in a file,\nthen it will create the CPIO archive from this list with ``gen_init_cpio``.\n``cmkcpiolist`` does not require root privileges.\n\nfindlib\n-------\n\n.. code-block:: console\n\n $ findlib --help\n usage: findlib [-h] [--verbose] [--quiet] [--version]\n [--compatible COMPATIBLE] [--root ROOT] [--null] [--glob]\n LIB [LIB ...]\n \n Find a library on the system\n \n positional arguments:\n LIB library to search\n \n options:\n -h, --help show this help message and exit\n --verbose, -v be verbose\n --quiet, -q be quiet (can be repeated)\n --version show program's version number and exit\n --compatible COMPATIBLE, -c COMPATIBLE\n set a binary the library must be compatible with\n --root ROOT, -r ROOT set the root directory to search for the library\n --null, -0 paths will be delemited by null characters instead of\n newlines\n --glob, -g library names are glob patterns\n\n``findlib`` will search the absolute path of a library on the system.\nIt will search in directories from ``/etc/ld.so.conf``, ``LD_LIBRARY_PATH``,\nand default library paths (see ``cmkinitramfs.bin.find_lib()`` and\n``cmkinitramfs.bin.find_lib_iter()``).\n\n\nExamples\n========\n\nCommand-line interface\n----------------------\n\n.. code-block:: console\n\n $ cmkcpiodir\n\n..\n\n - Creates init script in ``/tmp/init.sh``.\n - If enabled, builds binary keymap in ``/tmp/keymap.bmap``.\n - Builds initramfs in ``/tmp/initramfs`` (disable this step with\n ``--only-build-archive``).\n - Builds CPIO archive from ``/tmp/initramfs`` to ``/usr/src/initramfs.cpio``\n (disable this step with ``--only-build-directory``).\n - Cleanup ``/tmp/initramfs`` directory (disable with ``--keep``).\n\n.. code-block:: console\n\n $ cmkcpiolist\n\n..\n\n - Creates init script in ``/tmp/init.sh``.\n - If enabled, builds binary keymap in ``/tmp/keymap.bmap``.\n - Builds CPIO list in ``/tmp/initramfs.list`` (disable this step with\n ``--only-build-archive``).\n - Builds CPIO archive from ``/tmp/initramfs.list``\n to ``/usr/src/initramfs.cpio`` (disable this step with\n ``--only-build-list``).\n\n.. code-block:: console\n\n $ findlib 'libgcc_s.so.1'\n /usr/lib/gcc/x86_64-pc-linux-gnu/10.2.0/libgcc_s.so.1\n\n..\n\n - Searches the ``libgcc_s.so.1`` library on the system and prints it\n to stdout.\n\n.. code-block:: console\n\n $ findlib -g 'libgcc_s.*'\n /usr/lib/gcc/x86_64-pc-linux-gnu/10.2.0/libgcc_s.so.1\n /lib64/libgcc_s.so.1\n /lib64/libgcc_s.so.1\n\n..\n\n - Search any library matching ``libgcc_s.*`` on the system and prints them\n to stdout.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A customizable simple initramfs generator",
"version": "0.2.4",
"project_urls": {
"Homepage": "https://github.com/teapot9/cmkinitramfs"
},
"split_keywords": [
"initramfs",
" initramfs-generator"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c88c9bf434d39d8be57af6e4d31b79df6f113473d41802b99e1b2c0a2d0ca1da",
"md5": "fcd329eb83cdf5f6be00d80bbde3d3fb",
"sha256": "f450f502c98de18f4a51bf4de0214cfe2696717580f07939c9b3d18caf4d49f3"
},
"downloads": -1,
"filename": "cmkinitramfs-0.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fcd329eb83cdf5f6be00d80bbde3d3fb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.7",
"size": 41507,
"upload_time": "2024-05-20T22:40:11",
"upload_time_iso_8601": "2024-05-20T22:40:11.981882Z",
"url": "https://files.pythonhosted.org/packages/c8/8c/9bf434d39d8be57af6e4d31b79df6f113473d41802b99e1b2c0a2d0ca1da/cmkinitramfs-0.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "61a86b3b2d2d61ad3bde4786b1b18552f993e2a0eff1901f85930e7fd43b9fd9",
"md5": "74b3c2e74c0cf7f7215553bc953e4c1a",
"sha256": "90fa945243f5806b450a12ac1e086e3f91abb81ae31d87f89fa1e9a75ff77097"
},
"downloads": -1,
"filename": "cmkinitramfs-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "74b3c2e74c0cf7f7215553bc953e4c1a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.7",
"size": 48182,
"upload_time": "2024-05-20T22:40:13",
"upload_time_iso_8601": "2024-05-20T22:40:13.753013Z",
"url": "https://files.pythonhosted.org/packages/61/a8/6b3b2d2d61ad3bde4786b1b18552f993e2a0eff1901f85930e7fd43b9fd9/cmkinitramfs-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-20 22:40:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "teapot9",
"github_project": "cmkinitramfs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "cmkinitramfs"
}
JSON
