LXC on 个人技术随想

在Incus容器中使用NVIDIA显卡

Wed, 15 Jan 2025 22:00:00 +0800

📝 喜报

这张P104显卡，在搬运过程中由于震动，金手指不幸接触不良，享练习时长一年半。

目前，该显卡的任务已由另一张锻炼过的P102-100所替代。

在内存全面涨价，V100价格先落后涨的2026年，P104价格已经落到80出头，而P102也只需要180元。

很难说这些电子垃圾还有没有必要购买，但下一代A100等产品的大船恐怕没那么容易靠岸。

从某海鲜市场捡回一个P104显卡。

是的，2025年了，还在捡垃圾卡，毕竟在当前的大模型浪潮下，连退役多年的麦克斯韦架构Tesla M40 24G二手推理卡，都能从2年多前500上下的价格炒到现在的1200以上。就这，还不是每个商家都有货呢。

与此同时，曾经的垃圾佬挚爱P106-100，价格也来到了130以上的区间。有没有搞错，一两年前这玩意只需要大约一半的价钱。而P102-100价格已经来到了280附近，好吧，1080Ti的核心屏蔽一下，12G显存还是有一定可玩性的。

相较之下，捡来的这张P104-100，8G显存比P106的6G显然更有可玩性。而大约是1070水平的核心显然不能和P102比，但在我下单时只需要100出头的价格，不仅比P102便宜了一半有余，甚至还没有溢价后的P106昂贵。反正买回来是插在Linux主机上，不指望打游戏，P104似乎是省钱和好玩的平衡点。

显卡上机，暂时没有爆炸，这里记录一下如何把显卡映射到Incus容器环境里，让容器能利用显卡的方法。

不得不说，有时候捡垃圾确实能学到一些东西。或者说，捡垃圾的优点就在于，它能教会大家解决买全新产品不会遇到的问题的能力。

宿主机配置

NVIDIA驱动

显然，开源的驱动nouveau是不能用的。

常见的建议是安装英伟达官方打的.run驱动包，这当然可以，但我个人不是很喜欢这种方法。

事实上，只需要装上系统apt源里的英伟达闭源驱动，如Debian的nvidia-driver包，或者是Ubuntu的nvidia-headless-550之类，就是OK的了。

除了驱动，还要在主机上安装一个NVIDIA Container Toolkit，这个工具能自动将主机上的NVIDIA运行时及工具等挂载到容器中。

一定会有人问：要不要在主机上装CUDA Toolkit？

在Ubuntu官方提供的教程中，的确提到需要在宿主机上安装CUDA Toolkit。但根据我的实验，如果在宿主机上没有使用CUDA工具如nvcc等的需要，其实完全没必要在宿主机上装CUDA Toolkit。

实际上，根据网上的说法，CUDA Toolkit主要包含三部分内容：

NVIDIA驱动程序（跟我们用apt装的，.run文件装的没啥区别）
CUDA SDK（NVCC，编译器，库文件，示例程序等）
其他工具（Debugger等）

显然，后两个部分实际上，要么是静态文件，要么是运行在用户态的程序，这些程序显然遵循“在哪里使用，就在哪里安装”的方法比较好。

因此，关于CUDA的结论是：

如果完全不涉及到C++ CUDA工具的编译等任务，可以完全不安装CUDA Toolkit；
如果只是想在容器中使用nvidia-smi等工具，也不需要安装CUDA Toolkit，系统会自动将宿主机的nvidia-smi映射到容器中；
如果需要在容器里使用NVCC等SDK工具，则需要在容器中安装CUDA Toolkit；

📝 备注

P104等矿卡与驱动问题

显然，P104这样的矿卡流入用户市场，并不是皮衣男想看到的。

一般来说在Windows上使用矿卡，都建议使用民间的魔改驱动。但在Linux下就比较微妙了。

官方驱动是否会限制显卡频率？

有坊间传闻说，自从535版本开始，N卡就在驱动程序层面限制了矿卡的功耗。

但就我测试的情况来看，使用Debian软件源中提供的535.216版本N卡驱动，P104在nvidia-smi工具中仍然能跑到180W的功率。

因此暂时无法确认该说法是否正确，以及该说法的适用范围。

矿卡能否使用NVENC视频解码器

另一个坊间传闻是，皮衣男还限制了矿卡上的NVENC视频编码器，要使用民间魔改驱动才能解锁NVENC。

我测试的结果是，使用ffmpeg命令无法显示出当前系统支持NVENC编码器。而在jellyfin-ffmpeg中设置使用NVENC硬件加速会报错。

因此暂时没有找到使用矿卡NVENC编码器的有效方法。

容器配置

时至今日，虚拟化GPU并将物理GPU与虚拟机共享，已经不是一件新鲜事了，从WSL到Docker，都有非常成熟且广泛的应用。

在Incus/LXD容器框架下，这一功能同样也是被支持的。然而，Incus的文档实在是语焉不详，缺少明确可复用的示例。说人话就是，官方文档看了一头雾水，没东西可以抄，最后绝知此事还是得躬行。

首先初始化一个容器：

`1`	`incus create images:debian/12 gpu-test`

指定使用显卡：

1
2

incus config set gpu-test nvidia.runtime=true nvidia.driver.capabilities=all
incus config device add gpu-test nvidia-0 gpu

到现在，启动容器，在/dev/下就可以找到N卡的设备文件了，同时也可以使用nvidia-smi等工具查看显卡信息。

值得一提的是，上面指定的NVIDIA Driver Capability，可选的值及意义如下表：

Driver Capability	Description
compute	required for CUDA and OpenCL applications.
compat32	required for running 32-bit applications.
graphics	required for running OpenGL and Vulkan applications.
utility	required for using nvidia-smi and NVML.
video	required for using the Video Codec SDK.
display	required for leveraging X11 display.

一般来说，如果只需要运行CUDA计算等，指定为utility,compute就足够了。

附赠：Micromamba配置教程

🚨 注意

悲报

就在这篇笔记写成之后没几天，PyTorch宣布自v2.6开始不再发布官方Conda包。如有需要，请直接安装 pip 包或者安装 conda-forge 渠道包。

好吧，除非有同时使用多个版本Python的需求，不然conda/mamba在Python生态中的应用场景就比较狭窄了。

mamba is a CLI tool to manage conda s environments.

If you already know conda, great, you already know mamba!

Mamba是一个C++编写的Conda实现，而Micromamba是Mamba的精简版，不附带base环境，只需要一个独立的可执行文件就能承担起以往Conda的职能，而且速度更快。

安装很简单，只需要前往Micromamba的Github Release下载最新的包，解压后提取其中的bin/micromamba可执行文件，放到自己的可执行文件目录下，例如~/.local/bin，然后确保将这一目录加入到PATH环境变量中，就算安装好了一半。

接着执行：

`1`	`micromamba shell init -s bash -r ~/micromamba`

这会修改~/.bashrc，配置与Micromamba相关的环境变量。如果使用的是zsh，则需要将上面的shell部分改成-s zsh。

接下来我们还要配置使用的软件源。事实上，Micromamba与以往的Conda的配置文件.condarc完全兼容，如果曾经安装过Conda，其实不需要重复配置。

如果是全新安装，则可以编辑~/.mambarc，填写以下内容：

channels:
  - defaults
show_channel_urls: true
default_channels:
  - https://mirrors.sustech.edu.cn/anaconda/pkgs/main
  - https://mirrors.sustech.edu.cn/anaconda/pkgs/free
  - https://mirrors.sustech.edu.cn/anaconda/pkgs/r
  - https://mirrors.sustech.edu.cn/anaconda/pkgs/pro
  - https://mirrors.sustech.edu.cn/anaconda/pkgs/msys2
custom_channels:
  conda-forge: https://mirrors.sustech.edu.cn/anaconda/cloud
  msys2: https://mirrors.sustech.edu.cn/anaconda/cloud
  bioconda: https://mirrors.sustech.edu.cn/anaconda/cloud
  menpo: https://mirrors.sustech.edu.cn/anaconda/cloud
  pytorch: https://mirrors.sustech.edu.cn/anaconda/cloud
  simpleitk: https://mirrors.sustech.edu.cn/anaconda/cloud

现在似乎就可以用Micromamba创建环境并安装包了。

报错

报错1: Critical libmamba: No CA certificates found on system, aborting

`1`	`sudo apt install ca-certificates`

报错2: Error libmamba: ZSTD decompression error: Unknown frame descriptor

尝试换一个镜像源。

Incus网络配置指北

Wed, 04 Dec 2024 22:00:00 +0800

网络配置大概是容器配置中最无聊的部分了。

Incus与Macvtap

什么是Macvtap？太简单了请自行百度。总之就是快速将虚拟机/容器作为一个独立机器，暴露给主机所在的网络的功能。

需要注意，Macvtap能实现与局域网内其他主机的通信，但唯独不能实现与主机的通信！

如果有和主机通信的需要，建议为虚拟机配置一块额外的网卡，或使用传统的Bridge网络。

# 创建一个配置文件
# macvlan-enp4s0是配置文件名称
# eth0是虚拟机中这个macvtap网卡的名称
# enp4s0是想要连接到的主机网卡名称
incus profile device add macvlan-enp4s0 eth0 nic nictype=macvlan parent=enp4s0

# 以该配置创建一个新容器
incus init images:debian/12 my-debian --profile default --profile macvlan-enp4s0

# 或是为虚拟机设置配置文件
incus profile add my-debian macvtap-enp4s0

Incus端口发布

在Docker中，我们可能已经习惯了采用-p 10086:80这样的命令，将容器的一个端口映射到主机上另一个端口。

这一目标在Incus中，需要借助Proxy这一设备类型实现，不过会稍显复杂。

📝 备注

Network Forward转发与Proxy有什么区别？
参考：Difference between network forward and proxy device

The proxy device is instance specific and can forward connections in either direction, between protocols, and when operating in non Nat mode doesn’t require a network connection between host and instance.

A forward on the other hand is more like a proxy device operating in Nat mode. But its defined at the network level rather than instance level and allows sharing an ip between multiple instances because it can forward different ports to different ips.

首先，如果是绑定到普通用户默认Project的容器实例，我们要先解除该Project禁止设置Proxy设备的限制。

`1`	`sudo incus project edit user-1000`

是的，sudo，除非账户在incus-admin用户组里，否则请用sudo。

在config下添加一行：

1
2
3

config:
  # ......
  restricted.devices.proxy: allow

保存。现在我们就可以向容器示例添加proxy设备了。

假设在容器my-http里，有一个Nginx正在监听80端口，我们现在希望将容器的80端口映射到主机的10086端口，以实现访问主机的10086端口，就能访问到容器的80端口。那么，命令如下：

`1`	`incus config device add my-http port10086to80 proxy connect="tcp:127.0.0.1:80" listen="tcp:0.0.0.0:10086"`

完成以后，可以在主机运行curl http://127.0.0.1:10086命令，查看绑定是否成功。

如果计划使用反向代理将外部的请求转发到容器，同时禁止外部网络直接通过访问端口号访问到容器内服务，那么可以将最后的listen字段中IP，改成127.0.0.1。

使用Distrobuilder构建Incus容器镜像

Wed, 07 Aug 2024 21:00:00 +0800

在拥有了自己的Distrobuilder后（还没有？请参见：这篇博客），我们来一起构建用于Incus的容器镜像，实现容器镜像自由吧！

一定会有人疑惑：既然已经有了LXC镜像站，为什么还需要自己构建镜像呢？

这是因为，本文希望描述一个全程可控的，避免过度抽象细节的，创建Incus容器镜像的方法。

预先准备

需要在系统上安装distrobuilder，可以使用snap下载，也可以自己构建。

案例1: Alpine Linux镜像

准备根文件系统(rootfs)

既然我们在讨论可控的构建过程，那么这一定包括一个可控的根文件系统(Root FileSystem, rootfs)。

让我们打开downloads | Alpine Linux，下拉找到MINI ROOT FILESYSTEM项目，下载对应架构的根文件系统。

例如，对于64位系统来说，我们将需要下载alpine-minirootfs-3.20.2-x86_64.tar.gz文件。中间的版本号请不要介意。

能不能用镜像站完成这一下载呢？又或者能不能用自己打包的Alpine Linux根文件系统呢？当然可以！这正是可控过程的魅力所在。

当然，distrobuilder实际上也已将下载rootfs的过程封装在程序中。就Alpine Linux来说，distrobuilder下载的rootfs和我们现在手动下载的是同一个文件。

如果更希望让distrobuilder代劳，请跳过当前这一步骤，后面会再展开介绍。

准备构建配置模板

构建镜像时需要的许多信息都由模板文件提供，如镜像的名称、类型、发行版，还有需要安装的软件包、执行的动作等等。

在distrobuilder中，镜像的模板文件是一个YAML文件，标准格式在官方仓库doc/examples/scheme.yaml中给出，文末也附有该文件复制过来的内容：

只不过，格式文件里，有非常多对键值。看起来一头雾水对吧？没关系，加法做不通我们可以做减法。

转到lxc/lxc-ci/images，这一目录下的镜像配置文件，就是Incus官方镜像服务器上，镜像构建所采用的配置文件。我们目前正在构建Alpine Linux，所以我们直接复制alpine.yaml文件中的内容到本地。由于内容太长，同样地，原始内容放在文末。

这文件也太长了吧？而且仔细一看，还有很多似乎我们不太用得上的配置项，例如适用于虚拟机镜像的命令，在容器中是用不到的。因此，让我们来进一步修改这些配置。

修改构建配置文件

Image: 容器镜像配置

首先，文件的第一节image部分，主要定义了镜像的名称和版本号等信息。

为了避免与官方构建的Alpine Linux镜像名称冲突，我们可以稍微修改一下这部分内容：

image:
  distribution: "Custom Alpinelinux"
  name: custom-alpine
  release: 3.20

Source: 镜像rootfs来源配置

配置文件第二节，source部分，主要定义了用于构建容器镜像的rootfs如何获得。由于各Linux发行版的rootfs定义与下载地址都有差异，因此distrobuilder预定义了许多Source，用于解析各种操作系统的rootfs下载规则。

对于Alpine Linux，distrobuilder已经定义好了alpinelinux-http这一Source，因此如果希望distrobuilder帮我们自动下载rootfs，此处可定义如下：

source:
  downloader: alpinelinux-http
  same_as: 3.12
  url: https://mirrors.hust.edu.cn/alpine/

其中，URL可以是任意Alpine Linux镜像站，以上例子使用了华中科大镜像站。不过，URL也可以file://开头，指向本地已经下载好的rootfs文件包。

如你所见，示例配置文件包含了一大段GPG公钥，用于验证下载的rootfs。如果信任下载源与下载文件完整性，并希望删掉keys部分以缩简配置文件，请在source节内加上skip_verification: true选项。

不过，既然我们正在尽可能追求可控，我们一定会想：

alpinelinux-http源在下载rootfs文件之外，是否还有额外的操作/Tricks？
不考虑后文安装软件包等定制操作，在当前这一步是否有通用于所有Linux发行版rootfs的方法？
是否可以利用已预先准备好的rootfs？

尽管根据sources/alpine-http.go源代码，就目前来说，并没有什么下载之外的额外小Tricks。但到目前为止，distrobuilder最新版3.0并没有直接提供使用现有rootfs目录直接构建容器系统的选项。如果直接在配置文件中删除source一节，进行构建时也会报错。

但是，distrobuilder的确提供了一种使用任意rootfs文件包的Source，即rootfs-http，相关源代码可见sources/rootfs-http.go。简单来说只需要提供一个指向rootfs包的URL，本地网络皆可。

因此，上述source节也可以改为（使用file://指向本地文件时需要使用绝对路径）：

1
2
3

source:
  downloader: rootfs-http
  url: file:///absolute/path/to/alpine-minirootfs-3.20.2-x86_64.tar.gz

Target: 目标特定配置

如果仅希望构建Incus容器镜像，不需要LXC镜像和虚拟机镜像，可以直接把这一节大幅精简：

1
2

targets:
  incus:

如有需要，请直接参阅Targets - distrobuilder documentation官方文档。

Files: 文件生成规则配置

和上面类似地，如果不需要Incus虚拟机镜像，仅仅需要保留用于Incus容器的部分，可以直接删除掉所有包含以下标记的虚拟机专用文件生成规则。

1
2

types:
  - vm

Packages: 软件包安装预定义配置

这部分将定义Incus在构建镜像时，需要使用何种包管理器，安装哪些软件包，大部分内容可以直接照抄示例。同上，可以删掉所有虚拟机限定的配置。

重点讨论一下软件源相关配置。官方手册中，与定制软件源相关的选项位于packages节下，可以通过添加repositories节设置额外的软件源。例如：

packages:
  # Other parameters
  # ...
  repositories:
    - name: hust
      url: |-
        https://mirrors.hust.edu.cn/alpine/v3.20/main
        https://mirrors.hust.edu.cn/alpine/v3.20/community

但是，这种方法会将新软件源附加到原本的软件源后，并不会替换掉速度可能非常缓慢的官方软件源。

如果希望替换掉rootfs中的官方软件源，我们可以不采用这种方案，请往下看。

Actions: 自定义操作

在这一部分，我们可以定义在容器构建的不同的时机要执行的操作(Action)。

目前，distrobuilder提供的执行时机（触发器/Trigger）包括：

post-unpack: 在rootfs被解压释放后执行。
post-update: 如果packages.update为true，在包管理器完成更新后执行。
post-packages: 在包管理器安装完所有指定的包后执行。
post-files: 在files配置块执行完成后执行。这一部分默认仅在build-lxc, build-incus, pack-lxc和pack-incus操作中执行。如果希望在build-dir操作中也执行这一块，需要指定--with-post-files选项。

例如，如果我们希望把rootfs中官方的软件源配置为镜像站，则可以添加一个post-unpack操作，内容如下：

actions:
- trigger: post-unpack
  action: |-
    #!/bin/sh
    set -eux
    sed -i 's/dl-cdn.alpinelinux.org/mirrors.hust.edu.cn/g' /etc/apk/repositories

该命令会在rootfs解压挂载后，容器执行apk update更新软件源之前执行。

Mappings: 架构名称映射配置

这部分主要是告诉Distrobuilder如何处理不同架构名称之间的映射关系，如amd64与x86_64，aarch64与arm64等。

这部分按照模板直接保留就行，详情见Mappings - distrobuilder documentation官方文档。

不得不感慨一下，Linux由于各种历史包袱和不一致的规范，有时会略显混乱。

最终配置文件

image:
  name: custom-alpine
  distribution: "Custom Alpinelinux"
  release: 3.20

source:
  downloader: rootfs-http
  url: file:///absolute/path/to/alpine-minirootfs-3.20.2-x86_64.tar.gz

targets:
  incus:

files:
- path: /etc/hostname
  generator: hostname

- path: /etc/hosts
  generator: hosts

- path: /etc/network/interfaces
  generator: dump
  content: |-
    auto eth0
    iface eth0 inet dhcp
    hostname $(hostname)

- path: /etc/inittab
  generator: dump
  content: |-
    # /etc/inittab
    ::sysinit:/sbin/openrc sysinit
    ::sysinit:/sbin/openrc boot
    ::wait:/sbin/openrc default

    # Set up a couple of getty's
    ::respawn:/sbin/getty 38400 console
    tty1::respawn:/sbin/getty 38400 tty1
    tty2::respawn:/sbin/getty 38400 tty2
    tty3::respawn:/sbin/getty 38400 tty3
    tty4::respawn:/sbin/getty 38400 tty4

    # Stuff to do for the 3-finger salute
    ::ctrlaltdel:/sbin/reboot

    # Stuff to do before rebooting
    ::shutdown:/sbin/openrc shutdown

- path: /etc/inittab
  generator: template
  name: inittab
  content: |-
    # /etc/inittab
    ::sysinit:/sbin/openrc sysinit
    ::sysinit:/sbin/openrc boot
    ::wait:/sbin/openrc default

    # Set up a couple of getty's
    ::respawn:/sbin/getty 38400 console

    # Stuff to do for the 3-finger salute
    ::ctrlaltdel:/sbin/reboot

    # Stuff to do before rebooting
    ::shutdown:/sbin/openrc shutdown

- name: meta-data
  generator: cloud-init
  variants:
  - cloud

- name: network-config
  generator: cloud-init
  content: |-
    version: 1
    config:
    - type: physical
      name: eth0
      subnets:
      - type: dhcp
        control: auto
  variants:
  - cloud

- name: user-data
  generator: cloud-init
  variants:
  - cloud

- name: vendor-data
  generator: cloud-init
  variants:
  - cloud

packages:
  manager: apk
  update: true
  cleanup: true
  sets:
  - packages:
    - alpine-base
    - logrotate
    - doas
    action: install

  - packages:
    - cloud-init
    - openssh
    - e2fsprogs-extra
    action: install
    variants:
    - cloud

  - packages:
    - py3-pyserial
    - py3-netifaces
    action: install
    variants:
    - cloud
    releases:
    - 3.17
    - 3.18
    - 3.19
    - 3.20
    - edge

actions:
- trigger: post-unpack
  action: |-
    #!/bin/sh
    set -eux
    sed -i 's/dl-cdn.alpinelinux.org/mirrors.hust.edu.cn/g' /etc/apk/repositories

- trigger: post-packages
  action: |-
    #!/bin/sh
    set -eux

    rm -f /var/cache/apk/*

- trigger: post-packages
  action: |-
    #!/bin/sh
    set -eux

    # Rewrite configuration for LXC
    sed -i 's/#rc_sys=""/rc_sys="lxc"/' /etc/rc.conf

    # Honor fstab by not making the localmount script a noop
    sed -i 's/-lxc//' /etc/init.d/localmount

    # Enable services
    for svc_name in bootmisc syslog devfs; do
        ln -s /etc/init.d/${svc_name} /etc/runlevels/boot/${svc_name}
    done

    for svc_name in networking crond; do
        ln -s /etc/init.d/${svc_name} /etc/runlevels/default/${svc_name}
    done
  types:
  - container

- trigger: post-files
  action: |-
    #!/bin/sh
    set -eux

    setup-cloud-init
  variants:
  - cloud

mappings:
  architecture_map: alpinelinux

我们将最终的配置文件保存，随便起个名字，比方说alpine.yaml即可。

开始构建

新建rootfs和images两个文件夹，分别用于暂存解压的rootfs，以及构建生成的镜像文件。

1
2

mkdir rootfs
mkdir images

首先需要执行的是build-dir指令。

`1`	`sudo distrobuilder build-dir alpine.yaml rootfs`

再接着执行pack-incus指令。

`1`	`sudo distrobuilder pack-incus alpine.yaml rootfs images`

等待一切完成，images文件夹下就存放着构建好的容器镜像了。

此时一定有人会问：为什么要分两步？为什么不直接执行build-incus指令？

答案当然是可以的。

`1`	`sudo distrobuilder build-incus alpine.yaml images`

有什么区别呢？我们来看看Distrobuilder开发者在论坛中的讨论：

Oops, I said build instead of pack here as that’s likely what you actually want to use.build-incus is equivalent of build-dir + pack-incus.

The reason why we do it in two steps in our CI is because we produce both LXC and Incus images so that lets us use the same rootfs for both. But if all you care about is the LXD/Incus image, just use build-incus directly.

导入Incus并开始使用

拥有了镜像，只需要导入Incus就可以开始使用了。

`1`	`incus image import images/incus.tar.xz images/rootfs.squashfs --alias custom-alpine/3.20`

命令末尾的--alias选项用于给镜像定义一个别名。如果没有别名，我们就只能用镜像的哈希指代镜像了。

接着创建实例，启动镜像。

1
2

incus launch local:custom-alpine/3.20 test-alp
incus exec test-alp -- /bin/ash

附录

配置文件

doc/examples/scheme.yaml

# This example contains every possible key

image:
  description: |-
    here goes the image description
  distribution: distro
  release: release
  architecture: x86_64
  expiry: 30d
  variant: default
  name: distro-release-x86_64
  serial: some-random-string

source:
  downloader: ubuntu-http
  url: http://archive.ubuntu.com
  keys:
    - 0xdeadbeaf
  keyserver: http://keyserver.ubuntu.com
  variant: default
  suite: suite
  same_as: bionic
  skip_verification: false
  components:
    - main

targets:
  lxc:
    create_message: |-
      You just created an {{ image.description }} container.

      To enable SSH, run: apt install openssh-server
      No default root or user password are set by LXC.

    config:
      - type: all
        before: 5
        content: |-
          lxc.include = LXC_TEMPLATE_CONFIG/ubuntu.common.conf

      - type: user
        before: 5
        content: |-
          lxc.include = LXC_TEMPLATE_CONFIG/ubuntu.userns.conf

      - type: all
        after: 4
        content: |-
          lxc.include = LXC_TEMPLATE_CONFIG/common.conf

      - type: user
        after: 4
        content: |-
          lxc.include = LXC_TEMPLATE_CONFIG/userns.conf

      - type: all
        content: |-
          lxc.arch = {{ image.architecture_personality }}
  incus:
    vm:
      size: 2147483648
      filesystem: ext4

files:
  - generator: dump
    path: /some/path
    content: |-
      here goes the content
    name: name
    mode: 0644
    gid: 1000
    uid: 1000
    template:
      properties:
        key: value
      when:
        - always
    templated: true
    releases:
      - a
      - b
    architectures:
      - x86_64
    variants:
      - default

  - generator: hostname
    path: /etc/hostname

  - generator: hosts
    path: /etc/hosts

  - generator: remove
    path: /root/file

  - generator: template
    name: foo
    content: |-
      Here goes the content
    template:
      properties:
        key: value
      when:
        - create
        - copy

packages:
  manager: apt
  custom_manager:
    clean:
      cmd: mgr
      flags:
        - clean
    install:
      cmd: mgr
      flags:
        - install
    remove:
      cmd: mgr
      flags:
        - remove
    refresh:
      cmd: mgr
      flags:
        - refresh
    update:
      cmd: mgr
      flags:
        - update
    flags:
      - --yes
  update: true
  cleanup: false
  sets:
    - packages:
        - gnupg
      action: install
      early: true

    - packages:
        - vim
      action: install
      releases:
        - a
        - b
      architectures:
        - x86_64
      variants:
        - default

    - packages:
        - lightdm
      action: install
      flags:
        - --no-install-recommends

    - packages:
        - grub
      action: remove

  repositories:
    - name: reponame
      url: |-
        deb http://archive.ubuntu.com/ubuntu {{ image.release }}-updates main restricted universe multiverse
      type: type
      key: 0xdeadbeaf
      releases:
        - a
        - b
      architectures:
        - x86_64
      variants:
        - default

actions:
  - trigger: post-unpack
    action: |-
      #!/bin/sh

      do something after the rootfs has been unpacked

  - trigger: post-files
    action: |-
      #!/bin/sh

      do something after the files section has been processed

  - trigger: post-update
    action: |-
      #!/bin/sh

      do something after packages have been processed

  - trigger: post-packages
    action: |-
      #!/bin/sh

      do something after the packages section has been processed

    releases:
      - a
      - b
    architectures:
      - x86_64
    variants:
      - default

mappings:
  architectures:
    a: b
    c: d
  architecture_map: debian

environment:
  clear_defaults: true
  variables:
    - key: FOO
      value: bar

lxc/lxc-ci/images/alpine.yaml

image:
  distribution: "alpinelinux"

source:
  downloader: alpinelinux-http
  same_as: 3.12
  url: https://mirror.csclub.uwaterloo.ca/alpine/
  keys:
  # 0482D84022F52DF1C4E7CD43293ACD0907D9495A
  - |-
    -----BEGIN PGP PUBLIC KEY BLOCK-----

    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
    bcgRRcklNr8mTzJH
    =ckew
    -----END PGP PUBLIC KEY BLOCK-----

targets:
  lxc:
    create_message: |
      You just created an {{ image.description }} container.

    config:
    - type: all
      before: 5
      content: |-
        lxc.include = LXC_TEMPLATE_CONFIG/alpine.common.conf
    - type: user
      before: 5
      content: |-
        lxc.include = LXC_TEMPLATE_CONFIG/alpine.userns.conf
    - type: all
      after: 4
      content: |-
        lxc.include = LXC_TEMPLATE_CONFIG/common.conf
    - type: user
      after: 4
      content: |-
        lxc.include = LXC_TEMPLATE_CONFIG/userns.conf
    - type: all
      content: |-
        lxc.arch = {{ image.architecture_personality }}
  incus:
    vm:
      filesystem: ext4

files:
- path: /etc/hostname
  generator: hostname

- path: /etc/hosts
  generator: hosts

- generator: fstab
  types:
  - vm

- generator: incus-agent
  types:
  - vm

- path: /etc/default/grub
  generator: dump
  pongo: true
  content: |-
    # Set the recordfail timeout
    GRUB_RECORDFAIL_TIMEOUT=0

    # Do not wait on grub prompt
    GRUB_TIMEOUT=0

    # Set the default commandline
    GRUB_CMDLINE_LINUX_DEFAULT="console=tty1 console=ttyS0 modules=sd-mod,usb-storage,{{ targets.incus.vm.filesystem }} rootfstype={{ targets.incus.vm.filesystem }}"

    # Set the grub console type
    GRUB_TERMINAL=console

    # Disable os-prober
    GRUB_DISABLE_OS_PROBER=true
  types:
  - vm

- path: /etc/network/interfaces
  generator: dump
  content: |-
    auto eth0
    iface eth0 inet dhcp
    hostname $(hostname)

- path: /etc/inittab
  generator: dump
  content: |-
    # /etc/inittab
    ::sysinit:/sbin/openrc sysinit
    ::sysinit:/sbin/openrc boot
    ::wait:/sbin/openrc default

    # Set up a couple of getty's
    ::respawn:/sbin/getty 38400 console
    tty1::respawn:/sbin/getty 38400 tty1
    tty2::respawn:/sbin/getty 38400 tty2
    tty3::respawn:/sbin/getty 38400 tty3
    tty4::respawn:/sbin/getty 38400 tty4

    # Stuff to do for the 3-finger salute
    ::ctrlaltdel:/sbin/reboot

    # Stuff to do before rebooting
    ::shutdown:/sbin/openrc shutdown

- path: /etc/inittab
  generator: template
  name: inittab
  content: |-
    # /etc/inittab
    ::sysinit:/sbin/openrc sysinit
    ::sysinit:/sbin/openrc boot
    ::wait:/sbin/openrc default

    # Set up a couple of getty's
    ::respawn:/sbin/getty 38400 console

    # Stuff to do for the 3-finger salute
    ::ctrlaltdel:/sbin/reboot

    # Stuff to do before rebooting
    ::shutdown:/sbin/openrc shutdown

- name: meta-data
  generator: cloud-init
  variants:
  - cloud

- name: network-config
  generator: cloud-init
  content: |-
    version: 1
    config:
    - type: physical
      name: eth0
      subnets:
      - type: dhcp
        control: auto
  variants:
  - cloud

- name: user-data
  generator: cloud-init
  variants:
  - cloud

- name: vendor-data
  generator: cloud-init
  variants:
  - cloud

packages:
  manager: apk
  update: true
  cleanup: true
  sets:
  - packages:
    - alpine-base
    - logrotate
    - doas
    action: install

  - packages:
    - cloud-init
    - openssh
    - e2fsprogs-extra
    action: install
    variants:
    - cloud

  - packages:
    - py3-pyserial
    - py3-netifaces
    action: install
    variants:
    - cloud
    releases:
    - 3.17
    - 3.18
    - 3.19
    - 3.20
    - edge

  - packages:
    - acpi
    - gcc
    - grub-efi
    - linux-virt
    - udev
    action: install
    types:
    - vm

actions:
- trigger: post-packages
  action: |-
    #!/bin/sh
    set -eux

    rm -f /var/cache/apk/*

- trigger: post-packages
  action: |-
    #!/bin/sh
    set -eux

    # Rewrite configuration for LXC
    sed -i 's/#rc_sys=""/rc_sys="lxc"/' /etc/rc.conf

    # Honor fstab by not making the localmount script a noop
    sed -i 's/-lxc//' /etc/init.d/localmount

    # Enable services
    for svc_name in bootmisc syslog devfs; do
        ln -s /etc/init.d/${svc_name} /etc/runlevels/boot/${svc_name}
    done

    for svc_name in networking crond; do
        ln -s /etc/init.d/${svc_name} /etc/runlevels/default/${svc_name}
    done
  types:
  - container

- trigger: post-files
  action: |-
    #!/bin/sh
    set -eux

    for svc_name in acpid bootmisc hostname hwclock loadkmap modules networking swap sysctl syslog urandom; do
        ln -fs /etc/init.d/${svc_name} /etc/runlevels/boot/${svc_name}
    done

    for svc_name in devfs dmesg hwdrivers mdev udev udev-settle udev-trigger; do
        ln -fs /etc/init.d/${svc_name} /etc/runlevels/sysinit/${svc_name}
    done

    target=/boot/grub/grub.cfg
    grub-mkconfig -o "${target}"
    sed -i "s#root=[^ ]*#root=${DISTROBUILDER_ROOT_UUID}#g" "${target}"

    TARGET="x86_64"
    [ "$(uname -m)" = "aarch64" ] && TARGET="arm64"
    grub-install --target=${TARGET}-efi --no-nvram --removable
    grub-install --target=${TARGET}-efi --no-nvram

    # Attempt to correct errors in the installation of all packages.
    apk fix
  types:
  - vm

- trigger: post-files
  action: |-
    #!/bin/sh
    set -eux

    for svc_name in sshd; do
        ln -fs /etc/init.d/${svc_name} /etc/runlevels/default/${svc_name}
    done

    # Tweak to prevent cloud-init from getting stuck.
    echo "datasource_list: ['NoCloud', 'ConfigDrive', 'LXD', 'None']" > /etc/cloud/cloud.cfg.d/99_lxc.cfg
  types:
  - vm
  variants:
  - cloud

- trigger: post-files
  action: |-
    #!/bin/sh
    set -eux

    setup-cloud-init
  variants:
  - cloud

mappings:
  architecture_map: alpinelinux

为Incus构建Distrobuilder

Wed, 07 Aug 2024 16:00:00 +0800

Distrobuilder作为构建Incus/LXC容器镜像的主要工具，竟然只通过Snap商店提供预编译的二进制包。

岂有此理，让我们设置一个Distrobuilder构建环境吧！一切其实很简单！

启动基础容器

当然，构建一系列动作都可以在本机上直接进行。如果决意如此，请自动忽略本文中容器相关的操作。

不过，Distrobuilder是用Golang编写的程序，因此我们完全可以在容器中构建完成后，移动到主机系统中运行。

既然，构建生成的可执行文件要在主机系统中运行，那当然更推荐设置一个和主机系统相符或接近的容器环境。

例如，我的主机系统是Debian，那么现在一个Debian容器构建环境将具备更好的兼容性。

`1`	`incus launch images:debian/12 go-dev`

安装容器基础软件

由于Debian Bookworm中的golang-go软件包版本号过低，不满足distrobuilder的最低要求版本1.21，因此需要先安装好系统基础组件，稍后自行下载golang编译器。

cat <<EOF | incus exec go-dev /bin/bash
sed -i 's/deb.debian.org/mirrors.bfsu.edu.cn/g' /etc/apt/sources.list
apt-get update
apt-get -y install debootstrap rsync gpg squashfs-tools git make build-essential
EOF

🚨 注意

不要遗漏构建基础套件
对于手动安装golang编译器的用户，请务必记得安装build-essential或其他构建基础套件！

安装Golang套件

cat <<EOF | incus exec go-dev -- /bin/bash
rm -rf /usr/local/go && wget -qO- https://go.dev/dl/go1.22.5.linux-amd64.tar.gz | tar xz -C /usr/local
echo 'export PATH=\$PATH:/usr/local/go/bin' >> /root/.bashrc
EOF

如有需要，可以将上述下载链接更换为镜像站链接。

获取distrobuilder源代码

直接前往Releases - lxc/distrobuilder下载最新的源代码包。

如果在本机上下载完成了，可以推送到容器中：

`1`	`incus file push distrobuilder-distrobuilder-3.0.tar.gz go-dev/root/`

执行incus exec go-dev -- /bin/bash进入容器，接着执行：

mkdir -p $HOME/go/src/github.com/lxc/
cd $HOME/go/src/github.com/lxc/
tar xzf /root/distrobuilder-distrobuilder-3.0.tar.gz
mv distrobuilder-distrobuilder-3.0 distrobuilder

配置go语言资源代理（可选）

以南京大学镜像站为例：

1
2

go env -w GO111MODULE=on
go env -w GOPROXY="https://repo.nju.edu.cn/go/,direct"

开始编译！

1
2

cd distrobuilder/
make

试运行

1
2

cd ~/go/bin/
./distrobuilder --help

若能成功运行，就可以拉回本机使用了。需要回到主机运行：

`1`	`incus file pull go-dev/root/go/bin/distrobuilder .`

容器也可以随之摧毁：

`1`	`incus delete go-dev -f`

Incus/LXD文件系统挂载与访问

Wed, 07 Aug 2024 12:00:00 +0800

当我们使用容器时，时常希望容器能挂载访问本地文件系统。例如，Docker可以将本地路径挂载为一个Volume访问。

Incus/LXD当然也提供了这一功能，但配置起来却有时略显复杂。

只读挂载

非常简单：

`1`	`incus config device add <container-name> <device-name> disk source=/path/on/host path=/path/in/container`

读写权限

然而，以上命令挂载的目录，在容器中常常只有只读权限。

这是因为，Incus非特权容器会默认将容器进程映射到不同的非特权UID/GID运行。

为了让容器内进程也能读写目录，常常可以采用下列方法。

方法1：shift选项

在添加挂载配置时，使用shift=true选项挂载，即可将容器中UID/GID映射到主机文件系统，命令如下：

`1`	`incus config device add <container-name> <device-name> disk source=/path/on/host path=/path/in/container shift=true`

这种方法看上去是最为便捷的，简洁，不需要额外配置。然而，这种方法的局限性与麻烦隐藏在背后。

Restricted path

在Debian/Ubuntu上，当属于incus组且不属于incus-admin组的用户访问Incus时，Incus会为用户创建一个独立的Incus项目(Project)，并限定用户的所有访问资源都位于这一项目下。

显然，这种设计增强了系统安全性，然而，需要注意到，这个项目是资源受限的。很不幸地，挂载主机文件系统同样在限制范围内。

此时，如果用户执行上述含有shift=true选项的挂载命令，会出现以下报错：

`1`	`Error: Failed to start device "my-vol": The "shift" property cannot be used with a restricted source path`

具体来说，在普通用户Incus项目中，Restricted选项会限制挂载的源路径。可以参考Project配置文档进一步了解。

那么，如何在坚持使用shift=true选项的前提下挂载目录呢？

最简单的方法之一是，使用root身份修改用户项目配置：

`1`	sudo incus project edit user-1000`

找到restricted.devices.disk.paths一行，将后面的路径删除，留下一对空白的双引号即可。

1
2

- restricted.devices.disk.paths: /home/xxx
+ restricted.devices.disk.paths: ""

安全隐忧

如果上述问题只是多了一个额外的步骤，修改完项目配置就一劳永逸了。那么接下来的问题恐怕能让安全人员睡不着觉。

当shift=true时，容器向挂载目录写入的文件，其用户组信息都将与容器中用户组保持一致！！！

例如，假设在容器的挂载路径中有一test.txt文件，如果其拥有者是root:root（当然也可以在容器中以root身份设置所有权），此时回到主机文件系统，test.txt文件的拥有者将会是主机上的root:root！

在这种情况下，任何一个拥有了不受挂载目录限制的，具备incus组身份的用户，都等价于拥有了主机上的root权限。

又或者，拥有容器root权限的，且能以主机上任意一个用户身份执行特定可知路径可执行文件的用户，都等价于拥有了主机上的root权限。

很可怕吗？是的很可怕。

⚠️ 警告

威胁的来源？
大体来说，任何具备了容器内root权限的人，都可以向挂载路径中以root身份写入可执行文件，并设置setgid属性与777权限。

此时只需要再在主机上获得任一用户shell，执行挂载路径中的可执行文件并setgid系统调用，即可获得root权限。

相比之下，这一问题就显得更加棘手了。

目前比较适合的解决方案是，在容器中创建非特权用户以执行代码，像保护主机root用户一样保护容器root用户。

但，恐怕大家都会同意的是，到这一步为止，一切都显得有些复杂了。

方法2：UID与GID映射

另一种方法显得较为传统，当然也是在网上最容易找到的方案，也就是将容器中的进程UID与GID，映射为主机上某一用户的UID与GID，从而赋予容器进程“扮演”该用户访问文件系统，从而达到读写主机文件的目的。

这一方法的好处是，可以非常方便地保证，容器进程对挂载文件目录的权限，与主机系统上特定角色的权限保持一致。常见的场景是：

如果希望容器访问我们的~家目录，只需要赋予容器和我们账户一样的UID与GID，再将我们的~挂载到容器中，剩下的事情就是一切如常了。
如果希望容器按照我们想要的权限，例如只读地访问一些文件，我们可以将容器里的用户组映射到本机某一用户组上，容器中的进程也将获得被映射到的组的文件系统权限，例如www-data等。

让我们直接参考Incus/LXD主要开发者的博客吧。

配置subuid与subgid

这里的第一步是，需要把希望容器映射到的用户ID和组ID，设置为允许Incus主进程，也就是root用户使用，从而让Incus能“扮演”我们用户账户。

如果只是想让Incus扮演我们当前使用的账户，访问我们当前账户能访问的资源，那么只需要执行以下命令：

1
2

printf "root:$(id -u):1\n" | sudo tee -a /etc/subuid
printf "root:$(id -g):1\n" | sudo tee -a /etc/subgid

现在，让我们重启Incus，让配置生效：

`1`	`sudo systemctl restart incus`

接下来是具体说明，不想看的可以略过。

实际上，这一步配置主要是向/etc/subuid和/etc/subgid文件添加类似下方的一行。

`1`	`root:1000:1`

这一句配置的意思是，允许root用户/组映射UID与GID，而映射的目标UID/GID范围从1000开始，root可以使用接下来的1个UID/GID，也就是1000这一个UID/GID。具体可以按需调整。

配置Incus容器

还差最后一步！我们现在需要让容器使用刚刚指定的UID与GID，真正开始扮演指定的用户或组。

依然是省流，如果只是希望test容器中的root用户(UID/GID均为0)扮演我们当前使用的账户，请直接执行：

`1`	`printf "uid $(id -u) 0\ngid $(id -g) 0" \| incus config set test raw.idmap -`

接下来是详细解释。以上命令会在容器实例的配置文件中出现类似于下面的一段：

config:
  raw.idmap: |-
    uid 1000 0
    gid 1000 0

这段配置的意思非常直观：将本机上的UID1000，映射成容器中的UID0。同理对GID也进行这一映射。

这一段配置使得容器中的root用户，实际上具备了主机中UID为1000用户的权限，因此，容器中以root身份执行的程序，实际上是以本机UID为1000的用户身份执行的。

📝 备注
能否在容器中使用其他用户身份？
当然可以！在上面的配置中，每一行末尾的0即表示容器中root用户的UID与GID。

如果希望映射成容器中的其他用户，假设容器内用户的UID和GID是10086，那么只需要将刚刚的命令修改成：
1
printf "uid $(id -u) 10086\ngid $(id -g) 10086" | incus config set test raw.idmap -
就可以将容器内的10086用户映射成主机上的当前用户了。

现在，我们就可以像设置只读挂载一样，将本地路径挂载到容器中，不再需要shift=true选项。

`1`	`incus config device add <container-name> <device-name> disk source=/path/on/host path=/path/in/container`

至此，我们终于能让Incus容器，在保持正确权限的同时，读写主机上挂载的文件目录。