{"id":28438849,"url":"https://github.com/teapot9/cmkinitramfs","last_synced_at":"2025-07-01T13:32:41.105Z","repository":{"id":144103017,"uuid":"262695849","full_name":"teapot9/cmkinitramfs","owner":"teapot9","description":"A customizable simple initramfs generator","archived":false,"fork":false,"pushed_at":"2024-05-20T22:41:09.000Z","size":342,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-25T22:43:28.662Z","etag":null,"topics":["initramfs","initramfs-generator"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/teapot9.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-10T02:17:02.000Z","updated_at":"2025-01-04T15:29:12.000Z","dependencies_parsed_at":null,"dependency_job_id":"a2ab91ae-4fd6-4608-8bf0-4a34159043ef","html_url":"https://github.com/teapot9/cmkinitramfs","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/teapot9/cmkinitramfs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teapot9%2Fcmkinitramfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teapot9%2Fcmkinitramfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teapot9%2Fcmkinitramfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teapot9%2Fcmkinitramfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/teapot9","download_url":"https://codeload.github.com/teapot9/cmkinitramfs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teapot9%2Fcmkinitramfs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262468436,"owners_count":23316114,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["initramfs","initramfs-generator"],"created_at":"2025-06-06T01:40:15.957Z","updated_at":"2025-06-28T17:30:40.244Z","avatar_url":"https://github.com/teapot9.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"============\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 ≥ 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=\u003cpath to init\u003e``: Set the init process to run after the initramfs.\n - ``quiet``: Same as ``rd.quiet``.\n - ``rd.break=\u003cbreakpoint\u003e``: 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteapot9%2Fcmkinitramfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fteapot9%2Fcmkinitramfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteapot9%2Fcmkinitramfs/lists"}