guestfs-faq - 云端在线

程序：

您的姓名

guestfs-faq - libguestfs 常见问题 (FAQ)

关于我们 来宾

什么是 is libguestfs？
libguestfs 是一种创建、访问和修改磁盘映像的方法。 你可以看看里面的磁盘
图像，修改它们包含的文件，从头开始创建它们，调整它们的大小等等
更多的。 它在脚本和程序以及命令行中特别有用。

libguestfs 是一个 C 库（因此称为“lib-”），以及基于该库构建的一组工具，以及
许多常见编程语言的绑定。

有关 libguestfs 可以做什么的更多信息，请阅读主页上的介绍
(http://libguestfs.org).

什么是 ，那恭喜你， 此 道德 工具？
Virt 工具（网站： http://virt-tools.org) 是一整套虚拟化管理
针对系统管理员的工具。 其中一些来自 libguestfs，一些来自
libvirt 和来自其他开源项目的许多其他项目。 所以 virt 工具是一个超集
libguestfs。 然而，libguestfs 附带了许多重要的工具。 看
http://libguestfs.org 一个完整的清单。

儿童在 libguestfs 需要 { libvirt的 / KVM / 红色 帽子 / Fedora }?
不！

libvirt 不是 libguestfs 的要求。

libguestfs 适用于任何磁盘映像，包括在 VMware、KVM、qemu、
VirtualBox、Xen 和许多其他管理程序，以及您从头开始创建的管理程序。

红帽赞助（即支付）开发 libguestfs 和大量其他开放
源项目。 但是您可以在许多不同的 Linux 上运行 libguestfs 和 virt 工具
发行版和 Mac OS X。我们尽最大努力支持所有 Linux 发行版作为一流
公民。 一些 virt 工具已移植到 Windows。

创新中心 不 libguestfs 比较 至 other 工具？
与 克帕特克斯
Libguestfs 采用与 kpartx 不同的方法。 kpartx 需要 root 并挂载
主机内核上的文件系统（可能不安全 - 请参阅 来宾安全（1））。
Libguestfs 将您的主机内核与来宾隔离，更加灵活、可编写脚本，
支持LVM，不需要root，与其他进程隔离，清理
在自己之后。 Libguestfs 不仅仅是文件访问，因为您可以使用它来
从头开始创建图像。

与 虚拟机
vdfuse 类似于 kpartx，但用于 VirtualBox 图像。 请参阅上面的 kpartx 比较。
您可以在 vdfuse 公开的分区文件上使用 libguestfs，尽管它不是
必要的，因为 libguestfs 可以直接访问 VirtualBox 图像。

与 qemu-nbd
NBD（网络块设备）是一种用于通过网络导出块设备的协议。
qemu-nbd 是一个 NBD 服务器，它可以处理 qemu 支持的任何磁盘格式（例如原始、
qcow2）。 你可以同时使用 libguestfs 和 qemu-nbd 或 nbdkit 来访问块
网络上的设备，例如：“guestfish -a nbd://remote”

与 安装 文件系统 in 此 主持人
在主机中挂载来宾文件系统是不安全的，应该完全避免
对于不受信任的客人。 使用 libguestfs 提供一层保护
文件系统漏洞利用。 也可以看看 来宾山（1）。

与 分手
Libguestfs 支持 LVM。 Libguestfs 使用 parted 并提供大部分 parted 功能
通过 libguestfs API。

抵达 帮助 AND REPORTING BUGS

创新中心 do I 知道 什么 版本 我 使用？
最简单的方法是：

来宾鱼--版本

Libguestfs 开发发生在一个不稳定的分支上，我们定期创建一个
我们向后移植稳定补丁的稳定分支。 要了解更多信息，请阅读“LIBGUESTFS
版本号”在 来宾（3）。

创新中心 能够 I 得到 帮助？
什么是 邮件 名单 or 即时通话 ROOMS ，那恭喜你， 有空吗
如果您是使用 Red Hat Enterprise Linux 的 Red Hat 客户，请联系
红帽支持： http://redhat.com/support

有一个邮件列表，主要用于开发，但也欢迎用户询问
关于 libguestfs 和 virt 工具的问题：
https://www.redhat.com/mailman/listinfo/libguestfs

您也可以在 FreeNode 上的 IRC 频道“#libguestfs”上与我们交谈。 我们并不总是
周围，​​所以请在问你的问题后留在频道，有人会回来的
的状况，我们将允许退货。

对于其他 virt 工具（不是 libguestfs 提供的工具），有一个通用的 virt 工具
邮件列表：https://www.redhat.com/mailman/listinfo/virt-tools-list

创新中心 do I 报告 错误？
请使用以下链接在 Bugzilla 中输入错误：

https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools

包括尽可能多的细节以及重现问题的方法。

包括完整的输出 libguestfs-测试工具（1）。

COMMON 问题

另见“LIBGUESTFS GOTCHAS” 来宾(3) 对于使用 libguestfs 的一些“问题”
API。

“可以 不能 分配 动态 翻译者 缓冲”
这个晦涩的错误实际上是 SELinux 失败。 您必须启用以下功能
SELinux 布尔值：

setebool -P virt_use_execmem=on

有关更多信息，请参阅 https://bugzilla.redhat.com/show_bug.cgi?id=806106。

“孩子 过程 死亡 不料”
[此错误消息在 libguestfs 1.21.18 中更改为更具解释性的内容。]

此错误表示 qemu 失败或主机内核无法启动。 为了更进一步
有关失败的信息，您必须运行：

libguestfs-测试工具

如果使用后，您仍然不了解故障，请联系我们（请参阅前面的
部分）。

libguestfs： 错误： 不能 发现 任何 合适的 libguestfs 超小， 固定 or 旧式 器具
on LIBGUESTFS_PATH
febootstrap-supermin-helper： 分机2： 亲 目录 不能 发现
超级帮手： 分机2： 亲 目录 不能 发现
[这个问题在 libguestfs ≥ 1.26 中永久修复。]

如果您在 Debian/Ubuntu 上看到任何这些错误，则需要运行以下命令：

须藤更新-guestfs-appliance

“允许 拒绝” ，尤其是 运行 libguestfs as 根
打开磁盘映像时出现权限被拒绝错误，即使您正在运行
以 root 身份运行 libguestfs。

这是由 libvirt 引起的，因此仅在使用 libvirt 后端时才会发生。 运行时
作为 root，libvirt 决定以用户“qemu.qemu”的身份运行 qemu 设备。 很遗憾
这通常意味着 qemu 无法打开磁盘映像，特别是如果这些磁盘映像是
由 root 拥有，或存在于需要 root 访问权限的目录中。

有一个针对 libvirt 的漏洞可以解决这个问题：
https://bugzilla.redhat.com/show_bug.cgi?id=1045069

您可以通过以下方法之一解决此问题：

· 切换到直接后端：

导出 LIBGUESTFS_BACKEND=direct

· 不要以 root 身份运行 libguestfs。

· Chmod 磁盘映像和任何父目录，以便 qemu 用户可以访问它们。

·（讨厌的）编辑 /etc/libvirt/qemu.conf 并更改“用户”设置。

执行： /在里面： 允许 否认
请注意： 如果在您使用 libguestfs 的发行版软件包时发生此错误（例如从
Fedora、Debian 等）然后针对发行版提交错误。 这不是一个错误
普通用户应该查看发行版软件包是否已正确准备。

此错误发生在启动设备的 supermin 启动阶段：

supermin：安装新的根 /根
超级管理员：chroot
execl: /init: 权限被拒绝
supermin: 调试: 列表目录 /
[...接着是很多调试输出...]

这是一个与相关的复杂错误 超小(1)电器。 设备构造
通过复制文件，如 / bin / bash 以及来自主机的许多库。 文件“主机文件”
列出应从主机复制到设备中的文件。 如果一些文件
主机上不存在，则它们会被遗漏，但如果按顺序需要这些文件
（例如）运行 / bin / bash 然后你会看到上面的错误。

诊断问题涉及研究所需的库 / bin / bash，即：

dd / bin / bash

将其与“hostfiles”以及主机文件系统中实际可用的文件进行比较，
并在错误消息中打印调试输出。 一旦你确定了哪个文件
丢失，请使用您的包管理器安装该文件，然后重试。

您还应该检查文件，如 /在里面 和 / bin / bash （在设备中）是
可执行。 调试输出显示文件模式。

下载， 安装， 编译 来宾

其中 能够 I 得到 此 最新 二进制 ......？
软呢帽 ≥ 11
使用方法：

yum 安装 '*guestf*'

有关最新版本，请参阅：
http://koji.fedoraproject.org/koji/packageinfo?packageID=8391

红帽企业Linux
RHEL 5
官方 RHEL 5 附带的版本很旧，除了
与 virt-v2v 结合使用。 在 EPEL 中使用最新的 libguestfs 1.20 包
5：https://fedoraproject.org/wiki/EPEL

RHEL 6
RHEL 7
它是默认安装的一部分。 在 RHEL 6 和 7（仅）上，您必须安装
“libguestfs-winsupport”以获得 Windows 来宾支持。

Debian和Ubuntu
对于 libguestfs < 1.26，安装 libguestfs 后，您需要执行以下操作：

须藤更新-guestfs-appliance

（此脚本已在 Debian/Ubuntu 上删除，libguestfs ≥ 1.26，取而代之的是
设备是按需构建的。）

仅在 Ubuntu 上：

须藤 chmod 0644 /boot/vmlinuz*

您可能需要将自己添加到“kvm”组：

sudo usermod -a -G kvm yourlogin

Debian压榨（6）
Hilko Bengen 在挤压向后移植中构建了 libguestfs：
http://packages.debian.org/search?keywords=guestfs&searchon=names§ion=all&suite=squeeze-backports

Debian Wheezy 及更高版本 (7+)
Hilko Bengen 在 Debian 上支持 libguestfs。 官方 Debian 软件包是
可供选择： http://packages.debian.org/search？关键字=libguestfs

Ubuntu
我们没有全职的 Ubuntu 维护人员，并且提供的软件包由
规范（不在我们的控制范围内）有时会被破坏。

Canonical 决定更改内核权限
可读，除了 root。 这完全是愚蠢的，但他们不会改变它
（https://bugs.launchpad.net/ubuntu/+source/linux/+bug/759725）。 所以每个用户
应该这样做：

须藤 chmod 0644 /boot/vmlinuz*

Ubuntu的12.04
这个版本的 Ubuntu 中的 libguestfs 可以工作，但是你需要更新 febootstrap
和 seabios 到最新版本。

您需要 febootstrap ≥ 3.14-2 来自：
http://packages.ubuntu.com/precise/febootstrap

安装或更新 febootstrap 后，重建设备：

须藤更新-guestfs-appliance

您需要 seabios ≥ 0.6.2-0ubuntu2.1 或 ≥ 0.6.2-0ubuntu3 来自：
http://packages.ubuntu.com/precise-updates/seabios or
http://packages.ubuntu.com/quantal/seabios

你还需要做（见上文）：

须藤 chmod 0644 /boot/vmlinuz*

Gentoo的
Libguestfs 由 Andreis Vinogradovs (libguestfs) 于 2012-07 年添加到 Gentoo 和
Maxim Koltsov（主要是蜂巢）。 做：

出现 libguestfs

苏斯
Libguestfs 于 2012 年由 Olaf Hering 添加到 SuSE。

ArchLinux的
Libguestfs 于 2010 年被添加到 AUR。

其他 Linux 发行版
从源代码编译（下一节）。

其他非 Linux 发行版
您必须从源代码编译并移植它。

创新中心 能够 I 编 和 安装 libguestfs 止 资源？
您可以从 git 或源 tarball 编译 libguestfs。 阅读 README 文件之前
开始。

Git：https://github.com/libguestfs/libguestfs 源码包：
http://libguestfs.org/download

不要运行“make install”！ 使用 ”。/ 跑" 脚本代替（请参阅自述文件）。

创新中心 能够 I 编 和 安装 libguestfs if my 发行 不 已可以选用 新 更多
qemu/supermin/内核？
Libguestfs 需要 supermin 5。如果 supermin 5 尚未移植到您的发行版，请参阅
下面的问题。

首先从源代码编译 qemu、supermin 和/或内核。 你做 不能 需要“使
安装”它们。

在 libguestfs 源目录中，创建两个文件。 “localconfigure”应包含：

源本地环境
#export PATH=/tmp/qemu/x86_64-softmmu:$PATH
./autogen.sh --前缀 在/ usr “$@”

使“localconfigure”可执行。

“localenv”应包含：

#export SUPERMIN=/tmp/supermin/src/supermin
#export LIBGUESTFS_HV=/tmp/qemu/x86_64-softmmu/qemu-system-x86_64
#export SUPERMIN_KERNEL=/tmp/linux/arch/x86/boot/bzImage
#export SUPERMIN_KERNEL_VERSION=4.XX.0
#export SUPERMIN_MODULES=/tmp/lib/modules/4.XX.0

取消注释并根据需要调整这些行以使用您拥有的替代程序
编译。

使用“./localconfigure”而不是“./configure”，否则你将 libguestfs 编译为
通常。

不要运行“make install”！ 使用 ”。/ 跑" 脚本代替（请参阅自述文件）。

创新中心 能够 I 编 和 安装 libguestfs 也完全不需要 超小？
如果 supermin 5 支持您的发行版，但您碰巧没有足够新的 supermin
安装，然后看上一个问题。

如果 supermin 5 根本不支持你的发行版，你将需要使用“fixed
设备方法”，您在其中使用预编译的二进制设备。构建 libguestfs
没有supermin，您需要将“--disable-appliance --disable-daemon”传递给任一
./autogen.sh or /配置 （取决于您是从 git 还是分别构建
来自 tarball）。 然后，在使用 libguestfs 时，您 必须 设置“LIBGUESTFS_PATH”
预编译组件的目录中的环境变量，也如在
“固定电器” 来宾（3）。

对于预编译的设备，另请参见： http://libguestfs.org/download/binaries/appliance/.

欢迎使用补丁将 supermin 移植到更多 Linux 发行版。

创新中心 能够 I 加 SUPPORT 虚拟？
备注 软呢帽/RHEL 用户： 此配置是 Fedora 18 和
RHEL 7. 如果您发现任何问题，请告诉我们或提交错误。

SVirt 提供了一个使用 SELinux 的强化设备，这使得流氓磁盘变得非常困难
图像从 libguestfs 的限制中“逃脱”并损坏主机（公平地说
即使在标准的 libguestfs 中，这也很难，但是 sVirt 提供了一个额外的层
保护主机，更重要的是保护同一主机上的虚拟机
相互之间）。

目前要启用 sVirt，您需要 libvirt ≥ 0.10.2（1.0 或更高版本），
libguestfs ≥ 1.20，以及最近 Fedora 的 SELinux 政策。 如果你没有跑步
Fedora 18+，您需要更改您的 SELinux 政策 - 联系我们
邮件列表。

满足要求后，请执行以下操作：

./configure --with-default-backend=libvirt # libguestfs >= 1.22
./configure --with-default-attach-method=libvirt # libguestfs <= 1.20
使

将 SELinux 设置为 Enforcing 模式，并自动使用 sVirt。

libguestfs 的所有或几乎所有功能都应该在 sVirt 下工作。 有一个已知
缺点： 虚拟救援(1) 不会使用 libvirt（因此是 sVirt），而是直接使用
qemu 的启动。 因此，您目前在使用时不会获得 sVirt 保护的好处
虚拟救援。

您可以通过启用 libvirtd 日志记录来检查是否正在使用 sVirt（请参阅
/etc/libvirt/libvirtd.log)，杀死并重新启动libvirtd，并检查日志文件
用于“在...上设置 SELinux 上下文”消息。

理论上sVirt应该支持AppArmor，但是我们还没试过。 几乎会
当然需要修补 libvirt 并编写 AppArmor 策略。

libguestfs 具有 a 真 长 名单 of 依赖！
基础库依赖不是很大，但是长列表有XNUMX个原因
其他依赖项：

1. Libguestfs 必须能够读取和编辑许多不同的磁盘格式。 例如，
XFS 支持需要 XFS 工具。

2. 有很多不同语言的语言绑定，都需要自己的
开发工具。 所有语言绑定（C 除外）都是可选的。

3. 有一些可选的库功能可以禁用。

由于 libguestfs ≥ 1.26，可以拆分组件依赖项（第 1 项）
上面的列表），因此有（例如）“libguestfs-xfs”作为一个单独的子包
处理 XFS 磁盘映像。 我们鼓励下游包装商开始拆分基础
libguestfs 打包成更小的子包。

故障 ，我们将参加 发射 on Fedora ≥ RHEL ≥ 7
在 Fedora ≥ 18 和 RHEL ≥ 7 中，libguestfs 使用 libvirt 来管理设备。 之前
（和上游）libguestfs 直接运行 qemu：

┌────────────────────────────────────┐
│ libguestfs │
├────────────────┬────────────────────┤
│ 直接后端 │ libvirt 后端 │
└──────────────────┴──────────────────┘
↓ ↓
┌────────┐ ┌──────────┐
│ qemu │ │ libvirtd │
└──────────┘ └──────────┘
↓
┌────────┐
│ 奇姆 │
└─────────┘

上游 Fedora 18+
非 Fedora RHEL 7+
非 RHEL

libvirt 后端更复杂，支持 SELinux/sVirt（见上文），
热插拔等等。 然而，它更复杂，因此不那么健壮。

如果您在使用 libvirt 后端时遇到权限问题，可以切换到直接
通过设置此环境变量来后端：

导出 LIBGUESTFS_BACKEND=direct

在运行任何 libguestfs 程序或 virt 工具之前。

创新中心 能够 I 开关 至 a 固定 / 预建 器具？
这可能会提高 libguestfs 在 Fedora 和 RHEL 上的稳定性和性能。

安装 libguestfs 后，随时以 root 身份运行以下命令：

mkdir -p /usr/local/lib/guestfs/appliance
libguestfs-make-fixed-appliance /usr/local/lib/guestfs/appliance
ls -l /usr/local/lib/guestfs/appliance

现在在使用 libguestfs 或任何 virt 工具之前设置以下环境变量：

导出 LIBGUESTFS_PATH=/usr/local/lib/guestfs/appliance

当然，您可以将路径更改为您想要的任何目录。 您可以共享设备
跨具有相同架构的机器（例如，所有 x86-64），但请注意 libvirt
由于权限问题，将阻止您跨 NFS 共享设备（因此
要么切换到直接后端，要么不使用 NFS）。

创新中心 能够 I 速度 up libguestfs 建造？
到目前为止，您可以做的最重要的事情是安装和正确配置 Squid。
请注意，Squid 附带的默认配置是垃圾，因此配置它是
不是可选的。

一个非常好的开始使用 Squid 配置的地方是这里：
https://fedoraproject.org/wiki/Extras/MockTricks#Using_Squid_to_Speed_Up_Mock_package_downloads

确保 Squid 正在运行，并且环境变量 $http_proxy 和 $ftp_proxy
正在指向它。

随着 Squid 的运行和正确配置，设备构建应该减少到几个
分钟。

创新中心 能够 I 速度 up libguestfs 建立 （Debian）？

Hilko Bengen 建议使用“approx”，这是一个 Debian 档案代理
(http://packages.debian.org/approx）。 这个工具记录在 Debian 的 大约(8)
手册页。

速度， DISK 空间 用过的 BY 来宾

请注意： 本节中的大部分信息已移动： 来宾性能（1）。

上传 or 写 似乎 非常 慢。
如果底层磁盘未完全分配（例如稀疏原始或 qcow2），则写入可以
慢，因为主机操作系统必须在您使用时进行昂贵的磁盘分配
写作。 解决方案是使用完全分配的格式，即。 非稀疏原始，或
qcow2 带有“预分配=元数据”选项。

libguestfs 使用 也有 许多 磁盘 空间！
libguestfs 将大型设备缓存在：

/var/tmp/.guestfs-

如果定义了环境变量“TMPDIR”，则 $TMPDIR/.guestfs- 用来
代替。

当您不使用 libguestfs 时，删除此目录是安全的。

虚拟化 似乎 至 使 此 图片 增长 至 此 ， 尺寸 of 此 虚拟 磁盘
如果输入到 虚拟化(1) 是原始的，那么输出将是原始稀疏的。 确保
您正在使用了解稀疏性的工具（例如“du -sh”）测量输出。
它可以产生巨大的差异：

$ ls -lh test1.img
-rw-rw-r--。 1 rjones rjones 100M Aug 8 08:08 test1.img
$ du -sh test1.img
3.6M 测试1.img

（比较表观尺寸 100M 与实际尺寸对比 3.6M)

如果所有这些都让您感到困惑，请通过指定使用非稀疏输出格式 - 转变
选项，例如：

virt-sparsify --转换 qcow2 disk.raw disk.qcow2

为什么 不 虚拟调整大小 工作 on 此 磁盘 图片 到位？
调整磁盘映像的大小非常棘手 - 特别是确保您不会丢失数据或
打破引导加载程序。 当前方法有效地创建了一个新的磁盘映像并复制
旧的数据和引导加载程序。 如果出现问题，您可以随时离开
回到原来的。

如果我们要让 virt-resize 就地工作，那么就必须有一些限制：对于
例如，您将不被允许移动现有分区（因为将数据跨
如果发生电源故障或崩溃，同一个磁盘最有可能损坏数据），
并且 LVM 将很难支持（因为几乎任意的映射
LV 内容和底层磁盘块之间）。

我们考虑过的另一种方法是在原始磁盘映像上放置快照，因此
原始数据未受影响，快照中仅记录差异。
您今天可以使用“qemu-img create”+“virt-resize”来执行此操作，但 qemu 目前不是
足够聪明，可以识别何时将同一块写回快照
存在于后备盘中，因此您会发现这不会为您节省任何空间或时间。

总而言之，这是一个难题，我们现在所拥有的大部分都有效，所以我们不情愿
改变它。

为什么 不 虚拟化 工作 on 此 磁盘 图片 到位？
在 libguestfs ≥ 1.26 中，virt-sparsify 现在可以在适当的位置处理磁盘映像。 用：

virt-sparsify --就地 disk.img

但首先你应该阅读“IN-PLACE SPARSIFICATION” 虚拟化（1）。

问题 开幕 DISK 图片

远程 libvirt的 宾客 不能 be 开了
目前不支持打开远程 libvirt 来宾。 例如，这将不起作用：

guestfish -c qemu://remote/system -d Guest

要打开远程磁盘，您必须以某种方式导出它们，然后连接到导出。 为了
例如，如果您决定使用 NBD：

远程 $ qemu-nbd -t -p 10809 guest.img
本地$ guestfish -a nbd://remote:10809 -i

其他可能性包括 ssh（如果 qemu 足够新）、NFS 或 iSCSI。 见“远程
存储”中 来宾（3）。

创新中心 能够 I 打开 Free Introduction 奇怪 磁盘 资源？
您有一个磁盘映像位于另一个系统中，需要通过库/
HTTP / REST / 专有 API，或以某种方式压缩或存档。 （一个例子
无需实际下载即可远程访问 OpenStack 概览图像。）

我们有一个名为 nbdkit 的姊妹项目（https://github.com/libguestfs/nbdkit）。 这个
project 可让您将任何磁盘源转换为 NBD 服务器。 libguestfs可以访问NBD
直接服务器，例如：

guestfish -a nbd://remote

nbdkit 已获得自由许可，因此您可以将其链接到或包含在专有库中
和代码。 它还具有简单、稳定的插件 API，因此您可以轻松地针对
将来会继续工作的 API。

误差 开放 虚拟机 磁盘： “用 a 虚拟机 特集 这 is 不能 支持的 by Free Introduction 哇 版本：
虚拟机 版本 3"
Qemu（以及 libguestfs）仅支持某些 VMDK 磁盘映像。 别人不行，
给出这个或类似的错误。

理想情况下，有人会修复 qemu 以支持最新的 VMDK 功能，但与此同时
您有三种选择：

1. 如果来宾托管在实时、可访问的 ESX 服务器上，则找到并下载
称为磁盘映像 一些名称-flat.vmdk. 尽管名称如此，但这是一个原始磁盘映像，并且
任何东西都可以打开。

如果您有足够新的 qemu 和 libguestfs 版本，那么您可以
使用 HTTPS 或 ssh 远程访问此磁盘映像。 见“远程存储”
来宾（3）。

2. 使用 VMware 专有的 vdiskmanager 工具将图像转换为原始格式。

3. 使用带有专有 VDDK 插件的 nbdkit 将磁盘映像实时导出为 NBD
来源。 这应该允许您读取和写入 VMDK 文件。

UFS 磁盘 （如 用过的 by BSD） 不能 be 开了
UFS 文件系统格式有许多变体，这些变体不能自我识别。 这
必须告诉 Linux 内核它必须使用哪种 UFS 变体，哪些 libguestfs 不能
知道了。

挂载这些文件系统时，您必须传递正确的“ufstype”挂载选项。

请参阅 https://www.kernel.org/doc/Documentation/filesystems/ufs.txt

Windows 参考文献
Windows ReFS 是 Microsoft 的 ZFS/Btrfs 副本。 此文件系统尚未反转
在 Linux 内核中设计和实现，因此 libguestfs 不支持
它。 目前，它似乎非常罕见“在野外”。

非 ASCII 字符 别 出现 on 可变FAT 文件系统。
此问题的典型症状：

· 创建文件名包含非 ASCII 的文件时出错
字符，尤其是来自亚洲语言（中文、日文、
等等）。 文件系统是 VFAT。

· 当您从 VFAT 文件系统列出目录时，文件名显示为问号。

这是 GNU/Linux 系统的设计缺陷。

VFAT 将长文件名存储为 UTF-16 字符。 打开或返回文件名时，
Linux 内核必须将这些转换为某种形式的 8 位字符串。 UTF-8 将是
显而易见的选择，除了坚持使用非 UTF-8 语言环境的 Linux 用户（用户的
内核不知道语言环境，因为它是 libc 的一个函数）。

因此，当您挂载时，您必须告诉内核您想要完成什么翻译
文件系统。 这两个方法是“iocharset”参数（与
libguestfs）和“utf8”标志。

因此，要使用 VFAT 文件系统，您必须在挂载时添加“utf8”标志。 从客鱼，
使用：

> 挂载选项 utf8 /dev/sda1 /

或在 guestfish 命令行上：

来宾鱼 [...] -m /dev/sda1:/:utf8

或来自 API：

guestfs_mount_options (g, "utf8", "/dev/sda1", "/");

然后内核将文件名与 UTF-8 字符串相互转换。

我们考虑透明地添加这个挂载选项，但不幸的是有几个
这样做的问题：

· 在某些 Linux 系统上，“utf8”挂载选项不起作用。 我们不准确
了解什么系统或为什么，但这是由一位用户可靠地报告的。

· 它会阻止您使用“iocharset”参数，因为它不兼容
与“utf8”。 使用这个参数可能不是一个好主意，但我们不希望
防止它。

非 ASCII 字符 出现 as 下划线 （_） on ISO9660 文件系统。
未使用 mkisofs 或 genisoimage 正确准备文件系统。 确保
文件系统是使用 Joliet 和/或 Rock Ridge 扩展创建的。 libguestfs 没有
需要任何特殊的挂载选项来处理文件系统。

不能 打开 Windows 宾客 这 使用 NTFS��
您会看到如下错误：

挂载：未知文件系统类型“ntfs”

在 Red Hat Enterprise Linux 或 CentOS 上，您必须安装 libguestfs-winsupport
包。

不能 打开 or 检查 RHEL 7 客人。
不能 打开 Linux 宾客 这 使用 XFS。
RHEL 7 来宾以及任何其他使用 XFS 的来宾都可以由 libguestfs 打开，但是您
必须安装“libguestfs-xfs”包。

使用 来宾 IN 你 拥有 课程

API 具有 数以百计 of 方法， 哪里 do I 开始？
我们建议您首先阅读 API 概述：“API 概述” 来宾（3）。

虽然 API 概述涵盖了 C API，但即使您是
打算使用另一种编程语言，因为API是一样的，只是简单
对调用名称的逻辑更改：

C guestfs_ln_sf（g，目标，链接名）；
Python g.ln_sf（目标，链接名）；
OCaml g#ln_sf 目标链接名；
Perl $g->ln_sf (target, linkname);
Shell (guestfish) ln-sf 目标链接名
PHP guestfs_ln_sf($g, $target, $linkname);

熟悉 API 概述后，您应该查看此入门列表
其他语言绑定的要点：“将 LIBGUESTFS 与其他编程语言一起使用”
来宾（3）。

能够 I 使用 libguestfs in my 所有权 / 关闭 资源 / 商业的 程序？
一般来说，是的。 然而，这不是法律建议 - 请阅读随附的许可证
libguestfs，如果您有具体问题，请联系律师。

在源代码树中，许可证位于文件“COPYING.LIB”（库和
绑定）和“复制”（独立程序的 GPLv2+）。

调试 来宾

帮助， 它的 不能 工作！
如果似乎根本没有 libguestfs 程序运行，请运行下面的程序并粘贴
完成， 未经编辑 输出到“libguestfs”@“redhat.com”的电子邮件中：

libguestfs-测试工具

如果特定操作失败，请在电子邮件中提供此清单中的所有信息
到“libguestfs”@“redhat.com”：

1. 你想做什么？

2. 您运行了哪些确切的命令？

3. 这些命令的准确错误或输出是什么？

4. 开启调试，再次运行命令，捕获 完成 输出。 Do 不能
编辑 此 输出。

导出 LIBGUESTFS_DEBUG=1
导出 LIBGUESTFS_TRACE=1

5.包括libguestfs的版本，操作系统版本，以及你是如何安装的
libguestfs（例如来自源代码、“yum install”等）

创新中心 do I 调试 ，尤其是 运用 任何 libguestfs 程序 or 工具 （例如。 virt-v2v or virt-df）？
您可以设置两个“LIBGUESTFS_*”环境变量以获得更多
来自 libguestfs 的信息。

“LIBGUESTFS_TRACE”
将此设置为 1，libguestfs 将以一种格式打印出每个命令/API 调用
类似于guestfish 命令。

"LIBGUESTFS_DEBUG"
将此设置为 1 以启用大量调试消息。 如果你认为
libguestfs 设备内部存在一些问题，那么您应该使用它
选项。

要从 shell 设置这些，请在运行程序之前执行以下操作：

导出 LIBGUESTFS_TRACE=1
导出 LIBGUESTFS_DEBUG=1

对于 csh/tcsh，等效的命令是：

setenv LIBGUESTFS_TRACE 1
setenv LIBGUESTFS_DEBUG 1

有关更多信息，请参阅：“环境变量” 来宾（3）。

创新中心 do I 调试 ，尤其是 运用 客鱼？
您可以使用上述相同的环境变量。 或者使用 guestfish 选项
-x（跟踪命令）或 -v（获取完整的调试输出），或两者兼而有之。

有关更多信息，请参见： 客鱼（1）。

创新中心 do I 调试 ，尤其是 运用 此 API？
调用“guestfs_set_trace” 来宾(3) 启用命令跟踪，和/或
“guestfs_set_verbose”中 来宾(3) 启用调试消息。

为获得最佳结果，请尽早调用这些函数，就在创建
如果可以的话，guestfs 会处理，而且一定要在调用 launch 之前处理。

创新中心 do I 捕获 调试 产量 和 放 it 成 my 记录 系统？
使用事件 API。 例如，参见：“SETTING CALLBACKS TO HANDLE EVENTS” 来宾(3)
和 示例/调试日志记录.c libguestfs 源中的程序。

挖掘 更深 成 此 器具 靴 的过程。
启用调试，然后阅读有关设备启动过程的此文档：
来宾内部（1）。

libguestfs 挂起 or 失败 ，我们将参加 运行/启动。
启用调试并查看完整输出。 如果你无法弄清楚发生了什么，
提交错误报告，包括 完成 输出 libguestfs-测试工具（1）。

调试 libvirt的
如果您使用的是 libvirt 后端，并且 libvirt 失败，那么您可以启用
通过编辑调试 /etc/libvirt/libvirtd.conf.

如果您以非 root 身份运行，则必须编辑不同的文件。 创建
〜/.config/libvirt/libvirtd.conf 包含：

日志级别=1
log_outputs="1:file:/tmp/libvirtd.log"

杀死任何正在运行的会话（非 root）libvirtd，下次运行 libguestfs 时
命令，您应该会在 libvirtd 中看到大量有用的调试信息
/tmp/libvirtd.log

设计/内部 OF 来宾

参见 来宾内部（1）。

为什么 别 您 do 一切 通过 此 FUSE / 文件系统 界面？
我们提供了一个名为 来宾山(1) 它允许您在
主持人。 这是作为 FUSE 模块实现的。 为什么我们不执行整个
libguestfs 使用这种机制，而不是拥有庞大而复杂的 API？

原因是双重的。 首先，libguestfs 提供 API 调用来执行诸如
创建和删除不适合文件系统的分区和逻辑卷
模型很容易。 或者更确切地说，您可以将它们放入：例如，创建一个分区
可以映射到“mkdir /fs/hda1”但是你必须指定一些方法来选择
分区的大小（可能是“echo 100M > /fs/hda1/.size”）和分区类型，
开始和结束扇区等，但是一旦你完成了基于文件系统的 API 开始
看起来比我们目前拥有的基于调用的 API 更复杂。

第二个原因是为了效率。 FUSE 本身相当有效，但它确实
对 FUSE 模块进行大量小的、独立的调用。 在guestmount这些必须
被翻译成消息到 libguestfs 设备，它有很大的开销（及时
和往返）。 例如，读取 64 KB 块中的文件是低效的，因为每个
chunk 会变成单次往返。 在 libguestfs API 中，它更多
通过像这样的流调用之一有效地下载整个文件或目录
“guestfs_download”或“guestfs_tar_out”。

为什么 别 您 do 一切 通过 GVFS？
这些问题类似于 FUSE 的问题。

GVFS 是比 POSIX/FUSE 更好的抽象。 GVFS 有一个 FTP 后端，它是
令人鼓舞，因为 FTP 在概念上类似于 libguestfs API。 然而 GVFS
FTP 后端进行多个同时连接以保持交互性，这
我们不能轻易地使用 libguestfs。

为什么 能够 I 写 至 此 磁盘， 甚至 虽然 I 添加 it 只读？
为什么 不 “——罗” 出现 至 已可以选用 没有 影响？
添加只读磁盘时，libguestfs 会在磁盘顶部放置一个可写覆盖
底层磁盘。 写入进入此覆盖层，并在句柄关闭时被丢弃
（或“guestfish”等退出）。

这样做有两个原因：首先，只读磁盘在
许多情况（例如，IDE 根本不支持它们，因此您无法模拟 IDE
只读磁盘，尽管这在真正的 libguestfs 安装中并不常见）。

其次，更重要的是，即使可以使用只读磁盘，您也不会想要
他们。 挂载任何有日志的文件系统，甚至是“mount -o ro”，都会导致写入
文件系统，因为必须重播日志并更新元数据。 如果磁盘
是真正只读的，您将无法挂载脏文件系统。

为了使其可用，我们创建了叠加层作为临时存储这些写入的地方，并且
然后我们之后丢弃它。 这可确保底层磁盘始终保持不变。

另请注意，在构建 libguestfs（在
“测试/qemu”）。 这就是为什么打包人员运行测试套件很重要的原因之一。

儿童在 “——罗” 使 所有 磁盘 只读？
不！ “--ro”选项仅影响在命令行中添加的磁盘，即。 使用“-a”和
“-d”选项。

在guestfish中，如果你使用“add”命令，那么磁盘被添加为读写（除非你
使用命令明确指定“readonly:true”标志）。

能够 I 使用 "客鱼 --ro" as a 方式 至 备份 my 虚拟 机器？
通常这是 不能 一个好主意。 此邮件中更详细地回答了该问题
列表发布：https://www.redhat.com/archives/libguestfs/2010-August/msg00024.html

另请参阅下一个问题。

为什么 不能 I 运行 fsck的 on a 生活 文件系统 运用 "客鱼 ——罗”？
这个命令通常会 不能 工作：

guestfish --ro -a /dev/vg/my_root_fs 运行：fsck /dev/sda

这样做的原因是 qemu 在原始文件系统上创建了一个快照，但它
不会创建严格的时间点快照。 底层数据块
随着 fsck 操作的进行，qemu 在不同时间读取文件系统，主机
写在中间。 结果是 fsck 看到了大规模的腐败（想象的，不是真实的！）
并失败。

您需要做的是创建一个时间点快照。 如果是逻辑卷，请使用
LVM2 快照。 如果文件系统位于类似 btrfs/ZFS 文件的内部，
使用 btrfs/ZFS 快照，然后在快照上运行 fsck。 在实践中你不会
需要为此使用 libguestfs - 只需运行 /sbin/fsck 直。

创建主机设备和文件的时间点快照超出了
libguestfs，尽管 libguestfs 可以在它们创建后对其进行操作。

什么是 此 差异 之间 客鱼 和 虚拟救援？
很多人对我们提供的两个表面相似的工具感到困惑：

$ guestfish --ro -a guest.img
> 跑
> fsck /dev/sda1

$ virt-rescue --ro guest.img
> /sbin/fsck / dev / sda1

然后出现的相关问题是为什么你不能输入完整的 shell 命令
使用 guestfish 中的所有 --options（但您可以在 虚拟救援（1））。

客鱼(1) 是一个提供结构化访问的程序 来宾(3) API。 它发生
也是一个很好的交互式 shell，但它的主要目的是结构化访问
外壳脚本。 把它想象成一种语言绑定，就像 Python 和其他绑定一样，
但对于外壳。 guestfish 的关键区别因素（以及 libguestfs API
一般）是自动化更改的能力。

虚拟救援(1) 是一种免费的自由形式引导 libguestfs 设备并使
对您的 VM 进行任意更改。 它不是结构化的，你不能自动化，但是为了制作
对您的客人进行快速临时修复，它可能非常有用。

但是，libguestfs 也有一个进入设备的“后门”，允许您发送任意
外壳命令。 它不如 virt-rescue 灵活，因为您无法与
shell 命令，但无论如何都是这样：

> 调试sh“cmd arg1 arg2 ...”

请注意，您应该 不能 靠这个。 将来可以删除或更改它。 如果你的
程序需要一些操作，请改为将其添加到libguestfs API。

什么是 此 处理 "客鱼 -一世”？
为什么 不 虚拟猫 仅由 工作 on a 真实 VM 图片， 但是 虚拟机 合作 on 任何 磁盘 图像？
什么是 不 “没有 根 设备 发现 in Free Introduction 操作 系统 图像 ” 是什么意思？
这些问题都在基本层面上相关，可能不会立即
明显。

在中国、德国、意大利、韩国和美国的 来宾(3) API 层面，一个“磁盘镜像”只是一堆分区和文件系统。

相反，当虚拟机启动时，它会将这些文件系统挂载到一致的
层次结构，例如：

/ (/开发/sda2)
│
├── /启动 (/开发/sda1)
│
├── /主页 （/dev/vg_external/Homes）
│
├── 在/ usr (/dev/vg_os/lv_usr)
│
└── / VAR (/dev/vg_os/lv_var)

（或 Windows 上的驱动器号）。

API 首先在“文件系统堆”级别查看磁盘映像。 但它也
有一种方法可以检查磁盘映像以查看它是否包含操作系统，以及
操作系统启动时挂载磁盘：“INSPECTION” 来宾（3）。

用户期望一些工具（例如 虚拟猫(1)) 使用 VM 路径：

虚拟猫 fedora.img /var/log/messages

virt-cat 怎么知道的 / VAR 是单独的分区吗？ 诀窍是那个 virt-cat
对磁盘映像执行检查，并使用它来正确转换路径。

一些工具（包括 虚拟猫（1） 虚拟编辑（1） 虚拟机(1)) 使用检查映射VM
路径。 其他工具，例如 虚拟机（1）和 虚拟文件系统(1) 完全在
libguestfs API 的原始“大堆文件系统”级别，并且不使用检查。

客鱼(1) 处于一个有趣的中间地带。 如果您使用 -a 和 -m 命令行
选项，那么您必须准确地告诉来宾鱼如何添加磁盘映像以及安装位置
分区。 这是原始 API 级别。

如果使用 -i 选项，libguestfs 执行检查并挂载文件系统
你。

错误“在此操作系统映像中找不到根设备”与此有关。 它
表示检查无法在您提供的磁盘映像中找到操作系统
它。 如果您尝试在某些东西上运行它们，您可能会从 virt-cat 之类的程序中看到这一点
这只是一个磁盘映像，而不是虚拟机磁盘映像。

什么是 do 这些 “调试*” 和 “内部的-*” 功能 做？
有一些用于调试和内部目的的函数是 不能
稳定 API 的一部分。

“debug*”（或“guestfs_debug*”）函数，主要是“guestfs_debug” 来宾（3）和
其他一些用于调试 libguestfs。 虽然他们不属于
稳定的 API，因此可能随时更改或删除，某些程序可能想要调用
这些同时等待功能添加到 libguestfs。

“internal-*”（或“guestfs_internal_*”）函数仅供 libguestfs 使用
本身。 程序没有理由调用它们，程序不应该尝试使用
他们。 使用它们通常会导致不好的事情发生，并且不会参与其中
记录在案的稳定 API。

开发商

其中 do I 提交 补丁？
请将补丁发送到 libguestfs 邮件列表
https://www.redhat.com/mailman/listinfo/libguestfs. You don't have to be subscribed, but
在您的发布被手动批准之前会有延迟。

别 使用 github上 拉 要求 - 他们 将 be 忽视. 原因是（a）我们想要
讨论和剖析邮件列表上的补丁，以及 (b) github 拉取请求变成
合并提交，但我们更喜欢线性历史。

创新中心 do I 提供 a 功能？
您打算贡献的大型新功能应该在邮件列表中讨论
首先（https://www.redhat.com/mailman/listinfo/libguestfs）。 这样可以避免失望
如果我们认为该功能不适合 libguestfs 项目，则会浪费工作。

如果你想推荐一个有用的功能但不想写代码，你可以提交一个
错误（请参阅“获取帮助和报告错误”）在摘要开头带有“RFE：”
线。

谁是 能够 承诺 至 libguestfs 吉特？
大约有 5 人拥有对 github 的提交访问权限。 补丁应该首先发布在列表中
并确认。 此处概述了 ACK 和推送补丁的策略：

https://www.redhat.com/archives/libguestfs/2012-January/msg00023.html

能够 I 叉 libguestfs？
当然可以。 Git 可以很容易地 fork libguestfs。 Github 让它变得更容易。
如果您在邮件列表中告诉我们有关分叉及其原因的信息，那就太好了。

其他条款 查询

能够 I 监控 此 生活 磁盘 活动 of a 虚拟 机 运用 libguestfs？
一个常见的要求是能够使用 libguestfs 来监控一个实时磁盘活动
例如，来宾每次创建新文件时都会收到通知。 Libguestfs
不 不能 以某些人想象的方式工作，正如您从这张图表中看到的：

┌────────────────────────────────────────┐
│ 使用 libguestfs 监控程序 │
└────────────────────────────────────────┘
↓
┌──────────────┐ ┌──────────────────────┐
│ live VM │ │ libguestfs 设备 │
├────────────┤ ├──────────────────────┤
│内核（一）│ │电器内核（二）│
└──────────────┘ └──────────────────────┘
↓ ↓ (r/o 连接)
┌────────────────────────┐
| 磁盘映像|
└────────────────────────┘

这种情况是安全的（只要您在添加驱动器时设置了“只读”标志）。
但是 libguestfs 组件内核 (2) 没有看到对磁盘所做的所有更改
图像，有两个原因：

一世。 VM 内核 (1) 可以将数据缓存在内存中，因此它不会出现在磁盘映像中。

ii. libguestfs 组件内核 (2) 不希望磁盘映像发生变化
在它下面，所以即使 VM 内核 (1) 也不会神奇地更新它自己的缓存
确实更新磁盘映像。

唯一受支持的解决方案是每当您重新启动整个 libguestfs 设备时
想看看磁盘映像的变化。 在调用对应的 API 级别
“guestfs_shutdown”后跟“guestfs_launch”，这是一个重量级的操作（见
还 来宾性能（3））。

如果重新启动设备真的太难了，您可以尝试一些不受支持的黑客攻击
昂贵：

· 调用“guestfs_drop_caches(g, 3)”。 这会导致 libguestfs 帮助所有缓存数据
设备内核 (2) 将被丢弃，因此它返回到磁盘映像。

然而，这本身是不够的，因为 qemu 也缓存了一些数据。 你
还需要修补 libguestfs 以（重新）启用“缓存=不安全”模式。 看：
https://rwmj.wordpress.com/2013/09/02/new-in-libguestfs-allow-cache-mode-to-be-selected/

· 改用类似 virt-bmap 的工具。

· 在来宾内部运行代理。

如果来宾进行更基本的更改（例如删除文件系统），则没有任何帮助。
对于这些类型的事情，您必须重新启动设备。

（注意还有第三个问题，你需要使用一致的快照来真正检查
实时磁盘映像，但这是对任何实时磁盘使用 libguestfs 的普遍问题
图片。）

使用 onworks.net 服务在线使用 guestfs-faq