{"id":16021838,"url":"https://github.com/cutecutecat/eulerinit","last_synced_at":"2025-04-05T03:43:46.090Z","repository":{"id":115862384,"uuid":"312158522","full_name":"cutecutecat/EulerInit","owner":"cutecutecat","description":"A mirror generating tool designed for openEuler OS to transform ISO file to cloud platform VM file. ","archived":false,"fork":false,"pushed_at":"2020-11-15T12:54:21.000Z","size":681,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-10T12:12:47.145Z","etag":null,"topics":["automation","cloud","install","iso","kickstart","os","qemu","system","virtual-machine"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cutecutecat.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-11-12T03:35:11.000Z","updated_at":"2024-04-16T13:08:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"598c3279-19c8-4fed-bd54-9b8f821d1ed3","html_url":"https://github.com/cutecutecat/EulerInit","commit_stats":{"total_commits":2,"total_committers":2,"mean_commits":1.0,"dds":0.5,"last_synced_commit":"2221bf57710ce8d8d2ea222f2f9f487294850411"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cutecutecat%2FEulerInit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cutecutecat%2FEulerInit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cutecutecat%2FEulerInit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cutecutecat%2FEulerInit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cutecutecat","download_url":"https://codeload.github.com/cutecutecat/EulerInit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247284918,"owners_count":20913691,"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":["automation","cloud","install","iso","kickstart","os","qemu","system","virtual-machine"],"created_at":"2024-10-08T18:06:12.131Z","updated_at":"2025-04-05T03:43:46.071Z","avatar_url":"https://github.com/cutecutecat.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EulerInit文档\n\n\n[TOC]\n\n## 概述\n\nEulerInit是一个便捷的镜像转换工具，用于将openEuler系统自动化从openEuler的iso制作出各种公有云的虚拟机镜像。原理是利用Python shell调用QEMU，在本地启动文件服务器用于传输相关安装包到虚拟机，并使用kickstart文件运行自动化安装。\n\n目前兼容情况如下：\n\n| | 阿里云 | 华为云 | 腾讯云 |\n| ------- | :----: | :----: | :----: |\n| x86_64 | √ | √ | √ |\n| aarch64 | x | √ | x |\n\nEulerInit在宿主机Windows 10和Ubuntu 20.04上通过了openEuler-20.03-LTS镜像生成测试。\n\n## 准备工作\n\nEulerInit依赖*qemu-img*，*qemu-system-x86_64*和*qemu-system-aarch64*等虚拟化工具，且需要将这些工具加入环境变量。\n\nwindows系统：\n\n从[此处](https://www.qemu.org/download/)下载QEMU的Windows版本，并人工将qemu安装目录加入环境变量。\n\nLinux系统：\n\n例如Ubuntu下可以利用apt-get或yum安装*qemu-system-x86*，*qemu-system-arm*和*qemu-utils*。\n\n其他发行版可以自行寻找相似软件包。\n\n检查是否安装成功：\n\n```\n# Windows\nqemu-system-x86_64.exe -version\nqemu-system-aarch64.exe -version\nqemu-img.exe -V\n\n# Linux\nqemu-system-x86_64 -version\nqemu-system-aarch64 -version\nqemu-img -V\n\n# output\nQEMU emulator version 5.0.0 (v5.0.0-11810-g8846fa22bb-dirty)\nCopyright (c) 2003-2020 Fabrice Bellard and the QEMU Project developers\nQEMU emulator version 5.0.0 (v5.0.0-11810-g8846fa22bb-dirty)\nCopyright (c) 2003-2020 Fabrice Bellard and the QEMU Project developers\nqemu-img version 5.0.0 (v5.0.0-11810-g8846fa22bb-dirty)\nCopyright (c) 2003-2020 Fabrice Bellard and the QEMU Project developers\n```\n\n除此之外，EulerInit依赖以下Python软件包，由requirments.txt指定。\n\n若使用pip安装EulerInit，它们将自动一并安装（需要联网环境）：\n\n```\n# 用于相关文件的下载\nrequests\u003e=2.24.0\n# 用于ISO文件的读取\npycdlib\u003e=1.10.0\n# 用于命令行工具的创建\nclick\u003e=7.1.2\n```\n\n## 实际安装\n\n因为EulerInit是标准化Python wheel格式，安装EulerInit非常简单：\n\n* 如果你已经获得了wheel安装包，可以直接利用pip安装：\n\n ```shell\n pip install EulerInit-0.1-py3-none-any.whl\n ```\n\n* 如果你试图从源码安装，可以使用如下命令：\n\n ```shell\n python setup.py bdist_wheel\n pip install dist/EulerInit-0.1-py3-none-any.whl\n ```\n\n在源码中，额外提供了Windows安装脚本install.bat，Windows环境下可直接运行安装。\n\n\n\n## 基本使用\n\n如果您只需要进行基础性的镜像转换，请使用如下基本命令在默认参数下进行生成：\n\n阿里云通用计算(x86_64)：\n\n```\nEulerInit -m ali path/to/x86_64/iso/file\n```\n\n腾讯云通用计算(x86_64)：\n\n```\nEulerInit -m tencent path/to/x86_64/iso/file\n```\n\n华为云通用计算(x86_64):\n\n```\nEulerInit -m huawei path/to/x86_64/iso/file\n```\n\n华为云鲲鹏计算(aarch64):\n\n```\nEulerInit -m huawei path/to/aarch64/iso/file\n```\n\n在默认参数下，生成的镜像文件将遵循以下特征描述：\n\n| 参数 | 描述 |\n| -------- | ----------------- |\n| 文件名 | virtual.img |\n| 输出路径 | ./tmp/virtual.img |\n| 大小 | 40GB |\n| 格式 | raw |\n| 密码 | openEuler@123456 |\n\n\n\n## 命令详解\n\n```\nUsage: EulerInit [OPTIONS] ISO\n\nOptions:\n -m, --mode [huawei|tencent|ali|template|script]\n Target cloud platform to generate.\n [required]\n\n -p, --path PATH Directory for temporary files and output\n image(default : ./tmp).\n\n -s, --script PATH Python script convertor defined by user(if\n mode is \"script\").\n\n -t, --template PATH Template files directory defined by user(if\n mode is \"template\" or \"script\").\n\n -i, --img TEXT Output img filename(default : virtual.img).\n -f, --format TEXT Output img format(default : raw).\n -q, --quiet Quiet mode(not output anything)\n --system [x86_64|aarch64|auto] System architecture of ISO image\n file(default : auto, \"auto\" is to fetch from\n ISO filename).\n\n --passwd TEXT default password of image root(default :\n openEuler@123456).\n\n --size TEXT Image file size to create(default : 40G).\n -h, --help Show this message and exit.\n```\n\n具体的options描述如下：\n\n| 指令 | 取值 | 描述 | 默认 | 强制 | 备注 |\n| -------- | ---------- | ------------------------------------------ | ---------------- | ---- | ------------------------------------------ |\n| mode | huawei | 使用为华为云配置的模板文件安装镜像 | 无 | 是 | |\n| | tencent | 使用为腾讯云配置的模板文件安装镜像 | | | |\n| | ali | 使用为阿里云配置的模板文件安装镜像 | | | |\n| | template | 使用用户自定义的模板文件安装镜像 | | | |\n| | script | 使用用户自定义的模板文件和安装脚本安装镜像 | | | 要求同时设置ALLOW_USER_SCRIPT=True环境变量 |\n| path | TEXT[PATH] | 指定的输出文件夹 | ./tmp | 否 | |\n| script | TEXT[PATH] | 指定的安装脚本Python文件 | 无 | 否 | 仅在mode为script时有效 |\n| template | TEXT[PATH] | 指定的模板文件夹 | 无 | 否 | 仅在mode为script和template时有效 |\n| img | TEXT | 输出镜像文件名 | virtual.img | 否 | |\n| format | TEXT | 输出镜像格式 | raw | 否 | 不做类型检查，必须是qemu-img允许的格式 |\n| quiet | | 安静模式 | | 否 | |\n| system | x86_64 | ISO文件为x86_64平台 | auto | 否 | |\n| | aarch64 | ISO文件为aarch64平台 | | | |\n| | auto | 自动检测 | | | ISO文件名必须包含x86_64或aarch64之一 |\n| passwd | TEXT | 输出镜像文件root用户密码 | openEuler@123456 | 否 | |\n| version | TEXT | ISO文件版本号 | auto | 否 | |\n| | auto | 自动检测 | | | ISO文件名必须包含版本号 |\n| size | TEXT | 输出镜像文件大小 | | 否 | 不做类型检查，必须是qemu-img允许的格式 |\n| help | | 显示帮助 | | 否 | |\n\n\n\n## 用户拓展\n\n如果需要兼容更多公有云平台，或进行其他的自定义安装，EulerInit提供了两种拓展方式：\n\n### 模板拓展\n\nEulerInit利用template模板文件定义了安装流程的细节，其中包含了文件下载，QEMU调用命令，kickstart引导文件和其它部分，这些模板文件被被放在模板文件夹下。在运行过程中，EulerInit将会拷贝这个文件夹中的内容到输出文件夹，并在输出文件夹下启动本地文件服务器，以供虚拟机安装过程中使用。\n\nEulerInit运行默认参数时，将会使用EulerInit/Convertor/template中指定的模板文件。但是，EulerInit也允许用户指定自己的template模板文件。\n\n用户使用如下指令指定自定义模板文件夹：\n\n```shell\nEulerInit -m template -t path/to/template/directory ...\n```\n\n用户构建自定义模板文件夹时，文件夹所包含文件必须符合以下规范，其中指定名称的文件必须要存在且不可改名。在部分自定义模板文件中，支持使用在执行时确定的**符号替换列表**，具体写法将在文件规范中描述：\n\n| 文件名 | 描述 | 符号替换 |\n| ------------- | ------------------------------------------------------------ | -------- |\n| files.json | 定义了文件下载与命名规则 | 无 |\n| qemu.json | 定义了QEMU调用命令 | 有 |\n| ks.cfg | 预置的kickstart安装引导脚本 | 有 |\n| [Other files] | 其他相关文件，如cloud-init所使用的cloud.cfg，在其他文件中被使用 | |\n\n***\n\nfile.json中定义了文件下载与命名规则，文件符合json规范。可参考Convertor/template/XXX/下的同名文件，具体格式描述如下：\n\n```mermaid\ngraph LR\nA[top] --\u003e |dict| B[x86_64]\nA[top] --\u003e |dict| C[aarch64]\nB[x86_64] --\u003e |dict| D[download]\nB[x86_64] --\u003e |dict| E[file]\nC[aarch64] --\u003e |dict| F[download]\nC[aarch64] --\u003e |dict| G[file]\nD[download] --\u003e |dict| H[id : url]\nE[file] --\u003e |dict| I[id : filename]\nF[download] --\u003e |dict| J[id : url]\nG[file] --\u003e |dict| K[id : filename]\n```\n\n在对应的ISO文件平台下，EulerInit将会在读取file.json后，根据top节点下相应平台节点的键值对信息，获得需要下载的文件地址和文件名，并执行下载过程。需要注意的是，**如果在输出文件夹下已有同名文件，EulerInit默认文件内容正确不进行检查和下载工作**，当用户网络较差不适合进行下载时，可以利用这一点事先准备好需要的文件以跳过下载。\n\n***\n\nqemu.json中定义了QEMU模拟器调用命令，文件符合json规范。可参考Convertor/template/XXX/下的同名文件，具体格式描述如下：\n\n```mermaid\ngraph LR\nA[top] --\u003e |dict| B[x86_64]\nA[top] --\u003e |dict| C[aarch64]\nB[x86_64] --\u003e |dict| D[key : value]\nC[aarch64] --\u003e |dict| E[key : value]\n```\n\n其中key-value为自定义键值对，key为字符串，将被转换成QEMU option被加入QEMU模拟器命令中，value可以有三种格式，描述如下：\n\n| value格式 | 描述 |\n| ------------- | ------------------------------------------------------------ |\n| str | 以字符串形式被转换成\"- key value\"加入命令 |\n| int | 以整数形式被转换成\"- key value\"加入命令 |\n| list[str/int] | 以字符串或整数形式被转换成\"-key value1 -key value2 -key value3 ...\"加入命令 |\n\n*备注：如需单独option样式命令如\"-q\"，可以使用 ```key : ''``` 格式如```'q' : '```*。\n\n在对应的ISO文件平台下，EulerInit将会在读取qemu.json后，根据top节点下相应平台节点的键值对信息，获得QEMU模拟器调用时的命令集合，并转换成实际的调用命令。\n\nqemu.json文件支持**符号替换列表**，用户在编写自定义模板文件时，可以使用如下符号标记，在程序执行时，这些标记将被自动替换为相应内容：\n\n| 符号 | 内容 | 取值 |\n| -------------- | ------------------------------ | --------------- |\n| {system} | ISO镜像文件对应平台 | x86_64或aarch64 |\n| {img_path} | ISO镜像文件路径 | TEXT[PATH] |\n| {machine} | QEMU虚拟机器类型 | pc或virt |\n| {vmlinuz_path} | vmlinuz文件路径 | TEXT[PATH] |\n| {initrd_path} | initrd.img文件路径 | TEXT[PATH] |\n| {bios_path} | QEMU_EFI.fd文件路径 | TEXT[PATH] |\n| {kernel_args} | 从grub.cfg获得的原始kernel参数 | TEXT |\n\n\n\n***\n\nks.cfg为kickstart自动化引导启动脚本，该文件将在运行QEMU安装时被提供。除了支持[标准kickstart语法](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/installation_guide/sect-kickstart-syntax#sect-kickstart-onerror)，ks.cfg文件还支持**符号替换列表**，用户在编写自定义模板文件时，可以使用如下符号标记，在程序执行时，这些标记将被自动替换为相应内容：\n\n| 符号 | 内容 | 取值 |\n| ---------------- | ------------------------------------------------------------ | ------- |\n| is_x86_64_pound | 当ISO镜像文件对应平台为x86_64时替换为'#'，否则替换为空字符串 | '#'或'' |\n| is_aarch64_pound | 当ISO镜像文件对应平台为aarch64时替换为'#'，否则替换为空字符串 | '#'或'' |\n| passwd | 输出镜像文件root用户密码 | TEXT |\n| version | ISO文件版本号 | TEXT |\n\n\n\n### 脚本拓展\n\n**注意：脚本拓展模式将会执行用户给定的脚本，因此可能会造成代码任意执行漏洞。为尽量避免这一点，在命令行工具中，要求用户定义环境变量EULERINIT_ALLOW_SCRIPT为True才可以使用脚本拓展，否则程序会报错并抛出PermissionError。**\n\nEulerInit利用Convertor定义了安装流程的基础指令。Convertor类定义在.py文件中，其中定义了以下几个基本方法：\n\n| 方法 | 描述 |\n| ---------- | ---------------------------------------- |\n| setup | 设置相关参数 |\n| prepare | 准备安装所需文件 |\n| serverUp | 启动文件服务器 |\n| install | 执行QEMU安装流程(分配空间和实际安装) |\n| serverDown | 关闭文件服务器 |\n| output | 执行镜像生成后续工作，如格式转换或重命名 |\n\nEulerInit运行默认参数时，将会使用EulerInit/Convertor/GeneralConvert.py中的Convertor类。但是，EulerInit也允许用户指定自己的Convertor类。\n\n用户使用如下指令指定自定义Convertor类，需要注意的是，自定义Convertor类时，也需要自定义template模板文件：\n\n```shell\nEulerInit -m script -s path/to/Convertor.py -t path/to/template/directory ...\n```\n\n***\n\n上述全部方法将在entry.py中被依次调用，如果用户利用entry.py中的script模式调用自定义脚本，则必须实现以上方法\n\n用户在自定义Convertor类时，建议继承BaseConvertor类，利用虚函数的检查，确保以上方法都已经实现。当然，如果只需要修改少数方法，也可以继承GeneralConvertor以使用其中部分预定义方法。\n\n\n\n## 已知问题\n\nEulerInit在生成阿里云镜像时，由于阿里云本身兼容性问题，无法支持从控制台初始化密码或者修改密码。用户可以考虑：\n\n* 临时使用生成镜像时的密码，远程登录后在命令行利用`passwd`等命令修改密码\n* 通过阿里云的[配置实例自定义数据](https://help.aliyun.com/document_detail/108461.html?spm=a2c4g.11186623.6.689.831e1bf9jDdplh)功能，编写在启动时自动执行的shell脚本以修改密码\n\n\n\n## 参考内容\n\n用户在编写自定义模板以进行模板拓展和脚本拓展时，对于模板可能会包含的文件格式，可以参考以下内容\n\n1. kickstart文件规范参见Red Hat Document的[kickstart部分](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/installation_guide/sect-kickstart-syntax#sect-kickstart-onerror)\n2. cloud.cfg文件规范参见[cloud-init Document](https://cloudinit.readthedocs.io/en/latest/)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcutecutecat%2Feulerinit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcutecutecat%2Feulerinit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcutecutecat%2Feulerinit/lists"}